@coda-console/codex 0.0.0-stage → 1.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 coda-console
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/agent/account-source.mjs

@@ -0,0 +1,71 @@
+// The account source another plugin plugs into Codex (the `account-source` extension point, docs/plugins.md「内置插件：Codex」):
+// its command, started once and asked over its standard input and output, one JSON object a line.
+//   → { "id": 1, "method": "selected" }                       ← { "id": 1, "result": { "account": { "id", "name" } | null } }
+//   → { "id": 2, "method": "tokens", "params": { "account", "refresh"? } } ← { "id": 2, "result": { "accessToken", "chatgptAccountId", "chatgptPlanType" } }
+// `refresh: true` asks the owner to renew a rejected access token, even before its expiry.
+// Either may answer `{ "id", "error": { "message" } }`. A source taking full ownership reports an error until an account
+// is chosen; a legacy source's `null` leaves the underlying login as it is. A source that ends is started again when asked.
+// An installed source owns the account panel and handles `--login` for Codex's existing login entry.
+import { spawn } from 'node:child_process';
+import { dirname } from 'node:path';
+import { readLines } from './lines.mjs';
+
+// What Coda hands this plugin's processes of the plugins plugged into its points (CODA_PLUGIN_EXTENSIONS): the first source.
+export function accountSource(env = process.env) {
+  let points; try { points = JSON.parse(env.CODA_PLUGIN_EXTENSIONS || '{}'); } catch { return null; }
+  return points?.['account-source']?.[0] ?? null;
+}
+
+export function sourceEnv(source, env = process.env) {
+  return { ...env, CODA_PLUGIN_PATH: source.path, ...(source.state ? { CODA_PLUGIN_STATE: source.state } : {}),
+    CODA_PLUGIN_DEPENDENCIES: JSON.stringify({ codex: env.CODA_PLUGIN_PATH }),
+    PATH: [dirname(process.execPath), env.PATH].filter(Boolean).join(':') };
+}
+
+export class AccountSource {
+  constructor(source, { env = process.env, timeoutMs = 10_000 } = {}) {
+    this.source = source; this.env = env; this.timeoutMs = timeoutMs; this.next = 0; this.pending = new Map(); this.child = null; this.closed = false;
+  }
+  start() {
+    const { command } = this.source;
+    // As a panel's command is run (docs/plugins.md「面板」): its plugin's directory and state, and this Node first on the PATH.
+    const child = spawn('/bin/sh', ['-c', command], { env: sourceEnv(this.source, this.env),
+      stdio: ['pipe', 'pipe', 'ignore'] });
+    child.stdin.on('error', () => {});
+    readLines(child.stdout).on('line', line => {
+      let message; try { message = JSON.parse(line); } catch { return; }
+      const waiter = this.pending.get(message?.id);
+      if (!waiter) return;
+      this.pending.delete(message.id); clearTimeout(waiter.timer);
+      if (message.error) waiter.reject(new Error(typeof message.error.message === 'string' && message.error.message.trim() ? message.error.message.trim().slice(0, 200) : '账号来源拒绝了请求'));
+      else waiter.resolve(message.result ?? {});
+    });
+    const ended = () => {
+      if (this.child === child) this.child = null;
+      for (const [id, waiter] of this.pending) if (waiter.child === child) { clearTimeout(waiter.timer); this.pending.delete(id); waiter.reject(new Error('账号来源提前退出了')); }
+    };
+    child.once('error', ended); child.once('exit', ended);
+    return child;
+  }
+  request(method, params) {
+    if (this.closed) return Promise.reject(new Error('账号来源已关闭'));
+    const child = this.child ??= this.start(), id = ++this.next;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { this.pending.delete(id); reject(new Error('账号来源没有答复')); }, this.timeoutMs);
+      this.pending.set(id, { resolve, reject, timer, child });
+      child.stdin.write(`${JSON.stringify({ id, method, ...(params ? { params } : {}) })}\n`);
+    });
+  }
+  async selected() {
+    const { account } = await this.request('selected');
+    if (account == null) return null;
+    if (typeof account?.id !== 'string' || !account.id) throw new Error('账号来源给的账号无效');
+    return { id: account.id, name: typeof account.name === 'string' && account.name ? account.name.slice(0, 80) : account.id };
+  }
+  async tokens(account, { refresh = false } = {}) {
+    const tokens = await this.request('tokens', { account, ...(refresh ? { refresh: true } : {}) });
+    if (typeof tokens.accessToken !== 'string' || typeof tokens.chatgptAccountId !== 'string') throw new Error('账号来源给的凭据不完整');
+    return { accessToken: tokens.accessToken, chatgptAccountId: tokens.chatgptAccountId, ...(typeof tokens.chatgptPlanType === 'string' ? { chatgptPlanType: tokens.chatgptPlanType } : {}) };
+  }
+  close() { this.closed = true; this.child?.kill(); }
+}

package/agent/accounts.mjs

@@ -0,0 +1,119 @@
+// The account bridge: what codex-acp runs as its Codex (`CODEX_PATH`, set by entry.mjs) when another plugin is plugged
+// into Codex's `account-source` point (account-source.mjs). Between codex-acp and the real app-server, it signs the
+// app-server in to the account the source has chosen, by handing it the source's tokens; they stay on this private pipe,
+// below ACP and the session's journal. Nothing chosen, Codex keeps this machine's own login.
+// The choice takes effect where nothing is under way: as a session starts and between turns (the native thread and turn
+// entry points ask the source each time). A turn whose account cannot be taken fails and says why, rather than going out
+// on the one before; one under way finishes on the account it began with.
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { AppServer } from '../scripts/app-server.mjs';
+import { AccountSource, accountSource } from './account-source.mjs';
+import { readLines } from './lines.mjs';
+
+class AccountError extends Error {}
+const failed = (account, error) => new AccountError(`没能换到所选的 Codex 账号${account ? ` ${account.name}` : ''}：${error?.message || '凭据不可用'}。去「资源」重新选择或登录`);
+
+export function startAccountBridge({ source = new AccountSource(accountSource()), makeServer = options => new AppServer(options), input = process.stdin,
+  output = value => process.stdout.write(`${JSON.stringify(value)}\n`) } = {}) {
+  let initialized = false, initializeId, applied = null, accountId = null, problem = null, queue = Promise.resolve(), closing = false;
+  const active = new Map(), starting = new Map();
+  const schedule = work => { const next = queue.then(work); queue = next.catch(() => {}); return next; };
+  async function login(tokens) {
+    await server.request('account/login/start', { type: 'chatgptAuthTokens', ...tokens });
+    const { account, workspaceRouting } = await server.request('account/read', { refreshToken: false });
+    if (account?.type !== 'chatgpt' || workspaceRouting?.chatgptAccountId !== tokens.chatgptAccountId) throw new Error('Codex 登录后的账号与所选的不符');
+  }
+  // Signs in to the chosen account when nothing is under way; with a turn under way, the next boundary does.
+  async function synchronize() {
+    if (!initialized || closing) return null;
+    let selected;
+    try { selected = await source.selected(); } catch (error) { problem = failed(null, error); throw problem; }
+    if (!selected || selected.id === applied?.id) { problem = null; return selected; }
+    if (active.size || starting.size) return selected;
+    try {
+      const tokens = await source.tokens(selected.id);
+      // Closed while they were read, the server is gone: a request made of it now would wait out its timeout for nobody.
+      if (closing) return selected;
+      // Once login begins a failed one means the actual account is unknown.
+      applied = null; accountId = null;
+      await login(tokens);
+      applied = selected; accountId = tokens.chatgptAccountId; problem = null;
+      return selected;
+    } catch (error) { problem = failed(selected, error); throw problem; }
+  }
+  const server = makeServer({ onMessage: message => {
+    // codex-acp 1.12 does not send an initialized notification. The successful
+    // initialize response is the boundary, before its first account/read.
+    if (!message.method && message.id === initializeId && !message.error) {
+      initialized = true; server.send({ method: 'initialized' });
+      void schedule(synchronize).catch(() => {});
+    }
+    if (message.method === 'account/chatgptAuthTokens/refresh' && message.id != null) {
+      // The source may have renewed the tokens since login. Never answer a request of account A with account B's.
+      const account = applied;
+      void (async () => {
+        try {
+          if (!account || (message.params?.previousAccountId && message.params.previousAccountId !== accountId)) throw new Error('当前没有 Coda 交给 Codex 的账号');
+          const tokens = await source.tokens(account.id, { refresh: true });
+          if (closing) return;
+          if (tokens.chatgptAccountId !== accountId) throw new Error('账号来源给的凭据属于另一个账号');
+          server.send({ id: message.id, result: tokens });
+        } catch (error) { if (!closing) server.send({ id: message.id, error: { code: -32000, message: failed(account, error).message } }); }
+      })(); return;
+    }
+    if (starting.has(message.id) && !message.method) {
+      const start = starting.get(message.id), turnId = message.result?.turn?.id;
+      starting.delete(message.id);
+      // Completion may overtake the request's response. Remember it only for
+      // outstanding starts, so late responses neither revive work nor grow a history.
+      if (!message.error && typeof turnId === 'string' && !start.completed.has(turnId)) {
+        if (!active.has(start.threadId)) active.set(start.threadId, turnId);
+      } else void schedule(synchronize).catch(() => {});
+    }
+    if (message.method === 'turn/started') active.set(message.params.threadId, message.params.turn.id);
+    if (message.method === 'turn/completed') {
+      const { threadId, turn } = message.params;
+      for (const start of starting.values()) if (start.threadId === threadId) start.completed.add(turn.id);
+      if (active.get(threadId) === turn.id) active.delete(threadId);
+      void schedule(synchronize).catch(() => {});
+    }
+    output(message);
+  } });
+  const reader = readLines(input);
+  reader.on('line', line => {
+    let message; try { message = JSON.parse(line); } catch { return; }
+    void schedule(async () => {
+      // A request that finds the bridge closed, or that it closes on, is neither sent on nor answered: its client is gone.
+      if (closing) return;
+      if (message.method === 'initialize') {
+        initializeId = message.id;
+        message.params.capabilities = { ...message.params.capabilities, experimentalApi: true };
+      }
+      if (message.method === 'initialized') return;
+      // Account reads during ACP startup and all native thread and turn entry points take the chosen account;
+      // one that could not be taken never sends on the one before.
+      if (['account/read', 'thread/start', 'thread/resume', 'thread/fork', 'turn/start'].includes(message.method)) {
+        const selected = await synchronize();
+        if (closing) return;
+        if (message.method === 'turn/start') {
+          if (selected && (problem || !applied || (applied.id !== selected.id && !active.size && !starting.size))) throw problem ?? failed(selected);
+          starting.set(message.id, { threadId: message.params.threadId, completed: new Set() });
+        }
+      }
+      // ACP's own login and logout would overwrite what the source gave, or this machine's login under it.
+      if (applied && ['account/login/start', 'account/logout'].includes(message.method)) throw new AccountError('Coda 正在为 Codex 选用账号，在「资源」里切换');
+      server.send(message);
+    }).catch(error => {
+      if (message.id != null) output({ id: message.id, error: { code: -32000, message: error instanceof AccountError ? error.message : failed(null, error).message } });
+    });
+  });
+  async function close() { if (closing) return; closing = true; reader.close(); source.close(); await server.close(); }
+  reader.on('close', () => void close());
+  void server.exited.then(() => reader.close());
+  return { close, server, settled: () => queue };
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const bridge = startAccountBridge();
+  for (const signal of ['SIGTERM', 'SIGINT']) process.on(signal, () => void bridge.close());
+}

