oh-my-workflow 0.1.0

package/src/runtime.ts

@@ -0,0 +1,235 @@
+// makeRuntime assembles the 5 hooks over an injected AgentPort + journal — this
+// is the whole core. The orchestration script the host agent writes is plain JS;
+// these hooks are the only surface it touches. The load-bearing invariant is the
+// null-contract: agent() NEVER throws; a terminal failure resolves to null and a
+// journal entry carrying the failure `kind`, so the authoring agent can read its
+// own failure and repair its own script. Workflow patterns (filter(Boolean),
+// abstain quorums) stand on top of that contract.
+
+import type { AgentPort, AgentResult } from "./adapters/types";
+import type { Journal } from "./journal";
+import { promptHash, optsHash } from "./journal";
+import type { ResumeIndex } from "./resume";
+import { schemaGate, makeValidator, type GateCall, type GateFeedback } from "./schema-gate";
+
+export type AgentOpts = {
+  label?: string;
+  phase?: string;
+  schema?: object;
+  model?: string;
+  cwd?: string;
+  timeoutMs?: number;
+  maxRetries?: number;
+};
+
+// `prev`/`item` are intentionally `any`: orchestration scripts are plain JS the
+// host agent authors, so a stage may declare concrete param types (`x: number`)
+// without fighting the type system. The runtime treats every value opaquely.
+export type Stage = (prev: any, item: any, index: number) => unknown | Promise<unknown>;
+
+export type Runtime = {
+  agent(prompt: string, opts?: AgentOpts): Promise<unknown | null>;
+  pipeline(items: unknown[], ...stages: Stage[]): Promise<unknown[]>;
+  parallel(thunks: Array<() => Promise<unknown>>): Promise<unknown[]>;
+  phase(title: string): void;
+  log(msg: string): void;
+};
+
+/** Bounded-concurrency gate: at most `max` bodies run at once; the rest queue.
+ *  Canonical counting-semaphore: a release HANDS its slot directly to the next
+ *  waiter (active unchanged) rather than decrementing first — otherwise a fresh
+ *  caller could slip past the `active >= max` check between the wake and the
+ *  woken waiter resuming, pushing in-flight above `max` (a TOCTOU race). */
+export function makeLimiter(max: number) {
+  let active = 0;
+  const waiters: Array<() => void> = [];
+  return async function run<T>(fn: () => Promise<T>): Promise<T> {
+    if (active >= max) {
+      await new Promise<void>((res) => waiters.push(res)); // slot transferred to us
+    } else {
+      active++;
+    }
+    try {
+      return await fn();
+    } finally {
+      const next = waiters.shift();
+      if (next) next(); // hand our slot to the next waiter; active stays the same
+      else active--;
+    }
+  };
+}
+
+const errMsg = (e: unknown): string => (e instanceof Error ? e.message : String(e));
+
+function retryPrompt(original: string, feedback: GateFeedback, fresh: boolean): string {
+  const note =
+    "Your previous output failed validation:\n" +
+    feedback.errors.map((e) => `- ${e}`).join("\n") +
+    "\nReturn ONLY corrected JSON, no prose.";
+  return fresh ? `${original}\n\n${note}` : note;
+}
+
+export function makeRuntime(deps: {
+  adapter: AgentPort;
+  journal: Journal;
+  concurrency?: number;
+  /** A prior run's journal as a lookup. When a node's (call, promptHash,
+   *  optsHash) key hits, the adapter is skipped and the cached result returned —
+   *  the longest-unchanged-prefix resume model. A miss (incl. a prior failure)
+   *  runs live, so resume only re-executes failed/changed nodes. */
+  resume?: ResumeIndex;
+}): Runtime {
+  const { adapter, journal, resume } = deps;
+  const limit = makeLimiter(deps.concurrency ?? 4);
+  let callCounter = 0;
+  let currentPhase: string | undefined;
+
+  async function agent(prompt: string, opts: AgentOpts = {}): Promise<unknown | null> {
+    const call = ++callCounter;
+    const phase = opts.phase ?? currentPhase;
+    const pHash = promptHash(prompt);
+    const oHash = optsHash(opts);
+    journal.agentStart({
+      call,
+      label: opts.label,
+      phase,
+      adapter: adapter.name,
+      promptHash: pHash,
+      optsHash: oHash,
+    });
+
+    // Resume short-circuit: a hit skips the limiter + adapter entirely, but still
+    // emits agent_end so every start has a matching end (the spine invariant).
+    if (resume) {
+      const hit = resume.lookup({ call, promptHash: pHash, optsHash: oHash });
+      if (hit.found) {
+        journal.agentEnd({ call, ok: true, result: hit.value, durationMs: 0, cached: true });
+        return hit.value;
+      }
+    }
+
+    return limit(async () => {
+      let durationMs = 0;
+      const account = (r: AgentResult) => {
+        durationMs += r.ok ? r.meta.durationMs : (r.meta?.durationMs ?? 0);
+      };
+
+      try {
+        // No schema: one shot, raw text out (or null).
+        if (!opts.schema) {
+          let r: AgentResult;
+          try {
+            r = await adapter.invoke({
+              prompt,
+              model: opts.model,
+              cwd: opts.cwd,
+              timeoutMs: opts.timeoutMs,
+            });
+          } catch (e) {
+            // A throw at the adapter boundary IS an adapter failure.
+            journal.agentEnd({ call, ok: false, kind: "spawn_failure", stderr: errMsg(e), durationMs });
+            return null;
+          }
+          account(r);
+          if (r.ok) {
+            journal.agentEnd({ call, ok: true, result: r.text, durationMs });
+            return r.text;
+          }
+          journal.agentEnd({ call, ok: false, kind: r.kind, stderr: r.stderr, durationMs });
+          return null;
+        }
+
+        // Schema path: gate retries node-level noise; followUp in-session if we
+        // have a sessionId, else fresh+error. The authoring agent never sees this.
+        const validate = makeValidator(opts.schema);
+        let lastSessionId: string | undefined;
+        const gateCall: GateCall = async (_n, feedback) => {
+          let r: AgentResult;
+          if (feedback && lastSessionId && adapter.followUp) {
+            r = await adapter.followUp(lastSessionId, retryPrompt(prompt, feedback, false));
+          } else {
+            const p = feedback ? retryPrompt(prompt, feedback, true) : prompt;
+            r = await adapter.invoke({ prompt: p, model: opts.model, cwd: opts.cwd, timeoutMs: opts.timeoutMs });
+          }
+          account(r);
+          if (r.ok && r.meta.sessionId) lastSessionId = r.meta.sessionId;
+          return r;
+        };
+
+        const outcome = await schemaGate({
+          call: gateCall,
+          validate,
+          maxRetries: opts.maxRetries,
+          onAttempt: (a) =>
+            journal.attempt({ call, n: a.n, kind: a.kind, errors: a.errors, stderr: a.stderr, rawText: a.rawText }),
+        });
+
+        if (outcome.ok) {
+          journal.agentEnd({ call, ok: true, result: outcome.value, durationMs });
+          return outcome.value;
+        }
+        journal.agentEnd({
+          call,
+          ok: false,
+          kind: outcome.kind,
+          stderr: outcome.stderr,
+          rawText: outcome.rawText,
+          durationMs,
+        });
+        return null;
+      } catch (e) {
+        // Last-resort guard: the null-contract holds even on an unexpected throw
+        // in OUR code (e.g. an invalid schema fails to compile). Labeled
+        // internal_error — distinct from adapter failures — so the authoring
+        // agent doesn't misread a schema bug as a flaky node.
+        journal.agentEnd({ call, ok: false, kind: "internal_error", error: errMsg(e), durationMs });
+        return null;
+      }
+    });
+  }
+
+  // NOTE: parallel/pipeline do NOT acquire the limiter themselves — the limiter
+  // is held at the agent() boundary (the heavy subprocess node). Wrapping these
+  // combinators too would deadlock: their thunks call agent(), which would wait
+  // for a slot the combinator already holds. Bounding cheap glue is a non-goal.
+  async function parallel(thunks: Array<() => Promise<unknown>>): Promise<unknown[]> {
+    return Promise.all(
+      thunks.map((t, i) =>
+        Promise.resolve()
+          .then(t)
+          .catch((e) => {
+            journal.log(`parallel thunk ${i} threw: ${errMsg(e)}`);
+            return null;
+          }),
+      ),
+    );
+  }
+
+  async function pipeline(items: unknown[], ...stages: Stage[]): Promise<unknown[]> {
+    return Promise.all(
+      items.map(async (item, index) => {
+        let acc: unknown = item;
+        for (const stage of stages) {
+          try {
+            acc = await stage(acc, item, index);
+          } catch (e) {
+            journal.log(`pipeline item ${index} stage threw: ${errMsg(e)}`);
+            return null;
+          }
+        }
+        return acc;
+      }),
+    );
+  }
+
+  return {
+    agent,
+    parallel,
+    pipeline,
+    phase: (title: string) => {
+      currentPhase = title;
+      journal.phase(title);
+    },
+    log: (msg: string) => journal.log(msg),
+  };
+}

