@jskit-ai/assistant-core 0.2.13 → 0.2.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant-core",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "type": "module",
   "scripts": {
     "test": "node --test --test-concurrency=1"
@@ -51,8 +51,8 @@
     "@ai-sdk/togetherai": "^3.0.49",
     "@ai-sdk/xai": "^4.0.58",
     "@jskit-ai/agent": "0.1.0",
-    "@jskit-ai/resource-core": "0.1.196",
-    "@jskit-ai/resource-crud-core": "0.1.196",
+    "@jskit-ai/resource-core": "0.1.197",
+    "@jskit-ai/resource-crud-core": "0.1.197",
     "@mdi/js": "^7.4.47",
     "@openrouter/ai-sdk-provider": "^3.0.0",
     "ai": "^7.0.152",
@@ -61,8 +61,8 @@
     "ws": "^8.20.1"
   },
   "peerDependencies": {
-    "@jskit-ai/http-runtime": "0.2.5",
-    "@jskit-ai/kernel": "0.2.5",
+    "@jskit-ai/http-runtime": "0.2.6",
+    "@jskit-ai/kernel": "0.2.6",
     "vue": "^3.5.13",
     "vuetify": "^4.0.0"
   },

package/src/server/conversation/boundedToolLoop.js

@@ -59,8 +59,10 @@ function boundedResponseSchema(outputSchema, descriptors) {
 
 /** Original bounded response/operation order, with one shared reply/tool protocol. */
 async function runBoundedAssistantToolLoop({ prompt, signal, policy, complete, outputSchema, limitError,
-  invalidResponseError = new Error("The assistant returned an invalid response."),
-  failureError = new Error("The assistant could not complete this request."), toolCatalog, toolContext,
+  invalidResponseError = Object.assign(new Error("The assistant returned an invalid response."), { messageCode: "assistant.turn.invalidResponse", messageParams: {} }),
+  failureError = Object.assign(new Error("The assistant could not complete this request."), {
+    messageCode: "assistant.turn.requestIncomplete", messageParams: {}
+  }), toolCatalog, toolContext,
   completedEnvelope = false, settle }) {
   if (typeof completedEnvelope !== "boolean") throw new TypeError("Completed envelope mode must be a boolean.");
   if (completedEnvelope && (policy.maximumResponses !== COMPLETED_ENVELOPE_RESPONSES || typeof settle !== "function")) {

package/src/server/conversation/claudeClient.js

@@ -3,8 +3,9 @@ import { TextDecoder } from "node:util";
 
 const CLAUDE_JSON_MAX_FRAME_BYTES = 16 * 1024 * 1024;
 
-function claudeProtocolError(message, code = "assistant_claude_protocol_error") {
-  return Object.assign(new Error(message), { code });
+// messageCode names the sentence, since one protocol code covers several.
+function claudeProtocolError(message, { code = "assistant_claude_protocol_error", params, messageCode } = {}) {
+  return Object.assign(new Error(message), { code, ...(params ? { params } : {}), ...(messageCode ? { messageCode, messageParams: {} } : {}) });
 }
 
 // Geometric growth keeps fragmented frames linear with bounded memory. Decode complete
@@ -116,7 +117,7 @@ function createClaudeJsonClient({
     }
     const next = writes.then(() => new Promise((resolve, reject) => {
       if (failure || closed || stream.destroyed) {
-        reject(failure || claudeProtocolError("Claude connection is closed."));
+        reject(failure || claudeProtocolError("Claude connection is closed.", { messageCode: "assistant.claude.connectionClosed" }));
         return;
       }
       // A write callback, unlike write()'s boolean return, respects backpressure
@@ -128,7 +129,7 @@ function createClaudeJsonClient({
   }
 
   async function request(request, options = {}) {
-    if (failure || closed) throw failure || claudeProtocolError("Claude connection is closed.");
+    if (failure || closed) throw failure || claudeProtocolError("Claude connection is closed.", { messageCode: "assistant.claude.connectionClosed" });
     const requestId = randomUUID();
     const { onProgress = reportNoProgress } = options;
     function progress(stage) {
@@ -139,7 +140,9 @@ function createClaudeJsonClient({
     const response = new Promise((resolve, reject) => {
       timer = setTimeout(() => {
         requests.delete(requestId);
-        reject(claudeProtocolError(`Claude ${request.subtype} timed out.`, "assistant_claude_control_timeout"));
+        reject(claudeProtocolError(`Claude ${request.subtype} timed out.`, {
+          code: "assistant_claude_control_timeout", params: { request: request.subtype }
+        }));
       }, options.timeoutMs ?? timeoutMs);
       requests.set(requestId, { resolve, reject, received: () => progress("response_received") });
     });
@@ -175,7 +178,7 @@ function createClaudeJsonClient({
         // Waiting here does not block the reader from answering interrupt controls.
         await precedingEvents;
         controller.signal.throwIfAborted();
-        if (!onControlRequest) throw claudeProtocolError("This control request requires the native Claude Code terminal.");
+        if (!onControlRequest) throw claudeProtocolError("This control request requires the native Claude Code terminal.", { messageCode: "assistant.claude.controlNeedsTerminal" });
         const value = await onControlRequest(frame.request, { signal: controller.signal });
         response = { subtype: "success", request_id: id, response: value || {} };
       } catch (error) {
@@ -223,14 +226,16 @@ function createClaudeJsonClient({
         }
       }
       await events;
-      if (!closed) throw claudeProtocolError("Claude event connection ended unexpectedly.", "assistant_claude_observation_lost");
+      if (!closed) throw claudeProtocolError("Claude event connection ended unexpectedly.", {
+        code: "assistant_claude_observation_lost", messageCode: "assistant.claude.eventConnectionEnded"
+      });
     } catch (error) {
       if (!closed) {
         fail(error);
         await onFailure(failure);
       }
     } finally {
-      fail(failure || claudeProtocolError("Claude connection is closed."));
+      fail(failure || claudeProtocolError("Claude connection is closed.", { messageCode: "assistant.claude.connectionClosed" }));
     }
   })();
   // Callers can await completion; the background observer must never leak an
@@ -262,7 +267,7 @@ function createClaudeJsonClient({
     // Older CLIs treat this control as a plain Stop, cancelling background
     // workers. Require the native capability before writing either frame.
     if (sendNow && !supportsSendNow) throw Object.assign(
-      claudeProtocolError("This Claude version does not support targeted Send now."), { delivery: "not-sent" }
+      claudeProtocolError("This Claude version does not support targeted Send now.", { messageCode: "assistant.claude.sendNowUnsupported" }), { delivery: "not-sent" }
     );
     await write({ type: "user", uuid: messageId, session_id: sessionId,
       parent_tool_use_id: null, message: { role: "user", content: message } });
@@ -272,7 +277,7 @@ function createClaudeJsonClient({
   /** Closes the connection; pending requests fail. */
   function close() {
     closed = true;
-    fail(claudeProtocolError("Claude connection was closed."));
+    fail(claudeProtocolError("Claude connection was closed.", { messageCode: "assistant.claude.connectionWasClosed" }));
   }
 
   return Object.freeze({

package/src/server/conversation/claudeCommandRun.js

@@ -41,7 +41,9 @@ export function createClaudeCommandRun({ bound, preparation, send, interrupt })
     const active = control.current;
     const applicationCommand = active && (active.tools || active.finishIfCurrent) ? { active, accept: command.accept } : null;
     if (applicationCommand) {
-      if (entry.disposed || entry.command && entry.command !== active) throw new Error("This Claude conversation is closed or already working.");
+      if (entry.disposed || entry.command && entry.command !== active) throw Object.assign(new Error("This Claude conversation is closed or already working."), {
+        messageCode: "assistant.claude.closedOrWorking", messageParams: {}
+      });
       if (active.entry && active.entry !== entry) throw new Error("Claude's application tools belong to another native conversation.");
       active.entry = entry;
       entry.command = active;
@@ -61,12 +63,16 @@ export function createClaudeCommandRun({ bound, preparation, send, interrupt })
 
   function steer(control, command, options) {
     if (!bound) return dispatch(control, command, options).then(delivered => ({ value: delivered.value }));
-    if (!control.current?.steer || !control.current.entry.nativeTurn.read().active) throw new Error("Claude has no active turn to steer.");
+    if (!control.current?.steer || !control.current.entry.nativeTurn.read().active) throw Object.assign(new Error("Claude has no active turn to steer."), {
+      messageCode: "assistant.claude.noTurnToSteer", messageParams: {}
+    });
     return control.current.steer(command);
   }
 
   async function run(control, command, { acquire, reportFailure, entry: selectedEntry, maximumOutput, maximumToolCalls = 32, timeoutMs } = {}) {
-    if (control.disposed || control.current) throw new Error("This Claude conversation is closed or already working.");
+    if (control.disposed || control.current) throw Object.assign(new Error("This Claude conversation is closed or already working."), {
+      messageCode: "assistant.claude.closedOrWorking", messageParams: {}
+    });
     const { configuration, context, input, tools, signal, beforeDispatch, accept, onMessage, onEvent, onNativeToolUse } = command;
     const completion = Promise.withResolvers();
     completion.promise.catch(() => {});
@@ -108,7 +114,9 @@ export function createClaudeCommandRun({ bound, preparation, send, interrupt })
     try {
       if (bound) {
         entry = selectedEntry;
-        if (entry.disposed || entry.command) throw new Error("This Claude conversation is closed or already working.");
+        if (entry.disposed || entry.command) throw Object.assign(new Error("This Claude conversation is closed or already working."), {
+          messageCode: "assistant.claude.closedOrWorking", messageParams: {}
+        });
         active.entry = entry;
         entry.command = active;
         entry.completion = completion;
@@ -138,12 +146,14 @@ export function createClaudeCommandRun({ bound, preparation, send, interrupt })
         problem = dispatchFailure || failure || problem;
         if (!problem && settling?.completion && (bound ? result.status !== "completed" : !result.ok)) {
           // readable-check: allow patched-error - data: status is the native turn's state, not an HTTP status
-          problem = Object.assign(new Error(result.error || (bound ? "Claude interrupted this answer." : `Claude turn ${result.status}.`)), { status: result.status });
+          problem = Object.assign(new Error(result.error || (bound ? "Claude interrupted this answer." : `Claude turn ${result.status}.`)), {
+            status: result.status, ...(bound ? { messageCode: "assistant.claude.answerInterrupted", messageParams: {} } : {})
+          });
         }
         break;
       }
     } catch (error) { problem = error; }
-    ready.reject(problem || new Error("Claude work ended."));
+    ready.reject(problem || Object.assign(new Error("Claude work ended."), { messageCode: "assistant.claude.workEnded", messageParams: {} }));
     signal.removeEventListener("abort", abort);
     if (bound) {
       try {

package/src/server/conversation/claudeNativeTurn.js

@@ -3,8 +3,9 @@ import { claudeMessageBlocks } from "./claudeHistory.js";
 import { stopClaudeCodeProcess } from "./claudeProcess.js";
 import { createClaudeConversationAdapter } from "./providers/claude.js";
 
-export function claudeTurnFailure(message, { code = "assistant_claude_turn_failed" } = {}) {
-  return Object.assign(new Error(message), { code });
+// messageCode names the sentence, since one turn-failure code covers several.
+export function claudeTurnFailure(message, { code = "assistant_claude_turn_failed", messageCode } = {}) {
+  return Object.assign(new Error(message), { code, ...(messageCode ? { messageCode, messageParams: {} } : {}) });
 }
 
 // Input for a turn that already finished is the caller's refusal; input that
@@ -109,7 +110,8 @@ function retainStoppedClaudeMessages(messages, pendingAssistantMessages) {
  * The owner's control of one native process, as a native turn uses it.
  * @typedef {import("./providers/claude.js").ClaudeProcessControl & {
  *   stopExecution?: (executionId: string, options?: object) => Promise<object>,
- *   releaseExecution?: () => Promise<unknown>
+ *   releaseExecution?: () => Promise<unknown>,
+ *   ownerClosing?: () => boolean
  * }} ClaudeTurnProcess
  */
 
@@ -275,6 +277,16 @@ export function createClaudeConversationTurn({ conversationId, onEvent, process,
         if (active) entry.completion?.resolve({ status: "interrupted", error: reason || "Work stopped." });
         return;
       }
+      if (entry.turn?.active && process.ownerClosing()) {
+        // At shutdown the turn's end belongs to the next server, as after a
+        // crash: its saved record keeps the execution and the active turn, so
+        // that server's recovery proves this exit, interrupts the turn and runs
+        // the host's checkpoint. Run here, that checkpoint (a Git snapshot, say)
+        // would hold the host's bounded shutdown for as long as it takes.
+        resolveCompletion({ ...readResult(), status: "interrupted", error: reason });
+        if (entry.startupCleanup === startup) entry.startupCleanup = null;
+        return entry.exitProof;
+      }
       if (entry.turn?.active) {
         try { await updateState("interrupted", reason); }
         catch (error) {
@@ -358,7 +370,7 @@ export function createClaudeConversationTurn({ conversationId, onEvent, process,
 
   function checkOutput(value, role = "assistant") {
     if (value.length > (role === "thinking" ? 4 * 1024 * 1024 : maximumOutput)) {
-      throw claudeTurnFailure("Claude output exceeded its size limit.");
+      throw claudeTurnFailure("Claude output exceeded its size limit.", { messageCode: "assistant.claude.outputTooLarge" });
     }
   }
 
@@ -600,7 +612,7 @@ export function createClaudeConversationTurn({ conversationId, onEvent, process,
   }
 
   function begin({ id, maxOutputCharacters = 4 * 1024 * 1024 } = {}) {
-    if (active) throw claudeTurnFailure("This Claude turn is still working.");
+    if (active) throw claudeTurnFailure("This Claude turn is still working.", { messageCode: "assistant.claude.turnStillWorking" });
     if (!id || !Number.isSafeInteger(maxOutputCharacters) || maxOutputCharacters < 1) throw new TypeError("Invalid Claude turn configuration.");
     generation++;
     clearTurnView();
@@ -615,7 +627,7 @@ export function createClaudeConversationTurn({ conversationId, onEvent, process,
   }
 
   function reset() {
-    if (active || inFlight.size || tasks.size) throw claudeTurnFailure("Stop Claude before resetting its turn view.");
+    if (active || inFlight.size || tasks.size) throw claudeTurnFailure("Stop Claude before resetting its turn view.", { messageCode: "assistant.claude.stopBeforeReset" });
     clearTurnView();
   }
 

package/src/server/conversation/claudeProcess.js

@@ -134,7 +134,9 @@ export function claudeConnectionIdentity(configRoot, providerId, baseUrl, apiKey
 export function claudeModelConfiguration({ providerId, model: modelId }, connection) {
   const provider = nativeAiProvider(providerId);
   const definition = provider?.models.find(({ id }) => id === modelId);
-  if (provider && (!definition || !connection?.apiKey)) throw new Error("Choose a connected Claude Code model.");
+  if (provider && (!definition || !connection?.apiKey)) throw Object.assign(new Error("Choose a connected Claude Code model."), {
+    messageCode: "assistant.claude.chooseConnectedModel", messageParams: {}
+  });
   const model = definition?.contextWindow >= 1000000 ? `${definition.id}[1m]` : modelId;
   const externalModel = provider ? model : "";
   // Reset every provider override when returning to the native subscription.
@@ -328,7 +330,9 @@ export function createClaudeAccountQueries({
   processes = noOwnedProcesses,
   isClosing = neverClosing
 }) {
-  const error = message => Object.assign(new Error(message), { code: "claude_account_query_failed" });
+  const error = (message, { messageCode }) => Object.assign(new Error(message), {
+    code: "claude_account_query_failed", messageCode, messageParams: {}
+  });
   const accountProcessStops = new Set();
   const accountReads = new Set();
   let catalog;
@@ -339,13 +343,17 @@ export function createClaudeAccountQueries({
   let revision = 0;
 
   function assertCurrent(expectedRevision) {
-    if (expectedRevision !== revision) throw error("Claude account query was cancelled for reconnection.");
-    if (isClosing()) throw error("Claude is reconnecting.");
+    if (expectedRevision !== revision) {
+      throw error("Claude account query was cancelled for reconnection.", { messageCode: "assistant.claude.accountQueryCancelled" });
+    }
+    if (isClosing()) throw error("Claude is reconnecting.", { messageCode: "assistant.claude.reconnecting" });
   }
 
   async function stopAccountProcess(native) {
     accountProcessStops.add(native);
-    if (!(await native.stop()).scopeEmpty) throw error("Claude account query process cleanup could not be confirmed.");
+    if (!(await native.stop()).scopeEmpty) throw error("Claude account query process cleanup could not be confirmed.", {
+      messageCode: "assistant.claude.accountQueryCleanupUnconfirmed"
+    });
     accountProcessStops.delete(native);
   }
 
@@ -406,7 +414,9 @@ export function createClaudeAccountQueries({
       const { value, command } = await readAccountProcess(identity, expectedRevision, "catalogue",
         async (native) => ({ value: await native.initialization, command: native.command }));
       const answered = await catalogueRevision(command);
-      if (identity !== await accountIdentity(context)) throw error("The signed-in Claude account changed. Refresh the model list.");
+      if (identity !== await accountIdentity(context)) throw error("The signed-in Claude account changed. Refresh the model list.", {
+        messageCode: "assistant.claude.accountChangedRefreshModels"
+      });
       assertCurrent(expectedRevision);
       catalog = { identity, command, revision: answered, value };
       return value;
@@ -480,7 +490,9 @@ export function createClaudeAccountQueries({
     revision++;
     // Dropped at once: a read started before this cannot store its answer.
     catalog = null;
-    for (const controller of accountReads) controller.abort(error("Claude account query was cancelled for reconnection."));
+    for (const controller of accountReads) {
+      controller.abort(error("Claude account query was cancelled for reconnection.", { messageCode: "assistant.claude.accountQueryCancelled" }));
+    }
     await Promise.allSettled([...catalogStarts.values(), ...usageReads]);
     // The account changed: the next request for an account this owner used reads again.
     for (const identity of usageAccounts) planUsageReads.delete(identity);
@@ -588,7 +600,7 @@ export async function createClaudeCodeProcess({
     // execution receipt after startup instead of waiting forever for pipe EOF.
     if (native.exited) void native.exited.then(processExit => {
       if (!stopped && !stopping) stream.destroy(Object.assign(new Error("Claude exited unexpectedly."), {
-        code: "assistant_claude_observation_lost", processExit
+        code: "assistant_claude_observation_lost", messageCode: "assistant.claude.exitedUnexpectedly", messageParams: {}, processExit
       }));
     }, error => {
       if (!stopped && !stopping) stream.destroy(error);

package/src/server/conversation/claudeProcessStart.js

@@ -97,7 +97,7 @@ export function createClaudeProcessStart({
         if (current && frame.type === "assistant" && !frame.parent_tool_use_id) {
           for (const tool of frame.message?.content || []) if (tool.type === "tool_use" && tool.id && tool.name?.startsWith("mcp__application__")) {
             if (current.nativeToolCount >= current.maximumToolCalls && !current.nativeTools.has(tool.id)) {
-              throw new Error("Claude exceeded the application tool-call limit.");
+              throw Object.assign(new Error("Claude exceeded the application tool-call limit."), { messageCode: "assistant.claude.toolCallLimit", messageParams: {} });
             }
             if (!current.nativeTools.has(tool.id)) {
               current.nativeToolCount++;

package/src/server/conversation/claudeSessionCleanup.js

@@ -36,24 +36,21 @@ export function createClaudeSessionCleanup({
     return closing || closingSessions.has(contextKey);
   }
 
+  // Reconciliation retires the work an earlier server left, as a session's
+  // close does: it reopens only saved custody, then stops each of the
+  // session's entries whose execution is unproven. Idle saved conversations
+  // stay closed and unwritten.
   async function reconcileSessions(sessions, options = {}, application) {
     const results = [];
     for (const session of sessions) {
       const ctx = await application.readContext({ ...options, session, sessionId: session.sessionId });
-      await recover(await restoreSessionEntries(ctx, { acquire }));
+      await recoverSavedCustody(ctx);
+      await recover([...entries.values()].filter((entry) => entry.context.key === ctx.key));
       results.push({ ok: true, sessionId: session.sessionId, resumed: false });
     }
     return { ok: true, results, failed: [], sessionCount: results.length };
   }
 
-  async function restoreSessionEntries(context, { acquire }) {
-    let saved = store.readSessionConversations(context);
-    // readable-check: allow method-probe - data: a store lists a session's conversations synchronously or with a promise
-    if (saved && typeof saved.then === "function") saved = await saved;
-    for (const conversationId of saved.ids) await acquire(saved.context, conversationId);
-    return [...entries.values()].filter((entry) => entry.context.key === context.key);
-  }
-
   // A session's close stops what this server runs for it, then reopens only
   // saved custody an earlier server left. Once the owner is closing for an
   // account change or shutdown it reopens nothing.
@@ -233,7 +230,6 @@ export function createClaudeSessionCleanup({
     closingSessions,
     isClosing,
     reconcileSessions,
-    restoreSessionEntries,
     closeSession,
     releaseSession,
     closeProject,

package/src/server/conversation/claudeTurn.js

@@ -318,8 +318,8 @@ export function createClaudeConversationOwner({
     if (!saved) return {};
     try { return JSON.parse(saved); }
     catch {
-      throw createError(`The saved Claude conversation ${conversationId} is unreadable. Restore its saved conversation state.`,
-        { code: "conversation_claude_saved_state_unreadable" });
+      throw Object.assign(createError(`The saved Claude conversation ${conversationId} is unreadable. Restore its saved conversation state.`,
+        { code: "conversation_claude_saved_state_unreadable" }), { params: { conversationId } });
     }
   }
 
@@ -368,6 +368,7 @@ export function createClaudeConversationOwner({
       process: {
         stopExecution: process.stopExecution,
         ...(bound ? { releaseExecution: () => store.releaseExecution(entry) } : {}),
+        ownerClosing: () => cleanup.closing,
         getProcess: () => entry.stopping ? null : entry.process,
         isActive: () => isTurnActive(entry),
         startProcess: input => processStart.startProcess(entry, input),
@@ -697,7 +698,6 @@ export function createClaudeConversationOwner({
     hasActiveConversation,
     retireConversationHistory,
     reconcileSessions: cleanup.reconcileSessions,
-    restoreSessionEntries: cleanup.restoreSessionEntries,
     closeSession: cleanup.closeSession,
     releaseSession: cleanup.releaseSession,
     closeProject: cleanup.closeProject,

package/src/server/conversation/codexAccountReader.js

@@ -16,11 +16,15 @@ export function createCodexAccountReader({
   identityNamespace = "codex-account-v1",
   secretNamespace = "codex-auth-secret-v1"
 } = {}) {
-  function codexAppServerHelperAuthError(code = "", message = "") {
+  // messageCode names the sentence, since one code covers several.
+  function codexAppServerHelperAuthError(code = "", message = "", { messageCode } = {}) {
     const error = new Error(
       normalizeNullableText(message) || "Codex helper authentication is unavailable. Reconnect Codex and retry."
     );
     error.code = normalizeNullableText(code) || `${errorPrefix}codex_helper_auth_unavailable`;
+    if (!normalizeNullableText(message)) error.messageCode = "assistant.codex.helperAuthUnavailable";
+    else if (messageCode) error.messageCode = messageCode;
+    if (error.messageCode) error.messageParams = {};
     return error;
   }
 
@@ -61,7 +65,8 @@ export function createCodexAccountReader({
       if (!fileStat.isFile() || fileStat.size > CODEX_APP_SERVER_SELECTED_AUTH_MAX_BYTES) {
         throw codexAppServerHelperAuthError(
           `${errorPrefix}codex_helper_auth_invalid`,
-          "The selected Codex authentication record is invalid. Reconnect Codex and retry."
+          "The selected Codex authentication record is invalid. Reconnect Codex and retry.",
+          { messageCode: "assistant.codex.authRecordInvalid" }
         );
       }
       const buffer = Buffer.alloc(CODEX_APP_SERVER_SELECTED_AUTH_MAX_BYTES + 1);
@@ -76,7 +81,8 @@ export function createCodexAccountReader({
       if (offset > CODEX_APP_SERVER_SELECTED_AUTH_MAX_BYTES) {
         throw codexAppServerHelperAuthError(
           `${errorPrefix}codex_helper_auth_invalid`,
-          "The selected Codex authentication record is too large. Reconnect Codex and retry."
+          "The selected Codex authentication record is too large. Reconnect Codex and retry.",
+          { messageCode: "assistant.codex.authRecordTooLarge" }
         );
       }
       const parsed = JSON.parse(buffer.subarray(0, offset).toString("utf8"));
@@ -91,7 +97,8 @@ export function createCodexAccountReader({
       }
       throw codexAppServerHelperAuthError(
         `${errorPrefix}codex_helper_auth_unavailable`,
-        "The selected Codex authentication record could not be read. Reconnect Codex and retry."
+        "The selected Codex authentication record could not be read. Reconnect Codex and retry.",
+        { messageCode: "assistant.codex.authRecordUnreadable" }
       );
     } finally {
       await handle?.close().catch(() => null);
@@ -103,7 +110,8 @@ export function createCodexAccountReader({
     if (!toolHomeSource || !path.isAbsolute(toolHomeSource)) {
       throw codexAppServerHelperAuthError(
         `${errorPrefix}codex_helper_auth_unavailable`,
-        "The selected Codex account is unavailable. Reconnect Codex and retry."
+        "The selected Codex account is unavailable. Reconnect Codex and retry.",
+        { messageCode: "assistant.codex.accountUnavailable" }
       );
     }
     const auth = await readBoundedCodexAuthJson(path.join(toolHomeSource, ".codex", "auth.json"));
@@ -148,7 +156,8 @@ export function createCodexAccountReader({
     }
     throw codexAppServerHelperAuthError(
       `${errorPrefix}codex_helper_auth_invalid`,
-      "The selected Codex authentication mode is unsupported. Reconnect Codex and retry."
+      "The selected Codex authentication mode is unsupported. Reconnect Codex and retry.",
+      { messageCode: "assistant.codex.authModeUnsupported" }
     );
   }
 

package/src/server/conversation/codexConversationStops.js

@@ -109,7 +109,7 @@ export function createCodexConversationStops({
     if (conversationState) {
       conversationState.status = "interrupted";
       if (conversationState.goal?.status === "active") conversationState.goal = { ...conversationState.goal, status: "paused" };
-      conversationState.watcher?.failNow(new Error("Temporary AI turn was stopped."));
+      conversationState.watcher?.failNow(Object.assign(new Error("Temporary AI turn was stopped."), { messageCode: "assistant.codex.temporaryTurnStopped", messageParams: {} }));
       conversationState.watcher = null;
       holdWhileActive(conversationState);
     }
@@ -143,7 +143,7 @@ export function createCodexConversationStops({
     });
     if (result.ok !== false && conversationState) {
       conversationState.status = "interrupted";
-      conversationState.watcher?.failNow(new Error("Temporary AI turn was stopped."));
+      conversationState.watcher?.failNow(Object.assign(new Error("Temporary AI turn was stopped."), { messageCode: "assistant.codex.temporaryTurnStopped", messageParams: {} }));
       conversationState.watcher = null;
       holdWhileActive(conversationState);
     }
@@ -212,7 +212,7 @@ export function createCodexConversationStops({
     if (result.ok !== false && conversation) {
       const { conversationId, sessionKey, conversations } = conversation;
       const state = conversations?.get(conversationId);
-      state?.watcher?.failNow(new Error("Temporary AI conversation was closed."));
+      state?.watcher?.failNow(Object.assign(new Error("Temporary AI conversation was closed."), { messageCode: "assistant.codex.temporaryConversationClosed", messageParams: {} }));
       if (state) forgetObservation(state);
       conversations?.delete(conversationId);
       if (conversations?.size === 0) {

package/src/server/conversation/codexConversations.js

@@ -250,7 +250,7 @@ export function createCodexConversationCommands({
     const thread = await context.provider.readThreadStatus(conversationId);
     if (codexAppServerThreadRawValue(thread).historyMode !== "paginated") {
       throw Object.assign(new Error("This conversation uses an unsupported Codex history format. Start a fresh conversation."), {
-        code: `${errorPrefix}codex_history_unsupported`
+        code: `${errorPrefix}codex_history_unsupported`, messageCode: "assistant.codex.historyFormatStartFresh", messageParams: {}
       });
     }
     const turns = [];

package/src/server/conversation/codexDetachedTurn.js

@@ -217,7 +217,7 @@ function createCodexAppServerDetachedTurnWatcher(provider, threadId = "", {
       rejectWaiter = reject;
       if (timeoutMs > 0) {
         timeout = setTimeout(() => {
-          fail(new Error("Timed out waiting for Codex app-server response."));
+          fail(Object.assign(new Error("Timed out waiting for Codex app-server response."), { messageCode: "assistant.codex.responseTimeout", messageParams: {} }));
         }, timeoutMs);
       } else {
         // Interactive repair turns may take longer than bounded helper jobs.
@@ -226,7 +226,9 @@ function createCodexAppServerDetachedTurnWatcher(provider, threadId = "", {
         connectionCheck = setInterval(() => {
           if (provider.isAvailable() === false ||
             provider.currentConnectionGeneration() !== generation) {
-            fail(new Error("Connection to Codex was lost while the temporary AI was working."));
+            fail(Object.assign(new Error("Connection to Codex was lost while the temporary AI was working."), {
+              messageCode: "assistant.codex.temporaryConnectionLost", messageParams: {}
+            }));
           }
         }, 1000);
         connectionCheck.unref();

package/src/server/conversation/codexGoalCommands.js

@@ -113,7 +113,9 @@ export function createCodexGoalCommands({
       if (recovered.reason === "error") throw new Error(recovered.error);
       await context.runtime.store.mutateSession(sessionId, async () => {
         const run = await readCodexAppServerAgentRunForSession(context.runtime.store, sessionId);
-        if (run.active || run.providerThreadId !== threadId) throw new Error("The assistant changed. Refresh before resuming.");
+        if (run.active || run.providerThreadId !== threadId) throw Object.assign(new Error("The assistant changed. Refresh before resuming."), {
+          messageCode: "assistant.codex.assistantChangedRefresh", messageParams: {}
+        });
         await context.runtime.store.writeAgentRunEvent(sessionId, CODEX_APP_SERVER_AGENT_RUN_ID, {
           event: { kind: "codex-observation-explicit-resume" },
           patch: { providerStatus: "interrupted", error: "" }

package/src/server/conversation/codexHelperExecution.js

@@ -47,15 +47,15 @@ export async function assertCodexAppServerHelperAccountIdentity(provider, expect
     return;
   }
   if (!/^sha256:[a-f0-9]{64}$/u.test(expected) || !provider) {
-    throw codexAppServerHelperOwnershipError(
+    throw Object.assign(codexAppServerHelperOwnershipError(
       "The requested low-cost assistant account identity is invalid. Refresh the task and retry."
-    );
+    ), { messageCode: "assistant.codex.helperAccountIdentityInvalid", messageParams: {} });
   }
   const actual = normalizeText((await provider.currentRuntimeInfo())?.accountIdentitySignature);
   if (actual !== expected) {
-    throw codexAppServerHelperOwnershipError(
+    throw Object.assign(codexAppServerHelperOwnershipError(
       "The selected Codex account changed before low-cost assistant work could run. Retry the task with the current account."
-    );
+    ), { messageCode: "assistant.codex.helperAccountChangedBeforeRun", messageParams: {} });
   }
 }
 

package/src/server/conversation/codexHelperThreadRecovery.js

@@ -66,10 +66,10 @@ export function createCodexHelperThreadRecovery(lifecycle, {
         const accountChanged = record.identity.runtime.accountIdentitySignature !==
           normalizeText(currentRuntime.accountIdentitySignature);
         if (accountChanged && !cleanupRequired) {
-          throw lifecycle.ownershipError(
+          throw Object.assign(lifecycle.ownershipError(
             "Reconnect the original Codex account to resume or delete this helper thread.",
             { retryable: false, sessionId: record.sessionId, threadId: record.threadId }
-          );
+          ), { messageCode: "assistant.codex.helperThreadReconnectAccount", messageParams: {} });
         }
         if (accountChanged || contextChanged) {
           // Context drift cannot reuse the previous provider configuration.

package/src/server/conversation/codexHistoryAdapter.js

@@ -467,7 +467,7 @@ async function prepareCodexHistory(params, client, { baseUrl, modelProviderId, .
   if (modelProvider !== "openai") return params;
   const { account } = await client.request("account/read", { refreshToken: false }, options);
   if (!["chatgpt", "apiKey"].includes(account?.type)) {
-    throw new Error("Reconnect the OpenAI account before using this model.");
+    throw Object.assign(new Error("Reconnect the OpenAI account before using this model."), { messageCode: "assistant.codex.reconnectOpenAi", messageParams: {} });
   }
   return { ...params, config: { ...params.config,
     openai_base_url: `${baseUrl}/${account.type}`

package/src/server/conversation/codexMessageCommands.js

@@ -83,7 +83,7 @@ export function createCodexMessageCommands({
     if (turn.status === "observation_lost") {
       if (turn.active) {
         throw Object.assign(new Error("Codex observation was lost and a stop is not yet verified. Retry after the service has stopped."), {
-          code: `${errorPrefix}codex_observation_lost`
+          code: `${errorPrefix}codex_observation_lost`, messageCode: "assistant.codex.observationLostStopUnverified", messageParams: {}
         });
       }
       const recovered = await output.submitAssistantResult(sessionId, turn.threadId, turn.turnId, { recoverFromProvider: true });
@@ -207,7 +207,9 @@ export function createCodexMessageCommands({
         workdir: source.workdir ?? workdir
       });
       if (source.requirePaginatedHistory && thread.thread.raw?.historyMode !== "paginated") {
-        throw new Error("Codex did not create the required paginated history. Update Codex before starting this conversation.");
+        throw Object.assign(new Error("Codex did not create the required paginated history. Update Codex before starting this conversation."), {
+          messageCode: "assistant.codex.paginatedHistoryMissing", messageParams: {}
+        });
       }
       debugLog("appServerPrompt.stage", {
         durationMs: Date.now() - stageStartedAt, messageId, sessionId, stage: "thread"

package/src/server/conversation/codexModelCatalog.js

@@ -38,7 +38,7 @@ export function createCodexAppServerModelCatalogCache({
   return async function readCodexAppServerModelCatalog(provider, { signal = null } = {}) {
     // readable-check: allow method-probe - safety invariant: a provider without live model discovery is refused with codex_model_catalog_unavailable
     if (typeof provider.listModels !== "function") {
-      const error = new Error("Codex live model discovery is unavailable.");
+      const error = Object.assign(new Error("Codex live model discovery is unavailable."), { messageCode: "assistant.codex.modelDiscoveryUnavailable", messageParams: {} });
       error.code = `${errorPrefix}codex_model_catalog_unavailable`;
       throw error;
     }

package/src/server/conversation/codexObservationControl.js

@@ -38,7 +38,7 @@ export function createCodexObservationControl({
   function assertCodexAppServerThreadCanResume(run, threadId) {
     if (run?.providerThreadId === threadId && run.providerStatus === "observation_lost") {
       throw Object.assign(new Error(run.error || "Codex is stopped. Use Resume or Send to continue."), {
-        code: `${errorPrefix}codex_observation_lost`
+        code: `${errorPrefix}codex_observation_lost`, messageCode: "assistant.codex.stoppedUseResume", messageParams: {}
       });
     }
   }