package/agent/entry.mjs

@@ -0,0 +1,67 @@
+// The Codex agent as Coda starts it (the plugin's `contributes.agents`): the locked codex-acp, run in this process with Coda's
+// patches, which fail the start once the adapter changes. Between it and Coda the entry speaks Coda's protocol for it
+// (waits.mjs, docs/agent-protocol.md): its session instructions become the thread's developer instructions (instructions.mjs),
+// and a steer that finds no turn going is answered `promptRequired` (steering.mjs). What Coda wants of Codex beyond ACP is set
+// here: the mode a session starts in, and which Codex program runs, through the account bridge when another plugin chooses
+// the account (accounts.mjs).
+import { createRequire, registerHooks } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { accountSource } from './account-source.mjs';
+import { readLines } from './lines.mjs';
+import { orderedCodexTitles } from './titles.mjs';
+import { continuedCodexSubagents } from './subagents.mjs';
+import { followCodexProcessExit } from './process-exit.mjs';
+import { networkedCodexDevelopment } from './network.mjs';
+import { codexOptionsAsShown } from './options.mjs';
+import { instructedCodexThreads } from './instructions.mjs';
+import { promptRequiredCodexSteering } from './steering.mjs';
+import { input, listen, relayedCodexStreams } from './relay.mjs';
+import { CodexWaits } from './waits.mjs';
+import { explainCodexError, reportedCodexFailures } from './errors.mjs';
+
+const env = process.env;
+// A session starts read-only, unless its machine's configuration says otherwise.
+env.INITIAL_AGENT_MODE ??= 'read-only';
+// The Codex this session runs, as the handshake's `agentInfo` names it (Coda's protocol「Agent 版本」): the connection's own
+// program when it sets one, else the plugin's locked @openai/codex.
+const own = env.CODEX_PATH;
+function codexVersion() {
+  if (own) return /\d+\.\d+\.\d+[\w.+-]*/.exec(spawnSync(own, ['--version'], { encoding: 'utf8', timeout: 3000 }).stdout ?? '')?.[0] ?? null;
+  try { return JSON.parse(readFileSync(createRequire(import.meta.url).resolve('@openai/codex/package.json'), 'utf8')).version; } catch { return null; }
+}
+// Another plugin plugged into Codex's `account-source` point chooses the account (accounts.mjs): codex-acp then runs the
+// account bridge as its Codex, through a small program written into this plugin's state, named for what it runs. A Codex
+// program of the connection's own (`CODEX_PATH`) keeps its own login.
+if (!env.CODEX_PATH && accountSource(env) && env.CODA_PLUGIN_STATE) {
+  const quote = value => `'${value.replaceAll("'", "'\\''")}'`;
+  const program = `#!/bin/sh\nexec ${quote(process.execPath)} ${quote(fileURLToPath(new URL('./accounts.mjs', import.meta.url)))} "$@"\n`;
+  const shim = join(env.CODA_PLUGIN_STATE, `account-bridge-${createHash('sha256').update(program).digest('hex').slice(0, 12)}`);
+  if (!existsSync(shim)) { writeFileSync(`${shim}.${process.pid}`, program, { mode: 0o700 }); renameSync(`${shim}.${process.pid}`, shim); }
+  env.CODEX_PATH = shim;
+}
+
+const version = codexVersion();
+const waits = new CodexWaits({ agentInfo: version ? { name: 'codex', version } : null }), parse = line => { try { return JSON.parse(line); } catch { return null; } };
+const say = message => process.stdout.write(`${JSON.stringify(message)}\n`);
+listen(line => { for (const message of waits.fromAgent(parse(line))) say(explainCodexError(message)); });
+readLines(process.stdin).on('line', line => {
+  const message = parse(line);
+  if (!message || typeof message !== 'object') return;
+  const { agent, coda } = waits.fromCoda(message);
+  for (const each of agent) input.write(`${JSON.stringify(each)}\n`);
+  for (const each of coda) say(each);
+}).on('close', () => input.end());
+
+// codex-acp as Node finds it from here (its package names dist/index.js as its main): the plugin's own dependency.
+const adapter = new URL(import.meta.resolve('@agentclientprotocol/codex-acp'));
+registerHooks({ load(url, context, nextLoad) {
+  const loaded = nextLoad(url, context);
+  if (url !== adapter.href) return loaded;
+  return { ...loaded, source: reportedCodexFailures(codexOptionsAsShown(relayedCodexStreams(orderedCodexTitles(followCodexProcessExit(continuedCodexSubagents(
+    promptRequiredCodexSteering(instructedCodexThreads(networkedCodexDevelopment(Buffer.from(loaded.source).toString('utf8')))))))))) };
+} });
+await import(adapter.href);

package/agent/errors.mjs

