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

package/dist/codex/app-server.js

@@ -1,8 +1,24 @@
+/**
+ * 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 { AsyncQueue } from "../core/async-queue.js";
 import { AGENT_ERROR_CODE, AgentError, NOT_AVAILABLE_CAUSE, TIMEOUT_KIND, } from "../core/error.js";
 import { readJsonRecord } from "../core/json.js";
 import { redactSecrets } from "../core/redact.js";
-import { OUTPUT_CHANNEL, PROCESS_SIGNAL } from "../core/values.js";
+import { endProcessGracefully } from "../core/process-close.js";
+import { OUTPUT_CHANNEL } from "../core/values.js";
 import { CODEX_APP_SERVER_METHOD, CODEX_APP_SERVER_RESULT_DECODERS, CODEX_MCP_STATUS_DETAIL, } from "./protocol.js";
+export const CODEX_INCOMING_KIND = {
+    notification: "notification",
+    request: "request",
+};
 const DEFAULT_CODEX_COMMAND = "codex";
 const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 const APP_SERVER_ARGS = ["app-server"];
@@ -14,7 +30,7 @@ const APP_SERVER_ARGS = ["app-server"];
 const DEFAULT_APP_SERVER_CLIENT_INFO = {
     name: "agents",
     title: "Agents",
-    version: "0.1.0",
+    version: "0.2.0",
 };
 const OUTPUT_TAIL_CHARS = 2_000;
 const MCP_PAGE_LIMIT = 500;
@@ -23,6 +39,7 @@ const JSON_RPC_FRAME_BOUNDARY = /\r?\n/u;
 const JSON_RPC_FIELD = {
     id: "id",
     method: "method",
+    params: "params",
     result: "result",
     error: "error",
     message: "message",
@@ -61,23 +78,65 @@ class ExecCodexAppServer {
     nextId = 1;
     stderr = "";
     stdoutLine = "";
+    /** Set by close(); no child is spawned after it. */
+    closing = false;
+    /** Set once every stream has ended (the child exited, or close() found none). */
+    closed = false;
     pending = new Map();
+    subscribers = new Set();
+    settleExit = () => { };
+    exit;
+    get stderrTail() {
+        return this.stderr;
+    }
     constructor(options) {
         this.options = options;
+        this.exit = new Promise((resolve) => {
+            this.settleExit = resolve;
+        });
+    }
+    get incoming() {
+        return {
+            [Symbol.asyncIterator]: () => {
+                const queue = new AsyncQueue();
+                if (this.closed) {
+                    queue.end();
+                }
+                else {
+                    this.subscribers.add(queue);
+                }
+                return queue[Symbol.asyncIterator]();
+            },
+        };
     }
     async request(method, params) {
         await this.connect();
         return this.sendRequest(method, params);
     }
