agentfootprint 7.14.0 → 7.16.0

package/dist/core/agent/compaction/turns.js

@@ -0,0 +1,153 @@
+"use strict";
+/**
+ * compaction/turns — where a turn boundary is, and which turns may fold.
+ *
+ * Pattern: Pure functions over the window (no scope, no I/O, no clock).
+ * Role:    core/ layer. The whole safety argument of compaction lives here:
+ *          a fold that splits an assistant's `tool_use` from its
+ *          `tool_result` produces a request the vendor rejects, and a fold
+ *          that swallows an unanswered question destroys the referent of the
+ *          answer that has not arrived yet.
+ * Emits:   N/A.
+ *
+ * Testable on its own — see `test/core/agent/compaction-turns.test.ts`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.windowChars = exports.planFold = exports.refusalFor = exports.answeredCallIds = exports.segmentTurns = void 0;
+/**
+ * Segment a window into turns.
+ *
+ * A new turn starts at any non-`tool` message; `tool` messages join the turn
+ * in progress. A leading `tool` message (only reachable from a hand-built
+ * history) starts its own turn rather than being silently dropped.
+ */
+function segmentTurns(history) {
+    const turns = [];
+    let current = [];
+    let start = 0;
+    const flush = () => {
+        if (current.length === 0)
+            return;
+        turns.push({ index: turns.length, start, length: current.length, messages: current });
+        current = [];
+    };
+    for (let i = 0; i < history.length; i++) {
+        const msg = history[i];
+        if (msg.role !== 'tool' || current.length === 0) {
+            flush();
+            start = i;
+        }
+        current.push(msg);
+    }
+    flush();
+    return turns;
+}
+exports.segmentTurns = segmentTurns;
+/** Every tool_call id that has a matching `role: 'tool'` message. */
+function answeredCallIds(history) {
+    const answered = new Set();
+    for (const msg of history) {
+        if (msg.role === 'tool' && msg.toolCallId)
+            answered.add(msg.toolCallId);
+    }
+    return answered;
+}
+exports.answeredCallIds = answeredCallIds;
+/**
+ * Why this turn may NOT fold, or `undefined` when it may.
+ *
+ * Order matters only for which reason gets reported first; every check is
+ * independent. `paused-tool` / `pending-check-in` are separated from
+ * `unresolved-tool-call` on purpose: they are the same shape but a different
+ * fact about the world, and "we are waiting on a human" is what the person
+ * reading the trace needs to see.
+ */
+function refusalFor(turn, ctx) {
+    for (const msg of turn.messages) {
+        if (msg.role === 'system')
+            return 'system-envelope';
+    }
+    const paused = ctx.pausedToolCallId;
+    if (paused !== undefined && paused.length > 0) {
+        for (const msg of turn.messages) {
+            const holdsPaused = msg.toolCallId === paused || (msg.toolCalls ?? []).some((tc) => tc.id === paused);
+            if (holdsPaused)
+                return ctx.pausedCheckIn === true ? 'pending-check-in' : 'paused-tool';
+        }
+    }
+    for (const msg of turn.messages) {
+        for (const call of msg.toolCalls ?? []) {
+            if (!ctx.answeredCallIds.has(call.id))
+                return 'unresolved-tool-call';
+        }
+    }
+    return undefined;
+}
+exports.refusalFor = refusalFor;
+/**
+ * Choose the fold span: the LONGEST CONTIGUOUS run of foldable candidate
+ * turns, starting at the oldest foldable one.
+ *
+ * Contiguity is not fussiness — it is what keeps the conversation in order.
+ * A fold replaces its span with ONE summary message; if the span skipped over
+ * an unfoldable turn, that turn would end up after a summary of things that
+ * happened before it. So an unfoldable turn at the front is stepped over (the
+ * fold "takes the next oldest instead") and an unfoldable turn in the middle
+ * ends the span. Everything not folded keeps its position.
+ *
+ * @param turns         the window's turn segmentation
+ * @param keepRecent    how many trailing turns are off-limits
+ * @param ctx           foldability inputs
+ * @param isSummaryTurn true for a turn that is a summary a prior fold wrote
+ */
+function planFold(turns, keepRecent, ctx, isSummaryTurn) {
+    const refusals = [];
+    const candidateCount = Math.max(0, turns.length - keepRecent);
+    for (let i = candidateCount; i < turns.length; i++) {
+        const turn = turns[i];
+        refusals.push({ reason: 'inside-keep-window', turnIndex: i, messageIndex: turn.start });
+    }
+    if (candidateCount === 0)
+        return { from: -1, to: -1, refusals };
+    const before = [];
+    let from = -1;
+    let to = -1;
+    for (let i = 0; i < candidateCount; i++) {
+        const turn = turns[i];
+        const reason = refusalFor(turn, ctx);
+        if (reason === undefined) {
+            if (from === -1)
+                from = i;
+            to = i;
+            continue;
+        }
+        before.push({ reason, turnIndex: i, messageIndex: turn.start });
+        if (from !== -1)
+            break; // an unfoldable turn ENDS the span
+    }
+    // A span that is nothing but one existing summary is not worth a call:
+    // re-summarizing a summary spends tokens to lose detail and names nothing
+    // new. It becomes foldable again as soon as a real turn joins it.
+    if (from !== -1 && from === to && isSummaryTurn(turns[from])) {
+        return {
+            from: -1,
+            to: -1,
+            refusals: [
+                ...before,
+                { reason: 'only-existing-summary', turnIndex: from, messageIndex: turns[from].start },
+                ...refusals,
+            ],
+        };
+    }
+    return { from, to, refusals: [...before, ...refusals] };
+}
+exports.planFold = planFold;
+/** Total characters of message content in a window. Exact; not tokens. */
+function windowChars(history) {
+    let total = 0;
+    for (const msg of history)
+        total += msg.content.length;
+    return total;
+}
+exports.windowChars = windowChars;
+//# sourceMappingURL=turns.js.map

