@tingrudeng/worker-review-orchestrator-cli 0.1.0-beta.1

package/PUBLISHING.md

@@ -0,0 +1,32 @@
+# Publishing @tingrudeng/worker-review-orchestrator-cli
+
+## Release Gate
+
+Before publishing:
+
+```bash
+pnpm --filter @tingrudeng/worker-review-orchestrator-cli typecheck
+pnpm --filter @tingrudeng/worker-review-orchestrator-cli test
+pnpm --filter @tingrudeng/worker-review-orchestrator-cli build
+git diff --check
+```
+
+If the package behavior depends on live dispatcher flows, also run the relevant focused dispatcher tests from the repository root.
+
+## Publish
+
+Build and publish from the repository root:
+
+```bash
+pnpm --filter @tingrudeng/worker-review-orchestrator-cli build
+pnpm --filter @tingrudeng/worker-review-orchestrator-cli publish --access public --no-git-checks
+```
+
+## Intended Install Shape
+
+After publish, users should be able to install the CLI globally with:
+
+```bash
+npm install -g @tingrudeng/worker-review-orchestrator-cli
+forgeflow-review-orchestrator --help
+```

package/README.md

@@ -0,0 +1,68 @@
+# @tingrudeng/worker-review-orchestrator-cli
+
+ForgeFlow control-layer CLI for dispatching tasks to workers, watching their status, and submitting review decisions.
+
+## Install
+
+Preferred global install after publish:
+
+```bash
+npm install -g @tingrudeng/worker-review-orchestrator-cli
+forgeflow-review-orchestrator --help
+```
+
+Repository-local fallback:
+
+```bash
+pnpm --filter @tingrudeng/worker-review-orchestrator-cli build
+node packages/worker-review-orchestrator-cli/dist/cli.js --help
+```
+
+This package is meant to pair with the `worker-review-orchestrator` skill, but it is installed separately from the skill itself.
+
+## Commands
+
+- `dispatch`
+  - POST a dispatch payload to `/api/dispatches`
+  - Supports `--target-worker-id` to pin all tasks in the payload to one worker
+- `dispatch-task`
+  - Build and POST a single-task dispatch payload from CLI flags
+  - Preferred when the control layer wants to send one focused task without hand-writing `dispatch.json`
+  - Supports `--worker-prompt` and `--context-markdown` for inline string inputs
+  - Does NOT support file paths for prompt or context; use `--worker-prompt` or `--context-markdown` with literal strings
+- `watch`
+  - Poll `/api/dashboard/snapshot` until a task reaches `review`, `failed`, `merged`, or `blocked`
+- `decide`
+  - Submit `merge` or `block` decisions through the dispatcher review flow
+  - Supports dispatcher HTTP or local `state-dir` fallback
+  - Optional parameters: `--actor`, `--notes`, `--at`
+- `inspect`
+  - Retrieve review material for a task from the dispatcher snapshot
+  - Fetches task, assignment, reviews, pull request, and events to help a control-layer reviewer summarize before merge/block decision
+  - Use `--summary` flag to get concise output with task status, branch, worker, result evidence, recent events, and review/PR state
+
+## Current Boundary
+
+- This package only orchestrates existing ForgeFlow dispatcher flows.
+- It does not implement worker execution.
+- It does not rewrite task state arbitrarily.
+
+## Minimal Use
+
+```bash
+forgeflow-review-orchestrator dispatch --dispatcher-url http://127.0.0.1:8787 --input dispatch.json
+forgeflow-review-orchestrator dispatch --dispatcher-url http://127.0.0.1:8787 --input dispatch.json --target-worker-id trae-remote-forgeflow
+forgeflow-review-orchestrator dispatch-task --dispatcher-url http://127.0.0.1:8787 --repo TingRuDeng/ForgeFlow --default-branch main --task-id task-1 --title "Update docs" --pool trae --branch-name ai/trae/task-1 --allowed-paths docs/**,README.md --acceptance "pnpm typecheck,git diff --check" --target-worker-id trae-remote-forgeflow
+forgeflow-review-orchestrator dispatch-task --dispatcher-url http://127.0.0.1:8787 --repo TingRuDeng/ForgeFlow --default-branch main --task-id task-1 --title "Refactor auth" --pool codex --branch-name ai/codex/auth --allowed-paths "packages/auth/**" --acceptance "pnpm typecheck" --worker-prompt "You are a codex worker. Refactor the auth module." --context-markdown "# Context\n\nFocus on packages/auth only."
+forgeflow-review-orchestrator watch --dispatcher-url http://127.0.0.1:8787 --task-id dispatch-1:task-1
+forgeflow-review-orchestrator decide --dispatcher-url http://127.0.0.1:8787 --task-id dispatch-1:task-1 --decision merge
+forgeflow-review-orchestrator decide --state-dir /path/to/.forgeflow-dispatcher --task-id dispatch-1:task-1 --decision block --notes "Scope exceeded"
+forgeflow-review-orchestrator inspect --dispatcher-url http://127.0.0.1:8787 --task-id dispatch-1:task-1
+forgeflow-review-orchestrator inspect --dispatcher-url http://127.0.0.1:8787 --task-id dispatch-1:task-1 --summary
+```
+
+When `--target-worker-id` is set, the CLI injects that worker id into every task and assignment package before posting the dispatch. This keeps the existing `dispatch.json` shape but gives the control layer an explicit way to target `trae-local-forgeflow` or `trae-remote-forgeflow`.
+
+Use `dispatch-task` for the common case of one worker task with one branch, one `allowedPaths` list, and one `acceptance` list. Keep `dispatch --input` for more complex multi-task or prebuilt payloads.
+
+For control-layer review flow, prefer this CLI over calling lower-level review-decision scripts directly. Keep the scripts as compatibility and implementation detail, but use `forgeflow-review-orchestrator decide` as the default operator entrypoint.

