opensquid 0.5.395

package/dist/runtime/agent_bridge/tool_dispatcher.js

@@ -0,0 +1,104 @@
+/**
+ * agent_bridge — tool dispatcher (WAB.4, 0.5.97).
+ *
+ * Authoritative spec: `docs/tasks/T-warm-agent-chat-bridge.md` WAB.4.
+ * Architecture: `docs/tasks/WAB.1-architecture.md` decisions (e) + (f).
+ *
+ * Responsibility:
+ *   1. Hold a name-indexed registry of `ToolSpec` + `ToolHandler` pairs.
+ *   2. On `call(name, input, ctx)`: look up the spec, run the spec's
+ *      optional `validate(input)` guard (throws on bad input), forward
+ *      the validated value to the handler, return the handler's string
+ *      output (which the agent loop feeds back as a `tool_result` block).
+ *   3. On `list()`: return the snapshot of registered specs in the order
+ *      they were registered. The agent loop passes this to
+ *      `Anthropic.messages.create({ tools })`.
+ *
+ * Non-responsibility:
+ *   - Does NOT call the model. The agent loop (`agent_loop.ts`) owns the
+ *     SDK round-trip; the dispatcher only resolves `tool_use` blocks.
+ *   - Does NOT manage tool lifecycle (registration happens once per
+ *     session at construction; no add/remove at runtime in WAB.4).
+ *   - Does NOT auto-convert zod → JSON Schema. Tool authors supply both
+ *     `input_schema` (JSON Schema, for the model) and `validate`
+ *     (runtime guard, for the dispatcher) — see types.ts comment.
+ *
+ * Error contract:
+ *   - Unknown name → `Error` with prefix `tool_dispatcher: unknown tool`.
+ *     The agent loop catches and surfaces as a fatal turn error (the
+ *     model invoked something not in the declared list — likely a
+ *     schema/spec mismatch).
+ *   - Validation failure → re-throws the validator's error (zod's
+ *     `ZodError` carries structured detail; ajv's `ValidationError`
+ *     similarly). Caller can inspect the error class.
+ *   - Handler rejection → surfaces unmodified.
+ *
+ * Imports from: ./types.js.
+ * Imported by: agent_loop.ts (caller), pack_binding.ts (WAB.6
+ *   builder), daemon.ts (WAB.7 wiring).
+ */
+// ---------------------------------------------------------------------------
+// SimpleToolDispatcher — the only impl shipped in WAB.4.
+//
+// Map-backed (O(1) lookup), insertion-order-preserving for `list()`. The
+// constructor accepts an optional initial registration list; `register`
+// adds more (throws on duplicate name — sessions should never silently
+// shadow a tool).
+//
+// Naming: prefixed `Simple` so a future WAB iteration (e.g. priority
+// routing, MCP-tool delegation) can add a parallel `LayeredToolDispatcher`
+// without renaming this one.
+// ---------------------------------------------------------------------------
+export class SimpleToolDispatcher {
+    tools = new Map();
+    constructor(initial = []) {
+        for (const t of initial)
+            this.register(t);
+    }
+    /**
+     * Add a tool to the registry. Throws on duplicate name — silent
+     * shadowing would let one pack hijack another pack's tool surface.
+     */
+    register(t) {
+        if (this.tools.has(t.spec.name)) {
+            throw new Error(`tool_dispatcher: duplicate tool name '${t.spec.name}' — refusing to shadow`);
+        }
+        this.tools.set(t.spec.name, { spec: t.spec, handler: t.handler });
+    }
+    /** Live tool count (telemetry / tests). */
+    get size() {
+        return this.tools.size;
+    }
+    /** Whether a tool with this name is registered. */
+    has(name) {
+        return this.tools.has(name);
+    }
+    // -------------------------------------------------------------------------
+    // ToolDispatcher impl
+    // -------------------------------------------------------------------------
+    list() {
+        // Snapshot — callers should be free to pass this directly to the SDK
+        // without worrying about it being mutated underneath them. The Map's
+        // values() iterator preserves insertion order, matching how authors
+        // expect tools to appear in the model's tool list.
+        return Array.from(this.tools.values()).map((t) => t.spec);
+    }
+    async call(name, input, ctx) {
+        const tool = this.tools.get(name);
+        if (tool === undefined) {
+            // Include the registered tool names in the message — debugging
+            // why the model picked a non-existent tool is much easier when
+            // you can see what WAS available at dispatch time.
+            const available = Array.from(this.tools.keys()).join(', ');
+            throw new Error(`tool_dispatcher: unknown tool '${name}' (registered: [${available}])`);
+        }
+        // Spec opted into runtime validation → run it. The validator may
+        // narrow the type by returning a refined value; we forward THAT to
+        // the handler so zod's `.parse()` doubles as a type-narrowing
+        // step. Validators that don't narrow can just return the input
+        // unchanged.
+        const validated = tool.spec.validate !== undefined ? tool.spec.validate(input) : input;
+        return tool.handler(validated, ctx);
+    }
+}
+//# sourceMappingURL=tool_dispatcher.js.map

