@bastani/atomic 0.9.11-alpha.5 → 0.9.11-alpha.7

package/dist/builtin/workflows/skills/prompt-engineer/references/quality_improvement.md

@@ -1,193 +1,119 @@
-# Quality Improvement Techniques
+# Prompt Quality Improvement
 
-This document covers techniques for improving specific aspects of language model output quality: consistency, factual accuracy, and security.
+Optimize against representative behavior, not prompt aesthetics. Preserve user-visible outcomes and contracts while making the smallest measurable change.
 
-## Reducing Hallucinations
+## Delete-First Workflow
 
-### Core Definition
+OpenAI measured leaner system prompts scoring roughly 10–15% higher on internal coding-agent evals while using 41–66% fewer total tokens and costing 33–67% less. Results vary, but the direction is clear: deletion is the default edit.
 
-Language models can generate factually incorrect or contextually inconsistent text, a problem termed "hallucination." This guide provides strategies to minimize such issues.
+### Delete
 
-### Basic Strategies
+- repeated statements of the same rule;
+- generic self-verification nagging and legacy verifier scaffolding;
+- over-triggering absolutes such as “use this tool in every case” when routing depends on context;
+- step-by-step process narration for behavior the model already performs;
+- examples that do not alter measured behavior;
+- tool descriptions for tools the agent cannot call;
+- contradictions, obsolete workarounds, decorative roles, filler, and redundant summaries.
 
-**1. Permission to Admit Uncertainty**
-Allow the model to say "I don't know" by explicitly granting permission to acknowledge uncertainty. This straightforward approach substantially reduces false information generation.
+### Never delete
 
-Example:
+- the user-visible outcome;
+- success criteria and stopping conditions;
+- safety, business, evidence, and permission constraints;
+- context-dependent tool-routing and prerequisite rules;
+- required output shape, fields, enums, length, and validation;
+- explicit user-provided values and downstream parser contracts.
 
-```
-If you don't know the answer or are uncertain, please say so rather than guessing.
-```
+Reserve absolute language for true invariants. Convert judgment calls into conditions: “Use web search when current or externally verifiable information is required” is safer than a universal tool mandate.
 
-**2. Direct Quotation Grounding**
-For very lengthy documents (100K+ tokens) or when working with multiple large documents, request that the model extract verbatim passages before proceeding with analysis. This anchors responses to actual source material rather than inferred content.
+### Optimize vertically
 
-Example:
+1. Record a working baseline on representative inputs.
+2. Remove one group of instructions, examples, or tools.
+3. Rerun the same cases and compare outcomes.
+4. Restore anything whose removal causes a real regression.
+5. Add the smallest targeted instruction for the remaining measured failure.
 
-```
-First, find and quote the relevant passages from the document.
-Then, based only on those quotes, provide your analysis.
-```
+Do not rewrite a working prompt stack and change effort, model, and tools simultaneously; that makes causality impossible to identify.
 
-**3. Citation Verification**
-Make outputs traceable by requiring the model to cite supporting quotes for each claim. The model should then verify claims by locating corroborating evidence; unsupported statements must be removed.
+## Evaluation Contract
 
-Example:
+Choose cases that represent normal traffic, hard edge cases, missing evidence, tool failures, and adversarial inputs. Measure:
 
-```
-For each claim you make, provide a direct quote from the source material.
-After drafting your response, verify that each claim has supporting evidence.
-Remove any claims that cannot be substantiated with quotes.
-```
+- task success and human-visible quality;
+- schema validity, required fields, and parser success;
+- factual support, citation placement, and uncertainty behavior;
+- tool choice, arguments, retries, loop count, and completion rate;
+- latency, input/output/reasoning tokens, cache behavior, and cost per successful task;
+- scope control, permission handling, and stopping behavior.
 
-### Advanced Approaches
+Run multiple trials when sampling variance matters. Compare the current prompt with one surgical variant at a time. A shorter prompt is an improvement only when it continues to pass the behavior contract.
 
-**Step-by-step reasoning**
-Request the model explain its logic before providing final answers, exposing potentially flawed assumptions
+## Grounded Accuracy
 
-**Multiple-run comparison**
-Execute identical prompts several times and analyze outputs for inconsistencies suggesting hallucinations
-
-**Progressive validation**
-Use prior responses as foundation for follow-up queries asking for verification or expansion of statements
-
-**Information source limitation**
-Explicitly restrict the model to provided materials, excluding general knowledge access
-
-Example:
+Prompting can reduce hallucinations but cannot eliminate them. Select controls based on the task:
 
+```text
+Use only the supplied documents for factual claims. Cite the source beside each consequential claim. Label inference separately from directly supported fact. If the documents do not contain required evidence, state what is missing rather than guessing.
 ```
