@kylecheng3146/agent-ops 0.5.2 → 0.6.0

package/dist/runtime/src/run/hosts/codex.js

@@ -0,0 +1,279 @@
+import { randomUUID } from "node:crypto";
+import { AgentOpsError } from "../../fs/paths.js";
+import { JsonRpcSession } from "./protocol.js";
+import { actionResult, assertContext, commandParts, event, assertProcessRunning, spawnNative, stopNativeProcess } from "./util.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nestedRecord(value, key) {
+    if (!isRecord(value) || !isRecord(value[key])) {
+        return null;
+    }
+    return value[key];
+}
+function stringField(value, key) {
+    return isRecord(value) && typeof value[key] === "string" ? value[key] : null;
+}
+function statusField(value) {
+    const status = stringField(value, "status");
+    return status === "active" || status === "paused" || status === "blocked" ||
+        status === "usageLimited" || status === "budgetLimited" || status === "complete"
+        ? status
+        : "unknown";
+}
+function resultThreadId(result, fallback = null) {
+    const thread = nestedRecord(result, "thread");
+    const id = stringField(thread, "id");
+    if (id === null) {
+        if (fallback !== null) {
+            return fallback;
+        }
+        throw new AgentOpsError("NATIVE_PROTOCOL_INVALID", "Codex app server did not return a thread id.");
+    }
+    return id;
+}
+function resultTurnId(result) {
+    const turn = nestedRecord(result, "turn");
+    return stringField(turn, "id");
+}
+export class CodexGoalHost {
+    options;
+    kind = "codex";
+    sessions = new WeakMap();
+    turns = new WeakMap();
+    now;
+    constructor(options = {}) {
+        this.options = options;
+        this.now = options.now ?? (() => new Date());
+    }
+    async start(input) {
+        const handle = await this.open(input, false, null);
+        return handle;
+    }
+    async resume(input, sessionId, objective) {
+        if (sessionId.length === 0) {
+            throw new AgentOpsError("NATIVE_SESSION_INVALID", "Codex thread id is required to resume.");
+        }
+        const handle = await this.open(input, true, sessionId);
+        if (objective !== undefined) {
+            await this.activate(handle, objective, input, input.tokenBudget);
+        }
+        return handle;
+    }
+    async activate(handle, objective, context, tokenBudget = null) {
+        assertContext(handle, context);
+        assertProcessRunning(handle.process);
+        if (objective.length === 0 || objective.length > 4000) {
+            throw new AgentOpsError("NATIVE_GOAL_INVALID", "Codex goal objective must be 1–4000 characters.");
+        }
+        const session = this.session(handle);
+        const goal = await session.request("thread/goal/set", {
+            threadId: handle.threadId,
+            objective,
+            status: "active",
+            tokenBudget
+        });
+        const turn = await session.request("turn/start", {
+            threadId: handle.threadId,
+            input: [{ type: "text", text: objective }],
+            approvalPolicy: "on-request",
+            approvalsReviewer: "auto_review"
+        });
+        const turnId = resultTurnId(turn);
+        if (turnId !== null) {
+            this.turns.set(handle, turnId);
+        }
+        return actionResult(true, statusField(nestedRecord(goal, "goal") ?? goal), goal);
+    }
+    async update(handle, update) {
+        assertContext(handle, update);
+        assertProcessRunning(handle.process);
+        const session = this.session(handle);
+        const goal = await session.request("thread/goal/set", {
+            threadId: handle.threadId,
+            objective: update.objective,
+            status: "active",
+            tokenBudget: update.tokenBudget ?? null
+        });
+        const turnId = this.turns.get(handle);
+        let turn;
+        if (turnId === undefined) {
+            turn = await session.request("turn/start", {
+                threadId: handle.threadId,
+                input: [{ type: "text", text: update.objective }],
+                approvalPolicy: "on-request",
+                approvalsReviewer: "auto_review"
+            });
+        }
+        else {
+            try {
+                turn = await session.request("turn/steer", {
+                    threadId: handle.threadId,
+                    expectedTurnId: turnId,
+                    input: [{ type: "text", text: update.objective }]
+                });
+            }
+            catch (error) {
+                if (!(error instanceof AgentOpsError) || error.code !== "NATIVE_REQUEST_FAILED") {
+                    throw error;
+                }
+                turn = await session.request("turn/start", {
+                    threadId: handle.threadId,
+                    input: [{ type: "text", text: update.objective }],
+                    approvalPolicy: "on-request",
+                    approvalsReviewer: "auto_review"
+                });
+            }
+        }
+        const nextTurnId = resultTurnId(turn);
+        if (nextTurnId !== null) {
+            this.turns.set(handle, nextTurnId);
+        }
+        return actionResult(true, statusField(nestedRecord(goal, "goal") ?? goal), goal);
+    }
+    async *observe(handle, options = {}) {
+        const session = this.session(handle);
+        while (true) {
+            const message = await session.nextEvent(options.signal);
+            if (message === null) {
+                return;
+            }
+            const mapped = this.mapEvent(handle, message);
+            yield { ...mapped, ...(typeof message.method === "string" ? { transportMethod: message.method } : {}) };
+            if (mapped.type === "completed" || mapped.type === "error" || mapped.type === "closed") {
+                return;
+            }
+        }
+    }
+    async interrupt(handle, context) {
+        assertContext(handle, context);
+        const session = this.session(handle);
+        const turnId = this.turns.get(handle);
+        if (turnId !== undefined) {
+            await session.request("turn/interrupt", { threadId: handle.threadId, turnId });
+        }
+        const result = await session.request("thread/goal/set", {
+            threadId: handle.threadId,
+            objective: null,
+            status: "paused",
+            tokenBudget: null
+        });
+        return actionResult(true, statusField(nestedRecord(result, "goal") ?? result), result);
+    }
+    async stop(handle, context, signal = "SIGTERM") {
+        assertContext(handle, context);
+        let payload = null;
+        try {
+            const result = await this.interrupt(handle, context);
+            payload = result.payload;
+        }
+        catch {
+            // A crashed or already closed native process is already stopped.
+        }
+        await stopNativeProcess(handle.process, signal);
+        return actionResult(true, "paused", payload);
+    }
+    async open(input, resume, threadId) {
+        const parts = commandParts(this.options, "codex", ["app-server", "--listen", "stdio://"]);
+        const process = spawnNative(parts.command, parts.args, input.cwd, input.env, this.options);
+        const channel = new JsonRpcSession(process, input.timeoutMs ?? this.options.requestTimeoutMs ?? 30_000);
+        try {
+            if (process.pid !== undefined)
+                await input.registerProcess?.(process.pid);
+            await this.sendInitialize(channel);
+            let nativeThreadId;
+            if (resume) {
+                const result = await channel.request("thread/resume", {
+                    threadId,
+                    cwd: input.cwd,
+                    approvalPolicy: "on-request",
+                    approvalsReviewer: "auto_review",
+                    sandbox: "workspace-write",
+                    excludeTurns: true
+                });
+                nativeThreadId = resultThreadId(result, threadId);
+            }
+            else {
+                const result = await channel.request("thread/start", {
+                    cwd: input.cwd,
+                    approvalPolicy: "on-request",
+                    approvalsReviewer: "auto_review",
+                    sandbox: "workspace-write",
+                    ephemeral: false
+                });
+                nativeThreadId = resultThreadId(result);
+            }
+            const handle = {
+                runId: input.runId,
+                workerId: input.workerId,
+                generation: input.generation,
+                contractHash: input.contractHash,
+                kind: this.kind,
+                sessionId: input.sessionId ?? randomUUID(),
+                threadId: nativeThreadId,
+                nativeVersion: input.nativeVersion ?? this.options.nativeVersion ?? null,
+                cwd: input.cwd,
+                processId: process.pid ?? null,
+                startedAt: this.now().toISOString(),
+                process,
+                goalStatus: "unknown"
+            };
+            this.sessions.set(handle, channel);
+            return handle;
+        }
+        catch (cause) {
+            channel.close(cause);
+            if (process.pid !== undefined)
+                await stopNativeProcess(process, "SIGKILL");
+            throw cause;
+        }
+    }
+    async sendInitialize(session) {
+        // Keep the notification sequence in one helper so callers cannot send a
+        // goal before the app-server handshake is complete.
+        await session.request("initialize", {
+            capabilities: { experimentalApi: true },
+            clientInfo: {
+                name: "agent-ops",
+                title: "agent-ops native goal host",
+                version: "0.6.0"
+            }
+        });
+        session.notify("initialized", {});
+    }
+    session(handle) {
+        const session = this.sessions.get(handle);
+        if (session === undefined) {
+            throw new AgentOpsError("NATIVE_SESSION_INVALID", "Unknown Codex native handle.");
+        }
+        return session;
+    }
+    mapEvent(handle, message) {
+        const method = typeof message.method === "string" ? message.method : "message";
+        const payload = isRecord(message.params) ? message.params : message;
+        if (method === "thread/goal/updated") {
+            const goal = isRecord(payload.goal) ? payload.goal : payload;
+            const status = statusField(goal);
+            return event(handle, status === "complete" ? "completed" : "goal-updated", status, payload, this.now);
+        }
+        if (method === "thread/goal/cleared") {
+            return event(handle, "goal-updated", "complete", payload, this.now);
+        }
+        if (method === "turn/completed") {
+            this.turns.delete(handle);
+            // A completed turn is not necessarily a completed native goal. Native
+            // goals can continue automatically after a turn boundary.
+            return event(handle, "message", "unknown", payload, this.now);
+        }
+        if (method === "turn/started") {
+            const turn = nestedRecord(payload, "turn");
+            const id = stringField(turn, "id");
+            if (id !== null)
+                this.turns.set(handle, id);
+        }
+        if (method.includes("usage") || method.includes("token")) {
+            return event(handle, "usage", "unknown", payload, this.now);
+        }
+        return event(handle, "message", "unknown", payload, this.now);
+    }
+}