package/dist/cli.d.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { runDispatch } from "./dispatch.js";
+import { runDecide } from "./decide.js";
+import { runInspect } from "./inspect.js";
+import { runRedrive } from "./redrive.js";
+import { watchTask } from "./watch.js";
+export interface CliDeps {
+    runDispatch: typeof runDispatch;
+    watchTask: typeof watchTask;
+    runDecide: typeof runDecide;
+    runInspect: typeof runInspect;
+    runRedrive: typeof runRedrive;
+    log: (message: string) => void;
+}
+export interface ParsedCliArgs {
+    command: "dispatch" | "dispatch-task" | "watch" | "decide" | "inspect" | "redrive";
+    options: Record<string, string | number | boolean>;
+}
+export declare function parseCliArgs(argv: string[]): ParsedCliArgs;
+export declare function runCli(argv: string[], partialDeps?: Partial<CliDeps>): Promise<import("./types.js").DispatchResult | import("./types.js").WatchSummaryResult | import("./types.js").DecideResult | import("./types.js").InspectResult | import("./types.js").InspectSummaryResult | import("./types.js").RedriveResult | {
+    dryRun: boolean;
+    dispatcherUrl: string;
+    payload: import("./types.js").DispatchInput;
+} | null>;
+export declare function isCliEntrypoint(scriptPath?: string): boolean;

