@yaag/runtime 0.1.2 → 0.2.0

package/src/transport.ts

@@ -1,6 +1,7 @@
 import type { CanonicalJsonObject } from "./ask-contract-identity.ts";
 import type { AskLimitOutcome, AskStalledOutcome } from "./errors.ts";
-import type { AskOptions, SpawnOptions, ThinkingLevel } from "./types.ts";
+import type { ReportedResult } from "./report-result.ts";
+import type { AskOptions, ResolvedSpawnOptions, ThinkingLevel } from "./types.ts";
 
 /**
  * The one seam of the runtime (ticket 04). An AgentTransport represents a whole
@@ -34,7 +35,7 @@ export interface AgentStats {
 export interface AskMarkerContext {
   readonly prompt: string;
   readonly spawn: Pick<
-    SpawnOptions,
+    ResolvedSpawnOptions,
     | "cwd"
     | "model"
     | "systemPrompt"
@@ -48,7 +49,7 @@ export interface AskMarkerContext {
   >;
   readonly ask: Pick<
     AskOptions,
-    "maxTurns" | "maxToolCalls" | "maxDurationMs" | "idleMs" | "wrapUpPrompt"
+    "maxTurns" | "maxToolCalls" | "maxDurationMs" | "idleMs" | "stallMs" | "wrapUpPrompt"
   > & {
     readonly outputSchema?: CanonicalJsonObject;
     readonly maxSteers?: number;
@@ -80,6 +81,18 @@ export interface AskInvalidOutputPlayback {
   readonly steeringEfforts: number;
 }
 
+/** What one live Ask produced, reported to its transport when the Ask finishes. */
+export interface AskCompletion {
+  /** Limit outcome, present only when the Ask rejected with ASK_LIMIT. */
+  readonly limit?: AskLimitOutcome;
+  /** Stalled outcome, present only when the Ask rejected with ASK_STALLED. */
+  readonly stalled?: AskStalledOutcome;
+  /** Invalid structured-output result, present only when it surfaced. */
+  readonly invalidOutput?: AskInvalidOutputPlayback;
+  /** The Stall Watchdog settled this Ask from observed state (ADR-0029). */
+  readonly recovered?: true;
+}
+
 /** Presence identifies Cassette playback, including recorded successful Asks. */
 export interface AskPlayback {
   /** Limit outcome recorded for this Ask, if it rejected with ASK_LIMIT. */
@@ -88,8 +101,26 @@ export interface AskPlayback {
   readonly stalled?: AskStalledOutcome;
   /** Invalid structured-output result recorded for this Ask, if it surfaced. */
   readonly outcome?: AskInvalidOutputPlayback;
+  /**
+   * The result the recorded Ask reported through `report_result`, read from its
+   * frames when the Cassette holds one. Reading it here keeps playback a pure
+   * function of the Cassette instead of a race with the replayed frame stream.
+   */
+  readonly reported?: ReportedResult;
   /** Whether recorded correction history has an abort settlement after final text. */
   readonly awaitsAbortSettlement?: true;
+  /**
+   * The recorded Ask settled through Stall Watchdog recovery, so no
+   * `agent_settled` frame exists: playback settles on the terminal assistant
+   * `message_end` instead.
+   */
+  readonly recovered?: true;
+  /**
+   * False when the recorded Ask holds no `agent_settled` frame. Playback then
+   * surfaces the recorded outcome instead of waiting for a settlement that the
+   * Cassette does not contain.
+   */
+  readonly settles?: false;
 }
 
 /** One Agent, as the layer above sees it. */
@@ -110,11 +141,15 @@ export interface AgentTransport {
   beginAsk(marker: AskMarker): AskPlayback | undefined;
 
   /** Reports surfaced live outcomes; replay ignores completion. */
-  finishAsk(
-    outcome?: AskLimitOutcome,
-    stalled?: AskStalledOutcome,
-    invalidOutput?: AskInvalidOutputPlayback,
-  ): void;
+  finishAsk(completion: AskCompletion): void;
+
+  /**
+   * The extraction policy recorded for the Ask at `index`, when a Cassette
+   * backs it. An Ask recorded under an older policy keeps that policy, so its
+   * identity and its settlement behavior stay the ones it was recorded with
+   * (ADR-0032). Live transports have nothing recorded and omit this method.
+   */
+  recordedExtractionPolicy?(index: number): string | undefined;
 
   /**
    * Shut the Agent down and report its cost. Idempotent.

package/src/types.ts

@@ -1,18 +1,29 @@
 import type { Static, TSchema } from "typebox";
+import type { ModelSpec, ThinkingSpec } from "./model-resolution.ts";
+import type { ThinkingLevel } from "./thinking-level.ts";
 
-/** pi's supported thinking levels. */
-export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+export type { ThinkingLevel } from "./thinking-level.ts";
 
 /** Options for spawning one Agent (ADR-0001, ADR-0009, ADR-0026). */
 export interface SpawnOptions {
   /** Working directory. Defaults to the Orchestrator's cwd. */
   readonly cwd?: string;
-  /** Model pattern, e.g. "anthropic/claude-haiku-4". Unset inherits the user's default. */
-  readonly model?: string;
+  /**
+   * Model pattern, e.g. "anthropic/claude-haiku-4". Unset inherits the user's default.
+   *
+   * An array is an ordered fallback list and a function picks the next candidate
+   * from the failures so far. Any resolved pattern may carry an inline thinking
+   * suffix (`"opus-5:medium"`), which wins over `thinking`.
+   */
+  readonly model?: ModelSpec;
   /** Replaces the default system prompt (`pi --system-prompt`). */
   readonly systemPrompt?: string;
-  /** Sets pi's thinking level; omission preserves pi's default. */
-  readonly thinking?: ThinkingLevel;
+  /**
+   * Sets pi's thinking level; omission preserves pi's default. A function picks
+   * the level from the settled model, and is not consulted for a model pattern
+   * that carries an inline thinking suffix.
+   */
+  readonly thinking?: ThinkingSpec;
   /** Appends text to pi's system prompt (`pi --append-system-prompt`). */
   readonly appendSystemPrompt?: string;
   /**
@@ -49,6 +60,12 @@ export interface SpawnOptions {
   readonly worktree?: boolean;
 }
 
+/** Spawn options after Model Resolution has settled one model and thinking level. */
+export interface ResolvedSpawnOptions extends Omit<SpawnOptions, "model" | "thinking"> {
+  readonly model?: string;
+  readonly thinking?: ThinkingLevel;
+}
+
 /** Topology-only fields that may change when spawning an Agent Definition. */
 export interface SpawnOverrides {
   /** Log and event label. Defaults to the definition's name; duplicates are suffixed. */
@@ -85,15 +102,32 @@ export interface AskOptions {
    * idle detection (ADR-0020).
    */
   readonly idleMs?: number;
+  /**
+   * Silence budget in milliseconds for the Stall Watchdog, which guards every
+   * live Ask by default (ADR-0029). On expiry yaag probes the Agent and either
+   * recovers a missed settlement or rejects with `ASK_STALLED`. Omission uses
+   * the 10-minute default. `false`, and any value that is not above zero,
+   * disable the watchdog for this Ask.
+   */
+  readonly stallMs?: number | false;
   /** Per-Ask replacement for the runtime's wrap-up steering message. */
   readonly wrapUpPrompt?: string;
 }
 
 /** Ask options that require a schema and preserve its inferred successful result. */
 export interface StructuredAskOptions<Schema extends TSchema> extends AskOptions {
-  /** TypeBox schema that changes successful Ask resolution from text to a parsed value. */
+  /**
+   * TypeBox object schema the Agent reports its result against, instead of text.
+   *
+   * It becomes the input schema of one internal tool, so it must describe an
+   * object (ADR-0032).
+   */
   readonly outputSchema: Schema;
-  /** Maximum corrective steering efforts for this Ask; defaults to 3 when omitted. */
+  /**
+   * Maximum settlements without a reported result that this Ask corrects;
+   * defaults to 3 when omitted. Argument repair inside a turn is the Agent's
+   * own loop and costs nothing here.
+   */
   readonly maxSteers?: number;
 }
 
@@ -115,12 +149,14 @@ export interface Handle {
    * Sends a prompt and resolves after the Agent's turn settles.
    *
    * Schema-free calls resolve with the exact final assistant text. Calls with
-   * `outputSchema` resolve with the extracted, TypeBox-validated value. Rejects
-   * with a YaagError for a failed or empty turn, timeout, `ASK_LIMIT`, or dead
-   * Agent; invalid structured output rejects recoverably with
-   * `ASK_INVALID_OUTPUT` after at most `maxSteers` (default 3) in-Ask
-   * correction efforts and an abort settlement. These recoverable outcomes
-   * leave the Handle reusable. A concurrent call rejects with `AGENT_BUSY`.
+   * `outputSchema` resolve with the TypeBox-validated value the Agent reports
+   * through one internal tool call (ADR-0032). Rejects with a YaagError for a
+   * failed or empty turn, timeout, `ASK_LIMIT`, or dead Agent. An Ask that
+   * settles without a reported result is corrected at most `maxSteers` times
+   * (default 3) and then rejects recoverably with `ASK_INVALID_OUTPUT` after an
+   * abort settlement; a reported value the schema rejects fails the same way
+   * without a correction. These recoverable outcomes leave the Handle reusable.
+   * A concurrent call rejects with `AGENT_BUSY`.
    */
   ask<Schema extends TSchema>(
     prompt: string,

package/src/validation-errors.ts

@@ -8,18 +8,23 @@ export function formatValidationErrors(
   return Array.from(errors).flatMap((error) => formatError(value, error));
 }
 
+/**
+ * A missing property is reported at the object that lacks it, never at the path
+ * the property would occupy: the absent path cannot be pointed at, and a pointer
+ * that contradicts its own message steers a model into the wrong shape (ADR-0032).
+ */
 function formatError(value: unknown, error: TLocalizedValidationError): readonly string[] {
+  const path = toJsonPath(value, error.instancePath);
   if (error.keyword === "required") {
     return error.params.requiredProperties.map(
-      (property) => `${toJsonPath(value, error.instancePath, property)}: ${error.message}`,
+      (property) => `${path}: must have required property ${JSON.stringify(property)}`,
     );
   }
-  return [`${toJsonPath(value, error.instancePath)}: ${error.message}`];
+  return [`${path}: ${error.message}`];
 }
 
-function toJsonPath(value: unknown, instancePath: string, property?: string): string {
+function toJsonPath(value: unknown, instancePath: string): string {
   const segments = reconstructSegments(value, instancePath);
-  if (property !== undefined) segments.push(property);
   return segments.reduce((path, segment) => `${path}${formatSegment(segment)}`, "$");
 }
 
@@ -66,5 +71,6 @@ function isArrayIndex(value: string): boolean {
 }
 
 function formatSegment(segment: string): string {
+  if (isArrayIndex(segment)) return `[${segment}]`;
   return /^[A-Za-z_$][\w$]*$/.test(segment) ? `.${segment}` : `[${JSON.stringify(segment)}]`;
 }