agentfootprint 9.6.0 → 9.7.0

package/dist/types/core/codeRunnerTool.d.ts

@@ -0,0 +1,121 @@
+/**
+ * codeRunnerTool — the tool that turns a {@link CodeRunner} into something an
+ * LLM can call, holding ONE session per isolation key.
+ *
+ * Pattern: Factory over `defineTool` + the 9.7.0 tool-session contract.
+ * Role:    the first consumer of `ctx.onTeardown` — and the proof it works.
+ * Emits:   nothing directly; the teardown tier reports
+ *          `agentfootprint.tools.session_started` / `_reused` / `_closed` /
+ *          `_close_failed`.
+ *
+ * ── The doctrine: summarize prose, compute data ─────────────────────────────
+ * A tool that hands the model 40,000 rows has not given it data; it has spent
+ * the window. The motivating failure is real and measured: a production request
+ * of 879,073 tokens, almost all of it one tool result pasted into the prompt.
+ * (Since 9.6.0 that shape at least fails by NAME —
+ * `ContextWindowExceededError` — instead of as a vendor 400. This is the other
+ * half: not failing better, but not needing to.)
+ *
+ * With a code runner the model writes an aggregation, the RUNNER holds the
+ * rows, and what comes back is the number. Prose gets summarized; data gets
+ * computed.
+ *
+ * ── Why the session must be keyed, and keyed WIDELY ENOUGH ──────────────────
+ * The session is the whole value: a code interpreter costs seconds to start and
+ * milliseconds to invoke. But a session holds a filesystem, an environment and
+ * half-run state, so the thing it is keyed on IS the isolation boundary. A
+ * standing agent serving many people from one process, holding one session in a
+ * module map, gives person B person A's files.
+ *
+ * So the key comes from `toolSessionKey(ctx, scope)` — one exported
+ * implementation, composing tenant + principal + (session | run). Never a bare
+ * `sessionId`: that is caller data, and anyone who can reach the host can put
+ * someone else's there.
+ *
+ * ── Degradation is REFUSED, never silent ────────────────────────────────────
+ * Ask for `scope: 'session'` at a door with no session and this throws, naming
+ * the door. It does not quietly fall back. Falling back to a WIDER key is the
+ * cross-binding bug itself; falling back to a NARROWER one is a silent 30×
+ * latency change nobody sees until the bill.
+ *
+ * @example a session per run, on a local dev machine
+ *   const agent = Agent.create({ provider })
+ *     .tool(codeRunnerTool({ runner: localCodeRunner() }))
+ *     .build();
+ *
+ * @example a session per hosted conversation, on a real sandbox
+ *   const runner = agentCoreCodeRunner({ region, identifier: 'aws.codeinterpreter.v1' });
+ *   const agent = Agent.create({ provider })
+ *     .tool(codeRunnerTool({ runner, scope: 'session', language: 'python' }))
+ *     .build();
+ *   // the composition root says when a session is over:
+ *   conversation.onClose(() => void agent.closeToolSessions({ sessionId }));
+ */
+import type { CodeRunner, CodeSession } from '../adapters/types.js';
+import type { CredentialNeed } from '../identity/types.js';
+import type { CheckInDemand } from './checkin.js';
+import { type Tool } from './tools.js';
+import { type TeardownScope } from './toolSessions.js';
+/** The scopes a code session can be held under. `'shutdown'` is not one: it is
+ *  when everything goes, not a thing to key a session on. */
+export type CodeRunnerToolScope = Extract<TeardownScope, 'call' | 'run' | 'session'>;
+export interface CodeRunnerToolOptions {
+    /** The backend. `localCodeRunner()` for a dev loop, `agentCoreCodeRunner(...)`
+     *  for a real sandbox — the tool is identical across the swap. */
+    readonly runner: CodeRunner;
+    /** Tool name the model sees. Default `'run_code'`. */
+    readonly name?: string;
+    /** Description the model sees. A sensible one is composed from `scope` +
+     *  `language` when you do not pass one. */
+    readonly description?: string;
+    /**
+     * How long one session lives. Default `'run'` — a turn's worth of work shares
+     * one interpreter, and nothing outlives the turn.
+     *
+     * `'session'` keeps the interpreter across the turns of one hosted
+     * conversation (variables persist, files persist) and REQUIRES a
+     * session-bound run plus a composition root that calls
+     * `agent.closeToolSessions({ sessionId })`.
+     *
+     * `'call'` starts and stops per invocation — the safest and the slowest.
+     */
+    readonly scope?: CodeRunnerToolScope;
+    /** Default language for the code the model writes. Default `'python'`. */
+    readonly language?: string;
+    /** Per-stream ceiling for what reaches the model, in characters. Default 4000.
+     *  Anything cut is STATED in the result, never dropped quietly. */
+    readonly maxOutputChars?: number;
+    /** Per-execution ceiling handed to the runner. */
+    readonly timeoutMs?: number;
+    /** Demand a human check-in before code runs — `'always'`, or a predicate over
+     *  the code string. A pause here does NOT tear the session down. */
+    readonly checkIn?: CheckInDemand<{
+        code: string;
+    }>;
+    /** A credential this tool needs (declare-and-push). Resolved before execute.
+     *  Do NOT cache it past the call: a session outliving a run outlives its token. */
+    readonly needs?: CredentialNeed;
+}
+/**
+ * The per-tool session map, riding the `Tool` under a REGISTRY symbol.
+ *
+ * `Symbol.for`, not a unique symbol: this package ships CJS and ESM, and a tool
+ * built through one entry point must be readable through the other. The same
+ * move `INNER_RUN_RECORDS` makes for `flowchartAsTool({ keepRecord })` — and
+ * deliberately a DIFFERENT symbol, so one tool can carry both (spreading a tool
+ * preserves symbol keys, which is why `{...tool, [SYM]: store}` composes).
+ *
+ * Invisible to the LLM, invisible to `Tool`'s shape, reachable by a test and by
+ * whatever inspector comes next.
+ */
+export declare const TOOL_SESSIONS: unique symbol;
+/** A `Tool` that holds live sessions, keyed by isolation key. */
+export interface HoldsToolSessions {
+    readonly [TOOL_SESSIONS]: ReadonlyMap<string, CodeSession>;
+}
+/** Read the live-session map off a candidate, or `undefined` when it holds none. */
+export declare function toolSessionsOf(candidate: unknown): ReadonlyMap<string, CodeSession> | undefined;
+export declare function codeRunnerTool(options: CodeRunnerToolOptions): Tool<{
+    code: string;
+}, string> & HoldsToolSessions;
+//# sourceMappingURL=codeRunnerTool.d.ts.map