package/dist/cli.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { buildSingleTaskDispatchInput, runDispatch } from "./dispatch.js";
+import { runDecide } from "./decide.js";
+import { runInspect } from "./inspect.js";
+import { runRedrive } from "./redrive.js";
+import { watchTask } from "./watch.js";
+function parseValue(raw) {
+    if (raw === "true") {
+        return true;
+    }
+    if (raw === "false") {
+        return false;
+    }
+    if (/^-?\d+$/.test(raw)) {
+        return Number(raw);
+    }
+    return raw;
+}
+export function parseCliArgs(argv) {
+    const [command, ...rest] = argv;
+    if (!command) {
+        throw new Error("command is required");
+    }
+    if (!["dispatch", "dispatch-task", "watch", "decide", "inspect", "redrive"].includes(command)) {
+        throw new Error(`unknown command: ${command}`);
+    }
+    const options = {};
+    for (let index = 0; index < rest.length; index += 1) {
+        const arg = rest[index];
+        if (!arg || !arg.startsWith("--")) {
+            throw new Error(`unknown argument: ${arg}`);
+        }
+        const key = arg.slice(2).replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+        const next = rest[index + 1];
+        if (!next || next.startsWith("--")) {
+            options[key] = true;
+            continue;
+        }
+        options[key] = parseValue(next);
+        index += 1;
+    }
+    return {
+        command: command,
+        options,
+    };
+}
+function printHelp() {
+    console.log(`
+Usage:
+  forgeflow-review-orchestrator dispatch --dispatcher-url http://127.0.0.1:8787 --input dispatch.json
+  forgeflow-review-orchestrator dispatch --dispatcher-url http://127.0.0.1:8787 --input dispatch.json --target-worker-id trae-remote-forgeflow
+  forgeflow-review-orchestrator dispatch-task --dispatcher-url http://127.0.0.1:8787 --repo TingRuDeng/ForgeFlow --default-branch main --task-id task-1 --title "Update docs" --pool trae --branch-name ai/trae/task-1 --allowed-paths docs/**,README.md --acceptance "pnpm typecheck,git diff --check"
+  forgeflow-review-orchestrator dispatch-task --dispatcher-url http://127.0.0.1:8787 --repo TingRuDeng/ForgeFlow --default-branch main --task-id task-1 --title "Update docs" --pool trae --branch-name ai/trae/task-1 --worker-prompt-file prompts/worker.md --context-markdown-file context/task.md
+  forgeflow-review-orchestrator watch --dispatcher-url http://127.0.0.1:8787 --task-id dispatch-1:task-1
+  forgeflow-review-orchestrator watch --dispatcher-url http://127.0.0.1:8787 --task-id dispatch-1:task-1 --summary
+  forgeflow-review-orchestrator decide --dispatcher-url http://127.0.0.1:8787 --task-id dispatch-1:task-1 --decision merge
+  forgeflow-review-orchestrator decide --state-dir /path/to/.forgeflow-dispatcher --task-id dispatch-1:task-1 --decision block
+  forgeflow-review-orchestrator inspect --dispatcher-url http://127.0.0.1:8787 --task-id dispatch-1:task-1
+  forgeflow-review-orchestrator inspect --dispatcher-url http://127.0.0.1:8787 --task-id dispatch-1:task-1 --summary
+  forgeflow-review-orchestrator inspect --state-dir /path/to/.forgeflow-dispatcher --task-id dispatch-1:task-1
+  forgeflow-review-orchestrator inspect --state-dir /path/to/.forgeflow-dispatcher --task-id dispatch-1:task-1 --summary
+  forgeflow-review-orchestrator redrive --dispatcher-url http://127.0.0.1:8787 --task-id dispatch-1:task-1
+`);
+}
+export async function runCli(argv, partialDeps = {}) {
+    const deps = {
+        runDispatch,
+        watchTask,
+        runDecide,
+        runInspect,
+        runRedrive,
+        log: (message) => console.log(message),
+        ...partialDeps,
+    };
+    const parsed = parseCliArgs(argv);
+    const options = parsed.options;
+    if (options.help === true) {
+        printHelp();
+        return null;
+    }
+    if (parsed.command === "dispatch") {
+        const dispatcherUrl = typeof options.dispatcherUrl === "string" ? options.dispatcherUrl : undefined;
+        const input = typeof options.input === "string" ? options.input : "-";
+        if (!dispatcherUrl) {
+            throw new Error("--dispatcher-url is required");
+        }
+        const result = await deps.runDispatch({
+            dispatcherUrl,
+            input,
+            targetWorkerId: typeof options.targetWorkerId === "string" ? options.targetWorkerId : undefined,
+            requestTimeoutMs: typeof options.requestTimeoutMs === "number" ? options.requestTimeoutMs : undefined,
+        });
+        deps.log(JSON.stringify(result, null, 2));
+        return result;
+    }
+    if (parsed.command === "dispatch-task") {
+        const dispatcherUrl = typeof options.dispatcherUrl === "string" ? options.dispatcherUrl : undefined;
+        const repo = typeof options.repo === "string" ? options.repo : undefined;
+        const defaultBranch = typeof options.defaultBranch === "string" ? options.defaultBranch : undefined;
+        const taskId = typeof options.taskId === "string" ? options.taskId : undefined;
+        const title = typeof options.title === "string" ? options.title : undefined;
+        const pool = typeof options.pool === "string" ? options.pool : undefined;
+        const branchName = typeof options.branchName === "string" ? options.branchName : undefined;
+        if (!dispatcherUrl) {
+            throw new Error("--dispatcher-url is required");
+        }
+        if (!repo || !defaultBranch || !taskId || !title || !pool || !branchName) {
+            throw new Error("--repo, --default-branch, --task-id, --title, --pool, and --branch-name are required");
+        }
+        const payload = buildSingleTaskDispatchInput({
+            repo,
+            defaultBranch,
+            taskId,
+            title,
+            pool,
+            branchName,
+            requestedBy: typeof options.requestedBy === "string" ? options.requestedBy : undefined,
+            allowedPaths: typeof options.allowedPaths === "string" ? options.allowedPaths : undefined,
+            acceptance: typeof options.acceptance === "string" ? options.acceptance : undefined,
+            dependsOn: typeof options.dependsOn === "string" ? options.dependsOn : undefined,
+            targetWorkerId: typeof options.targetWorkerId === "string" ? options.targetWorkerId : undefined,
+            verificationMode: typeof options.verificationMode === "string" ? options.verificationMode : undefined,
+            workerPrompt: typeof options.workerPrompt === "string" ? options.workerPrompt : undefined,
+            contextMarkdown: typeof options.contextMarkdown === "string" ? options.contextMarkdown : undefined,
+            workerPromptFile: typeof options.workerPromptFile === "string" ? options.workerPromptFile : undefined,
+            contextMarkdownFile: typeof options.contextMarkdownFile === "string" ? options.contextMarkdownFile : undefined,
+        });
+        if (options.dryRun === true) {
+            const dryRunResult = { dryRun: true, dispatcherUrl, payload };
+            deps.log(JSON.stringify(dryRunResult, null, 2));
+            return dryRunResult;
+        }
+        const result = await deps.runDispatch({
+            dispatcherUrl,
+            input: "-",
+            payload,
+            requestTimeoutMs: typeof options.requestTimeoutMs === "number" ? options.requestTimeoutMs : undefined,
+        });
+        deps.log(JSON.stringify(result, null, 2));
+        return result;
+    }
+    if (parsed.command === "watch") {
+        const dispatcherUrl = typeof options.dispatcherUrl === "string" ? options.dispatcherUrl : undefined;
+        const taskId = typeof options.taskId === "string" ? options.taskId : undefined;
+        if (!dispatcherUrl) {
+            throw new Error("--dispatcher-url is required");
+        }
+        if (!taskId) {
+            throw new Error("--task-id is required");
+        }
+        const result = await deps.watchTask({
+            dispatcherUrl,
+            taskId,
+            intervalMs: typeof options.intervalMs === "number" ? options.intervalMs : undefined,
+            timeoutMs: typeof options.timeoutMs === "number" ? options.timeoutMs : undefined,
+            summary: options.summary === true,
+        });
+        deps.log(JSON.stringify(result, null, 2));
+        return result;
+    }
+    if (parsed.command === "decide") {
+        const taskId = typeof options.taskId === "string" ? options.taskId : undefined;
+        const decision = typeof options.decision === "string" ? options.decision : undefined;
+        if (!taskId) {
+            throw new Error("--task-id is required");
+        }
+        if (!decision) {
+            throw new Error("--decision is required");
+        }
+        const result = await deps.runDecide({
+            taskId,
+            decision: decision,
+            actor: typeof options.actor === "string" ? options.actor : undefined,
+            notes: typeof options.notes === "string" ? options.notes : undefined,
+            at: typeof options.at === "string" ? options.at : undefined,
+            dispatcherUrl: typeof options.dispatcherUrl === "string" ? options.dispatcherUrl : undefined,
+            stateDir: typeof options.stateDir === "string" ? options.stateDir : undefined,
+        });
+        deps.log(JSON.stringify(result, null, 2));
+        return result;
+    }
+    if (parsed.command === "inspect") {
+        const dispatcherUrl = typeof options.dispatcherUrl === "string" ? options.dispatcherUrl : undefined;
+        const taskId = typeof options.taskId === "string" ? options.taskId : undefined;
+        const stateDir = typeof options.stateDir === "string" ? options.stateDir : undefined;
+        if (!dispatcherUrl && !stateDir) {
+            throw new Error("--dispatcher-url or --state-dir is required");
+        }
+        if (!taskId) {
+            throw new Error("--task-id is required");
+        }
+        const result = await deps.runInspect({
+            dispatcherUrl,
+            taskId,
+            summary: options.summary === true,
+            stateDir,
+        });
+        deps.log(JSON.stringify(result, null, 2));
+        return result;
+    }
+    if (parsed.command === "redrive") {
+        const dispatcherUrl = typeof options.dispatcherUrl === "string" ? options.dispatcherUrl : undefined;
+        const taskId = typeof options.taskId === "string" ? options.taskId : undefined;
+        if (!dispatcherUrl) {
+            throw new Error("--dispatcher-url is required");
+        }
+        if (!taskId) {
+            throw new Error("--task-id is required");
+        }
+        const result = await deps.runRedrive({
+            dispatcherUrl,
+            taskId,
+        });
+        deps.log(JSON.stringify(result, null, 2));
+        return result;
+    }
+    throw new Error(`unknown command: ${parsed.command}`);
+}
+function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        printHelp();
+        return;
+    }
+    runCli(args).catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    });
+}
+export function isCliEntrypoint(scriptPath = process.argv[1]) {
+    if (!scriptPath) {
+        return false;
+    }
+    const resolvedPath = scriptPath.startsWith("file:")
+        ? fileURLToPath(scriptPath)
+        : scriptPath;
+    try {
+        return import.meta.url === pathToFileURL(fs.realpathSync(resolvedPath)).href;
+    }
+    catch {
+        return import.meta.url === pathToFileURL(resolvedPath).href;
+    }
+}
+if (isCliEntrypoint()) {
+    main();
+}