package/dist/runtime/agent_bridge/tool_dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool_dispatcher.js","sourceRoot":"","sources":["../../../src/runtime/agent_bridge/tool_dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AA0BH,8EAA8E;AAC9E,yDAAyD;AACzD,EAAE;AACF,yEAAyE;AACzE,wEAAwE;AACxE,uEAAuE;AACvE,kBAAkB;AAClB,EAAE;AACF,qEAAqE;AACrE,2EAA2E;AAC3E,6BAA6B;AAC7B,8EAA8E;AAE9E,MAAM,OAAO,oBAAoB;IACd,KAAK,GAAG,IAAI,GAAG,EAA0B,CAAC;IAE3D,YAAY,UAA8B,EAAE;QAC1C,KAAK,MAAM,CAAC,IAAI,OAAO;YAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC5C,CAAC;IAED;;;OAGG;IACH,QAAQ,CAAC,CAAmB;QAC1B,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC,IAAI,CAAC,IAAI,wBAAwB,CAAC,CAAC;QAChG,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IACpE,CAAC;IAED,2CAA2C;IAC3C,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED,mDAAmD;IACnD,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,4EAA4E;IAC5E,sBAAsB;IACtB,4EAA4E;IAE5E,IAAI;QACF,qEAAqE;QACrE,qEAAqE;QACrE,oEAAoE;QACpE,mDAAmD;QACnD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC5D,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAY,EAAE,KAAc,EAAE,GAAgB;QACvD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,+DAA+D;YAC/D,+DAA+D;YAC/D,mDAAmD;YACnD,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC3D,MAAM,IAAI,KAAK,CAAC,kCAAkC,IAAI,mBAAmB,SAAS,IAAI,CAAC,CAAC;QAC1F,CAAC;QACD,iEAAiE;QACjE,mEAAmE;QACnE,8DAA8D;QAC9D,+DAA+D;QAC/D,aAAa;QACb,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QACvF,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IACtC,CAAC;CACF"}

package/dist/runtime/agent_bridge/tools/chat_send.d.ts

@@ -0,0 +1,56 @@
+/**
+ * agent_bridge built-in tool — `chat_send`.
+ *
+ * Authoritative spec: `docs/tasks/T-warm-agent-chat-bridge.md` WAB.6 §"Tool
+ * surface". Wraps the chat-daemon's `send` JSON-RPC method so the warm
+ * agent can reply on the same channel that delivered the inbound message.
+ *
+ * Responsibility:
+ *   1. Build a `project:<platform>` shorthand from the session's platform if
+ *      the model didn't supply an explicit `channel` arg — the most common
+ *      path is "reply on the same Telegram topic that delivered me".
+ *   2. Forward the request to the chat-daemon over its UNIX socket via the
+ *      same one-shot JSON-RPC pattern used by `src/mcp/chat-bridge-server.ts`
+ *      and `src/chat_daemon/client.ts`. We re-implement the socket dance here
+ *      (rather than importing) because:
+ *        - `chat-bridge-server.ts` is an MCP-shaped binary, not a reusable
+ *          library. Pulling its handlers into the agent-bridge would couple
+ *          tool wiring to MCP transport boundaries.
+ *      The duplicated socket logic is small (~40 LOC) and will collapse onto
+ *      a shared `src/chat_daemon/client.ts` in a later cleanup pass.
+ *
+ * Non-responsibility:
+ *   - Does NOT spawn the daemon. If the daemon isn't running, the call
+ *     fails — the error surfaces back to the model as the tool_result so it
+ *     can decide whether to retry or surrender.
+ *   - Does NOT validate the channel URI scheme; the daemon does that.
+ *
+ * Imports from: node:net, node:os, node:path, ../types.js, ../../paths.js,
+ *   zod.
+ * Imported by: ./index.ts (tools barrel).
+ */
+import type { ToolHandler, ToolSpec } from '../types.js';
+interface DaemonSendResult {
+    ok: boolean;
+    platform: string;
+    message_id: string;
+    delivered_at: string;
+}
+export interface DaemonSendParams {
+    channel: string;
+    text: string;
+    replyTo?: string;
+    threadId?: string;
+    /** CAT.4 — absolute path to a local image to deliver as a photo (text →
+     *  caption). Forwarded to the daemon `send` RPC as `mediaPath`. */
+    imagePath?: string;
+}
+export type DaemonSendFn = (params: DaemonSendParams) => Promise<DaemonSendResult>;
+/** Default daemon-send — the shared client's one-shot UDS RPC (CL.3: was a local copy
+ *  of the socket dance; now delegates to the one owner src/chat_daemon/client.ts). The
+ *  local `DaemonSendParams`/`DaemonSendResult` are structurally identical to the client's. */
+export declare const defaultDaemonSend: DaemonSendFn;
+export declare const chatSendSpec: ToolSpec;
+export declare function makeChatSendHandler(daemonSend?: DaemonSendFn): ToolHandler;
+export {};
+//# sourceMappingURL=chat_send.d.ts.map

