@particle-academy/prism-acp 0.4.1 → 0.5.1

package/README.md

@@ -20,12 +20,13 @@ API key to supply and no adapter program to install.
 ## Status
 
 Early, but a client can talk to it. `initialize`, `session/new`,
-`session/load`, `session/prompt` and `session/cancel` work over a pipe, driving
-the Claude CLI, proven end to end against an authenticated binary. The mapping
-is tested against **captured traffic** rather than a hand-written fixture.
+`session/load`, `session/prompt` and `session/cancel` work over a pipe. Claude
+has been proven end to end against an authenticated binary; Codex is driven
+through its App Server and tested against a fake transport, with the wire
+shapes measured against captured traffic.
 
-Missing: `session/set_mode`, the client-side `fs/*` and `terminal/*` calls an
-agent can make back, and the Codex driver. The surface will change.
+Missing: `session/set_mode` and the client-side `fs/*` and `terminal/*` calls an
+agent can make back. The surface will change.
 
 | piece | state |
 |---|---|
@@ -38,7 +39,7 @@ agent can make back, and the Codex driver. The surface will change.
 | ACP server surface + stdio | built |
 | `session/load` resume | built, and **proven** to remember the first turn |
 | `session/set_mode`, `fs/*`, `terminal/*` | not yet |
-| Codex driver (`app-server`) | not yet |
+| Codex App Server driver | built; paged history and permission requests |
 
 **It maps 7 of ACP's 19 `session/update` kinds**, and that number is asserted by
 a test rather than described here, so raising it means moving it. The twelve it
@@ -91,6 +92,12 @@ in the direction that spends money silently. Names are compared
 case-insensitively, because Windows environment names are case-insensitive and
 `anthropic_api_key` reaches a child exactly as the uppercase spelling does.
 
+The allow-list withholds every variable not named in it, credentials and
+non-credentials alike. If the child needs an orchestrator session or terminal
+id, a callback URL, or a feature flag, name it in `allowEnv` or it will not
+arrive. This failure is silent: the child can start and appear healthy while
+being unable to identify itself, rather than reporting a missing variable.
+
 Nothing here mutates `process.env`. A workspace may hold an API key on purpose —
 other consumers beside this one legitimately bill per token — so the child's
 environment is constructed and the ambient one is left alone.
@@ -115,9 +122,10 @@ implementations of one protocol disagree without anyone noticing. So:
 which id to pass.
 
 **ACP's `sessionId` is not resumable.** `session/new` returns an id this server
-minted; the CLI has its own session id, a UUID, and `claude --resume` accepts
-only that one (or a session title). The two are deliberately separate, and the
-CLI's is published on the **first** `session/update` of every session:
+minted; providers resume with their own session identity. Claude accepts its
+CLI session id (a UUID or session title) through `claude --resume`; Codex uses
+its App Server thread id. The provider's id is published on the **first**
+`session/update` of every session:
 
 ```ts
 import { META_CLI_SESSION_ID } from '@particle-academy/prism-acp';
@@ -142,9 +150,16 @@ but by then `session/load` has already returned `{}` and you believe you have a
 resumed session.
 
 A session whose agent has **exited** is loadable; one whose agent is **still
-running** is refused, by either id. No history is replayed on load, because the
-CLI replays none -- `session/load` returning `{}` with no `session/update`
-notifications is the honest report of that, not an omission.
+running** is refused, by either id.
+
+History on load depends on the provider. **Claude replays none**: its CLI emits
+no transcript on resume, so returning `{}` with no `session/update` is the
+honest report. **Codex does replay history**: the driver resumes with
+`excludeTurns: true`, then fetches turns and items through the paged App Server
+methods and sends them as ACP updates. This deliberately differs between the
+drivers because their measured resume behavior differs. Codex thread ids are
+the provider's own captured ids and are the same ids accepted by its resume
+method; ACP-minted ids are refused.
 
 ### Refusing an unknown id at load, not a turn later
 
@@ -190,9 +205,19 @@ const probeSession = (sessionId: string) => probeSessionStore(sessionId, { env:
 ```
 
 `probeSession` is yours to supply because the answer belongs to the agent being
-driven, not to ACP: `probeSessionStore` reads claude's session store, and a Codex
-driver would resolve the same question through `thread/resume`. Omit it and
-`session/load` behaves as it always did.
+driven, not to ACP: `probeSessionStore` reads Claude's session store. Codex
+checks its identity by resuming the captured id through `thread/resume`; omit
+`probeSession` when using Codex.
+
+## Codex permissions
+
+Codex App Server approvals become ACP `session/request_permission` requests.
+The driver offers the decisions Codex sent, including the persistent
+execpolicy-amendment choice; its argv is kept on that option under
+`particle.academy/execpolicy_amendment` so a client can preserve the distinction
+between one-time approval and a remembered command. Human decisions have no
+default timeout. Cancelling a session, disconnecting the ACP client, or shutting
+down the driver answers any outstanding Codex approval with `cancel`.
 
 ## Rate limits are a gauge, not just a breach event
 