@@ -0,0 +1,67 @@
+// codex-acp puts model-service errors in data.message, SDK-wrapped exceptions in data.details, and some configuration
+// errors in a string data payload. Explain them in ACP's standard message so clients need not know those private shapes.
+export function explainCodexError(message) {
+  if (!message || typeof message !== 'object' || !('id' in message) || 'method' in message) return message;
+  const error = message.error;
+  if (!error || typeof error.message !== 'string') return message;
+  const parts = [error.message];
+  for (const value of [error.data?.message, error.data?.details, error.data]) {
+    const detail = typeof value === 'string' ? value.trim() : '';
+    if (detail && !parts.some(part => part.includes(detail))) parts.push(detail);
+  }
+  return parts.length === 1 ? message : { ...message, error: { ...error, message: parts.join('\n\n') } };
+}
+
+// Native service facts, not a retry policy: Coda decides when/how often to try again. Explicit permanent kinds win over
+// generic messages (in particular, quota failures also arrive as JSON-RPC Internal error).
+export function codexFailureData(error, input) {
+  const data = error.data && typeof error.data === 'object' && !Array.isArray(error.data) ? error.data : {};
+  const info = data.codexErrorInfo;
+  const message = typeof data.message === 'string' ? data.message : typeof data.details === 'string' ? data.details : typeof error.data === 'string' ? error.data : error.message;
+  let provider; try { provider = JSON.parse(message); } catch {}
+  const status = provider?.status ?? (info && typeof info === 'object' ? Object.values(info)[0]?.httpStatusCode : null);
+  const permanent = ['usageLimitExceeded', 'unauthorized', 'contextWindowExceeded', 'sessionBudgetExceeded',
+    'cyberPolicy', 'misalignmentPolicyViolation', 'sandboxError', 'threadRollbackFailed'].includes(info) || [401, 403].includes(status);
+  const unavailableModel = provider?.type === 'error' && status === 400 && provider.error?.type === 'invalid_request_error' &&
+    /^model ['"][^'"\r\n]+['"] is not enabled in rustponsesapi\.?$/.test(provider.error.message ?? '');
+  const transport = info && typeof info === 'object' && ['httpConnectionFailed', 'responseStreamConnectionFailed',
+    'responseStreamDisconnected', 'responseTooManyFailedAttempts'].some(kind => kind in info);
+  const temporary = !permanent && (unavailableModel || (status >= 500 && status <= 599) ||
+    ['internalServerError', 'serverOverloaded'].includes(info) ||
+    (transport && (status == null || status >= 500)) ||
+    (info === 'other' && message === 'Selected model is at capacity. Please try a different model.') ||
+    (info == null && error.code === -32603 && message?.trim() === 'Internal error'));
+  if (!temporary) return data;
+  return { ...data, ...(data.message || data.details ? {} : { details: error.message }),
+    _meta: { ...data._meta, coda: { ...data._meta?.coda, failure: { kind: 'service_unavailable', input: data._meta?.coda?.failure?.input === 'accepted' ? 'accepted' : input } } } };
+}
+
+// codex-acp 1.12 only throws quota/auth failures for plain ACP clients; other failed native turns look successful.
+// Keep native failure data at the ACP boundary, even when the terminal notification has no preceding error event.
+export function reportedCodexFailures(source) {
+  const replacements = [
+    ['  async handleFailedTurn(turn) {\n    const activeFailure', `  async handleFailedTurn(turn) {
+    if (!this.supportsTypedSessionFailures && turn.status === "failed" && this.failure === null) {
+      this.failure = RequestError.internalError(this.createTurnErrorData(turn.error ?? {
+        message: "Turn failed", codexErrorInfo: null, additionalDetails: null
+      }));
+      return;
+    }
+    const activeFailure`],
+    ['    if (error51 === "usageLimitExceeded") {\n      this.failure = RequestError.internalError(',
+      '    if (!this.isAuthenticationRequiredError(error51)) {\n      this.failure = RequestError.internalError('],
+    ['    return createAgentTextMessageChunk(`${params.error.message}\n\n`);', '    return null;'],
+    ['    return data;\n  }\n  handleTokenUsageUpdated(params) {',
+      '    return codexFailureData({ code: -32603, message: error51.message, data }, "accepted");\n  }\n  handleTokenUsageUpdated(params) {'],
+    ['      throw err;\n    } finally {\n      promptNotificationsActive = false;', `      const codaData = codexFailureData(err, sessionState.currentTurnId === null ? "not_accepted" : "accepted");
+      if (codaData._meta?.coda?.failure) throw new RequestError(err.code ?? -32603, err.message, codaData);
+      throw err;
+    } finally {
+      promptNotificationsActive = false;`],
+  ];
+  for (const [before, after] of replacements) {
+    if (source.split(before).length !== 2) throw new Error('codex-acp error reporting patch no longer matches the locked adapter');
+    source = source.replace(before, after);
+  }
+  return `import { codexFailureData } from ${JSON.stringify(import.meta.url)};\n${source.replace(/^#![^\n]*\n/, '')}`;
+}

package/agent/instructions.mjs

@@ -0,0 +1,45 @@
+// Coda's session instructions (docs/agent-protocol.md「会话指令」) reach Codex as the thread's developer instructions, given on
+// `thread/start` and `thread/resume`. codex-acp reads `session/new` and `session/load` through ACP's schema, which drops
+// `systemPrompt`: the entry checks it and hands its text over in the request's `_meta` under INSTRUCTIONS (waits.mjs), which
+// the schema keeps, and the patched adapter passes that on. They are appended to the developer instructions Codex's own
+// configuration gives as seen from the session's directory (`config/read`), which the thread's would otherwise replace;
+// without them Codex is told nothing. A collaboration mode codex-acp sets carries instructions of its own mode
+// (`developer_instructions: null` is the mode's built-in ones), beside the thread's, not in place of them.
+export const INSTRUCTIONS = 'coda/sessionInstructions';
+
+// ACP's `systemPrompt`: its text, '' when there is none; throws on anything but text appended to the agent's own.
+export function sessionInstructions(systemPrompt) {
+  if (systemPrompt === undefined || systemPrompt === null) return '';
+  if (systemPrompt.mode !== 'append') throw new Error('会话指令只支持 append 模式');
+  const { content } = systemPrompt;
+  if (!Array.isArray(content) || content.some(block => block?.type !== 'text' || typeof block.text !== 'string')) throw new Error('会话指令只接受文本块');
+  return content.map(block => block.text).join('\n\n');
+}
+
+// The thread's developer instructions for a session request: its own configuration's, then Coda's.
+export async function codaDeveloperInstructions(codexClient, request) {
+  const ours = request._meta?.[INSTRUCTIONS];
+  if (!ours) return void 0;
+  const own = (await codexClient.configRead({ cwd: request.cwd, includeLayers: false }))?.config?.developer_instructions;
+  return own ? `${own}\n\n${ours}` : ours;
+}
+
+const given = ',\n      developerInstructions: await codaDeveloperInstructions(this.codexClient, request)';
+const patches = [
+  // newSession
+  [`      modelProvider: this.getModelProvider(),
+      cwd: request.cwd
+    });`, before => before.replace('\n    });', `${given}\n    });`), 1],
+  // loadSession and resumeSession
+  [`      modelProvider: await this.getResumeModelProvider(),
+      threadId: request.sessionId
+    });`, before => before.replace('\n    });', `${given}\n    });`), 2],
+];
+// Fails loudly once the locked adapter changes.
+export function instructedCodexThreads(source) {
+  for (const [before, after, count] of patches) {
+    if (source.split(before).length !== count + 1) throw new Error('codex-acp session instructions patch no longer matches the locked adapter');
+    source = source.replaceAll(before, after(before));
+  }
+  return `import { codaDeveloperInstructions } from ${JSON.stringify(import.meta.url)};\n${source.replace(/^#![^\n]*\n/, '')}`;
+}

package/agent/lines.mjs

