@jskit-ai/assistant-core 0.2.12 → 0.2.14

package/src/server/conversation/codexProvider.js

@@ -262,7 +262,7 @@ export class CodexAppServerAgentProvider {
 
   staleRuntimeError() {
     return Object.assign(new Error("Codex (OpenAI) changed account. Send your message again."), {
-      code: `${this.errorPrefix}codex_account_changed`, retryable: true
+      code: `${this.errorPrefix}codex_account_changed`, retryable: true, messageCode: "assistant.codex.accountChangedSendAgain", messageParams: {}
     });
   }
 
@@ -610,7 +610,9 @@ export class CodexAppServerAgentProvider {
   close() {
     const { onClose = closeNothing } = this.options;
     onClose();
-    for (const reject of this.settingsWaiters) reject(new Error("The assistant connection closed before confirming its settings."));
+    for (const reject of this.settingsWaiters) reject(Object.assign(new Error("The assistant connection closed before confirming its settings."), {
+      messageCode: "assistant.codex.connectionClosedBeforeSettings", messageParams: {}
+    }));
     this.settingsWaiters.clear();
     this.conversationRuntime.close();
     this.turns.clear();

package/src/server/conversation/codexProviderAuth.js

@@ -24,7 +24,8 @@ function codexAppServerHelperLoginParams(auth = {}, errorPrefix = "") {
   }
   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" }
   );
 }
 
@@ -65,7 +66,7 @@ export function codexAppServerHelperRequestError(error = null, reason = "", erro
   ) {
     return error;
   }
-  const failure = new Error("Codex isolated helper execution failed. Retry the task.");
+  const failure = Object.assign(new Error("Codex isolated helper execution failed. Retry the task."), { messageCode: "assistant.codex.helperExecutionFailed", messageParams: {} });
   failure.code = `${errorPrefix}codex_helper_provider_request_failed`;
   const providerCode = Number(error?.code);
   if (Number.isSafeInteger(providerCode)) {
@@ -109,7 +110,8 @@ export function createCodexProviderAuth({ provider }) {
     if (helperAuthBlocked) {
       throw provider.accountReader.error(
         `${provider.errorPrefix}codex_helper_auth_changed`,
-        "The selected Codex account changed during helper work. Retry the task with the current account."
+        "The selected Codex account changed during helper work. Retry the task with the current account.",
+        { messageCode: "assistant.codex.helperAccountChanged" }
       );
     }
     const current = await selectedHelperAuth();
@@ -117,7 +119,8 @@ export function createCodexProviderAuth({ provider }) {
       helperAuthBlocked = true;
       throw provider.accountReader.error(
         `${provider.errorPrefix}codex_helper_auth_changed`,
-        "The selected Codex account changed during helper work. Retry the task with the current account."
+        "The selected Codex account changed during helper work. Retry the task with the current account.",
+        { messageCode: "assistant.codex.helperAccountChanged" }
       );
     }
   }
@@ -133,7 +136,8 @@ export function createCodexProviderAuth({ provider }) {
     ) {
       throw provider.accountReader.error(
         `${provider.errorPrefix}codex_helper_auth_changed`,
-        "The selected Codex account changed while helper execution was starting. Retry the task."
+        "The selected Codex account changed while helper execution was starting. Retry the task.",
+        { messageCode: "assistant.codex.helperAccountChangedStarting" }
       );
     }
     helperAuth = auth;
@@ -162,7 +166,8 @@ export function createCodexProviderAuth({ provider }) {
       helperAuthBlocked = true;
       throw provider.accountReader.error(
         `${provider.errorPrefix}codex_helper_auth_unavailable`,
-        "Codex could not activate the selected account for isolated helper work. Reconnect Codex and retry."
+        "Codex could not activate the selected account for isolated helper work. Reconnect Codex and retry.",
+        { messageCode: "assistant.codex.helperAccountActivationFailed" }
       );
     }
   }
@@ -182,7 +187,8 @@ export function createCodexProviderAuth({ provider }) {
       helperAuthBlocked = true;
       throw provider.accountReader.error(
         `${provider.errorPrefix}codex_helper_auth_refresh_rejected`,
-        "Codex helper authentication refresh was rejected. Reconnect Codex and retry."
+        "Codex helper authentication refresh was rejected. Reconnect Codex and retry.",
+        { messageCode: "assistant.codex.helperAuthRefreshRejected" }
       );
     }
     const refreshed = await selectedHelperAuth();
@@ -193,14 +199,16 @@ export function createCodexProviderAuth({ provider }) {
       helperAuthBlocked = true;
       throw provider.accountReader.error(
         `${provider.errorPrefix}codex_helper_auth_changed`,
-        "The selected Codex account changed during helper work. Retry the task with the current account."
+        "The selected Codex account changed during helper work. Retry the task with the current account.",
+        { messageCode: "assistant.codex.helperAccountChanged" }
       );
     }
     if (refreshed.secretSignature === currentAuth.secretSignature) {
       helperAuthBlocked = true;
       throw provider.accountReader.error(
         `${provider.errorPrefix}codex_helper_auth_refresh_pending`,
-        "The selected Codex account has not produced a newer access token yet. Reconnect Codex and retry."
+        "The selected Codex account has not produced a newer access token yet. Reconnect Codex and retry.",
+        { messageCode: "assistant.codex.helperAccessTokenStale" }
       );
     }
     helperAuth = refreshed;

package/src/server/conversation/codexProviderInvalidation.js

@@ -60,7 +60,9 @@ export function createCodexProviderInvalidation({ inScope, withLifecycle, forget
           let cursor;
           do {
             const page = await request(inspector, "thread/loaded/list", { limit: 100, ...(cursor ? { cursor } : {}) });
-            if (!Array.isArray(page?.data)) throw new Error("Codex returned an invalid loaded-thread inventory. Restore its connection before retrying.");
+            if (!Array.isArray(page?.data)) throw Object.assign(new Error("Codex returned an invalid loaded-thread inventory. Restore its connection before retrying."), {
+              messageCode: "assistant.codex.loadedThreadsInvalid", messageParams: {}
+            });
             for (const id of page.data) {
               if (typeof id !== "string" || !id) throw new Error("Codex returned an invalid loaded-thread identity.");
               candidates.add(id);
@@ -77,7 +79,9 @@ export function createCodexProviderInvalidation({ inScope, withLifecycle, forget
             const { thread } = await request(inspector, "thread/read", { threadId: id, includeTurns: false });
             if (!thread || thread.id !== id || typeof thread.modelProvider !== "string" || !thread.modelProvider ||
                 !(typeof thread.status === "string" ? thread.status : thread.status?.type)) {
-              throw new Error("Codex returned an untrustworthy thread/provider inventory. Restore its connection before changing credentials.");
+              throw Object.assign(new Error("Codex returned an untrustworthy thread/provider inventory. Restore its connection before changing credentials."), {
+                messageCode: "assistant.codex.threadInventoryUntrusted", messageParams: {}
+              });
             }
             if (dedicated && thread.modelProvider !== modelProviderId) {
               throw new Error("Codex's provider credential home retains another provider thread. Close its native terminal/helper and retry; unrelated threads remain running.");

package/src/server/conversation/codexProviderThreads.js

@@ -243,7 +243,9 @@ export function codexApplicationToolConfiguration(tools) {
 
 export function assertCodexApplicationToolSchemaIdentity(threadId, savedIdentity, toolSchemaIdentity) {
   if (threadId && (savedIdentity || codexApplicationToolConfiguration().toolSchemaIdentity) !== toolSchemaIdentity) {
-    throw new Error("This Codex conversation was created with different application tool entry points. Start a new conversation to enable or remove application tools.");
+    throw Object.assign(new Error("This Codex conversation was created with different application tool entry points. Start a new conversation to enable or remove application tools."), {
+      messageCode: "assistant.codex.toolEntryPointsChanged", messageParams: {}
+    });
   }
 }
 
@@ -394,7 +396,7 @@ export function createCodexProviderThreads({ provider }) {
     // Paginated history is required only for persistent conversations.
     if (params.ephemeral !== true && response?.thread?.historyMode === "legacy") {
       throw Object.assign(new Error("Codex did not create the required paginated conversation history. Update Codex before starting a conversation."), {
-        code: `${provider.errorPrefix}codex_history_unsupported`
+        code: `${provider.errorPrefix}codex_history_unsupported`, messageCode: "assistant.codex.paginatedConversationHistoryMissing", messageParams: {}
       });
     }
     if (response?.thread?.historyMode === "paginated" && response.thread.ephemeral !== true) {

package/src/server/conversation/codexProviderTurns.js

@@ -410,7 +410,7 @@ export function createCodexProviderTurns({ provider }) {
     if (goal?.status === "active") {
       const result = await request("thread/goal/set", { threadId, status: "paused" });
       if (result.goal?.status !== "paused" || result.goal?.createdAt !== goal.createdAt || result.goal?.objective !== goal.objective) {
-        throw new Error("Codex did not confirm that the same goal was paused.");
+        throw Object.assign(new Error("Codex did not confirm that the same goal was paused."), { messageCode: "assistant.codex.goalPauseUnconfirmed", messageParams: {} });
       }
       goal = result.goal;
     }
@@ -425,7 +425,9 @@ export function createCodexProviderTurns({ provider }) {
       }
       if (!turnId) throw new Error("Codex's running turn could not be identified.");
       await interruptNativeTurn(client, threadId, turnId, signal);
-      if (await readStatus() !== "idle") throw new Error("Codex did not confirm that its turn stopped.");
+      if (await readStatus() !== "idle") throw Object.assign(new Error("Codex did not confirm that its turn stopped."), {
+        messageCode: "assistant.codex.turnStopUnconfirmed", messageParams: {}
+      });
     }
     return { goal };
   }

package/src/server/conversation/codexRenewalThreads.js

@@ -194,14 +194,14 @@ export async function resumeExactCodexAppServerThread({
       if (error?.code === errorCode) {
         throw error;
       }
-      throw codexRenewalThreadError(
+      throw Object.assign(codexRenewalThreadError(
         errorCode,
         "The old assistant thread cannot be read. Write or edit the handover manually instead.",
         {
           expectedThreadId: normalizedExpectedThreadId,
           providerError: normalizeAgentText(error?.message)
         }
-      );
+      ), { messageCode: "assistant.codex.oldThreadUnreadable", messageParams: {} });
     }
     throw error;
   }

package/src/server/conversation/conversationTurnDelivery.js

@@ -297,7 +297,9 @@ function createConversationTurnDelivery({ storage, streams, events, reads, deliv
           admitted.resolve(result.value);
           return;
         }
-        if (!request.accepted) throw new Error("The engine did not acknowledge the message.");
+        if (!request.accepted) throw Object.assign(new Error("The engine did not acknowledge the message."), {
+          messageCode: "assistant.conversation.messageNotAcknowledged", messageParams: {}
+        });
       }).catch(async error => {
         if (!request.accepted && (error.delivery === "not-sent" || !entry.conversation && error.delivery !== "uncertain")) {
           try { await input.onPromptRejected(); }

package/src/server/conversation/conversationTurns.js

@@ -494,7 +494,9 @@ function createConversationTurns({ storage, streams, events, entries, reads, del
       entry.storageFailure.cause = saveError;
       problem ||= saveError;
     }
-    if (!initial.admissionSettled) initial.admission.reject(problem || new Error("The engine did not acknowledge the message."));
+    if (!initial.admissionSettled) initial.admission.reject(problem || Object.assign(new Error("The engine did not acknowledge the message."), {
+      messageCode: "assistant.conversation.messageNotAcknowledged", messageParams: {}
+    }));
     entry.active = null;
     await events.setPhase(entry, "", active.request.turnId);
     await events.emit(entry, { type: "settled", turnId: active.request.turnId, status: entry.storageFailure || entry.executionFailure ? "failed" : status,

package/src/server/conversation/openCodeProcess.js

@@ -130,10 +130,10 @@ async function waitForOpenCodeReady({
       signal?.throwIfAborted();
       if (health?.healthy === true) {
         if (expectedVersion && normalizeNullableText(health.version) !== expectedVersion) {
-          const error = new Error(
-            `OpenCode ${normalizeNullableText(health.version) || "(unknown)"} is installed; this host requires ${expectedVersion}.`
-          );
+          const installed = normalizeNullableText(health.version) || "(unknown)";
+          const error = new Error(`OpenCode ${installed} is installed; this host requires ${expectedVersion}.`);
           error.code = "assistant_opencode_version_mismatch";
+          error.params = { installed, required: expectedVersion };
           throw error;
         }
         return health;
@@ -569,12 +569,8 @@ export async function verifyOpenCodeApiKey({
         Boolean(normalizeNullableText(result?.code)) ||
         (Number.isSafeInteger(exitCode) && exitCode !== 1);
       const error = unavailable
-        ? new AppError(503, "OpenCode API-key verification could not run.", {
-          code: "assistant_opencode_key_verification_unavailable"
-        })
-        : new AppError(422, "OpenCode rejected the API-key verification request.", {
-          code: "assistant_opencode_key_verification_failed"
-        });
+        ? new AppError(503, "OpenCode API-key verification could not run.", { code: "assistant_opencode_key_verification_unavailable" })
+        : new AppError(422, "OpenCode rejected the API-key verification request.", { code: "assistant_opencode_key_verification_failed" });
       error.retryable = unavailable;
       throw error;
     }

package/src/server/conversation/openCodeRuntime.js

@@ -188,7 +188,9 @@ export function createOpenCodeSharedRuntime({ onStop = ignoreRuntimeStop, scope,
   function allowTerminalAttachments(sessionId, terminalSessionId, input) {
     const target = [...processes.values()].find((candidate) =>
       candidate.sessionId === sessionId && candidate.terminalSessionId === terminalSessionId);
-    if (!target) throw new Error("Reopen the OpenCode terminal before attaching files.");
+    if (!target) throw Object.assign(new Error("Reopen the OpenCode terminal before attaching files."), {
+      messageCode: "assistant.opencode.reopenTerminalToAttach", messageParams: {}
+    });
     return target.server.client.allowConversationAttachments(target.upstreamSessionId, input.attachments);
   }
 

package/src/server/conversation/openCodeTurn.js

@@ -83,7 +83,7 @@ async function consumeOpenCodeEvents(client, conversationId, {
     ) {
       const failure = normalizeObject(event.data?.properties?.error);
       onError(Object.assign(new Error(readError({ error: failure }) || "OpenCode turn failed."), {
-        name: normalizeNullableText(failure.name) || "Error"
+        name: normalizeNullableText(failure.name) || "Error", messageCode: "assistant.opencode.turnFailed", messageParams: {}
       }));
     }
     if (summary.type && current && typeof onEvent === "function") {
@@ -527,7 +527,8 @@ export async function runOpenCodeConversationTurn(client, conversationId, input
     createError = (reason, message, details) => new AppError(
       ["thread_mismatch", "fresh_thread_required", "unrelated_history"].includes(reason) ? 409 : 502,
       message || (reason === "unreadable" ? "The exact OpenCode turn did not produce a readable result." : "OpenCode did not finish the turn."),
-      { code: `assistant_opencode_turn_${reason}`, details })
+      { code: `assistant_opencode_turn_${reason}`, details,
+        ...(message ? {} : reason === "unreadable" ? { messageCode: "assistant.opencode.turnUnreadable" } : { messageCode: "assistant.opencode.turnNotFinished" }) })
   } = input;
   if (
     (expectedThreadId && expectedThreadId !== conversationId) ||

package/src/server/conversation/providers/claudeDriver.js

@@ -124,7 +124,9 @@ export function createClaudeConversationDriver({
       credentialHome: { home: env.HOME || homedir() }, commandRunner: captureAccountStatus, signal });
     signal.throwIfAborted();
     if (!account.loggedIn || !account.email) {
-      throw new Error(account.error || "Sign in with claude auth login before using this conversation.");
+      throw Object.assign(new Error(account.error || "Sign in with claude auth login before using this conversation."), {
+        messageCode: "assistant.claude.signInRequired", messageParams: {}
+      });
     }
     return hash([configRoot, account.authMethod, account.email.toLowerCase()]);
   }
@@ -221,9 +223,13 @@ export function createClaudeConversationDriver({
       }
       const provider = nativeAiProvider(providerId);
       const model = nativeAiModel(connection.model, providerId);
-      if (providerId !== "anthropic" && (!provider || !model)) throw new Error("This exact provider/model is not supported by the Claude integration. Choose a supported model without renaming it.");
+      if (providerId !== "anthropic" && (!provider || !model)) throw Object.assign(new Error("This exact provider/model is not supported by the Claude integration. Choose a supported model without renaming it."), {
+        messageCode: "assistant.claude.modelUnsupported", messageParams: {}
+      });
       validateConnectionModel(configuration, connection);
-      if (model && configuration.effort && !model.variants.includes(configuration.effort)) throw new Error("The selected Claude model does not support this reasoning effort.");
+      if (model && configuration.effort && !model.variants.includes(configuration.effort)) throw Object.assign(new Error("The selected Claude model does not support this reasoning effort."), {
+        messageCode: "assistant.claude.reasoningEffortUnsupported", messageParams: {}
+      });
       selected = claudeModelConfiguration({ providerId, model: connection.model }, {
         apiKey: connection.apiKey, baseUrl: provider?.claudeBaseUrl || connection.baseURL || "https://api.anthropic.com"
       });
@@ -390,7 +396,9 @@ export function createClaudeConversationDriver({
         ? await realpath(env.HOME || homedir()) : scopeWorkdir;
       if (binding.workdir !== nativeWorkdir || binding.configRoot !== configRoot ||
         (Object.hasOwn(binding, "scopeWorkdir") && binding.scopeWorkdir !== scopeWorkdir)) {
-        throw new Error("This Claude conversation belongs to another working directory or credential home. Restore its original host configuration.");
+        throw Object.assign(new Error("This Claude conversation belongs to another working directory or credential home. Restore its original host configuration."), {
+          messageCode: "assistant.claude.otherHostConfiguration", messageParams: {}
+        });
       }
       owner = standaloneOwner();
       const context = { key: scopeWorkdir, workdir: binding.workdir, binding, reportFailure,

package/src/server/conversation/providers/codex.js

@@ -133,7 +133,9 @@ export function createCodexConversationAdapter(host) {
           (bound?.managed === false ? bound.params.config.shell_environment_policy : null);
         if (!settings && fixedPolicy && (params.developerInstructions == null || params.ephemeral || bound?.params.ephemeral)) {
           if (bound && params.developerInstructions != null && instructionPrompts.get(threadId) !== params.developerInstructions) {
-            throw new Error("Start a new ephemeral conversation to change its instructions.");
+            throw Object.assign(new Error("Start a new ephemeral conversation to change its instructions."), {
+              messageCode: "assistant.codex.ephemeralInstructionsFixed", messageParams: {}
+            });
           }
           assertRecoveryOpen();
           return operation(threadParameters({ ...bound?.params, ...params }, {}));
@@ -162,7 +164,7 @@ export function createCodexConversationAdapter(host) {
           const { thread } = await request("thread/read", { threadId, includeTurns: false });
           if (thread?.historyMode !== "paginated") {
             throw Object.assign(new Error("This conversation uses an unsupported Codex history format. Renew the session to keep your files and saved chat and start a fresh conversation. You can write the handover yourself."), {
-              code: "assistant_codex_history_unsupported"
+              code: "assistant_codex_history_unsupported", messageCode: "assistant.codex.historyFormatUnsupported", messageParams: {}
             });
           }
           nativeModelProvider = thread?.modelProvider || "";
@@ -331,10 +333,12 @@ export function createCodexConversationAdapter(host) {
           host.onRecoveryFailure(threadId);
           bindings.delete(threadId);
           log("recovery_failed", { code: cause?.code || "", reason: cause.message });
-          throw Object.assign(new Error(["assistant_agent_control_binding_retained", "assistant_codex_provider_binding_retained"].includes(cause?.code)
+          const retained = ["assistant_agent_control_binding_retained", "assistant_codex_provider_binding_retained"].includes(cause?.code);
+          throw Object.assign(new Error(retained
             ? `${cause.message} Your conversation and work are preserved.`
             : "The assistant connection could not be verified. Your conversation and files are preserved. Retry the connection, or renew the session to continue in a fresh conversation.", { cause }), {
-            code: "assistant_agent_control_recovery_failed", retryable: true
+            code: "assistant_agent_control_recovery_failed", retryable: true,
+            ...(retained ? {} : { messageCode: "assistant.codex.connectionUnverified", messageParams: {} })
           });
         }
         // A newer settings save supersedes the older choice before scheduling

package/src/server/conversation/providers/codexDriver.js

@@ -50,6 +50,19 @@ function assertCodexApplicationEnvironment(host) {
   if (!host.env) throw new TypeError("createCodexConversationDriver requires the application's environment, such as process.env.");
 }
 
+// Refusals Codex conversations send from several places; each names its sentence.
+function codexOutputTooLarge() {
+  return Object.assign(new Error("Codex output exceeded the configured limit."), {
+    messageCode: "assistant.codex.outputTooLarge", messageParams: {}
+  });
+}
+
+function nativeGoalChanged() {
+  return Object.assign(new Error("The native goal changed. Read it again before changing it."), {
+    messageCode: "assistant.codex.nativeGoalChanged", messageParams: {}
+  });
+}
+
 /**
  * Conversations own threads and observers on the account's shared native runtime.
  * @param {object} dependencies
@@ -95,7 +108,7 @@ export function createCodexConversationDriver({ connections, host = {}, limits =
     } catch (error) {
       // Native keychain logins can have no auth file. Never expose malformed
       // credential contents in a parser's error message.
-      if (error.code !== "ENOENT") throw new Error("Codex credential data could not be read. Restore its account configuration.");
+      if (error.code !== "ENOENT") throw Object.assign(new Error("Codex credential data could not be read. Restore its account configuration."), { messageCode: "assistant.codex.credentialsUnreadable", messageParams: {} });
     } finally { await file?.close(); }
     return auth;
   }
@@ -110,7 +123,7 @@ export function createCodexConversationDriver({ connections, host = {}, limits =
     }
     const key = env.OPENAI_API_KEY || auth.OPENAI_API_KEY;
     if (account?.type === "apiKey" && typeof key === "string" && key) return hash([configRoot, account.type, key]);
-    throw new Error("Sign in with codex login before using this conversation.");
+    throw Object.assign(new Error("Sign in with codex login before using this conversation."), { messageCode: "assistant.codex.signInRequired", messageParams: {} });
   }
 
   async function nativeHost(selected) {
@@ -137,7 +150,7 @@ export function createCodexConversationDriver({ connections, host = {}, limits =
       identity: generation,
       generation,
       async assertCurrent(captured) {
-        if (captured && captured !== await generation()) throw new Error("Codex authentication changed. Reopen the conversation with its original account.");
+        if (captured && captured !== await generation()) throw Object.assign(new Error("Codex authentication changed. Reopen the conversation with its original account."), { messageCode: "assistant.codex.authChangedReopen", messageParams: {} });
       },
       markInvalid() {},
       reconnectRequiredCode: "codex_reconnect_required",
@@ -297,7 +310,7 @@ export function createCodexConversationDriver({ connections, host = {}, limits =
     }
     if (!supplied) assertCodexApplicationEnvironment(host);
     if (!supplied && (!binding || typeof binding.threadId !== "string" || binding.workdir !== await realpath(workdir) || binding.configRoot !== configRoot)) {
-      throw new Error("This Codex conversation belongs to another working directory or credential home. Restore its original host configuration.");
+      throw Object.assign(new Error("This Codex conversation belongs to another working directory or credential home. Restore its original host configuration."), { messageCode: "assistant.codex.otherHostConfiguration", messageParams: {} });
     }
     const session = {
       binding,
@@ -325,7 +338,7 @@ export function createCodexConversationDriver({ connections, host = {}, limits =
         : name.includes("AssistantMessage") ? Math.min(maximumOutput, maximumFinalReply) : maximumOutput;
       const length = input.text?.length || 0;
       if (length <= limit) return nativeStore[name](id, input);
-      if (!name.includes("AssistantMessage") || length > maximumOutput) throw new Error("Codex output exceeded the configured limit.");
+      if (!name.includes("AssistantMessage") || length > maximumOutput) throw codexOutputTooLarge();
       return nativeStore.mutateSession(id, async transaction => {
         const { runtime: state } = await transaction.readMetadata();
         const identity = input.nativeIdentity;
@@ -344,7 +357,7 @@ export function createCodexConversationDriver({ connections, host = {}, limits =
             break;
           }
         }
-        throw new Error("Codex output exceeded the configured limit.");
+        throw codexOutputTooLarge();
       });
     };
     const runtime = supplied ? conversation.runtime : { ...conversation.runtime, store: { ...nativeStore,
@@ -353,9 +366,9 @@ export function createCodexConversationDriver({ connections, host = {}, limits =
       writeConversationCommentaryMessage: boundedWriter("writeConversationCommentaryMessage"),
       writeConversationThinkingMessage: boundedWriter("writeConversationThinkingMessage"),
       async updateConversationStream(id, input) {
-        if ((input.delta?.length || input.text?.length || 0) > maximumOutput) throw new Error("Codex output exceeded the configured limit.");
+        if ((input.delta?.length || input.text?.length || 0) > maximumOutput) throw codexOutputTooLarge();
         const stream = await nativeStore.updateConversationStream(id, input);
-        if (stream?.messages.some(message => message.text.length > maximumOutput)) throw new Error("Codex output exceeded the configured limit.");
+        if (stream?.messages.some(message => message.text.length > maximumOutput)) throw codexOutputTooLarge();
         return stream;
       },
       writeConversationUserMessage(id, input) {
@@ -497,7 +510,7 @@ export function createCodexConversationDriver({ connections, host = {}, limits =
             if (representation !== "native") {
               session.binding.threadId = nativeContext.threadId;
               const goal = session.binding.goal || null;
-              if ((goalValue(goal)?.id || null) !== (input.expectedGoalId || null)) throw new Error("The native goal changed. Read it again before changing it.");
+              if ((goalValue(goal)?.id || null) !== (input.expectedGoalId || null)) throw nativeGoalChanged();
               command = { ...input, threadId: session.binding.threadId,
                 createdAt: goal?.createdAt, objective: input.action === "set" ? input.objective : goal?.objective };
             }
@@ -523,7 +536,7 @@ export function createCodexConversationDriver({ connections, host = {}, limits =
           prepareThread: Boolean(session.binding.threadId && ["set", "resume"].includes(input.action)), tools
         });
         const goal = session.binding.threadId ? (await session.native.readGoal(session.binding.threadId, { signal })).goal : null;
-        if ((goalValue(goal)?.id || null) !== (input.expectedGoalId || null)) throw new Error("The native goal changed. Read it again before changing it.");
+        if ((goalValue(goal)?.id || null) !== (input.expectedGoalId || null)) throw nativeGoalChanged();
         const result = await owner.updateGoal(sessionId, { ...input, threadId: session.binding.threadId,
           createdAt: goal?.createdAt, objective: input.action === "set" ? input.objective : goal?.objective }, {
           context: nativeContext, signal: context?.signal,

package/src/server/conversation/providers/codexDriverConnection.js

@@ -93,7 +93,9 @@ export function createCodexDriverConnection({
       prepareThreadEnvironment: environment => session.preparedThreadSettings?.config.shell_environment_policy.set || environment,
       prepareThreadResumeParams(threadId, params) {
         if (threadId !== session.binding.threadId || !session.preparedThreadSettings) {
-          throw new Error("Codex requires current authorized settings before resuming this conversation.");
+          throw Object.assign(new Error("Codex requires current authorized settings before resuming this conversation."), {
+            messageCode: "assistant.codex.authorizedSettingsRequired", messageParams: {}
+          });
         }
         return { ...session.preparedThreadSettings, ...params,
           config: { ...session.preparedThreadSettings.config, ...params.config } };
@@ -197,9 +199,13 @@ export function createCodexDriverConnection({
     signal.throwIfAborted();
     const provider = nativeAiProvider(connection.providerId);
     const model = nativeAiModel(connection.model, connection.providerId);
-    if (!provider || !model) throw new Error("This exact provider/model is not supported by the Codex integration. Choose a supported model without renaming it.");
+    if (!provider || !model) throw Object.assign(new Error("This exact provider/model is not supported by the Codex integration. Choose a supported model without renaming it."), {
+      messageCode: "assistant.codex.modelUnsupported", messageParams: {}
+    });
     validateConnectionModel(configuration, connection);
-    if (configuration.effort && !model.variants.includes(configuration.effort)) throw new Error("The selected Codex model does not support this reasoning effort.");
+    if (configuration.effort && !model.variants.includes(configuration.effort)) throw Object.assign(new Error("The selected Codex model does not support this reasoning effort."), {
+      messageCode: "assistant.codex.reasoningEffortUnsupported", messageParams: {}
+    });
     const identity = hash([provider.id, provider.baseUrl, connection.apiKey]);
     const previous = session.binding.connectionIdentities?.[provider.id];
     const expected = receiptBinding?.connectionIdentities?.[provider.id];
@@ -207,7 +213,9 @@ export function createCodexDriverConnection({
     if (requireBound && (previous !== expected || identity !== expected)) {
       throw new Error("The completed Codex response belongs to a different provider account binding.");
     }
-    if (previous && previous !== identity) throw new Error("This conversation belongs to another Codex provider account. Restore that connection or start a new conversation.");
+    if (previous && previous !== identity) throw Object.assign(new Error("This conversation belongs to another Codex provider account. Restore that connection or start a new conversation."), {
+      messageCode: "assistant.codex.otherProviderAccount", messageParams: {}
+    });
     if (!previous) await updateBinding({ connectionIdentities: { ...session.binding.connectionIdentities, [provider.id]: identity } });
     return { model: model.id, providerId: provider.id, accountIdentity: identity, config: codexProviderConfiguration(provider, connection.apiKey) };
   }
@@ -250,7 +258,9 @@ export function createCodexDriverConnection({
     const identity = await accountIdentity(session.native.client, signal);
     if (session.binding.accountIdentity && session.binding.accountIdentity !== identity) {
       providerOwner.closeProvider(providerKey);
-      throw new Error("This conversation belongs to another Codex account. Restore that account or start a new conversation.");
+      throw Object.assign(new Error("This conversation belongs to another Codex account. Restore that account or start a new conversation."), {
+        messageCode: "assistant.codex.otherAccount", messageParams: {}
+      });
     }
     if (!session.binding.accountIdentity) await updateBinding({ accountIdentity: identity });
   }
@@ -315,7 +325,9 @@ export function createCodexDriverConnection({
         async write({ threadId }) { await updateBinding({ threadId, toolSchemaIdentity }); } }
     });
     if (!retainedThreadId && prepared.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: {}
+      });
     }
     owner.subscribeEvents(sessionId, session.native, prepared.threadId, { providerKey });
     return { ...selected, resumeOptions: params };

package/src/server/conversation/providers/codexDriverTurns.js

@@ -274,7 +274,9 @@ export function createCodexDriverTurns({
     const admission = Promise.withResolvers();
     completion.promise.catch(() => {});
     admission.promise.catch(() => {});
-    if (input.goal) throw new Error("Codex goals are controls. Inspect any unresolved goal-message record before continuing.");
+    if (input.goal) throw Object.assign(new Error("Codex goals are controls. Inspect any unresolved goal-message record before continuing."), {
+      messageCode: "assistant.codex.goalsAreControls", messageParams: {}
+    });
     const active = session.current = { configuration, context, inputId: input.messageId,
       onEvent, onNativeTurn, signal, completion, admission, inputReady: admission.promise, finishIfCurrent,
       admitted: false, dispatched: false, turnId: "" };

package/src/server/conversation/providers/opencode.js

@@ -39,7 +39,9 @@ export function createOpenCodeConversationAdapter({ resolveInstructions }) {
       });
     }
     const text = await current.text;
-    if (contexts.get(id) !== current) throw new Error("Conversation context changed while reading instructions. Retry before sending.");
+    if (contexts.get(id) !== current) throw Object.assign(new Error("Conversation context changed while reading instructions. Retry before sending."), {
+      messageCode: "assistant.conversation.contextChangedReadingInstructions", messageParams: {}
+    });
     const previous = contributions.get(output.system);
     if (previous !== undefined) {
       const index = output.system.indexOf(previous);

package/src/server/conversation/providers/opencodeDriver.js

@@ -272,7 +272,9 @@ export function createOpenCodeConversationDriver({
           return representation === "native" ? result : { accepted: result.admission === "accepted" };
         },
         async run(command) {
-          if (disposed || current) throw new Error("This OpenCode conversation is closed or already working.");
+          if (disposed || current) throw Object.assign(new Error("This OpenCode conversation is closed or already working."), {
+            messageCode: "assistant.opencode.closedOrWorking", messageParams: {}
+          });
           const active = { context: command.context, failure: Promise.withResolvers(),
             ...(command.tools ? { tools: command.tools, messageIds: new Map() } : {}) };
           let failure;