@getpipher/armory-fleet 0.11.0 → 0.12.0

package/src/workflows/runtime/hydrate.ts

@@ -0,0 +1,116 @@
+// SPEC-6-3 §8 — journal hydration. On session start, reconstruct terminal + interrupted
+// run rows from journal files so the store reflects historical state after a restart.
+import { readdirSync, existsSync } from "node:fs"
+import { join } from "node:path"
+
+import type { WorkflowJournal, WorkflowJournalEvent } from "../journal.ts"
+import type { WorkflowRunStore } from "./run-store.ts"
+import type { WorkflowRunState } from "./types.ts"
+
+export function hydrateWorkflowRuns(
+  journal: WorkflowJournal,
+  store: WorkflowRunStore,
+): void {
+  const dir = (journal as unknown as { dir: string }).dir
+  if (!existsSync(dir)) return
+
+  for (const f of readdirSync(dir)) {
+    if (!f.endsWith(".jsonl")) continue
+    const runId = f.slice(0, -".jsonl".length)
+    const events = journal.replay(runId)
+    if (events.length === 0) continue
+
+    const state = buildStateFromEvents(runId, events)
+    if (state) store.set(runId, state)
+  }
+}
+
+function buildStateFromEvents(
+  runId: string,
+  events: WorkflowJournalEvent[],
+): WorkflowRunState | undefined {
+  let startedEvent: Extract<WorkflowJournalEvent, { type: "wf:started" }> | undefined
+  let lastProgress: Extract<WorkflowJournalEvent, { type: "wf:progress" }> | undefined
+  let terminalEvent:
+    | Extract<WorkflowJournalEvent, { type: "wf:completed" }>
+    | Extract<WorkflowJournalEvent, { type: "wf:aborted" }>
+    | undefined
+
+  for (const e of events) {
+    if (e.type === "wf:started") {
+      startedEvent = e
+    } else if (e.type === "wf:progress") {
+      lastProgress = e
+    } else if (e.type === "wf:completed" || e.type === "wf:aborted") {
+      terminalEvent = e
+    }
+  }
+
+  if (!startedEvent) return undefined
+
+  const script = startedEvent.script
+  const mode = startedEvent.mode
+  const startedAt = startedEvent.ts
+
+  // Base fields from the latest progress snapshot (if any).
+  const currentPhase = lastProgress?.currentPhase ?? "default"
+  const phases = lastProgress?.phases ?? []
+  const childRunIds = lastProgress?.childRunIds ?? []
+  const logs = lastProgress?.logs ?? []
+  const tokenTotal = lastProgress?.tokenTotal ?? 0
+  const costTotal = lastProgress?.costTotal ?? 0
+
+  if (terminalEvent) {
+    if (terminalEvent.type === "wf:completed") {
+      return {
+        runId,
+        name: runId,
+        script,
+        mode,
+        status: "completed",
+        startedAt,
+        endedAt: terminalEvent.ts,
+        currentPhase,
+        phases,
+        childRunIds,
+        logs,
+        tokenTotal: terminalEvent.tokenTotal ?? tokenTotal,
+        costTotal: terminalEvent.costTotal ?? costTotal,
+        ...(terminalEvent.result !== undefined ? { result: terminalEvent.result } : {}),
+      }
+    }
+    // wf:aborted
+    return {
+      runId,
+      name: runId,
+      script,
+      mode,
+      status: "aborted",
+      startedAt,
+      endedAt: terminalEvent.ts,
+      currentPhase,
+      phases,
+      childRunIds,
+      logs,
+      tokenTotal,
+      costTotal,
+      error: terminalEvent.reason,
+    }
+  }
+
+  // Non-terminal: interrupted.
+  return {
+    runId,
+    name: runId,
+    script,
+    mode,
+    status: "interrupted",
+    startedAt,
+    currentPhase,
+    phases,
+    childRunIds,
+    logs,
+    tokenTotal,
+    costTotal,
+  }
+}

package/src/workflows/runtime/pause-gate.ts

