handmux 0.25.2 → 0.27.1

package/dist/src/cli/supervisor.js

@@ -7,6 +7,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
+import { providerMode, voiceProviderRegistry } from '../asr/providerRegistry.js';
 import { getDriver } from './drivers.js';
 import { writeState, clearState, claudeStatePath, pushStorePath, previewStorePath, notificationsDirPath } from './state.js';
 import { initialSupervisorComponentState, reduceSupervisorComponent, } from './supervisorState.js';
@@ -114,7 +115,7 @@ export function supervise(cfg, { home, log = console, spawnChild = defaultSpawnC
     const startServer = () => {
         // The server reads only process.env (no .env files) — the CLI resolved the one config file and we
         // hand the server everything it needs here. This is the single injection point: config.json fields →
-        // the env names the server already reads (HANDMUX_* / VAPID_* / XFYUN_*).
+        // the env names the server reads. Voice injects only the selected provider's credentials.
         const env = {
             ...processRef.env,
             NODE_ENV: 'handmux',
@@ -142,13 +143,28 @@ export function supervise(cfg, { home, log = console, spawnChild = defaultSpawnC
             if (cfg.vapid.subject)
                 env.VAPID_SUBJECT = cfg.vapid.subject;
         }
-        if (cfg.xfyun) {
-            if (cfg.xfyun.appId)
-                env.XFYUN_APPID = cfg.xfyun.appId;
-            if (cfg.xfyun.apiKey)
-                env.XFYUN_APIKEY = cfg.xfyun.apiKey;
-            if (cfg.xfyun.apiSecret)
-                env.XFYUN_APISECRET = cfg.xfyun.apiSecret;
+        // Config is authoritative for voice. Always remove inherited ASR state first, including when setup
+        // explicitly disabled voice; otherwise stale shell/service credentials silently re-enable XFYUN.
+        for (const key of [
+            'HANDMUX_ASR_PROVIDER',
+            'HANDMUX_ASR_MODE',
+            ...voiceProviderRegistry.adapters.flatMap((candidate) => (candidate.fields.map((field) => field.env))),
+        ])
+            delete env[key];
+        const voice = cfg.voice === null || cfg.voice?.enabled === false ? null
+            : cfg.voice ?? (cfg.xfyun ? { provider: 'xfyun', providers: { xfyun: cfg.xfyun } } : null);
+        if (voice) {
+            const adapter = voiceProviderRegistry.get(voice.provider);
+            if (adapter) {
+                env.HANDMUX_ASR_PROVIDER = adapter.id;
+                env.HANDMUX_ASR_MODE = providerMode(adapter, voice.mode);
+                const provider = voice.providers[adapter.id];
+                for (const field of adapter.fields) {
+                    const value = provider?.[field.key] || field.defaultValue;
+                    if (value)
+                        env[field.env] = value;
+                }
+            }
         }
         const c = spawnChild(processRef.execPath, [SERVER], { env, stdio: ['ignore', 'inherit', 'inherit'] });
         children.server = c;

package/dist/src/cli/supervisorLaunch.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { readSupervisorConfig, supervisorConfigPath, writeSupervisorConfig, } from './state.js';
+import { providerMode, voiceProviderRegistry } from '../asr/providerRegistry.js';
 import { TUNNELS } from './options.js';
 import { normalizeShortcuts } from '../shortcutConfig.js';
 const recordOf = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
@@ -43,6 +44,28 @@ const stringFields = (value, keys, key) => {
     }
     return result;
 };
+const voiceConfig = (value) => {
+    if (value === undefined || value === null)
+        return value;
+    const record = recordOf(value);
+    const providers = recordOf(record?.providers);
+    const adapter = voiceProviderRegistry.get(record?.provider);
+    if (!record || !adapter || !providers) {
+        throw new Error('invalid supervisor config: voice must select a known provider');
+    }
+    const parsed = {};
+    for (const candidate of voiceProviderRegistry.adapters) {
+        const config = stringFields(providers[candidate.id], candidate.fields.map((field) => field.key), `voice.providers.${candidate.id}`);
+        if (config)
+            parsed[candidate.id] = config;
+    }
+    return {
+        ...(record.enabled === false ? { enabled: false } : {}),
+        provider: adapter.id,
+        mode: providerMode(adapter, record.mode),
+        providers: parsed,
+    };
+};
 // The persisted file and the legacy base64 argv are untrusted process boundaries. Parse them before the
 // supervisor starts so malformed or stale data fails as one explicit configuration error instead of being
 // used as partially-typed process arguments.
@@ -87,6 +110,7 @@ export function parseSupervisorConfig(value) {
     const cpolarBin = optionalString(record.cpolarBin, 'cpolarBin');
     const cpolarRegion = optionalString(record.cpolarRegion, 'cpolarRegion');
     const vapid = stringFields(record.vapid, ['public', 'private', 'subject'], 'vapid');
+    const voice = voiceConfig(record.voice);
     const xfyun = stringFields(record.xfyun, ['appId', 'apiKey', 'apiSecret'], 'xfyun');
     if (name !== undefined)
         config.name = name;
@@ -120,6 +144,8 @@ export function parseSupervisorConfig(value) {
         config.cpolarRegion = cpolarRegion;
     if (vapid !== undefined)
         config.vapid = vapid;
+    if (voice !== undefined)
+        config.voice = voice;
     if (xfyun !== undefined)
         config.xfyun = xfyun;
     return config;

package/dist/src/codexAppServer.js

@@ -15,6 +15,7 @@ const MAX_SUBMISSION_RECEIPTS = 256;
 const SUBMISSION_RECEIPT_TTL_MS = 24 * 60 * 60 * 1_000;
 const MAX_STREAM_EVENTS = 512;
 const MAX_STREAM_MESSAGE_IDS = 100;
+const MAX_COMPACTOR_ITEM_KEYS = 128;
 const MAX_OBSERVATION_SETUP_EVENTS = 512;
 const MAX_GOAL_READ_ATTEMPTS = 3;
 const CONTROL_TURN_LIMIT = 2;
@@ -41,6 +42,20 @@ const RESUME_SNAPSHOT_INVALIDATING_METHODS = new Set([
     'thread/compacted',
     'thread/started',
 ]);
+function compactorItemKey(turnId, itemId) {
+    return `${turnId}\0${itemId}`;
+}
+function rememberCompactorItem(state, turnId, itemId) {
+    const key = compactorItemKey(turnId, itemId);
+    state.compactorItemKeys.delete(key);
+    state.compactorItemKeys.add(key);
+    while (state.compactorItemKeys.size > MAX_COMPACTOR_ITEM_KEYS) {
+        const oldest = state.compactorItemKeys.values().next().value;
+        if (typeof oldest !== 'string')
+            break;
+        state.compactorItemKeys.delete(oldest);
+    }
+}
 function recordOf(value) {
     return value != null && typeof value === 'object' && !Array.isArray(value)
         ? value
@@ -788,6 +803,9 @@ class CodexAppConnection {
                 state.compacting = false;
             }
             if (params.item.type === 'agentMessage') {
+                if (state.compacting && params.turnId && params.item.id) {
+                    rememberCompactorItem(state, params.turnId, params.item.id);
+                }
                 const itemKey = `${params.turnId}\0${params.item.id}`;
                 if (message.method === 'item/completed')
                     state.completedAgentItemIds.add(itemKey);
@@ -991,7 +1009,8 @@ class CodexAppConnection {
                 activePrompt: '', contextUsage: null, lastTurn: null, loadedOnly: false, liveItemIds: new Map(),
                 completedAgentItemIds: new Set(), plans: new Map(), goal: undefined,
                 goalRevision: 0, goalEvent: null, goalTurnId: null,
-                compacting: false, deliveryHistorySafe: true, deliveryProofClientIds: new Set(),
+                compacting: false, compactorItemKeys: new Set(),
+                deliveryHistorySafe: true, deliveryProofClientIds: new Set(),
             });
         return this.threadState.get(threadId);
     }
@@ -2995,10 +3014,20 @@ export function createCodexAppServer({ home, connect = connectUnixWebSocket, exi
             return { client, thread: await client.readThread(threadId) };
         },
         async discover(pane) {
-            const observed = await observe(pane);
-            if (!observed)
+            // Absence of the pane-owned socket is the only authoritative unmanaged verdict. If the
+            // socket exists but its App Server is still starting or reconnecting, ownership is unknown;
+            // callers must not offer to replace that Codex process as though it were native/unmanaged.
+            if (!exists(codexAppSocketPath(pane, home)))
                 return { managed: false, threadId: null };
-            return { managed: true, threadId: observed.threadId };
+            try {
+                const observed = await observe(pane);
+                return observed
+                    ? { managed: true, threadId: observed.threadId }
+                    : { managed: null, threadId: null };
+            }
+            catch {
+                return { managed: null, threadId: null };
+            }
         },
         async inboxStates(livePanes = []) {
             const out = {};
@@ -3052,6 +3081,14 @@ export function createCodexAppServer({ home, connect = connectUnixWebSocket, exi
                 revision: state.revision,
             };
         },
+        async compactorItemKeys(pane, threadId) {
+            const client = await connection(pane);
+            if (!client)
+                throw new Error('Codex session is not managed by Handmux');
+            await client.assertCurrentThread(threadId);
+            const state = await client.ensureThread(threadId);
+            return [...state.compactorItemKeys];
+        },
         async subscribe(pane, threadId, listener, afterSequence = null) {
             const client = await connection(pane);
             if (!client)

package/dist/src/routes/agents.js

@@ -160,7 +160,11 @@ export function agentRoutes({ runtime }) {
         const status = error.code === 'unsupported' ? 409
             : error.code === 'in_progress' ? 409
                 : error.code === 'contract_violation' ? 502 : 503;
-        res.status(status).json({ error: error.message, code: error.code });
+        res.status(status).json({
+            error: error.message,
+            code: error.code,
+            ...(error.recovery === undefined ? {} : { recovery: error.recovery }),
+        });
         return true;
     };
     router.get('/agents/conversation-activation', async (req, res, next) => {
@@ -193,21 +197,54 @@ export function agentRoutes({ runtime }) {
                     error: ref ? 'stale agent run' : 'invalid agent run',
                     ...(ref ? { code: 'stale_run' } : {}),
                 });
-            const operation = new AbortController();
-            const cancel = () => {
-                if (!res.writableEnded)
-                    operation.abort(new Error('Activation request disconnected'));
-            };
-            req.once('aborted', cancel);
-            res.once('close', cancel);
-            try {
-                await runtime.conversationActivation.activate(lease, operation.signal);
+            // The user already confirmed a destructive process replacement. Once accepted, C-c → managed
+            // resume is one bounded server operation: a mobile navigation or dropped HTTP connection must not
+            // strand the pane at the intermediate shell. AgentConversationActivationService still owns its
+            // hard timeout and the controller revalidates the process before every irreversible step.
+            const result = await runtime.conversationActivation.activate(lease);
+            return res.status(202).json({
+                accepted: true,
+                ...(result?.recovery === undefined ? {} : { recovery: result.recovery }),
+            });
+        }
+        catch (error) {
+            if (activationError(error, res))
+                return;
+            return next(error);
+        }
+    });
+    router.get('/agents/conversation-activation-recovery', async (req, res, next) => {
+        try {
+            if (!runtime.conversationActivation) {
+                return res.status(409).json({ error: 'conversation recovery unsupported', code: 'unsupported' });
             }
-            finally {
-                req.removeListener('aborted', cancel);
-                res.removeListener('close', cancel);
+            const paneId = typeof req.query.paneId === 'string' ? req.query.paneId : '';
+            if (!/^%\d+$/.test(paneId)) {
+                return res.status(400).json({ error: 'invalid conversation recovery pane' });
             }
-            return res.status(202).json({ accepted: true });
+            return res.json({ receipt: await runtime.conversationActivation.recovery(paneId) });
+        }
+        catch (error) {
+            if (activationError(error, res))
+                return;
+            return next(error);
+        }
+    });
+    router.post('/agents/conversation-activation-recovery', async (req, res, next) => {
+        try {
+            if (!runtime.conversationActivation) {
+                return res.status(409).json({ error: 'conversation recovery unsupported', code: 'unsupported' });
+            }
+            const paneId = typeof req.body?.paneId === 'string' ? req.body.paneId : '';
+            const operationId = typeof req.body?.operationId === 'string' ? req.body.operationId : '';
+            if (!/^%\d+$/.test(paneId) || !/^[0-9a-f]{64}$/.test(operationId)) {
+                return res.status(400).json({ error: 'invalid conversation recovery request' });
+            }
+            const result = await runtime.conversationActivation.recover(paneId, operationId);
+            return res.status(202).json({
+                accepted: true,
+                ...(result?.recovery === undefined ? {} : { recovery: result.recovery }),
+            });
         }
         catch (error) {
             if (activationError(error, res))

package/dist/src/routes/system.js

@@ -6,20 +6,29 @@ import { dirname, resolve as resolvePath } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { readFileSync } from 'node:fs';
 import { isSessionId } from '../tmux/commands.js';
-import { buildIatSignedUrl } from '../asr/iflySign.js';
-import { asrConfig, isAsrConfigured } from '../asr/iflyConfig.js';
+import { asrConfig } from '../asr/config.js';
+import { voiceProviderRegistry } from '../asr/providerRegistry.js';
 import { hooksStatus, installHooks } from '../cli/claudeHooks.js';
 import { agentIntegrationStatus, defaultAgentIntegrationContext, enableAgentIntegration, } from '../cli/agentIntegration.js';
 import { scanOrphans, takeoverOrphan, defaultProjectsDir } from '../orphans.js';
 import { readCache, isNewer, shouldRefresh, refreshLatestAsync } from '../cli/updateCheck.js';
 import { normalizeShortcuts } from '../shortcutConfig.js';
 import { projectLegacyInboxStates } from '../agent-runtime/legacyInboxProjection.js';
+import { PublicApiError } from '../apiErrors.js';
+export const MAX_SENTENCE_PCM_BYTES = 2 * 1024 * 1024;
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 const errorMessage = (error) => error instanceof Error ? error.message : String(error);
 const here = dirname(fileURLToPath(import.meta.url));
 const HOOKS_SRC = resolvePath(here, '../../hooks'); // server/hooks (bundled scripts)
 const PI_ENTRY = resolvePath(here, '../../connectors/pi/index.js');
 const WEB_AGENT_INTEGRATIONS = ['claude', 'pi'];
+const FILLER_FILTER_LEVELS = ['low', 'medium', 'high'];
+const requestFillerFilter = (value) => {
+    if (value === undefined)
+        return 'medium';
+    return typeof value === 'string' && FILLER_FILTER_LEVELS.includes(value)
+        ? value : null;
+};
 // The installed CLI version (server/package.json) — read once. The phone compares this against the cached
 // npm "latest" to surface an update hint ("run `handmux update` on your computer"); see the /version route.
 const PKG_VERSION = (() => {
@@ -47,8 +56,13 @@ export function systemRoutes({ commands, claudeEvents, agentRuntime, asrEnv, sho
     // `claudeHooks` is intentionally Claude-only. Codex is always App Server-backed and never affects
     // this setup prompt or endpoint.
     r.get('/config', (_req, res) => {
+        const voice = asrConfig(asrEnv);
+        const voiceAdapter = voice ? voiceProviderRegistry.get(voice.provider) : undefined;
         return res.json({
-            asr: isAsrConfigured(asrEnv),
+            asr: voice !== null,
+            asrProvider: voice?.provider ?? null,
+            asrMode: voice?.mode ?? null,
+            asrFillerFilter: voiceAdapter?.capabilities?.fillerFilter === true,
             claudeHooks: hooksStatus(home),
             managedCodex: true,
             shortcuts: activeShortcuts,
@@ -131,14 +145,99 @@ export function systemRoutes({ commands, claudeEvents, agentRuntime, asrEnv, sho
             return next(error);
         }
     });
-    // --- Voice input: iFlytek IAT signed-URL handoff -------------------------------------------
-    // The browser connects to iFlytek directly; we only mint a short-lived signed wss URL so the
-    // apiSecret never reaches the phone. 503 if creds aren't configured (front-end hides the mic).
-    r.get('/asr/sign', (_req, res) => {
-        if (!isAsrConfigured(asrEnv))
+    // --- Voice input: provider-neutral, short-lived session handoff -----------------------------
+    r.get('/asr/session', (req, res) => {
+        const config = asrConfig(asrEnv);
+        if (!config)
             return res.status(503).json({ error: 'asr not configured' });
-        const { appId, apiKey, apiSecret } = asrConfig(asrEnv);
-        return res.json(buildIatSignedUrl({ appId, apiKey, apiSecret, date: new Date().toUTCString() }));
+        if (config.mode !== 'streaming') {
+            return res.status(503).json({ error: 'streaming asr is not selected' });
+        }
+        const adapter = voiceProviderRegistry.get(config.provider);
+        if (!adapter?.createStreamingSession) {
+            return res.status(503).json({ error: 'streaming asr is unsupported by the selected provider' });
+        }
+        const fillerFilter = requestFillerFilter(req.query.fillerFilter);
+        if (!fillerFilter)
+            return res.status(400).json({ error: 'invalid filler filter level' });
+        return res.json(adapter.createStreamingSession(config, { fillerFilter }));
+    });
+    const rawSentenceAudio = express.raw({
+        type: 'application/octet-stream', limit: MAX_SENTENCE_PCM_BYTES,
+    });
+    const parseSentenceAudio = (req, res, next) => {
+        if (!req.is('application/octet-stream')) {
+            res.status(415).json({
+                error: 'audio must use application/octet-stream',
+                code: 'unsupported_audio_type', requestId: res.locals.requestId,
+            });
+            return;
+        }
+        rawSentenceAudio(req, res, (error) => {
+            const bodyError = error && typeof error === 'object'
+                ? error : null;
+            if (bodyError?.status === 413 || bodyError?.type === 'entity.too.large') {
+                res.status(413).json({
+                    error: `audio exceeds ${MAX_SENTENCE_PCM_BYTES} bytes`,
+                    code: 'audio_too_large', requestId: res.locals.requestId,
+                });
+                return;
+            }
+            next(error);
+        });
+    };
+    r.post('/asr/sentence', parseSentenceAudio, async (req, res, next) => {
+        const config = asrConfig(asrEnv);
+        const adapter = config ? voiceProviderRegistry.get(config.provider) : undefined;
+        if (!config || config.mode !== 'sentence' || !adapter?.recognizeSentence) {
+            return res.status(503).json({
+                error: 'sentence ASR is not selected',
+                code: 'sentence_asr_not_selected', requestId: res.locals.requestId,
+            });
+        }
+        const audio = Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0);
+        if (audio.byteLength === 0)
+            return res.status(400).json({
+                error: 'audio is empty', code: 'audio_empty', requestId: res.locals.requestId,
+            });
+        const fillerFilter = requestFillerFilter(req.query.fillerFilter);
+        if (!fillerFilter)
+            return res.status(400).json({
+                error: 'invalid filler filter level', code: 'invalid_filler_filter', requestId: res.locals.requestId,
+            });
+        try {
+            const result = await adapter.recognizeSentence(config, audio, { fillerFilter });
+            return res.json({ text: result.text });
+        }
+        catch (error) {
+            const publicError = adapter.publicError?.(error);
+            if (publicError) {
+                if (publicError.logFields) {
+                    return next(new PublicApiError(502, publicError.code, publicError.message, undefined, {
+                        ...(publicError.providerRequestId
+                            ? { providerRequestId: publicError.providerRequestId } : {}),
+                        logFields: publicError.logFields,
+                    }));
+                }
+                return res.status(502).json({
+                    error: publicError.message,
+                    code: publicError.code,
+                    requestId: res.locals.requestId,
+                    ...(publicError.providerRequestId
+                        ? { providerRequestId: publicError.providerRequestId } : {}),
+                });
+            }
+            return next(error);
+        }
+    });
+    // Historical endpoint retained for already-loaded Web clients. It can only describe XFYUN's protocol.
+    r.get('/asr/sign', (_req, res) => {
+        const config = asrConfig(asrEnv);
+        if (!config || config.provider !== 'xfyun')
+            return res.status(503).json({ error: 'xfyun asr not configured' });
+        const session = voiceProviderRegistry.get(config.provider)?.createStreamingSession?.(config, { fillerFilter: 'medium' });
+        return session ? res.json({ url: session.url, appId: session.appId })
+            : res.status(503).json({ error: 'xfyun asr not configured' });
     });
     // ?sessions=a,b scopes the roster to the session NAMES this device subscribed to (per-device inbox
     // isolation). Omitted → null → all (back-compat); present-but-empty → [] → nothing.

package/dist/src/server.js

@@ -39,6 +39,9 @@ import { InboxPushProjection } from './agent-runtime/inboxPushProjection.js';
 import { defaultGit } from './git.js';
 import { createProjectTaskRuntime } from './projectTask/runtime.js';
 import { clearCodexConversationThroughTui } from './agents/codexTerminalControl.js';
+import { sessionsDir as codexSessionsDir } from './agents/codex.js';
+import { inspectCodexOpenRootSession } from './agents/codexOpenSession.js';
+import { CodexActivationReceiptStore } from './agents/codexActivationReceipt.js';
 import { ApiAccountService, apiAccountsPath } from './apiAccounts.js';
 import { ClaudeHookBridgeConnector } from '../connectors/claude/index.js';
 const here = path.dirname(fileURLToPath(import.meta.url));
@@ -82,6 +85,7 @@ const observeEnvironment = createEnvironmentProvider({
 const stateFile = process.env.CLAUDE_STATE_FILE || claudeStatePath(home);
 let codexApp = null;
 const agentRuntimeDirectory = agentRuntimeDirectoryPath(home);
+const codexActivationReceipts = new CodexActivationReceiptStore(path.join(agentRuntimeDirectory, 'codex-activation-receipts.json'));
 const legacyCodexOutbox = codexOutboxPath(home);
 let conversationStartupBlockReason;
 try {
@@ -150,9 +154,14 @@ const agentRuntime = createBuiltinAgentRuntime({
         pendingKind: (paneId) => events?.paneKind(paneId) ?? null,
     },
     codexApp,
+    codexActivationReceipts,
     codexActivationCommands: {
-        sendKey: (pane, key) => commands.sendKey(pane, key),
-        capturePlain: (pane) => commands.capturePlain(pane),
+        openOutputCapture: (pane) => commands.openPaneOutputCapture(pane),
+        paneEpoch: async () => {
+            const environment = await workspaceTmux.observeEnvironment();
+            return environment.status === 'present' ? environment.tmuxServerId : null;
+        },
+        inspectOpenSession: (pid) => inspectCodexOpenRootSession(pid, codexSessionsDir(home)),
         runPaneCommand: (pane, command) => commands.runPaneCommand(pane, command),
     },
     codexClear: async (pane, threadId) => {

package/dist/src/terminalStream.js

@@ -3,6 +3,8 @@ import { WebSocketServer } from 'ws';
 import { tokenEquals } from './auth.js';
 import { isPaneId } from './tmux/commands.js';
 import { restoreCaptureBackgrounds } from './captureBackground.js';
+import { decodeControlData } from './tmux/controlProtocol.js';
+export { decodeControlData } from './tmux/controlProtocol.js';
 const MAX_BUFFERED_BYTES = 1024 * 1024;
 const MAX_CLIENT_MESSAGE_BYTES = 16 * 1024;
 const START_TIMEOUT_MS = 5000;
@@ -36,32 +38,6 @@ function parsePaneInfo(infoLines) {
     }
     return values;
 }
-export function decodeControlData(data) {
-    const bytes = [];
-    for (let i = 0; i < data.length;) {
-        const current = data[i];
-        if (current === 0x5c && data[i + 1] === 0x5c) {
-            bytes.push(0x5c);
-            i += 2;
-            continue;
-        }
-        if (current === 0x5c && i + 3 < data.length) {
-            const a = data[i + 1];
-            const b = data[i + 2];
-            const c = data[i + 3];
-            if (a !== undefined && b !== undefined && c !== undefined
-                && a >= 0x30 && a <= 0x37 && b >= 0x30 && b <= 0x37 && c >= 0x30 && c <= 0x37) {
-                bytes.push(((a - 0x30) << 6) | ((b - 0x30) << 3) | (c - 0x30));
-                i += 4;
-                continue;
-            }
-        }
-        if (current !== undefined)
-            bytes.push(current);
-        i += 1;
-    }
-    return Buffer.from(bytes);
-}
 export class PaneControlStream {
     ws;
     pane;

package/dist/src/tmux/commands.js

@@ -1,6 +1,7 @@
 import { execFile } from 'node:child_process';
 import os from 'node:os';
 import { parseTmuxRows, tmuxFormat } from './format.js';
+import { TmuxPaneOutputCapture } from './paneOutputCapture.js';
 export const isPaneId = (value) => typeof value === 'string' && /^%\d+$/.test(value);
 export const isWindowId = (value) => typeof value === 'string' && /^@\d+$/.test(value);
 export const isSessionId = (value) => typeof value === 'string' && /^\$\d+$/.test(value);
@@ -165,6 +166,19 @@ export async function paneSession(paneId) {
         throw new Error('pane session not found');
     return id;
 }
+export async function openPaneOutputCapture(paneId) {
+    if (!isPaneId(paneId))
+        throw new TypeError('invalid pane id');
+    const capture = new TmuxPaneOutputCapture({ pane: paneId, session: await paneSession(paneId) });
+    try {
+        await capture.start();
+        return capture;
+    }
+    catch (error) {
+        capture.close();
+        throw error;
+    }
+}
 // Exit tmux copy/scroll mode if the pane is currently in it. Called before any user input so
 // text and keys reach the shell instead of being swallowed by tmux's mode key-bindings.
 export async function exitCopyModeIfActive(paneId) {

package/dist/src/tmux/controlProtocol.js

@@ -0,0 +1,26 @@
+export function decodeControlData(data) {
+    const bytes = [];
+    for (let i = 0; i < data.length;) {
+        const current = data[i];
+        if (current === 0x5c && data[i + 1] === 0x5c) {
+            bytes.push(0x5c);
+            i += 2;
+            continue;
+        }
+        if (current === 0x5c && i + 3 < data.length) {
+            const a = data[i + 1];
+            const b = data[i + 2];
+            const c = data[i + 3];
+            if (a !== undefined && b !== undefined && c !== undefined
+                && a >= 0x30 && a <= 0x37 && b >= 0x30 && b <= 0x37 && c >= 0x30 && c <= 0x37) {
+                bytes.push(((a - 0x30) << 6) | ((b - 0x30) << 3) | (c - 0x30));
+                i += 4;
+                continue;
+            }
+        }
+        if (current !== undefined)
+            bytes.push(current);
+        i += 1;
+    }
+    return Buffer.from(bytes);
+}