agentfootprint 7.13.0 → 7.15.0

package/dist/esm/hosting/errors.d.ts

@@ -0,0 +1,78 @@
+/**
+ * hosting/errors — the refusals, authored once so every adapter refuses in the
+ * same words.
+ *
+ * A refusal that varies by adapter is a refusal nobody can write a test or a
+ * runbook against. These three carry a stable `code`, name WHO refused, and say
+ * what the caller should do instead. Adapters map the codes onto whatever their
+ * transport uses to say "no" — that mapping is the adapter's business and lives
+ * in the adapter, never here.
+ *
+ * `requireCapability` is the fourth refusal and the only one that is a
+ * programming mistake rather than a runtime condition, so it throws a plain
+ * `Error`: nothing branches on "I forgot to feature-detect", it just needs to
+ * say so loudly and name the adapter it is talking about.
+ */
+import type { AgentHost, HostCapability } from './types.js';
+/**
+ * Thrown when a request arrives at a host that is shutting down or shut down.
+ *
+ * `close()` lets in-flight work finish and refuses everything after it; this is
+ * what "everything after it" receives.
+ */
+export declare class HostClosedError extends Error {
+    readonly code: "ERR_HOST_CLOSED";
+    /** Which adapter refused. */
+    readonly hostName: string;
+    constructor(hostName: string);
+}
+/**
+ * Thrown when a request arrives for a session that already has a run in flight
+ * and the policy is `'reject'`.
+ *
+ * The refusal is about the SESSION, not about load: two turns of one
+ * conversation racing each other would each answer from the state the other is
+ * about to replace. A request for any OTHER session is never refused — it
+ * simply waits.
+ */
+export declare class ConcurrentRunError extends Error {
+    readonly code: "ERR_CONCURRENT_RUN";
+    /** The session that already has a run going. */
+    readonly sessionId: string;
+    /** The run that is already going, when it has announced itself. */
+    readonly activeRunId?: string;
+    constructor(sessionId: string, activeRunId?: string);
+}
+/**
+ * Raised when a run paused to ask a person something and the reply cannot carry
+ * a pause.
+ *
+ * **The run did not fail.** A pause is unfinished work: the agent stopped to ask
+ * and is waiting for an answer. What cannot happen here is storing it — the
+ * `'conversation-v1'` envelope holds a conversation, and a paused run is a
+ * conversation plus an engine checkpoint. So nothing is written, and the
+ * session keeps exactly the conversation it had before this request.
+ */
+export declare class PauseNotCarriedError extends Error {
+    readonly code: "ERR_PAUSE_NOT_CARRIED";
+    /** The tool that asked, when the run recorded which one it was. */
+    readonly toolName?: string;
+    /** The session whose stored conversation was left untouched. */
+    readonly sessionId?: string;
+    constructor(toolName?: string, sessionId?: string);
+}
+/**
+ * Assert that a host can do something, and throw a corrective error naming the
+ * adapter when it cannot.
+ *
+ * This is the feature-detection law with teeth: capabilities are read, never
+ * assumed, and asking for one that is absent tells you which adapter you are
+ * actually holding rather than failing quietly somewhere downstream.
+ *
+ * @example
+ *   requireCapability(host, 'streaming'); // throws unless this host streams
+ *
+ *   // or branch instead of insisting:
+ *   if (host.capabilities.includes('streaming')) { ... }
+ */
+export declare function requireCapability(host: AgentHost, capability: HostCapability): void;

package/dist/esm/hosting/errors.js