package/dist/runtime/agent_bridge/tools/chat_send.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat_send.d.ts","sourceRoot":"","sources":["../../../../src/runtime/agent_bridge/tools/chat_send.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAKH,OAAO,KAAK,EAAe,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAMtE,UAAU,gBAAgB;IACxB,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB;AAOD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;uEACmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,gBAAgB,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAEnF;;8FAE8F;AAC9F,eAAO,MAAM,iBAAiB,EAAE,YAA2C,CAAC;AA0B5E,eAAO,MAAM,YAAY,EAAE,QA0B1B,CAAC;AAOF,wBAAgB,mBAAmB,CAAC,UAAU,GAAE,YAAgC,GAAG,WAAW,CAa7F"}

package/dist/runtime/agent_bridge/tools/chat_send.js

@@ -0,0 +1,101 @@
+/**
+ * agent_bridge built-in tool — `chat_send`.
+ *
+ * Authoritative spec: `docs/tasks/T-warm-agent-chat-bridge.md` WAB.6 §"Tool
+ * surface". Wraps the chat-daemon's `send` JSON-RPC method so the warm
+ * agent can reply on the same channel that delivered the inbound message.
+ *
+ * Responsibility:
+ *   1. Build a `project:<platform>` shorthand from the session's platform if
+ *      the model didn't supply an explicit `channel` arg — the most common
+ *      path is "reply on the same Telegram topic that delivered me".
+ *   2. Forward the request to the chat-daemon over its UNIX socket via the
+ *      same one-shot JSON-RPC pattern used by `src/mcp/chat-bridge-server.ts`
+ *      and `src/chat_daemon/client.ts`. We re-implement the socket dance here
+ *      (rather than importing) because:
+ *        - `chat-bridge-server.ts` is an MCP-shaped binary, not a reusable
+ *          library. Pulling its handlers into the agent-bridge would couple
+ *          tool wiring to MCP transport boundaries.
+ *      The duplicated socket logic is small (~40 LOC) and will collapse onto
+ *      a shared `src/chat_daemon/client.ts` in a later cleanup pass.
+ *
+ * Non-responsibility:
+ *   - Does NOT spawn the daemon. If the daemon isn't running, the call
+ *     fails — the error surfaces back to the model as the tool_result so it
+ *     can decide whether to retry or surrender.
+ *   - Does NOT validate the channel URI scheme; the daemon does that.
+ *
+ * Imports from: node:net, node:os, node:path, ../types.js, ../../paths.js,
+ *   zod.
+ * Imported by: ./index.ts (tools barrel).
+ */
+import { z } from 'zod';
+import { sendChat } from '../../../chat_daemon/client.js';
+/** Default daemon-send — the shared client's one-shot UDS RPC (CL.3: was a local copy
+ *  of the socket dance; now delegates to the one owner src/chat_daemon/client.ts). The
+ *  local `DaemonSendParams`/`DaemonSendResult` are structurally identical to the client's. */
+export const defaultDaemonSend = (params) => sendChat(params);
+// ---------------------------------------------------------------------------
+// Tool input schema + spec
+//
+// `text` is required (no point in an empty reply). `channel` defaults to
+// `project:<platform>` derived from the session key at handler-time — so
+// the model gets the most common path right with zero args. Explicit
+// `channel` overrides for callers that need to cross-post.
+// ---------------------------------------------------------------------------
+const ChatSendInput = z
+    .object({
+    text: z.string(),
+    channel: z.string().min(1).optional(),
+    /** CAT.4 — optional absolute path to a local image to attach. When set,
+     *  `text` becomes the photo caption and may be empty. */
+    imagePath: z.string().min(1).optional(),
+})
+    // A reply must carry SOMETHING: either non-empty text or an image. (Was
+    // `text.min(1)`; relaxed so image-only sends are valid, with caption empty.)
+    .refine((v) => v.text.length > 0 || v.imagePath !== undefined, {
+    message: 'chat_send requires non-empty text or an imagePath',
+});
+export const chatSendSpec = {
+    name: 'chat_send',
+    description: 'Send a reply to the user on the active chat channel. Defaults to the channel that delivered the inbound message.',
+    input_schema: {
+        type: 'object',
+        properties: {
+            text: {
+                type: 'string',
+                description: 'Reply body (plain text). Becomes the caption when imagePath is set.',
+            },
+            channel: {
+                type: 'string',
+                description: 'Optional channel override. Defaults to "project:<platform>" derived from the inbound session.',
+            },
+            imagePath: {
+                type: 'string',
+                description: 'Optional absolute path to a local image to send as a photo. When set, text is the caption and may be empty.',
+            },
+        },
+        required: ['text'],
+        additionalProperties: false,
+    },
+    validate: (input) => ChatSendInput.parse(input),
+};
+// ---------------------------------------------------------------------------
+// Handler factory — closes over the daemon-send seam so tests can inject
+// a stub without monkey-patching node:net.
+// ---------------------------------------------------------------------------
+export function makeChatSendHandler(daemonSend = defaultDaemonSend) {
+    return async (input, ctx) => {
+        const parsed = input; // already narrowed by validate
+        const channel = parsed.channel ?? `project:${ctx.sessionKey.platform}`;
+        const params = {
+            channel,
+            text: parsed.text,
+            ...(ctx.sessionKey.threadId !== undefined ? { threadId: ctx.sessionKey.threadId } : {}),
+            ...(parsed.imagePath !== undefined ? { imagePath: parsed.imagePath } : {}),
+        };
+        const result = await daemonSend(params);
+        return `sent ok (platform=${result.platform}, message_id=${result.message_id})`;
+    };
+}
+//# sourceMappingURL=chat_send.js.map

