/** * hosting/types — the ports an agent needs to stand up and stay up. * * `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 * 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 { FlowchartCheckpoint } from 'footprintjs'; import type { Agent } from '../core/Agent.js'; import type { AskComponent } from '../tools/askComponent.js'; import type { CheckInRequest } from '../core/checkin.js'; import type { MiddlewareAsk } from '../core/pause.js'; import type { AgentRunCheckpoint } from '../core/runCheckpoint.js'; import type { AwaitingInput } from '../tools/inputRequest.js'; import type { Unsubscribe } from '../events/dispatcher.js'; import type { ToolArtifacts } from '../artifacts/capability.js'; import type { ArtifactWireRequest, ArtifactWireResult } from './artifactWire.js'; import type { AnswerAccountsOptions } from './answerAccounts.js'; import type { DoorIdentity } from './identityVerification.js'; import type { AdmissionPolicy } from './admission.js'; import type { IngressSink } from './ingressRecord.js'; import type { RequestSealer } from './requestSealing.js'; import type { SessionSummary, SessionWireRequest, SessionWireResult } from './sessionWire.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 * 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. * * - `'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' | 'conversation'; /** * One inbound request, as the transport described it. */ export interface HostRequest { /** What the caller is asking. */ readonly input: string; /** * A person's answer to an outstanding {@link PendingAsk} — and **the one * thing that distinguishes a resume from a new message.** * * Present ⇒ this request answers the run that paused on this session. Absent * ⇒ this request is a new message. That is the whole contract, and it is a * FIELD rather than an inference on purpose: reading approval out of prose * ("yes, go ahead") is a guess, and a guess is not something a consent gate * may be built on. * * The port never interprets it. It is handed to `agent.resume(checkpoint, * decision)` exactly as it arrived — a {@link CheckInRequest} or a middleware * `ask` is answered with the shipped `checkInApproved()` / `checkInDeclined()` * vocabulary, built from the pending ask (`checkInApproved({ request: * pending.checkIn, by })`) so it names the request it answers, and the resume * refuses it for any other request or a second time (`ResumeDecisionError`); * a plain `askHuman` pause is answered with whatever that tool's author * documented. Typed `unknown` because the library does not get to decide what * a tool asked for. */ readonly decision?: unknown; /** * 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. * * Bounded at every door the library ships: an id longer than * `MAX_SESSION_ID_LENGTH` or holding a control character is refused before * any handler sees the request, because it travels into every stored row, * log line and trace span of the conversation. */ readonly sessionId?: string; /** * WHO the transport says is calling — the end user's id, exactly as the * transport declared it (9.12.0). * * A different fact from {@link sessionId} beside it, and the difference is * the whole reason it is a second field: a session is a THREAD and this is a * PERSON. One conversation belongs to one user; one user has many * conversations; and an audit trail that reports the thread where the actor * belongs names the wrong party in a way nobody can see from the outside. * * **Absent when absent.** No wire derives it from the session id, from the * body, or from anything else — a request that carried no user is a request * with no `userId`, and inventing one would be worse than reporting none. * * **How much it is worth is the transport's answer, not this port's.** A * managed runtime whose front door authenticates the caller and forwards the * result is a transport whose wire can fill this in, and its adapter does. A * container you expose directly is not: a header there is a string anybody * can send, and the generic JSON wire therefore reads none — a wire that * promoted one to "who did this" would hand every caller the ability to sign * somebody else's name. Which is which is decided in the adapter, by whoever * knows what stands in front of it. */ readonly userId?: string; /** * An artifact operation this request carries INSTEAD of a message (9.23.0) * — `head` (the claim ticket's metadata) or `get` (metadata + payload), for * one ref. * * Its PRESENCE is the discriminant, exactly as {@link decision}'s is: a * request carrying `artifact` redeems a ticket and never starts or resumes * a run — `input` and `decision` do not ride it. A handler that serves * artifacts answers with {@link HostReply.artifact}; a handler that does * not should refuse it by name rather than treat it as a message, because a * redemption silently answered by a model turn is a caller told nothing and * billed anyway. `standingAgent` answers it: the ref is resolved against * the serving agent's store under the requesting session's * identity-composed scope — exactly the scope the run's own tools used. */ readonly artifact?: ArtifactWireRequest; /** * A session-history operation this request carries INSTEAD of a message * (9.26.0) — `list` (the verified caller's own sessions) or `transcript` * (one owned session's messages). * * Its PRESENCE is the discriminant, exactly as {@link artifact}'s is: a * request carrying `session` reads history and never starts or resumes a * run. Both ops REQUIRE a door that verifies identity * ({@link StandingAgentBaseOptions.identity}) — reading "your" conversations * from an unverified header is enumeration — and both are refused by name * where the session store keeps no owner index. */ readonly session?: SessionWireRequest; /** * 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. * * Since 9.26.0 this is also where a door that verifies identity reads the * caller's credential from — `authorization: Bearer `, the one * vocabulary every transport in this package normalizes onto. The port still * does not interpret headers itself; it hands them to whoever was configured * to. */ readonly headers?: Readonly>; /** * The sign-in this request named, as its KEY — set by a transport built * with a sign-in cookie (`httpHost`/`nodeHost` `signIn`), which strips the * cookie itself from {@link headers} before any handler sees them. The key is * the cookie value's SHA-256: the store is keyed by it and it cannot be * turned back into a cookie. Absent when the transport has no sign-in cookie * configured, and when the request carried none. * * Not identity: `verifyRequestIdentity` turns it into one, through the * deployment's sign-in source, exactly as it turns a bearer token into one. */ readonly signInKey?: string; /** Aborted when the caller goes away. */ readonly signal?: AbortSignal; } /** * The one reply a request gets. Exactly one of {@link HostReply.complete}, * {@link HostReply.awaiting}, {@link HostReply.artifact} or * {@link HostReply.fail} ends it; a second call is ignored rather than allowed * to corrupt the wire. * * Three terminals for a RUN, because a run has three ends and only three: it * answered, it stopped to ask a person something, or it failed. Before * `'flowchart-v1'` there was nowhere to keep a paused run, so the middle one * was delivered through `fail` — an error standing in for unfinished work. It * is a terminal of its own now, and a pause is never reported as a failure * again. The fourth terminal ends a request that never was a run: * {@link HostRequest.artifact} redeems a claim ticket, and `artifact(...)` is * how the resolved ticket comes back. */ export interface HostReply { /** Deliver the final answer and end the reply. */ complete(output: string): void; /** * End the reply with **unfinished work**: the run stopped to ask a person * something, the paused run is stored, and a later request carrying * {@link HostRequest.decision} continues it. * * This is not a failure and must not be reported as one. The agent did not * break, no work was lost, and there is nothing to retry — there is a question * outstanding. An adapter that maps this onto a 5xx, an error counter or a * dead-letter queue is telling every dashboard it feeds something that is not * true. * * Optional on the TYPE for the same reason {@link HostReply.emit} is: a * minimal adapter need not implement it. Every shipped adapter does. When it * is absent the composer still STORES the paused run — the store is not the * transport's business — and ends the reply with a named refusal instead, so * the pause is never lost merely because the wire could not describe it. */ awaiting?(pending: PendingAsk): void; /** * End the reply with a **resolved artifact** (9.23.0): the metadata for a * `head`, metadata + payload for a `get`. The terminal a request carrying * {@link HostRequest.artifact} ends through when the ref resolved; a ref * that did not resolve ends through `fail` with the one indistinguishable * not-found refusal. * * Optional on the TYPE for the same reason {@link HostReply.awaiting} is: a * minimal adapter need not implement it, and every shipped adapter does. * When it is absent the composer ends the reply with a named refusal * (`ArtifactNotCarriedError`) instead — the resolution is not lost quietly * merely because the wire could not describe it. */ artifact?(result: ArtifactWireResult): void; /** * End the reply with **resolved session history** (9.26.0): the caller's own * sessions for a `list`, one owned session's messages for a `transcript`. * * The terminal a request carrying {@link HostRequest.session} ends through. * A session the verified caller does not own does not end here — it ends * through `fail` with the one indistinguishable not-found, because "exists * but not yours" is an oracle for which ids are real. * * Optional on the TYPE for the same reason {@link artifact} is: a minimal * adapter need not implement it, and every shipped adapter does. When it is * absent the composer ends the reply with a named refusal * (`SessionsNotCarriedError`) rather than improvising a body shape no client * was written against. */ sessions?(result: SessionWireResult): 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; /** * The turn's artifact store, **already bound** to the scope this request's * claim tickets are redeemed under — so host code that files its OWN * artifacts for a turn (a story, the person's clicks, anything joined to it) * files them where `artifact-get` will look for the same caller, without * ever composing a scope. * * ── Awaited, inside the turn — and bounded ──────────────────────────────── * Not a terminal. The composer calls it exactly ONCE per turn, AWAITS it * while the session's lane is still held, and only then ends the reply with * `complete` or `awaiting` — so a ticket filed here exists before the body * that carries it is composed. Never called for a request that is not a turn * (an artifact redemption, a session op) or for a turn that ends through * `fail`. * * The wait is BOUNDED: the hook and every operation it started must settle * within `turnArtifactsTimeoutMs` (default `TURN_ARTIFACTS_TIMEOUT_MS`, 5 s) * and before the request's own `signal` aborts. Whichever comes first ends * the hand-over: the binding is revoked, what is in flight is NOT cancelled * (it may still land, stamped with this turn's session and run), the cause is * reported, and the terminal is delivered. In the shared `{ agent }` shape * every session waits behind this turn's lane, so the hook's I/O is paid by * everyone — keep it to filing. * * ── Live only for its turn ───────────────────────────────────────────────── * The binding is live while the hand-over is: after the composer has waited * for every operation started through it (a `put` that was not awaited * included), or after the bound ended the wait, it REVOKES it. A verb called * later rejects with `TurnArtifactsExpiredError` — a rejection already * handled, so a floating late call cannot crash the process — and is reported * as `'expired'`. File inside the hook; never hold the binding. * * ── Never decides the reply, never silent ────────────────────────────────── * A hook that throws or rejects, an operation that fails (awaited or not), the * bound, the abort and a late call are all put on the serving agent's stream * as `agentfootprint.artifacts.hand_over_failed { cause, op?, errorClass?, * errorCode? }` — class only, stamped with the session — and the FIRST of * them on the ingress record (`IngressRecord.turnArtifactsFailure`). None of * them turns a delivered answer, or a stored question, into a failure. * Awaiting another turn of the same standing agent from inside the hook can * never finish (that turn queues behind this one); the bound ends the wait. * ── The scope, and what it is not ───────────────────────────────────────── * The scope is the one {@link HostRequest.artifact} redemption re-composes * for this request: the verified user (or the transport's own `userId` when * no verifier is configured), the stored conversation's tenant and * namespace, else the session rung `{ conversationId: sessionId }`. One * owner of that tuple — the library — so an app cannot derive a slightly * different one. It is where the DOOR redeems, which is not always where the * run filed its own recording: at an unverified door a conversation that * carries an identity of its own can put the recording elsewhere (the known * edges are listed in `src/hosting/README.md`). * * Every put is stamped `origin: { runId }` with the run this turn executed, * or carries no origin when it executed none (a partial answer to an input * request, or its cancellation); a caller's own `origin` is always dropped. * A PAUSED turn's run id names a run that files no recording — a pause is * not a finished run, and the resumed run records under its own id — so a * reader joining on it must say "paused, no recording", not "missing". Each * filing lands on the serving agent's record as * `agentfootprint.artifacts.minted` with no `tool` field, its meta naming the * session and the run it was filed FOR — captured when the binding was * built, never read from whichever run is live when a late fact lands. * * When there is nothing to bind, the value SAYS so rather than inventing a * scope — see {@link TurnArtifacts}. * * Optional, and feature-detected: a host that does not implement it is * served exactly as before. * * @example File a turn's story and carry its ticket on the reply * turnArtifacts: async (turn) => { * if (!turn.bound) return; * const story = await turn.artifacts.put({ kind: 'story/turn', mediaType: 'application/json', data }); * ticketForThisReply = story.ref; // the body `complete` composes next can carry it * }, */ turnArtifacts?(turn: TurnArtifacts): void | Promise; /** End the reply with a failure. */ fail(error: Error): void; } /** * What {@link HostReply.turnArtifacts} is handed: this turn's artifact store, * bound to exactly one scope — or the reason there is none. * * `artifacts` has the shape a tool gets as `ctx.artifacts`: five verbs, none * of which takes a scope, so a binding can reach this request's scope and no * other. The scope itself is deliberately NOT on the value — a tuple a host * can read is a tuple a host can copy, edit and put under. The verbs work only * while the hand-over is live (then `TurnArtifactsExpiredError`, already * handled, reported as `'expired'`). * * A filing's `origin.runId` is the run the turn executed — none for a turn that * executed none. On a PAUSED turn that run files no recording (a pause is not a * finished run; the resumed run records under its own id), so a reader joining * a filing to "its recording" by run id must read the absence as "paused, no * recording", never as "missing". * * `bound: false` says why nothing was bound, checked in this order: * - `'no-session'` — the request named no session. An anonymous run scopes * its artifacts to its own run id, which no later request can present, so * there is no scope to bind — and none is invented. Wins over `'no-store'` * when both apply. * - `'no-store'` — the serving agent has no artifact store. */ export type TurnArtifacts = { readonly bound: true; readonly artifacts: ToolArtifacts; } | { readonly bound: false; readonly reason: 'no-session' | 'no-store'; }; /** * What {@link StandingAgentHandle.artifactsForRequest} reads off a request: * WHICH conversation (`sessionId`) and WHO is asking — the transport's headers * (the bearer token a configured verifier checks), the sign-in KEY (a sign-in * the server keeps) and, at a door with no verifier, its `userId` claim. The * same fields, read the same way, as a turn or a redemption on the wire. * * The fields are {@link HostRequest}'s own, so inside a handler the request the * transport built goes in AS IT IS — `handle.artifactsForRequest(request)` — * and no credential can be left behind. A {@link HostConversation} goes in the * same way. * * `headers` takes a Node / Express `IncomingHttpHeaders` as it is: a value * that arrived as an array (a repeated header) is not read, and a REPEATED * `authorization` — two credentials — is refused as `'unverified'`. */ export interface ArtifactsForRequestInput { readonly sessionId?: string; readonly headers?: Readonly>; readonly userId?: string; /** * The sign-in this request named, as its KEY — {@link HostRequest.signInKey}, * or on an app's own route `readSignIn(req.headers, cookieName).key`. Never * the cookie: the seam does not read cookies, and a key cannot be turned * back into one. * * Verified exactly as the turn door verifies it (`verifyRequestIdentity` * with the key): an ended, expired or unknown sign-in is `'unverified'` * (`'expired'`), a sign-in store that cannot answer is `'unavailable'`, and * a key together with a bearer token is `'unverified'` * (`'two-credentials'`). Absent, the request is judged as one that carried * no sign-in — at a door that requires a credential, `'unverified'` * (`'no-token'`), exactly as the turn door would judge it without its key. */ readonly signInKey?: string; } /** * What {@link StandingAgentHandle.artifactsForRequest} answers: the serving * agent's artifact store bound to the scope a REDEMPTION by this caller of this * session would read — or why nothing was bound. * * `artifacts` has the {@link TurnArtifacts} shape: five verbs, no scope on the * value, never the unscoped store. Its verbs count against * `artifactOpsPerSession` with the wire's redemptions (a verb past the bound * rejects with `ArtifactOpsBusyError`), and the binding is REVOKED when the * instance it is bound to is retired from the pool or the host is closed — * a verb STARTED after that rejects with `RequestArtifactsRevokedError` * (already handled; ask the handle again); one already in flight completes. * * `bound: false` says why, checked in this order: * - `'unverified'` — a verifier is configured and the request did not pass it * (no credential where one is required, a token that does not verify, a * sign-in that ended or expired, a token AND a sign-in, a claimed user the * credential does not prove). `error` is the verifier's refusal; a host's * 401. * - `'unavailable'` — the verifier could not answer (`VerifierUnavailableError`, * an identity-provider outage, a sign-in store that is down). `error` says * which; a host's 503, never a 401 — the caller's credential was not * judged. * - `'no-session'` — the request named no session. * - `'invalid-session'` — the session id is one the wire refuses at the door * (empty, over the length bound, or a character outside visible ASCII — * `InvalidSessionIdError` as `error`); a host's 400. * - `'not-found'` — at a verifying door, no conversation THIS caller can * open under that id: somebody else's, one nobody signed for, or one whose * first turn has not persisted (unless that turn is this caller's, in * flight). One reason for all of them, as redemption answers them with one * not-found. Never builds or evicts a pooled instance to find out. Having * no live instance is NOT by itself a reason: past that ownership check a * lane-less session binds through the pool's reader — at a door with no * verifier, a session nobody has chatted in yet included, which is where a * guide filed before its first turn goes — and whether a ref exists is the * store's answer (`head` → `null`). * - `'no-store'` — the serving agent has no artifact store. */ export type ArtifactsForRequestResult = { readonly bound: true; readonly artifacts: ToolArtifacts; } | { readonly bound: false; readonly reason: 'unverified' | 'unavailable' | 'no-session' | 'invalid-session' | 'not-found' | 'no-store'; /** Present with `'unverified'`, `'unavailable'` and `'invalid-session'`. */ readonly error?: Error; }; /** * What `standingAgent(...)` adds to the host adapter's own handle. */ export interface StandingAgentHandle { /** * The serving agent's artifact store, bound to the scope a redemption by this * request's caller of this session reads — for the paths that are not a chat * turn: a read before a run (a panel redeeming a payload by ref), or an * app-owned route that files its own artifacts beside a conversation. * * "The caller" is what the door knows: at a door with a verifier, the person * the token or the sign-in PROVES; at a door with no verifier, the session id and the * transport's `userId` claim are the key, by law — exactly as on the wire. * * Inside a handler, hand it the request the transport built — * `handle.artifactsForRequest(request)` — so the sign-in key * ({@link HostRequest.signInKey}) goes in with the headers. On an app's own * route, take the sign-in cookie off first and pass only its key: * `const { key, headers } = readSignIn(req.headers, door.cookieName)`, then * `{ sessionId, headers, signInKey: key }`. * * The host never composes the scope. This runs the door's own steps with the * door's own instances: the configured verifier, the session-id check, the * session store (woken and hydrated as a redemption does), the redemption * door's ownership rule, the ONE scope composer redemption and * `reply.turnArtifacts` use, and the store of the instance serving that * session — never building or evicting a pooled instance to find it. So a ref * filed through it is redeemed on the wire by the same caller, and a ref * another caller filed answers exactly like a ref that never existed. * * A filing made through it carries NO `origin`: this call executes no run, * so there is no run id the library can vouch for (a caller's own `origin` * is dropped, as on every binding). The caller is already the scope, and * its `minted` fact names the session. * * @example An Express route that reads a payload by ref before the turn runs * const handle = await standingAgent({ agent, sessions, host, identity: door.identity }); * app.get('/panel/:sessionId/:ref', async (req, res) => { * const { key, headers } = readSignIn(req.headers, door.cookieName); // the cookie comes off * const found = await handle.artifactsForRequest({ * sessionId: req.params.sessionId, * headers, * ...(key !== undefined && { signInKey: key }), * }); * if (!found.bound) { * const status = { unverified: 401, unavailable: 503, 'invalid-session': 400 } as Record; * return res.status(status[found.reason] ?? 404).end(); * } * const payload = await found.artifacts.get(req.params.ref); // null: missing, expired or not yours * return payload ? res.json(payload.data) : res.status(404).end(); * }); * * @throws HostClosedError after `close()` — including a call that was * waiting (on the verifier or the session store) when `close()` ran: it * binds nothing and builds nothing, exactly like the wire. * @throws UnreadableEnvelopeError when the stored conversation is present but * cannot be read (the turn door's law — never composed into a scope). * @throws whatever the session store's own `onWake` / `hydrate` throws (an * outage is the store's to name, not a refusal value). */ artifactsForRequest(request: ArtifactsForRequestInput): Promise; } /** * 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; /** 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. * * "Release the transport" is as strong as the port can be, because an * adapter may be serving on a transport the CALLER owns rather than one it * created. Releasing one of those means handing the routes back — never * closing it — and a request arriving afterwards is the caller's to answer, * not this host's to refuse. */ close(): Promise; } /** * A request the HOST refused before any handler saw it — the door guard's * decision about a caller: a cross-site shape, a Host this door does not answer * for, a session id it will not carry. * * Only decisions travel here. A body that is merely malformed (unparseable * JSON, an unknown wire op, a body over the ceiling) is a broken request, not a * decision about who is knocking, and stays the transport's own 4xx. * * Carries the refusal's class and the fact of a credential — never a header, * never the credential, never the session id. It is what * {@link AgentHost.onRefusal} hands a listener, and a listener is free to log * all of it. */ export interface HostRefusal { /** * Which door refused: `'request'` — the one-exchange door, refused before * the body was read or before the handler was called (which of the * composer's turn / session-op / artifact doors it was headed for is not * recorded) — or `'conversation'`, an upgrade refused before the 101. */ readonly door: 'request' | 'conversation'; /** The named refusal the caller was answered with. Its `code` is stable. */ readonly error: Error & { readonly code: string; }; /** Whether an `authorization: Bearer …` credential was PRESENT. Never its value. */ readonly bearerPresent: boolean; } /** * 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; /** * Hear about every request this host refuses BEFORE a handler sees it — on * any of its doors, the conversation door included. Returns the way to stop * listening. * * Optional, and feature-detected: a host that refuses nothing on its own * has nothing to report. Every host built on `httpHost` has it, and * `standingAgent` subscribes whenever `onIngressDecision` is set — which is * how a forged request the host turned away still lands in the ingress * record, though no run, no handler and no verifier ever saw it. * * A listener that throws is contained: the refusal is still answered. */ onRefusal?(listener: (refusal: HostRefusal) => void): Unsubscribe; } /** * 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. * * Never the sign-in cookie: a host built with one strips it (see * {@link signInKey}). */ readonly headers?: Readonly>; /** * The sign-in the handshake carried, as its KEY (see * {@link HostRequest.signInKey}). When it is present the door already * checked it before the 101, re-checks it before handing on every inbound * frame, and closes the conversation when the sign-in ends. */ readonly signInKey?: 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; /** * 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; } /** * A session packed for storage. * * `format` names WHAT is inside, so a reader that does not know the shape * refuses BY NAME instead of restoring a session 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. Two exist: * * • `'conversation-v1'` — a conversation and only a conversation. Every turn * that ran to an answer stores this. * • `'flowchart-v1'` — a run that stopped mid-flow to ask a person something: * the engine's own checkpoint, the conversation as of the pause, and the * outstanding ask. 7.14 shipped the version field for exactly this day, and * said so; this is that day. * * The union is discriminated on `format`, so a reader that switches on it is * exhaustive by construction and a third format tomorrow breaks the switch at * compile time rather than at 3am. */ export type CheckpointEnvelope = ConversationEnvelope | PausedRunEnvelope; /** A conversation packed for storage — what a turn that ANSWERED leaves behind. */ export interface ConversationEnvelope { /** Names the shape of `data`. Unknown values are refused, never guessed at. */ readonly format: 'conversation-v1'; /** The conversation itself. */ readonly data: AgentRunCheckpoint; /** Wall-clock when it was packed. Diagnostic. */ readonly savedAt: number; } /** A paused run packed for storage — what a turn that ASKED leaves behind. */ export interface PausedRunEnvelope { /** Names the shape of `data`. Unknown values are refused, never guessed at. */ readonly format: 'flowchart-v1'; /** The paused run. */ readonly data: PausedRun; /** Wall-clock when it was packed. Diagnostic. */ readonly savedAt: number; } /** * A run that stopped to ask a person something, in the three pieces a session * actually needs: what continues it, what it has said so far, and what it is * waiting on. * * ── JSON, honestly ─────────────────────────────────────────────────────────── * A `FlowchartCheckpoint` is **JSON-safe to resume from, and not byte-identical * through JSON.** `JSON.stringify` drops any property whose value is * `undefined`, and a real paused agent run has a dozen of them. Every one * measured sits in `executionTree` / `subflowResults` — the diagnostic halves * the engine keeps for narrative and BTS. `sharedState`, which is the half * `agent.resume()` actually reads, round-trips unchanged, because footprintjs's * TypedScope already JSON-round-trips every object write on its way into * committed state. * * So: store it anywhere that speaks JSON and resume works. Do not assert that * what came back deep-equals what went in — `key: undefined` comes back as no * key at all, and a test written to expect otherwise is testing `JSON`, not * this library. */ export interface PausedRun { /** The engine checkpoint — everything `agent.resume(checkpoint, decision)` needs. */ readonly checkpoint: FlowchartCheckpoint; /** * The conversation as of the pause, in the same shape every other turn stores. * * Kept alongside the checkpoint so a session that is waiting on a person is * still a readable conversation: a support view can show what was said, and a * runtime that cannot resume this run can still see the turn that led to the * question. */ readonly conversation: AgentRunCheckpoint; /** What the run is waiting on, as data. */ readonly pending: PendingAsk; /** * What the WIRE that served the pause recorded about it — the ids it handed * the caller for the answer — so a later request on that wire is matched to * this pause and continued as the same invocation (`streamHandler` keeps the * AG-UI adapter's record here). Absent for a pause a door with nothing to * remember stored, and opaque to the store and to every other door. */ readonly wire?: PausedWire; /** * Set when a resume of this pause failed — in the run, or in storing its * result — after its decision may have been used: it reached a ledger, so * the call may have run (a resume that never took the decision to a ledger * leaves the pause unmarked). The pause is answered: a decision for it is * refused (`ResumeDecisionError`, `'already-answered'`), whether its call ran * is not known to the host, and the next message continues the conversation * in `conversation` — what this session stored (the run's own, kept mid-run * under durable writes, else as of the pause), every call left open settled * as unknown, and a call the person declined settled as declined. `at` is * when the host marked it. Absent on every pause still waiting — and code * that reads stored pauses itself (`readPausedRun`) must honour it: an * answered pause is a conversation to continue, never a question to show. */ readonly answered?: { readonly at: number; }; } /** One wire protocol's own record of a pause it served — see {@link PausedRun.wire}. */ export interface PausedWire { /** The protocol that recorded it: the protocol adapter's `name`. */ readonly protocol: string; /** Plain JSON, the protocol's own; ids and names, never a value of the run. */ readonly record: unknown; } /** * The question a paused run is waiting on — the part of a pause that is safe to * hand to whoever asked. * * **It deliberately carries no checkpoint.** The engine checkpoint holds the * entire shared state of the run: the system prompt, the whole conversation, * every tool result. That belongs in the store, which the operator chose and * controls, and not in a reply to whoever posted the request. The caller gets * the question; the store gets the state. */ export interface PendingAsk { /** Typed missing-input collection. Respond with {requestId, values}; never approval. */ readonly awaitingInput?: AwaitingInput; /** The session holding the paused run — where the decision has to be sent back. */ readonly sessionId?: string; /** The tool that asked, when the run recorded which one it was. */ readonly tool?: string; /** The question in plain words, when the pause carried one. */ readonly question?: string; /** * Present ONLY when a tool declared `checkIn` — the typed ask plus its * evidence pack (what the tool will do, what context the run read, which * context drove the choice, the run so far). Answer with * `checkInApproved({ request: pending.checkIn, by })` / `checkInDeclined(...)` * — `checkIn.id` names the request, and the decision answers it once. */ readonly checkIn?: CheckInRequest; /** * Present ONLY when a `toolMiddleware` answered `ask` — the question and the * middleware that put it. Answered with the same decision vocabulary a * check-in uses, deliberately: a person approving is a person approving — * `checkInApproved({ request: pending.ask, by })`, naming `ask.id`. */ readonly ask?: MiddlewareAsk; /** * Which REGISTERED screen component collects the answer (9.24.0) — the * typed half of the question, lifted from whichever pause kind carried it * so a screen has ONE place to look. Ids and props only, never markup: the * registry lives in the frontend, and a screen that does not know the id * falls back to the prose `question` exactly as before. * * `props` is the small inline half; `propsRef` is a claim ticket the screen * redeems through the artifact wire (`head` then `get`) under the SAME * session identity every other redemption presents — a 200-option picker * rides the store, not this reply and not the checkpoint. The ref was * validated to resolve when the ask was raised. * * The answer comes back through {@link HostRequest.decision} unchanged — * the component changes how the question is asked, never what the answer * is. A screen may render the decision as words; the words are display, * the structured decision is the record. */ readonly component?: AskComponent; /** * Exactly what the tool passed to `askHuman()` / `pauseHere()`, uninterpreted. * For a plain pause this is the whole of what the tool's author chose to say, * and the library is not entitled to summarise it. */ readonly pauseData: unknown; } /** * How often a run's progress is written to the session store — the trade * between latency and how much a crash can cost you. * * - `'exit'` (default) — one write, when the run finishes. The behaviour every * release before 7.19 had, spelled out rather than implied. A crash mid-run * loses the whole turn. * - `'async'` — a write is STARTED whenever the conversation changes and never * waited on. The run never slows down; the store is behind by however much * the newest un-landed write carried. At most one write is in flight and the * newest snapshot supersedes any queued one, so what a crash leaves is always * a PREFIX of the run, never a mixture. * - `'sync'` — persist-then-proceed. The same trigger, but **iteration N's * tools do not execute until iteration N-1's write has landed**, and the * answer is not delivered until the last write has landed. You pay the * store's latency once per iteration, knowingly, and in exchange the amount * of work a crash can re-run has a number: **the current iteration, and * nothing before it.** * * ── The bound, stated exactly ──────────────────────────────────────────────── * A commit boundary is a whole stage, and the agent dispatches ALL of one * iteration's tool calls inside one stage body. So under `'sync'` a crash * re-executes the tools of the iteration that was in flight — never an earlier * one. That is the same idempotency requirement `resumeOnError` has always * carried, now with a boundary instead of a warning: mutating tools must be * idempotent, keyed on stable call content rather than `ctx.toolCallId`. */ export type DurabilityMode = 'exit' | 'async' | 'sync'; /** * Why a session is being woken. * * - `'invoke'` — a request arrived for that session. * - `'resume'` — that request carries a person's decision for a run which * paused earlier. * - `'artifact'` — that request redeems an artifact ref (or binds through * `artifactsForRequest`), and the stored conversation decides something: * its identity tuple composes the scope (a request carrying a `userId`) or * its owner decides who may redeem (a verifying door). Fired only when the * resolution actually reads the store; a session-only resolution at a door * with no verifier composes its scope from the request alone and wakes * nothing — whether its ref exists is the artifact store's answer. * - `'transcript'` — a verified owner is READING that session's messages back * (9.26.0). Nothing runs and nothing is written; the store is woken because * it is about to be read from, which is the only promise this hook ever * made. * * `'resume'` was absent until 7.19, `'artifact'` until 9.23 and `'transcript'` * until 9.26, because nothing could produce them: naming reasons nothing fires * would be an interface describing a system that does not exist. Something * produces each of them now. */ export type WakeReason = 'invoke' | 'resume' | 'artifact' | 'transcript'; /** * 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. * * ── Claiming the port ─────────────────────────────────────────────────────── * The two required methods are what TypeScript checks. What a store has to * *behave* like is a battery every shipped store runs against and any store * can: `sessionLifecycleConformance`, exported from this same subpath. It was * written after a flaw in THIS interface's semantics turned up in four * independent adapters at once — every one of them tested, and every one of * them tested only against its own doubles, which is precisely why none of * them could see it. Run it against your store; a case your store cannot * satisfy is DECLARED by name with its reason, never skipped. */ export interface SessionLifecycle { /** The stored conversation, or `undefined` for a session that has none yet. */ hydrate(sessionId: string): Promise; /** * Store the conversation for this session. Last write wins — with ONE * exception, and it is the only thing this method ever refuses. * * **A store that keeps an owner index refuses a turn signed by somebody * other than the established owner** (`SessionOwnershipConflictError`, * 9.36.1), and refuses it whole: neither the index nor the ENVELOPE changes. * Until 9.36.1 the write-once rule protected only the index, so such a write * kept the first writer's `owner` and stored the second writer's entire * conversation — leaving the index naming one person and the stored * conversation naming another. The person the index named listed it, opened * it, and read the other one's conversation. * * A turn carrying a LEANER identity is not refused. It claims nobody, so it * contradicts nobody, and the established owner stands — see `listByUser`. * * The composer refuses a foreign turn at the door long before this, when a * verifier is configured. This is the store keeping the same promise for * every caller that holds it directly, and for a door with no verifier. */ persist(sessionId: string, envelope: CheckpointEnvelope): Promise; /** * 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; /** * OPTIONAL (9.26.0) — the sessions this user owns, newest first. * * Feature-detected, never assumed. The two required methods are a key/value * map and most stores are exactly that; demanding a secondary index of every * implementation that will ever exist would be this port breaking its own * rule ("anything a real store also wants is that store's API, not a demand * this port makes"). A store that leaves this absent makes * `{ op: 'session-list' }` refuse BY NAME, naming the store's limitation — * never answer "you have no sessions", which is an answer nobody could * distinguish from the truth. * * **Ownership is derived, never declared.** `persist` takes no owner and * gains none: a store fills its index from the stored envelope itself * (`envelopeOwner`), which reads the `principal` on the conversation the * composer put there. A store that let a caller state an owner would be a * store where owning somebody's session is a matter of asking for it. * * **And established ONCE.** The first turn that signs for a conversation owns * it; no later write moves that — not a leaner identity (which would erase * it) and not a different one (which would transfer it). Every shipped store * implements the index that way, and a custom one that let the last writer * win would undo every ownership check made against it one turn later. * * The two halves of "no later write moves it" are NOT symmetrical, and * 9.36.1 exists because they were treated as if they were: * * - a **leaner** turn is stored, and the owner is kept. It claims nobody, so * it contradicts nobody. Refusing it would break a flow this contract * blesses in the sentence above. * - a **different** turn is REFUSED — index and envelope both. Keeping the * index while storing the payload is not "not moving" the owner; it is * moving the CONVERSATION out from under them, which is worse. Don't * write this rule yourself: `resolveSessionOwner(sessionId, stored, * incoming)` is the one implementation, and it is what every shipped store * now calls. * * ── Which of the two says who owns a session ──────────────────────────────── * This index is the authority for LISTING and for the session-history ops: * `ownerOf` is the question `{ op: 'session-transcript' }` asks, and nothing * re-derives an answer behind it. An ordinary TURN does not ask it — it * re-derives from the envelope it has just hydrated (`envelopeOwner`), which * is the same derivation and one round-trip cheaper, and which is what keeps * a store with NO index protected exactly as well as one with a fast one. * * Those two can never name different people: that is what the refusal above * buys, and it is the only reason a turn is safe to answer from the envelope. * They CAN differ in one direction — an index that names somebody over a * conversation that names nobody, which is what a leaner turn leaves behind. * That state only ever REFUSES: the owner can still list and read the * session, and a turn on it is refused at any verifying door, for everybody. * Stated because it is a real asymmetry and not a bug to be surprised by. * * A conversation that ran anonymously has no owner and appears in nobody's * list. That is the honest consequence of deriving rather than inventing. */ listByUser?(userId: string, options?: SessionListOptions): Promise; /** * OPTIONAL (9.26.0) — who owns one session, or `undefined` for a session * that does not exist OR names no owner. * * The deliberate ambiguity is the same one `ArtifactStore.get` makes: * "missing" and "not yours" must be indistinguishable from the outside, and * a store that answered them differently would hand a caller an oracle for * which session ids are real. * * Implement it beside `listByUser` — a door that can list but not check * ownership can hand somebody a list and then refuse to open any of it. * * This is the ownership INDEX, and it is not a second source of truth beside * the identity embedded in the stored envelope: `persist` refuses any write * that would make the two name different people. A store that answers this * from something a caller supplied, rather than from what it derived, has * built a permission system out of a request field. */ ownerOf?(sessionId: string): Promise; /** * OPTIONAL (9.42.0) — how conversations in this store stop existing. * * Feature-detected exactly like the two members above, and for the same * reason: the two required methods are a key/value map, and demanding a * retention mechanism of every implementation that will ever exist would be * this port breaking its own rule ("anything a real store also wants is that * store's API, not a demand this port makes"). A store that leaves this * absent makes {@link sessionRetention} refuse BY NAME, naming the store's * limitation and which shipped stores do implement it — never a silent * no-op, which is the one failure mode a retention feature must not have, * because from the outside "nothing was deleted" and "everything is fine" * look identical until somebody asks how long you keep conversations. * * ── Why it is one member with two arms, and not one verb ──────────────────── * Because there are exactly two honest implementations of retention, and a * port member only half the shipped stores could implement would not be a * port member at all: * * - some stores **delete when you ask them to** — a `Map`, a table, a file. * A sweep is one loop or one statement there, and the caller's cron * decides when. * - some stores **cannot honestly sweep, because the backend already * expires rows on a policy the operator configured** out of band. Asking * such a store to sweep would mean a query plus one delete per row, at an * unbounded cost, duplicating a job the service does for free — and a * store that reported "0 deleted" from a backend that deletes plenty * would be lying by omission. * * So the answer is a DISCRIMINATED UNION and `deletedBy` is the field a * consumer branches on: one feature check, then one exhaustive branch the * compiler enforces. See {@link SessionRetention}. * * ── The shape that was deliberately NOT chosen ────────────────────────────── * A stated expiry at persist time — `persist(id, envelope, { expiresAt })` — * reads well and is the wrong shape twice over. It puts a demand on the one * method every store must implement, so every store that will ever exist has * to honour it; and it cannot be feature-detected, because `typeof * store.persist === 'function'` is true whether or not the third argument is * read. A store that ignored it would keep every conversation forever while * its caller believed retention was configured. An optional member that is * absent refuses; an optional ARGUMENT that is ignored does not. * * ── Why not the shape the ARTIFACT port already uses ──────────────────────── * That sibling port states an expiry at MINT (`ttlMs` → a stamped * `expiresAt`) and sweeps a scope when a put next touches it. It is the right * shape THERE because every artifact store in that family holds its own * bytes, so every one of them can sweep. This family does not: two of its * stores are managed services that expire rows on a policy nobody here * controls, and one has no delete at all. A port copies its sibling's * vocabulary only where the sibling's assumption also holds. * * ── What this is not ──────────────────────────────────────────────────────── * Not a wire op. No door in this package deletes conversations on request, * and the composer never expires anything on its own: retention is an * operator's job with an operator's blast radius, and a request that could * delete somebody's history because it named a cutoff is not a feature. * * @example A cleanup job that works against any store that can answer * const policy = sessionRetention(sessions); * if (policy.deletedBy === 'this-store') { * const { forgotten, more } = await policy.forgetOlderThan(Date.now() - THIRTY_DAYS); * log(`forgot ${forgotten} conversations${more ? ', more remain' : ''}`); * } else { * log(`the backend expires these on '${policy.expiresOn}': ${policy.enableWith}`); * } */ retention?(): SessionRetention; } /** * How one store's conversations stop existing — the answer * {@link SessionLifecycle.retention} gives, in the two shapes a store can * honestly give it. * * `deletedBy` is the discriminant, and it is spelled as WHO does the deleting * rather than as a mechanism, because that is the fact a caller acts on: one * arm hands you something to call, the other hands you something to configure. */ export type SessionRetention = SessionSweep | SessionExpiryPolicy; /** * This store deletes, when you ask it to. * * The shape for a store that holds its own bytes — a map, a table, a file. * Nothing sweeps on a timer of its own: a library that started an interval * would be deciding your process's lifetime for you, and a sweep that runs * without anybody asking is a deletion nobody can point at afterwards. */ export interface SessionSweep { readonly deletedBy: 'this-store'; /** * Forget every session whose stored `savedAt` is STRICTLY BEFORE `before` * (epoch milliseconds), and say how many went. * * Strictly before, so that passing the same cutoff twice is stable and a * session written exactly at the boundary survives — an off-by-one here * deletes a conversation somebody is still holding. * * The clock is the ENVELOPE's `savedAt` — the same value the listing sorts * on — and not the store's own wall clock. That makes a sweep a pure * function of what is stored: the same cutoff over the same rows forgets the * same conversations, in a test and at 3am. * * Bounded by `options.limit` ({@link DEFAULT_SWEEP_LIMIT} when absent), so a * first sweep of a store that has been running for a year cannot become one * unbounded transaction. `more` says whether another call has work to do. * * Deleting a session that is not there is not an error, and a sweep that * matches nothing answers `{ forgotten: 0, more: false }` rather than * refusing — a cleanup job runs on a schedule, and most of its runs have * nothing to do. */ forgetOlderThan(before: number, options?: SessionSweepOptions): Promise; } /** * The BACKEND deletes, on a policy an operator configured — this store only * writes what that policy reads, and can say exactly what to turn on. * * There is nothing to call here on purpose. A method that did nothing but * report "the backend handles it" would be a method somebody puts in a cron * job, and a cron job that deletes nothing is worse than no cron job: it looks * like retention is running. */ export interface SessionExpiryPolicy { readonly deletedBy: 'the-backend'; /** * Whether this store is actually stamping an expiry on every write. * * `false` means the mechanism exists and nothing is using it — the store was * built without a retention setting, so the backend's policy has nothing to * act on and conversations live until somebody deletes them. Reported rather * than implied, because "there is a TTL field" and "things are expiring" are * different facts and only one of them answers an auditor. */ readonly active: boolean; /** * What the backend's policy acts on — a stored field name, or the setting * that starts the clock. Named so an operator can configure the policy * against the right thing rather than guessing from a schema dump. */ readonly expiresOn: string; /** * What an operator does to turn the policy on, in one step they can act on * — with this store's own collection, database or resource already filled * in where the step needs one. * * A sentence rather than a code, for the same reason the refusals in this * package print a whole command instead of naming a concept: the operator * reading this is the person who can fix it in sixty seconds, and only if * nobody makes them go and look it up first. */ readonly enableWith: string; } /** Options for {@link SessionSweep.forgetOlderThan}. */ export interface SessionSweepOptions { /** * The most sessions to forget in this call. Default * {@link DEFAULT_SWEEP_LIMIT}; stores may cap it lower. * * A bound rather than "delete everything matching", because the first sweep * after this feature is turned on is the biggest one that store will ever * do, and it is the one most likely to hold a write lock long enough to be * noticed by every request behind it. */ readonly limit?: number; } /** What one sweep did. */ export interface SessionSweepResult { /** How many conversations this call forgot. */ readonly forgotten: number; /** * True when sessions older than the cutoff REMAIN — i.e. the limit was * reached. A caller that loops until this is `false` drains the backlog in * bounded steps; one that ignores it simply sweeps again next time. */ readonly more: boolean; } /** * How many sessions one {@link SessionSweep.forgetOlderThan} forgets when the * caller names no limit. * * Big enough that an ordinary nightly sweep finishes in one call, small enough * that the first sweep of a neglected store is a series of short transactions * rather than one long one. */ export declare const DEFAULT_SWEEP_LIMIT = 1000; /** Paging for {@link SessionLifecycle.listByUser} — the cursor convention every * listing in this package follows. */ export interface SessionListOptions { /** Continuation token from a previous page. Omit for the first page. */ readonly cursor?: string; /** Maximum rows this page. Stores may cap it lower. */ readonly limit?: number; } /** One page of a user's sessions. Never carries message content — a listing * says WHICH conversations exist, and `session-transcript` says what is in * one. */ export interface SessionListPage { readonly sessions: readonly SessionSummary[]; /** Present iff more pages exist. */ readonly cursor?: string; } /** * 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'; /** * Everything {@link standingAgent} takes EXCEPT which agent answers — that is * the one choice with two shapes, and it lives on * {@link StandingAgentOptions}. * * 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 StandingAgentBaseOptions { /** Where conversations live between requests. */ readonly sessions: SessionLifecycle; /** What carries requests in. */ readonly host: AgentHost & { serve(handler: HostHandler): Promise; }; /** Default `'reject'`. See {@link ConcurrentInvokePolicy}. */ readonly onConcurrentInvoke?: ConcurrentInvokePolicy; /** * Verify WHO is calling, instead of believing a header (9.26.0). * * With this set, every request's `Authorization: Bearer ` is checked * BEFORE the run's identity/scope is composed, and the proven user id is the * one that reaches `EventMeta.principal`, `ctx.identity`, the memory * namespace and the artifact scope. A request that NAMES a user it cannot * prove is refused by name — never downgraded to anonymous, never served * under the name it claimed. * * **It also decides whose sessions are whose.** With a verifier configured, * EVERY door that opens a stored conversation asks one question first — the * two session-history ops and an ordinary turn alike: does this session * belong to the caller who proved who they are? A turn naming somebody * else's session is refused with the same indistinguishable * `SessionNotFoundError` a transcript gets, before a line of that * conversation is hydrated into a model's context and before anything is * written back. Ownership is the `principal` the first turn signed with, and * no later turn moves it. * * The consequence to plan for: conversations stored BEFORE a door started * verifying name no owner, so they cannot be continued at one that does. That * is a loud refusal by design — the alternative is a door that hands old * conversations to whoever names them first. * * Unset — the default — nothing changes: `HostRequest.userId` is read exactly * as it has been since 9.12.0, and every release's behaviour before this one * is byte-identical. Which is right depends on what stands in front of you, * and that is a fact only the deployment knows. * * @example * identity: { verify: jwksIdentity({ * jwksUrl: 'https://idp.example.com/.well-known/jwks.json', * issuer: 'https://idp.example.com/', * audience:'my-api', * }).verify } */ readonly identity?: DoorIdentity; /** * Decide whether a request runs at all, BEFORE any model is called (9.26.0). * * Called once per turn with the verified caller, the session and what that * caller has spent inside a rolling window; it answers `'allow'`, * `{ queue: true }` (run it, but behind this session's other work) or * `{ refuse: '' }`. `turnsPerHour({ limit })` is the shipped * reference policy. * * Unset — the default — no accounting is kept, no listener is installed, and * not one line of this runs. * * **The honest boundary, stated once:** accounting is PER PROCESS. Two * containers each keep their own window, so a limit of 20 across three * replicas is a limit of 60. Centralize by writing a policy that consults * your own store — the `decide` seam is exactly where that goes. * * And the second one: a turn is counted when it is ADMITTED, so a request * the lane then refuses as a concurrent run still counts against the * window. Counting later would let a burst of simultaneous requests each be * decided against a window none of them had joined. */ readonly admission?: AdmissionPolicy; /** * Seal the credential a request carries for its run — a gateway's * per-request token in a header, read by a `requestCredentials` provider * (`agentfootprint/security`) for the tools that declare a `needs` for it. * * Called once per request that RUNS (a turn or an answer — never an * artifact or session op, never a refused request), after the caller is * verified and the session's ownership is checked, with the request's * headers ({@link HostRequest.headers}: `nodeHost` and `httpHost` deliver * them) and nothing else. Return * `requestContext({ secrets })`, or `undefined` for a request that carries * none; the handle goes to THAT request's `run()` / `resume()` only — never * the reply, the stored session or the checkpoint, so a resumed run is * served the RESUMING request's credential. A handle any host was handed * before is refused; a sealer that throws refuses the request in fixed words * (`ERR_REQUEST_NOT_SEALED`, 400) — so decrypt at vend time * (`decodedWith`), not here. The HANDLE never reaches a reply; a tool that * returns the credential's value itself does (`hostFilled` scrubs an echo). * * Unset — the default — no run carries a request, exactly as before. * * @example * sealRequest: ({ headers }) => * headers['x-crm-token'] === undefined * ? undefined * : requestContext({ secrets: { crmToken: headers['x-crm-token'] } }), */ readonly sealRequest?: RequestSealer; /** * Where this door's ingress decisions go (9.32.0) — one record per request, * including every request that never became a run. * * `auditExport()` is a record of RUNS, so a 401 from `identity.verify` and a * 429 from `admission.decide` are not in it: they happen before an agent * exists. Two independent review rounds named that gap. This is where the * turned-away go — and where the SERVED are recorded too, because an absence * is only readable against a census. * * **It does not join the audit hash chain.** Nothing here is hashed, * sequenced or verifiable by `verifyAuditBundle`; it is a stream you chain * into your own sink. Claiming otherwise would make this the very * looks-like-evidence failure it exists to close. * * The record carries classes and identifiers only — never the token, never a * header, never a claim set, never an error's message. See * {@link IngressRecord} for the field-by-field contract and for the one thing * it deliberately does not cover (a body the transport's own wire grammar * refused as malformed before this composer ever saw it). * * The HOST's own refusals are on it too: set this, and the composer * subscribes to the host's `onRefusal`, so a forged request the door guard * turned away, or a session id over the bound, is recorded * (`'cross-site-refused'` / `'refused'`, door `'request'` or * `'conversation'`) though no handler ever saw it. * * Unset — the default — nothing is built, nothing is wrapped, nothing is * subscribed, and the reply the handler uses is the host's own object, to the * byte. * * @example * onIngressDecision: (record) => { * if (record.outcome !== 'served') securityLog.write(record); * } */ readonly onIngressDecision?: IngressSink; /** * How often a run's progress becomes crash-survivable. Default `'exit'` — * one write when the run finishes, which is what every release before this * one did. See {@link DurabilityMode} for what the other two buy and cost. * * Under `'exit'` nothing is attached to the agent at all: no observer, no * per-commit work, no barrier. An agent served this way behaves and performs * exactly as it did in 7.18. */ readonly durability?: DurabilityMode; /** * What `close()` does to the telemetry enabled on the agent (8.12.0). * Default `'flush'`. * * - `'flush'` — drain every strategy the agent has enabled, and leave them * running. This is the default because it is what everyone already * believed happened: an exporter that batches otherwise loses whatever it * had buffered when the server stops. Draining is safe on an agent this * composer only BORROWED — it ships data and disables nothing. * - `'flush-and-stop'` — drain, then release: timers cleared, clients * closed, further events dropped. Say this only when the agent's life * ends with the host, because stopping is terminal. * - `'none'` — touch nothing, exactly as releases before 8.12.0 did. */ readonly shutdown?: 'flush' | 'flush-and-stop' | 'none'; /** * Signals whose arrival should close this host (8.12.0). Off by default, * and that is a deliberate refusal rather than an omission. * * **A library must not grab signals.** `process.on('SIGTERM', …)` is not * observation: Node's default action for SIGTERM is to terminate, and * ADDING any listener suppresses that default. A library that installs one * behind your back can turn a container's graceful stop into a thirty-second * wait for SIGKILL in an application that never asked for it. Handlers are * process-global and cannot be arbitrated between libraries, ten runners * would mean ten handlers and a `MaxListenersExceededWarning`, only Node has * signals at all, and no library can know your exit policy. * * A composition root may, because it already owns the shape of the process * — and this one asks first. When you pass signals here, this composer: * * 1. installs one listener per signal; * 2. on arrival, runs the same `close()` you would have called — the host * stops taking requests, in-flight runs finish, telemetry drains per * {@link StandingAgentBaseOptions.shutdown}; * 3. removes its own listeners and RE-RAISES the signal, so the process * dies exactly the way the platform expects rather than by an exit code * this library invented. * * `close()` removes the listeners too, so a handle you close yourself leaves * nothing installed. * * @example * await standingAgent({ agent, sessions, host, shutdownOn: ['SIGTERM', 'SIGINT'] }); */ readonly shutdownOn?: readonly NodeJS.Signals[]; /** * How long a turn's artifact hand-over (`HostReply.turnArtifacts`) may hold * the reply — the hook AND every operation it started — before the composer * stops waiting. Default {@link TURN_ARTIFACTS_TIMEOUT_MS} (5 s). The * request's own `signal` ends the wait earlier when the caller hangs up. * * On expiry the binding is revoked, nothing in flight is cancelled (it may * still land, attributed to its own session and run), the cause is reported * (`agentfootprint.artifacts.hand_over_failed { cause: 'timeout' }`), the * terminal is delivered and the lane released — so one host's hung store or * hook can hold neither every other session (the shared shape), nor a pooled * lane past `maxActiveSessions`, nor `close()` on the SIGTERM path. * * Must be a positive, finite number of milliseconds — a bound that can never * fire is not a bound; anything else is refused at construction. Only read * when the host implements the hook. */ readonly turnArtifactsTimeoutMs?: number; /** * Serve "Explain this answer": the `{ op: 'answer-account', ref }` wire op, * which returns one answer's plain-words account (`AnswerAccount` plus its * allow-listed show-me leaves), computed HERE from the recording the ref * names. The browser never receives the recording through it. * * Off unless given — a host without it answers the op with the unknown-op * refusal before reading anything (`false` says the same). `true` opts in * with every default; the * object form sets the app's `declarations` (validated now, never taken * from a request), the recording ceiling and the cache size. See * {@link AnswerAccountsOptions}. * * The op follows `artifact-get`'s own path — the same ownership check, the * same one not-found, lane-free — and adds one refusal of its own: a * recording over the ceiling (`ERR_RECORDING_TOO_LARGE_FOR_ACCOUNT`, 413). * * @example * await standingAgent({ agent, sessions, host, answerAccounts: { * declarations: { tools: { lookup_volumes: { rowsAt: 'volumes' } } }, * } }); */ readonly answerAccounts?: AnswerAccountsOptions | boolean; /** * How many artifact operations — `artifact-head`, `artifact-get` and * `answer-account`, counted together — ONE session may have in flight at * once. Default {@link DEFAULT_ARTIFACT_OPS_PER_SESSION} (8). * * Artifact ops are lane-free (they never wait behind a run) and turn * admission does not see them, so this is their bound: a session over it is * refused with `ArtifactOpsBusyError` (`ERR_ARTIFACT_OPS_BUSY`, 429) while * every other session is served. Counted after the ownership check, so a * stranger cannot spend another session's slots. A screen that redraws many * panes at once should redeem them a few at a time, or raise this. * `Infinity` means no bound; anything else must be a positive whole number. */ readonly artifactOpsPerSession?: number; } /** * How many artifact operations one session may have in flight by default — * enough for a screen redrawing a handful of panes, too few for one session * to crowd the event loop every session shares. See * {@link StandingAgentBaseOptions.artifactOpsPerSession}. */ export declare const DEFAULT_ARTIFACT_OPS_PER_SESSION = 8; /** How many sessions a `agentFactory` pool holds before it evicts the least * recently used one. See {@link StandingAgentPoolOptions.maxActiveSessions}. */ export declare const DEFAULT_MAX_ACTIVE_SESSIONS = 100; /** * How long a turn's artifact hand-over may hold its reply by default — the * hook plus the operations it started. Five seconds: the order of * `TOOL_TEARDOWN_TIMEOUT_MS`, and for the same reason — both sit on the * shutdown path (`close()` drains in-flight requests), where an unbounded wait * turns a container stop into a wait for SIGKILL — while leaving a store room * for a few ordinary writes. See * {@link StandingAgentBaseOptions.turnArtifactsTimeoutMs}. */ export declare const TURN_ARTIFACTS_TIMEOUT_MS = 5000; /** * One shared agent, serving every session — the original shape, and still the * right one for most deployments. * * An `Agent` instance holds per-run state on itself, so one instance can only * be in one run at a time. That is why this shape SERIALIZES globally: not a * tuning choice, a correctness requirement. See * {@link StandingAgentPoolOptions.agentFactory} for the shape that runs * sessions in parallel, and `standingAgent`'s own doc for the full comparison. */ export interface StandingAgentSharedOptions extends StandingAgentBaseOptions { /** * The agent that answers. ONE instance, shared by every session — which is * why this shape runs one request at a time, globally (see * {@link ConcurrentInvokePolicy} for the separate question of two turns of * the SAME conversation). * * The composer only BORROWS it: `close()` drains its telemetry and leaves it * usable, per {@link StandingAgentBaseOptions.shutdown}. */ readonly agent: Agent; /** Refused beside `agent` — see {@link StandingAgentPoolOptions.agentFactory}. */ readonly agentFactory?: undefined; /** Meaningless without a pool; refused rather than ignored. */ readonly maxActiveSessions?: undefined; } /** * One agent PER ACTIVE SESSION, built on demand — sessions run in parallel * (9.10.0). */ export interface StandingAgentPoolOptions extends StandingAgentBaseOptions { /** Refused beside `agentFactory` — two spellings of one choice. */ readonly agent?: undefined; /** * Build an agent. Called once per session that arrives and is not already in * the pool; the instance it returns serves that session and nobody else. * * ── What it buys ────────────────────────────────────────────────────────── * **Sessions run at the same time.** Two people asking two questions are two * instances and two runs; neither waits for the other. Within one session the * turns still serialize — on that session's own instance — which is the same * correctness rule the shared shape enforces globally, applied where it * actually binds. * * ── What it costs ───────────────────────────────────────────────────────── * An instance per active session: memory, and whatever your agent builds at * construction (a provider client, tool wiring). The pool is bounded by * {@link StandingAgentPoolOptions.maxActiveSessions} and evicts least * recently used, which is invisible to the user because the CONVERSATION * lives in the session store — an evicted session re-hydrates onto a fresh * instance on its next request. * * ── The one law ─────────────────────────────────────────────────────────── * **Return a NEW agent every call.** A factory that hands back an instance it * has already handed back is refused BY NAME on the spot: two sessions on one * instance is the exact corruption the pool exists to prevent, and it would * otherwise show up as one user's answer appearing in another user's * conversation with nothing in the recording to say so. Build the agent * INSIDE the factory; do not close over one. * * Instances the factory makes are the composer's, so it stops them — on * eviction, and on `close()` unless * {@link StandingAgentBaseOptions.shutdown} is `'none'`. * * @example * await standingAgent({ * agentFactory: () => Agent.create({ provider, model }).system('…').build(), * sessions: sqliteSessions({ file: './sessions.db' }), * host: nodeHost({ port: 8080 }), * maxActiveSessions: 200, * }); */ readonly agentFactory: () => Agent; /** * How many sessions hold an instance at once. Default * {@link DEFAULT_MAX_ACTIVE_SESSIONS} (100). Must be a positive integer. * * When a new session arrives at a full pool, the least recently used session * that is NOT running is retired: its tool sessions are closed with reason * `'evicted'`, its agent is shut down, and its conversation stays in the * session store. Nothing about that is visible to the person on the other * end — their next message hydrates the same conversation onto a fresh * instance. * * **A running session is never evicted.** If every session in the pool is * busy, the pool grows past this number rather than tearing down a live run: * the bound is on how many idle instances are RETAINED, and losing somebody's * answer to a cache policy is not a trade this composer will make on your * behalf. It comes back under the bound as soon as a run finishes. */ readonly maxActiveSessions?: number; } /** * Options for {@link standingAgent} — pick ONE of the two agent shapes. * * - `{ agent }` — one instance shared by every session, serialized globally. * See {@link StandingAgentSharedOptions}. * - `{ agentFactory }` — one instance per active session, sessions in * parallel. See {@link StandingAgentPoolOptions}. * * Passing both is refused by name at construction: they are two spellings of * the same decision, and which one won would be invisible. */ export type StandingAgentOptions = StandingAgentSharedOptions | StandingAgentPoolOptions; //# sourceMappingURL=types.d.ts.map