package/dist/types/core/codeRunnerTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codeRunnerTool.d.ts","sourceRoot":"","sources":["../../../src/core/codeRunnerTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,OAAO,KAAK,EAAc,UAAU,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAChF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAc,KAAK,IAAI,EAA6B,MAAM,YAAY,CAAC;AAC9E,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvE;6DAC6D;AAC7D,MAAM,MAAM,mBAAmB,GAAG,OAAO,CAAC,aAAa,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC,CAAC;AAErF,MAAM,WAAW,qBAAqB;IACpC;sEACkE;IAClE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,sDAAsD;IACtD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;+CAC2C;IAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAC;IACrC,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;uEACmE;IACnE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,kDAAkD;IAClD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;wEACoE;IACpE,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnD;uFACmF;IACnF,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;CACjC;AAID;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,EAAE,OAAO,MAAoD,CAAC;AAExF,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,CAAC,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CAC5D;AAED,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,SAAS,EAAE,OAAO,GAAG,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,SAAS,CAI/F;AAED,wBAAgB,cAAc,CAC5B,OAAO,EAAE,qBAAqB,GAC7B,IAAI,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,CAAC,GAAG,iBAAiB,CA2FpD"}

package/dist/types/core/toolSessions.d.ts

@@ -0,0 +1,319 @@
+/**
+ * toolSessions — the end-signal a tool can be handed, and the tier that fires it.
+ *
+ * Pattern: Registrar + Template Method for the firing matrix.
+ * Role:    core primitive. `ToolExecutionContext.onTeardown` registers here;
+ *          `Agent.run`'s terminals, `RunnerBase.closeToolSessions` and
+ *          `RunnerBase.shutdown` fire it.
+ * Emits:   nothing itself. `register()` ANSWERS what it did (started/reused) so
+ *          the caller — still inside a stage — can emit with a real
+ *          `runtimeStageId`, and teardown REPORTS (see {@link ToolSessionReport})
+ *          so the runner can emit the two that fire after the last stage.
+ *
+ * ── The gap this closes ─────────────────────────────────────────────────────
+ * A session-based tool service (a managed code interpreter, a headless browser)
+ * is Start → Invoke ×N → Stop. Before 9.7.0 a `Tool` had nowhere to hold the
+ * middle of that: `ToolExecutionContext` carried no run or session identity, and
+ * nothing in the framework ever said "this is over". So a tool either paid
+ * start-up on every call, or held the session in a module-level map — which, in
+ * a standing agent serving many people from one process, hands ONE live sandbox
+ * to whoever calls next. That is not a leak of memory; it is a leak of a
+ * filesystem, an environment and half-run state, across users.
+ *
+ * ── Why the registration lives on the CONTEXT ───────────────────────────────
+ * Not `Tool.dispose()`: a `Tool` is a singleton, built once and shared by every
+ * run and every session, so "dispose the tool" cannot mean "dispose this
+ * caller's session".
+ * Not a lifecycle PORT the consumer wires: that makes the common case (one tool
+ * that happens to hold a session) a wiring exercise, and the tool that knows the
+ * key is the one that cannot reach the port.
+ * `ctx.onTeardown(cleanup, { scope, key })` is the only seam where the key and
+ * the resource are both in hand at the same instant.
+ *
+ * ── The seven laws ──────────────────────────────────────────────────────────
+ *  1. **At most once, ever** per registration — the `stopped`-flag mechanism
+ *     `strategies/lifecycle.ts` uses for strategies, applied one layer down.
+ *  2. **Idempotent by `(tool, scope, key)`, first wins.** A second registration
+ *     under the same key does not replace the first — the first is the one
+ *     holding the live handle; replacing it would drop that handle on the
+ *     floor. The repeat is a TOUCH: it refreshes liveness (that is how the
+ *     idle sweep and the LRU learn a session is still in use) and answers
+ *     `'reused'`.
+ *  3. **Reverse order of registration**, settled with `Promise.allSettled`.
+ *  4. **Bounded** by `timeoutMs` (default 5s). Teardown is on the SIGTERM path;
+ *     an unbounded `stop()` turns a container stop into a wait for SIGKILL.
+ *  5. **Never throws into the run** — but **never silent** either. Every
+ *     failure, and every timeout, is reported. "Swallowed AND silent" is what
+ *     separates a passive recorder from a resource that did not get released.
+ *  6. **Tolerates "already gone."** The far side reaps idle sessions on its own
+ *     schedule; a `Stop` on a session AWS already collected is a no-op, not an
+ *     incident. It still reports, so the difference is visible.
+ *  7. **Nothing live is ever persisted.** A checkpoint carries what survives
+ *     `structuredClone`; a session handle does not. A resumed run re-opens.
+ *
+ * Zero-cost when unused: no tool registers → the runner never builds a tier →
+ * the terminal path is one `undefined` check.
+ */
+import type { ToolExecutionContext } from './tools.js';
+/**
+ * How long a registered cleanup is allowed to live.
+ *
+ *  - `'call'`     — until `tool.execute` settles (resolve OR throw). Available
+ *                   at every door, including `mcpServe`, where a served call is
+ *                   the only unit there is.
+ *  - `'run'`      — until the run reaches a terminal that is NOT a pause.
+ *                   **A pause is not a terminal**: a check-in on a code
+ *                   interpreter is a person deciding, and tearing the sandbox
+ *                   down there destroys the exact state the resume needs.
+ *  - `'session'`  — until the composition root says the hosting session ended
+ *                   (`agent.closeToolSessions({ sessionId })`). Nobody but the
+ *                   composition root can know that: a request/reply deployment
+ *                   has no end-of-session signal, and inventing one would be a
+ *                   library guessing about somebody else's protocol.
+ *  - `'shutdown'` — until `agent.shutdown()` (which `standingAgent`'s close
+ *                   calls). The backstop under all three.
+ */
+export type TeardownScope = 'call' | 'run' | 'session' | 'shutdown';
+/** Why a cleanup ran. Reported on `agentfootprint.tools.session_closed`. */
+export type TeardownReason = 'call-end' | 'run-end' | 'session-end' | 'shutdown' | 'idle' | 'evicted';
+/** What a tool says about the cleanup it is registering. */
+export interface TeardownOptions {
+    /** Default `'run'`. Refused by name when the door cannot honour it — see
+     *  {@link ToolExecutionContext.teardownScopes}. */
+    readonly scope?: TeardownScope;
+    /**
+     * Dedup key within `(tool, scope)`. Omitted → the tool gets one registration
+     * per scope, which is right for a tool that holds exactly one thing.
+     *
+     * Derive it with {@link toolSessionKey} rather than by hand: a key that is
+     * narrower than the identity it isolates is the cross-binding bug, and a key
+     * that is wider is a silent latency change.
+     */
+    readonly key?: string;
+    /** The adapter holding the resource — `CodeRunner.id`, say. Reported so a
+     *  row names its backend instead of only its tool. */
+    readonly runnerId?: string;
+    /** One free-form fact about what was opened (the language, the browser
+     *  profile). Reported as-is; never a place for user data. */
+    readonly label?: string;
+}
+/** The call a registration came from — what the firing matrix filters on. */
+export interface ToolSessionOrigin {
+    readonly tool: string;
+    readonly toolCallId: string;
+    /** Absent when the door has no run (`mcpServe`). */
+    readonly runId?: string;
+    /** Absent unless the run is bound to a hosting conversation. */
+    readonly sessionId?: string;
+}
+/**
+ * What `register()` did — a new session, or a call joining one already held.
+ *
+ * Returned rather than reported, because the two halves of a session's life
+ * happen in different places and only one of them has a stage to be stamped
+ * with. A start and a reuse happen INSIDE `tool.execute`, where the caller
+ * still holds the scope and can emit with the real `runtimeStageId`; a close
+ * happens after the run's last stage committed, where nothing does. Reporting
+ * both through one channel would have meant stamping a live, mid-stage event
+ * with the teardown pseudo-stage — a small lie, and exactly the kind that makes
+ * a trace disagree with itself.
+ */
+export type RegisterOutcome = 'started' | 'reused';
+/**
+ * A teardown that happened. The runner turns it into
+ * `agentfootprint.tools.session_closed` / `_close_failed`.
+ */
+export interface ToolSessionReport {
+    readonly kind: 'closed' | 'close-failed';
+    readonly tool: string;
+    readonly scope: TeardownScope;
+    /** {@link hashSessionKey} of the isolation key — never the key. */
+    readonly keyHash: string;
+    readonly runnerId?: string;
+    readonly label?: string;
+    /** Which firing site ran it. */
+    readonly reason: TeardownReason;
+    /** Wall-clock from registration to close. */
+    readonly durationMs: number;
+    /** `close-failed` only. */
+    readonly error?: string;
+    readonly errorClass?: string;
+}
+/**
+ * Derive the isolation key a tool should hold a session under.
+ *
+ * ONE implementation, exported, because the derivation is the security
+ * boundary. Returns `undefined` when the facts the scope needs are absent —
+ * which is a refusal to guess, not a failure: the caller decides whether to
+ * narrow the scope loudly or refuse the call.
+ *
+ * ```
+ * session →  t=<tenant|_>/p=<principal|_>/s=<sessionId>     requires sessionId
+ * run     →  t=<tenant|_>/p=<principal|_>/r=<runId>         requires runId
+ * call    →  c=<toolCallId>                                 always available
+ * ```
+ *
+ * **`sessionId` alone must never key a live session.** The hosting port says
+ * why in its own words: a `sessionId` "is not identity and must never be
+ * trusted as identity on its own: anyone who can reach the host can put any
+ * string here, including someone else's." A code interpreter keyed on
+ * `sessionId` alone hands a live sandbox — files, environment, half-run state —
+ * to anyone who guesses one. Tenant and principal are in the key whenever they
+ * exist; a deployment that has no principal is thereby STATING it is
+ * single-principal rather than quietly assuming it.
+ *
+ * `'shutdown'` is not a key scope: it is when everything goes, not a thing to
+ * hold one session under. Ask for it and you get `undefined`.
+ *
+ * @example
+ *   const key = toolSessionKey(ctx, 'run');
+ *   if (!key) throw new Error("run_code: scope 'run' needs a run …");
+ */
+export declare function toolSessionKey(ctx: Pick<ToolExecutionContext, 'toolCallId' | 'runId' | 'sessionId' | 'identity'>, scope: TeardownScope): string | undefined;
+/**
+ * A short, stable digest of an isolation key.
+ *
+ * The key carries tenant, principal and the hosting `sessionId`. Publishing it
+ * on the event wire would put a user identifier into every exporter's payload —
+ * so the wire carries this instead, which is enough to JOIN two rows and not
+ * enough to name whose they are. `meta.sessionId` already carries the session
+ * legitimately (9.4.0); the payload does not repeat it.
+ *
+ * SHA-256, first 12 hex chars, wherever `node:crypto` resolves. In a browser
+ * bundle, where it does not, this falls back to the package's non-cryptographic
+ * FNV-1a digest — stated here rather than implied, because a fallback nobody
+ * documented is how "hashed" comes to mean less than a reader assumed.
+ */
+export declare function hashSessionKey(key: string): string;
+/** Defaults, named so a test and a docstring cannot drift from the code. */
+export declare const TOOL_TEARDOWN_TIMEOUT_MS = 5000;
+/** A session untouched this long is swept on the tier's next interaction. */
+export declare const TOOL_SESSION_IDLE_MS = 900000;
+/** How many live registrations one tier holds before it evicts the coldest. */
+export declare const TOOL_SESSION_MAX_LIVE = 64;
+export interface ToolSessionTierOptions {
+    /** Per-cleanup ceiling. Default {@link TOOL_TEARDOWN_TIMEOUT_MS}. */
+    readonly timeoutMs?: number;
+    /** Idle ceiling for the lazy sweep. Default {@link TOOL_SESSION_IDLE_MS}. */
+    readonly idleMs?: number;
+    /** Live-registration ceiling before LRU eviction. Default
+     *  {@link TOOL_SESSION_MAX_LIVE}. */
+    readonly maxLive?: number;
+    /** Where TEARDOWN reports go. The runner wires this to the typed event
+     *  dispatcher. Starts and reuses are the caller's to announce — see
+     *  {@link RegisterOutcome}. */
+    readonly report?: (report: ToolSessionReport) => void;
+    /** Clock seam — tests drive idle and duration without waiting. */
+    readonly now?: () => number;
+}
+/**
+ * The teardown tier for one runner.
+ *
+ * Holds nothing until a tool registers, and the runner builds one only when
+ * that happens — so an agent whose tools hold no sessions pays a single
+ * `undefined` check at each terminal and nothing else.
+ */
+export declare class ToolSessionTier {
+    private readonly registrations;
+    private readonly timeoutMs;
+    private readonly idleMs;
+    private readonly maxLive;
+    private readonly report;
+    private readonly now;
+    private seq;
+    constructor(options?: ToolSessionTierOptions);
+    /** Live registrations. Diagnostics and tests. */
+    liveCount(): number;
+    /**
+     * Resolve once every teardown this tier started IN THE BACKGROUND has
+     * settled.
+     *
+     * Two firings have no caller to await them: the idle sweep and the LRU
+     * eviction, both of which are triggered by a SYNCHRONOUS `register()` inside
+     * somebody else's `tool.execute`. They cannot be awaited there without making
+     * a cleanup's latency the tool's latency, so they run detached — and this is
+     * how a shutdown path, or a test, joins them.
+     */
+    settled(): Promise<void>;
+    /** Fires nobody is awaiting — see {@link settled}. */
+    private readonly background;
+    /** Start a detached fire and keep it joinable. */
+    private detach;
+    /**
+     * Register a cleanup, or TOUCH the one already holding this key (law 2).
+     *
+     * Synchronous and total: it never throws, because it runs inside somebody
+     * else's `tool.execute`. Scope support is judged one layer up, where
+     * `teardownScopes` is known.
+     *
+     * @returns `'started'` for a new session, `'reused'` when this call joined
+     *   one already held, with `calls` counting how many have now shared it. The
+     *   CALLER announces it, because the caller is the one still inside a stage
+     *   and able to stamp a real `runtimeStageId` — see {@link RegisterOutcome}.
+     */
+    register(origin: ToolSessionOrigin, cleanup: () => void | Promise<void>, options?: TeardownOptions): {
+        readonly outcome: RegisterOutcome;
+        readonly keyHash: string;
+        readonly calls: number;
+    };
+    /** Fire every `'call'` registration this tool call opened. */
+    fireCall(toolCallId: string): Promise<void>;
+    /**
+     * Fire `'run'`-scoped registrations at a run terminal.
+     *
+     * Called from `Agent.run`/`resume` at a terminal that is NOT a pause — and
+     * deliberately not from a `finally`, which also runs on the two pause shapes.
+     *
+     * **`runId` is optional, and the Agent omits it.** A `'run'` scope means
+     * "release this when the TURN that opened it ends", and a turn is not a
+     * runId: a pause and its resume are one turn across two runs (`resume()`
+     * builds a fresh executor with a fresh id). Filtering on the id would leave
+     * every session a paused turn had opened alive forever — the failure would
+     * look like nothing at all, because the run answered fine.
+     *
+     * Firing all of them is exactly right under the runner's own
+     * ONE-IN-FLIGHT-RUN-PER-AGENT invariant: at a terminal there is no other turn
+     * whose sessions these could be. An ABANDONED pause is the interesting case
+     * and it lands the right way round too — the next completed turn releases
+     * what the abandoned one left holding.
+     *
+     * Pass an id where a caller really does mean one specific run.
+     */
+    fireRun(runId?: string): Promise<void>;
+    /**
+     * Fire the `'session'` registrations for one hosting session — or, with no
+     * `sessionId`, every `'session'` registration there is.
+     *
+     * Answers how many it closed, so a composition root can log a number instead
+     * of hoping.
+     */
+    fireSession(sessionId?: string, reason?: TeardownReason): Promise<number>;
+    /** Fire EVERYTHING, whatever scope it asked for. The backstop. */
+    fireShutdown(): Promise<number>;
+    /**
+     * Sweep sessions nobody has touched for `idleMs`.
+     *
+     * LAZY, on the next tier interaction — never a timer. A library that installs
+     * an interval keeps the host process alive, which is the same reason
+     * `shutdownOn` refuses to grab signals unless asked.
+     */
+    sweepIdle(): void;
+    private evictOverflow;
+    /**
+     * The one firing implementation: select, claim (law 1), reverse (law 3),
+     * settle everything (law 5).
+     *
+     * Selection and claiming happen SYNCHRONOUSLY before the first `await`, so
+     * two overlapping fires — a shutdown racing an idle sweep — cannot both take
+     * the same registration.
+     */
+    private fire;
+    /** One cleanup, bounded, reported either way. Never rethrows. */
+    private run;
+}
+/** A teardown that outran its budget. Named so an alert can route on it. */
+export declare class ToolTeardownTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(what: string, timeoutMs: number);
+}
+//# sourceMappingURL=toolSessions.d.ts.map

