rl-workspaces 0.0.0-stage → 0.5.0

package/dist/agent-runner.js

@@ -0,0 +1,366 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { git, gitRaw, now, object, sessionId, writeJson } from "./common.js";
+import { readJsonObject } from "./json.js";
+import { validateAutomation, } from "./automation-config.js";
+import { evaluate, validateResult, } from "./review-policy.js";
+import { agentAdapter } from "./agent-registry.js";
+export function captureScope(cwd, base) {
+    if (!base || base.startsWith("-") || /[\x00-\x20\x7f]/.test(base))
+        throw new Error("Expected a literal base ref");
+    const baseCommit = git(cwd, "rev-parse", "--verify", "--end-of-options", `${base}^{commit}`);
+    const head = git(cwd, "rev-parse", "HEAD");
+    const ancestor = git(cwd, "merge-base", head, baseCommit);
+    const patch = gitRaw(cwd, "diff", "--no-ext-diff", "--no-textconv", "--binary", ancestor, "--");
+    const stagedPatch = gitRaw(cwd, "diff", "--cached", "--no-ext-diff", "--no-textconv", "--binary", ancestor, "--");
+    const unstagedPatch = gitRaw(cwd, "diff", "--no-ext-diff", "--no-textconv", "--binary", "--");
+    const changed = gitRaw(cwd, "diff", "--no-ext-diff", "--no-textconv", "--name-only", "-z", ancestor, "--")
+        .split("\0")
+        .filter(Boolean);
+    const untracked = gitRaw(cwd, "ls-files", "--others", "--exclude-standard", "-z")
+        .split("\0")
+        .filter(Boolean);
+    const stagedFiles = gitRaw(cwd, "diff", "--cached", "--no-ext-diff", "--no-textconv", "--name-only", "-z", ancestor, "--")
+        .split("\0")
+        .filter(Boolean);
+    const unstagedFiles = gitRaw(cwd, "diff", "--no-ext-diff", "--no-textconv", "--name-only", "-z", "--")
+        .split("\0")
+        .filter(Boolean);
+    let size = Buffer.byteLength(patch) +
+        Buffer.byteLength(stagedPatch) +
+        Buffer.byteLength(unstagedPatch);
+    const additional = untracked.map((file) => {
+        const absolute = path.join(cwd, file), stat = fs.lstatSync(absolute);
+        size += stat.size;
+        if (size > 4 * 1024 * 1024)
+            throw new Error("Review scope exceeds 4 MiB; narrow the changes before running this workflow");
+        if (!stat.isFile() && !stat.isSymbolicLink())
+            throw new Error(`Unsupported untracked path: ${file}`);
+        return {
+            file,
+            mode: stat.mode & 0o777,
+            kind: stat.isSymbolicLink() ? "symlink" : "file",
+            content: stat.isSymbolicLink()
+                ? fs.readlinkSync(absolute)
+                : fs.readFileSync(absolute).toString("base64"),
+        };
+    });
+    if (size > 4 * 1024 * 1024)
+        throw new Error("Review scope exceeds 4 MiB");
+    const context = JSON.stringify({
+        head,
+        base,
+        baseCommit,
+        mergeBase: ancestor,
+        patch,
+        stagedPatch,
+        unstagedPatch,
+        untracked: additional,
+    });
+    return {
+        scope: {
+            base,
+            baseCommit,
+            head,
+            fingerprint: createHash("sha256").update(context).digest("hex"),
+            files: [
+                ...new Set([
+                    ...changed,
+                    ...stagedFiles,
+                    ...unstagedFiles,
+                    ...untracked,
+                ]),
+            ],
+        },
+        context,
+    };
+}
+function runDirectory(instanceFile, id) {
+    sessionId(id);
+    const parent = path.join(path.dirname(instanceFile), "workflow-runs");
+    const directory = path.join(parent, id);
+    for (const file of [parent, directory, path.join(directory, "run.json")])
+        if (fs.lstatSync(file, { throwIfNoEntry: false })?.isSymbolicLink())
+            throw new Error("Workflow state must not be a symlink");
+    return directory;
+}
+function load(directory) {
+    const raw = readJsonObject(path.join(directory, "run.json"));
+    if (raw.version !== 1 ||
+        typeof raw.id !== "string" ||
+        typeof raw.key !== "string" ||
+        typeof raw.workspace !== "string" ||
+        typeof raw.branch !== "string" ||
+        typeof raw.workflow !== "string" ||
+        typeof raw.createdAt !== "string" ||
+        typeof raw.updatedAt !== "string" ||
+        !["running", "paused", "cancelled", "completed"].includes(String(raw.status)) ||
+        (raw.controlRequested !== null &&
+            raw.controlRequested !== "pause" &&
+            raw.controlRequested !== "cancel") ||
+        typeof raw.routed !== "boolean" ||
+        typeof raw.prompt !== "string" ||
+        !object(raw.scope) ||
+        typeof raw.scope.fingerprint !== "string" ||
+        typeof raw.scope.base !== "string" ||
+        typeof raw.scope.head !== "string" ||
+        typeof raw.scope.baseCommit !== "string" ||
+        !Array.isArray(raw.scope.files) ||
+        raw.scope.files.some((file) => typeof file !== "string") ||
+        !Array.isArray(raw.stages) ||
+        !Array.isArray(raw.assessments))
+        throw new Error("Invalid workflow run metadata");
+    sessionId(raw.id);
+    if (raw.execution !== undefined && raw.execution !== "native")
+        throw new Error("Invalid workflow execution mode");
+    if (raw.execution === "native") {
+        if (!object(raw.owner) ||
+            !["codex", "claude"].includes(String(raw.owner.agent)))
+            throw new Error("Invalid workflow parent");
+        agentAdapter(raw.owner.agent).observedId(raw.owner.sessionId);
+        if (raw.requestId !== undefined)
+            sessionId(raw.requestId);
+    }
+    validateAutomation(raw.config);
+    if (!Object.hasOwn(raw.config.workflows, raw.workflow))
+        throw new Error("Invalid saved workflow");
+    const definition = raw.config.workflows[raw.workflow];
+    const seen = new Set();
+    for (const stage of raw.stages) {
+        if (!object(stage) ||
+            typeof stage.id !== "string" ||
+            !/^(?:followup-)?[a-z][a-z0-9_-]{0,63}$/.test(stage.id) ||
+            !["pending", "running", "completed", "failed", "blocked"].includes(String(stage.status)) ||
+            !Number.isSafeInteger(stage.attempts) ||
+            Number(stage.attempts) < 0 ||
+            typeof stage.durationMs !== "number" ||
+            stage.durationMs < 0 ||
+            !Array.isArray(stage.after))
+            throw new Error("Invalid workflow stage metadata");
+        if (seen.has(stage.id))
+            throw new Error("Duplicate saved workflow stage");
+        seen.add(stage.id);
+        const original = definition.steps.find((step) => step.id === stage.id || `followup-${step.id}` === stage.id);
+        if (!original ||
+            JSON.stringify(stage.command) !== JSON.stringify(original.command) ||
+            stage.agent !== original.agent ||
+            JSON.stringify(stage.after) !==
+                JSON.stringify(stage.id.startsWith("followup-") ? [original.id] : original.after))
+            throw new Error("Saved workflow stage does not match its configuration");
+        if (stage.claim !== undefined)
+            sessionId(stage.claim);
+        if (stage.scopeFingerprint !== undefined &&
+            typeof stage.scopeFingerprint !== "string")
+            throw new Error("Invalid stage scope fingerprint");
+        if (stage.startedAt !== undefined &&
+            (typeof stage.startedAt !== "string" ||
+                !Number.isFinite(Date.parse(stage.startedAt))))
+            throw new Error("Invalid stage start time");
+        if (raw.execution === "native" &&
+            stage.status === "running" &&
+            (stage.claim === undefined || stage.startedAt === undefined))
+            throw new Error("Running native stage is missing its claim");
+        if (stage.result !== undefined)
+            validateResult(stage.result);
+    }
+    if (raw.scope.files.length &&
+        definition.steps.some((step) => !seen.has(step.id)))
+        throw new Error("Saved workflow is missing configured steps");
+    return raw;
+}
+export function readRun(store, requested) {
+    const [file, data] = store.current();
+    let id = requested;
+    if (!id || id === "latest") {
+        const parent = path.dirname(runDirectory(file, "00000000-0000-0000-0000-000000000000"));
+        const entries = fs.existsSync(parent)
+            ? fs
+                .readdirSync(parent)
+                .filter((id) => /^[a-f0-9-]{36}$/.test(id))
+                .map((id) => load(runDirectory(file, id)))
+            : [];
+        id = entries.sort((a, b) => b.createdAt.localeCompare(a.createdAt))[0]?.id;
+        if (!id)
+            throw new Error("No workflow runs in this RL workspace");
+    }
+    const directory = runDirectory(file, id), run = load(directory);
+    if (run.id !== id ||
+        run.key !== data.key ||
+        run.workspace !== data.worktree ||
+        run.branch !== data.branch)
+        throw new Error("Workflow run belongs to a different RL workspace");
+    return { run, directory };
+}
+export async function controlRun(store, id, action) {
+    return store.locked(() => {
+        const { run, directory } = readRun(store, id);
+        if (run.status === "completed")
+            throw new Error("Workflow has already completed");
+        run.controlRequested = action;
+        if (run.execution === "native" || run.status !== "running")
+            run.status = action === "pause" ? "paused" : "cancelled";
+        run.updatedAt = now();
+        writeJson(path.join(directory, "run.json"), run);
+        return run;
+    });
+}
+export function evaluation(run, policy = run.config.policies[run.config.workflows[run.workflow].policy]) {
+    const currentScope = (stage) => stage.scopeFingerprint === undefined ||
+        stage.scopeFingerprint === run.scope.fingerprint;
+    const reports = run.stages
+        .filter((stage) => stage.status === "completed" &&
+        stage.result !== undefined &&
+        currentScope(stage))
+        .map((stage) => ({ owner: stage.id, result: stage.result }));
+    const limitations = run.stages
+        .filter((stage) => stage.status !== "completed")
+        .map((stage) => `${stage.id}: ${stage.error ?? stage.status}`);
+    if (run.status !== "completed")
+        limitations.push(`Run ${run.status}`);
+    for (const stage of run.stages.filter((stage) => stage.status === "completed" && !currentScope(stage))) {
+        if (stage.agent &&
+            run.config.agents[stage.agent].access === "workspace-write")
+            continue;
+        const refreshed = run.stages.some((other) => other.status === "completed" &&
+            currentScope(other) &&
+            (stage.agent
+                ? other.agent === stage.agent
+                : JSON.stringify(other.command) === JSON.stringify(stage.command)));
+        if (!refreshed)
+            limitations.push(`${stage.id}: result predates workspace changes; rerun this role/check after writing`);
+    }
+    for (const stage of run.stages)
+        if (stage.id.startsWith("followup-") && stage.result?.routingLeads.length)
+            limitations.push(`${stage.id}: further routing leads require review`);
+    for (const { owner, result } of reports)
+        for (const requested of result.checkRequests) {
+            const check = run.stages.find((step) => step.id === requested && step.command);
+            if (!check || check.status !== "completed" || !currentScope(check))
+                limitations.push(`${owner}: requested check ${requested} was not completed`);
+        }
+    const result = evaluate(policy, reports, limitations);
+    if (!run.scope.files.length) {
+        result.score = null;
+        result.verdict = "incomplete";
+        result.limitations.push("No changes to review");
+    }
+    return result;
+}
+export function runMetrics(run) {
+    const agents = run.stages.filter((stage) => stage.agent && stage.attempts);
+    const reported = agents.flatMap((stage) => stage.status === "completed" && stage.usage ? [stage.usage] : []);
+    const total = (key) => reported.length === agents.length &&
+        agents.every((stage) => stage.attempts === 1) &&
+        reported.length &&
+        reported.every((item) => item[key] !== null)
+        ? reported.reduce((sum, item) => sum + item[key], 0)
+        : null;
+    return {
+        execution: run.execution ?? "legacy",
+        usageSource: run.execution === "native"
+            ? "parent-reported; unreported usage remains unknown"
+            : "legacy provider-reported",
+        attempts: run.stages.reduce((sum, step) => sum + step.attempts, 0),
+        totalStageDurationMs: run.stages.reduce((sum, step) => sum + step.durationMs, 0),
+        completed: run.stages.filter((step) => step.status === "completed").length,
+        failed: run.stages.filter((step) => step.status === "failed").length,
+        inputTokens: total("inputTokens"),
+        outputTokens: total("outputTokens"),
+        costUsd: total("costUsd"),
+        usageCoverage: `${reported.length}/${run.stages.filter((step) => step.agent && step.attempts).length} agent stages`,
+        stages: run.stages.map(({ id, status, attempts, durationMs, usage }) => ({
+            id,
+            status,
+            attempts,
+            durationMs,
+            usage: usage ?? null,
+        })),
+    };
+}
+export async function rescoreRun(store, id, policy, config) {
+    if (!Object.hasOwn(config.policies, policy))
+        throw new Error(`Unknown policy: ${policy}`);
+    return store.locked(() => {
+        const { run, directory } = readRun(store, id);
+        if (run.status === "running")
+            throw new Error("Wait for the run to stop before rescoring");
+        run.evaluation = evaluation(run, config.policies[policy]);
+        run.assessments.push({
+            at: now(),
+            policyName: policy,
+            policy: structuredClone(config.policies[policy]),
+            evaluation: structuredClone(run.evaluation),
+        });
+        run.updatedAt = now();
+        writeJson(path.join(directory, "run.json"), run);
+        return run;
+    });
+}
+export function createRunLocked(store, config, workflow, base, prompt) {
+    if (!Object.hasOwn(config.workflows, workflow))
+        throw new Error(`Unknown workflow: ${workflow}`);
+    const [file, data] = store.current();
+    const { scope, context } = captureScope(data.worktree, base), id = randomUUID();
+    const directory = runDirectory(file, id);
+    const run = {
+        version: 1,
+        id,
+        key: data.key,
+        workspace: data.worktree,
+        branch: data.branch,
+        workflow,
+        createdAt: now(),
+        updatedAt: now(),
+        status: "paused",
+        controlRequested: null,
+        config: structuredClone(config),
+        scope,
+        prompt,
+        routed: false,
+        assessments: [],
+        stages: config.workflows[workflow].steps.map((step) => ({
+            ...step,
+            status: "pending",
+            attempts: 0,
+            durationMs: 0,
+        })),
+    };
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(path.join(directory, "scope.json"), context, {
+        mode: 0o600,
+    });
+    writeJson(path.join(directory, "run.json"), run);
+    return { run, directory };
+}
+export function planRun(store, config, workflow, base) {
+    if (!Object.hasOwn(config.workflows, workflow))
+        throw new Error(`Unknown workflow: ${workflow}`);
+    const [, data] = store.current();
+    return {
+        workspace: data.worktree,
+        workflow,
+        scope: captureScope(data.worktree, base).scope,
+        definition: config.workflows[workflow],
+        policy: config.workflows[workflow].policy,
+    };
+}
+export function workflowSummary(store) {
+    const [file] = store.current();
+    const parent = path.dirname(runDirectory(file, "00000000-0000-0000-0000-000000000000"));
+    if (!fs.existsSync(parent) ||
+        !fs.readdirSync(parent).some((id) => /^[a-f0-9-]{36}$/.test(id)))
+        return null;
+    const { run } = readRun(store);
+    return {
+        id: run.id,
+        workflow: run.workflow,
+        status: run.status,
+        completed: run.stages.filter((step) => step.status === "completed").length,
+        total: run.stages.length,
+        score: run.evaluation?.score ?? null,
+        verdict: run.evaluation?.verdict ?? null,
+        execution: run.execution,
+        owner: run.owner,
+    };
+}

