agentfootprint 7.24.0 → 7.26.0

package/dist/esm/core/agent/types.d.ts

@@ -21,6 +21,7 @@ import type { ReliabilityScope } from '../../reliability/types.js';
 import type { WindowRecord } from './window/types.js';
 import type { MessagesDelivery } from './delivery/types.js';
 import type { MiddlewareDecision } from './middleware/types.js';
+import type { OutputAttempt } from './outputEnforcement.js';
 /**
  * Dials for the deferred observer queue (RFC-001) — only meaningful with
  * `observerDelivery: 'deferred'` (passing them without it throws at
@@ -360,6 +361,23 @@ export interface AgentState {
      *  taken later can find the moment the text changed and who changed it.
      *  Written only by an agent that configured a chain; absent otherwise. */
     middlewareDecisions?: readonly MiddlewareDecision[];
+    /** One row per final-answer attempt, in order: what was answered, whether
+     *  it satisfied the schema, and — when it did not — the validator's own
+     *  words and the correction that went back. Read it from
+     *  `snapshot.sharedState` to see why a run took three turns to answer.
+     *  Written only by an agent that opted into `retries`; absent otherwise. */
+    outputAttempts?: readonly OutputAttempt[];
+    /** In-flight hand-off from the Route decider (which judges the answer and
+     *  picks the branch) to the retry stage (which writes the correction). Not
+     *  a record — the record is `outputAttempts`. Always freshly written by the
+     *  decider immediately before the retry branch runs, so it is never read
+     *  stale. */
+    outputSchemaFailure?: {
+        readonly attempt: number;
+        readonly stage: 'json-parse' | 'schema-validate';
+        readonly error: string;
+        readonly path?: string;
+    };
     /** Set by the seed / prepare-final stage when a `messageMiddleware` returned
      *  `deny`. Read at the API boundary, where it becomes a `MessageDeniedError`.
      *  Never carries the refused content — see MessageDeniedError. */

package/dist/esm/core/outputSchema.d.ts

@@ -69,6 +69,21 @@ export interface OutputSchemaParser<T> {
      */
     readonly description?: string;
 }
+/**
+ * How the schema reaches the model.
+ *
+ *   • `'instruct'` (default) — the shape is described in the system prompt
+ *     and the model is asked for JSON. Works on every provider, because it
+ *     is only words.
+ *   • `'tool-forced'` — the shape is presented as a synthetic tool and the
+ *     provider's tool choice is FORCED to it, so generation is constrained
+ *     at the source instead of requested in prose. Requires a provider that
+ *     declares `carriesForcedToolChoice`; a provider that does not is
+ *     refused BY NAME at run start rather than quietly downgraded, because
+ *     a strategy that silently falls back to the other one is config that
+ *     lies.
+ */
+export type OutputSchemaStrategy = 'instruct' | 'tool-forced';
 /**
  * Optional configuration for `outputSchema`.
  */