package/dist/types/core/toolSessions.d.ts.map

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

package/dist/types/core/tools.d.ts

@@ -8,7 +8,9 @@
  */
 import type { LLMToolSchema } from '../adapters/types.js';
 import type { Credential, CredentialNeed, CredentialProvider } from '../identity/types.js';
+import type { MemoryIdentity } from '../memory/identity/types.js';
 import type { CheckInDemand } from './checkin.js';
+import type { TeardownOptions, TeardownScope } from './toolSessions.js';
 /**
  * One executable tool the Agent can call.
  *
@@ -79,6 +81,64 @@ export interface ToolExecutionContext {
     /** The credential resolved for this tool's declared `needs` (declare-and-push).
      *  Present only when the tool declared a need and it resolved successfully. */
     readonly credential?: Credential;
+    /**
+     * The run this call belongs to.
+     *
+     * **Absent when there is no run.** A call served over `mcpServe` is one call,
+     * not a turn in a conversation, and minting a synthetic run id there would
+     * fabricate a run that never existed. Branch on the absence.
+     */
+    readonly runId?: string;
+    /**
+     * The hosting conversation this run is bound to, when it is bound to one —
+     * `HostRequest.sessionId`, threaded through `agent.run({ sessionId })`.
+     *
+     * Never derived, never defaulted to `runId`, never the anonymous latch.
+     *
+     * **It is caller data, not identity.** Anyone who can reach the host can put
+     * any string here, including someone else's. Never key a live session on it
+     * alone — compose it with tenant and principal via {@link toolSessionKey}.
+     */
+    readonly sessionId?: string;
+    /**
+     * The identity the CALLER supplied — `run({ identity })`, the same tuple
+     * memory and the permission gate scope on.
+     *
+     * **Absent when the caller passed none.** Deliberately NOT the run's internal
+     * `runIdentity`, which is always populated (it defaults to
+     * `{ conversationId: '<runId>' }`): handing that to a tool would publish a
+     * synthesized conversation as if somebody had named one.
+     */
+    readonly identity?: MemoryIdentity;
+    /**
+     * Register cleanup for work THIS call started — a code-interpreter session, a
+     * browser context, a lease.
+     *
+     * The tool learns its isolation key at execute time and registers cleanup for
+     * exactly that key in the same breath; there is no other seam where both are
+     * in hand. Registering twice under one `(tool, scope, key)` is a no-op that
+     * keeps the FIRST cleanup (it holds the live handle) and refreshes liveness,
+     * so calling this on every execute is the intended shape for a reused
+     * session.
+     *
+     * Throws, naming the door, when `scope` is not in {@link teardownScopes} — a
+     * capability nobody implements is a promise the library cannot keep.
+     *
+     * @example a session that lives as long as the run
+     *   const key = toolSessionKey(ctx, 'run');
+     *   const session = await runner.start({ key });
+     *   ctx.onTeardown?.(() => session.stop(), { scope: 'run', key });
+     */
+    onTeardown?(cleanup: () => void | Promise<void>, options?: TeardownOptions): void;
+    /**
+     * Which teardown scopes this door can actually honour — `[]` means none ever
+     * fires here.
+     *
+     * A FACT to branch on, exactly like `hasCredentials`, rather than an
+     * `undefined` to optional-chain past: a tool that wants a run-scoped session
+     * needs to know it is talking to a door that has no runs BEFORE it opens one.
+     */
+    readonly teardownScopes?: readonly TeardownScope[];
 }
 /**
  * Internal: registry entry keyed by tool name.

package/dist/types/core/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/core/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC3F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD;;;;;;;GAOG;AACH,MAAM,WAAW,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO;IACtE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B;;sCAEkC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;IAChC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IACjC;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CAC7E;AAED,gDAAgD;AAChD,MAAM,WAAW,oBAAoB;IACnC,gFAAgF;IAChF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC;IACzC;2EACuE;IACvE,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC;mFAC+E;IAC/E,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB,CAAC,KAAK,EAAE,OAAO;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACzD;uEACmE;IACnE,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;IAChC;8DAC0D;IAC1D,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC;IACxC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CAC7E;AA+BD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,CAkBzE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAQzD;AAED,wBAAgB,UAAU,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,EAC3E,OAAO,EAAE,iBAAiB,CAAC,KAAK,EAAE,OAAO,CAAC,GACzC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CActB"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/core/tools.ts"],"names":[],"mappings":"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"}

package/dist/types/doors/providers.d.ts

@@ -11,6 +11,11 @@
  *                          plus the MCP client/server bridge.
  *   • Thinking handlers  — per-vendor parsing of extended-thinking blocks,
  *                          which is a provider concern wearing another hat.
+ *   • Code runners       — `localCodeRunner` (process isolation, on this
+ *                          machine, and it says so) and `agentCoreCodeRunner`
+ *                          (a real managed sandbox). Both are backends behind
+ *                          the `CodeRunner` port; `codeRunnerTool` on the main
+ *                          barrel is the tool that holds one.
  *
  * Each vendor SDK is lazy-required, so importing this door loads no vendor
  * code — only calling a factory does.
@@ -24,4 +29,6 @@ export * from '../llm-providers.js';
 export * from '../embedders/index.js';
 export * from '../tool-providers/index.js';
 export * from '../thinking/index.js';
+export { localCodeRunner, type LocalCodeRunnerOptions } from '../adapters/code/local.js';
+export { agentCoreCodeRunner, type AgentCoreCodeRunnerOptions, type AgentCoreCodeClientLike, type AgentCoreInvokeAnswer, type BedrockAgentCoreCodeSdkModule, } from '../adapters/code/agentcore.js';
 //# sourceMappingURL=providers.d.ts.map

package/dist/types/doors/providers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../../src/doors/providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../../src/doors/providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AAKrC,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACzF,OAAO,EACL,mBAAmB,EACnB,KAAK,0BAA0B,EAC/B,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,6BAA6B,GACnC,MAAM,+BAA+B,CAAC"}

package/dist/types/events/payloads.d.ts

@@ -624,6 +624,55 @@ export interface ToolsShadowedPayload {
     /** That source's id — the skill id, for the provider↔skill pair. */
     readonly dispatchToId?: string;
 }