@@ -0,0 +1,119 @@
+/**
+ * hosting/errors — the refusals, authored once so every adapter refuses in the
+ * same words.
+ *
+ * A refusal that varies by adapter is a refusal nobody can write a test or a
+ * runbook against. These three carry a stable `code`, name WHO refused, and say
+ * what the caller should do instead. Adapters map the codes onto whatever their
+ * transport uses to say "no" — that mapping is the adapter's business and lives
+ * in the adapter, never here.
+ *
+ * `requireCapability` is the fourth refusal and the only one that is a
+ * programming mistake rather than a runtime condition, so it throws a plain
+ * `Error`: nothing branches on "I forgot to feature-detect", it just needs to
+ * say so loudly and name the adapter it is talking about.
+ */
+/**
+ * Thrown when a request arrives at a host that is shutting down or shut down.
+ *
+ * `close()` lets in-flight work finish and refuses everything after it; this is
+ * what "everything after it" receives.
+ */
+export class HostClosedError extends Error {
+    code = 'ERR_HOST_CLOSED';
+    /** Which adapter refused. */
+    hostName;
+    constructor(hostName) {
+        super(`[hosting] the '${hostName}' host is closed and is not accepting new requests. ` +
+            `In-flight requests were allowed to finish; this one arrived after close() was called. ` +
+            `Serve again on a fresh host to accept new work.`);
+        this.name = 'HostClosedError';
+        this.hostName = hostName;
+    }
+}
+/**
+ * Thrown when a request arrives for a session that already has a run in flight
+ * and the policy is `'reject'`.
+ *
+ * The refusal is about the SESSION, not about load: two turns of one
+ * conversation racing each other would each answer from the state the other is
+ * about to replace. A request for any OTHER session is never refused — it
+ * simply waits.
+ */
+export class ConcurrentRunError extends Error {
+    code = 'ERR_CONCURRENT_RUN';
+    /** The session that already has a run going. */
+    sessionId;
+    /** The run that is already going, when it has announced itself. */
+    activeRunId;
+    constructor(sessionId, activeRunId) {
+        super(`[hosting] session '${sessionId}' already has a run in flight` +
+            (activeRunId ? ` (run '${activeRunId}')` : '') +
+            `. Refusing rather than running two turns of one conversation at once — ` +
+            `they would each answer from state the other is about to replace. ` +
+            `Wait for the active run, or build the standing agent with ` +
+            `onConcurrentInvoke: 'enqueue' to queue this turn behind it instead.`);
+        this.name = 'ConcurrentRunError';
+        this.sessionId = sessionId;
+        if (activeRunId !== undefined)
+            this.activeRunId = activeRunId;
+    }
+}
+/**
+ * Raised when a run paused to ask a person something and the reply cannot carry
+ * a pause.
+ *
+ * **The run did not fail.** A pause is unfinished work: the agent stopped to ask
+ * and is waiting for an answer. What cannot happen here is storing it — the
+ * `'conversation-v1'` envelope holds a conversation, and a paused run is a
+ * conversation plus an engine checkpoint. So nothing is written, and the
+ * session keeps exactly the conversation it had before this request.
+ */
+export class PauseNotCarriedError extends Error {
+    code = 'ERR_PAUSE_NOT_CARRIED';
+    /** The tool that asked, when the run recorded which one it was. */
+    toolName;
+    /** The session whose stored conversation was left untouched. */
+    sessionId;
+    constructor(toolName, sessionId) {
+        super(`[hosting] the run paused to ask a person about ` +
+            (toolName ? `'${toolName}'` : 'a tool') +
+            ` and this reply cannot carry a pause. ` +
+            `The run did not fail — it is unfinished, waiting on an answer. ` +
+            `Nothing was written: ` +
+            (sessionId ? `session '${sessionId}'` : 'the session') +
+            ` still holds the conversation it held before this request. ` +
+            `The 'conversation-v1' envelope stores a conversation; a paused run is a ` +
+            `conversation plus an engine checkpoint, and storing half of it would be worse ` +
+            `than storing none. Carry the pause yourself with agent.run() / agent.resume().`);
+        this.name = 'PauseNotCarriedError';
+        if (toolName !== undefined)
+            this.toolName = toolName;
+        if (sessionId !== undefined)
+            this.sessionId = sessionId;
+    }
+}
+/**
+ * Assert that a host can do something, and throw a corrective error naming the
+ * adapter when it cannot.
+ *
+ * This is the feature-detection law with teeth: capabilities are read, never
+ * assumed, and asking for one that is absent tells you which adapter you are
+ * actually holding rather than failing quietly somewhere downstream.
+ *
+ * @example
+ *   requireCapability(host, 'streaming'); // throws unless this host streams
+ *
+ *   // or branch instead of insisting:
+ *   if (host.capabilities.includes('streaming')) { ... }
+ */
+export function requireCapability(host, capability) {
+    if (host.capabilities.includes(capability))
+        return;
+    const has = host.capabilities.length > 0 ? host.capabilities.join(', ') : 'none';
+    throw new Error(`[hosting] the '${host.name}' host does not support '${capability}'. ` +
+        `It reports: ${has}. Feature-detect with ` +
+        `host.capabilities.includes('${capability}') and fall back, or serve on a host ` +
+        `that has it — capabilities are read from the adapter, never assumed from its name.`);
+}
+//# sourceMappingURL=errors.js.map