package/dist/runtime/src/run/hosts/index.js

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./protocol.js";
+export * from "./codex.js";
+export * from "./claude.js";

package/dist/runtime/src/run/hosts/protocol.js

@@ -0,0 +1,254 @@
+import { createInterface } from "node:readline";
+import { AgentOpsError } from "../../fs/paths.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseLine(line, source) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch (error) {
+        throw new AgentOpsError("NATIVE_PROTOCOL_INVALID", `Invalid JSON from ${source}.`, { cause: error });
+    }
+    if (!isRecord(parsed)) {
+        throw new AgentOpsError("NATIVE_PROTOCOL_INVALID", `Native ${source} message is not an object.`);
+    }
+    return parsed;
+}
+/** JSONL request/notification channel used by the Codex app server. */
+export class JsonRpcSession {
+    child;
+    requestTimeoutMs;
+    lines;
+    pending = new Map();
+    events = [];
+    waiters = [];
+    nextId = 1;
+    closed = null;
+    constructor(child, requestTimeoutMs = 30_000) {
+        this.child = child;
+        this.requestTimeoutMs = requestTimeoutMs;
+        this.lines = createInterface({ input: child.stdout });
+        this.lines.on("line", (line) => this.receive(line, "stdout"));
+        child.once("error", (error) => this.close(error));
+        child.once("exit", (code, signal) => {
+            this.close(new AgentOpsError("NATIVE_PROCESS_CLOSED", `Native process closed (code=${String(code)}, signal=${String(signal)}).`));
+        });
+    }
+    async request(method, params) {
+        if (this.closed !== null) {
+            throw this.closed;
+        }
+        const id = this.nextId++;
+        const request = { jsonrpc: "2.0", id, method, params };
+        const response = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new AgentOpsError("NATIVE_REQUEST_TIMEOUT", `Native request timed out: ${method}`));
+            }, this.requestTimeoutMs);
+            this.pending.set(id, { resolve, reject, timer });
+        });
+        this.write(request);
+        return response;
+    }
+    notify(method, params = {}) {
+        if (this.closed !== null) {
+            throw this.closed;
+        }
+        this.write({ jsonrpc: "2.0", method, params });
+    }
+    async nextEvent(signal) {
+        if (this.events.length > 0) {
+            return this.events.shift() ?? null;
+        }
+        if (this.closed !== null) {
+            return null;
+        }
+        return new Promise((resolve, reject) => {
+            const waiter = { resolve, reject, signal };
+            if (signal !== undefined) {
+                if (signal.aborted) {
+                    resolve(null);
+                    return;
+                }
+                const onAbort = () => {
+                    const index = this.waiters.indexOf(waiter);
+                    if (index >= 0) {
+                        this.waiters.splice(index, 1);
+                    }
+                    resolve(null);
+                };
+                waiter.onAbort = onAbort;
+                signal.addEventListener("abort", onAbort, { once: true });
+            }
+            this.waiters.push(waiter);
+        });
+    }
+    close(error = null) {
+        if (this.closed !== null) {
+            return;
+        }
+        this.closed = error ?? new AgentOpsError("NATIVE_PROCESS_CLOSED", "Native process closed.");
+        this.lines.close();
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(this.closed);
+        }
+        this.pending.clear();
+        for (const waiter of this.waiters.splice(0)) {
+            if (waiter.signal !== undefined && waiter.onAbort !== undefined) {
+                waiter.signal.removeEventListener("abort", waiter.onAbort);
+            }
+            waiter.resolve(null);
+        }
+    }
+    receive(line, source) {
+        if (line.trim().length === 0) {
+            return;
+        }
+        let message;
+        try {
+            message = parseLine(line, source);
+        }
+        catch (error) {
+            this.close(error);
+            return;
+        }
+        const id = message.id;
+        if (typeof id === "number" && Number.isSafeInteger(id)) {
+            const pending = this.pending.get(id);
+            if (pending === undefined) {
+                this.enqueue(message);
+                return;
+            }
+            this.pending.delete(id);
+            clearTimeout(pending.timer);
+            if (isRecord(message.error)) {
+                pending.reject(new AgentOpsError("NATIVE_REQUEST_FAILED", String(message.error.message ?? "Native request failed"), { cause: message.error }));
+            }
+            else if (isRecord(message.result)) {
+                pending.resolve(message.result);
+            }
+            else {
+                pending.resolve(message);
+            }
+            return;
+        }
+        this.enqueue(message);
+    }
+    write(message) {
+        this.child.stdin.write(`${JSON.stringify(message)}\n`);
+    }
+    enqueue(message) {
+        const waiter = this.waiters.shift();
+        if (waiter !== undefined) {
+            if (waiter.signal !== undefined && waiter.onAbort !== undefined) {
+                waiter.signal.removeEventListener("abort", waiter.onAbort);
+            }
+            waiter.resolve(message);
+        }
+        else {
+            this.events.push(message);
+        }
+    }
+}
+/** Newline-delimited stream used by Claude Code's stream-json mode. */
+export class JsonLineStream {
+    child;
+    lines;
+    events = [];
+    waiters = [];
+    closed = false;
+    constructor(child) {
+        this.child = child;
+        this.lines = createInterface({ input: child.stdout });
+        this.lines.on("line", (line) => {
+            if (line.trim().length === 0) {
+                return;
+            }
+            try {
+                this.enqueue(parseLine(line, "stdout"));
+            }
+            catch (error) {
+                this.close(error);
+            }
+        });
+        child.once("error", (error) => this.close(error));
+        child.once("exit", () => this.close());
+    }
+    async next(signal) {
+        if (this.events.length > 0) {
+            return this.events.shift() ?? null;
+        }
+        if (this.closed) {
+            return null;
+        }
+        return new Promise((resolve, reject) => {
+            const waiter = { resolve, reject, signal };
+            if (signal !== undefined) {
+                if (signal.aborted) {
+                    resolve(null);
+                    return;
+                }
+                const onAbort = () => {
+                    const index = this.waiters.indexOf(waiter);
+                    if (index >= 0) {
+                        this.waiters.splice(index, 1);
+                    }
+                    resolve(null);
+                };
+                waiter.onAbort = onAbort;
+                signal.addEventListener("abort", onAbort, { once: true });
+            }
+            this.waiters.push(waiter);
+        });
+    }
+    requeue(message) {
+        this.events.unshift(message);
+    }
+    close(_error) {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.lines.close();
+        for (const waiter of this.waiters.splice(0)) {
+            if (waiter.signal !== undefined && waiter.onAbort !== undefined) {
+                waiter.signal.removeEventListener("abort", waiter.onAbort);
+            }
+            waiter.resolve(null);
+        }
+    }
+    enqueue(message) {
+        const waiter = this.waiters.shift();
+        if (waiter !== undefined) {
+            if (waiter.signal !== undefined && waiter.onAbort !== undefined) {
+                waiter.signal.removeEventListener("abort", waiter.onAbort);
+            }
+            waiter.resolve(message);
+        }
+        else {
+            this.events.push(message);
+        }
+    }
+}
+export function asNativePayload(value) {
+    if (value === null || typeof value === "boolean" || typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? value : null;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => asNativePayload(item));
+    }
+    if (typeof value === "object") {
+        const object = {};
+        for (const [key, item] of Object.entries(value)) {
+            object[key] = asNativePayload(item);
+        }
+        return object;
+    }
+    return null;
+}

