@anvia/core 1.0.0-rc.3 → 1.0.0-rc.5

package/README.md

@@ -12,10 +12,17 @@ The package is dependency-injection oriented: create provider models, typed tool
 
 ## Installation
 
+Anvia 1.0 is currently published on npm under the `rc` tag. The unqualified `latest` tag remains
+on the maintenance-only v0 line until 1.0 reaches general availability. Keep Core and every Anvia
+adapter on the same release channel.
+
 ```sh
-pnpm add @anvia/core
+pnpm add @anvia/core@rc
 ```
 
+See the repository's [1.0 release policy](../../docs/releases/v1.md) for channel and support
+details.
+
 In this monorepo, the package is available through the workspace:
 
 ```sh
@@ -184,7 +191,9 @@ keys. Cancellation is forwarded to provider SDK calls and is never retried.
 
 Agents own their default retry policy. A run with no `retries` value inherits the Agent setting;
 `false` disables it for that run; an object replaces it for that run. Retries apply to the current
-provider call only, so completed tools and earlier turns are never replayed.
+completion only, so completed tools and earlier turns are never replayed. `maxAttempts` is the
+total number of model attempts for that completion, including the initial attempt; it is not the
+number of additional retries.
 
 ```ts
 const agent = new Agent({
@@ -201,6 +210,19 @@ await agent.generate({
 });
 ```
 
+When an Agent has `outputSchema`, JSON parsing and schema-validation failures use the same retry
+budget when retries are explicitly enabled. A correction request includes the rejected response in
+the provider transcript and asks for raw JSON matching the schema, without Markdown or commentary.
+Transport failures and structured-output failures therefore cannot exceed `maxAttempts` in total.
+
+Structured output remains strict: Core trims surrounding whitespace, parses JSON, and validates the
+result with the configured Zod schema. As a compatibility fallback for OpenAI-compatible providers
+that violate strict JSON mode, Core also accepts a response consisting entirely of one lowercase
+`json` Markdown fence or one unlabeled Markdown fence. It does not search prose for JSON, accept
+content before or after a fence, or bypass schema validation. `AgentStructuredOutputError` reports
+the `parse` or `schema` phase, attempt counts, output length/format metadata, cumulative attempt
+usage, and the original `cause`; its message never contains the rejected model response.
+
 Agent results are discriminated by `status`. Completed results include typed `output` and `text`;
 guardrail blocks return `status: "blocked"`, `stage`, and `text`; tool approvals and first-class
 questions return a JSON-safe `status: "suspended"` result.
@@ -233,6 +255,17 @@ continuation and current Agent/tool registration but does not provide a durable
 or exactly-once execution. Use `createQuestionTool({ name, description })` when a model must ask for
 structured free-text or choice answers.
 
+Import JSON-safe interaction contracts and parsers from their browser-safe subpath. This entrypoint
+does not load the Agent runtime, MCP clients, or Node infrastructure:
+
+```ts
+import {
+  type AgentInteractionResponse,
+  parseAgentInteractionRequest,
+  parseAgentInteractionResponse,
+} from "@anvia/core/agent/interactions";
+```
+
 An Agent with `outputSchema` carries that output type through `generate`, `stream`, `asTool`, and
 Pipeline Agent stages. Agent stream finals use the same result shape:
 
@@ -497,7 +530,8 @@ added to Agent instructions.
 
 ## Public Areas
 
-- `agent`: typed Agent runtime, continuations, interactions, retries, and stream events
+- `agent`: typed Agent runtime, retries, and stream events
+- `agent/interactions`: browser-safe interaction contracts, schemas, assertions, and parsers
 - `tool`: typed tool creation and tool sets
 - `completion`: direct completion helpers and provider-neutral model contracts
 - `memory`: durable session memory interfaces and in-memory store

package/dist/agent/index.d.ts

@@ -1,10 +1,9 @@
 export { M as ModelCallOptions } from '../model-call-options-CZkSw_xN.js';
 export { R as RetryContext, a as RetryOptions, b as RetrySetting } from '../retry-CjvSlKGW.js';
-export { A as Agent, a as AgentContextInput, b as AgentMemory, c as AgentMemoryOptions, d as AgentOptions, e as AgentToolInput, f as AgentToolOptions, C as CreateHybridVectorContextOptions, g as CreateVectorContextOptions, V as VectorContext, h as VectorContextBaseOptions, i as createVectorContext, j as isVectorContext } from '../agent-CXScUOpX.js';
-import { M as Message } from '../types-D9rKQ_as.js';
-import { A as AgentBlockedResult, t as AgentSuspendedResult } from '../types-CElwurHZ.js';
-export { a as AgentChildStreamEvent, b as AgentDeltaEvent, c as AgentErrorEvent, d as AgentErrorStreamEvent, e as AgentFinishEvent, f as AgentInput, g as AgentLifecycle, h as AgentMemoryCompactionEvent, i as AgentPrompt, j as AgentResponse, k as AgentResult, l as AgentRunOptions, m as AgentRunSettings, n as AgentStartEvent, o as AgentSteerInput, p as AgentSteerReceipt, q as AgentStepFinishEvent, r as AgentStream, s as AgentStreamEvent, u as AgentToolCallDeltaEvent, v as AgentToolFinishEvent, w as AgentToolStartEvent } from '../types-CElwurHZ.js';
-export { A as AgentContinuation, a as AgentInteractionRequest, b as AgentInteractionResponse, d as AgentQuestionAnswer, e as AgentQuestionChoice, f as AgentQuestionPrompt, g as AgentToolApprovalRequest, h as AgentToolQuestionRequest, p as agentContinuationSchema, q as agentInteractionRequestSchema, r as agentInteractionResponseSchema, w as assertAgentInteractionResponse, t as parseAgentContinuation, u as parseAgentInteractionRequest, v as parseAgentInteractionResponse } from '../interactions-csssHYcN.js';
+export { A as Agent, a as AgentContextInput, b as AgentMemory, c as AgentMemoryOptions, d as AgentOptions, e as AgentToolInput, f as AgentToolOptions, C as CreateHybridVectorContextOptions, g as CreateVectorContextOptions, V as VectorContext, h as VectorContextBaseOptions, i as createVectorContext, j as isVectorContext } from '../agent-LlCD_2UQ.js';
+import { M as Message, U as Usage } from '../types-D9rKQ_as.js';
+import { A as AgentBlockedResult, t as AgentSuspendedResult } from '../types-1KpjDfoN.js';
+export { a as AgentChildStreamEvent, b as AgentDeltaEvent, c as AgentErrorEvent, d as AgentErrorStreamEvent, e as AgentFinishEvent, f as AgentInput, g as AgentLifecycle, h as AgentMemoryCompactionEvent, i as AgentPrompt, j as AgentResponse, k as AgentResult, l as AgentRunOptions, m as AgentRunSettings, n as AgentStartEvent, o as AgentSteerInput, p as AgentSteerReceipt, q as AgentStepFinishEvent, r as AgentStream, s as AgentStreamEvent, u as AgentToolCallDeltaEvent, v as AgentToolFinishEvent, w as AgentToolStartEvent } from '../types-1KpjDfoN.js';
 import '../zod-schema-C7F4clpm.js';
 import 'zod';
 import '../types-CIPaIbZo.js';
@@ -16,12 +15,35 @@ import '@modelcontextprotocol/sdk/client/auth.js';
 import '@modelcontextprotocol/sdk/client/streamableHttp.js';
 import '@modelcontextprotocol/sdk/shared/transport.js';
 import '../tool-r62gf3QY.js';
+import '../middleware-BqtLB_Xt.js';
 import '../types-DbolvLtZ.js';
 import '../types-RT3cuyRk.js';
 import '../dynamic-tools-AEBOTgu1.js';
 import '../types-Cr4uiYo5.js';
 import '../types-C3gv9EX6.js';
+import './interactions/index.js';
 
+type AgentStructuredOutputPhase = "parse" | "schema";
+type AgentStructuredOutputFormat = "raw" | "json-fence" | "unlabeled-fence";
+declare class AgentStructuredOutputError extends Error {
+    readonly phase: AgentStructuredOutputPhase;
+    readonly attempt: number;
+    readonly maxAttempts: number;
+    readonly outputLength: number;
+    readonly normalizedLength: number;
+    readonly outputFormat: AgentStructuredOutputFormat;
+    readonly usage: Usage;
+    constructor(options: {
+        phase: AgentStructuredOutputPhase;
+        attempt: number;
+        maxAttempts: number;
+        outputLength: number;
+        normalizedLength: number;
+        outputFormat: AgentStructuredOutputFormat;
+        usage: Usage;
+        cause: unknown;
+    });
+}
 declare class MaxTurnsError extends Error {
     readonly maxTurns: number;
     readonly chatHistory: Message[];
@@ -45,4 +67,4 @@ declare class AgentToolSuspensionError extends Error {
     constructor(result: AgentSuspendedResult);
 }
 
-export { AgentBlockedResult, AgentRunBlockedError, AgentRunCancelledError, AgentStreamClosedError, AgentSuspendedResult, AgentToolSuspensionError, MaxTurnsError };
+export { AgentBlockedResult, AgentRunBlockedError, AgentRunCancelledError, AgentStreamClosedError, AgentStructuredOutputError, type AgentStructuredOutputFormat, type AgentStructuredOutputPhase, AgentSuspendedResult, AgentToolSuspensionError, MaxTurnsError };

package/dist/agent/index.js

@@ -1,51 +1,41 @@
 import {
   Agent,
-  agentContinuationSchema,
-  agentInteractionRequestSchema,
-  agentInteractionResponseSchema,
-  assertAgentInteractionResponse,
   createVectorContext,
-  isVectorContext,
-  parseAgentContinuation,
-  parseAgentInteractionRequest,
-  parseAgentInteractionResponse
-} from "../chunk-BY4OMNIU.js";
+  isVectorContext
+} from "../chunk-FCANRQ5Q.js";
+import "../chunk-BEU6FCTN.js";
+import "../chunk-7YAH2F3J.js";
+import "../chunk-DNQNOHD5.js";
+import "../chunk-E5J4OY4K.js";
 import "../chunk-YK4WAAS4.js";
-import "../chunk-5MK3BISB.js";
 import "../chunk-CQNNSZPG.js";
-import "../chunk-KV6QCRQ4.js";
-import "../chunk-3CMWKK32.js";
-import "../chunk-KFR4CDGK.js";
-import "../chunk-VKYZZXP5.js";
+import "../chunk-JXZTTNCR.js";
+import "../chunk-RZDI7B6Z.js";
 import {
   AgentRunBlockedError,
   AgentRunCancelledError,
   AgentStreamClosedError,
+  AgentStructuredOutputError,
   AgentToolSuspensionError,
   MaxTurnsError
-} from "../chunk-TRQ3XRFD.js";
-import "../chunk-GQL5KRAH.js";
+} from "../chunk-TEV3OB7N.js";
+import "../chunk-H7BI3BSP.js";
 import "../chunk-3RM57ZT2.js";
 import "../chunk-MGNTXGTX.js";
-import "../chunk-D2ECOWN5.js";
-import "../chunk-PK5LKOFL.js";
-import "../chunk-FN7HLLAZ.js";
+import "../chunk-HSA6NL2E.js";
+import "../chunk-G5OACQEI.js";
+import "../chunk-SROQA7I7.js";
+import "../chunk-UBE4WH6G.js";
 import "../chunk-AZB6N7P4.js";
 export {
   Agent,
   AgentRunBlockedError,
   AgentRunCancelledError,
   AgentStreamClosedError,
+  AgentStructuredOutputError,
   AgentToolSuspensionError,
   MaxTurnsError,
-  agentContinuationSchema,
-  agentInteractionRequestSchema,
-  agentInteractionResponseSchema,
-  assertAgentInteractionResponse,
   createVectorContext,
-  isVectorContext,
-  parseAgentContinuation,
-  parseAgentInteractionRequest,
-  parseAgentInteractionResponse
+  isVectorContext
 };
 //# sourceMappingURL=index.js.map

package/dist/{interactions-csssHYcN.d.ts → agent/interactions/index.d.ts}

@@ -1,58 +1,6 @@
-import { e as CompletionRequest, f as CompletionResponse, o as JsonValue, x as ToolResultContentPart, J as JsonObject, _ as ToolQuestionAnswer } from './types-D9rKQ_as.js';
-import { M as MaybePromise } from './type-utils-CtHVDRn_.js';
 import { z } from 'zod';
-
-type CompletionRequestMiddlewareArgs = {
-    turn: number;
-    request: CompletionRequest;
-    originalRequest: CompletionRequest;
-};
-type CompletionRequestMiddlewareResult = {
-    request: CompletionRequest;
-} | undefined;
-type CompletionResponseMiddlewareArgs<RawResponse = unknown> = {
-    turn: number;
-    request: CompletionRequest;
-    response: CompletionResponse<RawResponse>;
-    originalResponse: CompletionResponse<RawResponse>;
-};
-type CompletionResponseMiddlewareResult<RawResponse = unknown> = {
-    response: CompletionResponse<RawResponse>;
-} | undefined;
-type ToolInputMiddlewareArgs = {
-    toolName: string;
-    args: string;
-    originalArgs: string;
-    turn: number;
-    toolCallId?: string | undefined;
-    internalCallId: string;
-};
-type ToolInputMiddlewareResult = {
-    args: JsonValue | string;
-} | undefined;
-type ToolResultMiddlewareArgs = {
-    toolName: string;
-    args: string;
-    result: string;
-    originalResult: string;
-    structuredResult?: readonly ToolResultContentPart[] | undefined;
-    originalStructuredResult?: readonly ToolResultContentPart[] | undefined;
-    turn: number;
-    toolCallId?: string | undefined;
-    internalCallId: string;
-};
-type ToolOutputMiddlewareArgs = ToolResultMiddlewareArgs;
-type ToolOutputMiddlewareResult = string | {
-    result?: string | undefined;
-    structuredResult?: readonly ToolResultContentPart[] | undefined;
-} | undefined;
-interface AgentMiddleware<RawResponse = unknown> {
-    onCompletionRequest?(args: CompletionRequestMiddlewareArgs): MaybePromise<CompletionRequestMiddlewareResult>;
-    onCompletionResponse?(args: CompletionResponseMiddlewareArgs<RawResponse>): MaybePromise<CompletionResponseMiddlewareResult<RawResponse>>;
-    onToolInput?(args: ToolInputMiddlewareArgs): MaybePromise<ToolInputMiddlewareResult>;
-    onToolOutput?(args: ToolOutputMiddlewareArgs): MaybePromise<ToolOutputMiddlewareResult>;
-}
-declare function createMiddleware<RawResponse = unknown>(middleware: AgentMiddleware<RawResponse>): AgentMiddleware<RawResponse>;
+import { o as JsonValue, J as JsonObject, _ as ToolQuestionAnswer } from '../../types-D9rKQ_as.js';
+import '../../model-call-options-CZkSw_xN.js';
 
 type AgentQuestionChoice = Readonly<{
     label: string;
@@ -171,4 +119,4 @@ declare function parseAgentInteractionResponse(value: unknown): AgentInteraction
 declare function parseAgentContinuation(value: unknown): AgentContinuation;
 declare function assertAgentInteractionResponse(request: AgentInteractionRequest, response: AgentInteractionResponse): void;
 
-export { type AgentContinuation as A, type CompletionRequestMiddlewareArgs as C, type ToolInputMiddlewareArgs as T, type AgentInteractionRequest as a, type AgentInteractionResponse as b, type AgentMiddleware as c, type AgentQuestionAnswer as d, type AgentQuestionChoice as e, type AgentQuestionPrompt as f, type AgentToolApprovalRequest as g, type AgentToolQuestionRequest as h, type CompletionRequestMiddlewareResult as i, type CompletionResponseMiddlewareArgs as j, type CompletionResponseMiddlewareResult as k, type ToolInputMiddlewareResult as l, type ToolOutputMiddlewareArgs as m, type ToolOutputMiddlewareResult as n, type ToolResultMiddlewareArgs as o, agentContinuationSchema as p, agentInteractionRequestSchema as q, agentInteractionResponseSchema as r, createMiddleware as s, parseAgentContinuation as t, parseAgentInteractionRequest as u, parseAgentInteractionResponse as v, assertAgentInteractionResponse as w };
+export { type AgentContinuation, type AgentInteractionRequest, type AgentInteractionResponse, type AgentQuestionAnswer, type AgentQuestionChoice, type AgentQuestionPrompt, type AgentToolApprovalRequest, type AgentToolQuestionRequest, agentContinuationSchema, agentInteractionRequestSchema, agentInteractionResponseSchema, assertAgentInteractionResponse, parseAgentContinuation, parseAgentInteractionRequest, parseAgentInteractionResponse };

package/dist/agent/interactions/index.js

@@ -0,0 +1,20 @@
+import {
+  agentContinuationSchema,
+  agentInteractionRequestSchema,
+  agentInteractionResponseSchema,
+  assertAgentInteractionResponse,
+  parseAgentContinuation,
+  parseAgentInteractionRequest,
+  parseAgentInteractionResponse
+} from "../../chunk-BEU6FCTN.js";
+import "../../chunk-SROQA7I7.js";
+export {
+  agentContinuationSchema,
+  agentInteractionRequestSchema,
+  agentInteractionResponseSchema,
+  assertAgentInteractionResponse,
+  parseAgentContinuation,
+  parseAgentInteractionRequest,
+  parseAgentInteractionResponse
+};
+//# sourceMappingURL=index.js.map

package/dist/agent/interactions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/{agent-CXScUOpX.d.ts → agent-LlCD_2UQ.d.ts}

@@ -3,8 +3,8 @@ import { D as Document, C as CompletionModel, P as ProviderTool, J as JsonObject
 import { Z as ZodSchema } from './zod-schema-C7F4clpm.js';
 import { d as GuardrailPolicyInput, c as GuardrailPolicy } from './types-CIPaIbZo.js';
 import { a as McpServer } from './client-DvUatElp.js';
-import { g as AgentLifecycle, E as AgentObservabilityOptions, l as AgentRunOptions, k as AgentResult, r as AgentStream, s as AgentStreamEvent } from './types-CElwurHZ.js';
-import { c as AgentMiddleware } from './interactions-csssHYcN.js';
+import { g as AgentLifecycle, E as AgentObservabilityOptions, l as AgentRunOptions, k as AgentResult, r as AgentStream, s as AgentStreamEvent } from './types-1KpjDfoN.js';
+import { A as AgentMiddleware } from './middleware-BqtLB_Xt.js';
 import { A as AnyTool, T as Tool, c as ToolCallContext, N as NormalizedToolOutput } from './tool-r62gf3QY.js';
 import { D as MemoryStore, y as MemorySavePolicy, m as MemoryCompactor, d as MemoryCompactionConflictRetryOptions, x as MemoryOptions } from './types-DbolvLtZ.js';
 import { a as SkillSet } from './types-RT3cuyRk.js';

package/dist/{chunk-AI5JMUW7.js → chunk-7OCVDT2X.js}

@@ -2,7 +2,7 @@ import {
   resolveRetryOptions,
   runWithRetries,
   throwIfAborted
-} from "./chunk-FN7HLLAZ.js";
+} from "./chunk-UBE4WH6G.js";
 
 // src/speech-generation/generate-speech.ts
 async function generateSpeech(options) {
@@ -42,4 +42,4 @@ function assertNonEmptyString(value, name) {
 export {
   generateSpeech
 };
-//# sourceMappingURL=chunk-AI5JMUW7.js.map
+//# sourceMappingURL=chunk-7OCVDT2X.js.map

package/dist/{chunk-5MK3BISB.js → chunk-7YAH2F3J.js}

@@ -3,11 +3,11 @@ import {
 } from "./chunk-CQNNSZPG.js";
 import {
   ToolOutput
-} from "./chunk-3CMWKK32.js";
+} from "./chunk-RZDI7B6Z.js";
 import {
   abortError,
   throwIfAborted
-} from "./chunk-FN7HLLAZ.js";
+} from "./chunk-UBE4WH6G.js";
 
 // src/mcp/client.ts
 import { readFileSync } from "fs";
@@ -701,4 +701,4 @@ export {
   McpClient,
   McpClientGroup
 };
-//# sourceMappingURL=chunk-5MK3BISB.js.map
+//# sourceMappingURL=chunk-7YAH2F3J.js.map

package/dist/{chunk-LXMAFD23.js → chunk-BAEFBTOW.js}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-CQNNSZPG.js";
 import {
   createTool
-} from "./chunk-3CMWKK32.js";
+} from "./chunk-RZDI7B6Z.js";
 
 // src/skills/instructions.ts
 function skillInstructions(skills) {
@@ -395,4 +395,4 @@ export {
   SkillValidationError,
   skill
 };
-//# sourceMappingURL=chunk-LXMAFD23.js.map
+//# sourceMappingURL=chunk-BAEFBTOW.js.map

package/dist/chunk-BEU6FCTN.js

@@ -0,0 +1,164 @@
+import {
+  isJsonValue
+} from "./chunk-SROQA7I7.js";
+
+// src/agent/interactions.ts
+import { z } from "zod";
+var nonblank = z.string().trim().min(1);
+var jsonValueSchema = z.custom(isJsonValue, {
+  message: "Expected a strict JSON value"
+});
+var jsonObjectSchema = z.custom(
+  (value) => typeof value === "object" && value !== null && !Array.isArray(value) && isJsonValue(value),
+  { message: "Expected a strict JSON object" }
+);
+var questionChoiceSchema = z.object({
+  label: nonblank,
+  value: nonblank
+}).strict();
+var questionPromptSchema = z.object({
+  id: nonblank,
+  text: nonblank,
+  choices: z.array(questionChoiceSchema).min(1).optional(),
+  allowCustom: z.boolean().optional()
+}).strict().superRefine((question, context) => {
+  if (question.choices === void 0 && question.allowCustom === false) {
+    context.addIssue({
+      code: "custom",
+      message: "A free-text question cannot disable custom answers.",
+      path: ["allowCustom"]
+    });
+  }
+  const values = /* @__PURE__ */ new Set();
+  for (const [index, choice] of (question.choices ?? []).entries()) {
+    if (values.has(choice.value)) {
+      context.addIssue({
+        code: "custom",
+        message: "Question choice values must be unique.",
+        path: ["choices", index, "value"]
+      });
+    }
+    values.add(choice.value);
+  }
+});
+var questionAnswerSchema = z.object({
+  questionId: nonblank,
+  value: nonblank
+}).strict();
+var interactionBase = {
+  id: nonblank,
+  toolName: nonblank,
+  toolCallId: nonblank,
+  callId: z.string().optional(),
+  internalCallId: nonblank
+};
+var approvalRequestSchema = z.object({
+  type: z.literal("tool-approval"),
+  ...interactionBase,
+  input: jsonValueSchema,
+  reason: z.string().optional()
+}).strict();
+var questionRequestSchema = z.object({
+  type: z.literal("tool-question"),
+  ...interactionBase,
+  questions: z.array(questionPromptSchema).min(1)
+}).strict().superRefine((request, context) => {
+  const ids = /* @__PURE__ */ new Set();
+  for (const [index, question] of request.questions.entries()) {
+    if (ids.has(question.id)) {
+      context.addIssue({
+        code: "custom",
+        message: "Question IDs must be unique.",
+        path: ["questions", index, "id"]
+      });
+    }
+    ids.add(question.id);
+  }
+});
+var agentInteractionRequestSchema = z.discriminatedUnion("type", [
+  approvalRequestSchema,
+  questionRequestSchema
+]);
+var agentInteractionResponseSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("tool-approval"),
+    approved: z.boolean(),
+    reason: z.string().optional()
+  }).strict(),
+  z.object({
+    type: z.literal("tool-question"),
+    answers: z.array(questionAnswerSchema)
+  }).strict()
+]);
+var agentContinuationSchema = z.object({
+  version: z.literal(1),
+  agentId: nonblank,
+  sourceRunId: nonblank,
+  interaction: agentInteractionRequestSchema,
+  state: jsonObjectSchema
+}).strict();
+function parseAgentInteractionRequest(value) {
+  return freeze(agentInteractionRequestSchema.parse(value));
+}
+function parseAgentInteractionResponse(value) {
+  return freeze(agentInteractionResponseSchema.parse(value));
+}
+function parseAgentQuestionPrompts(value) {
+  const request = questionRequestSchema.parse({
+    type: "tool-question",
+    id: "validation",
+    toolName: "validation",
+    toolCallId: "validation",
+    internalCallId: "validation",
+    questions: value
+  });
+  return freeze(request.questions);
+}
+function parseAgentContinuation(value) {
+  return freeze(agentContinuationSchema.parse(value));
+}
+function assertAgentInteractionResponse(request, response) {
+  if (request.type !== response.type) {
+    throw new TypeError("Interaction response type does not match the pending request.");
+  }
+  if (request.type === "tool-question" && response.type === "tool-question") {
+    assertQuestionAnswers(request, response.answers);
+  }
+}
+function assertQuestionAnswers(request, answers) {
+  const parsed = answers.map((answer) => questionAnswerSchema.parse(answer));
+  const byId = new Map(parsed.map((answer) => [answer.questionId, answer]));
+  if (byId.size !== parsed.length) {
+    throw new TypeError("Question answers must not contain duplicate question IDs.");
+  }
+  if (byId.size !== request.questions.length) {
+    throw new TypeError("Question responses must answer every question exactly once.");
+  }
+  for (const question of request.questions) {
+    const answer = byId.get(question.id);
+    if (answer === void 0) {
+      throw new TypeError(`Question response is missing an answer for "${question.id}".`);
+    }
+    const choices = question.choices;
+    if (choices !== void 0 && question.allowCustom !== true && !choices.some((choice) => choice.value === answer.value)) {
+      throw new TypeError(`Question "${question.id}" requires one of its configured choices.`);
+    }
+  }
+}
+function freeze(value) {
+  if (typeof value !== "object" || value === null || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) freeze(child);
+  return Object.freeze(value);
+}
+
+export {
+  agentInteractionRequestSchema,
+  agentInteractionResponseSchema,
+  agentContinuationSchema,
+  parseAgentInteractionRequest,
+  parseAgentInteractionResponse,
+  parseAgentQuestionPrompts,
+  parseAgentContinuation,
+  assertAgentInteractionResponse
+};
+//# sourceMappingURL=chunk-BEU6FCTN.js.map

package/dist/chunk-BEU6FCTN.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/agent/interactions.ts"],"sourcesContent":["import { z } from \"zod\";\nimport { isJsonValue } from \"../completion/json\";\nimport type { JsonObject, JsonValue, ToolQuestionAnswer } from \"../completion/types\";\n\nexport type AgentQuestionChoice = Readonly<{\n  label: string;\n  value: string;\n}>;\n\nexport type AgentQuestionPrompt = Readonly<{\n  id: string;\n  text: string;\n  choices?: readonly AgentQuestionChoice[];\n  allowCustom?: boolean;\n}>;\n\nexport type AgentQuestionAnswer = ToolQuestionAnswer;\n\ntype AgentInteractionRequestBase = Readonly<{\n  id: string;\n  toolName: string;\n  toolCallId: string;\n  callId?: string;\n  internalCallId: string;\n}>;\n\nexport type AgentToolApprovalRequest = AgentInteractionRequestBase &\n  Readonly<{\n    type: \"tool-approval\";\n    input: JsonValue;\n    reason?: string;\n  }>;\n\nexport type AgentToolQuestionRequest = AgentInteractionRequestBase &\n  Readonly<{\n    type: \"tool-question\";\n    questions: readonly AgentQuestionPrompt[];\n  }>;\n\nexport type AgentInteractionRequest = AgentToolApprovalRequest | AgentToolQuestionRequest;\n\nexport type AgentInteractionResponse =\n  | Readonly<{\n      type: \"tool-approval\";\n      approved: boolean;\n      reason?: string;\n    }>\n  | Readonly<{\n      type: \"tool-question\";\n      answers: readonly AgentQuestionAnswer[];\n    }>;\n\nexport type AgentContinuation = Readonly<{\n  version: 1;\n  agentId: string;\n  sourceRunId: string;\n  interaction: AgentInteractionRequest;\n  state: JsonObject;\n}>;\n\nconst nonblank = z.string().trim().min(1);\nconst jsonValueSchema = z.custom<JsonValue>(isJsonValue, {\n  message: \"Expected a strict JSON value\",\n});\nconst jsonObjectSchema = z.custom<JsonObject>(\n  (value) =>\n    typeof value === \"object\" && value !== null && !Array.isArray(value) && isJsonValue(value),\n  { message: \"Expected a strict JSON object\" },\n);\n\nconst questionChoiceSchema = z\n  .object({\n    label: nonblank,\n    value: nonblank,\n  })\n  .strict();\n\nconst questionPromptSchema = z\n  .object({\n    id: nonblank,\n    text: nonblank,\n    choices: z.array(questionChoiceSchema).min(1).optional(),\n    allowCustom: z.boolean().optional(),\n  })\n  .strict()\n  .superRefine((question, context) => {\n    if (question.choices === undefined && question.allowCustom === false) {\n      context.addIssue({\n        code: \"custom\",\n        message: \"A free-text question cannot disable custom answers.\",\n        path: [\"allowCustom\"],\n      });\n    }\n    const values = new Set<string>();\n    for (const [index, choice] of (question.choices ?? []).entries()) {\n      if (values.has(choice.value)) {\n        context.addIssue({\n          code: \"custom\",\n          message: \"Question choice values must be unique.\",\n          path: [\"choices\", index, \"value\"],\n        });\n      }\n      values.add(choice.value);\n    }\n  });\n\nconst questionAnswerSchema = z\n  .object({\n    questionId: nonblank,\n    value: nonblank,\n  })\n  .strict();\n\nconst interactionBase = {\n  id: nonblank,\n  toolName: nonblank,\n  toolCallId: nonblank,\n  callId: z.string().optional(),\n  internalCallId: nonblank,\n};\n\nconst approvalRequestSchema = z\n  .object({\n    type: z.literal(\"tool-approval\"),\n    ...interactionBase,\n    input: jsonValueSchema,\n    reason: z.string().optional(),\n  })\n  .strict();\n\nconst questionRequestSchema = z\n  .object({\n    type: z.literal(\"tool-question\"),\n    ...interactionBase,\n    questions: z.array(questionPromptSchema).min(1),\n  })\n  .strict()\n  .superRefine((request, context) => {\n    const ids = new Set<string>();\n    for (const [index, question] of request.questions.entries()) {\n      if (ids.has(question.id)) {\n        context.addIssue({\n          code: \"custom\",\n          message: \"Question IDs must be unique.\",\n          path: [\"questions\", index, \"id\"],\n        });\n      }\n      ids.add(question.id);\n    }\n  });\n\nexport const agentInteractionRequestSchema = z.discriminatedUnion(\"type\", [\n  approvalRequestSchema,\n  questionRequestSchema,\n]);\n\nexport const agentInteractionResponseSchema = z.discriminatedUnion(\"type\", [\n  z\n    .object({\n      type: z.literal(\"tool-approval\"),\n      approved: z.boolean(),\n      reason: z.string().optional(),\n    })\n    .strict(),\n  z\n    .object({\n      type: z.literal(\"tool-question\"),\n      answers: z.array(questionAnswerSchema),\n    })\n    .strict(),\n]);\n\nexport const agentContinuationSchema = z\n  .object({\n    version: z.literal(1),\n    agentId: nonblank,\n    sourceRunId: nonblank,\n    interaction: agentInteractionRequestSchema,\n    state: jsonObjectSchema,\n  })\n  .strict();\n\nexport function parseAgentInteractionRequest(value: unknown): AgentInteractionRequest {\n  return freeze(agentInteractionRequestSchema.parse(value)) as AgentInteractionRequest;\n}\n\nexport function parseAgentInteractionResponse(value: unknown): AgentInteractionResponse {\n  return freeze(agentInteractionResponseSchema.parse(value)) as AgentInteractionResponse;\n}\n\nexport function parseAgentQuestionPrompts(value: unknown): readonly AgentQuestionPrompt[] {\n  const request = questionRequestSchema.parse({\n    type: \"tool-question\",\n    id: \"validation\",\n    toolName: \"validation\",\n    toolCallId: \"validation\",\n    internalCallId: \"validation\",\n    questions: value,\n  });\n  return freeze(request.questions) as readonly AgentQuestionPrompt[];\n}\n\nexport function parseAgentContinuation(value: unknown): AgentContinuation {\n  return freeze(agentContinuationSchema.parse(value)) as AgentContinuation;\n}\n\nexport function assertAgentInteractionResponse(\n  request: AgentInteractionRequest,\n  response: AgentInteractionResponse,\n): void {\n  if (request.type !== response.type) {\n    throw new TypeError(\"Interaction response type does not match the pending request.\");\n  }\n  if (request.type === \"tool-question\" && response.type === \"tool-question\") {\n    assertQuestionAnswers(request, response.answers);\n  }\n}\n\nfunction assertQuestionAnswers(\n  request: AgentToolQuestionRequest,\n  answers: readonly AgentQuestionAnswer[],\n): void {\n  const parsed = answers.map((answer) => questionAnswerSchema.parse(answer));\n  const byId = new Map(parsed.map((answer) => [answer.questionId, answer]));\n  if (byId.size !== parsed.length) {\n    throw new TypeError(\"Question answers must not contain duplicate question IDs.\");\n  }\n  if (byId.size !== request.questions.length) {\n    throw new TypeError(\"Question responses must answer every question exactly once.\");\n  }\n  for (const question of request.questions) {\n    const answer = byId.get(question.id);\n    if (answer === undefined) {\n      throw new TypeError(`Question response is missing an answer for \"${question.id}\".`);\n    }\n    const choices = question.choices;\n    if (\n      choices !== undefined &&\n      question.allowCustom !== true &&\n      !choices.some((choice) => choice.value === answer.value)\n    ) {\n      throw new TypeError(`Question \"${question.id}\" requires one of its configured choices.`);\n    }\n  }\n}\n\nfunction freeze<T>(value: T): T {\n  if (typeof value !== \"object\" || value === null || Object.isFrozen(value)) return value;\n  for (const child of Object.values(value)) freeze(child);\n  return Object.freeze(value);\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-KFR4CDGK.js → chunk-DNQNOHD5.js}

@@ -1,6 +1,6 @@
 import {
   generateCompletion
-} from "./chunk-D2ECOWN5.js";
+} from "./chunk-HSA6NL2E.js";
 
 // src/memory/errors.ts
 var MemoryCompactionError = class extends Error {
@@ -235,4 +235,4 @@ export {
   createMemoryCompactionSummary,
   cumulativeCompactedMessageCount
 };
-//# sourceMappingURL=chunk-KFR4CDGK.js.map
+//# sourceMappingURL=chunk-DNQNOHD5.js.map

package/dist/{chunk-VKYZZXP5.js → chunk-E5J4OY4K.js}

@@ -1,6 +1,6 @@
 import {
   Usage
-} from "./chunk-D2ECOWN5.js";
+} from "./chunk-HSA6NL2E.js";
 
 // src/observability/snapshot.ts
 function observerSnapshot(value) {
@@ -320,4 +320,4 @@ export {
   AgentObserverDispatchError,
   startAgentRunObservers
 };
-//# sourceMappingURL=chunk-VKYZZXP5.js.map
+//# sourceMappingURL=chunk-E5J4OY4K.js.map