package/dist/esm/hosting/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/hosting/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;;;;;GAKG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,IAAI,GAAG,iBAA0B,CAAC;IAC3C,6BAA6B;IACpB,QAAQ,CAAS;IAE1B,YAAY,QAAgB;QAC1B,KAAK,CACH,kBAAkB,QAAQ,sDAAsD;YAC9E,wFAAwF;YACxF,iDAAiD,CACpD,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,IAAI,GAAG,oBAA6B,CAAC;IAC9C,gDAAgD;IACvC,SAAS,CAAS;IAC3B,mEAAmE;IAC1D,WAAW,CAAU;IAE9B,YAAY,SAAiB,EAAE,WAAoB;QACjD,KAAK,CACH,sBAAsB,SAAS,+BAA+B;YAC5D,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU,WAAW,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9C,yEAAyE;YACzE,mEAAmE;YACnE,4DAA4D;YAC5D,qEAAqE,CACxE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,WAAW,KAAK,SAAS;YAAE,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IAChE,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,IAAI,GAAG,uBAAgC,CAAC;IACjD,mEAAmE;IAC1D,QAAQ,CAAU;IAC3B,gEAAgE;IACvD,SAAS,CAAU;IAE5B,YAAY,QAAiB,EAAE,SAAkB;QAC/C,KAAK,CACH,iDAAiD;YAC/C,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,QAAQ,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;YACvC,wCAAwC;YACxC,iEAAiE;YACjE,uBAAuB;YACvB,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,SAAS,GAAG,CAAC,CAAC,CAAC,aAAa,CAAC;YACtD,6DAA6D;YAC7D,0EAA0E;YAC1E,gFAAgF;YAChF,gFAAgF,CACnF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,QAAQ,KAAK,SAAS;YAAE,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACrD,IAAI,SAAS,KAAK,SAAS;YAAE,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC1D,CAAC;CACF;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAe,EAAE,UAA0B;IAC3E,IAAI,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,UAAU,CAAC;QAAE,OAAO;IACnD,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACjF,MAAM,IAAI,KAAK,CACb,kBAAkB,IAAI,CAAC,IAAI,4BAA4B,UAAU,KAAK;QACpE,eAAe,GAAG,wBAAwB;QAC1C,+BAA+B,UAAU,uCAAuC;QAChF,oFAAoF,CACvF,CAAC;AACJ,CAAC"}

package/dist/esm/hosting/httpHost.d.ts