package/dist/runtime/src/run/hosts/types.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/src/run/hosts/util.js

@@ -0,0 +1,136 @@
+import { randomUUID } from "node:crypto";
+import { spawn as nodeSpawn } from "node:child_process";
+import { AgentOpsError } from "../../fs/paths.js";
+import { asNativePayload } from "./protocol.js";
+export function spawnNative(command, args, cwd, env, options) {
+    const spawn = options.spawn ?? ((name, argv, spawnOptions) => nodeSpawn(name, [...argv], spawnOptions));
+    const child = spawn(command, args, {
+        cwd,
+        env: { ...process.env, ...options.env, ...env },
+        stdio: ["pipe", "pipe", "pipe"],
+        detached: process.platform !== "win32"
+    });
+    // Native clients can emit diagnostics independently of their structured
+    // stdout protocol. Drain stderr so a long-lived writer cannot deadlock on a
+    // full pipe; structured lifecycle events remain the source of truth.
+    child.stderr.resume();
+    return child;
+}
+export function assertContext(handle, context) {
+    if (handle.runId !== context.runId ||
+        handle.workerId !== context.workerId ||
+        handle.generation !== context.generation ||
+        handle.contractHash !== context.contractHash) {
+        throw new AgentOpsError("NATIVE_STALE_WRITER", "The native action belongs to a stale run worker generation.");
+    }
+}
+export function assertProcessRunning(child) {
+    if (child.exitCode !== null || child.signalCode !== null) {
+        throw new AgentOpsError("NATIVE_PROCESS_CLOSED", "The native worker process is already closed.");
+    }
+}
+export function actionResult(accepted, nativeStatus, payload) {
+    return {
+        actionId: randomUUID(),
+        accepted,
+        nativeStatus,
+        payload: asNativePayload(payload)
+    };
+}
+export function event(handle, type, nativeStatus, payload, now) {
+    return {
+        type,
+        host: handle.kind,
+        runId: handle.runId,
+        workerId: handle.workerId,
+        generation: handle.generation,
+        contractHash: handle.contractHash,
+        at: now().toISOString(),
+        nativeStatus,
+        payload: asNativePayload(payload),
+        proof: false
+    };
+}
+export async function waitForExit(child, timeoutMs = 10_000) {
+    if (child.exitCode !== null || child.signalCode !== null) {
+        return;
+    }
+    await new Promise((resolve) => {
+        let settled = false;
+        const settle = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(settle, timeoutMs);
+        child.once("exit", settle);
+        child.once("error", settle);
+    });
+}
+export function commandParts(options, fallbackCommand, fallbackArgs) {
+    return {
+        command: options.command ?? fallbackCommand,
+        args: options.args ?? fallbackArgs
+    };
+}
+/** Native writers own a process group, including their managed command children. */
+export function nativeProcessGroupAlive(pid) {
+    try {
+        process.kill(-pid, 0);
+        return true;
+    }
+    catch (cause) {
+        if (cause.code === "ESRCH")
+            return false;
+        // Permission errors cannot establish death.
+        return true;
+    }
+}
+export async function signalNativeProcessGroup(pid, signal) {
+    try {
+        process.kill(process.platform === "win32" ? pid : -pid, signal);
+    }
+    catch (cause) {
+        const code = cause.code;
+        if (code === "ESRCH")
+            return;
+        if (code === "EPERM" && process.platform !== "win32") {
+            // macOS can report EPERM while an already-killed group is being reaped.
+            // Permission failure is safe to dismiss only after the kernel confirms absence.
+            for (let i = 0; i < 30 && nativeProcessGroupAlive(pid); i++)
+                await new Promise(resolve => setTimeout(resolve, 100));
+            if (!nativeProcessGroupAlive(pid))
+                return;
+        }
+        throw cause;
+    }
+}
+export async function stopNativeProcess(child, signal) {
+    const pid = child.pid;
+    if (pid === undefined)
+        throw new AgentOpsError("NATIVE_PROCESS_UNKNOWN", "Native process has no registered PID.");
+    const send = async (s) => {
+        if (process.platform !== "win32")
+            return await signalNativeProcessGroup(pid, s);
+        try {
+            child.kill(s);
+        }
+        catch (cause) {
+            if (cause.code !== "ESRCH")
+                throw cause;
+        }
+    };
+    await send(signal);
+    await waitForExit(child, 3000);
+    if (process.platform !== "win32" && nativeProcessGroupAlive(pid)) {
+        await send("SIGKILL");
+        for (let i = 0; i < 30 && nativeProcessGroupAlive(pid); i++)
+            await new Promise(resolve => setTimeout(resolve, 100));
+        if (nativeProcessGroupAlive(pid))
+            throw new AgentOpsError("NATIVE_PROCESS_STILL_ALIVE", "Managed native descendants have not stopped; takeover is refused.");
+    }
+    if (child.exitCode === null && child.signalCode === null)
+        throw new AgentOpsError("NATIVE_PROCESS_STILL_ALIVE", "Native stop did not confirm process death.");
+}