@alpacakit/agents 0.1.0-beta.39 → 0.2.0-beta.2

package/dist/agents/codex-session.js

@@ -0,0 +1,495 @@
+/**
+ * Codex session adapter: one `codex app-server` process holding one thread.
+ *
+ * Protocol facts (codex 0.153.4, T53 / T57 / T61 lab runs):
+ * - `thread/start {cwd, sandbox, approvalPolicy, approvalsReviewer}` creates
+ *   the thread and takes its writer lock; with a writable sandbox Codex also
+ *   appends a `trust_level` entry for `cwd` to `~/.codex/config.toml`;
+ * - `thread/resume` must repeat the permissions — without `sandbox` the
+ *   resumed turns ran as danger-full-access; it answers -32600 "already has
+ *   an active writer" while another process holds the thread and -32600
+ *   "… is archived" for an archived one (`thread/unarchive` first, opt-in);
+ * - `turn/start` answers the turn id at once; `turn/steer {expectedTurnId}`
+ *   appends to it; `turn/interrupt` ends it with `turn/completed`
+ *   status `interrupted` (the command's own `item/completed` may trail by ~36 s);
+ * - `item/commandExecution/requestApproval` is a server request answered by
+ *   `{"decision": "accept" | "decline"}`; closing stdin releases the lock.
+ */
+import path from "node:path";
+import { CODEX_INCOMING_KIND, createCodexAppServer, } from "../codex/app-server.js";
+import { CODEX_APP_SERVER_INCOMING, CODEX_APP_SERVER_METHOD, CODEX_SANDBOX_MODE, encodeCodexThreadPermissions, } from "../codex/protocol.js";
+import { isAgentError } from "../core/error.js";
+import { readArray, readBoolean, readRecord, readString, } from "../core/json.js";
+import { APPROVAL_DECISION, SESSION_EVENT_TYPE, SESSION_OWNER_KIND, TURN_OUTCOME, } from "../core/session.js";
+import { fileExists, readDirectoryNames, scanJsonlFirstLast, } from "../host/session-files.js";
+import { assertHostSessionId, SessionState, sessionStateError, } from "../kernel/session.js";
+const CODEX_ID = "codex";
+const CODEX_COMMAND = "codex";
+/** `approval_policy` words (codex 0.153.4 `AskForApproval`; the granular object form is not modeled). */
+export const CODEX_APPROVAL_POLICY = {
+    untrusted: "untrusted",
+    onRequest: "on-request",
+    never: "never",
+};
+export const CODEX_APPROVALS_REVIEWER = {
+    user: "user",
+    autoReview: "auto_review",
+    guardianSubagent: "guardian_subagent",
+};
+const CODEX_SESSION = {
+    notification: {
+        threadId: "threadId",
+        turnId: "turnId",
+        turn: "turn",
+        item: "item",
+        id: "id",
+        type: "type",
+        text: "text",
+        status: "status",
+        items: "items",
+        phase: "phase",
+        finalAnswer: "final_answer",
+        agentMessage: "agentMessage",
+        userMessage: "userMessage",
+        reasoning: "reasoning",
+        command: "command",
+        reason: "reason",
+    },
+    turnStatus: {
+        completed: "completed",
+        interrupted: "interrupted",
+        failed: "failed",
+    },
+    decision: { accept: "accept", decline: "decline" },
+    error: {
+        archived: "is archived",
+        methodNotFound: -32601,
+        unsupported: "unsupported server request",
+    },
+    files: {
+        root: ".codex",
+        sessions: "sessions",
+        archivedSessions: "archived_sessions",
+        writerLocks: "thread-writer-locks",
+        lockExtension: ".lock",
+        rolloutExtension: ".jsonl",
+        type: "type",
+        payload: "payload",
+        sessionMeta: "session_meta",
+        turnContext: "turn_context",
+        cwd: "cwd",
+        approvalPolicy: "approval_policy",
+        approvalsReviewer: "approvals_reviewer",
+        sandboxPolicy: "sandbox_policy",
+        writableRoots: "writable_roots",
+        networkAccess: "network_access",
+        excludeTmpdirEnvVar: "exclude_tmpdir_env_var",
+        excludeSlashTmp: "exclude_slash_tmp",
+    },
+};
+const USER_INPUT_TEXT = "text";
+const APPROVAL_METHODS = [
+    CODEX_APP_SERVER_INCOMING.commandExecutionRequestApproval,
+    CODEX_APP_SERVER_INCOMING.fileChangeRequestApproval,
+];
+const NON_TOOL_ITEM_TYPES = [
+    CODEX_SESSION.notification.agentMessage,
+    CODEX_SESSION.notification.userMessage,
+    CODEX_SESSION.notification.reasoning,
+];
+function wirePermissions(permissions) {
+    const sandbox = permissions.sandbox;
+    return encodeCodexThreadPermissions({
+        sandbox: sandbox.type,
+        approvalPolicy: permissions.approvalPolicy,
+        approvalsReviewer: permissions.approvalsReviewer,
+        workspaceWrite: sandbox.type === CODEX_SANDBOX_MODE.workspaceWrite
+            ? {
+                writableRoots: sandbox.writableRoots,
+                networkAccess: sandbox.networkAccess,
+                excludeTmpdirEnvVar: sandbox.excludeTmpdirEnvVar,
+                excludeSlashTmp: sandbox.excludeSlashTmp,
+            }
+            : null,
+    });
+}
+function turnOutcomeFrom(status) {
+    if (status === CODEX_SESSION.turnStatus.interrupted) {
+        return TURN_OUTCOME.interrupted;
+    }
+    if (status === CODEX_SESSION.turnStatus.completed) {
+        return TURN_OUTCOME.completed;
+    }
+    return TURN_OUTCOME.failed;
+}
+/** The last `agentMessage` with phase `final_answer` among a completed turn's items. */
+function finalAnswerOf(turn) {
+    let text = null;
+    for (const value of readArray(turn, CODEX_SESSION.notification.items) ?? []) {
+        const item = value !== null && typeof value === "object"
+            ? value
+            : null;
+        if (item !== null &&
+            readString(item, CODEX_SESSION.notification.type) ===
+                CODEX_SESSION.notification.agentMessage &&
+            readString(item, CODEX_SESSION.notification.phase) ===
+                CODEX_SESSION.notification.finalAnswer) {
+            text = readString(item, CODEX_SESSION.notification.text) ?? text;
+        }
+    }
+    return text;
+}
+/**
+ * Codex accepts `decline` for every approval request even when its
+ * `availableDecisions` lists only `accept` plus amendment / `cancel`
+ * variants (T53 h2), so the caller is always offered both answers.
+ */
+const CODEX_APPROVAL_DECISIONS = [
+    APPROVAL_DECISION.accept,
+    APPROVAL_DECISION.decline,
+];
+class CodexSession {
+    id;
+    client;
+    ctx;
+    state = new SessionState(CODEX_ID);
+    pendingApprovals = new Map();
+    /** Notifications that arrived while `turn/start` was still unanswered. */
+    buffered = [];
+    reading;
+    constructor(id, client, incoming, ctx) {
+        this.id = id;
+        this.client = client;
+        this.ctx = ctx;
+        this.reading = this.read(incoming);
+    }
+    get events() {
+        return this.state.events;
+    }
+    async send(text) {
+        this.state.requireIdle();
+        // The slot is taken from here: a second send() during the round trip is
+        // refused, and notifications that beat the response are held back.
+        this.state.markStarting();
+        let turnId;
+        try {
+            ({ turnId } = await this.client.request(CODEX_APP_SERVER_METHOD.turnStart, {
+                threadId: this.id,
+                input: [{ type: USER_INPUT_TEXT, text }],
+            }));
+        }
+        catch (error) {
+            this.state.clearStarting();
+            this.buffered.splice(0);
+            throw error;
+        }
+        const turn = this.state.beginTurn(turnId);
+        for (const held of this.buffered.splice(0)) {
+            this.handleNotification(held.method, held.params);
+        }
+        return turn;
+    }
+    async steer(text) {
+        const turnId = this.state.requireActive();
+        await this.client.request(CODEX_APP_SERVER_METHOD.turnSteer, {
+            threadId: this.id,
+            expectedTurnId: turnId,
+            input: [{ type: USER_INPUT_TEXT, text }],
+        });
+    }
+    async interrupt() {
+        const turnId = this.state.requireActive();
+        await this.client.request(CODEX_APP_SERVER_METHOD.turnInterrupt, {
+            threadId: this.id,
+            turnId,
+        });
+    }
+    async respond(requestId, decision) {
+        this.state.requireOpen();
+        const request = this.pendingApprovals.get(requestId);
+        if (request === undefined) {
+            throw sessionStateError(CODEX_ID, `no pending approval request "${requestId}"`);
+        }
+        this.pendingApprovals.delete(requestId);
+        this.client.respond(request.id, {
+            result: {
+                decision: decision === APPROVAL_DECISION.accept
+                    ? CODEX_SESSION.decision.accept
+                    : CODEX_SESSION.decision.decline,
+            },
+        });
+    }
+    async close() {
+        await this.client.close();
+        await this.reading;
+    }
+    async read(incoming) {
+        try {
+            for (let step = await incoming.next(); !step.done; step = await incoming.next()) {
+                if (step.value.kind === CODEX_INCOMING_KIND.request) {
+                    this.handleServerRequest(step.value);
+                }
+                else {
+                    this.handleNotification(step.value.method, step.value.params);
+                }
+            }
+        }
+        catch (error) {
+            this.ctx.logger.log("error", "codex session reader failed", error);
+        }
+        finally {
+            // Whatever happened above, the stream must end so `events` consumers
+            // and `close()` are released.
+            this.pendingApprovals.clear();
+            this.state.end(await this.client.exit, this.client.stderrTail);
+        }
+    }
+    forActiveTurn(params) {
+        if (params === null ||
+            readString(params, CODEX_SESSION.notification.threadId) !== this.id) {
+            return null;
+        }
+        return params;
+    }
+    handleNotification(method, raw) {
+        const params = this.forActiveTurn(raw);
+        if (params === null) {
+            return;
+        }
+        if (this.state.isStarting) {
+            this.buffered.push({ method, params });
+            return;
+        }
+        const active = this.state.activeTurnId;
+        if (method === CODEX_APP_SERVER_INCOMING.turnCompleted) {
+            const turn = readRecord(params, CODEX_SESSION.notification.turn);
+            if (turn === null ||
+                readString(turn, CODEX_SESSION.notification.id) !== active) {
+                return;
+            }
+            // Approval requests belong to the turn that raised them.
+            this.pendingApprovals.clear();
+            this.state.endTurn(turnOutcomeFrom(readString(turn, CODEX_SESSION.notification.status)), finalAnswerOf(turn));
+            return;
+        }
+        if (readString(params, CODEX_SESSION.notification.turnId) !== active) {
+            return;
+        }
+        const item = readRecord(params, CODEX_SESSION.notification.item);
+        const itemType = item === null ? null : readString(item, CODEX_SESSION.notification.type);
+        if (item === null || itemType === null) {
+            return;
+        }
+        if (method === CODEX_APP_SERVER_INCOMING.itemStarted &&
+            !NON_TOOL_ITEM_TYPES.includes(itemType)) {
+            this.state.emit({ type: SESSION_EVENT_TYPE.tool, name: itemType });
+            return;
+        }
+        if (method === CODEX_APP_SERVER_INCOMING.itemCompleted &&
+            itemType === CODEX_SESSION.notification.agentMessage) {
+            const text = readString(item, CODEX_SESSION.notification.text);
+            if (text !== null && text !== "") {
+                this.state.message(text);
+            }
+        }
+    }
+    handleServerRequest(request) {
+        const params = this.forActiveTurn(request.params);
+        if (params === null || !APPROVAL_METHODS.includes(request.method)) {
+            // An unanswered server request would hang the turn; refusing it lets
+            // the model see the failure and go on.
+            this.ctx.logger.log("warn", `refusing unsupported codex server request "${request.method}"`);
+            this.client.respond(request.id, {
+                error: {
+                    code: CODEX_SESSION.error.methodNotFound,
+                    message: CODEX_SESSION.error.unsupported,
+                },
+            });
+            return;
+        }
+        const requestId = String(request.id);
+        this.pendingApprovals.set(requestId, request);
+        this.state.emit({
+            type: SESSION_EVENT_TYPE.approvalRequested,
+            requestId,
+            summary: readString(params, CODEX_SESSION.notification.command) ??
+                readString(params, CODEX_SESSION.notification.reason) ??
+                request.method,
+            decisions: CODEX_APPROVAL_DECISIONS,
+        });
+    }
+}
+function subscribe(client) {
+    return client.incoming[Symbol.asyncIterator]();
+}
+async function openCodexSession(options, ctx) {
+    const client = createCodexAppServer({
+        exec: ctx.exec,
+        clock: ctx.clock,
+        env: ctx.env,
+        cwd: options.workspace,
+        command: CODEX_COMMAND,
+    });
+    const incoming = subscribe(client);
+    try {
+        const { threadId } = await client.request(CODEX_APP_SERVER_METHOD.threadStart, {
+            cwd: options.workspace,
+            ...wirePermissions(options.permissions),
+        });
+        return new CodexSession(threadId, client, incoming, ctx);
+    }
+    catch (error) {
+        await client.close();
+        throw error;
+    }
+}
+async function resumeCodexSession(id, options, ctx) {
+    assertHostSessionId(id, CODEX_ID);
+    const client = createCodexAppServer({
+        exec: ctx.exec,
+        clock: ctx.clock,
+        env: ctx.env,
+        cwd: options.workspace,
+        command: CODEX_COMMAND,
+    });
+    const incoming = subscribe(client);
+    const params = {
+        threadId: id,
+        excludeTurns: true,
+        ...wirePermissions(options.permissions),
+    };
+    try {
+        let resumed;
+        try {
+            resumed = await client.request(CODEX_APP_SERVER_METHOD.threadResume, params);
+        }
+        catch (error) {
+            // Unarchiving is a visible side effect (the thread returns to the
+            // ChatGPT app's active list), so it happens only on request.
+            if (!options.unarchive || !isArchivedError(error)) {
+                throw error;
+            }
+            await client.request(CODEX_APP_SERVER_METHOD.threadUnarchive, {
+                threadId: id,
+            });
+            resumed = await client.request(CODEX_APP_SERVER_METHOD.threadResume, params);
+        }
+        return new CodexSession(resumed.threadId, client, incoming, ctx);
+    }
+    catch (error) {
+        await client.close();
+        throw error;
+    }
+}
+function isArchivedError(error) {
+    return (isAgentError(error, "failed") &&
+        error.message.includes(CODEX_SESSION.error.archived));
+}
+function codexRoot(ctx, ...segments) {
+    return path.join(ctx.location.homeDir, CODEX_SESSION.files.root, ...segments);
+}
+/** `rollout-<time>-<id>.jsonl` under `sessions/YYYY/MM/DD/` (live) or `archived_sessions/` (archived). */
+async function findCodexRollout(ctx, id) {
+    const suffix = `-${id.toLowerCase()}${CODEX_SESSION.files.rolloutExtension}`;
+    const matches = (name) => name.toLowerCase().endsWith(suffix);
+    const root = codexRoot(ctx, CODEX_SESSION.files.sessions);
+    for (const year of (await readDirectoryNames(root)).sort().reverse()) {
+        for (const month of (await readDirectoryNames(path.join(root, year)))
+            .sort()
+            .reverse()) {
+            const monthDir = path.join(root, year, month);
+            for (const day of (await readDirectoryNames(monthDir)).sort().reverse()) {
+                const dayDir = path.join(monthDir, day);
+                const file = (await readDirectoryNames(dayDir)).find(matches);
+                if (file !== undefined) {
+                    return { file: path.join(dayDir, file), archived: false };
+                }
+            }
+        }
+    }
+    const archivedRoot = codexRoot(ctx, CODEX_SESSION.files.archivedSessions);
+    const archived = (await readDirectoryNames(archivedRoot)).find(matches);
+    return archived === undefined
+        ? null
+        : { file: path.join(archivedRoot, archived), archived: true };
+}
+function oneOf(values, value) {
+    return value !== null && values.includes(value)
+        ? value
+        : null;
+}
+/** Only shapes seen in rollouts decode; anything unfamiliar is `null`, never a guess. */
+function sandboxPolicyFrom(policy) {
+    const type = policy === null ? null : readString(policy, CODEX_SESSION.files.type);
+    if (type === CODEX_SANDBOX_MODE.readOnly ||
+        type === CODEX_SANDBOX_MODE.dangerFullAccess) {
+        return { type };
+    }
+    if (policy === null || type !== CODEX_SANDBOX_MODE.workspaceWrite) {
+        return null;
+    }
+    const roots = readArray(policy, CODEX_SESSION.files.writableRoots) ?? [];
+    const networkAccess = readBoolean(policy, CODEX_SESSION.files.networkAccess);
+    const excludeTmpdirEnvVar = readBoolean(policy, CODEX_SESSION.files.excludeTmpdirEnvVar);
+    const excludeSlashTmp = readBoolean(policy, CODEX_SESSION.files.excludeSlashTmp);
+    if (!roots.every((root) => typeof root === "string") ||
+        networkAccess === null ||
+        excludeTmpdirEnvVar === null ||
+        excludeSlashTmp === null) {
+        return null;
+    }
+    return {
+        type,
+        writableRoots: roots,
+        networkAccess,
+        excludeTmpdirEnvVar,
+        excludeSlashTmp,
+    };
+}
+function permissionsFrom(context) {
+    const approvalPolicy = oneOf(Object.values(CODEX_APPROVAL_POLICY), readString(context, CODEX_SESSION.files.approvalPolicy));
+    const approvalsReviewer = oneOf(Object.values(CODEX_APPROVALS_REVIEWER), readString(context, CODEX_SESSION.files.approvalsReviewer));
+    const sandbox = sandboxPolicyFrom(readRecord(context, CODEX_SESSION.files.sandboxPolicy));
+    if (approvalPolicy === null ||
+        approvalsReviewer === null ||
+        sandbox === null) {
+        return null;
+    }
+    return { approvalPolicy, approvalsReviewer, sandbox };
+}
+function payloadOfType(record, type) {
+    return readString(record, CODEX_SESSION.files.type) === type
+        ? readRecord(record, CODEX_SESSION.files.payload)
+        : null;
+}
+async function inspectCodexSession(id, ctx) {
+    assertHostSessionId(id, CODEX_ID);
+    const rollout = await findCodexRollout(ctx, id);
+    if (rollout === null) {
+        return null;
+    }
+    const cwd = await scanJsonlFirstLast(rollout.file, (record) => {
+        const meta = payloadOfType(record, CODEX_SESSION.files.sessionMeta);
+        return meta === null ? null : readString(meta, CODEX_SESSION.files.cwd);
+    });
+    if (cwd.first === null) {
+        return null;
+    }
+    const contexts = await scanJsonlFirstLast(rollout.file, (record) => payloadOfType(record, CODEX_SESSION.files.turnContext));
+    const locked = await fileExists(codexRoot(ctx, CODEX_SESSION.files.writerLocks, `${id}${CODEX_SESSION.files.lockExtension}`));
+    return {
+        workspace: cwd.first,
+        lastPermissions: contexts.last === null ? null : permissionsFrom(contexts.last),
+        owner: locked
+            ? { kind: SESSION_OWNER_KIND.process, pid: null, entrypoint: null }
+            : { kind: SESSION_OWNER_KIND.none },
+        archived: rollout.archived,
+    };
+}
+export function codexSessions() {
+    return {
+        open: openCodexSession,
+        resume: resumeCodexSession,
+        inspect: inspectCodexSession,
+    };
+}

