@scotthuang/agent-knock-knock 0.11.6 → 0.12.0

package/dist/src/terminal-control-provider.js

@@ -2,6 +2,163 @@ import { randomUUID } from "node:crypto";
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { createTerminalEndpointRef, sameTerminalEndpointIdentity, terminalControlWithCapabilities, terminalEndpointFromControlRef, tmuxTerminalRouteKey } from "./terminal-control-ref.js";
+export class TerminalControlProviderRegistry {
+    providers = new Map();
+    facade;
+    constructor(providers = []) {
+        for (const provider of providers) {
+            this.register(provider);
+        }
+    }
+    register(provider) {
+        if (!provider.kind.trim()) {
+            throw new Error("terminal control provider kind is required");
+        }
+        if (this.providers.has(provider.kind)) {
+            throw new Error(`terminal control provider is already registered for ${provider.kind}`);
+        }
+        this.providers.set(provider.kind, provider);
+        return this;
+    }
+    get(kind) {
+        return this.providers.get(kind);
+    }
+    require(kind) {
+        const provider = this.get(kind);
+        if (!provider) {
+            throw new Error(`terminal control provider is not registered for ${kind || "<empty>"}`);
+        }
+        return provider;
+    }
+    list() {
+        return [...this.providers.values()];
+    }
+    /**
+     * Exposes all registered providers through the same provider boundary used
+     * by the terminal bridge. Discovery is aggregated, while every operation on
+     * an existing endpoint is dispatched only to that endpoint's provider.
+     *
+     * The facade advertises only capabilities shared by every registered
+     * provider. This keeps generic preflight checks conservative; the selected
+     * provider still performs its own endpoint-specific checks when dispatched.
+     */
+    asProvider() {
+        this.facade ??= new RegistryTerminalControlProvider(() => this.list());
+        return this.facade;
+    }
+}
+class RegistryTerminalControlProvider {
+    registeredProviders;
+    kind = "registry";
+    discoveryErrors = new Map();
+    constructor(registeredProviders) {
+        this.registeredProviders = registeredProviders;
+    }
+    get supportedCapabilities() {
+        return intersectRegisteredCapabilities(this.registeredProviders(), (provider) => provider.supportedCapabilities);
+    }
+    get providerCapabilities() {
+        return intersectRegisteredCapabilities(this.registeredProviders(), (provider) => provider.providerCapabilities);
+    }
+    async diagnostics() {
+        const providers = this.registeredProviders();
+        const diagnostics = await Promise.all(providers.map(async (provider) => {
+            try {
+                return [provider.kind, await provider.diagnostics()];
+            }
+            catch (error) {
+                return [provider.kind, {
+                        provider: provider.kind,
+                        status: "error",
+                        error: terminalProviderErrorMessage(error)
+                    }];
+            }
+        }));
+        return {
+            provider: this.kind,
+            providerKinds: providers.map((provider) => provider.kind),
+            providers: Object.fromEntries(diagnostics),
+            discoveryErrors: Object.fromEntries(this.discoveryErrors)
+        };
+    }
+    async listTerminals() {
+        const batches = await Promise.all(this.registeredProviders().map(async (provider) => {
+            try {
+                const terminals = await provider.listTerminals();
+                for (const terminal of terminals) {
+                    assertEndpointKind(terminal, provider.kind);
+                }
+                this.discoveryErrors.delete(provider.kind);
+                return terminals;
+            }
+            catch (error) {
+                // A provider that cannot prove its own endpoints must contribute no
+                // candidates, but it must not make a different healthy transport
+                // disappear. Keep the last failure visible through diagnostics.
+                this.discoveryErrors.set(provider.kind, terminalProviderErrorMessage(error));
+                return [];
+            }
+        }));
+        return batches.flat();
+    }
+    endpoint(terminalControl) {
+        const provider = this.requireProvider(terminalControl.kind);
+        const terminal = provider.endpoint(terminalControl);
+        assertEndpointKind(terminal, provider.kind);
+        return terminal;
+    }
+    toControlRef(terminal, capabilities) {
+        const provider = this.providerForEndpoint(terminal);
+        const control = provider.toControlRef(terminal, capabilities);
+        if (control.kind !== provider.kind) {
+            throw new Error(`terminal control provider ${provider.kind} returned control for ` +
+                `${control.kind}`);
+        }
+        return control;
+    }
+    async resolve(terminal) {
+        const provider = this.providerForEndpoint(terminal);
+        const resolved = await provider.resolve(terminal);
+        assertEndpointKind(resolved, provider.kind);
+        return resolved;
+    }
+    containsProcess(terminal, process, processes) {
+        return this.providerForEndpoint(terminal).containsProcess(terminal, process, processes);
+    }
+    capture(terminal, options = {}) {
+        return this.providerForEndpoint(terminal).capture(terminal, options);
+    }
+    sendText(terminal, text) {
+        return this.providerForEndpoint(terminal).sendText(terminal, text);
+    }
+    sendKeys(terminal, keys) {
+        return this.providerForEndpoint(terminal).sendKeys(terminal, keys);
+    }
+    providerForEndpoint(terminal) {
+        return this.requireProvider(terminal.identity.providerKind);
+    }
+    requireProvider(kind) {
+        const provider = this.registeredProviders().find((candidate) => candidate.kind === kind);
+        if (!provider) {
+            throw new Error(`terminal control provider is not registered for ${kind || "<empty>"}`);
+        }
+        return provider;
+    }
+}
+function terminalProviderErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function intersectRegisteredCapabilities(providers, capabilities) {
+    const [first, ...rest] = providers;
+    if (!first) {
+        return [];
+    }
+    return [...new Set(capabilities(first))].filter((capability) => rest.every((provider) => capabilities(provider).includes(capability)));
+}
+export function createTerminalControlProviderRegistry(providers = []) {
+    return new TerminalControlProviderRegistry(providers);
+}
 /**
  * A provider-level failure proving that no terminal input operation succeeded.
  * Unknown/time-out outcomes must use an ordinary Error instead.
@@ -14,6 +171,23 @@ export class TerminalControlInputNotSentError extends Error {
     }
 }
 export class TmuxTerminalControlProvider {
+    kind = "tmux";
+    supportedCapabilities = [
+        "screen_status",
+        "send_keys",
+        "terminal_approval",
+        "screen_completion",
+        "durable_completion",
+        "terminal_cancel"
+    ];
+    providerCapabilities = [
+        "screen_capture",
+        "ansi_capture",
+        "text_delivery",
+        "key_delivery",
+        "process_inspection",
+        "stable_resource_resolution"
+    ];
     runCommand;
     socketPaths;
     commands;
@@ -25,6 +199,35 @@ export class TmuxTerminalControlProvider {
     async listPanes() {
         return (await this.diagnose()).panes;
     }
+    async listTerminals() {
+        return (await this.listPanes()).map((pane) => tmuxEndpointFromPane(pane, this.supportedCapabilities));
+    }
+    endpoint(terminalControl) {
+        if (terminalControl.kind !== this.kind) {
+            throw new Error(`terminal control provider ${this.kind} cannot resolve ${terminalControl.kind}`);
+        }
+        return terminalEndpointFromControlRef(terminalControl);
+    }
+    toControlRef(terminal, capabilities = terminal.capabilities) {
+        const control = tmuxControlFromEndpoint(terminal);
+        return terminalControlWithCapabilities(control, intersectCapabilities(capabilities, this.supportedCapabilities));
+    }
+    async resolve(terminal) {
+        assertProviderCapability(this.kind, this.providerCapabilities, "stable_resource_resolution");
+        assertEndpointKind(terminal, this.kind);
+        const matches = (await this.listTerminals()).filter((candidate) => sameTerminalEndpointIdentity(candidate, terminal) ||
+            legacyTmuxEndpointMatches(candidate, terminal));
+        if (matches.length !== 1) {
+            throw new Error(matches.length === 0
+                ? `terminal resource ${terminal.route.label} is no longer available`
+                : `terminal resource ${terminal.route.label} is ambiguous`);
+        }
+        return endpointWithCapabilities(matches[0], intersectCapabilities(terminal.capabilities, this.supportedCapabilities));
+    }
+    containsProcess(terminal, process, processes) {
+        assertProviderCapability(this.kind, this.providerCapabilities, "process_inspection");
+        return terminalPaneContainsProcess(process, tmuxPaneFromEndpoint(terminal), processes);
+    }
     async diagnose() {
         const panes = [];
         const diagnosticAttempts = [];
@@ -36,7 +239,7 @@ export class TmuxTerminalControlProvider {
                     "list-panes",
                     "-a",
                     "-F",
-                    "#{session_name}\t#{window_index}\t#{pane_index}\t#{pane_pid}\t#{pane_current_command}\t#{pane_current_path}"
+                    "#{session_name}\t#{window_index}\t#{pane_index}\t#{pane_pid}\t#{pane_current_command}\t#{pane_current_path}\t#{socket_path}\t#{pane_id}"
                 ]));
                 const parsedPanes = result.status === 0 ? parseTmuxListPanes(result.stdout, socketPath) : [];
                 diagnosticAttempts.push({
@@ -53,9 +256,12 @@ export class TmuxTerminalControlProvider {
                     continue;
                 }
                 for (const pane of parsedPanes) {
-                    // A default-server query and its discovered socket path can describe the
-                    // same pane. The pane PID is system-unique, so keep only the first route.
-                    const key = `${pane.target}\t${pane.panePid}`;
+                    // A default-server query and its discovered socket path can describe
+                    // the same pane. Prefer tmux's server-scoped stable pane identity; the
+                    // complete legacy route+PID tuple is the safe fallback for old tmux.
+                    const key = pane.serverSocketPath && pane.paneId
+                        ? `${pane.serverSocketPath}\t${pane.paneId}`
+                        : `${pane.target}\t${pane.panePid}`;
                     if (seenTargets.has(key)) {
                         continue;
                     }
@@ -72,11 +278,17 @@ export class TmuxTerminalControlProvider {
             panes
         };
     }
-    async capture(target, options = {}) {
+    async diagnostics() {
+        return this.diagnose();
+    }
+    async capture(terminal, options = {}) {
+        assertTerminalCapability(terminal, "screen_status", this.supportedCapabilities);
+        assertProviderCapability(this.kind, this.providerCapabilities, options.preserveEscapes ? "ansi_capture" : "screen_capture");
+        const { target, socketPath } = tmuxIoRoute(terminal);
         const scrollbackLines = Math.max(0, Math.floor(options.scrollbackLines ?? 200));
         let lastResult;
         for (const command of this.commands) {
-            const result = this.runCommand(command, tmuxArgs(options.socketPath, [
+            const result = this.runCommand(command, tmuxArgs(socketPath, [
                 "capture-pane",
                 ...(options.preserveEscapes ? ["-e"] : []),
                 "-t",
@@ -92,10 +304,13 @@ export class TmuxTerminalControlProvider {
         }
         throw new Error(lastResult?.stderr || lastResult?.error?.message || `tmux capture-pane failed for ${target}`);
     }
-    async sendKeys(target, keys, options = {}) {
+    async sendKeys(terminal, keys) {
+        assertTerminalCapability(terminal, "send_keys", this.supportedCapabilities);
+        assertInputProviderCapability(this.kind, this.providerCapabilities, "key_delivery");
+        const { target, socketPath } = tmuxIoRoute(terminal);
         let lastResult;
         for (const command of this.commands) {
-            const result = this.runCommand(command, tmuxArgs(options.socketPath, ["send-keys", "-t", target, ...keys]));
+            const result = this.runCommand(command, tmuxArgs(socketPath, ["send-keys", "-t", target, ...keys]));
             if (result.status === 0) {
                 return;
             }
@@ -116,12 +331,15 @@ export class TmuxTerminalControlProvider {
         throw new TerminalControlInputNotSentError(lastResult?.stderr || lastResult?.error?.message ||
             `tmux send-keys failed for ${target}`);
     }
-    async sendText(target, text, options = {}) {
+    async sendText(terminal, text) {
+        assertTerminalCapability(terminal, "send_keys", this.supportedCapabilities);
+        assertInputProviderCapability(this.kind, this.providerCapabilities, "text_delivery");
+        const { target, socketPath } = tmuxIoRoute(terminal);
         let lastResult;
         for (const command of this.commands) {
             if (/[\r\n]/u.test(text)) {
                 const bufferName = `akk-${process.pid}-${randomUUID()}`;
-                const setBuffer = this.runCommand(command, tmuxArgs(options.socketPath, [
+                const setBuffer = this.runCommand(command, tmuxArgs(socketPath, [
                     "set-buffer",
                     "-b",
                     bufferName,
@@ -132,7 +350,7 @@ export class TmuxTerminalControlProvider {
                     lastResult = setBuffer;
                     continue;
                 }
-                const pasteBuffer = this.runCommand(command, tmuxArgs(options.socketPath, [
+                const pasteBuffer = this.runCommand(command, tmuxArgs(socketPath, [
                     "paste-buffer",
                     "-p",
                     "-d",
@@ -144,12 +362,12 @@ export class TmuxTerminalControlProvider {
                 if (pasteBuffer.status === 0) {
                     return;
                 }
-                this.runCommand(command, tmuxArgs(options.socketPath, [
+                this.runCommand(command, tmuxArgs(socketPath, [
                     "delete-buffer",
                     "-b",
                     bufferName
                 ]));
-                if (pasteBuffer.status === null &&
+                if (pasteBuffer.status !== null ||
                     !commandDefinitelyDidNotStart(pasteBuffer.error)) {
                     throw new Error(pasteBuffer.stderr || pasteBuffer.error?.message ||
                         `tmux terminal paste outcome is uncertain for ${target}`);
@@ -157,7 +375,7 @@ export class TmuxTerminalControlProvider {
                 lastResult = pasteBuffer;
                 continue;
             }
-            const result = this.runCommand(command, tmuxArgs(options.socketPath, ["send-keys", "-t", target, "-l", text]));
+            const result = this.runCommand(command, tmuxArgs(socketPath, ["send-keys", "-t", target, "-l", text]));
             if (result.status === 0) {
                 return;
             }
@@ -180,6 +398,23 @@ function commandDefinitelyDidNotStart(error) {
     return code === "ENOENT" || code === "EACCES" || code === "ENOTDIR";
 }
 export class StaticTerminalControlProvider {
+    kind = "tmux";
+    supportedCapabilities = [
+        "screen_status",
+        "send_keys",
+        "terminal_approval",
+        "screen_completion",
+        "durable_completion",
+        "terminal_cancel"
+    ];
+    providerCapabilities = [
+        "screen_capture",
+        "ansi_capture",
+        "text_delivery",
+        "key_delivery",
+        "process_inspection",
+        "stable_resource_resolution"
+    ];
     panes;
     screens;
     sentKeys = [];
@@ -190,13 +425,56 @@ export class StaticTerminalControlProvider {
     async listPanes() {
         return this.panes;
     }
-    async capture(target) {
+    async diagnostics() {
+        return {
+            provider: "static",
+            paneCount: (await this.listTerminals()).length
+        };
+    }
+    async listTerminals() {
+        return this.panes.map((pane) => tmuxEndpointFromPane(pane, this.supportedCapabilities));
+    }
+    endpoint(terminalControl) {
+        if (terminalControl.kind !== this.kind) {
+            throw new Error(`terminal control provider ${this.kind} cannot resolve ${terminalControl.kind}`);
+        }
+        return terminalEndpointFromControlRef(terminalControl);
+    }
+    toControlRef(terminal, capabilities = terminal.capabilities) {
+        return terminalControlWithCapabilities(tmuxControlFromEndpoint(terminal), intersectCapabilities(capabilities, this.supportedCapabilities));
+    }
+    async resolve(terminal) {
+        assertProviderCapability(this.kind, this.providerCapabilities, "stable_resource_resolution");
+        assertEndpointKind(terminal, this.kind);
+        const matches = (await this.listTerminals()).filter((candidate) => sameTerminalEndpointIdentity(candidate, terminal) ||
+            legacyTmuxEndpointMatches(candidate, terminal));
+        if (matches.length !== 1) {
+            throw new Error(matches.length === 0
+                ? `terminal resource ${terminal.route.label} is no longer available`
+                : `terminal resource ${terminal.route.label} is ambiguous`);
+        }
+        return endpointWithCapabilities(matches[0], intersectCapabilities(terminal.capabilities, this.supportedCapabilities));
+    }
+    containsProcess(terminal, process, processes) {
+        assertProviderCapability(this.kind, this.providerCapabilities, "process_inspection");
+        return terminalPaneContainsProcess(process, tmuxPaneFromEndpoint(terminal), processes);
+    }
+    async capture(terminal) {
+        assertTerminalCapability(terminal, "screen_status", this.supportedCapabilities);
+        assertProviderCapability(this.kind, this.providerCapabilities, "screen_capture");
+        const { target } = tmuxControlFromEndpoint(terminal);
         return this.screens.get(target) ?? "";
     }
-    async sendText(target, text) {
+    async sendText(terminal, text) {
+        assertTerminalCapability(terminal, "send_keys", this.supportedCapabilities);
+        assertInputProviderCapability(this.kind, this.providerCapabilities, "text_delivery");
+        const { target } = tmuxControlFromEndpoint(terminal);
         this.sentKeys.push({ target, keys: ["-l", text] });
     }
-    async sendKeys(target, keys) {
+    async sendKeys(terminal, keys) {
+        assertTerminalCapability(terminal, "send_keys", this.supportedCapabilities);
+        assertInputProviderCapability(this.kind, this.providerCapabilities, "key_delivery");
+        const { target } = tmuxControlFromEndpoint(terminal);
         this.sentKeys.push({ target, keys: [...keys] });
     }
 }
@@ -221,20 +499,31 @@ export function parseTmuxListPanes(output, socketPath) {
 }
 function parseTmuxPaneLine(line) {
     const tabFields = line.split("\t");
-    const fields = tabFields.length >= 6
+    const fields = tabFields.length >= 8
         ? [
             tabFields[0],
             tabFields[1],
             tabFields[2],
             tabFields[3],
             tabFields[4],
-            tabFields.slice(5).join("\t")
+            tabFields.slice(5, -2).join("\t"),
+            tabFields.at(-2) ?? "",
+            tabFields.at(-1) ?? ""
         ]
-        : parseWhitespaceTmuxPaneLine(line) ?? parseUnderscoreTmuxPaneLine(line);
+        : tabFields.length >= 6
+            ? [
+                tabFields[0],
+                tabFields[1],
+                tabFields[2],
+                tabFields[3],
+                tabFields[4],
+                tabFields.slice(5).join("\t")
+            ]
+            : parseWhitespaceTmuxPaneLine(line) ?? parseUnderscoreTmuxPaneLine(line);
     if (!fields) {
         return undefined;
     }
-    const [session, windowIndex, paneIndex, panePid, currentCommand, currentPath] = fields;
+    const [session, windowIndex, paneIndex, panePid, currentCommand, currentPath, serverSocketPath, paneId] = fields;
     const window = Number(windowIndex);
     const pane = Number(paneIndex);
     const parsedPanePid = Number(panePid);
@@ -247,7 +536,9 @@ function parseTmuxPaneLine(line) {
         pane,
         panePid: parsedPanePid,
         currentCommand: currentCommand || undefined,
-        currentPath: currentPath || undefined
+        currentPath: currentPath || undefined,
+        serverSocketPath: serverSocketPath || undefined,
+        paneId: paneId || undefined
     };
 }
 function parseWhitespaceTmuxPaneLine(line) {
@@ -259,30 +550,161 @@ function parseUnderscoreTmuxPaneLine(line) {
     return match ? match.slice(1) : undefined;
 }
 export async function enrichActiveProcessesWithTerminalControl(processes, provider, options = {}) {
-    const panes = await provider.listPanes();
-    if (panes.length === 0) {
+    const terminals = await provider.listTerminals();
+    if (terminals.length === 0) {
         return processes;
     }
     const matches = new Map();
     const processTree = options.processTree ?? processes;
     for (const process of processes) {
-        const pane = panes.find((candidate) => terminalPaneContainsProcess(process, candidate, processTree));
-        if (!pane) {
+        const matchingTerminals = terminals.filter((candidate) => provider.containsProcess(candidate, process, processTree));
+        // Never guess when nested/multiple terminal providers both contain the
+        // same process. A wrong match would grant control over an unrelated route.
+        if (matchingTerminals.length !== 1) {
             continue;
         }
-        matches.set(process.pid, pane);
+        matches.set(process.pid, matchingTerminals[0]);
     }
     return processes.map((process) => {
-        const pane = matches.get(process.pid);
-        if (!pane) {
+        const terminal = matches.get(process.pid);
+        if (!terminal) {
             return process;
         }
         return {
             ...process,
-            terminalControl: terminalRefFromPane(pane, options.capabilities)
+            terminalControl: provider.toControlRef(terminal, options.capabilities ?? ["screen_status", "send_keys"])
         };
     });
 }
+function assertEndpointKind(terminal, kind) {
+    if (terminal.identity.providerKind !== kind) {
+        throw new Error(`terminal control provider ${kind} cannot resolve ` +
+            `${terminal.identity.providerKind}`);
+    }
+}
+function assertTerminalCapability(terminal, capability, supportedCapabilities) {
+    if (!supportedCapabilities.includes(capability) ||
+        !terminal.capabilities.includes(capability)) {
+        throw new Error(`terminal control capability ${capability} is not available for ` +
+            `${terminal.identity.providerKind}:${terminal.route.label}`);
+    }
+}
+function assertProviderCapability(kind, supported, capability) {
+    if (!supported.includes(capability)) {
+        throw new Error(`terminal control provider ${kind} does not support ${capability}`);
+    }
+}
+function assertInputProviderCapability(kind, supported, capability) {
+    if (!supported.includes(capability)) {
+        throw new TerminalControlInputNotSentError(`terminal control provider ${kind} does not support ${capability}`);
+    }
+}
+function intersectCapabilities(requested, supported) {
+    const supportedSet = new Set(supported);
+    return [...new Set(requested)].filter((capability) => supportedSet.has(capability));
+}
+function endpointWithCapabilities(terminal, capabilities) {
+    const providerRef = terminalControlWithCapabilities(tmuxControlFromEndpoint(terminal), capabilities);
+    return createTerminalEndpointRef({
+        identity: terminal.identity,
+        route: terminal.route,
+        processAnchorPid: terminal.processAnchorPid,
+        capabilities,
+        providerRef
+    });
+}
+function tmuxEndpointFromPane(pane, capabilities) {
+    const providerRef = terminalRefFromPane(pane, capabilities);
+    const legacy = terminalEndpointFromControlRef(providerRef);
+    const endpointKey = pane.serverSocketPath
+        ? `socket:${pane.serverSocketPath}`
+        : legacy.identity.endpointKey;
+    const resourceKey = pane.paneId
+        ? `pane-id:${pane.paneId}`
+        : legacy.identity.resourceKey;
+    return createTerminalEndpointRef({
+        identity: {
+            providerKind: "tmux",
+            endpointKey,
+            resourceKey
+        },
+        route: {
+            routeKey: tmuxTerminalRouteKey(endpointKey, pane.target, pane.socketPath),
+            label: pane.target,
+            currentCommand: pane.currentCommand,
+            currentPath: pane.currentPath
+        },
+        processAnchorPid: pane.panePid,
+        capabilities,
+        providerRef
+    });
+}
+function legacyTmuxEndpointMatches(candidate, requested) {
+    if (!requested.identity.resourceKey.startsWith("legacy:")) {
+        return false;
+    }
+    const candidateControl = tmuxControlFromEndpoint(candidate);
+    const requestedControl = tmuxControlFromEndpoint(requested);
+    if (candidateControl.target !== requestedControl.target ||
+        candidateControl.panePid !== requestedControl.panePid) {
+        return false;
+    }
+    if (!requestedControl.socketPath) {
+        return true;
+    }
+    return candidateControl.socketPath === requestedControl.socketPath ||
+        candidate.identity.endpointKey === `socket:${requestedControl.socketPath}`;
+}
+function tmuxControlFromEndpoint(terminal) {
+    assertEndpointKind(terminal, "tmux");
+    const control = terminal.providerRef;
+    if (!isTmuxTerminalControlRef(control)) {
+        throw new Error("tmux terminal endpoint has an invalid provider reference");
+    }
+    return control;
+}
+function tmuxIoRoute(terminal) {
+    const control = tmuxControlFromEndpoint(terminal);
+    const stablePaneId = terminal.identity.resourceKey.startsWith("pane-id:")
+        ? terminal.identity.resourceKey.slice("pane-id:".length)
+        : undefined;
+    const stableSocketPath = terminal.identity.endpointKey.startsWith("socket:")
+        ? terminal.identity.endpointKey.slice("socket:".length)
+        : undefined;
+    return {
+        // tmux's `%pane_id` remains valid across session/window/pane renames and
+        // cannot be confused with a newly reused human selector.
+        target: stablePaneId || control.target,
+        socketPath: stableSocketPath || control.socketPath
+    };
+}
+function isTmuxTerminalControlRef(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const control = value;
+    return control.kind === "tmux" &&
+        typeof control.target === "string" &&
+        typeof control.session === "string" &&
+        Number.isInteger(control.window) &&
+        Number.isInteger(control.pane) &&
+        Number.isInteger(control.panePid) &&
+        Array.isArray(control.capabilities);
+}
+function tmuxPaneFromEndpoint(terminal) {
+    const control = tmuxControlFromEndpoint(terminal);
+    return {
+        kind: "tmux",
+        target: control.target,
+        socketPath: control.socketPath,
+        session: control.session,
+        window: control.window,
+        pane: control.pane,
+        panePid: control.panePid,
+        currentCommand: control.currentCommand,
+        currentPath: control.currentPath
+    };
+}
 export function terminalRefFromPane(pane, capabilities = ["screen_status", "send_keys"]) {
     return {
         kind: "tmux",