@@ -0,0 +1,121 @@
+/**
+ * hosting/httpHost — one HTTP host, parameterised by the JSON dialect it speaks.
+ *
+ * Everything hard about serving an agent over HTTP happens once, here: draining
+ * on close, aborting when the caller hangs up, failing a handler that throws,
+ * failing a handler that answers nothing, mapping refusal codes onto status
+ * codes, and choosing between one JSON body and Server-Sent Events based on
+ * what the caller asked for.
+ *
+ * Everything a deployment target gets to re-decide is an {@link HttpWire}: the
+ * two paths, and the five JSON shapes — how a request names its input and its
+ * session, and what a health probe, a completion, a failure and a streamed
+ * piece look like on the wire.
+ *
+ * ── Why this file exists ─────────────────────────────────────────────────────
+ * `nodeHost` shipped first and hard-coded its own dialect: `{ input }` in,
+ * `{ output }` out, `{ status: 'ok' }` on the health path. That was fine while
+ * it was the only HTTP adapter and wrong the moment there was a second one. A
+ * container runtime dictates its own body shape as surely as it dictates its
+ * paths, and an adapter for it should be a CONFIGURATION of the HTTP work, not
+ * a second copy of it — a copy is where the drain semantics of two adapters
+ * silently diverge.
+ *
+ * Note what did NOT have to change for that: the ports. `AgentHost`,
+ * `HostRequest` and `HostReply` say exactly what they said before. The gap was
+ * in the first adapter, which had no seam, not in the port, which needed none.
+ *
+ * Pattern: Template method via configuration (Strategy on the wire format).
+ * Everything HTTP lives here and in the wires; `types.ts` knows none of it.
+ */
+import type { AgentHost, HostCapability, HostHandle, HostHandler } from './types.js';
+/** Everything a {@link HttpWire} may read when pulling a request apart. */
+export interface HttpRequestFacts {
+    /** The parsed JSON body, or `{}` for an empty one. */
+    readonly body: Readonly<Record<string, unknown>>;
+    /** Request headers with lower-cased names — so a wire never has to guess casing. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** The query string, already parsed. */
+    readonly query: URLSearchParams;
+}
+/**
+ * The JSON dialect one deployment target speaks.
+ *
+ * A wire is pure: it reads facts and returns values. It never touches the
+ * socket, never decides a status code, and never knows whether the reply is
+ * going out as one body or as a stream of frames — those are {@link httpHost}'s
+ * job, identical for every wire, which is the entire point of separating them.
+ */
+export interface HttpWire {
+    /**
+     * Pull the port's vocabulary out of one request. Anything the wire cannot
+     * find is simply absent — a missing input is the empty string, and a missing
+     * session id means "no session", never an error, because refusing a request
+     * on the shape of its body is a policy decision that belongs above the
+     * transport.
+     */
+    readRequest(facts: HttpRequestFacts): {
+        readonly input: string;
+        readonly sessionId?: string;
+    };
+    /** Body for a health probe. `uptimeMs` is how long this host has been serving. */
+    health(uptimeMs: number): unknown;
+    /** Body for a reply that completed. */
+    output(output: string): unknown;
+    /** Body for a reply that failed. `code` is the refusal's stable code, when it has one. */
+    failure(message: string, code?: string): unknown;
+    /** Body for one streamed piece, when the caller asked for Server-Sent Events. */
+    chunk(text: string): unknown;
+}
+/** Options for {@link httpHost}. */
+export interface HttpHostOptions {
+    /**
+     * Which adapter this is. Every refusal names it, so a caller reading an error
+     * learns which adapter said no rather than which file it came from.
+     */
+    readonly name: string;
+    /** The JSON dialect this host speaks. */
+    readonly wire: HttpWire;
+    /**
+     * Path that takes a request. **Required, deliberately.** A default here would
+     * be inherited by every adapter built on this file, and a default that
+     * silently matched one runtime's container contract is exactly how a vendor
+     * leaks into a library that promises not to know about one.
+     */
+    readonly invokePath: string;
+    /** Path that answers a health probe. Required, for the same reason. */
+    readonly healthPath: string;
+    /** Port to bind. Default `8080`. Pass `0` for an ephemeral port. */
+    readonly port?: number;
+    /** Interface to bind. Default `'0.0.0.0'`. */
+    readonly hostname?: string;
+    /** What this adapter claims beyond the baseline. Default `['streaming']`. */
+    readonly capabilities?: readonly HostCapability[];
+}
+/** A {@link HostHandle} that also says where it landed. */
+export interface HttpHostHandle extends HostHandle {
+    /** Where it is actually listening, e.g. `http://127.0.0.1:53211`. */
+    readonly url: string;
+    /** The port it actually bound — the real one, when you asked for `0`. */
+    readonly port: number;
+}
+/** {@link AgentHost} narrowed to an HTTP handle. */
+export interface HttpHost extends AgentHost {
+    serve(handler: HostHandler): Promise<HttpHostHandle>;
+}
+/**
+ * An HTTP host for one handler, speaking the dialect you hand it.
+ *
+ * @example  The same machinery, two dialects
+ *   httpHost({ name: 'nodeHost', wire: jsonWire, invokePath: '/invoke', healthPath: '/health' });
+ *   httpHost({ name: 'myRuntime', wire: myWire, invokePath: '/v1/run', healthPath: '/up' });
+ */
+export declare function httpHost(options: HttpHostOptions): HttpHost;
+/**
+ * Read a header case-insensitively from already-lower-cased facts.
+ *
+ * Exported because every wire that maps a header needs it and re-deriving it
+ * per adapter is how one of them ends up matching only the exact casing the
+ * author happened to test with.
+ */
+export declare function headerValue(facts: HttpRequestFacts, name: string, ...fallbacks: string[]): string | undefined;

