@pentoshi/clai 3.11.7 → 3.11.9

package/dist/interactive-session/transport-pipe.js

@@ -0,0 +1,267 @@
+/**
+ * Managed-pipe transport. Used directly for `terminalMode: "pipe"` and as the
+ * single fallback for `"preferred"` when PTY capability is unavailable.
+ *
+ * This module never imports or probes PTY code, and it does not touch the spawn
+ * options used by `shell.ts` or `jobs.ts`.
+ */
+import { spawn } from "node:child_process";
+import { augmentedPathEnv } from "../os/command.js";
+import { processIdentityTracker } from "../os/process-identity.js";
+import { supportsProcessGroups, terminateProcessTree, } from "../os/process-tree.js";
+import { resolveShell } from "../tools/shell.js";
+import { LaunchFailure, pipeControlAction, } from "./transport.js";
+class PipeTransport {
+    child;
+    kind = "pipe";
+    pid;
+    processGroupId;
+    identity;
+    outputListeners = new Set();
+    exitListeners = new Set();
+    pendingOutput = [];
+    inputClosed = false;
+    exited = false;
+    outcome;
+    disposed = false;
+    outputStarted = false;
+    outputDrained = false;
+    resolveOutputDrain;
+    outputDrain = new Promise((resolve) => {
+        this.resolveOutputDrain = resolve;
+    });
+    constructor(child) {
+        this.child = child;
+        this.pid = child.pid ?? -1;
+        this.processGroupId = supportsProcessGroups() ? child.pid : undefined;
+        this.identity = processIdentityTracker.capture(child.pid, { refresh: true });
+        child.stdout?.on("data", (chunk) => this.emitOutput("stdout", chunk));
+        child.stderr?.on("data", (chunk) => this.emitOutput("stderr", chunk));
+        child.stdout?.pause();
+        child.stderr?.pause();
+        // A broken input pipe after the child exits is an expected race, not a crash.
+        child.stdin?.on("error", () => undefined);
+        child.on("exit", (code, signal) => {
+            this.exited = true;
+            const outcome = {
+                endedAt: Date.now(),
+                ...(code !== null ? { exitCode: code } : {}),
+                ...(signal ? { signal } : {}),
+            };
+            this.outcome = outcome;
+            for (const listener of [...this.exitListeners])
+                listener(outcome);
+        });
+        child.once("close", () => {
+            this.outputDrained = true;
+            this.resolveOutputDrain();
+        });
+    }
+    emitOutput(stream, chunk) {
+        const event = {
+            stream,
+            bytes: new Uint8Array(chunk),
+            observedAt: Date.now(),
+        };
+        if (!this.outputStarted) {
+            this.pendingOutput.push(event);
+            this.pauseOutput();
+            return;
+        }
+        for (const listener of [...this.outputListeners])
+            listener(event);
+    }
+    async write(bytes) {
+        const stdin = this.child.stdin;
+        if (!stdin || this.inputClosed || stdin.destroyed || this.exited) {
+            return { status: "not-delivered", deliveredBytes: 0 };
+        }
+        return await new Promise((resolve) => {
+            let settled = false;
+            const settle = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(result);
+            };
+            try {
+                stdin.write(Buffer.from(bytes), (error) => {
+                    // The callback fires after the bytes leave our buffer. A late error
+                    // cannot prove whether the child observed them, so it is `unknown`.
+                    if (error)
+                        settle({ status: "unknown", deliveredBytes: bytes.length, cause: error });
+                    else
+                        settle({ status: "delivered", deliveredBytes: bytes.length });
+                });
+            }
+            catch (error) {
+                settle({ status: "not-delivered", deliveredBytes: 0, cause: error });
+            }
+        });
+    }
+    async control(action) {
+        const mapped = pipeControlAction(action);
+        if (mapped.kind === "unsupported") {
+            return { status: "not-delivered", deliveredBytes: 0 };
+        }
+        if (mapped.kind === "bytes")
+            return await this.write(mapped.bytes);
+        if (mapped.kind === "close-input")
+            return await this.closeInput();
+        // Interrupt/suspend target the whole tree so a shell wrapper cannot swallow
+        // the signal while the real workload keeps running.
+        const outcome = terminateProcessTree(this.pid, {
+            signal: mapped.signal,
+            ...(this.processGroupId !== undefined ? { processGroupId: this.processGroupId } : {}),
+        });
+        return outcome === "failed"
+            ? { status: "unknown", deliveredBytes: 0 }
+            : { status: "delivered", deliveredBytes: 0 };
+    }
+    async closeInput() {
+        if (this.inputClosed)
+            return { status: "delivered", deliveredBytes: 0 };
+        this.inputClosed = true;
+        try {
+            this.child.stdin?.end();
+            return { status: "delivered", deliveredBytes: 0 };
+        }
+        catch (error) {
+            return { status: "unknown", deliveredBytes: 0, cause: error };
+        }
+    }
+    pauseOutput() {
+        this.child.stdout?.pause();
+        this.child.stderr?.pause();
+    }
+    resumeOutput() {
+        this.child.stdout?.resume();
+        this.child.stderr?.resume();
+    }
+    async requestTreeTermination(kind) {
+        return terminateProcessTree(this.pid, {
+            signal: kind === "graceful" ? "SIGTERM" : "SIGKILL",
+            ...(this.processGroupId !== undefined ? { processGroupId: this.processGroupId } : {}),
+        });
+    }
+    onOutput(listener) {
+        this.outputListeners.add(listener);
+        if (!this.outputStarted) {
+            this.outputStarted = true;
+            for (const event of this.pendingOutput.splice(0)) {
+                for (const outputListener of [...this.outputListeners]) {
+                    outputListener(event);
+                }
+            }
+            this.child.stdout?.resume();
+            this.child.stderr?.resume();
+        }
+        return () => {
+            this.outputListeners.delete(listener);
+        };
+    }
+    onExit(listener) {
+        this.exitListeners.add(listener);
+        if (this.outcome)
+            queueMicrotask(() => listener(this.outcome));
+        return () => {
+            this.exitListeners.delete(listener);
+        };
+    }
+    async waitForOutputDrain() {
+        if (this.outputDrained)
+            return;
+        await this.outputDrain;
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.outputListeners.clear();
+        this.exitListeners.clear();
+        this.pendingOutput.length = 0;
+        try {
+            this.child.stdin?.destroy();
+            this.child.stdout?.destroy();
+            this.child.stderr?.destroy();
+        }
+        catch {
+            // Streams may already be torn down by the exit path.
+        }
+        this.child.removeAllListeners();
+        processIdentityTracker.forget(this.child.pid);
+    }
+}
+/** Wait for the OS to confirm (or refuse) the spawn before reporting a launch. */
+function waitForSpawn(child) {
+    return new Promise((resolve) => {
+        const onSpawn = () => {
+            child.off("error", onError);
+            resolve(undefined);
+        };
+        const onError = (error) => {
+            child.off("spawn", onSpawn);
+            resolve(error);
+        };
+        child.once("spawn", onSpawn);
+        child.once("error", onError);
+    });
+}
+export async function startPipeTransport(request) {
+    const shell = resolveShell();
+    if (!shell) {
+        throw new LaunchFailure("SHELL_NOT_FOUND", "No usable command shell was found for an interactive session.", false, false);
+    }
+    const child = spawn(request.command, {
+        cwd: request.cwd,
+        shell,
+        detached: supportsProcessGroups(),
+        stdio: ["pipe", "pipe", "pipe"],
+        env: { ...(request.env ?? process.env), PATH: augmentedPathEnv() },
+        windowsHide: true,
+    });
+    let transport;
+    let identityNotified = false;
+    try {
+        if (child.pid) {
+            transport = new PipeTransport(child);
+            request.onLaunchIdentity?.({
+                pid: transport.pid,
+                processGroupId: transport.processGroupId,
+                identity: transport.identity,
+            });
+            identityNotified = true;
+        }
+        const error = await waitForSpawn(child);
+        if (error) {
+            throw new LaunchFailure(error.code ?? "UNKNOWN", `Interactive session launch failed before spawn: ${error.code ?? "UNKNOWN"}.`, Boolean(child.pid), error.code === "ENOENT" || error.code === "EAGAIN");
+        }
+        if (!child.pid) {
+            throw new LaunchFailure("NO_PID", "The interactive session process reported no process id after spawn.", true, false);
+        }
+        transport ??= new PipeTransport(child);
+        if (!identityNotified) {
+            request.onLaunchIdentity?.({
+                pid: transport.pid,
+                processGroupId: transport.processGroupId,
+                identity: transport.identity,
+            });
+        }
+        return { transport };
+    }
+    catch (error) {
+        try {
+            await transport?.requestTreeTermination("forceful");
+        }
+        catch { }
+        try {
+            child.kill("SIGKILL");
+        }
+        catch { }
+        await transport?.dispose().catch(() => undefined);
+        if (error instanceof LaunchFailure)
+            throw error;
+        throw new LaunchFailure("LAUNCH_IDENTITY_FAILED", "Interactive session launch identity could not be persisted.", Boolean(child.pid), false);
+    }
+}
+//# sourceMappingURL=transport-pipe.js.map