@@ -0,0 +1,42 @@
+// A copy of Coda's backend/src/adapters/json-lines.mjs: an agent plugin's entry imports nothing of Coda's (docs/plugins.md「Agent」).
+// Reads newline-delimited JSON from a stream. Only \n ends a message: readline also
+// ends lines at a lone \r and at U+2028/U+2029, which JSON leaves unescaped inside
+// strings, so a tool output carrying them would split one message into pieces.
+import { EventEmitter } from 'node:events';
+import { StringDecoder } from 'node:string_decoder';
+
+// Emits 'line' for each message (a trailing \r is dropped) and 'close' once, when the
+// input ends or closes or close() is called. Only a clean end delivers an unterminated
+// last line; a destroyed input drops it. Input errors stay with the input's own handlers.
+export function readLines(input) {
+  const reader = new EventEmitter(), decoder = new StringDecoder('utf8');
+  // The unfinished message stays in pieces until its \n arrives: appending each chunk to one
+  // string and searching it would copy a large message over and over.
+  let pending = [], closed = false;
+  const emit = line => reader.emit('line', line.endsWith('\r') ? line.slice(0, -1) : line);
+  const take = text => {
+    let start = 0, end;
+    while (!closed && (end = text.indexOf('\n', start)) >= 0) {
+      pending.push(text.slice(start, end)); start = end + 1;
+      const line = pending.join(''); pending = [];
+      emit(line);
+    }
+    if (!closed && start < text.length) pending.push(text.slice(start));
+  };
+  const data = chunk => take(typeof chunk === 'string' ? chunk : decoder.write(chunk));
+  const finish = () => {
+    if (closed) return;
+    take(decoder.end());
+    if (pending.length && !closed) { const rest = pending.join(''); pending = []; emit(rest); }
+    reader.close();
+  };
+  reader.close = () => {
+    if (closed) return;
+    closed = true;
+    input.off('data', data); input.off('end', finish); input.off('close', reader.close);
+    input.pause?.();
+    reader.emit('close');
+  };
+  input.on('data', data); input.on('end', finish); input.on('close', reader.close);
+  return reader;
+}

package/agent/network.mjs

@@ -0,0 +1,25 @@
+// codex-acp 1.12.0 supplies its own sandbox policy on every turn, overriding CODEX_CONFIG's
+// sandbox_workspace_write.network_access. Coda's automatic development mode permits networking
+// inside workspace-write; filesystem escapes still use on-request and the native automatic reviewer.
+// The explicit ask-for-approval mode keeps its network boundary. Fail loudly on an adapter upgrade.
+const before = `  static Agent = new _AgentMode(
+    "agent",
+    "Approve for me",
+    "Only ask for actions detected as potentially unsafe",
+    "auto_review",
+    "on-request",
+    "auto_review",
+    {
+      type: "workspaceWrite",
+      writableRoots: [],
+      networkAccess: false,
+      excludeTmpdirEnvVar: false,
+      excludeSlashTmp: false
+    },
+    "workspace-write"
+  );`;
+
+export function networkedCodexDevelopment(source) {
+  if (source.split(before).length !== 2) throw new Error('codex-acp network policy patch no longer matches the locked adapter');
+  return source.replace(before, before.replace('networkAccess: false', 'networkAccess: true'));
+}

package/agent/options.mjs

@@ -0,0 +1,67 @@
+// Codex's speed is one ordinary ACP select option. The native model catalog decides which paid tiers are offered;
+// their IDs travel unchanged to turn/start. `fast` is Codex's config alias for the catalog/request ID `priority`.
+export const nativeServiceTier = tier => tier === 'fast' ? 'priority' : tier ?? 'default';
+export function codexSpeedOption(model, tier) {
+  const tiers = model?.serviceTiers ?? [];
+  if (!tiers.length) return null;
+  return { id: 'service-tier', name: '速度', description: '加速生成会增加用量', category: 'model_config', type: 'select',
+    currentValue: nativeServiceTier(tier), options: [
+      { value: 'default', name: '标准', description: '标准速度与用量' },
+      ...tiers.filter(t => t.id !== 'default').map(t => ({ value: t.id,
+        name: t.id === 'priority' ? '加速' : t.id === 'ultrafast' ? '超高速' : t.name, description: t.description })),
+    ] };
+}
+
+// Patch the locked codex-acp's session state, config options and outgoing turn together. No boolean conversion may
+// discard an Ultrafast (or future) tier when opening or restoring a session. A different model starts at its own default.
+// The collaboration mode (plan before changing) is not offered; its `/plan` command remains (#1069).
+export function codexOptionsAsShown(source) {
+  const patches = [
+    ['      createCollaborationModeConfigOption(sessionState.collaborationMode),\n', '', 1],
+    ['    const currentModelSupportsFast = modelSupportsFast(currentModel);\n', '', 2],
+    ['      fastModeEnabled: sessionMetadata.currentServiceTier === "fast",\n      currentModelSupportsFast,',
+      '      serviceTier: nativeServiceTier(sessionMetadata.currentServiceTier),', 2],
+    [`      case FAST_MODE_CONFIG_ID:
+        this.applyFastModeChange(sessionState, params);
+        break;`, `      case "service-tier": {
+        const model = this.findCurrentModel(sessionState.availableModels, sessionState.currentModelId);
+        const option = codexSpeedOption(model, sessionState.serviceTier);
+        if (!option?.options.some(choice => choice.value === params.value)) throw RequestError.invalidParams();
+        sessionState.serviceTier = params.value;
+        break;
+      }`, 1],
+    [`  applyFastModeChange(sessionState, params) {
+    const value = params.value;
+    if (typeof value === "boolean") {
+      sessionState.fastModeEnabled = value;
+      return;
+    }
+    if (value !== FAST_MODE_ON && value !== FAST_MODE_OFF) {
+      throw RequestError.invalidParams();
+    }
+    sessionState.fastModeEnabled = value === FAST_MODE_ON;
+  }
+`, '', 1],
+    ['  applyModelAndEffort(sessionState, model, effort) {', `  applyModelAndEffort(sessionState, model, effort) {
+    if (ModelId.fromString(sessionState.currentModelId).model !== model.model) {
+      sessionState.serviceTier = nativeServiceTier(model.defaultServiceTier);
+    }`, 1],
+    ['    sessionState.currentModelSupportsFast = modelSupportsFast(model);\n', '', 1],
+    [`    if (sessionState.currentModelSupportsFast) {
+      configOptions.push(createFastModeConfigOption(
+        sessionState.fastModeEnabled,
+        this.booleanConfigOptionsSupported
+      ));
+    }`, `    const speed = codexSpeedOption(currentModel, sessionState.serviceTier);
+    if (speed) configOptions.push(speed);`, 1],
+    [`      const serviceTier = resolveFastServiceTier(
+        sessionState.fastModeEnabled,
+        sessionState.currentModelSupportsFast
+      );`, '      const serviceTier = sessionState.serviceTier === "default" ? null : sessionState.serviceTier;', 1],
+  ];
+  for (const [before, after, count] of patches) {
+    if (source.split(before).length !== count + 1) throw new Error('codex-acp config option patch no longer matches the locked adapter');
+    source = source.replaceAll(before, after);
+  }
+  return `import { codexSpeedOption, nativeServiceTier } from ${JSON.stringify(import.meta.url)};\n${source.replace(/^#![^\n]*\n/, '')}`;
+}

package/agent/process-exit.mjs

@@ -0,0 +1,17 @@
+// codex-acp 1.12.0 outlives its Codex app-server. When that child exits on its own, the adapter only
+// fails background tasks: a started turn keeps waiting for a completion that never comes, and every
+// later request fails against the dead child. Follow the child out instead, so the session host reports
+// an agent exit and the backend settles the turn through its connection-lost path. A deliberate provider
+// restart moves the generation first, and stays unaffected. Fails loudly once the adapter changes.
+const before = `      if (generation !== this.codexProcessGeneration) return;
+      void this.finishAllAsyncTasks("failed", "after the Codex process exited");`;
+// Exit only after stdout has flushed the failed background tasks.
+const after = `      if (generation !== this.codexProcessGeneration) return;
+      void this.finishAllAsyncTasks("failed", "after the Codex process exited").finally(() => {
+        logger.log("Codex process exited; ending the adapter with it");
+        process.stdout.write("", () => process.exit(1));
+      });`;
+export function followCodexProcessExit(source) {
+  if (source.split(before).length !== 2) throw new Error('codex-acp process exit patch no longer matches the locked adapter');
+  return source.replace(before, after);
+}

package/agent/relay.mjs

