agentfootprint 7.13.0 → 7.14.0

package/dist/hosting/nodeHost.js

@@ -0,0 +1,272 @@
+"use strict";
+/**
+ * hosting/nodeHost — the plain HTTP adapter, built on `node:http` and nothing
+ * else.
+ *
+ *   const host = nodeHost({ port: 8080 });
+ *   const handle = await host.serve(async (request, reply) => {
+ *     reply.complete(await answer(request.input));
+ *   });
+ *
+ * Two routes: `POST /invoke` takes `{ input, sessionId? }` and answers
+ * `{ output }`; `GET /health` answers `{ status: 'ok' }`. Both paths are
+ * options, because the paths are the part most likely to be dictated to you by
+ * whatever is in front of the process — a load balancer, a container contract,
+ * a colleague's convention. A path is a deployment detail, so it is a knob
+ * here and absent from the port entirely.
+ *
+ * **Streaming is the caller's choice, not the server's.** Send
+ * `Accept: text/event-stream` and the reply is Server-Sent Events, one `chunk`
+ * event per `reply.emit(...)` then a final `complete`. Send anything else and
+ * the same handler produces one JSON body — it emits into a buffer that the
+ * completion settles. The handler cannot tell the difference and does not need
+ * to, which is the property `capabilities` exists to describe.
+ *
+ * Pattern: Adapter. Everything specific to HTTP — the paths, the JSON body
+ * shape, the status codes, the SSE framing — lives in this file. `types.ts`
+ * knows none of it, and a future adapter for somewhere else re-decides all of
+ * it without touching a port.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodeHost = void 0;
+const stream_js_1 = require("../stream.js");
+const errors_js_1 = require("./errors.js");
+const HOST_NAME = 'nodeHost';
+const CAPABILITIES = ['streaming'];
+/**
+ * Status codes this adapter maps by error code. Anything else is a 500.
+ *
+ * All three are deliberately NOT 5xx: none of them is the agent breaking. A
+ * closed host is shutting down (503), a concurrent turn conflicts with the run
+ * already going (409), and a paused run conflicts with the state this reply can
+ * carry (409) — the run is unfinished, not failed, and a 500 would say
+ * otherwise to every dashboard that ever sees it.
+ */
+const STATUS_BY_CODE = {
+    ERR_HOST_CLOSED: 503,
+    ERR_CONCURRENT_RUN: 409,
+    ERR_PAUSE_NOT_CARRIED: 409,
+};
+/**
+ * An HTTP host for one handler.
+ *
+ * @example
+ *   const handle = await nodeHost({ port: 0 }).serve(handler);
+ *   await fetch(`${handle.url}/invoke`, {
+ *     method: 'POST',
+ *     headers: { 'content-type': 'application/json' },
+ *     body: JSON.stringify({ input: 'hello', sessionId: 'c-1' }),
+ *   });
+ *   await handle.close();
+ */
+function nodeHost(options = {}) {
+    const port = options.port ?? 8080;
+    const hostname = options.hostname ?? '0.0.0.0';
+    const invokePath = options.invokePath ?? '/invoke';
+    const healthPath = options.healthPath ?? '/health';
+    return {
+        name: HOST_NAME,
+        capabilities: CAPABILITIES,
+        async serve(handler) {
+            const { createServer } = await Promise.resolve().then(() => __importStar(require('node:http')));
+            const startedAt = Date.now();
+            const inFlight = new Set();
+            let accepting = true;
+            let closing;
+            const server = createServer((req, res) => {
+                const path = (req.url ?? '').split('?')[0];
+                if (req.method === 'GET' && path === healthPath) {
+                    sendJson(res, 200, { status: 'ok', uptimeMs: Date.now() - startedAt });
+                    return;
+                }
+                if (req.method !== 'POST' || path !== invokePath) {
+                    sendJson(res, 404, { error: `no route for ${req.method ?? '?'} ${path}` });
+                    return;
+                }
+                if (!accepting) {
+                    const refusal = new errors_js_1.HostClosedError(HOST_NAME);
+                    sendJson(res, STATUS_BY_CODE[refusal.code] ?? 500, {
+                        error: refusal.message,
+                        code: refusal.code,
+                    });
+                    return;
+                }
+                const served = serveOne(req, res, handler);
+                inFlight.add(served);
+                void served.finally(() => inFlight.delete(served));
+            });
+            await new Promise((resolve, reject) => {
+                server.once('error', reject);
+                server.listen(port, hostname, resolve);
+            });
+            const address = server.address();
+            const boundPort = typeof address === 'object' && address ? address.port : port;
+            const displayHost = hostname === '0.0.0.0' || hostname === '::' ? '127.0.0.1' : hostname;
+            return {
+                url: `http://${displayHost}:${boundPort}`,
+                port: boundPort,
+                close() {
+                    // Idempotent: the first call owns the shutdown, later ones await it.
+                    closing ??= (async () => {
+                        accepting = false;
+                        // Drain BEFORE touching sockets — an in-flight request is work the
+                        // caller is still waiting on, and dropping it would be the exact
+                        // thing close() promises not to do.
+                        await Promise.allSettled([...inFlight]);
+                        server.closeIdleConnections();
+                        await new Promise((resolve) => server.close(() => resolve()));
+                    })();
+                    return closing;
+                },
+            };
+        },
+    };
+}
+exports.nodeHost = nodeHost;
+/** Run one request through the handler and write whatever it decides. */
+async function serveOne(req, res, handler) {
+    const wantsStream = (req.headers.accept ?? '').includes('text/event-stream');
+    const controller = new AbortController();
+    let body;
+    try {
+        body = await readJson(req);
+    }
+    catch (err) {
+        sendJson(res, 400, { error: `invalid JSON body: ${asError(err).message}` });
+        return;
+    }
+    const input = typeof body.input === 'string' ? body.input : '';
+    // sessionId is caller data whichever way it arrives; the body wins so a
+    // caller that sets both is not surprised by which one the server preferred.
+    const sessionId = typeof body.sessionId === 'string'
+        ? body.sessionId
+        : typeof req.headers['x-session-id'] === 'string'
+            ? req.headers['x-session-id']
+            : undefined;
+    if (wantsStream) {
+        res.writeHead(200, {
+            'content-type': 'text/event-stream',
+            'cache-control': 'no-cache',
+            connection: 'keep-alive',
+        });
+    }
+    let settled = false;
+    // The caller hung up before we answered — tell the handler so it can stop
+    // paying for work nobody is waiting for.
+    res.once('close', () => {
+        if (!settled)
+            controller.abort();
+    });
+    const reply = {
+        emit(chunk) {
+            // Not streaming? The chunk is a preview of text `complete` will deliver
+            // in full, so there is nothing to send and nothing to keep.
+            if (settled || !wantsStream)
+                return;
+            res.write((0, stream_js_1.encodeSSE)('chunk', { text: chunk }));
+        },
+        complete(output) {
+            if (settled)
+                return;
+            settled = true;
+            if (wantsStream) {
+                res.write((0, stream_js_1.encodeSSE)('complete', { output }));
+                res.end();
+            }
+            else {
+                sendJson(res, 200, { output });
+            }
+        },
+        fail(error) {
+            if (settled)
+                return;
+            settled = true;
+            const code = error.code;
+            const payload = { error: error.message, ...(code !== undefined && { code }) };
+            if (wantsStream) {
+                res.write((0, stream_js_1.encodeSSE)('error', payload));
+                res.end();
+            }
+            else {
+                sendJson(res, code !== undefined ? STATUS_BY_CODE[code] ?? 500 : 500, payload);
+            }
+        },
+    };
+    try {
+        await handler({
+            input,
+            ...(sessionId !== undefined && { sessionId }),
+            headers: lowerCased(req.headers),
+            signal: controller.signal,
+        }, reply);
+    }
+    catch (err) {
+        // A handler that throws is a failed request, never a hung one.
+        reply.fail(asError(err));
+    }
+    // A handler that returned without answering gets one authored answer rather
+    // than a socket the caller waits on until it times out.
+    if (!settled) {
+        reply.fail(new Error('[hosting] the handler returned without calling complete() or fail().'));
+    }
+}
+function readJson(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('error', reject);
+        req.on('end', () => {
+            const raw = Buffer.concat(chunks).toString('utf8');
+            if (!raw)
+                return resolve({});
+            try {
+                const parsed = JSON.parse(raw);
+                resolve(parsed && typeof parsed === 'object' ? parsed : {});
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+    });
+}
+function sendJson(res, status, body) {
+    res.writeHead(status, { 'content-type': 'application/json' });
+    res.end(JSON.stringify(body));
+}
+function lowerCased(headers) {
+    const out = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (typeof value === 'string')
+            out[name.toLowerCase()] = value;
+        else if (Array.isArray(value))
+            out[name.toLowerCase()] = value.join(', ');
+    }
+    return out;
+}
+function asError(err) {
+    return err instanceof Error ? err : new Error(String(err));
+}
+//# sourceMappingURL=nodeHost.js.map

