@frockbot/plugin-tools 0.0.0 → 0.1.1

package/frockbot.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 2,
+  "id": "tools",
+  "displayName": "Tools",
+  "version": "0.0.1",
+  "compatibility": {
+    "frockbot": ">=0.0.1"
+  },
+  "contributions": {
+    "runtime": {
+      "entry": "./agent"
+    }
+  },
+  "permissions": []
+}

package/package.json

@@ -1,14 +1,35 @@
 {
   "name": "@frockbot/plugin-tools",
-  "version": "0.0.0",
-  "description": "Placeholder reserving this name for trusted publishing. Superseded by the first release.",
-  "license": "UNLICENSED",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./agent": "./src/tools.ts",
+    "./manifest": "./src/manifest.ts",
+    "./frockbot.json": "./frockbot.json",
+    "./package.json": "./package.json"
+  },
+  "frockbot": {
+    "manifest": "./frockbot.json"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@frockbot/kernel-contracts": "0.1.1",
+    "cordis": "4.0.0-rc.8"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.0",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/timoconnellaus/frockbot.git",
     "directory": "packages/plugin-tools"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./tools.js";
+export { default as toolsManifest } from "./manifest.js";

package/src/manifest.ts

@@ -0,0 +1,3 @@
+import manifest from "../frockbot.json" with { type: "json" };
+
+export default manifest;

package/src/tools.test.ts

@@ -0,0 +1,463 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { Context } from "cordis";
+import { ToolRegistry } from "./tools.js";
+import type {
+  ToolCall,
+  ToolDefinition,
+  ToolExecutionContext,
+} from "@frockbot/kernel-contracts";
+
+const roots: Context[] = [];
+
+async function registryFixture(tool: ToolDefinition): Promise<{
+  root: Context;
+  call: ToolCall;
+  context: ToolExecutionContext;
+}> {
+  const root = new Context();
+  roots.push(root);
+  await root.plugin(ToolRegistry);
+  root.tools.register(tool);
+  return {
+    root,
+    call: { id: "provider-call", name: tool.name, input: {} },
+    context: {
+      botId: "primary",
+      agentId: "primary",
+      sessionId: "alice:primary",
+      compositionGenerationId: "test-composition-generation",
+      effectId: "tool:1:1:0",
+      toolCall: { id: "provider-call", name: tool.name, input: {} },
+      turnType: "chat" as const,
+      signal: new AbortController().signal,
+    },
+  };
+}
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => root.fiber.dispose()));
+});
+
+describe("ToolRegistry effect reconciliation", () => {
+  test("retries an idempotent definition with the same durable effect id", async () => {
+    const effects: string[] = [];
+    const fixture = await registryFixture({
+      name: "idempotent",
+      description: "Idempotent fixture.",
+      inputSchema: { type: "object" },
+      idempotent: true,
+      execute(_input, context) {
+        effects.push(context.effectId);
+        return Promise.resolve({ content: "settled", isError: false });
+      },
+    });
+    const preparation = await fixture.root.tools.prepare(
+      fixture.call,
+      fixture.context,
+    );
+    if (preparation.kind !== "ready") throw new Error("tool was denied");
+
+    expect(
+      await fixture.root.tools.reconcilePrepared(preparation, fixture.context),
+    ).toEqual({
+      status: "recovered",
+      result: { content: "settled", isError: false },
+    });
+    expect(effects).toEqual(["tool:1:1:0"]);
+  });
+
+  test("retrieves a non-idempotent result without executing the effect", async () => {
+    let executions = 0;
+    const reconciled: string[] = [];
+    const fixture = await registryFixture({
+      name: "non-idempotent",
+      description: "Non-idempotent fixture.",
+      inputSchema: { type: "object" },
+      execute() {
+        executions += 1;
+        return Promise.resolve({ content: "duplicate", isError: false });
+      },
+      reconcile(_input, context) {
+        reconciled.push(context.effectId);
+        return Promise.resolve({
+          status: "recovered",
+          result: { content: "original", isError: false },
+        });
+      },
+    });
+    const preparation = await fixture.root.tools.prepare(
+      fixture.call,
+      fixture.context,
+    );
+    if (preparation.kind !== "ready") throw new Error("tool was denied");
+
+    expect(
+      await fixture.root.tools.reconcilePrepared(preparation, fixture.context),
+    ).toEqual({
+      status: "recovered",
+      result: { content: "original", isError: false },
+    });
+    expect(executions).toBe(0);
+    expect(reconciled).toEqual(["tool:1:1:0"]);
+  });
+
+  test("does not let middleware elevate a non-idempotent durable effect", async () => {
+    let executions = 0;
+    let retrievals = 0;
+    const fixture = await registryFixture({
+      name: "guarded",
+      description: "Guarded fixture.",
+      inputSchema: { type: "object" },
+      execute() {
+        executions += 1;
+        return Promise.resolve({ content: "duplicate", isError: false });
+      },
+      reconcile() {
+        retrievals += 1;
+        return Promise.resolve({
+          status: "recovered",
+          result: { content: "original", isError: false },
+        });
+      },
+    });
+    fixture.root.on("tools/pre-execute", async (_call, _context, next) => {
+      const prepared = await next();
+      return prepared.kind === "ready"
+        ? { ...prepared, idempotent: true }
+        : prepared;
+    });
+
+    const preparation = await fixture.root.tools.prepare(
+      fixture.call,
+      fixture.context,
+    );
+    if (preparation.kind !== "ready") throw new Error("tool was denied");
+    expect(preparation.idempotent).toBe(true);
+
+    expect(
+      await fixture.root.tools.reconcilePrepared(preparation, fixture.context),
+    ).toEqual({
+      status: "recovered",
+      result: { content: "original", isError: false },
+    });
+    expect(executions).toBe(0);
+    expect(retrievals).toBe(1);
+
+    expect(
+      await fixture.root.tools.reconcilePrepared(
+        {
+          ...preparation,
+          call: { ...fixture.call, input: { changed: true } },
+        },
+        fixture.context,
+      ),
+    ).toMatchObject({ status: "unavailable" });
+    expect(executions).toBe(0);
+  });
+
+  test("normalizes unavailable outcomes to a bounded reason", async () => {
+    const fixture = await registryFixture({
+      name: "pending",
+      description: "Pending fixture.",
+      inputSchema: { type: "object" },
+      execute: () => Promise.resolve({ content: "duplicate", isError: false }),
+      reconcile: () =>
+        Promise.resolve({
+          status: "unavailable",
+          reason: "💥".repeat(1_000),
+        }),
+    });
+    const preparation = await fixture.root.tools.prepare(
+      fixture.call,
+      fixture.context,
+    );
+    if (preparation.kind !== "ready") throw new Error("tool was denied");
+
+    const outcome = await fixture.root.tools.reconcilePrepared(
+      preparation,
+      fixture.context,
+    );
+    expect(outcome.status).toBe("unavailable");
+    if (outcome.status !== "unavailable") return;
+    expect(new TextEncoder().encode(outcome.reason).byteLength).toBe(512);
+  });
+
+  test("returns unavailable when a non-idempotent definition has no retrieval seam", async () => {
+    const fixture = await registryFixture({
+      name: "opaque",
+      description: "Opaque fixture.",
+      inputSchema: { type: "object" },
+      execute: () => Promise.resolve({ content: "effect", isError: false }),
+    });
+    const preparation = await fixture.root.tools.prepare(
+      fixture.call,
+      fixture.context,
+    );
+    if (preparation.kind !== "ready") throw new Error("tool was denied");
+
+    expect(
+      await fixture.root.tools.reconcilePrepared(preparation, fixture.context),
+    ).toEqual({
+      status: "unavailable",
+      reason: "Tool opaque does not support effect reconciliation",
+    });
+  });
+});
+
+describe("ToolRegistry turn admission", () => {
+  async function admissionRoot(): Promise<Context> {
+    const root = new Context();
+    roots.push(root);
+    await root.plugin(ToolRegistry);
+    return root;
+  }
+
+  const work: ToolDefinition = {
+    name: "work",
+    description: "A work tool.",
+    inputSchema: { type: "object" },
+    execute: () => Promise.resolve({ content: "worked", isError: false }),
+  };
+  const chatOnly: ToolDefinition = {
+    name: "send_to_user",
+    description: "The voice to the User.",
+    inputSchema: { type: "object" },
+    admission: { turnTypes: ["chat"] },
+    execute: () => Promise.resolve({ content: "sent", isError: false }),
+  };
+  const automationOnly: ToolDefinition = {
+    name: "wake_parent",
+    description: "Hands off to the parent conversation.",
+    inputSchema: { type: "object" },
+    admission: { turnTypes: ["automation", "subagent"] },
+    execute: () => Promise.resolve({ content: "woke", isError: false }),
+  };
+
+  function contextFor(
+    name: string,
+    turnType: ToolExecutionContext["turnType"],
+  ): ToolExecutionContext {
+    return {
+      botId: "primary",
+      agentId: "primary",
+      sessionId: "alice:primary",
+      compositionGenerationId: "test-composition-generation",
+      effectId: "tool:1:1:0",
+      toolCall: { id: "provider-call", name, input: {} },
+      turnType,
+      signal: new AbortController().signal,
+    };
+  }
+
+  test("offers a tool with no declaration on every turn type", async () => {
+    const root = await admissionRoot();
+    root.tools.register(work);
+    for (const turnType of ["chat", "automation", "subagent"] as const) {
+      expect(root.tools.schemas({ turnType }).map((s) => s.name)).toEqual([
+        "work",
+      ]);
+    }
+  });
+
+  test("trims the catalog to what the turn type admits", async () => {
+    const root = await admissionRoot();
+    root.tools.register(work);
+    root.tools.register(chatOnly);
+    root.tools.register(automationOnly);
+
+    expect(root.tools.schemas({ turnType: "chat" }).map((s) => s.name)).toEqual(
+      ["work", "send_to_user"],
+    );
+    expect(
+      root.tools.schemas({ turnType: "automation" }).map((s) => s.name),
+    ).toEqual(["work", "wake_parent"]);
+  });
+
+  test("bounds a tool declaration by the manifest ceiling", async () => {
+    const root = await admissionRoot();
+    root.tools.register(work, { admissionCeiling: ["automation"] });
+    root.tools.register(chatOnly, {
+      admissionCeiling: ["automation", "subagent"],
+    });
+
+    expect(root.tools.schemas({ turnType: "chat" })).toEqual([]);
+    expect(
+      root.tools.schemas({ turnType: "automation" }).map((s) => s.name),
+    ).toEqual(["work"]);
+  });
+
+  test("denies an out-of-admission call without executing it", async () => {
+    let executions = 0;
+    const root = await admissionRoot();
+    root.tools.register({
+      ...chatOnly,
+      execute: () => {
+        executions += 1;
+        return Promise.resolve({ content: "sent", isError: false });
+      },
+    });
+
+    const denied = await root.tools.prepare(
+      { id: "provider-call", name: "send_to_user", input: {} },
+      contextFor("send_to_user", "automation"),
+    );
+    expect(denied).toMatchObject({
+      kind: "denied",
+      result: { isError: true },
+    });
+    if (denied.kind !== "denied") throw new Error("expected a denial");
+    expect(denied.result.content).toContain("send_to_user");
+    expect(executions).toBe(0);
+
+    const ready = await root.tools.prepare(
+      { id: "provider-call", name: "send_to_user", input: {} },
+      contextFor("send_to_user", "chat"),
+    );
+    expect(ready.kind).toBe("ready");
+  });
+
+  test("denies a call the manifest ceiling excludes even when the tool allows it", async () => {
+    const root = await admissionRoot();
+    root.tools.register(chatOnly, { admissionCeiling: ["automation"] });
+    const denied = await root.tools.prepare(
+      { id: "provider-call", name: "send_to_user", input: {} },
+      contextFor("send_to_user", "chat"),
+    );
+    expect(denied.kind).toBe("denied");
+  });
+
+  test("carries endsTurn through execution and reconciliation", async () => {
+    const root = await admissionRoot();
+    root.tools.register({
+      name: "hand_off",
+      description: "Ends the Turn.",
+      inputSchema: { type: "object" },
+      execute: () =>
+        Promise.resolve({
+          content: "handed off",
+          isError: false,
+          endsTurn: true,
+        }),
+      reconcile: () =>
+        Promise.resolve({
+          status: "recovered" as const,
+          result: { content: "handed off", isError: false, endsTurn: true },
+        }),
+    });
+    const context = contextFor("hand_off", "automation");
+    const preparation = await root.tools.prepare(
+      { id: "provider-call", name: "hand_off", input: {} },
+      context,
+    );
+    if (preparation.kind !== "ready") throw new Error("tool was denied");
+    expect(await root.tools.executePrepared(preparation, context)).toEqual({
+      content: "handed off",
+      isError: false,
+      endsTurn: true,
+    });
+    expect(await root.tools.reconcilePrepared(preparation, context)).toEqual({
+      status: "recovered",
+      result: { content: "handed off", isError: false, endsTurn: true },
+    });
+  });
+  // -------------------------------------------------------------------------
+  // The second ceiling dimension: the subagent role (ADR 0017, slice G3).
+  //
+  // The registry treats a role exactly as it treats a turn type — an opaque
+  // string a registration may narrow itself by. It reads no meaning into
+  // "browserUse"; it only intersects declaration with manifest ceiling and
+  // filters.
+  // -------------------------------------------------------------------------
+
+  const desktop: ToolDefinition = {
+    name: "computer_exec",
+    description: "Runs a shell command on the Computer.",
+    inputSchema: { type: "object" },
+    admission: {
+      turnTypes: ["chat", "automation", "subagent"],
+      subagentRoles: ["executor", "computerUse"],
+    },
+    execute: () => Promise.resolve({ content: "ran", isError: false }),
+  };
+  const browser: ToolDefinition = {
+    name: "computer_browser",
+    description: "Drives the browser on the Computer.",
+    inputSchema: { type: "object" },
+    admission: {
+      turnTypes: ["chat", "automation", "subagent"],
+      subagentRoles: ["executor", "browserUse", "computerUse"],
+    },
+    execute: () => Promise.resolve({ content: "snapshot", isError: false }),
+  };
+
+  test("a turn that names no role is narrowed by no role", async () => {
+    const root = await admissionRoot();
+    root.tools.register(work);
+    root.tools.register(desktop);
+    expect(root.tools.schemas({ turnType: "chat" }).map((s) => s.name)).toEqual(
+      ["work", "computer_exec"],
+    );
+  });
+
+  test("trims the catalog to what the subagent role admits", async () => {
+    const root = await admissionRoot();
+    root.tools.register(work);
+    root.tools.register(desktop);
+    root.tools.register(browser);
+
+    expect(
+      root.tools
+        .schemas({ turnType: "subagent", subagentRole: "browserUse" })
+        .map((s) => s.name),
+    ).toEqual(["work", "computer_browser"]);
+    expect(
+      root.tools
+        .schemas({ turnType: "subagent", subagentRole: "computerUse" })
+        .map((s) => s.name),
+    ).toEqual(["work", "computer_exec", "computer_browser"]);
+    expect(
+      root.tools
+        .schemas({ turnType: "subagent", subagentRole: "watchVideo" })
+        .map((s) => s.name),
+    ).toEqual(["work"]);
+  });
+
+  test("bounds a role declaration by the manifest role ceiling", async () => {
+    const root = await admissionRoot();
+    root.tools.register(browser, { subagentRoleCeiling: ["executor"] });
+    expect(
+      root.tools
+        .schemas({ turnType: "subagent", subagentRole: "browserUse" })
+        .map((s) => s.name),
+    ).toEqual([]);
+    expect(
+      root.tools
+        .schemas({ turnType: "subagent", subagentRole: "executor" })
+        .map((s) => s.name),
+    ).toEqual(["computer_browser"]);
+  });
+
+  test("denies a call a role was never offered, without executing it", async () => {
+    let executions = 0;
+    const root = await admissionRoot();
+    root.tools.register({
+      ...desktop,
+      execute: () => {
+        executions += 1;
+        return Promise.resolve({ content: "ran", isError: false });
+      },
+    });
+    const preparation = await root.tools.prepare(
+      { id: "provider-call", name: "computer_exec", input: {} },
+      {
+        ...contextFor("computer_exec", "subagent"),
+        subagentRole: "browserUse",
+      },
+    );
+    expect(preparation.kind).toBe("denied");
+    if (preparation.kind !== "denied") throw new Error("expected a denial");
+    expect(preparation.result.isError).toBe(true);
+    expect(preparation.result.content).toContain("browserUse");
+    expect(executions).toBe(0);
+  });
+});

