@adia-ai/agent 0.8.29 → 0.8.31

package/mcp.js

@@ -0,0 +1,264 @@
+/**
+ * MCP-client mode — a server becomes a tool/resource source.
+ *
+ * `mcpServer({ url })` declares a source; the agent connects it and every
+ * tool the server lists arrives as a normal `ToolDef` in the loop. Nothing
+ * downstream knows the difference: guardrails see the calls, the tracer
+ * records the executions, `checkInput` runs at the boundary, a failure comes
+ * back as an `isError` tool_result. That sameness is the point — MCP is a
+ * SOURCE of tools, not a second kind of tool.
+ *
+ * How it composes with the tier-2 registry (integrations.ts):
+ *  - `register` — used, and it is the fail-fast the lead cares about: two
+ *    servers exposing `search`, or a server tool colliding with a declared
+ *    one, throws at connect instead of silently shadowing.
+ *  - `buildToolDispatch` — used: the ONE place a manifest becomes a ToolDef
+ *    (law 8's shared executor seam) stays the only place.
+ *  - `resolveIntegrations` — deliberately NOT used. Its two jobs are
+ *    persona-enablement intersection and dropping manifests whose env key is
+ *    unprovisioned; an MCP server has neither a persona list nor an env key,
+ *    and its `MAX_INTEGRATIONS` cap SILENTLY drops the overflow. A server
+ *    exposing more tools than the cap is a real thing (the in-repo a2ui
+ *    server has ~20), and quietly serving two thirds of them is the failure
+ *    mode this whole feature is supposed to prevent. So the cap here is
+ *    explicit and LOUD: `maxTools` (default `MAX_INTEGRATIONS`) throws when
+ *    exceeded, and `tools` narrows the list on purpose.
+ *
+ * Schemas arrive as JSON Schema and are passed to the model VERBATIM. They
+ * are not trimmed to `checkInput`'s allowlist: the MCP server is the
+ * authoritative validator (its rejection comes back as an error result the
+ * model can read), so a faithful copy of a contract someone else owns beats
+ * a locally-enforceable subset that describes the tool less accurately. The
+ * manifest says so with `validation: 'remote'` rather than leaving it
+ * implied.
+ *
+ * RESOURCES map onto the two existing modes and no new one. `tool` is the
+ * default — the harness cannot know which of a remote server's resources an
+ * app wants in every prompt, and attaching all of them would grow the system
+ * prompt without bound — and `attach: [name|uri]` promotes the ones the APP
+ * decides belong there every turn. That is the whole application-controlled
+ * vs. model-controlled distinction MCP itself draws, expressed with the
+ * modes the harness already has. gh#671's third mode is NOT needed here; see
+ * the README's ruling.
+ *
+ * Everything a server returns — tool descriptions, resource text, error
+ * strings — is DATA. A description that reads like an instruction is still a
+ * description; it lands inside the tool spec or a `<resource>` envelope and
+ * decides nothing about what the harness does.
+ */
+import { buildToolDispatch, createIntegrationRegistry, MAX_INTEGRATIONS, } from './integrations.js';
+import { defineResource } from './resource.js';
+import { connectStreamableHttp, McpCallError, McpConnectionError, } from './mcp-transport.js';
+/** Declare an MCP server as a source. Pure — no connection happens here, so
+ *  this is safe to call at module scope; the agent connects on first use (or
+ *  eagerly via `agent.connect()`). */
+export function mcpServer(options) {
+    if (!options?.url)
+        throw new Error('mcpServer: url is required');
+    return { kind: 'mcp', url: options.url, options };
+}
+function sanitize(name) {
+    return name.replace(/[^a-zA-Z0-9_-]/g, '_');
+}
+/** Pull every page of a cursor-paginated list method. The page bound is a
+ *  guard against a server that keeps handing back a cursor, not a limit on
+ *  legitimate size. */
+async function listAll(connection, method, key, signal) {
+    const items = [];
+    let cursor;
+    for (let page = 0; page < 50; page++) {
+        const result = await connection.request(method, cursor ? { cursor } : {}, signal ? { signal } : undefined);
+        const batch = result?.[key];
+        if (Array.isArray(batch))
+            items.push(...batch);
+        const next = result?.['nextCursor'];
+        if (typeof next !== 'string' || !next)
+            return items;
+        cursor = next;
+    }
+    throw new McpConnectionError(`${method} paginated past 50 pages`, connection.url);
+}
+/** MCP content blocks → the one string a tool_result carries. Non-text
+ *  blocks are named rather than dropped: a model told "[image/png, 4.2 kB
+ *  omitted]" can ask for something else; a model handed silence cannot. */
+function contentToText(blocks) {
+    if (!Array.isArray(blocks))
+        return typeof blocks === 'string' ? blocks : JSON.stringify(blocks ?? null);
+    return blocks
+        .map((raw) => {
+        const block = (raw ?? {});
+        if (typeof block.text === 'string')
+            return block.text;
+        if (typeof block.blob === 'string') {
+            return `[${block.mimeType ?? 'binary'}, ${block.blob.length} base64 chars omitted]`;
+        }
+        return JSON.stringify(block);
+    })
+        .join('\n');
+}
+function toolManifest(connection, listing, prefix) {
+    const wireName = sanitize(`${prefix}${listing.name}`);
+    return {
+        id: `mcp:${connection.url}:${listing.name}`,
+        tool: {
+            name: wireName,
+            ...(listing.description ? { description: listing.description } : {}),
+            inputSchema: listing.inputSchema ?? { type: 'object', properties: {} },
+        },
+        label: listing.title ?? listing.name,
+        validation: 'remote',
+        auth: { kind: 'none' },
+        execute: async (input, ctx) => {
+            // The turn's signal reaches the wire: a user who aborts mid-answer
+            // cancels the server call instead of leaving it running and ignored.
+            const result = await connection.request('tools/call', { name: listing.name, arguments: input }, ctx?.signal ? { signal: ctx.signal } : undefined);
+            const text = contentToText(result?.content);
+            // A tool the SERVER rejected must reach the model as an error, not as
+            // prose that reads like a successful answer. `executeTool` turns a
+            // throw into an isError tool_result, so throwing is how a ToolDef says
+            // "this failed" without a second return shape.
+            if (result?.isError)
+                throw new McpCallError(text || 'tool reported an error', connection.url);
+            if (text)
+                return text;
+            return result?.structuredContent ?? '';
+        },
+    };
+}
+function resourceDef(connection, listing, prefix, mode) {
+    const name = sanitize(`${prefix}${listing.name ?? listing.uri}`);
+    return defineResource({
+        name,
+        description: listing.description ?? `MCP resource ${listing.uri}`,
+        mode,
+        get: async (_input, ctx) => {
+            const result = await connection.request('resources/read', { uri: listing.uri }, ctx?.signal ? { signal: ctx.signal } : undefined);
+            return contentToText(result?.contents);
+        },
+    });
+}
+/** Connect one declared source: handshake, list, register, build. Any
+ *  failure along the way throws `McpConnectionError` — including a failure
+ *  the REGISTRY raises, which is a plain Error about a manifest and would
+ *  otherwise escape as a different error class than the one the failure
+ *  table promises. The caller never receives a half-built source or an empty
+ *  tool list that looks like a server with nothing to offer.
+ *
+ *  `signal` cancels the connect in flight (the turn that triggered it was
+ *  aborted); it does NOT stay attached to the resulting connection, whose
+ *  later calls carry their own turn's signal. */
+export async function connectMcpSource(source, opts = {}) {
+    const options = source.options;
+    const signal = opts.signal;
+    const connection = await connectStreamableHttp(options, signal ? { signal } : {});
+    try {
+        return await describeSource(source, connection, signal);
+    }
+    catch (err) {
+        // The handshake succeeded and something after it did not: the session on
+        // the server is ours and nobody else holds a reference to it, so it gets
+        // closed here rather than left to a timeout.
+        await connection.close().catch(() => { });
+        throw err;
+    }
+}
+async function describeSource(source, connection, signal) {
+    const options = source.options;
+    const prefix = options.prefix ?? '';
+    let listings;
+    try {
+        listings = await listAll(connection, 'tools/list', 'tools', signal);
+    }
+    catch (err) {
+        throw new McpConnectionError(`tools/list failed: ${err.message}`, source.url, { cause: err });
+    }
+    const allow = options.tools ? new Set(options.tools) : null;
+    const selected = allow ? listings.filter(t => allow.has(t.name)) : listings;
+    if (allow) {
+        const missing = [...allow].filter(name => !listings.some(t => t.name === name));
+        if (missing.length) {
+            throw new McpConnectionError(`requested tool(s) ${missing.join(', ')} are not exposed by this server ` +
+                `(it lists: ${listings.map(t => t.name).join(', ') || 'nothing'})`, source.url);
+        }
+    }
+    const maxTools = options.maxTools ?? MAX_INTEGRATIONS;
+    if (selected.length > maxTools) {
+        throw new McpConnectionError(`server exposes ${selected.length} tools, over the ${maxTools} cap — ` +
+            'raise maxTools or narrow the list with tools: [...]', source.url);
+    }
+    // Registration and ToolDef construction raise plain Errors about a
+    // manifest — a duplicate wire name after sanitizing, an empty name, an
+    // inputSchema that is not an object. They are connect-time faults like any
+    // other, so they wear the connect-time class (cause preserved) instead of
+    // escaping as something a caller catching McpConnectionError would miss.
+    let toolDefs;
+    try {
+        const registry = createIntegrationRegistry();
+        for (const listing of selected)
+            registry.register(toolManifest(connection, listing, prefix));
+        const dispatch = buildToolDispatch(registry.list(), {});
+        toolDefs = 'tools' in dispatch ? dispatch.tools : [];
+    }
+    catch (err) {
+        if (err instanceof McpConnectionError)
+            throw err;
+        throw new McpConnectionError(`cannot register this server's tools: ${err.message}`, source.url, { cause: err });
+    }
+    let resourceDefs = [];
+    let resourceReport = [];
+    const serverDoesResources = !!connection.capabilities['resources'];
+    if (options.resources !== false && serverDoesResources) {
+        let resourceListings;
+        try {
+            resourceListings = await listAll(connection, 'resources/list', 'resources', signal);
+        }
+        catch (err) {
+            throw new McpConnectionError(`resources/list failed: ${err.message}`, source.url, { cause: err });
+        }
+        const attachSet = new Set(options.attach ?? []);
+        const unknownAttach = [...attachSet].filter(key => !resourceListings.some(r => r.name === key || r.uri === key));
+        if (unknownAttach.length) {
+            throw new McpConnectionError(`attach names ${unknownAttach.join(', ')} match no listed resource ` +
+                `(it lists: ${resourceListings.map(r => r.name ?? r.uri).join(', ') || 'nothing'})`, source.url);
+        }
+        try {
+            resourceDefs = resourceListings.map((listing) => {
+                const mode = attachSet.has(listing.name ?? '') || attachSet.has(listing.uri) ? 'attach' : 'tool';
+                return resourceDef(connection, listing, prefix, mode);
+            });
+        }
+        catch (err) {
+            throw new McpConnectionError(`cannot register this server's resources: ${err.message}`, source.url, { cause: err });
+        }
+        resourceReport = resourceListings.map((listing, index) => ({
+            name: resourceDefs[index].name,
+            uri: listing.uri,
+            mode: resourceDefs[index].mode,
+        }));
+    }
+    return {
+        url: source.url,
+        serverInfo: connection.serverInfo,
+        protocolVersion: connection.protocolVersion,
+        tools: toolDefs.map(t => t.name),
+        resources: resourceReport,
+        connection,
+        toolDefs,
+        resourceDefs,
+    };
+}
+/** The whole assembled tool set must have unique names — the loop dispatches
+ *  by name, so a duplicate is a tool that silently never runs. Per-server
+ *  registration cannot see across sources or into the declared tools, so the
+ *  check lands here, once, over everything. */
+export function assertUniqueToolNames(tools) {
+    const seen = new Set();
+    for (const tool of tools) {
+        if (seen.has(tool.name)) {
+            throw new McpConnectionError(`tool name "${tool.name}" is contributed twice (an MCP server collides with a declared tool ` +
+                'or another server) — set a prefix on one of the sources');
+        }
+        seen.add(tool.name);
+    }
+}
+//# sourceMappingURL=mcp.js.map