package/dist/agents/codex.d.ts

@@ -7,6 +7,7 @@
  */
 import { type FailureMatcher } from "../kernel/classify.js";
 import type { AgentDefinition } from "../kernel/definition.js";
+import { type CodexSessionPermissions } from "./codex-session.js";
 export declare const CODEX_HOME_ENV_VAR = "CODEX_HOME";
 export declare const CODEX_API_KEY_ENV_VAR = "OPENAI_API_KEY";
 /**
@@ -15,5 +16,5 @@ export declare const CODEX_API_KEY_ENV_VAR = "OPENAI_API_KEY";
  * surface the same provider text.
  */
 export declare function capacityTextMatcher(): FailureMatcher;
-export declare function codex(): AgentDefinition<"codex">;
+export declare function codex(): AgentDefinition<"codex", CodexSessionPermissions>;
 //# sourceMappingURL=codex.d.ts.map

package/dist/agents/codex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../src/agents/codex.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAyCH,OAAO,EAAE,KAAK,cAAc,EAAqB,MAAM,uBAAuB,CAAC;AAG/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG/D,eAAO,MAAM,kBAAkB,eAAe,CAAC;AAC/C,eAAO,MAAM,qBAAqB,mBAAmB,CAAC;AA6GtD;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CAepD;AAiND,wBAAgB,KAAK,IAAI,eAAe,CAAC,OAAO,CAAC,CAqFhD"}
+{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../src/agents/codex.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAyCH,OAAO,EAAE,KAAK,cAAc,EAAqB,MAAM,uBAAuB,CAAC;AAG/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE/D,OAAO,EACL,KAAK,uBAAuB,EAE7B,MAAM,oBAAoB,CAAC;AAE5B,eAAO,MAAM,kBAAkB,eAAe,CAAC;AAC/C,eAAO,MAAM,qBAAqB,mBAAmB,CAAC;AA6GtD;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CAepD;AAiND,wBAAgB,KAAK,IAAI,eAAe,CAAC,OAAO,EAAE,uBAAuB,CAAC,CAsFzE"}

package/dist/agents/codex.js

@@ -21,6 +21,7 @@ import { parseCooldownHint } from "../kernel/classify.js";
 import { defineCliAgent } from "../kernel/cli-agent.js";
 import { cliLoginCommand } from "../kernel/cli-login.js";
 import { SANDBOX_MODE } from "../kernel/options.js";
+import { codexSessions, } from "./codex-session.js";
 export const CODEX_HOME_ENV_VAR = "CODEX_HOME";
 export const CODEX_API_KEY_ENV_VAR = "OPENAI_API_KEY";
 const CODEX = {
@@ -298,7 +299,7 @@ function codexLogin(args) {
     });
 }
 export function codex() {
-    return defineCliAgent({
+    const definition = defineCliAgent({
         id: CODEX.id,
         command: CODEX.command,
         args: {
@@ -374,4 +375,5 @@ export function codex() {
             remove: removeCodexMcp,
         },
     });
+    return { ...definition, session: codexSessions() };
 }

package/dist/codex/app-server.d.ts

@@ -1,4 +1,15 @@
-import type { Clock, Exec } from "../core/ports.js";
+/**
+ * Codex app-server client over stdio JSON-RPC. One client is one child
+ * process, held as long as the caller wants: host-plane calls create one
+ * per call (`withCodexAppServer`), a Session keeps one for the thread's
+ * whole life. Both directions are modeled — client requests get typed,
+ * decoded results; server notifications and server-initiated requests
+ * (approval prompts) arrive on `incoming`, and `respond` answers the latter.
+ * A request timeout fails that request only; it never kills the process,
+ * because a Session's other traffic shares it.
+ */
+import { type UnknownRecord } from "../core/json.js";
+import type { Clock, Exec, ExecExit } from "../core/ports.js";
 import type { CodexAppServerMethods, CodexMcpServerStatus } from "./protocol.js";
 /**
  * How the client identifies itself to the codex app-server `initialize`
@@ -20,8 +31,46 @@ export type CodexAppServerOptions = {
     readonly requestTimeoutMs?: number;
     readonly clientInfo?: AppServerClientInfo;
 };
+export declare const CODEX_INCOMING_KIND: {
+    readonly notification: "notification";
+    readonly request: "request";
+};
+/** JSON-RPC ids the server chooses for its own requests. */
+export type CodexServerRequestId = number | string;
+/** What the server sends on its own: notifications, or requests it awaits an answer to. */
+export type CodexIncoming = {
+    readonly kind: typeof CODEX_INCOMING_KIND.notification;
+    readonly method: string;
+    readonly params: UnknownRecord | null;
+} | {
+    readonly kind: typeof CODEX_INCOMING_KIND.request;
+    readonly id: CodexServerRequestId;
+    readonly method: string;
+    readonly params: UnknownRecord | null;
+};
+export type CodexServerRequestAnswer = {
+    readonly result: unknown;
+} | {
+    readonly error: {
+        readonly code: number;
+        readonly message: string;
+    };
+};
 export interface CodexAppServer {
     request<M extends keyof CodexAppServerMethods>(method: M, params: CodexAppServerMethods[M]["params"]): Promise<CodexAppServerMethods[M]["result"]>;
+    /**
+     * Server-originated traffic in arrival order. Each iteration is its own
+     * subscription that starts at the moment of subscribing; nothing is
+     * buffered for consumers that never subscribe.
+     */
+    readonly incoming: AsyncIterable<CodexIncoming>;
+    /** Answer a server-initiated request by its id. */
+    respond(id: CodexServerRequestId, answer: CodexServerRequestAnswer): void;
+    /** Resolves when the child has exited (after `close()`, or on its own). */
+    readonly exit: Promise<ExecExit>;
+    /** The last ~2 KB of the server's stderr, for failure evidence. */
+    readonly stderrTail: string;
+    /** End stdin (the server exits on EOF), escalate to SIGTERM then SIGKILL after graces, wait for exit. */
     close(): Promise<void>;
 }
 export declare function createCodexAppServer(options: CodexAppServerOptions): CodexAppServer;

package/dist/codex/app-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-server.d.ts","sourceRoot":"","sources":["../../src/codex/app-server.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAA0B,MAAM,kBAAkB,CAAC;AAG5E,OAAO,KAAK,EACV,qBAAqB,EACrB,oBAAoB,EAErB,MAAM,eAAe,CAAC;AAOvB;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,UAAU,CAAC,EAAE,mBAAmB,CAAC;CAC3C,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,CAAC,SAAS,MAAM,qBAAqB,EAC3C,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GACzC,OAAO,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAwED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CAEhB;AAED,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,OAAO,EAAE,qBAAqB,EAC9B,IAAI,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,GAC3C,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,wBAAsB,6BAA6B,CACjD,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAgBjC"}
+{"version":3,"file":"app-server.d.ts","sourceRoot":"","sources":["../../src/codex/app-server.ts"],"names":[],"mappings":"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"}