agentfootprint 7.13.0 → 7.14.0

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

@@ -0,0 +1,79 @@
+/**
+ * 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;
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/hosting/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5D;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,oBAA8B;IAC3C,6BAA6B;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,QAAQ,EAAE,MAAM;CAS7B;AAED;;;;;;;;GAQG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,uBAAiC;IAC9C,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;gBAElB,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;CAapD;AAED;;;;;;;;;GASG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,0BAAoC;IACjD,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,gEAAgE;IAChE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;gBAEhB,QAAQ,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;CAiBlD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,cAAc,GAAG,IAAI,CASnF"}

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

@@ -0,0 +1,54 @@
+/**
+ * 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';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hosting/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAE/E,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;AAErB,YAAY,EACV,SAAS,EACT,kBAAkB,EAClB,sBAAsB,EACtB,cAAc,EACd,UAAU,EACV,WAAW,EACX,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,oBAAoB,EACpB,UAAU,GACX,MAAM,YAAY,CAAC"}

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

@@ -0,0 +1,23 @@
+/**
+ * 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;
+//# sourceMappingURL=memorySessions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memorySessions.d.ts","sourceRoot":"","sources":["../../../src/hosting/memorySessions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEvE;;;;;;GAMG;AACH,wBAAgB,cAAc,IAAI,gBAAgB,CASjD"}

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

@@ -0,0 +1,65 @@
+/**
+ * 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;
+//# sourceMappingURL=nodeHost.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"nodeHost.d.ts","sourceRoot":"","sources":["../../../src/hosting/nodeHost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAMH,OAAO,KAAK,EAAE,SAAS,EAAkB,UAAU,EAAE,WAAW,EAAa,MAAM,YAAY,CAAC;AAEhG,oCAAoC;AACpC,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,2GAA2G;AAC3G,MAAM,WAAW,cAAe,SAAQ,UAAU;IAChD,qEAAqE;IACrE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,2DAA2D;AAC3D,MAAM,WAAW,QAAS,SAAQ,SAAS;IACzC,KAAK,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACtD;AAoBD;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,QAAQ,CAqEhE"}

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

@@ -0,0 +1,63 @@
+/**
+ * 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>;
+//# sourceMappingURL=standingAgent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"standingAgent.d.ts","sourceRoot":"","sources":["../../../src/hosting/standingAgent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAMH,OAAO,KAAK,EACV,UAAU,EAGV,oBAAoB,EAErB,MAAM,YAAY,CAAC;AAGpB;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,CAAC,EAAE,SAAS,UAAU,EACvD,OAAO,EAAE,oBAAoB,CAAC,EAAE,CAAC,GAChC,OAAO,CAAC,EAAE,CAAC,CAuHb"}

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

@@ -0,0 +1,207 @@
+/**
+ * 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.
+ */
+import type { Agent } from '../core/Agent.js';
+import type { AgentRunCheckpoint } from '../core/runCheckpoint.js';
+/**
+ * Something a host can do BEYOND the baseline of "accept a request, deliver one
+ * reply". Read it from {@link AgentHost.capabilities} and branch on it — never
+ * assume it, and never infer it from the adapter's name.
+ *
+ * The union starts at exactly what a shipped adapter can honour today. A name
+ * is added when an adapter can actually keep the promise, never in anticipation
+ * of a transport that does not exist yet: a capability nobody implements is a
+ * promise the library cannot keep, and pre-minting one for an imagined future
+ * transport would bake that transport's assumptions in before it arrives.
+ */
+export type HostCapability = 'streaming';
+/**
+ * One inbound request, as the transport described it.
+ */
+export interface HostRequest {
+    /** What the caller is asking. */
+    readonly input: string;
+    /**
+     * The conversation this request CLAIMS to belong to — caller data, exactly as
+     * the transport declared it (a JSON field, a header, a path segment).
+     *
+     * It is **not identity** and must never be trusted as identity on its own:
+     * anyone who can reach the host can put any string here, including someone
+     * else's. Authenticate the caller by your own means, then check that the
+     * authenticated principal is allowed this session, before you serve it.
+     */
+    readonly sessionId?: string;
+    /**
+     * Transport headers with lower-cased names, as delivered. Present so a
+     * handler can map its own conventions (a correlation id, a tenant) without
+     * the port having to guess which ones matter.
+     */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Aborted when the caller goes away. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * The one reply a request gets. Exactly one of {@link HostReply.complete} or
+ * {@link HostReply.fail} ends it; a second call is ignored rather than allowed
+ * to corrupt the wire.
+ */
+export interface HostReply {
+    /** Deliver the final answer and end the reply. */
+    complete(output: string): void;
+    /**
+     * A piece of the answer, as it is produced.
+     *
+     * Optional on the TYPE so a minimal adapter need not implement it — every
+     * shipped adapter does. Whether the caller SEES the pieces as they arrive is
+     * the whole difference between hosts, and that is what `'streaming'` in
+     * {@link AgentHost.capabilities} reports. A host without it buffers what it is
+     * handed and the authoritative `complete(output)` is what the caller
+     * receives; the buffer is settled by the completion, never sent alongside it,
+     * because a chunk is a preview of the same text and delivering both would
+     * hand the caller the answer twice.
+     *
+     * Handler code is identical either way: emit freely, complete once.
+     */
+    emit?(chunk: string): void;
+    /** End the reply with a failure. */
+    fail(error: Error): void;
+}
+/**
+ * What you hand {@link AgentHost.serve}. Throwing is treated exactly like
+ * calling `reply.fail(err)` — a handler that throws is a failed request, never
+ * a hung one.
+ */
+export type HostHandler = (request: HostRequest, reply: HostReply) => void | Promise<void>;
+/** A live host. */
+export interface HostHandle {
+    /**
+     * Stop taking new requests, let the in-flight ones finish, then release the
+     * transport. Idempotent, so a shutdown hook and an explicit close can
+     * coexist. Requests arriving after it are refused with a
+     * {@link HostClosedError} naming the adapter.
+     */
+    close(): Promise<void>;
+}
+/**
+ * The port: something that can carry requests to one handler and carry its
+ * replies back.
+ */
+export interface AgentHost {
+    /**
+     * Which adapter this is. Every refusal names it, so an error tells you WHO
+     * refused rather than leaving you to guess which layer you are looking at.
+     */
+    readonly name: string;
+    /** What this adapter can do beyond the baseline. Feature-detect; never assume. */
+    readonly capabilities: readonly HostCapability[];
+    /** Start serving. Resolves once the host is actually live. */
+    serve(handler: HostHandler): Promise<HostHandle>;
+}
+/**
+ * A conversation packed for storage.
+ *
+ * `format` names WHAT is inside, so a reader that does not know the shape
+ * refuses BY NAME instead of restoring a conversation it cannot actually read.
+ * Formats are ADDED, never redefined: an old runtime meeting a new format says
+ * so and stops, which is the only safe thing it can do with a payload it cannot
+ * interpret.
+ *
+ * `'conversation-v1'` stores a conversation and only a conversation. A run that
+ * paused mid-flow is a conversation PLUS an engine checkpoint, and this format
+ * has nowhere to put the second half — which is why `standingAgent` refuses to
+ * store a paused run rather than storing half of it. Carrying a pause would be
+ * a NEW format name in this same envelope, read by a runtime that knows it and
+ * refused by name everywhere else. That is what the version field is for.
+ */
+export interface CheckpointEnvelope {
+    /** Names the shape of `data`. Unknown values are refused, never guessed at. */
+    readonly format: 'conversation-v1';
+    /** The conversation itself — an `AgentRunCheckpoint` for `'conversation-v1'`. */
+    readonly data: AgentRunCheckpoint;
+    /** Wall-clock when it was packed. Diagnostic. */
+    readonly savedAt: number;
+}
+/**
+ * Why a session is being woken.
+ *
+ * One member, because one thing in this release can actually fire it: a request
+ * arrived for that session. Naming reasons nothing can produce would be an
+ * interface describing a system that does not exist.
+ */
+export type WakeReason = 'invoke';
+/**
+ * The port: where a conversation lives between requests.
+ *
+ * Deliberately two required methods. Anything a real store also wants — a TTL,
+ * a scan, a delete — is that store's own API, not a demand this port makes of
+ * every store that will ever implement it.
+ */
+export interface SessionLifecycle {
+    /** The stored conversation, or `undefined` for a session that has none yet. */
+    hydrate(sessionId: string): Promise<CheckpointEnvelope | undefined>;
+    /** Store the conversation for this session. Last write wins. */
+    persist(sessionId: string, envelope: CheckpointEnvelope): Promise<void>;
+    /**
+     * Called once per served request, before `hydrate`, for stores that need to
+     * spin something up before they can answer. Errors from it fail the request —
+     * a store that could not wake cannot be read from either.
+     */
+    onWake?(sessionId: string, reason: WakeReason): void | Promise<void>;
+}
+/**
+ * What to do when a request arrives for a session that already has a run in
+ * flight.
+ *
+ *  - `'reject'` (default) — refuse it, naming the run that is already going.
+ *    A user who double-submits gets one answer and one refusal, not two runs
+ *    racing to write the same conversation.
+ *  - `'enqueue'` — queue it. It starts after the active run has persisted, so
+ *    the second turn sees the first turn's stored state rather than the state
+ *    it was about to overwrite.
+ *
+ * This governs the SAME session only. A request for a different session is
+ * never refused — there is nothing wrong with it; it simply waits its turn.
+ */
+export type ConcurrentInvokePolicy = 'reject' | 'enqueue';
+/**
+ * Options for {@link standingAgent}.
+ *
+ * Generic in the host's own handle type so composing does not cost you what
+ * the adapter told you. `nodeHost` hands back the URL it actually bound —
+ * which is the only way to find out when you asked for port `0` — and passing
+ * it through `standingAgent` keeps that, without the port having to know that
+ * "a URL" is a thing some adapters have.
+ */
+export interface StandingAgentOptions<TH extends HostHandle = HostHandle> {
+    /**
+     * The agent that answers. ONE instance, shared by every session — which is
+     * why the composer runs one request at a time (see
+     * {@link ConcurrentInvokePolicy}).
+     */
+    readonly agent: Agent;
+    /** Where conversations live between requests. */
+    readonly sessions: SessionLifecycle;
+    /** What carries requests in. */
+    readonly host: AgentHost & {
+        serve(handler: HostHandler): Promise<TH>;
+    };
+    /** Default `'reject'`. See {@link ConcurrentInvokePolicy}. */
+    readonly onConcurrentInvoke?: ConcurrentInvokePolicy;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "7.13.0",
+  "version": "7.14.0",
   "description": "The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",
@@ -276,6 +276,16 @@
         "default": "./dist/identity.js"
       }
     },
+    "./hosting": {
+      "import": {
+        "types": "./dist/esm/hosting/index.d.ts",
+        "default": "./dist/esm/hosting/index.js"
+      },
+      "require": {
+        "types": "./dist/types/hosting/index.d.ts",
+        "default": "./dist/hosting/index.js"
+      }
+    },
     "./reliability": {
       "import": {
         "types": "./dist/esm/reliability/index.d.ts",
@@ -381,6 +391,9 @@
       "identity": [
         "./dist/types/identity.d.ts"
       ],
+      "hosting": [
+        "./dist/types/hosting/index.d.ts"
+      ],
       "reliability": [
         "./dist/types/reliability/index.d.ts"
       ],