@frockbot/plugin-tools 0.3.9 → 0.3.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-tools",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "private": false,
   "type": "module",
   "exports": {
@@ -17,7 +17,7 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/kernel-contracts": "0.3.9",
+    "@frockbot/kernel-contracts": "0.3.11",
     "cordis": "4.0.0-rc.8"
   },
   "devDependencies": {

package/src/dynamic-tools.test.ts

@@ -590,3 +590,114 @@ describe("progressive tool disclosure", () => {
     );
   });
 });
+
+describe("the envelope discovery hands back", () => {
+  test("is the envelope dispatch accepts, for a non-external namespace", async () => {
+    // The Applets Package mounts through the isolate host, whose namespaces
+    // used to register `external: true`. The dispatch guard then refused every
+    // call without `mcpDetails.description`, while discovery's `callWith`
+    // never mentioned the field — so the envelope offered was the envelope
+    // refused, and no Applet could be created by chat at all.
+    const root = await rootWithTools();
+    root.tools.register(dynamicTool("applets", "applet_create"));
+    root.tools.registerNamespace({ name: "applets", status: "ready" });
+
+    const discovered = await invoke(root, GET_DYNAMIC_TOOLS_NAME, {
+      namespace: "applets",
+      toolName: "applet_create",
+    });
+    const envelope = JSON.parse(discovered.content as string).callWith as {
+      tool: string;
+      input: Record<string, unknown>;
+    };
+    expect(envelope.tool).toBe(CALL_DYNAMIC_TOOL_NAME);
+    expect(envelope.input.mcpDetails).toBeUndefined();
+
+    // The exact envelope, with only the placeholder arguments made real.
+    const dispatched = await invoke(root, CALL_DYNAMIC_TOOL_NAME, {
+      ...envelope.input,
+      arguments: { value: "a todo list" },
+    });
+
+    expect(dispatched.isError).toBe(false);
+    expect(dispatched.content).toContain("a todo list");
+  });
+
+  test("carries mcpDetails when the namespace really is external", async () => {
+    const root = await rootWithTools();
+    root.tools.register(dynamicTool("linear", "issue_create"));
+    root.tools.registerNamespace({ name: "linear", external: true });
+
+    const discovered = await invoke(root, GET_DYNAMIC_TOOLS_NAME, {
+      namespace: "linear",
+      toolName: "issue_create",
+    });
+    const envelope = JSON.parse(discovered.content as string).callWith as {
+      input: Record<string, unknown>;
+    };
+    expect(envelope.input.mcpDetails).toEqual({
+      description: "<one sentence saying why you are calling this>",
+    });
+
+    const dispatched = await invoke(root, CALL_DYNAMIC_TOOL_NAME, {
+      ...envelope.input,
+      arguments: { value: "an issue" },
+      mcpDetails: { description: "Filing the bug the User just described." },
+    });
+
+    expect(dispatched.isError).toBe(false);
+  });
+});
+
+describe("a dynamic tool called by its bare name", () => {
+  test("is answered with the envelope, not a dead-end Unknown tool", async () => {
+    // `applet_list` is listed to the model by bare name in
+    // `<dynamic_tool_namespaces>`, so the model reaches for it that way. The
+    // refusal used to be `Unknown tool: applet_list` and nothing else — a dead
+    // end for a tool that was right there.
+    const root = await rootWithTools();
+    root.tools.register(dynamicTool("applets", "applet_list"));
+
+    const result = await invoke(root, "applet_list", {});
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("applet_list");
+    expect(result.content).toContain(CALL_DYNAMIC_TOOL_NAME);
+    expect(result.content).toContain(
+      '{"namespace":"applets","toolName":"applet_list"',
+    );
+    expect(result.content).toContain(GET_DYNAMIC_TOOLS_NAME);
+  });
+
+  test("names every namespace the bare name is in", async () => {
+    const root = await rootWithTools();
+    root.tools.register(dynamicTool("mail-one", "search"));
+    root.tools.register(dynamicTool("mail-two", "search"));
+
+    const result = await invoke(root, "search", {});
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("mail-one");
+    expect(result.content).toContain("mail-two");
+  });
+
+  test("routes an external namespace with the mcpDetails its guard demands", async () => {
+    const root = await rootWithTools();
+    root.tools.register(dynamicTool("linear", "issue_create"));
+    root.tools.registerNamespace({ name: "linear", external: true });
+
+    const result = await invoke(root, "issue_create", {});
+
+    expect(result.content).toContain("mcpDetails");
+    expect(result.content).toContain("description");
+  });
+
+  test("a name in no namespace still says only that it is unknown", async () => {
+    const root = await rootWithTools();
+    root.tools.register(dynamicTool("applets", "applet_list"));
+
+    const result = await invoke(root, "not_a_tool", {});
+
+    expect(result.content).toBe("Unknown tool: not_a_tool");
+  });
+});