package/dist/agent-workflows.js

@@ -0,0 +1,231 @@
+import path from "node:path";
+import fs from "node:fs";
+import { stripVTControlCharacters } from "node:util";
+import { args, arity, json } from "./common.js";
+import { commandContext, contextOptions } from "./command-context.js";
+import { CONFIG_FILES, initAutomation, readAutomation, setAutomation, } from "./automation-config.js";
+import { controlRun, planRun, readRun, rescoreRun, runMetrics, } from "./agent-runner.js";
+import { callWorkflowTool, resumeNativeRun } from "./session-workflows.js";
+import { parseJsonObject } from "./json.js";
+const visible = (value) => stripVTControlCharacters(String(value ?? "")).replace(/[\x00-\x1f\x7f-\x9f]/g, " ");
+function report(run, asJson) {
+    const metrics = runMetrics(run);
+    if (asJson) {
+        json({ ...run, metrics });
+        return;
+    }
+    console.log(`\n${visible(run.workflow)} · ${run.status}\nRun: ${run.id}\nWorkspace: ${visible(run.workspace)}\nScope: ${visible(run.scope.base)} → ${run.scope.head.slice(0, 12)} · ${run.scope.files.length} changed files\n`);
+    for (const stage of run.stages)
+        console.log(`  ${stage.id.padEnd(22)} ${stage.status.padEnd(10)} ${stage.attempts} attempt(s) · ${(stage.durationMs / 1000).toFixed(1)}s${stage.error ? ` · ${visible(stage.error)}` : ""}`);
+    if (run.evaluation) {
+        const result = run.evaluation;
+        console.log(`\n${result.score === null ? "Not scored" : `Score: ${result.score}/100`} · ${result.verdict}${result.verdict === "incomplete" && result.score !== null ? " (provisional)" : ""}`);
+        for (const finding of result.findings) {
+            console.log(`\n  ${finding.severity.toUpperCase()} · ${finding.required ? "required fix" : "quick win"} · ${visible(finding.title)}\n  ${visible(finding.file)}:${finding.line} · ${finding.owners.join(", ")}\n  ${visible(finding.evidence)}\n  Fix: ${visible(finding.recommendation)}`);
+        }
+        for (const limitation of result.limitations)
+            console.log(`  Limitation: ${visible(limitation)}`);
+    }
+    console.log(`\nMetrics: ${metrics.attempts} attempts · ${(metrics.totalStageDurationMs / 1000).toFixed(1)}s total stage time · usage ${metrics.usageCoverage}`);
+}
+export async function main(argv) {
+    const { values, positionals } = args(argv, [
+        ...contextOptions,
+        "base",
+        "prompt",
+        "provider",
+        "policy",
+        "file",
+        "instructions",
+        "description",
+        "model",
+        "reasoning",
+        "agent",
+        "session",
+        "step",
+        "request",
+    ], ["json", "dry-run"]);
+    const context = commandContext(values);
+    const [namespace, action, ...rest] = positionals;
+    arity(rest, 0, 1);
+    const [, data] = context.store.current();
+    const asJson = !!values.json;
+    if (values.file && values.instructions)
+        throw new Error("Choose --file or --instructions, not both");
+    if ((values.description || values.model || values.reasoning) &&
+        !(namespace === "agent" &&
+            ["add", "set"].includes(action) &&
+            values.instructions))
+        throw new Error("--description, --model and --reasoning require agent add/set --instructions");
+    if (values.provider && !(namespace === "workflow" && action === "init"))
+        throw new Error("--provider is only supported by workflow init");
+    if (values.request &&
+        !(namespace === "workflow" && action === "run" && !values["dry-run"]))
+        throw new Error("--request is only supported by workflow run without --dry-run");
+    if ((values.base || values.prompt || values["dry-run"]) &&
+        !(namespace === "workflow" && action === "run"))
+        throw new Error("--base, --prompt and --dry-run are only supported by workflow run");
+    if (values.policy && !(namespace === "workflow" && action === "score"))
+        throw new Error("--policy is only supported by workflow score");
+    if (namespace === "workflow" && action === "init") {
+        arity(rest, 0);
+        const provider = values.provider ?? "inherit";
+        if (provider !== "inherit" && provider !== "codex" && provider !== "claude")
+            throw new Error("Provider must be inherit, codex or claude");
+        await context.store.locked(() => initAutomation(data.worktree, provider));
+        await context.store.adopt(data.worktree);
+        const paths = Object.values(CONFIG_FILES).map((file) => path.join(data.worktree, file));
+        if (asJson)
+            json({ files: paths });
+        else
+            console.log(`Created separate agent, policy and workflow configurations:\n${paths.map((file) => "  " + visible(file)).join("\n")}`);
+        return 0;
+    }
+    const loadInput = () => {
+        if (typeof values.file !== "string")
+            throw new Error("Missing --file <json|->");
+        return parseJsonObject(fs.readFileSync(values.file === "-" ? 0 : values.file, "utf8"));
+    };
+    if ((namespace === "agent" || namespace === "workflow") &&
+        ["add", "set"].includes(action)) {
+        arity(rest, 1);
+        const value = namespace === "agent" && values.instructions !== undefined
+            ? {
+                provider: "inherit",
+                description: String(values.description ?? rest[0]),
+                instructions: fs.readFileSync(values.instructions === "-" ? 0 : String(values.instructions), "utf8"),
+                ...(values.model ? { model: values.model } : {}),
+                ...(values.reasoning ? { reasoning: values.reasoning } : {}),
+            }
+            : loadInput();
+        await context.store.locked(() => setAutomation(data.worktree, namespace === "agent" ? "agents" : "workflows", rest[0], value, action === "add"));
+        await context.store.adopt(data.worktree);
+        if (asJson)
+            json(value);
+        else
+            console.log(`${namespace} ${action}: ${visible(rest[0])}`);
+        return 0;
+    }
+    const parent = {
+        ...(values.agent ? { agent: values.agent } : {}),
+        ...(values.session ? { sessionId: values.session } : {}),
+    };
+    if (namespace === "workflow" &&
+        ["context", "pending", "event", "claim", "report", "dismiss"].includes(action)) {
+        const input = action === "report" || action === "dismiss" || action === "event"
+            ? loadInput()
+            : {};
+        const result = await callWorkflowTool(context.store, `rl_workflow_${action}`, {
+            ...input,
+            ...parent,
+            ...(rest[0] ? { run: rest[0] } : {}),
+            ...(values.step ? { step: values.step } : {}),
+        });
+        if (asJson || action !== "context")
+            json(result);
+        else
+            console.log(result.instructions);
+        return 0;
+    }
+    const configuration = () => readAutomation(data.worktree);
+    if ((namespace === "agent" ||
+        namespace === "policy" ||
+        namespace === "workflow") &&
+        ["list", "show"].includes(action)) {
+        const config = configuration();
+        const entries = namespace === "agent"
+            ? config.agents
+            : namespace === "policy"
+                ? config.policies
+                : config.workflows;
+        if (action === "list") {
+            arity(rest, 0);
+            if (asJson)
+                json(entries);
+            else
+                for (const [name, value] of Object.entries(entries))
+                    console.log(`${name.padEnd(22)} ${"description" in value ? visible(value.description) : "Review scoring and readiness policy"}`);
+        }
+        else {
+            arity(rest, 1);
+            if (!Object.hasOwn(entries, rest[0]))
+                throw new Error(`Unknown ${namespace}: ${rest[0]}`);
+            const item = entries[rest[0]];
+            if (asJson)
+                json(item);
+            else {
+                console.log(`${rest[0]}\n`);
+                for (const [key, value] of Object.entries(item))
+                    console.log(`${key}: ${visible(typeof value === "object" ? JSON.stringify(value) : value)}`);
+            }
+        }
+        return 0;
+    }
+    if (namespace !== "workflow")
+        throw new Error("Usage: rl agent|policy list|show <name>");
+    const name = rest[0];
+    if (action === "run") {
+        const config = configuration();
+        const workflow = name ?? "triple-review", base = String(values.base ?? context.defaultBase);
+        if (values["dry-run"]) {
+            const plan = planRun(context.store, config, workflow, base);
+            if (asJson)
+                json(plan);
+            else {
+                console.log(`Preview: ${workflow}\nWorkspace: ${visible(plan.workspace)}\nScope: ${visible(base)} · ${plan.scope.files.length} changed files\nPolicy: ${plan.policy}`);
+                for (const step of plan.definition.steps)
+                    console.log(`  ${step.id}: ${step.agent ? `${step.agent} (${config.agents[step.agent].provider ?? "inherit"})` : JSON.stringify(step.command)} · after ${step.after.join(", ") || "start"}`);
+            }
+            return 0;
+        }
+        const run = (await callWorkflowTool(context.store, "rl_workflow_start", {
+            ...parent,
+            ...(name || !values.request ? { workflow } : {}),
+            ...(values.base || !values.request ? { base } : {}),
+            ...(values.request ? { requestId: values.request } : {}),
+            ...(values.prompt ? { prompt: values.prompt } : {}),
+        }));
+        report(run, asJson);
+        if (!asJson)
+            console.log("Prepared for this session's native subagents. Claim ready steps with rl_workflow_claim or rl workflow claim; RL has not started any agent processes.");
+        return 0;
+    }
+    if (action === "resume") {
+        const run = await resumeNativeRun(context.store, name, parent);
+        report(run, asJson);
+        return 0;
+    }
+    if (action === "pause" || action === "cancel") {
+        const run = await controlRun(context.store, name, action);
+        if (asJson)
+            json({ id: run.id, status: run.status, requested: action });
+        else
+            console.log(`${action} requested for ${run.id}`);
+        return 0;
+    }
+    if (action === "status") {
+        report(readRun(context.store, name).run, asJson);
+        return 0;
+    }
+    if (action === "metrics") {
+        const { run } = readRun(context.store, name);
+        const metrics = runMetrics(run);
+        if (asJson)
+            json(metrics);
+        else {
+            console.log(`Metrics: ${run.id}`);
+            for (const [key, value] of Object.entries(metrics))
+                if (key !== "stages")
+                    console.log(`${key}: ${value ?? "not reported"}`);
+        }
+        return 0;
+    }
+    if (action === "score") {
+        const { run: saved } = readRun(context.store, name);
+        const policy = String(values.policy ?? saved.config.workflows[saved.workflow].policy);
+        const run = await rescoreRun(context.store, saved.id, policy, configuration());
+        report(run, asJson);
+        return run.evaluation?.verdict === "ready" ? 0 : 1;
+    }
+    throw new Error("Usage: rl workflow init|list|show|run|status|metrics|pause|cancel|resume|score");
+}

