harnery 0.19.1 → 0.21.0

package/src/core/workflow/engine.ts

@@ -64,9 +64,11 @@ import type {
   WorkflowEvidenceRecord,
   WorkflowModule,
   WorkflowProof,
+  WorkflowWorkContext,
 } from "./types.ts";
 import { WORKFLOW_PROOF_SCHEMA_VERSION } from "./types.ts";
 import { parseStageOutput, validateAgainstSchema } from "./validate.ts";
+import { freezeWorkflowWorkContext } from "./work-context.ts";
 
 const DEFAULT_MAX_AGENTS = 50;
 const DEFAULT_CONCURRENCY = 4;
@@ -110,6 +112,19 @@ export async function runWorkflow(scriptPath: string, opts: EngineOpts): Promise
   if (opts.workItemId && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(opts.workItemId)) {
     throw new Error(`invalid work item id ${JSON.stringify(opts.workItemId)}`);
   }
+  if (opts.resumeRunId && opts.workContext !== undefined) {
+    throw new Error("parked workflow resume uses the frozen manifest work context");
+  }
+  const requestedWorkContext =
+    opts.workContext === undefined ? undefined : freezeWorkflowWorkContext(opts.workContext);
+  if (requestedWorkContext && !opts.workItemId) {
+    throw new Error("workflow work context requires a work item id");
+  }
+  if (requestedWorkContext && requestedWorkContext.id !== opts.workItemId) {
+    throw new Error(
+      `workflow work context ${requestedWorkContext.id} does not match work item ${opts.workItemId}`,
+    );
+  }
   if (opts.resumeRunId && opts.resumeFrom) {
     throw new Error("resumeRunId and resumeFrom are mutually exclusive");
   }
@@ -123,6 +138,9 @@ export async function runWorkflow(scriptPath: string, opts: EngineOpts): Promise
   ) {
     throw new Error(`workflow run ${opts.resumeRunId} belongs to a different work item`);
   }
+  const workContext = resumeState?.manifest.work_context
+    ? freezeWorkflowWorkContext(resumeState.manifest.work_context)
+    : requestedWorkContext;
   const absScript = isAbsolute(scriptPath) ? scriptPath : resolve(process.cwd(), scriptPath);
   if (resumeState) {
     if (resolve(resumeState.manifest.script.path) !== resolve(absScript)) {
@@ -139,7 +157,7 @@ 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);
+    return await executeWorkflow(scriptPath, absScript, opts, resumeState, workContext);
   } finally {
     releaseResumeLease?.();
   }