package/dist/interactive-session/transport-pipe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-pipe.js","sourceRoot":"","sources":["../../src/interactive-session/transport-pipe.ts"],"names":[],"mappings":"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"}

package/dist/interactive-session/transport.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Session transport contracts plus the single centralized table that maps text
+ * submission and named controls onto transport/platform byte sequences.
+ *
+ * A launch is confirmed only after the OS acknowledges spawn. Host stdin is
+ * never inherited: agent-controlled sessions must not be able to take the
+ * user's controlling terminal.
+ */
+import type { TreeSignalOutcome } from "../os/process-tree.js";
+import type { Unsubscribe } from "./runtime.js";
+import type { ControlInput, OutputStream, ProcessOutcome, SessionTransportKind, SubmitBehavior, TerminalDimensions } from "./types.js";
+export interface TransportOutput {
+    readonly stream: OutputStream;
+    readonly bytes: Uint8Array;
+    readonly observedAt: number;
+}
+export type DeliveryResult = {
+    readonly status: "delivered";
+    readonly deliveredBytes: number;
+} | {
+    readonly status: "not-delivered";
+    readonly deliveredBytes: 0;
+    readonly cause?: unknown;
+} | {
+    readonly status: "unknown";
+    readonly deliveredBytes: number;
+    readonly cause?: unknown;
+};
+export interface SessionTransport {
+    readonly kind: SessionTransportKind;
+    readonly pid: number;
+    readonly processGroupId?: number | undefined;
+    /** Hashed start-time evidence captured at launch confirmation. */
+    readonly identity: string | undefined;
+    write(bytes: Uint8Array): Promise<DeliveryResult>;
+    control(action: ControlInput): Promise<DeliveryResult>;
+    closeInput(): Promise<DeliveryResult>;
+    resize?(dimensions: TerminalDimensions): Promise<void>;
+    pauseOutput(): void;
+    resumeOutput(): void;
+    requestTreeTermination(kind: "graceful" | "forceful"): Promise<TreeSignalOutcome>;
+    onOutput(listener: (event: TransportOutput) => void): Unsubscribe;
+    onExit(listener: (outcome: ProcessOutcome) => void): Unsubscribe;
+    /** Settles after transport output sources can emit no additional bytes. */
+    waitForOutputDrain?(): Promise<void>;
+    dispose(): Promise<void>;
+}
+export interface LaunchIdentity {
+    readonly pid: number;
+    readonly processGroupId?: number | undefined;
+    readonly identity: string | undefined;
+}
+export interface LaunchRequest {
+    readonly command: string;
+    readonly cwd: string;
+    readonly env?: NodeJS.ProcessEnv | undefined;
+    readonly onLaunchIdentity?: ((identity: LaunchIdentity) => void) | undefined;
+}
+export interface LaunchResult {
+    readonly transport: SessionTransport;
+}
+export interface PtyCapability {
+    readonly available: boolean;
+    readonly platform: NodeJS.Platform;
+    /** Non-secret diagnostic for why PTY is unavailable on this target. */
+    readonly reason?: string | undefined;
+}
+export interface SessionTransportFactory {
+    capability(platform?: NodeJS.Platform): Promise<PtyCapability>;
+    startPipe(request: LaunchRequest): Promise<LaunchResult>;
+    startPty(request: LaunchRequest & {
+        dimensions: TerminalDimensions;
+    }): Promise<LaunchResult>;
+}
+/**
+ * A transient pre-spawn failure proves no process side effect occurred, so the
+ * manager may retry the launch exactly once.
+ */
+export declare class LaunchFailure extends Error {
+    readonly code: string;
+    readonly spawnConfirmed: boolean;
+    readonly transient: boolean;
+    constructor(code: string, message: string, spawnConfirmed: boolean, transient: boolean);
+}
+/** PTY line discipline expects CR; a pipe expects LF. */
+export declare function enterSequence(kind: SessionTransportKind): Uint8Array;
+export declare function encodeTextInput(text: string, submit: SubmitBehavior, kind: SessionTransportKind): Uint8Array;
+/**
+ * Byte payload for a named control on a PTY. `undefined` means the control has
+ * no byte form on that platform and must be reported as unsupported or handled
+ * out of band (signals on a pipe).
+ */
+export declare function ptyControlBytes(action: ControlInput, platform?: NodeJS.Platform): Uint8Array | undefined;
+/**
+ * Pipe controls: `interrupt`/`suspend` are process signals because there is no
+ * line discipline, `eof` half-closes stdin, and the rest are the same bytes a
+ * terminal would have delivered.
+ */
+export type PipeControlAction = {
+    readonly kind: "signal";
+    readonly signal: NodeJS.Signals;
+} | {
+    readonly kind: "bytes";
+    readonly bytes: Uint8Array;
+} | {
+    readonly kind: "close-input";
+} | {
+    readonly kind: "unsupported";
+};
+export declare function pipeControlAction(action: ControlInput, platform?: NodeJS.Platform): PipeControlAction;