package/dist/decide.d.ts

@@ -0,0 +1,4 @@
+import type { DecideOptions, DecideResult } from "./types.js";
+export declare function runDecide(options: DecideOptions & {
+    fetchImpl?: typeof globalThis.fetch;
+}): Promise<DecideResult>;

package/dist/decide.js

@@ -0,0 +1,143 @@
+import path from "node:path";
+import { createJsonHttpClient, loadRuntimeState, saveRuntimeState } from "./http.js";
+function normalizeDecision(decision) {
+    if (decision === "merge") {
+        return "merge";
+    }
+    return "block";
+}
+function readNowIso() {
+    return new Date().toISOString();
+}
+function upsertByTaskId(items, payload) {
+    const index = items.findIndex((item) => item.taskId === payload.taskId);
+    if (index === -1) {
+        return [...items, payload];
+    }
+    const next = [...items];
+    next[index] = {
+        ...next[index],
+        ...payload,
+    };
+    return next;
+}
+function buildLocalDecisionState(state, input) {
+    const task = state.tasks.find((candidate) => candidate.id === input.taskId);
+    if (!task) {
+        throw new Error(`task not found: ${input.taskId}`);
+    }
+    const assignment = state.assignments.find((candidate) => candidate.taskId === input.taskId);
+    if (!assignment) {
+        throw new Error(`assignment not found: ${input.taskId}`);
+    }
+    if (task.status !== "review") {
+        throw new Error(`task not in review: ${input.taskId}`);
+    }
+    const nextStatus = input.decision === "merge" ? "merged" : "blocked";
+    const at = input.at || readNowIso();
+    const nextEvents = [
+        ...state.events,
+        {
+            taskId: input.taskId,
+            type: "status_changed",
+            at,
+            payload: {
+                from: "review",
+                to: nextStatus,
+            },
+        },
+    ];
+    const nextTasks = state.tasks.map((candidate) => candidate.id === input.taskId
+        ? {
+            ...candidate,
+            status: nextStatus,
+        }
+        : candidate);
+    const nextAssignments = state.assignments.map((candidate) => candidate.taskId === input.taskId
+        ? {
+            ...candidate,
+            status: nextStatus,
+            assignment: {
+                ...candidate.assignment,
+                status: nextStatus,
+            },
+        }
+        : candidate);
+    const nextReviews = upsertByTaskId(state.reviews, {
+        taskId: input.taskId,
+        decision: input.decision,
+        actor: input.actor ?? "codex-control",
+        notes: input.notes ?? "",
+        decidedAt: at,
+    });
+    const nextPullRequests = state.pullRequests.map((pullRequest) => pullRequest.taskId === input.taskId
+        ? {
+            ...pullRequest,
+            status: input.decision === "merge" ? "merged" : "changes_requested",
+            updatedAt: at,
+        }
+        : pullRequest);
+    const nextState = {
+        ...state,
+        updatedAt: at,
+        events: nextEvents,
+        tasks: nextTasks,
+        assignments: nextAssignments,
+        reviews: nextReviews,
+        pullRequests: nextPullRequests,
+    };
+    return {
+        state: nextState,
+        result: {
+            taskId: input.taskId,
+            decision: input.decision,
+            status: nextStatus,
+            actor: input.actor ?? "codex-control",
+            notes: input.notes ?? "",
+            at,
+            task,
+            assignment,
+        },
+    };
+}
+export async function runDecide(options) {
+    const decision = normalizeDecision(options.decision);
+    const payload = {
+        actor: options.actor ?? "codex-control",
+        decision,
+        notes: options.notes ?? "",
+        at: options.at ?? readNowIso(),
+    };
+    if (options.dispatcherUrl) {
+        const client = createJsonHttpClient(options.dispatcherUrl, {
+            fetchImpl: options.fetchImpl,
+        });
+        const result = await client.request(`/api/reviews/${encodeURIComponent(options.taskId)}/decision`, {
+            method: "POST",
+            body: payload,
+        });
+        return {
+            taskId: options.taskId,
+            decision,
+            status: decision === "merge" ? "merged" : "blocked",
+            source: "dispatcher",
+            payload: result,
+        };
+    }
+    if (!options.stateDir) {
+        throw new Error("dispatcherUrl or stateDir is required");
+    }
+    const state = loadRuntimeState(path.resolve(options.stateDir));
+    const result = buildLocalDecisionState(state, {
+        ...options,
+        decision,
+    });
+    saveRuntimeState(path.resolve(options.stateDir), result.state);
+    return {
+        taskId: options.taskId,
+        decision,
+        status: decision === "merge" ? "merged" : "blocked",
+        source: "state-dir",
+        payload: result.result,
+    };
+}

