@osolmaz/pi-workflows 0.12.0 → 0.12.1

package/src/workflows/engine.ts

@@ -32,7 +32,7 @@ import {
   readRunBundle,
 } from "./store.js";
 import type {
-  AcceptedHumanDecision,
+  ResolvedHumanDecision,
   AgentNodeDefinition,
   AgentStepExecutor,
   ActionNodeDefinition,
@@ -377,7 +377,7 @@ export class WorkflowEngine {
       workflowSource?: WorkflowSource;
       runId?: string;
       force?: boolean;
-      humanDecision?: AcceptedHumanDecision;
+      humanDecision?: ResolvedHumanDecision;
     } = {},
   ): Promise<WorkflowRunResult> {
     workflow = isCompiledWorkflow(workflow) ? workflow : compileWorkflowDefinition(workflow);
@@ -412,14 +412,13 @@ export class WorkflowEngine {
       }
       const request = parent.state.finalOutput as HumanDecisionRequest;
       if (
-        (request?.schema !== "pi-workflows.human-decision-request.v1" &&
-          request?.schema !== "pi-workflows.human-decision-request.v2") ||
+        request?.schema !== "pi-workflows.human-decision-request.v1" ||
         request.decisionId !== options.humanDecision.decisionId ||
         request.requestDigest !== options.humanDecision.requestDigest
       ) {
         throw new Error("Accepted human decision does not match the waiting request");
       }
-      const durableDecision = await new HumanDecisionStore(this.store.outputRoot).readAccepted(
+      const durableDecision = await new HumanDecisionStore(this.store.outputRoot).readResolved(
         request.decisionId,
       );
       if (durableDecision === null || !isDeepStrictEqual(durableDecision, options.humanDecision)) {
@@ -464,19 +463,17 @@ export class WorkflowEngine {
         requestDigest: options.humanDecision.requestDigest,
         nodeId: acceptedNodeId ?? waitingNodeId,
         response: options.humanDecision.response,
+        provenance: options.humanDecision.provenance,
         acceptedAt: options.humanDecision.acceptedAt,
         answerDigest: options.humanDecision.answerDigest,
       };
-      state.humanDecision =
-        options.humanDecision.schema === "pi-workflows.human-decision-accepted.v2"
-          ? {
-              schema: "pi-workflows.human-decision-receipt.v2",
-              ...receipt,
-              subjectDigest: options.humanDecision.subjectDigest,
-              presentationDigest: options.humanDecision.presentationDigest,
-              revision: options.humanDecision.revision,
-            }
-          : { schema: "pi-workflows.human-decision-receipt.v1", ...receipt };
+      state.humanDecision = {
+        schema: "pi-workflows.human-decision-receipt.v1",
+        ...receipt,
+        subjectDigest: options.humanDecision.subjectDigest,
+        presentationDigest: options.humanDecision.presentationDigest,
+        revision: options.humanDecision.revision,
+      };
       state.outputs[waitingNodeId] = acceptedResponse;
       const priorResult = state.results[waitingNodeId];
       if (priorResult === undefined) {
@@ -1317,6 +1314,10 @@ async function runCheckpointNode(
       typeof node.humanDecision.audience === "function"
         ? await node.humanDecision.audience(context)
         : node.humanDecision.audience;
+    const timeout =
+      typeof node.humanDecision.onTimeout === "function"
+        ? await node.humanDecision.onTimeout(context)
+        : node.humanDecision.onTimeout;
     const request = createHumanDecisionRequest({
       runId: context.state.runId,
       workflowName: execution.workflowName,
@@ -1324,6 +1325,7 @@ async function runCheckpointNode(
       attemptId: execution.attemptId,
       contract: { audience, choices: node.humanDecision.choices },
       prompt,
+      ...(timeout !== undefined ? { timeout } : {}),
     });
     await new HumanDecisionStore(execution.store.outputRoot).createRequest(request);
     return { output: request, promptText: null };

package/src/workflows/errors.ts

@@ -56,6 +56,30 @@ export class WorkflowSourceChangedError extends Error {
   }
 }
 
+/** A built-in revision is unavailable, so its incompatible run must restart. */
+export class BuiltinWorkflowRevisionChangedError extends Error {
+  readonly runId: string;
+  readonly workflowId: string;
+  readonly previousRevision: string;
+  readonly currentRevision: string;
+
+  constructor(options: {
+    runId: string;
+    workflowId: string;
+    previousRevision: string;
+    currentRevision: string;
+  }) {
+    super(
+      `Built-in workflow ${options.workflowId} revision ${options.previousRevision} cannot resume run ${options.runId} with installed revision ${options.currentRevision}; cancel run ${options.runId}, then start ${options.workflowId} again`,
+    );
+    this.name = "BuiltinWorkflowRevisionChangedError";
+    this.runId = options.runId;
+    this.workflowId = options.workflowId;
+    this.previousRevision = options.previousRevision;
+    this.currentRevision = options.currentRevision;
+  }
+}
+
 export function isClaimLostError(error: unknown): error is ClaimLostError {
   return error instanceof ClaimLostError;
 }

package/src/workflows/human-decision.ts

@@ -24,6 +24,8 @@ import type {
   HumanDecisionSettlementRecord,
   HumanDecisionSubmission,
   HumanDecisionTextInput,
+  HumanDecisionTimeout,
+  ResolvedHumanDecision,
   WorkflowNodeCommon,
   WorkflowNodeContext,
 } from "./types.js";
@@ -43,6 +45,14 @@ export type HumanDecisionDefinition<TChoices extends HumanDecisionChoiceMap> =
     audience: HumanDecisionAudience;
     choices: TChoices;
     request: (context: WorkflowNodeContext) => HumanDecisionPrompt | Promise<HumanDecisionPrompt>;
+    onTimeout?:
+      | { afterMs: number; response: HumanDecisionResponseFor<TChoices> }
+      | ((
+          context: WorkflowNodeContext,
+        ) =>
+          | { afterMs: number; response: HumanDecisionResponseFor<TChoices> }
+          | undefined
+          | Promise<{ afterMs: number; response: HumanDecisionResponseFor<TChoices> } | undefined>);
   };
 
 export type HumanDecisionResponseFor<TChoices extends HumanDecisionChoiceMap> = {
@@ -98,11 +108,25 @@ export function humanDecision<const TChoices extends HumanDecisionChoiceMap>(
   if (typeof definition.request !== "function") {
     throw new Error("Human decision request must be a function");
   }
-  const { choices, request, ...common } = definition;
+  const { choices, request, onTimeout, ...common } = definition;
+  if (
+    onTimeout !== undefined &&
+    typeof onTimeout !== "function" &&
+    (typeof onTimeout.afterMs !== "number" ||
+      !Number.isFinite(onTimeout.afterMs) ||
+      onTimeout.afterMs <= 0)
+  ) {
+    throw new Error("Human decision onTimeout afterMs must be a finite positive number");
+  }
   return checkpoint({
     ...common,
     summary: typeof audience === "string" ? `human decision for ${audience}` : "human decision",
-    humanDecision: { audience, choices, request },
+    humanDecision: {
+      audience,
+      choices,
+      request,
+      ...(onTimeout !== undefined ? { onTimeout } : {}),
+    },
   }) as CheckpointNodeDefinition & { readonly __humanChoices?: TChoices };
 }
 
@@ -136,11 +160,31 @@ export function createHumanDecisionRequest(input: {
   attemptId: string;
   contract: { audience: string; choices: HumanDecisionChoiceMap };
   prompt: HumanDecisionPrompt;
+  timeout?: HumanDecisionTimeout;
   createdAt?: string;
 }): HumanDecisionRequest {
   validateChoices(input.contract.choices);
+  const createdAt = input.createdAt ?? new Date().toISOString();
   const title = requireString(input.prompt.title, "Human decision title");
-  const expiresAt = validateExpiry(input.prompt.expiresAt, input.createdAt);
+  if (input.timeout !== undefined && input.prompt.expiresAt !== undefined) {
+    throw new Error("Human decision request cannot combine expiresAt with onTimeout");
+  }
+  if (
+    input.timeout !== undefined &&
+    (typeof input.timeout.afterMs !== "number" ||
+      !Number.isFinite(input.timeout.afterMs) ||
+      input.timeout.afterMs <= 0)
+  ) {
+    throw new Error("Human decision onTimeout afterMs must be a finite positive number");
+  }
+  const defaultResponse =
+    input.timeout === undefined
+      ? undefined
+      : validateResponseForChoices(input.contract.choices, input.timeout.response);
+  const expiresAt =
+    input.timeout === undefined
+      ? validateExpiry(input.prompt.expiresAt, createdAt)
+      : new Date(Date.parse(createdAt) + input.timeout.afterMs).toISOString();
   const common = {
     runId: input.runId,
     workflowName: input.workflowName,
@@ -150,58 +194,35 @@ export function createHumanDecisionRequest(input: {
     title,
     choices: input.contract.choices,
     ...(expiresAt !== undefined ? { expiresAt } : {}),
+    ...(defaultResponse !== undefined ? { defaultResponse } : {}),
   } as const;
-  const presented =
-    Object.hasOwn(input.prompt, "subject") || Object.hasOwn(input.prompt, "presentation");
-  if (presented) {
-    validatePresentedText(title, "Human decision title");
-    validatePresentedChoices(input.contract.choices);
-    if (Object.hasOwn(input.prompt, "body")) {
-      throw new Error("Presented human decision requests must not contain a legacy body");
-    }
-    if (!Object.hasOwn(input.prompt, "subject") || !Object.hasOwn(input.prompt, "presentation")) {
-      throw new Error("Presented human decision requests require subject and presentation");
-    }
-    const prompt = input.prompt as Extract<HumanDecisionPrompt, { subject: unknown }>;
-    assertJsonValue(prompt.subject, "Human decision subject");
-    const presentation = normalizeDecisionPresentation(prompt.presentation);
-    const revision = prompt.revision ?? 1;
-    if (!Number.isInteger(revision) || revision < 1) {
-      throw new Error("Human decision revision must be a positive integer");
-    }
-    const basis = {
-      schema: "pi-workflows.human-decision-request.v2" as const,
-      ...common,
-      subject: prompt.subject,
-      presentation,
-      revision,
-    };
-    const subjectDigest = digestCanonical(prompt.subject);
-    const presentationDigest = digestCanonical(presentation);
-    const requestDigest = digestCanonical(basis);
-    const decisionId = decisionIdFor(input, requestDigest);
-    return {
-      ...basis,
-      decisionId,
-      requestDigest,
-      subjectDigest,
-      presentationDigest,
-      createdAt: input.createdAt ?? new Date().toISOString(),
-    };
+  validatePresentedText(title, "Human decision title");
+  validatePresentedChoices(input.contract.choices);
+  const prompt = input.prompt;
+  assertJsonValue(prompt.subject, "Human decision subject");
+  const presentation = normalizeDecisionPresentation(prompt.presentation);
+  const revision = prompt.revision ?? 1;
+  if (!Number.isInteger(revision) || revision < 1) {
+    throw new Error("Human decision revision must be a positive integer");
   }
-  const prompt = input.prompt as Extract<HumanDecisionPrompt, { body: unknown }>;
-  assertJsonValue(prompt.body, "Human decision body");
   const basis = {
     schema: "pi-workflows.human-decision-request.v1" as const,
     ...common,
-    body: prompt.body,
+    subject: prompt.subject,
+    presentation,
+    revision,
   };
-  const requestDigest = digest(basis);
+  const subjectDigest = digestCanonical(prompt.subject);
+  const presentationDigest = digestCanonical(presentation);
+  const requestDigest = digestCanonical(basis);
+  const decisionId = decisionIdFor(input, requestDigest);
   return {
     ...basis,
-    decisionId: decisionIdFor(input, requestDigest),
+    decisionId,
     requestDigest,
-    createdAt: input.createdAt ?? new Date().toISOString(),
+    subjectDigest,
+    presentationDigest,
+    createdAt,
   };
 }
 
@@ -220,13 +241,20 @@ function decisionIdFor(
 export function validateHumanDecisionResponse(
   request: HumanDecisionRequest,
   value: unknown,
+): HumanDecisionResponse {
+  return validateResponseForChoices(request.choices, value);
+}
+
+function validateResponseForChoices(
+  choices: HumanDecisionChoiceMap,
+  value: unknown,
 ): HumanDecisionResponse {
   const response = requireRecord(value, "Human decision response");
   const selected = response.choice;
-  if (typeof selected !== "string" || !Object.hasOwn(request.choices, selected)) {
+  if (typeof selected !== "string" || !Object.hasOwn(choices, selected)) {
     throw new Error(`Human decision choice ${JSON.stringify(selected)} is not available`);
   }
-  const selectedChoice = request.choices[selected];
+  const selectedChoice = choices[selected];
   if (!selectedChoice) throw new Error("Human decision choice contract is missing");
   if (selectedChoice.input === undefined) {
     if (response.input !== undefined) {
@@ -288,34 +316,65 @@ export function humanDecisionStateRoot(runsRoot: string): string {
 }
 
 export type HumanDecisionAcceptance =
-  | { status: "accepted" | "adopted"; decision: AcceptedHumanDecision }
-  | { status: "conflict"; decision: AcceptedHumanDecision };
+  | { status: "accepted" | "adopted"; decision: ResolvedHumanDecision }
+  | { status: "conflict"; decision: ResolvedHumanDecision };
 
 type HumanDecisionResolution =
   | {
       schema: "pi-workflows.human-decision-resolution.v1";
       outcome: "accepted";
-      decision: Extract<
-        AcceptedHumanDecision,
-        { schema: "pi-workflows.human-decision-accepted.v1" }
-      >;
+      decision: ResolvedHumanDecision;
     }
   | {
-      schema: "pi-workflows.human-decision-resolution.v2";
-      outcome: "accepted";
-      decision: Extract<
-        AcceptedHumanDecision,
-        { schema: "pi-workflows.human-decision-accepted.v2" }
-      >;
-    }
-  | {
-      schema:
-        | "pi-workflows.human-decision-resolution.v1"
-        | "pi-workflows.human-decision-resolution.v2";
+      schema: "pi-workflows.human-decision-resolution.v1";
       outcome: "cancelled";
       cancellation: HumanDecisionCancellationRecord;
     };
 
+const INCOMPATIBLE_HUMAN_DECISION_STATE =
+  "Human decision state uses an incompatible alpha contract; reset the affected workflow run and decision state.";
+
+function requireCurrentDecision(value: unknown): ResolvedHumanDecision {
+  const decision = requireRecord(value, "Resolved human decision");
+  if (
+    decision.schema !== "pi-workflows.human-decision-accepted.v1" ||
+    !Object.hasOwn(decision, "subjectDigest") ||
+    !Object.hasOwn(decision, "presentationDigest") ||
+    !Object.hasOwn(decision, "revision")
+  ) {
+    throw new Error(INCOMPATIBLE_HUMAN_DECISION_STATE);
+  }
+  return value as ResolvedHumanDecision;
+}
+
+function requireCurrentResolution(value: unknown): HumanDecisionResolution | null {
+  if (value === null) return null;
+  const resolution = requireRecord(value, "Human decision resolution");
+  if (resolution.schema !== "pi-workflows.human-decision-resolution.v1") {
+    throw new Error(INCOMPATIBLE_HUMAN_DECISION_STATE);
+  }
+  if (resolution.outcome === "accepted") {
+    return {
+      ...resolution,
+      decision: requireCurrentDecision(resolution.decision),
+    } as HumanDecisionResolution;
+  }
+  if (resolution.outcome === "cancelled") return value as HumanDecisionResolution;
+  throw new Error(INCOMPATIBLE_HUMAN_DECISION_STATE);
+}
+
+function requireCurrentDelivery(value: unknown): HumanDecisionDeliveryRecord {
+  const delivery = requireRecord(value, "Human decision delivery");
+  if (
+    delivery.schema !== "pi-workflows.human-decision-delivery.v1" ||
+    !Object.hasOwn(delivery, "presentationDigest") ||
+    !Object.hasOwn(delivery, "phase")
+  ) {
+    throw new Error(INCOMPATIBLE_HUMAN_DECISION_STATE);
+  }
+  return value as HumanDecisionDeliveryRecord;
+}
+
 export class HumanDecisionStore {
   readonly root: string;
 
@@ -412,36 +471,35 @@ export class HumanDecisionStore {
       decisionId: request.decisionId,
       requestDigest: request.requestDigest,
       response,
+      provenance: "human" as const,
       source: normalized.source,
       idempotencyKey: normalized.idempotencyKey,
       acceptedAt: attemptedAt,
       answerDigest: digest({ response, source: normalized.source }),
     };
-    const decision: AcceptedHumanDecision =
-      request.schema === "pi-workflows.human-decision-request.v2"
-        ? {
-            schema: "pi-workflows.human-decision-accepted.v2",
-            ...commonDecision,
-            subjectDigest: request.subjectDigest,
-            presentationDigest: request.presentationDigest,
-            revision: request.revision,
-          }
-        : { schema: "pi-workflows.human-decision-accepted.v1", ...commonDecision };
+    const decision: AcceptedHumanDecision = {
+      schema: "pi-workflows.human-decision-accepted.v1",
+      ...commonDecision,
+      subjectDigest: request.subjectDigest,
+      presentationDigest: request.presentationDigest,
+      revision: request.revision,
+    };
     const resolutionPath = path.join(this.decisionDir(request.decisionId), "resolution.json");
-    const resolution = {
-      schema:
-        decision.schema === "pi-workflows.human-decision-accepted.v2"
-          ? ("pi-workflows.human-decision-resolution.v2" as const)
-          : ("pi-workflows.human-decision-resolution.v1" as const),
-      outcome: "accepted" as const,
+    const resolution: HumanDecisionResolution = {
+      schema: "pi-workflows.human-decision-resolution.v1",
+      outcome: "accepted",
       decision,
-    } as HumanDecisionResolution;
+    };
     const result = await writeImmutableJson(resolutionPath, resolution, false);
     const winner =
       result === "created"
         ? resolution
         : ((await readJson(resolutionPath)) as HumanDecisionResolution | null);
     if (winner === null) throw new Error("Human decision resolution became unreadable");
+    const winningCancellation = await this.readCancellation(request.decisionId);
+    if (winningCancellation !== null) {
+      throw new Error(`Human decision request was ${winningCancellation.reason}`);
+    }
     if (winner.outcome === "cancelled") {
       throw new Error(`Human decision request was ${winner.cancellation.reason}`);
     }
@@ -455,6 +513,7 @@ export class HumanDecisionStore {
       return { status: "adopted", decision: existing };
     }
     if (
+      existing.provenance === "human" &&
       existing.idempotencyKey === decision.idempotencyKey &&
       canonicalJson(existing.response) === canonicalJson(decision.response) &&
       canonicalJson(existing.source) === canonicalJson(decision.source)
@@ -464,13 +523,74 @@ export class HumanDecisionStore {
     return { status: "conflict", decision: existing };
   }
 
+  async resolveTimeout(
+    request: HumanDecisionRequest,
+    now = new Date(),
+  ): Promise<HumanDecisionAcceptance> {
+    validateHumanDecisionRequestIntegrity(request);
+    if (request.expiresAt === undefined || request.defaultResponse === undefined) {
+      throw new Error("Human decision request has no timeout default");
+    }
+    if (Date.parse(request.expiresAt) > now.getTime()) {
+      throw new Error("Human decision timeout default is not eligible yet");
+    }
+    const response = validateHumanDecisionResponse(request, request.defaultResponse);
+    const commonDecision = {
+      decisionId: request.decisionId,
+      requestDigest: request.requestDigest,
+      response,
+      provenance: "timeout" as const,
+      acceptedAt: now.toISOString(),
+      answerDigest: digest({
+        provenance: "timeout",
+        requestDigest: request.requestDigest,
+        response,
+      }),
+    };
+    const decision: ResolvedHumanDecision = {
+      schema: "pi-workflows.human-decision-accepted.v1",
+      ...commonDecision,
+      subjectDigest: request.subjectDigest,
+      presentationDigest: request.presentationDigest,
+      revision: request.revision,
+    };
+    const resolutionPath = path.join(this.decisionDir(request.decisionId), "resolution.json");
+    const resolution: HumanDecisionResolution = {
+      schema: "pi-workflows.human-decision-resolution.v1",
+      outcome: "accepted",
+      decision,
+    };
+    const result = await writeImmutableJson(resolutionPath, resolution, false);
+    const winner =
+      result === "created"
+        ? resolution
+        : ((await readJson(resolutionPath)) as HumanDecisionResolution | null);
+    if (winner === null) throw new Error("Human decision resolution became unreadable");
+    const winningCancellation = await this.readCancellation(request.decisionId);
+    if (winningCancellation !== null) {
+      throw new Error(`Human decision request was ${winningCancellation.reason}`);
+    }
+    if (winner.outcome === "cancelled") {
+      throw new Error(`Human decision request was ${winner.cancellation.reason}`);
+    }
+    const existing = winner.decision;
+    await writeImmutableJson(
+      path.join(this.decisionDir(request.decisionId), "accepted.json"),
+      existing,
+    );
+    if (result === "created") return { status: "accepted", decision: existing };
+    return canonicalJson(existing) === canonicalJson(decision)
+      ? { status: "adopted", decision: existing }
+      : { status: "conflict", decision: existing };
+  }
+
   async listDeliveries(
     decisionId: string,
     channel: string,
   ): Promise<HumanDecisionDeliveryRecord[]> {
     const safeChannel = requireSimpleId(channel, "Human decision channel");
     const directory = path.join(this.decisionDir(decisionId), "deliveries", safeChannel);
-    return (await readJsonDirectory(directory)) as HumanDecisionDeliveryRecord[];
+    return (await readJsonDirectory(directory)).map(requireCurrentDelivery);
   }
 
   async recordSettlement(
@@ -505,8 +625,8 @@ export class HumanDecisionStore {
     reason: HumanDecisionCancellationRecord["reason"],
   ): Promise<"created" | "adopted"> {
     validateHumanDecisionRequestIntegrity(request);
-    if ((await this.readAccepted(request.decisionId)) !== null) {
-      throw new Error("Accepted human decision cannot be cancelled");
+    if ((await this.readResolved(request.decisionId)) !== null) {
+      throw new Error("Resolved human decision cannot be cancelled");
     }
     const filePath = path.join(this.decisionDir(request.decisionId), "cancelled.json");
     const record: HumanDecisionCancellationRecord = {
@@ -518,10 +638,7 @@ export class HumanDecisionStore {
     };
     const resolutionPath = path.join(this.decisionDir(request.decisionId), "resolution.json");
     const resolution: HumanDecisionResolution = {
-      schema:
-        request.schema === "pi-workflows.human-decision-request.v2"
-          ? "pi-workflows.human-decision-resolution.v2"
-          : "pi-workflows.human-decision-resolution.v1",
+      schema: "pi-workflows.human-decision-resolution.v1",
       outcome: "cancelled",
       cancellation: record,
     };
@@ -532,7 +649,7 @@ export class HumanDecisionStore {
         : ((await readJson(resolutionPath)) as HumanDecisionResolution | null);
     if (winner === null) throw new Error("Human decision resolution became unreadable");
     if (winner.outcome === "accepted") {
-      throw new Error("Accepted human decision cannot be cancelled");
+      throw new Error("Resolved human decision cannot be cancelled");
     }
     const existing = winner.cancellation;
     if (
@@ -551,9 +668,9 @@ export class HumanDecisionStore {
       path.join(this.decisionDir(decisionId), "cancelled.json"),
     )) as HumanDecisionCancellationRecord | null;
     if (stored !== null) return stored;
-    const resolution = (await readJson(
-      path.join(this.decisionDir(decisionId), "resolution.json"),
-    )) as HumanDecisionResolution | null;
+    const resolution = requireCurrentResolution(
+      await readJson(path.join(this.decisionDir(decisionId), "resolution.json")),
+    );
     if (resolution?.outcome !== "cancelled") return null;
     await writeImmutableJson(
       path.join(this.decisionDir(decisionId), "cancelled.json"),
@@ -562,14 +679,14 @@ export class HumanDecisionStore {
     return resolution.cancellation;
   }
 
-  async readAccepted(decisionId: string): Promise<AcceptedHumanDecision | null> {
-    const stored = (await readJson(
-      path.join(this.decisionDir(decisionId), "accepted.json"),
-    )) as AcceptedHumanDecision | null;
-    if (stored !== null) return stored;
-    const resolution = (await readJson(
-      path.join(this.decisionDir(decisionId), "resolution.json"),
-    )) as HumanDecisionResolution | null;
+  async readResolved(decisionId: string): Promise<ResolvedHumanDecision | null> {
+    const cancellation = await readJson(path.join(this.decisionDir(decisionId), "cancelled.json"));
+    if (cancellation !== null) return null;
+    const stored = await readJson(path.join(this.decisionDir(decisionId), "accepted.json"));
+    if (stored !== null) return requireCurrentDecision(stored);
+    const resolution = requireCurrentResolution(
+      await readJson(path.join(this.decisionDir(decisionId), "resolution.json")),
+    );
     if (resolution?.outcome !== "accepted") return null;
     await writeImmutableJson(
       path.join(this.decisionDir(decisionId), "accepted.json"),

package/src/workflows/index.ts

@@ -23,8 +23,8 @@ export {
   decisionPresentationFingerprint,
   digestCanonical,
   humanDecisionChannelRequest,
-  legacyDecisionPresentation,
   normalizeDecisionPresentation,
+  valueDecisionPresentation,
   validateHumanDecisionRequestIntegrity,
   type DecisionDocumentSegment,
 } from "./decision-presentation.js";
@@ -137,8 +137,8 @@ export {
 } from "./store.js";
 export type {
   AcceptedHumanDecision,
-  AcceptedHumanDecisionV1,
-  AcceptedHumanDecisionV2,
+  DefaultedHumanDecision,
+  ResolvedHumanDecision,
   AgentNodeDefinition,
   AgentStepContract,
   AgentStepExecutor,
@@ -167,24 +167,18 @@ export type {
   HumanDecisionChoiceMap,
   HumanDecisionContinuationRecord,
   HumanDecisionDeliveryRecord,
-  HumanDecisionDeliveryRecordV1,
-  HumanDecisionDeliveryRecordV2,
   HumanDecisionNodeContract,
   HumanDecisionPrompt,
   HumanDecisionReceipt,
-  HumanDecisionReceiptV1,
-  HumanDecisionReceiptV2,
   HumanDecisionRequest,
-  HumanDecisionRequestV1,
-  HumanDecisionRequestV2,
   HumanDecisionResponse,
   HumanDecisionSettlementRecord,
   HumanDecisionSubmission,
   HumanDecisionTextInput,
-  LegacyHumanDecisionPrompt,
+  HumanDecisionTimeout,
+  HumanDecisionTimeoutPolicy,
   MaybePromise,
   NotifyNodeDefinition,
-  PresentedHumanDecisionPrompt,
   ShellActionExecution,
   ShellActionNodeDefinition,
   ShellActionResult,

package/src/workflows/progress.ts

@@ -18,6 +18,7 @@ export type ProgressEstimate = {
   confidence?: ProgressConfidence;
   sourceEstimatedFinishAt?: string;
   unavailableReason?: string;
+  elapsedMs?: number;
 };
 
 export type ProgressSample = {
@@ -42,7 +43,16 @@ export function estimateProgress(
   for (const sample of samples) validateProgressData(sample.data as Record<string, unknown>);
   const latest = samples.at(-1) as ProgressSample;
   const data = latest.data;
-  const base: ProgressEstimate = { key, data, sampleCount: 1 };
+  const firstAt = Date.parse(samples[0]!.at);
+  const endAt = TERMINAL.has(data.status) ? Date.parse(latest.at) : now.getTime();
+  const elapsedMs =
+    Number.isFinite(firstAt) && Number.isFinite(endAt) ? Math.max(0, endAt - firstAt) : undefined;
+  const base: ProgressEstimate = {
+    key,
+    data,
+    sampleCount: 1,
+    ...(elapsedMs !== undefined ? { elapsedMs } : {}),
+  };
   if (TERMINAL.has(data.status)) return base;
   const sourceFinish = validSourceFinish(latest, now);
   if (sourceFinish !== undefined) base.sourceEstimatedFinishAt = sourceFinish;
@@ -212,10 +222,15 @@ export function formatProgressLine(estimate: ProgressEstimate, now = new Date())
         ? `${formatRemaining(estimate.remainingLowMs)}–${formatRemaining(estimate.remainingHighMs)}`
         : formatRemaining(estimate.remainingMedianMs);
     eta = `ETA ${range}`;
-  } else if (!TERMINAL.has(data.status)) {
+  } else if (!TERMINAL.has(data.status) && data.phase === undefined) {
     eta = `ETA unavailable${estimate.unavailableReason ? ` (${estimate.unavailableReason})` : ""}`;
   }
-  return [label, count, eta].filter(Boolean).join("  ");
+  const phase = data.phase === undefined ? "" : sanitizeText(data.phase);
+  const elapsed =
+    data.phase === undefined || estimate.elapsedMs === undefined
+      ? ""
+      : `elapsed ${formatRemaining(estimate.elapsedMs)}`;
+  return [label, count, phase, elapsed, eta].filter(Boolean).join("  ");
 }
 
 export function formatProgressReport(