handmux 0.23.0 → 0.25.0

package/dist/src/agents/piInboxBridge.js

@@ -0,0 +1,368 @@
+const STATES = new Set(['working', 'waiting', 'done', 'error']);
+const AVAILABILITIES = new Set(['ready', 'degraded', 'unavailable']);
+const EVENT_ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,255}$/;
+export class PiInboxBridgeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PiInboxBridgeError';
+    }
+}
+function isControlOperation(operation) {
+    return operation.kind === 'superseded' || operation.kind === 'gap';
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function optionalText(value, max, nullable = false) {
+    return value === undefined || (nullable && value === null)
+        || (typeof value === 'string' && value.length > 0 && value.length <= max);
+}
+function optionalEventId(value) {
+    return value === undefined || (typeof value === 'string' && EVENT_ID_RE.test(value));
+}
+function optionalTime(value) {
+    return value === undefined || (typeof value === 'number' && Number.isFinite(value));
+}
+function copyRun(ref) {
+    return {
+        agentId: ref.agentId,
+        paneId: ref.paneId,
+        runId: ref.runId,
+        ...(ref.sessionId === undefined ? {} : { sessionId: ref.sessionId }),
+    };
+}
+function sameRun(first, second) {
+    return first.agentId === second.agentId
+        && first.paneId === second.paneId
+        && first.runId === second.runId
+        && first.sessionId === second.sessionId;
+}
+function parseItem(value) {
+    if (!isRecord(value) || typeof value.state !== 'string' || !STATES.has(value.state)
+        || !optionalText(value.message, 4096) || !optionalText(value.reason, 1024)
+        || !optionalText(value.correlationId, 256) || !optionalEventId(value.eventId)
+        || !optionalTime(value.sourceOccurredAt))
+        return null;
+    return {
+        state: value.state,
+        ...(value.message === undefined ? {} : { message: value.message }),
+        ...(value.reason === undefined ? {} : { reason: value.reason }),
+        ...(value.correlationId === undefined ? {} : { correlationId: value.correlationId }),
+        ...(value.eventId === undefined ? {} : { eventId: value.eventId }),
+        ...(value.sourceOccurredAt === undefined ? {} : { sourceOccurredAt: value.sourceOccurredAt }),
+    };
+}
+function parseSnapshot(value, availability, run, sourceId, sequence, label = 'Pi') {
+    if (availability === 'unavailable') {
+        return {
+            current: undefined,
+            result: { availability: 'unavailable', message: `${label} Inbox snapshot is unavailable` },
+        };
+    }
+    if (!isRecord(value) || typeof value.availability !== 'string'
+        || !AVAILABILITIES.has(value.availability)
+        || !optionalText(value.message, 1024)) {
+        throw new PiInboxBridgeError(`${label} Inbox Bridge returned an invalid snapshot`);
+    }
+    const snapshotAvailability = value.availability;
+    if (snapshotAvailability === 'unavailable' && value.current !== undefined) {
+        throw new PiInboxBridgeError(`Unavailable ${label} Inbox snapshot cannot contain current state`);
+    }
+    const current = value.current === undefined ? undefined : parseItem(value.current);
+    if (value.current !== undefined && !current) {
+        throw new PiInboxBridgeError(`${label} Inbox Bridge snapshot contains an invalid current state`);
+    }
+    const baseline = current ? [{
+            run: copyRun(run),
+            source: { sourceId, cursor: `bridge:${sequence}` },
+            ...current,
+        }] : [];
+    return {
+        current: current ?? undefined,
+        result: {
+            availability: snapshotAvailability,
+            ...(snapshotAvailability === 'unavailable' ? {} : { snapshot: baseline }),
+            ...(value.message === undefined ? {} : { message: value.message }),
+        },
+    };
+}
+function parseOperation(envelope, sourceId) {
+    const value = envelope.payload;
+    if (!isRecord(value)
+        || (value.kind !== 'set' && value.kind !== 'clear'
+            && value.kind !== 'superseded' && value.kind !== 'gap')
+        || !optionalText(value.correlationId, 256) || !optionalEventId(value.eventId)
+        || !optionalTime(value.sourceOccurredAt)
+        || (envelope.eventId !== undefined && value.eventId !== undefined
+            && envelope.eventId !== value.eventId))
+        return null;
+    const eventId = typeof value.eventId === 'string'
+        ? value.eventId : envelope.eventId;
+    const base = {
+        source: { sourceId, cursor: `bridge:${envelope.sequence}` },
+        ...(value.correlationId === undefined ? {} : { correlationId: value.correlationId }),
+        ...(eventId === undefined ? {} : { eventId }),
+        ...(value.sourceOccurredAt === undefined ? {} : { sourceOccurredAt: value.sourceOccurredAt }),
+    };
+    if (value.kind === 'superseded' || value.kind === 'gap') {
+        if (!eventId)
+            return null;
+        return { kind: value.kind, ...base, eventId };
+    }
+    if (value.kind === 'clear')
+        return { kind: 'clear', ...base };
+    if (typeof value.state !== 'string' || !STATES.has(value.state)
+        || !optionalText(value.message, 4096, true) || !optionalText(value.reason, 1024, true))
+        return null;
+    const state = value.state;
+    if ((state === 'waiting' || state === 'done' || state === 'error') && eventId === undefined)
+        return null;
+    return {
+        kind: 'set',
+        state,
+        ...base,
+        ...(value.message === undefined ? {} : { message: value.message }),
+        ...(value.reason === undefined ? {} : { reason: value.reason }),
+    };
+}
+// Owns only Bridge source ordering and semantic arbitration. Bridge sequence remains a source cursor;
+// Inbox Core allocates the public run-scoped sequence and authoritative acceptedAt.
+export class BridgeInboxCoordinator {
+    #host;
+    #projector;
+    #agentId;
+    #sourceId;
+    #label;
+    #bindings = new Map();
+    #stopConsumer;
+    #restoreTail = Promise.resolve();
+    #closed = false;
+    constructor({ host, projector, agentId = 'pi', sourceId = 'pi.bridge.inbox', label = 'Pi', }) {
+        this.#host = host;
+        this.#projector = projector;
+        this.#agentId = agentId;
+        this.#sourceId = sourceId;
+        this.#label = label;
+    }
+    start() {
+        if (this.#closed)
+            throw new PiInboxBridgeError(`${this.#label} Inbox Bridge coordinator is closed`);
+        if (this.#stopConsumer)
+            return;
+        this.#stopConsumer = this.#host.consumeDurableReplays('inbox', (replay) => this.#consumeDurable(replay));
+    }
+    async bind(lease) {
+        if (this.#closed || lease.signal.aborted || lease.ref.agentId !== this.#agentId) {
+            throw new PiInboxBridgeError(`${this.#label} Inbox Bridge requires a live run lease`);
+        }
+        this.start();
+        const existing = this.#bindings.get(lease.ref.runId);
+        if (existing) {
+            if (existing.lease !== lease || existing.phase === 'closed') {
+                throw new PiInboxBridgeError(`${this.#label} Inbox Bridge runId is already bound to another lease`);
+            }
+            return existing.exposed;
+        }
+        const binding = {};
+        const exposed = Object.freeze({
+            run: copyRun(lease.ref),
+            close: () => this.#closeBinding(binding),
+        });
+        Object.assign(binding, {
+            lease,
+            projector: this.#projector.forRun(lease),
+            exposed,
+            phase: 'opening',
+            baselineSequence: 0,
+            baseline: undefined,
+            baselineReady: false,
+            handle: undefined,
+            buffered: [],
+            tail: Promise.resolve(),
+            abort: new AbortController(),
+            detachAbort: () => { },
+        });
+        const onAbort = () => this.#closeBinding(binding);
+        lease.signal.addEventListener('abort', onAbort, { once: true });
+        binding.detachAbort = () => lease.signal.removeEventListener('abort', onAbort);
+        this.#bindings.set(lease.ref.runId, binding);
+        try {
+            const handle = await this.#host.openChannel(lease, 'inbox', async (event) => {
+                if (binding.phase === 'closed')
+                    return;
+                if (binding.phase !== 'live') {
+                    binding.buffered.push(event);
+                    return;
+                }
+                try {
+                    await this.#enqueue(binding, () => this.#processHostEvent(binding, event));
+                }
+                catch (error) {
+                    this.#closeBinding(binding);
+                    throw error;
+                }
+            });
+            binding.handle = handle;
+            binding.baselineSequence = handle.streamSequence;
+            binding.baseline = parseSnapshot(handle.snapshot, handle.snapshotAvailability, lease.ref, this.#sourceId, handle.streamSequence, this.#label);
+            binding.phase = 'prebaseline';
+            await this.#host.drainDurable(lease.ref, 'inbox', handle.streamSequence, {
+                signal: binding.abort.signal,
+            });
+            if (lease.signal.aborted || this.#bindings.get(lease.ref.runId) !== binding) {
+                throw new PiInboxBridgeError(`${this.#label} Inbox Bridge binding closed during restore`);
+            }
+            binding.baselineReady = true;
+            await this.#restoreBindings();
+            const buffered = binding.buffered.splice(0);
+            let initialization = binding.tail;
+            for (const event of buffered) {
+                initialization = initialization.then(() => this.#processHostEvent(binding, event));
+            }
+            binding.tail = initialization.catch(() => { });
+            binding.phase = 'live';
+            await initialization;
+            return exposed;
+        }
+        catch (error) {
+            this.#closeBinding(binding);
+            throw error;
+        }
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#stopConsumer?.();
+        this.#stopConsumer = undefined;
+        for (const binding of [...this.#bindings.values()])
+            this.#closeBinding(binding);
+    }
+    async #consumeDurable(replay) {
+        const operation = parseOperation(replay.event, this.#sourceId);
+        if (!operation)
+            return 'invalid';
+        if (isControlOperation(operation)) {
+            return replay.runStatus === 'current' ? 'accepted' : 'invalid';
+        }
+        if (replay.runStatus === 'revoked') {
+            if (operation.kind !== 'set' || (operation.state !== 'done' && operation.state !== 'error')
+                || !operation.eventId)
+                return 'invalid';
+            const result = await this.#projector.submitTerminalReplay({
+                run: replay.run,
+                source: operation.source,
+                state: operation.state,
+                eventId: operation.eventId,
+                ...(typeof operation.message === 'string' ? { message: operation.message } : {}),
+                ...(typeof operation.reason === 'string' ? { reason: operation.reason } : {}),
+                ...(operation.correlationId === undefined ? {} : { correlationId: operation.correlationId }),
+                ...(operation.sourceOccurredAt === undefined ? {} : { sourceOccurredAt: operation.sourceOccurredAt }),
+            });
+            return this.#replayResult(result.accepted, result.reason);
+        }
+        const binding = this.#bindings.get(replay.run.runId);
+        if (!binding || !sameRun(binding.lease.ref, replay.run) || binding.phase === 'opening'
+            || binding.phase === 'closed')
+            return 'retry';
+        if (binding.phase === 'prebaseline') {
+            if (replay.event.sequence > binding.baselineSequence)
+                return 'retry';
+            if (operation.kind === 'set' && operation.state === 'waiting'
+                && binding.baseline?.result.availability === 'ready') {
+                const current = binding.baseline.current;
+                if (!current || current.state !== 'waiting' || current.eventId !== operation.eventId)
+                    return 'invalid';
+            }
+        }
+        const result = await binding.projector.submit(operation);
+        return this.#replayResult(result.accepted, result.reason);
+    }
+    #replayResult(accepted, reason) {
+        if (accepted)
+            return 'accepted';
+        if (reason === 'persistence_failed' || reason === 'stale_lease')
+            return 'retry';
+        return 'invalid';
+    }
+    #enqueue(binding, operation) {
+        const pending = binding.tail.then(operation);
+        binding.tail = pending.catch(() => { });
+        return pending;
+    }
+    #restore(result) {
+        const pending = this.#restoreTail.then(() => this.#projector.restore(result()).then(() => undefined));
+        this.#restoreTail = pending.catch(() => { });
+        return pending;
+    }
+    #restoreBindings() {
+        return this.#restore(() => {
+            const bindings = [...this.#bindings.values()].filter((binding) => binding.phase !== 'closed');
+            const available = bindings.filter((binding) => (binding.baselineReady && binding.baseline?.result.availability !== 'unavailable'));
+            const pending = bindings.filter((binding) => !binding.baselineReady || !binding.baseline);
+            const unavailable = bindings.filter((binding) => (binding.baselineReady && binding.baseline?.result.availability === 'unavailable'));
+            if ((pending.length || unavailable.length) && available.length === 0) {
+                return {
+                    availability: 'unavailable',
+                    message: unavailable[0]?.baseline?.result.message
+                        ?? `${this.#label} Inbox baseline is still restoring`,
+                };
+            }
+            const baselines = available.map((binding) => binding.baseline);
+            const degraded = baselines.find((baseline) => baseline.result.availability === 'degraded');
+            return {
+                availability: degraded || pending.length || unavailable.length ? 'degraded' : 'ready',
+                snapshot: baselines.flatMap((baseline) => baseline.result.snapshot ?? []),
+                ...((degraded?.result.message ?? unavailable[0]?.baseline?.result.message) === undefined
+                    ? {} : { message: degraded?.result.message ?? unavailable[0].baseline.result.message }),
+            };
+        });
+    }
+    async #processHostEvent(binding, event) {
+        if (binding.phase === 'closed')
+            return;
+        if (event.type === 'gap') {
+            await this.#restore(() => ({
+                availability: 'unavailable',
+                message: `${this.#label} Inbox stream gap after Bridge sequence ${event.afterSequence}`,
+            }));
+            this.#closeBinding(binding);
+            throw new PiInboxBridgeError(`${this.#label} Inbox Bridge stream continuity was lost`);
+        }
+        if (event.type === 'snapshot') {
+            const snapshot = parseSnapshot(event.value, 'ready', binding.lease.ref, this.#sourceId, event.sequence, this.#label);
+            binding.baseline = snapshot;
+            binding.baselineReady = true;
+            await this.#restoreBindings();
+            return;
+        }
+        const operation = parseOperation(event.event, this.#sourceId);
+        if (!operation)
+            throw new PiInboxBridgeError(`${this.#label} Inbox Bridge returned an invalid live event`);
+        if (isControlOperation(operation))
+            return;
+        const result = await binding.projector.submit(operation);
+        if (!result.accepted) {
+            throw new PiInboxBridgeError(`${this.#label} Inbox live operation rejected: ${result.reason ?? 'unknown'}`);
+        }
+    }
+    #closeBinding(binding) {
+        if (!binding || binding.phase === 'closed')
+            return;
+        binding.phase = 'closed';
+        binding.abort.abort('binding_closed');
+        binding.detachAbort();
+        binding.handle?.close();
+        binding.buffered = [];
+        if (this.#bindings.get(binding.lease.ref.runId) === binding) {
+            this.#bindings.delete(binding.lease.ref.runId);
+            if (!this.#closed)
+                void this.#restoreBindings().catch(() => { });
+        }
+    }
+}
+export class PiInboxBridgeCoordinator extends BridgeInboxCoordinator {
+    constructor(options) {
+        super({ ...options, agentId: 'pi', label: 'Pi' });
+    }
+}

