agentfootprint 9.6.0 → 9.8.0

package/dist/esm/adapters/observability/file.js

@@ -0,0 +1,303 @@
+/**
+ * fileObservability — the typed event stream, one JSON line per event, in a
+ * local file.
+ *
+ * The sink for the shop that has no collector. Every other adapter in this
+ * folder ships somewhere: CloudWatch, X-Ray, an OTLP endpoint. A great many
+ * on-premises deployments have none of those — they have a directory, a log
+ * shipper (Filebeat, Fluent Bit, Vector, `promtail`, `journald`, or a person
+ * with `grep`), and a rule that nothing leaves the network. NDJSON on disk is
+ * the format all of those already read, so the sink is the file.
+ *
+ * Zero dependencies: `node:fs`, lazily required at construction so merely
+ * importing `agentfootprint/observe` stays browser-safe (this factory is
+ * Node-only; calling it in a browser throws by name).
+ *
+ * ## The line
+ *
+ * One `JSON.stringify(event)` per line, newline-terminated, appended in
+ * dispatch order — the SAME envelope `cloudwatchObservability` puts in a log
+ * event, so a query written against one reads the other:
+ *
+ * ```jsonl
+ * {"type":"agentfootprint.agent.turn_start","payload":{…},"meta":{"runId":"…","sessionId":"…"}}
+ * {"type":"agentfootprint.stream.tool_end","payload":{…},"meta":{…}}
+ * ```
+ *
+ * Nothing is summarized, bounded or redacted on the way out. **A payload that
+ * must not be on that disk must not reach this strategy** — narrow it with
+ * `eventTypes` / `tier` / `sampleRate`, or apply a footprintjs
+ * `RedactionPolicy` upstream, exactly as with every other sink. (For a bounded
+ * record by construction, `auditExport({ payloadMode: 'bounded' })` is the
+ * adapter that does that job.)
+ *
+ * ## Buffered, not synchronous
+ *
+ * `exportEvent` is sync and never touches the disk: it serializes, buffers, and
+ * returns. Batches are appended asynchronously on a size trigger
+ * (`maxBufferEvents` / `maxBufferBytes`), on a timer (`flushIntervalMs`), and on
+ * `flush()`. A hard kill therefore loses at most the buffer — the price of not
+ * making telemetry a term in agent-loop latency. Call `flush()` (or
+ * `agent.shutdown()`, which does) at process end; see the 8.12.0 lifecycle laws
+ * on {@link BaseStrategy.flush}.
+ *
+ * ## Rotation is ONE generation, and that is deliberate
+ *
+ * With `maxBytes` set, a batch that would push the file past the ceiling first
+ * renames it to `<path>.1` — **replacing any previous `.1`** — and starts a
+ * fresh file. That is the whole policy. There is no `.2`, no compression, no
+ * time-based schedule, no cross-process coordination (two processes writing one
+ * file each keep their own byte count and will both rotate it). It exists so an
+ * unattended agent cannot fill a disk, and for nothing else: **retention is a
+ * log-management daemon's job**, and `logrotate` with `copytruncate`, Fluent Bit,
+ * or a systemd timer will do it properly. Omit `maxBytes` — the default — and
+ * this adapter never renames anything, which is the right choice when a real
+ * rotator already owns the file.
+ *
+ * @example
+ * ```ts
+ * import { fileObservability } from 'agentfootprint/observe';
+ *
+ * const telemetry = agent.enable.observability({
+ *   strategy: fileObservability({
+ *     path: '/var/log/agentfootprint/events.ndjson',
+ *     maxBytes: 64 * 1024 * 1024,   // safety ceiling; logrotate owns retention
+ *   }),
+ * });
+ *
+ * // … run …
+ * await agent.shutdown();           // flushes + stops everything enabled
+ * ```
+ */
+import { lazyRequire } from '../../lib/lazyRequire.js';
+import { rateLimitedConsoleSink } from './deliveryErrors.js';
+// ─── Public factory ──────────────────────────────────────────────────
+/**
+ * NDJSON-to-a-local-file observability strategy. See
+ * {@link FileObservabilityOptions} for the per-option contract, and this
+ * module's docstring for the rotation policy and what is NOT bounded.
+ */
+export function fileObservability(opts) {
+    const strategyName = 'file';
+    if (!opts.path || typeof opts.path !== 'string' || opts.path.trim() === '') {
+        throw new TypeError(`[${strategyName}Observability] \`path\` is required — the file this sink writes. ` +
+            `Pass one, e.g. '/var/log/agentfootprint/events.ndjson'. There is no default: ` +
+            `where a run's telemetry lands on your disk is not a decision this library makes.`);
+    }
+    if (opts.maxBytes !== undefined && !(opts.maxBytes > 0)) {
+        throw new TypeError(`[${strategyName}Observability] \`maxBytes\` must be a positive number of bytes ` +
+            `(got ${String(opts.maxBytes)}). Omit it for no rotation at all, which is the ` +
+            `right choice when logrotate or a log shipper already owns '${opts.path}'.`);
+    }
+    const path = opts.path;
+    const rotatedPath = `${path}.1`;
+    const maxBufferEvents = opts.maxBufferEvents ?? 100;
+    const maxBufferBytes = opts.maxBufferBytes ?? 65_536;
+    const flushIntervalMs = opts.flushIntervalMs ?? 1000;
+    const fs = opts._fs ?? createNodeFileSink(strategyName);
+    // Claim the file NOW. Two things this buys, both worth the syscall:
+    //   1. an unwritable path (no directory, no permission, a directory where a
+    //      file should be, a read-only mount) is refused at construction, where
+    //      the caller can still read the message;
+    //   2. `statSync` below gives the rotation counter a true starting size, so a
+    //      restart appends to an existing file rather than believing it is empty.
+    let bytesOnDisk = 0;
+    try {
+        const dir = parentDir(path);
+        if (dir)
+            fs.mkdirSync(dir, { recursive: true });
+        fs.appendFileSync(path, '');
+        bytesOnDisk = fs.statSync(path).size;
+    }
+    catch (err) {
+        throw new Error(`[${strategyName}Observability] cannot write '${path}': ${errorMessage(err)}. ` +
+            `The parent directory is created for you; a failure here means the path is a ` +
+            `directory, the mount is read-only, or the process user lacks permission. ` +
+            `Fix the path or the permission — this sink refuses to start rather than ` +
+            `silently drop every event.`);
+    }
+    // Buffered lines — drained by `flush()` / size trigger / timer.
+    const buffer = [];
+    let bufferBytes = 0;
+    let lastFlushPromise = Promise.resolve();
+    let timer;
+    let stopped = false;
+    // The fallback when the consumer wires nothing. Rate-limited; a
+    // consumer-supplied sink is not.
+    const consoleSink = rateLimitedConsoleSink(strategyName);
+    function scheduleTimedFlush() {
+        if (timer || flushIntervalMs <= 0 || stopped)
+            return;
+        timer = setTimeout(() => {
+            timer = undefined;
+            void doFlush();
+        }, flushIntervalMs);
+        // Never hold the process open for telemetry. `unref` exists on Node's
+        // Timeout and not on the browser's number — feature-detected, so a
+        // non-Node runtime with an injected `_fs` still works.
+        timer.unref?.();
+    }
+    /** Route a delivery failure through whatever `_onError` IS RIGHT NOW —
+     *  reading it at call time, so a consumer who assigns `_onError` after
+     *  construction still receives them (the 8.11.0 fix). */
+    function reportFailure(err) {
+        strategy._onError?.(err);
+    }
+    /** ONE generation. A file already at or over the ceiling is renamed to
+     *  `<path>.1` (replacing any previous `.1`) and the counter resets. A batch
+     *  bigger than the whole ceiling is still written — truncating a run's
+     *  telemetry to fit a dial nobody set for that purpose would be worse. */
+    async function rotateIfNeeded(incomingBytes) {
+        const ceiling = opts.maxBytes;
+        if (ceiling === undefined)
+            return;
+        if (bytesOnDisk === 0)
+            return;
+        if (bytesOnDisk + incomingBytes <= ceiling)
+            return;
+        await fs.rename(path, rotatedPath);
+        bytesOnDisk = 0;
+    }
+    async function doFlush() {
+        // `stopped` is deliberately NOT a guard here — same stance as the AWS
+        // adapters since 8.11.1. `stop()` stops this strategy ACCEPTING events; it
+        // does not authorise throwing away events already accepted, and a `flush()`
+        // that cannot make progress after a `stop()` is how shutdown spins forever.
+        if (buffer.length === 0)
+            return;
+        // Snapshot + clear so events emitted during the in-flight write accumulate
+        // into the next batch.
+        const batch = buffer.splice(0);
+        const batchBytes = bufferBytes;
+        bufferBytes = 0;
+        const data = `${batch.join('\n')}\n`;
+        try {
+            await rotateIfNeeded(batchBytes);
+            await fs.appendFile(path, data);
+            bytesOnDisk += byteLength(data);
+        }
+        catch (err) {
+            reportFailure(new Error(`${batch.length} event(s) dropped writing to '${path}': ${errorMessage(err)}`));
+        }
+    }
+    function enqueue(event) {
+        if (stopped)
+            return;
+        // The hot path must not throw (port law). `JSON.stringify` can — a cycle, a
+        // BigInt, a throwing getter — and an event that cannot be serialized is a
+        // reportable fact, not a reason to break the agent loop.
+        let line;
+        try {
+            line = JSON.stringify(event);
+        }
+        catch (err) {
+            reportFailure(new Error(`event '${event?.type ?? 'unknown'}' could not be serialized: ` + errorMessage(err)));
+            return;
+        }
+        // `JSON.stringify` returns undefined for an undefined input — nothing to
+        // write, and a bare "undefined" line would corrupt the NDJSON stream.
+        if (line === undefined)
+            return;
+        buffer.push(line);
+        bufferBytes += byteLength(line) + 1; // + the newline this line will carry
+        if (buffer.length >= maxBufferEvents || bufferBytes >= maxBufferBytes) {
+            // Size trigger. Chain onto the last write rather than racing it — the
+            // file's line order IS the dispatch order, and that is the only thing an
+            // offline reader can rely on.
+            lastFlushPromise = lastFlushPromise.then(doFlush, doFlush);
+        }
+        else {
+            scheduleTimedFlush();
+        }
+    }
+    const strategy = {
+        name: strategyName,
+        capabilities: { events: true, logs: true },
+        ...(opts.eventTypes && { relevantEventTypes: opts.eventTypes }),
+        exportEvent: enqueue,
+        /**
+         * Write what is buffered. Called for you on shutdown (8.12.0) — by the
+         * handle `enable.observability()` returns, by `agent.shutdown()`, and by a
+         * `standingAgent` closing. Safe at any time, including after `stop()`.
+         */
+        async flush() {
+            // BOUNDED BY CONSTRUCTION — every pass must remove at least one buffered
+            // line; a pass that removes none ends the drain instead of retrying. The
+            // shape the CloudWatch adapter arrived at in 8.11.1, for the same reason:
+            // a drain that cannot finish must return, never spin.
+            for (;;) {
+                const pending = buffer.length;
+                lastFlushPromise = lastFlushPromise.then(doFlush, doFlush);
+                await lastFlushPromise;
+                if (buffer.length === 0)
+                    return;
+                if (buffer.length >= pending)
+                    return;
+            }
+        },
+        /** Clear the timer and stop accepting events. Terminal: there is no
+         *  restart. What it does NOT do is discard the buffer — `flush()` after
+         *  `stop()` still writes it. */
+        stop() {
+            stopped = true;
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+        },
+        /** Where failures go. Two callers: the dispatch layer (when `exportEvent`
+         *  itself throws) and this adapter's own write path. */
+        _onError(err, event) {
+            (opts.onError ?? consoleSink)(err, event);
+        },
+    };
+    return strategy;
+}
+// ─── node:fs binding (lazy) ──────────────────────────────────────────
+/**
+ * Bind {@link FileSinkFs} to `node:fs`. Lazily required so that importing
+ * `agentfootprint/observe` in a browser bundle never resolves `node:fs` — only
+ * CALLING this factory does, and a runtime without it is refused by name.
+ */
+function createNodeFileSink(strategyName) {
+    let mod;
+    try {
+        mod = lazyRequire('node:fs');
+    }
+    catch {
+        throw new Error(`[${strategyName}Observability] needs \`node:fs\`, and this runtime has none. ` +
+            `It is a Node-only sink by definition — a browser has no local file to append to. ` +
+            `In a browser, ship events over your own transport, or pass \`_fs\` to write ` +
+            `somewhere you control.`);
+    }
+    return {
+        mkdirSync: (dir, options) => void mod.mkdirSync(dir, options),
+        appendFileSync: (file, data) => mod.appendFileSync(file, data),
+        statSync: (file) => mod.statSync(file),
+        appendFile: (file, data) => mod.promises.appendFile(file, data),
+        rename: (from, to) => mod.promises.rename(from, to),
+    };
+}
+// ─── Small helpers ───────────────────────────────────────────────────
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** UTF-8 byte length. `Buffer` where there is one, `TextEncoder` otherwise —
+ *  the byte count decides rotation, so a multi-byte prompt must not be counted
+ *  as its character length. */
+function byteLength(s) {
+    const B = globalThis.Buffer;
+    if (B)
+        return B.byteLength(s, 'utf8');
+    return new TextEncoder().encode(s).length;
+}
+/** The directory part of a path, POSIX or Windows separators, or `''` for a
+ *  bare filename (nothing to create). Done by hand rather than through
+ *  `node:path` so the module has exactly one Node import, behind one seam. */
+function parentDir(file) {
+    const idx = Math.max(file.lastIndexOf('/'), file.lastIndexOf('\\'));
+    if (idx <= 0)
+        return '';
+    return file.slice(0, idx);
+}
+//# sourceMappingURL=file.js.map