package/dist/esm/hosting/httpHost.js

@@ -0,0 +1,248 @@
+/**
+ * hosting/httpHost — one HTTP host, parameterised by the JSON dialect it speaks.
+ *
+ * Everything hard about serving an agent over HTTP happens once, here: draining
+ * on close, aborting when the caller hangs up, failing a handler that throws,
+ * failing a handler that answers nothing, mapping refusal codes onto status
+ * codes, and choosing between one JSON body and Server-Sent Events based on
+ * what the caller asked for.
+ *
+ * Everything a deployment target gets to re-decide is an {@link HttpWire}: the
+ * two paths, and the five JSON shapes — how a request names its input and its
+ * session, and what a health probe, a completion, a failure and a streamed
+ * piece look like on the wire.
+ *
+ * ── Why this file exists ─────────────────────────────────────────────────────
+ * `nodeHost` shipped first and hard-coded its own dialect: `{ input }` in,
+ * `{ output }` out, `{ status: 'ok' }` on the health path. That was fine while
+ * it was the only HTTP adapter and wrong the moment there was a second one. A
+ * container runtime dictates its own body shape as surely as it dictates its
+ * paths, and an adapter for it should be a CONFIGURATION of the HTTP work, not
+ * a second copy of it — a copy is where the drain semantics of two adapters
+ * silently diverge.
+ *
+ * Note what did NOT have to change for that: the ports. `AgentHost`,
+ * `HostRequest` and `HostReply` say exactly what they said before. The gap was
+ * in the first adapter, which had no seam, not in the port, which needed none.
+ *
+ * Pattern: Template method via configuration (Strategy on the wire format).
+ * Everything HTTP lives here and in the wires; `types.ts` knows none of it.
+ */
+import { encodeSSE } from '../stream.js';
+import { HostClosedError } from './errors.js';
+/**
+ * Status codes mapped by refusal code. Anything else is a 500.
+ *
+ * None of the three is a 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,
+};
+const DEFAULT_CAPABILITIES = ['streaming'];
+/**
+ * An HTTP host for one handler, speaking the dialect you hand it.
+ *
+ * @example  The same machinery, two dialects
+ *   httpHost({ name: 'nodeHost', wire: jsonWire, invokePath: '/invoke', healthPath: '/health' });
+ *   httpHost({ name: 'myRuntime', wire: myWire, invokePath: '/v1/run', healthPath: '/up' });
+ */
+export function httpHost(options) {
+    const { name, wire, invokePath, healthPath } = options;
+    const port = options.port ?? 8080;
+    const hostname = options.hostname ?? '0.0.0.0';
+    const capabilities = options.capabilities ?? DEFAULT_CAPABILITIES;
+    return {
+        name,
+        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, wire.health(Date.now() - startedAt));
+                    return;
+                }
+                if (req.method !== 'POST' || path !== invokePath) {
+                    sendJson(res, 404, wire.failure(`no route for ${req.method ?? '?'} ${path}`));
+                    return;
+                }
+                if (!accepting) {
+                    const refusal = new HostClosedError(name);
+                    sendJson(res, STATUS_BY_CODE[refusal.code] ?? 500, wire.failure(refusal.message, refusal.code));
+                    return;
+                }
+                const served = serveOne(req, res, handler, wire);
+                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, wire) {
+    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, wire.failure(`invalid JSON body: ${asError(err).message}`));
+        return;
+    }
+    const headers = lowerCased(req.headers);
+    const query = new URLSearchParams((req.url ?? '').split('?')[1] ?? '');
+    const { input, sessionId } = wire.readRequest({ body, headers, query });
+    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', wire.chunk(chunk)));
+        },
+        complete(output) {
+            if (settled)
+                return;
+            settled = true;
+            if (wantsStream) {
+                res.write(encodeSSE('complete', wire.output(output)));
+                res.end();
+            }
+            else {
+                sendJson(res, 200, wire.output(output));
+            }
+        },
+        fail(error) {
+            if (settled)
+                return;
+            settled = true;
+            const code = error.code;
+            const payload = wire.failure(error.message, 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,
+            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));
+}
+/**
+ * Read a header case-insensitively from already-lower-cased facts.
+ *
+ * Exported because every wire that maps a header needs it and re-deriving it
+ * per adapter is how one of them ends up matching only the exact casing the
+ * author happened to test with.
+ */
+export function headerValue(facts, name, ...fallbacks) {
+    for (const candidate of [name, ...fallbacks]) {
+        const found = facts.headers[candidate.toLowerCase()];
+        if (typeof found === 'string' && found.length > 0)
+            return found;
+    }
+    return undefined;
+}
+//# sourceMappingURL=httpHost.js.map