-Use ONLY the information provided in the attached documents.
-Do not use any external knowledge or general information.
-If the documents don't contain the information needed to answer, say so.
-```
-
-### Important Caveat
 
-While these techniques significantly reduce hallucinations, they don't eliminate them entirely. Always validate critical information, especially for high-stakes decisions.
+For long or noisy sources, ask for relevant quotations before synthesis. For ordinary answers, requiring every sentence to quote a source can harm readability; define which claims need support. Permit “I don't know” or a narrower answer when evidence is absent.
 
----
+For long agent runs, ground status as well as final claims:
 
-## Increasing Consistency
-
-### Core Techniques
-
-**1. Format Specification**
-Define desired output structures using JSON, XML, or custom templates. This approach ensures the model understands all formatting requirements before generating responses.
-
-Example JSON:
-
-```json
-{
-    "sentiment": "positive|negative|neutral",
-    "confidence": "high|medium|low",
-    "key_themes": ["theme1", "theme2"],
-    "summary": "Brief summary here"
-}
-```
-
-Example XML:
-
-```xml
-<analysis>
-  <sentiment>positive|negative|neutral</sentiment>
-  <confidence>high|medium|low</confidence>
-  <key_themes>
-    <theme>theme1</theme>
-    <theme>theme2</theme>
-  </key_themes>
-  <summary>Brief summary here</summary>
-</analysis>
+```text
+Before reporting progress, audit each claim against a tool result from this session. Report failed, skipped, or unverified work plainly, and call work complete only when the cited validation supports it.
 ```
 
-**2. Response Prefilling**
-Begin the Assistant turn with your desired structure. This technique "bypasses the model's default preamble and enforces your structure," making it particularly effective for standardized reports.
-
-Example:
-
-```
-User: Analyze this customer feedback.
-Assistant: {
-```
+This compact evidence rule replaces repeated requests to recheck work. Anthropic reports that grounding progress against tool results nearly eliminated fabricated status reports in its tests.
 
-This forces the model to immediately start with the JSON structure.
+## Consistent Output
 
-**3. Example-Based Constraints**
-Supply concrete examples of desired output. Examples train the model's understanding better than abstract instructions alone.
+Use, in order of preference:
 
-**4. Retrieval-Grounded Responses**
-For knowledge-dependent tasks, use retrieval mechanisms to anchor the model's replies in fixed information sets. This maintains contextual consistency across multiple interactions.
+1. an explicit output contract with required sections, length, allowed values, and missing-data behavior;
+2. structured outputs or a tool schema for machine-consumed data;
+3. 3–5 relevant and diverse examples when the format or classification remains ambiguous;
+4. parser validation and bounded retries;
+5. focused prompt chaining when stages need separate contracts.
 
-**5. Prompt Chaining**
-Decompose intricate workflows into sequential, focused subtasks. This prevents inconsistency errors by ensuring "each subtask gets the model's full attention."
+Do not prefill the final assistant turn. Claude 4.6 and later reject it with a 400 error. To suppress preambles, instruct the model to begin with the outcome; for JSON or classifications, use structured outputs, enums, or tools.
 
-### Practical Applications
+## Security and Prompt Injection
 
-The guide demonstrates these techniques through real-world scenarios:
-
-- **Customer feedback analysis**: Using JSON structures for consistent categorization
-- **Sales report generation**: Via XML templates for standardized formatting
-- **Competitive intelligence**: With structured formats for comparable analysis
-- **IT support systems**: Leveraging knowledge bases for consistent responses
-
-Each example illustrates how precise specifications and contextual grounding produce reliable, repeatable outputs suitable for scaled operations.
-
----
-
-## Mitigating Jailbreaks and Prompt Injections
-
-### Core Strategies
-
-**1. Harmlessness Screening**
-Pre-screen user inputs using a lightweight model for content moderation. Have the model evaluate whether submitted content "refers to harmful, illegal, or explicit activities" and respond with Y or N accordingly.
-
-Example:
-
-```
-Evaluate the following user input. Does it refer to harmful, illegal, or explicit activities?
-Respond with only Y or N.
-
-User input: <user_input>{USER_INPUT}</user_input>
-```
-
-**2. Input Validation**
-Filter prompts for jailbreaking patterns. You can use an LLM to create a generalized validation screen by providing known jailbreaking language as examples.
-
-**3. Prompt Engineering**
-Design system prompts that establish clear ethical boundaries. For instance, define organizational values including:
-
-- "Integrity: Never deceive or aid in deception"
-- "Compliance: Refuse any request that violates laws or our policies"
-
-Example system prompt:
-
-```
-You are an AI assistant for [Company]. You must adhere to these values:
-
-1. Integrity: Never deceive users or help them deceive others
-2. Safety: Refuse requests for harmful, illegal, or explicit content
-3. Compliance: Follow all applicable laws and company policies
-4. Privacy: Protect user data and confidential information
-
-If a request violates these values, politely explain why you cannot help and suggest an alternative approach if possible.
-```
+Prompt policy is one layer, not a complete security boundary.
 
