polygram 0.21.0 → 0.23.0

package/lib/error/classify.js

@@ -131,10 +131,136 @@ const AUTO_RECOVER = {
   imageProcess:     'reset_session',
 };
 
+function stableCodeShape(kind, userMessage) {
+  return Object.freeze({
+    kind,
+    userMessage,
+    isTransient: false,
+    autoRecover: null,
+  });
+}
+
+function mapCodes(codes, shape) {
+  return Object.fromEntries(codes.map((code) => [code, shape]));
+}
+
+const CODEX_ERROR_SHAPES = Object.freeze({
+  auth: stableCodeShape(
+    'codexAuthUnavailable',
+    '🔑 Codex authentication is unavailable. The operator needs to re-authenticate the pinned deployment.',
+  ),
+  model: stableCodeShape(
+    'codexModelUnavailable',
+    '⚠️ That Codex model or reasoning effort is unavailable. Choose one from the authenticated Codex catalog.',
+  ),
+  rateLimit: stableCodeShape(
+    'codexRateLimited',
+    '⏳ Codex is rate-limited. Codex owns any provider retry; otherwise wait before sending a new request.',
+  ),
+  protocol: stableCodeShape(
+    'codexProtocol',
+    '🧩 Codex protocol or runtime pin verification failed. The operator must restore the reviewed deployment.',
+  ),
+  timeout: stableCodeShape(
+    'codexTimeout',
+    '⏳ Codex timed out. No automatic retry was started; check Codex status before taking action.',
+  ),
+  cancelled: stableCodeShape(
+    'codexCancelled',
+    '🛑 The Codex request was cancelled. No automatic retry was started.',
+  ),
+  durability: stableCodeShape(
+    'codexDurability',
+    '⚠️ Codex could not verify this request’s durable outcome. Do not resend automatically; check status and follow operator recovery guidance.',
+  ),
+  childExit: stableCodeShape(
+    'codexChildExit',
+    '⚠️ The Codex app-server exited unexpectedly. The outcome may be unknown; wait for operator diagnostics before sending more work.',
+  ),
+  notSent: stableCodeShape(
+    'codexNotSent',
+    '↩️ Codex did not receive this request. It is safe to try again.',
+  ),
+  providerError: stableCodeShape(
+    'codexProviderError',
+    '⚠️ Codex rejected the request. No automatic retry was started; check Codex status.',
+  ),
+  busy: stableCodeShape(
+    'codexBusy',
+    '⏳ Another chat owns this daemon’s native Codex runtime. No session or configuration was changed.',
+  ),
+});
+
+const CODEX_ERROR_CODES = {
+  ...mapCodes([
+    'CODEX_AUTH_UNAVAILABLE',
+  ], CODEX_ERROR_SHAPES.auth),
+  ...mapCodes([
+    'CODEX_MODEL_UNAVAILABLE',
+    'CODEX_EFFORT_UNAVAILABLE',
+    'CODEX_MODEL_SELECTION_MISMATCH',
+  ], CODEX_ERROR_SHAPES.model),
+  ...mapCodes([
+    'CODEX_RATE_LIMITED',
+    'CODEX_RATE_LIMIT_EXCEEDED',
+  ], CODEX_ERROR_SHAPES.rateLimit),
+  ...mapCodes([
+    'CODEX_PROTOCOL_ERROR',
+    'CODEX_SERVER_REQUEST_DENIED',
+    'CODEX_RUNTIME_PIN_MISMATCH',
+    'CODEX_STATIC_PROFILE_MISMATCH',
+    'CODEX_THREAD_POLICY_MISMATCH',
+    'CODEX_PREFLIGHT_UNEXPECTED_NOTIFICATION',
+    'CODEX_PREFLIGHT_CLIENT_FAULT',
+    'CODEX_RUNTIME_CLIENT_FAULT',
+  ], CODEX_ERROR_SHAPES.protocol),
+  ...mapCodes([
+    'CODEX_RPC_TIMEOUT',
+    'CODEX_TURN_START_TIMEOUT',
+    'CODEX_TURN_TIMEOUT',
+    'CODEX_INTERRUPT_TIMEOUT',
+    'CODEX_TERMINAL_CLEANUP_TIMEOUT',
+    'CODEX_SINK_TIMEOUT',
+    'CODEX_PROCESS_CLOSE_TIMEOUT',
+    'CODEX_CONTAINMENT_CLOSE_TIMEOUT',
+  ], CODEX_ERROR_SHAPES.timeout),
+  ...mapCodes([
+    'CODEX_SINK_ABORTED',
+    'CODEX_CLIENT_CLOSED',
+    'CODEX_PROCESS_CLOSED',
+    'CODEX_PROCESS_QUIESCING',
+    'CODEX_LIFECYCLE_SUPERSEDED',
+  ], CODEX_ERROR_SHAPES.cancelled),
+  ...mapCodes([
+    'CODEX_DURABILITY_FAILED',
+    'CODEX_RPC_CHECKPOINT_FAILED',
+    'CODEX_GENERATION_NOT_DURABLE',
+    'CODEX_DISPATCH_STEER_NOT_DURABLE',
+    'CODEX_QUEUE_SETTLEMENT_NOT_DURABLE',
+    'CODEX_RETIREMENT_UNVERIFIED',
+    'CODEX_RPC_OUTCOME_UNKNOWN',
+    'CODEX_CONTAINMENT_FAILED',
+    'CODEX_CONTAINMENT_QUARANTINED',
+    'CODEX_BOOT_RECONSTRUCTION_FAILED',
+    'CODEX_BOOT_RECONSTRUCTION_REQUIRED',
+    'CODEX_PERSISTED_IDENTITY_MISSING',
+  ], CODEX_ERROR_SHAPES.durability),
+  ...mapCodes([
+    'CODEX_PROCESS_EXITED',
+    'CODEX_PROCESS_ERROR',
+    'CODEX_TRANSPORT_ERROR',
+    'CODEX_PROCESS_CLEANUP_UNVERIFIED',
+  ], CODEX_ERROR_SHAPES.childExit),
+  CODEX_RPC_NOT_SENT: CODEX_ERROR_SHAPES.notSent,
+  CODEX_RPC_ERROR: CODEX_ERROR_SHAPES.providerError,
+  CODEX_DAEMON_GENERATION_BUSY: CODEX_ERROR_SHAPES.busy,
+};
+
 // Typed-code short-circuits — set on errors polygram throws itself
 // (see lib/process-manager-sdk.js), not pattern-matched. Keep these
 // in sync with the codes pm emits.
 const CODES = {
+  ...CODEX_ERROR_CODES,
   // 0.7.6 (item H): queue cap drop. Pre-empts pattern matching so
   // the queue-overflow message is exact, not classified.
   QUEUE_OVERFLOW: {
@@ -284,9 +410,22 @@ function classify(err) {
   // Errors polygram constructs internally (QUEUE_OVERFLOW etc.) set
   // `err.code` so we don't depend on string content.
   const code = err?.code;
+  if (
+    code === 'CODEX_RPC_ERROR'
+    && (
+      err?.rpcCode === 429
+      || err?.providerCode === 'rate_limit'
+      || err?.providerCode === 'rate_limit_exceeded'
+    )
+  ) {
+    return { ...CODEX_ERROR_SHAPES.rateLimit };
+  }
   if (code && CODES[code]) {
     return { ...CODES[code] };
   }
+  if (typeof code === 'string' && /^CODEX_[A-Z0-9_]+$/.test(code)) {
+    return { ...CODEX_ERROR_SHAPES.providerError };
+  }
 
   // SDKAssistantMessage.error is a short string code from a fixed
   // union — match those directly, not via regex. Result subtypes
@@ -475,6 +614,7 @@ function classifyTurnEndError(err) {
   // one (regression caught in the 0.16 code review).
   const isTimeout = code === 'TURN_TIMEOUT'
     || code === 'TURN_MAX_EXCEEDED'
+    || CODES[code]?.kind === 'codexTimeout'
     || /wall-clock ceiling|idle with no Claude activity/i.test(err?.message || '');
   return { errorSuffix: 'stream interrupted', reactorState: isTimeout ? 'TIMEOUT' : 'ERROR' };
 }

package/lib/handlers/abort.js

@@ -8,16 +8,17 @@
  *   1. Mark the session aborted BEFORE the SDK interrupt fires —
  *      pm-sdk's close handler races; if we marked after, the
  *      generic error-reply could slip through.
- *   2. Tiered cancel (cheap by default, 2026-06-12): in-place
- *      interrupt keeps the proc warm (no --resume); kill only for
- *      ghosts / detached background shells / unverifiable state.
- *   3. pm.drainQueue() — rejects queued pendings with
+ *   2. pm.drainQueue() — rejects queued pendings with
  *      err.code='INTERRUPTED' so the abort-grace classifier
  *      suppresses error replies on the way out.
+ *   3. Stop through the backend contract. Claude CLI keeps its
+ *      tiered cheap-interrupt/kill behavior; Codex delegates its
+ *      exact terminal/clean/empty proof to ProcessManager.
  *   4. Clear ✍ reactions on already-autosteered messages from
  *      this turn (now dead context).
  *   5. Acknowledge with a 👍 reaction on the stop message when
- *      something was stopped; silence otherwise. Never text.
+ *      stopping was verified. A Codex containment failure gets the
+ *      existing error reaction instead. Never text.
  *
  * Returns true when the message was handled as an abort, false
  * otherwise. Caller short-circuits on true.
@@ -25,6 +26,41 @@
 
 'use strict';
 
+const CODEX_ACTIVE_STATES = new Set([
+  'StartingTurn',
+  'Active',
+  'Settling',
+  'BackgroundWorking',
+  'BackgroundSettling',
+  'Quiescing',
+]);
+
+const SAFE_CODEX_STOP_ERROR_CODES = new Set([
+  'CODEX_BACKGROUND_OWNERSHIP_UNKNOWN',
+  'CODEX_CONTAINMENT_CLOSE_TIMEOUT',
+  'CODEX_CONTAINMENT_FAILED',
+  'CODEX_DURABILITY_FAILED',
+  'CODEX_INTERRUPT_TIMEOUT',
+  'CODEX_INTERRUPT_UNMATCHED',
+  'CODEX_LIFECYCLE_SUPERSEDED',
+  'CODEX_PROCESS_CLOSED',
+  'CODEX_PROCESS_EXITED',
+  'CODEX_PROTOCOL_ERROR',
+  'CODEX_RETIREMENT_UNVERIFIED',
+  'CODEX_RPC_CHECKPOINT_FAILED',
+  'CODEX_RPC_ERROR',
+  'CODEX_RPC_NOT_SENT',
+  'CODEX_RPC_OUTCOME_UNKNOWN',
+  'CODEX_TERMINAL_CLEANUP_TIMEOUT',
+  'CODEX_TURN_START_TIMEOUT',
+]);
+
+function safeCodexStopErrorCode(error, fallback) {
+  return SAFE_CODEX_STOP_ERROR_CODES.has(error?.code)
+    ? error.code
+    : fallback;
+}
+
 function createHandleAbort({
   pm,
   bot,
@@ -49,6 +85,108 @@ function createHandleAbort({
     const proc = pm.has(sessionKey) ? pm.get(sessionKey) : null;
     let hadActive = !!proc?.inFlight;
 
+    // Codex has an explicit verified stop protocol in Orchestra:
+    // queued sends are cancelled, the exact active turn is reconciled,
+    // background terminals are cleaned, and a fresh empty registry is
+    // durably observed before ProcessManager resolves true. Do not mix that
+    // contract with the Claude CLI pane/shell heuristics below.
+    if (proc?.backend === 'codex') {
+      hadActive = hadActive || CODEX_ACTIVE_STATES.has(proc.state);
+      let markedAborted = false;
+      if (hadActive) {
+        markSessionAborted(sessionKey);
+        markedAborted = true;
+      }
+
+      let queueDrained = 0;
+      let queueDrainErrorCode = null;
+      try {
+        const count = pm.drainQueue(sessionKey, 'INTERRUPTED');
+        if (Number.isSafeInteger(count) && count > 0) queueDrained = count;
+      } catch (error) {
+        queueDrainErrorCode = safeCodexStopErrorCode(
+          error,
+          'CODEX_QUEUE_DRAIN_FAILED',
+        );
+        logger.error?.(
+          `[${botName}] Codex queue drain failed (${queueDrainErrorCode})`,
+        );
+      }
+      if (queueDrained > 0 && !markedAborted) {
+        markSessionAborted(sessionKey);
+      }
+
+      let feedbackClearErrorCode = null;
+      try {
+        await clearAutosteeredReactions(sessionKey);
+      } catch (error) {
+        feedbackClearErrorCode = safeCodexStopErrorCode(
+          error,
+          'CODEX_FEEDBACK_CLEAR_FAILED',
+        );
+        logger.error?.(
+          `[${botName}] Codex stop feedback clear failed (${feedbackClearErrorCode})`,
+        );
+      }
+
+      let stopVerified = false;
+      let stopErrorCode = null;
+      try {
+        stopVerified = await pm.interrupt(sessionKey) === true;
+        if (!stopVerified) stopErrorCode = 'CODEX_STOP_NOT_VERIFIED';
+      } catch (error) {
+        stopErrorCode = safeCodexStopErrorCode(
+          error,
+          'CODEX_STOP_FAILED',
+        );
+      }
+      if (!stopVerified) {
+        logger.error?.(
+          `[${botName}] Codex stop did not verify (${stopErrorCode})`,
+        );
+      }
+
+      logEvent('abort-requested', {
+        chat_id: chatId,
+        user_id: msg.from?.id || null,
+        backend: 'codex',
+        had_active: hadActive,
+        cancel_mode: stopVerified ? 'interrupt' : 'none',
+        kill_reason: null,
+        killed_background_shell: false,
+        busy_probe: null,
+        queue_drained: queueDrained,
+        queue_drain_error_code: queueDrainErrorCode,
+        feedback_clear_error_code: feedbackClearErrorCode,
+        stop_verified: stopVerified,
+        stop_error_code: stopErrorCode,
+        trigger: cleanText.slice(0, 40),
+      });
+
+      // 👍 means the complete native stop proof settled, not merely that an
+      // interrupt request was sent or acknowledged. A failed proof gets the
+      // existing error reaction instead, so containment failure is visible
+      // without introducing a text acknowledgement.
+      try {
+        await tg(bot, 'setMessageReaction', {
+          chat_id: chatId,
+          message_id: msg.message_id,
+          reaction: [{
+            type: 'emoji',
+            emoji: stopVerified ? '👍' : '🤯',
+          }],
+        }, {
+          source: stopVerified ? 'abort-ack' : 'abort-error',
+          botName,
+        });
+      } catch (error) {
+        logger.error?.(
+          `[${botName}] Codex stop reaction failed (TELEGRAM_REACTION_FAILED)`,
+        );
+      }
+      return true;
+    }
+
     // Mark BEFORE killing: the 'close' event fires almost immediately
     // after interrupt, and the surrounding handleMessage's catch
     // needs to see the flag to skip the generic error-reply.

package/lib/handlers/autosteer.js

@@ -36,6 +36,73 @@ function priorityFor(chatConfig, config) {
   return mode === 'queue' ? 'later' : 'next';
 }
 
+const QUEUEABLE_CODEX_STATES = new Set([
+  'Active',
+  'Idle',
+  'StartingTurn',
+]);
+
+const AMBIGUOUS_STEER_ERROR_CODES = new Set([
+  'CODEX_RPC_OUTCOME_UNKNOWN',
+  'CODEX_RPC_CHECKPOINT_FAILED',
+  'CODEX_DURABILITY_FAILED',
+  'CODEX_RPC_ERROR',
+]);
+
+const OPAQUE_ID_CONTROL_CHAR_RE = /[\x00-\x1f\x7f]/;
+
+function opaqueId(value) {
+  return (
+    typeof value === 'string'
+    && value.length > 0
+    && Buffer.byteLength(value, 'utf8') <= 512
+    && !OPAQUE_ID_CONTROL_CHAR_RE.test(value)
+  )
+    ? value
+    : null;
+}
+
+function codexGenerationId(entry) {
+  return opaqueId(entry?.generationId);
+}
+
+function isCodexEntry(pm, sessionKey, entry) {
+  const backend = typeof pm.getBackend === 'function'
+    ? pm.getBackend(sessionKey)
+    : entry?.backend;
+  return backend === 'codex' || entry?.runtime === 'codex';
+}
+
+function sameCodexGeneration(pm, sessionKey, generationId) {
+  const current = pm.get(sessionKey);
+  return {
+    current,
+    same: (
+      current != null
+      && codexGenerationId(current) === generationId
+    ),
+  };
+}
+
+function canQueueCodexNotSent(entry) {
+  return (
+    entry != null
+    && !entry.closed
+    && QUEUEABLE_CODEX_STATES.has(entry.state)
+  );
+}
+
+function codexClassification(outcome, priority, reason, detail = {}) {
+  return {
+    autosteered: false,
+    outcome,
+    queueOnce: outcome === 'queue-once',
+    priority,
+    reason,
+    ...detail,
+  };
+}
+
 function createAutosteerHandlers({
   config,
   pm,
@@ -94,7 +161,195 @@ function createAutosteerHandlers({
     return { autosteered: true, priority };
   }
 
-  return { willAutosteer, tryAutosteer };
+  /**
+   * Attempt a native Codex turn/steer RPC.
+   *
+   * The caller owns the per-session intent lock and the durable Telegram
+   * dispatch reservation. This function keeps that lock held by awaiting the
+   * RPC and returns a classification; it never performs the fallback send.
+   */
+  async function tryCodexAutosteer({
+    sessionKey,
+    chatConfig,
+    chatId,
+    msg,
+    prompt,
+  }) {
+    const priority = priorityFor(chatConfig, config);
+    if (!isAutosteerEnabledFor(chatConfig, config)) {
+      return codexClassification('not-applicable', priority, 'disabled');
+    }
+    if (!pm.has(sessionKey)) {
+      return codexClassification('not-applicable', priority, 'missing-session');
+    }
+
+    const entry = pm.get(sessionKey);
+    if (!isCodexEntry(pm, sessionKey, entry)) {
+      return codexClassification('not-applicable', priority, 'not-codex');
+    }
+    const generationId = codexGenerationId(entry);
+    if (!generationId) {
+      return codexClassification(
+        'unavailable',
+        priority,
+        'missing-generation-id',
+        {
+        generationId: null,
+        },
+      );
+    }
+    if (entry.closed || !entry.inFlight) {
+      return codexClassification(
+        'not-applicable',
+        priority,
+        entry.closed ? 'closed' : 'not-in-flight',
+        { generationId },
+      );
+    }
+
+    const expectedTurnId = opaqueId(entry.activeTurnId);
+    if (priority === 'later') {
+      return codexClassification('queue-once', priority, 'queue-mode', {
+        generationId,
+        turnId: expectedTurnId,
+      });
+    }
+
+    let result;
+    try {
+      result = await pm.steerTurn(sessionKey, prompt, {
+        context: { sourceMsgId: msg.message_id },
+      });
+    } catch (error) {
+      const observed = sameCodexGeneration(pm, sessionKey, generationId);
+      if (!observed.same) {
+        return codexClassification('ambiguous', priority, 'generation-changed', {
+          generationId,
+          observedGenerationId: codexGenerationId(observed.current),
+        });
+      }
+      if (
+        error?.code === 'CODEX_RPC_NOT_SENT'
+        && canQueueCodexNotSent(observed.current)
+      ) {
+        return codexClassification('queue-once', priority, 'rpc-not-sent', {
+          generationId,
+          turnId: expectedTurnId,
+        });
+      }
+      if (AMBIGUOUS_STEER_ERROR_CODES.has(error?.code)) {
+        return codexClassification(
+          'ambiguous',
+          priority,
+          error.code === 'CODEX_RPC_OUTCOME_UNKNOWN'
+            ? 'rpc-outcome-unknown'
+            : 'steer-outcome-ambiguous',
+          { generationId, errorCode: error.code },
+        );
+      }
+      return codexClassification(
+        'unavailable',
+        priority,
+        !QUEUEABLE_CODEX_STATES.has(observed.current?.state)
+          ? String(observed.current?.state || 'unavailable').toLowerCase()
+          : 'steer-failed',
+        { generationId, errorCode: opaqueId(error?.code) },
+      );
+    }
+
+    const observed = sameCodexGeneration(pm, sessionKey, generationId);
+    if (!observed.same) {
+      return codexClassification('ambiguous', priority, 'generation-changed', {
+        generationId,
+        observedGenerationId: codexGenerationId(observed.current),
+      });
+    }
+
+    const turnId = opaqueId(result?.turnId);
+    if (result?.outcome === 'queueable-not-active') {
+      if (!canQueueCodexNotSent(observed.current)) {
+        return codexClassification(
+          'unavailable',
+          priority,
+          String(observed.current?.state || result.reason || 'unavailable')
+            .toLowerCase(),
+          { generationId },
+        );
+      }
+      return codexClassification('queue-once', priority, 'not-active', {
+        generationId,
+        turnId,
+      });
+    }
+    if (result?.outcome === 'unavailable') {
+      return codexClassification(
+        'unavailable',
+        priority,
+        opaqueId(result.reason) || 'unavailable',
+        { generationId },
+      );
+    }
+    if (result?.outcome !== 'accepted') {
+      return codexClassification(
+        'ambiguous',
+        priority,
+        'unrecognized-steer-outcome',
+        { generationId },
+      );
+    }
+
+    const resultGenerationId = opaqueId(result.generationId);
+    const attemptId = opaqueId(result.attemptId);
+    const targetAttemptId = result.targetAttemptId == null
+      ? null
+      : opaqueId(result.targetAttemptId);
+    if (
+      !turnId
+      || !attemptId
+      || !targetAttemptId
+      || resultGenerationId !== generationId
+      || (expectedTurnId && turnId !== expectedTurnId)
+    ) {
+      return codexClassification(
+        'ambiguous',
+        priority,
+        'accepted-without-durable-identifiers',
+        {
+        generationId,
+        turnId,
+        attemptId,
+        targetAttemptId,
+        ...(resultGenerationId !== generationId
+          ? { observedGenerationId: resultGenerationId }
+          : {}),
+        },
+      );
+    }
+
+    autosteeredRefs.add(sessionKey, { chatId, msgId: msg.message_id });
+    logEvent('autosteer', {
+      chat_id: chatId,
+      msg_id: msg.message_id,
+      text_len: prompt?.length ?? 0,
+      priority,
+      backend: 'codex',
+      generation_id: generationId,
+      turn_id: turnId,
+      attempt_id: attemptId,
+      target_attempt_id: targetAttemptId,
+    });
+    return {
+      autosteered: true,
+      outcome: 'accepted',
+      priority,
+      generationId,
+      turnId,
+      attemptId,
+      targetAttemptId,
+    };
+  }
+
+  return { willAutosteer, tryAutosteer, tryCodexAutosteer };
 }
 
 module.exports = {