@@ -252,6 +277,16 @@ parse and not an interface: an interface over `unknown` is a cast, so a renamed
 provider field would still read as `undefined`, and a gauge renders `undefined`
 as empty. An empty headroom gauge is read by a human as plenty of headroom.
 
+Codex has a separate `CodexRateLimit` parser because App Server windows report
+`usedPercent` and `windowDurationMins`; Claude's
+`ClaudeRateLimit` uses fractional `utilization` and named windows. Both convert
+the provider's epoch-second reset timestamp to `resetsAtMs`. Do not feed one
+provider's payload to the other's parser.
+
+Both parsers accept usage beyond the allowance (`usedPercent` above 100 or
+`utilization` above 1) without capping it. Overage is real state, and capping
+would invent a reading; clamp only the rendered bar, not the reported value.
+
 ## Using it
 
 ```ts

package/dist/acp/agent.d.ts

@@ -37,16 +37,29 @@ export interface AgentDriver {
 }
 export interface DriverEvents {
     readonly onUpdate?: (update: AcpUpdate) => void;
+    /** Ask the ACP client to decide a Codex permission request. */
+    readonly onRequestPermission?: (request: PermissionRequest) => Promise<PermissionOutcome>;
     readonly onTurnEnd?: (outcome: TurnOutcome) => void;
     readonly onProtocolError?: (problem: string) => void;
     readonly onStderr?: (line: string) => void;
     readonly onExit?: (code: number | null, signal: NodeJS.Signals | null) => void;
 }
+export interface PermissionRequest {
+    readonly toolCall: Record<string, unknown>;
+    readonly options: readonly Record<string, unknown>[];
+    readonly _meta?: Readonly<Record<string, unknown>>;
+}
+export type PermissionOutcome = {
+    readonly outcome: 'selected';
+    readonly optionId: string;
+} | {
+    readonly outcome: 'cancelled';
+};
 /**
  * Builds a driver for one session.
  *
- * Injected rather than hardcoded because this surface is meant to front more
- * than one CLI -- Codex's `app-server` is the next one -- and because a server
+ * Injected rather than hardcoded because this surface fronts more than one
+ * CLI, including Codex's `app-server`, and because a server
  * that could only be tested by spawning a real agent would have its session
  * bookkeeping covered by nothing.
  */
@@ -60,8 +73,8 @@ export type DriverFactory = (options: {
  * Injected, and for two reasons. Tests must not read the developer's real
  * session store; and the answer is a property of the AGENT being driven, not of
  * ACP -- a Codex driver resolves it through `thread/resume`, not through
- * claude's `~/.claude/projects` layout. Omit it and `session/load` behaves as it
- * did before: it accepts the id and the agent reports the problem later.
+ * claude's `~/.claude/projects` layout. The store helper is Claude-specific;
+ * Codex users should omit it and let the driver check the App Server identity.
  */
 export type SessionProbe = (sessionId: string) => {
     readonly existence: 'present' | 'absent' | 'indeterminate';

package/dist/acp/agent.js

@@ -146,11 +146,11 @@ export class AcpAgent {
                 throw new RpcError(RPC_INVALID_PARAMS, `session ${sessionId} is already open as ${session.id} and its agent is still running`);
             }
         }
-        // REFUSE an id this server minted, because `--resume` provably cannot take
-        // it: `session/new` returns an id of OUR making, the CLI has its own UUID,
-        // and only the CLI's works. A client that stored the id it was handed and
-        // passed it back here was the obvious thing to do and could never have
-        // worked.
+        // REFUSE an id this server minted, because the provider's resume mechanism
+        // cannot take it: `session/new` returns an id of OUR making, while the
+        // driver resumes with the provider's own captured id. A client that stored
+        // the id it was handed and passed it back here was the obvious thing to do
+        // and could never have worked.
         //
         // Refused HERE rather than left to the CLI, even though the CLI does error
         // on it (verified: "is not a UUID and does not match any session title",
@@ -172,7 +172,7 @@ export class AcpAgent {
         // CLI session title by inspection. That residue is exactly why the CLI's
         // own id is published in `_meta` rather than left to be guessed at.
         if (MINTED_SESSION_ID.test(sessionId) || this.#minted.has(sessionId)) {
-            throw new RpcError(RPC_INVALID_PARAMS, `${sessionId} is an ACP session id minted by this server, which 'claude --resume' cannot accept. ` +
+            throw new RpcError(RPC_INVALID_PARAMS, `${sessionId} is an ACP session id minted by this server and cannot be resumed by the provider. ` +
                 `Resume with the CLI's own session id, sent as '${META_CLI_SESSION_ID}' in the _meta of the first ` +
                 `session/update of the original session.`);
         }
