agentfootprint 9.68.0 → 9.70.0

package/CLAUDE.md

@@ -40,6 +40,7 @@ not in this table, search `src/index.ts` for the nearest noun before writing cod
 | declaring an agent's whole setup as one named, versioned thing — a preset, a template, a blueprint, "the support agent we all use" | `defineAgentRecipe` + `AgentBuilder.recipe()` | `src/recipes/` | 9.48.0 |
 | naming your own branches and nodes — which prefix is reserved, and telling framework plumbing from consumer structure in a trace | `RESERVED_SUBFLOW_PREFIX` + `isReservedSubflowSegment` | `src/conventions.ts` | 9.49.0 |
 | keeping a large tool result out of the model's context | `artifacts` + `wants` + `placement` | `src/artifacts/` | 9.21.0 |
+| the ticket placement just minted being REFUSED by your own `wants` argument as a kind mismatch — because the mint says `tool-result/<toolName>` and your consumer says `dataset/rows` | `Tool.resultKind` + `placedResultKind(toolName, declared?)` (the mint speaks the consumer's vocabulary; the exact-match matcher is untouched) | `src/artifacts/placement.ts` | 9.70.0 |
 | letting the UI draw an artifact without the model naming a component | `registerArtifactComponent` (in the `agentfootprint-lens` package) | — | — |
 | finding which tools the model keeps writing by hand | `agentfootprint.tools.code_run` + `codeShape` | `src/core/codeRunnerTool.ts` | 9.46.0 |
 | a skill wrongly activated by a keyword staying loaded for the whole turn — suspending/parking a map's prompt + tools when its contribution goes unused, WITHOUT touching its cursor, and re-engaging it on evidence | `.maps()` + `advanceEngagement` + `agentfootprint.map.engaged/parked` + skip reason `'parked'` | `src/maps/` | 9.58.0 |
@@ -47,6 +48,7 @@ not in this table, search `src/index.ts` for the nearest noun before writing cod
 | asking a debugging model "what did this run contradict itself about, and why?" — the Context Integrity findings, joined to the step that filed them | `find_context_errors` | `src/lib/trace-toolpack/traceToolpack.ts` | 9.61.0 |
 | a tool answering "I looked and found nothing", routably | `absent` | `src/core/agent/coverage/absent.ts` | 9.43.0 |
 | stating what a clean answer does NOT rule out | `coverage` | `src/core/agent/coverage/ledger.ts` | 9.43.0 |
+| minting one of those shapes from a tool that is NOT JavaScript — the canonical note sentences and reserved marker keys as DATA, so a Python/Go/Rust sidecar reads a file instead of regex-scraping `dist/esm` (which a consumer really did) | `canonical-notes.json` at the package root + the `./canonical-notes.json` exports entry, GENERATED from the built barrel by `scripts/gen-canonical-notes.mjs` | `scripts/gen-canonical-notes.mjs` | 9.70.0 |
 | proving a session store really honours the port | `runSessionLifecycleConformance` | `src/hosting/conformance/` | 9.37.0 |
 | deciding who owns a contested session write | `resolveSessionOwner` | `src/hosting/sessionOwnership.ts` | 9.37.0 |
 | making a caller-supplied id safe for a backend | `encodeIdentityField` | `src/memory/identity/encode.ts` | 9.40.0 |

package/canonical-notes.json

@@ -0,0 +1,16 @@
+{
+  "$comment": "GENERATED by scripts/gen-canonical-notes.mjs from this package's own built exports - do not edit by hand. These are the strings a tool written in another language must reproduce byte for byte: the static notes each result shape carries, the reserved marker keys that make those shapes recognizable, and the coverage block's heading. Keys are the exported constant names, so the same value is reachable as a TypeScript import from the package's main entry point. The package version lives in package.json.",
+  "notes": {
+    "ABSENCE_NOTE": "The search ran and matched nothing. This is an ANSWER, not an error: nothing failed, nothing was substituted for what was asked, and calling this tool again with the same arguments returns this same result. `checked` is the ground this answer covers; anything under `not_checked` or `cannot_cover` is ground it does NOT cover, and reaching that needs a different question, not a retry.",
+    "COVERAGE_NOTE": "This result covers only what `checked` lists. `not_checked` is ground this call did not look at, and `cannot_cover` is ground this tool can never see — a clean result here is NOT evidence about either, and no retry changes `cannot_cover`. Carry these limits into any answer you build on this result.",
+    "SEMANTICS_NOTE": "Typed data, not prose. `grain` and `provenance` are caveats that travel with the numbers: check `is_counter` before summing values from a series, read `measured_at` (and `age_seconds`) as how old the data is, and treat everything under `not_covered` as ground this result does NOT cover — a clean look here says nothing about it."
+  },
+  "markers": {
+    "ABSENCE_MARKER": "af_absent",
+    "COVERAGE_MARKER": "af_coverage",
+    "SEMANTICS_MARKER": "af_semantics"
+  },
+  "headings": {
+    "COVERAGE_BLOCK_HEADING": "Coverage of this answer"
+  }
+}

package/dist/adapters/browser/agentcore.js

@@ -0,0 +1,203 @@
+"use strict";
+/**
+ * agentCoreBrowser — AWS Bedrock AgentCore **Browser** as a {@link BrowserRunner}.
+ *
+ * A managed Chrome in AWS's account that an agent can drive, a person can watch
+ * live, and — the part this adapter exists for — a person can TAKE OVER
+ * mid-session and hand back.
+ *
+ * ── Two channels, and only one of them is here ───────────────────────────────
+ * A browser session has two doors, and confusing them wastes a day:
+ *
+ *   1. **The automation stream** — a CDP WebSocket. Navigate, find an element,
+ *      fill a form: everything page-shaped happens here, driven by Playwright
+ *      or another CDP client. This adapter hands you
+ *      {@link BrowserSession.automationEndpoint} and stays out of the way. It
+ *      does not depend on Playwright and does not drive the page for you.
+ *   2. **`InvokeBrowser`** — the data-plane operation this adapter calls. It is
+ *      OS-LEVEL input ABOVE the page: mouse, keyboard, screenshots. Its action
+ *      union, read off the SDK rather than remembered, is exactly
+ *      `mouseClick | mouseMove | mouseDrag | mouseScroll | keyType | keyPress |
+ *      keyShortcut | screenshot`. **There is no navigate action**, and a reader
+ *      expecting one is looking at the wrong door.
+ *
+ * ── The takeover ─────────────────────────────────────────────────────────────
+ * `UpdateBrowserStream` with `automationStreamUpdate.streamStatus` set to
+ * `DISABLED` stops the automation channel and leaves the live-view user in
+ * control; `ENABLED` gives it back. That is `handControlTo('person' | 'agent')`
+ * here, and it composes with this library's check-in: the agent pauses, a
+ * person finishes the login, the agent resumes on the page they left — and both
+ * handovers are ordinary events in the trace.
+ *
+ * ── How this talks to the SDK (the 9.4.0 law) ────────────────────────────────
+ * Through `client.send(new SomeCommand(input))`, never a method on the client —
+ * a bare `@aws-sdk/client-*` Client carries `send` and `destroy` and nothing
+ * else. Every command name and request shape below was read off a real install
+ * of `@aws-sdk/client-bedrock-agentcore` **3.1118.0**, including the action
+ * union above and `ScreenshotResult`'s `{ status, error?, data? }`.
+ *
+ * ── One documented contradiction, left as AWS wrote it ───────────────────────
+ * The devguide says a session defaults to 15 minutes; `StartBrowserSession`'s
+ * API reference says 3600 seconds. This adapter sends nothing unless you pass
+ * `sessionTimeoutSeconds`, so the default is whatever the service applies —
+ * rather than this file picking a side in somebody else's disagreement.
+ *
+ * Pattern: Adapter (GoF) + lazy peer-dep load — the SDK is required only when
+ * `start()` first runs, or never, if you inject `_client` / `_sdk`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentCoreBrowser = exports.AWS_SYSTEM_BROWSER = void 0;
+const lazyRequire_js_1 = require("../../lib/lazyRequire.js");
+/** AWS's managed browser. A custom `CreateBrowser` resource id goes here instead. */
+exports.AWS_SYSTEM_BROWSER = 'aws.browser.v1';
+const BUTTONS = { left: 'LEFT', middle: 'MIDDLE', right: 'RIGHT' };
+function createBrowserClient(options) {
+    let mod;
+    if (options._sdk) {
+        mod = options._sdk;
+    }
+    else {
+        try {
+            mod = (0, lazyRequire_js_1.lazyRequire)('@aws-sdk/client-bedrock-agentcore');
+        }
+        catch {
+            throw new Error('agentCoreBrowser requires the `@aws-sdk/client-bedrock-agentcore` peer dependency.\n' +
+                '  Install:  npm install @aws-sdk/client-bedrock-agentcore\n' +
+                '  Or pass `_client` for a pre-built or mock client.');
+        }
+    }
+    if (!mod.BedrockAgentCoreClient) {
+        throw new Error('agentCoreBrowser: `@aws-sdk/client-bedrock-agentcore` is installed but ' +
+            '`BedrockAgentCoreClient` was not found. Update the SDK.');
+    }
+    const sdk = new mod.BedrockAgentCoreClient({ ...(options.region && { region: options.region }) });
+    const send = async (Ctor, name, input) => {
+        if (!Ctor) {
+            throw new Error(`agentCoreBrowser: \`@aws-sdk/client-bedrock-agentcore\` is missing ${name}. ` +
+                'Upgrade the SDK, or pass `_client` with your own mapping.');
+        }
+        return sdk.send(new Ctor(input));
+    };
+    return {
+        async startBrowserSession(input) {
+            return (await send(mod.StartBrowserSessionCommand, 'StartBrowserSessionCommand', input));
+        },
+        async invokeBrowser(input) {
+            return (await send(mod.InvokeBrowserCommand, 'InvokeBrowserCommand', input));
+        },
+        async updateBrowserStream(input) {
+            await send(mod.UpdateBrowserStreamCommand, 'UpdateBrowserStreamCommand', input);
+        },
+        async stopBrowserSession(input) {
+            await send(mod.StopBrowserSessionCommand, 'StopBrowserSessionCommand', input);
+        },
+    };
+}
+/**
+ * Build a {@link BrowserRunner} backed by AgentCore Browser.
+ *
+ * @example  A session, a person taking over, and the agent resuming
+ *   const browser = agentCoreBrowser({ region: 'us-east-1' });
+ *   const session = await browser.start({ key: toolSessionKey(ctx, 'run') });
+ *
+ *   // Page work goes over CDP, not through this adapter:
+ *   //   const page = await chromium.connectOverCDP(session.automationEndpoint!)
+ *
+ *   await session.handControlTo?.('person');   // they finish the login
+ *   await session.handControlTo?.('agent');    // and the agent carries on
+ *   await session.stop();
+ */
+function agentCoreBrowser(options = {}) {
+    const browserIdentifier = options.browserIdentifier ?? exports.AWS_SYSTEM_BROWSER;
+    let client;
+    const getClient = () => {
+        client ??= options._client ?? createBrowserClient(options);
+        return client;
+    };
+    return {
+        id: options.id ?? 'agentcore-browser',
+        async start(req) {
+            const c = getClient();
+            const started = await c.startBrowserSession({
+                browserIdentifier,
+                name: req.key,
+                ...(options.sessionTimeoutSeconds !== undefined && {
+                    sessionTimeoutSeconds: options.sessionTimeoutSeconds,
+                }),
+                ...(options.viewport !== undefined && { viewPort: options.viewport }),
+            });
+            const sessionId = started.sessionId;
+            if (!sessionId) {
+                throw new Error('agentCoreBrowser: StartBrowserSession returned no sessionId, so there is no session ' +
+                    'to drive. Check the browser identifier and the execution role.');
+            }
+            const act = async (action) => {
+                const answer = await c.invokeBrowser({ browserIdentifier, sessionId, action });
+                return answer.result;
+            };
+            const automationEndpoint = started.streams?.automationStream?.streamEndpoint;
+            const liveViewEndpoint = started.streams?.liveViewStream?.streamEndpoint;
+            const session = {
+                id: sessionId,
+                ...(automationEndpoint !== undefined && { automationEndpoint }),
+                ...(liveViewEndpoint !== undefined && { liveViewEndpoint }),
+                async click({ x, y, button, clicks }) {
+                    await act({
+                        mouseClick: {
+                            x,
+                            y,
+                            ...(button !== undefined && { button: BUTTONS[button] }),
+                            ...(clicks !== undefined && { clickCount: clicks }),
+                        },
+                    });
+                },
+                async type(text) {
+                    await act({ keyType: { text } });
+                },
+                async press({ key, times }) {
+                    await act({ keyPress: { key, ...(times !== undefined && { presses: times }) } });
+                },
+                async screenshot() {
+                    const result = await act({ screenshot: { format: 'PNG' } });
+                    const shot = result?.screenshot;
+                    if (!shot?.data) {
+                        // The result member carries its own status and error, so a failed
+                        // screenshot says what the service said rather than answering with
+                        // an empty image that reads as a blank page.
+                        throw new Error(`agentCoreBrowser: the screenshot did not produce image data` +
+                            `${shot?.status ? ` (status ${shot.status})` : ''}` +
+                            `${shot?.error ? `: ${shot.error}` : '.'}`);
+                    }
+                    return { data: shot.data, format: 'png' };
+                },
+                async handControlTo(driver) {
+                    // The person takes over by DISABLING automation: the live-view user
+                    // is already connected, and stopping the automation stream is what
+                    // lets their input through.
+                    await c.updateBrowserStream({
+                        browserIdentifier,
+                        sessionId,
+                        streamUpdate: {
+                            automationStreamUpdate: {
+                                streamStatus: driver === 'person' ? 'DISABLED' : 'ENABLED',
+                            },
+                        },
+                    });
+                },
+                async stop() {
+                    try {
+                        await c.stopBrowserSession({ browserIdentifier, sessionId });
+                    }
+                    catch {
+                        // A managed session reaped by its own idle timeout is the ordinary
+                        // case, and stopping one that is already gone is a no-op — the port
+                        // says so, and a throw here would fail a teardown that succeeded.
+                    }
+                },
+            };
+            return session;
+        },
+    };
+}
+exports.agentCoreBrowser = agentCoreBrowser;
+//# sourceMappingURL=agentcore.js.map

package/dist/adapters/browser/agentcore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentcore.js","sourceRoot":"","sources":["../../../src/adapters/browser/agentcore.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;;;AAGH,6DAAuD;AAEvD,qFAAqF;AACxE,QAAA,kBAAkB,GAAG,gBAAgB,CAAC;AAkEnD,MAAM,OAAO,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAW,CAAC;AAE5E,SAAS,mBAAmB,CAAC,OAAgC;IAC3D,IAAI,GAAqC,CAAC;IAC1C,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IACrB,CAAC;SAAM,CAAC;QACN,IAAI,CAAC;YACH,GAAG,GAAG,IAAA,4BAAW,EAAmC,mCAAmC,CAAC,CAAC;QAC3F,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,KAAK,CACb,sFAAsF;gBACpF,6DAA6D;gBAC7D,qDAAqD,CACxD,CAAC;QACJ,CAAC;IACH,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,sBAAsB,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CACb,yEAAyE;YACvE,yDAAyD,CAC5D,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,sBAAsB,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;IAElG,MAAM,IAAI,GAAG,KAAK,EAChB,IAA+C,EAC/C,IAAY,EACZ,KAAc,EACI,EAAE;QACpB,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CACb,sEAAsE,IAAI,IAAI;gBAC5E,2DAA2D,CAC9D,CAAC;QACJ,CAAC;QACD,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACnC,CAAC,CAAC;IAEF,OAAO;QACL,KAAK,CAAC,mBAAmB,CAAC,KAAK;YAC7B,OAAO,CAAC,MAAM,IAAI,CAChB,GAAG,CAAC,0BAA0B,EAC9B,4BAA4B,EAC5B,KAAK,CACN,CAA2E,CAAC;QAC/E,CAAC;QACD,KAAK,CAAC,aAAa,CAAC,KAAK;YACvB,OAAO,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,oBAAoB,EAAE,sBAAsB,EAAE,KAAK,CAAC,CAE1E,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,mBAAmB,CAAC,KAAK;YAC7B,MAAM,IAAI,CAAC,GAAG,CAAC,0BAA0B,EAAE,4BAA4B,EAAE,KAAK,CAAC,CAAC;QAClF,CAAC;QACD,KAAK,CAAC,kBAAkB,CAAC,KAAK;YAC5B,MAAM,IAAI,CAAC,GAAG,CAAC,yBAAyB,EAAE,2BAA2B,EAAE,KAAK,CAAC,CAAC;QAChF,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,gBAAgB,CAAC,UAAmC,EAAE;IACpE,MAAM,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,IAAI,0BAAkB,CAAC;IAC1E,IAAI,MAA8C,CAAC;IACnD,MAAM,SAAS,GAAG,GAA+B,EAAE;QACjD,MAAM,KAAK,OAAO,CAAC,OAAO,IAAI,mBAAmB,CAAC,OAAO,CAAC,CAAC;QAC3D,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;IAEF,OAAO;QACL,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,mBAAmB;QACrC,KAAK,CAAC,KAAK,CAAC,GAAG;YACb,MAAM,CAAC,GAAG,SAAS,EAAE,CAAC;YACtB,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,mBAAmB,CAAC;gBAC1C,iBAAiB;gBACjB,IAAI,EAAE,GAAG,CAAC,GAAG;gBACb,GAAG,CAAC,OAAO,CAAC,qBAAqB,KAAK,SAAS,IAAI;oBACjD,qBAAqB,EAAE,OAAO,CAAC,qBAAqB;iBACrD,CAAC;gBACF,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;aACtE,CAAC,CAAC;YACH,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;YACpC,IAAI,CAAC,SAAS,EAAE,CAAC;gBACf,MAAM,IAAI,KAAK,CACb,sFAAsF;oBACpF,gEAAgE,CACnE,CAAC;YACJ,CAAC;YAED,MAAM,GAAG,GAAG,KAAK,EACf,MAAyC,EACe,EAAE;gBAC1D,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,aAAa,CAAC,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;gBAC/E,OAAO,MAAM,CAAC,MAAM,CAAC;YACvB,CAAC,CAAC;YAEF,MAAM,kBAAkB,GAAG,OAAO,CAAC,OAAO,EAAE,gBAAgB,EAAE,cAAc,CAAC;YAC7E,MAAM,gBAAgB,GAAG,OAAO,CAAC,OAAO,EAAE,cAAc,EAAE,cAAc,CAAC;YAEzE,MAAM,OAAO,GAAmB;gBAC9B,EAAE,EAAE,SAAS;gBACb,GAAG,CAAC,kBAAkB,KAAK,SAAS,IAAI,EAAE,kBAAkB,EAAE,CAAC;gBAC/D,GAAG,CAAC,gBAAgB,KAAK,SAAS,IAAI,EAAE,gBAAgB,EAAE,CAAC;gBAE3D,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE;oBAClC,MAAM,GAAG,CAAC;wBACR,UAAU,EAAE;4BACV,CAAC;4BACD,CAAC;4BACD,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;4BACxD,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;yBACpD;qBACF,CAAC,CAAC;gBACL,CAAC;gBAED,KAAK,CAAC,IAAI,CAAC,IAAI;oBACb,MAAM,GAAG,CAAC,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;gBACnC,CAAC;gBAED,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE;oBACxB,MAAM,GAAG,CAAC,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;gBACnF,CAAC;gBAED,KAAK,CAAC,UAAU;oBACd,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,EAAE,UAAU,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;oBAC5D,MAAM,IAAI,GAAG,MAAM,EAAE,UAER,CAAC;oBACd,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;wBAChB,kEAAkE;wBAClE,mEAAmE;wBACnE,6CAA6C;wBAC7C,MAAM,IAAI,KAAK,CACb,6DAA6D;4BAC3D,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,YAAY,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;4BACnD,GAAG,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAC7C,CAAC;oBACJ,CAAC;oBACD,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;gBAC5C,CAAC;gBAED,KAAK,CAAC,aAAa,CAAC,MAAqB;oBACvC,oEAAoE;oBACpE,mEAAmE;oBACnE,4BAA4B;oBAC5B,MAAM,CAAC,CAAC,mBAAmB,CAAC;wBAC1B,iBAAiB;wBACjB,SAAS;wBACT,YAAY,EAAE;4BACZ,sBAAsB,EAAE;gCACtB,YAAY,EAAE,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;6BAC3D;yBACF;qBACF,CAAC,CAAC;gBACL,CAAC;gBAED,KAAK,CAAC,IAAI;oBACR,IAAI,CAAC;wBACH,MAAM,CAAC,CAAC,kBAAkB,CAAC,EAAE,iBAAiB,EAAE,SAAS,EAAE,CAAC,CAAC;oBAC/D,CAAC;oBAAC,MAAM,CAAC;wBACP,mEAAmE;wBACnE,oEAAoE;wBACpE,kEAAkE;oBACpE,CAAC;gBACH,CAAC;aACF,CAAC;YACF,OAAO,OAAO,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC;AA5GD,4CA4GC"}

package/dist/adapters/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAsHH;;;;GAIG;AACU,QAAA,2BAA2B,GAAwB,MAAM,CAAC,MAAM,CAAC;IAC5E,MAAM;IACN,WAAW;CACZ,CAAC,CAAC;AAqsBH;;;;;;GAMG;AACH,SAAgB,cAAc,CAC5B,OAAsC,EACtC,UAAgC;IAEhC,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,IAAI,UAAU,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IAC5C,OAAO,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;AACxD,CAAC;AAPD,wCAOC;AAqDD;;;;;;;;;GASG;AACU,QAAA,iBAAiB,GAAG,kBAAkB,CAAC;AAgGpD;uDACuD;AACvD,SAAgB,kBAAkB,CAChC,OAAoB;IAEpB,OAAO,OAAO,OAAO,CAAC,WAAW,KAAK,UAAU,CAAC;AACnD,CAAC;AAJD,gDAIC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAsHH;;;;GAIG;AACU,QAAA,2BAA2B,GAAwB,MAAM,CAAC,MAAM,CAAC;IAC5E,MAAM;IACN,WAAW;CACZ,CAAC,CAAC;AAqsBH;;;;;;GAMG;AACH,SAAgB,cAAc,CAC5B,OAAsC,EACtC,UAAgC;IAEhC,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,IAAI,UAAU,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IAC5C,OAAO,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;AACxD,CAAC;AAPD,wCAOC;AAqID;;;;;;;;;GASG;AACU,QAAA,iBAAiB,GAAG,kBAAkB,CAAC;AAgGpD;uDACuD;AACvD,SAAgB,kBAAkB,CAChC,OAAoB;IAEpB,OAAO,OAAO,OAAO,CAAC,WAAW,KAAK,UAAU,CAAC;AACnD,CAAC;AAJD,gDAIC"}

package/dist/artifacts/placement.js

@@ -5,7 +5,8 @@
  * An OPTIONAL operator dial on the agent's artifacts wiring:
  * `Agent.create({ artifacts: { store, placement: { maxInlineChars: N } } })`.
  * A tool result whose finalized text exceeds the threshold is checked into
- * the store (kind `tool-result/<toolName>`) and the model receives the claim
+ * the store (kind `tool-result/<toolName>`, or the tool's declared
+ * `resultKind` — see `placedResultKind`) and the model receives the claim
  * ticket instead — a SHORT substitute naming ref + meta + how to consume it.
  * The whole 879,073-token failure class, retired by configuration.
  *
@@ -49,12 +50,25 @@ function assertArtifactPlacement(site, placement) {
     }
 }
 exports.assertArtifactPlacement = assertArtifactPlacement;
