@signalridge/pi-workflows 1.2.1 → 1.3.2

package/src/capabilities.ts

@@ -0,0 +1,318 @@
+/**
+ * capabilities.ts — machine-readable workflow capability contract (A11).
+ *
+ * One authoritative declaration of the runtime surface: every global a script
+ * may use, every option a helper accepts, and every workflow-tool input. The
+ * runtime builds its bindings from this declaration, and `check:capabilities`
+ * asserts that the shipped docs (README) stay aligned — the tool schema,
+ * documentation, and the real runtime face cannot drift apart.
+ */
+
+import type { WorkflowRuntimeBindings } from "./runtime.js";
+
+/** Classification of a capability entry. */
+export type CapabilityClass = "runtime-global" | "workflow-tool-input" | "script-contract";
+
+export interface CapabilityOption {
+  name: string;
+  kind: string;
+  optional: boolean;
+  default: string;
+}
+
+export interface CapabilityEntry {
+  name: string;
+  classification: CapabilityClass;
+  signature: string;
+  options: CapabilityOption[];
+  constraints: string[];
+}
+
+/** The contract format version. Bump on any breaking surface change. */
+export const WORKFLOW_CAPABILITY_CONTRACT_VERSION = "1.0.0";
+
+/**
+ * The runtime globals a script can rely on. `options` documents each helper's
+ * accepted inputs with defaults; `constraints` states the behavioral contract.
+ */
+export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
+  {
+    name: "agent",
+    classification: "runtime-global",
+    signature: "agent(prompt, options?) => Promise<string | structured value | null>",
+    options: [
+      { name: "label", kind: "string", optional: true, default: "derived from phase and call count" },
+      { name: "phase", kind: "string", optional: true, default: "current phase" },
+      { name: "schema", kind: "plain JSON Schema", optional: true, default: "none" },
+      { name: "model", kind: "string", optional: true, default: "pi-subagents model resolver" },
+      { name: "tier", kind: "small|medium|large", optional: true, default: "pi-subagents workflow tier" },
+      { name: "isolation", kind: '"worktree"', optional: true, default: "pi-subagents worktree policy" },
+      { name: "thread", kind: "string", optional: true, default: "fresh session per call" },
+      { name: "toolset", kind: "string", optional: true, default: "configured host/agent toolset hint" },
+      { name: "excludeTools", kind: "string[]", optional: true, default: "none" },
+      { name: "agentType", kind: "string", optional: true, default: "general-purpose" },
+      { name: "timeoutMs", kind: "number | null", optional: true, default: "300000 (5min); null disables" },
+      { name: "retries", kind: "number", optional: true, default: "run retry count" },
+    ],
+    constraints: [
+      "recoverable failures return null after retries; nonrecoverable failures throw",
+      "schema noncompliance after bounded repair attempts is nonrecoverable",
+      "resume replays only the longest unchanged prefix; the first miss and every later call execute live",
+      "spawnKeys rotate by generation on resume so pi-subagents never raises a fingerprint conflict",
+      "explicit model is resolved and scope-checked by pi-subagents; unavailable selectors fail closed",
+      "same-thread calls must be sequential and preserve a stable workflow thread name",
+      "threads cannot be combined with worktree isolation",
+    ],
+  },
+  {
+    name: "parallel",
+    classification: "runtime-global",
+    signature: "parallel(thunks) => Promise<Array<unknown | null>>",
+    options: [],
+    constraints: [
+      "requires functions rather than promises",
+      "result order matches input order",
+      "recoverable thunk failures become null; nonrecoverable failures throw",
+      "a breached agent cap cancels only its own batch",
+    ],
+  },
+  {
+    name: "pipeline",
+    classification: "runtime-global",
+    signature: "pipeline(items, ...stages) => Promise<Array<unknown | null>>",
+    options: [],
+    constraints: [
+      "items run concurrently while stages per item run sequentially",
+      "each stage receives previousValue, originalItem, and zero-based index",
+      "a null stage result is passed to the next stage",
+    ],
+  },
+  {
+    name: "workflow",
+    classification: "runtime-global",
+    signature: "workflow(savedName, childArgs?) => Promise<unknown>",
+    options: [],
+    constraints: [
+      "one nested level",
+      "shares limiter, counters, token accounting, and store",
+      "nested runs get unique runIds via nestedCallSeq",
+    ],
+  },
+  {
+    name: "verify",
+    classification: "runtime-global",
+    signature: "verify(item, options?) => Promise<{ real, realCount, total, votes }>",
+    options: [
+      { name: "reviewers", kind: "number", optional: true, default: "2" },
+      { name: "threshold", kind: "number", optional: true, default: "0.5" },
+      { name: "lens", kind: "string | string[]", optional: true, default: "none" },
+    ],
+    constraints: ["threshold comparison is inclusive; real is false when no reviewer succeeds"],
+  },
+  {
+    name: "judgePanel",
+    classification: "runtime-global",
+    signature: "judgePanel(attempts, options?) => Promise<{ index, attempt, score, judgments } | undefined>",
+    options: [
+      { name: "judges", kind: "number", optional: true, default: "3" },
+      { name: "rubric", kind: "string", optional: true, default: "overall quality and correctness" },
+    ],
+    constraints: ["highest mean score wins with stable input index as the tie-break; empty input returns undefined"],
+  },
+  {
+    name: "loopUntilDry",
+    classification: "runtime-global",
+    signature: "loopUntilDry({ round, key?, consecutiveEmpty?, maxRounds? }) => Promise<unknown[]>",
+    options: [
+      { name: "round", kind: "(roundIndex) => unknown[]", optional: false, default: "required" },
+      { name: "key", kind: "(item) => string", optional: true, default: "JSON.stringify" },
+      { name: "consecutiveEmpty", kind: "number", optional: true, default: "2" },
+      { name: "maxRounds", kind: "number", optional: true, default: "50" },
+    ],
+    constraints: ["budget/agent-limit exhaustion returns the partial array instead of throwing"],
+  },
+  {
+    name: "completenessCheck",
+    classification: "runtime-global",
+    signature: "completenessCheck(taskArgs, results) => Promise<{ complete, missing? } | null>",
+    options: [],
+    constraints: ["only the first 4,000 characters of serialized result evidence are sent to the critic"],
+  },
+  {
+    name: "retry",
+    classification: "runtime-global",
+    signature: "retry(thunk, options?) => Promise<unknown>",
+    options: [
+      { name: "attempts", kind: "number", optional: true, default: "3" },
+      { name: "until", kind: "(result) => boolean", optional: true, default: "accept first result" },
+    ],
+    constraints: ["until must be synchronous"],
+  },
+  {
+    name: "gate",
+    classification: "runtime-global",
+    signature: "gate(thunk, validator, options?) => Promise<{ ok, value, attempts }>",
+    options: [{ name: "attempts", kind: "number", optional: true, default: "3" }],
+    constraints: ["a value is accepted only when the validator returns an object with a truthy ok"],
+  },
+  {
+    name: "checkpoint",
+    classification: "runtime-global",
+    signature: "checkpoint(prompt, options?) => Promise<unknown>",
+    options: [
+      { name: "default", kind: "unknown", optional: true, default: "true when no UI and omitted" },
+      { name: "headless", kind: '"default" | "abort"', optional: true, default: '"default"' },
+      { name: "kind", kind: '"confirm" | "input" | "select"', optional: true, default: '"confirm"' },
+      { name: "choices", kind: "string[]", optional: true, default: "none" },
+      { name: "timeoutMs", kind: "number", optional: true, default: "none" },
+    ],
+    constraints: [
+      "consumes one agent slot and no tokens",
+      "journaled answers replay only within an unchanged resume prefix",
+    ],
+  },
+  { name: "log", classification: "runtime-global", signature: "log(message) => void", options: [], constraints: [] },
+  {
+    name: "console",
+    classification: "runtime-global",
+    signature: "console: { log, info, warn, error }",
+    options: [],
+    constraints: ["compatibility only — new workflows should use log()"],
+  },
+  {
+    name: "phase",
+    classification: "runtime-global",
+    signature: "phase(title, options?) => void",
+    options: [{ name: "budget", kind: "number", optional: true, default: "positive soft pre-call token gate" }],
+    constraints: ["phase budgets are soft pre-call gates"],
+  },
+  { name: "args", classification: "runtime-global", signature: "args: unknown", options: [], constraints: [] },
+  { name: "cwd", classification: "runtime-global", signature: "cwd: string", options: [], constraints: [] },
+  {
+    name: "process",
+    classification: "runtime-global",
+    signature: "process: { cwd(): string }",
+    options: [],
+    constraints: ["restricted: only cwd() is exposed"],
+  },
+  {
+    name: "budget",
+    classification: "runtime-global",
+    signature: "budget: { total, spent(), remaining() }",
+    options: [],
+    constraints: ["frozen view over shared soft token accounting; nested workflows share the same accounting"],
+  },
+  {
+    name: "script",
+    classification: "workflow-tool-input",
+    signature: "script?: string",
+    options: [],
+    constraints: ["required raw JavaScript workflow source unless `name` is given"],
+  },
+  {
+    name: "name",
+    classification: "workflow-tool-input",
+    signature: "name?: string",
+    options: [],
+    constraints: [
+      "resolves a saved workflow first, then one of the 5 built-in patterns",
+      "mutually exclusive with script and resumeFromRunId",
+    ],
+  },
+  { name: "args", classification: "workflow-tool-input", signature: "args?: unknown", options: [], constraints: [] },
+  {
+    name: "background",
+    classification: "workflow-tool-input",
+    signature: "background?: boolean = true",
+    options: [],
+    constraints: [
+      "background workflows are headless; use background false when checkpoint must show foreground confirmation",
+    ],
+  },
+  {
+    name: "maxAgents",
+    classification: "workflow-tool-input",
+    signature: "maxAgents?: number = 1000",
+    options: [],
+    constraints: [],
+  },
+  {
+    name: "concurrency",
+    classification: "workflow-tool-input",
+    signature: "concurrency?: number",
+    options: [],
+    constraints: ["runtime clamps to 1..16"],
+  },
+  {
+    name: "agentRetries",
+    classification: "workflow-tool-input",
+    signature: "agentRetries?: number = 0",
+    options: [],
+    constraints: ["floored and clamped to 0..3"],
+  },
+  {
+    name: "agentTimeoutMs",
+    classification: "workflow-tool-input",
+    signature: "agentTimeoutMs?: number = 300000",
+    options: [],
+    constraints: ["null disables the hard timeout; default 300000ms (5min)"],
+  },
+  {
+    name: "tokenBudget",
+    classification: "workflow-tool-input",
+    signature: "tokenBudget?: number",
+    options: [],
+    constraints: ["soft pre-call gate; in-flight work can overshoot"],
+  },
+  {
+    name: "resumeFromRunId",
+    classification: "workflow-tool-input",
+    signature: "resumeFromRunId?: string",
+    options: [],
+    constraints: [
+      "resumes a prior incomplete run with an edited script",
+      "unchanged positional calls replay from cache until the first changed call",
+      "always runs in the background",
+    ],
+  },
+  {
+    name: "export const meta",
+    classification: "script-contract",
+    signature: "export const meta = { name, description, phases? }",
+    options: [],
+    constraints: [
+      "must be the first statement",
+      "name and description must be nonblank literals",
+      "spread, computed keys, methods, template interpolation, and __proto__/constructor/prototype are rejected",
+    ],
+  },
+  {
+    name: "determinism",
+    classification: "script-contract",
+    signature: "Date.now(), Math.random(), no-argument new Date() unavailable",
+    options: [],
+    constraints: ["pass timestamps and randomness through args"],
+  },
+];
+
+/**
+ * Every runtime global the script realm actually exposes. `check:capabilities`
+ * asserts this set matches the declaration above, so a binding added to the
+ * runtime but not documented fails the gate.
+ */
+export function declaredRuntimeGlobals(): string[] {
+  return WORKFLOW_CAPABILITIES.filter((entry) => entry.classification === "runtime-global").map((entry) => entry.name);
+}
+
+/** Validate that the runtime's binding surface matches the contract. */
+export function checkRuntimeBindings(bindings: WorkflowRuntimeBindings): string[] {
+  const problems: string[] = [];
+  const declared = new Set(declaredRuntimeGlobals());
+  for (const name of declared) {
+    if (!(name in bindings)) problems.push(`runtime is missing declared global "${name}"`);
+  }
+  for (const name of Object.keys(bindings) as Array<keyof WorkflowRuntimeBindings>) {
+    if (!declared.has(name)) problems.push(`runtime exposes undocumented global "${String(name)}"`);
+  }
+  return problems;
+}