@@ -0,0 +1,23 @@
+// codex-acp speaks ACP over these streams instead of standard input and output (`relayedCodexStreams`), so that the entry
+// stands between it and Coda without another process: what Coda says reaches it through `input`; what it says leaves
+// through `output`, a line at a time, to whoever `listen`s, in the order said.
+import { PassThrough, Writable } from 'node:stream';
+import { StringDecoder } from 'node:string_decoder';
+
+export const input = new PassThrough();
+let heard = () => {}, pending = '';
+const decoder = new StringDecoder('utf8');
+const take = text => {
+  pending += text;
+  for (let end; (end = pending.indexOf('\n')) >= 0;) { const line = pending.slice(0, end); pending = pending.slice(end + 1); heard(line); }
+};
+// Each line is passed on before the write is done: what codex-acp waits on having said has reached the listener.
+export const output = new Writable({ write(chunk, _, done) { take(decoder.write(chunk)); done(); }, final(done) { take(decoder.end()); done(); } });
+export const listen = listener => { heard = listener; };
+
+const before = '  const acpJsonStream = createJsonStream(process.stdin, process.stdout);';
+// Fails loudly once the locked adapter changes.
+export function relayedCodexStreams(source) {
+  if (source.split(before).length !== 2) throw new Error('codex-acp stream patch no longer matches the locked adapter');
+  return `import * as codaRelay from ${JSON.stringify(import.meta.url)};\n${source.replace(before, '  const acpJsonStream = createJsonStream(codaRelay.input, codaRelay.output);')}`;
+}

package/agent/steering.mjs

@@ -0,0 +1,32 @@
+// Coda's steering (docs/agent-protocol.md「插话」): codex-acp 1.12.0 declares `_session/steering` and, when no turn is going to
+// take the message in, starts a turn of its own with it. Coda asks with `_meta.steering.idleBehavior: "promptRequired"` to be
+// told so instead, and sends the message as the next prompt once the turn it meant to join has ended: then nothing is started
+// and the answer is `promptRequired`. Without that behaviour codex-acp's own way is kept. Fails loudly once the adapter changes.
+const patches = [
+  // codex-acp reads only the session and the prompt of the request: the behaviour asked for goes along.
+  [`    return {
+      sessionId,
+      prompt
+    };
+  }
+  createSessionConfigOptions(sessionState) {`, `    return {
+      sessionId,
+      prompt,
+      idleBehavior: params["_meta"]?.steering?.idleBehavior
+    };
+  }
+  createSessionConfigOptions(sessionState) {`],
+  // No live turn, or one that ended before the message was injected.
+  ['    return await this.startNewTurnFromSteering(params);\n', `    if (params.idleBehavior === "promptRequired") {
+      logger.log("Steering session found no running turn", { sessionId: params.sessionId });
+      return { outcome: "promptRequired", reason: "noRunningTurn" };
+    }
+    return await this.startNewTurnFromSteering(params);\n`],
+];
+export function promptRequiredCodexSteering(source) {
+  for (const [before, after] of patches) {
+    if (source.split(before).length !== 2) throw new Error('codex-acp steering patch no longer matches the locked adapter');
+    source = source.replace(before, after);
+  }
+  return source;
+}

package/agent/subagents.mjs

@@ -0,0 +1,16 @@
+// Patches to the locked codex-acp for native subagent sessions. Each fails loudly once the adapter changes.
+const patches = [
+  // Codex continues a finished subagent with `followup_task`, which starts a new turn in its thread. The adapter
+  // reopens a finished subagent only for `sendInput` and `resumeAgent`, so it drops everything that run does as
+  // updates for a terminal subagent. Reopen it when its thread actually starts a turn: a queued `send_message`
+  // reports the same "interacted" activity but runs nothing, and must not open a run nobody ends.
+  ['    if (notification.method === "turn/started") {\n', before => `${before}      const codaThreadId = notification.params.threadId;
+      if (codaThreadId !== this.rootSessionId && (this.children.get(codaThreadId)?.terminalState !== void 0 || this.terminalPendingSpawns.has(codaThreadId))) await this.reopen(codaThreadId);\n`],
+];
+export function continuedCodexSubagents(source) {
+  for (const [before, after] of patches) {
+    if (source.split(before).length !== 2) throw new Error('codex-acp subagent patch no longer matches the locked adapter');
+    source = source.replace(before, after(before));
+  }
+  return source;
+}

package/agent/titles.mjs