package/dist/core/agent/compaction/turns.js.map

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

package/dist/core/agent/compaction/types.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * compaction/types — the public shape of `.compaction()` and the record it
+ * writes into the ledger.
+ *
+ * Pattern: Value objects (no behavior) + one resolved-config type.
+ * Role:    core/ layer. The law this feature exists to keep is stated once,
+ *          here, because every other file in this folder implements a piece
+ *          of it: **compaction edits the WINDOW, never the LEDGER.**
+ * Emits:   N/A (types only).
+ *
+ * The window is `scope.history` — the array `call-llm` hands the provider.
+ * The ledger is footprintjs's commit log, which is append-only: the turns a
+ * fold removes from the window were committed by `seed#0` / `tool-calls#N`
+ * BEFORE the fold and stay in those bundles byte-identical forever. A fold
+ * therefore cannot destroy history even in principle; it can only stop
+ * re-sending it. The summary is a CLAIM about the past, so it is filed as a
+ * claim — its own recorded step, naming every `runtimeStageId` it folded.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/core/agent/compaction/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/core/agent/compaction/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/core/agent/stages/compact.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * compact — the loop-head stage that keeps the window inside budget.
+ *
+ * Reads the last call's ADAPTER-REPORTED input tokens from the compaction
+ * meter and, when they exceed `thresholdTokens`, hands the window to a window
+ * strategy. Runs once per ReAct iteration boundary, as the loop target, so
+ * everything downstream in the turn — the injection engine's triggers, all
+ * three context slots, and the wire itself — sees ONE window. No component
+ * gets a different past than the model does.
+ *
+ * The law: **it edits the window, never the ledger.** The turns a fold removes
+ * were committed by `seed#0` / `tool-calls#N` before this stage ran and stay
+ * in those bundles byte-identical; footprintjs's commit log is append-only, so
+ * a fold cannot erase history even in principle. What it can do is stop
+ * re-sending it — and say so, in its own commit, naming every runtimeStageId
+ * it folded. A compacted run is still a provable run.
+ *
+ * This file is deliberately all WIRING. The decision — what the window should
+ * become — lives behind `WindowStrategy` (compaction/strategy.ts, internal),
+ * so the duty to record, emit and cost what happened stays in exactly one
+ * place instead of being re-implemented per strategy. `.compaction()` is the
+ * only strategy that ships.
+ *
+ * Emits (existing vocabulary only — no new event types):
+ *   agentfootprint.context.evicted          — one per message leaving the window
+ *   agentfootprint.context.budget_pressure  — one per over-budget visit
+ *   agentfootprint.cost.tick                — when a pricingTable is set: the
+ *                                             summarizer's call is a real
+ *                                             billed call and counts
+ *
+ * The summarizer call is deliberately NOT bracketed with
+ * `stream.llm_start` / `llm_end`: those carry an `iteration` and every
+ * consumer pairs them by it, so a second bracket inside one iteration would
+ * corrupt the pairing. Its cost rides the cost channel and its tokens are
+ * recorded in the commit instead.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCompactStage = void 0;
+const typedEmit_js_1 = require("../../../recorders/core/typedEmit.js");
+const helpers_js_1 = require("../../slots/helpers.js");
+const cost_js_1 = require("../../cost.js");
+const errors_js_1 = require("../compaction/errors.js");
+const strategy_js_1 = require("../compaction/strategy.js");
+const turns_js_1 = require("../compaction/turns.js");
+/** Build the compaction stage function. */
+function buildCompactStage(deps) {
+    const { config, meter } = deps;
+    const now = deps.now ?? (() => Date.now());
+    const strategy = (0, strategy_js_1.summarizeOldestStrategy)(config, deps.defaultModel);
+    // Dedup latch for the strategy's warning: a summarizer that is down is down
+    // for the whole run, and one warning is a warning while ten is noise.
+    let warned = false;
+    return async (scope) => {
+        const metered = meter.lastCall();
+        // Iteration 1: nothing has been sent, so nothing has been counted. A
+        // compactor that acted here would be guessing, which is the one thing
+        // this feature refuses to do.
+        if (metered === undefined)
+            return;
+        if (metered.input === 0 && metered.output === 0) {
+            throw new errors_js_1.CompactionUnmeasurableError(deps.providerName);
+        }
+        if (metered.input <= config.thresholdTokens)
+            return;
+        // ── Over budget. Ask the strategy what the window should become. ──
+        const history = (scope.history ?? []).slice();
+        const pausedToolCallId = scope.pausedToolCallId;
+        const foldability = {
+            answeredCallIds: (0, turns_js_1.answeredCallIds)(history),
+            ...(pausedToolCallId !== undefined && { pausedToolCallId }),
+            ...(scope.pausedCheckIn === true && { pausedCheckIn: true }),
+        };
+        const result = await strategy.plan({
+            history,
+            turns: (0, turns_js_1.segmentTurns)(history),
+            origins: meter.origins(),
+            measuredTokens: metered.input,
+            foldability,
+            iteration: scope.iteration ?? 1,
+            signal: scope.$getEnv?.()?.signal,
+            now,
+        });
+        // ── Apply. The stage owns every side effect. ─────────────────────
+        if (result.window !== undefined && result.rebase !== undefined) {
+            // Tell the meter before writing: the fold is the one window shape it
+            // cannot infer (the set trap JSON-round-trips every write).
+            meter.rebaseForFold(result.rebase.headCount, result.rebase.keptTailCount, now());
+            scope.history = result.window;
+        }
+        const prior = scope.compactions ?? [];
+        scope.compactions = [...prior, result.record];
+        // One eviction per message that left, in the slot vocabulary consumers
+        // already subscribe to. The hash uses the SAME formula the messages slot
+        // used to report the piece as injected, so evicted and injected refer to
+        // the same piece by the same name.
+        for (const eviction of result.evictions) {
+            const msg = history[eviction.index];
+            if (msg === undefined)
+                continue;
+            (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.context.evicted', {
+                slot: 'messages',
+                contentHash: (0, helpers_js_1.fnv1a)(`${msg.role}:${eviction.index}:${msg.content}`),
+                reason: 'budget',
+                survivalMs: eviction.survivalMs,
+            });
+        }
+        // `capTokens` / `projectedTokens` are the historical names on
+        // `BudgetPressureRecord`; the slots measure them in chars, and this
+        // measures them in the tokens the decision was actually made on.
+        (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.context.budget_pressure', {
+            slot: 'messages',
+            capTokens: config.thresholdTokens,
+            projectedTokens: metered.input,
+            overflowBy: Math.max(0, metered.input - config.thresholdTokens),
+            planAction: result.planAction,
+        });
+        // A summarizer call is real money. It counts against the same budget.
+        if (result.spend !== undefined) {
+            (0, cost_js_1.emitCostTick)(scope, deps.pricingTable, deps.costBudget, result.spend.model, result.spend.usage);
+        }
+        if (result.warning !== undefined && !warned) {
+            warned = true;
+            // eslint-disable-next-line no-console
+            console.warn(`[agentfootprint compaction] ${result.warning}`);
+        }
+    };
+}
+exports.buildCompactStage = buildCompactStage;
+//# sourceMappingURL=compact.js.map

