rl-workspaces 0.0.0-stage → 0.5.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,45 @@
+export const PRESET = {
+    agents: {
+        behavior: {
+            provider: "inherit",
+            reasoning: "high",
+            description: "Runtime correctness, user journeys, persistence and security",
+            instructions: "Investigate supported end-to-end user journeys: input, validation, serialization, persistence, queries, subscriptions, caches, rendering and downstream consumers. Own runtime bugs, regressions, concurrency, error behavior, tenant isolation and demonstrable runtime performance failures. Check current code and intended behavior; history and old comments are leads, not proof. Distinguish current defects from fixed regressions, intentional boundaries and unverified hypotheses. Findings need prerequisites, reproducible steps, expected versus actual behavior, and evidence; label code-inferred reproductions. Do not review type hygiene without runtime impact, test design, debug cleanup, duplication or structural simplification. Attach regression advice to the corresponding bug rather than filing duplicate missing-test findings.",
+        },
+        reuse: {
+            provider: "inherit",
+            reasoning: "high",
+            description: "Reuse, duplicated behavior and avoidable complexity",
+            instructions: "Search the repository for existing components, hooks, services, utilities, dependencies and alternate implementations before judging a new capability. Own duplicated business behavior, unnecessary abstractions/features, redundant state and misplaced responsibilities with concrete maintenance cost. Prefer reuse, extension, composition, then a small focused implementation. Cite both the reviewed implementation and existing counterpart, the behavioral overlap and a viable smaller solution. For pure simplification, name removable machinery and explain how requirements are preserved. Small duplication and different presentations can be justified. Do not investigate runtime/security bugs, type-only duplication, logging cleanup or test quality. Labels such as DRY, YAGNI and code smell are not evidence.",
+        },
+        quality: {
+            provider: "inherit",
+            reasoning: "high",
+            description: "Type contracts, static checks, debug leftovers and test quality",
+            instructions: "Own unjustified any, casts and suppressions, overly broad contracts, failure to reuse applicable types, accidental debug leftovers, attributable static-check failures, and tests that cannot protect their claimed behavior. Distinguish safe unknown narrowing and justified dependency escape hatches from weakened checking. Preserve intentional operational logging. For test findings name a specific material contract and a useful assertion, not a coverage percentage. Do not review runtime correctness/security, architecture or duplicated business behavior. A test failure is not automatically a product bug. Request configured checks from the coordinator instead of running duplicate commands. Omit style preferences and broad cleanup of existing code.",
+        },
+    },
+    policies: {
+        review: {
+            instructions: "Report only evidence-backed problems caused or materially worsened by the reviewed changes. Separate required fixes from optional quick wins with reasons. Critical means security exposure, destructive data loss or outage; high means broken core behavior or substantial structural cost; medium means a contained defect or worthwhile required quality fix; low means an optional quick win. Do not block on stylistic preference, tiny duplication, justified type escape hatches, intentional operational logging, speculative flexibility or generic demands for tests. Missing dependencies, unverified critical paths and unresolved material questions are coverage limitations. Do not invent findings or treat a score as a probability of correctness.",
+            weights: { critical: 50, high: 20, medium: 10, low: 2 },
+            minimumScore: 0,
+            blockRequired: true,
+        },
+    },
+    workflows: {
+        "triple-review": {
+            description: "Three independent reviewers, owner follow-ups and a policy-based verdict",
+            policy: "review",
+            concurrency: 3,
+            retries: 1,
+            timeoutSeconds: 600,
+            triggers: [{ event: "before_finish", changes: true }],
+            steps: [
+                { id: "behavior", agent: "behavior", after: [] },
+                { id: "reuse", agent: "reuse", after: [] },
+                { id: "quality", agent: "quality", after: [] },
+            ],
+        },
+    },
+};

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;
+}