harnery 0.13.0 → 0.15.0

package/src/core/workflow/engine.ts

@@ -35,7 +35,7 @@ import {
   policyDigest,
   summarizePolicyRequest,
 } from "../policy/index.ts";
-import { createWorkflowApproval } from "./approvals.ts";
+import { assertWorkflowRunId, createWorkflowApproval } from "./approvals.ts";
 import { type BillingProbe, probeBilling } from "./billing.ts";
 import {
   buildWorkflowProof,
@@ -51,6 +51,7 @@ import {
   workflowScriptDigest,
   writeWorkflowRunManifest,
 } from "./run-state.ts";
+import { normalizeWorkflowSpecialists, resolveSpecialistAssignment } from "./specialists.ts";
 import type {
   AgentOpts,
   EngineOpts,
@@ -101,12 +102,26 @@ export class WorkflowParkedError extends Error {
 }
 
 export async function runWorkflow(scriptPath: string, opts: EngineOpts): Promise<RunReport> {
+  if (opts.runId && opts.resumeRunId) {
+    throw new Error("runId and resumeRunId are mutually exclusive");
+  }
+  if (opts.runId) assertWorkflowRunId(opts.runId);
+  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.resumeFrom) {
     throw new Error("resumeRunId and resumeFrom are mutually exclusive");
   }
   const resumeState = opts.resumeRunId
     ? assertWorkflowRunResumable(opts.coordRoot, opts.resumeRunId)
     : undefined;
+  if (
+    resumeState !== undefined &&
+    opts.workItemId !== undefined &&
+    resumeState.manifest.work_item_id !== opts.workItemId
+  ) {
+    throw new Error(`workflow run ${opts.resumeRunId} belongs to a different work item`);
+  }
   const absScript = isAbsolute(scriptPath) ? scriptPath : resolve(process.cwd(), scriptPath);
   if (resumeState) {
     if (resolve(resumeState.manifest.script.path) !== resolve(absScript)) {
@@ -145,6 +160,7 @@ async function executeWorkflow(
 
   const runId =
     opts.resumeRunId ??
+    opts.runId ??
     `wf-${new Date().toISOString().replace(/[:.]/g, "-")}-${randomBytes(3).toString("hex")}`;
   const runDir = join(opts.coordRoot, ".harnery", "workflows", runId);
   mkdirSync(runDir, { recursive: true });
@@ -160,6 +176,8 @@ async function executeWorkflow(
   const log = opts.onLog ?? ((line: string) => process.stderr.write(`${line}\n`));
   const defaultHarness: HarnessName =
     frozen?.default_harness ?? opts.defaultHarness ?? "claude-code";
+  const specialists =
+    frozen?.specialists ?? (resumeState ? {} : normalizeWorkflowSpecialists(opts.specialists));
   const isolation = frozen?.isolation ?? opts.isolation ?? "shared";
   const networkAccess = frozen?.network_access ?? opts.networkAccess ?? "unknown";
   const policy =
@@ -178,6 +196,7 @@ async function executeWorkflow(
       manifest: {
         schema_version: 1,
         run_id: runId,
+        work_item_id: opts.workItemId,
         name,
         started_at: startedAt,
         script: { path: absScript, sha256: workflowScriptDigest(absScript) },
@@ -194,6 +213,7 @@ async function executeWorkflow(
           isolation,
           network_access: networkAccess,
           policy: policy ? (policy as NormalizedPolicy) : undefined,
+          specialists,
         },
       },
     });
@@ -399,7 +419,10 @@ async function executeWorkflow(
     return decision;
   };
 
-  const agent = async (prompt: string, agentOpts: AgentOpts = {}): Promise<unknown> => {
+  const agent = async (prompt: string, requestedOpts: AgentOpts = {}): Promise<unknown> => {
+    const assignment = resolveSpecialistAssignment(specialists, prompt, requestedOpts);
+    const agentOpts = assignment.opts;
+    const assignmentPrompt = assignment.prompt;
     let reservedForDispatch = 0;
     let spawnCountClaimed = false;
     const harness = agentOpts.harness ?? defaultHarness;
@@ -417,6 +440,7 @@ async function executeWorkflow(
       id,
       label: proofLabel,
       stage: currentStage || undefined,
+      specialist: agentOpts.specialist,
       harness,
       model: agentOpts.model,
       status: "failed",
@@ -427,7 +451,7 @@ async function executeWorkflow(
 
     // Call identity for resume: same stage + harness + model + effort + turns + schema
     // + ORIGINAL prompt → same key. Retry-mutated prompts never enter the key.
-    const key = agentCallKey(currentStage, harness, agentOpts, prompt);
+    const key = agentCallKey(currentStage, harness, agentOpts, assignmentPrompt);
     const cached = resumeCache.get(key);
     if (cached) {
       // Exact-run replay skips dispatch authorization because no dispatch
@@ -442,6 +466,7 @@ async function executeWorkflow(
         label,
         key,
         harness,
+        specialist: agentOpts.specialist ?? null,
         model: agentOpts.model ?? null,
         kind: cached.kind,
       });
@@ -462,7 +487,7 @@ async function executeWorkflow(
         max_attempts: maxAttempts,
         max_turns: agentOpts.maxTurns ?? DEFAULT_MAX_TURNS,
         timeout_ms: agentOpts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-        prompt_bytes: Buffer.byteLength(prompt),
+        prompt_bytes: Buffer.byteLength(assignmentPrompt),
         isolation,
         network_access: networkAccess,
         current_cost_usd: round4(costUsd + reservedCostUsd),
@@ -578,12 +603,13 @@ async function executeWorkflow(
         label,
         key,
         harness,
+        specialist: agentOpts.specialist ?? null,
         model: agentOpts.model ?? null,
         effort: agentOpts.effort ?? null,
       });
       log(`[${name}] ${currentStage || "(no stage)"} → ${id} [${harness}] ${label}`);
 
-      let attemptPrompt = prompt;
+      let attemptPrompt = assignmentPrompt;
       let last: SpawnResult | null = null;
       let agentCostUsd = 0;
       for (let attempt = 1; attempt <= maxAttempts; attempt++) {
@@ -655,7 +681,7 @@ async function executeWorkflow(
         // Feed the validation failure back verbatim — the retry prompt carries
         // exactly what was wrong, which is what makes bounded retry converge.
         attemptPrompt =
-          `${prompt}\n\nYour previous reply failed validation:\n` +
+          `${assignmentPrompt}\n\nYour previous reply failed validation:\n` +
           `${problems.map((p) => `  - ${p}`).join("\n")}\n` +
           `Reply with ONLY the corrected JSON object. No prose, no code fences.`;
       }
@@ -739,11 +765,13 @@ async function executeWorkflow(
     } else {
       journal("run.start", {
         name,
+        work_item_id: opts.workItemId ?? null,
         script: absScript,
         objective: meta.objective ?? null,
         acceptance: meta.acceptance,
         max_agents: maxAgents,
         concurrency,
+        specialists: Object.keys(specialists),
         policy: policy ? { name: policy.name, sha256: policyDigest(policy) } : null,
         isolation,
         network_access: networkAccess,
@@ -763,6 +791,7 @@ async function executeWorkflow(
     try {
       proof = buildWorkflowProof({
         runId,
+        workItemId: opts.workItemId ?? resumeState?.manifest.work_item_id,
         meta,
         status: "succeeded",
         startedAt,
@@ -795,6 +824,7 @@ async function executeWorkflow(
     }
     const report: RunReport = {
       runId,
+      workItemId: opts.workItemId ?? resumeState?.manifest.work_item_id,
       name,
       result,
       agentsSpawned,
@@ -827,6 +857,7 @@ async function executeWorkflow(
     try {
       const proof = buildWorkflowProof({
         runId,
+        workItemId: opts.workItemId ?? resumeState?.manifest.work_item_id,
         meta,
         status: "failed",
         startedAt,
@@ -869,15 +900,17 @@ function agentCallKey(
   agentOpts: AgentOpts,
   prompt: string,
 ): string {
-  const basis = JSON.stringify([
+  const parts: unknown[] = [
     stage,
     harness,
     agentOpts.model ?? null,
     agentOpts.effort ?? null,
     agentOpts.maxTurns ?? DEFAULT_MAX_TURNS,
     agentOpts.schema ?? null,
-    prompt,
-  ]);
+  ];
+  if (agentOpts.specialist) parts.push(agentOpts.specialist);
+  parts.push(prompt);
+  const basis = JSON.stringify(parts);
   return createHash("sha256").update(basis).digest("hex").slice(0, 16);
 }
 

package/src/core/workflow/index.ts

@@ -70,5 +70,6 @@ export type {
   WorkflowRepoEvidence,
   WorkflowRepoSnapshot,
   WorkflowRunStatus,
+  WorkflowSpecialistProfile,
 } from "./types.ts";
 export { WORKFLOW_PROOF_SCHEMA_VERSION } from "./types.ts";

package/src/core/workflow/proof.ts

@@ -58,6 +58,7 @@ export interface NormalizedWorkflowMeta {
 
 export interface BuildWorkflowProofInput {
   runId: string;
+  workItemId?: string;
   meta: NormalizedWorkflowMeta;
   status: "succeeded" | "failed";
   startedAt: string;
@@ -202,6 +203,7 @@ export function buildWorkflowProof(input: BuildWorkflowProofInput): WorkflowProo
   const agents = input.agents.map((agent) => ({
     ...agent,
     label: clipped(agent.label, MAX_LABEL_CHARS),
+    specialist: clippedOptional(agent.specialist, MAX_LABEL_CHARS),
     model: clippedOptional(agent.model, MAX_LABEL_CHARS),
     session_id: clippedOptional(agent.session_id, MAX_REF_CHARS),
     error: clippedOptional(agent.error, MAX_SUMMARY_CHARS),
@@ -213,6 +215,7 @@ export function buildWorkflowProof(input: BuildWorkflowProofInput): WorkflowProo
     schema_version: WORKFLOW_PROOF_SCHEMA_VERSION,
     run: {
       id: input.runId,
+      work_item_id: input.workItemId,
       name: input.meta.name,
       status: input.status,
       started_at: input.startedAt,

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

@@ -22,6 +22,8 @@ import {
   policyDigest,
 } from "../policy/index.ts";
 import { assertWorkflowRunId, readWorkflowApproval } from "./approvals.ts";
+import { normalizeWorkflowSpecialists } from "./specialists.ts";
+import type { WorkflowSpecialistProfile } from "./types.ts";
 
 export const WORKFLOW_RUN_MANIFEST_SCHEMA_VERSION = 1 as const;
 
@@ -31,6 +33,7 @@ const FOREIGN_LEASE_STALE_MS = 24 * 60 * 60 * 1_000;
 export interface WorkflowRunManifest {
   schema_version: typeof WORKFLOW_RUN_MANIFEST_SCHEMA_VERSION;
   run_id: string;
+  work_item_id?: string;
   name: string;
   started_at: string;
   script: { path: string; sha256: string };
@@ -47,6 +50,7 @@ export interface WorkflowRunManifest {
     isolation: PolicyIsolation;
     network_access: PolicyNetworkAccess;
     policy?: NormalizedPolicy;
+    specialists?: Record<string, WorkflowSpecialistProfile>;
   };
 }
 
@@ -97,6 +101,8 @@ export function readWorkflowRunManifest(coordRoot: string, runId: string): Workf
   if (
     manifest.schema_version !== WORKFLOW_RUN_MANIFEST_SCHEMA_VERSION ||
     manifest.run_id !== runId ||
+    (manifest.work_item_id !== undefined &&
+      !/^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(manifest.work_item_id)) ||
     typeof manifest.name !== "string" ||
     manifest.name.length === 0 ||
     manifest.name.length > 200 ||
@@ -250,10 +256,24 @@ function validExecution(value: WorkflowRunManifest["execution"]): boolean {
     value.approval_addressee.length <= 200 &&
     ["shared", "worktree", "sandbox", "remote"].includes(value.isolation) &&
     ["enabled", "disabled", "unknown"].includes(value.network_access) &&
+    validSpecialists(value.specialists) &&
     validFrozenPolicy(value.policy, value.cwd)
   );
 }
 
+function validSpecialists(
+  specialists: Record<string, WorkflowSpecialistProfile> | undefined,
+): boolean {
+  if (specialists === undefined) return true;
+  try {
+    return (
+      JSON.stringify(normalizeWorkflowSpecialists(specialists)) === JSON.stringify(specialists)
+    );
+  } catch {
+    return false;
+  }
+}
+
 function validFrozenPolicy(policy: NormalizedPolicy | undefined, cwd: string): boolean {
   if (policy === undefined) return true;
   try {

package/src/core/workflow/specialists.ts

@@ -0,0 +1,97 @@
+import type { AgentOpts, WorkflowSpecialistProfile } from "./types.ts";
+
+const SPECIALIST_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const MAX_SPECIALISTS = 32;
+const MAX_INSTRUCTIONS = 4_000;
+const MAX_OPTION = 200;
+
+export function normalizeWorkflowSpecialists(
+  input: Readonly<Record<string, WorkflowSpecialistProfile>> | undefined,
+): Record<string, WorkflowSpecialistProfile> {
+  if (input === undefined) return {};
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("workflow specialists must be an object keyed by role id");
+  }
+  const entries = Object.entries(input);
+  if (entries.length > MAX_SPECIALISTS) {
+    throw new Error(`workflow specialists exceed ${MAX_SPECIALISTS} roles`);
+  }
+  const normalized: Record<string, WorkflowSpecialistProfile> = {};
+  for (const [id, profile] of entries.sort(([left], [right]) => left.localeCompare(right))) {
+    if (!SPECIALIST_ID.test(id))
+      throw new Error(`invalid workflow specialist id ${JSON.stringify(id)}`);
+    if (!profile || typeof profile !== "object" || Array.isArray(profile)) {
+      throw new Error(`workflow specialist ${id} must be an object`);
+    }
+    normalized[id] = {
+      instructions: bounded(
+        profile.instructions,
+        `workflow specialist ${id} instructions`,
+        MAX_INSTRUCTIONS,
+      ),
+      harness: optional(profile.harness, `workflow specialist ${id} harness`),
+      model: optional(profile.model, `workflow specialist ${id} model`),
+      effort: optional(profile.effort, `workflow specialist ${id} effort`),
+      maxAttempts: positiveOptional(
+        profile.maxAttempts,
+        `workflow specialist ${id} maxAttempts`,
+        10,
+      ),
+      timeoutMs: positiveOptional(
+        profile.timeoutMs,
+        `workflow specialist ${id} timeoutMs`,
+        24 * 60 * 60 * 1_000,
+      ),
+      maxTurns: positiveOptional(profile.maxTurns, `workflow specialist ${id} maxTurns`, 1_000),
+    };
+  }
+  return normalized;
+}
+
+export function resolveSpecialistAssignment(
+  profiles: Readonly<Record<string, WorkflowSpecialistProfile>>,
+  prompt: string,
+  opts: AgentOpts,
+): { prompt: string; opts: AgentOpts } {
+  if (!opts.specialist) return { prompt, opts };
+  if (!SPECIALIST_ID.test(opts.specialist)) {
+    throw new Error(`invalid workflow specialist id ${JSON.stringify(opts.specialist)}`);
+  }
+  const profile = profiles[opts.specialist];
+  if (!profile)
+    throw new Error(`workflow specialist ${JSON.stringify(opts.specialist)} is not configured`);
+  return {
+    prompt: `${profile.instructions}\n\nAssignment:\n${prompt}`,
+    opts: {
+      specialist: opts.specialist,
+      harness: opts.harness ?? profile.harness,
+      model: opts.model ?? profile.model,
+      effort: opts.effort ?? profile.effort,
+      maxAttempts: opts.maxAttempts ?? profile.maxAttempts,
+      timeoutMs: opts.timeoutMs ?? profile.timeoutMs,
+      maxTurns: opts.maxTurns ?? profile.maxTurns,
+      label: opts.label,
+      schema: opts.schema,
+    },
+  };
+}
+
+function bounded(value: unknown, field: string, max: number): string {
+  if (typeof value !== "string") throw new Error(`${field} must be a string`);
+  const normalized = value.trim();
+  if (!normalized) throw new Error(`${field} must not be empty`);
+  if (normalized.length > max) throw new Error(`${field} exceeds ${max} characters`);
+  return normalized;
+}
+
+function optional(value: unknown, field: string): string | undefined {
+  return value === undefined ? undefined : bounded(value, field, MAX_OPTION);
+}
+
+function positiveOptional(value: unknown, field: string, max: number): number | undefined {
+  if (value === undefined) return undefined;
+  if (!Number.isSafeInteger(value) || (value as number) < 1 || (value as number) > max) {
+    throw new Error(`${field} must be an integer from 1 to ${max}`);
+  }
+  return value as number;
+}

package/src/core/workflow/types.ts

@@ -82,6 +82,7 @@ export interface WorkflowAgentProof {
   id: string;
   label: string;
   stage?: string;
+  specialist?: string;
   harness: HarnessName;
   model?: string;
   status: "succeeded" | "failed" | "cached";
@@ -147,6 +148,8 @@ export interface WorkflowProof {
   schema_version: typeof WORKFLOW_PROOF_SCHEMA_VERSION;
   run: {
     id: string;
+    /** Durable objective this execution attempt belongs to, when linked. */
+    work_item_id?: string;
     name: string;
     status: WorkflowRunStatus;
     started_at: string;
@@ -208,6 +211,9 @@ export interface StageSchema {
 }
 
 export interface AgentOpts {
+  /** Frozen specialist profile whose instructions and defaults wrap this
+   * assignment. The host supplies profiles through EngineOpts.specialists. */
+  specialist?: string;
   /** Stage gate: when present, the agent's reply must strict-parse as JSON and
    * validate; the engine retries with the validation error appended, up to
    * `maxAttempts`. Without it, `agent()` resolves to the raw reply text. */
@@ -237,6 +243,18 @@ export interface AgentOpts {
  * a package-owned union first. */
 export type HarnessName = string;
 
+/** Durable role defaults supplied by a goal supervisor or embedding host.
+ * Profiles are frozen into a workflow run manifest before the first spawn. */
+export interface WorkflowSpecialistProfile {
+  instructions: string;
+  harness?: HarnessName;
+  model?: string;
+  effort?: string;
+  maxAttempts?: number;
+  timeoutMs?: number;
+  maxTurns?: number;
+}
+
 /** What a spawn adapter returns for one subagent run. */
 export interface SpawnResult {
   ok: boolean;
@@ -307,6 +325,8 @@ export interface EngineOpts {
   spawners: Readonly<Record<HarnessName, Spawner | undefined>>;
   /** Harness used when an agent() call doesn't name one (default "claude-code"). */
   defaultHarness?: HarnessName;
+  /** Named specialist roles available to agent(..., { specialist }). */
+  specialists?: Readonly<Record<string, WorkflowSpecialistProfile>>;
   /** Resume: run id of a prior run whose journal supplies cached results.
    * agent() calls whose (stage, prompt, model, maxTurns, schema) key matches a
    * completed prior agent return the journaled result without spawning. */
@@ -315,6 +335,10 @@ export interface EngineOpts {
    * approval has been resolved. The frozen run manifest supplies execution
    * options and the original repository-before snapshot. */
   resumeRunId?: string;
+  /** Stable id for a new run allocated by a durable-work host. */
+  runId?: string;
+  /** Durable objective this execution attempt belongs to. */
+  workItemId?: string;
   /** Total-agent ceiling for the run (default 50): the runaway backstop. */
   maxAgents?: number;
   /** Concurrent-subagent cap for parallel() (default 4). */
@@ -357,6 +381,7 @@ export interface EngineOpts {
 
 export interface RunReport {
   runId: string;
+  workItemId?: string;
   name: string;
   /** What the script's default export returned. */
   result: unknown;