package/dist/esm/adapters/observability/file.js.map

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

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

@@ -584,3 +584,90 @@ export interface PricingTable {
     /** USD per ONE token for the given model+kind. */
     pricePerToken(model: string, kind: TokenKind): number;
 }
+/**
+ * A service that runs code in an isolated session — a managed code
+ * interpreter, a container pool, a subprocess.
+ *
+ * **The shape is Start → Execute ×N → Stop**, because that is what every real
+ * one is, and the middle is the part a framework has to make possible. Paying
+ * session start-up on every call is the honest cheap version; holding the
+ * session in a module-level map is the fast version that hands one live sandbox
+ * to whoever calls next. `ctx.onTeardown` + {@link ToolExecutionContext.runId}
+ * are what let a tool do neither.
+ *
+ * ── Why this port exists at all: "summarize prose, compute data" ────────────
+ * A tool that returns 40MB of rows does not need a bigger context window; it
+ * needs to not put the rows in one. The motivating failure is a real production
+ * request of 879,073 tokens — a tool result pasted straight into the prompt.
+ * With a code runner, the model writes the aggregation, the RUNNER holds the
+ * data, and what comes back is the answer. Prose gets summarized; data gets
+ * computed. `CodeResult.truncated` exists so the second half of that promise
+ * cannot quietly break.
+ *
+ * Implement it for your own backend; ship it to `codeRunnerTool({ runner })`.
+ */
+export interface CodeRunner {
+    /** Stable id — reported on every `agentfootprint.tools.session_*` event so a
+     *  row names its backend, not just its tool. */
+    readonly id: string;
+    /**
+     * Open a session.
+     *
+     * `key` is the ISOLATION key the caller derived (see `toolSessionKey`). An
+     * adapter may use it to name the remote session; it must never widen it.
+     */
+    start(req: {
+        readonly key: string;
+        readonly language?: string;
+        readonly signal?: AbortSignal;
+    }): Promise<CodeSession>;
+}
+/** One live session. `stop()` is idempotent and tolerates "already gone". */
+export interface CodeSession {
+    /** The backend's own id for this session, when it has one. */
+    readonly id: string;
+    execute(req: {
+        readonly code: string;
+        readonly language?: string;
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<CodeResult>;
+    /**
+     * Release the session.
+     *
+     * Must tolerate a session the far side already reaped — an idle timeout is
+     * the reality on every managed backend, and a `Stop` on a dead session is a
+     * no-op, not an error.
+     */
+    stop(): Promise<void>;
+}
+/** What one execution produced. */
+export interface CodeResult {
+    /** Did the code run to completion without an error exit? */
+    readonly ok: boolean;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode?: number;
+    /** Files the run produced, described rather than inlined — the whole point is
+     *  that big data does not enter the window. */
+    readonly artifacts?: readonly {
+        readonly name: string;
+        readonly bytes: number;
+        readonly uri?: string;
+    }[];
+    /**
+     * Present IFF output was cut, and then it says by how much.
+     *
+     * Load-bearing, not politeness. A runner exists so big data is computed
+     * outside the context window instead of pasted into it; a runner that
+     * quietly slices its own output to fit is the same bug wearing a different
+     * hat, and the model would go on to reason over a truncated table it was
+     * never told was truncated. An unstated slice is a silent success.
+     */
+    readonly truncated?: {
+        readonly stdout?: boolean;
+        readonly stderr?: boolean;
+        /** The pre-truncation length, in characters, of whichever stream was cut. */
+        readonly ofChars?: number;
+    };
+}

package/dist/esm/core/Agent.d.ts

@@ -286,6 +286,9 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      *  default is derived from a runId, and storing that would pin a whole
      *  conversation to the id of the one run that started it. */
     private lastRunIdentity?;
+    /** How long ONE tool teardown may take before the runner stops waiting.
+     *  See `AgentOptions.toolTeardownTimeoutMs`. */
+    private readonly toolTeardownTimeoutMs;
     /** The run in flight, by id — the whole of the one-turn-at-a-time guard.
      *  Set before the executor is built and cleared in `finally`, so a run that
      *  throws does not leave the agent permanently refusing. */
@@ -611,6 +614,29 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      */
     private installCheckpointTracker;
     resume(checkpoint: FlowchartCheckpoint, input?: unknown, options?: AgentRunOptions): Promise<AgentOutput | RunnerPauseOutcome>;
+    /**
+     * Fire `'run'`-scoped tool teardown — IF this run really ended.
+     *
+     * **Not on `finally`, and that is the whole point.** `finally` runs on every
+     * exit including a pause, and a pause exits TWO ways: a returned
+     * `RunnerPauseOutcome` and a thrown `PauseSignal`. A check-in on a
+     * code-interpreter call pauses the run so a person can approve the code —
+     * tearing the sandbox down there destroys the exact state the resume needs,
+     * and it fails QUIETLY, as a resumed run that "just re-ran everything".
+     * Both shapes are discriminated here and both are skipped.
+     *
+     * An error IS a terminal: the run is over, nobody is coming back, and a
+     * sandbox held by a run that crashed is the clearest kind of leak. Only a
+     * pause survives.
+     *
+     * Fired for the TURN, not for `currentRunContext.runId` — `resume()` mints a
+     * fresh run id, so a pause and its resume are one turn across two runs, and
+     * filtering on the id would leave everything a paused turn opened alive
+     * forever. See `ToolSessionTier.fireRun`.
+     *
+     * @param outcome what `run()`/`resume()` is about to return, or about to throw.
+     */
+    private endRunToolSessions;
     /**
      * The conversation this agent's LAST completed run leaves behind, packed as
      * the same `AgentRunCheckpoint` that `resumeOnError(...)` accepts. Store it,
@@ -761,6 +787,45 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      * An open pick ACTIVATES but never moves the cursor — see the tool-calls gate.
      * Computed once per chart build; the injection list is fixed at construction.
      */
+    /**
+     * The identity facts this run hands `tool.execute` (9.7.0).
+     *
+     * Read through an ACCESSOR from the chart (see `ToolCallsHandlerDeps.currentRun`)
+     * because the chart is built once and this changes every run.
+     *
+     * `identity` is `lastRunIdentity` — what the CALLER passed — and deliberately
+     * NOT `scope.runIdentity`, which is always populated and defaults to
+     * `{ conversationId: '<runId>' }`. Handing a tool a synthesized conversation
+     * as "the identity" would let it key an isolated session on a fiction, and
+     * would make "absent" unrepresentable at exactly the layer that most needs to
+     * see it.
+     */
+    private toolRunFacts;
+    /**
+     * The teardown tier, built on FIRST registration.
+     *
+     * An agent whose tools never hold a session never allocates one, and its
+     * terminals stay a single `undefined` check.
+     */
+    private toolSessions;
+    /**
+     * Turn one TEARDOWN report into a typed `agentfootprint.tools.session_*` event.
+     *
+     * Only the two closing events come through here. A start and a reuse happen
+     * inside `tool.execute`, where the dispatch loop still holds the scope, so
+     * those ride the ordinary emit channel and carry the stage they really
+     * happened in. These two fire after the run's last stage committed, and this
+     * is the one place that has to answer "from where?" without a stage to point
+     * at.
+     *
+     * **Built with `buildEventMeta`, never `minimalMeta()`.** `minimalMeta()`
+     * hardcodes `runId: 'consumer-scope'`, and a teardown event stamped that way
+     * cannot be joined to the run that OPENED the session — the exact
+     * unjoinability 9.4.0 spent a release fixing for credential events. So the
+     * meta comes from `currentRunContext`, with a STATED pseudo-stage, the same
+     * move as the `'<stageId>#paused'` stamp at the pause boundary.
+     */
+    private emitToolSessionReport;
     private openSkillIds;
     /**
      * The per-iteration `read_skill` offer builder — or `undefined` to leave the tool