rl-workspaces 0.0.0-stage → 0.6.0

package/dist/hooks.js

@@ -0,0 +1,159 @@
+import fs from "node:fs";
+import { observeWorkflowEvent } from "./session-workflows.js";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { agentAdapter } from "./agent-registry.js";
+import { recordActivity } from "./activity.js";
+import { git, json, message, now, object } from "./common.js";
+import { contextText } from "./store.js";
+export async function handleHook(store, key, name) {
+    const adapter = agentAdapter(name);
+    const payload = JSON.parse(fs.readFileSync(0, "utf8"));
+    if (!object(payload) ||
+        typeof payload.cwd !== "string" ||
+        !path.isAbsolute(payload.cwd))
+        throw new Error("Hook requires an absolute cwd");
+    // Resolve repository membership before waiting for the state lock. Recheck
+    // the branch inside it so a branch switch while waiting cannot bind a session.
+    const [root] = store.worktree(payload.cwd);
+    return store.locked(() => {
+        // Establish ownership before persisting even diagnostics. A copied hook
+        // cannot change the original instance or the destination instance.
+        const [file, data] = store.instanceForWorktree(root, git(root, "branch", "--show-current"));
+        if (data.key !== key)
+            throw new Error("Hook belongs to a different RL instance; run 'rl adopt' to repair it");
+        try {
+            const event = adapter.parse(payload);
+            // Workflow workers are ephemeral. Supply task context without turning a
+            // review pass into a saved conversation or changing the user's last-used
+            // session. Other native/managed hooks remain under the CLI's own policy.
+            if (process.env.RL_WORKFLOW_RUN && process.env.RL_WORKFLOW_STEP) {
+                const context = [
+                    "session.started",
+                    "context.restored",
+                    "child.started",
+                    "turn.started",
+                ].includes(event.type)
+                    ? contextText(file, data)
+                    : undefined;
+                const response = adapter.response(event, context);
+                if (response !== undefined)
+                    json(response);
+                return 0;
+            }
+            const stamp = now();
+            let context, hash;
+            if ([
+                "session.started",
+                "context.restored",
+                "child.started",
+                "turn.started",
+            ].includes(event.type)) {
+                const text = contextText(file, data);
+                const digest = createHash("sha256").update(text);
+                // Changes beyond the injected excerpt must also trigger a refresh.
+                for (const name of ["context.md", "progress.md"])
+                    digest.update(fs.readFileSync(path.join(path.dirname(file), name)));
+                hash = digest.digest("hex");
+                const previous = data.activity?.[adapter.name]?.find((s) => s.sessionId === event.sessionId && s.childId === event.childId);
+                if (event.type !== "turn.started" || previous?.contextHash !== hash)
+                    context = text;
+            }
+            // Keep last-used selection tied to starts/prompts, not a late shutdown
+            // event from an older session or a child's activity.
+            const used = event.resumable &&
+                ["session.started", "context.restored", "turn.started"].includes(event.type);
+            if (used)
+                store.associateSession(file, data, adapter.name, event.sessionId, stamp);
+            else
+                store.assertSessionOwner(file, adapter.name, event.sessionId);
+            recordActivity(data, adapter.name, event, stamp, hash);
+            if (used)
+                store.touch(file, data, stamp);
+            else
+                store.save(file, data);
+            // Native workers never recursively schedule their own workflow. Tool hooks
+            // describe what happened; the parent remains responsible for delegation.
+            let queued = [];
+            if (!event.childId && !payload.stop_hook_active) {
+                const tool = typeof payload.tool_name === "string" ? payload.tool_name : undefined;
+                const input = object(payload.tool_input) ? payload.tool_input : {};
+                const coordination = !!tool &&
+                    (tool.includes("rl_workflow_") ||
+                        (tool === "Bash" &&
+                            [input.command, input.cmd].some((value) => typeof value === "string" &&
+                                /^(?:command\s+)?rl\s+workflow\s+/.test(value.trim()))));
+                const paths = [];
+                const addPath = (value) => {
+                    if (typeof value === "string") {
+                        const relative = path.relative(root, path.resolve(event.cwd, value));
+                        if (relative && relative !== ".." && !relative.startsWith("../"))
+                            paths.push(relative);
+                    }
+                };
+                for (const value of [input.file_path, input.path])
+                    addPath(value);
+                const patch = typeof input.patch === "string"
+                    ? input.patch
+                    : typeof input.input === "string"
+                        ? input.input
+                        : typeof payload.tool_input === "string"
+                            ? payload.tool_input
+                            : "";
+                for (const match of patch.matchAll(/^\*\*\* (?:(?:Add|Update|Delete) File|Move to): (.+)$/gm))
+                    addPath(match[1]);
+                const edit = !!tool &&
+                    ["Edit", "Write", "MultiEdit", "apply_patch"].includes(tool);
+                const milestone = event.type === "session.started"
+                    ? "session_start"
+                    : event.type === "turn.started"
+                        ? "prompt"
+                        : event.type === "turn.stopped"
+                            ? "before_finish"
+                            : event.type === "tool.before"
+                                ? edit
+                                    ? "before_edit"
+                                    : "before_tool"
+                                : event.type === "tool.after"
+                                    ? edit
+                                        ? "after_edit"
+                                        : "after_tool"
+                                    : undefined;
+                if (milestone && !coordination)
+                    queued = observeWorkflowEvent(store, file, data, { agent: adapter.name, sessionId: event.sessionId }, milestone, tool, paths);
+            }
+            const notification = queued.length
+                ? `RL workflow requests for this parent session (${adapter.name}, sessionId ${event.sessionId}): ${JSON.stringify(queued)}. Use rl_workflow_start with requestId, then rl_workflow_claim, spawn your own native subagents, and rl_workflow_report their evidence. If native delegation is unavailable, dismiss the request with the reason and tell the user. Follow current instructions and workspace permissions.`
+                : undefined;
+            if (notification)
+                context = [context, notification].filter(Boolean).join("\n\n");
+            if (context && !event.childId)
+                context += `\nCurrent RL parent conversation: agent=${adapter.name}, sessionId=${event.sessionId}. Use this identity for workflow coordination tools.`;
+            if (event.childId && context)
+                context +=
+                    "\nYou are a native child. Follow your assigned role; do not create workflows or spawn further agents.";
+            const response = event.type === "tool.before" && notification
+                ? {
+                    hookSpecificOutput: {
+                        hookEventName: event.nativeEvent,
+                        permissionDecision: "deny",
+                        permissionDecisionReason: notification,
+                    },
+                }
+                : event.type === "turn.stopped" && notification
+                    ? { decision: "block", reason: notification }
+                    : adapter.response(event, context);
+            if (response !== undefined)
+                json(response);
+            return 0;
+        }
+        catch (error) {
+            ((data.hookHealth ??= {})[adapter.name] ??= {}).lastError = {
+                message: message(error),
+                at: now(),
+            };
+            store.save(file, data);
+            throw error;
+        }
+    });
+}

