taskflow-core 0.1.0

package/dist/runner-core.js

@@ -0,0 +1,208 @@
+/**
+ * Host-neutral subagent-result helpers: failure classification, transient-error
+ * detection, error sanitization, and the NDJSON event accumulator/parser.
+ *
+ * This is the pure, host-SDK-free half of the original runner. The pi spawn
+ * machinery lives in the pi adapter (`pi-taskflow`); the codex spawn machinery
+ * in the codex adapter (`codex-taskflow`). Both reuse everything here so failure
+ * semantics, retry heuristics, and usage folding are identical across hosts.
+ */
+import { emptyUsage } from "./usage.js";
+export function isFailed(r) {
+    return r.exitCode !== 0 || r.stopReason === "error" || r.stopReason === "aborted";
+}
+/**
+ * Heuristic: did this failure look like a transient/retryable provider error
+ * (rate limit, overload, timeout, 5xx)? Such errors should be retried inside
+ * the taskflow run with backoff rather than bubbled up — otherwise the calling
+ * agent tends to re-invoke the whole tool, producing duplicate progress blocks.
+ */
+const TRANSIENT_ERROR_RE = /rate[_\s-]?limit|too\s+many\s+requests|overloaded|\b429\b|\b503\b|\b502\b|\b504\b|service\s+unavailable|temporarily\s+unavailable|timeout|timed?\s+out|econnreset|etimedout|socket\s+hang\s*up/i;
+export function isTransientError(r) {
+    if (r.stopReason === "aborted")
+        return false;
+    // Idle timeout is a deterministic stall — retrying won't help.
+    if (r.stopReason === "error" && r.idleTimeout)
+        return false;
+    const hay = `${r.errorMessage ?? ""} ${r.stderr ?? ""} ${r.output ?? ""}`;
+    return TRANSIENT_ERROR_RE.test(hay);
+}
+/** Placeholder written to a failed phase's `output` so downstream interpolation
+ *  can detect "upstream failed" without being polluted by raw HTML/JSON. */
+export const TRANSPORT_ERROR_PLACEHOLDER = "(upstream error: subagent failed; see error)";
+/** Hard cap on the errorMessage field stored in PhaseState (≈ 4 KB). */
+export const ERROR_MESSAGE_MAX_LEN = 4096;
+/** Cheap HTML/JSON detector so we can summarize upstream garbage. */
+export function looksLikeHtmlOrJson(s) {
+    const t = s.trimStart();
+    if (!t)
+        return false;
+    if (t.startsWith("<")) {
+        // HTML/XML/Cloudflare challenge pages
+        return /^<(?:!doctype\s+html|html|head|body|script|svg|div|iframe|span|p)\b/i.test(t);
+    }
+    if (t.startsWith("{")) {
+        // Truncated JSON. A genuine JSON envelope is fine to keep; an unwrapped
+        // {error: "..."} from an SDK is short. We only treat it as "garbage" if
+        // it parses and is huge — but that's caught by the size cap below.
+        return false;
+    }
+    return false;
+}
+/**
+ * Truncate and (when obviously HTML) summarize an errorMessage before it is
+ * persisted. Returns the cleaned string. Empty input returns empty.
+ */
+export function sanitizeErrorMessage(raw) {
+    if (!raw)
+        return "";
+    const cleaned = raw.replace(/\s+/g, " ").trim();
+    if (!cleaned)
+        return "";
+    // Decide the sanitization branch on the RAW length, not the whitespace-
+    // collapsed length — otherwise an HTML page padded with spaces would slip
+    // through the "looks like HTML" branch and be persisted as-is.
+    const rawLen = raw.length;
+    if (rawLen > ERROR_MESSAGE_MAX_LEN) {
+        const head = cleaned.slice(0, 200);
+        const tail = cleaned.slice(-200);
+        return `${head} ... [truncated ${rawLen - 400} chars] ... ${tail}`;
+    }
+    if (looksLikeHtmlOrJson(cleaned)) {
+        // Any document-like HTML (Cloudflare challenge pages, proxy error pages,
+        // gateway error pages) is a strong signal the upstream returned a page
+        // instead of JSON. Summarize it instead of letting HTML pollute the
+        // phase's error and downstream interpolation contexts.
+        const title = cleaned.match(/<title[^>]*>([^<]*)<\/title>/i)?.[1]?.trim();
+        const stripped = cleaned.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+        const m = stripped.match(/(?:Unable to load site|Ray ID[: ]+([A-Za-z0-9]+)|[A-Z][a-z]+Error[: ]+(.{0,200}))/i);
+        const hint = title || (m ? (m[1] || m[0]).trim() : stripped.slice(0, 200));
+        return `Upstream returned non-JSON response (${rawLen} chars). Hint: ${hint}`;
+    }
+    return cleaned;
+}
+export function getFinalOutput(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (msg.role === "assistant") {
+            for (const part of msg.content) {
+                if (part.type === "text" && part.text?.trim())
+                    return part.text;
+            }
+        }
+    }
+    return "";
+}
+export function newAccumulator(model) {
+    return { messages: [], usage: emptyUsage(), model, lastActivity: "" };
+}
+/**
+ * Fold one NDJSON line into the accumulator. Returns a LiveUpdate when an
+ * assistant message ended (for streaming), else null. Empty, malformed, and
+ * non-`message_end` lines are ignored — making the parser robust to partial
+ * buffers/noise and unit-testable without spawning a process.
+ */
+export function foldEventLine(acc, line) {
+    if (!line.trim())
+        return null;
+    let event;
+    try {
+        event = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (event.type !== "message_end" || !event.message)
+        return null;
+    const msg = event.message;
+    // Cap prevents OOM from misconfigured loops. 500 messages is generous for
+    // normal subagent tasks (50 turns × 10 messages each). Messages beyond the
+    // cap are still parsed for usage/model/stopReason extraction.
+    const MAX_MESSAGES = 500;
+    if (acc.messages.length < MAX_MESSAGES) {
+        acc.messages.push(msg);
+    }
+    else {
+        acc.truncated = true;
+    }
+    if (msg.role !== "assistant")
+        return null;
+    acc.usage.turns++;
+    const u = msg.usage;
+    if (u) {
+        acc.usage.input += u.input || 0;
+        acc.usage.output += u.output || 0;
+        acc.usage.cacheRead += u.cacheRead || 0;
+        acc.usage.cacheWrite += u.cacheWrite || 0;
+        acc.usage.cost += u.cost?.total || 0;
+        acc.usage.contextTokens = u.totalTokens || 0;
+    }
+    if (!acc.model && msg.model)
+        acc.model = msg.model;
+    if (msg.stopReason)
+        acc.stopReason = msg.stopReason;
+    if (msg.errorMessage)
+        acc.errorMessage = msg.errorMessage;
+    const activity = describeActivity(msg);
+    if (activity)
+        acc.lastActivity = activity;
+    return { text: acc.lastActivity, usage: { ...acc.usage }, model: acc.model };
+}
+/** One-line description of the most recent assistant activity (text or tool call). */
+function describeActivity(msg) {
+    if (msg.role !== "assistant")
+        return "";
+    let lastText = "";
+    let lastTool = "";
+    for (const part of msg.content ?? []) {
+        if (part.type === "text" && part.text?.trim())
+            lastText = part.text.trim();
+        else if (part.type === "toolCall")
+            lastTool = summarizeToolCall(part.name, part.arguments ?? {});
+    }
+    const chosen = lastText || lastTool;
+    return chosen.replace(/\s+/g, " ").trim();
+}
+function summarizeToolCall(name, args) {
+    const short = (p) => {
+        const s = String(p ?? "");
+        return s.length > 48 ? `${s.slice(0, 48)}…` : s;
+    };
+    switch (name) {
+        case "bash":
+            return `$ ${short(args.command)}`;
+        case "read":
+            return `read ${short(args.path ?? args.file_path)}`;
+        case "write":
+            return `write ${short(args.path ?? args.file_path)}`;
+        case "edit":
+            return `edit ${short(args.path ?? args.file_path)}`;
+        case "grep":
+            return `grep ${short(args.pattern)}`;
+        case "find":
+            return `find ${short(args.pattern)}`;
+        case "ls":
+            return `ls ${short(args.path)}`;
+        default:
+            return `${name}`;
+    }
+}
+/** Run an array of items through `fn` with a bounded concurrency pool. */
+export async function mapWithConcurrencyLimit(items, concurrency, fn) {
+    if (items.length === 0)
+        return [];
+    const limit = Math.max(1, Math.min(concurrency, items.length));
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    const workers = new Array(limit).fill(null).map(async () => {
+        while (true) {
+            const current = nextIndex++;
+            if (current >= items.length)
+                return;
+            results[current] = await fn(items[current], current);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+//# sourceMappingURL=runner-core.js.map

package/dist/runner-core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner-core.js","sourceRoot":"","sources":["../src/runner-core.ts"],"names":[],"mappings":"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"}

package/dist/runtime.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Taskflow runtime — the orchestration engine.
+ *
+ * Resolves the phase DAG into topological layers and executes each phase by
+ * delegating to isolated subagents. Intermediate phase outputs live here (in
+ * RunState) and never enter the host conversation's context window — only the
+ * final phase output is returned to the caller.
+ *
+ * Supports resume: phases whose resolved input hash matches a cached completed
+ * result are skipped.
+ */
+import type { AgentConfig } from "./agents.ts";
+import type { SubagentRunner } from "./host/runner-types.ts";
+/** The host-neutral subagent runner signature the engine drives. A host adapter
+ *  (pi, codex) injects a concrete `runTask` via `RuntimeDeps`. */
+type RunTaskFn = SubagentRunner<any>["runTask"];
+import { type UsageStats } from "./usage.ts";
+import { type CacheScope, type Taskflow } from "./schema.ts";
+import { type PhaseState, type RunState } from "./store.ts";
+import { CacheStore } from "./cache.ts";
+/** A human-in-the-loop approval request raised by an `approval` phase. */
+export interface ApprovalRequest {
+    phaseId: string;
+    /** Interpolated prompt shown to the human. */
+    message: string;
+    /** Output of the immediately-upstream phase, for context. */
+    upstream?: string;
+}
+/** The human's decision. `edit` carries guidance passed downstream as the phase output. */
+export interface ApprovalDecision {
+    decision: "approve" | "reject" | "edit";
+    note?: string;
+}
+export interface RuntimeDeps {
+    cwd: string;
+    agents: AgentConfig[];
+    globalThinking?: string;
+    signal?: AbortSignal;
+    /** Persist run state after each phase (for resume). */
+    persist?: (state: RunState) => void;
+    /** Live progress callback for TUI streaming. */
+    onProgress?: (state: RunState) => void;
+    /** Injectable task runner (defaults to spawning a real subagent). Enables testing. */
+    runTask?: RunTaskFn;
+    /** Resolve an `approval` phase. Omit for non-interactive runs (auto-reject). */
+    requestApproval?: (req: ApprovalRequest) => Promise<ApprovalDecision>;
+    /** Resolve a saved taskflow by name for `flow` (sub-workflow) phases. */
+    loadFlow?: (name: string) => Taskflow | undefined;
+    /** Cross-run memoization store. Omit to construct a default one for `deps.cwd`. */
+    cacheStore?: CacheStore;
+    /** Default cache scope for phases that don't specify one. */
+    cacheScopeDefault?: CacheScope;
+    /** Internal: sub-flow call stack, for recursion detection. */
+    _stack?: string[];
+    /** Internal: pre-resolved Shared Context Tree dir for this run (sub-flows inherit the parent's). */
+    _ctxDir?: string;
+    /** Internal: an isolated workspace dir override for the current phase (worktree isolation). */
+    _cwdOverride?: string;
+}
+export interface RuntimeResult {
+    state: RunState;
+    finalOutput: string;
+    ok: boolean;
+    totalUsage: UsageStats;
+    /** Incremental-reuse summary: how many phases were reused from cache vs.
+     *  freshly executed this run, and the cost the reused work would otherwise
+     *  have incurred (known only for within-run resume; cross-run hits zero
+     *  their usage so their original cost is not recoverable). Optional &
+     *  additive — callers that ignore it are unaffected. */
+    reuse?: ReuseSummary;
+}
+/** A run's incremental-reuse accounting (see RuntimeResult.reuse). */
+export interface ReuseSummary {
+    /** Phases that completed by executing a subagent this run. */
+    executed: number;
+    /** Phases served from the within-run resume cache (no new tokens). */
+    reusedRunOnly: number;
+    /** Phases restored from the cross-run store (no new tokens). */
+    reusedCrossRun: number;
+    /** Total phases that reached `done` (executed + reused). */
+    done: number;
+    /** USD the within-run-reused phases would have cost if re-executed (their
+     *  preserved prior usage). Cross-run hits are excluded (cost not recoverable). */
+    savedUSD: number;
+}
+/** Compute the incremental-reuse summary from a run's terminal phase states.
+ *  Pure, total, never throws. A phase is "reused" iff it carries a `cacheHit`
+ *  marker (set by `cachedPhase` for both within-run resume and cross-run hits). */
+export declare function summarizeReuse(state: RunState): ReuseSummary;
+/**
+ * Per-phase cache policy resolved once at the top of executePhase. Carries the
+ * scope, optional TTL, and a pre-resolved fingerprint string so each phase-type
+ * branch can fold it into its inputHash and consult the cross-run store uniformly.
+ */
+export interface PhaseCacheCtx {
+    scope: CacheScope;
+    ttlMs?: number;
+    fingerprint: string;
+    store: CacheStore;
+    prior: PhaseState | undefined;
+    phaseId: string;
+    flowName: string;
+    runId: string;
+    /** Per-phase execution config that materially affects subagent output and
+     *  therefore must be part of the cache identity (else a config change could
+     *  silently serve a stale cross-run hit). */
+    thinking?: string;
+    tools?: string[];
+    /** Resolved `context` pre-read content. Explicitly part of the cache identity
+     *  so a context-file change always invalidates the phase — independent of
+     *  whether a given branch happens to fold preRead into its task string
+     *  (previously this was only incidentally true via `fullTask`). */
+    preRead?: string;
+    /** Content fingerprint of the desugared flow definition — folded into the
+     *  key so two structurally-different flows that share a name can never
+     *  collide, and a changed flow never serves a stale cross-run hit. */
+    flowDefHash?: string | "failed";
+    /** Per-phase structural sub-fingerprint (M6). When present, folds into the
+     *  key as `v3:phasefp:<subfp>` so editing phase B invalidates only B + its
+     *  transitive dependents. When absent (sub-flow inner states, or a phase
+     *  for which per-phase soundness couldn't be guaranteed), `cacheKeys`
+     *  falls back to `flowDefHash` — preserving pre-M6 whole-flow behavior. */
+    phaseFp?: string;
+    /** Force this phase to re-execute, ignoring the within-run prior AND the
+     *  cross-run store (M5 recompute seed). Downstream phases are NOT forced —
+     *  they re-evaluate naturally: if the seed's new output changed their
+     *  inputHash they miss and re-run, otherwise they hit (early cutoff). */
+    forceRerun?: boolean;
+}
+/** Fold the phase fingerprint into the base hash parts to form the final cache key. */
+/** A computed cache identity: the new (versioned) key plus the read-only
+ *  fallback keys used to honor entries written by older releases. The `key`
+ *  is what we WRITE under and what `PhaseState.inputHash` carries; the
+ *  `v2Key`/`bareKey`/`legacyKey` are consulted READ-ONLY on a miss so an
+ *  upgrade never produces a miss-storm. See docs/internal/cache-migration.md. */
+export interface CacheKeys {
+    /** Current key: folds `v3:phasefp:<subfp>` (the per-phase structural
+     *  sub-fingerprint; degrades to the whole-flow hash when per-phase
+     *  soundness couldn't be guaranteed). */
+    key: string;
+    /** Pre-M6 key: `v2:flowdef:<flowDefHash>` (whole-flow fingerprint).
+     *  Read-only. */
+    v2Key: string;
+    /** Bare (unversioned) `flowdef:` key — written by pre-H1 code that folded
+     *  the hash without a `v2:` prefix. Read-only. Removed in v0.1.0. */
+    bareKey: string;
+    /** Pre-flowDefHash-era key: the flowdef line OMITTED entirely. Read-only. */
+    legacyKey: string;
+}
+/** Fold the phase fingerprint into the base hash parts to form the cache keys.
+ *
+ *  Four keys are produced for backward compatibility (see
+ *  docs/internal/cache-migration.md):
+ *    - `key`      : `v3:phasefp:<subfp>` — the current write key (per-phase
+ *      structural sub-fingerprint; falls back to the whole-flow hash when
+ *      `cc.phaseFp` is absent).
+ *    - `v2Key`    : `v2:flowdef:<flowDefHash>` — pre-M6 whole-flow key.
+ *    - `bareKey`  : bare `flowdef:<flowDefHash>` (unversioned) — pre-H1 entries.
+ *    - `legacyKey`: the flowdef line omitted — pre-flowDefHash entries.
+ *  `cachedPhase` consults all four READ-ONLY on a miss; `recordCache` writes
+ *  only `key`. This means an upgrade never produces a miss-storm: existing
+ *  entries (whichever shape) still hit, and new writes converge on `key`. */
+export declare function cacheKeys(cc: PhaseCacheCtx, baseParts: string[]): CacheKeys;
+/**
+ * Parse a gate phase's output into a verdict. Blocks the flow only on an
+ * explicit negative signal; ambiguous output passes (fail-open).
+ * Accepts JSON ({continue|pass: bool} or {verdict: "..."}) or a text marker
+ * `VERDICT: PASS|BLOCK|FAIL|STOP|OK|REJECT|HALT` (last occurrence wins).
+ */
+export declare function parseGateVerdict(output: string): {
+    verdict: "pass" | "block";
+    reason?: string;
+};
+/**
+ * Parse a judge's pick of the winning variant. Accepts JSON ({"winner":n} or
+ * {"best":n}) or a `WINNER: n` line (last match wins). Clamps to [1, count].
+ * Fail-open: an unreadable verdict defaults to variant 1 so the work is never
+ * lost. Returns the 1-based index plus an optional reason.
+ */
+export declare function parseTournamentWinner(output: string, count: number): {
+    winner: number;
+    reason?: string;
+};
+/**
+ * Execute a full taskflow. Mutates and persists `state` as it progresses.
+ */
+/** Result of a recompute: what was (or would be) re-executed vs reused.
+ *  `cutoff` is the prize — phases in the stale frontier whose inputHash did
+ *  NOT move, so they hit their cached result instead of re-running (early
+ *  cutoff). That is what makes recompute cheaper than a full re-run. */
+export interface RecomputeReport {
+    readonly dryRun: boolean;
+    readonly aborted: boolean;
+    readonly seeds: readonly string[];
+    /** Phases that were (dry-run: would be) re-executed, or whose result moved. */
+    readonly rerun: readonly string[];
+    /** Phases outside the frontier — untouched, reused verbatim. */
+    readonly reused: readonly string[];
+    /** Phases in the frontier whose inputHash did NOT move → cached result
+     *  reused, no re-execution (early cutoff). Empty in dry-run (unknowable). */
+    readonly cutoff: readonly string[];
+    /** Per-phase decision trace: WHY each phase was rerun / cut off / reused.
+     *  The "explainable reactivity" layer — like React DevTools telling you why
+     *  a component re-rendered. Additive; callers that ignore it are unaffected. */
+    readonly decisions: readonly RecomputeDecision[];
+}
+/** Why a single phase landed in its recompute outcome. */
+export interface RecomputeDecision {
+    readonly phaseId: string;
+    /** What happened (real run) or would happen (dry-run). */
+    readonly outcome: "rerun" | "cutoff" | "reused" | "failed";
+    /** Human-readable cause. */
+    readonly reason: string;
+    /** The upstream phase(s) that caused this outcome, when applicable
+     *  (e.g. the changed upstreams that forced a rerun). */
+    readonly causedBy?: readonly string[];
+}
+/** Recompute a completed run minimally: force-rerun the `seeds`, then walk
+ *  their stale frontier in topological order. The cache provides early cutoff
+ *  for free — a downstream whose inputHash didn't move (because the seed's new
+ *  output happened to equal the old) hits its prior and is reused rather than
+ *  re-executed. `dryRun` computes the worst-case frontier without spending a
+ *  token. Returns a fresh state + a report. Throws only when dryRun:false is
+ *  requested for a flow with unobserved dependencies; callers should surface
+ *  that as a user-facing error. */
+export declare function recomputeTaskflow(state: RunState, deps: RuntimeDeps, seeds: readonly string[], opts?: {
+    dryRun?: boolean;
+}): Promise<{
+    report: RecomputeReport;
+    state: RunState;
+}>;
+export declare function executeTaskflow(state: RunState, deps: RuntimeDeps): Promise<RuntimeResult>;
+export {};
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}