Files
Netcatty/application/state/useTerminalBackend.ts
T
205d1591e8 feat(terminal): add disconnect/reconnect on workspace split status bar (#2769) (#2771)
* feat(terminal): add disconnect/reconnect controls on session status bar

Workspace panes could not reach tab-level reconnect. Expose disconnect
(without closing the pane) and reconnect beside the host info actions so
split sessions stay operable. Closes #2769.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix(terminal): abort in-flight boot on status-bar disconnect

Disconnect keeps the pane mounted, so cancel's unmount cleanup never runs.
Flip isBootActiveRef (and isCancelling) so a late startSSH/startMosh attach
cannot resurrect the session after the user disconnects mid-connect.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix(terminal): ignore stale start UI after status-bar disconnect

When disconnect aborts an in-flight connect, starter catch paths must not
reopen auth or repopulate errors. Gate SSH/telnet/mosh/ET/local/serial
failure UI on isTerminalBootActive and harden the boot effect awaits.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix(terminal): hide disconnect/reconnect on compact popup terminals

Owned command popups use compactToolbar with a one-shot startup command.
Exposing reconnect there can re-run that command; keep the controls on
normal tabs/workspace panes only.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix(terminal): use boot epoch so reconnect cannot revive aborted starts

Disconnect alone flipping isBootActiveRef is not enough: an immediate
reconnect re-arms boot, and a late startSSH from the aborted attempt can
still attach. Capture a boot epoch per attempt and ignore stale attaches/UI.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix(terminal): do not let stale attach abort a newer reconnect

tryAttach failure for an expired boot epoch must close the orphan session
only. Calling abortSessionStartAfterUnmount() would force disconnected on
a reconnect that already re-armed boot.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix(terminal): reject late host-key prompts after disconnect

Disconnect can land before pendingHostKeyRequestId is set. Auto-deny
onHostKeyVerification when boot is inactive or status is disconnected
so approval UI cannot reopen on an aborted pane.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix(terminal): cancel wake and MFA when status-bar disconnects

Invalidate hibernation reconnect-wake tokens on disconnect so a late wake
cannot re-arm boot. Reject/cancel keyboard-interactive prompts for
disconnected panes and clear any already-queued MFA for that session.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix(terminal): ignore stale SSH catch UI and password fallback

Check boot attempt currency before resetting reconnect UI state on
SSH start failure, and before launching key→password fallback after
disconnect so a replacement reconnect is not interrupted.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix(terminal): guard stale SSH progress and host-key prompts

Ignore chain-progress callbacks from superseded boot attempts, and
thread bootEpoch through SSH host-key verification so a late prompt
from an aborted start cannot overwrite a replacement reconnect.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix(terminal): correlate MFA and jump host-keys with boot epoch

Forward bootEpoch through jump-host verification and keyboard-interactive
prompts, and reject superseded MFA when the retained tab has already
started a replacement reconnect.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix(terminal): keep replacement SSH session alive across stale starts

Skip closeSession for superseded starts while a newer boot still owns
the shared sessionId, and avoid clearing MFA wait state before the
attempt-freshness guard on SSH success.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix(terminal): own shared sessionIds by boot epoch

Claim SSH/local registry slots with bootEpoch so a stale start cannot
overwrite a replacement, and make closeSession no-op when the payload
epoch does not match the live session owner.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix(terminal): claim bootEpoch for all reconnectable backends

Pass bootEpoch through Telnet/Mosh/ET/serial starts, claim registry slots
the same way as SSH/local, and dispose displaced owners when a newer
boot replaces the shared sessionId.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix(terminal): protect preload listeners and ET artifacts on displace

Defer epoch-scoped closeSession listener teardown until main confirms
ownership, and remove ET external-auth temp artifacts when a newer boot
displaces the previous registry owner.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix(terminal): clean rejected Mosh starts and keep replacement listeners

Kill superseded Mosh/ET PTYs and auth temp files when claimSessionSlot
rejects, and never clear shared preload listeners on epoch-scoped closes.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix(terminal): settle superseded boots and stop displaced log streams

Reject Telnet/SSH claim failures through Promise reject/failReuse instead of
uncaught EventEmitter/.then throws, and stop a displaced session's log stream
so a logging-disabled reconnect cannot append into the old file.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix(terminal): keep woken runtime when disconnect cancels hibernate wake

Disconnect invalidates in-flight hibernated reconnects with keep mode so a
successful wake that already cleared hibernatedRef is not disposed into a
dead pane that can never reconnect. Unmount still disposes orphan runtimes.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix(terminal): bind reused SSH shellPid only to the claimed session

Late PID discovery after Copy Tab reuse must not write onto a newer
bootEpoch that already replaced the shared sessionId registry slot.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix(terminal): await plugin cancel cleanup and clear boot epochs on teardown

Track plugin start/cancel promises so Disconnect→Reconnect waits until the
external session finishes unregistering, and stop unmount teardown from
republishing boot epochs into the process-wide map.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix(terminal): cancel SSH passphrase prompts on disconnect

Register a pending-boot AbortSignal for SSH starts, abort it (and session-
scoped passphrase requests) from closeSession even before a registry slot
exists, and filter/drop late passphrase modals by boot epoch / disconnect.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix(terminal): close owned boot epoch and scope passphrase cancels

Capture the pre-bump epoch for disconnect/teardown closeSession so live
transports are not skipped by epoch mismatch, cancel only passphrase prompts
at or below that epoch, and revalidate boot currency after async passphrase
lookups before queuing a modal.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix(terminal): tag Telnet auto-login and Mosh ready with bootEpoch

Emit bootEpoch on telnet auto-login and mosh:ready events so overlapping
Disconnect→Reconnect boots ignore cross-delivered callbacks meant for an
older shared sessionId.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix(terminal): update disconnect assertion and cancel pending serial opens

Align the disconnect source regression with invalidateBootEpochForClose, and
abort in-flight serialPort.open attempts via pending boot AbortSignal so
Disconnect→Reconnect cannot leave a stale open racing the replacement.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

* fix(terminal): keep flow-pause leases on skipped epoch closes

Worker close:await previously cleared pause ownership in finally even when
the worker returned skipped for an epoch mismatch, dropping the live
replacement's lease. Only clear on non-skipped closes; epoch-scoped
fire-and-forget close similarly defers to onSessionClosed.

Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>
2026-08-06 15:47:20 +08:00

706 lines
25 KiB
TypeScript

import { useCallback, useMemo } from "react";
import { netcattyBridge } from "../../infrastructure/services/netcattyBridge";
import type { TerminalSessionExitEvent } from "./resolveTerminalSessionExitIntent";
type PluginConnectionStartOptions = NetcattyPluginConnectionStartRequest & {
signal?: AbortSignal;
};
const throwIfPluginConnectionStartAborted = (signal?: AbortSignal): void => {
if (!signal?.aborted) return;
const reason = signal.reason;
if (reason instanceof Error) throw reason;
throw new DOMException("Plugin connection request was cancelled", "AbortError");
};
const raceWithPluginConnectionStartAbort = async <T,>(
operation: Promise<T>,
signal?: AbortSignal,
): Promise<T> => {
if (!signal) return operation;
throwIfPluginConnectionStartAborted(signal);
return new Promise<T>((resolve, reject) => {
const onAbort = () => {
reject(signal.reason instanceof Error
? signal.reason
: new DOMException("Plugin connection request was cancelled", "AbortError"));
};
signal.addEventListener("abort", onAbort, { once: true });
operation.then(
(value) => {
signal.removeEventListener("abort", onAbort);
if (signal.aborted) {
onAbort();
return;
}
resolve(value);
},
(error) => {
signal.removeEventListener("abort", onAbort);
reject(error);
},
);
});
};
export async function startPluginConnectionWithBridge(
bridge: Pick<NetcattyBridge, "invokePluginExtensionProvider" | "startPluginConnection">,
options: PluginConnectionStartOptions,
) {
if (!bridge?.startPluginConnection) throw new Error("startPluginConnection unavailable");
if (!bridge.invokePluginExtensionProvider) throw new Error("Plugin connection validation unavailable");
const { signal, ...bridgeOptions } = options;
throwIfPluginConnectionStartAborted(signal);
const validation = await raceWithPluginConnectionStartAbort(bridge.invokePluginExtensionProvider({
requestId: bridgeOptions.requestId,
providerId: bridgeOptions.providerId,
kind: "connection",
operation: "validateConfiguration",
payload: { configuration: bridgeOptions.configuration },
deadlineMs: bridgeOptions.deadlineMs,
}), signal);
throwIfPluginConnectionStartAborted(signal);
if (!validation || typeof validation !== "object" || Array.isArray(validation)
|| (validation as { valid?: unknown }).valid !== true) {
const issues = (validation as { issues?: Array<{ message?: string }> } | null)?.issues;
throw new Error(issues?.[0]?.message || "Plugin connection configuration is invalid");
}
throwIfPluginConnectionStartAborted(signal);
const probe = await raceWithPluginConnectionStartAbort(bridge.invokePluginExtensionProvider({
requestId: bridgeOptions.requestId,
providerId: bridgeOptions.providerId,
kind: "connection",
operation: "probe",
payload: { configuration: bridgeOptions.configuration },
deadlineMs: bridgeOptions.deadlineMs,
}), signal);
throwIfPluginConnectionStartAborted(signal);
if (!probe || typeof probe !== "object" || Array.isArray(probe)
|| (probe as { available?: unknown }).available !== true) {
throw new Error((probe as { message?: string } | null)?.message || "Plugin connection provider is unavailable");
}
return bridge.startPluginConnection(bridgeOptions);
}
export async function signalPluginConnectionWithBridge(
bridge: Pick<NetcattyBridge, "controlPluginConnection">,
sessionId: string,
signal: "interrupt" | "terminate" | "kill" | "eof" | "break" = "interrupt",
) {
if (!bridge?.controlPluginConnection) throw new Error("Plugin connection signaling unavailable");
return bridge.controlPluginConnection(sessionId, "signal", { signal });
}
export const useTerminalBackend = () => {
const telnetAvailable = useCallback(() => {
const bridge = netcattyBridge.get();
return !!bridge?.startTelnetSession;
}, []);
const moshAvailable = useCallback(() => {
const bridge = netcattyBridge.get();
return !!bridge?.startMoshSession;
}, []);
const etAvailable = useCallback(() => {
const bridge = netcattyBridge.get();
return !!bridge?.startEtSession;
}, []);
const localAvailable = useCallback(() => {
const bridge = netcattyBridge.get();
return !!bridge?.startLocalSession;
}, []);
const serialAvailable = useCallback(() => {
const bridge = netcattyBridge.get();
return !!bridge?.startSerialSession;
}, []);
const pluginConnectionAvailable = useCallback(() => {
const bridge = netcattyBridge.get();
return !!bridge?.startPluginConnection;
}, []);
const execAvailable = useCallback(() => {
const bridge = netcattyBridge.get();
return !!bridge?.execCommand;
}, []);
const startSSHSession = useCallback(async (options: NetcattySSHOptions) => {
const bridge = netcattyBridge.get();
if (!bridge?.startSSHSession) throw new Error("startSSHSession unavailable");
return bridge.startSSHSession(options);
}, []);
const startTelnetSession = useCallback(async (options: Parameters<NonNullable<NetcattyBridge["startTelnetSession"]>>[0]) => {
const bridge = netcattyBridge.get();
if (!bridge?.startTelnetSession) throw new Error("startTelnetSession unavailable");
return bridge.startTelnetSession(options);
}, []);
const startMoshSession = useCallback(async (options: Parameters<NonNullable<NetcattyBridge["startMoshSession"]>>[0]) => {
const bridge = netcattyBridge.get();
if (!bridge?.startMoshSession) throw new Error("startMoshSession unavailable");
return bridge.startMoshSession(options);
}, []);
const startEtSession = useCallback(async (options: Parameters<NonNullable<NetcattyBridge["startEtSession"]>>[0]) => {
const bridge = netcattyBridge.get();
if (!bridge?.startEtSession) throw new Error("startEtSession unavailable");
return bridge.startEtSession(options);
}, []);
const startLocalSession = useCallback(async (options: Parameters<NonNullable<NetcattyBridge["startLocalSession"]>>[0]) => {
const bridge = netcattyBridge.get();
if (!bridge?.startLocalSession) throw new Error("startLocalSession unavailable");
return bridge.startLocalSession(options);
}, []);
const startSerialSession = useCallback(async (options: Parameters<NonNullable<NetcattyBridge["startSerialSession"]>>[0]) => {
const bridge = netcattyBridge.get();
if (!bridge?.startSerialSession) throw new Error("startSerialSession unavailable");
return bridge.startSerialSession(options);
}, []);
const startPluginConnection = useCallback(async (options: PluginConnectionStartOptions) => {
const bridge = netcattyBridge.get();
if (!bridge) throw new Error("startPluginConnection unavailable");
return startPluginConnectionWithBridge(bridge, options);
}, []);
const cancelPluginExtensionRequest = useCallback(async (requestId: string) => {
const bridge = netcattyBridge.get();
return bridge?.cancelPluginExtensionRequest?.(requestId) ?? false;
}, []);
const signalPluginConnection = useCallback(async (
sessionId: string,
signal: "interrupt" | "terminate" | "kill" | "eof" | "break" = "interrupt",
) => {
const bridge = netcattyBridge.get();
if (!bridge) throw new Error("Plugin connection signaling unavailable");
return signalPluginConnectionWithBridge(bridge, sessionId, signal);
}, []);
const execCommand = useCallback(async (options: Parameters<NetcattyBridge["execCommand"]>[0]) => {
const bridge = netcattyBridge.get();
if (!bridge?.execCommand) throw new Error("execCommand unavailable");
return bridge.execCommand(options);
}, []);
const setupOsc7Tracking = useCallback(async (sessionId: string, command: string) => {
const bridge = netcattyBridge.get();
if (!bridge?.setupOsc7Tracking) {
return { success: false, error: "setupOsc7Tracking unavailable" };
}
return bridge.setupOsc7Tracking(sessionId, command);
}, []);
const writeToSession = useCallback((sessionId: string, data: string, options?: Parameters<NonNullable<NetcattyBridge["writeToSession"]>>[2]) => {
const bridge = netcattyBridge.get();
bridge?.writeToSession?.(sessionId, data, options);
}, []);
const interruptSession = useCallback((sessionId: string, trace?: NetcattyTerminalInterruptTrace) => {
const bridge = netcattyBridge.get();
if (bridge?.interruptSession) {
bridge.interruptSession(sessionId, trace);
return;
}
bridge?.writeToSession?.(sessionId, "\x03");
}, []);
const resizeSession = useCallback((sessionId: string, cols: number, rows: number) => {
const bridge = netcattyBridge.get();
bridge?.resizeSession?.(sessionId, cols, rows);
}, []);
const clearSessionPtyBuffer = useCallback((sessionId: string) => {
const bridge = netcattyBridge.get();
bridge?.clearSessionPtyBuffer?.(sessionId);
}, []);
const setSessionFlowPaused = useCallback((sessionId: string, paused: boolean) => {
const bridge = netcattyBridge.get();
bridge?.setSessionFlowPaused?.(sessionId, paused);
}, []);
const setSessionFlowPausedAndWait = useCallback(async (sessionId: string, paused: boolean) => {
const bridge = netcattyBridge.get();
if (!bridge?.setSessionFlowPausedAndWait) {
bridge?.setSessionFlowPaused?.(sessionId, paused);
return paused
? { success: false, error: "Output drain unavailable" }
: { success: true };
}
return bridge.setSessionFlowPausedAndWait(sessionId, paused);
}, []);
const acquireSessionFlowPauseLease = useCallback(async (sessionId: string) => {
const bridge = netcattyBridge.get();
if (!bridge?.acquireSessionFlowPauseLease) {
throw new Error("Terminal flow pause leases unavailable");
}
const acquired = await bridge.acquireSessionFlowPauseLease(sessionId);
if (!acquired?.success || !acquired.leaseId) {
throw new Error(acquired?.error || "Failed to pause terminal output");
}
const leaseId = acquired.leaseId;
let released = false;
return {
release: (options?: { keepPaused?: boolean }) => {
if (released) return;
released = true;
void bridge.releaseSessionFlowPauseLease?.(
sessionId,
leaseId,
options,
);
},
waitForPause: async () => {
if (!bridge.waitSessionFlowPauseLease) {
return { success: false, error: "Output drain unavailable" };
}
return bridge.waitSessionFlowPauseLease(sessionId, leaseId);
},
};
}, []);
const ackSessionFlow = useCallback((sessionId: string, bytes: number) => {
const bridge = netcattyBridge.get();
bridge?.ackSessionFlow?.(sessionId, bytes);
}, []);
const notifyTerminalSessionDisplayReady = useCallback((sessionId: string) => {
netcattyBridge.get()?.notifyTerminalSessionDisplayReady?.(sessionId);
}, []);
const closeSession = useCallback(async (sessionId: string, options?: { bootEpoch?: number }) => {
const bridge = netcattyBridge.get();
await bridge?.closeSession?.(sessionId, options);
}, []);
const rebindSessionOutput = useCallback(async (sessionId: string, authorization: string) => {
const bridge = netcattyBridge.get();
if (!bridge?.rebindTerminalSessionOutput) {
return { success: false as const, error: "rebindTerminalSessionOutput unavailable" };
}
return bridge.rebindTerminalSessionOutput(sessionId, authorization);
}, []);
const restoreSessionOutput = useCallback(async (
sessionId: string,
webContentsId?: number | null,
authorization?: string,
) => {
const bridge = netcattyBridge.get();
if (!bridge?.restoreTerminalSessionOutput) {
return { success: false as const, error: "restoreTerminalSessionOutput unavailable" };
}
return bridge.restoreTerminalSessionOutput(sessionId, webContentsId, authorization);
}, []);
const requestSessionSnapshot = useCallback(async (sessionId: string, authorization: string) => {
const bridge = netcattyBridge.get();
if (!bridge?.requestTerminalSessionSnapshot) {
return { success: false as const, snapshot: "", error: "requestTerminalSessionSnapshot unavailable" };
}
return bridge.requestTerminalSessionSnapshot(sessionId, authorization);
}, []);
const applySessionSnapshot = useCallback(async (
sessionId: string,
snapshot: string,
context: {
contextSnapshot: string;
contextViewportSnapshot: string;
contextScrollbackSnapshot: string;
alternateScreen: boolean;
kittyKeyboardModeState?: NetcattyKittyKeyboardModeState;
kittyKeyboardProtocolEnabled?: boolean;
},
authorization: string,
) => {
const bridge = netcattyBridge.get();
if (!bridge?.applyTerminalSessionSnapshot) {
return { success: false as const, error: "applyTerminalSessionSnapshot unavailable" };
}
return bridge.applyTerminalSessionSnapshot(sessionId, snapshot, context, authorization);
}, []);
const setSessionEncoding = useCallback(async (sessionId: string, encoding: string) => {
const bridge = netcattyBridge.get();
if (!bridge?.setSessionEncoding) return { ok: false, encoding };
return bridge.setSessionEncoding(sessionId, encoding);
}, []);
const onSessionData = useCallback((
sessionId: string,
cb: Parameters<NetcattyBridge["onSessionData"]>[1],
options?: Parameters<NetcattyBridge["onSessionData"]>[2],
) => {
const bridge = netcattyBridge.get();
if (!bridge?.onSessionData) throw new Error("onSessionData unavailable");
return bridge.onSessionData(sessionId, cb, options);
}, []);
const onSessionExit = useCallback((sessionId: string, cb: (evt: TerminalSessionExitEvent) => void) => {
const bridge = netcattyBridge.get();
if (!bridge?.onSessionExit) throw new Error("onSessionExit unavailable");
return bridge.onSessionExit(sessionId, cb);
}, []);
const onTelnetAutoLoginComplete = useCallback((sessionId: string, cb: (evt: { sessionId: string; bootEpoch?: number }) => void) => {
const bridge = netcattyBridge.get();
return bridge?.onTelnetAutoLoginComplete?.(sessionId, cb);
}, []);
const onTelnetAutoLoginCancelled = useCallback((sessionId: string, cb: (evt: { sessionId: string; bootEpoch?: number }) => void) => {
const bridge = netcattyBridge.get();
return bridge?.onTelnetAutoLoginCancelled?.(sessionId, cb);
}, []);
const onMoshSessionReady = useCallback((sessionId: string, cb: (evt: { sessionId: string; bootEpoch?: number }) => void) => {
const bridge = netcattyBridge.get();
return bridge?.onMoshSessionReady?.(sessionId, cb);
}, []);
const onTelnetEchoMode = useCallback((sessionId: string, cb: (evt: { sessionId: string; remoteEcho: boolean; localEcho: boolean }) => void) => {
const bridge = netcattyBridge.get();
return bridge?.onTelnetEchoMode?.(sessionId, cb);
}, []);
const getTelnetEchoMode = useCallback(async (sessionId: string) => {
const bridge = netcattyBridge.get();
if (!bridge?.getTelnetEchoMode) return { success: false as const, error: "getTelnetEchoMode unavailable" };
return bridge.getTelnetEchoMode(sessionId);
}, []);
const onChainProgress = useCallback((cb: (sessionId: string, hop: number, total: number, label: string, status: string, error?: string) => void) => {
const bridge = netcattyBridge.get();
return bridge?.onChainProgress?.(cb);
}, []);
const onConnectionReuseFallback = useCallback((cb: (sessionId: string, sourceSessionId?: string) => void) => {
const bridge = netcattyBridge.get();
return bridge?.onConnectionReuseFallback?.(cb);
}, []);
const onWindowFullScreenChanged = useCallback((cb: (isFullscreen: boolean) => void) => {
const bridge = netcattyBridge.get();
return bridge?.onWindowFullScreenChanged?.(cb);
}, []);
const onWindowShown = useCallback((cb: () => void) => {
const bridge = netcattyBridge.get();
return bridge?.onWindowShown?.(cb);
}, []);
const onHostKeyVerification = useCallback((cb: Parameters<NonNullable<NetcattyBridge["onHostKeyVerification"]>>[0]) => {
const bridge = netcattyBridge.get();
return bridge?.onHostKeyVerification?.(cb);
}, []);
const respondHostKeyVerification = useCallback(async (
requestId: string,
accept: boolean,
addToKnownHosts?: boolean,
) => {
const bridge = netcattyBridge.get();
if (!bridge?.respondHostKeyVerification) {
return { success: false, error: "respondHostKeyVerification unavailable" };
}
return bridge.respondHostKeyVerification(requestId, accept, addToKnownHosts);
}, []);
const openExternal = useCallback(async (url: string) => {
const bridge = netcattyBridge.get();
await bridge?.openExternal?.(url);
}, []);
const openExternalAvailable = useCallback(() => {
const bridge = netcattyBridge.get();
return !!bridge?.openExternal;
}, []);
const backendAvailable = useCallback(() => {
const bridge = netcattyBridge.get();
return !!bridge?.startSSHSession;
}, []);
const listSerialPorts = useCallback(async () => {
const bridge = netcattyBridge.get();
if (!bridge?.listSerialPorts) return [];
return bridge.listSerialPorts();
}, []);
const serialYmodemAvailable = useCallback(() => {
const bridge = netcattyBridge.get();
return !!bridge?.sendSerialYmodem;
}, []);
const serialYmodemReceiveAvailable = useCallback(() => {
const bridge = netcattyBridge.get();
return !!bridge?.receiveSerialYmodem;
}, []);
const selectFileAvailable = useCallback(() => {
const bridge = netcattyBridge.get();
return !!bridge?.selectFile;
}, []);
const selectDirectoryAvailable = useCallback(() => {
const bridge = netcattyBridge.get();
return !!bridge?.selectDirectory;
}, []);
const sendSerialYmodem = useCallback(async (sessionId: string, filePath: string) => {
const bridge = netcattyBridge.get();
if (!bridge?.sendSerialYmodem) return { success: false, error: 'sendSerialYmodem unavailable' };
return bridge.sendSerialYmodem(sessionId, filePath);
}, []);
const receiveSerialYmodem = useCallback(async (sessionId: string, destinationDir: string) => {
const bridge = netcattyBridge.get();
if (!bridge?.receiveSerialYmodem) return { success: false, error: 'receiveSerialYmodem unavailable' };
return bridge.receiveSerialYmodem(sessionId, destinationDir);
}, []);
const selectFile = useCallback(async (
title?: string,
defaultPath?: string,
filters?: Array<{ name: string; extensions: string[] }>,
) => {
const bridge = netcattyBridge.get();
if (!bridge?.selectFile) return null;
return bridge.selectFile(title, defaultPath, filters);
}, []);
const selectDirectory = useCallback(async (title?: string, defaultPath?: string) => {
const bridge = netcattyBridge.get();
if (!bridge?.selectDirectory) return null;
return bridge.selectDirectory(title, defaultPath);
}, []);
const startZmodemDragDropUpload = useCallback(async (
sessionId: string,
files: Array<{
path?: string;
name: string;
remoteName: string;
data?: ArrayBuffer;
}>,
uploadCommand?: string,
) => {
const bridge = netcattyBridge.get();
if (!bridge?.startZmodemDragDropUpload) {
return { success: false, error: "startZmodemDragDropUpload unavailable" };
}
return bridge.startZmodemDragDropUpload(sessionId, files, uploadCommand);
}, []);
const cancelZmodem = useCallback((sessionId: string, options?: { interrupt?: boolean }) => {
const bridge = netcattyBridge.get();
bridge?.cancelZmodem?.(sessionId, options);
}, []);
const onZmodemEvent = useCallback((
sessionId: string,
cb: Parameters<NonNullable<NetcattyBridge["onZmodemEvent"]>>[1],
) => {
const bridge = netcattyBridge.get();
return bridge?.onZmodemEvent?.(sessionId, cb) ?? (() => {});
}, []);
const getSessionPwd = useCallback(async (sessionId: string, options?: { allowHomeFallback?: boolean }) => {
const bridge = netcattyBridge.get();
if (!bridge?.getSessionPwd) return { success: false, error: 'getSessionPwd unavailable' };
return bridge.getSessionPwd(sessionId, options);
}, []);
const getSessionRemoteInfo = useCallback(async (sessionId: string) => {
const bridge = netcattyBridge.get();
if (!bridge?.getSessionRemoteInfo) {
return { success: false, error: 'getSessionRemoteInfo unavailable' };
}
return bridge.getSessionRemoteInfo(sessionId);
}, []);
const getSessionDistroInfo = useCallback(async (sessionId: string) => {
const bridge = netcattyBridge.get();
if (!bridge?.getSessionDistroInfo) {
return { success: false, error: 'getSessionDistroInfo unavailable' };
}
return bridge.getSessionDistroInfo(sessionId);
}, []);
const getServerStats = useCallback(async (sessionId: string) => {
const bridge = netcattyBridge.get();
if (!bridge?.getServerStats) return { success: false, error: 'getServerStats unavailable' };
return bridge.getServerStats(sessionId);
}, []);
// Memoize the returned object so its identity is stable across the
// hook's lifetime. Each method above is already useCallback([])-stable,
// so listing them as deps means useMemo recomputes once and then
// caches forever. Without this, every render produced a fresh object
// literal — making `terminalBackend` an unstable reference that
// forced consumers' useEffects (`}, [..., terminalBackend])`) to
// rerun on every parent render and forced lint to flag any deeper
// property dep (`}, [terminalBackend.onHostKeyVerification])`) it
// couldn't statically prove safe.
return useMemo(
() => {
const api = {
backendAvailable,
telnetAvailable,
moshAvailable,
etAvailable,
localAvailable,
serialAvailable,
pluginConnectionAvailable,
execAvailable,
openExternalAvailable,
startSSHSession,
startTelnetSession,
startMoshSession,
startEtSession,
startLocalSession,
startSerialSession,
startPluginConnection,
cancelPluginExtensionRequest,
signalPluginConnection,
listSerialPorts,
serialYmodemAvailable,
serialYmodemReceiveAvailable,
selectFileAvailable,
selectDirectoryAvailable,
sendSerialYmodem,
receiveSerialYmodem,
selectFile,
selectDirectory,
startZmodemDragDropUpload,
cancelZmodem,
onZmodemEvent,
execCommand,
setupOsc7Tracking,
getSessionPwd,
getSessionRemoteInfo,
getSessionDistroInfo,
getServerStats,
writeToSession,
interruptSession,
resizeSession,
clearSessionPtyBuffer,
setSessionFlowPaused,
setSessionFlowPausedAndWait,
acquireSessionFlowPauseLease,
ackSessionFlow,
notifyTerminalSessionDisplayReady,
closeSession,
rebindSessionOutput,
restoreSessionOutput,
requestSessionSnapshot,
applySessionSnapshot,
setSessionEncoding,
onSessionData,
onSessionExit,
onTelnetAutoLoginComplete,
onTelnetAutoLoginCancelled,
onTelnetEchoMode,
getTelnetEchoMode,
onChainProgress,
onConnectionReuseFallback,
onWindowFullScreenChanged,
onWindowShown,
onHostKeyVerification,
respondHostKeyVerification,
openExternal,
};
// Only surface onMoshSessionReady when the bridge actually implements it.
// A always-truthy wrapper would skip the documented no-event fallback and
// leave mosh startup/scripts waiting forever on older builds.
Object.defineProperty(api, "onMoshSessionReady", {
enumerable: true,
configurable: true,
get() {
const bridge = netcattyBridge.get();
if (typeof bridge?.onMoshSessionReady !== "function") {
return undefined;
}
return onMoshSessionReady;
},
});
return api;
},
[
backendAvailable,
telnetAvailable,
moshAvailable,
etAvailable,
localAvailable,
serialAvailable,
pluginConnectionAvailable,
execAvailable,
openExternalAvailable,
startSSHSession,
startTelnetSession,
startMoshSession,
startEtSession,
startLocalSession,
startSerialSession,
startPluginConnection,
cancelPluginExtensionRequest,
signalPluginConnection,
listSerialPorts,
serialYmodemAvailable,
serialYmodemReceiveAvailable,
selectFileAvailable,
selectDirectoryAvailable,
sendSerialYmodem,
receiveSerialYmodem,
selectFile,
selectDirectory,
startZmodemDragDropUpload,
cancelZmodem,
onZmodemEvent,
execCommand,
setupOsc7Tracking,
getSessionPwd,
getSessionRemoteInfo,
getSessionDistroInfo,
getServerStats,
writeToSession,
interruptSession,
resizeSession,
clearSessionPtyBuffer,
setSessionFlowPaused,
setSessionFlowPausedAndWait,
acquireSessionFlowPauseLease,
ackSessionFlow,
notifyTerminalSessionDisplayReady,
closeSession,
rebindSessionOutput,
restoreSessionOutput,
requestSessionSnapshot,
applySessionSnapshot,
setSessionEncoding,
onSessionData,
onSessionExit,
onTelnetAutoLoginComplete,
onTelnetAutoLoginCancelled,
onMoshSessionReady,
onTelnetEchoMode,
getTelnetEchoMode,
onChainProgress,
onConnectionReuseFallback,
onWindowFullScreenChanged,
onWindowShown,
onHostKeyVerification,
respondHostKeyVerification,
openExternal,
],
);
};