@stage-labs/metro 0.1.0-beta.26 → 0.1.0-beta.261

package/runtime/node_modules/@metro-labs/daemon/src/gateway/codex-auth.ts

@@ -0,0 +1,219 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { isRecord } from '@metro-labs/core/is-record';
+import { readJson, writeSecure } from '@metro-labs/core/secure-fs';
+import { ticketStore } from '@metro-labs/core/tickets';
+import { agentsDir } from '../agents/files.js';
+import { newPkce } from './pkce.js';
+import { nonEmpty } from './text.js';
+
+export const CODEX_ISSUER = 'https://auth.openai.com';
+export const CODEX_REDIRECT = 'http://127.0.0.1:1455/auth/callback';
+export const OPENAI_API = 'https://api.openai.com/v1';
+export const NEW_CLIENT = 'dynamic_agent_client';
+export const APP_NAME = 'Metro';
+export const PLAN_SCOPE = 'chatgpt.tokens.use.direct';
+export const CODEX_SIGN_IN = 'Codex is not signed in: sign in with ChatGPT on the Model page.';
+const SCOPE = `openid profile email offline_access resource.invoke ${PLAN_SCOPE}`;
+const PROFILE_CLAIM = 'https://api.openai.com/profile';
+const HOST_FILE = 'chatgpt-host.json';
+const HOST_RE = /^urn:uuid:[0-9a-f-]{36}$/;
+const PENDING_TTL_MS = 10 * 60_000;
+const DEFAULT_TTL_MS = 60 * 60_000;
+const RENEW_BEFORE_MS = 2 * 60_000;
+const AGAIN = 'press Continue with ChatGPT again';
+
+export type CodexMethod = 'chatgpt' | 'code';
+
+export interface CodexCredential {
+  email: string | null;
+  accessToken: string;
+  refreshToken: string;
+  expiresAt: number;
+  savedAt: string;
+}
+
+export interface ChatgptTokens extends CodexCredential {
+  method: 'chatgpt';
+  clientId: string;
+  subject: string;
+}
+
+export interface CodeTokens extends CodexCredential {
+  method: 'code';
+  accountId: string;
+  plan: string | null;
+}
+
+export type CodexTokens = ChatgptTokens | CodeTokens;
+
+export class CodexAuthError extends Error {}
+
+interface Pending {
+  verifier: string;
+  nonce: string;
+  clientId: string | null;
+  subject: string | null;
+}
+
+const pending = ticketStore<Pending>(PENDING_TTL_MS, 24);
+
+export function chatgptHostId(dir = agentsDir()): string {
+  const path = join(dir, HOST_FILE);
+  const saved = readJson<unknown>(path, null);
+  if (isRecord(saved) && typeof saved.hostId === 'string' && HOST_RE.test(saved.hostId)) return saved.hostId;
+  const made = `urn:uuid:${randomUUID()}`;
+  writeSecure(path, JSON.stringify({ hostId: made }));
+  return made;
+}
+
+function returning(previous: ChatgptTokens | null): Record<string, string> {
+  if (previous === null) return { client_id: NEW_CLIENT, agent_name_hint: APP_NAME };
+  return { client_id: previous.clientId, ...(previous.email === null ? {} : { login_hint: previous.email }) };
+}
+
+export function beginLogin(previous: ChatgptTokens | null, hostId: string, issuer = CODEX_ISSUER, now = Date.now()): string {
+  const { verifier, challenge } = newPkce();
+  const nonce = randomBytes(32).toString('base64url');
+  const { ticket: state } = pending.mint({ verifier, nonce, clientId: previous?.clientId ?? null, subject: previous?.subject ?? null }, now);
+  const query = new URLSearchParams({
+    ...returning(previous),
+    ext_agent_host_id: hostId,
+    response_type: 'code',
+    redirect_uri: CODEX_REDIRECT,
+    scope: SCOPE,
+    resource: OPENAI_API,
+    state,
+    nonce,
+    code_challenge_method: 'S256',
+    code_challenge: challenge,
+  });
+  return `${issuer}/api/accounts/authorize?${query.toString()}`;
+}
+
+function queryOf(raw: string): URLSearchParams {
+  const text = raw.trim();
+  try {
+    return new URL(text).searchParams;
+  } catch {
+    return new URLSearchParams(text.replace(/^\?/, ''));
+  }
+}
+
+const param = (query: URLSearchParams, name: string): string => query.get(name)?.trim() ?? '';
+
+function assertAllowed(query: URLSearchParams): void {
+  const error = param(query, 'error');
+  if (error === 'access_denied') throw new CodexAuthError('you did not allow Metro to use your ChatGPT plan, so nothing was saved');
+  if (error !== '') throw new CodexAuthError(`ChatGPT stopped the sign-in (${query.get('error_description') ?? error}); ${AGAIN}`);
+}
+
+export function parseCallback(raw: string): { code: string; state: string; clientId: string | null } {
+  const query = queryOf(raw);
+  assertAllowed(query);
+  const code = param(query, 'code');
+  const state = param(query, 'state');
+  if (code === '' || state === '') throw new CodexAuthError('paste the whole address the browser landed on; it carries code= and state=');
+  return { code, state, clientId: nonEmpty(param(query, 'client_id')) };
+}
+
+export function decodeJwtPayload(jwt: string): Record<string, unknown> {
+  const part = jwt.split('.')[1] ?? '';
+  try {
+    const parsed: unknown = JSON.parse(Buffer.from(part, 'base64url').toString('utf8'));
+    return isRecord(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+export function emailOf(claims: Record<string, unknown>): string | null {
+  const profile = isRecord(claims[PROFILE_CLAIM]) ? claims[PROFILE_CLAIM] : {};
+  return nonEmpty(claims.email) ?? nonEmpty(profile.email);
+}
+
+function identityOf(idToken: unknown, expected: { issuer: string; clientId: string; nonce: string }): { subject: string; email: string | null } {
+  const claims = decodeJwtPayload(typeof idToken === 'string' ? idToken : '');
+  const audience: unknown[] = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
+  const subject = nonEmpty(claims.sub);
+  if (subject === null || claims.iss !== expected.issuer || !audience.includes(expected.clientId) || claims.nonce !== expected.nonce)
+    throw new CodexAuthError(`OpenAI sent back an identity that does not match this sign-in; ${AGAIN}`);
+  return { subject, email: emailOf(claims) };
+}
+
+interface Encoded {
+  type: string;
+  body: string;
+}
+
+export const asForm = (fields: Record<string, string>): Encoded => ({ type: 'application/x-www-form-urlencoded', body: new URLSearchParams(fields).toString() });
+
+export const asJson = (fields: Record<string, string>): Encoded => ({ type: 'application/json', body: JSON.stringify(fields) });
+
+export async function tokenCall(url: string, sent: Encoded, fetchImpl: typeof fetch): Promise<Record<string, unknown>> {
+  const res = await fetchImpl(url, { method: 'POST', headers: { 'content-type': sent.type, accept: 'application/json' }, body: sent.body });
+  const raw = await res.text();
+  let parsed: unknown = null;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    parsed = null;
+  }
+  const body = isRecord(parsed) ? parsed : {};
+  if (!res.ok) throw new CodexAuthError(`OpenAI refused the token request (${String(res.status)}): ${nonEmpty(body.error_description) ?? nonEmpty(body.error) ?? raw.slice(0, 300)}`);
+  return body;
+}
+
+export function grantOf(body: Record<string, unknown>, keptRefresh: string, now: number): Omit<CodexCredential, 'email'> {
+  const accessToken = nonEmpty(body.access_token) ?? '';
+  const refreshToken = nonEmpty(body.refresh_token) ?? keptRefresh;
+  if (accessToken === '' || refreshToken === '') throw new CodexAuthError('OpenAI returned no usable tokens; sign in again');
+  const ttl = typeof body.expires_in === 'number' && body.expires_in > 0 ? body.expires_in * 1000 : DEFAULT_TTL_MS;
+  return { accessToken, refreshToken, expiresAt: now + ttl, savedAt: new Date(now).toISOString() };
+}
+
+const tokensFrom = (body: Record<string, unknown>, who: Pick<ChatgptTokens, 'clientId' | 'subject' | 'email'>, keptRefresh: string, now: number): ChatgptTokens => ({
+  method: 'chatgpt',
+  clientId: who.clientId,
+  subject: who.subject,
+  email: who.email,
+  ...grantOf(body, keptRefresh, now),
+});
+
+const officialToken = (issuer: string): string => `${issuer}/api/accounts/oauth/token`;
+
+function clientOf(started: Pending, returned: string | null): string {
+  const clientId = started.clientId ?? returned;
+  if (clientId === null || clientId === NEW_CLIENT) throw new CodexAuthError(`ChatGPT did not finish registering Metro; ${AGAIN}`);
+  if (returned !== null && returned !== clientId) throw new CodexAuthError(`ChatGPT answered for another Metro registration; ${AGAIN}`);
+  return clientId;
+}
+
+export async function finishLogin(callback: string, issuer = CODEX_ISSUER, fetchImpl: typeof fetch = fetch, now = Date.now()): Promise<ChatgptTokens> {
+  const { code, state, clientId: returned } = parseCallback(callback);
+  const started = pending.take(state, now);
+  if (started === undefined) throw new CodexAuthError(`this sign-in link has expired or was started elsewhere; ${AGAIN}`);
+  const clientId = clientOf(started, returned);
+  const body = await tokenCall(
+    officialToken(issuer),
+    asForm({ grant_type: 'authorization_code', client_id: clientId, code, code_verifier: started.verifier, redirect_uri: CODEX_REDIRECT, resource: OPENAI_API }),
+    fetchImpl,
+  );
+  const who = identityOf(body.id_token, { issuer, clientId, nonce: started.nonce });
+  if (started.subject !== null && who.subject !== started.subject)
+    throw new CodexAuthError('this is another ChatGPT account than the one this connection signed in with; add a new connection for it');
+  const scopes = (nonEmpty(body.scope) ?? '').split(/\s+/);
+  if (!scopes.includes(PLAN_SCOPE)) throw new CodexAuthError('ChatGPT did not allow Metro to use your plan: sign in again and allow it (it needs ChatGPT Plus or Pro)');
+  return tokensFrom(body, { clientId, ...who }, '', now);
+}
+
+export async function refreshTokens(previous: ChatgptTokens, issuer = CODEX_ISSUER, fetchImpl: typeof fetch = fetch, now = Date.now()): Promise<ChatgptTokens> {
+  const body = await tokenCall(
+    officialToken(issuer),
+    asForm({ grant_type: 'refresh_token', client_id: previous.clientId, refresh_token: previous.refreshToken, resource: OPENAI_API }),
+    fetchImpl,
+  );
+  return tokensFrom(body, previous, previous.refreshToken, now);
+}
+
+export const tokensStale = (tokens: CodexTokens, now = Date.now()): boolean => now >= tokens.expiresAt - RENEW_BEFORE_MS;

package/runtime/node_modules/@metro-labs/daemon/src/gateway/codex-device.ts

@@ -0,0 +1,119 @@
+import { randomBytes } from 'node:crypto';
+import { isRecord } from '@metro-labs/core/is-record';
+import { errMsg } from '@metro-labs/core/log';
+import { stringOf } from '@metro-labs/http/api-http';
+import { asForm, asJson, CODEX_ISSUER, CodexAuthError, decodeJwtPayload, emailOf, grantOf, tokenCall, type CodeTokens } from './codex-auth.js';
+import { nonEmpty } from './text.js';
+
+const CODEX_CLIENT_ID = 'app_EMoamEEZ73f0CkXaXp7hrann';
+const AUTH_CLAIM = 'https://api.openai.com/auth';
+const VERIFY_PATH = '/codex/device';
+const DEVICE_TTL_MS = 15 * 60_000;
+const DEFAULT_INTERVAL_S = 5;
+const ID_BYTES = 18;
+const AGAIN = 'press Sign in with a code again';
+
+export interface DeviceLogin {
+  id: string;
+  userCode: string;
+  verifyUrl: string;
+  interval: number;
+}
+
+export type DeviceStatus = { status: 'pending' } | { status: 'done'; tokens: CodeTokens } | { status: 'failed'; error: string };
+
+interface Entry {
+  deviceAuthId: string;
+  userCode: string;
+  interval: number;
+  issuer: string;
+  startedAt: number;
+  polledAt: number | null;
+}
+
+const logins = new Map<string, Entry>();
+
+function claimsOf(idToken: string): { accountId: string | null; email: string | null; plan: string | null } {
+  const payload = decodeJwtPayload(idToken);
+  const auth = isRecord(payload[AUTH_CLAIM]) ? payload[AUTH_CLAIM] : {};
+  return { accountId: nonEmpty(auth.chatgpt_account_id), email: emailOf(payload), plan: nonEmpty(auth.chatgpt_plan_type) };
+}
+
+function codeTokensFrom(body: Record<string, unknown>, previous: CodeTokens | null, now: number): CodeTokens {
+  const fresh = claimsOf(nonEmpty(body.id_token) ?? '');
+  const kept = previous ?? { accountId: null, email: null, plan: null, refreshToken: '' };
+  const accountId = fresh.accountId ?? kept.accountId ?? '';
+  if (accountId === '') throw new CodexAuthError('the id token carries no ChatGPT account id; sign in with a ChatGPT account that has Codex');
+  return { method: 'code', accountId, email: fresh.email ?? kept.email, plan: fresh.plan ?? kept.plan, ...grantOf(body, kept.refreshToken, now) };
+}
+
+const cliToken = (issuer: string): string => `${issuer}/oauth/token`;
+
+export async function refreshCodeTokens(previous: CodeTokens, issuer = CODEX_ISSUER, fetchImpl: typeof fetch = fetch, now = Date.now()): Promise<CodeTokens> {
+  const body = await tokenCall(cliToken(issuer), asJson({ client_id: CODEX_CLIENT_ID, grant_type: 'refresh_token', refresh_token: previous.refreshToken }), fetchImpl);
+  return codeTokensFrom(body, previous, now);
+}
+
+function intervalOf(value: unknown): number {
+  const n = typeof value === 'number' ? value : typeof value === 'string' ? Number(value) : NaN;
+  return Number.isFinite(n) && n >= 1 ? Math.round(n) : DEFAULT_INTERVAL_S;
+}
+
+function sweep(now: number): void {
+  for (const [id, entry] of logins) if (now - entry.startedAt > DEVICE_TTL_MS) logins.delete(id);
+}
+
+const post = (url: string, body: unknown, fetchImpl: typeof fetch): Promise<Response> =>
+  fetchImpl(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+
+export async function beginDeviceLogin(issuer = CODEX_ISSUER, fetchImpl: typeof fetch = fetch, now = Date.now()): Promise<DeviceLogin> {
+  sweep(now);
+  const res = await post(`${issuer}/api/accounts/deviceauth/usercode`, { client_id: CODEX_CLIENT_ID }, fetchImpl);
+  if (res.status === 404) throw new CodexAuthError('OpenAI is not offering the code sign-in right now; use Continue with ChatGPT instead');
+  if (!res.ok) throw new CodexAuthError(`OpenAI refused to start the code sign-in (${String(res.status)})`);
+  const body: unknown = await res.json();
+  const parsed = isRecord(body) ? body : {};
+  const deviceAuthId = stringOf(parsed.device_auth_id);
+  const userCode = stringOf(parsed.user_code) || stringOf(parsed.usercode);
+  if (deviceAuthId === '' || userCode === '') throw new CodexAuthError('OpenAI answered without a device code');
+  const id = randomBytes(ID_BYTES).toString('base64url');
+  const interval = intervalOf(parsed.interval);
+  logins.set(id, { deviceAuthId, userCode, interval, issuer, startedAt: now, polledAt: null });
+  return { id, userCode, verifyUrl: `${issuer}${VERIFY_PATH}`, interval };
+}
+
+async function claim(entry: Entry, fetchImpl: typeof fetch, now: number): Promise<DeviceStatus> {
+  const res = await post(`${entry.issuer}/api/accounts/deviceauth/token`, { device_auth_id: entry.deviceAuthId, user_code: entry.userCode }, fetchImpl);
+  if (res.status === 403 || res.status === 404) {
+    await res.body?.cancel();
+    return { status: 'pending' };
+  }
+  if (!res.ok) return { status: 'failed', error: `OpenAI ended the code sign-in (${String(res.status)})` };
+  const body: unknown = await res.json();
+  const parsed = isRecord(body) ? body : {};
+  const code = stringOf(parsed.authorization_code);
+  const verifier = stringOf(parsed.code_verifier);
+  if (code === '' || verifier === '') return { status: 'failed', error: 'OpenAI approved the sign-in but sent no code back' };
+  const granted = await tokenCall(
+    cliToken(entry.issuer),
+    asForm({ grant_type: 'authorization_code', code, redirect_uri: `${entry.issuer}/deviceauth/callback`, client_id: CODEX_CLIENT_ID, code_verifier: verifier }),
+    fetchImpl,
+  );
+  return { status: 'done', tokens: codeTokensFrom(granted, null, now) };
+}
+
+export async function pollDeviceLogin(id: string, fetchImpl: typeof fetch = fetch, now = Date.now()): Promise<DeviceStatus> {
+  sweep(now);
+  const entry = logins.get(id);
+  if (entry === undefined) throw new CodexAuthError(`this sign-in has expired or already finished; ${AGAIN}`);
+  if (entry.polledAt !== null && now - entry.polledAt < entry.interval * 1000) return { status: 'pending' };
+  entry.polledAt = now;
+  let result: DeviceStatus;
+  try {
+    result = await claim(entry, fetchImpl, now);
+  } catch (err) {
+    result = { status: 'failed', error: errMsg(err) };
+  }
+  if (result.status !== 'pending') logins.delete(id);
+  return result;
+}

package/runtime/node_modules/@metro-labs/daemon/src/gateway/codex-stream.ts

@@ -0,0 +1,179 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import { encodeSignature } from './codex-translate.js';
+import { errorFrame } from './forward.js';
+import { frame, messageEnd, messageStart, type Usage } from './frames.js';
+import { stringOf } from '@metro-labs/http/api-http';
+
+type Item = Record<string, unknown>;
+
+interface Block {
+  index: number;
+  kind: 'text' | 'thinking' | 'tool_use';
+  deltas: number;
+}
+
+const responseOf = (data: Item): Item => (isRecord(data.response) ? data.response : {});
+const itemOf = (data: Item): Item => (isRecord(data.item) ? data.item : {});
+
+const PLAN_LIMIT = 'subscription_sharing_usage_limit_exceeded';
+const USAGE_URL = 'https://chatgpt.com/settings/usage';
+
+export const withUsageLink = (code: string, message: string): string => (code === PLAN_LIMIT ? `${message} Manage usage: ${USAGE_URL}` : message);
+
+function errorKind(code: string): string {
+  if (code === 'rate_limit_exceeded' || code === 'usage_limit_reached' || code === PLAN_LIMIT) return 'rate_limit_error';
+  if (code === 'context_length_exceeded' || code === 'invalid_prompt') return 'invalid_request_error';
+  if (code === 'insufficient_quota') return 'permission_error';
+  return 'api_error';
+}
+
+function usageOf(response: Item): Usage {
+  const usage = isRecord(response.usage) ? response.usage : {};
+  const details = isRecord(usage.input_tokens_details) ? usage.input_tokens_details : {};
+  const cached = typeof details.cached_tokens === 'number' ? details.cached_tokens : 0;
+  const input = typeof usage.input_tokens === 'number' ? usage.input_tokens : 0;
+  return {
+    input_tokens: Math.max(0, input - cached),
+    output_tokens: typeof usage.output_tokens === 'number' ? usage.output_tokens : 0,
+    cache_read_input_tokens: cached,
+  };
+}
+
+const startBlock = (kind: Block['kind'], id: string, name: string): Item =>
+  kind === 'text' ? { type: 'text', text: '' } : kind === 'thinking' ? { type: 'thinking', thinking: '' } : { type: 'tool_use', id, name, input: {} };
+
+const messageText = (item: Item): string =>
+  Array.isArray(item.content) ? item.content.filter(isRecord).map((part) => stringOf(part.text)).join('') : '';
+
+export class CodexEventTranslator {
+  private readonly blocks = new Map<string, Block>();
+  private next = 0;
+  private started = false;
+  private toolCalls = 0;
+  private done = false;
+  private readonly model: string;
+  private readonly restore: (name: string) => string;
+  private readonly handlers: Record<string, (data: Item) => string> = {
+    'response.created': (d) => this.start(responseOf(d)),
+    'response.output_item.added': (d) => this.start({}) + this.itemAdded(itemOf(d)),
+    'response.output_text.delta': (d) => this.delta(stringOf(d.item_id), 'text', stringOf(d.delta)),
+    'response.reasoning_summary_text.delta': (d) => this.delta(stringOf(d.item_id), 'thinking', stringOf(d.delta)),
+    'response.reasoning_summary_part.added': (d) => this.partAdded(stringOf(d.item_id)),
+    'response.function_call_arguments.delta': (d) => this.delta(stringOf(d.item_id), 'tool_use', stringOf(d.delta)),
+    'response.output_item.done': (d) => this.itemDone(itemOf(d)),
+    'response.completed': (d) => this.start(responseOf(d)) + this.completed(responseOf(d)),
+    'response.failed': (d) => this.failed(responseOf(d), 'Codex failed the response'),
+    'response.incomplete': (d) => this.incomplete(responseOf(d)),
+    error: (d) => this.failed({ error: d }, 'Codex stream error'),
+  };
+
+  constructor(model: string, restore: (name: string) => string = (name) => name) {
+    this.model = model;
+    this.restore = restore;
+  }
+
+  get finished(): boolean {
+    return this.done;
+  }
+
+  private open(key: string, kind: Block['kind'], id = '', name = ''): string {
+    const block: Block = { index: this.next, kind, deltas: 0 };
+    this.next += 1;
+    this.blocks.set(key, block);
+    return frame('content_block_start', { type: 'content_block_start', index: block.index, content_block: startBlock(kind, id, name) });
+  }
+
+  private start(response: Item): string {
+    if (this.started) return '';
+    this.started = true;
+    return messageStart(stringOf(response.id) || 'msg_codex', this.model);
+  }
+
+  private openCall(key: string, item: Item): string {
+    this.toolCalls += 1;
+    return this.open(key, 'tool_use', stringOf(item.call_id) || key, this.restore(stringOf(item.name)));
+  }
+
+  private itemAdded(item: Item): string {
+    const key = stringOf(item.id) || String(this.next);
+    if (item.type === 'function_call') return this.openCall(key, item);
+    if (item.type === 'reasoning') return this.open(key, 'thinking');
+    return '';
+  }
+
+  private partAdded(key: string): string {
+    const block = this.blocks.get(key);
+    return block !== undefined && block.deltas > 0 ? this.delta(key, 'thinking', '\n\n') : '';
+  }
+
+  private delta(key: string, kind: Block['kind'], text: string): string {
+    const opened = this.blocks.has(key) ? '' : this.open(key, kind);
+    const block = this.blocks.get(key);
+    if (block === undefined) return opened;
+    block.deltas += 1;
+    const delta =
+      kind === 'tool_use' ? { type: 'input_json_delta', partial_json: text } : kind === 'text' ? { type: 'text_delta', text } : { type: 'thinking_delta', thinking: text };
+    return opened + frame('content_block_delta', { type: 'content_block_delta', index: block.index, delta });
+  }
+
+  private stop(key: string): string {
+    const block = this.blocks.get(key);
+    if (block === undefined) return '';
+    this.blocks.delete(key);
+    return frame('content_block_stop', { type: 'content_block_stop', index: block.index });
+  }
+
+  private reasoningDone(key: string, item: Item): string {
+    const opened = this.blocks.has(key) ? '' : this.open(key, 'thinking');
+    const block = this.blocks.get(key);
+    if (block === undefined || typeof item.encrypted_content !== 'string') return opened + this.stop(key);
+    const signature = encodeSignature({ id: key, encrypted_content: item.encrypted_content });
+    return opened + frame('content_block_delta', { type: 'content_block_delta', index: block.index, delta: { type: 'signature_delta', signature } }) + this.stop(key);
+  }
+
+  private callDone(key: string, item: Item): string {
+    let out = this.blocks.has(key) ? '' : this.openCall(key, item);
+    if (this.blocks.get(key)?.deltas === 0 && stringOf(item.arguments) !== '') out += this.delta(key, 'tool_use', stringOf(item.arguments));
+    return out + this.stop(key);
+  }
+
+  private itemDone(item: Item): string {
+    const key = stringOf(item.id);
+    if (item.type === 'reasoning') return this.reasoningDone(key, item);
+    if (item.type === 'function_call') return this.callDone(key, item);
+    if (item.type === 'message' && !this.blocks.has(key) && messageText(item) !== '') return this.delta(key, 'text', messageText(item)) + this.stop(key);
+    return this.stop(key);
+  }
+
+  private completed(response: Item, forced: string | null = null): string {
+    this.done = true;
+    let out = '';
+    for (const key of [...this.blocks.keys()]) out += this.stop(key);
+    const stop = forced ?? (this.toolCalls > 0 ? 'tool_use' : 'end_turn');
+    return out + messageEnd(stop, usageOf(response));
+  }
+
+  private incomplete(response: Item): string {
+    const details = isRecord(response.incomplete_details) ? response.incomplete_details : {};
+    if (details.reason === 'max_output_tokens') return this.start(response) + this.completed(response, 'max_tokens');
+    return this.failed(response, `Codex left the response incomplete (${stringOf(details.reason) || 'no reason given'})`);
+  }
+
+  private failed(response: Item, fallback: string): string {
+    this.done = true;
+    const error = isRecord(response.error) ? response.error : {};
+    const code = stringOf(error.code);
+    return errorFrame(errorKind(code), withUsageLink(code, stringOf(error.message) || fallback));
+  }
+
+  push(event: string, data: Item): string {
+    const handler = this.handlers[event];
+    return handler === undefined ? '' : handler(data);
+  }
+
+  close(message = 'Codex ended the stream before completing the response'): string {
+    if (this.done) return '';
+    this.done = true;
+    return errorFrame('api_error', message);
+  }
+}