agencyx-cli 0.0.0-stage → 0.1.0-dev.4

package/dist/runtime/ipc.js

@@ -0,0 +1,316 @@
+import net from "node:net";
+import { chmod, readFile } from "node:fs/promises";
+import { timingSafeEqual } from "node:crypto";
+import { EventEmitter } from "node:events";
+import { AgencyxError, fail } from "../diagnostics.js";
+import { isRecord } from "../validation.js";
+const MAX_FRAME_BYTES = 2 * 1024 * 1024;
+export class JsonLinePeer extends EventEmitter {
+    stream;
+    buffer = "";
+    closed = false;
+    constructor(stream) {
+        super();
+        this.stream = stream;
+        stream.setEncoding("utf8");
+        stream.on("data", (chunk) => this.receive(chunk));
+        stream.on("error", () => this.emit("fault"));
+        stream.on("close", () => {
+            this.closed = true;
+            this.emit("closed");
+        });
+    }
+    receive(chunk) {
+        this.buffer += chunk;
+        if (Buffer.byteLength(this.buffer) > MAX_FRAME_BYTES) {
+            this.stream.destroy();
+            this.emit("fault");
+            return;
+        }
+        let newline;
+        while ((newline = this.buffer.indexOf("\n")) >= 0) {
+            const line = this.buffer.slice(0, newline);
+            this.buffer = this.buffer.slice(newline + 1);
+            if (!line.trim())
+                continue;
+            let value;
+            try {
+                value = JSON.parse(line);
+            }
+            catch {
+                this.stream.destroy();
+                this.emit("fault");
+                return;
+            }
+            this.emit("message", value);
+        }
+    }
+    send(value) {
+        if (this.closed || this.stream.destroyed)
+            fail("HANDOFF_DISCONNECTED", "handoff", "The session control channel closed.", {}, 6);
+        this.stream.write(`${JSON.stringify(value)}\n`);
+    }
+    waitFor(type, timeoutMs = 5_000) {
+        return new Promise((resolve, reject) => {
+            const cleanup = () => {
+                clearTimeout(timer);
+                this.off("message", onMessage);
+                this.off("fault", onFailure);
+                this.off("closed", onFailure);
+            };
+            const onMessage = (message) => {
+                if (isRecord(message) && message.type === type) {
+                    cleanup();
+                    resolve(message);
+                }
+            };
+            const onFailure = () => {
+                cleanup();
+                reject(new AgencyxError({
+                    code: "HANDOFF_DISCONNECTED",
+                    stage: "handoff",
+                    reason: "The session control channel closed before acknowledging the operation.",
+                }, 6));
+            };
+            const timer = setTimeout(onFailure, timeoutMs);
+            this.on("message", onMessage);
+            this.on("fault", onFailure);
+            this.on("closed", onFailure);
+            if (this.closed || this.stream.destroyed)
+                onFailure();
+        });
+    }
+    close() {
+        this.stream.end();
+    }
+}
+function equalToken(candidate, expected) {
+    if (typeof candidate !== "string")
+        return false;
+    const left = Buffer.from(candidate);
+    const right = Buffer.from(expected);
+    return left.length === right.length && timingSafeEqual(left, right);
+}
+function validExit(value) {
+    return (isRecord(value) &&
+        ((Number.isInteger(value.code) &&
+            Number(value.code) >= 0 &&
+            Number(value.code) <= 0xffffffff &&
+            value.signal === null) ||
+            (value.code === null &&
+                typeof value.signal === "string" &&
+                /^SIG[A-Z0-9]+$/.test(value.signal))));
+}
+export class SessionServer extends EventEmitter {
+    session;
+    context;
+    server;
+    peers = new Set();
+    execution;
+    executionConnected = false;
+    engineStarted = false;
+    result;
+    failure;
+    failureExitCode;
+    plan;
+    constructor(session, context) {
+        super();
+        this.session = session;
+        this.context = context;
+        this.server = net.createServer((socket) => this.accept(socket));
+    }
+    static async listen(session, context) {
+        const channel = new SessionServer(session, context);
+        await new Promise((resolve, reject) => {
+            channel.server.once("error", reject);
+            channel.server.listen(session.endpoint, () => {
+                channel.server.off("error", reject);
+                resolve();
+            });
+        });
+        channel.server.on("error", () => channel.emit("fault"));
+        if (process.platform !== "win32")
+            await chmod(session.endpoint, 0o600);
+        return channel;
+    }
+    accept(socket) {
+        const peer = new JsonLinePeer(socket);
+        this.peers.add(peer);
+        let authenticated = false;
+        let role;
+        const deadline = setTimeout(() => socket.destroy(), 3_000);
+        deadline.unref();
+        peer.on("message", (message) => {
+            if (!isRecord(message)) {
+                socket.destroy();
+                return;
+            }
+            if (!authenticated) {
+                if (message.type !== "hello" ||
+                    message.protocol !== 1 ||
+                    message.sessionId !== this.session.id ||
+                    !equalToken(message.token, this.session.token) ||
+                    (message.role !== "probe" && message.role !== "execution") ||
+                    (message.role === "execution" && this.executionConnected)) {
+                    socket.destroy();
+                    return;
+                }
+                authenticated = true;
+                role = message.role;
+                clearTimeout(deadline);
+                if (role === "execution") {
+                    this.execution = peer;
+                    this.executionConnected = true;
+                }
+                peer.send({ type: "context", context: this.context });
+                return;
+            }
+            if (role !== "execution")
+                return;
+            if (message.type === "engine-started") {
+                this.engineStarted = true;
+                return;
+            }
+            if (message.type === "plan") {
+                this.plan = message.plan;
+                peer.send({ type: "ack" });
+                return;
+            }
+            if (message.type === "exit" &&
+                validExit(message.exit) &&
+                (this.engineStarted ||
+                    (this.context.options.dryRun && message.stage === "dry-run")) &&
+                !this.result &&
+                !this.failure) {
+                this.result = message.exit;
+                peer.send({ type: "ack" });
+            }
+            else if (message.type === "failure" &&
+                isRecord(message.diagnostic) &&
+                typeof message.diagnostic.code === "string" &&
+                !this.result &&
+                !this.failure) {
+                this.failure = message.diagnostic;
+                this.failureExitCode =
+                    Number.isInteger(message.exitCode) &&
+                        Number(message.exitCode) > 0 &&
+                        Number(message.exitCode) <= 255
+                        ? Number(message.exitCode)
+                        : 4;
+                peer.send({ type: "ack" });
+            }
+            else {
+                socket.destroy();
+            }
+        });
+        peer.on("fault", () => socket.destroy());
+        peer.on("closed", () => {
+            clearTimeout(deadline);
+            this.peers.delete(peer);
+            if (peer === this.execution && !this.result && !this.failure) {
+                this.failure = {
+                    code: "HANDOFF_DISCONNECTED",
+                    stage: "handoff",
+                    reason: "The execution bridge exited without reporting a result.",
+                };
+                this.emit("execution-lost");
+            }
+        });
+    }
+    abort(signal) {
+        if (this.execution && !this.result && !this.failure) {
+            try {
+                this.execution.send({ type: "abort", signal });
+            }
+            catch {
+                /* The bridge already exited. */
+            }
+        }
+    }
+    async close() {
+        for (const peer of this.peers)
+            peer.stream.destroy();
+        await new Promise((resolve) => this.server.close(() => resolve()));
+    }
+}
+export async function connectBridge(env, role) {
+    let endpoint = env.AGENCYX_SESSION_CHANNEL;
+    let token = env.AGENCYX_SESSION_TOKEN;
+    let id = env.AGENCYX_SESSION_ID;
+    if (env.AGENCYX_SESSION_FILE) {
+        try {
+            const session = JSON.parse(await readFile(env.AGENCYX_SESSION_FILE, "utf8"));
+            if (!isRecord(session) ||
+                session.protocol !== 1 ||
+                typeof session.endpoint !== "string" ||
+                typeof session.token !== "string" ||
+                typeof session.id !== "string")
+                throw new Error("Invalid bootstrap data.");
+            endpoint = session.endpoint;
+            token = session.token;
+            id = session.id;
+        }
+        catch {
+            fail("HANDOFF_CONTEXT_INVALID", "handoff", "The private launcher session file cannot be read.", {}, 6);
+        }
+    }
+    if (!endpoint || !token || !id)
+        fail("HANDOFF_CONTEXT_REQUIRED", "handoff", "The private bridge can only be launched by an active agencyx session.", {}, 6);
+    const socket = net.createConnection(endpoint);
+    const peer = new JsonLinePeer(socket);
+    const contextResponse = peer.waitFor("context");
+    socket.once("connect", () => peer.send({ type: "hello", protocol: 1, sessionId: id, token, role }));
+    let response;
+    try {
+        response = await contextResponse;
+    }
+    catch (error) {
+        socket.destroy();
+        throw error;
+    }
+    const context = response.context;
+    if (!isRecord(context) ||
+        context.sessionId !== id ||
+        !isRecord(context.options) ||
+        typeof context.codexPath !== "string" ||
+        typeof context.cwd !== "string" ||
+        typeof context.sessionRoot !== "string") {
+        socket.destroy();
+        fail("HANDOFF_CONTEXT_INVALID", "handoff", "The wrapper returned an invalid session context.", {}, 6);
+    }
+    const abort = new AbortController();
+    const typedContext = context;
+    let finished = false;
+    peer.on("message", (message) => {
+        if (isRecord(message) && message.type === "abort")
+            abort.abort(message.signal === "SIGINT" ? "SIGINT" : "SIGTERM");
+    });
+    peer.on("closed", () => {
+        if (!finished)
+            abort.abort("SIGTERM");
+    });
+    const finish = async (value, final = true) => {
+        const acknowledgement = peer.waitFor("ack");
+        peer.send(value);
+        await acknowledgement;
+        if (final)
+            finished = true;
+    };
+    return {
+        context: typedContext,
+        signal: abort.signal,
+        engineStarted: () => peer.send({ type: "engine-started" }),
+        reportExit: (result) => finish({
+            type: "exit",
+            stage: typedContext.options.dryRun ? "dry-run" : "execution",
+            exit: result,
+        }),
+        reportFailure: (diagnostic, exitCode = 4) => finish({ type: "failure", diagnostic, exitCode }),
+        reportPlan: (plan) => finish({ type: "plan", plan }, false),
+        close: () => {
+            finished = true;
+            peer.close();
+        },
+    };
+}
+//# sourceMappingURL=ipc.js.map

