openclaw-swarm-layer 0.1.0

package/dist/src/planning/planner.js

@@ -0,0 +1,39 @@
+import { defaultSwarmPluginConfig } from "../config.js";
+import { upsertTaskStatuses, validateTaskGraph } from "./task-graph.js";
+function taskIdForPhase(phaseId, index) {
+    return `${phaseId}-task-${index + 1}`;
+}
+export function planTasksFromSpec(spec, config) {
+    const resolvedConfig = { ...defaultSwarmPluginConfig, ...config };
+    const tasks = [];
+    for (const phase of spec.phases) {
+        const phaseTasks = phase.tasks.length > 0 ? phase.tasks : [`Execute ${phase.title}`];
+        phaseTasks.forEach((taskTitle, index) => {
+            const previousTask = tasks[tasks.length - 1];
+            tasks.push({
+                taskId: taskIdForPhase(phase.phaseId, index),
+                specId: spec.specId,
+                phaseId: phase.phaseId,
+                title: taskTitle,
+                description: taskTitle,
+                kind: "coding",
+                deps: previousTask ? [previousTask.taskId] : [],
+                status: "planned",
+                workspace: {
+                    mode: resolvedConfig.defaultWorkspaceMode,
+                },
+                runner: {
+                    type: resolvedConfig.defaultRunner,
+                },
+                review: {
+                    required: resolvedConfig.reviewRequiredByDefault,
+                },
+            });
+        });
+    }
+    const validation = validateTaskGraph(tasks);
+    if (!validation.ok) {
+        throw new Error(`Invalid task graph: ${validation.errors.join("; ")}`);
+    }
+    return upsertTaskStatuses(tasks);
+}

package/dist/src/planning/task-graph.d.ts

@@ -0,0 +1,8 @@
+import type { TaskNode } from "../types.js";
+export type TaskGraphValidationResult = {
+    ok: boolean;
+    errors: string[];
+};
+export declare function validateTaskGraph(tasks: TaskNode[]): TaskGraphValidationResult;
+export declare function getRunnableTasks(tasks: TaskNode[]): TaskNode[];
+export declare function upsertTaskStatuses(tasks: TaskNode[]): TaskNode[];

package/dist/src/planning/task-graph.js

@@ -0,0 +1,59 @@
+export function validateTaskGraph(tasks) {
+    const errors = [];
+    const ids = new Set();
+    const tasksById = new Map(tasks.map((task) => [task.taskId, task]));
+    for (const task of tasks) {
+        if (ids.has(task.taskId)) {
+            errors.push(`duplicate taskId: ${task.taskId}`);
+        }
+        ids.add(task.taskId);
+        for (const dep of task.deps) {
+            if (!tasksById.has(dep)) {
+                errors.push(`missing dependency: ${task.taskId} -> ${dep}`);
+            }
+        }
+    }
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (taskId) => {
+        if (visited.has(taskId)) {
+            return;
+        }
+        if (visiting.has(taskId)) {
+            errors.push(`cycle detected at taskId: ${taskId}`);
+            return;
+        }
+        visiting.add(taskId);
+        const task = tasksById.get(taskId);
+        if (task) {
+            for (const dep of task.deps) {
+                visit(dep);
+            }
+        }
+        visiting.delete(taskId);
+        visited.add(taskId);
+    };
+    tasks.forEach((task) => visit(task.taskId));
+    return { ok: errors.length === 0, errors };
+}
+export function getRunnableTasks(tasks) {
+    const taskStatus = new Map(tasks.map((task) => [task.taskId, task.status]));
+    return tasks.filter((task) => {
+        if (task.status !== "planned" && task.status !== "ready") {
+            return false;
+        }
+        return task.deps.every((dep) => taskStatus.get(dep) === "done");
+    }).map((task) => ({
+        ...task,
+        status: task.status === "planned" ? "ready" : task.status,
+    }));
+}
+export function upsertTaskStatuses(tasks) {
+    const runnableIds = new Set(getRunnableTasks(tasks).map((task) => task.taskId));
+    return tasks.map((task) => {
+        if (task.status === "planned" && runnableIds.has(task.taskId)) {
+            return { ...task, status: "ready" };
+        }
+        return task;
+    });
+}

package/dist/src/reporting/obsidian-journal.d.ts

