@particle-academy/prism-acp 0.4.1 → 0.5.0

package/dist/codex/rate-limit.d.ts

@@ -0,0 +1,32 @@
+/** Codex's percentage-based rate-limit window. */
+export interface CodexRateLimitWindow {
+    readonly usedPercent: number;
+    readonly windowDurationMins: number;
+    /** Epoch milliseconds, converted from Codex's epoch-second `resetsAt`. */
+    readonly resetsAtMs: number;
+}
+export interface CodexRateLimit {
+    readonly ordinaryUsageAllowed: boolean | null;
+    readonly planType?: string;
+    readonly primary: CodexRateLimitWindow | null;
+    readonly secondary: CodexRateLimitWindow | null;
+    readonly credits?: {
+        readonly hasCredits: boolean;
+        readonly unlimited: boolean;
+        readonly balance: number | null;
+    };
+    readonly spendControlReached?: boolean | null;
+    readonly rateLimitReachedType?: string | null;
+    readonly availableResetCredits?: number;
+}
+export type CodexRateLimitRead = {
+    readonly ok: true;
+    readonly limit: CodexRateLimit;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** Read the allow-listed rate-limit fields; identifiers and unknown fields never pass through. */
+export declare function readCodexRateLimit(value: unknown): CodexRateLimitRead;
+export declare function parseCodexRateLimit(value: unknown): CodexRateLimit | undefined;
+export declare function codexRateLimitNotice(limit: CodexRateLimit): string;

package/dist/codex/rate-limit.js

@@ -0,0 +1,129 @@
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function describe(value) {
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'undefined';
+    if (typeof value === 'string')
+        return `string(${value.length})`;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (Array.isArray(value))
+        return `array(${value.length})`;
+    return typeof value === 'object' ? 'object' : typeof value;
+}
+function refuse(path, expected, got) {
+    return { ok: false, reason: `codex_rate_limit: ${path} expected ${expected}, got ${describe(got)}` };
+}
+function finite(value, min) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= min;
+}
+function readWindow(value, path) {
+    if (value === null)
+        return null;
+    if (!isObject(value))
+        return refuse(path, 'an object or null', value);
+    if (!finite(value.usedPercent, 0)) {
+        return refuse(`${path}.usedPercent`, 'finite number >= 0', value.usedPercent);
+    }
+    const windowDurationMins = value.windowDurationMins;
+    if (typeof windowDurationMins !== 'number' || !Number.isSafeInteger(windowDurationMins) || windowDurationMins < 1) {
+        return refuse(`${path}.windowDurationMins`, 'safe integer >= 1', value.windowDurationMins);
+    }
+    if (!finite(value.resetsAt, Number.MIN_VALUE)) {
+        return refuse(`${path}.resetsAt`, 'finite number > 0 (epoch seconds)', value.resetsAt);
+    }
+    const resetsAtMs = value.resetsAt * 1000;
+    if (!Number.isFinite(resetsAtMs) || resetsAtMs > 8.64e15) {
+        return refuse(`${path}.resetsAt`, 'valid epoch seconds representable as a JavaScript date', value.resetsAt);
+    }
+    return {
+        usedPercent: value.usedPercent,
+        windowDurationMins,
+        resetsAtMs,
+    };
+}
+/** Read the allow-listed rate-limit fields; identifiers and unknown fields never pass through. */
+export function readCodexRateLimit(value) {
+    if (!isObject(value))
+        return refuse('payload', 'an object', value);
+    const outer = value;
+    const rates = isObject(value.rateLimits) ? value.rateLimits : value;
+    const ordinaryUsageAllowed = outer.ordinaryUsageAllowed ?? rates.ordinaryUsageAllowed ?? null;
+    if (ordinaryUsageAllowed !== null && typeof ordinaryUsageAllowed !== 'boolean') {
+        return refuse('ordinaryUsageAllowed', 'boolean or null', ordinaryUsageAllowed);
+    }
+    const primary = readWindow(rates.primary, 'rateLimits.primary');
+    if (primary !== null && 'ok' in primary && primary.ok === false)
+        return primary;
+    const secondary = readWindow(rates.secondary, 'rateLimits.secondary');
+    if (secondary !== null && 'ok' in secondary && secondary.ok === false)
+        return secondary;
+    let credits;
+    if (rates.credits !== undefined && rates.credits !== null) {
+        if (!isObject(rates.credits))
+            return refuse('rateLimits.credits', 'an object or null', rates.credits);
+        const { hasCredits, unlimited, balance } = rates.credits;
+        if (typeof hasCredits !== 'boolean') {
+            return refuse('rateLimits.credits.hasCredits', 'boolean', hasCredits);
+        }
+        if (typeof unlimited !== 'boolean') {
+            return refuse('rateLimits.credits.unlimited', 'boolean', unlimited);
+        }
+        if (balance !== undefined && balance !== null && !finite(balance, 0)) {
+            return refuse('rateLimits.credits.balance', 'finite number >= 0 or null', balance);
+        }
+        credits = { hasCredits, unlimited, balance: typeof balance === 'number' ? balance : null };
+    }
+    if (rates.planType !== undefined && typeof rates.planType !== 'string') {
+        return refuse('rateLimits.planType', 'string', rates.planType);
+    }
+    const planType = typeof rates.planType === 'string' ? rates.planType : undefined;
+    if (rates.spendControlReached !== undefined &&
+        rates.spendControlReached !== null &&
+        typeof rates.spendControlReached !== 'boolean') {
+        return refuse('rateLimits.spendControlReached', 'boolean or null', rates.spendControlReached);
+    }
+    const spendControlReached = typeof rates.spendControlReached === 'boolean' || rates.spendControlReached === null
+        ? rates.spendControlReached
+        : undefined;
+    if (rates.rateLimitReachedType !== undefined &&
+        rates.rateLimitReachedType !== null &&
+        typeof rates.rateLimitReachedType !== 'string') {
+        return refuse('rateLimits.rateLimitReachedType', 'string or null', rates.rateLimitReachedType);
+    }
+    const rateLimitReachedType = typeof rates.rateLimitReachedType === 'string' || rates.rateLimitReachedType === null
+        ? rates.rateLimitReachedType
+        : undefined;
+    const resetCredits = isObject(outer.rateLimitResetCredits)
+        ? outer.rateLimitResetCredits.availableCount
+        : undefined;
+    if (resetCredits !== undefined && (!Number.isSafeInteger(resetCredits) || resetCredits < 0)) {
+        return refuse('rateLimitResetCredits.availableCount', 'integer >= 0', resetCredits);
+    }
+    return {
+        ok: true,
+        limit: {
+            ordinaryUsageAllowed: ordinaryUsageAllowed,
+            ...(planType === undefined ? {} : { planType }),
+            primary: primary,
+            secondary: secondary,
+            ...(credits === undefined ? {} : { credits }),
+            ...(spendControlReached === undefined ? {} : { spendControlReached }),
+            ...(rateLimitReachedType === undefined ? {} : { rateLimitReachedType }),
+            ...(resetCredits === undefined ? {} : { availableResetCredits: resetCredits }),
+        },
+    };
+}
+export function parseCodexRateLimit(value) {
+    const result = readCodexRateLimit(value);
+    return result.ok ? result.limit : undefined;
+}
+export function codexRateLimitNotice(limit) {
+    const window = limit.primary;
+    if (window === null)
+        return 'Codex rate limit usage is unavailable.';
+    return `Codex rate limit: ${window.usedPercent}% used in ${window.windowDurationMins} minutes, resets ${new Date(window.resetsAtMs).toISOString()}.`;
+}

