harnery 0.21.0 → 0.22.0

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). */