handmux 0.23.0 → 0.25.0

package/dist/src/workspace/agentRunner.js

@@ -0,0 +1,301 @@
+import { spawn as spawnChild } from 'node:child_process';
+import { constants as fsConstants } from 'node:fs';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ensurePrivateDir, writeJsonAtomic } from './atomicJson.js';
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const PANE_RE = /^%\d+$/;
+const RUNNER_FILE = fileURLToPath(import.meta.url);
+const HANDMUX_BIN = fileURLToPath(new URL('../../bin/handmux.js', import.meta.url));
+const MAX_PATH_LENGTH = 32_768;
+const MAX_PATH_ENTRIES = 256;
+const MAX_PATH_ENTRY_LENGTH = 4_096;
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+const recordOf = (value) => (value && typeof value === 'object' && !Array.isArray(value)
+    ? value : null);
+function errorCode(error) {
+    return error && typeof error === 'object' ? error.code : undefined;
+}
+export function validateAgentRequest(input) {
+    const request = recordOf(input);
+    const args = request?.args;
+    const cmd = request?.cmd;
+    const valid = cmd === 'claude'
+        ? Array.isArray(args) && args.length === 2 && args[0] === '--resume' && typeof args[1] === 'string' && UUID_RE.test(args[1])
+        : cmd === 'codex'
+            && Array.isArray(args) && args.length === 2 && args[0] === 'resume' && typeof args[1] === 'string' && UUID_RE.test(args[1]);
+    if (!valid)
+        throw new Error('unsafe agent request');
+    const validArgs = args;
+    return { cmd: cmd, args: [validArgs[0], validArgs[1]] };
+}
+function validatePathSnapshot(value, platform) {
+    if (typeof value !== 'string' || !value || value.length > MAX_PATH_LENGTH || /[\0\r\n]/.test(value)) {
+        throw new Error('unsafe agent PATH snapshot');
+    }
+    const pathApi = platform === 'win32' ? path.win32 : path.posix;
+    const entries = value.split(platform === 'win32' ? ';' : ':');
+    if (!entries.length || entries.length > MAX_PATH_ENTRIES)
+        throw new Error('unsafe agent PATH snapshot');
+    for (const entry of entries) {
+        if (!entry || entry.length > MAX_PATH_ENTRY_LENGTH || !pathApi.isAbsolute(entry)) {
+            throw new Error('unsafe agent PATH snapshot');
+        }
+    }
+    return value;
+}
+export function validatePreparedAgentRequest(input, platform = process.platform) {
+    const record = recordOf(input);
+    const request = validateAgentRequest(input);
+    const paneId = record?.paneId;
+    if (typeof paneId !== 'string' || !PANE_RE.test(paneId))
+        throw new Error('unsafe prepared agent request');
+    return { ...request, paneId, pathEnv: validatePathSnapshot(record?.pathEnv, platform) };
+}
+function earlyFailure(request, error, code) {
+    if (errorCode(error) === 'ENOENT')
+        return `${request.cmd} binary not found`;
+    if (error)
+        return `${request.cmd} failed to start: ${errorText(error)}`;
+    return `${request.cmd} exited ${code ?? 'unknown'} before ready`;
+}
+export function launchAgentRequest(requestInput, { spawn = spawnChild, readinessMs = 500, setTimeout = globalThis.setTimeout, clearTimeout = globalThis.clearTimeout, env, } = {}) {
+    const request = validateAgentRequest(requestInput);
+    let child;
+    let readyDone = false;
+    let timer = null;
+    let completionDone = false;
+    let settleReady;
+    let settleCompletion;
+    const ready = new Promise((resolve) => { settleReady = resolve; });
+    const completion = new Promise((resolve) => { settleCompletion = resolve; });
+    const finishCompletion = (value) => {
+        if (completionDone)
+            return;
+        completionDone = true;
+        settleCompletion(value);
+    };
+    const failReady = (error, code) => {
+        if (readyDone)
+            return;
+        readyDone = true;
+        if (timer)
+            clearTimeout(timer);
+        settleReady({ status: 'failed', error: earlyFailure(request, error, code) });
+    };
+    try {
+        const command = request.cmd === 'codex' ? process.execPath : request.cmd;
+        const args = request.cmd === 'codex' ? [HANDMUX_BIN, 'codex', ...request.args] : request.args;
+        child = spawn(command, args, {
+            stdio: 'inherit',
+            shell: false,
+            ...(env ? { env } : {}),
+        });
+    }
+    catch (error) {
+        failReady(error);
+        finishCompletion({ code: null, signal: null, error: errorText(error) });
+        return { child: null, ready, completion, terminate: async () => completion };
+    }
+    child.once('spawn', () => {
+        timer = setTimeout(() => {
+            if (readyDone)
+                return;
+            readyDone = true;
+            settleReady({ status: 'ready' });
+        }, readinessMs);
+    });
+    child.once('error', (error) => {
+        failReady(error);
+        finishCompletion({ code: null, signal: null, error: errorText(error) });
+    });
+    child.once('exit', (code, signal) => {
+        failReady(null, code);
+        finishCompletion({ code, signal });
+    });
+    return {
+        child,
+        ready,
+        completion,
+        async terminate() {
+            if (!completionDone)
+                child.kill('SIGTERM');
+            return completion;
+        },
+    };
+}
+export function launchPreparedAgentRequest(requestInput, { env = process.env, platform = process.platform, ...options } = {}) {
+    const request = validatePreparedAgentRequest(requestInput, platform);
+    return launchAgentRequest(request, { ...options, env: { ...env, PATH: request.pathEnv } });
+}
+export async function publishAgentReadiness(launched, writeStatus) {
+    const ready = await launched.ready;
+    try {
+        await writeStatus(ready);
+    }
+    catch (error) {
+        let cleanupError;
+        try {
+            await launched.terminate();
+        }
+        catch (failure) {
+            cleanupError = failure;
+        }
+        if (cleanupError)
+            throw new Error(`${errorText(error)}; cleanup failed: ${errorText(cleanupError)}`);
+        throw error;
+    }
+    return ready;
+}
+function shellQuote(value) {
+    return `'${String(value).replaceAll("'", `'"'"'`)}'`;
+}
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function executableOnPath(command, { fs = fsp, env = process.env, platform = process.platform, } = {}) {
+    const pathValue = env.PATH;
+    if (!pathValue)
+        return false;
+    const pathApi = platform === 'win32' ? path.win32 : path.posix;
+    const delimiter = platform === 'win32' ? ';' : ':';
+    const extensions = platform === 'win32'
+        ? String(env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';').filter(Boolean)
+        : [''];
+    for (const directory of pathValue.split(delimiter)) {
+        if (!directory)
+            continue;
+        for (const extension of extensions) {
+            const candidate = pathApi.join(directory, platform === 'win32' ? `${command}${extension}` : command);
+            try {
+                const stat = await fs.stat(candidate);
+                if (!stat.isFile())
+                    continue;
+                await fs.access(candidate, platform === 'win32' ? fsConstants.F_OK : fsConstants.X_OK);
+                return true;
+            }
+            catch { /* keep searching while an install may be replacing the executable */ }
+        }
+    }
+    return false;
+}
+export async function waitForAgentExecutable(command, { available = executableOnPath, now = Date.now, wait = delay, timeoutMs = 8_000, pollMs = 100, } = {}) {
+    if (command !== 'claude' && command !== 'codex')
+        throw new Error('unsafe agent executable');
+    const started = now();
+    while (true) {
+        if (await available(command))
+            return { status: 'ready' };
+        const remaining = timeoutMs - (now() - started);
+        if (remaining <= 0) {
+            return { status: 'failed', error: `${command} executable unavailable after startup wait` };
+        }
+        await wait(Math.min(pollMs, remaining));
+    }
+}
+async function unlinkIfPresent(fs, file) {
+    try {
+        await fs.unlink(file);
+    }
+    catch (error) {
+        if (errorCode(error) !== 'ENOENT')
+            throw error;
+    }
+}
+export function createAgentRunner({ home = os.homedir(), fs = fsp, now = Date.now, wait = delay, timeoutMs = 3_000, pollMs = 25, executableAvailable, executableWaitMs = 8_000, executablePollMs = 100, pathEnv = process.env.PATH, platform = process.platform, } = {}) {
+    const dir = path.join(home, '.handmux', 'workspaces', 'agent-runs');
+    const command = `${shellQuote(process.execPath)} ${shellQuote(RUNNER_FILE)}`;
+    const files = (paneId) => {
+        if (!PANE_RE.test(paneId))
+            throw new Error('invalid agent runner pane id');
+        const base = paneId.slice(1);
+        return { request: path.join(dir, `${base}.request.json`), status: path.join(dir, `${base}.status.json`) };
+    };
+    return {
+        command,
+        waitForExecutable(cmd) {
+            let safePath;
+            try {
+                safePath = validatePathSnapshot(pathEnv, platform);
+            }
+            catch (error) {
+                return Promise.resolve({ status: 'failed', error: errorText(error) });
+            }
+            return waitForAgentExecutable(cmd, {
+                available: executableAvailable ?? ((command) => executableOnPath(command, {
+                    fs,
+                    env: { PATH: safePath, PATHEXT: process.env.PATHEXT },
+                    platform,
+                })),
+                now,
+                wait,
+                timeoutMs: executableWaitMs,
+                pollMs: executablePollMs,
+            });
+        },
+        async prepare({ paneId, cmd, args }) {
+            const request = validateAgentRequest({ cmd, args });
+            const safePath = validatePathSnapshot(pathEnv, platform);
+            const target = files(paneId);
+            await ensurePrivateDir(dir, { fs });
+            await unlinkIfPresent(fs, target.status);
+            await writeJsonAtomic(target.request, { paneId, ...request, pathEnv: safePath }, { fs });
+        },
+        async waitReady(paneId) {
+            const target = files(paneId);
+            const started = now();
+            while (now() - started <= timeoutMs) {
+                try {
+                    const status = recordOf(JSON.parse(await fs.readFile(target.status, 'utf8')));
+                    if (status?.status === 'ready')
+                        return { status: 'ready' };
+                    if (status?.status === 'failed' && typeof status.error === 'string')
+                        return { status: 'failed', error: status.error };
+                }
+                catch (error) {
+                    if (errorCode(error) !== 'ENOENT' && !(error instanceof SyntaxError))
+                        throw error;
+                }
+                await wait(pollMs);
+            }
+            return { status: 'failed', error: 'agent readiness timed out' };
+        },
+        async cancel(paneId) {
+            const target = files(paneId);
+            await Promise.all([target.request, target.status].map((file) => unlinkIfPresent(fs, file)));
+        },
+    };
+}
+async function runPreparedAgent() {
+    const paneId = process.env.TMUX_PANE;
+    const target = (() => {
+        if (typeof paneId !== 'string' || !PANE_RE.test(paneId))
+            throw new Error('agent runner requires TMUX_PANE');
+        const dir = path.join(os.homedir(), '.handmux', 'workspaces', 'agent-runs');
+        const base = paneId.slice(1);
+        return { request: path.join(dir, `${base}.request.json`), status: path.join(dir, `${base}.status.json`) };
+    })();
+    const input = JSON.parse(await fsp.readFile(target.request, 'utf8'));
+    const request = validatePreparedAgentRequest(input);
+    if (request.paneId !== paneId)
+        throw new Error('agent runner pane mismatch');
+    const launched = launchPreparedAgentRequest(request);
+    try {
+        const ready = await publishAgentReadiness(launched, (status) => writeJsonAtomic(target.status, status));
+        if (ready.status === 'ready')
+            await launched.completion;
+        if (ready.status !== 'ready')
+            throw new Error(ready.error);
+    }
+    finally {
+        await unlinkIfPresent(fsp, target.request);
+    }
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === RUNNER_FILE) {
+    runPreparedAgent().catch((error) => {
+        process.stderr.write(`handmux agent resume: ${errorText(error)}\n`);
+        process.exitCode = 1;
+    });
+}