@@ -0,0 +1,7 @@
+import type { ObsidianJournalConfig } from "../config.js";
+import type { SwarmPaths } from "../lib/paths.js";
+import type { RunRecord, SpecDoc, WorkflowState } from "../types.js";
+export declare function journalRunEntry(paths: SwarmPaths, journal: ObsidianJournalConfig, runRecord: RunRecord): Promise<void>;
+export declare function journalReviewEntry(paths: SwarmPaths, journal: ObsidianJournalConfig, taskId: string, decision: "approve" | "reject", note?: string): Promise<void>;
+export declare function journalSpecArchive(paths: SwarmPaths, journal: ObsidianJournalConfig, spec: SpecDoc): Promise<void>;
+export declare function journalCompletionSummary(paths: SwarmPaths, journal: ObsidianJournalConfig, workflow: WorkflowState, runs: RunRecord[]): Promise<void>;

package/dist/src/reporting/obsidian-journal.js

@@ -0,0 +1,126 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ensureDir } from "../lib/json-file.js";
+function timestamp() {
+    return new Date().toISOString().replace("T", " ").slice(0, 19);
+}
+async function ensureTableFile(filePath, header, columns) {
+    await ensureDir(path.dirname(filePath));
+    try {
+        await fs.access(filePath);
+    }
+    catch {
+        await fs.writeFile(filePath, `# ${header}\n\n${columns}\n`, "utf8");
+    }
+}
+async function appendToFile(filePath, line) {
+    await fs.appendFile(filePath, `${line}\n`, "utf8");
+}
+/**
+ * Write to local path first, then async-mirror to Obsidian if configured.
+ * Local write is synchronous (awaited). Obsidian write is fire-and-forget.
+ */
+async function dualWrite(localPath, obsidianPath, content, init) {
+    // Local: always write
+    await ensureTableFile(localPath, init.header, init.columns);
+    await appendToFile(localPath, content);
+    // Obsidian: async mirror (fire-and-forget)
+    if (obsidianPath) {
+        ensureTableFile(obsidianPath, init.header, init.columns)
+            .then(() => appendToFile(obsidianPath, content))
+            .catch(() => { });
+    }
+}
+async function dualWriteFile(localPath, obsidianPath, content) {
+    await ensureDir(path.dirname(localPath));
+    await fs.writeFile(localPath, content, "utf8");
+    if (obsidianPath) {
+        ensureDir(path.dirname(obsidianPath))
+            .then(() => fs.writeFile(obsidianPath, content, "utf8"))
+            .catch(() => { });
+    }
+}
+// --- Run Log ---
+export async function journalRunEntry(paths, journal, runRecord) {
+    if (!journal.enableRunLog)
+        return;
+    const line = `| ${timestamp()} | \`${runRecord.runId}\` | ${runRecord.taskId} | ${runRecord.runner.type} | ${runRecord.status} | ${runRecord.resultSummary?.slice(0, 80) ?? ""} |`;
+    const init = {
+        header: "Run Log",
+        columns: "| Time | Run ID | Task | Runner | Status | Summary |\n|------|--------|------|--------|--------|---------|",
+    };
+    await dualWrite(paths.localRunLogPath, paths.obsidianRunLogPath, line, init);
+}
+// --- Review Log ---
+export async function journalReviewEntry(paths, journal, taskId, decision, note) {
+    if (!journal.enableReviewLog)
+        return;
+    const noteText = note ?? "";
+    const line = `| ${timestamp()} | ${taskId} | **${decision}** | ${noteText} |`;
+    const init = {
+        header: "Review Log",
+        columns: "| Time | Task | Decision | Note |\n|------|------|----------|------|",
+    };
+    await dualWrite(paths.localReviewLogPath, paths.obsidianReviewLogPath, line, init);
+}
+// --- Spec Archive ---
+export async function journalSpecArchive(paths, journal, spec) {
+    if (!journal.enableSpecArchive)
+        return;
+    const content = [
+        `# ${spec.title}`,
+        ``,
+        `> Archived from \`${path.basename(spec.sourcePath)}\` at ${timestamp()}`,
+        ``,
+        `## Goals`,
+        ...spec.goals.map((g) => `- ${g}`),
+        ``,
+        ...(spec.constraints.length > 0
+            ? [`## Constraints`, ...spec.constraints.map((c) => `- ${c}`), ``]
+            : []),
+        ...(spec.acceptanceCriteria.length > 0
+            ? [`## Acceptance Criteria`, ...spec.acceptanceCriteria.map((a) => `- ${a}`), ``]
+            : []),
+        `## Phases`,
+        ...spec.phases.flatMap((p) => [`### ${p.title}`, ...p.tasks.map((t) => `- ${t}`), ``]),
+    ].join("\n");
+    const localPath = path.join(paths.localSpecsArchiveDir, `${spec.specId}.md`);
+    const obsidianPath = paths.obsidianSpecsDir ? path.join(paths.obsidianSpecsDir, `${spec.specId}.md`) : undefined;
+    await dualWriteFile(localPath, obsidianPath, content);
+}
+// --- Completion Summary ---
+export async function journalCompletionSummary(paths, journal, workflow, runs) {
+    if (!journal.enableCompletionSummary)
+        return;
+    const doneTasks = workflow.tasks.filter((t) => t.status === "done").length;
+    const totalTasks = workflow.tasks.length;
+    const deadLetterTasks = workflow.tasks.filter((t) => t.status === "dead_letter").length;
+    const totalRuns = runs.length;
+    const completedRuns = runs.filter((r) => r.status === "completed").length;
+    const failedRuns = runs.filter((r) => r.status === "failed" || r.status === "timed_out").length;
+    const content = [
+        `# Completion Summary`,
+        ``,
+        `> Generated at ${timestamp()}`,
+        ``,
+        `## Workflow`,
+        `- Spec: ${workflow.activeSpecId ?? "(none)"}`,
+        `- Lifecycle: ${workflow.lifecycle}`,
+        `- Tasks: ${doneTasks}/${totalTasks} done${deadLetterTasks > 0 ? `, ${deadLetterTasks} dead letter` : ""}`,
+        ``,
+        `## Execution`,
+        `- Total runs: ${totalRuns}`,
+        `- Completed: ${completedRuns}`,
+        `- Failed/Timed out: ${failedRuns}`,
+        ``,
+        `## Tasks`,
+        ...workflow.tasks.map((t) => `- **${t.title}** — \`${t.status}\` (${t.runner.type})`),
+        ``,
+        `## Timeline`,
+        ...runs
+            .sort((a, b) => a.startedAt.localeCompare(b.startedAt))
+            .map((r) => `- ${r.startedAt.slice(0, 19)} — \`${r.runId}\` ${r.runner.type} [${r.status}]${r.resultSummary ? ` — ${r.resultSummary.slice(0, 60)}` : ""}`),
+        ``,
+    ].join("\n");
+    await dualWriteFile(paths.localCompletionPath, paths.obsidianCompletionPath, content);
+}