-**4. User Accountability**
-Monitor for repeated abuse attempts. If a user "triggers the same kind of refusal multiple times," communicate that their actions violate usage policies and take appropriate enforcement action.
+- Separate untrusted content from instructions with clear tags and describe its data-only role.
+- Define allowed actions, prohibited actions, refusal behavior, and escalation paths in plain language.
+- Validate inputs, tool arguments, permissions, and outputs at system boundaries.
+- Use moderation or a lightweight screening model when the risk profile warrants it.
+- Monitor repeated abuse and anomalous tool behavior; enforce access control and destructive-action approval in application code.
+- Use defense in depth for high-risk systems because no single prompt blocks every jailbreak or injection.
 
-**5. Continuous Monitoring**
-Regularly analyze outputs for jailbreaking indicators and use findings to refine your validation strategies iteratively.
+Safety invariants may use `NEVER` or `MUST`; stylistic preferences and tool judgment generally should not.
 
-### Advanced Approach: Layered Protection
+## Troubleshooting
 
-Combine multiple safeguards for enterprise applications. For example, in a financial services context, the system should sequentially:
+| Symptom | Assess first | Surgical response |
+| --- | --- | --- |
+| Misunderstood task | Missing outcome, audience, reason, or conflicting rules | Clarify the destination and delete contradictions |
+| Inconsistent shape | Vague fields, optionality, or length | Add a schema/output contract; add examples only if needed |
+| Unsupported claims | Undefined evidence scope or missing-data behavior | Require cited support, distinguish inference, permit uncertainty |
+| Missing tool call | User asked for suggestions rather than action, or routing is vague | State the authorized action and a conditional route |
+| Excess tool calls | Repeated prerequisites, aggressive triggers, no stop rule | Deduplicate and define evidence-based stopping |
+| Agent stops early | Permission boundary is vague or final plan substitutes for action | Define authorized actions and completion/blocker stop rules |
+| Agent overbuilds | Scope and success criteria are broad | Name the requested scope and exclude unrelated features or refactors |
+| Too much delegation | No size or independence threshold | Add delegation damping and a concurrency cap |
+| Long visible answer | No explicit output length contract | Specify preserved content, omissions, sections, and word limit |
+| High latency/cost | Excess prompt text or effort | Delete first, then compare one lower effort level |
+| Long-context miss | Query precedes large documents | Put documents first and query last; Anthropic measured up to ~30% improvement |
+| Fable 5 refusal/fallback | Prompt solicits internal reasoning text | Request evidence and conclusions; consume API-provided summaries if needed |
 
-1. Screen queries for compliance
-2. Process legitimate requests
-3. Refuse non-compliant ones with specific explanations
+## Model and Effort Regression Checks
 
-This multi-layered approach creates comprehensive defense without relying on any single security mechanism.
+Preserve the current model and effort as the baseline before tuning. For GPT-5.6, test the same reasoning effort and one level lower. For Claude Opus 5 and Claude Fable 5, start from `high`, then compare lower levels where quality holds and higher levels only for capability-sensitive work.
 
-### Important Note
+Effort is not a substitute for missing success criteria, routing, dependencies, validation, or stop rules. On Opus 5, effort does not reliably control visible response length; use an explicit length and shape contract.
 
-No single technique provides complete protection. A defense-in-depth approach combining multiple strategies provides the most robust security against jailbreaks and prompt injections.
+When a prompt regresses, inspect a small set of real traces, classify the observable failure, locate the likely instruction or contradiction, make one surgical edit, and rerun those same traces. Stop iterating when the acceptance threshold is met or the remaining issue belongs in model choice, runtime controls, tools, retrieval, or application enforcement rather than prompt prose.

package/dist/builtin/workflows/src/authoring.d.ts

@@ -1,6 +1,6 @@
 import type { TSchema } from "typebox";
 export type { Static, TSchema } from "typebox";