package/src/schema-gate.ts

@@ -0,0 +1,164 @@
+// The schema gate turns probabilistic node output into a validated object — or
+// null. Extraction MUST be deterministic so the same text always yields the same
+// result (the journal/resume model depends on it). Precedence:
+//   1. the LAST fenced code block that parses as JSON, else
+//   2. the LARGEST balanced-brace span that parses as JSON, else
+//   3. undefined.
+
+import Ajv from "ajv";
+import type { AgentResult, AgentFailureKind } from "./adapters/types";
+
+function tryParse(s: string): unknown | undefined {
+  const t = s.trim();
+  if (!t) return undefined;
+  try {
+    return JSON.parse(t);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Top-level balanced `{...}` substrings, ignoring braces inside string literals. */
+function balancedBraceSpans(text: string): string[] {
+  const spans: string[] = [];
+  const n = text.length;
+  let i = 0;
+  while (i < n) {
+    if (text[i] !== "{") {
+      i++;
+      continue;
+    }
+    let depth = 0;
+    let inStr = false;
+    let esc = false;
+    let j = i;
+    for (; j < n; j++) {
+      const c = text[j];
+      if (inStr) {
+        if (esc) esc = false;
+        else if (c === "\\") esc = true;
+        else if (c === '"') inStr = false;
+        continue;
+      }
+      if (c === '"') inStr = true;
+      else if (c === "{") depth++;
+      else if (c === "}" && --depth === 0) break;
+    }
+    if (depth === 0 && j < n) {
+      spans.push(text.slice(i, j + 1));
+      i = j + 1;
+    } else {
+      i++; // never closed — skip this brace
+    }
+  }
+  return spans;
+}
+
+export function extractJson(text: string): unknown | undefined {
+  // 1) Fenced code blocks — last parseable wins.
+  const fences = [...text.matchAll(/```[^\n]*\n([\s\S]*?)```/g)].map((m) => m[1] ?? "");
+  for (let i = fences.length - 1; i >= 0; i--) {
+    const parsed = tryParse(fences[i] ?? "");
+    if (parsed !== undefined) return parsed;
+  }
+  // 2) Largest balanced-brace span that parses.
+  let best: { value: unknown; len: number } | undefined;
+  for (const span of balancedBraceSpans(text)) {
+    const parsed = tryParse(span);
+    if (parsed !== undefined && (best === undefined || span.length > best.len)) {
+      best = { value: parsed, len: span.length };
+    }
+  }
+  return best?.value;
+}
+
+// ── validation ──────────────────────────────────────────────────────────────
+
+export type Validation = { valid: boolean; errors: string[] };
+export type ValidateFn = (value: unknown) => Validation;
+
+/** Compile a JSON Schema into a reusable validate function (errors as strings). */
+export function makeValidator(schema: object): ValidateFn {
+  const ajv = new Ajv({ allErrors: true, strict: false });
+  const validateFn = ajv.compile(schema);
+  return (value: unknown): Validation => {
+    const valid = validateFn(value) as boolean;
+    const errors = (validateFn.errors ?? []).map(
+      (e) => `${e.instancePath || "/"} ${e.message ?? "is invalid"}`.trim(),
+    );
+    return { valid, errors };
+  };
+}
+
+// ── the retry loop ────────────────────────────────────────────────────────────
+
+/** Why a single attempt ended. "ok" plus the terminal kinds we journal. */
+export type AttemptKind = "ok" | "no_json" | "schema_violation" | AgentFailureKind;
+
+export type GateAttempt = { n: number; kind: AttemptKind; errors?: string[]; stderr?: string; rawText?: string };
+
+export type GateFeedback = { errors: string[]; rawText: string };
+
+/** Produce one node result. `n` is 1-based; `feedback` is null on the first try.
+ *  The runtime supplies this — it decides followUp (in-session) vs fresh+error. */
+export type GateCall = (n: number, feedback: GateFeedback | null) => Promise<AgentResult>;
+
+export type GateOutcome =
+  | { ok: true; value: unknown }
+  // On failure we carry the diagnostic payload up so the runtime can journal it:
+  // adapter stderr for hard failures, the node's raw text for schema/no_json.
+  | { ok: false; kind: Exclude<AttemptKind, "ok">; stderr?: string; rawText?: string };
+
+/**
+ * Run a node through the gate. Schema noise (no_json / schema_violation) is
+ * retried up to `maxRetries` times; a hard adapter failure short-circuits with
+ * its own kind. NEVER throws — exhaustion or error resolves to { ok:false }.
+ */
+export async function schemaGate(opts: {
+  call: GateCall;
+  validate: ValidateFn;
+  maxRetries?: number;
+  onAttempt?: (a: GateAttempt) => void;
+}): Promise<GateOutcome> {
+  const maxRetries = opts.maxRetries ?? 2;
+  let feedback: GateFeedback | null = null;
+  let lastKind: Exclude<AttemptKind, "ok"> = "schema_violation";
+  let lastRawText: string | undefined;
+
+  for (let n = 1; n <= maxRetries + 1; n++) {
+    let result: AgentResult;
+    try {
+      result = await opts.call(n, feedback);
+    } catch {
+      opts.onAttempt?.({ n, kind: "spawn_failure" });
+      return { ok: false, kind: "spawn_failure" };
+    }
+
+    if (!result.ok) {
+      // Adapter-level failure is not schema noise — short-circuit, keep stderr.
+      opts.onAttempt?.({ n, kind: result.kind, stderr: result.stderr });
+      return { ok: false, kind: result.kind, stderr: result.stderr };
+    }
+
+    lastRawText = result.text;
+    const extracted = extractJson(result.text);
+    if (extracted === undefined) {
+      lastKind = "no_json";
+      opts.onAttempt?.({ n, kind: "no_json", rawText: result.text });
+      feedback = { errors: ["output contained no extractable JSON"], rawText: result.text };
+      continue;
+    }
+
+    const { valid, errors } = opts.validate(extracted);
+    if (valid) {
+      opts.onAttempt?.({ n, kind: "ok" });
+      return { ok: true, value: extracted };
+    }
+
+    lastKind = "schema_violation";
+    opts.onAttempt?.({ n, kind: "schema_violation", errors, rawText: result.text });
+    feedback = { errors, rawText: result.text };
+  }
+
+  return { ok: false, kind: lastKind, rawText: lastRawText };
+}