package/dist/hosting/nodeHost.js.map

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

package/dist/hosting/standingAgent.js

@@ -0,0 +1,196 @@
+"use strict";
+/**
+ * hosting/standingAgent — an agent that stays up and remembers.
+ *
+ *   await standingAgent({
+ *     agent,
+ *     sessions: memorySessions(),
+ *     host: nodeHost({ port: 8080 }),
+ *   });
+ *
+ * One request at a time it does four things: wake and hydrate the session,
+ * resume that conversation or start a fresh one, persist what the run leaves
+ * behind, then reply. Everything else is somebody else's job — the host carries
+ * bytes, the store keeps them, the agent thinks.
+ *
+ * ── Resuming is a REPLAY, and that has a cost you must know about ────────────
+ * A stored conversation is restored through `agent.resumeOnError(...)`, and
+ * this is its caveat, stated here in the words the Agent states it in, because
+ * a composition that hides the caveat of the thing it composes is worse than no
+ * composition at all:
+ *
+ *   > **Tool re-execution / idempotency**: tool side effects from the FAILED
+ *   > iteration are not in the checkpoint. The model re-decides from the
+ *   > restored history and may re-issue those tool calls — they WILL execute
+ *   > again (there is no built-in toolCallId dedup). Mutating tools (payments,
+ *   > emails, DB writes) must be idempotent — key on stable call content, not
+ *   > `ctx.toolCallId` (a re-issued call gets a new id).
+ *
+ * ── Why one run at a time ───────────────────────────────────────────────────
+ * An Agent instance holds per-run state on itself, and this composer shares ONE
+ * instance across every session. Two runs overlapping on it do not crash —
+ * which is precisely the danger. They both finish, and the state the composer
+ * reads afterwards belongs to whichever started last, so one session's envelope
+ * can end up holding another session's conversation. Nothing in the recording
+ * would say so. Runs are therefore serialized, globally, and that is a
+ * correctness requirement rather than a tuning choice.
+ *
+ * `onConcurrentInvoke` is the separate question of what to do when a second
+ * turn of the SAME conversation arrives while the first is running: refuse it
+ * (default) or queue it. A request for a DIFFERENT session is never refused —
+ * there is nothing wrong with it; it simply waits its turn.
+ *
+ * Pattern: Composition root. It owns wiring and ordering; it invents no
+ * mechanism of its own.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.standingAgent = void 0;
+const pause_js_1 = require("../core/pause.js");
+const envelope_js_1 = require("./envelope.js");
+const errors_js_1 = require("./errors.js");
+/**
+ * Serve one agent, with per-session conversation memory, on any
+ * {@link AgentHost}.
+ *
+ * Resolves once the host is live. Closing the returned handle closes the host
+ * and detaches the listeners this composer added to the agent.
+ *
+ * @example
+ *   const handle = await standingAgent({
+ *     agent,
+ *     sessions: memorySessions(),
+ *     host: nodeHost({ port: 0 }),
+ *     onConcurrentInvoke: 'enqueue',
+ *   });
+ *   process.on('SIGTERM', () => void handle.close());
+ */
+async function standingAgent(options) {
+    const { agent, sessions, host } = options;
+    const policy = options.onConcurrentInvoke ?? 'reject';
+    // Runs are serialized, so at any moment there is at most one active reply and
+    // at most one active run to name in a refusal.
+    let activeReply;
+    let activeRunId;
+    let activeSession;
+    const queued = [];
+    let chain = Promise.resolve();
+    let anonymous = 0;
+    const offTurnStart = agent.on('agentfootprint.agent.turn_start', (event) => {
+        activeRunId = event.meta?.runId;
+    });
+    // Tokens reach the caller only if the host streams; `emit` on a host that
+    // does not is a no-op by design, so this needs no capability check.
+    const offToken = agent.on('agentfootprint.stream.token', (event) => {
+        const content = event.payload?.content;
+        if (typeof content === 'string' && content.length > 0)
+            activeReply?.emit?.(content);
+    });
+    /** Queue `work` behind everything already waiting, FIFO. */
+    function serialize(sessionKey, work) {
+        if (policy === 'reject' && (activeSession === sessionKey || queued.includes(sessionKey))) {
+            return Promise.reject(new errors_js_1.ConcurrentRunError(sessionKey, activeRunId));
+        }
+        queued.push(sessionKey);
+        const mine = chain.then(async () => {
+            queued.splice(queued.indexOf(sessionKey), 1);
+            activeSession = sessionKey;
+            try {
+                await work();
+            }
+            finally {
+                activeSession = undefined;
+                activeRunId = undefined;
+            }
+        });
+        // The chain must never reject, or one failed request would wedge every
+        // request behind it.
+        chain = mine.then(() => undefined, () => undefined);
+        return mine;
+    }
+    const handler = async (request, reply) => {
+        const sessionId = request.sessionId;
+        // A request with no session has nothing to hydrate and nowhere to persist
+        // that the caller could ask for again, so it gets its own key and can never
+        // collide with anyone.
+        const sessionKey = sessionId ?? `#anonymous-${++anonymous}`;
+        try {
+            await serialize(sessionKey, () => answerOne(agent, sessions, request, reply, sessionId));
+        }
+        catch (err) {
+            reply.fail(err instanceof Error ? err : new Error(String(err)));
+        }
+    };
+    async function answerOne(runner, store, request, reply, sessionId) {
+        activeReply = reply;
+        try {
+            let prior;
+            if (sessionId !== undefined) {
+                await store.onWake?.(sessionId, 'invoke');
+                const stored = await store.hydrate(sessionId);
+                // Throws by name on a format this runtime cannot read — better a loud
+                // refusal than an agent answering from half a conversation.
+                if (stored !== undefined)
+                    prior = (0, envelope_js_1.readEnvelope)(stored);
+            }
+            // The signal reaches tool execution, tool discovery and skill-entry
+            // scoring. It does NOT currently reach the LLM call, so a caller who
+            // hangs up mid-generation stops the tools, not the token stream.
+            const runOptions = request.signal ? { env: { signal: request.signal } } : undefined;
+            const output = prior
+                ? await runner.resumeOnError(continueConversation(prior, request.input), runOptions)
+                : await runner.run({ message: request.input }, runOptions);
+            if ((0, pause_js_1.isPaused)(output)) {
+                reply.fail(new errors_js_1.PauseNotCarriedError(pausedToolName(runner), sessionId));
+                return;
+            }
+            if (sessionId !== undefined) {
+                const conversation = runner.checkpoint();
+                // Persist BEFORE answering: the caller learns the answer only once the
+                // conversation that produced it is durable, so a queued next turn can
+                // never read state older than the answer already given.
+                if (conversation)
+                    await store.persist(sessionId, (0, envelope_js_1.toEnvelope)(conversation));
+            }
+            reply.complete(typeof output === 'string' ? output : String(output));
+        }
+        finally {
+            activeReply = undefined;
+        }
+    }
+    const handle = await host.serve(handler);
+    // Keep whatever the adapter put on its own handle (nodeHost's bound `url`,
+    // say) and replace only `close`, which now also detaches this composer's
+    // listeners. The cast is the one place TypeScript cannot see that a spread
+    // plus one override is still the adapter's handle type.
+    return {
+        ...handle,
+        async close() {
+            await handle.close();
+            offTurnStart();
+            offToken();
+        },
+    };
+}
+exports.standingAgent = standingAgent;
+/**
+ * The stored conversation plus this turn's message.
+ *
+ * The new message has to be appended by hand: `resumeOnError` restores the
+ * history it is given and the LLM stage reads that history directly, so a
+ * message left out here is a message the model never sees.
+ */
+function continueConversation(prior, input) {
+    return {
+        ...prior,
+        history: [...prior.history, { role: 'user', content: input }],
+        originalInput: { message: input },
+        checkpointedAt: Date.now(),
+    };
+}
+/** Which tool asked for a human, when the paused run recorded one. */
+function pausedToolName(runner) {
+    const state = runner.getLastSnapshot()?.sharedState;
+    const name = state?.pausedToolName;
+    return typeof name === 'string' && name.length > 0 ? name : undefined;
+}
+//# sourceMappingURL=standingAgent.js.map

