agentfootprint 9.6.0 → 9.7.0

package/dist/esm/core/toolSessions.js

@@ -0,0 +1,389 @@
+/**
+ * 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 { fnv1a } from '../lib/fnv1a.js';
+import { lazyRequire } from '../lib/lazyRequire.js';
+/**
+ * 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 function toolSessionKey(ctx, scope) {
+    if (scope === 'call')
+        return `c=${ctx.toolCallId}`;
+    if (scope === 'shutdown')
+        return undefined;
+    const tenant = ctx.identity?.tenant || '_';
+    const principal = ctx.identity?.principal || '_';
+    const prefix = `t=${tenant}/p=${principal}`;
+    if (scope === 'session') {
+        return ctx.sessionId ? `${prefix}/s=${ctx.sessionId}` : undefined;
+    }
+    return ctx.runId ? `${prefix}/r=${ctx.runId}` : 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 function hashSessionKey(key) {
+    const crypto = loadCrypto();
+    if (crypto)
+        return crypto.createHash('sha256').update(key).digest('hex').slice(0, 12);
+    return fnv1a(key);
+}
+let cryptoModule;
+function loadCrypto() {
+    if (cryptoModule !== undefined)
+        return cryptoModule ?? undefined;
+    try {
+        const mod = lazyRequire('node:crypto');
+        cryptoModule = typeof mod?.createHash === 'function' ? mod : null;
+    }
+    catch {
+        cryptoModule = null;
+    }
+    return cryptoModule ?? undefined;
+}
+/** Defaults, named so a test and a docstring cannot drift from the code. */
+export const TOOL_TEARDOWN_TIMEOUT_MS = 5_000;
+/** A session untouched this long is swept on the tier's next interaction. */
+export const TOOL_SESSION_IDLE_MS = 900_000;
+/** How many live registrations one tier holds before it evicts the coldest. */
+export const TOOL_SESSION_MAX_LIVE = 64;
+/**
+ * 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 class ToolSessionTier {
+    registrations = new Map();
+    timeoutMs;
+    idleMs;
+    maxLive;
+    report;
+    now;
+    seq = 0;
+    constructor(options = {}) {
+        this.timeoutMs = options.timeoutMs ?? TOOL_TEARDOWN_TIMEOUT_MS;
+        this.idleMs = options.idleMs ?? TOOL_SESSION_IDLE_MS;
+        this.maxLive = options.maxLive ?? TOOL_SESSION_MAX_LIVE;
+        this.report = options.report ?? (() => { });
+        this.now = options.now ?? (() => Date.now());
+    }
+    /** Live registrations. Diagnostics and tests. */
+    liveCount() {
+        return this.registrations.size;
+    }
+    /**
+     * 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.
+     */
+    async settled() {
+        while (this.background.size > 0) {
+            await Promise.allSettled([...this.background]);
+        }
+    }
+    /** Fires nobody is awaiting — see {@link settled}. */
+    background = new Set();
+    /** Start a detached fire and keep it joinable. */
+    detach(work) {
+        this.background.add(work);
+        void work.finally(() => this.background.delete(work));
+    }
+    /**
+     * 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, cleanup, options = {}) {
+        this.sweepIdle();
+        const scope = options.scope ?? 'run';
+        const key = options.key ?? `${scope}:${origin.tool}`;
+        const mapKey = `${origin.tool}${scope}${key}`;
+        const existing = this.registrations.get(mapKey);
+        if (existing) {
+            // First wins — it is the one holding the live handle. The repeat is what
+            // tells the sweep and the LRU that this session is still being used.
+            existing.touchedMs = this.now();
+            existing.calls += 1;
+            return { outcome: 'reused', keyHash: existing.keyHash, calls: existing.calls };
+        }
+        const nowMs = this.now();
+        const registration = {
+            id: ++this.seq,
+            tool: origin.tool,
+            scope,
+            key,
+            keyHash: hashSessionKey(key),
+            origin,
+            cleanup,
+            ...(options.runnerId !== undefined && { runnerId: options.runnerId }),
+            ...(options.label !== undefined && { label: options.label }),
+            startedMs: nowMs,
+            touchedMs: nowMs,
+            calls: 1,
+            fired: false,
+        };
+        this.registrations.set(mapKey, registration);
+        this.evictOverflow();
+        return { outcome: 'started', keyHash: registration.keyHash, calls: 1 };
+    }
+    /** Fire every `'call'` registration this tool call opened. */
+    fireCall(toolCallId) {
+        return this.fire((r) => r.scope === 'call' && r.origin.toolCallId === toolCallId, 'call-end').then(() => undefined);
+    }
+    /**
+     * 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) {
+        return this.fire((r) => r.scope === 'run' && (runId === undefined || r.origin.runId === runId), 'run-end').then(() => undefined);
+    }
+    /**
+     * 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, reason = 'session-end') {
+        return this.fire((r) => r.scope === 'session' && (sessionId === undefined || r.origin.sessionId === sessionId), reason);
+    }
+    /** Fire EVERYTHING, whatever scope it asked for. The backstop. */
+    fireShutdown() {
+        return this.fire(() => true, 'shutdown');
+    }
+    /**
+     * 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() {
+        if (this.registrations.size === 0)
+            return;
+        const cutoff = this.now() - this.idleMs;
+        const stale = [...this.registrations.values()].filter((r) => r.touchedMs <= cutoff);
+        if (stale.length === 0)
+            return;
+        this.detach(this.fire((r) => stale.includes(r), 'idle'));
+    }
+    evictOverflow() {
+        if (this.registrations.size <= this.maxLive)
+            return;
+        const surplus = this.registrations.size - this.maxLive;
+        const coldest = [...this.registrations.values()]
+            .sort((a, b) => a.touchedMs - b.touchedMs || a.id - b.id)
+            .slice(0, surplus);
+        this.detach(this.fire((r) => coldest.includes(r), 'evicted'));
+    }
+    /**
+     * 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.
+     */
+    async fire(match, reason) {
+        const claimed = [];
+        for (const [mapKey, registration] of this.registrations) {
+            if (registration.fired || !match(registration))
+                continue;
+            registration.fired = true;
+            this.registrations.delete(mapKey);
+            claimed.push(registration);
+        }
+        if (claimed.length === 0)
+            return 0;
+        claimed.sort((a, b) => b.id - a.id); // reverse registration order
+        await Promise.allSettled(claimed.map((registration) => this.run(registration, reason)));
+        return claimed.length;
+    }
+    /** One cleanup, bounded, reported either way. Never rethrows. */
+    async run(registration, reason) {
+        const startedAt = this.now();
+        const base = {
+            tool: registration.tool,
+            scope: registration.scope,
+            keyHash: registration.keyHash,
+            ...(registration.runnerId !== undefined && { runnerId: registration.runnerId }),
+            ...(registration.label !== undefined && { label: registration.label }),
+            reason,
+        };
+        try {
+            await withTimeout(async () => registration.cleanup(), this.timeoutMs, `${registration.tool} teardown`);
+            this.report({
+                ...base,
+                kind: 'closed',
+                durationMs: this.now() - startedAt,
+            });
+        }
+        catch (err) {
+            // Law 5: swallowed at the caller, never silent on the wire.
+            this.report({
+                ...base,
+                kind: 'close-failed',
+                durationMs: this.now() - startedAt,
+                error: err instanceof Error ? err.message : String(err),
+                ...(err instanceof Error && { errorClass: err.constructor?.name ?? err.name }),
+            });
+        }
+    }
+}
+/** A teardown that outran its budget. Named so an alert can route on it. */
+export class ToolTeardownTimeoutError extends Error {
+    timeoutMs;
+    constructor(what, timeoutMs) {
+        super(`${what} did not finish within ${timeoutMs}ms and was abandoned. The cleanup may still ` +
+            'be running; the runner stopped waiting so a shutdown cannot hang on a vendor call.');
+        this.name = 'ToolTeardownTimeoutError';
+        this.timeoutMs = timeoutMs;
+    }
+}
+/**
+ * Run `work`, giving up after `timeoutMs`.
+ *
+ * The abandoned promise is deliberately NOT cancelled — there is nothing to
+ * cancel a vendor's in-flight `Stop` with, and pretending otherwise would be
+ * worse than saying we stopped waiting. The timer is unref'd where the runtime
+ * allows it, so a pending teardown can never be the reason a process stays up.
+ */
+async function withTimeout(work, timeoutMs, what) {
+    let timer;
+    try {
+        await Promise.race([
+            work(),
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new ToolTeardownTimeoutError(what, timeoutMs)), timeoutMs);
+                timer.unref?.();
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=toolSessions.js.map

package/dist/esm/core/toolSessions.js.map

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

package/dist/esm/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/esm/core/tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../src/core/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AA6GxC;;;;;;;;;;;;;;;;;;GAkBG;AACH;;;;;;;GAOG;AACH,MAAM,gBAAgB,GAAG,uBAAuB,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAa;IAC/C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CACb,yDAAyD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAClF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,MAAM,MAAM,GACV,IAAI,CAAC,MAAM,GAAG,EAAE;YACd,CAAC,CAAC,SAAS,IAAI,CAAC,MAAM,iBAAiB;YACvC,CAAC,CAAC,mFAAmF,CAAC;QAC1F,MAAM,IAAI,KAAK,CACb,aAAa,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,MAAM,IAAI;YAC/C,sFAAsF;YACtF,wEAAwE;YACxE,0DAA0D,CAC7D,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAa;IACjD,IAAI,CAAC,SAAS,EAAE;QAAE,OAAO;IACzB,IAAI,CAAC;QACH,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,sCAAsC;QACtC,OAAO,CAAC,IAAI,CAAC,4BAA6B,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;IACnE,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CACxB,OAA0C;IAE1C,qBAAqB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO;QACL,MAAM,EAAE;YACN,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;SACvE;QACD,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QAC9C,uEAAuE;QACvE,2DAA2D;QAC3D,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,OAAwB,EAAE,CAAC;QACnF,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../src/core/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAoLxC;;;;;;;;;;;;;;;;;;GAkBG;AACH;;;;;;;GAOG;AACH,MAAM,gBAAgB,GAAG,uBAAuB,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAa;IAC/C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CACb,yDAAyD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAClF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,MAAM,MAAM,GACV,IAAI,CAAC,MAAM,GAAG,EAAE;YACd,CAAC,CAAC,SAAS,IAAI,CAAC,MAAM,iBAAiB;YACvC,CAAC,CAAC,mFAAmF,CAAC;QAC1F,MAAM,IAAI,KAAK,CACb,aAAa,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,MAAM,IAAI;YAC/C,sFAAsF;YACtF,wEAAwE;YACxE,0DAA0D,CAC7D,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAa;IACjD,IAAI,CAAC,SAAS,EAAE;QAAE,OAAO;IACzB,IAAI,CAAC;QACH,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,sCAAsC;QACtC,OAAO,CAAC,IAAI,CAAC,4BAA6B,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;IACnE,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CACxB,OAA0C;IAE1C,qBAAqB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO;QACL,MAAM,EAAE;YACN,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;SACvE;QACD,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QAC9C,uEAAuE;QACvE,2DAA2D;QAC3D,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,OAAwB,EAAE,CAAC;QACnF,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC;AACJ,CAAC"}

package/dist/esm/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,3 +29,5 @@ 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';

package/dist/esm/doors/providers.js

@@ -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,9 @@ export * from '../llm-providers.js';
 export * from '../embedders/index.js';
 export * from '../tool-providers/index.js';
 export * from '../thinking/index.js';
+// Code runners — the backends behind the `CodeRunner` port (9.7.0). The port
+// types themselves live on the main barrel with `codeRunnerTool`, alongside the
+// other adapter ports.
+export { localCodeRunner } from '../adapters/code/local.js';
+export { agentCoreCodeRunner, } from '../adapters/code/agentcore.js';
 //# sourceMappingURL=providers.js.map

package/dist/esm/doors/providers.js.map

@@ -1 +1 @@
-{"version":3,"file":"providers.js","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.js","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;AAErC,6EAA6E;AAC7E,gFAAgF;AAChF,uBAAuB;AACvB,OAAO,EAAE,eAAe,EAA+B,MAAM,2BAA2B,CAAC;AACzF,OAAO,EACL,mBAAmB,GAKpB,MAAM,+BAA+B,CAAC"}

package/dist/esm/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,3 +1166,4 @@ export interface AgentThinkingParseFailedPayload {
     readonly errorName: string;
     readonly iteration: number;
 }
+export {};

package/dist/esm/events/registry.d.ts

@@ -16,7 +16,7 @@
  * major bump. See agentfootprint_v2_detailed_design.md for rules.
  */
 import type { AgentfootprintEventEnvelope } from './types.js';
-import type { AgentHandoffPayload, AgentIterationEndPayload, AgentIterationStartPayload, AgentRouteDecidedPayload, AgentTurnEndPayload, AgentTurnStartPayload, CompositionEnterPayload, CompositionExitPayload, ConditionalRouteDecidedPayload, ContextBudgetPressurePayload, ContextEvaluatedPayload, ContextEvictedPayload, ContextInjectedPayload, ContextSlotComposedPayload, CostLimitHitPayload, CostTickPayload, EmbeddingGeneratedPayload, ErrorFatalPayload, ErrorRecoveredPayload, ErrorRetriedPayload, EvalScorePayload, EvalThresholdCrossedPayload, AgentOutputSchemaValidationFailedPayload, AgentOutputContractUnmetPayload, AgentOutputSchemaRetryPayload, AgentThinkingParseFailedPayload, StreamThinkingDeltaPayload, StreamThinkingEndPayload, FallbackTriggeredPayload, LLMEndPayload, LLMStartPayload, LLMTokenPayload, LoopIterationExitPayload, LoopIterationStartPayload, MemoryAttachedPayload, MemoryDetachedPayload, MemoryRetrievedPayload, MemoryStrategyAppliedPayload, MemoryWrittenPayload, ParallelBranchCompletePayload, ParallelForkStartPayload, ParallelMergeEndPayload, PauseRequestPayload, PauseResumePayload, CheckInRequestPayload, CheckInDecisionPayload, PermissionCheckPayload, PermissionGateClosedPayload, PermissionHaltPayload, PermissionGateOpenedPayload, CredentialRequestedPayload, CredentialAcquiredPayload, CredentialAuthorizationRequiredPayload, CredentialFailedPayload, ReliabilityFailFastPayload, ReliabilityRetriedPayload, ReliabilityRecoveredPayload, RiskFlaggedPayload, SkillActivatedPayload, SkillDeactivatedPayload, SkillRejectedPayload, SkillRerouteSupersededPayload, ToolEndPayload, ToolsActivatedPayload, ToolsDeactivatedPayload, ToolsDiscoveryStartedPayload, ToolsDiscoveryCompletedPayload, ToolsDiscoveryFailedPayload, ToolsShadowedPayload, ToolsOfferedPayload, ToolStartPayload, ValidationArgsInvalidPayload, MiddlewareDecisionPayload } from './payloads.js';
+import type { AgentHandoffPayload, AgentIterationEndPayload, AgentIterationStartPayload, AgentRouteDecidedPayload, AgentTurnEndPayload, AgentTurnStartPayload, CompositionEnterPayload, CompositionExitPayload, ConditionalRouteDecidedPayload, ContextBudgetPressurePayload, ContextEvaluatedPayload, ContextEvictedPayload, ContextInjectedPayload, ContextSlotComposedPayload, CostLimitHitPayload, CostTickPayload, EmbeddingGeneratedPayload, ErrorFatalPayload, ErrorRecoveredPayload, ErrorRetriedPayload, EvalScorePayload, EvalThresholdCrossedPayload, AgentOutputSchemaValidationFailedPayload, AgentOutputContractUnmetPayload, AgentOutputSchemaRetryPayload, AgentThinkingParseFailedPayload, StreamThinkingDeltaPayload, StreamThinkingEndPayload, FallbackTriggeredPayload, LLMEndPayload, LLMStartPayload, LLMTokenPayload, LoopIterationExitPayload, LoopIterationStartPayload, MemoryAttachedPayload, MemoryDetachedPayload, MemoryRetrievedPayload, MemoryStrategyAppliedPayload, MemoryWrittenPayload, ParallelBranchCompletePayload, ParallelForkStartPayload, ParallelMergeEndPayload, PauseRequestPayload, PauseResumePayload, CheckInRequestPayload, CheckInDecisionPayload, PermissionCheckPayload, PermissionGateClosedPayload, PermissionHaltPayload, PermissionGateOpenedPayload, CredentialRequestedPayload, CredentialAcquiredPayload, CredentialAuthorizationRequiredPayload, CredentialFailedPayload, ReliabilityFailFastPayload, ReliabilityRetriedPayload, ReliabilityRecoveredPayload, RiskFlaggedPayload, SkillActivatedPayload, SkillDeactivatedPayload, SkillRejectedPayload, SkillRerouteSupersededPayload, ToolEndPayload, ToolsActivatedPayload, ToolsDeactivatedPayload, ToolsDiscoveryStartedPayload, ToolsDiscoveryCompletedPayload, ToolsDiscoveryFailedPayload, ToolsShadowedPayload, ToolsSessionStartedPayload, ToolsSessionReusedPayload, ToolsSessionClosedPayload, ToolsSessionCloseFailedPayload, ToolsOfferedPayload, ToolStartPayload, ValidationArgsInvalidPayload, MiddlewareDecisionPayload } from './payloads.js';
 export declare const EVENT_NAMES: {
     readonly composition: {
         readonly enter: "agentfootprint.composition.enter";
@@ -71,6 +71,10 @@ export declare const EVENT_NAMES: {
         readonly discoveryCompleted: "agentfootprint.tools.discovery_completed";
         readonly discoveryFailed: "agentfootprint.tools.discovery_failed";
         readonly shadowed: "agentfootprint.tools.shadowed";
+        readonly sessionStarted: "agentfootprint.tools.session_started";
+        readonly sessionReused: "agentfootprint.tools.session_reused";
+        readonly sessionClosed: "agentfootprint.tools.session_closed";
+        readonly sessionCloseFailed: "agentfootprint.tools.session_close_failed";
     };
     readonly skill: {
         readonly activated: "agentfootprint.skill.activated";
@@ -175,6 +179,10 @@ export interface AgentfootprintEventMap {
     'agentfootprint.tools.discovery_completed': AgentfootprintEventEnvelope<'agentfootprint.tools.discovery_completed', ToolsDiscoveryCompletedPayload>;
     'agentfootprint.tools.discovery_failed': AgentfootprintEventEnvelope<'agentfootprint.tools.discovery_failed', ToolsDiscoveryFailedPayload>;
     'agentfootprint.tools.shadowed': AgentfootprintEventEnvelope<'agentfootprint.tools.shadowed', ToolsShadowedPayload>;
+    'agentfootprint.tools.session_started': AgentfootprintEventEnvelope<'agentfootprint.tools.session_started', ToolsSessionStartedPayload>;
+    'agentfootprint.tools.session_reused': AgentfootprintEventEnvelope<'agentfootprint.tools.session_reused', ToolsSessionReusedPayload>;
+    'agentfootprint.tools.session_closed': AgentfootprintEventEnvelope<'agentfootprint.tools.session_closed', ToolsSessionClosedPayload>;
+    'agentfootprint.tools.session_close_failed': AgentfootprintEventEnvelope<'agentfootprint.tools.session_close_failed', ToolsSessionCloseFailedPayload>;
     'agentfootprint.skill.activated': AgentfootprintEventEnvelope<'agentfootprint.skill.activated', SkillActivatedPayload>;
     'agentfootprint.skill.deactivated': AgentfootprintEventEnvelope<'agentfootprint.skill.deactivated', SkillDeactivatedPayload>;
     'agentfootprint.skill.rejected': AgentfootprintEventEnvelope<'agentfootprint.skill.rejected', SkillRejectedPayload>;

package/dist/esm/events/registry.js

@@ -72,6 +72,10 @@ export const EVENT_NAMES = {
         discoveryCompleted: 'agentfootprint.tools.discovery_completed',
         discoveryFailed: 'agentfootprint.tools.discovery_failed',
         shadowed: 'agentfootprint.tools.shadowed',
+        sessionStarted: 'agentfootprint.tools.session_started',
+        sessionReused: 'agentfootprint.tools.session_reused',
+        sessionClosed: 'agentfootprint.tools.session_closed',
+        sessionCloseFailed: 'agentfootprint.tools.session_close_failed',
     },
     skill: {
         activated: 'agentfootprint.skill.activated',
@@ -180,6 +184,10 @@ export const ALL_EVENT_TYPES = [
     'agentfootprint.tools.discovery_completed',
     'agentfootprint.tools.discovery_failed',
     'agentfootprint.tools.shadowed',
+    'agentfootprint.tools.session_started',
+    'agentfootprint.tools.session_reused',
+    'agentfootprint.tools.session_closed',
+    'agentfootprint.tools.session_close_failed',
     'agentfootprint.validation.args_invalid',
     'agentfootprint.skill.activated',
     'agentfootprint.skill.deactivated',