Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import '@xterm/xterm/css/xterm.css';
import {
assertNeverPtyAdoptReason,
assertNeverPtyCreateReason,
assetOpenRefusalRevealsInstead,
} from '@inkeep/open-knowledge-core/desktop-bridge';
import {
BRACKETED_PASTE_ENABLE_MARKER,
buildPosixCliLaunch,
buildStartupInjectionBytes,
buildTerminalInputBytes,
buildWindowsCliLaunch,
quoteWindowsShellPath,
shellSingleQuote,
startupInjectionFor,
type TerminalCli,
type TerminalLaunchCommand,
type WindowsShellFamily,
} from '@inkeep/open-knowledge-core/handoff';
import { useLingui } from '@lingui/react/macro';
import { FitAddon } from '@xterm/addon-fit';
import { Unicode11Addon } from '@xterm/addon-unicode11';
import { WebLinksAddon } from '@xterm/addon-web-links';
import { WebglAddon } from '@xterm/addon-webgl';
import { Terminal } from '@xterm/xterm';
import { useTheme } from 'next-themes';
import { use, useEffect, useRef, useState } from 'react';
import { ConfigContext } from '@/lib/config-context';
import type { OkDesktopBridge, OkPtyNotice } from '@/lib/desktop-bridge-types';
import { revealEditor } from '@/lib/reveal-editor';
import { cn } from '@/lib/utils';
import { getPageListCache } from '../editor/page-list-cache';
import { filePathToDocName, hashFromDocName, hashFromFolderPath } from '../lib/doc-hash';
import type { TerminalCliLaunchIntent, TerminalLaunchIntent } from './EditorPane';
import { filesFromExternalDrop, isExternalFileDrag } from './file-tree-adapter';
import {
type TerminalCommandId,
terminalCommandFor,
windowsTerminalCommandFor,
} from './handoff/terminal-command-events';
import { registerBracketedPasteProbe } from './handoff/terminal-paste-mode';
import { TerminalAgentConnectionBanner } from './TerminalAgentConnectionBanner';
import { TerminalCliMissingBanner } from './TerminalCliMissingBanner';
import { TerminalCliUnverifiedBanner } from './TerminalCliUnverifiedBanner';
import { type TerminalExitInfo, TerminalExitNotice } from './TerminalExitNotice';
import { TerminalNoticeBanner } from './TerminalNoticeBanner';
import { TerminalRefusalNotice } from './TerminalRefusalNotice';
import { TerminalStartingNotice } from './TerminalStartingNotice';
import { isRenderedContainer, shouldFitForResize } from './terminal-fit-gate';
import { createTerminalFileLinkProvider } from './terminal-link-provider';
import { createRecentOpenGuard, type TerminalLinkTarget } from './terminal-links';
import { createSameFrameRepaint } from './terminal-render-flush';
import { createResizeThrottle } from './terminal-resize-throttle';
import { restoreScrollReach } from './terminal-scroll-reach';
import { nextWheelReports, sgrWheelReport, wheelReportPosition } from './terminal-wheel';
import { useLiveXtermTheme } from './use-live-xterm-theme';
const PTY_RESIZE_THROTTLE_MS = 100;
export const STAGE_PASTE_SETTLE_MS = 500;
export const STAGE_PASTE_CAP_MS = 4000;
interface TerminalPanelProps {
readonly bridge: OkDesktopBridge;
readonly className?: string;
readonly onClose?: () => void;
readonly onExit?: (info: { readonly exitCode: number; readonly signal: number | null }) => void;
readonly onTitleChange?: (title: string) => void;
readonly launch?: TerminalLaunchIntent | null;
readonly commandId?: TerminalCommandId | null;
readonly adoptPtyId?: string | null;
readonly onPtyId?: (ptyId: string | null) => void;
}
export function TerminalPanel({
bridge,
className,
onClose,
onExit,
onTitleChange,
launch = null,
commandId = null,
adoptPtyId = null,
onPtyId,
}: TerminalPanelProps) {
const { t } = useLingui();
const { resolvedTheme } = useTheme();
const xtermTheme = useLiveXtermTheme(resolvedTheme);
const [restartKey, setRestartKey] = useState(0);
const adoptForThisMount = restartKey === 0 ? adoptPtyId : null;
return (
<section
aria-label={t`Terminal`}
style={{ backgroundColor: xtermTheme.background }}
className={cn('relative flex h-full w-full flex-col overflow-hidden', className)}
>
<div className="relative min-h-0 flex-1">
<TerminalSession
key={restartKey}
bridge={bridge}
onClose={onClose}
onExit={onExit}
onTitleChange={onTitleChange}
onRestart={() => setRestartKey((k) => k + 1)}
launch={launch}
commandId={commandId}
adoptPtyId={adoptForThisMount}
onPtyId={onPtyId}
/>
</div>
</section>
);
}
type SessionStatus = 'starting' | 'running' | 'no-project' | 'not-consented' | 'exited';
interface TerminalSessionProps {
readonly bridge: OkDesktopBridge;
readonly onClose?: () => void;
readonly onExit?: (info: { readonly exitCode: number; readonly signal: number | null }) => void;
readonly onTitleChange?: (title: string) => void;
readonly onRestart: () => void;
readonly launch?: TerminalLaunchIntent | null;
readonly commandId?: TerminalCommandId | null;
readonly adoptPtyId?: string | null;
readonly onPtyId?: (ptyId: string | null) => void;
}
function TerminalSession({
bridge,
onClose,
onExit,
onTitleChange,
onRestart,
launch = null,
commandId = null,
adoptPtyId = null,
onPtyId,
}: TerminalSessionProps) {
const { t } = useLingui();
const containerRef = useRef<HTMLDivElement | null>(null);
const onExitRef = useRef(onExit);
const onTitleChangeRef = useRef(onTitleChange);
const onPtyIdRef = useRef(onPtyId);
const { resolvedTheme } = useTheme();
const xtermTheme = useLiveXtermTheme(resolvedTheme);
const termRef = useRef<Terminal | null>(null);
const initialXtermThemeRef = useRef(xtermTheme);
const [status, setStatus] = useState<SessionStatus>('starting');
const [hasOutput, setHasOutput] = useState(false);
const [connectionCli, setConnectionCli] = useState<TerminalCli | null>(null);
const [exitInfo, setExitInfo] = useState<TerminalExitInfo | null>(null);
const [shellNotice, setShellNotice] = useState<Extract<
OkPtyNotice,
{ notice: 'invalid-shell-override' }
> | null>(null);
const [supportFileNotice, setSupportFileNotice] = useState<Extract<
OkPtyNotice,
{ notice: 'support-file-degraded' }
> | null>(null);
const [pathDropNotice, setPathDropNotice] = useState(false);
const [manualSubmitNotice, setManualSubmitNotice] = useState(false);
const ptyIdRef = useRef<string | null>(null);
const terminalInputEnabledRef = useRef(false);
const terminalInputRef = useRef<(data: string) => void>(() => undefined);
const [cliNotice, setCliNotice] = useState<
{ cli: TerminalCli; kind: 'unverified' } | { cli: TerminalCli; kind: 'not-found' } | null
>(null);
const configCtx = use(ConfigContext);
const autoApproveOkToolsRef = useRef(configCtx?.userConfig?.agents?.autoApproveOkTools ?? true);
const shellFamilyRef = useRef<WindowsShellFamily | null>(null);
useEffect(() => {
onExitRef.current = onExit;
onTitleChangeRef.current = onTitleChange;
onPtyIdRef.current = onPtyId;
autoApproveOkToolsRef.current = configCtx?.userConfig?.agents?.autoApproveOkTools ?? true;
});
useEffect(() => {
const container = containerRef.current;
if (!container) return;
setConnectionCli(null);
setCliNotice(null);
setManualSubmitNotice(false);
setSupportFileNotice(null);
setShellNotice(null);
setPathDropNotice(false);
terminalInputEnabledRef.current = false;
let cancelled = false;
let sessionEnded = false;
let shellLive = false;
let ptyId: string | null = null;
let unsubData: (() => void) | undefined;
let unsubExit: (() => void) | undefined;
let unsubNotice: (() => void) | undefined;
let pendingShellNotices: OkPtyNotice[] = [];
let launchCapabilityLimited = false;
let readinessScan: ((data: string) => void) | undefined;
const armReadinessScan = (marker: string, onReady: () => void): void => {
let acc = '';
readinessScan = (data) => {
acc += data;
if (acc.includes(marker)) {
readinessScan = undefined;
onReady();
return;
}
if (acc.length > marker.length + 256) acc = acc.slice(-(marker.length + 256));
};
};
let unregisterPasteProbe: () => void = () => undefined;
let injectCapTimer: ReturnType<typeof setTimeout> | undefined;
let titleDisposable: { dispose(): void } | undefined;
let linkProviderDisposable: { dispose(): void } | undefined;
let observer: ResizeObserver | undefined;
let canvasPixelObserver: ResizeObserver | undefined;
let ptyResizeThrottle: ReturnType<typeof createResizeThrottle> | undefined;
let documentUnloading = false;
const markDocumentUnloading = (event: PageTransitionEvent): void => {
documentUnloading = !event.persisted;
};
const markDocumentVisible = (): void => {
if (document.visibilityState === 'visible') documentUnloading = false;
};
window.addEventListener('pagehide', markDocumentUnloading);
document.addEventListener('visibilitychange', markDocumentVisible);
const applyShellNotice = (notice: OkPtyNotice): void => {
if (notice.notice === 'shell-resolved') {
shellFamilyRef.current = notice.shellFamily;
} else if (notice.notice === 'invalid-shell-override') {
if (notice.reason === 'unsupported-family') launchCapabilityLimited = true;
setShellNotice(notice);
} else {
setSupportFileNotice(notice);
}
};
unsubNotice = bridge.terminal.onNotice((msg) => {
if (ptyId === null) {
pendingShellNotices.push(msg);
return;
}
if (msg.ptyId !== ptyId) return;
applyShellNotice(msg);
});
const screenReaderModeAtMount =
bridge.config.e2eSmoke === true || (bridge.accessibility?.isScreenReaderActive() ?? true);
const recentOpen = createRecentOpenGuard();
const openUrl = (uri: string) => {
if (termRef.current?.modes.mouseTrackingMode !== 'none') return;
if (recentOpen(uri, Date.now())) return;
void bridge.shell.openExternal(uri);
};
const term = new Terminal({
screenReaderMode: screenReaderModeAtMount,
minimumContrastRatio: 4.5,
allowProposedApi: true,
cursorBlink: true,
fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Monaco, monospace',
fontSize: 13,
scrollback: 10000,
smoothScrollDuration: 125,
scrollSensitivity: 3,
windowsPty: bridge.platform === 'win32' ? { backend: 'conpty' } : undefined,
linkHandler: {
activate: (_event, uri) => openUrl(uri),
},
theme: initialXtermThemeRef.current,
});
termRef.current = term;
const fit = new FitAddon();
term.loadAddon(fit);
term.loadAddon(new Unicode11Addon());
term.unicode.activeVersion = '11';
term.loadAddon(new WebLinksAddon((_event, uri) => openUrl(uri)));
term.open(container);
const activateFileLink = (target: TerminalLinkTarget) => {
switch (target.kind) {
case 'doc':
revealEditor();
window.location.hash = hashFromDocName(filePathToDocName(target.relPath));
return;
case 'folder':
revealEditor();
window.location.hash = hashFromFolderPath(target.relPath);
return;
case 'external':
void bridge.shell
.revealExternal(target.absPath)
.catch((err) => console.warn('[terminal] revealExternal failed:', err));
return;
case 'asset':
void bridge.shell
.openAsset(target.relPath)
.then((result) => {
if (result.ok) return;
if (assetOpenRefusalRevealsInstead(result.reason)) {
void bridge.shell
.revealAsset(target.relPath)
.catch((err) => console.warn('[terminal] revealAsset failed:', err));
return;
}
console.warn('[terminal] openAsset refused:', result.reason);
})
.catch((err) => console.warn('[terminal] openAsset failed:', err));
return;
default: {
const _never: never = target;
return _never;
}
}
};
linkProviderDisposable = term.registerLinkProvider(
createTerminalFileLinkProvider({
projectPath: bridge.config.projectPath,
readLogicalLine: (bufferLineNumber) => {
const buf = term.buffer.active;
const idx = bufferLineNumber - 1;
if (!buf.getLine(idx)) return undefined;
let start = idx;
while (start > 0 && buf.getLine(start)?.isWrapped) start--;
let end = idx;
while (buf.getLine(end + 1)?.isWrapped) end++;
let text = '';
for (let row = start; row <= end; row++) {
text += buf.getLine(row)?.translateToString(false) ?? '';
}
return { text, startLine: start + 1, cols: term.cols };
},
getSnapshot: getPageListCache,
checkTargetExists: (kind, path) =>
bridge.project.checkTargetExists({
projectPath: bridge.config.projectPath,
kind,
path,
}),
onActivate: activateFileLink,
}),
);
const useDomRenderer = bridge.config.e2eSmoke === true;
if (!useDomRenderer) {
try {
const webgl = new WebglAddon();
webgl.onContextLoss(() => {
console.warn('[terminal] WebGL context lost, falling back to DOM renderer');
webgl.dispose();
});
term.loadAddon(webgl);
} catch (err) {
const expected = err instanceof Error && /webgl2?|context/i.test(err.message);
const log = expected ? console.warn : console.error;
log('[terminal] WebGL addon failed, using DOM renderer:', err);
}
}
if (
isRenderedContainer(container.getBoundingClientRect(), window.getComputedStyle(container))
) {
fit.fit();
}
const repaintSameFrame = createSameFrameRepaint(term);
const webglCanvas = container.querySelector<HTMLCanvasElement>('.xterm-screen canvas');
if (webglCanvas !== null) {
canvasPixelObserver = new ResizeObserver(() => repaintSameFrame());
try {
canvasPixelObserver.observe(webglCanvas, { box: 'device-pixel-content-box' });
} catch (err) {
console.warn('[terminal] device-pixel canvas observe failed:', err);
canvasPixelObserver.disconnect();
canvasPixelObserver = undefined;
}
}
titleDisposable = term.onTitleChange((title) => {
if (!cancelled) onTitleChangeRef.current?.(title);
});
const sendInput = (data: string): void => {
const livePtyId = ptyIdRef.current;
if (cancelled || !terminalInputEnabledRef.current || livePtyId === null) return;
bridge.terminal.input(livePtyId, data);
};
terminalInputRef.current = sendInput;
const markInteractive = (): void => {
if (cancelled || sessionEnded || terminalInputEnabledRef.current) return;
terminalInputEnabledRef.current = true;
setStatus('running');
const active = document.activeElement;
const sessionHost = term.element?.closest('[data-session-id]') ?? term.element;
const focusUnclaimed =
active === null || active === document.body || sessionHost?.contains(active) === true;
const hostRect = sessionHost?.getBoundingClientRect();
const hostOnScreen =
sessionHost?.closest('[inert]') == null &&
hostRect !== undefined &&
hostRect.width > 0 &&
hostRect.height > 0;
if (focusUnclaimed || hostOnScreen) term.focus();
};
term.attachCustomKeyEventHandler((event) => {
if (event.type !== 'keydown') return true;
const key = event.key.toLowerCase();
const platformClipboardKey =
(bridge.platform === 'linux' || bridge.platform === 'win32') &&
event.ctrlKey &&
!event.altKey &&
!event.metaKey &&
(key === 'c' || key === 'v');
if (platformClipboardKey) {
event.preventDefault();
if (key === 'c') {
const hasSelection = term.hasSelection();
const copiesSelection = event.shiftKey || (bridge.platform === 'win32' && hasSelection);
if (!copiesSelection) return true;
if (hasSelection && navigator.clipboard?.writeText) {
void navigator.clipboard
.writeText(term.getSelection())
.catch((err) => console.warn('[terminal] clipboard copy failed', err));
}
if (bridge.platform === 'win32') term.clearSelection();
return false;
}
if (!event.shiftKey && bridge.platform !== 'win32') return true;
if (!terminalInputEnabledRef.current) return false;
if (navigator.clipboard?.readText) {
void navigator.clipboard
.readText()
.then((text) => {
const ptyId = ptyIdRef.current;
if (!cancelled && ptyId !== null) term.paste(text);
})
.catch((err) => console.warn('[terminal] clipboard paste failed', err));
}
return false;
}
if (!event.shiftKey) return true;
if (event.key === 'Tab') {
event.preventDefault();
return true;
}
if (event.key === 'Enter') {
const ptyId = ptyIdRef.current;
if (ptyId === null) return true;
event.preventDefault();
sendInput('\n');
return false;
}
return true;
});
let wheelRowAccumulator = 0;
let warnedMissingCellHeight = false;
term.attachCustomWheelEventHandler((event) => {
const core = (
term as unknown as {
_core?: {
coreMouseService?: { activeEncoding?: string };
_renderService?: {
dimensions?: { css?: { cell?: { width?: number; height?: number } } };
};
};
}
)._core;
const encoding = core?.coreMouseService?.activeEncoding;
const sgrTrackingActive =
term.modes.mouseTrackingMode !== 'none' &&
(encoding === 'SGR' || encoding === 'SGR_PIXELS');
if (!sgrTrackingActive) {
wheelRowAccumulator = 0;
return true;
}
if (!terminalInputEnabledRef.current || event.deltaY === 0) return true;
const measuredCellHeight = core?._renderService?.dimensions?.css?.cell?.height;
if (measuredCellHeight === undefined && !warnedMissingCellHeight) {
warnedMissingCellHeight = true;
console.warn(
'[terminal] xterm cell-height internal not found; wheel scroll using fallback. An xterm upgrade may have moved _core._renderService.dimensions.css.cell.height.',
);
}
const cellHeight = measuredCellHeight ?? 17;
const { count, button, accumulator } = nextWheelReports(
event.deltaY,
event.deltaMode,
wheelRowAccumulator,
{ cellHeight, sensitivity: 1.5, maxRowsPerEvent: 20, viewportRows: term.rows },
);
wheelRowAccumulator = accumulator;
if (count > 0) {
const rect = (
term.element?.querySelector('.xterm-screen') ?? term.element
)?.getBoundingClientRect();
const position = wheelReportPosition(
rect === undefined ? undefined : event.clientX - rect.left,
rect === undefined ? undefined : event.clientY - rect.top,
{
cellWidth: core?._renderService?.dimensions?.css?.cell?.width,
cellHeight,
cols: term.cols,
rows: term.rows,
pixels: encoding === 'SGR_PIXELS',
},
);
sendInput(sgrWheelReport(button, position).repeat(count));
}
return false;
});
let sawFirstOutput = false;
const markFirstOutput = () => {
if (sawFirstOutput) return;
sawFirstOutput = true;
setHasOutput(true);
};
const attachSession = (livePtyId: string): void => {
ptyId = livePtyId;
ptyIdRef.current = livePtyId;
unregisterPasteProbe();
unregisterPasteProbe = registerBracketedPasteProbe(
livePtyId,
() => term.modes.bracketedPasteMode,
);
onPtyIdRef.current?.(livePtyId);
for (const notice of pendingShellNotices) {
if (notice.ptyId !== livePtyId) continue;
applyShellNotice(notice);
}
pendingShellNotices = [];
term.onData((data) => {
sendInput(data);
});
unsubData = bridge.terminal.onData((msg) => {
if (msg.ptyId !== ptyId) return;
markFirstOutput();
term.write(msg.data, () => bridge.terminal.drain(msg.ptyId, msg.data.length));
readinessScan?.(msg.data);
});
unsubExit = bridge.terminal.onExit((msg) => {
if (msg.ptyId !== ptyId) return;
sessionEnded = true;
terminalInputEnabledRef.current = false;
setExitInfo(
msg.neverStarted
? msg.hostExited === true
? { phase: 'start', reason: 'host-exited' }
: msg.launchFailure !== undefined
? { phase: 'start', reason: 'launch-unsupported' }
: { phase: 'start', detail: msg.error ?? '' }
: {
phase: 'exit',
exitCode: msg.exitCode,
signal: msg.signal,
error: msg.error,
...(msg.hostExited === true ? ({ hostExited: true } as const) : {}),
},
);
setStatus('exited');
if (!msg.neverStarted) onExitRef.current?.({ exitCode: msg.exitCode, signal: msg.signal });
});
ptyResizeThrottle = createResizeThrottle(() => {
if (ptyId) bridge.terminal.resize(ptyId, term.cols, term.rows);
}, PTY_RESIZE_THROTTLE_MS);
observer = new ResizeObserver((entries) => {
if (!shouldFitForResize(entries)) return;
const colsBefore = term.cols;
const rowsBefore = term.rows;
fit.fit();
if (term.cols !== colsBefore || term.rows !== rowsBefore) {
repaintSameFrame();
restoreScrollReach(term);
}
ptyResizeThrottle?.request();
});
observer.observe(container);
};
const startSession = async (livePtyId: string): Promise<void> => {
let failure: TerminalExitInfo;
try {
const attached = await bridge.terminal.start(livePtyId);
if (attached.ok) {
shellLive = true;
if (cancelled) return;
if (attached.shellFamily !== undefined) shellFamilyRef.current = attached.shellFamily;
if (attached.shellNoticeReason !== undefined) {
applyShellNotice({
ptyId: livePtyId,
notice: 'invalid-shell-override',
reason: attached.shellNoticeReason,
});
}
if (attached.replay !== '') {
markFirstOutput();
term.write(attached.replay);
}
return;
}
if (cancelled) return;
console.error('[terminal] shell start refused:', attached.reason, livePtyId);
switch (attached.reason) {
case 'not-consented':
sessionEnded = true;
terminalInputEnabledRef.current = false;
setStatus('not-consented');
return;
case 'not-started':
case 'unknown-session':
case 'host-unavailable':
failure = { phase: 'start', reason: attached.reason };
break;
default:
assertNeverPtyAdoptReason(attached.reason);
}
} catch (err) {
console.error('[terminal] initial start() failed:', err);
failure = { phase: 'start', detail: err instanceof Error ? err.message : String(err) };
}
if (cancelled || sessionEnded || shellLive) return;
sessionEnded = true;
terminalInputEnabledRef.current = false;
setExitInfo(failure);
setStatus('exited');
};
const resolveLaunchCommand = async (
intent: TerminalCliLaunchIntent,
): Promise<TerminalLaunchCommand | undefined> => {
const buildLaunch = (opts: Parameters<typeof buildPosixCliLaunch>[2]) =>
bridge.platform === 'win32'
? buildWindowsCliLaunch(intent.cli, intent.prompt, opts)
: buildPosixCliLaunch(intent.cli, intent.prompt, opts);
if (intent.cli === 'claude') {
try {
const fresh = await bridge.terminal.claudePreflight();
if (fresh.claude === 'present') {
if (!cancelled) setConnectionCli('claude');
return buildLaunch({
mcpPreApprove: fresh.mcpPreApprovable === true,
mcpServerName: fresh.mcpServerName,
...(bridge.cliCommandName ? { cliCommandName: bridge.cliCommandName } : {}),
autoApproveOkTools:
autoApproveOkToolsRef.current && fresh.okToolsAutoApprovable === true,
});
}
if (!cancelled) {
if (fresh.claude === 'not-found') {
setCliNotice({ cli: 'claude', kind: 'not-found' });
} else {
setCliNotice({ cli: 'claude', kind: 'unverified' });
}
}
} catch (err) {
console.warn('[terminal] claude launch preflight failed', err);
if (!cancelled) setCliNotice({ cli: 'claude', kind: 'unverified' });
}
return undefined;
}
try {
let res = await bridge.terminal.cliPreflight(intent.cli);
if (res.onPath === 'unknown') {
if (cancelled) return undefined;
res = await bridge.terminal.cliPreflight(intent.cli);
}
if (res.onPath === 'present') {
if (!cancelled) setConnectionCli(intent.cli);
return buildLaunch({
autoApproveOkTools:
intent.cli === 'codex' &&
res.okServerConfigured === true &&
autoApproveOkToolsRef.current,
mcpServerName: res.mcpServerName,
});
}
if (!cancelled) {
setCliNotice({
cli: intent.cli,
kind: res.onPath === 'not-found' ? 'not-found' : 'unverified',
});
}
} catch (err) {
console.warn('[terminal] cliPreflight failed', { cli: intent.cli, err });
if (!cancelled) setCliNotice({ cli: intent.cli, kind: 'unverified' });
}
return undefined;
};
let stagePasteTimer: ReturnType<typeof setTimeout> | undefined;
void (async () => {
if (adoptPtyId !== null) {
let adopted: Awaited<ReturnType<typeof bridge.terminal.adopt>>;
try {
adopted = await bridge.terminal.adopt(adoptPtyId);
} catch (err) {
console.error('[terminal] adopt() failed:', err);
adopted = { ok: false, reason: 'unknown-session' };
}
if (cancelled) return;
if (adopted.ok) {
shellFamilyRef.current = adopted.shellFamily ?? null;
if (adopted.shellNoticeReason !== undefined) {
applyShellNotice({
ptyId: adoptPtyId,
notice: 'invalid-shell-override',
reason: adopted.shellNoticeReason,
});
}
const replay = adopted.replay;
const hasReplay = replay !== '';
attachSession(adoptPtyId);
shellLive = true;
if (hasReplay) {
markFirstOutput();
term.write(replay, markInteractive);
} else {
markInteractive();
}
return;
}
}
let launchCommand: string | TerminalLaunchCommand | undefined;
let launchCli: TerminalCli | undefined;
if (launch !== null && adoptPtyId === null) {
if (launch.cli === null) {
launchCommand = launch.command;
} else {
launchCli = launch.cli;
launchCommand = await resolveLaunchCommand(launch);
if (cancelled) return;
}
} else if (commandId !== null && adoptPtyId === null) {
launchCommand =
bridge.platform === 'win32'
? windowsTerminalCommandFor(commandId)
: terminalCommandFor(commandId);
}
let result: Awaited<ReturnType<typeof bridge.terminal.create>>;
try {
result = await bridge.terminal.create({
cols: term.cols,
rows: term.rows,
launchCommand,
launchCli,
});
} catch (err) {
console.error('[terminal] create() failed:', err);
if (cancelled) return;
setExitInfo({
phase: 'start',
detail: err instanceof Error ? err.message : String(err),
});
setStatus('exited');
return;
}
if (cancelled) {
if (result.ok)
void bridge.terminal
.kill(result.ptyId)
.catch((err) => console.warn('[terminal] kill after cancelled mount failed:', err));
return;
}
if (!result.ok) {
switch (result.reason) {
case 'not-consented':
case 'no-project':
setStatus(result.reason);
break;
default:
assertNeverPtyCreateReason(result.reason);
}
return;
}
// STOP: attachSession installs onData/onExit before start() posts the spawn (terminal-manager.ts, same tick); once start() resolves, nothing below may await before the readinessScan assignment or the shell's first output outruns the scanner.
attachSession(result.ptyId);
await startSession(result.ptyId);
if (cancelled || sessionEnded) return;
markInteractive();
const staged = launch?.stagePaste;
const cliLaunch = launch !== null && launch.cli !== null ? launch : null;
const injectionBytes =
cliLaunch !== null && launchCommand !== undefined && cliLaunch.prompt != null
? buildStartupInjectionBytes(cliLaunch.cli, cliLaunch.prompt, bridge.platform)
: null;
if (injectionBytes != null && cliLaunch !== null) {
const cfg = startupInjectionFor(cliLaunch.cli, bridge.platform);
const settleMs = cfg?.settleMs ?? STAGE_PASTE_SETTLE_MS;
const marker = cfg?.readyMarker;
const bytes = injectionBytes;
const stagedBytes =
bridge.platform === 'win32' && cfg != null && bytes.endsWith(cfg.submit)
? bytes.slice(0, -cfg.submit.length)
: bytes;
let fired = false;
const inject = (): void => {
if (fired) return;
fired = true;
readinessScan = undefined;
if (stagePasteTimer !== undefined) clearTimeout(stagePasteTimer);
if (injectCapTimer !== undefined) clearTimeout(injectCapTimer);
if (cancelled || !terminalInputEnabledRef.current || launchCapabilityLimited) return;
const isWindowsStagedPaste = bridge.platform === 'win32';
const payload = isWindowsStagedPaste ? stagedBytes : bytes;
sendInput(payload);
term.focus();
if (isWindowsStagedPaste) setManualSubmitNotice(true);
};
injectCapTimer = setTimeout(inject, cfg?.capMs ?? settleMs);
if (marker != null) {
armReadinessScan(marker, () => {
if (fired || stagePasteTimer !== undefined) return;
stagePasteTimer = setTimeout(inject, settleMs);
});
} else {
stagePasteTimer = setTimeout(inject, settleMs);
}
} else if (launch != null && launch.prompt != null && staged != null) {
console.warn(
'[terminal] TerminalLaunchIntent carried both prompt and stagePaste; dropping stagePaste',
);
} else if (launchCommand !== undefined && staged != null && staged !== '') {
let stageFired = false;
const stage = (): void => {
if (stageFired) return;
stageFired = true;
readinessScan = undefined;
if (stagePasteTimer !== undefined) clearTimeout(stagePasteTimer);
if (injectCapTimer !== undefined) clearTimeout(injectCapTimer);
if (cancelled || !terminalInputEnabledRef.current || launchCapabilityLimited) return;
sendInput(buildTerminalInputBytes(staged, term.modes.bracketedPasteMode));
term.focus();
};
injectCapTimer = setTimeout(stage, STAGE_PASTE_CAP_MS);
armReadinessScan(BRACKETED_PASTE_ENABLE_MARKER, () => {
if (stageFired || stagePasteTimer !== undefined) return;
stagePasteTimer = setTimeout(stage, STAGE_PASTE_SETTLE_MS);
});
}
})().catch((err) => {
console.error('[terminal] mount sequence failed:', err);
if (cancelled || sessionEnded) return;
if (shellLive) {
markInteractive();
return;
}
sessionEnded = true;
terminalInputEnabledRef.current = false;
setExitInfo({ phase: 'start', detail: err instanceof Error ? err.message : String(err) });
setStatus('exited');
});
return () => {
cancelled = true;
terminalInputEnabledRef.current = false;
terminalInputRef.current = () => undefined;
window.removeEventListener('pagehide', markDocumentUnloading);
document.removeEventListener('visibilitychange', markDocumentVisible);
if (stagePasteTimer !== undefined) clearTimeout(stagePasteTimer);
if (injectCapTimer !== undefined) clearTimeout(injectCapTimer);
readinessScan = undefined;
unregisterPasteProbe();
ptyIdRef.current = null;
onPtyIdRef.current?.(null);
termRef.current = null;
observer?.disconnect();
canvasPixelObserver?.disconnect();
ptyResizeThrottle?.cancel();
unsubData?.();
unsubExit?.();
unsubNotice?.();
titleDisposable?.dispose();
linkProviderDisposable?.dispose();
term.dispose();
if (ptyId && !documentUnloading)
void bridge.terminal
.kill(ptyId)
.catch((err) => console.warn('[terminal] kill on unmount failed:', err));
};
}, [bridge, adoptPtyId, launch, commandId]);
useEffect(() => {
const term = termRef.current;
if (term === null) return;
term.options.theme = xtermTheme;
}, [xtermTheme]);
useEffect(() => {
const accessibility = bridge.accessibility;
if (accessibility == null || bridge.config.e2eSmoke === true) return;
return accessibility.onScreenReaderChanged((active) => {
const term = termRef.current;
if (term !== null) term.options.screenReaderMode = active;
});
}, [bridge]);
useEffect(() => {
const container = containerRef.current;
if (container === null) return;
function onDragOver(event: DragEvent) {
if (!isExternalFileDrag(event)) return;
event.preventDefault();
}
function onDrop(event: DragEvent) {
if (!isExternalFileDrag(event)) return;
event.preventDefault();
if (!terminalInputEnabledRef.current) return;
const droppedFiles = filesFromExternalDrop(event);
const paths = droppedFiles
.map((file) => bridge.getPathForFile(file))
.filter((path): path is string => path !== null && path !== '' && !/\p{Cc}/u.test(path));
let rejectedCount = droppedFiles.length - paths.length;
const escapedPaths = paths.flatMap((path) => {
if (bridge.platform !== 'win32') return [shellSingleQuote(path)];
const family = shellFamilyRef.current;
if (family === null) {
rejectedCount += 1;
return [];
}
const quoted = quoteWindowsShellPath(family, path);
if (quoted === null) {
rejectedCount += 1;
return [];
}
return [quoted];
});
if (rejectedCount > 0) setPathDropNotice(true);
if (escapedPaths.length === 0) return;
terminalInputRef.current(`${escapedPaths.join(' ')} `);
}
container.addEventListener('dragover', onDragOver, { capture: true });
container.addEventListener('drop', onDrop, { capture: true });
return () => {
container.removeEventListener('dragover', onDragOver, { capture: true });
container.removeEventListener('drop', onDrop, { capture: true });
};
}, [bridge]);
const isSettling = status === 'starting' || (status === 'running' && !hasOutput);
return (
<div className="flex h-full w-full flex-col">
{status === 'running' && connectionCli !== null ? (
<TerminalAgentConnectionBanner
key={connectionCli}
cli={connectionCli}
onRestart={onRestart}
/>
) : null}
{status === 'running' && cliNotice ? (
cliNotice.kind === 'not-found' ? (
<TerminalCliMissingBanner
cli={cliNotice.cli}
bridge={bridge}
onDismiss={() => setCliNotice(null)}
/>
) : (
<TerminalCliUnverifiedBanner cli={cliNotice.cli} onDismiss={() => setCliNotice(null)} />
)
) : null}
{status === 'running' ? (
pathDropNotice ? (
<TerminalNoticeBanner
testId="terminal-path-drop-notice-banner"
onDismiss={() => setPathDropNotice(false)}
>
{t`Some dropped files could not be inserted safely.`}
</TerminalNoticeBanner>
) : supportFileNotice ? (
<TerminalNoticeBanner
testId="terminal-support-file-notice-banner"
onDismiss={() => setSupportFileNotice(null)}
>
{supportFileNotice.reason === 'containment-refused'
? t`OpenKnowledge couldn't write launch settings under .ok/local/terminal because the folder is not safely contained in this project. Check that it is a real folder inside the project, not a link. Claude will ask you to approve OpenKnowledge.`
: t`OpenKnowledge couldn't write launch settings under .ok/local/terminal this time. Check that the folder is writable. Claude will ask you to approve OpenKnowledge.`}
</TerminalNoticeBanner>
) : shellNotice ? (
<TerminalNoticeBanner
testId="terminal-shell-notice-banner"
onDismiss={() => setShellNotice(null)}
>
{shellNotice.reason === 'config-unreadable'
? t`OpenKnowledge couldn't read terminal.shell in .ok/local/config.yml. Using an available Windows shell instead.`
: shellNotice.reason === 'invalid-value'
? t`terminal.shell in .ok/local/config.yml must be a string. Using an available Windows shell instead.`
: shellNotice.reason === 'not-absolute'
? t`terminal.shell in .ok/local/config.yml must be an absolute Windows path. Using an available Windows shell instead.`
: shellNotice.reason === 'unsupported-family'
? t`terminal.shell in .ok/local/config.yml supports PowerShell, cmd.exe, or Git Bash for OpenKnowledge-managed launches and dropped-file paths. This shell opens a plain terminal only; agent and command launches do not run in it.`
: t`The terminal.shell executable in .ok/local/config.yml was not found. Using an available Windows shell instead.`}
</TerminalNoticeBanner>
) : manualSubmitNotice ? (
<TerminalNoticeBanner
testId="terminal-manual-submit-notice-banner"
onDismiss={() => setManualSubmitNotice(false)}
>
{t`The prompt was pasted but not submitted automatically. Review it, then press Enter to send it.`}
</TerminalNoticeBanner>
) : null
) : null}
<div className="relative min-h-0 flex-1">
<div
ref={containerRef}
data-terminal-status={status}
aria-busy={isSettling}
className="h-full w-full px-1.5"
/>
{isSettling ? (
<TerminalStartingNotice className="pointer-events-none absolute inset-0 z-20" />
) : null}
</div>
{status === 'exited' && exitInfo ? (
<TerminalExitNotice info={exitInfo} onRestart={onRestart} />
) : null}
{status === 'no-project' || status === 'not-consented' ? (
<TerminalRefusalNotice reason={status} onClose={onClose} />
) : null}
</div>
);
}