Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

21.3 KB
Raw Blame
/**
 * The INFERENCE half of the Codex ChatGPT-subscription provider (#5590), pure.
 *
 * `codexAccount.js` answers "is this subscription usable"; this module answers
 * "what can it run, and what did a run produce". It owns the thread/turn/model
 * slice of the documented Codex app-server protocol: which methods and
 * notifications PortOS speaks, the fixed safety envelope a generic text call
 * runs under, and the normalizers that turn protocol frames into PortOS's own
 * `{ text, usage, error }` contract. The process half is
 * `services/codexAppServer.js`.
 *
 * Two boundaries this file exists to hold:
 *
 *   - **A text call is not a coding agent.** The `codex` provider stays a
 *     file-writing CLI/TUI harness for CoS tasks; that path is untouched. When
 *     the SAME record is selected as a text transport it runs under
 *     {@link CODEX_TEXT_THREAD_CONFIG}: an empty throwaway cwd, a read-only
 *     sandbox with no network, approvals that can only deny, no MCP servers,
 *     and no web search. Codex can still read local files by absolute path, so
 *     the Providers UI requires an explicit acknowledgement before this
 *     transport can be enabled.
 *   - **Partial output is not an answer.** A turn that is interrupted, fails,
 *     or never reaches `turn/completed` yields an error, never the text
 *     accumulated so far — a half-streamed JSON object that parsed would be
 *     silently wrong data.
 *
 * Sentinel discipline (AGENTS.md) carries over from `codexAccount.js`:
 * `models: null` = NEVER FETCHED and `models: []` = fetched and genuinely
 * empty, so a catalog read that fails can never overwrite a last-known-good
 * list with "this account has no models".
 */

import { ERROR_CATEGORIES } from './aiToolkit/errorDetection.js';
import { CODEX_ERROR_CODES, isCodexSubscriptionProvider, redactCodexMessage } from './codexAccount.js';

/**
 * The value a provider record carries to advertise that it can serve generic
 * text through the app-server. One string rather than a boolean so a future
 * second transport is a new value, not a second flag that can contradict the
 * first.
 */
export const CODEX_TEXT_TRANSPORT = 'codex-app-server';

/** Thread/turn/model JSON-RPC methods. Read + run; nothing that mutates state. */
export const CODEX_TURN_RPC = Object.freeze({
  threadStart: 'thread/start',
  turnStart: 'turn/start',
  turnInterrupt: 'turn/interrupt',
  modelList: 'model/list',
});

/** Server notifications a running turn projects into text/usage. */
export const CODEX_TURN_NOTIFICATIONS = Object.freeze({
  turnStarted: 'turn/started',
  agentMessageDelta: 'item/agentMessage/delta',
  itemCompleted: 'item/completed',
  turnCompleted: 'turn/completed',
  tokenUsage: 'thread/tokenUsage/updated',
  error: 'error',
});

/**
 * The safety envelope every generic text turn runs under.
 *
 * What this GUARANTEES: the turn cannot write anywhere, cannot reach the
 * network, has no MCP servers and no web search, starts in a fresh empty
 * directory outside the PortOS checkout, and leaves no thread behind.
 * `approvalPolicy: 'never'` is FAIL-CLOSED here rather than permissive — paired
 * with a read-only sandbox it means an escalation request is refused outright
 * instead of queued for a human who is not watching a Brain summary, and
 * `sandbox_permissions: []` withholds every opt-in widening (notably Codex's
 * `disk-full-read-access`).
 *
 * What it does NOT guarantee: Codex's read-only sandbox still lets the model's
 * own shell tool READ files by absolute path. Live verification for #5628
 * confirmed that Codex's narrowest built-in permission profile (`:read-only`)
 * has the same gap, so a prompt carrying injected instructions can quote local
 * file contents back into its answer. The transport therefore stays gated on
 * `textTransportReadRiskAcknowledged`; this envelope is NOT read confinement.
 *
 * The `cwd` is supplied per call because it is a runtime path, not a constant.
 */
export const CODEX_TEXT_THREAD_CONFIG = Object.freeze({
  approvalPolicy: 'never',
  sandbox: 'read-only',
  ephemeral: true,
  config: Object.freeze({
    mcp_servers: {},
    tools: { web_search: false },
    // An explicit empty list, not an omission: Codex's opt-in widenings (e.g.
    // `disk-full-read-access`) are additive, so declaring none can only narrow.
    sandbox_permissions: [],
  }),
});