package/dist/core/agent/stages/compact.js.map

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

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

@@ -0,0 +1,199 @@
+/**
+ * adapters/hosting/agentcore — AWS Bedrock **AgentCore Runtime** adapters for
+ * the two hosting ports.
+ *
+ *   import { agentCoreRuntimeHost, agentCoreSessions } from 'agentfootprint/hosting-providers';
+ *   import { standingAgent } from 'agentfootprint/hosting';
+ *
+ *   const handle = await standingAgent({
+ *     agent,
+ *     host: agentCoreRuntimeHost(),
+ *     sessions: agentCoreSessions({ store: 'session-storage' }),
+ *   });
+ *
+ * ── What this file actually is ───────────────────────────────────────────────
+ * Vendor paths, a header name, and two JSON body shapes. That is the whole
+ * adapter, and it is the claim the hosting ports were designed to make: a
+ * container runtime's contract is a CONFIGURATION of HTTP work that already
+ * exists, not a second implementation of it. Nothing here reaches into the
+ * ports, and nothing here needed the ports to change.
+ *
+ * AgentCore Runtime is a **container contract**: an ARM64 image serving HTTP on
+ * `0.0.0.0:8080` —
+ *
+ *   POST /invocations   JSON `{ "prompt": "..." }` → JSON `{ "response", "status" }`
+ *   GET  /ping          → `{ "status": "Healthy", "time_of_last_update": <unix seconds> }`
+ *
+ * and the caller's conversation arrives in the
+ * `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header rather than in the body,
+ * which is the one thing paths-and-bodies configuration alone could not
+ * express before this release.
+ *
+ * ── Verification status, stated plainly ──────────────────────────────────────
+ * `agentCoreRuntimeHost` is **plain HTTP and is really verified**: it runs the
+ * same host conformance suite as `nodeHost`, over a real socket, in
+ * `test/hosting/host-contract.test.ts`. There is no AWS SDK on its path.
+ *
+ * `agentCoreSessions({ store: 'memory' })` is **contract-mapped and
+ * injection-tested**: its AgentCore Memory calls are exercised through the
+ * `_client` seam, never against AWS. Confirm the command and field names
+ * against your installed `@aws-sdk/client-bedrock-agentcore` before you rely
+ * on it; real-cloud verification lands with a field deployment.
+ *
+ * Pattern: Adapter (GoF). Role: outer ring. The file-backed session store uses
+ * `node:fs` and nothing else; the event-backed one lazy-loads the AWS SDK, so
+ * importing this module costs zero peer-dep load.
+ */
+import type { HttpHost, HttpWire } from '../../hosting/httpHost.js';
+import type { CheckpointEnvelope, SessionLifecycle } from '../../hosting/types.js';
+/** Options for {@link agentCoreRuntimeHost}. */
+export interface AgentCoreRuntimeHostOptions {
+    /**
+     * Port to bind. Default `8080` — the port the container contract specifies.
+     * Pass `0` in tests to take an ephemeral one.
+     */
+    readonly port?: number;
+    /**
+     * Interface to bind. Default `'0.0.0.0'`, which the contract requires: bind
+     * to loopback inside the container and the runtime's health probe cannot
+     * reach you.
+     */
+    readonly hostname?: string;
+    /**
+     * Report `'HealthyBusy'` instead of `'Healthy'` on the health path.
+     *
+     * A function, not a flag, because busy is a live fact about the process, not
+     * a setting: the runtime reads it on every probe to decide whether to send
+     * you more work. Omit it and the host reports `'Healthy'`, which is the
+     * honest answer for an agent that answers synchronously.
+     */
+    readonly busy?: () => boolean;
+}
+/**
+ * The AgentCore Runtime contract as an {@link HttpWire}.
+ *
+ * Exported so the body shapes are inspectable and testable without binding a
+ * socket, and so a deployment that must serve the same bodies from somewhere
+ * else can reuse them by name.
+ */
+export declare function agentCoreRuntimeWire(busy?: () => boolean): HttpWire;
+/**
+ * An `AgentHost` that speaks AgentCore Runtime's container contract.
+ *
+ * Passes the same conformance suite as `nodeHost` — it is the same HTTP host
+ * with this runtime's two paths, its header, and its two body shapes.
+ *
+ * @example  The container's entry point
+ *   const handle = await standingAgent({
+ *     agent,
+ *     host: agentCoreRuntimeHost(),
+ *     sessions: agentCoreSessions({ store: 'session-storage' }),
+ *   });
+ *   process.on('SIGTERM', () => void handle.close());
+ */
+export declare function agentCoreRuntimeHost(options?: AgentCoreRuntimeHostOptions): HttpHost;
+/**
+ * Where {@link agentCoreSessions} keeps a conversation between requests.
+ *
+ *  - `'session-storage'` — a JSON file under the container's own storage. The
+ *    runtime keeps that storage for the life of a session, INCLUDING across a
+ *    stop/resume of the container, so a conversation survives the thing most
+ *    likely to interrupt it. It does not survive the session ending.
+ *  - `'memory'` — one AgentCore Memory event per persist. Outlives the session,
+ *    the container and the deployment; costs an API call per turn and the
+ *    `@aws-sdk/client-bedrock-agentcore` peer dependency.
+ *
+ * Chosen at construction, never per call: a store that silently changed where
+ * it wrote would be a store you cannot reason about after an incident.
+ */
+export type AgentCoreSessionStore = 'session-storage' | 'memory';
+/** The default file the `'session-storage'` mode writes to. */
+export declare const DEFAULT_SESSION_STORAGE_PATH = "/tmp/agentcore-session";
+/** Options for the file-backed mode. */
+export interface AgentCoreFileSessionsOptions {
+    readonly store: 'session-storage';
+    /**
+     * Where to write. Default {@link DEFAULT_SESSION_STORAGE_PATH}. One file
+     * holds every session this container has seen, keyed by session id — the
+     * runtime already gives each session its own storage, so the keying is
+     * belt-and-braces for the case where it does not.
+     */
+    readonly path?: string;
+}
+/** One AgentCore Memory event, as this adapter cares about it. */
+export interface AgentCoreSessionEvent {
+    /** Server-assigned event id. */
+    readonly eventId: string;
+    /** The envelope decoded from the event's blob payload, or `null` when unreadable. */
+    readonly envelope: unknown;
+}
+/**
+ * The minimal AgentCore Memory surface the session store calls. The real SDK is
+ * adapted to this shape in one function below; tests inject a fake via
+ * `_client` and never touch AWS.
+ */
+export interface AgentCoreSessionClientLike {
+    /** Append one envelope as an event (the server assigns the event id). */
+    createEvent(input: {
+        memoryId: string;
+        actorId: string;
+        sessionId: string;
+        envelope: CheckpointEnvelope;
+    }): Promise<void>;
+    /** The session's events, newest first — the adapter reads only the newest. */
+    listEvents(input: {
+        memoryId: string;
+        actorId: string;
+        sessionId: string;
+        maxResults?: number;
+    }): Promise<{
+        events: readonly AgentCoreSessionEvent[];
+    }>;
+}
+/** Options for the event-backed mode. */
+export interface AgentCoreMemorySessionsOptions {
+    readonly store: 'memory';
+    /** AgentCore Memory ARN or id. Required. */
+    readonly memoryId: string;
+    /** AWS region, when the adapter constructs the SDK client itself. */
+    readonly region?: string;
+    /**
+     * The AgentCore `actorId` these conversations belong to. Default
+     * `'afp-standing-agent'`. One actor per deployed agent is the usual shape.
+     */
+    readonly actorId?: string;
+    /** Pre-built client, to share one SDK config across the host app. */
+    readonly client?: AgentCoreSessionClientLike;
+    /** @internal Test injection — skips the SDK require entirely. */
+    readonly _client?: AgentCoreSessionClientLike;
+    /** @internal Test injection — the AWS SDK module, to exercise the real shim with a fake SDK. */
+    readonly _sdk?: BedrockAgentCoreSessionSdkModule;
+}
+/** Options for {@link agentCoreSessions}. */
+export type AgentCoreSessionsOptions = AgentCoreFileSessionsOptions | AgentCoreMemorySessionsOptions;
+/**
+ * A `SessionLifecycle` backed by AgentCore, with the checkpoint's home chosen
+ * at construction.
+ *
+ * Both modes store the SAME `CheckpointEnvelope` the port defines, and both
+ * refuse an unknown `format` by name through the shared `readEnvelope` — a
+ * conversation written by a newer runtime is refused, never half-restored.
+ * That law is inherited, not re-implemented.
+ *
+ * @example  Survive a stop/resume, no AWS SDK required
+ *   agentCoreSessions({ store: 'session-storage' });
+ *
+ * @example  Outlive the session entirely
+ *   agentCoreSessions({ store: 'memory', memoryId: process.env.MEMORY_ID!, region: 'us-west-2' });
+ */
+export declare function agentCoreSessions(options: AgentCoreSessionsOptions): SessionLifecycle;
+/** The slice of `@aws-sdk/client-bedrock-agentcore` this shim touches. */
+export interface BedrockAgentCoreSessionSdkModule {
+    readonly BedrockAgentCoreClient?: new (config: {
+        region?: string;
+    }) => {
+        send(cmd: unknown): Promise<unknown>;
+    };
+    readonly CreateEventCommand?: new (input: unknown) => unknown;
+    readonly ListEventsCommand?: new (input: unknown) => unknown;
+}