package/dist/codex/transport.d.ts

@@ -0,0 +1,24 @@
+export interface CodexTransportHandlers {
+    readonly onFrame: (frame: unknown) => void;
+    readonly onStderr: (line: string) => void;
+    readonly onProblem: (problem: string) => void;
+    readonly onExit: (code: number | null, signal: NodeJS.Signals | null) => void;
+}
+export interface CodexTransport {
+    start(): Promise<void>;
+    send(frame: unknown): void;
+    close(signal?: NodeJS.Signals): void;
+}
+export interface CodexTransportOptions {
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string>>;
+    readonly binary?: string;
+}
+/** Run App Server over its measured, newline-framed stdio JSON-RPC channel. */
+export declare class StdioCodexTransport implements CodexTransport {
+    #private;
+    constructor(options: CodexTransportOptions, handlers: CodexTransportHandlers);
+    start(): Promise<void>;
+    send(frame: unknown): void;
+    close(signal?: NodeJS.Signals): void;
+}

package/dist/codex/transport.js

@@ -0,0 +1,90 @@
+import { spawn } from 'node:child_process';
+import { NdjsonFramer, encodeLine } from '../ndjson.js';
+/** Run App Server over its measured, newline-framed stdio JSON-RPC channel. */
+export class StdioCodexTransport {
+    #options;
+    #handlers;
+    #framer = new NdjsonFramer();
+    #child = null;
+    #stderrBuffer = '';
+    #closed = false;
+    #stderrOverflowReported = false;
+    constructor(options, handlers) {
+        this.#options = options;
+        this.#handlers = handlers;
+    }
+    async start() {
+        if (this.#child !== null)
+            throw new Error('Codex transport already started');
+        const major = Number(process.versions.node.split('.')[0]);
+        if (!Number.isInteger(major) || major < 22) {
+            throw new Error('Codex app-server stdio transport requires Node.js 22 or newer');
+        }
+        const child = spawn(this.#options.binary ?? 'codex', ['app-server', '--listen', 'stdio://'], {
+            cwd: this.#options.cwd,
+            env: { ...this.#options.env },
+            shell: process.platform === 'win32',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        this.#child = child;
+        child.stdout?.on('data', (chunk) => {
+            for (const frame of this.#framer.push(chunk)) {
+                if (frame.ok)
+                    this.#handlers.onFrame(frame.value);
+                else
+                    this.#handlers.onProblem(frame.error.message);
+            }
+        });
+        child.stderr?.setEncoding('utf8');
+        child.stderr?.on('data', (chunk) => this.#onStderr(chunk));
+        child.on('error', (cause) => this.#handlers.onProblem(`failed to spawn Codex (${cause.name})`));
+        child.on('close', (code, signal) => {
+            this.#closed = true;
+            for (const frame of this.#framer.end()) {
+                if (frame.ok)
+                    this.#handlers.onFrame(frame.value);
+                else
+                    this.#handlers.onProblem(frame.error.message);
+            }
+            this.#handlers.onExit(code, signal);
+        });
+        await new Promise((resolve, reject) => {
+            child.once('spawn', resolve);
+            child.once('error', (cause) => reject(new Error(`Codex app-server spawn failed (${cause.name})`)));
+        });
+    }
+    send(frame) {
+        const stdin = this.#child?.stdin;
+        if (stdin === null || stdin === undefined || stdin.destroyed || this.#closed) {
+            throw new Error('Codex app-server stdin is not open');
+        }
+        stdin.write(encodeLine(frame));
+    }
+    close(signal = 'SIGTERM') {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#child?.stdin?.end();
+        this.#child?.kill(signal);
+    }
+    #onStderr(chunk) {
+        this.#stderrBuffer += chunk;
+        if (this.#stderrBuffer.length > 64_000) {
+            if (!this.#stderrOverflowReported) {
+                this.#stderrOverflowReported = true;
+                this.#handlers.onProblem('Codex stderr buffer exceeded 64000 characters');
+            }
+            this.#stderrBuffer = this.#stderrBuffer.slice(-64_000);
+        }
+        let newline;
+        while ((newline = this.#stderrBuffer.indexOf('\n')) !== -1) {
+            const line = this.#stderrBuffer.slice(0, newline).replace(/\r$/, '');
+            this.#stderrBuffer = this.#stderrBuffer.slice(newline + 1);
+            if (line.length > 0) {
+                // App Server stderr is not a public logging surface: provider output
+                // can contain account and rate-limit identifiers.
+                this.#handlers.onStderr(`Codex stderr line withheld (${line.length} characters)`);
+            }
+        }
+    }
+}

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { BASE_ALLOW, OUTRANKING_CREDENTIALS, childEnv } from './env.js';
 export type { ChildEnvOptions, ChildEnvResult } from './env.js';
 export { JsonRpcPeer, RPC_INTERNAL_ERROR, RPC_INVALID_PARAMS, RPC_INVALID_REQUEST, RPC_METHOD_NOT_FOUND, RPC_PARSE_ERROR, RpcError, } from './jsonrpc.js';
 export type { JsonRpcPeerOptions, NotificationHandler, RequestHandler, RpcId, } from './jsonrpc.js';
-export { META_CLI_SESSION_ID, META_NS, META_RATE_LIMIT, META_THINKING_SIGNATURE, META_THINKING_TOKENS_ESTIMATE, META_UNMAPPED_FRAME, RESERVED_META_KEYS, metaKey, withMeta, } from './meta.js';
+export { META_CLI_SESSION_ID, META_EXEC_POLICY_AMENDMENT, META_NS, META_RATE_LIMIT, META_THINKING_SIGNATURE, META_THINKING_TOKENS_ESTIMATE, META_UNMAPPED_FRAME, RESERVED_META_KEYS, metaKey, withMeta, } from './meta.js';
 export { ClaudeToAcp } from './claude/to-acp.js';
 export type { AcpUpdate, ToolStatus } from './claude/to-acp.js';
 export { parseRateLimit, rateLimitNotice, readRateLimit } from './claude/rate-limit.js';
@@ -12,10 +12,14 @@ export type { ClaudeRateLimit, ClaudeRateLimitWindow, RateLimitRead } from './cl
 export { ClaudeDriver, claudeArgs, promptLine, updatesFromFrames } from './claude/driver.js';
 export type { ClaudeDriverEvents, ClaudeDriverOptions, ClaudePermissionMode, } from './claude/driver.js';
 export { AcpAgent, PROTOCOL_VERSION } from './acp/agent.js';
-export type { AcpAgentOptions, AgentDriver, DriverEvents, DriverFactory, SessionProbe as AcpSessionProbe, } from './acp/agent.js';
+export type { AcpAgentOptions, AgentDriver, DriverEvents, DriverFactory, PermissionOutcome, PermissionRequest, SessionProbe as AcpSessionProbe, } from './acp/agent.js';
 export { probeSessionStore } from './claude/session-store.js';
 export type { SessionExistence, SessionProbe, SessionStoreOptions } from './claude/session-store.js';
 export { serve } from './acp/stdio.js';
 export type { Served, ServeOptions } from './acp/stdio.js';
 export { cliSessionIdOf, turnOutcomeOf } from './claude/driver.js';
 export type { StopReason, TurnOutcome } from './claude/driver.js';
+export { CodexDriver } from './codex/driver.js';
+export type { CodexDriverOptions, CodexTransportFactory } from './codex/driver.js';
+export { codexRateLimitNotice, parseCodexRateLimit, readCodexRateLimit } from './codex/rate-limit.js';
+export type { CodexRateLimit, CodexRateLimitRead, CodexRateLimitWindow } from './codex/rate-limit.js';

package/dist/index.js

@@ -1,7 +1,7 @@
 export { MAX_LINE_BYTES, NdjsonFramer, encodeLine, parseLine } from './ndjson.js';
 export { BASE_ALLOW, OUTRANKING_CREDENTIALS, childEnv } from './env.js';
 export { JsonRpcPeer, RPC_INTERNAL_ERROR, RPC_INVALID_PARAMS, RPC_INVALID_REQUEST, RPC_METHOD_NOT_FOUND, RPC_PARSE_ERROR, RpcError, } from './jsonrpc.js';
-export { META_CLI_SESSION_ID, META_NS, META_RATE_LIMIT, META_THINKING_SIGNATURE, META_THINKING_TOKENS_ESTIMATE, META_UNMAPPED_FRAME, RESERVED_META_KEYS, metaKey, withMeta, } from './meta.js';
+export { META_CLI_SESSION_ID, META_EXEC_POLICY_AMENDMENT, META_NS, META_RATE_LIMIT, META_THINKING_SIGNATURE, META_THINKING_TOKENS_ESTIMATE, META_UNMAPPED_FRAME, RESERVED_META_KEYS, metaKey, withMeta, } from './meta.js';
 export { ClaudeToAcp } from './claude/to-acp.js';
 export { parseRateLimit, rateLimitNotice, readRateLimit } from './claude/rate-limit.js';
 export { ClaudeDriver, claudeArgs, promptLine, updatesFromFrames } from './claude/driver.js';
@@ -9,3 +9,5 @@ export { AcpAgent, PROTOCOL_VERSION } from './acp/agent.js';
 export { probeSessionStore } from './claude/session-store.js';
 export { serve } from './acp/stdio.js';
 export { cliSessionIdOf, turnOutcomeOf } from './claude/driver.js';
+export { CodexDriver } from './codex/driver.js';
+export { codexRateLimitNotice, parseCodexRateLimit, readCodexRateLimit } from './codex/rate-limit.js';

package/dist/meta.d.ts

@@ -69,15 +69,18 @@ export declare const META_THINKING_SIGNATURE: string;
 export declare const META_THINKING_TOKENS_ESTIMATE: string;
 /** Structured rate-limit detail, alongside the human-readable notice. */
 export declare const META_RATE_LIMIT: string;
+/** A command-line approval's persistent execpolicy amendment, tied to its ACP option. */
+export declare const META_EXEC_POLICY_AMENDMENT: string;
 /** The CLI frame a mapping could not place, kept so nothing is lost unseen. */
 export declare const META_UNMAPPED_FRAME: string;
 /**
- * The CLI's OWN session id -- the only string `session/load` can resume with.
+ * The provider's OWN session id -- the identity `session/load` can resume with.
  *
  * This exists because its absence was a hole in the middle of resume. ACP's
- * `sessionId` is minted by this server; the CLI has a different id of its own,
- * a UUID, and `--resume` wants that one. The two were kept correctly separate
- * inside the driver and then **never handed to the client**, so a client that
+ * `sessionId` is minted by this server; providers have their own identities
+ * (Claude's CLI accepts a UUID or title, while Codex uses its App Server thread
+ * id). The two were kept correctly separate inside the driver and then
+ * **never handed to the client**, so a client that
  * stored the id `session/new` returned and passed it back to `session/load`
  * was passing a string the CLI cannot resume.
  *

package/dist/meta.js

@@ -81,15 +81,18 @@ export const META_THINKING_SIGNATURE = metaKey('thinking_signature');
 export const META_THINKING_TOKENS_ESTIMATE = metaKey('thinking_tokens_estimate');
 /** Structured rate-limit detail, alongside the human-readable notice. */
 export const META_RATE_LIMIT = metaKey('rate_limit');
+/** A command-line approval's persistent execpolicy amendment, tied to its ACP option. */
+export const META_EXEC_POLICY_AMENDMENT = metaKey('execpolicy_amendment');
 /** The CLI frame a mapping could not place, kept so nothing is lost unseen. */
 export const META_UNMAPPED_FRAME = metaKey('unmapped_frame');
 /**
- * The CLI's OWN session id -- the only string `session/load` can resume with.
+ * The provider's OWN session id -- the identity `session/load` can resume with.
  *
  * This exists because its absence was a hole in the middle of resume. ACP's
- * `sessionId` is minted by this server; the CLI has a different id of its own,
- * a UUID, and `--resume` wants that one. The two were kept correctly separate
- * inside the driver and then **never handed to the client**, so a client that
+ * `sessionId` is minted by this server; providers have their own identities
+ * (Claude's CLI accepts a UUID or title, while Codex uses its App Server thread
+ * id). The two were kept correctly separate inside the driver and then
+ * **never handed to the client**, so a client that
  * stored the id `session/new` returned and passed it back to `session/load`
  * was passing a string the CLI cannot resume.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/prism-acp",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Speak the Agent Client Protocol to a coding-agent CLI the user has already authenticated. No API key, no third-party adapter.",
   "license": "MIT",
   "repository": {