/** The per-turn sandbox override, restated so a turn cannot inherit a wider one. */
export const CODEX_TEXT_TURN_SANDBOX = Object.freeze({ type: 'readOnly', networkAccess: false });

/** Typed failures the transport raises, alongside `CODEX_ERROR_CODES`. */
export const CODEX_TURN_ERROR_CODES = Object.freeze({
  turnFailed: 'CODEX_TURN_FAILED',
  turnInterrupted: 'CODEX_TURN_INTERRUPTED',
  turnEmpty: 'CODEX_TURN_EMPTY',
  quotaExhausted: 'CODEX_QUOTA_EXHAUSTED',
  transportBenched: 'CODEX_TRANSPORT_BENCHED',
});

/**
 * Does this record ADVERTISE the subscription text transport?
 *
 * Advertising is not permission — see {@link isCodexTextTransportEnabled}. The
 * shipped seed advertises it so the Providers page has something to offer,
 * while the capability stays off until the user turns it on.
 */
export const providerDeclaresCodexTextTransport = (provider) =>
  provider?.textTransport === CODEX_TEXT_TRANSPORT
  // "Which record IS the Codex subscription" is one question with one answer,
  // keyed on the COMMAND so a renamed clone still resolves. Reused rather than
  // restated so the account side and the inference side can never drift.
  && isCodexSubscriptionProvider(provider);

/**
 * May PortOS actually route a text call here?
 *
 * Requires the explicit opt-in, so a fresh install that has never signed in
 * cannot have a background feature quietly start billing a subscription — the
 * epic's "keep the capability off until the user enables it" rule, enforced at
 * the one place every caller passes through.
 */
export const isCodexTextTransportEnabled = (provider) =>
  providerDeclaresCodexTextTransport(provider)
  && provider.enabled !== false
  && provider.textTransportEnabled === true
  && provider.textTransportReadRiskAcknowledged === true;

const trimmed = (value) => (typeof value === 'string' && value.trim() !== '' ? value.trim() : null);

const finiteInt = (value) => (typeof value === 'number' && Number.isFinite(value) ? Math.trunc(value) : null);

/**
 * The non-secret shape of one `model/list` entry, or `null` when the entry has
 * no usable id.
 */
const normalizeModel = (raw) => {
  if (!raw || typeof raw !== 'object') return null;
  const id = trimmed(raw.id) || trimmed(raw.model);
  if (!id) return null;
  const supportedEfforts = Array.isArray(raw.supportedReasoningEfforts)
    ? raw.supportedReasoningEfforts
      .map((entry) => trimmed(typeof entry === 'string' ? entry : entry?.reasoningEffort))
      .filter(Boolean)
    : [];
  return {
    id,
    displayName: trimmed(raw.displayName) || id,
    description: trimmed(raw.description),
    isDefault: raw.isDefault === true,
    hidden: raw.hidden === true,
    defaultEffort: trimmed(raw.defaultReasoningEffort),
    supportedEfforts,
    contextWindow: finiteInt(raw.contextWindow),
  };
};

/**
 * The non-secret shape of `model/list`.
 *
 * THROWS for a response that is not a catalog, so a failed read stays `null`
 * at the call site and the last-known-good list survives. A catalog that is
 * genuinely empty returns `[]`, which is a real answer and must not be
 * re-labelled as a failed fetch.
 *
 * Hidden models are dropped: they are not in Codex's own picker, so offering
 * them in PortOS would surface ids the account cannot actually run.
 */
export const normalizeCodexModels = (result) => {
  if (!result || typeof result !== 'object') throw new Error('model/list returned a non-object result');
  const data = Array.isArray(result.data) ? result.data : (Array.isArray(result.models) ? result.models : null);
  if (!data) throw new Error('model/list returned no model array');
  return {
    models: data.map(normalizeModel).filter((model) => model !== null && !model.hidden),
    nextCursor: trimmed(result.nextCursor),
  };
};

/**
 * One token-usage breakdown, normalized to PortOS's field names, or `null`
 * when the payload carries no counts.
 *
 * `source: 'chatgpt-subscription'` is the attribution the criterion asks for:
 * the tokens are real, the dollar cost is NOT — a subscription turn has no
 * per-call price, and inventing one would corrupt the savings/quota views that
 * consume these records.
 */
