agentfootprint 9.6.0 → 9.7.0

package/dist/core/toolSessions.js

@@ -0,0 +1,396 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolTeardownTimeoutError = exports.ToolSessionTier = exports.TOOL_SESSION_MAX_LIVE = exports.TOOL_SESSION_IDLE_MS = exports.TOOL_TEARDOWN_TIMEOUT_MS = exports.hashSessionKey = exports.toolSessionKey = void 0;
+const fnv1a_js_1 = require("../lib/fnv1a.js");
+const lazyRequire_js_1 = require("../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 …");
+ */
+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;
+}
+exports.toolSessionKey = toolSessionKey;
+/**
+ * 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.
+ */
+function hashSessionKey(key) {
+    const crypto = loadCrypto();
+    if (crypto)
+        return crypto.createHash('sha256').update(key).digest('hex').slice(0, 12);
+    return (0, fnv1a_js_1.fnv1a)(key);
+}
+exports.hashSessionKey = hashSessionKey;
+let cryptoModule;
+function loadCrypto() {
+    if (cryptoModule !== undefined)
+        return cryptoModule ?? undefined;
+    try {
+        const mod = (0, lazyRequire_js_1.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. */
+exports.TOOL_TEARDOWN_TIMEOUT_MS = 5_000;
+/** A session untouched this long is swept on the tier's next interaction. */
+exports.TOOL_SESSION_IDLE_MS = 900_000;
+/** How many live registrations one tier holds before it evicts the coldest. */
+exports.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.
+ */
+class ToolSessionTier {
+    registrations = new Map();
+    timeoutMs;
+    idleMs;
+    maxLive;
+    report;
+    now;
+    seq = 0;
+    constructor(options = {}) {
+        this.timeoutMs = options.timeoutMs ?? exports.TOOL_TEARDOWN_TIMEOUT_MS;
+        this.idleMs = options.idleMs ?? exports.TOOL_SESSION_IDLE_MS;
+        this.maxLive = options.maxLive ?? exports.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 }),
+            });
+        }
+    }
+}
+exports.ToolSessionTier = ToolSessionTier;
+/** A teardown that outran its budget. Named so an alert can route on it. */
+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;
+    }
+}
+exports.ToolTeardownTimeoutError = ToolTeardownTimeoutError;
+/**
+ * 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/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/core/tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/core/tools.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH,6CAAwC;AA6GxC;;;;;;;;;;;;;;;;;;GAkBG;AACH;;;;;;;GAOG;AACH,MAAM,gBAAgB,GAAG,uBAAuB,CAAC;AAEjD;;;;;;GAMG;AACH,SAAgB,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;AAlBD,kDAkBC;AAED;;;;;;GAMG;AACH,SAAgB,qBAAqB,CAAC,IAAa;IACjD,IAAI,CAAC,IAAA,uBAAS,GAAE;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;AARD,sDAQC;AAED,SAAgB,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;AAhBD,gCAgBC"}
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/core/tools.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH,6CAAwC;AAoLxC;;;;;;;;;;;;;;;;;;GAkBG;AACH;;;;;;;GAOG;AACH,MAAM,gBAAgB,GAAG,uBAAuB,CAAC;AAEjD;;;;;;GAMG;AACH,SAAgB,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;AAlBD,kDAkBC;AAED;;;;;;GAMG;AACH,SAAgB,qBAAqB,CAAC,IAAa;IACjD,IAAI,CAAC,IAAA,uBAAS,GAAE;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;AARD,sDAQC;AAED,SAAgB,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;AAhBD,gCAgBC"}

package/dist/doors/providers.js

@@ -12,6 +12,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.
@@ -36,8 +41,16 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentCoreCodeRunner = exports.localCodeRunner = void 0;
 __exportStar(require("../llm-providers.js"), exports);
 __exportStar(require("../embedders/index.js"), exports);
 __exportStar(require("../tool-providers/index.js"), exports);
 __exportStar(require("../thinking/index.js"), exports);
+// 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.
+var local_js_1 = require("../adapters/code/local.js");
+Object.defineProperty(exports, "localCodeRunner", { enumerable: true, get: function () { return local_js_1.localCodeRunner; } });
+var agentcore_js_1 = require("../adapters/code/agentcore.js");
+Object.defineProperty(exports, "agentCoreCodeRunner", { enumerable: true, get: function () { return agentcore_js_1.agentCoreCodeRunner; } });
 //# sourceMappingURL=providers.js.map

package/dist/doors/providers.js.map

@@ -1 +1 @@
-{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../src/doors/providers.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;;;;;;;;;;;;;;AAEH,sDAAoC;AACpC,wDAAsC;AACtC,6DAA2C;AAC3C,uDAAqC"}
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../src/doors/providers.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;;;;;;;;;;;;;;;;AAEH,sDAAoC;AACpC,wDAAsC;AACtC,6DAA2C;AAC3C,uDAAqC;AAErC,6EAA6E;AAC7E,gFAAgF;AAChF,uBAAuB;AACvB,sDAAyF;AAAhF,2GAAA,eAAe,OAAA;AACxB,8DAMuC;AALrC,mHAAA,mBAAmB,OAAA"}

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

@@ -0,0 +1,133 @@
+/**
+ * agentCoreCodeRunner — AWS Bedrock AgentCore Code Interpreter behind the
+ * {@link CodeRunner} port (peer-dep `@aws-sdk/client-bedrock-agentcore`).
+ *
+ *   import { agentCoreCodeRunner } from 'agentfootprint/providers';
+ *   const runner = agentCoreCodeRunner({ region: 'us-east-1', identifier: 'aws.codeinterpreter.v1' });
+ *
+ * A REAL sandbox, which is the point: `localCodeRunner` gives you process
+ * isolation on your own machine and says so; this gives you a managed,
+ * network-and-filesystem-isolated environment, and the tool code is identical
+ * across the swap.
+ *
+ * ── The three operations, verified against the SDK ──────────────────────────
+ * Pinned in `test/adapters/aws/awsCommandPin.ts`, and verified against a real
+ * install of `@aws-sdk/client-bedrock-agentcore` 3.1108.0:
+ *
+ *   • `StartCodeInterpreterSessionCommand`
+ *       in  `{ codeInterpreterIdentifier, name?, sessionTimeoutSeconds? }`
+ *       out `{ codeInterpreterIdentifier, sessionId, createdAt }`
+ *   • `InvokeCodeInterpreterCommand`
+ *       in  `{ codeInterpreterIdentifier, sessionId, name: 'executeCode',
+ *              arguments: { code, language } }`
+ *       out `{ sessionId, stream }` — an **event stream**, not a body (below)
+ *   • `StopCodeInterpreterSessionCommand`
+ *       in  `{ codeInterpreterIdentifier, sessionId }`   ← the session ID, not a URI
+ *       out `{ codeInterpreterIdentifier, sessionId, lastUpdatedAt }`
+ *
+ * **`Invoke` answers with an `AsyncIterable`.** `InvokeCodeInterpreterResponse`
+ * is `{ sessionId?, stream?: AsyncIterable<CodeInterpreterStreamOutput> }`, and
+ * every member of that union is either `{ result }` or a modelled EXCEPTION —
+ * `accessDeniedException`, `throttlingException`, `validationException`, and
+ * four more. An adapter that read a `body` field would find `undefined` and
+ * report an empty success on every call, and one that iterated only for
+ * `result` would treat an AccessDenied as "the code printed nothing." So this
+ * drains the stream, raises the exception members BY NAME, and folds the
+ * result members into one `CodeResult`.
+ *
+ * The payload lands twice: `structuredContent` carries `{ stdout, stderr,
+ * exitCode, executionTime }` and `content[]` carries typed blocks. The
+ * structured half is preferred because it is typed; the text blocks are the
+ * fallback for a response that only filled the other one.
+ *
+ * ── 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 is command-based**: its prototype carries
+ * `send` and `destroy` and nothing else — verified again for this adapter
+ * (`BedrockAgentCoreClient.prototype.startCodeInterpreterSession` is
+ * `undefined`; the shortcut exists only on the aggregated `BedrockAgentCore`).
+ * Three adapters have shipped that bug in this package.
+ *
+ * ── Credentials ─────────────────────────────────────────────────────────────
+ * Standard AWS credential resolution (the SDK's own chain). A tool holding a
+ * long-lived session must NOT cache a `Credential` object from `ctx.credential`
+ * past the call that produced it — a session outliving a run outlives its
+ * token. Re-resolve per execute through `ctx.credentials`.
+ *
+ * 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 { CodeRunner } from '../types.js';
+export interface AgentCoreCodeRunnerOptions {
+    readonly region?: string;
+    /**
+     * The code-interpreter resource to run in — AWS's built-in
+     * (`'aws.codeinterpreter.v1'`) or your own custom interpreter's identifier.
+     */
+    readonly identifier: string;
+    /**
+     * Session TTL in seconds. AgentCore terminates the session past it regardless
+     * of activity. Service default 900 (15 min); max 28,800 (8 h).
+     *
+     * **This is why "already gone" is a normal outcome, not an incident**: the
+     * far side reaps on its own schedule, so a `Stop` may arrive after AWS has
+     * already collected the session. `stop()` treats that as done.
+     */
+    readonly sessionTimeoutSeconds?: number;
+    /** Default language when a call does not name one. `'python'` (the service
+     *  accepts `javascript`, `python`, `typescript`). */
+    readonly language?: string;
+    /** Per-stream output ceiling, in characters. Default 8000; anything cut is
+     *  REPORTED on `CodeResult.truncated`, never dropped quietly. */
+    readonly maxOutputChars?: number;
+    /** Stable id (default `'agentcore-code-runner'`). Rides the session events. */
+    readonly id?: string;
+    /** Test seam — inject a client implementing {@link AgentCoreCodeClientLike}.
+     *  Bypasses the SDK entirely; the field mapping below is then yours. */
+    readonly _client?: AgentCoreCodeClientLike;
+    /** @internal Test injection — the AWS SDK module, to exercise the real shim
+     *  (`send(new Command(...))`) with a fake SDK. */
+    readonly _sdk?: BedrockAgentCoreCodeSdkModule;
+}
+/** The operation-semantic surface this adapter calls. */
+export interface AgentCoreCodeClientLike {
+    startSession(input: {
+        readonly codeInterpreterIdentifier: string;
+        readonly name?: string;
+        readonly sessionTimeoutSeconds?: number;
+    }): Promise<{
+        readonly sessionId?: string;
+    }>;
+    invoke(input: {
+        readonly codeInterpreterIdentifier: string;
+        readonly sessionId: string;
+        readonly name: string;
+        readonly arguments: {
+            readonly code: string;
+            readonly language?: string;
+        };
+    }): Promise<AgentCoreInvokeAnswer>;
+    stopSession(input: {
+        readonly codeInterpreterIdentifier: string;
+        readonly sessionId: string;
+    }): Promise<void>;
+}
+/** What `invoke` reports back, already drained of its event stream. */
+export interface AgentCoreInvokeAnswer {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode?: number;
+    readonly isError?: boolean;
+}
+/** The slice of `@aws-sdk/client-bedrock-agentcore` this shim touches. */
+export interface BedrockAgentCoreCodeSdkModule {
+    readonly BedrockAgentCoreClient?: new (config: {
+        region?: string;
+    }) => {
+        send(cmd: unknown): Promise<unknown>;
+    };
+    readonly StartCodeInterpreterSessionCommand?: new (input: unknown) => unknown;
+    readonly InvokeCodeInterpreterCommand?: new (input: unknown) => unknown;
+    readonly StopCodeInterpreterSessionCommand?: new (input: unknown) => unknown;
+}
+export declare function agentCoreCodeRunner(options: AgentCoreCodeRunnerOptions): CodeRunner;