package/dist/runtime/process.js

@@ -0,0 +1,286 @@
+import crossSpawn from "cross-spawn";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { constants } from "node:os";
+import { readFile } from "node:fs/promises";
+import { setTimeout as delay } from "node:timers/promises";
+import { AgencyxError } from "../diagnostics.js";
+const execFileAsync = promisify(execFile);
+export function exitCode(result) {
+    return (result.code ?? 128 + (constants.signals[result.signal ?? "SIGTERM"] ?? 1));
+}
+export function startProcess(command, args, options = {}) {
+    const child = crossSpawn(command, [...args], { ...options, shell: false });
+    const exited = new Promise((resolve, reject) => {
+        child.once("error", () => reject(new AgencyxError({
+            code: "PROCESS_START_FAILED",
+            stage: "codex",
+            reason: "The selected executable could not be started.",
+        }, 3)));
+        child.once("exit", (code, signal) => resolve({ code, signal }));
+    });
+    const completion = new Promise((resolve, reject) => {
+        child.once("error", () => reject(new AgencyxError({
+            code: "PROCESS_START_FAILED",
+            stage: "codex",
+            reason: "The selected executable could not be started.",
+        }, 3)));
+        child.once("close", (code, signal) => resolve({ code, signal }));
+    });
+    // Callers can finish preparing their listeners before awaiting completion.
+    void completion.catch(() => undefined);
+    void exited.catch(() => undefined);
+    let stopping;
+    return {
+        child,
+        exited,
+        completion,
+        stop: (signal = "SIGTERM") => (stopping ??= stopProcessTree(child, completion, signal, options.detached === true)),
+    };
+}
+async function descendantPids(pid) {
+    try {
+        const { stdout } = await execFileAsync("ps", ["-eo", "pid=,ppid="], {
+            timeout: 2_000,
+            maxBuffer: 2 * 1024 * 1024,
+        });
+        const rows = stdout
+            .trim()
+            .split("\n")
+            .map((line) => line.trim().split(/\s+/).map(Number));
+        const descendants = [];
+        const parents = [pid];
+        for (let index = 0; index < parents.length; index++) {
+            for (const [child, parent] of rows) {
+                if (parent === parents[index] &&
+                    child !== undefined &&
+                    child !== process.pid &&
+                    !parents.includes(child)) {
+                    parents.push(child);
+                    descendants.push(child);
+                }
+            }
+        }
+        return descendants.reverse();
+    }
+    catch {
+        return [];
+    }
+}
+async function processIdentity(pid) {
+    try {
+        if (process.platform === "linux") {
+            const raw = await readFile(`/proc/${pid}/stat`, "utf8");
+            const state = raw.slice(raw.lastIndexOf(") ") + 2).split(" ");
+            return state[0] === "Z" ? undefined : state[19];
+        }
+        const { stdout } = await execFileAsync("ps", ["-p", String(pid), "-o", "lstart="], { timeout: 1_000 });
+        return stdout.trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function groupExists(pid) {
+    try {
+        process.kill(-pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function stopProcessTree(child, completion, signal, detached) {
+    if (!child.pid)
+        return;
+    const pid = child.pid;
+    if (process.platform !== "win32" && detached) {
+        // The group belongs to this headless child, including workers that outlive
+        // its launcher. Never signal the user's interactive foreground group.
+        if (!groupExists(pid))
+            return;
+        try {
+            process.kill(-pid, signal);
+        }
+        catch {
+            /* The group already exited. */
+        }
+        const deadline = Date.now() + 2_000;
+        while (groupExists(pid) && Date.now() < deadline)
+            await delay(25);
+        if (groupExists(pid)) {
+            try {
+                process.kill(-pid, "SIGKILL");
+            }
+            catch {
+                /* The group already exited. */
+            }
+        }
+        await completion.catch(() => undefined);
+        return;
+    }
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    if (process.platform === "win32") {
+        // taskkill is restricted to this child and its descendants, never an image name.
+        try {
+            await execFileAsync("taskkill.exe", ["/PID", String(pid), "/T", "/F"], {
+                timeout: 5_000,
+                windowsHide: true,
+            });
+        }
+        catch {
+            child.kill();
+        }
+    }
+    else {
+        const descendants = await descendantPids(pid);
+        const identities = new Map(await Promise.all(descendants.map(async (target) => [target, await processIdentity(target)])));
+        for (const target of [...descendants, pid]) {
+            try {
+                process.kill(target, signal);
+            }
+            catch {
+                /* The owned process already exited. */
+            }
+        }
+        let deadline;
+        const ended = await Promise.race([
+            completion.then(() => true, () => true),
+            new Promise((resolve) => {
+                deadline = setTimeout(() => resolve(false), 2_000);
+            }),
+        ]);
+        clearTimeout(deadline);
+        const surviving = async () => {
+            const checks = await Promise.all([...identities].map(async ([target, identity]) => identity !== undefined && (await processIdentity(target)) === identity
+                ? target
+                : undefined));
+            return checks.filter((target) => target !== undefined);
+        };
+        const grace = Date.now() + 2_000;
+        let remaining = await surviving();
+        while (remaining.length && Date.now() < grace) {
+            await delay(25);
+            remaining = await surviving();
+        }
+        for (const target of remaining) {
+            try {
+                process.kill(target, "SIGKILL");
+            }
+            catch {
+                /* The owned process already exited. */
+            }
+        }
+        if (!ended)
+            child.kill("SIGKILL");
+    }
+    await completion.catch(() => undefined);
+}
+export async function captureProcess(command, args, options = {}) {
+    const running = startProcess(command, args, {
+        ...options,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+        detached: process.platform !== "win32",
+    });
+    const limit = options.maxBytes ?? 8 * 1024 * 1024;
+    let stdout = "";
+    let stderr = "";
+    let size = 0;
+    let overflow = false;
+    let timedOut = false;
+    const collect = (stream, chunk) => {
+        size += Buffer.byteLength(chunk);
+        if (size > limit) {
+            overflow = true;
+            void running.stop();
+            return;
+        }
+        if (stream === "stdout")
+            stdout += chunk;
+        else
+            stderr += chunk;
+    };
+    running.child
+        .stdout.setEncoding("utf8")
+        .on("data", (chunk) => collect("stdout", chunk));
+    running.child
+        .stderr.setEncoding("utf8")
+        .on("data", (chunk) => collect("stderr", chunk));
+    const timer = setTimeout(() => {
+        if (running.child.exitCode !== null || running.child.signalCode !== null)
+            return;
+        timedOut = true;
+        void running.stop();
+    }, options.timeoutMs ?? 15_000);
+    timer.unref();
+    try {
+        const result = await Promise.race([
+            running.completion,
+            running.exited.then(async (status) => {
+                // Some official metadata commands detach helpers that retain their output
+                // handles. Drain the exited command, then release our readers; its helpers
+                // remain under the original CLI's ownership.
+                let timer;
+                await Promise.race([
+                    running.completion.catch(() => undefined),
+                    new Promise((resolve) => {
+                        timer = setTimeout(resolve, 100);
+                    }),
+                ]);
+                clearTimeout(timer);
+                running.child.stdout?.destroy();
+                running.child.stderr?.destroy();
+                return status;
+            }),
+        ]);
+        if (timedOut || overflow)
+            throw new AgencyxError({
+                code: timedOut ? "PROCESS_TIMEOUT" : "PROCESS_OUTPUT_LIMIT",
+                stage: "codex",
+                reason: timedOut
+                    ? "A preparation command exceeded its time limit."
+                    : "A preparation command exceeded its output limit.",
+            }, 6);
+        return { ...result, stdout, stderr };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function runInteractive(command, args, options) {
+    const running = startProcess(command, args, {
+        cwd: options.cwd,
+        env: options.env,
+        stdio: "inherit",
+    });
+    const abort = () => {
+        void running.stop(options.signal?.reason === "SIGINT" ? "SIGINT" : "SIGTERM");
+    };
+    options.signal?.addEventListener("abort", abort, { once: true });
+    if (options.signal?.aborted)
+        abort();
+    try {
+        return await running.completion;
+    }
+    finally {
+        options.signal?.removeEventListener("abort", abort);
+    }
+}
+export function observeSignals(onSignal, interactive = Boolean(process.stdin.isTTY), interruptPreparation = () => false) {
+    // A terminal sends SIGINT to the entire foreground group. Forwarding it again
+    // would turn Codex's cancel-current-turn behavior into a second interrupt.
+    const interrupt = () => {
+        if (!interactive || interruptPreparation())
+            onSignal("SIGINT");
+    };
+    const terminate = () => onSignal("SIGTERM");
+    process.on("SIGINT", interrupt);
+    process.on("SIGTERM", terminate);
+    return () => {
+        process.off("SIGINT", interrupt);
+        process.off("SIGTERM", terminate);
+    };
+}
+//# sourceMappingURL=process.js.map

package/dist/runtime/resolve-command.js

@@ -0,0 +1,38 @@
+import { access, realpath, stat } from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+import { fail } from "../diagnostics.js";
+export async function resolveCommand(name, override, cwd = process.cwd(), env = process.env) {
+    const requested = override ?? name;
+    if (!requested || requested.includes("\0"))
+        fail("DEPENDENCY_NOT_FOUND", "discovery", "The executable path is empty or invalid.", { component: name }, 3);
+    const windows = process.platform === "win32";
+    const pathKey = Object.keys(env).find((key) => key.toLowerCase() === "path");
+    const search = path.isAbsolute(requested) || /[/\\]/.test(requested)
+        ? [""]
+        : (env[pathKey ?? "PATH"] ?? "").split(path.delimiter).filter(Boolean);
+    // npm also creates an extensionless POSIX shell shim on Windows. Prefer the
+    // native Windows executable/shim rather than accidentally starting Git Bash.
+    const extensions = windows && !path.extname(requested)
+        ? (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD")
+            .toLowerCase()
+            .split(";")
+            .filter((extension) => [".com", ".exe", ".bat", ".cmd"].includes(extension))
+        : [""];
+    for (const directory of search) {
+        for (const extension of extensions) {
+            const candidate = path.resolve(cwd, directory, requested + extension);
+            try {
+                if (!(await stat(candidate)).isFile())
+                    continue;
+                await access(candidate, windows ? constants.F_OK : constants.X_OK);
+                return await realpath(candidate);
+            }
+            catch {
+                // Continue PATH lookup; a dependency error below never prints environment values.
+            }
+        }
+    }
+    fail("DEPENDENCY_NOT_FOUND", "discovery", `Install ${name} separately or set its AGENCYX executable-path override.`, { component: name }, 3);
+}
+//# sourceMappingURL=resolve-command.js.map