agentfootprint 7.24.0 → 7.25.0

package/dist/esm/hosting/index.js

@@ -1,13 +1,17 @@
 /**
- * agentfootprint/hosting — the two ports between an agent and the place it runs.
+ * agentfootprint/hosting — the 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.
+ * a month differ in a few things: something has to carry requests to it,
+ * something sometimes has to hold a channel OPEN to it, and the conversation
+ * has to outlive the request. This subpath is those things as **ports**, plus
+ * local adapters that prove the ports work, plus the composer that wires the
+ * request half together.
  *
  *   `AgentHost`         — something can call me.
+ *   `ConversationHost`  — something can talk to me, both ways, until one of us
+ *                         ends it. `HostRequest → HostReply` is one exchange;
+ *                         some doors are not.
  *   `SessionLifecycle`  — the conversation outlives the request.
  *   `standingAgent`     — hydrate → resume-or-fresh → persist → reply.
  *
@@ -34,6 +38,17 @@
  *     re-decides. Pass `server` and it attaches to a `node:http` server YOU
  *     own instead of binding one — for the container that gets a single port
  *     and must serve a WebSocket upgrade (or anything else) beside the agent.
+ *   • `host.serveConversations(handler)` — the conversation door, on every
+ *     adapter built on `httpHost` that was given a `conversationPath`.
+ *     `nodeHost` serves it on `/conversation` with a real WebSocket
+ *     implementation and **no dependency to install**, sharing the socket with
+ *     `/invoke`. Frames are STRINGS at the port; what they mean is your
+ *     protocol's business, not this port's.
+ *   • `ConversationLimits` — the ceilings a door DECLARES
+ *     (`maxFrameBytes`, `idleMs`, `maxPendingBytes`) so the layer above can
+ *     chunk or heartbeat on its own protocol. The port does neither, on
+ *     purpose: hiding a cap inside auto-chunking decides a protocol question
+ *     for every consumer at once.
  *   • `memorySessions()` — conversations in a Map, for tests and local dev.
  *   • `standingAgent({ agent, sessions, host, durability? })` — the composer.
  *   • `toEnvelope` / `readEnvelope` — pack a conversation, and refuse by name to
@@ -63,5 +78,5 @@ export { httpHost, headerValue } from './httpHost.js';
 export { memorySessions } from './memorySessions.js';
 export { toEnvelope, toPausedEnvelope, readEnvelope, readPausedRun, checkEnvelope, } from './envelope.js';
 export { standingAgent } from './standingAgent.js';
-export { requireCapability, HostClosedError, ConcurrentRunError, PauseNotCarriedError, AwaitingDecisionError, NoPendingAskError, UnreadableEnvelopeError, } from './errors.js';
+export { requireCapability, HostClosedError, ConcurrentRunError, PauseNotCarriedError, AwaitingDecisionError, NoPendingAskError, UnreadableEnvelopeError, ConversationClosedError, FrameTooLargeError, } from './errors.js';
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/hosting/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAEH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGnD,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAStD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/hosting/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AAEH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGnD,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAWtD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,uBAAuB,EACvB,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,aAAa,CAAC"}

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

@@ -21,6 +21,13 @@
  * instead of binding one, so a WebSocket upgrade or your own routes can share
  * the port. `close()` then detaches and drains, and your socket stays up.
  *
+ * **There is a third door.** `serveConversations(handler)` takes WebSocket
+ * upgrades on `/conversation` and hands each one to your handler as a
+ * `HostConversation` — a channel that stays open, for the callers that cannot
+ * host an inbound endpoint and dial out instead. It shares this host's socket
+ * with `/invoke` and `/health`, needs nothing installed, and declares what it
+ * caps.
+ *
  * **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
@@ -36,6 +43,7 @@
  */
 /// <reference types="node" />
 import { type HttpHost, type HttpHostHandle, type HttpWire } from './httpHost.js';