package/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["src/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,EACL,iBAAiB,EAAE,yBAAyB,EAAE,gBAAgB,GAE/D,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAA0C,MAAM,eAAe,CAAC;AAEvF,OAAO,EACL,qBAAqB,EAAE,YAAY,EAAE,kBAAkB,GAExD,MAAM,oBAAoB,CAAC;AAoE5B;;sCAEsC;AACtC,MAAM,UAAU,SAAS,CAAC,OAAyB;IACjD,IAAI,CAAC,OAAO,EAAE,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;IACjE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC;AACpD,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC;AAC9C,CAAC;AAED;;uBAEuB;AACvB,KAAK,UAAU,OAAO,CACpB,UAAyB,EACzB,MAAc,EACd,GAAW,EACX,MAAoB;IAEpB,MAAM,KAAK,GAAQ,EAAE,CAAC;IACtB,IAAI,MAA0B,CAAC;IAC/B,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,OAAO,CACrC,MAAM,EACN,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EACxB,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAChC,CAAC;QACF,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,GAAI,KAAa,CAAC,CAAC;QACxD,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,YAAY,CAAC,CAAC;QACpC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI;YAAE,OAAO,KAAK,CAAC;QACpD,MAAM,GAAG,IAAI,CAAC;IAChB,CAAC;IACD,MAAM,IAAI,kBAAkB,CAAC,GAAG,MAAM,0BAA0B,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC;AACpF,CAAC;AAED;;2EAE2E;AAC3E,SAAS,aAAa,CAAC,MAAe;IACpC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC;IACxG,OAAO,MAAM;SACV,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACX,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,EAAE,CAAoB,CAAC;QAC7C,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC,IAAI,CAAC;QACtD,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACnC,OAAO,IAAI,KAAK,CAAC,QAAQ,IAAI,QAAQ,KAAK,KAAK,CAAC,IAAI,CAAC,MAAM,wBAAwB,CAAC;QACtF,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,SAAS,YAAY,CACnB,UAAyB,EACzB,OAAuB,EACvB,MAAc;IAEd,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IACtD,OAAO;QACL,EAAE,EAAE,OAAO,UAAU,CAAC,GAAG,IAAI,OAAO,CAAC,IAAI,EAAE;QAC3C,IAAI,EAAE;YACJ,IAAI,EAAE,QAAQ;YACd,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACpE,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;SACvE;QACD,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,IAAI;QACpC,UAAU,EAAE,QAAQ;QACpB,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;QACtB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAgB,EAAE,EAAE;YACzC,mEAAmE;YACnE,qEAAqE;YACrE,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,OAAO,CACrC,YAAY,EACZ,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,EACxC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CACjD,CAAC;YACF,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAC5C,sEAAsE;YACtE,mEAAmE;YACnE,uEAAuE;YACvE,+CAA+C;YAC/C,IAAI,MAAM,EAAE,OAAO;gBAAE,MAAM,IAAI,YAAY,CAAC,IAAI,IAAI,wBAAwB,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC;YAC9F,IAAI,IAAI;gBAAE,OAAO,IAAI,CAAC;YACtB,OAAO,MAAM,EAAE,iBAAiB,IAAI,EAAE,CAAC;QACzC,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAClB,UAAyB,EACzB,OAA2B,EAC3B,MAAc,EACd,IAAuB;IAEvB,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACjE,OAAO,cAAc,CAAC;QACpB,IAAI;QACJ,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,gBAAgB,OAAO,CAAC,GAAG,EAAE;QACjE,IAAI;QACJ,GAAG,EAAE,KAAK,EAAE,MAAgC,EAAE,GAAqB,EAAE,EAAE;YACrE,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,OAAO,CACrC,gBAAgB,EAChB,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,EACpB,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CACjD,CAAC;YACF,OAAO,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QACzC,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;iDASiD;AACjD,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,MAAiB,EACjB,OAAiC,EAAE;IAEnC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC3B,MAAM,UAAU,GAAG,MAAM,qBAAqB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAClF,IAAI,CAAC;QACH,OAAO,MAAM,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;IAC1D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,yEAAyE;QACzE,yEAAyE;QACzE,6CAA6C;QAC7C,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACzC,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,KAAK,UAAU,cAAc,CAC3B,MAAiB,EACjB,UAAyB,EACzB,MAA+B;IAE/B,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC/B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC;IAEpC,IAAI,QAA0B,CAAC;IAC/B,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,OAAO,CAAiB,UAAU,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IACtF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,kBAAkB,CAAC,sBAAuB,GAAa,CAAC,OAAO,EAAE,EAAE,MAAM,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IAC3G,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5D,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC5E,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC;QAChF,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnB,MAAM,IAAI,kBAAkB,CAC1B,qBAAqB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,kCAAkC;gBACzE,cAAc,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,SAAS,GAAG,EAClE,MAAM,CAAC,GAAG,CACX,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,gBAAgB,CAAC;IACtD,IAAI,QAAQ,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;QAC/B,MAAM,IAAI,kBAAkB,CAC1B,kBAAkB,QAAQ,CAAC,MAAM,oBAAoB,QAAQ,SAAS;YACtE,qDAAqD,EACrD,MAAM,CAAC,GAAG,CACX,CAAC;IACJ,CAAC;IAED,mEAAmE;IACnE,uEAAuE;IACvE,2EAA2E;IAC3E,0EAA0E;IAC1E,yEAAyE;IACzE,IAAI,QAAmB,CAAC;IACxB,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,yBAAyB,EAAE,CAAC;QAC7C,KAAK,MAAM,OAAO,IAAI,QAAQ;YAAE,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;QAC7F,MAAM,QAAQ,GAAG,iBAAiB,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QACxD,QAAQ,GAAG,OAAO,IAAI,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IACvD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,kBAAkB;YAAE,MAAM,GAAG,CAAC;QACjD,MAAM,IAAI,kBAAkB,CAC1B,wCAAyC,GAAa,CAAC,OAAO,EAAE,EAChE,MAAM,CAAC,GAAG,EACV,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;IACJ,CAAC;IAED,IAAI,YAAY,GAAkB,EAAE,CAAC;IACrC,IAAI,cAAc,GAAiC,EAAE,CAAC;IACtD,MAAM,mBAAmB,GAAG,CAAC,CAAC,UAAU,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IACnE,IAAI,OAAO,CAAC,SAAS,KAAK,KAAK,IAAI,mBAAmB,EAAE,CAAC;QACvD,IAAI,gBAAsC,CAAC;QAC3C,IAAI,CAAC;YACH,gBAAgB,GAAG,MAAM,OAAO,CAAqB,UAAU,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;QAC1G,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,kBAAkB,CAAC,0BAA2B,GAAa,CAAC,OAAO,EAAE,EAAE,MAAM,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;QAC/G,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;QAChD,MAAM,aAAa,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC,MAAM,CACzC,GAAG,CAAC,EAAE,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,IAAI,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CACpE,CAAC;QACF,IAAI,aAAa,CAAC,MAAM,EAAE,CAAC;YACzB,MAAM,IAAI,kBAAkB,CAC1B,gBAAgB,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,4BAA4B;gBACpE,cAAc,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,SAAS,GAAG,EACnF,MAAM,CAAC,GAAG,CACX,CAAC;QACJ,CAAC;QACD,IAAI,CAAC;YACH,YAAY,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;gBAC9C,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,IAAI,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC;gBACjG,OAAO,WAAW,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;YACxD,CAAC,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,kBAAkB,CAC1B,4CAA6C,GAAa,CAAC,OAAO,EAAE,EACpE,MAAM,CAAC,GAAG,EACV,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;QACJ,CAAC;QACD,cAAc,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;YACzD,IAAI,EAAE,YAAY,CAAC,KAAK,CAAE,CAAC,IAAI;YAC/B,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,IAAI,EAAE,YAAY,CAAC,KAAK,CAAE,CAAC,IAAI;SAChC,CAAC,CAAC,CAAC;IACN,CAAC;IAED,OAAO;QACL,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,UAAU,EAAE,UAAU,CAAC,UAAU;QACjC,eAAe,EAAE,UAAU,CAAC,eAAe;QAC3C,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QAChC,SAAS,EAAE,cAAc;QACzB,UAAU;QACV,QAAQ;QACR,YAAY;KACb,CAAC;AACJ,CAAC;AAED;;;+CAG+C;AAC/C,MAAM,UAAU,qBAAqB,CAAC,KAAgB;IACpD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,kBAAkB,CAC1B,cAAc,IAAI,CAAC,IAAI,sEAAsE;gBAC7F,yDAAyD,CAC1D,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/agent",
-  "version": "0.8.29",
+  "version": "0.8.31",
   "description": "Composable chat-agent harness — assemble an agent from four declared parts (prompt layers, tools, workflows, resources) on top of @adia-ai/llm. Owns the tool-call loop, the session model, and the one shared event reducer. Works in browser and Node.",
   "type": "module",
   "exports": {

package/resource.d.ts

@@ -8,20 +8,45 @@
  *    never asks; the data is just there.
  *  - 'tool'   — model-controlled: the resource becomes a read-only tool
  *    (`read_<name>`) the model calls when it decides it needs the data.
+ *
+ * Attach mode inlines somebody else's bytes into the system prompt, so the
+ * envelope has to be forgeable-proof: see `attachLayers` for the escaping
+ * and why it is not optional.
  */
 import type { PromptLayer } from './prompt.js';
 import { type ToolDef } from './tools.js';
+/** What a `get` may USE — the turn's cancellation, today. Passed as the
+ *  SECOND argument, so every existing one-argument `get` is unaffected. */
+export interface ResourceContext {
+    signal?: AbortSignal;
+}
 export interface ResourceDef {
     name: string;
     description?: string;
     mode: 'attach' | 'tool';
-    get: (input?: Record<string, unknown>) => string | Promise<string>;
+    /** Tool-mode only: the arguments the model may pass. Without it a
+     *  tool-mode resource is a zero-argument read, which can't express a
+     *  parameterized corpus read (`search_chunks(query, kind, limit)`).
+     *  Attach-mode resources take no input and ignore this. */
+    inputSchema?: Record<string, unknown>;
+    /** Non-string returns are JSON-serialized — a corpus record is an object,
+     *  and making every call site stringify was the same tax the tool
+     *  executor already pays for `execute`. */
+    get: (input?: Record<string, unknown>, ctx?: ResourceContext) => unknown | Promise<unknown>;
 }
 export declare function defineResource(def: ResourceDef): ResourceDef;
 /** Attach-mode resources → dynamic prompt layers. Resolution happens at
  *  compose time (async), so the layer text is a plain string by the time
- *  it reaches composeSystem. */
-export declare function attachLayers(resources: ResourceDef[]): Promise<PromptLayer[]>;
+ *  it reaches composeSystem.
+ *
+ *  The content is DATA, and the envelope is what says so. A resource body
+ *  that contains `</resource>` would otherwise close its own envelope and
+ *  everything after it would read as prompt — a server, a file, or a
+ *  database row could then write instructions into the system prompt. That
+ *  is a containment bug in the harness, not a hazard the resource's author
+ *  is responsible for, so the escaping lives here and covers EVERY attach
+ *  resource, MCP or hand-declared. */
+export declare function attachLayers(resources: ResourceDef[], ctx?: ResourceContext): Promise<PromptLayer[]>;
 /** Tool-mode resources → read-only tools the model can call. */
 export declare function resourceTools(resources: ResourceDef[]): ToolDef[];
 //# sourceMappingURL=resource.d.ts.map

package/resource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["src/resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAc,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAEtD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;IACxB,GAAG,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACpE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CAS5D;AAED;;gCAEgC;AAChC,wBAAsB,YAAY,CAAC,SAAS,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAOnF;AAED,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,SAAS,EAAE,WAAW,EAAE,GAAG,OAAO,EAAE,CASjE"}
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["src/resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAc,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAEtD;2EAC2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;IACxB;;;+DAG2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC;;+CAE2C;IAC3C,GAAG,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,eAAe,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7F;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CAY5D;AA0BD;;;;;;;;;;sCAUsC;AACtC,wBAAsB,YAAY,CAChC,SAAS,EAAE,WAAW,EAAE,EACxB,GAAG,CAAC,EAAE,eAAe,GACpB,OAAO,CAAC,WAAW,EAAE,CAAC,CASxB;AAED,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,SAAS,EAAE,WAAW,EAAE,GAAG,OAAO,EAAE,CASjE"}

package/resource.js

@@ -8,6 +8,10 @@
  *    never asks; the data is just there.
  *  - 'tool'   — model-controlled: the resource becomes a read-only tool
  *    (`read_<name>`) the model calls when it decides it needs the data.
+ *
+ * Attach mode inlines somebody else's bytes into the system prompt, so the
+ * envelope has to be forgeable-proof: see `attachLayers` for the escaping
+ * and why it is not optional.
  */
 import { defineTool } from './tools.js';
 export function defineResource(def) {
@@ -19,16 +23,50 @@ export function defineResource(def) {
     if (typeof def.get !== 'function') {
         throw new Error(`defineResource "${def.name}": get() is required`);
     }
+    if (def.inputSchema && def.mode !== 'tool') {
+        throw new Error(`defineResource "${def.name}": inputSchema is tool-mode only`);
+    }
     return def;
 }
+function asText(value) {
+    return typeof value === 'string' ? value : JSON.stringify(value ?? null);
+}
+/** Attribute values: a `"` would end the attribute early and let the rest of
+ *  a name or description pose as further attributes. */
+function escapeAttribute(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/"/g, '&quot;');
+}
+/** Bodies get the narrowest escape that still makes the envelope
+ *  unforgeable: only the two STRUCTURAL sequences — an opening `<resource`
+ *  and a closing `</resource` — have their `<` escaped.
+ *
+ *  Escaping every `<` was the alternative and it is worse: attached bodies
+ *  here are catalog JSON, component markup, docs. Mangling every tag in them
+ *  to close one hole degrades the data the model reads on every turn, for a
+ *  containment property those two sequences already give. A body can no
+ *  longer end its own envelope or open a nested one that claims a different
+ *  name; everything else it contains arrives byte-for-byte. */
+function fenceBody(text) {
+    return text.replace(/<(\/?resource\b)/gi, '&lt;$1');
+}
 /** Attach-mode resources → dynamic prompt layers. Resolution happens at
  *  compose time (async), so the layer text is a plain string by the time
- *  it reaches composeSystem. */
-export async function attachLayers(resources) {
+ *  it reaches composeSystem.
+ *
+ *  The content is DATA, and the envelope is what says so. A resource body
+ *  that contains `</resource>` would otherwise close its own envelope and
+ *  everything after it would read as prompt — a server, a file, or a
+ *  database row could then write instructions into the system prompt. That
+ *  is a containment bug in the harness, not a hazard the resource's author
+ *  is responsible for, so the escaping lives here and covers EVERY attach
+ *  resource, MCP or hand-declared. */
+export async function attachLayers(resources, ctx) {
     const attach = resources.filter(r => r.mode === 'attach');
     const resolved = await Promise.all(attach.map(async (r) => ({
         name: `resource:${r.name}`,
-        text: `<resource name="${r.name}"${r.description ? ` description="${r.description}"` : ''}>\n${await r.get()}\n</resource>`,
+        text: `<resource name="${escapeAttribute(r.name)}"` +
+            `${r.description ? ` description="${escapeAttribute(r.description)}"` : ''}>\n` +
+            `${fenceBody(asText(await r.get(undefined, ctx)))}\n</resource>`,
     })));
     return resolved.filter(l => l.text);
 }
@@ -39,8 +77,8 @@ export function resourceTools(resources) {
         .map(r => defineTool({
         name: `read_${r.name.replace(/[^a-zA-Z0-9_-]/g, '_')}`,
         description: r.description ?? `Read the "${r.name}" resource`,
-        inputSchema: { type: 'object', properties: {} },
-        execute: (input) => r.get(input),
+        inputSchema: r.inputSchema ?? { type: 'object', properties: {} },
+        execute: (input, toolCtx) => r.get(input, toolCtx.signal ? { signal: toolCtx.signal } : {}),
     }));
 }
 //# sourceMappingURL=resource.js.map

package/resource.js.map

@@ -1 +1 @@
-{"version":3,"file":"resource.js","sourceRoot":"","sources":["src/resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,UAAU,EAAgB,MAAM,YAAY,CAAC;AAStD,MAAM,UAAU,cAAc,CAAC,GAAgB;IAC7C,IAAI,CAAC,GAAG,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACnE,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CAAC,mBAAmB,GAAG,CAAC,IAAI,8BAA8B,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,GAAG,KAAK,UAAU,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,mBAAmB,GAAG,CAAC,IAAI,sBAAsB,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;gCAEgC;AAChC,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,SAAwB;IACzD,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;IAC1D,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAC,CAAC,EAAC,EAAE,CAAC,CAAC;QACxD,IAAI,EAAE,YAAY,CAAC,CAAC,IAAI,EAAE;QAC1B,IAAI,EAAE,mBAAmB,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,EAAE,MAAM,MAAM,CAAC,CAAC,GAAG,EAAE,eAAe;KAC5H,CAAC,CAAC,CAAC,CAAC;IACL,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AACtC,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,aAAa,CAAC,SAAwB;IACpD,OAAO,SAAS;SACb,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC;SAC9B,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC;QACnB,IAAI,EAAE,QAAQ,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,EAAE;QACtD,WAAW,EAAE,CAAC,CAAC,WAAW,IAAI,aAAa,CAAC,CAAC,IAAI,YAAY;QAC7D,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;QAC/C,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC;KACjC,CAAC,CAAC,CAAC;AACR,CAAC"}
+{"version":3,"file":"resource.js","sourceRoot":"","sources":["src/resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,UAAU,EAAgB,MAAM,YAAY,CAAC;AAuBtD,MAAM,UAAU,cAAc,CAAC,GAAgB;IAC7C,IAAI,CAAC,GAAG,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACnE,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CAAC,mBAAmB,GAAG,CAAC,IAAI,8BAA8B,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,GAAG,KAAK,UAAU,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,mBAAmB,GAAG,CAAC,IAAI,sBAAsB,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CAAC,mBAAmB,GAAG,CAAC,IAAI,kCAAkC,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,MAAM,CAAC,KAAc;IAC5B,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC;AAC3E,CAAC;AAED;wDACwD;AACxD,SAAS,eAAe,CAAC,KAAa;IACpC,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AACpF,CAAC;AAED;;;;;;;;;+DAS+D;AAC/D,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,IAAI,CAAC,OAAO,CAAC,oBAAoB,EAAE,QAAQ,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;;;;sCAUsC;AACtC,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,SAAwB,EACxB,GAAqB;IAErB,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;IAC1D,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAC,CAAC,EAAC,EAAE,CAAC,CAAC;QACxD,IAAI,EAAE,YAAY,CAAC,CAAC,IAAI,EAAE;QAC1B,IAAI,EAAE,mBAAmB,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG;YACjD,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,iBAAiB,eAAe,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK;YAC/E,GAAG,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC,eAAe;KACnE,CAAC,CAAC,CAAC,CAAC;IACL,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AACtC,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,aAAa,CAAC,SAAwB;IACpD,OAAO,SAAS;SACb,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC;SAC9B,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC;QACnB,IAAI,EAAE,QAAQ,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,EAAE;QACtD,WAAW,EAAE,CAAC,CAAC,WAAW,IAAI,aAAa,CAAC,CAAC,IAAI,YAAY;QAC7D,WAAW,EAAE,CAAC,CAAC,WAAW,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;QAChE,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5F,CAAC,CAAC,CAAC;AACR,CAAC"}

package/session.d.ts

@@ -9,6 +9,13 @@
  * `draft` is reduce()'s in-flight assistant turn (text snapshot + parts
  * accumulated between a round's first chunk and its close). It is part of
  * the serialized shape on purpose — resuming mid-turn drops nothing.
+ *
+ * `memory` is the per-session key/value slot (gh#665). It is JSON-safe by
+ * contract and written ONLY through `reduce()` — same single-writer rule
+ * the messages obey, so a memory write is an event in the same stream and
+ * cannot happen behind a consumer's back. Cross-session persistence is a
+ * SEAM, not an implementation: a Session serializes with its memory, and
+ * where that JSON goes (localStorage, a DB row) stays the caller's.
  */
 import type { Part } from '@adia-ai/llm';
 export interface Msg {
@@ -19,11 +26,22 @@ export interface Draft {
     text: string;
     parts: Part[];
 }
+/** The values a memory slot may hold — the JSON-safe closure. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
 export interface Session {
     id: string;
     messages: Msg[];
     draft?: Draft;
+    /** Per-session memory. Present only once something has been remembered. */
+    memory?: Record<string, JsonValue>;
 }
+/** Throws on anything a Session could not survive `JSON.stringify` →
+ *  `JSON.parse` unchanged (functions, undefined, Date, Map, cycles). Loud
+ *  at the write, because the alternative is a session that silently loses
+ *  a field the next time it round-trips through storage. */
+export declare function assertJsonSafe(value: unknown, path?: string): void;
 export declare function createSession(id?: string): Session;
 export declare function toJSON(session: Session): string;
 export declare function fromJSON(json: string): Session;

package/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEzC,MAAM,WAAW,GAAG;IAClB,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IACpC,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,GAAG,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAID,wBAAgB,aAAa,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAKlD;AAED,wBAAgB,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAE/C;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAM9C"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEzC,MAAM,WAAW,GAAG;IAClB,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IACpC,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AAED,iEAAiE;AACjE,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEtG,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,GAAG,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CACpC;AAED;;;4DAG4D;AAC5D,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,SAAW,GAAG,IAAI,CA2BpE;AAID,wBAAgB,aAAa,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAKlD;AAED,wBAAgB,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAE/C;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAM9C"}

package/session.js

@@ -9,7 +9,47 @@
  * `draft` is reduce()'s in-flight assistant turn (text snapshot + parts
  * accumulated between a round's first chunk and its close). It is part of
  * the serialized shape on purpose — resuming mid-turn drops nothing.
+ *
+ * `memory` is the per-session key/value slot (gh#665). It is JSON-safe by
+ * contract and written ONLY through `reduce()` — same single-writer rule
+ * the messages obey, so a memory write is an event in the same stream and
+ * cannot happen behind a consumer's back. Cross-session persistence is a
+ * SEAM, not an implementation: a Session serializes with its memory, and
+ * where that JSON goes (localStorage, a DB row) stays the caller's.
  */
+/** Throws on anything a Session could not survive `JSON.stringify` →
+ *  `JSON.parse` unchanged (functions, undefined, Date, Map, cycles). Loud
+ *  at the write, because the alternative is a session that silently loses
+ *  a field the next time it round-trips through storage. */
+export function assertJsonSafe(value, path = 'memory') {
+    if (value === null)
+        return;
+    switch (typeof value) {
+        case 'string':
+        case 'number':
+        case 'boolean':
+            if (typeof value === 'number' && !Number.isFinite(value)) {
+                throw new Error(`${path}: ${value} is not JSON-safe`);
+            }
+            return;
+        case 'object': {
+            if (Array.isArray(value)) {
+                value.forEach((item, i) => assertJsonSafe(item, `${path}[${i}]`));
+                return;
+            }
+            const proto = Object.getPrototypeOf(value);
+            if (proto !== Object.prototype && proto !== null) {
+                throw new Error(`${path}: ${value.constructor?.name ?? 'object'} is not JSON-safe (plain objects only)`);
+            }
+            for (const [key, item] of Object.entries(value)) {
+                assertJsonSafe(item, `${path}.${key}`);
+            }
+            return;
+        }
+        default:
+            throw new Error(`${path}: ${typeof value} is not JSON-safe`);
+    }
+}
 let sessionCounter = 0;
 export function createSession(id) {
     return {

package/session.js.map

@@ -1 +1 @@
-{"version":3,"file":"session.js","sourceRoot":"","sources":["src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAoBH,IAAI,cAAc,GAAG,CAAC,CAAC;AAEvB,MAAM,UAAU,aAAa,CAAC,EAAW;IACvC,OAAO;QACL,EAAE,EAAE,EAAE,IAAI,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,EAAE;QAC5D,QAAQ,EAAE,EAAE;KACb,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,OAAgB;IACrC,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;IAC3C,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,CAAC,EAAE,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QAChF,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"session.js","sourceRoot":"","sources":["src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAyBH;;;4DAG4D;AAC5D,MAAM,UAAU,cAAc,CAAC,KAAc,EAAE,IAAI,GAAG,QAAQ;IAC5D,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO;IAC3B,QAAQ,OAAO,KAAK,EAAE,CAAC;QACrB,KAAK,QAAQ,CAAC;QACd,KAAK,QAAQ,CAAC;QACd,KAAK,SAAS;YACZ,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;gBACzD,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,KAAK,KAAK,mBAAmB,CAAC,CAAC;YACxD,CAAC;YACD,OAAO;QACT,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBACzB,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;gBAClE,OAAO;YACT,CAAC;YACD,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;YAC3C,IAAI,KAAK,KAAK,MAAM,CAAC,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACjD,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,KAAM,KAAgB,CAAC,WAAW,EAAE,IAAI,IAAI,QAAQ,wCAAwC,CAAC,CAAC;YACvH,CAAC;YACD,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;gBAC3E,cAAc,CAAC,IAAI,EAAE,GAAG,IAAI,IAAI,GAAG,EAAE,CAAC,CAAC;YACzC,CAAC;YACD,OAAO;QACT,CAAC;QACD;YACE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,KAAK,OAAO,KAAK,mBAAmB,CAAC,CAAC;IACjE,CAAC;AACH,CAAC;AAED,IAAI,cAAc,GAAG,CAAC,CAAC;AAEvB,MAAM,UAAU,aAAa,CAAC,EAAW;IACvC,OAAO;QACL,EAAE,EAAE,EAAE,IAAI,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,EAAE;QAC5D,QAAQ,EAAE,EAAE;KACb,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,OAAgB;IACrC,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;IAC3C,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,CAAC,EAAE,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QAChF,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/stub.d.ts

@@ -11,6 +11,14 @@ import type { ChatOpts, LLMClient, ToolUse } from '@adia-ai/llm';
 export interface ScriptedTurn {
     text?: string;
     toolUse?: ToolUse[];
+    /** Argument fragments streamed BEFORE the complete `toolUse` chunks, the
+     *  way Anthropic/OpenAI stream partial tool input. Scripted explicitly:
+     *  a stub that invented its own split would be testing the stub. */
+    toolUseDeltas?: Array<{
+        id: string;
+        name: string;
+        partial: string;
+    }>;
     stopReason?: string;
 }
 export interface ScriptClient extends LLMClient {

package/stub.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stub.d.ts","sourceRoot":"","sources":["src/stub.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAc,SAAS,EAAe,OAAO,EAAE,MAAM,cAAc,CAAC;AAE1F,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAa,SAAQ,SAAS;IAC7C;mDAC+C;IAC/C,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;CACjC;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,YAAY,CA0ChE"}
+{"version":3,"file":"stub.d.ts","sourceRoot":"","sources":["src/stub.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAc,SAAS,EAAe,OAAO,EAAE,MAAM,cAAc,CAAC;AAE1F,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;IACpB;;wEAEoE;IACpE,aAAa,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAa,SAAQ,SAAS;IAC7C;mDAC+C;IAC/C,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;CACjC;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,YAAY,CAuDhE"}

package/stub.js

@@ -37,6 +37,19 @@ export function scriptClient(turns) {
                 snapshot = turn.text;
                 yield { type: 'text', text: turn.text, snapshot };
             }
+            const snapshots = new Map();
+            for (const delta of turn.toolUseDeltas ?? []) {
+                const accumulated = (snapshots.get(delta.id) ?? '') + delta.partial;
+                snapshots.set(delta.id, accumulated);
+                yield {
+                    type: 'tool_use_delta',
+                    id: delta.id,
+                    name: delta.name,
+                    index: 0,
+                    partial: delta.partial,
+                    snapshot: accumulated,
+                };
+            }
             for (const call of turn.toolUse ?? []) {
                 yield { type: 'tool_use', id: call.id, name: call.name, input: call.input };
             }

package/stub.js.map

@@ -1 +1 @@
-{"version":3,"file":"stub.js","sourceRoot":"","sources":["src/stub.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAgBH,MAAM,UAAU,YAAY,CAAC,KAAqB;IAChD,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,MAAM,KAAK,GAA6B,EAAE,CAAC;IAE3C,SAAS,IAAI;QACX,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;QAC3B,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,MAAM,GAAG,CAAC,aAAa,KAAK,CAAC,MAAM,iBAAiB,CAAC,CAAC;QACvG,MAAM,EAAE,CAAC;QACT,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO;QACL,KAAK;QACL,KAAK,CAAC,IAAI,CAAC,IAAuB;YAChC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjB,MAAM,IAAI,GAAG,IAAI,EAAE,CAAC;YACpB,OAAO;gBACL,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE;gBACrB,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;gBAC9B,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC;gBAC1E,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC3D,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,CAAC,MAAM,CAAC,IAAuB;YACnC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjB,MAAM,IAAI,GAAG,IAAI,EAAE,CAAC;YACpB,IAAI,QAAQ,GAAG,EAAE,CAAC;YAClB,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBACd,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC;gBACrB,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC;YACpD,CAAC;YACD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;gBACtC,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;YAC9E,CAAC;YACD,MAAM;gBACJ,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,QAAQ;gBACd,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;gBAC9B,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC;aAC3E,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"stub.js","sourceRoot":"","sources":["src/stub.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAoBH,MAAM,UAAU,YAAY,CAAC,KAAqB;IAChD,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,MAAM,KAAK,GAA6B,EAAE,CAAC;IAE3C,SAAS,IAAI;QACX,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;QAC3B,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,MAAM,GAAG,CAAC,aAAa,KAAK,CAAC,MAAM,iBAAiB,CAAC,CAAC;QACvG,MAAM,EAAE,CAAC;QACT,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO;QACL,KAAK;QACL,KAAK,CAAC,IAAI,CAAC,IAAuB;YAChC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjB,MAAM,IAAI,GAAG,IAAI,EAAE,CAAC;YACpB,OAAO;gBACL,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE;gBACrB,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;gBAC9B,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC;gBAC1E,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC3D,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,CAAC,MAAM,CAAC,IAAuB;YACnC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjB,MAAM,IAAI,GAAG,IAAI,EAAE,CAAC;YACpB,IAAI,QAAQ,GAAG,EAAE,CAAC;YAClB,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBACd,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC;gBACrB,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC;YACpD,CAAC;YACD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;YAC5C,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,aAAa,IAAI,EAAE,EAAE,CAAC;gBAC7C,MAAM,WAAW,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC;gBACpE,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,WAAW,CAAC,CAAC;gBACrC,MAAM;oBACJ,IAAI,EAAE,gBAAgB;oBACtB,EAAE,EAAE,KAAK,CAAC,EAAE;oBACZ,IAAI,EAAE,KAAK,CAAC,IAAI;oBAChB,KAAK,EAAE,CAAC;oBACR,OAAO,EAAE,KAAK,CAAC,OAAO;oBACtB,QAAQ,EAAE,WAAW;iBACtB,CAAC;YACJ,CAAC;YACD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;gBACtC,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;YAC9E,CAAC;YACD,MAAM;gBACJ,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,QAAQ;gBACd,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;gBAC9B,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC;aAC3E,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/tools.d.ts

@@ -12,9 +12,15 @@
  * can validate inside their own `execute`.
  */
 import type { ToolSpec } from '@adia-ai/llm';
+import type { JsonValue } from './session.js';
 export interface ToolContext {
     sessionId: string;
     signal?: AbortSignal;
+    /** Ask for a session-memory write. This does NOT write: the loop turns
+     *  the patch into a `memory` event, and `reduce()` remains the only
+     *  writer. Absent when a tool runs outside the loop (a direct
+     *  `executeTool` call). A null value deletes the key. */
+    remember?: (patch: Record<string, JsonValue | null>) => void;
 }
 export interface ToolDef {
     name: string;

package/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3F,QAAQ,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC;CAC/E;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAWhD;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,QAAQ,EAAE,CAMpD;AAED;gDACgD;AAChD,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI,CAmBzG;AAeD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;oEAEoE;AACpE,wBAAsB,WAAW,CAC/B,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,WAAW,CAAC,CA4BtB"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;6DAGyD;IACzD,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC;CAC9D;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3F,QAAQ,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC;CAC/E;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAWhD;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,QAAQ,EAAE,CAMpD;AAED;gDACgD;AAChD,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI,CAmBzG;AAeD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;oEAEoE;AACpE,wBAAsB,WAAW,CAC/B,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,WAAW,CAAC,CA4BtB"}