rl-workspaces 0.0.0-stage → 0.6.0

package/bin/rl

@@ -0,0 +1,54 @@
+#!/bin/zsh -f
+emulate -L zsh
+readonly rl_home="${${(%):-%x}:A:h:h}"
+if [[ "$1" == __hook ]]; then
+  # Hooks resolve the installed CLI on PATH, not a version-specific package path.
+  # Their explicit repository/state arguments must not be replaced by user config.
+  shift
+  exec node "$rl_home/dist/cli.js" state "$@"
+fi
+if [[ "$1" == --version || "$1" == -V ]]; then
+  exec node -p 'JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8")).version' "$rl_home/package.json"
+fi
+if [[ "$1" == init ]]; then
+  if (( $# == 1 )); then
+    exec node "$rl_home/dist/help.js" init
+  fi
+  for argument in "$@"; do
+    [[ "$argument" == -- ]] && break
+    if [[ "$argument" == --help || "$argument" == -h ]]; then
+      exec node "$rl_home/dist/help.js" "$@"
+    fi
+  done
+  if [[ "$2" != zsh && "$2" != bash || $# != 2 ]]; then
+    print -u2 'Usage: rl setup shell <zsh|bash>'
+    exit 1
+  fi
+  if [[ "$2" == zsh ]]; then
+    print -r -- "source ${(q)rl_home}/shell/rl.zsh"
+  else
+    print -r -- "_rl_executable=${(qq)rl_home}/bin/rl"
+    cat <<'BASH'
+rl() {
+  local destination_file destination result previous="$PWD"
+  local -a arguments=("$@")
+  if [[ "$1" == switch && "${2:-}" == - ]]; then
+    [[ -n "${RL_PREVIOUS_WORKSPACE:-}" ]] || { printf '%s\n' 'No previous workspace in this shell' >&2; return 1; }
+    arguments[1]="$RL_PREVIOUS_WORKSPACE"
+  fi
+  destination_file=$(mktemp "${TMPDIR:-/tmp}/rl-shell.XXXXXXXX") || return 1
+  if RL_SHELL_OUTPUT="$destination_file" command "$_rl_executable" "${arguments[@]}"; then result=0; else result=$?; fi
+  destination=$(cat -- "$destination_file")
+  rm -f -- "$destination_file"
+  if [[ -n "$destination" ]]; then
+    builtin cd -- "$destination" || return 1
+    RL_PREVIOUS_WORKSPACE="$previous"
+  fi
+  return "$result"
+}
+BASH
+  fi
+  exit 0
+fi
+source "$rl_home/lib/rl.zsh" || exit 1
+_rl_main "$@"

package/config.example.zsh

@@ -0,0 +1,9 @@
+# Copy to ~/.config/rl/config.zsh (or use RL_CONFIG).
+RL_REPO_ROOT="$HOME/Documents/GitHub/my-project"
+RL_WORKTREE_DIR="$HOME/.rl/worktrees"
+RL_REPO_NAME="my-project"
+RL_DEFAULT_BASE="origin/test"
+RL_STATE_DIR="$HOME/.rl/instances"
+# Optional registered repository alias; rl --repo <alias> overrides this.
+# Without it, RL selects by current worktree, then `rl repo use` default.
+# RL_REPO="frontend"

package/dist/access.js

@@ -0,0 +1,40 @@
+import { timestamp } from "./common.js";
+/** Historical sessions/creation provide a fallback without mistaking metadata edits for use. */
+export function lastAccessed(data) {
+    if (!data)
+        return undefined;
+    const candidates = [
+        data.lastAccessedAt,
+        data.createdAt,
+        ...Object.values(data.sessions)
+            .flat()
+            .map((session) => session.lastUsedAt),
+    ];
+    let latest;
+    for (const value of candidates) {
+        if (typeof value !== "string")
+            continue;
+        try {
+            if (!latest || timestamp(value) > timestamp(latest)) {
+                timestamp(value);
+                latest = value;
+            }
+        }
+        catch {
+            /* Legacy records may not have an access timestamp. */
+        }
+    }
+    return latest;
+}
+export function accessLabel(value, now = Date.now()) {
+    if (!value)
+        return "—";
+    const seconds = Math.max(0, Math.floor((now - Date.parse(value)) / 1000));
+    if (seconds < 60)
+        return "just now";
+    if (seconds < 3600)
+        return `${Math.floor(seconds / 60)}m ago`;
+    if (seconds < 86400)
+        return `${Math.floor(seconds / 3600)}h ago`;
+    return `${Math.floor(seconds / 86400)}d ago`;
+}

package/dist/activity.js

@@ -0,0 +1,90 @@
+import { object, timestamp } from "./common.js";
+export const STALE_AFTER_MS = 30 * 60 * 1000;
+export function activityView(items = [], at = Date.now()) {
+    return items.map((item) => ({
+        ...item,
+        state: item.state !== "ended" &&
+            at - Date.parse(item.observedAt) > STALE_AFTER_MS
+            ? "stale"
+            : item.state,
+    }));
+}
+export function recordActivity(data, agent, event, stamp, contextHash) {
+    const records = ((data.activity ??= {})[agent] ??= []);
+    let item = records.find((entry) => entry.sessionId === event.sessionId && entry.childId === event.childId);
+    if (!item) {
+        item = {
+            sessionId: event.sessionId,
+            childId: event.childId,
+            state: "idle",
+            lastEvent: event.nativeEvent,
+            observedAt: stamp,
+            resumable: event.resumable,
+        };
+        records.push(item);
+    }
+    // Arrival order is the only portable ordering available. Do not invent a
+    // source timestamp or claim this is a process-liveness signal.
+    item.state =
+        event.type === "context.restored" ||
+            event.type === "notification" ||
+            event.type === "tool.before" ||
+            event.type === "tool.after"
+            ? item.state
+            : event.type === "session.ended"
+                ? "ended"
+                : ["turn.started", "child.started"].includes(event.type)
+                    ? "working"
+                    : "idle";
+    item.lastEvent = event.nativeEvent;
+    item.observedAt = stamp;
+    if (contextHash)
+        item.contextHash = contextHash;
+    // Keep one snapshot per identity so ownership remains known across sessions.
+    records.sort((a, b) => a.observedAt.localeCompare(b.observedAt));
+    ((data.hookHealth ??= {})[agent] ??= {}).lastSuccess = {
+        event: event.nativeEvent,
+        at: stamp,
+    };
+}
+export function validateTracking(data) {
+    if (data.activity !== undefined) {
+        if (!object(data.activity))
+            throw new Error("Invalid activity");
+        for (const items of Object.values(data.activity)) {
+            if (!Array.isArray(items))
+                throw new Error("Invalid activity");
+            for (const item of items) {
+                if (!object(item) ||
+                    typeof item.sessionId !== "string" ||
+                    (item.childId !== undefined && typeof item.childId !== "string") ||
+                    !["idle", "working", "ended"].includes(String(item.state)) ||
+                    typeof item.lastEvent !== "string" ||
+                    typeof item.observedAt !== "string" ||
+                    typeof item.resumable !== "boolean" ||
+                    (item.contextHash !== undefined &&
+                        typeof item.contextHash !== "string"))
+                    throw new Error("Invalid activity");
+                timestamp(item.observedAt);
+            }
+        }
+    }
+    if (data.hookHealth !== undefined) {
+        if (!object(data.hookHealth))
+            throw new Error("Invalid hook health");
+        for (const health of Object.values(data.hookHealth)) {
+            if (!object(health))
+                throw new Error("Invalid hook health");
+            for (const key of ["lastSuccess", "lastError"]) {
+                const entry = health[key];
+                if (entry === undefined)
+                    continue;
+                if (!object(entry) ||
+                    typeof entry.at !== "string" ||
+                    typeof entry[key === "lastSuccess" ? "event" : "message"] !== "string")
+                    throw new Error("Invalid hook health");
+                timestamp(entry.at);
+            }
+        }
+    }
+}

package/dist/agent-claude.js

@@ -0,0 +1,16 @@
+import { sessionId } from "./common.js";
+import { contextResponse, lifecycleEvents, parseEvent, } from "./agents.js";
+export const claude = {
+    name: "claude",
+    configPath: ".claude/settings.local.json",
+    events: { ...lifecycleEvents },
+    extraEvents: { StopFailure: "turn.failed", Notification: "notification" },
+    observedId: sessionId,
+    resumeArgs: (id) => ["claude", "--resume", sessionId(id)],
+    startArgs: (argv) => ["claude", ...argv],
+    runArgs: (prompt, argv) => ["claude", "--print", ...argv, "--", prompt],
+    parse(payload) {
+        return parseEvent(claude, payload);
+    },
+    response: contextResponse,
+};

package/dist/agent-codex.js

@@ -0,0 +1,22 @@
+import { sessionId } from "./common.js";
+import { contextResponse, lifecycleEvents, parseEvent, } from "./agents.js";
+export const codex = {
+    name: "codex",
+    configPath: ".codex/hooks.json",
+    events: { ...lifecycleEvents },
+    extraEvents: { Interrupt: "turn.interrupted" },
+    observedId(value) {
+        // The hook contract also documents thread IDs. Record these for diagnostics,
+        // but don't send them to CLI resume until that contract is verified.
+        if (typeof value === "string" && /^thr_[A-Za-z0-9_-]{1,128}$/.test(value))
+            return value;
+        return sessionId(value);
+    },
+    resumeArgs: (id) => ["codex", "resume", sessionId(id)],
+    startArgs: (argv) => ["codex", ...argv],
+    runArgs: (prompt, argv) => ["codex", "exec", ...argv, "--", prompt],
+    parse(payload) {
+        return parseEvent(codex, payload);
+    },
+    response: contextResponse,
+};

package/dist/agent-launch.js

@@ -0,0 +1,74 @@
+import fs from "node:fs";
+import { agentAdapter } from "./agent-registry.js";
+import { args, arity, execute } from "./common.js";
+import { commandContext, contextOptions, resolveWorkspace, } from "./command-context.js";
+import { readWorkflowConfig, workflowEnvironment } from "./workflow-config.js";
+import { contextText } from "./store.js";
+export async function launchAgent(store, name, argv = [], options = {}) {
+    const adapter = agentAdapter(name);
+    const [, data] = await store.locked(() => store.current(options.cwd));
+    const headless = options.mode === "run";
+    const prompt = options.prompt ?? "";
+    if (headless && !prompt.trim())
+        throw new Error("Agent run requires a non-empty --prompt");
+    if (!headless && options.prompt !== undefined)
+        throw new Error("Use agent run for --prompt");
+    const command = headless
+        ? adapter.runArgs(prompt, argv)
+        : adapter.startArgs(argv);
+    const result = await execute(command, data.worktree, {
+        interactive: !headless,
+        terminalError: headless,
+        env: {
+            ...workflowEnvironment(store.repo, data.worktree, readWorkflowConfig(store.repo)),
+            RL_STATE_DIR: store.stateDir,
+        },
+    });
+    if (headless)
+        process.stdout.write(result.stdout);
+    return result.code;
+}
+export async function handoff(store, target, cwd) {
+    const adapter = target ? agentAdapter(target) : undefined;
+    return store.locked(() => {
+        const [file, data] = store.current(cwd);
+        return ([
+            adapter
+                ? `Handoff to ${adapter.name}. Start with: rl agent start ${adapter.name}`
+                : "RL agent handoff",
+            "Shared task notes follow. Agent conversations remain in their original sessions.",
+            contextText(file, data),
+        ].join("\n\n") + "\n");
+    });
+}
+export async function main(argv) {
+    const separator = argv.indexOf("--");
+    const extra = separator < 0 ? [] : argv.slice(separator + 1);
+    const { values, positionals } = args(separator < 0 ? argv : argv.slice(0, separator), [...contextOptions, "prompt", "workspace", "output"], ["stdout"]);
+    const context = commandContext(values);
+    const target = resolveWorkspace(context, typeof values.workspace === "string" ? values.workspace : undefined);
+    const [command, name, ...rest] = positionals;
+    arity(rest, 0);
+    if (command === "handoff") {
+        if (extra.length ||
+            values.prompt !== undefined ||
+            (values.stdout && values.output !== undefined))
+            throw new Error("Usage: rl handoff [agent] [--stdout | --output path]");
+        const text = await handoff(context.store, name, target.path);
+        if (typeof values.output === "string")
+            fs.writeFileSync(values.output, text, { flag: "wx", mode: 0o600 });
+        else
+            process.stdout.write(text);
+        return 0;
+    }
+    if ((command !== "start" && command !== "run") ||
+        !name ||
+        values.output !== undefined ||
+        values.stdout)
+        throw new Error("Usage: rl agent start <codex|claude> [-- args] | run <agent> --prompt text [-- args]");
+    return launchAgent(context.store, name, extra, {
+        mode: command,
+        prompt: typeof values.prompt === "string" ? values.prompt : undefined,
+        cwd: target.path,
+    });
+}

package/dist/agent-presets.js

@@ -0,0 +1,70 @@
+export const PRESET = {
+    defaultWorkflow: "writer-reviewer-dry",
+    agents: {
+        writer: {
+            provider: "inherit",
+            reasoning: "high",
+            access: "workspace-write",
+            description: "Implement scoped changes and submit review checkpoints",
+            instructions: "Own implementation in the assigned workspace and files. You are not alone: preserve other people's work and coordinate changes with the parent. Start alongside the reviewer and DRY peer; do not spawn replacement reviewers or searchers. Follow the workflow's configured consultation rules. By default, before adding any new function consult the existing DRY peer using event new_function and a precise subject such as src/file.ts#functionName, then wait for its answer and reuse existing behavior when appropriate. Submit bounded, stable file groups to the reviewer with all newFunctions declared. Freeze submitted files while a review is pending; you may continue on unrelated files. Address feedback and resubmit until the configured rating and policy requirements pass. Report actual checks, remaining work and limitations honestly. Do not close your stage until current changes have accepted reviews and your consultations are answered.",
+        },
+        reviewer: {
+            provider: "inherit",
+            reasoning: "high",
+            access: "read-only",
+            description: "Review writer submissions and return evidence-backed ratings",
+            instructions: "Stay read-only and available alongside the writer and DRY peer. Review each writer submission against its saved checkpoint, surrounding source, intended behavior and the separate policy. Assess correctness, authorization, persistence, concurrency, type contracts and meaningful validation. Return a rating and rationale using the configured rating scale, with structured findings, coverage limitations and required fixes. Follow the workflow's configured consultation rules. By default, if you suspect duplication consult the existing DRY peer using event suspected_duplicate and a precise subject before returning the review. Declare every duplicateSuspicions subject. Incorporate its evidence rather than treating similarity as proof. Send actionable feedback to the writer, re-review resubmissions, and never equate missing evidence with a clean result. Do not edit code, silently replace peers, or finish before the writer and all submitted work are settled.",
+        },
+        dry: {
+            provider: "inherit",
+            reasoning: "high",
+            access: "read-only",
+            description: "Shared reuse and duplication specialist for writer and reviewer",
+            instructions: "Stay read-only and available as the single DRY peer for both writer and reviewer. You may map relevant existing utilities while waiting for requests. Answer new_function consultations from the writer before it adds behavior, and suspected_duplicate consultations from the reviewer before it returns a rating. Search current source for existing functions, components, services, types and dependencies. Cite concrete paths/symbols, behavioral overlap, relevant differences and a viable reuse approach; state explicitly when no suitable implementation was found or coverage is incomplete. Small or superficial similarity alone is not evidence of harmful duplication. Respond to the requesting peer through its consultation record; do not edit files, assign ratings, create more agents, or close while requests or either peer remain active.",
+        },
+    },
+    policies: {
+        review: {
+            instructions: "Report evidence-backed defects caused or materially worsened by the submitted work. Separate required fixes from optional improvements, and explain prerequisites, expected behavior and observed or inferred failures. Evaluate reuse against concrete alternatives. Avoid style-only blockers and invented findings. Missing checks, dependencies and unverified material paths are coverage limitations. Review ratings are judgments supported by evidence; RL's policy score is calculated separately and is not a probability of correctness.",
+            weights: { critical: 50, high: 20, medium: 10, low: 2 },
+            minimumScore: 0,
+            blockRequired: true,
+            rating: {
+                min: 0,
+                max: 100,
+                minimum: 90,
+                instructions: "Rate each submission from 0 to 100. 90–100 means ready with verified material behavior and no required fixes; 70–89 needs contained corrections or validation; below 70 needs substantial corrections. Explain the rating and uncertainty. A high rating never overrides required fixes, failed checks or incomplete coverage.",
+            },
+        },
+    },
+    workflows: {
+        "writer-reviewer-dry": {
+            description: "Parallel writer, reviewer and DRY peers with rated review checkpoints",
+            policy: "review",
+            concurrency: 3,
+            retries: 1,
+            timeoutSeconds: 3600,
+            triggers: [{ event: "task_planned" }, { event: "before_edit" }],
+            steps: [
+                { id: "writer", agent: "writer", after: [] },
+                { id: "reviewer", agent: "reviewer", after: [] },
+                { id: "dry", agent: "dry", after: [] },
+            ],
+            collaboration: {
+                writer: "writer",
+                reviewer: "reviewer",
+                dry: "dry",
+                maxRounds: 5,
+                rules: [
+                    { from: "writer", event: "new_function", to: "dry", required: true },
+                    {
+                        from: "reviewer",
+                        event: "suspected_duplicate",
+                        to: "dry",
+                        required: true,
+                    },
+                ],
+            },
+        },
+    },
+};

package/dist/agent-registry.js

@@ -0,0 +1,8 @@
+import { codex } from "./agent-codex.js";
+import { claude } from "./agent-claude.js";
+export const adapters = { codex, claude };
+export function agentAdapter(name) {
+    if (name !== "codex" && name !== "claude")
+        throw new Error("Agent must be codex or claude");
+    return adapters[name];
+}

package/dist/agent-resume.js

@@ -0,0 +1,96 @@
+import { agentAdapter } from "./agent-registry.js";
+import { syncCodexSessions } from "./codex-sessions.js";
+import { execute, message, now, sessionId, timestamp } from "./common.js";
+import { readWorkflowConfig, workflowEnvironment } from "./workflow-config.js";
+import { stripVTControlCharacters } from "node:util";
+export async function resumeSessions(store, kind, options = {}) {
+    if (kind !== "claude")
+        await syncCodexSessions(store);
+    const [, data] = await store.locked(() => store.current());
+    const kinds = kind ? [kind] : ["codex", "claude"];
+    const choices = kinds
+        .flatMap((agent) => data.sessions[agent].map((session) => ({ ...session, agent })))
+        .sort((a, b) => {
+        const recent = timestamp(b.lastUsedAt) - timestamp(a.lastUsedAt);
+        return recent > 0n
+            ? 1
+            : recent < 0n
+                ? -1
+                : a.agent.localeCompare(b.agent) || a.id.localeCompare(b.id);
+    });
+    if (!choices.length)
+        throw new Error(`No ${kind ? `${kind} ` : ""}session recorded for ${data.id}. Use 'rl session save' to save a session first`);
+    let selected = choices[0];
+    if (choices.length > 1 && !options.latest) {
+        const visible = (value) => stripVTControlCharacters(value).replace(/[\x00-\x1f\x7f-\x9f]/g, " ");
+        const lines = choices.map((choice) => `${choice.agent}:${choice.id}\t${choice.agent}\t${choice.id}\tLast used: ${visible(choice.lastUsedAt)}\tStarted: ${visible(choice.createdAt)}`);
+        let result;
+        try {
+            result = await execute([
+                "fzf",
+                "--delimiter=\t",
+                "--with-nth=2..",
+                "--no-multi",
+                "--no-sort",
+                "--height=70%",
+                "--border=rounded",
+                "--reverse",
+                "--prompt=Resume session › ",
+                `--header=${visible(data.id)} · Agent / session UUID / last used / started\nMost recently used first · Enter resume · Esc cancel`,
+            ], data.worktree, { input: lines.join("\n") + "\n", terminalError: true });
+        }
+        catch (error) {
+            throw new Error(`Cannot open session selector: ${message(error)}. Install fzf to choose a saved session`);
+        }
+        if ([1, 130].includes(result.code))
+            return 0;
+        if (result.code)
+            throw new Error(`Session selector failed (exit ${result.code})`);
+        const index = lines.indexOf(result.stdout.replace(/\r?\n$/, ""));
+        if (index < 0)
+            throw new Error("Session selector returned an unknown selection");
+        selected = choices[index];
+    }
+    return resumeAgent(store, selected.agent, {
+        cwd: data.worktree,
+        sessionId: selected.id,
+        expectedKey: data.key,
+    });
+}
+export async function resumeAgent(store, kind, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    if (kind === "codex" && options.sessionId === undefined)
+        await syncCodexSessions(store, cwd);
+    const [file, data, sid] = await store.locked(() => {
+        const [file, data] = store.current(cwd);
+        if (options.expectedKey && data.key !== options.expectedKey)
+            throw new Error("Instance changed before agent launch");
+        const sessions = data.sessions[kind];
+        const item = options.sessionId !== undefined
+            ? sessions.find((item) => item.id === sessionId(options.sessionId))
+            : sessions.reduce((a, b) => !a || timestamp(b.lastUsedAt) > timestamp(a.lastUsedAt) ? b : a, undefined);
+        if (!item)
+            throw new Error(`No ${kind} session recorded for ${data.id}. Use 'rl session save ${kind}${kind === "claude" ? " <UUID>" : ""}'`);
+        return [file, data, sessionId(item.id)];
+    });
+    const stamp = now();
+    console.error(`Resuming ${kind} session ${sid} for ${data.id}`);
+    const command = agentAdapter(kind).resumeArgs(sid);
+    if (options.prompt !== undefined)
+        command.push(options.prompt);
+    const result = await execute(command, data.worktree, {
+        interactive: true,
+        env: {
+            ...workflowEnvironment(store.repo, data.worktree, readWorkflowConfig(store.repo)),
+            RL_STATE_DIR: store.stateDir,
+        },
+    });
+    if (result.code === 0)
+        await store.locked(() => {
+            const [currentFile, current] = store.current(data.worktree);
+            if (currentFile !== file)
+                throw new Error("Instance changed while the agent was running");
+            store.recordSession(file, current, kind, sid, stamp);
+        });
+    return result.code;
+}