-export type { AgentSessionAdapter, CompleteAdapter, CompleteStageOpts, GitWorktreeSetupOptions, GitWorktreeSetupResult, PromptAdapter, PromptOptions, ResolvedInputs, RunResult, RunStatus, StageAdapters, StageStatus, StageOptions, StageContext, StageSnapshot, StageExecutionMeta, StageMcpOptions, StageOutputOptions, StagePromptOptions, StageSendUserMessageOptions, StageUserMessageContent, StageUserMessageDelivery, StageSessionCreateOptions, StageSessionCreateResult, StageSessionEvent, StageSessionRuntime, WorkflowAction, WorkflowArtifact, WorkflowChainOptions, WorkflowChildResult, WorkflowContextMode, WorkflowControlEvent, WorkflowCustomToolDefinition, WorkflowCustomUiComponent, WorkflowCustomUiFactory, WorkflowCustomUiKeybindings, WorkflowCustomUiOptions, WorkflowCustomUiOverlayHandle, WorkflowCustomUiOverlayOptions, WorkflowCustomUiTheme, WorkflowCustomUiTui, WorkflowDetails, WorkflowDetailsMode, WorkflowDetailsStatus, WorkflowExecutionMode, WorkflowExecutionPolicy, WorkflowExitOptions, WorkflowExitStatus, WorkflowInputBindings, WorkflowInputSchema, WorkflowInputSchemaMap, WorkflowInputValues, WorkflowIntercomSummary, WorkflowMaxOutput, WorkflowMcpPort, WorkflowModelAttempt, WorkflowModelCatalogPort, WorkflowModelFallbackFields, WorkflowModelInfo, WorkflowModelUsage, WorkflowModelValue, WorkflowOutputMode, WorkflowOutputSchema, WorkflowOutputSchemaMap, WorkflowOutputValues, WorkflowParallelOptions, WorkflowPersistencePort, WorkflowProgressSummary, WorkflowRunChildArgs, WorkflowRunChildOptions, WorkflowRunChildOptionsArgument, WorkflowRunOutput, WorkflowRuntimeConfig, WorkflowSerializableObject, WorkflowSerializablePrimitive, WorkflowSerializableValue, WorkflowSharedTaskDefaults, WorkflowTaskContext, WorkflowTaskContextInput, WorkflowTaskOptions, WorkflowTaskResult, WorkflowTaskSessionFields, WorkflowTaskSessionOptions, WorkflowTaskStep, WorkflowThinkingLevel, WorkflowUIAdapter, WorkflowUIContext, WorkflowWorktreeInputBinding, } from "./shared/authoring-contract.js";
+export type { AgentSessionAdapter, CompleteAdapter, CompleteStageOpts, GitWorktreeSetupOptions, GitWorktreeSetupResult, PromptAdapter, PromptOptions, ResolvedInputs, RunResult, RunStatus, StageAdapters, StageStatus, StageOptions, StageContext, StageSnapshot, ToolNodeSnapshot, StageExecutionMeta, StageMcpOptions, StageOutputOptions, StagePromptOptions, StageSendUserMessageOptions, StageUserMessageContent, StageUserMessageDelivery, StageSessionCreateOptions, StageSessionCreateResult, StageSessionEvent, StageSessionRuntime, WorkflowAction, WorkflowArtifact, WorkflowChainOptions, WorkflowChildResult, WorkflowContextMode, WorkflowControlEvent, WorkflowCustomToolDefinition, WorkflowCustomUiComponent, WorkflowCustomUiFactory, WorkflowCustomUiKeybindings, WorkflowCustomUiOptions, WorkflowCustomUiOverlayHandle, WorkflowCustomUiOverlayOptions, WorkflowCustomUiTheme, WorkflowCustomUiTui, WorkflowDetails, WorkflowDetailsMode, WorkflowDetailsStatus, WorkflowExecutionMode, WorkflowExecutionPolicy, WorkflowExitOptions, WorkflowExitStatus, WorkflowInputBindings, WorkflowInputSchema, WorkflowInputSchemaMap, WorkflowInputValues, WorkflowIntercomSummary, WorkflowMaxOutput, WorkflowMcpPort, WorkflowModelAttempt, WorkflowModelCatalogPort, WorkflowModelFallbackFields, WorkflowModelInfo, WorkflowModelUsage, WorkflowModelValue, WorkflowOutputMode, WorkflowOutputSchema, WorkflowOutputSchemaMap, WorkflowOutputValues, WorkflowParallelOptions, WorkflowPersistencePort, WorkflowProgressSummary, WorkflowRunChildArgs, WorkflowRunChildOptions, WorkflowRunChildOptionsArgument, WorkflowRunOutput, WorkflowRuntimeConfig, WorkflowSerializableObject, WorkflowSerializablePrimitive, WorkflowSerializableValue, WorkflowSharedTaskDefaults, WorkflowTaskContext, WorkflowTaskContextInput, WorkflowTaskOptions, WorkflowTaskResult, WorkflowTaskSessionFields, WorkflowTaskSessionOptions, WorkflowTaskStep, WorkflowThinkingLevel, WorkflowUIAdapter, WorkflowToolError, WorkflowToolFailure, WorkflowToolOptions, WorkflowToolOutcome, WorkflowToolPrimitive, WorkflowToolReturnOptions, WorkflowToolSuccess, WorkflowToolThrowOptions, WorkflowUIContext, WorkflowWorktreeInputBinding, } from "./shared/authoring-contract.js";
 import type * as AuthoringContract from "./shared/authoring-contract.js";
 import type { AuthoredWorkflowSpec as SharedAuthoredWorkflowSpec, WorkflowInputsFromSchemas, WorkflowOutputsFromSchemas, WorkflowProvidedInputsFromSchemas } from "./shared/workflow-authoring-types.js";
 export type { WorkflowInputsFromSchemas, WorkflowOutputsFromSchemas, WorkflowProvidedInputsFromSchemas, } from "./shared/workflow-authoring-types.js";