package/dist/src/reporting/operator-summary.d.ts

@@ -0,0 +1,32 @@
+import type { RunRecord, WorkflowState } from "../types.js";
+export type ReviewQueueItem = {
+    taskId: string;
+    title?: string;
+    status?: string;
+    latestRunId?: string;
+    latestRunStatus?: string;
+    latestRunSummary?: string;
+    recommendedAction?: string;
+};
+export type AttentionItem = {
+    kind: "review" | "blocked" | "running" | "dead_letter";
+    taskId: string;
+    title?: string;
+    message: string;
+    latestRunId?: string;
+    latestRunStatus?: string;
+    latestRunSummary?: string;
+    recommendedAction: string;
+};
+export type OperatorHighlight = {
+    kind: "completed" | "failed" | "cancelled" | "timed_out";
+    runId: string;
+    taskId: string;
+    runner: string;
+    summary?: string;
+    recommendedAction: string;
+};
+export declare function buildReviewQueueItems(workflow: WorkflowState, runs: RunRecord[]): ReviewQueueItem[];
+export declare function buildAttentionItems(workflow: WorkflowState, runs: RunRecord[]): AttentionItem[];
+export declare function buildOperatorHighlights(runs: RunRecord[]): OperatorHighlight[];
+export declare function buildRecommendedActions(workflow: WorkflowState, runs: RunRecord[]): string[];

package/dist/src/reporting/operator-summary.js