@@ -0,0 +1,41 @@
+// SPEC-6-3 cooperative pause gate — blocks new work when paused, releases all waiters on resume,
+// rejects waiters on abort signal.
+
+export class PauseGate {
+  private paused = false;
+  private readonly waiters = new Set<() => void>();
+
+  pause(): void {
+    this.paused = true;
+  }
+
+  resume(): void {
+    this.paused = false;
+    const toRelease = [...this.waiters];
+    this.waiters.clear();
+    for (const resolve of toRelease) resolve();
+  }
+
+  isPaused(): boolean {
+    return this.paused;
+  }
+
+  wait(signal: AbortSignal): Promise<void> {
+    if (!this.paused) return Promise.resolve();
+
+    return new Promise<void>((resolve, reject) => {
+      const onAbort = () => {
+        this.waiters.delete(resolve);
+        reject(signal.reason);
+      };
+
+      const resolveFn = () => {
+        signal.removeEventListener("abort", onAbort, { once: true } as EventListenerOptions);
+        resolve();
+      };
+
+      this.waiters.add(resolveFn);
+      signal.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+}

package/src/workflows/runtime/run-store.ts

@@ -0,0 +1,31 @@
+// SPEC-6-3 reactive run store — mirrors BgRunsStore pattern (private Map + listener Set)
+// but values() returns newest-first by startedAt for panel ordering.
+
+import type { WorkflowRunState } from "./types.ts";
+
+export type WorkflowRunChangeListener = (runId: string) => void;
+
+export class WorkflowRunStore {
+  private readonly runs = new Map<string, WorkflowRunState>();
+  private readonly listeners = new Set<WorkflowRunChangeListener>();
+
+  set(runId: string, state: WorkflowRunState): void {
+    this.runs.set(runId, state);
+    for (const fn of this.listeners) fn(runId);
+  }
+
+  get(runId: string): WorkflowRunState | undefined {
+    return this.runs.get(runId);
+  }
+
+  values(): WorkflowRunState[] {
+    return [...this.runs.values()].sort((a, b) => b.startedAt - a.startedAt);
+  }
+
+  subscribe(listener: WorkflowRunChangeListener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+}

package/src/workflows/runtime/save.ts

@@ -0,0 +1,111 @@
+// SPEC-6-3 §6 — atomic workflow save with an injectable fs port for deterministic failure tests.
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+  writeSync,
+} from "node:fs"
+import { join } from "node:path"
+import { randomBytes } from "node:crypto"
+
+import { parseWorkflowSource, validateWorkflowName } from "../source.ts"
+import type { WorkflowDef, WorkflowSource } from "../registry.ts"
+
+export interface SaveFs {
+  existsSync(path: string): boolean
+  mkdirSync(path: string, opts: { recursive: boolean }): void
+  openSync(path: string, flags: string): number
+  writeSync(fd: number, data: string): number
+  closeSync(fd: number): void
+  renameSync(oldPath: string, newPath: string): void
+  unlinkSync(path: string): void
+  readdirSync(path: string): string[]
+  readFileSync(path: string, encoding: string): string
+  writeFileSync(path: string, data: string, encoding: string): void
+}
+
+export const NODE_SAVE_FS: SaveFs = {
+  existsSync,
+  mkdirSync: (p, o) => mkdirSync(p, o),
+  openSync,
+  writeSync,
+  closeSync,
+  renameSync,
+  unlinkSync,
+  readdirSync,
+  readFileSync: (p, enc) => readFileSync(p, enc as BufferEncoding),
+  writeFileSync: (p, data, enc) => writeFileSync(p, data, enc as BufferEncoding),
+}
+
+export interface SaveInput {
+  name: string
+  source: string
+  overwrite?: boolean
+  /** Target directory for the workflow file. Defaults to process.cwd(). */
+  dir?: string
+}
+
+export function saveWorkflowAtomic(input: SaveInput, fsOps: SaveFs = NODE_SAVE_FS): WorkflowDef {
+  validateWorkflowName(input.name)
+
+  const filePath = `${input.name}.js`
+  const parsed = parseWorkflowSource(input.source, { filePath, requireMeta: true })
+  if (!parsed.meta) throw new Error(`${filePath}: missing meta`)
+  if (parsed.meta.name !== input.name) {
+    throw new Error(`meta.name '${parsed.meta.name}' does not match save name '${input.name}'`)
+  }
+
+  const targetDir = input.dir ?? process.cwd()
+  const targetPath = join(targetDir, filePath)
+
+  fsOps.mkdirSync(targetDir, { recursive: true })
+
+  if (fsOps.existsSync(targetPath) && !input.overwrite) {
+    throw new Error(`workflow '${input.name}' already exists; set overwrite:true to replace`)
+  }
+
+  const nonce = randomBytes(6).toString("hex")
+  const tempName = `.${input.name}.tmp-${process.pid}-${nonce}`
+  const tempPath = join(targetDir, tempName)
+
+  let fd: number | undefined
+  try {
+    fd = fsOps.openSync(tempPath, "w")
+    fsOps.writeSync(fd, input.source)
+    fsOps.closeSync(fd)
+    fd = undefined
+    fsOps.renameSync(tempPath, targetPath)
+  } catch (e) {
+    if (fd !== undefined) {
+      try {
+        fsOps.closeSync(fd)
+      } catch {
+        // best-effort
+      }
+    }
+    try {
+      fsOps.unlinkSync(tempPath)
+    } catch {
+      // best-effort — never mask the original error
+    }
+    throw e
+  }
+
+  const source: WorkflowSource = "project"
+  return {
+    name: parsed.meta.name,
+    description: parsed.meta.description,
+    phases: parsed.meta.phases,
+    sourceText: parsed.source,
+    body: parsed.body,
+    executable: parsed.executable,
+    source,
+    filePath: targetPath,
+  }
+}

package/src/workflows/runtime/types.ts

@@ -0,0 +1,78 @@
+// SPEC-6-3 runtime types — public state shapes consumed by the runner, store, panel, and later tasks.
+
+export type WorkflowStatus =
+  | "queued"
+  | "running"
+  | "paused"
+  | "checkpoint"
+  | "completed"
+  | "failed"
+  | "aborted"
+  | "interrupted";
+
+export interface WorkflowRunState {
+  runId: string;
+  name: string;
+  script: string;
+  args?: unknown;
+  mode: "auto" | "checkpointed";
+  status: WorkflowStatus;
+  startedAt: number;
+  endedAt?: number;
+  currentPhase: string;
+  phases: Array<{ title: string; agents: number; cached: number; reRun: number }>;
+  childRunIds: string[];
+  logs: string[];
+  tokenTotal: number;
+  costTotal: number;
+  result?: unknown;
+  error?: string;
+  resumeFromRunId?: string;
+  checkpoint?: { prompt: string; opts: Record<string, unknown> };
+}
+
+export interface WorkflowProgressEvent {
+  kind:
+    | "started"
+    | "phase"
+    | "child-started"
+    | "child-completed"
+    | "child-failed"
+    | "helper-started"
+    | "helper-completed"
+    | "log"
+    | "checkpoint"
+    | "checkpoint-resolved"
+    | "completed"
+    | "failed"
+    | "aborted";
+  runId: string;
+  snapshot: WorkflowRunState;
+}
+
+export interface WorkflowStartInput {
+  script?: string;
+  workflowName?: string;
+  name?: string;
+  overwrite?: boolean;
+  args?: unknown;
+  mode: "auto" | "checkpointed";
+  background?: boolean;
+  resumeFromRunId?: string;
+  maxAgents?: number;
+  concurrency?: number;
+  agentRetries?: number;
+  agentTimeoutMs?: number;
+  tokenBudget?: number;
+}
+
+export interface WorkflowStartReceipt {
+  runId: string;
+  status: "background";
+}
+
+export interface WorkflowSaveInput {
+  name: string;
+  source: string;
+  overwrite?: boolean;
+}

package/src/workflows/source.ts

@@ -0,0 +1,156 @@
+// SPEC-6-3 §3.1 — canonical workflow source parser. Extracts `export const meta = {…}`
+// via a balanced-brace scanner (the old non-greedy regex broke on nested braces / multi-line),
+// retains the editable sourceText + stripped body, and normalizes an executable string
+// that the vm realm can compile as CommonJS.
+
+export interface WorkflowMeta {
+  name: string;
+  description: string;
+  phases: { title: string }[];
+}
+
+export interface ParsedWorkflowSource {
+  meta?: WorkflowMeta;
+  source: string;
+  body: string;
+  executable: string;
+}
+
+const META_MARKER = "export const meta =";
+
+const NAME_RE = /^[a-z][a-z0-9-]{0,63}$/;
+
+const WINDOWS_RESERVED = new Set<string>([
+  "con", "prn", "aux", "nul",
+  ...Array.from({ length: 9 }, (_, i) => `com${i + 1}`),
+  ...Array.from({ length: 9 }, (_, i) => `lpt${i + 1}`),
+]);
+
+/**
+ * Validate a workflow save name. Must be kebab-case (`^[a-z][a-z0-9-]{0,63}$`).
+ * Rejects Windows device names (con, prn, aux, nul, com1–9, lpt1–9) and any path traversal.
+ */
+export function validateWorkflowName(name: string): void {
+  if (!NAME_RE.test(name) || WINDOWS_RESERVED.has(name.toLowerCase())) {
+    throw new Error(`invalid workflow name: '${name}'`);
+  }
+}
+
+/**
+ * Scan a balanced `{…}` object starting at `start` (which must point at the opening brace).
+ * Ignores braces inside single/double/backtick quoted strings. Returns the raw text including
+ * the outer braces, or `null` if unbalanced.
+ */
+function extractBalancedBraces(source: string, start: number): string | null {
+  let depth = 0;
+  let inSingle = false;
+  let inDouble = false;
+  let inBacktick = false;
+
+  for (let i = start; i < source.length; i++) {
+    const ch = source[i]!;
+
+    if (inSingle) {
+      if (ch === "\\") { i++; continue; }
+      if (ch === "'") inSingle = false;
+      continue;
+    }
+    if (inDouble) {
+      if (ch === "\\") { i++; continue; }
+      if (ch === '"') inDouble = false;
+      continue;
+    }
+    if (inBacktick) {
+      if (ch === "\\") { i++; continue; }
+      if (ch === "`") inBacktick = false;
+      continue;
+    }
+
+    if (ch === "'") { inSingle = true; continue; }
+    if (ch === '"') { inDouble = true; continue; }
+    if (ch === "`") { inBacktick = true; continue; }
+
+    if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) return source.slice(start, i + 1);
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Parse a workflow source file into its meta, body, and executable form.
+ *
+ * - Extracts `export const meta = {…}` via balanced-brace scanning (ignoring braces in
+ *   quoted strings). Evaluates the extracted object under the existing trusted-dev posture.
+ * - `body` is the source after the meta declaration is removed (trimmed).
+ * - `executable` wraps the body as `module.exports = (async () => { … })()` unless the body
+ *   already starts with `module.exports =` (legacy CommonJS).
+ *
+ * When `requireMeta` is true and no meta declaration is found, throws.
+ */
+export function parseWorkflowSource(
+  source: string,
+  opts: { filePath: string; requireMeta: boolean },
+): ParsedWorkflowSource {
+  const metaStart = source.indexOf(META_MARKER);
+
+  if (metaStart === -1) {
+    if (opts.requireMeta) {
+      throw new Error(`${opts.filePath}: missing \`export const meta = {…}\``);
+    }
+    const body = source.trim();
+    const executable = /^\s*module\.exports\s*=/.test(body)
+      ? body
+      : `module.exports = (async () => {\n${body}\n})()`;
+    return { source, body, executable };
+  }
+
+  // Skip whitespace to find the opening brace
+  let braceStart = metaStart + META_MARKER.length;
+  while (braceStart < source.length && source[braceStart] !== "{") braceStart++;
+  if (braceStart >= source.length) {
+    throw new Error(`${opts.filePath}: meta declaration has no opening brace`);
+  }
+
+  const metaText = extractBalancedBraces(source, braceStart);
+  if (metaText === null) {
+    throw new Error(`${opts.filePath}: meta declaration has unbalanced braces`);
+  }
+
+  // Evaluate the extracted object (trusted-dev-environment; meta is small + author-controlled)
+  let meta: WorkflowMeta;
+  try {
+    // eslint-disable-next-line no-new-func
+    const fn = new Function(`"use strict"; return (${metaText})`);
+    const raw = fn() as Record<string, unknown>;
+    if (typeof raw.name !== "string" || !raw.name.trim()) {
+      throw new Error(`${opts.filePath}: meta.name missing`);
+    }
+    if (typeof raw.description !== "string") {
+      throw new Error(`${opts.filePath}: meta.description missing`);
+    }
+    const phases = Array.isArray(raw.phases) ? raw.phases as { title: string }[] : [];
+    meta = {
+      name: raw.name.trim(),
+      description: raw.description.trim(),
+      phases,
+    };
+  } catch (e) {
+    const msg = (e as Error).message;
+    if (msg.startsWith(opts.filePath)) throw e;
+    throw new Error(`${opts.filePath}: meta parse failed: ${msg}`);
+  }
+
+  // Body is everything after the complete meta declaration
+  const declEnd = braceStart + metaText.length;
+  const body = source.slice(declEnd).trim();
+
+  const executable = /^\s*module\.exports\s*=/.test(body)
+    ? body
+    : `module.exports = (async () => {\n${body}\n})()`;
+
+  return { meta, source, body, executable };
+}

package/src/workflows/vm-realm.ts

@@ -0,0 +1,106 @@
+// SPEC-6-3 §3.1 — the vm sandbox realm. Determinism, NOT security (PRD §6: trusted-dev-environment).
+// JS-only workflow scripts (no .ts → no transpile). Strips Date/Math.random/require/import/fs/net/timers/eval;
+// injects the 5 orchestration globals + 7 helpers + realm globals (log/args/cwd/process.cwd/budget).
+import vm from "node:vm";
+
+export interface RealmDeps {
+  agent: (prompt: string, opts?: Record<string, unknown>) => Promise<unknown>;
+  parallel: (thunks: Array<() => Promise<unknown>>) => Promise<unknown[]>;
+  pipeline: (items: unknown[], ...stages: Array<(item: unknown) => Promise<unknown>>) => Promise<unknown[]>;
+  phase: (title: string, opts?: { budget?: number }) => void;
+  workflow: (name: string, args?: unknown) => Promise<unknown>;
+  verify: (item: unknown, opts?: Record<string, unknown>) => Promise<unknown>;
+  judgePanel: (attempts: unknown[], opts?: Record<string, unknown>) => Promise<unknown>;
+  loopUntilDry: (opts: Record<string, unknown>) => Promise<unknown[]>;
+  completenessCheck: (taskArgs: unknown, results: unknown) => Promise<unknown>;
+  gate: (thunk: (feedback: string | undefined, attempt: number) => unknown, validator: (v: unknown) => { ok: boolean; feedback?: string }, opts?: Record<string, unknown>) => Promise<unknown>;
+  retry: (thunk: (attempt: number) => unknown, opts?: Record<string, unknown>) => Promise<unknown>;
+  checkpoint: (prompt: string, opts?: Record<string, unknown>) => Promise<unknown>;
+  log: (message: unknown) => void;
+  args: unknown;
+  cwd: string;
+  budget: { total: number; spent: () => number; remaining: () => number };
+}
+
+export const REALM_GLOBAL_NAMES = [
+  "agent", "parallel", "pipeline", "phase", "workflow",
+  "verify", "judgePanel", "loopUntilDry", "completenessCheck", "gate", "retry", "checkpoint",
+  "log", "args", "cwd", "process", "budget",
+] as const;
+
+/** Build a vm context with the injected globals + stripped non-determinism. */
+export function buildRealm(deps: RealmDeps): vm.Context {
+  const sandbox: Record<string, unknown> = {
+    // 5 orchestration globals
+    agent: deps.agent,
+    parallel: deps.parallel,
+    pipeline: deps.pipeline,
+    phase: deps.phase,
+    workflow: deps.workflow,
+    // 7 helpers
+    verify: deps.verify,
+    judgePanel: deps.judgePanel,
+    loopUntilDry: deps.loopUntilDry,
+    completenessCheck: deps.completenessCheck,
+    gate: deps.gate,
+    retry: deps.retry,
+    checkpoint: deps.checkpoint,
+    // realm globals
+    log: deps.log,
+    args: deps.args,
+    cwd: deps.cwd,
+    budget: deps.budget,
+    // process.cwd() returns the session cwd (deterministic); no process.env.
+    process: { cwd: () => deps.cwd },
+    // CommonJS module surface so scripts can `module.exports = …`
+    module: { exports: {} as unknown },
+    exports: undefined as unknown,
+    // async + Promise must be present for the script to use await
+    Promise,
+    // console absent (log() is the channel) — but provide a noop for accidental use
+    console: { log: deps.log, error: deps.log, warn: deps.log, info: deps.log },
+  };
+  // Fix: extract typed locals so we can alias `exports` without `unknown` errors.
+  const mod = sandbox.module as { exports: unknown };
+  sandbox.exports = mod.exports;
+  // JSON + the bare operators need nothing extra; but `JSON` is a global — provide it
+  sandbox.JSON = JSON;
+  // Symbol/Array/Object/Number/String/Boolean/Math (for JSON.stringify/Array.from etc.) —
+  // but we STRIP Math.random + Date by NOT providing them. Provide the safe builtins:
+  sandbox.Array = Array;
+  sandbox.Object = Object;
+  sandbox.String = String;
+  sandbox.Number = Number;
+  sandbox.Boolean = Boolean;
+  sandbox.Symbol = Symbol;
+  sandbox.Map = Map;
+  sandbox.Set = Set;
+  sandbox.Error = Error;
+  sandbox.RegExp = RegExp;
+  sandbox.parseInt = parseInt;
+  sandbox.parseFloat = parseFloat;
+  sandbox.isNaN = isNaN;
+  sandbox.isFinite = isFinite;
+  // Deliberately NOT provided (determinism contract): Date, Math, require, import,
+  // setTimeout, setInterval, setImmediate, fetch, globalThis, process.env, eval, Function.
+  // vm.createContext provides builtins (Date, Math, timers, eval, etc.) regardless of
+  // sandbox contents — shadow them with throwing getters so any access throws ReferenceError.
+  // process is NOT here: we inject `process: { cwd: () => deps.cwd }` above, and the spec
+  // strips process.env (not process.cwd). Exclude process from the strip set.
+  const STRIPPED = ["Date", "Math", "setTimeout", "setInterval", "setImmediate", "clearTimeout", "clearInterval", "clearImmediate", "eval", "Function", "globalThis", "fetch", "require"] as const;
+  for (const name of STRIPPED) {
+    Object.defineProperty(sandbox, name, {
+      get() { throw new ReferenceError(`${name} is not defined`); },
+      set() { throw new ReferenceError(`${name} is not defined`); },
+      configurable: false,
+      enumerable: false,
+    });
+  }
+  return vm.createContext(sandbox, { name: "armory-fleet-workflow" });
+}
+
+/** Compile a JS workflow script. JS-only — a .ts script is rejected upstream. */
+export function compileWorkflowScript(script: string): vm.Script {
+  // Wrap so the script can use `module.exports = …` (CommonJS) OR an async IIFE.
+  return new vm.Script(script, { filename: "workflow.js" });
+}

package/src/worktree/worktree-service.ts

@@ -40,6 +40,16 @@ export class WorktreeService {
     return existsSync(this.pathFor(runId));
   }
 
+  /** v0.11.1: is `rootDir` (or `dir`) inside a git repo? Cheap sync pre-flight for isolation routing. */
+  isGitRepo(dir: string = this.rootDir): boolean {
+    try {
+      sh("git rev-parse --show-toplevel", dir);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
   create(runId: string, baseRef = "HEAD"): WorktreeRef {
     if (this.exists(runId)) {
       throw new Error(`worktree for run ${runId} already exists at ${this.pathFor(runId)}`);