@@ -100,11 +100,15 @@ export interface RunSnapshot {
     readonly name: string;
     readonly status: RunStatus;
     readonly stages: readonly StageSnapshot[];
+    /** First-class durable ctx.tool nodes; populated by the runtime. */
+    readonly toolNodes?: readonly import("./shared/authoring-contract.js").ToolNodeSnapshot[];
     readonly startedAt: number;
     readonly endedAt?: number;
     readonly durationMs?: number;
     readonly result?: WorkflowOutputValues;
     readonly error?: string;
+    /** Tool node whose rejection supplied the selected terminal failure. */
+    readonly failedToolNodeId?: string;
     /** True when the run reached its terminal status through ctx.exit(). */
     readonly exited?: boolean;
     readonly exitReason?: string;

package/dist/builtin/workflows/src/durable/backend.ts

@@ -12,6 +12,7 @@ import type {
   DurableStageCheckpoint,
   DurableWorkflowHandle,
   DurableWorkflowStatus,
+  DurableWorkflowFailureMetadata,
   ResumableWorkflowEntry,
 } from "./types.js";
 export interface DurableWorkflowCatalogEntries {
@@ -50,6 +51,12 @@ export interface DurableWorkflowBackend {
   /** Persist a checkpoint before exposing its side effect. */
   recordCheckpointAsync(checkpoint: DurableCheckpoint): Promise<void>;
 
+  /**
+   * Persist additive replay metadata without turning a rejected storage write
+   * into a fatal flush error. Returns false only for the storage rejection.
+   */
+  recordAdditiveCheckpointBestEffort(checkpoint: DurableCheckpoint): Promise<boolean>;
+
   /** Wait for all serialized writes to settle. */
   flush(): Promise<void>;
 
@@ -59,6 +66,8 @@ export interface DurableWorkflowBackend {
    * effects on resume.
    */
   getToolOutput(workflowId: string, argsHash: string): WorkflowSerializableValue | undefined;
+  /** Return the full cached tool checkpoint so graph topology can be replayed. */
+  getToolCheckpoint(workflowId: string, argsHash: string): DurableToolCheckpoint | undefined;
 
   /**
    * Look up a cached UI response by prompt hash. Returns `undefined` if the
@@ -90,7 +99,7 @@ export interface DurableWorkflowBackend {
   getLoadableWorkflow(workflowId: string): DurableWorkflowHandle | undefined;
 
   /** Update workflow status (running/paused/completed/failed/cancelled/blocked). */
-  setWorkflowStatus(workflowId: string, status: DurableWorkflowStatus, pendingPrompts?: number, resumable?: boolean): void;
+  setWorkflowStatus(workflowId: string, status: DurableWorkflowStatus, pendingPrompts?: number, resumable?: boolean, failure?: DurableWorkflowFailureMetadata): void;
   /** Atomically update status only when the authoritative status is expected. */
   transitionWorkflowStatus(
     workflowId: string,
@@ -186,6 +195,9 @@ export class InMemoryDurableBackend implements DurableWorkflowBackend {
       ...(handle.label !== undefined ? { label: handle.label } : {}),
       ...(handle.rootWorkflowId !== undefined ? { rootWorkflowId: handle.rootWorkflowId } : {}),
       ...(handle.resumable !== undefined ? { resumable: handle.resumable } : {}),
+      ...workflowFailureFields(handle.error !== undefined
+        ? handle
+        : handle.status === "running" ? undefined : existing?.handle),
       ...(handle.ownerExecutorId !== undefined ? { ownerExecutorId: handle.ownerExecutorId } : existing?.handle.ownerExecutorId !== undefined ? { ownerExecutorId: existing.handle.ownerExecutorId } : {}),
     };
     if (existing) existing.handle = full;
@@ -199,9 +211,15 @@ export class InMemoryDurableBackend implements DurableWorkflowBackend {
     const key = checkpointKey(currentCheckpoint);
     if (rec.checkpoints.has(key)) return;
     rec.checkpoints.set(key, currentCheckpoint);
-    if (currentCheckpoint.kind === "tool") rec.toolByHash.set(currentCheckpoint.argsHash, currentCheckpoint);
-    else if (currentCheckpoint.kind === "ui") rec.uiByHash.set(currentCheckpoint.promptHash, currentCheckpoint);
-    else {
+    if (currentCheckpoint.kind === "tool") {
+      const existing = rec.toolByHash.get(currentCheckpoint.argsHash);
+      if (currentCheckpoint.throwingFailureError === undefined
+        && (existing === undefined || currentCheckpoint.completedAt >= existing.completedAt)) {
+        rec.toolByHash.set(currentCheckpoint.argsHash, currentCheckpoint);
+      }
+    } else if (currentCheckpoint.kind === "ui") {
+      rec.uiByHash.set(currentCheckpoint.promptHash, currentCheckpoint);
+    } else {
       if ("output" in currentCheckpoint) rec.stageOutputByReplayKey.set(currentCheckpoint.replayKey, currentCheckpoint);
       if (currentCheckpoint.sessionId !== undefined || currentCheckpoint.sessionFile !== undefined) {
         const existing = rec.stageSessionByReplayKey.get(currentCheckpoint.replayKey);
@@ -217,12 +235,25 @@ export class InMemoryDurableBackend implements DurableWorkflowBackend {
     this.recordCheckpoint(checkpoint);
   }
 
+  async recordAdditiveCheckpointBestEffort(checkpoint: DurableCheckpoint): Promise<boolean> {
+    try {
+      await this.recordCheckpointAsync(checkpoint);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
   async flush(): Promise<void> {}
 
   getToolOutput(workflowId: string, argsHash: string): WorkflowSerializableValue | undefined {
     return this.workflows.get(workflowId)?.toolByHash.get(argsHash)?.output;
   }
 
+  getToolCheckpoint(workflowId: string, argsHash: string): DurableToolCheckpoint | undefined {
+    return this.workflows.get(workflowId)?.toolByHash.get(argsHash);
+  }
+
   getUiResponse(workflowId: string, promptHash: string): WorkflowSerializableValue | undefined {
     return this.workflows.get(workflowId)?.uiByHash.get(promptHash)?.response;
   }
@@ -269,10 +300,23 @@ export class InMemoryDurableBackend implements DurableWorkflowBackend {
     return { resumable: this.listResumableWorkflows(), completed: this.listCompletedWorkflows() };
   }
 
-  setWorkflowStatus(workflowId: string, status: DurableWorkflowStatus, pendingPrompts?: number, resumable?: boolean): void {
+  setWorkflowStatus(workflowId: string, status: DurableWorkflowStatus, pendingPrompts?: number, resumable?: boolean, failure?: DurableWorkflowFailureMetadata): void {
     const rec = this.workflows.get(workflowId);
     if (!rec) return;
-    rec.handle = { ...rec.handle, status, updatedAt: Date.now(), ...(pendingPrompts !== undefined ? { pendingPrompts } : {}), ...(resumable !== undefined ? { resumable } : {}) };
+    rec.handle = {
+      ...rec.handle,
+      error: undefined,
+      failureKind: undefined,
+      failureCode: undefined,
+      failureRecoverability: undefined,
+      failureDisposition: undefined,
+      failedToolNodeId: undefined,
+      status,
+      updatedAt: Date.now(),
+      ...(pendingPrompts !== undefined ? { pendingPrompts } : {}),
+      ...(resumable !== undefined ? { resumable } : {}),
+      ...(status === "failed" ? failure ?? {} : {}),
+    };
     if (pendingPrompts !== undefined) this.promptReservations.delete(workflowId);
   }
 
@@ -340,7 +384,7 @@ export class InMemoryDurableBackend implements DurableWorkflowBackend {
 
   listCompletedWorkflows(): readonly ResumableWorkflowEntry[] {
     return [...this.workflows.values()]
-      .filter((rec) => isRootWorkflow(rec.handle) && isCompletedHandle(rec.handle))
+      .filter((rec) => isRootWorkflow(rec.handle) && isHistoricalHandle(rec.handle))
       .map((rec) => toResumableEntry(rec.handle));
   }
 
@@ -363,6 +407,7 @@ export class InMemoryDurableBackend implements DurableWorkflowBackend {
       ...(h.label !== undefined ? { label: h.label } : {}),
       ...(h.rootWorkflowId !== undefined ? { rootWorkflowId: h.rootWorkflowId } : {}),
       ...(h.resumable !== undefined ? { resumable: h.resumable } : {}),
+      ...workflowFailureFields(h),
       ...(h.invocationCwd !== undefined ? { invocationCwd: h.invocationCwd } : {}),
       ...(h.workflowCwd !== undefined ? { workflowCwd: h.workflowCwd } : {}),
       ...(h.repositoryRoot !== undefined ? { repositoryRoot: h.repositoryRoot } : {}),
@@ -405,8 +450,21 @@ function hasResumeProgress(handle: DurableWorkflowHandle): boolean {
   return handle.completedCheckpoints > 0 || handle.pendingPrompts > 0;
 }
 
-function isCompletedHandle(handle: DurableWorkflowHandle): boolean {
-  return handle.status === "completed" && hasResumeProgress(handle);
+function isHistoricalHandle(handle: DurableWorkflowHandle): boolean {
+  return handle.status === "completed" && hasResumeProgress(handle)
+    || handle.status === "failed" && !isDurableWorkflowResumable(handle) && hasResumeProgress(handle);
+}
+
+function workflowFailureFields(handle: Partial<DurableWorkflowHandle> | undefined): Partial<DurableWorkflowFailureMetadata> {
+  if (handle === undefined) return {};
+  return {
+    ...(handle.error !== undefined ? { error: handle.error } : {}),
+    ...(handle.failureKind !== undefined ? { failureKind: handle.failureKind } : {}),
+    ...(handle.failureCode !== undefined ? { failureCode: handle.failureCode } : {}),
+    ...(handle.failureRecoverability !== undefined ? { failureRecoverability: handle.failureRecoverability } : {}),
+    ...(handle.failureDisposition !== undefined ? { failureDisposition: handle.failureDisposition } : {}),
+    ...(handle.failedToolNodeId !== undefined ? { failedToolNodeId: handle.failedToolNodeId } : {}),
+  };
 }
 
 /** Convert a durable workflow handle into a resume-catalog entry. */
@@ -426,6 +484,7 @@ function toResumableEntry(handle: DurableWorkflowHandle): ResumableWorkflowEntry
     ...(handle.label !== undefined ? { label: handle.label } : {}),
     ...(handle.rootWorkflowId !== undefined ? { rootWorkflowId: handle.rootWorkflowId } : {}),
     ...(handle.resumable !== undefined ? { resumable: handle.resumable } : {}),
+    ...workflowFailureFields(handle),
     ...(handle.invocationCwd !== undefined ? { invocationCwd: handle.invocationCwd } : {}),
     ...(handle.workflowCwd !== undefined ? { workflowCwd: handle.workflowCwd } : {}),
     ...(handle.repositoryRoot !== undefined ? { repositoryRoot: handle.repositoryRoot } : {}),

package/dist/builtin/workflows/src/durable/boundary-lifecycle.ts

@@ -0,0 +1,148 @@
+import type { WorkflowChildResult, WorkflowOutputValues } from "../shared/types.js";
+import {
+  DURABLE_BOUNDARY_TOPOLOGY_VERSION,
+  DURABLE_STAGE_TOPOLOGY_VERSION,
+  type DurableStageCheckpoint,
+  type DurableStageRunTopology,
+  type DurableStageTopology,
+  type DurableWorkflowBoundaryTopology,
+} from "./types.js";
+import { sameRun, sameStrings } from "./stage-topology-validation.js";
+import { parseWorkflowChildResult } from "./workflow-child-result.js";
+
+export interface ValidBoundaryLifecycle {
+  readonly latestTerminal?: DurableStageCheckpoint;
+  readonly completedOutput?: WorkflowChildResult<WorkflowOutputValues>;
+}
+
+export type BoundaryLifecycleResolution =
+  | { readonly error: string }
+  | { readonly lifecycle: ValidBoundaryLifecycle };
+
+/** Validate one boundary's atomic start/terminal lifecycle and resolve its latest legal state. */
+export function resolveBoundaryLifecycle(
+  start: DurableStageCheckpoint,
+  stages: readonly DurableStageCheckpoint[],
+  requireTerminal: boolean,
+): BoundaryLifecycleResolution {
+  const startTopology = start.topology;
+  const startBoundary = startTopology?.boundary;
+  const startRun = startTopology?.run;
+  const related = stages.filter((stage) => {
+    const boundary = stage.topology?.boundary;
+    return boundary !== undefined && (stage.replayKey === start.replayKey
+      || stage.topology?.stageId === startTopology?.stageId
+      || boundary.child.runId === startBoundary?.child.runId);
+  });
+  const starts = related.filter((stage) => stage.topology!.boundary!.event === "start");
+  if (starts.length !== 1 || starts[0] !== start) return failure("boundary has no unique start record");
+  if (startTopology === undefined || startBoundary === undefined || startRun === undefined
+    || startTopology.version !== DURABLE_STAGE_TOPOLOGY_VERSION
+    || startBoundary.version !== DURABLE_BOUNDARY_TOPOLOGY_VERSION
+    || startTopology.stageId.length === 0 || startTopology.sourceOrder === undefined
+    || startTopology.status !== "running" || startBoundary.status !== "running"
+    || startBoundary.event !== "start" || start.output !== undefined
+    || startBoundary.replayScope !== start.replayKey
+    || !validBoundaryOwnership(startTopology, startRun, startBoundary)) {
+    return failure("malformed boundary-start transition");
+  }
+
+  const terminals = related.filter((stage) => stage.topology!.boundary!.event === "terminal");
+  if (terminals.length === 0) {
+    return requireTerminal
+      ? failure("completed boundary has no terminal record")
+      : { lifecycle: {} };
+  }
+  const statuses = new Set<string>();
+  let completedOutput: WorkflowChildResult<WorkflowOutputValues> | undefined;
+  for (const terminal of terminals) {
+    const terminalTopology = terminal.topology!;
+    const terminalBoundary = terminalTopology.boundary!;
+    if (statuses.has(terminalBoundary.status)
+      || terminalTopology.status !== terminalBoundary.status) {
+      return failure("boundary has conflicting terminal records");
+    }
+    statuses.add(terminalBoundary.status);
+    if (terminalTopology.version !== startTopology.version
+      || terminalTopology.stageId !== startTopology.stageId
+      || !sameStrings(terminalTopology.parentIds, startTopology.parentIds)
+      || terminalTopology.sourceOrder !== startTopology.sourceOrder
+      || !sameRun(terminalTopology.run, startRun)
+      || terminal.name !== start.name || terminal.replayKey !== start.replayKey
+      || terminalBoundary.version !== startBoundary.version
+      || terminalBoundary.replayScope !== startBoundary.replayScope
+      || terminalBoundary.alias !== startBoundary.alias
+      || terminalBoundary.workflow !== startBoundary.workflow
+      || terminalBoundary.invocationFingerprint !== startBoundary.invocationFingerprint
+      || !sameBoundaryChild(terminalBoundary.child, startBoundary.child)) {
+      return failure("boundary terminal immutable identity drifted from its start");
+    }
+    if (terminalBoundary.status === "completed") {
+      const parsed = parseWorkflowChildResult(terminal.output);
+      if (parsed === undefined || parsed.runId !== startBoundary.child.runId
+        || parsed.workflow !== startBoundary.workflow) {
+        return failure("completed boundary output is malformed or stale");
+      }
+      completedOutput = parsed;
+    } else if (terminal.output !== undefined) {
+      return failure("failed or skipped boundary cannot persist a successful output");
+    }
+  }
+
+  if (terminals.length > 2 || (terminals.length === 2
+    && (!statuses.has("completed") || (!statuses.has("failed") && !statuses.has("skipped"))
+      || terminals[0]!.completedAt === terminals[1]!.completedAt))) {
+    return failure("boundary has an illegal terminal transition");
+  }
+  const completed = terminals.find((terminal) => terminal.topology!.boundary!.status === "completed");
+  const outputRecords = stages.filter((stage) => stage.replayKey === start.replayKey && stage.output !== undefined);
+  if (outputRecords.length !== (completed === undefined ? 0 : 1)
+    || (completed !== undefined && outputRecords[0]?.checkpointId !== completed.checkpointId)) {
+    return failure("boundary replay key has conflicting output records");
+  }
+  const latestTerminal = terminals.reduce((latest, terminal) =>
+    terminal.completedAt > latest.completedAt ? terminal : latest
+  );
+  return {
+    lifecycle: {
+      latestTerminal,
+      ...(completedOutput !== undefined ? { completedOutput } : {}),
+    },
+  };
+}
+
+export function boundaryTransitionError(
+  start: DurableStageCheckpoint,
+  stages: readonly DurableStageCheckpoint[],
+  requireTerminal: boolean,
+): string | undefined {
+  const resolved = resolveBoundaryLifecycle(start, stages, requireTerminal);
+  return "error" in resolved ? resolved.error : undefined;
+}
+
+function validBoundaryOwnership(
+  topology: DurableStageTopology,
+  run: DurableStageRunTopology,
+  boundary: DurableWorkflowBoundaryTopology,
+): boolean {
+  const expectedRoot = run.rootRunId ?? run.runId;
+  return boundary.alias.length > 0 && boundary.workflow.length > 0
+    && boundary.child.runId.length > 0 && boundary.child.runName.length > 0
+    && boundary.child.parentRunId === run.runId
+    && boundary.child.parentStageId === topology.stageId
+    && boundary.child.rootRunId === expectedRoot;
+}
+
+function sameBoundaryChild(
+  actual: DurableWorkflowBoundaryTopology["child"],
+  expected: DurableWorkflowBoundaryTopology["child"],
+): boolean {
+  return actual.runId === expected.runId && actual.runName === expected.runName
+    && actual.parentRunId === expected.parentRunId
+    && actual.parentStageId === expected.parentStageId
+    && actual.rootRunId === expected.rootRunId;
+}
+
+function failure(error: string): { readonly error: string } {
+  return { error };
+}