@@ -88,6 +103,42 @@ export interface OutputSchemaOptions {
      * domain-specific framing.
      */
     readonly instruction?: string;
+    /**
+     * How many corrective re-asks the run may spend when the final answer
+     * fails the schema. Default `0` — the historical behaviour, where the
+     * first answer is the only answer and `runTyped()` throws on a bad one.
+     *
+     * Each retry is a REAL turn: the failed answer and an authored corrective
+     * message join the conversation, the ReAct loop re-enters, and the next
+     * attempt gets its own `llm_start`/`llm_end` bracket and its own
+     * `cost.tick` against `costBudget`. A retry therefore consumes one
+     * iteration of the agent's budget, the same way a tool call does.
+     *
+     * When the cap is spent the last answer stands and `runTyped()` throws
+     * `OutputSchemaError` exactly as it always has — `.outputFallback()`
+     * composes on top, unchanged.
+     */
+    readonly retries?: number;
+    /**
+     * How the schema reaches the model. Default `'instruct'`.
+     * See {@link OutputSchemaStrategy}.
+     */
+    readonly strategy?: OutputSchemaStrategy;
+    /**
+     * The JSON Schema for the synthetic tool, required by
+     * `strategy: 'tool-forced'` unless the parser can produce one itself
+     * (a `toJsonSchema()` method, which ArkType has). The library will not
+     * infer a shape from a `parse()` function — guessing what your schema
+     * means is not a thing it gets to do.
+     *
+     * This value and the parser CAN disagree. Nothing here prevents that,
+     * and nothing needs to: the forced shape satisfies the wire, the parser
+     * still judges the answer, and a disagreement surfaces as an ordinary
+     * validation failure that the retry loop corrects using the validator's
+     * own words. The schema constrains generation; the parser remains the
+     * judge.
+     */
+    readonly jsonSchema?: Readonly<Record<string, unknown>>;
 }
 /**
  * Thrown by `agent.parseOutput(...)` / `agent.runTyped(...)` when the

package/dist/esm/core/outputSchema.js.map

@@ -1 +1 @@
-{"version":3,"file":"outputSchema.js","sourceRoot":"","sources":["../../../src/core/outputSchema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AA6CH;;;;;;;GAOG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,SAAS,CAAS;IAClB,KAAK,CAAmC;IAC/B,KAAK,CAAW;IAElC,YACE,OAAe,EACf,IAAqF;QAErF,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IACxD,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAmC;IACzE,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,sBAAsB,MAAM,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACnF,OAAO,CACL,2DAA2D;QAC3D,6DAA6D;QAC7D,IAAI,CACL,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAI,GAAW,EAAE,MAA6B;IAC7E,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,iBAAiB,CACzB,gFAAgF,EAChF,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,CAC/C,CAAC;IACJ,CAAC;IACD,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,iBAAiB,CAAC,iEAAiE,EAAE;YAC7F,SAAS,EAAE,GAAG;YACd,KAAK,EAAE,iBAAiB;YACxB,KAAK;SACN,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}
+{"version":3,"file":"outputSchema.js","sourceRoot":"","sources":["../../../src/core/outputSchema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAiGH;;;;;;;GAOG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,SAAS,CAAS;IAClB,KAAK,CAAmC;IAC/B,KAAK,CAAW;IAElC,YACE,OAAe,EACf,IAAqF;QAErF,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IACxD,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAmC;IACzE,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,sBAAsB,MAAM,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACnF,OAAO,CACL,2DAA2D;QAC3D,6DAA6D;QAC7D,IAAI,CACL,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAI,GAAW,EAAE,MAA6B;IAC7E,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,iBAAiB,CACzB,gFAAgF,EAChF,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,CAC/C,CAAC;IACJ,CAAC;IACD,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,iBAAiB,CAAC,iEAAiE,EAAE;YAC7F,SAAS,EAAE,GAAG;YACd,KAAK,EAAE,iBAAiB;YACxB,KAAK;SACN,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}

package/dist/esm/events/payloads.d.ts

@@ -106,7 +106,13 @@ export interface AgentIterationEndPayload {
 export interface AgentRouteDecidedPayload {
     readonly turnIndex: number;
     readonly iterIndex: number;
-    readonly chosen: 'tool-calls' | 'final';
+    /**
+     * The branch the turn took. `'output-retry'` (7.26) appears only on an
+     * agent built with `.outputSchema(parser, { retries })`, and only on a
+     * turn whose answer failed the schema with retries left — the loop is
+     * about to ask again rather than finish.
+     */
+    readonly chosen: 'tool-calls' | 'final' | 'output-retry';
     readonly rationale?: string;
 }
 export interface AgentHandoffPayload {
@@ -621,6 +627,46 @@ export interface EvalThresholdCrossedPayload {
  * Fires BEFORE PostDecide rules evaluate, so observability sees the
  * failure even if a buggy rule routes to fail-fast or swallows it.
  */
+/**
+ * Emitted (7.26) once per failed final answer that the run is about to
+ * ASK AGAIN about, on an agent built with
+ * `.outputSchema(parser, { retries })`.
+ *
+ * Its sibling `agent.output_schema_validation_failed` reports a failure the
+ * reliability gate is handling INSIDE one `call-llm` stage. This one reports
+ * a failure the LOOP is handling: the corrective message named here joins the
+ * conversation, the ReAct loop re-enters, and the next attempt arrives with
+ * its own `stream.llm_start` / `stream.llm_end` bracket and its own
+ * `cost.tick`. Subscribe to it to see how often a model needs a second ask —
+ * a leading indicator of drift, and of a schema that is harder to hit than
+ * its author thinks.
+ *
+ * Fires from the retry branch, after the corrective turn is committed, so a
+ * consumer that reads `snapshot.sharedState.outputAttempts` finds the
+ * matching row (joined by `correctiveMessageHash`) already there.
+ */
+export interface AgentOutputSchemaRetryPayload {
+    /** 1-based attempt that just failed. `1` is the first answer. */
+    readonly attempt: number;
+    /** Corrective asks left AFTER this one. `0` means this is the last. */
+    readonly retriesRemaining: number;
+    /** The ReAct iteration the failed answer came from. A retry consumes an
+     *  iteration, so the next attempt reports `iteration + 1`. */
+    readonly iteration: number;
+    /** Which half of validation failed — `'json-parse'` (the model emitted
+     *  prose) vs `'schema-validate'` (JSON, wrong shape). They trend
+     *  differently under model drift. */
+    readonly stage: 'json-parse' | 'schema-validate';
+    /** The validator's own message, verbatim. DATA, not narrative: it is
+     *  quoted into the corrective message after an authored frame, and it is
+     *  quoted here the same way. */
+    readonly error: string;
+    /** Failing field path when the parser exposes one (Zod-style issues). */
+    readonly path?: string;
+    /** `fnv1a` of the corrective message that went back to the model — the
+     *  join to the message in `history` and to the `outputAttempts` row. */
+    readonly correctiveMessageHash: string;
+}
 export interface AgentOutputSchemaValidationFailedPayload {
     /** Validation error message (from Zod / parser). */
     readonly message: string;

package/dist/esm/events/registry.d.ts

@@ -16,7 +16,7 @@
  * major bump. See agentfootprint_v2_detailed_design.md for rules.
  */
 import type { AgentfootprintEventEnvelope } from './types.js';
-import type { AgentHandoffPayload, AgentIterationEndPayload, AgentIterationStartPayload, AgentRouteDecidedPayload, AgentTurnEndPayload, AgentTurnStartPayload, CompositionEnterPayload, CompositionExitPayload, ConditionalRouteDecidedPayload, ContextBudgetPressurePayload, ContextEvaluatedPayload, ContextEvictedPayload, ContextInjectedPayload, ContextSlotComposedPayload, CostLimitHitPayload, CostTickPayload, EmbeddingGeneratedPayload, ErrorFatalPayload, ErrorRecoveredPayload, ErrorRetriedPayload, EvalScorePayload, EvalThresholdCrossedPayload, AgentOutputSchemaValidationFailedPayload, AgentThinkingParseFailedPayload, StreamThinkingDeltaPayload, StreamThinkingEndPayload, FallbackTriggeredPayload, LLMEndPayload, LLMStartPayload, LLMTokenPayload, LoopIterationExitPayload, LoopIterationStartPayload, MemoryAttachedPayload, MemoryDetachedPayload, MemoryStrategyAppliedPayload, MemoryWrittenPayload, ParallelBranchCompletePayload, ParallelForkStartPayload, ParallelMergeEndPayload, PauseRequestPayload, PauseResumePayload, CheckInRequestPayload, CheckInDecisionPayload, PermissionCheckPayload, PermissionGateClosedPayload, PermissionHaltPayload, PermissionGateOpenedPayload, CredentialRequestedPayload, CredentialAcquiredPayload, CredentialAuthorizationRequiredPayload, CredentialFailedPayload, ReliabilityFailFastPayload, ReliabilityRetriedPayload, ReliabilityRecoveredPayload, RiskFlaggedPayload, SkillActivatedPayload, SkillDeactivatedPayload, SkillRejectedPayload, ToolEndPayload, ToolsActivatedPayload, ToolsDeactivatedPayload, ToolsDiscoveryStartedPayload, ToolsDiscoveryCompletedPayload, ToolsDiscoveryFailedPayload, ToolsOfferedPayload, ToolStartPayload, ValidationArgsInvalidPayload, MiddlewareDecisionPayload } from './payloads.js';
+import type { AgentHandoffPayload, AgentIterationEndPayload, AgentIterationStartPayload, AgentRouteDecidedPayload, AgentTurnEndPayload, AgentTurnStartPayload, CompositionEnterPayload, CompositionExitPayload, ConditionalRouteDecidedPayload, ContextBudgetPressurePayload, ContextEvaluatedPayload, ContextEvictedPayload, ContextInjectedPayload, ContextSlotComposedPayload, CostLimitHitPayload, CostTickPayload, EmbeddingGeneratedPayload, ErrorFatalPayload, ErrorRecoveredPayload, ErrorRetriedPayload, EvalScorePayload, EvalThresholdCrossedPayload, AgentOutputSchemaValidationFailedPayload, AgentOutputSchemaRetryPayload, AgentThinkingParseFailedPayload, StreamThinkingDeltaPayload, StreamThinkingEndPayload, FallbackTriggeredPayload, LLMEndPayload, LLMStartPayload, LLMTokenPayload, LoopIterationExitPayload, LoopIterationStartPayload, MemoryAttachedPayload, MemoryDetachedPayload, MemoryStrategyAppliedPayload, MemoryWrittenPayload, ParallelBranchCompletePayload, ParallelForkStartPayload, ParallelMergeEndPayload, PauseRequestPayload, PauseResumePayload, CheckInRequestPayload, CheckInDecisionPayload, PermissionCheckPayload, PermissionGateClosedPayload, PermissionHaltPayload, PermissionGateOpenedPayload, CredentialRequestedPayload, CredentialAcquiredPayload, CredentialAuthorizationRequiredPayload, CredentialFailedPayload, ReliabilityFailFastPayload, ReliabilityRetriedPayload, ReliabilityRecoveredPayload, RiskFlaggedPayload, SkillActivatedPayload, SkillDeactivatedPayload, SkillRejectedPayload, ToolEndPayload, ToolsActivatedPayload, ToolsDeactivatedPayload, ToolsDiscoveryStartedPayload, ToolsDiscoveryCompletedPayload, ToolsDiscoveryFailedPayload, ToolsOfferedPayload, ToolStartPayload, ValidationArgsInvalidPayload, MiddlewareDecisionPayload } from './payloads.js';
 export declare const EVENT_NAMES: {
     readonly composition: {
         readonly enter: "agentfootprint.composition.enter";
@@ -36,6 +36,7 @@ export declare const EVENT_NAMES: {
         readonly routeDecided: "agentfootprint.agent.route_decided";
         readonly handoff: "agentfootprint.agent.handoff";
         readonly outputSchemaValidationFailed: "agentfootprint.agent.output_schema_validation_failed";
+        readonly outputSchemaRetry: "agentfootprint.agent.output_schema_retry";
         readonly thinkingParseFailed: "agentfootprint.agent.thinking_parse_failed";
     };
     readonly stream: {
@@ -143,6 +144,7 @@ export interface AgentfootprintEventMap {
     'agentfootprint.agent.route_decided': AgentfootprintEventEnvelope<'agentfootprint.agent.route_decided', AgentRouteDecidedPayload>;
     'agentfootprint.agent.handoff': AgentfootprintEventEnvelope<'agentfootprint.agent.handoff', AgentHandoffPayload>;
     'agentfootprint.agent.output_schema_validation_failed': AgentfootprintEventEnvelope<'agentfootprint.agent.output_schema_validation_failed', AgentOutputSchemaValidationFailedPayload>;
+    'agentfootprint.agent.output_schema_retry': AgentfootprintEventEnvelope<'agentfootprint.agent.output_schema_retry', AgentOutputSchemaRetryPayload>;
     'agentfootprint.agent.thinking_parse_failed': AgentfootprintEventEnvelope<'agentfootprint.agent.thinking_parse_failed', AgentThinkingParseFailedPayload>;
     'agentfootprint.stream.llm_start': AgentfootprintEventEnvelope<'agentfootprint.stream.llm_start', LLMStartPayload>;
     'agentfootprint.stream.llm_end': AgentfootprintEventEnvelope<'agentfootprint.stream.llm_end', LLMEndPayload>;

package/dist/esm/events/registry.js

@@ -37,6 +37,7 @@ export const EVENT_NAMES = {
         routeDecided: 'agentfootprint.agent.route_decided',
         handoff: 'agentfootprint.agent.handoff',
         outputSchemaValidationFailed: 'agentfootprint.agent.output_schema_validation_failed',
+        outputSchemaRetry: 'agentfootprint.agent.output_schema_retry',
         thinkingParseFailed: 'agentfootprint.agent.thinking_parse_failed',
     },
     stream: {
@@ -148,6 +149,7 @@ export const ALL_EVENT_TYPES = [
     'agentfootprint.agent.route_decided',
     'agentfootprint.agent.handoff',
     'agentfootprint.agent.output_schema_validation_failed',
+    'agentfootprint.agent.output_schema_retry',
     'agentfootprint.agent.thinking_parse_failed',
     'agentfootprint.stream.llm_start',
     'agentfootprint.stream.llm_end',

package/dist/esm/events/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/events/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA0EH,yEAAyE;AACzE,gEAAgE;AAChE,wEAAwE;AACxE,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,WAAW,EAAE;QACX,KAAK,EAAE,kCAAkC;QACzC,IAAI,EAAE,iCAAiC;QACvC,SAAS,EAAE,uCAAuC;QAClD,cAAc,EAAE,4CAA4C;QAC5D,QAAQ,EAAE,sCAAsC;QAChD,YAAY,EAAE,0CAA0C;QACxD,cAAc,EAAE,4CAA4C;QAC5D,aAAa,EAAE,2CAA2C;KAC3D;IACD,KAAK,EAAE;QACL,SAAS,EAAE,iCAAiC;QAC5C,OAAO,EAAE,+BAA+B;QACxC,cAAc,EAAE,sCAAsC;QACtD,YAAY,EAAE,oCAAoC;QAClD,YAAY,EAAE,oCAAoC;QAClD,OAAO,EAAE,8BAA8B;QACvC,4BAA4B,EAAE,sDAAsD;QACpF,mBAAmB,EAAE,4CAA4C;KAClE;IACD,MAAM,EAAE;QACN,QAAQ,EAAE,iCAAiC;QAC3C,MAAM,EAAE,+BAA+B;QACvC,KAAK,EAAE,6BAA6B;QACpC,SAAS,EAAE,kCAAkC;QAC7C,OAAO,EAAE,gCAAgC;QACzC,aAAa,EAAE,sCAAsC;QACrD,WAAW,EAAE,oCAAoC;KAClD;IACD,OAAO,EAAE;QACP,QAAQ,EAAE,iCAAiC;QAC3C,OAAO,EAAE,gCAAgC;QACzC,YAAY,EAAE,sCAAsC;QACpD,cAAc,EAAE,wCAAwC;QACxD,SAAS,EAAE,kCAAkC;KAC9C;IACD,MAAM,EAAE;QACN,eAAe,EAAE,wCAAwC;QACzD,QAAQ,EAAE,gCAAgC;QAC1C,QAAQ,EAAE,gCAAgC;QAC1C,OAAO,EAAE,+BAA+B;KACzC;IACD,KAAK,EAAE;QACL,OAAO,EAAE,8BAA8B;QACvC,SAAS,EAAE,gCAAgC;QAC3C,WAAW,EAAE,kCAAkC;QAC/C,gBAAgB,EAAE,wCAAwC;QAC1D,kBAAkB,EAAE,0CAA0C;QAC9D,eAAe,EAAE,uCAAuC;KACzD;IACD,KAAK,EAAE;QACL,SAAS,EAAE,gCAAgC;QAC3C,WAAW,EAAE,kCAAkC;QAC/C,QAAQ,EAAE,+BAA+B;KAC1C;IACD,UAAU,EAAE;QACV,WAAW,EAAE,wCAAwC;KACtD;IACD,UAAU,EAAE;QACV,KAAK,EAAE,iCAAiC;QACxC,UAAU,EAAE,uCAAuC;QACnD,UAAU,EAAE,uCAAuC;QACnD,IAAI,EAAE,gCAAgC;KACvC;IACD,UAAU,EAAE;QACV,SAAS,EAAE,qCAAqC;QAChD,QAAQ,EAAE,oCAAoC;QAC9C,qBAAqB,EAAE,kDAAkD;QACzE,MAAM,EAAE,kCAAkC;KAC3C;IACD,IAAI,EAAE;QACJ,OAAO,EAAE,6BAA6B;KACvC;IACD,QAAQ,EAAE;QACR,SAAS,EAAE,mCAAmC;KAC/C;IACD,IAAI,EAAE;QACJ,IAAI,EAAE,0BAA0B;QAChC,QAAQ,EAAE,+BAA+B;KAC1C;IACD,IAAI,EAAE;QACJ,KAAK,EAAE,2BAA2B;QAClC,gBAAgB,EAAE,uCAAuC;KAC1D;IACD,KAAK,EAAE;QACL,OAAO,EAAE,8BAA8B;QACvC,SAAS,EAAE,gCAAgC;QAC3C,KAAK,EAAE,4BAA4B;KACpC;IACD,WAAW,EAAE;QACX,QAAQ,EAAE,sCAAsC;QAChD,OAAO,EAAE,oCAAoC;QAC7C,SAAS,EAAE,sCAAsC;KAClD;IACD,KAAK,EAAE;QACL,OAAO,EAAE,8BAA8B;QACvC,MAAM,EAAE,6BAA6B;KACtC;IACD,OAAO,EAAE;QACP,OAAO,EAAE,gCAAgC;QACzC,QAAQ,EAAE,iCAAiC;KAC5C;IACD,UAAU,EAAE;QACV,QAAQ,EAAE,oCAAoC;KAC/C;IACD,SAAS,EAAE;QACT,SAAS,EAAE,oCAAoC;KAChD;CACO,CAAC;AAiTX;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAuC;IACjE,kCAAkC;IAClC,iCAAiC;IACjC,uCAAuC;IACvC,4CAA4C;IAC5C,sCAAsC;IACtC,0CAA0C;IAC1C,4CAA4C;IAC5C,2CAA2C;IAC3C,iCAAiC;IACjC,+BAA+B;IAC/B,sCAAsC;IACtC,oCAAoC;IACpC,oCAAoC;IACpC,8BAA8B;IAC9B,sDAAsD;IACtD,4CAA4C;IAC5C,iCAAiC;IACjC,+BAA+B;IAC/B,6BAA6B;IAC7B,kCAAkC;IAClC,gCAAgC;IAChC,sCAAsC;IACtC,oCAAoC;IACpC,iCAAiC;IACjC,gCAAgC;IAChC,sCAAsC;IACtC,wCAAwC;IACxC,kCAAkC;IAClC,wCAAwC;IACxC,gCAAgC;IAChC,gCAAgC;IAChC,+BAA+B;IAC/B,8BAA8B;IAC9B,gCAAgC;IAChC,kCAAkC;IAClC,wCAAwC;IACxC,0CAA0C;IAC1C,uCAAuC;IACvC,wCAAwC;IACxC,gCAAgC;IAChC,kCAAkC;IAClC,+BAA+B;IAC/B,iCAAiC;IACjC,uCAAuC;IACvC,uCAAuC;IACvC,gCAAgC;IAChC,qCAAqC;IACrC,oCAAoC;IACpC,kDAAkD;IAClD,kCAAkC;IAClC,6BAA6B;IAC7B,mCAAmC;IACnC,0BAA0B;IAC1B,+BAA+B;IAC/B,2BAA2B;IAC3B,uCAAuC;IACvC,8BAA8B;IAC9B,gCAAgC;IAChC,4BAA4B;IAC5B,sCAAsC;IACtC,oCAAoC;IACpC,sCAAsC;IACtC,8BAA8B;IAC9B,6BAA6B;IAC7B,gCAAgC;IAChC,iCAAiC;IACjC,oCAAoC;IACpC,oCAAoC;CAC5B,CAAC"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/events/registry.ts"],"names":[],"mappings":"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"}

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

@@ -17,7 +17,7 @@
  * `Error`: nothing branches on "I forgot to feature-detect", it just needs to
  * say so loudly and name the adapter it is talking about.
  */
-import type { AgentHost, HostCapability, PendingAsk } from './types.js';
+import type { AgentHost, ConversationHost, HostCapability, PendingAsk } from './types.js';
 /**
  * Thrown when a request arrives at a host that is shutting down or shut down.
  *
@@ -110,6 +110,44 @@ export declare class NoPendingAskError extends Error {
     readonly sessionId: string;
     constructor(sessionId: string);
 }
+/**
+ * Thrown when something is sent down a conversation that has already ended.
+ *
+ * A closed channel that accepts frames and drops them is the worst of the three
+ * options: the sender believes the far side got it, the far side never did, and
+ * nothing anywhere says so. Refusing by name is the only version of this that
+ * leaves a trace.
+ *
+ * `onClose` is how you avoid meeting this — subscribe, and stop sending.
+ */
+export declare class ConversationClosedError extends Error {
+    readonly code: "ERR_CONVERSATION_CLOSED";
+    /** Which adapter's door this was. */
+    readonly hostName: string;
+    /** The session the conversation claimed, when it claimed one. */
+    readonly sessionId?: string;
+    constructor(hostName: string, sessionId?: string);
+}
+/**
+ * Thrown when a frame is bigger than the ceiling the adapter DECLARED.
+ *
+ * This is the other half of {@link ConversationLimits} — a declared ceiling
+ * nothing enforces is a number in a doc comment. The port neither chunks nor
+ * truncates, on purpose: how a message is split, numbered and reassembled is
+ * the consumer's protocol question, and answering it inside the adapter would
+ * answer it for every consumer at once. So the ceiling is visible, the refusal
+ * names it, and the splitting happens above the port where the protocol lives.
+ */
+export declare class FrameTooLargeError extends Error {
+    readonly code: "ERR_FRAME_TOO_LARGE";
+    /** Which adapter's door refused. */
+    readonly hostName: string;
+    /** How big the frame was, in bytes of UTF-8. */
+    readonly bytes: number;
+    /** The declared ceiling it crossed. */
+    readonly maxFrameBytes: number;
+    constructor(hostName: string, bytes: number, maxFrameBytes: number);
+}
 /**
  * Thrown when a store hands back something that is **present but unreadable**
  * where a `CheckpointEnvelope` should be.
@@ -161,10 +199,14 @@ export declare class UnreadableEnvelopeError extends TypeError {
  * assumed, and asking for one that is absent tells you which adapter you are
  * actually holding rather than failing quietly somewhere downstream.
  *
+ * Takes either port, because both declare the same two facts — who they are and
+ * what they can do — and a caller holding a conversation-only host is entitled
+ * to the same answer as one holding a request host.
+ *
  * @example
  *   requireCapability(host, 'streaming'); // throws unless this host streams
  *
  *   // or branch instead of insisting:
  *   if (host.capabilities.includes('streaming')) { ... }
  */
-export declare function requireCapability(host: AgentHost, capability: HostCapability): void;
+export declare function requireCapability(host: AgentHost | ConversationHost, capability: HostCapability): void;

package/dist/esm/hosting/errors.js

@@ -168,6 +168,65 @@ export class NoPendingAskError extends Error {
         this.sessionId = sessionId;
     }
 }
+/**
+ * Thrown when something is sent down a conversation that has already ended.
+ *
+ * A closed channel that accepts frames and drops them is the worst of the three
+ * options: the sender believes the far side got it, the far side never did, and
+ * nothing anywhere says so. Refusing by name is the only version of this that
+ * leaves a trace.
+ *
+ * `onClose` is how you avoid meeting this — subscribe, and stop sending.
+ */
+export class ConversationClosedError extends Error {
+    code = 'ERR_CONVERSATION_CLOSED';
+    /** Which adapter's door this was. */
+    hostName;
+    /** The session the conversation claimed, when it claimed one. */
+    sessionId;
+    constructor(hostName, sessionId) {
+        super(`[hosting] this conversation on the '${hostName}' host has ended` +
+            (sessionId !== undefined ? ` (session '${sessionId}')` : '') +
+            `, so there is nowhere for that frame to go. Refusing rather than accepting it ` +
+            `and dropping it — a send that silently goes nowhere looks identical to a send ` +
+            `that worked. Subscribe with onClose(...) and stop sending when it fires, or open ` +
+            `a new conversation.`);
+        this.name = 'ConversationClosedError';
+        this.hostName = hostName;
+        if (sessionId !== undefined)
+            this.sessionId = sessionId;
+    }
+}
+/**
+ * Thrown when a frame is bigger than the ceiling the adapter DECLARED.
+ *
+ * This is the other half of {@link ConversationLimits} — a declared ceiling
+ * nothing enforces is a number in a doc comment. The port neither chunks nor
+ * truncates, on purpose: how a message is split, numbered and reassembled is
+ * the consumer's protocol question, and answering it inside the adapter would
+ * answer it for every consumer at once. So the ceiling is visible, the refusal
+ * names it, and the splitting happens above the port where the protocol lives.
+ */
+export class FrameTooLargeError extends Error {
+    code = 'ERR_FRAME_TOO_LARGE';
+    /** Which adapter's door refused. */
+    hostName;
+    /** How big the frame was, in bytes of UTF-8. */
+    bytes;
+    /** The declared ceiling it crossed. */
+    maxFrameBytes;
+    constructor(hostName, bytes, maxFrameBytes) {
+        super(`[hosting] this frame is ${bytes} bytes and the '${hostName}' host declares a ` +
+            `maxFrameBytes of ${maxFrameBytes}. Refusing rather than truncating it or splitting ` +
+            `it for you: how a message is chunked, numbered and put back together is your ` +
+            `protocol's question, and an adapter that answered it would answer it for every ` +
+            `consumer at once. Read host.conversationLimits and chunk above the port.`);
+        this.name = 'FrameTooLargeError';
+        this.hostName = hostName;
+        this.bytes = bytes;
+        this.maxFrameBytes = maxFrameBytes;
+    }
+}
 /**
  * An already-computed preview, so {@link UnreadableEnvelopeError.withSession}
  * can copy a refusal without being handed the stored bytes a second time. Not
@@ -255,6 +314,10 @@ export class UnreadableEnvelopeError extends TypeError {
  * assumed, and asking for one that is absent tells you which adapter you are
  * actually holding rather than failing quietly somewhere downstream.
  *
+ * Takes either port, because both declare the same two facts — who they are and
+ * what they can do — and a caller holding a conversation-only host is entitled
+ * to the same answer as one holding a request host.
+ *
  * @example
  *   requireCapability(host, 'streaming'); // throws unless this host streams
  *

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

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

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

@@ -0,0 +1,16 @@
+/**
+ * hosting/headers — one lower-casing of one header bag, shared by every door.
+ *
+ * A six-line helper gets its own file for the reason every other shared piece
+ * in this folder does: two copies of it is how the request door and the
+ * conversation door end up disagreeing about whether a header the caller sent
+ * as `X-Session-Id` is present, and that disagreement would surface as one door
+ * seeing a session the other cannot.
+ */
+/// <reference types="node" />
+import type { IncomingMessage } from 'node:http';
+/**
+ * Header names lower-cased, repeated values joined — the shape every wire reads
+ * from, so no wire ever has to guess at casing.
+ */
+export declare function lowerCasedHeaders(headers: IncomingMessage['headers']): Record<string, string>;

package/dist/esm/hosting/headers.js

@@ -0,0 +1,24 @@
+/**
+ * hosting/headers — one lower-casing of one header bag, shared by every door.
+ *
+ * A six-line helper gets its own file for the reason every other shared piece
+ * in this folder does: two copies of it is how the request door and the
+ * conversation door end up disagreeing about whether a header the caller sent
+ * as `X-Session-Id` is present, and that disagreement would surface as one door
+ * seeing a session the other cannot.
+ */
+/**
+ * Header names lower-cased, repeated values joined — the shape every wire reads
+ * from, so no wire ever has to guess at casing.
+ */
+export function lowerCasedHeaders(headers) {
+    const out = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (typeof value === 'string')
+            out[name.toLowerCase()] = value;
+        else if (Array.isArray(value))
+            out[name.toLowerCase()] = value.join(', ');
+    }
+    return out;
+}
+//# sourceMappingURL=headers.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"headers.js","sourceRoot":"","sources":["../../../src/hosting/headers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAmC;IACnE,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACpD,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,GAAG,KAAK,CAAC;aAC1D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

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

@@ -34,12 +34,28 @@
  * detaches and drains without closing a socket it never opened. That is the
  * whole difference; every other law on this page is the same either way.
  *
+ * ── The third door: a conversation ───────────────────────────────────────────
+ * `serveConversations(handler)` sits beside `serve(handler)` and takes upgrades
+ * on `conversationPath`, because `HostRequest → HostReply` is one exchange and
+ * some doors are not. Give a host a `conversationPath` and it declares
+ * `'conversation'`; leave it out and `serveConversations` refuses by name.
+ *
+ * **Both doors share ONE socket.** That is not an optimisation, it is the
+ * premise: the runtimes that need a conversation are the ones that hand a
+ * container exactly one port, so a host whose two doors each bound their own
+ * would fail with `EADDRINUSE` on the deployment it exists for. On a private
+ * socket the server is created by whichever door opens first and closed by
+ * whichever closes last; on a caller-owned one each door attaches and detaches
+ * its own listener and neither touches the socket.
+ *
  * Pattern: Template method via configuration (Strategy on the wire format).
  * Everything HTTP lives here and in the wires; `types.ts` knows none of it.
  */
 /// <reference types="node" />
 import type { Server } from 'node:http';
-import type { AgentHost, HostCapability, HostHandle, HostHandler, PendingAsk } from './types.js';
+import type { AgentHost, ConversationHandler, ConversationHost, ConversationLimits, HostCapability, HostHandle, HostHandler, PendingAsk } from './types.js';
+import { type ConversationHandshake, type HandshakeFacts } from './webSocketConversation.js';
+export type { ConversationHandshake, HandshakeFacts };
 /** Everything a {@link HttpWire} may read when pulling a request apart. */
 export interface HttpRequestFacts {
     /** The parsed JSON body, or `{}` for an empty one. */
@@ -93,6 +109,17 @@ export interface HttpWire {
      * either way.
      */
     awaiting?(pending: PendingAsk): unknown;
+    /**
+     * Pull the port's vocabulary out of one conversation handshake — the session
+     * this conversation claims, any header mapping this dialect performs, and the
+     * subprotocol to echo.
+     *
+     * Optional, and absent means "raw headers, no session": there is no body in a
+     * handshake, so a dialect that wants a session id has to name where it looks,
+     * and guessing on its behalf would invent an affinity rule the deployment
+     * never agreed to.
+     */
+    readConversation?(facts: HandshakeFacts): ConversationHandshake;
 }
 /** Options for {@link httpHost}. */
 export interface HttpHostOptions {
@@ -161,6 +188,31 @@ export interface HttpHostOptions {
      *   await handle.close();
      */
     readonly server?: Server;
+    /**
+     * Path that takes a conversation upgrade.
+     *
+     * **No default, for exactly the reason `invokePath` has none** — a default
+     * here is inherited by every adapter built on this file, and one that
+     * silently matched somebody's runtime contract is that runtime leaking into a
+     * library that promises not to know about one.
+     *
+     * ABSENT is meaningful: the host does not declare `'conversation'` and
+     * {@link HttpHost.serveConversations} refuses by name. Present, and the host
+     * can carry conversations whether or not anybody serves them.
+     */
+    readonly conversationPath?: string;
+    /**
+     * What the conversation door caps. Whatever is left out is filled with this
+     * file's defaults and then DECLARED, so `conversationLimits` on the host is
+     * always what is actually enforced rather than what was passed in.
+     *
+     * An unset `maxFrameBytes` would mean an unbounded buffer somebody else
+     * fills, which is a way to kill this process; an unset `maxPendingBytes` the
+     * same, one layer up. `idleMs` has no default because this door does not idle
+     * anything out — it reports the ceiling of whatever sits in front of it, and
+     * inventing one would be reporting a fact nobody established.
+     */
+    readonly conversationLimits?: ConversationLimits;
 }
 /** A {@link HostHandle} that also says where it landed. */
 export interface HttpHostHandle extends HostHandle {
@@ -174,9 +226,18 @@ export interface HttpHostHandle extends HostHandle {
     /** The port it actually bound — the real one, when you asked for `0`. */
     readonly port: number;
 }
-/** {@link AgentHost} narrowed to an HTTP handle. */
-export interface HttpHost extends AgentHost {
+/**
+ * {@link AgentHost} and {@link ConversationHost} narrowed to an HTTP handle.
+ *
+ * One object with two doors, because they share one socket. Whether the
+ * conversation door is USABLE is `capabilities`' answer, not this type's: a
+ * host built without a `conversationPath` still has the method and refuses by
+ * name, which is a better error than a method that is missing at runtime on
+ * some adapters and present on others.
+ */
+export interface HttpHost extends AgentHost, ConversationHost {
     serve(handler: HostHandler): Promise<HttpHostHandle>;
+    serveConversations(handler: ConversationHandler): Promise<HttpHostHandle>;
 }
 /**
  * An HTTP host for one handler, speaking the dialect you hand it.
@@ -192,5 +253,10 @@ export declare function httpHost(options: HttpHostOptions): HttpHost;
  * Exported because every wire that maps a header needs it and re-deriving it
  * per adapter is how one of them ends up matching only the exact casing the
  * author happened to test with.
+ *
+ * Takes anything carrying lower-cased headers, so a request wire and a
+ * handshake wire read a header the same way rather than each growing their own.
  */
-export declare function headerValue(facts: HttpRequestFacts, name: string, ...fallbacks: string[]): string | undefined;
+export declare function headerValue(facts: {
+    readonly headers: Readonly<Record<string, string>>;
+}, name: string, ...fallbacks: string[]): string | undefined;