@@ -0,0 +1,49 @@
+// Title generation is advisory. Wait for its publication before completion, but
+// never let a stalled generator or a cancelled prompt hold the session open.
+export async function settleTitle(work, { signal, timeout = 15000 } = {}) {
+  if (signal?.aborted) return;
+  let timer, abort;
+  try {
+    await Promise.race([
+      Promise.resolve().then(work).catch(() => {}),
+      new Promise(resolve => {
+        timer = setTimeout(resolve, timeout);
+        abort = resolve;
+        signal?.addEventListener('abort', abort, { once: true });
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener('abort', abort);
+  }
+}
+
+// codex-acp 1.12.0 starts title generation without returning its promise. Keep
+// this compatibility patch scoped to the locked bundle; fail visibly if its
+// implementation changes, rather than silently restoring completion races.
+export function orderedCodexTitles(source) {
+  // Once execution has finished, stopping the advisory title wait must not
+  // turn the completed prompt or its file-change report into a cancellation.
+  const replacements = [
+    ['    let promptWasCancelled = false;',
+      '    let promptWasCancelled = false;\n    let codaExecutionCompleted = false;'],
+    ['      if (sessionState.titleGen) {\n        const promptText',
+      '      codaExecutionCompleted = true;\n      if (sessionState.titleGen) {\n        const promptText'],
+    ['        if (promptWasCancelled || activePrompt.signal.aborted || this.sessionIsClosing(params.sessionId)) {',
+      '        if (promptWasCancelled || (!codaExecutionCompleted && (activePrompt.signal.aborted || this.sessionIsClosing(params.sessionId)))) {'],
+    ['    this.generateAndPersist(userPromptText).catch(() => {',
+      '    return this.generateAndPersist(userPromptText).catch(() => {'],
+    ['        sessionState.titleGen.onTurnCompleted(promptText);',
+      `        await settleTitle(async () => {
+          await sessionState.titleGen.onTurnCompleted(promptText);
+          await this.codexAcpClient.waitForSessionNotifications(params.sessionId);
+        }, { signal: activePrompt.signal });`],
+    ['    sessionState.sessionTitle = title;\n    sessionState.sessionTitleSource = "fallback";',
+      '    title = Array.from(title.replace(/\\s+/g, " ").trim()).slice(0, 80).join("");\n    sessionState.sessionTitle = title;\n    sessionState.sessionTitleSource = "fallback";'],
+  ];
+  for (const [before, after] of replacements) {
+    if (source.split(before).length !== 2) throw new Error('codex-acp title ordering patch no longer matches the locked adapter');
+    source = source.replace(before, after);
+  }
+  return `import { settleTitle } from ${JSON.stringify(import.meta.url)};\n${source.replace(/^#![^\n]*\n/, '')}`;
+}

package/agent/waits.mjs

@@ -0,0 +1,105 @@
+// What codex-acp says of the work it has going beside a turn, in JetBrains AIR (its subagents and the commands it moved to
+// the background), said to Coda as waits of its own (docs/agent-protocol.md「_coda/wait」); and a stop Coda asks of one, asked
+// of codex-acp the AIR way. A continued subagent is another session to codex-acp (`X:generation:N`) and the same one to
+// Coda: every session it names to Coda is `X`, and each run of it a wait of its own. Coda's session instructions are checked
+// here and handed to the patched codex-acp in the request's `_meta` (instructions.mjs).
+import { INSTRUCTIONS, sessionInstructions } from './instructions.mjs';
+
+const record = value => value && typeof value === 'object' && !Array.isArray(value);
+const string = value => typeof value === 'string' && value.length > 0;
+const base = id => id.replace(/:generation:\d+$/, '');
+const SUBAGENT_END = { completed: 'done', failed: 'failed', cancelled: 'cancelled', disconnected: 'failed' };
+const TASK_END = { completed: 'done', failed: 'failed', stopped: 'cancelled' };
+const AIR = { version: 1, capabilities: ['nativeSubagentSessions', 'asyncTasks'] };
+
+export class CodexWaits {
+  // `agentInfo`: the Codex it runs, said in place of codex-acp's own name and version.
+  constructor({ agentInfo = null } = {}) {
+    // The root session; Coda's requests whose answers are read here, by id; the waits said, by id.
+    this.root = null; this.asked = new Map(); this.waits = new Map(); this.agentInfo = agentInfo;
+  }
+  // What Coda says: `agent`, what codex-acp is told; `coda`, what Coda is answered here.
+  fromCoda(message) {
+    if (message.method === 'initialize' && record(message.params)) {
+      this.asked.set(message.id, 'initialize');
+      // Without native subagent sessions codex-acp drops a delegated thread's own events and only reports start and end;
+      // without async tasks it does not say which commands it moved to the background.
+      const capabilities = record(message.params.clientCapabilities) ? message.params.clientCapabilities : {};
+      const meta = record(capabilities._meta) ? capabilities._meta : {};
+      message = { ...message, params: { ...message.params, clientCapabilities: { ...capabilities, _meta: { ...meta, jetbrains: { air: AIR } } } } };
+    } else if (message.method === '_coda/wait/stop' && 'id' in message) return this.stop(message);
+    if (['session/new', 'session/load'].includes(message.method) && record(message.params)) {
+      let instructions;
+      try { instructions = sessionInstructions(message.params.systemPrompt); }
+      catch (error) { return { agent: [], coda: [{ jsonrpc: '2.0', id: message.id, error: { code: -32602, message: error.message } }] }; }
+      const { systemPrompt, ...params } = message.params, meta = record(params._meta) ? params._meta : {};
+      message = { ...message, params: instructions ? { ...params, _meta: { ...meta, [INSTRUCTIONS]: instructions } } : params };
+    }
+    if (message.method === 'session/new') this.asked.set(message.id, 'session');
+    else if (message.method === 'session/load' && string(message.params?.sessionId)) this.root = message.params.sessionId;
+    return { agent: [message], coda: [] };
+  }
+  // A command is stopped through the session that keeps it, the root; a subagent by cancelling its session.
+  stop({ id, params }) {
+    const wait = this.waits.get(params?.waitId);
+    if (wait?.stoppable && wait.asyncTaskId) {
+      this.asked.set(id, 'stop');
+      return { agent: [{ jsonrpc: '2.0', id, method: '_session/async_task/stop', params: { sessionId: this.root, asyncTaskId: wait.asyncTaskId } }], coda: [] };
+    }
+    if (wait?.stoppable) return { agent: [{ jsonrpc: '2.0', method: 'session/cancel', params: { sessionId: wait.subagentSessionId } }], coda: [{ jsonrpc: '2.0', id, result: {} }] };
+    return { agent: [], coda: [{ jsonrpc: '2.0', id, error: { code: -32602, message: '没有可以停止的等待项' } }] };
+  }
+  // What codex-acp says, as said to Coda.
+  fromAgent(message) {
+    if (!record(message)) return [];
+    if ('id' in message && !('method' in message)) return [this.answer(message)];
+    if (record(message.params) && string(message.params.sessionId)) message = { ...message, params: { ...message.params, sessionId: base(message.params.sessionId) } };
+    if (message.method !== 'session/update' || !record(message.params?.update)) return [message];
+    const { sessionId, update: u } = message.params;
+    const said = params => [{ jsonrpc: '2.0', method: '_coda/wait', params: { sessionId, ...params } }];
+    switch (u.sessionUpdate) {
+      case 'subagent_spawned': {
+        if (!string(u.subagentSessionId)) return [];
+        const stoppable = u.capabilities?.cancel === true;
+        this.waits.set(u.subagentSessionId, { subagentSessionId: u.subagentSessionId, stoppable });
+        return said({ waitId: u.subagentSessionId, kind: 'subagent', state: 'waiting', title: cut(u.name, 500), detail: cut(u.task, 4000),
+          childSessionId: base(u.subagentSessionId), stoppable });
+      }
+      case 'subagent_state_update':
+        return string(u.subagentSessionId) && SUBAGENT_END[u.state] ? said({ waitId: u.subagentSessionId, state: SUBAGENT_END[u.state] }) : [];
+      case 'async_task_spawned': {
+        if (!string(u.asyncTaskId)) return [];
+        const stoppable = u.canStop === true;
+        this.waits.set(u.asyncTaskId, { asyncTaskId: u.asyncTaskId, stoppable });
+        return said({ waitId: u.asyncTaskId, kind: 'task', state: 'waiting', title: cut(u.name, 500), stoppable,
+          ...(string(u.toolCallId) ? { toolCallId: u.toolCallId } : {}) });
+      }
+      case 'async_task_state_update':
+        return string(u.asyncTaskId) && TASK_END[u.state] ? said({ waitId: u.asyncTaskId, state: TASK_END[u.state] }) : [];
+      case 'async_task_progress': return [];
+      case 'tool_call_update': {
+        // That a call's command went to the background is told by its wait.
+        if (!record(u._meta?.jetbrains?.air?.asyncTasks)) return [message];
+        const { asyncTasks, ...air } = u._meta.jetbrains.air;
+        return [{ ...message, params: { ...message.params, update: { ...u, _meta: { ...u._meta, jetbrains: { ...u._meta.jetbrains, air } } } } }];
+      }
+    }
+    return [message];
+  }
+  answer(message) {
+    const asked = this.asked.get(message.id);
+    if (!asked) return message;
+    this.asked.delete(message.id);
+    if (asked === 'stop') return { jsonrpc: '2.0', id: message.id, ...('error' in message ? { error: message.error } : { result: {} }) };
+    if (!record(message.result)) return message;
+    if (asked === 'session' && string(message.result.sessionId)) this.root = message.result.sessionId;
+    if (asked !== 'initialize') return message;
+    // It reports its waits and takes Coda's session instructions; codex-acp itself declares steering (`_meta.steering`).
+    const capabilities = record(message.result.agentCapabilities) ? message.result.agentCapabilities : {};
+    const meta = record(capabilities._meta) ? capabilities._meta : {};
+    const sessions = record(capabilities.sessionCapabilities) ? capabilities.sessionCapabilities : {};
+    return { ...message, result: { ...message.result, ...(this.agentInfo ? { agentInfo: this.agentInfo } : {}),
+      agentCapabilities: { ...capabilities, sessionCapabilities: { ...sessions, systemPrompt: {} }, _meta: { ...meta, coda: { waits: {} } } } } };
+  }
+}
+const cut = (value, limit) => typeof value === 'string' ? value.slice(0, limit) : undefined;

package/icons/README.md

@@ -0,0 +1,15 @@
+# Codex 品牌图形
+
+仅用于标识会话所用的服务，不作为 Coda 自身标志。商标归各自权利人所有。
+
+- `openai.svg`：取自 [OpenAI 品牌指南](https://openai.com/brand/) 展示的 [Blossom_Light.svg](https://images.ctfassets.net/kftzwdyauwt9/3hUGLn3ypllZ0oa01qOYVq/28e8188e6f11b84c3e876569d492734f/Blossom_Light.svg) 中的完整黑色 Blossom 路径。未包含指南的网格、尺寸辅助线和重复示例；保留路径几何。按产品约定用于 Codex。
+
+提取日期：2026-09-19。SVG 是可审阅的源文件，PDF 是由 CairoSVG 转换的等比矢量资源，清单的 `icon` 指向 PDF。重新生成 PDF（开发工具，不是构建或运行依赖）：
+
+```sh
+uv run --with cairosvg python - <<'PY'
+import cairosvg
+for name in ['openai']:
+    cairosvg.svg2pdf(url=f'{name}.svg', write_to=f'{name}.pdf')
+PY
+```

package/icons/openai.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="267.198" height="264.812" viewBox="146.694 227.042 267.198 264.812">
+<path fill="black" d="M249.176 323.434V298.276C249.176 296.158 249.971 294.569 251.825 293.509L302.406 264.381C309.29 260.409 317.5 258.555 325.973 258.555C357.75 258.555 377.877 283.185 377.877 309.399C377.877 311.253 377.877 313.371 377.611 315.49L325.178 284.771C322.001 282.919 318.822 282.919 315.645 284.771L249.176 323.434ZM367.283 421.415V361.301C367.283 357.592 365.694 354.945 362.516 353.092L296.048 314.43L317.763 301.982C319.617 300.925 321.206 300.925 323.058 301.982L373.639 331.112C388.205 339.586 398.003 357.592 398.003 375.069C398.003 395.195 386.087 413.733 367.283 421.412V421.415ZM233.553 368.452L211.838 355.742C209.986 354.684 209.19 353.095 209.19 350.975V292.718C209.19 264.383 230.905 242.932 260.301 242.932C271.423 242.932 281.748 246.641 290.49 253.26L238.321 283.449C235.146 285.303 233.555 287.951 233.555 291.659V368.455L233.553 368.452ZM280.292 395.462L249.176 377.985V340.913L280.292 323.436L311.407 340.913V377.985L280.292 395.462ZM300.286 475.968C289.163 475.968 278.837 472.259 270.097 465.64L322.264 435.449C325.441 433.597 327.03 430.949 327.03 427.239V350.445L349.011 363.155C350.865 364.213 351.66 365.802 351.66 367.922V426.179C351.66 454.514 329.679 475.965 300.286 475.965V475.968ZM237.525 416.915L186.944 387.785C172.378 379.31 162.582 361.305 162.582 343.827C162.582 323.436 174.763 305.164 193.563 297.485V357.861C193.563 361.571 195.154 364.217 198.33 366.071L264.535 404.467L242.82 416.915C240.967 417.972 239.377 417.972 237.525 416.915ZM234.614 460.343C204.689 460.343 182.71 437.833 182.71 410.028C182.71 407.91 182.976 405.792 183.238 403.672L235.405 433.863C238.582 435.715 241.763 435.715 244.938 433.863L311.407 395.466V420.622C311.407 422.742 310.612 424.331 308.758 425.389L258.179 454.519C251.293 458.491 243.083 460.343 234.611 460.343H234.614ZM300.286 491.854C332.329 491.854 359.073 469.082 365.167 438.892C394.825 431.211 413.892 403.406 413.892 375.073C413.892 356.535 405.948 338.529 391.648 325.552C392.972 319.991 393.766 314.43 393.766 308.87C393.766 271.003 363.048 242.666 327.562 242.666C320.413 242.666 313.528 243.723 306.644 246.109C294.725 234.457 278.307 227.042 260.301 227.042C228.258 227.042 201.513 249.815 195.42 280.004C165.761 287.685 146.694 315.49 146.694 343.824C146.694 362.362 154.638 380.368 168.938 393.344C167.613 398.906 166.819 404.467 166.819 410.027C166.819 447.894 197.538 476.231 233.024 476.231C240.172 476.231 247.058 475.173 253.943 472.788C265.859 484.441 282.278 491.854 300.286 491.854Z"/>
+</svg>

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "@coda-console/codex",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "id": "codex",
+  "displayName": "Codex",
+  "description": "Codex Agent：Coda 自带的入口运行 codex-acp，报告子 Agent 与后台命令。额度与登录由账号来源插件接管；未接入账号来源时使用 Codex 自己的登录面板。",
+  "version": "1.6.1",
+  "dependencies": {
+    "@agentclientprotocol/codex-acp": "1.12.0",
+    "@openai/codex": "0.162.1"
+  },
+  "overrides": {
+    "@agentclientprotocol/codex-acp": {
+      "@openai/codex": "$@openai/codex"
+    }
+  },
+  "contributes": {
+    "agents": [
+      {
+        "id": "codex",
+        "displayName": "Codex",
+        "icon": {
+          "light": "icons/openai.pdf",
+          "template": true
+        },
+        "command": "exec \"$CODA_NODE\" \"$CODA_PLUGIN_PATH/agent/entry.mjs\"",
+        "modes": {
+          "title": "审批模式",
+          "unset": "人工审批",
+          "auto": "agent",
+          "full": "agent-full-access"
+        },
+        "skillsDir": ".agents/skills",
+        "configFiles": [
+          "${CODEX_HOME:-~/.codex}/config.toml",
+          ".codex/config.toml"
+        ],
+        "setupHint": "请在运行机为后端所属账号完成 Codex 认证。"
+      }
+    ],
+    "panels": [
+      {
+        "id": "login",
+        "title": "Codex",
+        "command": "node \"$CODA_PLUGIN_PATH/scripts/panel.mjs\"",
+        "maxAge": "PT0S",
+        "actions": {
+          "reset": {
+            "command": "node \"$CODA_PLUGIN_PATH/scripts/reset.mjs\"",
+            "confirm": "使用一次完全重置？\n用最早到期的那一次。成功后消耗 1 次，无法撤销。"
+          }
+        },
+        "signIn": {
+          "command": "NO_COLOR=1 exec node \"$CODA_PLUGIN_PATH/scripts/cli.mjs\" login --device-auth",
+          "note": "接入账号插件后，登录会添加或更新插件管理的账号。"
+        }
+      }
+    ],
+    "extensionPoints": {
+      "account-source": {
+        "description": "Codex 的账号与登录入口：来源给出当前账号和令牌，响应 --login，并提供账号与额度面板；接入后 Codex 自带的额度面板隐藏。"
+      }
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/coda-console/coda-plugins.git",
+    "directory": "plugins/codex"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "agent",
+    "scripts",
+    "icons"
+  ]
+}

package/scripts/app-server.mjs

@@ -0,0 +1,61 @@
+// A private connection to the Codex CLI's app-server, as this machine's Codex sessions are signed in: the plugin's own CLI
+// (its `@openai/codex` dependency, the one codex-acp runs) in its own home (`CODEX_HOME`, or ~/.codex).
+// Codex reads and renews that login itself; nothing of it passes through here, unless a login is handed to it (the account
+// bridge, agent/accounts.mjs, which also takes what Codex says and asks of its client: `onMessage`).
+import { spawn } from 'node:child_process';
+import { readLines } from '../agent/lines.mjs';
+
+export class AppServer {
+  constructor({ env = process.env, command = [process.execPath, new URL(import.meta.resolve('@openai/codex/bin/codex.js')).pathname, 'app-server'],
+    timeoutMs = 15_000, onMessage = null } = {}) {
+    this.pending = new Map(); this.next = 0; this.timeoutMs = timeoutMs; this.onMessage = onMessage;
+    this.child = spawn(command[0], command.slice(1), { env, stdio: ['pipe', 'pipe', 'ignore'] });
+    this.child.stdin.on('error', () => {});
+    readLines(this.child.stdout).on('line', line => {
+      let message; try { message = JSON.parse(line); } catch { return; }
+      const waiter = message.method ? null : this.pending.get(message.id);
+      if (!waiter) {
+        if (this.onMessage) return this.onMessage(message);
+        // Codex asking for something of its client (new tokens for a login it was handed): this one has none to give.
+        if (message.id !== undefined && message.method) this.send({ id: message.id, error: { code: -32601, message: 'not supported' } });
+        return;
+      }
+      this.pending.delete(message.id); clearTimeout(waiter.timer);
+      if (message.error) waiter.reject(new Error(oneLine(message.error.message) || 'Codex 拒绝了请求'));
+      else waiter.resolve(message.result);
+    });
+    this.exited = new Promise(resolve => {
+      const done = () => {
+        for (const waiter of this.pending.values()) { clearTimeout(waiter.timer); waiter.reject(new Error('Codex 提前退出了')); }
+        this.pending.clear(); resolve();
+      };
+      this.child.once('error', done); this.child.once('exit', done);
+    });
+  }
+  send(message) { this.child.stdin.write(`${JSON.stringify(message)}\n`); }
+  request(method, params = {}) {
+    const id = `coda-${process.pid}-${++this.next}`;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { this.pending.delete(id); reject(new Error('Codex 没有答复')); }, this.timeoutMs);
+      this.pending.set(id, { resolve, reject, timer });
+      this.send({ id, method, params });
+    });
+  }
+  async initialize() {
+    await this.request('initialize', { clientInfo: { name: 'coda_panel', version: '1' }, capabilities: { experimentalApi: true } });
+    this.send({ method: 'initialized' });
+  }
+  async close() {
+    this.child.kill('SIGTERM');
+    const timer = setTimeout(() => this.child.kill('SIGKILL'), 2000);
+    await this.exited; clearTimeout(timer);
+  }
+}
+const oneLine = value => typeof value === 'string' ? value.replace(/\s+/g, ' ').trim().slice(0, 200) : '';
+
+// Runs `work` against a started app-server, which is always ended after.
+export async function withAppServer(work, options) {
+  const server = new AppServer(options);
+  try { await server.initialize(); return await work(server); }
+  finally { await server.close(); }
+}

package/scripts/cli.mjs

@@ -0,0 +1,11 @@
+// Once an account source owns the accounts, even the pre-existing Codex login entry adds to its managed store.
+import { spawn } from 'node:child_process';
+import { accountSource, sourceEnv } from '../agent/account-source.mjs';
+
+const source = accountSource();
+if (source && process.argv[2] === 'login') {
+  const child = spawn('/bin/sh', ['-c', `${source.command} --login`], { env: sourceEnv(source), stdio: 'inherit' });
+  process.on('SIGTERM', () => child.kill('SIGTERM')); process.on('SIGINT', () => child.kill('SIGINT'));
+  child.on('error', () => { console.error('无法启动账号插件的登录'); process.exitCode = 1; });
+  child.on('close', code => { process.exitCode = code ?? 1; });
+} else await import('@openai/codex/bin/codex.js');

package/scripts/panel.mjs

@@ -0,0 +1,7 @@
+// An account source owns its quota panel. Without one, show Codex's own login as before.
+import { withAppServer } from './app-server.mjs';
+import { panel } from './quota.mjs';
+import { accountSource } from '../agent/account-source.mjs';
+
+try { console.log(JSON.stringify(accountSource() ? { items: [] } : await withAppServer(panel))); }
+catch (error) { console.error(error.message); process.exit(1); }

package/scripts/quota.mjs

@@ -0,0 +1,85 @@
+import { createHash } from 'node:crypto';
+
+// What the Codex panel shows of a login (docs/plugins.md「内置插件：Codex」), from what Codex's app-server says of it:
+// `account/read` and `account/rateLimits/read`. Kept apart from the commands so the tests can hand it answers.
+
+const CARD_ITEMS = 20;
+const line = (value, max = 80) => typeof value === 'string' ? [...value.replace(/\s+/g, ' ').trim()].slice(0, max).join('') : '';
+// The account a card shows, compared across machines by Coda's group view (its panel cards' `identity`): who signed in
+// and in which ChatGPT workspace, as the quota is one person's in one workspace (one email may sign in to several, and a
+// workspace has many members). A hash of the email and of the workspace's account ID hashed as codex-account keeps it;
+// none where Codex does not say both.
+const hash = text => createHash('sha256').update(text).digest('hex');
+const identity = (account, workspace) => {
+  const email = line(account.email, 320).toLowerCase();
+  return email && typeof workspace === 'string' && workspace ? { identity: `codex:${hash(`${email}\n${hash(workspace)}`)}` } : {};
+};
+const unixTime = value => typeof value === 'number' && Number.isFinite(new Date(value * 1000).getTime()) ? new Date(value * 1000).toISOString() : null;
+// A credit's expiry as the clients write times (UTC+8), here because a figure's value is text.
+export function utc8(seconds) {
+  const d = new Date(seconds * 1000 + 8 * 3600_000);
+  return `${d.getUTCFullYear()}/${String(d.getUTCMonth() + 1).padStart(2, '0')}/${String(d.getUTCDate()).padStart(2, '0')} ${d.getUTCHours()}:${String(d.getUTCMinutes()).padStart(2, '0')}`;
+}
+
+// A bar per window of each limit, of what is left. A limit's name is said only when there are several.
+export function windows(result) {
+  const byID = result?.rateLimitsByLimitId ? Object.values(result.rateLimitsByLimitId) : [];
+  const limits = (byID.length ? byID : [result?.rateLimits]).filter(Boolean);
+  return limits.flatMap(limit => ['primary', 'secondary'].flatMap(key => {
+    const w = limit[key]; if (!w) return [];
+    const minutes = w.windowDurationMins;
+    const duration = minutes === 300 ? '5 小时' : minutes === 10080 ? '7 天' : Number.isSafeInteger(minutes) && minutes > 0 ? `${minutes} 分钟` : '额度';
+    const used = typeof w.usedPercent === 'number' && w.usedPercent >= 0 && w.usedPercent <= 100 ? w.usedPercent : null;
+    const left = used === null ? null : Math.round(100 - used), resets = unixTime(w.resetsAt);
+    return [{ type: 'meter', label: `${limits.length > 1 ? `${line(limit.limitName ?? limit.limitId, 40) || '额度'} · ` : ''}${duration}`,
+      ...(left === null ? {} : { value: `剩余 ${left}%`, fraction: left / 100 }),
+      ...(resets ? { time: resets, timeLabel: '重置' } : {}) }];
+  }));
+}
+
+// The full resets left: the count is Codex's word (its list of them may be capped or missing). Those listed are the
+// available ones, earliest to expire first; one without an expiry never expires.
+export function credits(result) {
+  const summary = result?.rateLimitResetCredits;
+  if (!Number.isSafeInteger(summary?.availableCount)) return null;
+  const listed = (summary.credits ?? []).filter(c => c?.status === 'available' && c.resetType === 'codexRateLimits' && typeof c.id === 'string' && c.id)
+    .sort((a, b) => (a.expiresAt ?? Infinity) - (b.expiresAt ?? Infinity));
+  return { count: summary.availableCount, listed };
+}
+
+// The login's card: its button for a full reset (the one to expire first, named in its question), its windows, then its
+// resets one line each.
+export function card(account, result, workspace) {
+  const name = line(account.email) || '本机登录';
+  const items = windows(result), resets = credits(result);
+  if (resets) {
+    const first = resets.listed[0];
+    const lines = resets.listed.map((c, i) => ({ type: 'stat', label: `第 ${i + 1} 次`, value: c.expiresAt == null ? '不会过期' : `${utc8(c.expiresAt)} 到期` }));
+    const room = CARD_ITEMS - items.length - (first ? 2 : 1);
+    items.push({ type: 'stat', label: '完全重置', value: `剩余 ${resets.count} 次` }, ...lines.slice(0, Math.max(0, room)));
+    if (first && resets.count > 0) items.unshift({ type: 'button', label: '使用完全重置', action: 'reset', args: { creditId: first.id },
+      confirm: `使用 ${line(name, 60)} 的完全重置？\n用最早到期的那一次（${first.expiresAt == null ? '不会过期' : `${utc8(first.expiresAt)} 到期，UTC+8`}）。成功后消耗 1 次，无法撤销。` });
+  }
+  if (!items.length) items.push({ type: 'error', text: '暂时无法获取额度：Codex 没有给出额度窗口' });
+  return { type: 'card', title: name, ...(line(account.planType) ? { subtitle: line(account.planType) } : {}), ...identity(account, workspace), items: items.slice(0, CARD_ITEMS) };
+}
+
+// The panel: nothing without a login (it is then offered under「添加资源」), a card for one. Quota Codex cannot read stays
+// on the card, which keeps「重新登录」 at hand; one not signed in with ChatGPT has no windows to read.
+export async function panel(server) {
+  const { account, workspaceRouting } = await server.request('account/read', { refreshToken: false });
+  const workspace = workspaceRouting?.chatgptAccountId;
+  if (!account) return { items: [] };
+  if (account.type !== 'chatgpt') return { items: [{ type: 'card', title: '本机登录', subtitle: line(account.type),
+    items: [{ type: 'markdown', text: '不是用 ChatGPT 账号登录的，没有额度可显示' }] }] };
+  let result;
+  try { result = await server.request('account/rateLimits/read'); }
+  catch (error) {
+    return { items: [{ type: 'card', title: line(account.email) || '本机登录', ...(line(account.planType) ? { subtitle: line(account.planType) } : {}), ...identity(account, workspace),
+      items: [{ type: 'error', text: `暂时无法获取额度：${error.message}` }] }] };
+  }
+  return { items: [card(account, result, workspace)] };
+}
+
+// What a full reset came to, as one line for the panel when it did not reset anything.
+export const outcomes = { nothingToReset: '当前额度无需重置', alreadyRedeemed: '这次重置已被使用', noCredit: '这次重置已不可用' };

package/scripts/reset.mjs

@@ -0,0 +1,15 @@
+// The panel's「使用完全重置」: redeems exactly the credit its button named (without one Codex would pick for itself), once.
+// Anything but a reset is said in one line and fails the action, so the panel shows it.
+import { randomUUID } from 'node:crypto';
+import { withAppServer } from './app-server.mjs';
+import { outcomes } from './quota.mjs';
+import { accountSource } from '../agent/account-source.mjs';
+
+if (accountSource()) { console.error('额度已由账号插件接管，请在账号面板使用完全重置'); process.exit(1); }
+
+const { creditId } = JSON.parse(process.env.CODA_PANEL_ARGS || '{}');
+if (typeof creditId !== 'string' || !creditId) { console.error('没有指明用哪一次完全重置'); process.exit(1); }
+let outcome;
+try { ({ outcome } = await withAppServer(server => server.request('account/rateLimitResetCredit/consume', { creditId, idempotencyKey: randomUUID() }))); }
+catch (error) { console.error(`使用结果未确认，请核对剩余次数：${error.message}`); process.exit(1); }
+if (outcome !== 'reset') { console.error(outcomes[outcome] ?? '使用结果未确认，请核对剩余次数'); process.exit(1); }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.