package/dist/runtime/agent_bridge/tools/chat_send.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat_send.js","sourceRoot":"","sources":["../../../../src/runtime/agent_bridge/tools/chat_send.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AA+B1D;;8FAE8F;AAC9F,MAAM,CAAC,MAAM,iBAAiB,GAAiB,CAAC,MAAM,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAE5E,8EAA8E;AAC9E,2BAA2B;AAC3B,EAAE;AACF,yEAAyE;AACzE,yEAAyE;AACzE,qEAAqE;AACrE,2DAA2D;AAC3D,8EAA8E;AAE9E,MAAM,aAAa,GAAG,CAAC;KACpB,MAAM,CAAC;IACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACrC;6DACyD;IACzD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CACxC,CAAC;IACF,wEAAwE;IACxE,6EAA6E;KAC5E,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,SAAS,KAAK,SAAS,EAAE;IAC7D,OAAO,EAAE,mDAAmD;CAC7D,CAAC,CAAC;AAGL,MAAM,CAAC,MAAM,YAAY,GAAa;IACpC,IAAI,EAAE,WAAW;IACjB,WAAW,EACT,kHAAkH;IACpH,YAAY,EAAE;QACZ,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,IAAI,EAAE;gBACJ,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,qEAAqE;aACnF;YACD,OAAO,EAAE;gBACP,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,+FAA+F;aAClG;YACD,SAAS,EAAE;gBACT,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,6GAA6G;aAChH;SACF;QACD,QAAQ,EAAE,CAAC,MAAM,CAAC;QAClB,oBAAoB,EAAE,KAAK;KAC5B;IACD,QAAQ,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC;CAChD,CAAC;AAEF,8EAA8E;AAC9E,yEAAyE;AACzE,2CAA2C;AAC3C,8EAA8E;AAE9E,MAAM,UAAU,mBAAmB,CAAC,aAA2B,iBAAiB;IAC9E,OAAO,KAAK,EAAE,KAAK,EAAE,GAAgB,EAAE,EAAE;QACvC,MAAM,MAAM,GAAG,KAAuB,CAAC,CAAC,+BAA+B;QACvE,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,WAAW,GAAG,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC;QACvE,MAAM,MAAM,GAAqB;YAC/B,OAAO;YACP,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvF,GAAG,CAAC,MAAM,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC3E,CAAC;QACF,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC,CAAC;QACxC,OAAO,qBAAqB,MAAM,CAAC,QAAQ,gBAAgB,MAAM,CAAC,UAAU,GAAG,CAAC;IAClF,CAAC,CAAC;AACJ,CAAC"}