package/dist/src/workspace/atomicJson.js

@@ -0,0 +1,31 @@
+import crypto from 'node:crypto';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+export async function ensurePrivateDir(dir, { fs = fsp } = {}) {
+    const resolved = path.resolve(dir);
+    const { root } = path.parse(resolved);
+    const parts = resolved.slice(root.length).split(path.sep).filter(Boolean);
+    const privateStart = parts.indexOf('.handmux');
+    const first = privateStart === -1 ? parts.length - 1 : privateStart;
+    for (let index = first; index < parts.length; index += 1) {
+        const current = path.join(root, ...parts.slice(0, index + 1));
+        await fs.mkdir(current, { recursive: true, mode: 0o700 });
+        await fs.chmod(current, 0o700);
+    }
+}
+export async function writeJsonAtomic(file, value, { fs = fsp } = {}) {
+    const temp = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    const handle = await fs.open(temp, 'wx', 0o600);
+    try {
+        await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, 'utf8');
+        await handle.sync();
+        await handle.close();
+        await fs.rename(temp, file);
+        await fs.chmod(file, 0o600);
+    }
+    catch (error) {
+        await handle.close().catch(() => { });
+        await fs.unlink(temp).catch(() => { });
+        throw error;
+    }
+}

package/dist/src/workspace/capture.js

