@jskit-ai/assistant-core 0.1.135 → 0.1.136

package/test/serviceToolCatalog.test.js

@@ -1,1295 +1,167 @@
-import test from "node:test";
 import assert from "node:assert/strict";
+import test from "node:test";
 import { createSchema } from "json-rest-schema";
-import { createContainer } from "@jskit-ai/kernel/_testable";
-import { ActionRuntimeServiceProvider } from "@jskit-ai/kernel/server/actions";
-import { installServiceRegistrationApi } from "@jskit-ai/kernel/server/runtime";
-import { createServiceToolCatalog } from "../src/server/lib/serviceToolCatalog.js";
-
-function createApp() {
-  const app = createContainer();
-  app.singleton("domainEvents", () => ({
-    async publish() {
-      return null;
-    }
-  }));
-  installServiceRegistrationApi(app);
-  return app;
-}
 
-function createEmptyInputSchema() {
-  return createSchema({});
-}
+import { createActionCatalogue } from "@jskit-ai/kernel/server/actions";
+import { createServiceToolCatalog } from "../src/server/lib/serviceToolCatalog.js";
 
-function createListOutputSchema() {
-  return createSchema({
-    items: {
-      type: "array",
-      required: true,
-      items: {
-        type: "object",
-        additionalProperties: true
-      }
-    }
-  });
+function schema(fields = {}) {
+  return { schema: createSchema(fields), mode: "patch" };
 }
 
-function createOkOutputSchema() {
-  return createSchema({
-    ok: {
-      type: "boolean",
-      required: true
-    }
+function createActions(definitions = []) {
+  const actions = createActionCatalogue();
+  actions.register({
+    contributorId: "test.tools",
+    domain: "demo",
+    actions: definitions
   });
+  return actions;
 }
 
-test("service tool catalog hides methods user cannot execute", () => {
-  const app = createApp();
-  const actionRuntimeProvider = new ActionRuntimeServiceProvider();
-  actionRuntimeProvider.register(app);
-
-  app.service(
-    "demo.customers.service",
-    () => ({
-      listRecords() {
-        return [];
-      },
-      deleteRecord() {
-        return { ok: true };
-      }
-    })
-  );
-
-  app.actions([
-    {
-      id: "demo.customers.list",
-      domain: "demo",
-      version: 1,
-      kind: "query",
-      channels: ["automation"],
-      surfaces: ["admin"],
-      permission: {
-        require: "authenticated"
-      },
-      dependencies: {
-        customersService: "demo.customers.service"
-      },
-      input: {
-        schema: createEmptyInputSchema()
-      },
-      output: {
-        schema: createListOutputSchema()
-      },
-      idempotency: "none",
-      audit: {
-        actionName: "demo.customers.list"
-      },
-      observability: {},
-      async execute(input, _context, deps) {
-        return deps.customersService.listRecords(input);
-      }
-    },
-    {
-      id: "demo.customers.delete",
-      domain: "demo",
-      version: 1,
-      kind: "command",
-      channels: ["automation"],
-      surfaces: ["admin"],
-      permission: {
-        require: "all",
-        permissions: ["customers.delete"]
-      },
-      dependencies: {
-        customersService: "demo.customers.service"
-      },
-      input: {
-        schema: createEmptyInputSchema()
-      },
-      output: {
-        schema: createOkOutputSchema()
-      },
-      idempotency: "optional",
-      audit: {
-        actionName: "demo.customers.delete"
-      },
-      observability: {},
-      async execute(input, _context, deps) {
-        return deps.customersService.deleteRecord(input);
-      }
-    }
-  ]);
-
-  const internalContext = {
-    channel: "internal",
-    surface: "admin"
-  };
-
-  const catalog = createServiceToolCatalog(app, {
-    skipActionPrefixes: []
-  });
-
-  const unauthenticatedTools = catalog.resolveToolSet({
-    ...internalContext,
-    permissions: []
-  }).tools;
-  assert.equal(unauthenticatedTools.length, 0);
-
-  const authenticatedTools = catalog.resolveToolSet({
-    ...internalContext,
-    actor: { id: 9 },
-    permissions: []
-  }).tools;
-  assert.equal(authenticatedTools.length, 1);
-  assert.equal(authenticatedTools[0].actionId, "demo.customers.list");
-
-  const privilegedTools = catalog.resolveToolSet({
-    ...internalContext,
-    actor: { id: 9 },
-    permissions: ["customers.delete"]
-  }).tools;
-  assert.equal(privilegedTools.length, 2);
-});
-
-test("service tool catalog does not expose non-action-backed service methods", async () => {
-  const app = createApp();
-
-  app.service(
-    "demo.profile.service",
-    () => ({
-      updateProfile(patch = {}, options = {}) {
-        return {
-          patch,
-          actorId: Number(options?.context?.actor?.id || 0),
-          source: String(options?.source || "")
-        };
-      }
-    })
-  );
-
-  const catalog = createServiceToolCatalog(app, {
-    skipActionPrefixes: []
-  });
-
-  const context = {
-    actor: {
-      id: 22
-    },
-    permissions: []
+function action({
+  id = "demo.books.list",
+  channels = ["automation"],
+  surfaces = ["admin"],
+  permission = { require: "authenticated" },
+  input = schema({}),
+  output = schema({ ok: { type: "boolean", required: true } }),
+  extensions = {},
+  execute = async () => ({ ok: true })
+} = {}) {
+  return {
+    id,
+    version: 1,
+    kind: "query",
+    channels,
+    surfaces,
+    permission,
+    input,
+    output,
+    idempotency: "none",
+    extensions,
+    execute
   };
-  const toolSet = catalog.resolveToolSet(context);
-  assert.equal(toolSet.tools.length, 0);
+}
 
-  const execution = await catalog.executeToolCall({
-    toolName: "demo_profile_service_updateprofile",
-    argumentsText: JSON.stringify({
-      args: [{ displayName: "Merc" }],
-      options: {
-        source: "assistant"
-      }
+test("assistant tools expose only automation actions allowed for the actor and surface", () => {
+  const actions = createActions([
+    action(),
+    action({
+      id: "demo.books.delete",
+      permission: { require: "all", permissions: ["books.delete"] }
     }),
-    context,
-    toolSet
-  });
-
-  assert.equal(execution.ok, false);
-  assert.deepEqual(execution.error, {
-    code: "assistant_tool_unknown",
-    message: "Unknown tool."
-  });
-});
-
-test("service tool catalog hides actions that are not automation-enabled", () => {
-  const app = createApp();
-  const actionRuntimeProvider = new ActionRuntimeServiceProvider();
-  actionRuntimeProvider.register(app);
-
-  app.service(
-    "demo.non_automation.service",
-    () => ({
-      listRecords() {
-        return [];
-      }
-    })
-  );
-
-  app.actions([
-    {
-      id: "demo.non_automation.list",
-      domain: "demo",
-      version: 1,
-      kind: "query",
-      channels: ["internal"],
-      surfaces: ["admin"],
-      permission: {
-        require: "authenticated"
-      },
-      dependencies: {
-        nonAutomationService: "demo.non_automation.service"
-      },
-      input: {
-        schema: createSchema({})
-      },
-      output: {
-        schema: createListOutputSchema()
-      },
-      idempotency: "none",
-      audit: {
-        actionName: "demo.non_automation.list"
-      },
-      observability: {},
-      async execute(input, _context, deps) {
-        return deps.nonAutomationService.listRecords(input);
-      }
-    }
-  ]);
-
-  const catalog = createServiceToolCatalog(app, {
-    skipActionPrefixes: []
-  });
-  const toolSet = catalog.resolveToolSet({
-    actor: { id: 1 },
-    permissions: [],
-    channel: "internal",
-    surface: "admin"
-  });
-
-  assert.equal(toolSet.tools.length, 0);
-});
-
-test("service tool catalog honors barred action ids", () => {
-  const app = createApp();
-  const actionRuntimeProvider = new ActionRuntimeServiceProvider();
-  actionRuntimeProvider.register(app);
-
-  app.service(
-    "demo.audit.service",
-    () => ({
-      listEntries() {
-        return [];
-      }
-    })
-  );
-
-  app.actions([
-    {
-      id: "demo.audit.list",
-      domain: "demo",
-      version: 1,
-      kind: "query",
-      channels: ["automation"],
-      surfaces: ["admin"],
-      permission: {
-        require: "authenticated"
-      },
-      dependencies: {
-        auditService: "demo.audit.service"
-      },
-      input: {
-        schema: createEmptyInputSchema()
-      },
-      output: {
-        schema: createListOutputSchema()
-      },
-      idempotency: "none",
-      audit: {
-        actionName: "demo.audit.list"
-      },
-      observability: {},
-      async execute(input, _context, deps) {
-        return deps.auditService.listEntries(input);
-      }
-    }
-  ]);
-
-  const catalog = createServiceToolCatalog(app, {
-    skipActionPrefixes: [],
-    barredActionIds: ["demo.audit.list"]
-  });
-
-  const toolSet = catalog.resolveToolSet({ actor: { id: 1 }, permissions: [], channel: "internal", surface: "admin" });
-  assert.equal(toolSet.tools.length, 0);
-});
-
-test("service tool catalog materializes action tools once and filters per request", () => {
-  const app = createApp();
-  const actionRuntimeProvider = new ActionRuntimeServiceProvider();
-  actionRuntimeProvider.register(app);
-  let factoryCalls = 0;
-
-  app.service(
-    "demo.cached.service",
-    () => {
-      factoryCalls += 1;
-      return {
-        listRecords() {
-          return [];
-        }
-      };
-    }
-  );
-
-  app.actions([
-    {
-      id: "demo.cached.list",
-      domain: "demo",
-      version: 1,
-      kind: "query",
-      channels: ["automation"],
-      surfaces: ["admin"],
-      permission: {
-        require: "authenticated"
-      },
-      dependencies: {
-        cachedService: "demo.cached.service"
-      },
-      input: {
-        schema: createEmptyInputSchema()
-      },
-      idempotency: "none",
-      audit: {
-        actionName: "demo.cached.list"
-      },
-      observability: {},
-      async execute(input, _context, deps) {
-        return deps.cachedService.listRecords(input);
-      }
-    }
-  ]);
-
-  const internalContext = {
-    channel: "internal",
-    surface: "admin"
-  };
-
-  const catalog = createServiceToolCatalog(app, {
-    skipActionPrefixes: []
-  });
-
-  assert.equal(factoryCalls, 0);
-
-  catalog.resolveToolSet({
-    ...internalContext,
-    permissions: []
-  });
-  catalog.resolveToolSet({
-    ...internalContext,
-    actor: { id: 1 },
-    permissions: []
-  });
-  catalog.resolveToolSet({
-    ...internalContext,
-    actor: { id: 2 },
-    permissions: ["demo.read"]
-  });
-
-  assert.equal(factoryCalls, 1);
-});
-
-test("service tool catalog uses action-backed schemas for tool contracts", () => {
-  const app = createApp();
-  const actionRuntimeProvider = new ActionRuntimeServiceProvider();
-  actionRuntimeProvider.register(app);
-
-  const inputSchema = createSchema({
-    args: {
-      type: "array",
-      required: true,
-      minItems: 1,
-      maxItems: 1,
-      items: createSchema({
-        displayName: {
-          type: "string",
-          required: true
-        }
-      })
-    },
-    options: {
-      type: "object",
-      required: false,
-      additionalProperties: true
-    }
-  });
-  const outputSchema = createOkOutputSchema();
-
-  app.service(
-    "demo.schemas.service",
-    () => ({
-      updateRecord(payload = {}) {
-        return {
-          ok: Boolean(payload?.displayName)
-        };
-      }
-    })
-  );
-
-  app.actions([
-    {
-      id: "demo.schemas.update",
-      domain: "demo",
-      version: 1,
-      kind: "command",
-      channels: ["automation"],
-      surfaces: ["admin"],
-      permission: {
-        require: "authenticated"
-      },
-      dependencies: {
-        schemasService: "demo.schemas.service"
-      },
-      input: {
-        schema: inputSchema
-      },
-      output: {
-        schema: outputSchema
-      },
-      idempotency: "optional",
-      audit: {
-        actionName: "demo.schemas.update"
-      },
-      observability: {},
-      extensions: {
-        assistant: {
-          description: "Update profile display name."
-        }
-      },
-      async execute(input, _context, deps) {
-        return deps.schemasService.updateRecord(input);
-      }
-    }
-  ]);
-
-  const catalog = createServiceToolCatalog(app, {
-    skipActionPrefixes: []
-  });
-  const toolSet = catalog.resolveToolSet({
-    actor: { id: 1 },
-    permissions: []
-  });
-
-  assert.equal(toolSet.tools.length, 1);
-  assert.equal(toolSet.tools[0].description, "Update profile display name.");
-  assert.deepEqual(toolSet.tools[0].parameters, inputSchema.toJsonSchema({ mode: "patch" }));
-  assert.deepEqual(toolSet.tools[0].outputSchema, outputSchema.toJsonSchema({ mode: "replace" }));
-});
-
-test("service tool catalog rejects unsupported assistantTool field at assistant layer", () => {
-  const app = createApp();
-  const actionRuntimeProvider = new ActionRuntimeServiceProvider();
-  actionRuntimeProvider.register(app);
-
-  app.service(
-    "demo.assistant_tool_shape.service",
-    () => ({
-      createWithAssistantToolField(input = {}) {
-        return {
-          ok: Boolean(input)
-        };
-      },
-      createWithAssistantExtension(input = {}) {
-        return {
-          ok: Boolean(input)
-        };
-      }
-    })
-  );
-
-  const schema = createEmptyInputSchema();
-  const outputSchema = createOkOutputSchema();
-
-  app.actions([
-    {
-      id: "demo.assistant_tool_shape.create",
-      domain: "demo",
-      version: 1,
-      kind: "command",
-      channels: ["automation"],
-      surfaces: ["admin"],
-      permission: {
-        require: "authenticated"
-      },
-      dependencies: {
-        assistantToolShapeService: "demo.assistant_tool_shape.service"
-      },
-      input: {
-        schema
-      },
-      output: {
-        schema: outputSchema
-      },
-      idempotency: "optional",
-      audit: {
-        actionName: "demo.assistant_tool_shape.create"
-      },
-      observability: {},
-      assistantTool: {
-        description: "Unsupported assistant tool metadata."
-      },
-      async execute(input, _context, deps) {
-        return deps.assistantToolShapeService.createWithAssistantToolField(input);
-      }
-    },
-    {
-      id: "demo.assistant_extension_shape.create",
-      domain: "demo",
-      version: 1,
-      kind: "command",
-      channels: ["automation"],
-      surfaces: ["admin"],
-      permission: {
-        require: "authenticated"
-      },
-      dependencies: {
-        assistantToolShapeService: "demo.assistant_tool_shape.service"
-      },
-      input: {
-        schema
-      },
-      output: {
-        schema: outputSchema
-      },
-      idempotency: "optional",
-      audit: {
-        actionName: "demo.assistant_extension_shape.create"
-      },
-      observability: {},
-      extensions: {
-        assistant: {
-          description: "Assistant extension metadata."
-        }
-      },
-      async execute(input, _context, deps) {
-        return deps.assistantToolShapeService.createWithAssistantExtension(input);
-      }
-    }
-  ]);
-
-  const catalog = createServiceToolCatalog(app, {
-    skipActionPrefixes: []
-  });
-  const toolSet = catalog.resolveToolSet({
-    actor: { id: 1 },
-    permissions: []
-  });
-  const actionIds = toolSet.tools.map((tool) => tool.actionId).sort();
-
-  assert.deepEqual(actionIds, ["demo.assistant_extension_shape.create"]);
-});
-
-test("service tool catalog can require input/output schemas for tool exposure", () => {
-  const app = createApp();
-  const actionRuntimeProvider = new ActionRuntimeServiceProvider();
-  actionRuntimeProvider.register(app);
-
-  app.service(
-    "demo.strict.service",
-    () => ({
-      noSchema() {
-        return {
-          ok: true
-        };
-      },
-      withSchema() {
-        return {
-          ok: true
-        };
-      }
-    })
-  );
-
-  app.actions([
-    {
-      id: "demo.strict.with_schema",
-      domain: "demo",
-      version: 1,
-      kind: "query",
-      channels: ["automation"],
-      surfaces: ["admin"],
-      permission: {
-        require: "authenticated"
-      },
-      dependencies: {
-        strictService: "demo.strict.service"
-      },
-      input: {
-        schema: createEmptyInputSchema()
-      },
-      output: {
-        schema: createOkOutputSchema()
-      },
-      idempotency: "none",
-      audit: {
-        actionName: "demo.strict.with_schema"
-      },
-      observability: {},
-      async execute(_input, _context, deps) {
-        return deps.strictService.withSchema();
-      }
-    }
+    action({ id: "demo.books.internal", channels: ["internal"] }),
+    action({ id: "demo.books.other", surfaces: ["app"] })
   ]);
+  const catalog = createServiceToolCatalog(actions);
 
-  const catalog = createServiceToolCatalog(app, {
-    skipActionPrefixes: []
-  });
-  const toolSet = catalog.resolveToolSet({
-    actor: { id: 1 },
-    permissions: []
-  });
-
-  assert.equal(toolSet.tools.length, 1);
-  assert.equal(toolSet.tools[0].actionId, "demo.strict.with_schema");
-});
-
-test("service tool catalog derives tool schemas from action contributors", () => {
-  const app = createApp();
-  const actionRuntimeProvider = new ActionRuntimeServiceProvider();
-  actionRuntimeProvider.register(app);
-
-  const inputSchema = createSchema({
-    workspaceSlug: {
-      type: "string",
-      required: false
-    },
-    name: {
-      type: "string",
-      required: false
-    },
-    surname: {
-      type: "string",
-      required: false
-    }
-  });
-  const outputSchema = createSchema({
-    id: {
-      type: "integer",
-      required: true
-    }
-  });
-
-  app.service(
-    "demo.customers.service",
-    () => ({
-      createRecord(payload = {}) {
-        return {
-          id: 1,
-          ...payload
-        };
-      }
-    })
+  assert.equal(catalog.resolveToolSet({ surface: "admin" }).tools.length, 0);
+  assert.deepEqual(
+    catalog.resolveToolSet({ actor: { id: "7" }, surface: "admin" }).tools.map((entry) => entry.actionId),
+    ["demo.books.list"]
   );
-
-  app.actions([
-    {
-      id: "demo.customers.create",
-      domain: "demo",
-      version: 1,
-      kind: "command",
-      channels: ["automation"],
-      surfaces: ["admin"],
-      permission: {
-        require: "authenticated"
-      },
-      dependencies: {
-        customersService: "demo.customers.service"
-      },
-      input: {
-        schema: inputSchema
-      },
-      output: {
-        schema: outputSchema
-      },
-      idempotency: "optional",
-      audit: {
-        actionName: "demo.customers.create"
-      },
-      observability: {},
-      async execute(input, _context, deps) {
-        return deps.customersService.createRecord(input);
-      }
-    }
-  ]);
-
-  const catalog = createServiceToolCatalog(app, {
-    skipActionPrefixes: []
-  });
-  const toolSet = catalog.resolveToolSet({
-    actor: {
-      id: 1
-    },
-    permissions: []
-  });
-  const createTool = toolSet.tools.find((tool) => tool.actionId === "demo.customers.create");
-
-  assert.ok(createTool);
-  assert.deepEqual(createTool.parameters, inputSchema.toJsonSchema({ mode: "patch" }));
-  assert.deepEqual(createTool.outputSchema, outputSchema.toJsonSchema({ mode: "replace" }));
-});
-
-test("service tool catalog derives input schema from a composed action schema", () => {
-  const app = createApp();
-  const actionRuntimeProvider = new ActionRuntimeServiceProvider();
-  actionRuntimeProvider.register(app);
-
-  app.service(
-    "demo.array_schema.service",
-    () => ({
-      createRecord(payload = {}) {
-        return {
-          id: 1,
-          ...payload
-        };
-      }
-    })
+  assert.deepEqual(
+    catalog.resolveToolSet({
+      actor: { id: "7" },
+      permissions: ["books.delete"],
+      surface: "admin"
+    }).tools.map((entry) => entry.actionId),
+    ["demo.books.delete", "demo.books.list"]
   );
-
-  app.actions([
-    {
-      id: "demo.array_schema.create",
-      domain: "demo",
-      version: 1,
-      kind: "command",
-      channels: ["automation"],
-      surfaces: ["admin"],
-      permission: {
-        require: "authenticated"
-      },
-      dependencies: {
-        arraySchemaService: "demo.array_schema.service"
-      },
-      input: {
-        schema: createSchema({
-          workspaceSlug: {
-            type: "string",
-            required: true,
-            minLength: 1
-          },
-          name: {
-            type: "string",
-            required: true,
-            minLength: 1
-          },
-          surname: {
-            type: "string",
-            required: true,
-            minLength: 1
-          }
-        })
-      },
-      output: {
-        schema: createSchema({
-          id: {
-            type: "integer",
-            required: true
-          },
-          payload: {
-            type: "object",
-            required: true
-          }
-        })
-      },
-      idempotency: "optional",
-      audit: {
-        actionName: "demo.array_schema.create"
-      },
-      observability: {},
-      async execute(input, _context, deps) {
-        return deps.arraySchemaService.createRecord(input);
-      }
-    }
-  ]);
-
-  const catalog = createServiceToolCatalog(app, {
-    skipActionPrefixes: []
-  });
-  const toolSet = catalog.resolveToolSet({
-    actor: {
-      id: 1
-    },
-    permissions: [],
-    channel: "internal",
-    surface: "admin"
-  });
-  const createTool = toolSet.tools.find((tool) => tool.actionId === "demo.array_schema.create");
-
-  assert.ok(createTool);
-  assert.equal(createTool.parameters?.type, "object");
-  assert.equal(typeof createTool.parameters?.properties?.workspaceSlug, "object");
-  assert.equal(typeof createTool.parameters?.properties?.name, "object");
-  assert.equal(typeof createTool.parameters?.properties?.surname, "object");
 });
 
-test("service tool catalog derives direct tool schemas from composed action inputs", () => {
-  const app = createApp();
-  const actionRuntimeProvider = new ActionRuntimeServiceProvider();
-  actionRuntimeProvider.register(app);
-
-  app.service(
-    "demo.workspace_settings.service",
-    () => ({
-      updateSettings(input = {}) {
-        return input;
-      }
-    })
-  );
-
-  app.actions([
-    {
-      id: "demo.workspace.settings.update",
-      domain: "demo",
-      version: 1,
-      kind: "command",
-      channels: ["automation"],
-      surfaces: ["admin"],
-      permission: {
-        require: "authenticated"
-      },
-      dependencies: {
-        workspaceSettingsService: "demo.workspace_settings.service"
-      },
-      input: {
-        schema: createSchema({
-          workspaceSlug: {
-            type: "string",
-            required: true,
-            minLength: 1
-          },
-          name: {
-            type: "string",
-            required: true,
-            minLength: 1
-          }
-        })
-      },
-      output: {
-        schema: createSchema({
-          ok: {
-            type: "boolean",
-            required: true
-          }
-        })
-      },
-      idempotency: "optional",
-      audit: {
-        actionName: "demo.workspace.settings.update"
-      },
-      observability: {},
-      extensions: {
-        assistant: {}
-      },
-      async execute(input, _context, deps) {
-        const result = deps.workspaceSettingsService.updateSettings(input);
-        return {
-          ok: Boolean(result)
-        };
-      }
-    }
+test("assistant tools honor barred ids, prefixes, schemas, and explicit descriptions", () => {
+  const actions = createActions([
+    action({
+      id: "demo.books.list",
+      input: schema({ search: { type: "string", required: false } }),
+      extensions: { assistant: { description: "Search the catalogue." } }
+    }),
+    action({ id: "demo.books.delete" }),
+    action({ id: "system.health.read" })
   ]);
-
-  const catalog = createServiceToolCatalog(app, {
-    skipActionPrefixes: []
-  });
-  const toolSet = catalog.resolveToolSet({
-    actor: { id: 1 },
-    permissions: [],
-    channel: "internal",
-    surface: "admin",
-    requestMeta: {
-      resolvedWorkspaceContext: {
-        workspace: {
-          slug: "tonymobily3"
-        }
-      }
-    }
+  const catalog = createServiceToolCatalog(actions, {
+    barredActionIds: ["demo.books.delete"],
+    skipActionPrefixes: ["system."]
   });
-  const updateTool = toolSet.tools.find((tool) => tool.actionId === "demo.workspace.settings.update");
+  const [tool] = catalog.resolveToolSet({ actor: { id: "7" }, surface: "admin" }).tools;
 
-  assert.ok(updateTool);
-  assert.equal(updateTool.parameters?.type, "object");
-  assert.equal(Object.hasOwn(updateTool.parameters?.properties || {}, "workspaceSlug"), false);
-  assert.equal(typeof updateTool.parameters?.properties?.name, "object");
+  assert.equal(tool.actionId, "demo.books.list");
+  assert.equal(tool.description, "Search the catalogue.");
+  assert.equal(tool.parameters.properties.search.type, "string");
+  assert.equal(tool.outputSchema.properties.ok["x-json-rest-schema"].castType, "boolean");
+  assert.equal(catalog.toOpenAiToolSchema(tool).function.name, tool.name);
 });
 
-test("service tool catalog hides workspaceSlug parameter when workspace context is already resolved", () => {
-  const app = createApp();
-  const actionRuntimeProvider = new ActionRuntimeServiceProvider();
-  actionRuntimeProvider.register(app);
-
-  app.service(
-    "demo.workspace_scope.service",
-    () => ({
-      createRecord(payload = {}) {
-        return payload;
-      }
-    })
-  );
-
-  app.actions([
-    {
-      id: "demo.workspace_scope.create",
-      domain: "demo",
-      version: 1,
-      kind: "command",
-      channels: ["automation"],
-      surfaces: ["admin"],
-      permission: {
-        require: "authenticated"
-      },
-      dependencies: {
-        workspaceScopeService: "demo.workspace_scope.service"
-      },
-      input: {
-        schema: createSchema({
-          workspaceSlug: {
-            type: "string",
-            required: true,
-            minLength: 1
-          },
-          name: {
-            type: "string",
-            required: true,
-            minLength: 1
-          }
-        })
-      },
-      output: {
-        schema: createSchema({
-          workspaceSlug: {
-            type: "string",
-            required: true,
-            minLength: 1
-          },
-          name: {
-            type: "string",
-            required: true,
-            minLength: 1
-          }
-        })
-      },
-      idempotency: "optional",
-      audit: {
-        actionName: "demo.workspace_scope.create"
-      },
-      observability: {},
-      async execute(input, _context, deps) {
-        return deps.workspaceScopeService.createRecord(input);
-      }
-    }
+test("assistant tools require both input and output contracts", () => {
+  const actions = createActions([
+    action({ id: "demo.complete" }),
+    action({ id: "demo.no-output", output: null })
   ]);
+  const tools = createServiceToolCatalog(actions)
+    .resolveToolSet({ actor: { id: "7" }, surface: "admin" })
+    .tools;
 
-  const catalog = createServiceToolCatalog(app, {
-    skipActionPrefixes: []
-  });
-  const toolSet = catalog.resolveToolSet({
-    actor: {
-      id: 1
-    },
-    permissions: [],
-    channel: "internal",
-    surface: "admin",
-    requestMeta: {
-      resolvedWorkspaceContext: {
-        workspace: {
-          slug: "tonymobily3"
-        }
-      }
-    }
-  });
-  const createTool = toolSet.tools.find(
-    (tool) => tool.actionId === "demo.workspace_scope.create"
-  );
-
-  assert.ok(createTool);
-  assert.equal(Object.hasOwn(createTool.parameters.properties, "workspaceSlug"), false);
-  assert.equal(typeof createTool.parameters.properties.name, "object");
+  assert.deepEqual(tools.map((entry) => entry.actionId), ["demo.complete"]);
 });
 
-test("service tool catalog injects workspaceSlug from requestMeta request params", async () => {
-  const app = createApp();
-  const actionRuntimeProvider = new ActionRuntimeServiceProvider();
-  actionRuntimeProvider.register(app);
-
-  app.service(
-    "demo.workspace_injection.service",
-    () => ({
-      createRecord(payload = {}) {
-        return payload;
-      }
-    })
-  );
-
-  app.actions([
-    {
-      id: "demo.workspace_injection.create",
-      domain: "demo",
-      version: 1,
-      kind: "command",
-      channels: ["automation"],
-      surfaces: ["admin"],
-      permission: {
-        require: "authenticated"
-      },
-      dependencies: {
-        workspaceInjectionService: "demo.workspace_injection.service"
-      },
-      input: {
-        schema: createSchema({
-          workspaceSlug: {
-            type: "string",
-            required: true,
-            minLength: 1
-          },
-          name: {
-            type: "string",
-            required: true,
-            minLength: 1
-          }
-        })
-      },
-      output: {
-        schema: createSchema({
-          workspaceSlug: {
-            type: "string",
-            required: true,
-            minLength: 1
-          },
-          name: {
-            type: "string",
-            required: true,
-            minLength: 1
-          }
-        })
-      },
-      idempotency: "optional",
-      audit: {
-        actionName: "demo.workspace_injection.create"
-      },
-      observability: {},
-      async execute(input, _context, deps) {
-        return deps.workspaceInjectionService.createRecord(input);
-      }
+test("assistant tools hide workspaceSlug after workspace context is resolved and inject it on execution", async () => {
+  let executed = null;
+  const actions = createActions([action({
+    input: schema({
+      workspaceSlug: { type: "string", required: true },
+      title: { type: "string", required: true }
+    }),
+    execute: async (input, context) => {
+      executed = { input, context };
+      return { ok: true };
     }
-  ]);
-
-  const catalog = createServiceToolCatalog(app, {
-    skipActionPrefixes: []
-  });
+  })]);
+  const catalog = createServiceToolCatalog(actions);
   const context = {
-    actor: {
-      id: 1
-    },
-    permissions: [],
-    channel: "internal",
+    actor: { id: "7" },
     surface: "admin",
-    requestMeta: {
-      request: {
-        input: {
-          params: {
-            workspaceSlug: "tonymobily3"
-          }
-        }
-      }
-    }
+    workspace: { slug: "library" }
   };
   const toolSet = catalog.resolveToolSet(context);
-  const createTool = toolSet.tools.find(
-    (tool) => tool.actionId === "demo.workspace_injection.create"
-  );
-  assert.ok(createTool);
 
-  const execution = await catalog.executeToolCall({
-    toolName: createTool.name,
-    argumentsText: JSON.stringify({
-      name: "Merc"
-    }),
+  assert.equal(Object.hasOwn(toolSet.tools[0].parameters.properties, "workspaceSlug"), false);
+  const response = await catalog.executeToolCall({
+    toolName: toolSet.tools[0].name,
+    argumentsText: JSON.stringify({ title: "Kindred" }),
     context,
     toolSet
   });
 
-  assert.equal(execution.ok, true);
-  assert.deepEqual(execution.result, {
-    workspaceSlug: "tonymobily3",
-    name: "Merc"
-  });
+  assert.deepEqual(response, { ok: true, result: { ok: true } });
+  assert.deepEqual(executed.input, { workspaceSlug: "library", title: "Kindred" });
+  assert.equal(executed.context.channel, "automation");
 });
 
-test("service tool catalog executes action-backed tools with object payloads", async () => {
-  const app = createApp();
-  const actionRuntimeProvider = new ActionRuntimeServiceProvider();
-  actionRuntimeProvider.register(app);
-
-  app.service(
-    "demo.customers.service",
-    () => ({
-      updateRecord(recordId, payload = {}) {
-        return {
-          id: Number(recordId),
-          payload
-        };
-      }
-    })
-  );
-
-  app.actions([
-    {
-      id: "demo.customers.update",
-      domain: "demo",
-      version: 1,
-      kind: "command",
-      channels: ["automation"],
-      surfaces: ["admin"],
-      permission: {
-        require: "authenticated"
-      },
-      dependencies: {
-        customersService: "demo.customers.service"
-      },
-      input: {
-        schema: createSchema({
-          recordId: {
-            type: "integer",
-            required: true,
-            min: 1
-          },
-          name: {
-            type: "string"
-          }
-        })
-      },
-      output: {
-        schema: createSchema({
-          id: {
-            type: "integer",
-            required: true
-          },
-          payload: {
-            type: "object",
-            required: true
-          }
-        })
-      },
-      idempotency: "optional",
-      audit: {
-        actionName: "demo.customers.update"
-      },
-      observability: {},
-      async execute(input, context, deps) {
-        const { recordId, ...patch } = input;
-        return deps.customersService.updateRecord(recordId, patch, {
-          context
-        });
-      }
-    }
-  ]);
-
-  const catalog = createServiceToolCatalog(app, {
-    skipActionPrefixes: []
-  });
-  const context = {
-    actor: {
-      id: 1
-    },
-    permissions: [],
-    channel: "internal",
-    surface: "admin"
-  };
+test("assistant tools reject unknown tools and return safe action failures", async () => {
+  const actions = createActions([action({
+    execute: async () => {
+      const error = new Error("Database exploded with secret detail.");
+      error.statusCode = 500;
+      error.code = "DATABASE_FAILED";
+      throw error;
+    }
+  })]);
+  const catalog = createServiceToolCatalog(actions);
+  const context = { actor: { id: "7" }, surface: "admin" };
   const toolSet = catalog.resolveToolSet(context);
-  const updateTool = toolSet.tools.find((tool) => tool.actionId === "demo.customers.update");
-  assert.ok(updateTool);
 
-  const execution = await catalog.executeToolCall({
-    toolName: updateTool.name,
-    argumentsText: JSON.stringify({
-      recordId: 7,
-      name: "Merc"
-    }),
+  assert.deepEqual(await catalog.executeToolCall({ toolName: "missing", context, toolSet }), {
+    ok: false,
+    error: { code: "assistant_tool_unknown", message: "Unknown tool." }
+  });
+  assert.deepEqual(await catalog.executeToolCall({
+    toolName: toolSet.tools[0].name,
     context,
     toolSet
+  }), {
+    ok: false,
+    error: { code: "DATABASE_FAILED", message: "Tool call failed.", status: 500 }
   });
-
-  assert.equal(execution.ok, true);
-  assert.deepEqual(execution.result, {
-    id: 7,
-    payload: {
-      name: "Merc"
-    }
-  });
-});
-
-test("service tool catalog hides automation actions from other surfaces", () => {
-  const app = createApp();
-  const actionRuntimeProvider = new ActionRuntimeServiceProvider();
-  actionRuntimeProvider.register(app);
-
-  app.actions([
-    {
-      id: "demo.admin.list",
-      domain: "demo",
-      version: 1,
-      kind: "query",
-      channels: ["automation"],
-      surfaces: ["admin"],
-      permission: {
-        require: "authenticated"
-      },
-      input: {
-        schema: createSchema({})
-      },
-      output: {
-        schema: createListOutputSchema()
-      },
-      idempotency: "none",
-      audit: {
-        actionName: "demo.admin.list"
-      },
-      observability: {},
-      async execute() {
-        return [];
-      }
-    },
-    {
-      id: "demo.console.list",
-      domain: "demo",
-      version: 1,
-      kind: "query",
-      channels: ["automation"],
-      surfaces: ["console"],
-      permission: {
-        require: "authenticated"
-      },
-      input: {
-        schema: createSchema({})
-      },
-      output: {
-        schema: createListOutputSchema()
-      },
-      idempotency: "none",
-      audit: {
-        actionName: "demo.console.list"
-      },
-      observability: {},
-      async execute() {
-        return [];
-      }
-    }
-  ]);
-
-  const catalog = createServiceToolCatalog(app, {
-    skipActionPrefixes: []
-  });
-
-  const adminToolSet = catalog.resolveToolSet({
-    actor: { id: 1 },
-    permissions: [],
-    channel: "internal",
-    surface: "admin"
-  });
-  const consoleToolSet = catalog.resolveToolSet({
-    actor: { id: 1 },
-    permissions: [],
-    channel: "internal",
-    surface: "console"
-  });
-
-  assert.deepEqual(adminToolSet.tools.map((entry) => entry.actionId), ["demo.admin.list"]);
-  assert.deepEqual(consoleToolSet.tools.map((entry) => entry.actionId), ["demo.console.list"]);
 });