@@ -0,0 +1,124 @@
+function buildLatestRunByTask(runs) {
+    const latestRunByTask = new Map();
+    for (const run of [...runs].sort((left, right) => right.startedAt.localeCompare(left.startedAt))) {
+        if (!latestRunByTask.has(run.taskId)) {
+            latestRunByTask.set(run.taskId, run);
+        }
+    }
+    return latestRunByTask;
+}
+function toReviewQueueItem(task, latestRun) {
+    return {
+        taskId: task?.taskId ?? "(unknown)",
+        title: task?.title,
+        status: task?.status,
+        latestRunId: latestRun?.runId,
+        latestRunStatus: latestRun?.status,
+        latestRunSummary: latestRun?.resultSummary,
+        recommendedAction: "Review the latest run outcome and approve or reject the task.",
+    };
+}
+export function buildReviewQueueItems(workflow, runs) {
+    const latestRunByTask = buildLatestRunByTask(runs);
+    return workflow.reviewQueue.map((taskId) => {
+        const task = workflow.tasks.find((entry) => entry.taskId === taskId);
+        return toReviewQueueItem(task, latestRunByTask.get(taskId));
+    });
+}
+export function buildAttentionItems(workflow, runs) {
+    const latestRunByTask = buildLatestRunByTask(runs);
+    const items = [];
+    for (const taskId of workflow.reviewQueue) {
+        const task = workflow.tasks.find((entry) => entry.taskId === taskId);
+        const latestRun = latestRunByTask.get(taskId);
+        items.push({
+            kind: "review",
+            taskId,
+            title: task?.title,
+            message: `Review required for ${task?.title ?? taskId}`,
+            latestRunId: latestRun?.runId,
+            latestRunStatus: latestRun?.status,
+            latestRunSummary: latestRun?.resultSummary,
+            recommendedAction: "Open the latest run summary, inspect artifacts, then approve or reject the task.",
+        });
+    }
+    for (const task of workflow.tasks.filter((entry) => entry.status === "blocked")) {
+        const latestRun = latestRunByTask.get(task.taskId);
+        items.push({
+            kind: "blocked",
+            taskId: task.taskId,
+            title: task.title,
+            message: `Task is blocked: ${task.title}`,
+            latestRunId: latestRun?.runId,
+            latestRunStatus: latestRun?.status,
+            latestRunSummary: latestRun?.resultSummary,
+            recommendedAction: "Inspect the blocking outcome, fix the issue, then rerun or explicitly reject/close the task.",
+        });
+    }
+    for (const task of workflow.tasks.filter((entry) => entry.status === "dead_letter")) {
+        const latestRun = latestRunByTask.get(task.taskId);
+        items.push({
+            kind: "dead_letter",
+            taskId: task.taskId,
+            title: task.title,
+            message: `Task exhausted all retries: ${task.title}`,
+            latestRunId: latestRun?.runId,
+            latestRunStatus: latestRun?.status,
+            latestRunSummary: latestRun?.resultSummary,
+            recommendedAction: "Review retry history, fix the root cause, then manually reset and rerun the task.",
+        });
+    }
+    for (const task of workflow.tasks.filter((entry) => entry.status === "running")) {
+        const latestRun = latestRunByTask.get(task.taskId);
+        items.push({
+            kind: "running",
+            taskId: task.taskId,
+            title: task.title,
+            message: `Task is still running: ${task.title}`,
+            latestRunId: latestRun?.runId,
+            latestRunStatus: latestRun?.status,
+            latestRunSummary: latestRun?.resultSummary,
+            recommendedAction: "Poll session status again or wait for completion before taking review action.",
+        });
+    }
+    return items;
+}
+export function buildOperatorHighlights(runs) {
+    const wantedStatuses = new Set(["completed", "failed", "cancelled", "timed_out"]);
+    const seen = new Set();
+    const highlights = [];
+    for (const run of [...runs].sort((left, right) => right.startedAt.localeCompare(left.startedAt))) {
+        if (!wantedStatuses.has(run.status)) {
+            continue;
+        }
+        if (seen.has(run.status)) {
+            continue;
+        }
+        seen.add(run.status);
+        highlights.push({
+            kind: run.status,
+            runId: run.runId,
+            taskId: run.taskId,
+            runner: run.runner.type,
+            summary: run.resultSummary,
+            recommendedAction: run.status === "completed"
+                ? "Inspect the completion summary and clear review items if the outcome is acceptable."
+                : run.status === "failed"
+                    ? "Inspect the failure summary, fix the issue, then rerun or reject the task."
+                    : run.status === "cancelled"
+                        ? "Confirm whether cancellation was intentional, then either unblock or rerun the task."
+                        : "Inspect the timeout context and decide whether to retry with a larger timeout.",
+        });
+    }
+    return highlights;
+}
+export function buildRecommendedActions(workflow, runs) {
+    const actions = new Set();
+    for (const item of buildAttentionItems(workflow, runs)) {
+        actions.add(item.recommendedAction);
+    }
+    for (const item of buildOperatorHighlights(runs)) {
+        actions.add(item.recommendedAction);
+    }
+    return [...actions];
+}