export const normalizeCodexTokenUsage = (raw) => {
  if (!raw || typeof raw !== 'object') return null;
  // `total` first: PortOS's threads are ephemeral and carry exactly one turn, so
  // the thread total IS this turn's usage, while `last` counts only the final
  // model request. A turn that took a reasoning step then answered would
  // otherwise under-report by an order of magnitude.
  const breakdown = raw.total ?? raw.last ?? raw;
  if (!breakdown || typeof breakdown !== 'object') return null;
  const inputTokens = finiteInt(breakdown.inputTokens);
  const outputTokens = finiteInt(breakdown.outputTokens);
  const totalTokens = finiteInt(breakdown.totalTokens);
  if (inputTokens === null && outputTokens === null && totalTokens === null) return null;
  return {
    inputTokens: inputTokens ?? 0,
    outputTokens: outputTokens ?? 0,
    cachedInputTokens: finiteInt(breakdown.cachedInputTokens) ?? 0,
    reasoningOutputTokens: finiteInt(breakdown.reasoningOutputTokens) ?? 0,
    totalTokens: totalTokens ?? ((inputTokens ?? 0) + (outputTokens ?? 0)),
    modelContextWindow: finiteInt(raw.modelContextWindow),
    source: 'chatgpt-subscription',
  };
};

/**
 * Which reasoning effort a turn should carry.
 *
 * The rule mirrors the existing Codex provider's visible clamp: an effort the
 * model does not advertise is reported as clamped to the model's own default
 * rather than silently sent and rejected mid-turn. A model whose catalog entry
 * PortOS has never fetched (`supportedEfforts: []`) is NOT evidence that the
 * effort is unsupported, so the request passes through untouched.
 */
export const resolveCodexEffort = (requested, model = null) => {
  const want = trimmed(requested);
  if (!want) return { effort: null, clamped: false, reason: null };
  const supported = Array.isArray(model?.supportedEfforts) ? model.supportedEfforts : [];
  if (supported.length === 0 || supported.includes(want)) return { effort: want, clamped: false, reason: null };
  const fallback = trimmed(model?.defaultEffort);
  return {
    effort: fallback,
    clamped: true,
    reason: `${model?.id || 'the selected model'} does not support "${want}" reasoning effort`
      + (fallback ? ` — using "${fallback}"` : ' — using the model default'),
  };
};

/**
 * Codex error identifiers that mean the SUBSCRIPTION is spent rather than the
 * request being wrong. Both spellings the protocol uses are listed because a
 * miss here degrades to a generic bench, which is the safe side.
 */
const QUOTA_ERROR_INFO = new Set(['usageLimitExceeded', 'sessionBudgetExceeded']);
const RATE_LIMIT_ERROR_INFO = new Set(['rateLimitExceeded', 'serverOverloaded']);
const AUTH_ERROR_INFO = new Set(['unauthorized']);

const errorInfoTag = (error) => {
  const info = error?.codexErrorInfo ?? error?.codex_error_info;
  if (typeof info === 'string') return info;
  if (info && typeof info === 'object') return Object.keys(info)[0] ?? null;
  return null;
};

/**
 * Map a `TurnError` (or a thrown transport error) onto the error category the
 * shared cooldown/fallback policy already understands.
 *
 * Returning a category rather than a bench duration keeps the policy in
 * `lib/providerCooldown.js` — one table, so a quota exhaustion benches for the
 * same window whichever path noticed it.
 */
export const classifyCodexTurnError = (error) => {
  const tag = errorInfoTag(error);
  // Scrubbed at the boundary: this message becomes a thrown error's text, which
  // `aiProvider` logs, reports through `ai:status`, and hands back to the caller
  // as `{ error }` — and an upstream failure can quote the credential.
  const message = redactCodexMessage(error?.message) || 'The Codex turn failed';
  if (QUOTA_ERROR_INFO.has(tag)) return { category: ERROR_CATEGORIES.USAGE_LIMIT, message };
  if (RATE_LIMIT_ERROR_INFO.has(tag)) return { category: ERROR_CATEGORIES.RATE_LIMIT, message };
  if (AUTH_ERROR_INFO.has(tag)) return { category: ERROR_CATEGORIES.AUTH_ERROR, message };
  // 'context-length' is one of providerCooldown's SCHEMA_TYPE categories rather
  // than an ERROR_CATEGORIES member: an oversized prompt is REQUEST-specific, so
  // it must shrink and retry, never bench the subscription for every other call.
  if (tag === 'contextWindowExceeded') return { category: 'context-length', message };
  if (['cyberPolicy', 'cyber_policy', 'misalignmentPolicyViolation', 'misalignment_policy_violation'].includes(tag)) {
    return { category: ERROR_CATEGORIES.CONTENT_REFUSAL, message };
  }
  if (tag === 'httpConnectionFailed' || tag === 'responseStreamConnectionFailed'
    || tag === 'responseStreamDisconnected' || tag === 'responseTooManyFailedAttempts') {
    return { category: ERROR_CATEGORIES.NETWORK_ERROR, message };
  }
  if (tag === 'badRequest') return { category: ERROR_CATEGORIES.MODEL_NOT_FOUND, message };
  // No structured tag: fall back to the account module's text heuristics for
  // the one case that must not be missed — a sign-in that is simply gone.
  if (/\b(401|unauthorized|unauthenticated|invalid[_ -]?grant|token (?:expired|revoked)|re-?authenticate)\b/i.test(message)) {
    return { category: ERROR_CATEGORIES.AUTH_ERROR, message };
  }
  if (/\busage limit|quota (?:exceeded|exhausted)|out of credits\b/i.test(message)) {
    return { category: ERROR_CATEGORIES.USAGE_LIMIT, message };
  }
  return { category: ERROR_CATEGORIES.UNKNOWN, message };
};