@@ -0,0 +1,139 @@
+import fsp from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { AGENTS } from '../agents/index.js';
+import { resolveCodexRollout, sessionsDir as codexSessionsDir } from '../agents/codex.js';
+import { canonicalizeSnapshot, WORKSPACE_SCHEMA_VERSION } from './schema.js';
+function agentMap(agents) {
+    return new Map(agents.map((agent) => [agent.id, agent]));
+}
+export async function readAgentBindings(stateFile, agents = AGENTS, readFile = fsp.readFile, access = fsp.access, stat = fsp.stat) {
+    let state;
+    try {
+        state = JSON.parse(String(await readFile(stateFile, 'utf8')));
+        if (!state || typeof state !== 'object' || Array.isArray(state))
+            return new Map();
+    }
+    catch {
+        return new Map();
+    }
+    const known = agentMap(agents);
+    const bindings = new Map();
+    for (const [paneRuntimeId, record] of Object.entries(state)) {
+        if (!record || typeof record !== 'object' || Array.isArray(record))
+            continue;
+        // This is the Claude Hook state file. Legacy Codex-tagged rows are deliberately ignored; managed
+        // Codex identity belongs to App Server and must not be reconstructed from the removed Hook path.
+        if (record.agent !== undefined && record.agent !== 'claude')
+            continue;
+        const id = 'claude';
+        if (!known.has(id))
+            continue;
+        const payload = record.payload;
+        if (!payload || typeof payload !== 'object' || Array.isArray(payload))
+            continue;
+        const sessionId = payload.session_id;
+        const transcriptPath = payload.transcript_path;
+        const driver = known.get(id);
+        if (typeof sessionId !== 'string' || !driver?.sessions?.isId(sessionId)
+            || typeof transcriptPath !== 'string' || !transcriptPath)
+            continue;
+        try {
+            await access(transcriptPath, constants.R_OK);
+            if (!(await stat(transcriptPath)).isFile())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        bindings.set(paneRuntimeId, { id, sessionId, transcriptPath });
+    }
+    return bindings;
+}
+function topologyPanes(topology) {
+    return topology.windows.flatMap((window) => window.panes);
+}
+export async function readManagedCodexBindings(topology, { codexApp, codexSessions = codexSessionsDir(), agents = AGENTS, findRollout = resolveCodexRollout, access = fsp.access, stat = fsp.stat, } = {}) {
+    if (typeof codexApp?.discover !== 'function')
+        return new Map();
+    const panes = topologyPanes(topology);
+    const discovered = new Map(await Promise.all(panes.map(async (pane) => {
+        try {
+            const state = await codexApp.discover(pane.runtimeId);
+            return [pane.runtimeId, state?.managed && typeof state.threadId === 'string' ? state.threadId : null];
+        }
+        catch {
+            return [pane.runtimeId, null];
+        }
+    })));
+    const driver = agents.find((agent) => agent.id === 'codex');
+    if (!driver)
+        return new Map();
+    const bindings = new Map();
+    for (const pane of panes) {
+        const sessionId = discovered.get(pane.runtimeId);
+        if (typeof sessionId !== 'string' || !driver.sessions?.isId(sessionId))
+            continue;
+        let transcriptPath;
+        try {
+            transcriptPath = await findRollout(codexSessions, sessionId);
+            if (typeof transcriptPath !== 'string' || !transcriptPath)
+                continue;
+            await access(transcriptPath, constants.R_OK);
+            if (!(await stat(transcriptPath)).isFile())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        bindings.set(pane.runtimeId, { id: 'codex', sessionId, transcriptPath });
+    }
+    return bindings;
+}
+export function attachBindings(topology, bindings) {
+    return {
+        ...topology,
+        windows: topology.windows.map((window) => ({
+            ...window,
+            panes: window.panes.map((pane) => ({ ...pane, agent: bindings.get(pane.runtimeId) || null })),
+        })),
+    };
+}
+function isUnknownFingerprint(value) {
+    return value === null || value === undefined
+        || (typeof value === 'object' && 'status' in value && value.status === 'unknown');
+}
+export async function captureWorkspace({ tmux, stateFile, environment, agents = AGENTS, readFile = fsp.readFile, access = fsp.access, stat = fsp.stat, codexApp, codexSessions = codexSessionsDir(), findCodexRollout = resolveCodexRollout, now = Date.now, }) {
+    try {
+        const before = await tmux.topologyFingerprint();
+        if (isUnknownFingerprint(before))
+            return { status: 'unknown' };
+        const topology = await tmux.captureTopology();
+        if (!topology || topology.status === 'unknown')
+            return { status: 'unknown' };
+        const bindings = await readAgentBindings(stateFile, agents, readFile, access, stat);
+        const managedCodex = await readManagedCodexBindings(topology, {
+            ...(codexApp ? { codexApp } : {}), codexSessions, agents,
+            findRollout: findCodexRollout, access, stat,
+        });
+        for (const [pane, binding] of managedCodex)
+            bindings.set(pane, binding);
+        const after = await tmux.topologyFingerprint();
+        if (isUnknownFingerprint(after))
+            return { status: 'unknown' };
+        if (before !== after)
+            return { status: 'changed-during-capture' };
+        const snapshot = canonicalizeSnapshot(attachBindings({
+            schemaVersion: WORKSPACE_SCHEMA_VERSION,
+            capturedAt: new Date(now()).toISOString(),
+            environment: { ...environment },
+            tmuxVersion: topology.tmuxVersion,
+            active: topology.active,
+            sessions: topology.sessions,
+            windows: topology.windows,
+        }, bindings));
+        return { status: topology.status === 'empty' ? 'empty' : 'ok', snapshot };
+    }
+    catch {
+        return { status: 'unknown' };
+    }
+}