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

The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.

/**
 * 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 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.
 *
 * ── Why the ports look like nothing in particular ────────────────────────────
 * Deliberately. Not one field, name or assumption here comes from any hosting
 * product, cloud or protocol. A port shaped around one provider's request
 * envelope stops being a port and becomes that provider's SDK with extra steps,
 * and every adapter after the first pays for the shortcut. So the ports carry
 * an input, a reply, an optional session id, headers, a signal — the vocabulary
 * every transport already has — and everything specific to one place you might
 * deploy lives in the adapter for that place. `nodeHost` gets no special
 * treatment: its paths, status codes and JSON body shape are all in
 * `nodeHost.ts` and the port types do not know they exist. A test greps these
 * source files for vendor names, crudely and on purpose.
 *
 * ── What ships here ──────────────────────────────────────────────────────────
 *   • `nodeHost({ port?, hostname?, invokePath?, healthPath? })` — plain
 *     `node:http`, zero dependencies. `POST /invoke`, `GET /health`, and
 *     Server-Sent Events when the caller asks for them.
 *   • `httpHost({ name, wire, invokePath, healthPath, ... })` — the HTTP work
 *     itself, parameterised by the JSON dialect it speaks. `nodeHost` is one
 *     configuration of it; an adapter for someone's container runtime is
 *     another. Two paths and five body shapes are all a second HTTP adapter
 *     re-decides. 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.
 *   • `sqliteSessions({ file })` — the same port, in a file, so a restart is not
 *     an amnesia event. Conversations AND runs paused waiting on a person, in
 *     one table, on Node's built-in `node:sqlite` — nothing to install and no
 *     peer dependency. One machine, one file, one writer at a time is the
 *     stated ceiling; it is not a distributed store. Refuses BY NAME on a Node
 *     without `node:sqlite` rather than falling back to memory, because a store
 *     that silently forgot everything looks exactly like a new user.
 *   • `standingAgent({ agent, sessions, host, durability? })` — the composer.
 *     `{ agentFactory }` instead of `{ agent }` gives every ACTIVE SESSION its
 *     own agent, so sessions run in parallel while each session's turns still
 *     serialize on its own instance — bounded by `maxActiveSessions`, evicted
 *     least-recently-used, and invisible when it evicts because the
 *     conversation lives in the store rather than in the instance.
 *   • `toEnvelope` / `readEnvelope` — pack a conversation, and refuse by name to
 *     unpack a format this runtime does not know.
 *   • `toPausedEnvelope` / `readPausedRun` — the same for a run that stopped to
 *     ask a person something (`'flowchart-v1'`). `checkEnvelope` validates
 *     either without committing to which half you wanted — what a STORE wants.
 *   • `UnreadableEnvelopeError` — the refusal every reader and every store
 *     adapter inherits when a stored session is PRESENT but cannot be read. An
 *     unreadable stored conversation and an absent one are different facts, and
 *     only one of them is safe to answer with a fresh start.
 *   • `sessionRetention(sessions)` — how long a store keeps a conversation.
 *     The port's optional `retention()` member, feature-detected once: a store
 *     that deletes its own bytes hands back a sweep your cron calls, one whose
 *     backend expires rows hands back the policy and the step that arms it, and
 *     a store that can do neither is REFUSED BY NAME rather than sweeping
 *     nothing. Nothing here runs on a timer of its own, and no wire op deletes
 *     a conversation.
 *   • `requireCapability` — feature-detection with teeth.
 *
 * @example  An agent that stays up and remembers
 *   import { Agent } from 'agentfootprint';
 *   import { standingAgent, nodeHost, memorySessions } from 'agentfootprint/hosting';
 *
 *   const handle = await standingAgent({
 *     agent: Agent.create({ provider, model }).system('You help customers.').build(),
 *     sessions: memorySessions(),
 *     host: nodeHost({ port: 8080 }),
 *   });
 *   process.on('SIGTERM', () => void handle.close());
 */
