@vibesdotdev/terminal-client 0.0.0-stage → 1.0.0-rc.2

package/dist/terminal-runtime.js

@@ -0,0 +1,673 @@
+/**
+ * Terminal Unified Tool Implementation (consumer)
+ *
+ * `execute` / `spawn` call `runtime/execution` (pipes). `session` / `open` open
+ * a PTY via the per-runtime `TerminalSessionStore`. One store per runtime;
+ * PTY ownership is keyed on the caller's participant/connection. A spawned
+ * process is held per owner too: its `procId` is a handle `read`, `wait`,
+ * `list` and `close` accept, with its stdout/stderr kept in a backlog ring.
+ */
+import { BaseRuntimeClient } from '@vibesdotdev/kernel/client';
+import { CapabilityError, CaughtFailureSchema, composeChildEnv, isCapabilityError, settle, valueFreeFailure } from '@vibesdotdev/kernel';
+import { getLogger } from '@vibesdotdev/logging';
+import { resolveSequence } from '@vibesdotdev/terminal-client/ansi';
+import * as z from 'zod/v4';
+import { openLocalSession } from "./client.js";
+import { createTerminalSessionStore } from "./server/session-store.js";
+import { TerminalInputSchema } from "./tools/terminal.schemas.js";
+/** Max concurrent PTY sessions per owner before `open` is rejected. */
+const MAX_SESSIONS_PER_OWNER = 8;
+/** Consecutive `wait` calls that saw no new output allowed on one session before the tool pushes back. */
+const MAX_CONSECUTIVE_WAITS = 3;
+/** Output chunks a spawned process keeps for `read`/`wait`, as the PTY backlog ring does. */
+const MAX_SPAWN_BACKLOG = 256;
+/** How long a wait that saw the exit gives the pipes to deliver their last output. */
+const SPAWN_DRAIN_JOIN_MS = 1_000;
+const ContextIdentitySchema = z.string().trim().min(1).max(512);
+function createState(runtime) {
+    const produced = new Map();
+    const store = createTerminalSessionStore(runtime, async (opts) => {
+        const session = await openLocalSession(runtime, {
+            command: opts.command,
+            args: opts.args,
+            cwd: opts.cwd,
+            env: opts.env,
+            cols: opts.cols,
+            rows: opts.rows
+        });
+        produced.set(session.id, 0);
+        // Attached first — before the store's backlog listener — so `produced`
+        // is always >= the number of chunks retained in the backlog ring.
+        const unsubscribe = session.onOutput(() => {
+            produced.set(session.id, (produced.get(session.id) ?? 0) + 1);
+        });
+        return {
+            id: session.id,
+            environmentId: session.environmentId,
+            write: session.write.bind(session),
+            resize: session.resize.bind(session),
+            signal: session.signal.bind(session),
+            onOutput: session.onOutput.bind(session),
+            kill() { unsubscribe(); session.kill(); },
+            exited: () => session.exited().finally(() => { unsubscribe(); })
+        };
+    }, { maxSessions: MAX_SESSIONS_PER_OWNER });
+    return { closed: false, store, produced, waitStreak: new Map(), spawned: new Map() };
+}
+/**
+ * Keep a spawned process's stream in its backlog ring until the stream ends.
+ * Disposal joins owned work before the tool's own disposal kills the process,
+ * so the read stops when disposal begins instead of holding it for a live process.
+ */
+function drainInto(runtime, procId, entry, stream) {
+    if (stream === null)
+        return;
+    const reader = stream.getReader();
+    let reading = true;
+    entry.stopDrains.push(() => reading ? reader.cancel() : Promise.resolve());
+    const lifecycle = runtime.lifecycle;
+    const drained = settle(() => lifecycle.own(async () => {
+        const stop = () => void settle(() => reader.cancel());
+        lifecycle.signal.addEventListener('abort', stop, { once: true });
+        try {
+            for (;;) {
+                const next = await reader.read();
+                if (next.done)
+                    return;
+                entry.produced += 1;
+                entry.backlog.push(next.value);
+                if (entry.backlog.length > MAX_SPAWN_BACKLOG)
+                    entry.backlog.shift();
+            }
+        }
+        finally {
+            lifecycle.signal.removeEventListener('abort', stop);
+            reading = false;
+            reader.releaseLock();
+        }
+    })).then((read) => {
+        if (read.ok)
+            return;
+        getLogger('terminal.tool', runtime).warn('spawned process output stopped being read', {
+            procId,
+            failure: valueFreeFailure(read.cause)
+        });
+    });
+    entry.drains.push(drained);
+}
+/** Record a spawned process's exit on its entry when the handle reports it. */
+function observeExit(runtime, procId, entry) {
+    void settle(() => entry.handle.exited).then((exit) => {
+        entry.exited = true;
+        if (exit.ok) {
+            entry.exitCode = exit.value.code;
+            return;
+        }
+        getLogger('terminal.tool', runtime).warn('spawned process exit could not be observed', {
+            procId,
+            failure: valueFreeFailure(exit.cause)
+        });
+    });
+}
+/** Bound participant custody survives reconnects; unbound MCP custody is connection-local. */
+function ownerOf(ctx) {
+    const participant = ctx?.caller?.participantId?.trim();
+    if (participant)
+        return `participant:${participant}`;
+    const md = ctx?.metadata;
+    for (const key of ['mcp.transportSessionId', 'mcp.connectionKey']) {
+        const value = ContextIdentitySchema.safeParse(md?.[key]);
+        if (value.success)
+            return `${key}:${value.data}`;
+    }
+    if (md?.['mcp.transportMode'] !== undefined) {
+        throw new CapabilityError('Terminal caller identity is unavailable.', 'AUTH_REQUIRED', {
+            reason: 'terminal-caller-identity-missing',
+            retryable: false
+        });
+    }
+    const agent = ctx?.caller?.agentId?.trim();
+    if (agent)
+        return `agent:${agent}`;
+    // Direct surfaces may provide their contextual session or authenticated user.
+    for (const key of ['sessionId', 'codeSessionId', 'userId', 'agentId', 'roomId']) {
+        const value = ContextIdentitySchema.safeParse(md?.[key]);
+        if (value.success)
+            return `${key}:${value.data}`;
+    }
+    throw new CapabilityError('Terminal caller identity is unavailable.', 'AUTH_REQUIRED', {
+        reason: 'terminal-caller-identity-missing',
+        retryable: false
+    });
+}
+// ANSI escape-sequence matcher (CSI / OSC / SS2-3 / single escapes). Mirrors the
+// widely-used `ansi-regex` pattern; used to strip control sequences for `read`.
+// The three control chars (ESC/CSI/BEL) are built at runtime via String.fromCharCode
+// so the regex source carries no literal control character (satisfies no-control-regex
+// without a lint suppression).
+const ANSI_ESC = String.fromCharCode(0x1b);
+const ANSI_CSI = String.fromCharCode(0x9b);
+const ANSI_BEL = String.fromCharCode(0x07);
+const ANSI_REGEX = new RegExp(`[${ANSI_ESC}${ANSI_CSI}][[\\]()#;?]*(?:(?:(?:(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]+)*|[a-zA-Z\\d]+(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]*)*)?${ANSI_BEL})|(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PR-TZcf-nq-uy=><~]))`, 'g');
+/** Parse a key spec like "ctrl+c", "alt+x", "shift+Tab", or plain "Enter". */
+function parseChord(spec) {
+    const parts = spec
+        .split('+')
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+    const key = parts.length > 0 ? parts[parts.length - 1] : spec;
+    const chord = { key };
+    for (const modifier of parts.slice(0, -1)) {
+        const name = modifier.toLowerCase();
+        if (name === 'ctrl' || name === 'control')
+            chord.ctrl = true;
+        else if (name === 'alt' || name === 'option')
+            chord.alt = true;
+        else if (name === 'shift')
+            chord.shift = true;
+        else if (name === 'meta' || name === 'cmd' || name === 'super' || name === 'win')
+            chord.meta = true;
+    }
+    return chord;
+}
+function buildWriteBytes(input) {
+    const parts = [];
+    if (input.keys && input.keys.length > 0) {
+        for (const key of input.keys)
+            parts.push(resolveSequence(parseChord(key)));
+    }
+    if (input.text !== undefined)
+        parts.push(input.text);
+    const enter = input.enter ?? input.text !== undefined;
+    if (enter)
+        parts.push('\r');
+    return new TextEncoder().encode(parts.join(''));
+}
+function notFound() {
+    return new CapabilityError('The terminal session was not found.', 'NOT_FOUND', {
+        reason: 'terminal-session-not-found',
+        retryable: false
+    });
+}
+function collectBacklog(stored, total, since, stripAnsi) {
+    const dropped = total - stored.backlog.length;
+    let chunks = [];
+    if (since < total) {
+        const startIndex = Math.max(since, dropped) - dropped;
+        chunks = stored.backlog.slice(startIndex);
+    }
+    const decoder = new TextDecoder();
+    let output = chunks.map((chunk) => decoder.decode(chunk, { stream: true })).join('');
+    output += decoder.decode();
+    if (stripAnsi)
+        output = output.replace(ANSI_REGEX, '');
+    return { output, cursor: total };
+}
+async function resolveExecution(runtime) {
+    return runtime.query('runtime/execution').resolve();
+}
+function scopedCwd(input, ctx) {
+    if (input.cwd !== undefined)
+        return input.cwd;
+    const md = ctx?.metadata ?? {};
+    for (const key of ['workspaceRoot', 'workspacePath']) {
+        const value = ContextIdentitySchema.safeParse(md[key]);
+        if (value.success)
+            return value.data;
+    }
+    return undefined;
+}
+async function dispatch(input, state, runtime, ctx) {
+    if (input.action === 'capabilities' || input.action === 'execute' || input.action === 'spawn') {
+        const exec = await resolveExecution(runtime);
+        const caps = exec.getCapabilities();
+        if (input.action === 'capabilities') {
+            return {
+                action: 'capabilities',
+                executionId: exec.id,
+                environmentId: exec.environmentId,
+                pty: caps.pty,
+                shell: caps.shell,
+                capabilities: caps
+            };
+        }
+        if (!caps.shell) {
+            throw new CapabilityError('The selected execution provider has no shell.', 'UNAVAILABLE', {
+                reason: 'terminal-shell-unavailable',
+                retryable: false
+            });
+        }
+        const cwd = scopedCwd(input, ctx);
+        const command = input.command[0];
+        const args = input.command.slice(1);
+        // Exactly the composed environment (rc02-rc03 C15): the host's base set
+        // plus the variables the call declares.
+        const env = composeChildEnv(runtime, {
+            env: {
+                GIT_CONFIG_COUNT: '1',
+                GIT_CONFIG_KEY_0: 'commit.gpgsign',
+                GIT_CONFIG_VALUE_0: 'false',
+                ...input.env
+            }
+        });
+        if (input.action === 'execute') {
+            const result = await exec.execute({
+                command,
+                args,
+                cwd,
+                env,
+                envMode: 'replace',
+                timeout: input.timeoutMs
+            });
+            return {
+                action: 'execute',
+                command: input.command,
+                cwd,
+                executionId: exec.id,
+                environmentId: exec.environmentId,
+                exitCode: result.exitCode,
+                stdout: result.stdout,
+                stderr: result.stderr,
+                durationMs: result.durationMs,
+                timedOut: result.timedOut,
+                pty: caps.pty,
+                shell: caps.shell
+            };
+        }
+        // The handle is held for its owner, so `read`/`wait`/`close` can reach it.
+        const owner = ownerOf(ctx);
+        const handle = await exec.spawn({
+            command,
+            args,
+            cwd,
+            env,
+            envMode: 'replace',
+            stdout: 'pipe',
+            stderr: 'pipe',
+            // `close` (or disposal) must end what the process started, not only the wrapper.
+            killTree: true
+        });
+        if (state.closed) {
+            await handle.kill();
+            throw new CapabilityError('The terminal runtime is disposed.', 'UNAVAILABLE', { reason: 'terminal-runtime-disposed' });
+        }
+        const procId = String(handle.pid);
+        const entry = {
+            owner,
+            command: input.command.join(' '),
+            startedAt: runtime.lifecycle.now(),
+            handle,
+            backlog: [],
+            produced: 0,
+            exitCode: null,
+            exited: false,
+            drains: [],
+            stopDrains: []
+        };
+        state.spawned.set(procId, entry);
+        drainInto(runtime, procId, entry, handle.stdout);
+        drainInto(runtime, procId, entry, handle.stderr);
+        observeExit(runtime, procId, entry);
+        const present = input.present === true && !caps.pty
+            ? { kind: 'log', procId }
+            : undefined;
+        const output = {
+            action: 'spawn',
+            command: input.command,
+            cwd,
+            executionId: exec.id,
+            environmentId: exec.environmentId,
+            procId,
+            running: true,
+            pty: caps.pty,
+            shell: caps.shell
+        };
+        if (present !== undefined)
+            output.present = present;
+        return output;
+    }
+    const owner = ownerOf(ctx);
+    const { store, produced, waitStreak } = state;
+    // Any action other than `wait` is real progress on that session.
+    if (input.action !== 'wait' && 'sessionId' in input && store.getOwnedSession(input.sessionId, owner)) {
+        waitStreak.delete(input.sessionId);
+    }
+    // A `procId` from `spawn` is a handle these actions accept like a session id.
+    const spawned = 'sessionId' in input ? ownedSpawn(state, input.sessionId, owner) : undefined;
+    if (spawned !== undefined && 'sessionId' in input) {
+        return dispatchSpawned(input, input.sessionId, spawned, state, runtime);
+    }
+    switch (input.action) {
+        case 'open':
+        case 'session': {
+            const command = Array.isArray(input.command)
+                ? (input.command[0] ?? (runtime.getEnv('SHELL') || '/bin/sh'))
+                : (input.command ?? (runtime.getEnv('SHELL') || '/bin/sh'));
+            const args = Array.isArray(input.command)
+                ? [...input.command.slice(1), ...(input.args ?? [])]
+                : input.args;
+            const cwd = scopedCwd(input, ctx);
+            const { id } = await store.openSession(owner, {
+                command,
+                args,
+                cwd,
+                env: input.env,
+                cols: input.cols,
+                rows: input.rows
+            });
+            const exec = await resolveExecution(runtime);
+            const caps = exec.getCapabilities();
+            const shouldPresent = input.present !== false;
+            const output = {
+                action: input.action,
+                sessionId: id,
+                cwd,
+                executionId: exec.id,
+                environmentId: exec.environmentId,
+                pty: caps.pty,
+                shell: caps.shell,
+                capabilities: caps
+            };
+            if (shouldPresent)
+                output.present = { kind: 'terminal', sessionId: id };
+            return output;
+        }
+        case 'list': {
+            // Cheap GC: drop cursor entries for sessions the store no longer tracks
+            // (killed, natural exit, or idle-reaped) so `produced` cannot leak.
+            for (const id of produced.keys()) {
+                if (!store.hasSession(id))
+                    produced.delete(id);
+            }
+            const sessions = store.listSessions(owner).map((meta) => ({
+                id: meta.id,
+                command: meta.command,
+                createdAt: meta.startedAt,
+                status: meta.exited ? 'exited' : 'running'
+            }));
+            for (const [procId, entry] of state.spawned) {
+                if (entry.owner !== owner)
+                    continue;
+                sessions.push({
+                    id: procId,
+                    command: entry.command,
+                    createdAt: entry.startedAt,
+                    status: entry.exited ? 'exited' : 'running'
+                });
+            }
+            return { action: 'list', sessions };
+        }
+        case 'read': {
+            const stored = store.getOwnedSession(input.sessionId, owner);
+            if (!stored)
+                throw notFound();
+            // Same cheap sweep as `list` — prune cursors for vanished sessions.
+            for (const id of produced.keys()) {
+                if (!store.hasSession(id))
+                    produced.delete(id);
+            }
+            const total = produced.get(input.sessionId) ?? stored.backlog.length;
+            const { output } = collectBacklog(stored, total, input.since ?? 0, input.stripAnsi ?? true);
+            // A read is real activity: refresh the idle clock so an actively polled
+            // but SSE-unattached session is not reaped as idle.
+            store.touchSession(input.sessionId, owner);
+            return { action: 'read', sessionId: input.sessionId, output, cursor: total };
+        }
+        case 'write': {
+            const stored = store.getOwnedSession(input.sessionId, owner);
+            if (!stored)
+                throw notFound();
+            const bytes = buildWriteBytes(input);
+            const ok = store.writeToSession(input.sessionId, owner, bytes);
+            if (ok)
+                store.touchSession(input.sessionId, owner);
+            return {
+                action: 'write',
+                sessionId: input.sessionId,
+                bytesWritten: ok ? bytes.length : 0
+            };
+        }
+        case 'resize': {
+            const ok = store.resizeSession(input.sessionId, owner, input.cols, input.rows);
+            if (!ok)
+                throw notFound();
+            store.touchSession(input.sessionId, owner);
+            return { action: 'resize', sessionId: input.sessionId, resized: true };
+        }
+        case 'wait': {
+            const stored = store.getOwnedSession(input.sessionId, owner);
+            if (!stored)
+                throw notFound();
+            const streak = (waitStreak.get(input.sessionId) ?? 0) + 1;
+            if (streak > MAX_CONSECUTIVE_WAITS) {
+                waitStreak.delete(input.sessionId);
+                throw new CapabilityError('The terminal wait limit has been reached.', 'RATE_LIMITED', {
+                    reason: 'terminal-wait-limit-reached',
+                    retryable: false
+                });
+            }
+            waitStreak.set(input.sessionId, streak);
+            store.touchSession(input.sessionId, owner);
+            const producedBefore = produced.get(input.sessionId) ?? stored.backlog.length;
+            const waitOutcome = await runtime.lifecycle
+                .wait(async () => stored.session.exited(), {
+                timeoutMs: input.timeoutMs ?? 30000,
+                reason: 'terminal wait'
+            })
+                .then((exited) => ({ kind: 'exit', exited }), (cause) => ({
+                kind: 'failure',
+                failure: CaughtFailureSchema.parse(cause)
+            }));
+            let result;
+            if (waitOutcome.kind === 'failure') {
+                if (!isWaitTimeout(waitOutcome.failure))
+                    throw waitOutcome.failure;
+                result = { exitCode: null, timedOut: true };
+            }
+            else {
+                result = { exitCode: waitOutcome.exited.exitCode, timedOut: false };
+                waitStreak.delete(input.sessionId);
+            }
+            const total = produced.get(input.sessionId) ?? stored.backlog.length;
+            // A wait that saw new output is progress, not a stalled poll.
+            if (total > producedBefore)
+                waitStreak.delete(input.sessionId);
+            const { output, cursor } = collectBacklog(stored, total, input.since ?? 0, input.stripAnsi ?? true);
+            return {
+                action: 'wait',
+                sessionId: input.sessionId,
+                ...result,
+                output,
+                cursor
+            };
+        }
+        case 'close': {
+            const ok = store.killSession(input.sessionId, owner);
+            if (!ok)
+                throw notFound();
+            // Only drop the cursor once ownership is confirmed — a non-owner must
+            // never mutate the owner's read state.
+            produced.delete(input.sessionId);
+            waitStreak.delete(input.sessionId);
+            return { action: 'close', sessionId: input.sessionId, closed: true };
+        }
+    }
+}
+/** The caller's spawned process under `procId`; another owner's process is not found. */
+function ownedSpawn(state, procId, owner) {
+    const entry = state.spawned.get(procId);
+    return entry?.owner === owner ? entry : undefined;
+}
+function spawnedOutput(entry, since, stripAnsi) {
+    return collectBacklog(entry, entry.produced, since ?? 0, stripAnsi ?? true);
+}
+/** `read` / `wait` / `close` on a spawned process; it has no PTY to `write` to or `resize`. */
+async function dispatchSpawned(input, procId, entry, state, runtime) {
+    const { waitStreak } = state;
+    if (input.action !== 'wait')
+        waitStreak.delete(procId);
+    switch (input.action) {
+        case 'read': {
+            const { output, cursor } = spawnedOutput(entry, input.since, input.stripAnsi);
+            return { action: 'read', sessionId: procId, output, cursor };
+        }
+        case 'wait': {
+            const streak = (waitStreak.get(procId) ?? 0) + 1;
+            if (streak > MAX_CONSECUTIVE_WAITS) {
+                waitStreak.delete(procId);
+                throw new CapabilityError('The terminal wait limit has been reached.', 'RATE_LIMITED', {
+                    reason: 'terminal-wait-limit-reached',
+                    retryable: false
+                });
+            }
+            waitStreak.set(procId, streak);
+            const producedBefore = entry.produced;
+            const waitOutcome = await runtime.lifecycle
+                .wait(async () => entry.handle.exited, {
+                timeoutMs: input.timeoutMs ?? 30000,
+                reason: 'terminal wait'
+            })
+                .then((exited) => ({ kind: 'exit', exited }), (cause) => ({ kind: 'failure', failure: CaughtFailureSchema.parse(cause) }));
+            let result;
+            if (waitOutcome.kind === 'failure') {
+                if (!isWaitTimeout(waitOutcome.failure))
+                    throw waitOutcome.failure;
+                result = { exitCode: null, timedOut: true };
+            }
+            else {
+                result = { exitCode: waitOutcome.exited.code, timedOut: false };
+                waitStreak.delete(procId);
+                // An ended process's last output is still in its pipes: answer once both are read. A
+                // descendant can hold a pipe open past the exit, so the join is bounded.
+                const joined = await settle(() => runtime.lifecycle.wait(async () => {
+                    await Promise.all(entry.drains);
+                }, { timeoutMs: SPAWN_DRAIN_JOIN_MS, reason: 'terminal spawned output' }));
+                if (!joined.ok && !isWaitTimeout(joined.cause))
+                    throw joined.cause;
+            }
+            // A wait that saw new output is progress, not a stalled poll.
+            if (entry.produced > producedBefore)
+                waitStreak.delete(procId);
+            const { output, cursor } = spawnedOutput(entry, input.since, input.stripAnsi);
+            return { action: 'wait', sessionId: procId, ...result, output, cursor };
+        }
+        case 'close': {
+            if (!entry.exited)
+                await entry.handle.kill();
+            await Promise.all(entry.stopDrains.map(stop => stop()));
+            state.spawned.delete(procId);
+            return { action: 'close', sessionId: procId, closed: true };
+        }
+        case 'write':
+        case 'resize':
+            throw new CapabilityError(`A spawned process has no terminal to ${input.action}.`, 'INVALID_INPUT', {
+                reason: 'terminal-spawned-process-not-interactive',
+                retryable: false,
+                details: { procId, action: input.action }
+            });
+    }
+}
+/** The kernel owns one terminal client and its lazy tool state per runtime. */
+export class TerminalClient extends BaseRuntimeClient {
+    state = null;
+    sequence = 0;
+    remoteAbortCleanup;
+    stopRemoteSessions = () => {
+        // Start session cleanup on abort; RPC closes its connection and drains
+        // explicitly owned remote references. The finalizer joins every outcome.
+        this.remoteAbortCleanup = Promise.allSettled([...this.remoteSessions].map(async (close) => { await close(); }));
+    };
+    prepareRemoteSession() {
+        this.runtime.lifecycle.signal.addEventListener('abort', this.stopRemoteSessions, { once: true });
+    }
+    remoteSessions = new Set();
+    nextRemoteSessionId(hostId) {
+        return `remote:${hostId}:${++this.sequence}`;
+    }
+    ownRemoteSession(close) {
+        this.remoteSessions.add(close);
+        return () => this.remoteSessions.delete(close);
+    }
+    /** Open the HTTP transport on this runtime; hosts select the semantic client once. */
+    async openHttpSession(options) {
+        if (this.runtime.lifecycle.signal.aborted) {
+            throw new CapabilityError('The terminal runtime is disposed.', 'UNAVAILABLE', { reason: 'terminal-runtime-disposed' });
+        }
+        this.prepareRemoteSession();
+        const opening = import("./client/http-session.js").then(({ openHttpSession }) => openHttpSession(this.runtime, options));
+        let closing = false;
+        let cleanup;
+        const close = () => {
+            closing = true;
+            cleanup ??= (async () => {
+                const outcome = await settle(() => opening);
+                // The opening caller owns its refusal; cleanup owns only acquired sessions.
+                if (outcome.ok) {
+                    outcome.value.session.kill();
+                    await outcome.value.session.exited();
+                }
+            })();
+            return cleanup;
+        };
+        const release = this.ownRemoteSession(close);
+        try {
+            const opened = await opening;
+            if (closing || this.runtime.lifecycle.signal.aborted) {
+                await close();
+                throw new CapabilityError('The terminal runtime is disposed.', 'UNAVAILABLE', { reason: 'terminal-runtime-disposed' });
+            }
+            void opened.session.exited().then(release, release);
+            return opened;
+        }
+        catch (cause) {
+            release();
+            if (this.runtime.lifecycle.signal.aborted) {
+                throw new CapabilityError('The terminal runtime is disposed.', 'UNAVAILABLE', { reason: 'terminal-runtime-disposed' });
+            }
+            throw cause;
+        }
+    }
+    execute(input, ctx) {
+        if (this.runtime.lifecycle.signal.aborted) {
+            throw new CapabilityError('The terminal runtime is disposed.', 'UNAVAILABLE', { reason: 'terminal-runtime-disposed' });
+        }
+        this.state ??= createState(this.runtime);
+        return dispatch(TerminalInputSchema.parse(input), this.state, this.runtime, ctx);
+    }
+    async onDispose() {
+        this.runtime.lifecycle.signal.removeEventListener('abort', this.stopRemoteSessions);
+        const abortCleanup = this.remoteAbortCleanup;
+        this.remoteAbortCleanup = undefined;
+        const state = this.state;
+        this.state = null;
+        if (state)
+            state.closed = true;
+        const cleanups = abortCleanup ? [] : [...this.remoteSessions];
+        for (const entry of state?.spawned.values() ?? []) {
+            if (!entry.exited)
+                cleanups.push(() => entry.handle.kill());
+            cleanups.push(...entry.stopDrains);
+            cleanups.push(async () => { await Promise.all(entry.drains); });
+        }
+        if (state)
+            cleanups.push(() => state.store.dispose());
+        const outcomes = await Promise.allSettled(cleanups.map(close => Promise.resolve().then(close)));
+        state?.produced.clear();
+        state?.waitStreak.clear();
+        state?.spawned.clear();
+        this.remoteSessions.clear();
+        this.sequence = 0;
+        const abortOutcomes = await abortCleanup ?? [];
+        const failures = [...abortOutcomes, ...outcomes].filter(result => result.status === 'rejected').map(result => result.reason);
+        if (failures.length === 1)
+            throw failures[0];
+        if (failures.length > 1)
+            throw new AggregateError(failures, 'Terminal client cleanup failed.');
+    }
+}
+export default TerminalClient;
+/** `lifecycle.wait` rejects a lapsed deadline as `CapabilityError` code `TIMEOUT`, reason `wait-timeout`. */
+function isWaitTimeout(error) {
+    return isCapabilityError(error) && error.code === 'TIMEOUT' && error.reason === 'wait-timeout';
+}
+//# sourceMappingURL=terminal-runtime.js.map