package/dist/agents.js

@@ -0,0 +1,73 @@
+import path from "node:path";
+import { object, sessionId } from "./common.js";
+export const lifecycleEvents = {
+    SessionStart: "session.started",
+    UserPromptSubmit: "turn.started",
+    PreToolUse: "tool.before",
+    PostToolUse: "tool.after",
+    Stop: "turn.stopped",
+    SessionEnd: "session.ended",
+    SubagentStart: "child.started",
+    SubagentStop: "child.stopped",
+};
+export function parseEvent(adapter, payload) {
+    if (!object(payload))
+        throw new Error("Hook input must be a JSON object");
+    const nativeEvent = String(payload.hook_event_name);
+    const events = { ...adapter.events, ...adapter.extraEvents };
+    if (!Object.hasOwn(events, nativeEvent))
+        throw new Error("Unsupported session hook event");
+    if (typeof payload.cwd !== "string" || !path.isAbsolute(payload.cwd))
+        throw new Error("Hook requires an absolute cwd");
+    const id = adapter.observedId(payload.session_id);
+    let childId;
+    if (payload.agent_id !== undefined) {
+        if (typeof payload.agent_id !== "string" ||
+            !/^[\w-]{1,200}$/.test(payload.agent_id))
+            throw new Error("Invalid child agent identifier");
+        childId = payload.agent_id;
+    }
+    const type = events[nativeEvent] === "session.started" && payload.source === "compact"
+        ? "context.restored"
+        : events[nativeEvent];
+    if (type.startsWith("child.") && !childId)
+        throw new Error("Subagent hook requires agent_id");
+    let resumable = false;
+    try {
+        sessionId(id);
+        resumable = !childId;
+    }
+    catch {
+        /* Observed IDs are not necessarily CLI resume IDs. */
+    }
+    return {
+        type,
+        nativeEvent,
+        sessionId: id,
+        childId,
+        cwd: payload.cwd,
+        resumable,
+    };
+}
+export function contextResponse(event, context) {
+    if (context &&
+        [
+            "session.started",
+            "context.restored",
+            "child.started",
+            "turn.started",
+            "tool.before",
+            "tool.after",
+        ].includes(event.type))
+        return {
+            hookSpecificOutput: {
+                hookEventName: event.nativeEvent,
+                additionalContext: context,
+            },
+        };
+    // Codex Stop/SubagentStop require JSON rather than plain text. An empty
+    // object is also a non-blocking response for Claude. End hooks are silent.
+    if (event.type === "turn.stopped" || event.type === "child.stopped")
+        return {};
+    return undefined;
+}