agentfootprint 7.13.0 → 7.14.0

package/dist/esm/hosting/nodeHost.js

@@ -0,0 +1,245 @@
+/**
+ * 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.
+ */
+import { encodeSSE } from '../stream.js';
+import { HostClosedError } from './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();
+ */
+export 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 import('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 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;
+                },
+            };
+        },
+    };
+}
+/** 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(encodeSSE('chunk', { text: chunk }));
+        },
+        complete(output) {
+            if (settled)
+                return;
+            settled = true;
+            if (wantsStream) {
+                res.write(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(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/esm/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/esm/hosting/standingAgent.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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.
+ */
+import type { HostHandle, StandingAgentOptions } from './types.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());
+ */
+export declare function standingAgent<TH extends HostHandle>(options: StandingAgentOptions<TH>): Promise<TH>;

package/dist/esm/hosting/standingAgent.js

@@ -0,0 +1,192 @@
+/**
+ * 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.
+ */
+import { isPaused } from '../core/pause.js';
+import { toEnvelope, readEnvelope } from './envelope.js';
+import { ConcurrentRunError, PauseNotCarriedError } from './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());
+ */
+export 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 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 = 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 (isPaused(output)) {
+                reply.fail(new 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, 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();
+        },
+    };
+}
+/**
+ * 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/esm/hosting/standingAgent.js.map

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