package/dist/interactive-session/transport.js

@@ -0,0 +1,89 @@
+/**
+ * Session transport contracts plus the single centralized table that maps text
+ * submission and named controls onto transport/platform byte sequences.
+ *
+ * A launch is confirmed only after the OS acknowledges spawn. Host stdin is
+ * never inherited: agent-controlled sessions must not be able to take the
+ * user's controlling terminal.
+ */
+/**
+ * A transient pre-spawn failure proves no process side effect occurred, so the
+ * manager may retry the launch exactly once.
+ */
+export class LaunchFailure extends Error {
+    code;
+    spawnConfirmed;
+    transient;
+    constructor(code, message, spawnConfirmed, transient) {
+        super(message);
+        this.code = code;
+        this.spawnConfirmed = spawnConfirmed;
+        this.transient = transient;
+        this.name = "LaunchFailure";
+    }
+}
+// --- Text and control mappings ------------------------------------------
+/** PTY line discipline expects CR; a pipe expects LF. */
+export function enterSequence(kind) {
+    return Buffer.from(kind === "pty" ? "\r" : "\n", "utf8");
+}
+export function encodeTextInput(text, submit, kind) {
+    const body = Buffer.from(text, "utf8");
+    if (submit === "none")
+        return body;
+    return Buffer.concat([body, Buffer.from(enterSequence(kind))]);
+}
+const ARROWS = {
+    up: "\u001b[A",
+    down: "\u001b[B",
+    right: "\u001b[C",
+    left: "\u001b[D",
+};
+/**
+ * Byte payload for a named control on a PTY. `undefined` means the control has
+ * no byte form on that platform and must be reported as unsupported or handled
+ * out of band (signals on a pipe).
+ */
+export function ptyControlBytes(action, platform = process.platform) {
+    switch (action) {
+        case "interrupt":
+            return Buffer.from([0x03]);
+        case "eof":
+            // Windows consoles terminate input with Ctrl+Z followed by Enter.
+            return platform === "win32"
+                ? Buffer.from([0x1a, 0x0d])
+                : Buffer.from([0x04]);
+        case "suspend":
+            return platform === "win32" ? undefined : Buffer.from([0x1a]);
+        case "escape":
+            return Buffer.from([0x1b]);
+        case "tab":
+            return Buffer.from([0x09]);
+        case "backspace":
+            return Buffer.from([0x7f]);
+        case "up":
+        case "down":
+        case "left":
+        case "right":
+            return Buffer.from(ARROWS[action], "utf8");
+        default:
+            return undefined;
+    }
+}
+export function pipeControlAction(action, platform = process.platform) {
+    if (action === "interrupt") {
+        return platform === "win32"
+            ? { kind: "signal", signal: "SIGTERM" }
+            : { kind: "signal", signal: "SIGINT" };
+    }
+    if (action === "suspend") {
+        return platform === "win32"
+            ? { kind: "unsupported" }
+            : { kind: "signal", signal: "SIGTSTP" };
+    }
+    if (action === "eof")
+        return { kind: "close-input" };
+    const bytes = ptyControlBytes(action, platform);
+    return bytes ? { kind: "bytes", bytes } : { kind: "unsupported" };
+}
+//# sourceMappingURL=transport.js.map

package/dist/interactive-session/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/interactive-session/transport.ts"],"names":[],"mappings":"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"}