@@ -195,9 +195,9 @@ export class AcpAgent {
         }
         this.#open(sessionId, cwd, sessionId);
         // The spec's result is an empty object; history arrives as session/update
-        // notifications. We send none, because the CLI replays nothing on --resume
-        // -- claiming otherwise by returning early would be a silent lie about what
-        // a client is about to receive.
+        // notifications. Whether the driver replays transcript history is
+        // provider-specific: Claude replays none; Codex replays through its paged
+        // App Server endpoints.
         return {};
     }
     #open(id, cwd, resumeSessionId) {
@@ -212,6 +212,14 @@ export class AcpAgent {
             onUpdate: (update) => {
                 this.#peer.notify('session/update', { sessionId: id, update });
             },
+            onRequestPermission: async (request) => {
+                const result = await this.#peer.request('session/request_permission', {
+                    sessionId: id,
+                    ...request,
+                });
+                const outcome = asObject(result)?.outcome;
+                return isPermissionOutcome(outcome) ? outcome : { outcome: 'cancelled' };
+            },
             onTurnEnd: (outcome) => {
                 const turn = session.turn;
                 session.turn = null;
@@ -341,6 +349,12 @@ function asObject(value) {
 function asString(value) {
     return typeof value === 'string' ? value : undefined;
 }
+function isPermissionOutcome(value) {
+    const outcome = asObject(value);
+    if (outcome?.outcome === 'cancelled')
+        return true;
+    return outcome?.outcome === 'selected' && typeof outcome.optionId === 'string';
+}
 function messageOf(cause) {
     return cause instanceof Error ? cause.message : String(cause);
 }

package/dist/acp/stdio.js

@@ -11,23 +11,33 @@ export function serve(options) {
     });
     const agent = new AcpAgent(peer, options);
     const closed = new Promise((resolve) => {
+        let finished = false;
         options.input.on('data', (chunk) => {
             for (const frame of framer.push(chunk))
                 deliver(frame);
         });
-        options.input.on('end', () => {
+        const closeClient = (flush, reason) => {
+            if (finished)
+                return;
+            finished = true;
             // Flush before closing: a client can send its last message without a
             // trailing newline, and on this transport the last message is the one
             // that matters.
-            for (const frame of framer.end())
-                deliver(frame);
+            if (flush)
+                for (const frame of framer.end())
+                    deliver(frame);
             // Every session's child process outlives this stream unless it is told
             // otherwise. A server that exited without killing them would leave an
             // agent running with nobody listening.
             agent.closeAll();
-            peer.fail(new Error('client disconnected'));
+            peer.fail(new Error(reason));
             resolve();
-        });
+        };
+        options.input.on('end', () => closeClient(true, 'client disconnected'));
+        // Destroyed pipes may emit `close` without `end`. That is a disconnect too:
+        // pending provider approvals must be cancelled before their socket closes.
+        options.input.on('close', () => closeClient(false, 'client disconnected'));
+        options.input.on('error', () => closeClient(false, 'client input failed'));
     });
     function deliver(frame) {
         if (!frame.ok) {

package/dist/codex/driver.d.ts

@@ -0,0 +1,29 @@
+import type { AgentDriver, DriverEvents } from '../acp/agent.js';
+import { type CodexTransport, type CodexTransportHandlers, type CodexTransportOptions } from './transport.js';
+export interface CodexDriverOptions {
+    readonly cwd: string;
+    /** Trusted configuration; must not be built from untrusted input. */
+    readonly binary?: string;
+    readonly parentEnv?: Readonly<Record<string, string | undefined>>;
+    readonly allowEnv?: readonly string[];
+    readonly resumeSessionId?: string;
+    readonly turnInactivityTimeoutMs?: number;
+}
+export type CodexTransportFactory = (options: CodexTransportOptions, handlers: CodexTransportHandlers) => CodexTransport;
+/**
+ * Codex App Server driver. The App Server owns the durable thread identity;
+ * this driver only captures it from thread/start or thread/resume.
+ */
+export declare class CodexDriver implements AgentDriver {
+    #private;
+    withheldCredentials: readonly string[];
+    cliSessionId: string | null;
+    constructor(options: CodexDriverOptions, events?: DriverEvents, transportFactory?: CodexTransportFactory);
+    /** Resolves once initialize and thread start/resume have completed. */
+    get ready(): Promise<void>;
+    start(): void;
+    prompt(text: string): void;
+    /** App Server has no stdin close operation; the thread remains promptable. */
+    endInput(): void;
+    kill(signal?: NodeJS.Signals): void;
+}