package/dist/hosting/standingAgent.js.map

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

package/dist/hosting/types.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * hosting/types — the two ports an agent needs to stand up and stay up.
+ *
+ * `AgentHost` is "something can call me". `SessionLifecycle` is "the
+ * conversation outlives the request". Both are deliberately written in the
+ * vocabulary every transport and every store already has — an input, a reply,
+ * a session id, a stored blob — and in nothing else.
+ *
+ * **The rule these types are written under:** no runtime, product or protocol
+ * gets a field, a name or an assumption here. A port shaped around one
+ * provider's request envelope stops being a port and becomes that provider's
+ * SDK with extra steps, and every later adapter pays for it. If a decision only
+ * makes sense for one place you might deploy, it belongs in the adapter for
+ * that place, not in this file. `nodeHost` is the first adapter and it does not
+ * get special treatment either: its paths, its status codes and its JSON body
+ * shape all live in `nodeHost.ts`, and nothing in this file knows they exist.
+ *
+ * Pattern: Ports & adapters (hexagonal). Role: the port side, exclusively.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/hosting/types.js.map

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

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

@@ -175,6 +175,10 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      *  function restores `scope.history` from this instead of starting
      *  fresh. Cleared on first read so subsequent runs start clean. */
     private pendingResumeHistory?;