export { nodeHost, jsonWire, jsonWireWith, DEFAULT_SESSION_HEADER, DEFAULT_NODE_MAX_BODY_BYTES, } from './nodeHost.js';
export type { NodeHost, NodeHostHandle, NodeHostOptions, JsonWireOptions } from './nodeHost.js';
export { httpHost, headerValue } from './httpHost.js';
export type { ConversationHandshake, HandshakeFacts, HttpHost, HttpHostHandle, HttpHostOptions, FailureOrigin, HttpRequestFacts, HttpWire, StreamFrame, StreamFraming, } from './httpHost.js';
export type { HeldConversation, PlanFacts, ProtocolAdapter, ProtocolPlan, ProtocolRequestFacts, ProtocolTurn, RunRefusal, RunSettlement, RunTranslation, StreamRunContext, ThreadBinder, ThreadBinding, } from './protocolAdapter.js';
export { streamHandler, DEFAULT_STREAM_HEARTBEAT_MS, DEFAULT_STREAM_MAX_BODY_BYTES, type StreamHandler, type StreamHandlerOptions, type StreamRunner, } from './streamHandler.js';
export { verifiedThreads } from './verifiedThreads.js';
export type { RequestSealer, RequestSealFacts } from './requestSealing.js';
export { memorySessions } from './memorySessions.js';
export { sqliteSessions, SqliteUnavailableError, UnreadableSessionFileError, } from './sqliteSessions.js';
export type { SqliteSessions, SqliteSessionsOptions } from './sqliteSessions.js';
export { toEnvelope, envelopeOwner, envelopeTranscript, toPausedEnvelope, readEnvelope, readPausedRun, checkEnvelope, } from './envelope.js';
export { listedFormatOf } from './answeredPause.js';
export { standingAgent } from './standingAgent.js';
export { DEFAULT_ARTIFACT_OPS_PER_SESSION, DEFAULT_MAX_ACTIVE_SESSIONS, DEFAULT_SWEEP_LIMIT, TURN_ARTIFACTS_TIMEOUT_MS, } from './types.js';
export { requireCapability, HostClosedError, ConcurrentRunError, PauseNotCarriedError, AwaitingDecisionError, NoPendingAskError, UnreadableEnvelopeError, ConversationClosedError, FrameTooLargeError, InvalidWireOpError, ArtifactSessionRequiredError, NoArtifactStoreError, ArtifactNotFoundError, ArtifactNotCarriedError, ArtifactOpsBusyError, RecordingTooLargeForAccountError, TurnArtifactsExpiredError, RequestArtifactsRevokedError, IdentityNotVerifiedError, VerifierUnavailableError, AdmissionRefusedError, SessionOpNeedsIdentityError, SessionIndexUnavailableError, SessionRetentionUnavailableError, SessionNotFoundError, SessionOwnershipConflictError, SessionsNotCarriedError, RequestTooLargeError, WireRequestRefusal, UnsupportedMediaTypeError, OriginNotAllowedError, HostNotAllowedError, InvalidSessionIdError, } from './errors.js';
export type { IdentityFailureClass, OriginRefusalRule } from './errors.js';
export { checkSessionId, doorGuard, MAX_SESSION_ID_LENGTH } from './doorGuard.js';
export type { CrossSiteOptions, CrossSiteRefusal, DoorGuard, DoorGuardOptions, DoorRequest, } from './doorGuard.js';
export { sessionRetention } from './sessionRetention.js';
export { resolveSessionOwner } from './sessionOwnership.js';
export { formatConformanceReport, runSessionLifecycleCase, runSessionLifecycleConformance, sessionLifecycleConformance, } from './conformance/index.js';
export type { ConformanceKit, SessionLifecycleCase, SessionLifecycleCaseName, SessionLifecycleOutcome, SessionLifecycleReport, SessionStoreHarness, SessionStoreMember, } from './conformance/index.js';
export { bearerToken, verifyRequestIdentity } from './identityVerification.js';
export type { DoorIdentity, IdentityVerificationOptions, SignInOnlyIdentity, IdentityVerifier, VerifiedIdentity, } from './identityVerification.js';
export { CREDENTIAL_HEADERS, readSignIn, signInKeyOf, withoutCredentials, type HeaderBag, type SignInRead, } from './signin/cookie.js';
export { signInSource, type SignInSourceOptions, type SignIns } from './signin/source.js';
export { accountKeyOf, signInDoor, WRONG_CREDENTIAL_SENTENCE, type SignInDoor, type SignInDoorOptions, } from './signin/door.js';
export { DEFAULT_SIGN_IN_MAX, DEFAULT_SIGN_INS_PER_ACCOUNT, memorySignIns, type MemorySignIns, type MemorySignInsOptions, } from './signin/memorySignIns.js';
export { MemorySignInsConfigError, PasswordCheckUnreachableError, SignInDoorConfigError, SignInStoreFullError, } from './signin/errors.js';
export type { CheckGateOptions } from './signin/checkGate.js';
export { SIGN_IN_AUDIT_PREFIX, signInAuditLine, type AdSubCodeName, type PasswordCheckDetail, type PasswordRefusalReason, type SignInAuditRecord, type SignInAuditSink, type SignInOutcome, type SignInReason, } from './signin/audit.js';
export type { AttemptLimits } from './signin/limits.js';
export { safeReturnTo } from './signin/returnTo.js';
export { randomSealKey, sealKeyFrom, type SealKey } from './signin/seal.js';
export { SIGN_IN_COOKIE, SIGN_IN_COOKIE_LOCALHOST, type HostSignInOptions, RedirectSignInError, type PasswordAccepted, type PasswordChecker, type PasswordKind, type RedirectFailure, type RedirectSignIn, type SignInAccepted, type SignInAttempt, type SignIn, type SignInSource, type SignInStore, } from './signin/types.js';
export { spendKeyFor, spendLedger, turnsPerHour } from './admission.js';
export type { AdmissionContext, AdmissionPolicy, AdmissionVerdict, RecentSpend, SpendLedger, SpendLedgerOptions, TurnsPerHourOptions, } from './admission.js';
export type { IngressAdmissionVerdict, IngressDoor, IngressOutcome, IngressRecord, IngressSink, } from './ingressRecord.js';
export { readSessionWireOp, sessionWireBody, SESSION_LIST_OP, SESSION_TRANSCRIPT_OP, SESSION_PENDING_OP, } from './sessionWire.js';
export type { SessionSummary, SessionWireRequest, SessionWireResult, TranscriptMessage, } from './sessionWire.js';
export { ALL_WIRE_OPS, isWireOp, refuseUnknownWireOp, WIRE_OPS } from './wireOps.js';
export type { WireOpName } from './wireOps.js';
export { readArtifactWireOp, artifactWireBody, ARTIFACT_HEAD_OP, ARTIFACT_GET_OP, } from './artifactWire.js';
export type { AnswerAccountWireBody, ArtifactWireRequest, ArtifactWireResult, } from './artifactWire.js';
export type { AnswerAccountsOptions } from './answerAccounts.js';
export type { AgentHost, ArtifactsForRequestInput, ArtifactsForRequestResult, CheckpointEnvelope, ConcurrentInvokePolicy, ConversationClose, ConversationEnvelope, ConversationHandler, ConversationHost, ConversationLimits, DurabilityMode, HostCapability, HostConversation, HostHandle, HostHandler, HostRefusal, HostReply, HostRequest, PausedRun, PausedRunEnvelope, PausedWire, PendingAsk, SessionExpiryPolicy, SessionLifecycle, SessionListOptions, SessionListPage, SessionRetention, SessionSweep, SessionSweepOptions, SessionSweepResult, StandingAgentBaseOptions, StandingAgentHandle, StandingAgentOptions, StandingAgentPoolOptions, StandingAgentSharedOptions, TurnArtifacts, Unsubscribe, WakeReason, } from './types.js';