refactor: separate voice action schemas from descriptions

src/voice/actionSchemas.test.mjs

@@ -0,0 +1,78 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { GEV_ACTION_SCHEMAS, createActionTools } from './actionSchemas.js';
+import { GEV_REALTIME_TOOLS } from '../../server/providers/openai/tools.js';
+
+const stable = (value) =>
+  Array.isArray(value)
+    ? value.map(stable)
+    : value && typeof value === 'object'
+      ? Object.fromEntries(
+          Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, child]) => [key, stable(child)]),
+        )
+      : value;
+
+test('the complete Realtime tool payload retains its pre-extraction contract and wording', () => {
+  const digest = createHash('sha256')
+    .update(JSON.stringify(stable(GEV_REALTIME_TOOLS)))
+    .digest('hex');
+  assert.equal(
+    digest,
+    '956381c3456d3644ed7c9cda72910dc68a34d9191e0b3e414ee200c348245214',
+  );
+});
+
+test('descriptions customize wording without changing immutable shared arguments', () => {
+  const descriptions = {
+    fly_to_location: {
+      description: 'Navigate',
+      parameters: { properties: { query: { description: 'A place' } } },
+    },
+  };
+  const tools = createActionTools(descriptions);
+  const tool = tools.find((tool) => tool.name === 'fly_to_location');
+  assert.equal(tool.description, 'Navigate');
+  assert.equal(tool.parameters.properties.query.description, 'A place');
+  assert.equal(tool.parameters.properties.query.type, 'string');
+  tool.parameters.properties.query.type = 'number';
+  assert.equal(
+    createActionTools()[0].parameters.properties.query.type,
+    'string',
+  );
+  assert.throws(() => {
+    GEV_ACTION_SCHEMAS[0].parameters.properties.query.type = 'number';
+  }, TypeError);
+  assert.equal(
+    JSON.stringify(GEV_ACTION_SCHEMAS).includes('"description"'),
+    false,
+  );
+});
+
+test('metadata cannot add tools, fields, types or enum values', () => {
+  for (const descriptions of [
+    { execute_shell: { description: 'not an action' } },
+    {
+      fly_to_location: {
+        parameters: { properties: { description: 'new field' } },
+      },
+    },
+    { fly_to_location: { $position: -1, description: 'invalid position' } },
+    { fly_to_location: { name: 'other' } },
+    {
+      fly_to_location: {
+        parameters: { properties: { arbitrary: { description: 'new field' } } },
+      },
+    },
+    {
+      fly_to_location: {
+        parameters: { properties: { query: { type: 'number' } } },
+      },
+    },
+    { fly_to_location: { parameters: { required: { 0: 'another' } } } },
+    { fly_to_location: { description: { nested: 'invalid' } } },
+  ])
+    assert.throws(() => createActionTools(descriptions), TypeError);
+});