-/** The kind vocabulary a placement mint declares: `tool-result/<toolName>`.
- *  Honest — it says exactly what the payload is and which tool produced it —
- *  and it is what a `wants` declaration or a `present` call names to consume
- *  the placed result. */
-function placedResultKind(toolName) {
-    return `tool-result/${toolName}`;
+/**
+ * The kind vocabulary a placement mint declares — THE one decision, and the
+ * only place it is made.
+ *
+ * Default: `tool-result/<toolName>`. Honest — it says exactly what the payload
+ * is and which tool produced it — and it is what a `wants` declaration or a
+ * `present` call names to consume the placed result.
+ *
+ * `declared` is the tool's own `Tool.resultKind` (9.70.0), and when a tool
+ * declares one it WINS. The reason is the exact-match law on the consuming
+ * end: `wants` matches kinds by exact string equality — no wildcards, no
+ * hierarchy — so the framework's default vocabulary is a ticket a
+ * `wants: { dataset: 'dataset/rows' }` argument must refuse. Rather than
+ * loosen the matcher (a ticket would stop being a promise) or make consumers
+ * re-mint at the seam (the framework declining to carry its own ref), the
+ * MINT speaks the author's vocabulary. Absent → today's bytes exactly.
+ */
+function placedResultKind(toolName, declared) {
+    return declared ?? `tool-result/${toolName}`;
 }
 exports.placedResultKind = placedResultKind;
 /** Type guard for consumers reading `tool_end.result` or a tool message. */

package/dist/artifacts/placement.js.map

@@ -1 +1 @@
-{"version":3,"file":"placement.js","sourceRoot":"","sources":["../../src/artifacts/placement.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;;;AAyBH;;;GAGG;AACH,SAAgB,uBAAuB,CACrC,IAAY,EACZ,SAAwC;IAExC,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO;IACpC,MAAM,KAAK,GAAG,SAAS,CAAC,cAAc,CAAC;IACvC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,KAAK,CACb,GAAG,IAAI,0EAA0E;YAC/E,mBAAmB,MAAM,CAAC,KAAK,CAAC,qDAAqD;YACrF,iFAAiF;YACjF,sFAAsF;YACtF,+CAA+C,CAClD,CAAC;IACJ,CAAC;AACH,CAAC;AAfD,0DAeC;AAED;;;yBAGyB;AACzB,SAAgB,gBAAgB,CAAC,QAAgB;IAC/C,OAAO,eAAe,QAAQ,EAAE,CAAC;AACnC,CAAC;AAFD,4CAEC;AAqBD,4EAA4E;AAC5E,SAAgB,kBAAkB,CAAC,KAAc;IAC/C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAA8B,CAAC,MAAM,KAAK,IAAI;QAC/C,OAAQ,KAA2B,CAAC,GAAG,KAAK,QAAQ;QACpD,OAAQ,KAA8B,CAAC,MAAM,KAAK,QAAQ,CAC3D,CAAC;AACJ,CAAC;AARD,gDAQC;AAED,qEAAqE;AACrE,SAAgB,gBAAgB,CAC9B,QAAgB,EAChB,IAAkB,EAClB,SAAiB,EACjB,cAAsB;IAEtB,OAAO;QACL,MAAM,EAAE,IAAI;QACZ,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,MAAM,EACJ,GAAG,QAAQ,aAAa,SAAS,oBAAoB,cAAc,kBAAkB;YACrF,yDAAyD,IAAI,CAAC,GAAG,IAAI;YACrE,IAAI,IAAI,CAAC,IAAI,mEAAmE;YAChF,WAAW,IAAI,CAAC,GAAG,qCAAqC,IAAI,CAAC,IAAI,aAAa;YAC9E,mBAAmB,IAAI,CAAC,GAAG,yDAAyD;YACpF,sCAAsC;KACzC,CAAC;AACJ,CAAC;AApBD,4CAoBC"}
+{"version":3,"file":"placement.js","sourceRoot":"","sources":["../../src/artifacts/placement.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;;;AAyBH;;;GAGG;AACH,SAAgB,uBAAuB,CACrC,IAAY,EACZ,SAAwC;IAExC,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO;IACpC,MAAM,KAAK,GAAG,SAAS,CAAC,cAAc,CAAC;IACvC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,KAAK,CACb,GAAG,IAAI,0EAA0E;YAC/E,mBAAmB,MAAM,CAAC,KAAK,CAAC,qDAAqD;YACrF,iFAAiF;YACjF,sFAAsF;YACtF,+CAA+C,CAClD,CAAC;IACJ,CAAC;AACH,CAAC;AAfD,0DAeC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,gBAAgB,CAAC,QAAgB,EAAE,QAAiB;IAClE,OAAO,QAAQ,IAAI,eAAe,QAAQ,EAAE,CAAC;AAC/C,CAAC;AAFD,4CAEC;AAsBD,4EAA4E;AAC5E,SAAgB,kBAAkB,CAAC,KAAc;IAC/C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAA8B,CAAC,MAAM,KAAK,IAAI;QAC/C,OAAQ,KAA2B,CAAC,GAAG,KAAK,QAAQ;QACpD,OAAQ,KAA8B,CAAC,MAAM,KAAK,QAAQ,CAC3D,CAAC;AACJ,CAAC;AARD,gDAQC;AAED,qEAAqE;AACrE,SAAgB,gBAAgB,CAC9B,QAAgB,EAChB,IAAkB,EAClB,SAAiB,EACjB,cAAsB;IAEtB,OAAO;QACL,MAAM,EAAE,IAAI;QACZ,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,MAAM,EACJ,GAAG,QAAQ,aAAa,SAAS,oBAAoB,cAAc,kBAAkB;YACrF,yDAAyD,IAAI,CAAC,GAAG,IAAI;YACrE,IAAI,IAAI,CAAC,IAAI,mEAAmE;YAChF,WAAW,IAAI,CAAC,GAAG,qCAAqC,IAAI,CAAC,IAAI,aAAa;YAC9E,mBAAmB,IAAI,CAAC,GAAG,yDAAyD;YACpF,sCAAsC;KACzC,CAAC;AACJ,CAAC;AApBD,4CAoBC"}

package/dist/core/agent/stages/toolCalls.js

@@ -1158,7 +1158,13 @@ function buildToolCallsHandler(deps) {
             // `mediaType` states what that text is: a JSON serialization when the
             // tool returned a value, plain text when it returned a string.
             meta = await bound.artifacts.put({
-                kind: (0, placement_js_1.placedResultKind)(call.toolName),
+                // The tool's own `resultKind` when it declared one (9.70.0), the
+                // framework's `tool-result/<name>` when it did not. Resolved HERE
+                // rather than threaded through the five dispatch doors: `lookupTool`
+                // is the closure's one resolver (registry + this iteration's cached
+                // provider list), so a sixth door added later cannot forget to carry
+                // the declaration — the `capResults` landmine, avoided by shape.
+                kind: (0, placement_js_1.placedResultKind)(call.toolName, lookupTool(call.toolName)?.resultKind),
                 mediaType: typeof values.modelResult === 'string' ? 'text/plain' : 'application/json',
                 data: text,
                 label: `${call.toolName} result`,