harnery 0.14.0 → 0.15.0

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;
 
@@ -48,6 +50,7 @@ export interface WorkflowRunManifest {
     isolation: PolicyIsolation;
     network_access: PolicyNetworkAccess;
     policy?: NormalizedPolicy;
+    specialists?: Record<string, WorkflowSpecialistProfile>;
   };
 }
 
@@ -253,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";
@@ -210,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. */
@@ -239,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;
@@ -309,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. */