package/dist/dispatch.d.ts

@@ -0,0 +1,14 @@
+import type { DispatchInput, DispatchResult, DispatchTaskInputOptions } from "./types.js";
+export interface DispatchOptions {
+    dispatcherUrl: string;
+    input: string;
+    payload?: DispatchInput;
+    targetWorkerId?: string;
+    requestTimeoutMs?: number;
+    fetchImpl?: typeof globalThis.fetch;
+    readStdin?: () => Promise<string>;
+}
+export declare function loadDispatchInput(source: string, readStdin?: () => Promise<string>): Promise<DispatchInput>;
+export declare function buildSingleTaskDispatchInput(options: DispatchTaskInputOptions): DispatchInput;
+export declare function applyDispatchTargetWorker(payload: DispatchInput, targetWorkerId?: string): DispatchInput;
+export declare function runDispatch(options: DispatchOptions): Promise<DispatchResult>;

package/dist/dispatch.js

@@ -0,0 +1,105 @@
+import { createJsonHttpClient, readJsonInput } from "./http.js";
+import { readFileSync } from "node:fs";
+export async function loadDispatchInput(source, readStdin) {
+    return readJsonInput(source, { readStdin });
+}
+function splitCsv(input) {
+    return String(input || "")
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+function readFileContent(filePath) {
+    if (!filePath) {
+        return undefined;
+    }
+    try {
+        return readFileSync(filePath, "utf-8").trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+export function buildSingleTaskDispatchInput(options) {
+    const targetWorkerId = String(options.targetWorkerId || "").trim() || undefined;
+    const allowedPaths = splitCsv(options.allowedPaths);
+    const acceptance = splitCsv(options.acceptance);
+    const dependsOn = splitCsv(options.dependsOn);
+    const workerPromptFromFile = readFileContent(options.workerPromptFile);
+    const contextMarkdownFromFile = readFileContent(options.contextMarkdownFile);
+    const workerPrompt = workerPromptFromFile || options.workerPrompt || "You are a ForgeFlow worker. Stay within allowedPaths and satisfy acceptance.";
+    const contextMarkdown = contextMarkdownFromFile || options.contextMarkdown || "# Context\n\nComplete the assigned task within scope.";
+    return {
+        repo: options.repo,
+        defaultBranch: options.defaultBranch,
+        requestedBy: options.requestedBy || "codex-control",
+        tasks: [
+            {
+                id: options.taskId,
+                title: options.title,
+                pool: options.pool,
+                allowedPaths,
+                acceptance,
+                dependsOn,
+                branchName: options.branchName,
+                verification: {
+                    mode: String(options.verificationMode || "run"),
+                },
+                ...(targetWorkerId ? { targetWorkerId } : {}),
+                ...(options.continuationMode ? { continuationMode: options.continuationMode } : {}),
+                ...(options.continueFromTaskId ? { continueFromTaskId: options.continueFromTaskId } : {}),
+            },
+        ],
+        packages: [
+            {
+                taskId: options.taskId,
+                assignment: {
+                    taskId: options.taskId,
+                    workerId: null,
+                    pool: options.pool,
+                    status: "pending",
+                    branchName: options.branchName,
+                    allowedPaths,
+                    repo: options.repo,
+                    defaultBranch: options.defaultBranch,
+                    ...(targetWorkerId ? { targetWorkerId } : {}),
+                    ...(options.continuationMode ? { continuationMode: options.continuationMode } : {}),
+                    ...(options.continueFromTaskId ? { continueFromTaskId: options.continueFromTaskId } : {}),
+                },
+                workerPrompt,
+                contextMarkdown,
+            },
+        ],
+    };
+}
+function applyTargetWorkerToRecords(records, targetWorkerId) {
+    return records.map((record) => ({
+        ...record,
+        targetWorkerId,
+        target_worker_id: targetWorkerId,
+    }));
+}
+export function applyDispatchTargetWorker(payload, targetWorkerId) {
+    const normalizedTargetWorkerId = String(targetWorkerId || "").trim();
+    if (!normalizedTargetWorkerId) {
+        return payload;
+    }
+    return {
+        ...payload,
+        tasks: applyTargetWorkerToRecords(payload.tasks, normalizedTargetWorkerId),
+        packages: applyTargetWorkerToRecords(payload.packages, normalizedTargetWorkerId),
+    };
+}
+export async function runDispatch(options) {
+    const payload = options.payload
+        ? applyDispatchTargetWorker(options.payload, options.targetWorkerId)
+        : applyDispatchTargetWorker(await loadDispatchInput(options.input, options.readStdin), options.targetWorkerId);
+    const client = createJsonHttpClient(options.dispatcherUrl, {
+        fetchImpl: options.fetchImpl,
+        requestTimeoutMs: options.requestTimeoutMs,
+    });
+    return client.request("/api/dispatches", {
+        method: "POST",
+        body: payload,
+    });
+}

package/dist/http.d.ts

@@ -0,0 +1,10 @@
+import type { JsonHttpClientOptions, JsonHttpRequestOptions, LocalRuntimeState } from "./types.js";
+export declare function createJsonHttpClient(baseUrl: string, options?: JsonHttpClientOptions): {
+    request: (pathname: string, init?: JsonHttpRequestOptions) => Promise<any>;
+};
+export declare function createEmptyRuntimeState(): LocalRuntimeState;
+export declare function loadRuntimeState(stateDir: string): LocalRuntimeState;
+export declare function saveRuntimeState(stateDir: string, state: LocalRuntimeState): void;
+export declare function readJsonInput(source: string, options?: {
+    readStdin?: () => Promise<string>;
+}): Promise<any>;