package/dist/json.js

@@ -0,0 +1,34 @@
+import fs from "node:fs";
+export function isJsonObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isJsonValue(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJsonValue);
+    return typeof value === "object" && Object.values(value).every(isJsonValue);
+}
+/** Raw JSON enters the program through this validated boundary. */
+export function parseJson(text) {
+    const value = JSON.parse(text);
+    if (!isJsonValue(value))
+        throw new Error("Invalid JSON value");
+    return value;
+}
+export function parseJsonObject(text) {
+    const value = parseJson(text);
+    if (!isJsonObject(value))
+        throw new Error("Expected a JSON object");
+    return value;
+}
+export function readJsonObject(file) {
+    try {
+        return parseJsonObject(fs.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Cannot read ${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/mcp.js

@@ -0,0 +1,336 @@
+import { fileURLToPath } from "node:url";
+import { args, arity, message, required } from "./common.js";
+import { activityView } from "./activity.js";
+import { contextText, Store } from "./store.js";
+import { agentAdapter } from "./agent-registry.js";
+import { currentSessionId } from "./session.js";
+import { syncCodexSessions } from "./codex-sessions.js";
+import { pauseTask, PAUSE_FIELDS } from "./task.js";
+import { HANDOFF_FIELDS, MAX_HANDOFF_TEXT } from "./task-state.js";
+import { automationContext, callWorkflowTool, WORKFLOW_TOOLS, } from "./session-workflows.js";
+import { isJsonObject, parseJson, readJsonObject, } from "./json.js";
+const PROTOCOL_VERSION = "2025-11-25";
+const RPC_VERSION = "2.0";
+const MAX_MESSAGE_BYTES = 1024 * 1024;
+const MAX_NOTE_LENGTH = 64 * 1024;
+const ERROR = {
+    parse: -32700,
+    request: -32600,
+    method: -32601,
+    params: -32602,
+};
+const TOOLS = [
+    {
+        name: "rl_task_pause",
+        description: "When the user asks to pause this task, save its current session and a durable handoff for rl continue. Include concrete changes, checks actually run and their results (or Not run), next steps, and blockers. agent defaults to codex. Supply the current session UUID if this server does not inherit it. Saving a pause does not terminate the agent.",
+        append: false,
+    },
+    {
+        name: "rl_session_save",
+        description: "Save a session for this workspace so it appears in status and can be resumed. agent defaults to codex. Supply sessionId with the full UUID of the current conversation; if omitted, Codex IDs are read from this server's environment when available. Claude requires sessionId.",
+        append: false,
+    },
+    {
+        name: "rl_status",
+        description: "Discover and save Codex sessions for this workspace, then read its branch, sessions and observed agent activity.",
+        append: false,
+    },
+    {
+        name: "rl_context",
+        description: "Read shared task context and progress for agent handoff.",
+        append: false,
+    },
+    {
+        name: "rl_progress",
+        description: "Read the complete shared progress document.",
+        append: false,
+    },
+    {
+        name: "rl_context_append",
+        description: "Append durable design or domain notes to shared context.",
+        append: true,
+    },
+    {
+        name: "rl_progress_append",
+        description: "Append a milestone or handoff update to shared progress.",
+        append: true,
+    },
+];
+async function* readMessages(input) {
+    let parts = [];
+    let size = 0;
+    let oversized = false;
+    for await (const chunk of input) {
+        if (!Buffer.isBuffer(chunk))
+            throw new Error("MCP input must be bytes");
+        let start = 0;
+        while (start < chunk.length) {
+            const newline = chunk.indexOf("\n", start);
+            const end = newline < 0 ? chunk.length : newline;
+            const length = end - start;
+            if (!oversized) {
+                if (size + length > MAX_MESSAGE_BYTES) {
+                    oversized = true;
+                    parts = [];
+                    size = 0;
+                }
+                else {
+                    parts.push(chunk.subarray(start, end));
+                    size += length;
+                }
+            }
+            if (newline < 0)
+                break;
+            yield oversized ? null : Buffer.concat(parts, size).toString("utf8");
+            parts = [];
+            size = 0;
+            oversized = false;
+            start = newline + 1;
+        }
+    }
+    if (oversized || size)
+        yield oversized ? null : Buffer.concat(parts, size).toString("utf8");
+}
+async function callTool(store, tool, input) {
+    const name = tool.name;
+    const session = name === "rl_session_save";
+    const allowed = session
+        ? ["agent", "sessionId"]
+        : name === "rl_task_pause"
+            ? PAUSE_FIELDS
+            : tool.append
+                ? ["text"]
+                : [];
+    if (Object.keys(input).some((key) => !allowed.includes(key)))
+        throw new Error("Unexpected tool argument");
+    if (name === "rl_task_pause")
+        return JSON.stringify(await pauseTask(store, input));
+    const text = input.text;
+    if (tool.append &&
+        (typeof text !== "string" || !text.trim() || text.length > MAX_NOTE_LENGTH))
+        throw new Error(`text must be non-empty and at most ${MAX_NOTE_LENGTH} characters`);
+    if (name === "rl_status")
+        await syncCodexSessions(store, process.cwd());
+    return store.locked(() => {
+        const [file, data] = store.current();
+        switch (name) {
+            case "rl_session_save": {
+                if (input.agent !== undefined && typeof input.agent !== "string")
+                    throw new Error("agent must be codex or claude");
+                const agent = agentAdapter(input.agent ?? "codex").name;
+                const sid = currentSessionId(agent, input.sessionId);
+                store.recordSession(file, data, agent, sid);
+                return JSON.stringify({ agent, sessionId: sid, instance: data.id });
+            }
+            case "rl_status":
+                return JSON.stringify({
+                    id: data.id,
+                    branch: data.branch,
+                    worktree: data.worktree,
+                    sessions: data.sessions,
+                    task: data.task ?? null,
+                    activity: {
+                        codex: activityView(data.activity?.codex),
+                        claude: activityView(data.activity?.claude),
+                    },
+                });
+            case "rl_context":
+                return contextText(file, data);
+            case "rl_progress":
+                return store.readDocument(file, "progress");
+            default: {
+                if (typeof text !== "string")
+                    throw new Error("text is required");
+                store.updateDocument(file, data, name === "rl_context_append" ? "context" : "progress", "append", text);
+                return "Update appended.";
+            }
+        }
+    });
+}
+export async function serveMcp(store) {
+    const metadata = readJsonObject(fileURLToPath(new URL("../package.json", import.meta.url)));
+    if (typeof metadata.version !== "string")
+        throw new Error("Invalid package version");
+    const version = metadata.version;
+    let initialized = false;
+    let ready = false;
+    for await (const line of readMessages(process.stdin)) {
+        let id = null;
+        let code = ERROR.parse;
+        try {
+            if (line === null)
+                throw new Error("Message too large");
+            const raw = parseJson(line);
+            code = ERROR.request;
+            if (!isJsonObject(raw) ||
+                raw.jsonrpc !== RPC_VERSION ||
+                typeof raw.method !== "string")
+                throw new Error("Invalid JSON-RPC request");
+            if (raw.id !== undefined &&
+                typeof raw.id !== "string" &&
+                typeof raw.id !== "number")
+                throw new Error("Invalid request id");
+            if (raw.id === undefined) {
+                if (raw.method === "notifications/initialized" && initialized)
+                    ready = true;
+                continue;
+            }
+            id = raw.id;
+            const params = raw.params ?? {};
+            code = ERROR.params;
+            if (!isJsonObject(params))
+                throw new Error("params must be an object");
+            let result;
+            if (raw.method === "initialize") {
+                if (initialized)
+                    throw new Error("Already initialized");
+                if (typeof params.protocolVersion !== "string" ||
+                    !isJsonObject(params.capabilities) ||
+                    !isJsonObject(params.clientInfo) ||
+                    typeof params.clientInfo.name !== "string" ||
+                    typeof params.clientInfo.version !== "string")
+                    throw new Error("Invalid initialization parameters");
+                initialized = true;
+                result = {
+                    protocolVersion: PROTOCOL_VERSION,
+                    capabilities: { tools: {} },
+                    serverInfo: { name: "rl", version },
+                    instructions: automationContext(store.current()[1].worktree) ||
+                        "Use RL tools for the current workspace's shared context and sessions.",
+                };
+            }
+            else if (raw.method === "ping")
+                result = {};
+            else {
+                if (!ready)
+                    throw new Error("Initialize before using tools");
+                if (raw.method === "tools/list") {
+                    result = {
+                        tools: [
+                            ...TOOLS.map((tool) => ({
+                                name: tool.name,
+                                description: tool.description,
+                                inputSchema: {
+                                    type: "object",
+                                    properties: tool.name === "rl_task_pause"
+                                        ? {
+                                            ...Object.fromEntries(HANDOFF_FIELDS.map((field) => [
+                                                field,
+                                                {
+                                                    type: "string",
+                                                    maxLength: MAX_HANDOFF_TEXT,
+                                                    ...(field === "blockers"
+                                                        ? {}
+                                                        : { minLength: 1 }),
+                                                },
+                                            ])),
+                                            agent: { type: "string", enum: ["codex", "claude"] },
+                                            sessionId: {
+                                                type: "string",
+                                                description: "Full UUID of the current conversation.",
+                                            },
+                                        }
+                                        : tool.name === "rl_session_save"
+                                            ? {
+                                                agent: {
+                                                    type: "string",
+                                                    enum: ["codex", "claude"],
+                                                },
+                                                sessionId: {
+                                                    type: "string",
+                                                    description: "Full session UUID; never a name or prefix.",
+                                                },
+                                            }
+                                            : tool.append
+                                                ? {
+                                                    text: {
+                                                        type: "string",
+                                                        minLength: 1,
+                                                        maxLength: MAX_NOTE_LENGTH,
+                                                    },
+                                                }
+                                                : {},
+                                    required: tool.name === "rl_task_pause"
+                                        ? ["summary", "changes", "validation", "next"]
+                                        : tool.append
+                                            ? ["text"]
+                                            : [],
+                                    additionalProperties: false,
+                                },
+                                annotations: {
+                                    readOnlyHint: !tool.append &&
+                                        tool.name !== "rl_session_save" &&
+                                        tool.name !== "rl_status" &&
+                                        tool.name !== "rl_task_pause",
+                                    destructiveHint: false,
+                                    openWorldHint: false,
+                                },
+                            })),
+                            ...WORKFLOW_TOOLS.map((tool) => ({
+                                name: tool.name,
+                                description: tool.description,
+                                inputSchema: {
+                                    type: "object",
+                                    properties: {
+                                        agent: { type: "string", enum: ["codex", "claude"] },
+                                        sessionId: {
+                                            type: "string",
+                                            description: "Current parent conversation ID. Claude requires a UUID; Codex also accepts observed thr_ IDs and may inherit it.",
+                                        },
+                                        ...tool.properties,
+                                    },
+                                    required: tool.required,
+                                    additionalProperties: false,
+                                },
+                                annotations: {
+                                    readOnlyHint: tool.readOnly,
+                                    destructiveHint: false,
+                                    openWorldHint: false,
+                                },
+                            })),
+                        ],
+                    };
+                }
+                else if (raw.method === "tools/call") {
+                    if (typeof params.name !== "string" ||
+                        (params.arguments !== undefined && !isJsonObject(params.arguments)))
+                        throw new Error("Invalid tool call");
+                    const tool = TOOLS.find((item) => item.name === params.name);
+                    const workflowTool = WORKFLOW_TOOLS.find((item) => item.name === params.name);
+                    if (!tool && !workflowTool)
+                        throw new Error(`Unknown tool: ${params.name}`);
+                    try {
+                        const text = workflowTool
+                            ? JSON.stringify(await callWorkflowTool(store, workflowTool.name, params.arguments ?? {}))
+                            : await callTool(store, tool, params.arguments ?? {});
+                        result = { content: [{ type: "text", text }] };
+                    }
+                    catch (error) {
+                        result = {
+                            isError: true,
+                            content: [{ type: "text", text: message(error) }],
+                        };
+                    }
+                }
+                else {
+                    code = ERROR.method;
+                    throw new Error("Method not found");
+                }
+            }
+            process.stdout.write(JSON.stringify({ jsonrpc: RPC_VERSION, id, result }) + "\n");
+        }
+        catch (error) {
+            process.stdout.write(JSON.stringify({
+                jsonrpc: RPC_VERSION,
+                id,
+                error: { code, message: message(error) },
+            }) + "\n");
+        }
+    }
+    return 0;
+}
+export async function main(argv) {
+    const { values, positionals } = args(argv, ["repo", "state-dir"], []);
+    arity(positionals, 0);
+    return serveMcp(new Store(required(values, "repo"), required(values, "state-dir")));
+}