package/dist/esm/hosting/httpHost.js.map

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

package/dist/esm/hosting/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * agentfootprint/hosting — the two ports between an agent and the place it runs.
+ *
+ * An agent that answers one call in a script and an agent that has been up for
+ * a month differ in two things, and only two: something has to carry requests
+ * to it, and the conversation has to outlive the request. This subpath is those
+ * two things as **ports**, plus local adapters that prove the ports work, plus
+ * the composer that wires them together.
+ *
+ *   `AgentHost`         — something can call me.
+ *   `SessionLifecycle`  — the conversation outlives the request.
+ *   `standingAgent`     — hydrate → resume-or-fresh → persist → reply.
+ *
+ * ── Why the ports look like nothing in particular ────────────────────────────
+ * Deliberately. Not one field, name or assumption here comes from any hosting
+ * product, cloud or protocol. A port shaped around one provider's request
+ * envelope stops being a port and becomes that provider's SDK with extra steps,
+ * and every adapter after the first pays for the shortcut. So the ports carry
+ * an input, a reply, an optional session id, headers, a signal — the vocabulary
+ * every transport already has — and everything specific to one place you might
+ * deploy lives in the adapter for that place. `nodeHost` gets no special
+ * treatment: its paths, status codes and JSON body shape are all in
+ * `nodeHost.ts` and the port types do not know they exist. A test greps these
+ * source files for vendor names, crudely and on purpose.
+ *
+ * ── What ships here ──────────────────────────────────────────────────────────
+ *   • `nodeHost({ port?, hostname?, invokePath?, healthPath? })` — plain
+ *     `node:http`, zero dependencies. `POST /invoke`, `GET /health`, and
+ *     Server-Sent Events when the caller asks for them.
+ *   • `httpHost({ name, wire, invokePath, healthPath, ... })` — the HTTP work
+ *     itself, parameterised by the JSON dialect it speaks. `nodeHost` is one
+ *     configuration of it; an adapter for someone's container runtime is
+ *     another. Two paths and five body shapes are all a second HTTP adapter
+ *     re-decides.
+ *   • `memorySessions()` — conversations in a Map, for tests and local dev.
+ *   • `standingAgent({ agent, sessions, host })` — the composer.
+ *   • `toEnvelope` / `readEnvelope` — pack a conversation, and refuse by name to
+ *     unpack a format this runtime does not know.
+ *   • `requireCapability` — feature-detection with teeth.
+ *
+ * @example  An agent that stays up and remembers
+ *   import { Agent } from 'agentfootprint';
+ *   import { standingAgent, nodeHost, memorySessions } from 'agentfootprint/hosting';
+ *
+ *   const handle = await standingAgent({
+ *     agent: Agent.create({ provider, model }).system('You help customers.').build(),
+ *     sessions: memorySessions(),
+ *     host: nodeHost({ port: 8080 }),
+ *   });
+ *   process.on('SIGTERM', () => void handle.close());
+ */
+export { nodeHost, jsonWire } from './nodeHost.js';
+export type { NodeHost, NodeHostHandle, NodeHostOptions } from './nodeHost.js';
+export { httpHost, headerValue } from './httpHost.js';
+export type { HttpHost, HttpHostHandle, HttpHostOptions, HttpRequestFacts, HttpWire, } from './httpHost.js';
+export { memorySessions } from './memorySessions.js';
+export { toEnvelope, readEnvelope } from './envelope.js';
+export { standingAgent } from './standingAgent.js';
+export { requireCapability, HostClosedError, ConcurrentRunError, PauseNotCarriedError, } from './errors.js';
+export type { AgentHost, CheckpointEnvelope, ConcurrentInvokePolicy, HostCapability, HostHandle, HostHandler, HostReply, HostRequest, SessionLifecycle, StandingAgentOptions, WakeReason, } from './types.js';