agentfootprint 7.13.0 → 7.14.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/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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.
+ *   • `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 } from './nodeHost.js';
+export type { NodeHost, NodeHostHandle, NodeHostOptions } from './nodeHost.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';

package/dist/esm/hosting/index.js

@@ -0,0 +1,52 @@
+/**
+ * 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.
+ *   • `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 } from './nodeHost.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';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/hosting/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,aAAa,CAAC"}

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

@@ -0,0 +1,22 @@
+/**
+ * hosting/memorySessions — conversations in a Map.
+ *
+ * The smallest thing that satisfies `SessionLifecycle`, for tests and for local
+ * development where a Redis is ceremony you have not earned yet. It is exactly
+ * as durable as the process: restart and every conversation is gone.
+ *
+ * That is not a shortcoming to apologise for, it is the point of the port. Swap
+ * this for a store that survives a restart and the standing agent is unchanged
+ * — which is also how the "a crashed process resumes the conversation" test is
+ * written: keep the store, throw away everything else, and watch the
+ * conversation come back through the envelope alone.
+ */
+import type { SessionLifecycle } from './types.js';
+/**
+ * An in-process session store.
+ *
+ * @example
+ *   const sessions = memorySessions();
+ *   await standingAgent({ agent, sessions, host: nodeHost({ port: 8080 }) });
+ */
+export declare function memorySessions(): SessionLifecycle;

package/dist/esm/hosting/memorySessions.js

@@ -0,0 +1,31 @@
+/**
+ * hosting/memorySessions — conversations in a Map.
+ *
+ * The smallest thing that satisfies `SessionLifecycle`, for tests and for local
+ * development where a Redis is ceremony you have not earned yet. It is exactly
+ * as durable as the process: restart and every conversation is gone.
+ *
+ * That is not a shortcoming to apologise for, it is the point of the port. Swap
+ * this for a store that survives a restart and the standing agent is unchanged
+ * — which is also how the "a crashed process resumes the conversation" test is
+ * written: keep the store, throw away everything else, and watch the
+ * conversation come back through the envelope alone.
+ */
+/**
+ * An in-process session store.
+ *
+ * @example
+ *   const sessions = memorySessions();
+ *   await standingAgent({ agent, sessions, host: nodeHost({ port: 8080 }) });
+ */
+export function memorySessions() {
+    const stored = new Map();
+    return {
+        hydrate: (sessionId) => Promise.resolve(stored.get(sessionId)),
+        persist: (sessionId, envelope) => {
+            stored.set(sessionId, envelope);
+            return Promise.resolve();
+        },
+    };
+}
+//# sourceMappingURL=memorySessions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memorySessions.js","sourceRoot":"","sources":["../../../src/hosting/memorySessions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH;;;;;;GAMG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,MAAM,GAAG,IAAI,GAAG,EAA8B,CAAC;IACrD,OAAO;QACL,OAAO,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC9D,OAAO,EAAE,CAAC,SAAS,EAAE,QAAQ,EAAE,EAAE;YAC/B,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;YAChC,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;KACF,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,64 @@
+/**
+ * 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 type { AgentHost, HostHandle, HostHandler } from './types.js';
+/** Options for {@link nodeHost}. */
+export interface NodeHostOptions {
+    /** 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;
+    /** Path that takes a request. Default `'/invoke'`. */
+    readonly invokePath?: string;
+    /** Path that answers a health probe. Default `'/health'`. */
+    readonly healthPath?: string;
+}
+/** What {@link nodeHost}'s `serve()` resolves to — a {@link HostHandle} that also says where it landed. */
+export interface NodeHostHandle 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 this adapter's handle. */
+export interface NodeHost extends AgentHost {
+    serve(handler: HostHandler): Promise<NodeHostHandle>;
+}
+/**
+ * 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 declare function nodeHost(options?: NodeHostOptions): NodeHost;