package/dist/src/reporting/reporter.d.ts

@@ -0,0 +1,10 @@
+import type { SwarmPluginConfig } from "../config.js";
+import type { RunRecord, WorkflowState } from "../types.js";
+import { StateStore } from "../state/state-store.js";
+export type ReportWriteResult = {
+    report: string;
+    localReportPath: string;
+    obsidianReportPath?: string;
+};
+export declare function buildWorkflowReport(workflow: WorkflowState, stateStore?: StateStore, runs?: RunRecord[]): string;
+export declare function writeWorkflowReport(projectRoot: string, workflow: WorkflowState, config?: Partial<SwarmPluginConfig>): Promise<ReportWriteResult>;

package/dist/src/reporting/reporter.js

@@ -0,0 +1,128 @@
+import path from "node:path";
+import { ensureDir } from "../lib/json-file.js";
+import { resolveSwarmPaths } from "../lib/paths.js";
+import { buildAttentionItems, buildOperatorHighlights, buildRecommendedActions, buildReviewQueueItems } from "./operator-summary.js";
+import { SessionStore } from "../session/session-store.js";
+import { summarizeSessionReuseForTask } from "../session/session-selector.js";
+import { StateStore } from "../state/state-store.js";
+import fs from "node:fs/promises";
+function buildRunLines(runs) {
+    const sorted = [...runs].sort((left, right) => right.startedAt.localeCompare(left.startedAt)).slice(0, 5);
+    return sorted.map((run) => {
+        const summary = run.resultSummary?.trim();
+        const suffix = summary ? ` - ${summary}` : "";
+        return `- ${run.runId}: ${run.runner.type} [${run.status}]${suffix}`;
+    });
+}
+function buildReviewQueueLines(workflow, runs) {
+    return buildReviewQueueItems(workflow, runs).map((item) => {
+        const suffix = item.latestRunSummary ? ` - ${item.latestRunSummary}` : "";
+        return `- ${item.taskId}: ${item.title ?? "(unknown task)"}${suffix}`;
+    });
+}
+function buildAttentionLines(workflow, runs) {
+    return buildAttentionItems(workflow, runs).map((item) => {
+        const suffix = item.latestRunSummary ? ` - ${item.latestRunSummary}` : "";
+        return `- [${item.kind}] ${item.taskId}: ${item.message}${suffix} | Action: ${item.recommendedAction}`;
+    });
+}
+function buildHighlightLines(runs) {
+    return buildOperatorHighlights(runs).map((item) => {
+        const suffix = item.summary ? ` - ${item.summary}` : "";
+        return `- [${item.kind}] ${item.runId}: ${item.runner}/${item.taskId}${suffix} | Action: ${item.recommendedAction}`;
+    });
+}
+function buildRecommendedActionLines(workflow, runs) {
+    return buildRecommendedActions(workflow, runs).map((action) => `- ${action}`);
+}
+function buildSessionLines(sessions) {
+    return [...sessions]
+        .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))
+        .slice(0, 5)
+        .map((session) => {
+        const suffix = session.summary ? ` - ${session.summary}` : "";
+        return `- ${session.sessionId}: ${session.runner}/${session.mode} [${session.state}]${suffix}`;
+    });
+}
+function buildSessionCandidateLines(workflow, sessions) {
+    return workflow.tasks.map((task) => {
+        const candidate = summarizeSessionReuseForTask(task, sessions);
+        const binding = candidate.bindingKey ? ` binding=${candidate.bindingKey}` : "";
+        const selected = candidate.selectedSessionId ? ` selected=${candidate.selectedSessionId}` : "";
+        return `- ${task.taskId}: policy=${candidate.policy} eligible=${candidate.eligible}${binding}${selected} - ${candidate.reason}`;
+    });
+}
+export function buildWorkflowReport(workflow, stateStore = new StateStore(), runs = []) {
+    const summary = stateStore.summarizeWorkflow(workflow);
+    const taskLines = workflow.tasks.map((task) => `- ${task.taskId}: ${task.title} [${task.status}]${task.review.required ? " review" : ""}`);
+    const runLines = buildRunLines(runs);
+    const reviewQueueLines = buildReviewQueueLines(workflow, runs);
+    const attentionLines = buildAttentionLines(workflow, runs);
+    const highlightLines = buildHighlightLines(runs);
+    const recommendedActionLines = buildRecommendedActionLines(workflow, runs);
+    return [
+        `# Swarm Report`,
+        ``,
+        `- Project: ${path.basename(workflow.projectRoot)}`,
+        `- Lifecycle: ${summary.lifecycle}`,
+        `- Active spec: ${summary.activeSpecId ?? "(none)"}`,
+        `- Total tasks: ${summary.totalTasks}`,
+        `- Ready tasks: ${summary.readyTasks}`,
+        `- Running tasks: ${summary.runningTasks}`,
+        `- Blocked tasks: ${summary.blockedTasks}`,
+        `- Dead letter tasks: ${summary.deadLetterTasks}`,
+        `- Review queue: ${summary.reviewQueueSize}`,
+        ...(workflow.lastAction
+            ? [
+                `- Last action: ${workflow.lastAction.type}${workflow.lastAction.message ? ` - ${workflow.lastAction.message}` : ""}`,
+            ]
+            : []),
+        ``,
+        `## Attention`,
+        ...(attentionLines.length > 0 ? attentionLines : ["- (none)"]),
+        ``,
+        `## Tasks`,
+        ...(taskLines.length > 0 ? taskLines : ["- (none)"]),
+        ``,
+        `## Review Queue`,
+        ...(reviewQueueLines.length > 0 ? reviewQueueLines : ["- (none)"]),
+        ``,
+        `## Highlights`,
+        ...(highlightLines.length > 0 ? highlightLines : ["- (none)"]),
+        ``,
+        `## Recommended Actions`,
+        ...(recommendedActionLines.length > 0 ? recommendedActionLines : ["- (none)"]),
+        ``,
+        `## Recent Runs`,
+        ...(runLines.length > 0 ? runLines : ["- (none)"]),
+    ].join("\n");
+}
+export async function writeWorkflowReport(projectRoot, workflow, config) {
+    const paths = resolveSwarmPaths(projectRoot, config);
+    const stateStore = new StateStore(config);
+    const sessionStore = new SessionStore(config);
+    const runs = await stateStore.loadRuns(projectRoot);
+    const sessions = await sessionStore.listSessions(projectRoot);
+    const report = buildWorkflowReport(workflow, stateStore, runs);
+    const sessionCandidateLines = buildSessionCandidateLines(workflow, sessions);
+    const reportWithSessions = [
+        report,
+        ``,
+        `## Sessions`,
+        ...(buildSessionLines(sessions).length > 0 ? buildSessionLines(sessions) : ["- (none)"]),
+        ``,
+        `## Session Reuse Candidates`,
+        ...(sessionCandidateLines.length > 0 ? sessionCandidateLines : ["- (none)"]),
+    ].join("\n");
+    await ensureDir(paths.reportsDir);
+    await fs.writeFile(paths.localReportPath, `${reportWithSessions}\n`, "utf8");
+    if (paths.obsidianReportPath) {
+        await ensureDir(path.dirname(paths.obsidianReportPath));
+        await fs.writeFile(paths.obsidianReportPath, `${reportWithSessions}\n`, "utf8");
+    }
+    return {
+        report: reportWithSessions,
+        localReportPath: paths.localReportPath,
+        obsidianReportPath: paths.obsidianReportPath,
+    };
+}