+    /** The last completed run's final answer — see `checkpoint()` for why it is
+     *  kept here rather than read back from the recording. Undefined after a run
+     *  that failed or paused. */
+    private lastRunAnswer?;
     /**
      * Optional `ToolProvider` set via the builder's `.toolProvider()`.
      * When present, the Tools slot subflow consults it per iteration
@@ -360,6 +364,49 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      */
     private installCheckpointTracker;
     resume(checkpoint: FlowchartCheckpoint, input?: unknown, options?: AgentRunOptions): Promise<AgentOutput | RunnerPauseOutcome>;
+    /**
+     * The conversation this agent's LAST completed run leaves behind, packed as
+     * the same `AgentRunCheckpoint` that `resumeOnError(...)` accepts. Store it,
+     * hand it back next turn, and the agent continues where it left off — across
+     * a restart, a deploy, or a different machine.
+     *
+     * Returns `undefined` before any run has completed.
+     *
+     * **Read from the run's own recording, not from a second copy.** The history
+     * comes from `getLastSnapshot().sharedState.history` — the state the run
+     * actually committed — cloned on the way out so a persistence layer can never
+     * mutate the live heap. The final assistant turn is appended from the answer
+     * `run()` returned, because nothing ever writes it back into `history`: the
+     * loop appends assistant turns only when they carry tool calls, and the turn
+     * that ends the run carries none. An agent that stored this conversation
+     * without that append would drop its own reply every turn and answer the next
+     * one having forgotten what it just said.
+     *
+     * Adds no events, no scope writes and no capture: every recording is
+     * byte-identical to an agent that never calls this.
+     *
+     * After a run that **paused**, this is the conversation as of the pause, with
+     * no answer appended — a pause is unfinished work, and pause/resume has its
+     * own carrier (`FlowchartCheckpoint`) that holds engine state this shape
+     * cannot.
+     *
+     * The conversation grows every turn and nothing here trims it. Bounding what
+     * the model is shown is the memory subsystem's job (`.memory(...)`), not a
+     * silent cap applied on the way to storage.
+     *
+     * @example
+     * ```ts
+     * await agent.run({ message: 'Book me a table for two.' });
+     * const conversation = agent.checkpoint();          // persist anywhere
+     * // …a restart later, on a fresh Agent:
+     * await agent.resumeOnError({
+     *   ...conversation,
+     *   history: [...conversation.history, { role: 'user', content: 'Make it three.' }],
+     *   originalInput: { message: 'Make it three.' },
+     * });
+     * ```
+     */
+    checkpoint(): AgentRunCheckpoint | undefined;
     private createExecutor;
     /**
      * Flush the deferred-observer backlog of the most recent run's executor,

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

@@ -1 +1 @@
-{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../../src/core/Agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../../src/core/Agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAGL,KAAK,sBAAsB,EAI3B,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EAExB,KAAK,UAAU,EACf,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAOjE,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAyBrD,OAAO,EAEL,KAAK,qBAAqB,EAE3B,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AASlE,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAE1E,OAAO,EAAuB,KAAK,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AACvF,OAAO,EAKL,KAAK,kBAAkB,EAExB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAwC,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAClG,OAAO,EAAE,UAAU,EAAa,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAM/D,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,WAAW,EAEX,uBAAuB,EACvB,SAAS,EACT,gBAAgB,EAChB,WAAW,EACX,mBAAmB,EACpB,MAAM,kBAAkB,CAAC;AAS1B,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAGvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,CAAC;AAMxB,YAAY,EACV,UAAU,EACV,YAAY,EACZ,WAAW,EACX,uBAAuB,EACvB,SAAS,EACT,gBAAgB,EAChB,WAAW,EACX,mBAAmB,GACpB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,8FAA8F;IAC9F,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uIAAuI;IACvI,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAOD,qBAAa,KAAM,SAAQ,UAAU,CAAC,UAAU,EAAE,WAAW,CAAC;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAc;IACtD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAU;IAC/C;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA+B;IACxD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuB;IAClD;;mEAE+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAgD;IACrF;;4DAEwD;IACxD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAiD;IACtF;;+EAE2E;IAC3E,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAC,CAGb;IAC3B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAe;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAoB;IACvD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAwB;IAC3D;;kFAE8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAwB;IACtD;;yDAEqD;IACrD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAc;IAC3C;;iEAE6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmB;IAChD;;;;qCAIiC;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmB;IAChD;;uEAEmE;IACnE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAsB;IACtD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAqB;IACzD,qEAAqE;IACrE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAA+B;IAC/D;;;4DAGwD;IACxD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAwB;IACzD;wDACoD;IACpD,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAC,CAA0B;IAEnE;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/D,QAAQ,CAAC,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAE7D,OAAO,CAAC,iBAAiB,CAIvB;IAcF;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8B;IAEvD;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAA8B;IAElE;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAkC;IAErE;;uEAEmE;IACnE,OAAO,CAAC,oBAAoB,CAAC,CAAwB;IAErD;;iCAE6B;IAC7B,OAAO,CAAC,aAAa,CAAC,CAAS;IAE/B;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAe;IAErD;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAoB;IAEvD;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAkB;IACnD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAS;IACzC;;;sBAGkB;IAClB,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAqD;IACzF;qDACiD;IACjD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAA4C;IAClF;;;;4BAIwB;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4C;gBAGpE,IAAI,EAAE,YAAY,EAClB,iBAAiB,EAAE,MAAM,EACzB,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,KAAK,EAAE;QACL,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAC/D,QAAQ,CAAC,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;KAC9D,EACD,UAAU,GAAE,SAAS,SAAS,EAAO,EACrC,QAAQ,GAAE,SAAS,gBAAgB,EAAO,EAC1C,kBAAkB,CAAC,EAAE,kBAAkB,CAAC,OAAO,CAAC,EAChD,YAAY,CAAC,EAAE,YAAY,EAC3B,uBAAuB,GAAE,WAAsB,EAC/C,eAAe,UAAQ,EACvB,aAAa,CAAC,EAAE,aAAa,EAC7B,iBAAiB,CAAC,EAAE,sBAAsB,CAAC,OAAO,CAAC,EACnD,iBAAiB,CAAC,EAAE,iBAAiB,EACrC,oBAAoB,CAAC,EAAE,eAAe,GAAG,IAAI,EAC7C,mBAAmB,CAAC,EAAE,MAAM,EAC5B,mBAAmB,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,MAAM,GAAG,SAAS,EACnE,mBAAmB,CAAC,EAAE,CAAC,cAAc,CAAC,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,EACpE,sBAAsB,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,EAC/F,cAAc,CAAC,EAAE,qBAAqB,EACtC,WAAW,CAAC,EAAE,WAAW;IAiH3B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,GAAG,YAAY;IAI/C;;;;;OAKG;IACH,0BAA0B,IAAI,WAAW;IAIzC;;;;;;;;;OASG;IACH,eAAe,IAAI,eAAe,GAAG,SAAS;IAI9C;;;;;;OAMG;IACH,uBAAuB,IAAI,SAAS,sBAAsB,EAAE;IAI5D;;;;;;OAMG;cAMgB,kBAAkB,IAAI,OAAO,iBAAiB,EAAE,eAAe,GAAG,SAAS;IAI9F;;;;;;;;6BAQyB;cACN,oBAAoB,IAAI,OAAO,iBAAiB,EAAE,aAAa;IAelF;;;;;;;;;;OAUG;IACH,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC;IAUxC;;;;;;;;;OASG;IACG,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAoC5D;;;;;;;;;;OAUG;IACG,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,CAAC,CAAC;IAiB/E,GAAG,CACP,KAAK,EAAE,UAAU,EACjB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,WAAW,GAAG,kBAAkB,CAAC;IAoE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACG,aAAa,CACjB,UAAU,EAAE,kBAAkB,GAAG,OAAO,EACxC,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,WAAW,GAAG,kBAAkB,CAAC;IAQ5C;;;;;;OAMG;IACH,OAAO,CAAC,wBAAwB;IAyB1B,MAAM,CACV,UAAU,EAAE,mBAAmB,EAC/B,KAAK,CAAC,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,WAAW,GAAG,kBAAkB,CAAC;IAc5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyCG;IACH,UAAU,IAAI,kBAAkB,GAAG,SAAS;IAmB5C,OAAO,CAAC,cAAc;IA8GtB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,cAAc,CAAC,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAK3E,OAAO,CAAC,cAAc;IA8FtB,OAAO,CAAC,UAAU;CA6MnB"}

package/dist/types/hosting/envelope.d.ts

@@ -0,0 +1,34 @@
+/**
+ * hosting/envelope — pack a conversation for storage, and refuse to unpack one
+ * you cannot read.
+ *
+ * Two functions and one rule: **an unknown format is refused by name, never
+ * guessed at.** A store outlives the code that wrote to it. Somebody will
+ * deploy a newer runtime, it will write a newer format, and an older instance
+ * still running will read it. The only honest thing that older instance can do
+ * is say which format it found, which ones it knows, and stop — because
+ * "restore what I can and hope" means an agent answering from a conversation
+ * that is missing whatever the older reader did not understand.
+ */
+import { type AgentRunCheckpoint } from '../core/runCheckpoint.js';
+import type { CheckpointEnvelope } from './types.js';
+/**
+ * Pack a conversation checkpoint for storage.
+ *
+ * @example
+ *   const conversation = agent.checkpoint();
+ *   if (conversation) await sessions.persist(sessionId, toEnvelope(conversation));
+ */
+export declare function toEnvelope(checkpoint: AgentRunCheckpoint): CheckpointEnvelope;
+/**
+ * Unpack a stored envelope back into a conversation checkpoint.
+ *
+ * Takes `unknown` on purpose: what comes back from a store is bytes somebody
+ * else wrote, in a format this runtime may not know, and typing the parameter
+ * as the happy shape would be assuming the very thing that needs checking.
+ *
+ * @throws TypeError naming the format when it is one this runtime cannot read,
+ *   and naming the missing field when the conversation inside is malformed.
+ */
+export declare function readEnvelope(envelope: unknown): AgentRunCheckpoint;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/types/hosting/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../../src/hosting/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACvF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAKrD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,kBAAkB,GAAG,kBAAkB,CAE7E;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,OAAO,GAAG,kBAAkB,CAkBlE"}