/**
 * The error category for anything the transport can throw — a protocol/process
 * failure as well as a model-side `TurnError`.
 *
 * Two failure shapes reach a caller: a typed `ServerError` from the app-server
 * client (the binary is missing, the child died, a request timed out) and a
 * classified turn failure carried on `context.category`. Folding both here
 * means the cooldown/fallback decision reads ONE vocabulary — the same
 * `ERROR_CATEGORIES` every other provider path uses.
 */
export const classifyCodexTransportError = (err) => {
  const carried = err?.context?.category;
  if (typeof carried === 'string' && carried) return carried;
  switch (err?.code) {
    case CODEX_ERROR_CODES.runtimeMissing:
    case CODEX_ERROR_CODES.startFailed:
    case CODEX_ERROR_CODES.exited:
      return ERROR_CATEGORIES.SPAWN_ERROR;
    case CODEX_ERROR_CODES.timeout:
      return ERROR_CATEGORIES.TIMEOUT;
    case CODEX_ERROR_CODES.authRevoked:
      return ERROR_CATEGORIES.AUTH_ERROR;
    case CODEX_TURN_ERROR_CODES.turnInterrupted:
      return ERROR_CATEGORIES.CANCELED;
    default:
      return classifyCodexTurnError({ message: err?.message }).category;
  }
};

// `MessagePhase` in the app-server protocol: interim narration vs the answer.
const CODEX_COMMENTARY_PHASE = 'commentary';

/** A fresh accumulator for one turn. */
export const createTurnAccumulator = ({ threadId = null, turnId = null } = {}) => ({
  threadId,
  turnId,
  deltas: [],
  finalText: null,
  usage: null,
  error: null,
  status: 'inProgress',
});

const appendText = (acc, text) => {
  if (typeof text !== 'string' || text === '') return;
  acc.deltas.push(text);
};

/**
 * Fold one server notification into the accumulator.
 *
 * Frames for another thread or another turn are ignored rather than merged —
 * one app-server connection is shared by every caller, so a concurrent turn's
 * deltas must never leak into this one's answer.
 *
 * Returns `true` when the turn has reached a terminal state.
 */
