agentfootprint 9.68.0 → 9.70.0

package/dist/esm/adapters/browser/agentcore.d.ts

@@ -0,0 +1,141 @@
+/**
+ * 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`.
+ */
+import type { BrowserRunner } from '../types.js';
+/** AWS's managed browser. A custom `CreateBrowser` resource id goes here instead. */
+export declare const AWS_SYSTEM_BROWSER = "aws.browser.v1";
+export interface AgentCoreBrowserOptions {
+    /** AWS region. Falls back to the SDK's own resolution when omitted. */
+    readonly region?: string;
+    /** Which browser resource. Default {@link AWS_SYSTEM_BROWSER}. */
+    readonly browserIdentifier?: string;
+    /**
+     * Session lifetime in seconds. **Left unset by default on purpose** — AWS's
+     * own devguide (15 minutes) and API reference (3600 seconds) disagree, so
+     * sending nothing lets the service apply whichever it actually means.
+     */
+    readonly sessionTimeoutSeconds?: number;
+    /** Viewport for the session, when you want one that is not the default. */
+    readonly viewport?: {
+        readonly width: number;
+        readonly height: number;
+    };
+    /** Stable runner id (default `'agentcore-browser'`). */
+    readonly id?: string;
+    /** Test seam — inject a client implementing {@link AgentCoreBrowserClientLike}. */
+    readonly _client?: AgentCoreBrowserClientLike;
+    /** @internal Test injection — the AWS SDK module. */
+    readonly _sdk?: BedrockAgentCoreBrowserSdkModule;
+}
+/** The operation-semantic surface this adapter calls. */
+export interface AgentCoreBrowserClientLike {
+    startBrowserSession(input: {
+        readonly browserIdentifier: string;
+        readonly name?: string;
+        readonly sessionTimeoutSeconds?: number;
+        readonly viewPort?: {
+            readonly width: number;
+            readonly height: number;
+        };
+    }): Promise<{
+        readonly sessionId?: string;
+        readonly streams?: {
+            readonly automationStream?: {
+                readonly streamEndpoint?: string;
+            };
+            readonly liveViewStream?: {
+                readonly streamEndpoint?: string;
+            };
+        };
+    }>;
+    invokeBrowser(input: {
+        readonly browserIdentifier: string;
+        readonly sessionId: string;
+        readonly action: Readonly<Record<string, unknown>>;
+    }): Promise<{
+        readonly result?: Readonly<Record<string, unknown>>;
+    }>;
+    updateBrowserStream(input: {
+        readonly browserIdentifier: string;
+        readonly sessionId: string;
+        readonly streamUpdate: {
+            readonly automationStreamUpdate: {
+                readonly streamStatus: 'ENABLED' | 'DISABLED';
+            };
+        };
+    }): Promise<void>;
+    stopBrowserSession(input: {
+        readonly browserIdentifier: string;
+        readonly sessionId: string;
+    }): Promise<void>;
+}
+/** The slice of `@aws-sdk/client-bedrock-agentcore` this shim touches. */
+export interface BedrockAgentCoreBrowserSdkModule {
+    readonly BedrockAgentCoreClient?: new (config: {
+        region?: string;
+    }) => {
+        send(cmd: unknown): Promise<unknown>;
+    };
+    readonly StartBrowserSessionCommand?: new (input: unknown) => unknown;
+    readonly InvokeBrowserCommand?: new (input: unknown) => unknown;
+    readonly UpdateBrowserStreamCommand?: new (input: unknown) => unknown;
+    readonly StopBrowserSessionCommand?: new (input: unknown) => unknown;
+}
+/**
+ * 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();
+ */
+export declare function agentCoreBrowser(options?: AgentCoreBrowserOptions): BrowserRunner;

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

@@ -0,0 +1,199 @@
+/**
+ * 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`.
+ */
+import { lazyRequire } from '../../lib/lazyRequire.js';
+/** AWS's managed browser. A custom `CreateBrowser` resource id goes here instead. */
+export const 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 = 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();
+ */
+export function agentCoreBrowser(options = {}) {
+    const browserIdentifier = options.browserIdentifier ?? 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;
+        },
+    };
+}
+//# sourceMappingURL=agentcore.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agentcore.js","sourceRoot":"","sources":["../../../../src/adapters/browser/agentcore.ts"],"names":[],"mappings":"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"}

