@agentvault/openai-bridge 0.1.13 → 0.1.14

package/README.md

@@ -42,13 +42,13 @@ If Codex is upgraded, install the supported version again before restarting. If
 AV_AGENT_NAME=aster AV_INVITE_TOKEN='<fresh-invite>' agentvault-openai-bridge replace
 ```
 
-Replacement acquires the agent lock before archiving prior AgentVault credentials under the private `replacement-recovery/<uuid>/` directory and forcing enrollment. Codex login and history are retained. Existing credentials are never silently reused for this explicit command. If enrollment fails, the archive remains for deliberate operator recovery; normal restarts do not restore it automatically. After approval, stop the foreground process and install the service again. Do not copy another agent's credentials into this state directory.
+Replacement acquires the agent lock before archiving prior AgentVault credentials under the private `replacement-recovery/<uuid>/` directory and forcing enrollment. Codex login and history are retained. This explicit command never reuses existing credentials silently. If enrollment fails, the archive remains for deliberate operator recovery; normal restarts do not restore it automatically. After approval, stop the foreground process and install the service again. Do not copy another agent's credentials into this state directory.
 
 The shared SecureChannel currently persists new enrollment keys only after activation. A crash before approval can leave the invite consumed without recoverable local keys. Retaining `pending-invite` does not solve that gap: obtain a fresh recovery invite if the interrupted enrollment cannot resume.
 
 ## Conversation and privacy boundaries
 
-Only direct messages positively attested by SecureChannel as owner 1:1 messages can dispatch a private turn. Rooms answer according to AgentVault's shared mention policy, evaluated on the typed caption, and remain silent while hushed. Recent context comes only from the addressed room. Replies are bound to the original conversation ID or room ID. Device ID, conversation kind, and conversation ID jointly select a separate persistent Codex session UUID; the bridge never resumes “last”.
+Only direct messages positively attested by SecureChannel as owner 1:1 messages can dispatch a private turn. Rooms answer according to AgentVault's shared mention policy, evaluated on the typed caption, and remain silent while hushed. Rooms use recent messages from the addressed room; a 1:1 that starts a new Codex session is seeded with that 1:1's recent messages only. A chat opened from a browser the agent has not mapped yet may start without earlier messages until the agent learns which person it belongs to. Replies are bound to the original conversation ID or room ID. Device ID, conversation kind, and conversation ID jointly select a separate persistent Codex session UUID; the bridge never resumes “last”.
 
 Each agent stores its state beneath `~/.agentvault/openai/<name-slug>/`, including isolated `home`, `codex`, `work`, `tmp`, and `sessions` directories (0700). Codex auth and local conversation transcripts persist there. Encryption protects AgentVault transport; local Codex history is plaintext and relies on the host account's filesystem protections. Do not share this directory.
 
@@ -56,6 +56,31 @@ Codex children receive only a dedicated HOME, CODEX_HOME, TMPDIR, and a minimal
 
 The bridge accepts only a terminal successful assistant reply after exit 0. Because the exec stream omits message phase, it additionally verifies the current turn's `final_answer` in the bounded local Codex rollout; a prior resumed turn or commentary cannot authorize delivery. Partial, failed, malformed, oversized or timed-out turns are discarded. Disconnect and shutdown invalidate pending results. One bounded queue serializes inference and awaited sending; child process groups are killed and reaped before another turn starts. Logs contain bridge-owned status codes, without prompts, replies, tokens or provider diagnostics.
 
+## When a reply fails
+
+When a turn fails, the bridge records it first and then tells the chat. It does not drop a failed turn without a trace.
+
+- **In a 1:1**, the owner sees one plain sentence that names the cause when the bridge can tell what it is. For example: "Aster couldn't answer this message: its OpenAI sign-in expired. Sign in again on the agent's computer." This bridge can also tell when OpenAI can't be reached and when the Codex CLI needs attention. The shared list also covers billing problems, rate limits and retired models, but this bridge does not detect those yet. When the cause is unclear, the sentence simply says the agent couldn't answer this message.
+- **In a room**, the sentence does not name the cause, because other people and agents can read it. The room just sees that the agent couldn't answer this message.
+- **In both cases**, the exact cause appears privately to the owner in the app under **Health, Recent problems**.
+
+These failure notices are left out of the context the bridge sends to Codex on later turns.
+
+The bridge log (`agentvault-openai-bridge logs`) writes one line per event:
+
+| Log line | What it means |
+|----------|---------------|
+| `turn_failed code=<code> exit=<n or none>` | Codex did not produce a verified reply. The code is the cause the bridge assigned, and `exit` is the Codex exit status, or `none` when there is no exit status to report. A notice follows. |
+| `reply_failed code=<code>` | Codex answered, but the reply could not be delivered to the chat. |
+| `notice_failed code=<code>` | The turn failed, and the failure notice could not be delivered either. The failure is still recorded under Health. |
+| `turn_cancelled reason=<reason>` | The turn was cut short before it could finish, so no reply or notice is posted. Reasons: `stop` (the bridge is shutting down), `revoked` (the agent's device was revoked), `channel_state` (the encrypted channel dropped or reconnected), `delivery_timeout` (sending took too long), `hushed` (the room was hushed), `device_changed` (the agent's device ID changed), and `unknown`. |
+| `turn_recovered code=session_resume_failed` | The saved Codex session for this chat was gone, so the bridge started a fresh one and its reply passed the final-answer check. Delivery is then logged as usual. See below. |
+| `dm_dropped reason=unmapped_conversation` | A 1:1 message arrived that the agent cannot yet match to a conversation. That message got no answer and no notice yet. |
+
+**Self-restart of a saved session.** Each chat keeps its own saved Codex session in the `sessions` directory. If that saved session can no longer be found, the bridge runs one fresh session, seeded with the recent messages of that same chat. It replaces the saved session only after the fresh reply passes the same final-answer check as any other reply. The first session it replaced is kept in a `.prev` file next to it, and that file is never overwritten, so a later restart cannot erase the original. If the fresh session also fails, nothing is replaced and the turn is reported as `turn_failed`.
+
+The log holds only these codes and exit numbers. It never holds message text or provider error text.
+
 ## Local checks
 
 ```sh