package/dist/src/agents/piSessionControl.js

@@ -0,0 +1,32 @@
+export const PI_SESSION_CONTROL_IMPLEMENTATION_VERSION = 3;
+function isSnapshot(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function createPiSessionControlAdapter({ host, }) {
+    if (!host || typeof host.request !== 'function') {
+        throw new TypeError('Pi Session Control adapter requires LocalAgentBridgeHost');
+    }
+    const read = async (run, refresh) => {
+        // Connector v2 knows nothing about Session Control. Treat absence as an optional capability instead
+        // of probing an unregistered Bridge method and delaying or disabling its otherwise healthy chat.
+        if ((run.ref.implementationVersion ?? 1) < PI_SESSION_CONTROL_IMPLEMENTATION_VERSION)
+            return null;
+        const value = await host.request(run, 'session-control', 'read', { refresh }, { timeoutMs: refresh ? 30_000 : 8_000, signal: run.signal });
+        if (!isSnapshot(value))
+            throw new Error('Pi Extension returned an invalid Session Control snapshot');
+        return value;
+    };
+    return {
+        apiVersion: 1,
+        readModelControl: (run, options) => read(run, options?.refresh === true),
+        async updateModelControl(run, patch) {
+            if ((run.ref.implementationVersion ?? 1) < PI_SESSION_CONTROL_IMPLEMENTATION_VERSION) {
+                throw new Error('Pi Session Control requires /reload');
+            }
+            const value = await host.request(run, 'session-control', 'update', patch, { timeoutMs: 8_000, signal: run.signal });
+            if (!isSnapshot(value))
+                throw new Error('Pi Extension returned an invalid Session Control snapshot');
+            return value;
+        },
+    };
+}

package/dist/src/agents/processIdentity.js

@@ -0,0 +1,94 @@
+import { promises as fsp } from 'node:fs';
+import path from 'node:path';
+import { normTty } from './scanUtils.js';
+const SUCCESS_TTL_MS = 30_000;
+const FAILURE_TTL_MS = 3_000;
+// Real executable path of a pid. lsof resolves launch symlinks on macOS; /proc is the cheap Linux path.
+// A transient lsof failure is inconclusive, not a negative identity verdict that should escape the call.
+export async function executablePath(run, pid) {
+    let out = '';
+    try {
+        out = await run('lsof', ['-a', '-p', String(pid), '-d', 'txt', '-Fn']);
+    }
+    catch { /* try /proc */ }
+    for (const line of String(out).split('\n'))
+        if (line[0] === 'n')
+            return line.slice(1).trim();
+    try {
+        return await fsp.readlink(`/proc/${pid}/exe`);
+    }
+    catch {
+        return '';
+    }
+}
+function parseForegroundProcesses(out) {
+    const rows = [];
+    for (const line of String(out).split('\n')) {
+        const m = line.match(/^\s*(\S+)\s+(\d+)\s+(\S+)\s*$/);
+        if (!m)
+            continue;
+        const [, rawTty, pid, stat] = m;
+        if (!rawTty || !pid || !stat)
+            continue;
+        const tty = normTty(rawTty);
+        if (tty && stat.includes('+'))
+            rows.push({ tty, pid });
+    }
+    return rows;
+}
+async function foregroundProcesses(run, ttys) {
+    let targeted = '';
+    try {
+        targeted = await run('ps', ['-t', ttys.join(','), '-o', 'tty=,pid=,stat=']);
+    }
+    catch { /* fall back to the portable full snapshot below */ }
+    if (String(targeted).trim())
+        return parseForegroundProcesses(targeted);
+    return parseForegroundProcesses(await run('ps', ['-Ao', 'tty=,pid=,stat=']));
+}
+// Normalize ambiguous tmux pane_current_command values only after tying the pane's TTY to a foreground
+// process whose REAL executable proves the agent identity. Every call refreshes the candidate TTYs with ps;
+// the cache only skips lsof while the exact foreground pid set is unchanged and its short TTL is live.
+// This makes TTY reuse/process replacement invalidate immediately, and failed probes retry quickly. If a
+// platform rejects the targeted query (defaultRun returns ''), retain the old full-system scan as fallback.
+export async function resolveByExecutable(panes, run, verdicts, { candidate, normalized, matches, now = () => Date.now(), successTtlMs = SUCCESS_TTL_MS, failureTtlMs = FAILURE_TTL_MS, }) {
+    const candidates = panes.filter((p) => p && p.tty && candidate(p.cmd || ''));
+    if (!candidates.length)
+        return panes;
+    const ttys = [...new Set(candidates.map((pane) => normTty(pane.tty)).filter(Boolean))];
+    if (!ttys.length)
+        return panes;
+    const rows = await foregroundProcesses(run, ttys);
+    for (const pane of candidates) {
+        const tty = normTty(pane.tty);
+        const procs = rows.filter((r) => r.tty === tty);
+        const signature = procs.map((r) => r.pid).sort().join(',');
+        const key = `${normalized}|${tty}|${pane.cmd}`;
+        const cached = verdicts.get(key);
+        if (cached && cached.signature === signature && cached.expiresAt > now()) {
+            if (cached.ok)
+                pane.cmd = normalized;
+            continue;
+        }
+        let ok = false;
+        let matchedPid = null;
+        for (const proc of procs) {
+            const exe = await executablePath(run, proc.pid);
+            if (matches(exe, pane.cmd || '')) {
+                ok = true;
+                matchedPid = proc.pid;
+                break;
+            }
+        }
+        verdicts.set(key, {
+            ok,
+            pid: matchedPid,
+            signature,
+            expiresAt: now() + (ok ? successTtlMs : failureTtlMs),
+        });
+        if (ok)
+            pane.cmd = normalized;
+    }
+    return panes;
+}
+export const executableBasename = (file) => path.basename(String(file || ''));