package/dist/runtime/agent_bridge/tools/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * agent_bridge built-in tools — barrel + BUILT_INS registry.
+ *
+ * Authoritative spec: `docs/tasks/T-warm-agent-chat-bridge.md` WAB.6 §"Tool
+ * surface". The three built-ins (`chat_send`, `recall`, `store_lesson`) are
+ * shipped as factories — `pack_binding.ts` constructs them with the
+ * runtime-wide dependencies (RagBackend, optional daemon-send seam) and
+ * assembles the final `SimpleToolDispatcher`.
+ *
+ * Why factories (not pre-built `ToolRegistration` objects):
+ *   - `chat_send` needs a daemon-send seam (closes over the UDS socket).
+ *   - `recall` needs the `RagBackend` instance.
+ *   - `store_lesson` needs an optional clock seam for tests.
+ *   Hard-coding these into a singleton list would force every consumer to
+ *   take the production wiring even in unit tests.
+ *
+ * `BUILT_INS` is the sealed list of names. Used by `pack_binding.ts` to
+ * iterate the built-in tool set and apply `disable_builtins` filtering.
+ * Matches `BuiltinToolName` from `src/packs/schemas/chat_agent.ts` — the
+ * two are kept in lockstep; adding a future built-in requires updating
+ * BOTH (and the schema enum + tests).
+ *
+ * Imports from: ./chat_send.js, ./recall.js, ./store_lesson.js.
+ * Imported by: ../pack_binding.ts.
+ */
+import type { BuiltinToolName } from '../../../packs/schemas/chat_agent.js';
+export { chatSendSpec, defaultDaemonSend, makeChatSendHandler, type DaemonSendFn, type DaemonSendParams, } from './chat_send.js';
+export { recallSpec, makeRecallHandler } from './recall.js';
+export { bufferPath as storeLessonBufferPath, makeStoreLessonHandler, storeLessonSpec, type MakeStoreLessonHandlerOptions, } from './store_lesson.js';
+/**
+ * Sealed list of built-in tool names. Order matches the spec's enumeration
+ * (chat_send, recall, store_lesson) and is the same insertion order the
+ * dispatcher will reflect via `list()`. Type-checked against
+ * `BuiltinToolName` so a drift between the schema enum and this array
+ * surfaces at compile time.
+ */
+export declare const BUILT_INS: readonly BuiltinToolName[];
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/agent_bridge/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/runtime/agent_bridge/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AAE5E,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,YAAY,EACjB,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,UAAU,IAAI,qBAAqB,EACnC,sBAAsB,EACtB,eAAe,EACf,KAAK,6BAA6B,GACnC,MAAM,mBAAmB,CAAC;AAE3B;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,EAAE,SAAS,eAAe,EAA4C,CAAC"}

package/dist/runtime/agent_bridge/tools/index.js

@@ -0,0 +1,37 @@
+/**
+ * agent_bridge built-in tools — barrel + BUILT_INS registry.
+ *
+ * Authoritative spec: `docs/tasks/T-warm-agent-chat-bridge.md` WAB.6 §"Tool
+ * surface". The three built-ins (`chat_send`, `recall`, `store_lesson`) are
+ * shipped as factories — `pack_binding.ts` constructs them with the
+ * runtime-wide dependencies (RagBackend, optional daemon-send seam) and
+ * assembles the final `SimpleToolDispatcher`.
+ *
+ * Why factories (not pre-built `ToolRegistration` objects):
+ *   - `chat_send` needs a daemon-send seam (closes over the UDS socket).
+ *   - `recall` needs the `RagBackend` instance.
+ *   - `store_lesson` needs an optional clock seam for tests.
+ *   Hard-coding these into a singleton list would force every consumer to
+ *   take the production wiring even in unit tests.
+ *
+ * `BUILT_INS` is the sealed list of names. Used by `pack_binding.ts` to
+ * iterate the built-in tool set and apply `disable_builtins` filtering.
+ * Matches `BuiltinToolName` from `src/packs/schemas/chat_agent.ts` — the
+ * two are kept in lockstep; adding a future built-in requires updating
+ * BOTH (and the schema enum + tests).
+ *
+ * Imports from: ./chat_send.js, ./recall.js, ./store_lesson.js.
+ * Imported by: ../pack_binding.ts.
+ */
+export { chatSendSpec, defaultDaemonSend, makeChatSendHandler, } from './chat_send.js';
+export { recallSpec, makeRecallHandler } from './recall.js';
+export { bufferPath as storeLessonBufferPath, makeStoreLessonHandler, storeLessonSpec, } from './store_lesson.js';
+/**
+ * Sealed list of built-in tool names. Order matches the spec's enumeration
+ * (chat_send, recall, store_lesson) and is the same insertion order the
+ * dispatcher will reflect via `list()`. Type-checked against
+ * `BuiltinToolName` so a drift between the schema enum and this array
+ * surfaces at compile time.
+ */
+export const BUILT_INS = ['chat_send', 'recall', 'store_lesson'];
+//# sourceMappingURL=index.js.map