package/dist/src/review/review-gate.d.ts

@@ -0,0 +1,15 @@
+import type { RunRecord, TaskNode, WorkflowState } from "../types.js";
+export type ReviewDecision = "approve" | "reject";
+export type ReviewResult = {
+    workflow: WorkflowState;
+    task: TaskNode;
+    runRecord?: RunRecord;
+};
+export declare function enqueueReview(workflow: WorkflowState, taskId: string): WorkflowState;
+export declare function applyAcpRunStatusToWorkflow(workflow: WorkflowState, params: {
+    taskId: string;
+    runStatus: RunRecord["status"];
+    summary?: string;
+    at?: string;
+}): WorkflowState;
+export declare function applyReviewDecision(workflow: WorkflowState, taskId: string, decision: ReviewDecision, note?: string): ReviewResult;

package/dist/src/review/review-gate.js

@@ -0,0 +1,116 @@
+export function enqueueReview(workflow, taskId) {
+    if (workflow.reviewQueue.includes(taskId)) {
+        return workflow;
+    }
+    return {
+        ...workflow,
+        lifecycle: "reviewing",
+        reviewQueue: [...workflow.reviewQueue, taskId],
+    };
+}
+export function applyAcpRunStatusToWorkflow(workflow, params) {
+    const task = workflow.tasks.find((entry) => entry.taskId === params.taskId);
+    if (!task) {
+        throw new Error(`Unknown taskId: ${params.taskId}`);
+    }
+    const actionTime = params.at ?? new Date().toISOString();
+    function withLastAction(nextWorkflow, type, message) {
+        return {
+            ...nextWorkflow,
+            lastAction: {
+                at: actionTime,
+                type,
+                message,
+            },
+        };
+    }
+    let nextTask = task;
+    let nextWorkflow = workflow;
+    if (params.runStatus === "accepted" || params.runStatus === "running") {
+        nextTask = {
+            ...task,
+            status: "running",
+        };
+        nextWorkflow = {
+            ...workflow,
+            lifecycle: "running",
+            tasks: workflow.tasks.map((entry) => (entry.taskId === task.taskId ? nextTask : entry)),
+        };
+        return withLastAction(nextWorkflow, `run:${params.runStatus}`, params.summary);
+    }
+    if (params.runStatus === "completed") {
+        nextTask = {
+            ...task,
+            status: task.review.required ? "review_required" : "done",
+            review: {
+                ...task.review,
+                status: task.review.required ? "pending" : task.review.status,
+            },
+        };
+        nextWorkflow = {
+            ...workflow,
+            lifecycle: task.review.required ? "reviewing" : "planned",
+            tasks: workflow.tasks.map((entry) => (entry.taskId === task.taskId ? nextTask : entry)),
+        };
+        const queued = task.review.required ? enqueueReview(nextWorkflow, task.taskId) : nextWorkflow;
+        return withLastAction(queued, `run:${params.runStatus}`, params.summary);
+    }
+    if (params.runStatus === "failed" || params.runStatus === "timed_out") {
+        nextTask = {
+            ...task,
+            status: "review_required",
+            review: {
+                ...task.review,
+                status: "pending",
+            },
+        };
+        nextWorkflow = {
+            ...workflow,
+            lifecycle: "reviewing",
+            tasks: workflow.tasks.map((entry) => (entry.taskId === task.taskId ? nextTask : entry)),
+        };
+        return withLastAction(enqueueReview(nextWorkflow, task.taskId), `run:${params.runStatus}`, params.summary);
+    }
+    if (params.runStatus === "cancelled") {
+        nextTask = {
+            ...task,
+            status: "blocked",
+        };
+        return withLastAction({
+            ...workflow,
+            lifecycle: "blocked",
+            tasks: workflow.tasks.map((entry) => (entry.taskId === task.taskId ? nextTask : entry)),
+            reviewQueue: workflow.reviewQueue.filter((entry) => entry !== task.taskId),
+        }, `run:${params.runStatus}`, params.summary);
+    }
+    return workflow;
+}
+export function applyReviewDecision(workflow, taskId, decision, note) {
+    const task = workflow.tasks.find((entry) => entry.taskId === taskId);
+    if (!task) {
+        throw new Error(`Unknown taskId: ${taskId}`);
+    }
+    const updatedTask = {
+        ...task,
+        status: decision === "approve" ? "done" : "blocked",
+        review: {
+            ...task.review,
+            status: decision === "approve" ? "approved" : "rejected",
+        },
+    };
+    const nextWorkflow = {
+        ...workflow,
+        lifecycle: decision === "approve" ? "planned" : "blocked",
+        tasks: workflow.tasks.map((entry) => (entry.taskId === taskId ? updatedTask : entry)),
+        reviewQueue: workflow.reviewQueue.filter((entry) => entry !== taskId),
+        lastAction: {
+            at: new Date().toISOString(),
+            type: `review:${decision}`,
+            message: note,
+        },
+    };
+    return {
+        workflow: nextWorkflow,
+        task: updatedTask,
+    };
+}