package/src/code-review-scope.ts

@@ -0,0 +1,144 @@
+/**
+ * Diff discovery for the `/code-review` command.
+ *
+ * The `code-review` script reviews a diff it is handed; a user types a *scope*
+ * (nothing, a PR number, a revision range, or a path). This module turns the
+ * one into the other, and degrades to a plain `git diff HEAD` whenever the
+ * narrower attempt fails or comes back empty — a review of nothing looks
+ * identical to a review that found nothing, so silence is not an option.
+ *
+ * Commands are run as argv arrays, never as shell strings: a branch or path
+ * argument is attacker-influenced often enough that interpolation is a real
+ * injection surface.
+ */
+
+/** Result of one command: `ok` is false for a non-zero exit or a spawn failure. */
+export interface CommandResult {
+  ok: boolean;
+  stdout: string;
+}
+
+/** Runs one command with an argv array. Injected so this module is testable without git. */
+export type CommandRunner = (file: string, args: string[]) => CommandResult;
+
+export interface CodeReviewScope {
+  diff: string;
+  /** Human-readable provenance, shown in the report and passed to the script. */
+  diffSource: string;
+  /** Degradation messages to surface with `ctx.ui.notify`; empty on the happy path. */
+  notices: string[];
+}
+
+/** Diffs above this are truncated — the review agents have a finite context. */
+export const MAX_DIFF_CHARS = 120_000;
+
+/**
+ * Pathspecs excluded from the no-argument auto scope.
+ *
+ * Deliberately limited to high-confidence generated or vendored output. A false
+ * exclusion silently hides real changes from review, which is worse than the
+ * noise it saves, so anything ambiguous is left in.
+ */
+export const AUTO_SCOPE_EXCLUSIONS: readonly string[] = [
+  ":(exclude)**/node_modules/**",
+  ":(exclude)**/dist/**",
+  ":(exclude)**/build/**",
+  ":(exclude)**/coverage/**",
+  ":(exclude)**/.next/**",
+  ":(exclude)**/__snapshots__/**",
+  ":(exclude)**/*.min.js",
+  ":(exclude)**/*.map",
+  ":(exclude)**/package-lock.json",
+  ":(exclude)**/bun.lock",
+  ":(exclude)**/bun.lockb",
+  ":(exclude)**/pnpm-lock.yaml",
+  ":(exclude)**/yarn.lock",
+  ":(exclude)**/Cargo.lock",
+  ":(exclude)**/go.sum",
+  ":(exclude)**/uv.lock",
+  ":(exclude)**/poetry.lock",
+];
+
+function truncate(diff: string): { diff: string; truncated: boolean } {
+  if (diff.length <= MAX_DIFF_CHARS) return { diff, truncated: false };
+  return {
+    diff: `${diff.slice(0, MAX_DIFF_CHARS)}\n\n[diff truncated at ${MAX_DIFF_CHARS} characters]`,
+    truncated: true,
+  };
+}
+
+function finish(diff: string, diffSource: string, notices: string[]): CodeReviewScope {
+  const capped = truncate(diff);
+  if (capped.truncated) {
+    notices.push(`Diff truncated at ${MAX_DIFF_CHARS} characters — review covers the first part only.`);
+  }
+  return { diff: capped.diff, diffSource, notices };
+}
+
+/**
+ * Resolve the `/code-review` argument into a diff.
+ *
+ * - `""` → working tree against HEAD, generated artifacts excluded
+ * - `"123"` → `gh pr diff 123`
+ * - `"main..HEAD"` → that revision range
+ * - anything else → treated as a path
+ */
+export function resolveCodeReviewScope(argument: string, run: CommandRunner): CodeReviewScope {
+  const text = argument.trim();
+  const notices: string[] = [];
+
+  if (/^\d+$/u.test(text)) {
+    const pr = run("gh", ["pr", "diff", text]);
+    if (!pr.ok) {
+      notices.push(`Could not read PR #${text} (is the gh CLI authenticated?). Nothing to review.`);
+      return finish("", `PR #${text}`, notices);
+    }
+    return finish(pr.stdout, `PR #${text}`, notices);
+  }
+
+  if (text.includes("..")) {
+    const range = run("git", ["diff", text]);
+    if (!range.ok) {
+      notices.push(`Could not diff range "${text}". Nothing to review.`);
+      return finish("", `range ${text}`, notices);
+    }
+    return finish(range.stdout, `range ${text}`, notices);
+  }
+
+  if (text) {
+    const scoped = run("git", ["diff", "HEAD", "--", text]);
+    if (!scoped.ok) {
+      notices.push(`Could not diff path "${text}". Nothing to review.`);
+      return finish("", `path ${text}`, notices);
+    }
+    return finish(scoped.stdout, `path ${text}`, notices);
+  }
+
+  // No argument: auto scope, with the two documented degradations.
+  const bare = () => run("git", ["diff", "HEAD"]);
+
+  const auto = run("git", ["diff", "HEAD", "--", ".", ...AUTO_SCOPE_EXCLUSIONS]);
+  if (!auto.ok) {
+    const fallback = bare();
+    notices.push("Auto-scoped diff failed; reviewing the full `git diff HEAD` instead.");
+    if (!fallback.ok) {
+      notices.push("`git diff HEAD` also failed — is this a git repository? Nothing to review.");
+      return finish("", "working tree", notices);
+    }
+    return finish(fallback.stdout, "working tree (unscoped)", notices);
+  }
+
+  if (auto.stdout.trim()) return finish(auto.stdout, "working tree vs HEAD", notices);
+
+  // The exclusions emptied the diff. Only fall back when there was in fact
+  // something to review — an genuinely clean tree must not be reported as a
+  // degradation.
+  const fallback = bare();
+  if (fallback.ok && fallback.stdout.trim()) {
+    notices.push("Every change was an excluded generated artifact; reviewing the full `git diff HEAD` instead.");
+    return finish(fallback.stdout, "working tree (unscoped)", notices);
+  }
+
+  notices.push("No uncommitted changes against HEAD — nothing to review.");
+  return finish("", "working tree vs HEAD", notices);
+}