harnery 0.21.0 → 0.22.1

package/src/core/workflow/attempt-context.ts

@@ -0,0 +1,215 @@
+import type {
+  AcceptanceSummary,
+  WorkflowAttemptContext,
+  WorkflowAttemptFailureCause,
+  WorkflowAttemptPriorContext,
+  WorkflowAttemptUnresolvedCriterion,
+} from "./types.ts";
+import { WORKFLOW_ATTEMPT_CONTEXT_SCHEMA_VERSION } from "./types.ts";
+
+const RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
+const ACCEPTANCE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const MAX_ATTEMPTS = 100;
+const MAX_ERROR = 2_000;
+const MAX_CRITERIA = 50;
+const MAX_STATEMENT = 500;
+const CONTEXT_FIELDS = new Set(["schema_version", "number", "trigger", "prior"]);
+const PRIOR_FIELDS = new Set(["run_id", "causes", "error", "acceptance", "unresolved"]);
+const SUMMARY_FIELDS = new Set(["satisfied", "unsatisfied", "unknown", "total"]);
+const CRITERION_FIELDS = new Set(["id", "statement", "status"]);
+const CAUSE_ORDER: readonly WorkflowAttemptFailureCause[] = [
+  "workflow_error",
+  "acceptance_unsatisfied",
+  "acceptance_unknown",
+  "lost",
+];
+
+export function normalizeWorkflowAttemptContext(value: unknown): WorkflowAttemptContext {
+  const input = objectValue(value, "workflow attempt context");
+  rejectExtraFields(input, CONTEXT_FIELDS, "workflow attempt context");
+  if (input.schema_version !== WORKFLOW_ATTEMPT_CONTEXT_SCHEMA_VERSION) {
+    throw new Error("workflow attempt context has an unsupported schema");
+  }
+  const number = safeInteger(input.number, "workflow attempt context number", 1, MAX_ATTEMPTS);
+  if (input.trigger !== "initial" && input.trigger !== "retry") {
+    throw new Error('workflow attempt context trigger must be "initial" or "retry"');
+  }
+  if (input.trigger === "initial") {
+    if (input.prior !== undefined) {
+      throw new Error("initial workflow attempt context cannot contain prior evidence");
+    }
+    return {
+      schema_version: WORKFLOW_ATTEMPT_CONTEXT_SCHEMA_VERSION,
+      number,
+      trigger: "initial",
+    };
+  }
+  if (number < 2) throw new Error("retry workflow attempt context number must be at least 2");
+  if (input.prior === undefined) {
+    throw new Error("retry workflow attempt context requires prior evidence");
+  }
+  return {
+    schema_version: WORKFLOW_ATTEMPT_CONTEXT_SCHEMA_VERSION,
+    number,
+    trigger: "retry",
+    prior: normalizePrior(input.prior),
+  };
+}
+
+export function freezeWorkflowAttemptContext(value: unknown): Readonly<WorkflowAttemptContext> {
+  const normalized = normalizeWorkflowAttemptContext(value);
+  if (normalized.prior) {
+    for (const criterion of normalized.prior.unresolved) Object.freeze(criterion);
+    Object.freeze(normalized.prior.causes);
+    Object.freeze(normalized.prior.acceptance);
+    Object.freeze(normalized.prior.unresolved);
+    Object.freeze(normalized.prior);
+  }
+  return Object.freeze(normalized);
+}
+
+export function isCanonicalWorkflowAttemptContext(value: unknown): value is WorkflowAttemptContext {
+  try {
+    const normalized = normalizeWorkflowAttemptContext(value);
+    return JSON.stringify(normalized) === JSON.stringify(value);
+  } catch {
+    return false;
+  }
+}
+
+function normalizePrior(value: unknown): WorkflowAttemptPriorContext {
+  const input = objectValue(value, "workflow attempt prior context");
+  rejectExtraFields(input, PRIOR_FIELDS, "workflow attempt prior context");
+  const runId = requiredString(input.run_id, "workflow attempt prior run id", 200);
+  if (!RUN_ID.test(runId)) {
+    throw new Error(`invalid workflow attempt prior run id ${JSON.stringify(runId)}`);
+  }
+  if (!Array.isArray(input.causes) || input.causes.length === 0) {
+    throw new Error("workflow attempt prior causes must be a non-empty array");
+  }
+  const seen = new Set<WorkflowAttemptFailureCause>();
+  for (const cause of input.causes) {
+    if (!CAUSE_ORDER.includes(cause as WorkflowAttemptFailureCause)) {
+      throw new Error(`unsupported workflow attempt failure cause ${JSON.stringify(cause)}`);
+    }
+    if (seen.has(cause as WorkflowAttemptFailureCause)) {
+      throw new Error(`duplicate workflow attempt failure cause ${JSON.stringify(cause)}`);
+    }
+    seen.add(cause as WorkflowAttemptFailureCause);
+  }
+  const causes = CAUSE_ORDER.filter((cause) => seen.has(cause));
+  if (causes.includes("lost")) {
+    if (causes.length !== 1)
+      throw new Error("lost must be the only workflow attempt failure cause");
+    if (input.error !== undefined || input.acceptance !== undefined) {
+      throw new Error("lost workflow attempt evidence cannot contain proof-derived fields");
+    }
+    const unresolved = normalizeUnresolved(input.unresolved);
+    if (unresolved.length > 0) {
+      throw new Error("lost workflow attempt evidence cannot contain unresolved criteria");
+    }
+    return { run_id: runId, causes, unresolved };
+  }
+
+  const acceptance = normalizeAcceptanceSummary(input.acceptance);
+  const unresolved = normalizeUnresolved(input.unresolved);
+  const unsatisfied = unresolved.filter((criterion) => criterion.status === "unsatisfied").length;
+  const unknown = unresolved.filter((criterion) => criterion.status === "unknown").length;
+  if (
+    unsatisfied !== acceptance.unsatisfied ||
+    unknown !== acceptance.unknown ||
+    causes.includes("acceptance_unsatisfied") !== acceptance.unsatisfied > 0 ||
+    causes.includes("acceptance_unknown") !== acceptance.unknown > 0
+  ) {
+    throw new Error("workflow attempt failure evidence does not match acceptance");
+  }
+  if (!causes.includes("workflow_error") && acceptance.unsatisfied + acceptance.unknown === 0) {
+    throw new Error("workflow attempt prior context does not describe a failure");
+  }
+  const error =
+    input.error === undefined
+      ? undefined
+      : requiredString(input.error, "workflow attempt prior error", MAX_ERROR);
+  return {
+    run_id: runId,
+    causes,
+    ...(error === undefined ? {} : { error }),
+    acceptance,
+    unresolved,
+  };
+}
+
+function normalizeAcceptanceSummary(value: unknown): AcceptanceSummary {
+  const input = objectValue(value, "workflow attempt acceptance summary");
+  rejectExtraFields(input, SUMMARY_FIELDS, "workflow attempt acceptance summary");
+  const satisfied = safeInteger(input.satisfied, "acceptance satisfied", 0, MAX_CRITERIA);
+  const unsatisfied = safeInteger(input.unsatisfied, "acceptance unsatisfied", 0, MAX_CRITERIA);
+  const unknown = safeInteger(input.unknown, "acceptance unknown", 0, MAX_CRITERIA);
+  const total = safeInteger(input.total, "acceptance total", 0, MAX_CRITERIA);
+  if (satisfied + unsatisfied + unknown !== total) {
+    throw new Error("workflow attempt acceptance summary total does not match its counts");
+  }
+  return { satisfied, unsatisfied, unknown, total };
+}
+
+function normalizeUnresolved(value: unknown): WorkflowAttemptUnresolvedCriterion[] {
+  if (!Array.isArray(value) || value.length > MAX_CRITERIA) {
+    throw new Error(
+      `workflow attempt unresolved criteria must contain at most ${MAX_CRITERIA} entries`,
+    );
+  }
+  const ids = new Set<string>();
+  return value.map((candidate, index) => {
+    const input = objectValue(candidate, `workflow attempt unresolved[${index}]`);
+    rejectExtraFields(input, CRITERION_FIELDS, `workflow attempt unresolved[${index}]`);
+    const id = requiredString(input.id, `workflow attempt unresolved[${index}].id`, 64);
+    if (!ACCEPTANCE_ID.test(id)) {
+      throw new Error(`invalid workflow attempt acceptance id ${JSON.stringify(id)}`);
+    }
+    if (ids.has(id))
+      throw new Error(`duplicate workflow attempt acceptance id ${JSON.stringify(id)}`);
+    ids.add(id);
+    if (input.status !== "unsatisfied" && input.status !== "unknown") {
+      throw new Error(`workflow attempt unresolved[${index}].status is invalid`);
+    }
+    return {
+      id,
+      statement: requiredString(
+        input.statement,
+        `workflow attempt unresolved[${index}].statement`,
+        MAX_STATEMENT,
+      ),
+      status: input.status,
+    };
+  });
+}
+
+function objectValue(value: unknown, field: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${field} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function rejectExtraFields(
+  value: Record<string, unknown>,
+  allowed: ReadonlySet<string>,
+  field: string,
+): void {
+  const extra = Object.keys(value).find((key) => !allowed.has(key));
+  if (extra) throw new Error(`${field} has unknown field ${JSON.stringify(extra)}`);
+}
+
+function requiredString(value: unknown, field: string, max: number): string {
+  if (typeof value !== "string" || value.trim() === "") throw new Error(`${field} is required`);
+  const normalized = value.trim();
+  if (normalized.length > max) throw new Error(`${field} exceeds ${max} characters`);
+  return normalized;
+}
+
+function safeInteger(value: unknown, field: string, min: number, max: number): number {
+  if (!Number.isSafeInteger(value) || (value as number) < min || (value as number) > max) {
+    throw new Error(`${field} must be an integer from ${min} to ${max}`);
+  }
+  return value as number;
+}

package/src/core/workflow/engine.ts

@@ -36,6 +36,7 @@ import {
   summarizePolicyRequest,
 } from "../policy/index.ts";
 import { assertWorkflowRunId, createWorkflowApproval } from "./approvals.ts";
+import { freezeWorkflowAttemptContext } from "./attempt-context.ts";
 import { type BillingProbe, probeBilling } from "./billing.ts";
 import {
   buildWorkflowProof,
@@ -60,6 +61,7 @@ import type {
   SpawnResult,
   StageSchema,
   WorkflowAgentProof,
+  WorkflowAttemptContext,
   WorkflowContext,
   WorkflowEvidenceRecord,
   WorkflowModule,
@@ -115,8 +117,15 @@ export async function runWorkflow(scriptPath: string, opts: EngineOpts): Promise
   if (opts.resumeRunId && opts.workContext !== undefined) {
     throw new Error("parked workflow resume uses the frozen manifest work context");
   }
+  if (opts.resumeRunId && opts.attemptContext !== undefined) {
+    throw new Error("parked workflow resume uses the frozen manifest attempt context");
+  }
   const requestedWorkContext =
     opts.workContext === undefined ? undefined : freezeWorkflowWorkContext(opts.workContext);
+  const requestedAttemptContext =
+    opts.attemptContext === undefined
+      ? undefined
+      : freezeWorkflowAttemptContext(opts.attemptContext);
   if (requestedWorkContext && !opts.workItemId) {
     throw new Error("workflow work context requires a work item id");
   }
@@ -125,6 +134,9 @@ export async function runWorkflow(scriptPath: string, opts: EngineOpts): Promise
       `workflow work context ${requestedWorkContext.id} does not match work item ${opts.workItemId}`,
     );
   }
+  if (requestedAttemptContext && !requestedWorkContext) {
+    throw new Error("workflow attempt context requires work context");
+  }
   if (opts.resumeRunId && opts.resumeFrom) {
     throw new Error("resumeRunId and resumeFrom are mutually exclusive");
   }
@@ -141,6 +153,9 @@ export async function runWorkflow(scriptPath: string, opts: EngineOpts): Promise
   const workContext = resumeState?.manifest.work_context
     ? freezeWorkflowWorkContext(resumeState.manifest.work_context)
     : requestedWorkContext;
+  const attemptContext = resumeState?.manifest.attempt_context
+    ? freezeWorkflowAttemptContext(resumeState.manifest.attempt_context)
+    : requestedAttemptContext;
   const absScript = isAbsolute(scriptPath) ? scriptPath : resolve(process.cwd(), scriptPath);
   if (resumeState) {
     if (resolve(resumeState.manifest.script.path) !== resolve(absScript)) {
@@ -157,7 +172,14 @@ export async function runWorkflow(scriptPath: string, opts: EngineOpts): Promise
       // the run between the optimistic read and lease acquisition.
       assertWorkflowRunResumable(opts.coordRoot, resumeState.manifest.run_id);
     }
-    return await executeWorkflow(scriptPath, absScript, opts, resumeState, workContext);
+    return await executeWorkflow(
+      scriptPath,
+      absScript,
+      opts,
+      resumeState,
+      workContext,
+      attemptContext,
+    );
   } finally {
     releaseResumeLease?.();
   }
@@ -169,6 +191,7 @@ async function executeWorkflow(
   opts: EngineOpts,
   resumeState: ReturnType<typeof assertWorkflowRunResumable> | undefined,
   workContext: Readonly<WorkflowWorkContext> | undefined,
+  attemptContext: Readonly<WorkflowAttemptContext> | undefined,
 ): Promise<RunReport> {
   const mod = (await import(pathToFileURL(absScript).href)) as WorkflowModule;
   if (typeof mod.default !== "function") {
@@ -218,6 +241,7 @@ async function executeWorkflow(
         run_id: runId,
         work_item_id: opts.workItemId,
         work_context: workContext,
+        attempt_context: attemptContext,
         name,
         started_at: startedAt,
         script: { path: absScript, sha256: workflowScriptDigest(absScript) },
@@ -784,6 +808,7 @@ async function executeWorkflow(
 
   const ctx: WorkflowContext = {
     work: workContext,
+    attempt: attemptContext,
     agent,
     parallel,
     stage,
@@ -803,6 +828,7 @@ async function executeWorkflow(
         name,
         work_item_id: opts.workItemId ?? null,
         work_context: workContext ?? null,
+        attempt_context: attemptContext ?? null,
         script: absScript,
         objective: meta.objective ?? null,
         acceptance: meta.acceptance,
@@ -830,6 +856,7 @@ async function executeWorkflow(
         runId,
         workItemId: opts.workItemId ?? resumeState?.manifest.work_item_id,
         workContext,
+        attemptContext,
         meta,
         status: "succeeded",
         startedAt,
@@ -897,6 +924,7 @@ async function executeWorkflow(
         runId,
         workItemId: opts.workItemId ?? resumeState?.manifest.work_item_id,
         workContext,
+        attemptContext,
         meta,
         status: "failed",
         startedAt,

package/src/core/workflow/index.ts

@@ -16,6 +16,11 @@ export {
   WORKFLOW_APPROVAL_SCHEMA_VERSION,
   workflowApprovalId,
 } from "./approvals.ts";
+export {
+  freezeWorkflowAttemptContext,
+  isCanonicalWorkflowAttemptContext,
+  normalizeWorkflowAttemptContext,
+} from "./attempt-context.ts";
 export { runWorkflow, WorkflowParkedError, WorkflowRunError } from "./engine.ts";
 export {
   buildWorkflowProof,
@@ -59,6 +64,10 @@ export type {
   StageSchema,
   WorkflowAgentProof,
   WorkflowApprovalMode,
+  WorkflowAttemptContext,
+  WorkflowAttemptFailureCause,
+  WorkflowAttemptPriorContext,
+  WorkflowAttemptUnresolvedCriterion,
   WorkflowContext,
   WorkflowEvidenceInput,
   WorkflowEvidenceRecord,
@@ -74,6 +83,7 @@ export type {
   WorkflowWorkContext,
 } from "./types.ts";
 export {
+  WORKFLOW_ATTEMPT_CONTEXT_SCHEMA_VERSION,
   WORKFLOW_PROOF_SCHEMA_VERSION,
   WORKFLOW_WORK_CONTEXT_SCHEMA_VERSION,
 } from "./types.ts";

package/src/core/workflow/proof.ts

@@ -18,6 +18,7 @@ import type {
   PolicyNetworkAccess,
 } from "../policy/index.ts";
 import { policyDigest } from "../policy/index.ts";
+import { isCanonicalWorkflowAttemptContext } from "./attempt-context.ts";
 import type {
   AcceptanceCriterion,
   AcceptanceResult,
@@ -26,6 +27,7 @@ import type {
   HarnessEvidenceCoverage,
   ResultDigest,
   WorkflowAgentProof,
+  WorkflowAttemptContext,
   WorkflowEvidenceInput,
   WorkflowEvidenceRecord,
   WorkflowMeta,
@@ -62,6 +64,7 @@ export interface BuildWorkflowProofInput {
   runId: string;
   workItemId?: string;
   workContext?: Readonly<WorkflowWorkContext>;
+  attemptContext?: Readonly<WorkflowAttemptContext>;
   meta: NormalizedWorkflowMeta;
   status: "succeeded" | "failed";
   startedAt: string;
@@ -225,6 +228,7 @@ export function buildWorkflowProof(input: BuildWorkflowProofInput): WorkflowProo
       ended_at: input.endedAt,
       duration_ms: input.durationMs,
       work_context: input.workContext,
+      attempt_context: input.attemptContext,
       objective: input.meta.objective,
       error: clippedOptional(input.error, MAX_SUMMARY_CHARS),
       result: input.result === undefined ? undefined : digestResult(input.result),
@@ -313,7 +317,11 @@ export function readWorkflowProof(coordRoot: string, runId: string): WorkflowPro
     (proof.run.work_context !== undefined &&
       (!proof.run.work_item_id ||
         proof.run.work_context.id !== proof.run.work_item_id ||
-        !isCanonicalWorkflowWorkContext(proof.run.work_context)))
+        !isCanonicalWorkflowWorkContext(proof.run.work_context))) ||
+    (proof.run.attempt_context !== undefined &&
+      (!proof.run.work_item_id ||
+        !proof.run.work_context ||
+        !isCanonicalWorkflowAttemptContext(proof.run.attempt_context)))
   ) {
     throw new Error(`workflow proof at ${path} has an unsupported or mismatched schema`);
   }

package/src/core/workflow/run-state.ts

@@ -22,8 +22,13 @@ import {
   policyDigest,
 } from "../policy/index.ts";
 import { assertWorkflowRunId, readWorkflowApproval } from "./approvals.ts";
+import { isCanonicalWorkflowAttemptContext } from "./attempt-context.ts";
 import { normalizeWorkflowSpecialists } from "./specialists.ts";
-import type { WorkflowSpecialistProfile, WorkflowWorkContext } from "./types.ts";
+import type {
+  WorkflowAttemptContext,
+  WorkflowSpecialistProfile,
+  WorkflowWorkContext,
+} from "./types.ts";
 import { isCanonicalWorkflowWorkContext } from "./work-context.ts";
 
 export const WORKFLOW_RUN_MANIFEST_SCHEMA_VERSION = 1 as const;
@@ -36,6 +41,7 @@ export interface WorkflowRunManifest {
   run_id: string;
   work_item_id?: string;
   work_context?: WorkflowWorkContext;
+  attempt_context?: WorkflowAttemptContext;
   name: string;
   started_at: string;
   script: { path: string; sha256: string };
@@ -109,6 +115,10 @@ export function readWorkflowRunManifest(coordRoot: string, runId: string): Workf
       (!manifest.work_item_id ||
         manifest.work_context.id !== manifest.work_item_id ||
         !isCanonicalWorkflowWorkContext(manifest.work_context))) ||
+    (manifest.attempt_context !== undefined &&
+      (!manifest.work_item_id ||
+        !manifest.work_context ||
+        !isCanonicalWorkflowAttemptContext(manifest.attempt_context))) ||
     typeof manifest.name !== "string" ||
     manifest.name.length === 0 ||
     manifest.name.length > 200 ||

package/src/core/workflow/types.ts

@@ -21,6 +21,7 @@ import type { BillingMode, BillingProber } from "./billing.ts";
 
 export const WORKFLOW_PROOF_SCHEMA_VERSION = 1 as const;
 export const WORKFLOW_WORK_CONTEXT_SCHEMA_VERSION = 1 as const;
+export const WORKFLOW_ATTEMPT_CONTEXT_SCHEMA_VERSION = 1 as const;
 
 export type EvidenceKind = "test" | "command" | "artifact" | "change" | "review" | "observation";
 export type EvidenceStatus = "passed" | "failed" | "observed" | "unknown";
@@ -157,6 +158,7 @@ export interface WorkflowProof {
     ended_at: string;
     duration_ms: number;
     work_context?: WorkflowWorkContext;
+    attempt_context?: WorkflowAttemptContext;
     objective?: string;
     error?: string;
     result?: ResultDigest;
@@ -304,6 +306,9 @@ export interface WorkflowContext {
   /** Frozen durable-work assignment for work-linked runs. Standalone and
    * legacy-resumed workflows have no work context. */
   work?: Readonly<WorkflowWorkContext>;
+  /** Frozen attempt identity and, on retry, a bounded synopsis of prior
+   * terminal evidence. Absent for standalone and legacy-resumed workflows. */
+  attempt?: Readonly<WorkflowAttemptContext>;
   /** Spawn one subagent; resolves to validated JSON (schema) or reply text. */
   agent: (prompt: string, opts?: AgentOpts) => Promise<unknown>;
   /** Run thunks with bounded concurrency; a rejected thunk resolves to null. */
@@ -340,6 +345,33 @@ export interface WorkflowWorkContext {
   readonly acceptance: readonly string[];
 }
 
+export type WorkflowAttemptFailureCause =
+  | "workflow_error"
+  | "acceptance_unsatisfied"
+  | "acceptance_unknown"
+  | "lost";
+
+export interface WorkflowAttemptUnresolvedCriterion {
+  readonly id: string;
+  readonly statement: string;
+  readonly status: "unsatisfied" | "unknown";
+}
+
+export interface WorkflowAttemptPriorContext {
+  readonly run_id: string;
+  readonly causes: readonly WorkflowAttemptFailureCause[];
+  readonly error?: string;
+  readonly acceptance?: Readonly<AcceptanceSummary>;
+  readonly unresolved: readonly WorkflowAttemptUnresolvedCriterion[];
+}
+
+export interface WorkflowAttemptContext {
+  readonly schema_version: typeof WORKFLOW_ATTEMPT_CONTEXT_SCHEMA_VERSION;
+  readonly number: number;
+  readonly trigger: "initial" | "retry";
+  readonly prior?: Readonly<WorkflowAttemptPriorContext>;
+}
+
 export interface EngineOpts {
   /** Repo root whose .harnery/ receives the run journal. */
   coordRoot: string;
@@ -365,6 +397,9 @@ export interface EngineOpts {
   /** Frozen assignment data supplied by a durable-work host. Requires the
    * matching `workItemId`; parked resume always uses the manifest copy. */
   workContext?: WorkflowWorkContext;
+  /** Frozen attempt data supplied by a durable-work host. Requires matching
+   * work item and work contexts; parked resume uses the manifest copy. */
+  attemptContext?: WorkflowAttemptContext;
   /** Total-agent ceiling for the run (default 50): the runaway backstop. */
   maxAgents?: number;
   /** Concurrent-subagent cap for parallel() (default 4). */

package/src/core/workflow/validate.ts

@@ -111,7 +111,16 @@ export function validateAgainstSchema(value: unknown, schema: StageSchema, path
   }
 }
 
-/** Strip accidental markdown code fences, then strict-parse JSON. */
+/**
+ * Parse one schema-gated JSON value.
+ *
+ * Exact JSON and a whole fenced value remain the normal paths. Some harnesses
+ * prepend a short narration despite an explicit JSON-only contract. Accept
+ * that drift only when the reply contains exactly one unambiguous top-level
+ * object or array, the value reaches the end of the reply, and JSON.parse
+ * accepts it. Trailing prose, multiple values, and malformed candidates remain
+ * failures.
+ */
 export function parseStageOutput(text: string): { value?: unknown; error?: string } {
   const stripped = text
     .trim()
@@ -120,10 +129,75 @@ export function parseStageOutput(text: string): { value?: unknown; error?: strin
   try {
     return { value: JSON.parse(stripped) };
   } catch (err) {
+    const embedded = singleTrailingJsonContainer(stripped);
+    if (embedded !== undefined) return { value: embedded };
     return { error: `not valid JSON: ${(err as Error).message}` };
   }
 }
 
+function singleTrailingJsonContainer(text: string): unknown | undefined {
+  const candidates: Array<{ end: number; value: unknown }> = [];
+  let start = -1;
+  let stack: string[] = [];
+  let inString = false;
+  let escaped = false;
+
+  for (let index = 0; index < text.length; index++) {
+    const char = text[index]!;
+    if (start === -1) {
+      if (char === "{" || char === "[") {
+        start = index;
+        stack = [char];
+        inString = false;
+        escaped = false;
+      }
+      continue;
+    }
+
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      continue;
+    }
+    if (char === "{" || char === "[") {
+      stack.push(char);
+      continue;
+    }
+    if (char !== "}" && char !== "]") continue;
+
+    const expectedOpen = char === "}" ? "{" : "[";
+    if (stack.at(-1) !== expectedOpen) {
+      start = -1;
+      stack = [];
+      continue;
+    }
+    stack.pop();
+    if (stack.length > 0) continue;
+
+    const end = index + 1;
+    try {
+      candidates.push({ end, value: JSON.parse(text.slice(start, end)) });
+    } catch {
+      // A balanced brace pair in narration is not a JSON candidate.
+    }
+    start = -1;
+  }
+
+  if (candidates.length !== 1 || text.slice(candidates[0]!.end).trim() !== "") {
+    return undefined;
+  }
+  return candidates[0]!.value;
+}
+
 function short(value: unknown): string {
   const s = JSON.stringify(value);
   return s === undefined ? String(value) : s.length > 60 ? `${s.slice(0, 60)}…` : s;