@@ -150,6 +168,7 @@ async function executeWorkflow(
   absScript: string,
   opts: EngineOpts,
   resumeState: ReturnType<typeof assertWorkflowRunResumable> | undefined,
+  workContext: Readonly<WorkflowWorkContext> | undefined,
 ): Promise<RunReport> {
   const mod = (await import(pathToFileURL(absScript).href)) as WorkflowModule;
   if (typeof mod.default !== "function") {
@@ -198,6 +217,7 @@ async function executeWorkflow(
         schema_version: 1,
         run_id: runId,
         work_item_id: opts.workItemId,
+        work_context: workContext,
         name,
         started_at: startedAt,
         script: { path: absScript, sha256: workflowScriptDigest(absScript) },
@@ -762,7 +782,15 @@ async function executeWorkflow(
     });
   };
 
-  const ctx: WorkflowContext = { agent, parallel, stage, log, evidence, authorize };
+  const ctx: WorkflowContext = {
+    work: workContext,
+    agent,
+    parallel,
+    stage,
+    log,
+    evidence,
+    authorize,
+  };
   try {
     if (resumeState) {
       journal("run.resume", {
@@ -774,6 +802,7 @@ async function executeWorkflow(
       journal("run.start", {
         name,
         work_item_id: opts.workItemId ?? null,
+        work_context: workContext ?? null,
         script: absScript,
         objective: meta.objective ?? null,
         acceptance: meta.acceptance,
@@ -800,6 +829,7 @@ async function executeWorkflow(
       proof = buildWorkflowProof({
         runId,
         workItemId: opts.workItemId ?? resumeState?.manifest.work_item_id,
+        workContext,
         meta,
         status: "succeeded",
         startedAt,
@@ -866,6 +896,7 @@ async function executeWorkflow(
       const proof = buildWorkflowProof({
         runId,
         workItemId: opts.workItemId ?? resumeState?.manifest.work_item_id,
+        workContext,
         meta,
         status: "failed",
         startedAt,

package/src/core/workflow/index.ts

@@ -71,5 +71,9 @@ export type {
   WorkflowRepoSnapshot,
   WorkflowRunStatus,
   WorkflowSpecialistProfile,
+  WorkflowWorkContext,
+} from "./types.ts";
+export {
+  WORKFLOW_PROOF_SCHEMA_VERSION,
+  WORKFLOW_WORK_CONTEXT_SCHEMA_VERSION,
 } from "./types.ts";
-export { WORKFLOW_PROOF_SCHEMA_VERSION } from "./types.ts";

package/src/core/workflow/proof.ts

@@ -34,8 +34,10 @@ import type {
   WorkflowProofUnknown,
   WorkflowRepoEvidence,
   WorkflowRepoSnapshot,
+  WorkflowWorkContext,
 } from "./types.ts";
 import { WORKFLOW_PROOF_SCHEMA_VERSION } from "./types.ts";
+import { isCanonicalWorkflowWorkContext } from "./work-context.ts";
 
 const MAX_ACCEPTANCE_CRITERIA = 50;
 const MAX_EVIDENCE_RECORDS = 200;
@@ -59,6 +61,7 @@ export interface NormalizedWorkflowMeta {
 export interface BuildWorkflowProofInput {
   runId: string;
   workItemId?: string;
+  workContext?: Readonly<WorkflowWorkContext>;
   meta: NormalizedWorkflowMeta;
   status: "succeeded" | "failed";
   startedAt: string;
@@ -221,6 +224,7 @@ export function buildWorkflowProof(input: BuildWorkflowProofInput): WorkflowProo
       started_at: input.startedAt,
       ended_at: input.endedAt,
       duration_ms: input.durationMs,
+      work_context: input.workContext,
       objective: input.meta.objective,
       error: clippedOptional(input.error, MAX_SUMMARY_CHARS),
       result: input.result === undefined ? undefined : digestResult(input.result),
@@ -303,7 +307,14 @@ export function readWorkflowProof(coordRoot: string, runId: string): WorkflowPro
   } catch (error) {
     throw new Error(`cannot parse workflow proof at ${path}: ${(error as Error).message}`);
   }
-  if (proof.schema_version !== WORKFLOW_PROOF_SCHEMA_VERSION || proof.run?.id !== runId) {
+  if (
+    proof.schema_version !== WORKFLOW_PROOF_SCHEMA_VERSION ||
+    proof.run?.id !== runId ||
+    (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)))
+  ) {
     throw new Error(`workflow proof at ${path} has an unsupported or mismatched schema`);
   }
   return proof;

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

@@ -23,7 +23,8 @@ import {
 } from "../policy/index.ts";
 import { assertWorkflowRunId, readWorkflowApproval } from "./approvals.ts";
 import { normalizeWorkflowSpecialists } from "./specialists.ts";
-import type { WorkflowSpecialistProfile } from "./types.ts";
+import type { WorkflowSpecialistProfile, WorkflowWorkContext } from "./types.ts";
+import { isCanonicalWorkflowWorkContext } from "./work-context.ts";
 
 export const WORKFLOW_RUN_MANIFEST_SCHEMA_VERSION = 1 as const;
 
@@ -34,6 +35,7 @@ export interface WorkflowRunManifest {
   schema_version: typeof WORKFLOW_RUN_MANIFEST_SCHEMA_VERSION;
   run_id: string;
   work_item_id?: string;
+  work_context?: WorkflowWorkContext;
   name: string;
   started_at: string;
   script: { path: string; sha256: string };
@@ -103,6 +105,10 @@ export function readWorkflowRunManifest(coordRoot: string, runId: string): Workf
     manifest.run_id !== runId ||
     (manifest.work_item_id !== undefined &&
       !/^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(manifest.work_item_id)) ||
+    (manifest.work_context !== undefined &&
+      (!manifest.work_item_id ||
+        manifest.work_context.id !== manifest.work_item_id ||
+        !isCanonicalWorkflowWorkContext(manifest.work_context))) ||
     typeof manifest.name !== "string" ||
     manifest.name.length === 0 ||
     manifest.name.length > 200 ||

package/src/core/workflow/types.ts

@@ -20,6 +20,7 @@ import type {
 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 type EvidenceKind = "test" | "command" | "artifact" | "change" | "review" | "observation";
 export type EvidenceStatus = "passed" | "failed" | "observed" | "unknown";
@@ -155,6 +156,7 @@ export interface WorkflowProof {
     started_at: string;
     ended_at: string;
     duration_ms: number;
+    work_context?: WorkflowWorkContext;
     objective?: string;
     error?: string;
     result?: ResultDigest;
@@ -299,6 +301,9 @@ export type Spawner = (req: SpawnRequest) => Promise<SpawnResult>;
 /** The API surface injected into a workflow script's default export. Explicit
  * injection (no ambient globals): keeps scripts portable and unit-testable. */
 export interface WorkflowContext {
+  /** Frozen durable-work assignment for work-linked runs. Standalone and
+   * legacy-resumed workflows have no work context. */
+  work?: Readonly<WorkflowWorkContext>;
   /** 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. */
@@ -326,6 +331,15 @@ export interface WorkflowModule {
   default: (ctx: WorkflowContext) => Promise<unknown>;
 }
 
+/** Minimal immutable durable-work input exposed to reusable workflow code. */
+export interface WorkflowWorkContext {
+  readonly schema_version: typeof WORKFLOW_WORK_CONTEXT_SCHEMA_VERSION;
+  readonly id: string;
+  readonly title: string;
+  readonly objective: string;
+  readonly acceptance: readonly string[];
+}
+
 export interface EngineOpts {
   /** Repo root whose .harnery/ receives the run journal. */
   coordRoot: string;
@@ -348,6 +362,9 @@ export interface EngineOpts {
   runId?: string;
   /** Durable objective this execution attempt belongs to. */
   workItemId?: string;
+  /** Frozen assignment data supplied by a durable-work host. Requires the
+   * matching `workItemId`; parked resume always uses the manifest copy. */
+  workContext?: WorkflowWorkContext;
   /** Total-agent ceiling for the run (default 50): the runaway backstop. */
   maxAgents?: number;
   /** Concurrent-subagent cap for parallel() (default 4). */

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

@@ -0,0 +1,66 @@
+import type { WorkflowWorkContext } from "./types.ts";
+import { WORKFLOW_WORK_CONTEXT_SCHEMA_VERSION } from "./types.ts";
+
+const WORK_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+const MAX_TITLE = 200;
+const MAX_OBJECTIVE = 4_000;
+const MAX_ACCEPTANCE = 50;
+const MAX_ACCEPTANCE_ITEM = 500;
+const FIELDS = new Set(["schema_version", "id", "title", "objective", "acceptance"]);
+
+export function normalizeWorkflowWorkContext(value: unknown): WorkflowWorkContext {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("workflow work context must be an object");
+  }
+  const input = value as Record<string, unknown>;
+  const extra = Object.keys(input).filter((key) => !FIELDS.has(key));
+  if (extra.length > 0) {
+    throw new Error(`workflow work context has unknown field ${JSON.stringify(extra[0])}`);
+  }
+  if (input.schema_version !== WORKFLOW_WORK_CONTEXT_SCHEMA_VERSION) {
+    throw new Error("workflow work context has an unsupported schema");
+  }
+  const id = requiredString(input.id, "workflow work context id", 100);
+  if (!WORK_ID.test(id)) {
+    throw new Error(`invalid workflow work context id ${JSON.stringify(id)}`);
+  }
+  if (!Array.isArray(input.acceptance) || input.acceptance.length > MAX_ACCEPTANCE) {
+    throw new Error(
+      `workflow work context acceptance must contain at most ${MAX_ACCEPTANCE} criteria`,
+    );
+  }
+  const acceptance = input.acceptance.map((criterion, index) =>
+    requiredString(criterion, `workflow work context acceptance[${index}]`, MAX_ACCEPTANCE_ITEM),
+  );
+  return {
+    schema_version: WORKFLOW_WORK_CONTEXT_SCHEMA_VERSION,
+    id,
+    title: requiredString(input.title, "workflow work context title", MAX_TITLE),
+    objective: requiredString(input.objective, "workflow work context objective", MAX_OBJECTIVE),
+    acceptance,
+  };
+}
+
+export function freezeWorkflowWorkContext(value: unknown): Readonly<WorkflowWorkContext> {
+  const normalized = normalizeWorkflowWorkContext(value);
+  Object.freeze(normalized.acceptance);
+  return Object.freeze(normalized);
+}
+
+export function isCanonicalWorkflowWorkContext(value: unknown): value is WorkflowWorkContext {
+  try {
+    const normalized = normalizeWorkflowWorkContext(value);
+    return JSON.stringify(normalized) === JSON.stringify(value);
+  } catch {
+    return false;
+  }
+}
+
+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;
+}