package/dist/runtime/agent_bridge/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/runtime/agent_bridge/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,GAGpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,UAAU,IAAI,qBAAqB,EACnC,sBAAsB,EACtB,eAAe,GAEhB,MAAM,mBAAmB,CAAC;AAE3B;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,SAAS,GAA+B,CAAC,WAAW,EAAE,QAAQ,EAAE,cAAc,CAAC,CAAC"}

package/dist/runtime/agent_bridge/tools/recall.d.ts

@@ -0,0 +1,38 @@
+/**
+ * agent_bridge built-in tool — `recall`.
+ *
+ * Authoritative spec: `docs/tasks/T-warm-agent-chat-bridge.md` WAB.6 §"Tool
+ * surface". Wraps the project-scoped RAG backend's `recall(query, k)` method.
+ *
+ * Responsibility:
+ *   1. Validate the agent-supplied `{query, k?}` input.
+ *   2. Call the injected `RagBackend.recall(query, k)`.
+ *   3. Serialize the hit list into a compact string suitable for feeding
+ *      back as a `tool_result.content`.
+ *
+ * Non-responsibility:
+ *   - Does NOT own backend lifecycle. The `RagBackend` is constructed once
+ *     per daemon (or per project, depending on WAB.7 wiring) and passed in.
+ *   - Does NOT scope by `sessionKey`. Phase-1 RAG backends are project-scoped
+ *     by construction (the libsql DB lives under the project's data dir) —
+ *     a per-session scope would require a multi-tenant key column that the
+ *     `RagBackend` interface does not expose today. The `ToolContext` is
+ *     accepted for symmetry with the other tools, but the project scope is
+ *     already baked into the backend instance.
+ *
+ * Output format:
+ *   When the backend returns hits, we format them as a small newline-
+ *   delimited list with `score: <0.xx>` + `source: <fused|semantic|lexical>`
+ *   prefixes — terse enough that the model can copy-paste a quotation
+ *   without first parsing JSON. When the backend returns `[]`, we surface
+ *   "no results" rather than an empty string so the model doesn't silently
+ *   misinterpret a successful-but-empty call as "tool errored".
+ *
+ * Imports from: zod, ../../../rag/types.js, ../types.js.
+ * Imported by: ./index.ts (tools barrel).
+ */
+import type { RagBackend } from '../../../rag/types.js';
+import type { ToolHandler, ToolSpec } from '../types.js';
+export declare const recallSpec: ToolSpec;
+export declare function makeRecallHandler(backend: RagBackend): ToolHandler;
+//# sourceMappingURL=recall.d.ts.map

package/dist/runtime/agent_bridge/tools/recall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall.d.ts","sourceRoot":"","sources":["../../../../src/runtime/agent_bridge/tools/recall.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAa,MAAM,uBAAuB,CAAC;AACnE,OAAO,KAAK,EAAe,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAgBtE,eAAO,MAAM,UAAU,EAAE,QAmBxB,CAAC;AAOF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,UAAU,GAAG,WAAW,CASlE"}

package/dist/runtime/agent_bridge/tools/recall.js