+    respond(id, answer) {
+        const process = this.process;
+        if (process === null) {
+            // A request that arrives while the server is closing has nobody left
+            // to answer; dropping it is the only honest option.
+            return;
+        }
+        process.writeStdin(`${JSON.stringify({ id, ...answer })}${JSON_RPC_FRAME_SEPARATOR}`);
+    }
     async close() {
+        this.closing = true;
         const process = this.process;
         this.process = null;
         this.initialized = false;
-        if (process !== null) {
-            process.endStdin();
-            process.kill(PROCESS_SIGNAL.sigterm);
-        }
         this.rejectAll(appServerClosedError());
+        if (process === null) {
+            this.finish({ code: null, signal: null });
+            return;
+        }
+        // EOF is what makes the server exit cleanly — it removes the thread
+        // writer lock on the way out, which a SIGTERM-ed server leaves behind
+        // (T61 lab). Signals follow only for a server that does not exit on EOF.
+        await endProcessGracefully(process, this.options.clock);
+        await this.exit;
     }
     async connect() {
         if (this.initialized) {
@@ -103,7 +162,14 @@ class ExecCodexAppServer {
         this.initialized = true;
     }
     async startProcess() {
+        if (this.closing) {
+            throw appServerClosedError();
+        }
         const command = await this.options.exec.which(this.options.command, this.options.env);
+        if (this.closing) {
+            // close() ran while PATH was being resolved: spawning now would orphan a child.
+            throw appServerClosedError();
+        }
         if (command === null) {
             throw new AgentError({
                 code: AGENT_ERROR_CODE.notAvailable,
@@ -124,6 +190,7 @@ class ExecCodexAppServer {
         void this.readProcess(process);
     }
     async readProcess(process) {
+        let exit = { code: null, signal: null };
         try {
             for await (const chunk of process.chunks) {
                 if (chunk.channel === OUTPUT_CHANNEL.stderr) {
@@ -133,30 +200,57 @@ class ExecCodexAppServer {
                     this.handleStdout(chunk.text);
                 }
             }
-            const exit = await process.exit;
+            exit = await process.exit;
+            this.rejectAll(appServerExitedError(exit.code, this.stderr));
+        }
+        catch (error) {
+            this.rejectAll(appServerExitedError(null, error instanceof Error ? error.message : ""));
+        }
+        finally {
             if (this.process === process) {
                 this.process = null;
                 this.initialized = false;
             }
-            if (this.pending.size > 0) {
-                this.rejectAll(appServerExitedError(exit.code, this.stderr));
-            }
+            this.finish(exit);
         }
-        catch (error) {
-            this.rejectAll(appServerExitedError(null, error instanceof Error ? error.message : ""));
+    }
+    /** The child is gone (or was never started and we closed): end every stream once. */
+    finish(exit) {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        for (const queue of this.subscribers) {
+            queue.end();
         }
+        this.subscribers.clear();
+        this.settleExit(exit);
     }
     handleStdout(text) {
         this.stdoutLine += text;
         const lines = this.stdoutLine.split(JSON_RPC_FRAME_BOUNDARY);
         this.stdoutLine = lines.pop() ?? "";
         for (const line of lines) {
-            const response = parseResponseLine(line);
+            const record = readJsonRecord(line.trim());
+            if (record === null) {
+                continue;
+            }
+            const incoming = parseIncoming(record);
+            if (incoming !== null) {
+                this.publish(incoming);
+                continue;
+            }
+            const response = parseResponse(record);
             if (response !== null) {
                 this.handleResponse(response);
             }
         }
     }
+    publish(incoming) {
+        for (const queue of this.subscribers) {
+            queue.push(incoming);
+        }
+    }
     sendRequest(method, params) {
         const process = this.process;
         if (process === null) {
@@ -165,14 +259,11 @@ class ExecCodexAppServer {
         const id = this.nextId;
         this.nextId += 1;
         return new Promise((resolve, reject) => {
+            // A timeout fails only this request. JSON-RPC has no per-call
+            // cancellation, but a Session's other turns share this process, so the
+            // client never kills it on a slow answer; `close()` is the caller's call.
             const cancelTimeout = this.options.clock.setTimeout(() => {
                 this.pending.delete(id);
-                // A timeout kills the whole server, not just this request: JSON-RPC
-                // gives no per-call cancellation, and a hung app-server cannot be
-                // trusted with further requests. Other in-flight requests are then
-                // rejected as `failed` by the exit path; clients are created per
-                // host-plane call, so the blast radius is that one call.
-                process.kill(PROCESS_SIGNAL.sigkill);
                 reject(new AgentError({
                     code: AGENT_ERROR_CODE.timeout,
                     classification: AgentError.agentFailure(AGENT_ERROR_CODE.timeout),
@@ -249,17 +340,29 @@ function appendTail(current, next) {
         ? combined
         : combined.slice(-OUTPUT_TAIL_CHARS);
 }
-function parseResponseLine(line) {
-    const record = readJsonRecord(line.trim());
-    if (record === null) {
+/**
+ * Server-originated frames carry `method`; a response never does. Their id
+ * space is the server's own, so an id on such a frame marks a request the
+ * server awaits an answer to, not one of our pending requests.
+ */
+function parseIncoming(record) {
+    const method = record[JSON_RPC_FIELD.method];
+    if (typeof method !== "string") {
         return null;
     }
-    // Server-initiated requests and notifications carry `method`; a JSON-RPC
-    // response never does. Their id space is the server's own, so treating
-    // them as responses would resolve an unrelated pending client request.
-    if (record[JSON_RPC_FIELD.method] !== undefined) {
-        return null;
+    const paramsValue = record[JSON_RPC_FIELD.params];
+    const params = typeof paramsValue === "object" &&
+        paramsValue !== null &&
+        !Array.isArray(paramsValue)
+        ? paramsValue
+        : null;
+    const id = record[JSON_RPC_FIELD.id];
+    if (typeof id === "number" || typeof id === "string") {
+        return { kind: CODEX_INCOMING_KIND.request, id, method, params };
     }
+    return { kind: CODEX_INCOMING_KIND.notification, method, params };
+}
+function parseResponse(record) {
     const id = record[JSON_RPC_FIELD.id];
     if (typeof id !== "number") {
         return null;

package/dist/codex/index.d.ts

@@ -1,3 +1,4 @@
-export { type AppServerClientInfo, type CodexAppServer, type CodexAppServerOptions, createCodexAppServer, listAllCodexMcpServerStatuses, withCodexAppServer, } from "./app-server.js";
-export type { CodexAppServerMethods, CodexMcpServerStatus, CodexMcpServerStatusPage, CodexPluginInstallResult, CodexPluginListResult, CodexPluginMarketplace, CodexPluginSummary, CodexSkillListResult, } from "./protocol.js";
+export { type AppServerClientInfo, CODEX_INCOMING_KIND, type CodexAppServer, type CodexAppServerOptions, type CodexIncoming, type CodexServerRequestAnswer, type CodexServerRequestId, createCodexAppServer, listAllCodexMcpServerStatuses, withCodexAppServer, } from "./app-server.js";
+export { CODEX_APP_SERVER_INCOMING, CODEX_APP_SERVER_METHOD, CODEX_SANDBOX_MODE, encodeCodexThreadPermissions, } from "./protocol.js";
+export type { CodexAppServerMethods, CodexConfigOverrides, CodexSandboxMode, CodexThreadPermissionParams, CodexThreadPermissionWireParams, CodexThreadRef, CodexTurnRef, CodexUserInput, CodexWorkspaceWriteConfig, CodexMcpServerStatus, CodexMcpServerStatusPage, CodexPluginInstallResult, CodexPluginListResult, CodexPluginMarketplace, CodexPluginSummary, CodexSkillListResult, } from "./protocol.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/codex/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,oBAAoB,EACpB,6BAA6B,EAC7B,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,qBAAqB,EACrB,oBAAoB,EACpB,wBAAwB,EACxB,wBAAwB,EACxB,qBAAqB,EACrB,sBAAsB,EACtB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/codex/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,mBAAmB,EACxB,mBAAmB,EACnB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,oBAAoB,EACpB,6BAA6B,EAC7B,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACvB,kBAAkB,EAClB,4BAA4B,GAC7B,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,2BAA2B,EAC3B,+BAA+B,EAC/B,cAAc,EACd,YAAY,EACZ,cAAc,EACd,yBAAyB,EACzB,oBAAoB,EACpB,wBAAwB,EACxB,wBAAwB,EACxB,qBAAqB,EACrB,sBAAsB,EACtB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,eAAe,CAAC"}

package/dist/codex/index.js

@@ -1 +1,2 @@
-export { createCodexAppServer, listAllCodexMcpServerStatuses, withCodexAppServer, } from "./app-server.js";
+export { CODEX_INCOMING_KIND, createCodexAppServer, listAllCodexMcpServerStatuses, withCodexAppServer, } from "./app-server.js";
+export { CODEX_APP_SERVER_INCOMING, CODEX_APP_SERVER_METHOD, CODEX_SANDBOX_MODE, encodeCodexThreadPermissions, } from "./protocol.js";

package/dist/codex/protocol.d.ts

@@ -15,6 +15,65 @@ export declare const CODEX_APP_SERVER_METHOD: {
     readonly pluginInstall: "plugin/install";
     readonly skillsList: "skills/list";
     readonly mcpServerStatusList: "mcpServerStatus/list";
+    readonly threadStart: "thread/start";
+    readonly threadResume: "thread/resume";
+    readonly threadUnarchive: "thread/unarchive";
+    readonly turnStart: "turn/start";
+    readonly turnSteer: "turn/steer";
+    readonly turnInterrupt: "turn/interrupt";
+};
+/** Notifications and server-initiated requests the session adapter reads. */
+export declare const CODEX_APP_SERVER_INCOMING: {
+    readonly itemStarted: "item/started";
+    readonly itemCompleted: "item/completed";
+    readonly turnCompleted: "turn/completed";
+    readonly commandExecutionRequestApproval: "item/commandExecution/requestApproval";
+    readonly fileChangeRequestApproval: "item/fileChange/requestApproval";
+};
+/** `thread/start` / `thread/resume` sandbox words (codex 0.153.4 `SandboxMode`). */
+export declare const CODEX_SANDBOX_MODE: {
+    readonly readOnly: "read-only";
+    readonly workspaceWrite: "workspace-write";
+    readonly dangerFullAccess: "danger-full-access";
+};
+export type CodexSandboxMode = (typeof CODEX_SANDBOX_MODE)[keyof typeof CODEX_SANDBOX_MODE];
+/**
+ * `workspace-write` details travel as config.toml overrides on
+ * `thread/start` / `thread/resume` (`config`), the same keys
+ * `codex -c sandbox_workspace_write.*` takes.
+ */
+export type CodexWorkspaceWriteConfig = {
+    readonly writableRoots: readonly string[];
+    readonly networkAccess: boolean;
+    readonly excludeTmpdirEnvVar: boolean;
+    readonly excludeSlashTmp: boolean;
+};
+export type CodexThreadPermissionParams = {
+    readonly sandbox: CodexSandboxMode;
+    readonly approvalPolicy: string;
+    readonly approvalsReviewer: string;
+    readonly workspaceWrite: CodexWorkspaceWriteConfig | null;
+};
+type CodexConfigScalar = boolean | string | readonly string[];
+/** A `config.toml` override object as `thread/start` / `thread/resume` take it. */
+export type CodexConfigOverrides = Readonly<Record<string, Readonly<Record<string, CodexConfigScalar>>>>;
+/** The wire shape of the permission params (`config` carries workspace-write). */
+export type CodexThreadPermissionWireParams = {
+    readonly sandbox: CodexSandboxMode;
+    readonly approvalPolicy: string;
+    readonly approvalsReviewer: string;
+    readonly config: CodexConfigOverrides | null;
+};
+export declare function encodeCodexThreadPermissions(input: CodexThreadPermissionParams): CodexThreadPermissionWireParams;
+export type CodexThreadRef = {
+    readonly threadId: string;
+};
+export type CodexTurnRef = {
+    readonly turnId: string;
+};
+export type CodexUserInput = {
+    readonly type: "text";
+    readonly text: string;
 };
 export declare const CODEX_MCP_STATUS_DETAIL: {
     readonly toolsAndAuthOnly: "toolsAndAuthOnly";
@@ -116,9 +175,51 @@ export type CodexAppServerMethods = {
         };
         readonly result: CodexMcpServerStatusPage;
     };
+    [CODEX_APP_SERVER_METHOD.threadStart]: {
+        readonly params: {
+            readonly cwd: string;
+        } & CodexThreadPermissionWireParams;
+        readonly result: CodexThreadRef;
+    };
+    [CODEX_APP_SERVER_METHOD.threadResume]: {
+        readonly params: {
+            readonly threadId: string;
+            readonly excludeTurns: boolean;
+        } & CodexThreadPermissionWireParams;
+        readonly result: CodexThreadRef;
+    };
+    [CODEX_APP_SERVER_METHOD.threadUnarchive]: {
+        readonly params: {
+            readonly threadId: string;
+        };
+        readonly result: CodexThreadRef;
+    };
+    [CODEX_APP_SERVER_METHOD.turnStart]: {
+        readonly params: {
+            readonly threadId: string;
+            readonly input: readonly CodexUserInput[];
+        };
+        readonly result: CodexTurnRef;
+    };
+    [CODEX_APP_SERVER_METHOD.turnSteer]: {
+        readonly params: {
+            readonly threadId: string;
+            readonly expectedTurnId: string;
+            readonly input: readonly CodexUserInput[];
+        };
+        readonly result: CodexTurnRef;
+    };
+    [CODEX_APP_SERVER_METHOD.turnInterrupt]: {
+        readonly params: {
+            readonly threadId: string;
+            readonly turnId: string;
+        };
+        readonly result: Readonly<Record<string, never>>;
+    };
 };
 export type CodexAppServerResultDecoder<M extends keyof CodexAppServerMethods> = (value: unknown) => CodexAppServerMethods[M]["result"] | null;
 export declare const CODEX_APP_SERVER_RESULT_DECODERS: {
     readonly [M in keyof CodexAppServerMethods]: CodexAppServerResultDecoder<M>;
 };
+export {};
 //# sourceMappingURL=protocol.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/codex/protocol.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/codex/protocol.ts"],"names":[],"mappings":"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"}

package/dist/codex/protocol.js

@@ -16,7 +16,53 @@ export const CODEX_APP_SERVER_METHOD = {
     pluginInstall: "plugin/install",
     skillsList: "skills/list",
     mcpServerStatusList: "mcpServerStatus/list",
+    threadStart: "thread/start",
+    threadResume: "thread/resume",
+    threadUnarchive: "thread/unarchive",
+    turnStart: "turn/start",
+    turnSteer: "turn/steer",
+    turnInterrupt: "turn/interrupt",
 };
+/** Notifications and server-initiated requests the session adapter reads. */
+export const CODEX_APP_SERVER_INCOMING = {
+    itemStarted: "item/started",
+    itemCompleted: "item/completed",
+    turnCompleted: "turn/completed",
+    commandExecutionRequestApproval: "item/commandExecution/requestApproval",
+    fileChangeRequestApproval: "item/fileChange/requestApproval",
+};
+/** `thread/start` / `thread/resume` sandbox words (codex 0.153.4 `SandboxMode`). */
+export const CODEX_SANDBOX_MODE = {
+    readOnly: "read-only",
+    workspaceWrite: "workspace-write",
+    dangerFullAccess: "danger-full-access",
+};
+/** config.toml keys, spelled once (`codex -c sandbox_workspace_write.writable_roots=…`). */
+const CODEX_CONFIG_KEY = {
+    sandboxWorkspaceWrite: "sandbox_workspace_write",
+    writableRoots: "writable_roots",
+    networkAccess: "network_access",
+    excludeTmpdirEnvVar: "exclude_tmpdir_env_var",
+    excludeSlashTmp: "exclude_slash_tmp",
+};
+export function encodeCodexThreadPermissions(input) {
+    const workspaceWrite = input.workspaceWrite;
+    return {
+        sandbox: input.sandbox,
+        approvalPolicy: input.approvalPolicy,
+        approvalsReviewer: input.approvalsReviewer,
+        config: workspaceWrite === null
+            ? null
+            : {
+                [CODEX_CONFIG_KEY.sandboxWorkspaceWrite]: {
+                    [CODEX_CONFIG_KEY.writableRoots]: workspaceWrite.writableRoots,
+                    [CODEX_CONFIG_KEY.networkAccess]: workspaceWrite.networkAccess,
+                    [CODEX_CONFIG_KEY.excludeTmpdirEnvVar]: workspaceWrite.excludeTmpdirEnvVar,
+                    [CODEX_CONFIG_KEY.excludeSlashTmp]: workspaceWrite.excludeSlashTmp,
+                },
+            },
+    };
+}
 export const CODEX_MCP_STATUS_DETAIL = {
     toolsAndAuthOnly: "toolsAndAuthOnly",
 };
@@ -50,14 +96,46 @@ const RESULT_FIELD = {
     shortDescription: "shortDescription",
     skills: "skills",
     status: "status",
+    thread: "thread",
     tools: "tools",
+    turn: "turn",
+    turnId: "turnId",
 };
 export const CODEX_APP_SERVER_RESULT_DECODERS = {
     [CODEX_APP_SERVER_METHOD.pluginList]: decodePluginListResult,
     [CODEX_APP_SERVER_METHOD.pluginInstall]: decodePluginInstallResult,
     [CODEX_APP_SERVER_METHOD.skillsList]: decodeSkillListResult,
     [CODEX_APP_SERVER_METHOD.mcpServerStatusList]: decodeMcpServerStatusPage,
+    [CODEX_APP_SERVER_METHOD.threadStart]: decodeThreadRef,
+    [CODEX_APP_SERVER_METHOD.threadResume]: decodeThreadRef,
+    [CODEX_APP_SERVER_METHOD.threadUnarchive]: decodeThreadRef,
+    [CODEX_APP_SERVER_METHOD.turnStart]: decodeTurnRefFromTurn,
+    [CODEX_APP_SERVER_METHOD.turnSteer]: decodeTurnRef,
+    [CODEX_APP_SERVER_METHOD.turnInterrupt]: decodeEmptyResult,
 };
+/** `{thread: {id}}` — the rest of the thread object is not modeled here. */
+function decodeThreadRef(value) {
+    const record = readUnknownRecord(value);
+    const thread = record === null ? null : readUnknownRecord(record[RESULT_FIELD.thread]);
+    const threadId = thread === null ? null : readString(thread, RESULT_FIELD.id);
+    return threadId === null ? null : { threadId };
+}
+/** `turn/start` answers `{turn: {id, status, …}}`. */
+function decodeTurnRefFromTurn(value) {
+    const record = readUnknownRecord(value);
+    const turn = record === null ? null : readUnknownRecord(record[RESULT_FIELD.turn]);
+    const turnId = turn === null ? null : readString(turn, RESULT_FIELD.id);
+    return turnId === null ? null : { turnId };
+}
+/** `turn/steer` answers `{turnId}`. */
+function decodeTurnRef(value) {
+    const record = readUnknownRecord(value);
+    const turnId = record === null ? null : readString(record, RESULT_FIELD.turnId);
+    return turnId === null ? null : { turnId };
+}
+function decodeEmptyResult(value) {
+    return readUnknownRecord(value) === null ? null : {};
+}
 function decodeItems(values, decodeItem) {
     const items = [];
     for (const value of values) {

package/dist/core/process-close.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The one way a held child is ended: stdin EOF first (both hosts exit on
+ * it — and only that exit removes Codex's thread writer lock), SIGTERM
+ * after a grace for a child that is not reading stdin, SIGKILL after
+ * another for one that ignores both. Shared by the session child and the
+ * codex app-server client so the escalation exists once.
+ */
+import type { Clock, ExecExit, InteractiveExecProcess } from "./ports.js";
+export declare const CLOSE_GRACE_MS = 5000;
+export declare function endProcessGracefully(process: InteractiveExecProcess, clock: Clock): Promise<ExecExit>;
+//# sourceMappingURL=process-close.d.ts.map

package/dist/core/process-close.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-close.d.ts","sourceRoot":"","sources":["../../src/core/process-close.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAG1E,eAAO,MAAM,cAAc,OAAQ,CAAC;AAEpC,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,sBAAsB,EAC/B,KAAK,EAAE,KAAK,GACX,OAAO,CAAC,QAAQ,CAAC,CAoBnB"}

package/dist/core/process-close.js

@@ -0,0 +1,27 @@
+/**
+ * The one way a held child is ended: stdin EOF first (both hosts exit on
+ * it — and only that exit removes Codex's thread writer lock), SIGTERM
+ * after a grace for a child that is not reading stdin, SIGKILL after
+ * another for one that ignores both. Shared by the session child and the
+ * codex app-server client so the escalation exists once.
+ */
+import { PROCESS_SIGNAL } from "./values.js";
+export const CLOSE_GRACE_MS = 5_000;
+export async function endProcessGracefully(process, clock) {
+    process.endStdin();
+    const cancels = [];
+    cancels.push(clock.setTimeout(() => {
+        process.kill(PROCESS_SIGNAL.sigterm);
+        cancels.push(clock.setTimeout(() => {
+            process.kill(PROCESS_SIGNAL.sigkill);
+        }, CLOSE_GRACE_MS));
+    }, CLOSE_GRACE_MS));
+    try {
+        return await process.exit;
+    }
+    finally {
+        for (const cancel of cancels.splice(0)) {
+            cancel();
+        }
+    }
+}

package/dist/core/session.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Session-plane vocabulary: a Session is one long-lived host conversation
+ * (Claude `-p --input-format stream-json` process, Codex app-server thread)
+ * that the caller keeps open across turns. One turn is one `send()`; the
+ * host's own conversation id is the Session id. Outbound types follow
+ * absence rule 2: keys always present, `null` is meaningful absence.
+ */
+export declare const SESSION_EVENT_TYPE: {
+    readonly turnStarted: "turn_started";
+    readonly turnEnded: "turn_ended";
+    readonly message: "message";
+    readonly tool: "tool";
+    readonly approvalRequested: "approval_requested";
+    readonly exited: "exited";
+};
+export declare const TURN_OUTCOME: {
+    readonly completed: "completed";
+    readonly interrupted: "interrupted";
+    readonly failed: "failed";
+};
+export type TurnOutcome = (typeof TURN_OUTCOME)[keyof typeof TURN_OUTCOME];
+/** The neutral answer to a host approval request; hosts map it to their own words. */
+export declare const APPROVAL_DECISION: {
+    readonly accept: "accept";
+    readonly decline: "decline";
+};
+export type ApprovalDecision = (typeof APPROVAL_DECISION)[keyof typeof APPROVAL_DECISION];
+export type SessionEvent = {
+    type: typeof SESSION_EVENT_TYPE.turnStarted;
+    turnId: string;
+} | {
+    type: typeof SESSION_EVENT_TYPE.turnEnded;
+    turnId: string;
+    outcome: TurnOutcome;
+} | {
+    type: typeof SESSION_EVENT_TYPE.message;
+    text: string;
+} | {
+    type: typeof SESSION_EVENT_TYPE.tool;
+    name: string;
+} | {
+    type: typeof SESSION_EVENT_TYPE.approvalRequested;
+    requestId: string;
+    /** Host-provided one-line description (command, tool name, reason). */
+    summary: string;
+    /** Decisions the host will accept for this request. */
+    decisions: readonly ApprovalDecision[];
+} | {
+    type: typeof SESSION_EVENT_TYPE.exited;
+    code: number | null;
+    signal: string | null;
+};
+export type TurnResult = {
+    turnId: string;
+    outcome: TurnOutcome;
+    /** The host's final answer text for the turn ("" when it produced none). */
+    text: string;
+};
+export declare const SESSION_OWNER_KIND: {
+    readonly none: "none";
+    readonly process: "process";
+};
+/**
+ * Who holds the conversation right now, as far as the host's own files say.
+ * Claude records `{pid, entrypoint}` in its session registry; Codex only
+ * leaves a writer lock, so `pid` is `null` there.
+ */
+export type SessionOwner = {
+    kind: typeof SESSION_OWNER_KIND.none;
+} | {
+    kind: typeof SESSION_OWNER_KIND.process;
+    pid: number | null;
+    entrypoint: string | null;
+};
+export type SessionFacts<Permissions> = {
+    /** The working directory the conversation was recorded in. */
+    workspace: string;
+    /** The permissions the last turn ran with; `null` when unreadable. */
+    lastPermissions: Permissions | null;
+    owner: SessionOwner;
+    /** Codex moves archived rollouts aside; resume unarchives first. */
+    archived: boolean;
+};
+export interface Session {
+    /** The host's own conversation id (Claude session_id / Codex thread id). */
+    readonly id: string;
+    /** Live events; a late subscriber receives the retained replay window. */
+    readonly events: AsyncIterable<SessionEvent>;
+    /** Start one turn as the user; resolves when the host ends the turn. */
+    send(text: string): Promise<TurnResult>;
+    /** Add to the running turn (Codex `turn/steer`; Claude absorbs it at the next tool boundary). */
+    steer(text: string): Promise<void>;
+    /** Stop the running turn; the turn ends with outcome `interrupted`. */
+    interrupt(): Promise<void>;
+    /** Answer an `approval_requested` event. */
+    respond(requestId: string, decision: ApprovalDecision): Promise<void>;
+    /** Release the conversation: close stdin, wait for exit (escalating to signals). */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/core/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/core/session.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,kBAAkB;;;;;;;CAOrB,CAAC;AAEX,eAAO,MAAM,YAAY;;;;CAIf,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE3E,sFAAsF;AACtF,eAAO,MAAM,iBAAiB;;;CAGpB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAC1B,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC;AAE7D,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,OAAO,kBAAkB,CAAC,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC/D;IACE,IAAI,EAAE,OAAO,kBAAkB,CAAC,SAAS,CAAC;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,WAAW,CAAC;CACtB,GACD;IAAE,IAAI,EAAE,OAAO,kBAAkB,CAAC,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,OAAO,kBAAkB,CAAC,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACtD;IACE,IAAI,EAAE,OAAO,kBAAkB,CAAC,iBAAiB,CAAC;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACxC,GACD;IACE,IAAI,EAAE,OAAO,kBAAkB,CAAC,MAAM,CAAC;IACvC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEN,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,WAAW,CAAC;IACrB,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,eAAO,MAAM,kBAAkB;;;CAGrB,CAAC;AAEX;;;;GAIG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,OAAO,kBAAkB,CAAC,IAAI,CAAA;CAAE,GACxC;IACE,IAAI,EAAE,OAAO,kBAAkB,CAAC,OAAO,CAAC;IACxC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AAEN,MAAM,MAAM,YAAY,CAAC,WAAW,IAAI;IACtC,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,eAAe,EAAE,WAAW,GAAG,IAAI,CAAC;IACpC,KAAK,EAAE,YAAY,CAAC;IACpB,oEAAoE;IACpE,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,MAAM,WAAW,OAAO;IACtB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IAC7C,wEAAwE;IACxE,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACxC,iGAAiG;IACjG,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,uEAAuE;IACvE,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,4CAA4C;IAC5C,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,oFAAoF;IACpF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}