package/src/tools.ts

@@ -0,0 +1,385 @@
+import { type Context, Service } from "cordis";
+import {
+  admittedSubagentRolesV1,
+  admittedTurnTypesV1,
+  isSubagentRoleAdmittedV1,
+  type ToolCall,
+  type ToolDefinition,
+  type ToolEffectReconciliation,
+  type ToolExecution,
+  type ToolExecutionContext,
+  type ToolExecutionResult,
+  type ToolPreparation,
+  type ToolRegistrationOptions,
+  type ToolSchema,
+  type TurnTypeV1,
+} from "@frockbot/kernel-contracts";
+
+function sameToolCall(left: ToolCall, right: ToolCall): boolean {
+  return (
+    left.id === right.id &&
+    left.name === right.name &&
+    JSON.stringify(left.input) === JSON.stringify(right.input)
+  );
+}
+
+/** One registration: the tool, and the turn types it may ever be offered on. */
+interface RegisteredTool {
+  definition: ToolDefinition;
+  /**
+   * The tool's own declaration intersected with its Capability's durable
+   * manifest ceiling, resolved once at registration so admission cannot drift
+   * between the catalog the model saw and the call the loop admits.
+   */
+  admitted: readonly TurnTypeV1[];
+  /**
+   * The second ceiling dimension, resolved the same way and at the same
+   * moment: the subagent roles this tool may be offered to. `undefined` is
+   * every role — a tool that declares nothing is narrowed by nothing.
+   */
+  admittedRoles: readonly string[] | undefined;
+}
+
+export class ToolRegistry extends Service implements ToolExecution {
+  private definitions = new Map<string, RegisteredTool>();
+
+  constructor(ctx: Context) {
+    super(ctx, "tools");
+  }
+
+  register(
+    definition: ToolDefinition,
+    options?: ToolRegistrationOptions,
+  ): () => void {
+    if (this.definitions.has(definition.name)) {
+      throw new Error(`tool "${definition.name}" is already registered`);
+    }
+    const registered: RegisteredTool = {
+      definition,
+      admitted: admittedTurnTypesV1(
+        definition.admission?.turnTypes,
+        options?.admissionCeiling,
+      ),
+      admittedRoles: admittedSubagentRolesV1(
+        definition.admission?.subagentRoles,
+        options?.subagentRoleCeiling,
+      ),
+    };
+    this.definitions.set(definition.name, registered);
+    return () => {
+      if (this.definitions.get(definition.name) === registered) {
+        this.definitions.delete(definition.name);
+      }
+    };
+  }
+
+  schemas(admission: {
+    turnType: TurnTypeV1;
+    subagentRole?: string;
+  }): ToolSchema[] {
+    return [...this.definitions.values()]
+      .filter(
+        (registered) =>
+          registered.admitted.includes(admission.turnType) &&
+          isSubagentRoleAdmittedV1(
+            registered.admittedRoles,
+            admission.subagentRole,
+          ),
+      )
+      .map(({ definition: { name, description, inputSchema } }) => ({
+        name,
+        description,
+        inputSchema,
+      }));
+  }
+
+  prepare(
+    call: ToolCall,
+    context: ToolExecutionContext,
+  ): Promise<ToolPreparation> {
+    return this.ctx.waterfall("tools/pre-execute", call, context, async () => {
+      const registered = this.definitions.get(call.name);
+      if (!registered) {
+        return {
+          kind: "denied",
+          call,
+          result: { content: `Unknown tool: ${call.name}`, isError: true },
+        };
+      }
+      // Defence in depth: the catalog was already trimmed, so a call that
+      // arrives here names a tool the model was never offered.
+      if (!registered.admitted.includes(context.turnType)) {
+        return {
+          kind: "denied",
+          call,
+          result: {
+            content: `Tool is not available on a ${context.turnType} turn: ${call.name}`,
+            isError: true,
+          },
+        };
+      }
+      // The same defence on the second dimension. A `browserUse` subagent that
+      // names `computer_exec` was never offered it, and the ceiling says so
+      // here as well as in the catalog.
+      if (
+        !isSubagentRoleAdmittedV1(
+          registered.admittedRoles,
+          context.subagentRole,
+        )
+      ) {
+        return {
+          kind: "denied",
+          call,
+          result: {
+            content: `Tool is not available to a ${context.subagentRole} subagent: ${call.name}`,
+            isError: true,
+          },
+        };
+      }
+      const definition = registered.definition;
+      if (definition.validate && !definition.validate(call.input)) {
+        return {
+          kind: "denied",
+          call,
+          result: {
+            content: `Invalid input for tool: ${call.name}`,
+            isError: true,
+          },
+        };
+      }
+      return {
+        kind: "ready",
+        call,
+        idempotent: definition.idempotent ?? false,
+      };
+    });
+  }
+
+  async executePrepared(
+    preparation: Extract<ToolPreparation, { kind: "ready" }>,
+    context: ToolExecutionContext,
+  ): Promise<ToolExecutionResult> {
+    const definition = this.definitions.get(preparation.call.name)?.definition;
+    const initial = await this.ctx.waterfall(
+      "tools/execute",
+      preparation.call,
+      context,
+      () => {
+        if (!definition) {
+          return Promise.resolve({
+            content: `Tool became unavailable: ${preparation.call.name}`,
+            isError: true,
+          });
+        }
+        return definition.execute(preparation.call.input, context);
+      },
+    );
+    const result = await this.ctx.waterfall(
+      "tools/post-execute",
+      preparation.call,
+      initial,
+      context,
+      () => Promise.resolve(initial),
+    );
+    this.ctx.emit("tools/result", preparation.call, result);
+    return result;
+  }
+
+  /**
+   * Settles one durably open effect without exposing provider selection to the
+   * Agent loop. Idempotent definitions retry execution with the same effectId;
+   * other definitions must retrieve their original result.
+   */
+  async reconcilePrepared(
+    preparation: Extract<ToolPreparation, { kind: "ready" }>,
+    context: ToolExecutionContext,
+  ): Promise<ToolEffectReconciliation> {
+    const expectedCall = context.toolCall;
+    if (!expectedCall) {
+      return {
+        status: "unavailable",
+        reason: boundedReconciliationReason(
+          `Tool ${preparation.call.name} has no durable call identity for effect reconciliation`,
+          preparation.call.name,
+        ),
+      };
+    }
+    if (!sameToolCall(preparation.call, expectedCall)) {
+      return {
+        status: "unavailable",
+        reason: boundedReconciliationReason(
+          `Prepared tool ${preparation.call.name} does not match durable effect ${expectedCall.name}`,
+          expectedCall.name,
+        ),
+      };
+    }
+    const definition = this.definitions.get(expectedCall.name)?.definition;
+    if (!definition) {
+      return {
+        status: "unavailable",
+        reason: boundedReconciliationReason(
+          `Tool ${expectedCall.name} is unavailable for effect reconciliation`,
+          expectedCall.name,
+        ),
+      };
+    }
+    // Preparation is middleware-visible and therefore cannot be the authority
+    // for retry safety. Only the registered definition may declare an effect
+    // idempotent.
+    if (definition.idempotent === true) {
+      try {
+        return {
+          status: "recovered",
+          result: await this.executePrepared(
+            { ...preparation, call: expectedCall, idempotent: true },
+            context,
+          ),
+        };
+      } catch (error) {
+        return {
+          status: "unavailable",
+          reason: boundedReconciliationReason(error, expectedCall.name),
+        };
+      }
+    }
+    if (!definition.reconcile) {
+      return {
+        status: "unavailable",
+        reason: boundedReconciliationReason(
+          `Tool ${expectedCall.name} does not support effect reconciliation`,
+          expectedCall.name,
+        ),
+      };
+    }
+    try {
+      const outcome = normalizedReconciliation(
+        await definition.reconcile(expectedCall.input, context),
+        expectedCall.name,
+      );
+      if (outcome.status === "recovered") {
+        this.ctx.emit("tools/result", expectedCall, outcome.result);
+      }
+      return outcome;
+    } catch (error) {
+      return {
+        status: "unavailable",
+        reason: boundedReconciliationReason(error, expectedCall.name),
+      };
+    }
+  }
+}
+
+const TOOL_RECONCILIATION_REASON_MAX_BYTES = 512;
+const RECONCILIATION_REASON_ENCODER = new TextEncoder();
+
+function ownStringKeys(
+  value: Record<PropertyKey, unknown>,
+): string[] | undefined {
+  const keys = Reflect.ownKeys(value);
+  return keys.every((key): key is string => typeof key === "string")
+    ? keys.sort()
+    : undefined;
+}
+
+function hasExactKeys(
+  value: Record<PropertyKey, unknown>,
+  expected: readonly string[],
+): boolean {
+  const keys = ownStringKeys(value);
+  const sortedExpected = [...expected].sort();
+  return (
+    keys !== undefined &&
+    keys.length === sortedExpected.length &&
+    keys.every((key, index) => key === sortedExpected[index])
+  );
+}
+
+function normalizedReconciliation(
+  input: unknown,
+  toolName: string,
+): ToolEffectReconciliation {
+  if (typeof input !== "object" || input === null) {
+    return invalidReconciliation(toolName);
+  }
+  const record = input as Record<PropertyKey, unknown>;
+  if (
+    hasExactKeys(record, ["result", "status"]) &&
+    record.status === "recovered"
+  ) {
+    const result = record.result;
+    if (
+      typeof result === "object" &&
+      result !== null &&
+      (hasExactKeys(result as Record<PropertyKey, unknown>, [
+        "content",
+        "isError",
+      ]) ||
+        hasExactKeys(result as Record<PropertyKey, unknown>, [
+          "content",
+          "isError",
+          "endsTurn",
+        ]))
+    ) {
+      const resultRecord = result as Record<PropertyKey, unknown>;
+      if (
+        typeof resultRecord.content === "string" &&
+        typeof resultRecord.isError === "boolean" &&
+        (resultRecord.endsTurn === undefined ||
+          typeof resultRecord.endsTurn === "boolean")
+      ) {
+        return {
+          status: "recovered",
+          result: {
+            content: resultRecord.content,
+            isError: resultRecord.isError,
+            // A recovered hand-off still ends the Turn it was recorded on.
+            ...(resultRecord.endsTurn === undefined
+              ? {}
+              : { endsTurn: resultRecord.endsTurn }),
+          },
+        };
+      }
+    }
+  }
+  if (
+    hasExactKeys(record, ["reason", "status"]) &&
+    record.status === "unavailable" &&
+    typeof record.reason === "string"
+  ) {
+    return {
+      status: "unavailable",
+      reason: boundedReconciliationReason(record.reason, toolName),
+    };
+  }
+  return invalidReconciliation(toolName);
+}
+
+function invalidReconciliation(toolName: string): ToolEffectReconciliation {
+  return {
+    status: "unavailable",
+    reason: boundedReconciliationReason(
+      `Tool ${toolName} returned an invalid reconciliation outcome`,
+      toolName,
+    ),
+  };
+}
+
+function boundedReconciliationReason(error: unknown, toolName: string): string {
+  const reason =
+    typeof error === "string"
+      ? error
+      : error instanceof Error
+        ? error.message
+        : "Tool effect is not currently retrievable";
+  const normalized = reason.trim() || `Tool ${toolName} effect is unavailable`;
+  let bounded = "";
+  let bytes = 0;
+  for (const character of normalized) {
+    const characterBytes =
+      RECONCILIATION_REASON_ENCODER.encode(character).byteLength;
+    if (bytes + characterBytes > TOOL_RECONCILIATION_REASON_MAX_BYTES) break;
+    bounded += character;
+    bytes += characterBytes;
+  }
+  return bounded || `Tool ${toolName} effect is unavailable`;
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "lib": ["ES2023", "DOM"],
+    "types": ["bun"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/README.md

@@ -1,3 +0,0 @@
-# @frockbot/plugin-tools
-
-Placeholder reserving this name. See https://github.com/timoconnellaus/frockbot.