export const applyCodexTurnEvent = (acc, method, params) => {
  // Already terminal: report it as such so a late frame cannot settle the turn
  // a second time, and never fold it into the answer.
  if (!acc || acc.status !== 'inProgress') return true;
  if (!params || typeof params !== 'object') return false;
  // Enforced HERE, not only in the caller that routes by thread: this function's
  // contract says another thread's frames are ignored, and its own tests drive
  // it directly.
  if (acc.threadId && typeof params.threadId === 'string' && params.threadId !== acc.threadId) return false;
  if (acc.turnId && typeof params.turnId === 'string' && params.turnId !== acc.turnId) return false;
  // Latch the id from the first frame that carries one. `turn/start`'s own
  // response also sets it, but a delta can arrive first (or that response can be
  // delayed) — and without an id the caller cannot `turn/interrupt` a cancelled
  // turn, which would leave it consuming subscription quota until it ends.
  if (!acc.turnId && typeof params.turnId === 'string' && params.turnId) acc.turnId = params.turnId;

  switch (method) {
    case CODEX_TURN_NOTIFICATIONS.turnStarted:
      // The earliest frame that carries the id, and the only one at all when a
      // turn produces no deltas. Without it a lost `turn/start` response leaves
      // the turn un-interruptible, so cancelling it would keep burning quota.
      if (!acc.turnId && typeof params.turn?.id === 'string') acc.turnId = params.turn.id;
      return false;
    case CODEX_TURN_NOTIFICATIONS.agentMessageDelta:
      appendText(acc, params.delta);
      return false;
    case CODEX_TURN_NOTIFICATIONS.itemCompleted:
      // A turn can emit several agent messages, so completed items CONCATENATE.
      // Within one message the completed item is authoritative and the deltas
      // that previewed it are dropped — appending both would double the prose —
      // while deltas that arrive AFTER it belong to the next message and are
      // still carried by `finalizeCodexTurn`.
      //
      // Newer models narrate before answering: an interim `commentary` message
      // ("I'll review the diff…") precedes the `final_answer` one. Folding that
      // narration into the answer turns a JSON envelope into prose-then-JSON
      // that no parser accepts (#9969), so a commentary item is dropped along
      // with the deltas that previewed it. `phase: null` is "unknown" — legacy
      // models never set it — and keeps the concatenating behavior.
      if (params.item?.type === 'agentMessage' && typeof params.item.text === 'string') {
        if (params.item.phase !== CODEX_COMMENTARY_PHASE) {
          acc.finalText = acc.finalText === null ? params.item.text : `${acc.finalText}${params.item.text}`;
        }
        acc.deltas.length = 0;
      }
      return false;
    case CODEX_TURN_NOTIFICATIONS.tokenUsage:
      acc.usage = normalizeCodexTokenUsage(params.tokenUsage) ?? acc.usage;
      return false;
    case CODEX_TURN_NOTIFICATIONS.error:
      // `willRetry` means the app-server is still working the turn — recording
      // it as terminal here would abandon a run that is about to succeed.
      if (params.willRetry === true) return false;
      acc.error = classifyCodexTurnError(params.error);
      acc.status = 'failed';
      return true;
    case CODEX_TURN_NOTIFICATIONS.turnCompleted: {
      const turn = params.turn;
      // A completion naming a DIFFERENT turn is somebody else's. One naming no
      // turn at all is still ours: the frame already reached this accumulator by
      // thread, and PortOS's threads are ephemeral with exactly one turn — so
      // rejecting it would discard a finished answer and hang the call until its
      // deadline over a field the server merely left off the envelope.
      if (acc.turnId && typeof turn?.id === 'string' && turn.id !== acc.turnId) return false;
      // A frame with no status is MALFORMED, and defaulting it to 'completed'
      // would hand the caller whatever text had streamed so far as a finished
      // answer. `finalizeCodexTurn` errors on anything that is not 'completed',
      // so an unrecognizable status fails the turn instead.
      acc.status = typeof turn?.status === 'string' && turn.status ? turn.status : 'malformed';
      if (acc.status === 'failed') acc.error = classifyCodexTurnError(turn?.error);
      return true;
    }
    default:
      return false;
  }
};

/**
 * The finished turn as PortOS's `{ text, usage }` contract, or a thrown-shaped
 * `{ error }`.
 *
 * A non-`completed` status NEVER yields text. That is the "partial output is
 * never accepted as complete structured data" rule: an interrupted turn's
 * half-written JSON would parse into plausible, wrong data, so the caller gets
 * an error and its own fallback path instead.
 */
export const finalizeCodexTurn = (acc) => {
  if (!acc) return { error: 'The Codex turn produced no result', category: ERROR_CATEGORIES.UNKNOWN };
  if (acc.status === 'failed') {
    return { error: acc.error?.message || 'The Codex turn failed', category: acc.error?.category || ERROR_CATEGORIES.UNKNOWN };
  }
  if (acc.status === 'interrupted') {
    return { error: 'The Codex turn was cancelled', category: ERROR_CATEGORIES.CANCELED, canceled: true };
  }
  if (acc.status !== 'completed') {
    return { error: 'The Codex turn ended without completing', category: ERROR_CATEGORIES.UNKNOWN };
  }
  // Completed items plus any deltas streamed after the last one — a trailing
  // message with no closing `item/completed` must not be silently dropped.
  const text = `${acc.finalText ?? ''}${acc.deltas.join('')}`;
  if (!text.trim()) {
    return { error: 'Codex returned an empty completion', category: ERROR_CATEGORIES.UNKNOWN };
  }
  return { text, usage: acc.usage };
};