+import type { ConversationLimits } from './types.js';
 /** Options for {@link nodeHost}. */
 export interface NodeHostOptions {
     /** Port to bind. Default `8080`. Pass `0` for an ephemeral port. Refused alongside `server`. */
@@ -46,6 +54,21 @@ export interface NodeHostOptions {
     readonly invokePath?: string;
     /** Path that answers a health probe. Default `'/health'`. */
     readonly healthPath?: string;
+    /**
+     * Path that takes a conversation upgrade. Default `'/conversation'` — this
+     * adapter's own word, chosen the way its other two paths were, and named for
+     * what it carries rather than for what any runtime calls it.
+     */
+    readonly conversationPath?: string;
+    /**
+     * What the conversation door caps. Defaults to one mebibyte per frame and one
+     * mebibyte held before a handler subscribes — declared, so
+     * `host.conversationLimits` always reports what is really enforced. This
+     * adapter declares no `idleMs`: it does not idle a conversation out, and
+     * reporting a ceiling it neither imposes nor sits behind would be inventing
+     * a fact.
+     */
+    readonly conversationLimits?: ConversationLimits;
     /**
      * A `node:http` server **you** own, already listening. Given one, this
      * adapter attaches its two routes to it instead of binding a socket of its

package/dist/esm/hosting/nodeHost.js

@@ -21,6 +21,13 @@
  * instead of binding one, so a WebSocket upgrade or your own routes can share
  * the port. `close()` then detaches and drains, and your socket stays up.
  *
+ * **There is a third door.** `serveConversations(handler)` takes WebSocket
+ * upgrades on `/conversation` and hands each one to your handler as a
+ * `HostConversation` — a channel that stays open, for the callers that cannot
+ * host an inbound endpoint and dial out instead. It shares this host's socket
+ * with `/invoke` and `/health`, needs nothing installed, and declares what it
+ * caps.
+ *
  * **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
@@ -34,7 +41,7 @@
  * never quietly drift apart on what `close()` drains or what a handler that
  * throws does. `types.ts` knows none of it either way.
  */
-import { httpHost } from './httpHost.js';
+import { headerValue, httpHost, } from './httpHost.js';
 const HOST_NAME = 'nodeHost';
 /**
  * This adapter's own JSON dialect: `{ input, sessionId? }` in, `{ output }`
@@ -66,6 +73,15 @@ export const jsonWire = {
     failure: (error, code) => ({ error, ...(code !== undefined && { code }) }),
     chunk: (text) => ({ text }),
     awaiting: (pending) => ({ awaiting: pending }),
+    readConversation(facts) {
+        // A handshake has no body, so this dialect names the two places a session
+        // id can be: the header a server-side caller sets, and the query a BROWSER
+        // has to use because the WebSocket API gives it no way to set a header.
+        // Header wins, so a caller that sets both is not surprised by which one the
+        // server preferred — the same rule the request dialect uses for body-vs-header.
+        const sessionId = headerValue(facts, 'x-session-id') ?? facts.query.get('sessionId') ?? undefined;
+        return { ...(sessionId !== undefined && sessionId.length > 0 && { sessionId }) };
+    },
 };
 /**
  * An HTTP host for one handler.
@@ -87,6 +103,10 @@ export function nodeHost(options = {}) {
         // particular runtime's container-contract path literal.
         invokePath: options.invokePath ?? '/invoke',
         healthPath: options.healthPath ?? '/health',
+        conversationPath: options.conversationPath ?? '/conversation',
+        ...(options.conversationLimits !== undefined && {
+            conversationLimits: options.conversationLimits,
+        }),
         // Passed through as given, never defaulted: with a caller-owned server
         // there is no port to default, and a port passed WITH one is a caller who
         // believes something untrue about where their agent answers — `httpHost`

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

@@ -1 +1 @@
-{"version":3,"file":"nodeHost.js","sourceRoot":"","sources":["../../../src/hosting/nodeHost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,QAAQ,EAAqD,MAAM,eAAe,CAAC;AAqC5F,MAAM,SAAS,GAAG,UAAU,CAAC;AAE7B;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAa;IAChC,WAAW,CAAC,KAAK;QACf,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3E,wEAAwE;QACxE,4EAA4E;QAC5E,MAAM,QAAQ,GAAG,OAAO,KAAK,CAAC,IAAI,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;QAC7F,MAAM,SAAS,GAAG,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;QAC5D,4EAA4E;QAC5E,wEAAwE;QACxE,0CAA0C;QAC1C,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC;QACrC,OAAO;YACL,KAAK;YACL,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;YAC7C,GAAG,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,CAAC;SAC5C,CAAC;IACJ,CAAC;IACD,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAClD,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,OAAO,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAC1E,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;IAC3B,QAAQ,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;CAC/C,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,QAAQ,CAAC,UAA2B,EAAE;IACpD,OAAO,QAAQ,CAAC;QACd,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,QAAQ;QACd,yEAAyE;QACzE,wDAAwD;QACxD,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,SAAS;QAC3C,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,SAAS;QAC3C,uEAAuE;QACvE,0EAA0E;QAC1E,yEAAyE;QACzE,0DAA0D;QAC1D,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;QACzD,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrE,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;KAChE,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"nodeHost.js","sourceRoot":"","sources":["../../../src/hosting/nodeHost.ts"],"names":[],"mappings":"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"}

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

@@ -1,10 +1,12 @@
 /**
- * hosting/types — the two ports an agent needs to stand up and stay up.
+ * hosting/types — the 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.
+ * `AgentHost` is "something can call me". `ConversationHost` is "something can
+ * TALK to me" — a door that stays open, because `HostRequest → HostReply` is
+ * one exchange and some doors are not. `SessionLifecycle` is "the conversation
+ * outlives the request". All three are deliberately written in the vocabulary
+ * every transport and every store already has — an input, a reply, a frame, 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
@@ -22,6 +24,8 @@ import type { Agent } from '../core/Agent.js';
 import type { CheckInRequest } from '../core/checkin.js';
 import type { MiddlewareAsk } from '../core/pause.js';
 import type { AgentRunCheckpoint } from '../core/runCheckpoint.js';
+import type { Unsubscribe } from '../events/dispatcher.js';
+export type { Unsubscribe };
 /**
  * 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
@@ -32,8 +36,18 @@ import type { AgentRunCheckpoint } from '../core/runCheckpoint.js';
  * 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.
+ *
+ *  - `'streaming'` — the caller SEES `reply.emit(...)` pieces as they arrive.
+ *  - `'conversation'` — this host can also carry a two-way channel that stays
+ *    open ({@link ConversationHost.serveConversations}). It joined the union
+ *    when two shipped adapters honoured it, not when it was imagined.
+ *
+ * Declared at CONSTRUCTION and static thereafter, which is a constraint worth
+ * knowing about: a capability whose truth depended on what happened to be
+ * installed at call time could not be declared here honestly, so an adapter
+ * that can only sometimes keep a promise does not make it.
  */
-export type HostCapability = 'streaming';
+export type HostCapability = 'streaming' | 'conversation';
 /**
  * One inbound request, as the transport described it.
  */
@@ -164,6 +178,198 @@ export interface AgentHost {
     /** Start serving. Resolves once the host is actually live. */
     serve(handler: HostHandler): Promise<HostHandle>;
 }
+/**
+ * A door that stays open: one session-scoped, two-way channel.
+ *
+ * The distinction this type exists for, in the words of the field report that
+ * bought it: **`HostRequest → HostReply` is one exchange, and this door is a
+ * conversation.** A request has one reply and then it is over. A conversation
+ * has neither side taking turns by rule, no reply count, and an end that either
+ * side can call.
+ *
+ * ── Frames are STRINGS here, deliberately ───────────────────────────────────
+ * What the frames MEAN is the consumer's contract, not this port's: one
+ * consumer pushes tool calls down the channel, another speaks a standardized
+ * agent↔UI protocol, a third exchanges long-running task updates. JSON is what
+ * all three happen to use and none of them agree on beyond that, so the port
+ * carries text and stays out of it. Binary is a capability question, deferred
+ * until a consumer needs it rather than guessed at now.
+ *
+ * ── What is NOT here ────────────────────────────────────────────────────────
+ * No authentication, no chunking, no heartbeat, no protocol framing. See
+ * {@link ConversationLimits} for why the last two are absences with a reason
+ * rather than gaps.
+ */
+export interface HostConversation {
+    /**
+     * The conversation this channel CLAIMS to belong to — caller data, exactly as
+     * the transport declared it, and **not identity**. The whole of
+     * {@link HostRequest.sessionId}'s warning applies here word for word: anyone
+     * who can reach the host can put any string here, including someone else's.
+     *
+     * A conversation and a request carrying the same string are the same
+     * session's, as far as this port is concerned. What that entitles either of
+     * them to is yours to decide, above the port.
+     */
+    readonly sessionId?: string;
+    /**
+     * Transport headers with lower-cased names, as delivered — so a handler can
+     * map its own conventions without the port guessing which ones matter.
+     *
+     * This is also where an adapter puts credentials that its transport spells
+     * some other way: a bearer token a browser could only send as a subprotocol
+     * arrives here as an ordinary `authorization` header, because a port field
+     * spelled the way one vendor spells it is how a port stops being one.
+     */
+    readonly headers?: Readonly<Record<string, string>>;
+    /**
+     * Host → far side. One frame, delivered whole.
+     *
+     * Refuses BY NAME rather than dropping quietly in two cases: a conversation
+     * that has ended (`ConversationClosedError`), and a frame past the ceiling the
+     * adapter declared (`FrameTooLargeError`). A dropped frame on a channel that
+     * looks open is the failure mode this port exists to make impossible.
+     */
+    send(frame: string): void;
+    /**
+     * Far side → host. Returns an unsubscribe.
+     *
+     * Frames that arrive BEFORE the first subscriber are held and delivered to
+     * it, up to the bound the adapter declares
+     * ({@link ConversationLimits.maxPendingBytes}) — an `async` handler that
+     * awaits anything before subscribing would otherwise silently lose the far
+     * side's opening frame, which on a channel whose first frame is a greeting is
+     * every conversation.
+     */
+    onFrame(cb: (frame: string) => void): Unsubscribe;
+    /**
+     * The end, delivered exactly once per subscriber — including to a subscriber
+     * that arrives after it already happened, which is answered immediately
+     * rather than never.
+     */
+    onClose(cb: (reason: ConversationClose) => void): Unsubscribe;
+    /**
+     * End it politely: flush what is queued, tell the far side, then stop.
+     * Idempotent — the first call owns the ending and later ones do nothing.
+     */
+    close(reason?: string): void;
+}
+/**
+ * How a conversation ended, in terms every transport can answer.
+ *
+ * `by` is the fact a consumer branches on and the reason there is no numeric
+ * code here: what all three of "a browser-parked channel", "a UI protocol" and
+ * "a long-running task exchange" need to know is whether the far side said
+ * goodbye, whether we did, or whether it broke — and a transport's own numbers
+ * answer that only if you already know that transport. Adapters render their
+ * own vocabulary (a close code, a timeout, a ceiling) into {@link reason}.
+ */
+export interface ConversationClose {
+    /**
+     *  - `'far-side'` — they ended it.
+     *  - `'host'` — we did, through {@link HostConversation.close}.
+     *  - `'transport'` — nobody ended it; it broke or timed out.
+     */
+    readonly by: 'far-side' | 'host' | 'transport';
+    /** What was said about it, when anything was. */
+    readonly reason?: string;
+}
+/**
+ * What you hand {@link ConversationHost.serveConversations} — called once per
+ * conversation, with that conversation.
+ *
+ * Throwing ends THAT conversation with a stated reason and never the host: one
+ * caller's bad frame is not an outage.
+ */
+export type ConversationHandler = (conversation: HostConversation) => void | Promise<void>;
+/**
+ * The ceilings a door imposes, **declared rather than discovered**.
+ *
+ * ── Why the port does not just handle them ──────────────────────────────────
+ * A transport that caps frame size or idles out must SAY so, and then get out
+ * of the way. Hiding a 32KB cap inside auto-chunking would be the adapter
+ * deciding a protocol question for every consumer at once — how a message is
+ * split, how the pieces are numbered, how the far side knows the last one has
+ * landed — and those answers differ per consumer. Same for liveness: a
+ * heartbeat is frames on somebody's protocol, and inventing them puts bytes on
+ * the wire that the consumer's parser never agreed to.
+ *
+ * So the port's job is to make the ceiling VISIBLE and let the layer above act:
+ * chunk above the port, heartbeat above the port.
+ *
+ * ── Enforced vs reported ────────────────────────────────────────────────────
+ * A door enforces what it IS and reports what it SITS BEHIND, and the doc on
+ * each field says which. Absent means "no ceiling this adapter knows of", never
+ * "no ceiling" — the runtime in front of you may have one it never told us
+ * about.
+ */
+export interface ConversationLimits {
+    /**
+     * Largest single frame this door carries, in bytes of UTF-8.
+     *
+     * **Enforced, both directions**, by the door that declares it: an inbound
+     * frame past it ends the conversation with a stated reason, and
+     * {@link HostConversation.send} past it refuses by name instead of
+     * truncating or silently splitting.
+     *
+     * A frame the transport delivered in pieces counts in TOTAL — the port's
+     * frame is the whole message, not the transport's packet, so fragmentation
+     * cannot be used to walk around the ceiling.
+     */
+    readonly maxFrameBytes?: number;
+    /**
+     * How long the transport tolerates silence before it closes the channel.
+     *
+     * **Reported, not imposed.** The door declaring it usually is not the thing
+     * enforcing it — a runtime's front door idles a socket out long before the
+     * process inside notices — and a consumer that needs the channel to stay up
+     * sends its own heartbeat frames on its own protocol. Making that possible is
+     * the whole reason this number is written down.
+     */
+    readonly idleMs?: number;
+    /**
+     * How much the door holds for you before the first
+     * {@link HostConversation.onFrame} subscriber exists, in bytes.
+     *
+     * **Enforced**, and a ceiling on the DOOR rather than on the transport: the
+     * pre-subscribe buffer that stops an `async` handler from losing the opening
+     * frame is a queue somebody else fills and this process pays for, so it gets
+     * a number and a stated overflow instead of growing until the host dies. Past
+     * it, the conversation ends with a reason naming this bound.
+     *
+     * Bounded in BYTES rather than in frames on purpose: a frame count would
+     * still admit `count × maxFrameBytes` of memory, which is the same unbounded
+     * queue with an extra step.
+     */
+    readonly maxPendingBytes?: number;
+}
+/**
+ * The port: something that can carry conversations to one handler.
+ *
+ * It sits BESIDE {@link AgentHost} rather than inside it, because a transport
+ * that can carry a request cannot necessarily carry a conversation, and one
+ * that carries conversations need not answer requests at all. A host that does
+ * both implements both and declares `'conversation'` in
+ * {@link AgentHost.capabilities}.
+ */
+export interface ConversationHost {
+    /** Which adapter this is. Every refusal names it. */
+    readonly name: string;
+    /** What this adapter can do beyond the baseline. Feature-detect; never assume. */
+    readonly capabilities: readonly HostCapability[];
+    /**
+     * What this door caps, as declared facts. Absent means this adapter knows of
+     * no ceiling — never that there is none.
+     */
+    readonly conversationLimits?: ConversationLimits;
+    /**
+     * Start taking conversations. Resolves once the door is actually open.
+     *
+     * The handle's `close()` ends every live conversation politely and then
+     * releases the door.
+     */
+    serveConversations(handler: ConversationHandler): Promise<HostHandle>;
+}
 /**
  * A session packed for storage.
  *

package/dist/esm/hosting/types.js

@@ -1,10 +1,12 @@
 /**
- * hosting/types — the two ports an agent needs to stand up and stay up.
+ * hosting/types — the 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.
+ * `AgentHost` is "something can call me". `ConversationHost` is "something can
+ * TALK to me" — a door that stays open, because `HostRequest → HostReply` is
+ * one exchange and some doors are not. `SessionLifecycle` is "the conversation
+ * outlives the request". All three are deliberately written in the vocabulary
+ * every transport and every store already has — an input, a reply, a frame, 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

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

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

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

@@ -0,0 +1,101 @@
+/**
+ * hosting/webSocketConversation — one upgraded socket, presented as a
+ * {@link HostConversation}.
+ *
+ * This is the whole adapter side of the conversation port: it takes the
+ * `'upgrade'` event a `node:http` server hands it, answers the handshake, and
+ * turns the frames flowing over the socket into the six-member port a handler
+ * sees. Everything protocol-shaped lives in `webSocketFrames.ts`; everything
+ * port-shaped lives in `types.ts`; this file is the join.
+ *
+ * ── The laws it keeps, all of them pinned by tests ───────────────────────────
+ *  - **A path this door does not own is not touched.** `node:http` calls EVERY
+ *    `'upgrade'` listener for every upgrade, exactly as it calls every
+ *    `'request'` listener — so a caller's own protocol lives beside this one on
+ *    the same socket. Whether an unclaimed path gets an answer is the caller's
+ *    business on a server they own, and this door's only on a server it owns.
+ *  - **Frames that arrive before the handler subscribes are held, up to a
+ *    declared bound.** An `async` handler that awaits before calling `onFrame`
+ *    would otherwise lose the far side's opening frame. The bound is in BYTES
+ *    and overflow ends the conversation with a stated reason, because an
+ *    unbounded queue somebody else fills is a way to kill this process, and an
+ *    undeclared ceiling is the exact thing the declared-ceilings rule exists to
+ *    forbid.
+ *  - **`close()` ends every live conversation before the socket is released.**
+ *    Measured, not assumed: an upgraded socket keeps `server.close()` waiting
+ *    forever, so a door that let go of its conversations would hang the whole
+ *    shutdown.
+ *  - **The port's frame is the whole message.** A message the transport
+ *    delivered in fragments counts against `maxFrameBytes` in total, so
+ *    fragmentation cannot be used to walk around the ceiling.
+ *
+ * Pattern: Adapter. Role: outer ring, one transport.
+ */
+/// <reference types="node" />
+/// <reference types="node" />
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import type { ConversationHandler, ConversationLimits } from './types.js';
+/**
+ * What a wire read out of one handshake — the conversation half of a
+ * deployment's dialect.
+ *
+ * There is no body to read here, which is the whole difference from a request:
+ * a handshake is a URL and some headers, so a dialect that wants a session id
+ * or a credential has to find it in those.
+ */
+export interface ConversationHandshake {
+    /** The session this conversation claims. Caller data; never identity. */
+    readonly sessionId?: string;
+    /**
+     * Headers to merge OVER the raw lower-cased ones the transport delivered.
+     *
+     * This is how an adapter maps its own spelling into the port's vocabulary —
+     * a credential a browser could only send as a subprotocol becomes an ordinary
+     * `authorization` header here. The raw headers are never removed, so nothing
+     * a mapping did not understand is lost.
+     */
+    readonly headers?: Readonly<Record<string, string>>;
+    /**
+     * The subprotocol to echo in the 101, when this dialect selects one.
+     *
+     * Selecting is the wire's job because only the wire read the offer. Echoing
+     * something the client did not offer makes the client fail the connection.
+     */
+    readonly protocol?: string;
+}
+/** Everything the door needs to answer one upgrade. */
+export interface ConversationDoorOptions {
+    /** The adapter's name — every refusal carries it. */
+    readonly hostName: string;
+    /** The path this door owns. Anything else is not ours. */
+    readonly path: string;
+    /** The ceilings this door declares, already defaulted. */
+    readonly limits: ConversationLimits;
+    /** This deployment's handshake dialect. Absent ⇒ raw headers and no session. */
+    readonly readConversation?: (facts: HandshakeFacts) => ConversationHandshake;
+    /** Where a new conversation goes. */
+    readonly handler: ConversationHandler;
+    /** Whether the host is still taking conversations — false after `close()`. */
+    readonly accepting: () => boolean;
+}
+/** What a handshake dialect may read. Deliberately the same shape a request wire gets, minus the body. */
+export interface HandshakeFacts {
+    /** Header names lower-cased. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** The query string, already parsed — where a browser has to put things it cannot header. */
+    readonly query: URLSearchParams;
+}
+/** A door: hand it upgrades, close it when you are done. */
+export interface ConversationDoor {
+    /**
+     * Take one upgrade, or decline it. Returns whether this door claimed the
+     * path — the caller decides what an unclaimed upgrade deserves.
+     */
+    handleUpgrade(request: IncomingMessage, socket: Duplex): boolean;
+    /** End every live conversation politely, then resolve. */
+    closeAll(reason: string): Promise<void>;
+    /** How many conversations are open right now. */
+    readonly liveCount: number;
+}
+export declare function conversationDoor(options: ConversationDoorOptions): ConversationDoor;