@@ -0,0 +1,90 @@
+/**
+ * agent_bridge built-in tool — `recall`.
+ *
+ * Authoritative spec: `docs/tasks/T-warm-agent-chat-bridge.md` WAB.6 §"Tool
+ * surface". Wraps the project-scoped RAG backend's `recall(query, k)` method.
+ *
+ * Responsibility:
+ *   1. Validate the agent-supplied `{query, k?}` input.
+ *   2. Call the injected `RagBackend.recall(query, k)`.
+ *   3. Serialize the hit list into a compact string suitable for feeding
+ *      back as a `tool_result.content`.
+ *
+ * Non-responsibility:
+ *   - Does NOT own backend lifecycle. The `RagBackend` is constructed once
+ *     per daemon (or per project, depending on WAB.7 wiring) and passed in.
+ *   - Does NOT scope by `sessionKey`. Phase-1 RAG backends are project-scoped
+ *     by construction (the libsql DB lives under the project's data dir) —
+ *     a per-session scope would require a multi-tenant key column that the
+ *     `RagBackend` interface does not expose today. The `ToolContext` is
+ *     accepted for symmetry with the other tools, but the project scope is
+ *     already baked into the backend instance.
+ *
+ * Output format:
+ *   When the backend returns hits, we format them as a small newline-
+ *   delimited list with `score: <0.xx>` + `source: <fused|semantic|lexical>`
+ *   prefixes — terse enough that the model can copy-paste a quotation
+ *   without first parsing JSON. When the backend returns `[]`, we surface
+ *   "no results" rather than an empty string so the model doesn't silently
+ *   misinterpret a successful-but-empty call as "tool errored".
+ *
+ * Imports from: zod, ../../../rag/types.js, ../types.js.
+ * Imported by: ./index.ts (tools barrel).
+ */
+import { z } from 'zod';
+import { resolveRecallScope } from '../../../rag/scope.js';
+// ---------------------------------------------------------------------------
+// Input schema — mirrors the `recall` primitive's argSchema in
+// `src/functions/rag.ts` (query non-empty, k bounded 1..100). Default k=5
+// matches the primitive's default for parity.
+// ---------------------------------------------------------------------------
+const RecallInput = z.object({
+    query: z.string().min(1),
+    k: z.number().int().positive().max(100).optional(),
+});
+const DEFAULT_K = 5;
+export const recallSpec = {
+    name: 'recall',
+    description: 'Recall lessons + memories from the project knowledge base via fused semantic + lexical search.',
+    input_schema: {
+        type: 'object',
+        properties: {
+            query: { type: 'string', description: 'Natural-language query.' },
+            k: {
+                type: 'integer',
+                description: `Max number of hits to return (default ${DEFAULT_K}, bounds 1..100).`,
+                minimum: 1,
+                maximum: 100,
+            },
+        },
+        required: ['query'],
+        additionalProperties: false,
+    },
+    validate: (input) => RecallInput.parse(input),
+};
+// ---------------------------------------------------------------------------
+// Handler factory — closes over the `RagBackend` instance so per-project
+// or per-daemon wiring stays the caller's choice (WAB.7).
+// ---------------------------------------------------------------------------
+export function makeRecallHandler(backend) {
+    return async (input, _ctx) => {
+        const parsed = input;
+        const k = parsed.k ?? DEFAULT_K;
+        const scope = await resolveRecallScope();
+        const hits = await backend.recall(parsed.query, k, scope);
+        if (hits.length === 0)
+            return `no results for query=${JSON.stringify(parsed.query)}`;
+        return hits.map(formatHit).join('\n---\n');
+    };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function formatHit(hit) {
+    const tagStr = hit.lesson.tags.length > 0 ? ` tags=[${hit.lesson.tags.join(',')}]` : '';
+    return [
+        `id=${hit.lesson.id} score=${hit.score.toFixed(3)} source=${hit.source}${tagStr}`,
+        hit.lesson.content,
+    ].join('\n');
+}
+//# sourceMappingURL=recall.js.map

package/dist/runtime/agent_bridge/tools/recall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall.js","sourceRoot":"","sources":["../../../../src/runtime/agent_bridge/tools/recall.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAI3D,8EAA8E;AAC9E,+DAA+D;AAC/D,0EAA0E;AAC1E,8CAA8C;AAC9C,8EAA8E;AAE9E,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;CACnD,CAAC,CAAC;AAGH,MAAM,SAAS,GAAG,CAAC,CAAC;AAEpB,MAAM,CAAC,MAAM,UAAU,GAAa;IAClC,IAAI,EAAE,QAAQ;IACd,WAAW,EACT,gGAAgG;IAClG,YAAY,EAAE;QACZ,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,yBAAyB,EAAE;YACjE,CAAC,EAAE;gBACD,IAAI,EAAE,SAAS;gBACf,WAAW,EAAE,yCAAyC,SAAS,mBAAmB;gBAClF,OAAO,EAAE,CAAC;gBACV,OAAO,EAAE,GAAG;aACb;SACF;QACD,QAAQ,EAAE,CAAC,OAAO,CAAC;QACnB,oBAAoB,EAAE,KAAK;KAC5B;IACD,QAAQ,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC;CAC9C,CAAC;AAEF,8EAA8E;AAC9E,yEAAyE;AACzE,0DAA0D;AAC1D,8EAA8E;AAE9E,MAAM,UAAU,iBAAiB,CAAC,OAAmB;IACnD,OAAO,KAAK,EAAE,KAAK,EAAE,IAAiB,EAAE,EAAE;QACxC,MAAM,MAAM,GAAG,KAAqB,CAAC;QACrC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,SAAS,CAAC;QAChC,MAAM,KAAK,GAAG,MAAM,kBAAkB,EAAE,CAAC;QACzC,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;QAC1D,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,wBAAwB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QACrF,OAAO,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC7C,CAAC,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,SAAS,SAAS,CAAC,GAAc;IAC/B,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACxF,OAAO;QACL,MAAM,GAAG,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,MAAM,GAAG,MAAM,EAAE;QACjF,GAAG,CAAC,MAAM,CAAC,OAAO;KACnB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/runtime/agent_bridge/tools/store_lesson.d.ts

@@ -0,0 +1,41 @@
+/**
+ * agent_bridge built-in tool — `store_lesson`.
+ *
+ * Authoritative spec: `docs/tasks/T-warm-agent-chat-bridge.md` WAB.6 §"Tool
+ * surface" + memory `project_opensquid_wedge_gate_two_stages` Stage 1 +
+ * `project_opensquid_automation_buffer_pattern`.
+ *
+ * Why the automation buffer (not direct wedge-gate `capturePendingLesson`):
+ *   The existing `src/runtime/wedge/capture.ts` writes to
+ *   `~/.opensquid/sessions/<sessionId>/pending-lessons/potential-lessons/`
+ *   — the buffer is SESSION-scoped, keyed by an opensquid hook session id
+ *   (provided by the host's hook payload). The chat-bridge does NOT have a
+ *   matching session id at this layer — the daemon-side SessionKey is a
+ *   `(platform, chatId, threadId?)` tuple, not the opensquid hook session.
+ *   Cross-wiring those would force a session-id translation table that
+ *   doesn't exist yet (and would belong in WAB.7 daemon wiring, not in a
+ *   tool wrapper).
+ *
+ *   So we follow the spec's recommendation: write to a separate
+ *   automation-buffer file at `~/.opensquid/agent-bridge/captured-lessons.jsonl`
+ *   (one JSON-per-line, append-only). End-of-run / user-driven validation
+ *   walks this file in a later pass — the wedge-gate Stage 1 invariant
+ *   holds because nothing here promotes silently; the user MUST review
+ *   the JSONL before anything moves to the proper wedge-gate buffer.
+ *
+ * Failure mode:
+ *   - Disk full / permission denied → the underlying `appendFile` throws,
+ *     and the agent loop catches + feeds the error back to the model as a
+ *     `tool_result`. The model can decide to retry or give up.
+ *
+ * Imports from: node:fs/promises, node:path, node:os, zod, ../types.js.
+ * Imported by: ./index.ts (tools barrel).
+ */
+import type { ToolHandler, ToolSpec } from '../types.js';
+export declare const storeLessonSpec: ToolSpec;
+export declare function bufferPath(): string;
+export interface MakeStoreLessonHandlerOptions {
+    nowIso?: () => string;
+}
+export declare function makeStoreLessonHandler(opts?: MakeStoreLessonHandlerOptions): ToolHandler;
+//# sourceMappingURL=store_lesson.d.ts.map

package/dist/runtime/agent_bridge/tools/store_lesson.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store_lesson.d.ts","sourceRoot":"","sources":["../../../../src/runtime/agent_bridge/tools/store_lesson.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAQH,OAAO,KAAK,EAAe,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAuBtE,eAAO,MAAM,eAAe,EAAE,QAoB7B,CAAC;AAOF,wBAAgB,UAAU,IAAI,MAAM,CAGnC;AAOD,MAAM,WAAW,6BAA6B;IAC5C,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CACvB;AAED,wBAAgB,sBAAsB,CAAC,IAAI,GAAE,6BAAkC,GAAG,WAAW,CAkB5F"}