package/dist/bridge.d.ts

@@ -16,6 +16,13 @@ export interface BridgeChannel {
         text: string;
         sender: string;
     }>;
+    /** #1560: one person's 1:1 history, scoped by the group the frame decrypted under. */
+    getConversationHistory?(id: string, max: number, opts?: {
+        groupId?: string;
+    }): Array<{
+        text: string;
+        sender: string;
+    }>;
     send(text: string, options: {
         conversationId: string;
     }): Promise<unknown>;
@@ -33,7 +40,9 @@ export interface BridgeChannel {
     } & Partial<ToolSpanSink>) | null;
 }
 export interface TurnDriver {
-    run(key: string, prompt: string, signal?: AbortSignal): Promise<TurnResult>;
+    run(key: string, prompt: string, signal?: AbortSignal, opts?: {
+        freshContext?: string;
+    }): Promise<TurnResult>;
 }
 /** Serial inference AND delivery; every queued entry owns its authenticated target. */
 export declare class OpenAIBridge {
@@ -49,6 +58,8 @@ export declare class OpenAIBridge {
     private ready;
     private accepting;
     private waiting;
+    /** The reason each generation ended, keyed by the generation it ended (#1560). */
+    private cancelReasons;
     private stopped;
     private active?;
     private hush;
@@ -56,8 +67,20 @@ export declare class OpenAIBridge {
     constructor(channel: BridgeChannel, driver: TurnDriver, name: string, report?: (event: string) => void, maxQueue?: number, deliveryTimeoutMs?: number);
     private listen;
     private hushed;
+    /** Ends the current generation. Its reason is recorded BEFORE the bump, under
+     *  the generation it ends, so a later invalidate (stop after revoked) cannot
+     *  overwrite why the turns of that generation were cut. */
     private invalidate;
+    private cancelReason;
+    /** Recent entries as `sender: text`, without the bridge's own failure notices. */
+    private context;
     private enqueue;
+    /** #1560: a turn that failed (not one cancelled on purpose). RECORD FIRST —
+     *  the span and the log line — then post the notice, so a notice that stalls
+     *  or fails cannot lose the record. Only codes and the exit status are
+     *  logged, never the error's text. In a room the notice is the bare sentence:
+     *  the coded ones describe the owner's own provider account. */
+    private turnFailed;
     /** Health (2026-10-14): tokens for the model call. No cost — the bridge runs
      *  on a ChatGPT login, so there is no per-token price to report honestly. */
     private reportUsage;

package/dist/cli.d.ts

@@ -1,6 +1,6 @@
 import { type HistoryRecoveryCommandInput } from "@agentvault/agentvault";
 import { type Layout } from "./driver.js";
-export declare const VERSION = "0.1.13";
+export declare const VERSION = "0.1.14";
 export interface RunConfig {
     name: string;
     apiUrl: string;

package/dist/driver.d.ts

@@ -1,5 +1,10 @@
+import { type TurnFailureCode } from "@agentvault/agentvault";
 export declare const SUPPORTED_CODEX_VERSION = "0.154.0";
 export declare const CODE_MODE_WARNING = "Code Mode is unavailable because code-mode host is disabled. Code mode will fail closed; enable `features.code_mode_host` and install `codex-code-mode-host`.";
+/** #1560 — observed on 0.154.0 as an `item.completed` error item when the
+ *  model name has no local metadata. Codex carries on and answers, so it is a
+ *  warning, not a failed turn (like CODE_MODE_WARNING). */
+export declare const MODEL_METADATA_WARNING: RegExp;
 export interface Layout {
     root: string;
     home: string;
@@ -17,7 +22,29 @@ export declare function buildInvocation(layout: Layout, sessionId?: string): {
     cwd: string;
 };
 export declare function resolveCodex(path?: string): Promise<string>;
-export declare function checkVersion(binary: string, layout: Layout): Promise<void>;
+/**
+ * #1560 (audit-3 F7): a `--version` that does not answer in time is a slow or
+ * loaded machine, not a wrong install, so it is the bare `model_error`. Only a
+ * binary that cannot run at all, or answers with the wrong version, is
+ * `ai_tool_unsupported`. No retry here: on a machine that is already slow a
+ * retry doubles the wait (follow-up 10).
+ */
+export declare function checkVersion(binary: string, layout: Layout, timeoutMs?: number): Promise<void>;
+/**
+ * #1560 — map Codex failure text to a shared turn-failure code. Only a code
+ * comes back; the text itself is never kept, logged or thrown.
+ *
+ * Every branch is a literal `return "<code>"` on purpose: the plugin's
+ * tool-error-codes.test.ts scans this file for `return "<code>"` and checks
+ * each against KNOWN_TOOL_ERROR_CODES. A lookup table, ternary or variable
+ * would hide a code from that scan, so do not refactor this into one.
+ *
+ * Only shapes observed from Codex 0.154.0 are matched; anything else is the
+ * bare `model_error`.
+ * TODO(#1560 follow-up): the usage-limit strings map to plan_limit_reached,
+ * and when billing and rate-limit rules are added, billing must precede rate.
+ */
+export declare function classifyCodexFailure(text: string): TurnFailureCode;
 /** The one model this bridge runs (pinned in buildInvocation). */
 export declare const CODEX_MODEL = "gpt-5.6-terra";
 /** Token usage Codex reports on `turn.completed`, for Health (2026-10-14). */
@@ -43,6 +70,14 @@ export interface DriverOptions {
     killGraceMs?: number;
     maxLineBytes?: number;
     maxOutputBytes?: number;
+    /** `--version` timeout (default 5000 ms). */
+    versionTimeoutMs?: number;
+    /** Called once after a refused resume was replaced by a fresh, verified session. */
+    onRecovered?: (code: "session_resume_failed") => void;
+}
+export interface RunOptions {
+    /** Recent messages of this conversation, sent only when a session starts fresh. */
+    freshContext?: string;
 }
 /** One caller at a time. The bridge serializes delivery as well as inference. */
 export declare class CodexDriver {
@@ -50,7 +85,13 @@ export declare class CodexDriver {
     private busy;
     private poisoned;
     constructor(options: DriverOptions);
-    run(key: string, prompt: string, signal?: AbortSignal): Promise<TurnResult>;
+    run(key: string, prompt: string, signal?: AbortSignal, opts?: RunOptions): Promise<TurnResult>;
+    /**
+     * #1560 — the stored session is gone: run exactly one fresh, seeded session.
+     * The stored id is replaced only after the fresh reply verifies; the first
+     * replaced id is kept in `<file>.prev` and never overwritten.
+     */
+    private recover;
     private execute;
 }
 //# sourceMappingURL=driver.d.ts.map