+/** Shared shape of the four `tools.session_*` payloads. */
+interface ToolSessionPayloadBase {
+    /** The tool that registered the cleanup. */
+    readonly tool: string;
+    /** Which scope it asked for — how long it expected to live. */
+    readonly scope: 'call' | 'run' | 'session' | 'shutdown';
+    /** Digest of the isolation key. SHA-256 (12 hex chars) where `node:crypto`
+     *  resolves, FNV-1a in a browser bundle. NEVER the key. */
+    readonly keyHash: string;
+    /** The adapter holding the resource — `CodeRunner.id`, say. */
+    readonly runnerId?: string;
+    /** One fact the tool chose to state about what was opened (the language, the
+     *  browser profile). Never user data. */
+    readonly label?: string;
+}
+/** A tool opened something and registered its cleanup. */
+export type ToolsSessionStartedPayload = ToolSessionPayloadBase;
+/**
+ * A later call reused the session already held under this key.
+ *
+ * This is the payoff being measured: `calls` is how many dispatches have shared
+ * one start-up. It is also the liveness signal the idle sweep and the LRU bound
+ * read, which is why a tool re-registers on every execute rather than only once.
+ */
+export interface ToolsSessionReusedPayload extends ToolSessionPayloadBase {
+    /** How many calls have now shared this session, including this one. */
+    readonly calls: number;
+}
+/** The cleanup ran. `reason` says which firing site ran it. */
+export interface ToolsSessionClosedPayload extends ToolSessionPayloadBase {
+    readonly reason: 'call-end' | 'run-end' | 'session-end' | 'shutdown' | 'idle' | 'evicted';
+    /** Wall-clock from registration to close. */
+    readonly durationMs: number;
+}
+/**
+ * The cleanup threw, or outran `toolTeardownTimeoutMs`.
+ *
+ * Teardown never throws into the run — but it is never SILENT either, and this
+ * event is the difference. A vendor `Stop` that fails leaves a live sandbox
+ * somebody is still paying for; the run has no way to say so, so this does.
+ * `errorClass` mirrors `credential.failed`'s 9.4.0 addition: routable without
+ * parsing prose (`'ToolTeardownTimeoutError'` for the budget case).
+ */
+export interface ToolsSessionCloseFailedPayload extends ToolSessionPayloadBase {
+    readonly reason: 'call-end' | 'run-end' | 'session-end' | 'shutdown' | 'idle' | 'evicted';
+    readonly durationMs: number;
+    readonly error: string;
+    readonly errorClass?: string;
+}
 /**
  * Emitted when LLM-produced tool args fail validation against the tool's
  * declared `inputSchema` (backlog #9). Fires for BOTH modes that validate:
@@ -1117,4 +1166,5 @@ export interface AgentThinkingParseFailedPayload {
     readonly errorName: string;
     readonly iteration: number;
 }
+export {};
 //# sourceMappingURL=payloads.d.ts.map