package/dist/esm/adapters/types.d.ts

@@ -811,6 +811,88 @@ export interface PricingTable {
  *
  * Implement it for your own backend; ship it to `codeRunnerTool({ runner })`.
  */
+/** One screenshot a browser session took. */
+export interface BrowserShot {
+    /** Image bytes. */
+    readonly data: Uint8Array;
+    /** Image format, lower-case (`'png'`). */
+    readonly format: string;
+}
+/** Who is driving a browser session right now. */
+export type BrowserDriver = 'agent' | 'person';
+/**
+ * A browser an agent can drive — the PORT (9.68.0).
+ *
+ * Deliberately small, and deliberately not a browser automation API. Page-level
+ * work (navigate, find an element, fill a form) is what CDP and Playwright
+ * already do far better than any interface here would; a session exposes
+ * {@link BrowserSession.automationEndpoint} so those attach directly. What this
+ * port carries is what an automation library CANNOT do on its own: open and
+ * release a managed session, reach the operating system above the page, and —
+ * the one that matters — hand the controls to a person and take them back.
+ */
+export interface BrowserRunner {
+    /** Stable id — reported on every tool-session event, so a row names its backend. */
+    readonly id: string;
+    /**
+     * Open a session.
+     *
+     * `key` is the ISOLATION key the caller derived. An adapter may use it to
+     * name the remote session; it must never widen it.
+     */
+    start(req: {
+        readonly key: string;
+        readonly signal?: AbortSignal;
+    }): Promise<BrowserSession>;
+}
+/** One open browser session. */
+export interface BrowserSession {
+    /** The backend's own id for this session. */
+    readonly id: string;
+    /**
+     * Where an automation client attaches — a CDP WebSocket, for Playwright and
+     * friends. Absent on a backend that offers no such channel.
+     *
+     * This library does not drive the page for you and does not depend on
+     * Playwright; it hands you the endpoint and stays out of the way.
+     */
+    readonly automationEndpoint?: string;
+    /** Where a PERSON can watch this session, when the backend offers a view. */
+    readonly liveViewEndpoint?: string;
+    /** Click at a point, in the operating system rather than in the page. */
+    click(req: {
+        readonly x: number;
+        readonly y: number;
+        readonly button?: 'left' | 'middle' | 'right';
+        readonly clicks?: number;
+    }): Promise<void>;
+    /** Type text, as a keyboard would. */
+    type(text: string): Promise<void>;
+    /** Press a named key, optionally more than once. */
+    press(req: {
+        readonly key: string;
+        readonly times?: number;
+    }): Promise<void>;
+    /** Take a screenshot of the session as it is now. */
+    screenshot(): Promise<BrowserShot>;
+    /**
+     * Hand the controls to a person, or take them back (optional).
+     *
+     * This is the seam a human-in-the-loop browsing flow is built on: the agent
+     * stops driving, a person finishes the step that needed them — a login, a
+     * consent screen, a CAPTCHA — and the agent resumes on the page they left.
+     * Absent on a backend with no such notion; feature-detect before offering it.
+     */
+    handControlTo?(driver: BrowserDriver): Promise<void>;
+    /**
+     * Release the session.
+     *
+     * Must tolerate a session the far side already reaped — an idle timeout is
+     * the reality on every managed backend, and a stop on a dead session is a
+     * no-op, not an error.
+     */
+    stop(): Promise<void>;
+}
 export interface CodeRunner {
     /** Stable id — reported on every `agentfootprint.tools.session_*` event so a
      *  row names its backend, not just its tool. */

package/dist/esm/adapters/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/adapters/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAsHH;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAwB,MAAM,CAAC,MAAM,CAAC;IAC5E,MAAM;IACN,WAAW;CACZ,CAAC,CAAC;AAqsBH;;;;;;GAMG;AACH,MAAM,UAAU,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;AAqDD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAgGpD;uDACuD;AACvD,MAAM,UAAU,kBAAkB,CAChC,OAAoB;IAEpB,OAAO,OAAO,OAAO,CAAC,WAAW,KAAK,UAAU,CAAC;AACnD,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/adapters/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAsHH;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAwB,MAAM,CAAC,MAAM,CAAC;IAC5E,MAAM;IACN,WAAW;CACZ,CAAC,CAAC;AAqsBH;;;;;;GAMG;AACH,MAAM,UAAU,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;AAqID;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAgGpD;uDACuD;AACvD,MAAM,UAAU,kBAAkB,CAChC,OAAoB;IAEpB,OAAO,OAAO,OAAO,CAAC,WAAW,KAAK,UAAU,CAAC;AACnD,CAAC"}

package/dist/esm/artifacts/placement.d.ts

@@ -4,7 +4,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.
  *
@@ -55,11 +56,24 @@ export interface ArtifactPlacement {
  * — never at the first oversized result of the first run.
  */
 export declare function assertArtifactPlacement(site: string, placement: ArtifactPlacement | undefined): void;
-/** 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. */
-export declare function placedResultKind(toolName: string): string;
+/**
+ * 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.
+ */
+export declare function placedResultKind(toolName: string, declared?: string): string;
 /**
  * The substitute the model reads in place of the payload — ONE shape, always
  * the object (the `TruncatedToolResult` law: a consumer branches on
@@ -70,7 +84,8 @@ export interface PlacedToolResult {
     /** Always `true`. The field a consumer branches on. */
     readonly placed: true;
     readonly ref: string;
-    /** `tool-result/<toolName>` — what a consumer names to want it. */
+    /** The minted kind — what a consumer names to want it. The tool's declared
+     *  `Tool.resultKind` when it has one, `tool-result/<toolName>` otherwise. */
     readonly kind: string;
     readonly mediaType: string;
     /** The stored payload's true size — the chars the window did NOT pay. */

package/dist/esm/artifacts/placement.js

@@ -4,7 +4,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.
  *
@@ -45,12 +46,25 @@ export function assertArtifactPlacement(site, placement) {
             `measured and never placed, exactly as before.`);
     }
 }
-/** 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. */
-export 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.
+ */
+export function placedResultKind(toolName, declared) {
+    return declared ?? `tool-result/${toolName}`;
 }
 /** Type guard for consumers reading `tool_end.result` or a tool message. */
 export function isPlacedToolResult(value) {

package/dist/esm/artifacts/placement.js.map

@@ -1 +1 @@
-{"version":3,"file":"placement.js","sourceRoot":"","sources":["../../../src/artifacts/placement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAyBH;;;GAGG;AACH,MAAM,UAAU,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;AAED;;;yBAGyB;AACzB,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,OAAO,eAAe,QAAQ,EAAE,CAAC;AACnC,CAAC;AAqBD,4EAA4E;AAC5E,MAAM,UAAU,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;AAED,qEAAqE;AACrE,MAAM,UAAU,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"}
+{"version":3,"file":"placement.js","sourceRoot":"","sources":["../../../src/artifacts/placement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAyBH;;;GAGG;AACH,MAAM,UAAU,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;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB,EAAE,QAAiB;IAClE,OAAO,QAAQ,IAAI,eAAe,QAAQ,EAAE,CAAC;AAC/C,CAAC;AAsBD,4EAA4E;AAC5E,MAAM,UAAU,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;AAED,qEAAqE;AACrE,MAAM,UAAU,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"}

package/dist/esm/core/agent/stages/toolCalls.d.ts

@@ -103,8 +103,9 @@ export interface ToolCallsHandlerDeps {
      * The placement threshold (9.22.0) — the operator's ref-ing dial. When set
      * (only ever beside `artifactStore`; the Agent option's shape enforces it),
      * every finalized tool result on every dispatch path is measured, and one
-     * whose text exceeds `maxInlineChars` is checked into the store (kind
-     * `tool-result/<toolName>`) with the model reading the claim ticket
+     * whose text exceeds `maxInlineChars` is checked into the store (under the
+     * tool's declared `resultKind`, or `tool-result/<toolName>` when it
+     * declares none) with the model reading the claim ticket
      * instead. Judged AFTER the tool's own `resultCeiling` and the after-tool
      * chain, BEFORE the `maxToolResultChars` truncation net. Undefined — the
      * default — and results are never measured against it (zero-cost).

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

@@ -1155,7 +1155,13 @@ export 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: 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: placedResultKind(call.toolName, lookupTool(call.toolName)?.resultKind),
                 mediaType: typeof values.modelResult === 'string' ? 'text/plain' : 'application/json',
                 data: text,
                 label: `${call.toolName} result`,