package/src/tools.ts

@@ -552,6 +552,37 @@ export class ToolRegistry extends Service implements ToolExecution {
     return { kind: "denied", call, result: { content, isError: true } };
   }
 
+  /**
+   * Why a name is not callable — and, when it *is* callable through the
+   * envelope, how.
+   *
+   * A dynamic tool is listed to the model by bare name in
+   * `<dynamic_tool_namespaces>`, so the model reaches for it by that name and
+   * used to get `Unknown tool: applet_list` and nothing else: a dead end for a
+   * tool that was right there, costing a step every time. The refusal now
+   * hands back the exact envelope for the namespace the name is actually in.
+   */
+  private unknownToolRefusal(name: string): string {
+    const namespaces = [...this.dynamicDefinitions]
+      .filter(([, definitions]) => definitions.has(name))
+      .map(([namespace]) => namespace)
+      .sort();
+    const first = namespaces[0];
+    if (first === undefined) return `Unknown tool: ${name}`;
+    const where =
+      namespaces.length === 1
+        ? `namespace "${first}"`
+        : `namespaces ${listOrNone(namespaces)} — pick one`;
+    // Same rule as the discovery envelope: an external namespace's dispatch
+    // guard refuses a call without `mcpDetails.description`, so a route that
+    // omits it just moves the dead end one step later.
+    const details =
+      this.namespaces.get(first)?.external === true
+        ? `,"mcpDetails":{"description":"<one sentence saying why you are calling this>"}`
+        : "";
+    return `Unknown tool: ${name}. It is a dynamic tool in ${where}; call it through ${CALL_DYNAMIC_TOOL_NAME} as {"namespace":"${first}","toolName":"${name}","arguments":{ … the tool's own input … }${details}}. Call ${GET_DYNAMIC_TOOLS_NAME}({"namespace":"${first}","toolName":"${name}"}) first if you do not have its schema.`;
+  }
+
   private async prepareRegistered(
     call: ToolCall,
     registered: RegisteredTool | undefined,
@@ -566,7 +597,10 @@ export class ToolRegistry extends Service implements ToolExecution {
           return {
             kind: "denied",
             call,
-            result: { content: `Unknown tool: ${call.name}`, isError: true },
+            result: {
+              content: this.unknownToolRefusal(call.name),
+              isError: true,
+            },
           };
         }
         // Defence in depth: the catalog was already trimmed, so a call that
@@ -963,6 +997,20 @@ export class ToolRegistry extends Service implements ToolExecution {
               namespace: namespaceName,
               toolName: registered.definition.name,
               arguments: "<an object matching inputSchema>",
+              // The envelope handed back has to be the envelope accepted. An
+              // external namespace's dispatch guard refuses a call without
+              // `mcpDetails.description`, and a model that copied this
+              // envelope verbatim was denied for a field the envelope never
+              // mentioned.
+              ...(this.namespaces.get(registered.definition.namespace ?? "")
+                ?.external === true
+                ? {
+                    mcpDetails: {
+                      description:
+                        "<one sentence saying why you are calling this>",
+                    },
+                  }
+                : {}),
             },
           },
         }),