@jskit-ai/assistant-core 0.1.244 → 0.2.0

package/src/client/conversation/submitText.js

@@ -1,3 +1,8 @@
+// Client-made errors keep their English message; messageCode lets a caller show
+// them in the active language through useJskitText().serverMessage(error).
+const CANNOT_SEND_YET = "Your words are in the chat box, but this conversation cannot send yet.";
+const submissionError = (message, { messageCode }) => Object.assign(new Error(message), { messageCode, messageParams: {} });
+
 /** A companion's text enters the same draft and send action as keyboard input. */
 export function createAssistantTextSubmission({ getState, setDraft, submit, afterDraftChange = async () => {} }) {
   let revision = 0;
@@ -5,7 +10,9 @@ export function createAssistantTextSubmission({ getState, setDraft, submit, afte
     const request = ++revision;
     const value = String(text || "").trim();
     const initial = getState();
-    if (!value || !initial.active || signal?.aborted) throw new Error("The chat composer is not ready yet.");
+    if (!value || !initial.active || signal?.aborted) {
+      throw submissionError("The chat composer is not ready yet.", { messageCode: "assistant.composer.notReady" });
+    }
     const hasDraft = Boolean(initial.draft?.trim());
     const writtenValue = hasDraft ? `${initial.draft}\n${value}` : value;
     setDraft(writtenValue);
@@ -15,14 +22,14 @@ export function createAssistantTextSubmission({ getState, setDraft, submit, afte
     while (true) {
       const state = getState();
       if (signal?.aborted || request !== revision || !state.active || state.id !== initial.id || state.draft !== writtenValue) {
-        throw new Error("The chat changed before sending. Review the draft before sending.");
+        throw submissionError("The chat changed before sending. Review the draft before sending.", { messageCode: "assistant.composer.chatChanged" });
       }
       if (state.canSend) {
         const result = await submit();
-        if (result === false) throw new Error("Your words are in the chat box, but this conversation cannot send yet.");
+        if (result === false) throw submissionError(CANNOT_SEND_YET, { messageCode: "assistant.composer.cannotSendYet" });
         return state.turnActive ? "steer" : "send";
       }
-      if (Date.now() >= deadline) throw new Error("Your words are in the chat box, but this conversation cannot send yet.");
+      if (Date.now() >= deadline) throw submissionError(CANNOT_SEND_YET, { messageCode: "assistant.composer.cannotSendYet" });
       await new Promise((resolve) => setTimeout(resolve, 16));
     }
   };

package/src/client/conversation/useAssistantAttachments.js

@@ -8,6 +8,16 @@ import {
   watch
 } from "vue";
 import { ASSISTANT_ATTACHMENT_MAX_ITEMS } from "../../shared/conversation/attachments.js";
+import { useJskitText } from "../i18n.js";
+import { attachmentLimitText } from "./attachmentSize.js";
+
+const { serverMessage, t } = useJskitText();
+
+// An upload or preparation failure in the active language; a thrown error keeps
+// its own English when it has no translation.
+function attachmentErrorText(error, fallback) {
+  return String((error && typeof error === "object" && serverMessage(error)) || error?.message || error || fallback);
+}
 
 function assistantAttachmentSessionId(sessionId) {
   return String(toValue(sessionId) || "").trim();
@@ -217,9 +227,6 @@ function useAssistantAttachments({
   if (![maxBytes, maxItems, uploadConcurrency].every(value => Number.isSafeInteger(value) && value > 0)) {
     throw new TypeError("Attachment limits must be positive integers.");
   }
-  const maxSizeLabel = maxBytes % (1024 * 1024) === 0
-    ? `${maxBytes / (1024 * 1024)} MiB`
-    : `${maxBytes / 1_000_000} MB`;
   const attachments = ref([]);
   const queueItems = ref([]);
   const dragDepth = ref(0);
@@ -266,10 +273,13 @@ function useAssistantAttachments({
     };
   });
 
-  function reportAttachmentError(error, fallbackMessage = "Attachment upload failed.", {
+  const tooLarge = (row) => t("jskit.assistant.attachments.error.tooLarge", { fileName: row.fileName, limit: attachmentLimitText(maxBytes) });
+  const tooMany = () => t("jskit.assistant.attachments.error.tooMany", { count: maxItems });
+
+  function reportAttachmentError(error, fallbackMessage = t("jskit.assistant.attachments.error.uploadFailed"), {
     notify = true
   } = {}) {
-    const message = String(error?.message || error || fallbackMessage);
+    const message = attachmentErrorText(error, fallbackMessage);
     status.value = message;
     if (notify && typeof onError === "function") {
       try {
@@ -319,7 +329,7 @@ function useAssistantAttachments({
 
   function trackCleanup(task) {
     const cleanup = Promise.resolve(task).catch((error) => {
-      reportAttachmentError(error, "Attachment cleanup failed.");
+      reportAttachmentError(error, t("jskit.assistant.attachments.error.cleanupFailed"));
       return false;
     });
     cleanupTasks.add(cleanup);
@@ -334,7 +344,7 @@ function useAssistantAttachments({
     }
     const response = await deleteAttachment(currentSessionId, attachmentId);
     if (response?.ok === false) {
-      throw new Error(attachmentUploadError(response) || "Attachment cleanup failed.");
+      throw new Error(attachmentUploadError(response) || t("jskit.assistant.attachments.error.cleanupFailed"));
     }
     return true;
   }
@@ -424,11 +434,11 @@ function useAssistantAttachments({
       }
       row.activeHandoffToken = null;
       removeReadyReceipt(row);
-      row.error = String(error?.message || error || "Uploaded attachment could not be used.");
+      row.error = attachmentErrorText(error, t("jskit.assistant.attachments.error.unusable"));
       row.failureStage = "handoff";
       row.phase = "failed";
       settleWaiter(row, null, waiter);
-      reportAttachmentError(error, "Uploaded attachment could not be used.", { notify: false });
+      reportAttachmentError(error, t("jskit.assistant.attachments.error.unusable"), { notify: false });
       return null;
     }
   }
@@ -468,13 +478,13 @@ function useAssistantAttachments({
       await handOffUploadedAttachment(row, receipt, attempt.waiter);
     } else {
       const error = uploadError || new Error(
-        attachmentUploadError(uploaded) || "Attachment upload failed."
+        attachmentUploadError(uploaded) || t("jskit.assistant.attachments.error.uploadFailed")
       );
-      row.error = String(error?.message || error || "Attachment upload failed.");
+      row.error = attachmentErrorText(error, t("jskit.assistant.attachments.error.uploadFailed"));
       row.failureStage = "upload";
       row.phase = "failed";
       settleWaiter(row, null, attempt.waiter);
-      reportAttachmentError(error, "Attachment upload failed.", { notify: false });
+      reportAttachmentError(error, t("jskit.assistant.attachments.error.uploadFailed"), { notify: false });
     }
     pumpQueue();
   }
@@ -572,7 +582,7 @@ function useAssistantAttachments({
       return Promise.resolve(null);
     }
     if (row.phase === "cancelled" && retainedItemCount.value >= maxItems) {
-      reportAttachmentError(`A message can keep at most ${maxItems} attachments.`);
+      reportAttachmentError(tooMany());
       return Promise.resolve(null);
     }
     if (row.failureStage === "handoff" && row.receipt) {
@@ -588,10 +598,10 @@ function useAssistantAttachments({
       return waiter.promise;
     }
     if (row.size > maxBytes) {
-      row.error = `${row.fileName} is larger than the ${maxSizeLabel} attachment limit.`;
+      row.error = tooLarge(row);
       row.failureStage = "validation";
       row.phase = "failed";
-      reportAttachmentError(row.error, "Attachment upload failed.", { notify: false });
+      reportAttachmentError(row.error, t("jskit.assistant.attachments.error.uploadFailed"), { notify: false });
       return Promise.resolve(null);
     }
     row.bytesSent = 0;
@@ -763,18 +773,20 @@ function useAssistantAttachments({
   function queuePreparedFile(row, file, waiter = row.waiter) {
     const preparedFile = assistantAttachmentFiles([file])[0];
     if (!preparedFile) {
-      throw new Error("The prepared attachment did not produce a file.");
+      throw Object.assign(new Error("The prepared attachment did not produce a file."), {
+        messageCode: "assistant.attachments.error.noFile", messageParams: {}
+      });
     }
     row.file = preparedFile;
     row.fileName = attachmentFileName(preparedFile);
     row.size = Number(preparedFile.size) || 0;
     row.totalBytes = row.size;
     if (row.size > maxBytes) {
-      row.error = `${row.fileName} is larger than the ${maxSizeLabel} attachment limit.`;
+      row.error = tooLarge(row);
       row.failureStage = "validation";
       row.phase = "failed";
       settleWaiter(row, null, waiter);
-      reportAttachmentError(row.error, "Attachment upload failed.", { notify: false });
+      reportAttachmentError(row.error, t("jskit.assistant.attachments.error.uploadFailed"), { notify: false });
       return false;
     }
     row.phase = "queued";
@@ -807,11 +819,11 @@ function useAssistantAttachments({
       try {
         queuePreparedFile(row, file, waiter);
       } catch (error) {
-        row.error = String(error?.message || error || "Attachment preparation failed.");
+        row.error = attachmentErrorText(error, t("jskit.assistant.attachments.error.preparationFailed"));
         row.failureStage = "preparing";
         row.phase = "failed";
         settleWaiter(row, null, waiter);
-        reportAttachmentError(error, "Attachment preparation failed.", { notify: false });
+        reportAttachmentError(error, t("jskit.assistant.attachments.error.preparationFailed"), { notify: false });
       }
       return file;
     }, (error) => {
@@ -825,10 +837,10 @@ function useAssistantAttachments({
         row.phase = "cancelled";
         row.error = "";
       } else {
-        row.error = String(error?.message || error || "Attachment preparation failed.");
+        row.error = attachmentErrorText(error, t("jskit.assistant.attachments.error.preparationFailed"));
         row.failureStage = "preparing";
         row.phase = "failed";
-        reportAttachmentError(error, "Attachment preparation failed.", { notify: false });
+        reportAttachmentError(error, t("jskit.assistant.attachments.error.preparationFailed"), { notify: false });
       }
       settleWaiter(row, null, waiter);
       return null;
@@ -836,13 +848,13 @@ function useAssistantAttachments({
   }
 
   function uploadFileProducer({
-    fileName = "Preparing attachment…",
+    fileName = t("jskit.assistant.attachments.preparingName"),
     produce
   } = {}) {
     const currentSessionId = assistantAttachmentSessionId(sessionId);
     if (!canAddFiles.value || typeof produce !== "function") {
       if (atCapacity.value) {
-        reportAttachmentError(`A message can keep at most ${maxItems} attachments.`);
+        reportAttachmentError(tooMany());
       }
       return Promise.resolve(null);
     }
@@ -875,7 +887,7 @@ function useAssistantAttachments({
     const availableSlots = Math.max(0, maxItems - retainedItemCount.value);
     const acceptedFiles = uploadableFiles.slice(0, availableSlots);
     if (acceptedFiles.length < uploadableFiles.length) {
-      reportAttachmentError(`A message can keep at most ${maxItems} attachments.`);
+      reportAttachmentError(tooMany());
     }
 
     const waiters = [];
@@ -884,11 +896,11 @@ function useAssistantAttachments({
       const waiter = row.waiter;
       waiters.push(waiter.promise);
       if (row.size > maxBytes) {
-        row.error = `${row.fileName} is larger than the ${maxSizeLabel} attachment limit.`;
+        row.error = tooLarge(row);
         row.failureStage = "validation";
         row.phase = "failed";
         settleWaiter(row, null);
-        reportAttachmentError(row.error, "Attachment upload failed.", { notify: false });
+        reportAttachmentError(row.error, t("jskit.assistant.attachments.error.uploadFailed"), { notify: false });
       } else {
         uploadQueue.push(row);
       }
@@ -910,9 +922,7 @@ function useAssistantAttachments({
     const files = assistantAttachmentFilesFromPasteEvent(event);
     if (files.length < 1) {
       if (assistantAttachmentClipboardLocalFileReference(event)) {
-        reportAttachmentError(
-          "Copied local files cannot be pasted from this browser. Drop the file or use Attach files."
-        );
+        reportAttachmentError(t("jskit.assistant.attachments.error.localFilePaste"));
       }
       return [];
     }

package/src/client/conversation/useAssistantSuggestions.js

@@ -1,4 +1,7 @@
 import { computed, onScopeDispose, ref, toValue, unref, watch } from "vue";
+import { useJskitText } from "../i18n.js";
+
+const { serverMessage } = useJskitText();
 
 /** Suggestion requests use an application-supplied agent; credentials stay on its server. */
 export function useAssistantSuggestions({
@@ -53,7 +56,7 @@ export function useAssistantSuggestions({
         }
         items.value = result.map(({ label, prompt }) => ({ label: label.trim(), prompt: prompt.trim() }));
       } catch (failure) {
-        if (request === controller && !controller.signal.aborted) error.value = String(failure.message || failure);
+        if (request === controller && !controller.signal.aborted) error.value = String(serverMessage(failure) || failure);
       } finally {
         if (request === controller) {
           request = null;

package/src/client/i18n.js

@@ -0,0 +1,6 @@
+import { registerJskitMessages, useJskitText } from "@jskit-ai/kernel/client";
+import en from "../../locales/en.json" with { type: "json" };
+
+registerJskitMessages(en);
+
+export { useJskitText };

package/src/client/lib/assistantApi.js

@@ -9,10 +9,22 @@ import {
   normalizeAssistantStreamEventType
 } from "../../shared/index.js";
 
+const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+
+// A stream error event keeps its code and English message, plus the params and
+// messageCode useJskitText().serverMessage(error) needs to show it in the active language.
 function buildStreamEventError(event) {
-  const message = String(event?.message || "Assistant request failed.");
-  const error = new Error(message);
+  const sent = String(event?.message || "");
+  const error = new Error(sent || "Assistant request failed.");
   error.code = String(event?.code || "assistant_stream_error");
+  error.params = isRecord(event?.params) ? event.params : {};
+  if (event?.messageCode) {
+    error.messageCode = String(event.messageCode);
+    error.messageParams = isRecord(event.messageParams) ? event.messageParams : {};
+  } else if (!sent) {
+    error.messageCode = "assistant.api.requestFailed";
+    error.messageParams = {};
+  }
   error.status = Number(event?.status || 500);
   error.event = event && typeof event === "object" ? { ...event } : null;
   return error;

package/src/server/conversation/attachments.js

@@ -1,15 +1,18 @@
 import path from "node:path";
 import { ASSISTANT_ATTACHMENT_ID_MAX_LENGTH, ASSISTANT_ATTACHMENT_MAX_ITEMS, conversationAttachmentManifest } from "../../shared/conversation/attachments.js";
 
-function invalid(message) {
-  return Object.assign(new Error(message), { code: "conversation_invalid_attachments", statusCode: 400 });
+// messageCode names the sentence; the shared code stays for callers.
+function invalid(message, { messageCode, messageParams = {} }) {
+  return Object.assign(new Error(message), { code: "conversation_invalid_attachments", statusCode: 400, messageCode, messageParams });
 }
 
 export function conversationAttachmentIds(value = []) {
   if (!Array.isArray(value) || value.length > ASSISTANT_ATTACHMENT_MAX_ITEMS ||
       value.some(id => typeof id !== "string" || !id.trim() || id.length > ASSISTANT_ATTACHMENT_ID_MAX_LENGTH) ||
       new Set(value).size !== value.length) {
-    throw invalid(`Attachments require at most ${ASSISTANT_ATTACHMENT_MAX_ITEMS} distinct, nonempty attachment IDs.`);
+    throw invalid(`Attachments require at most ${ASSISTANT_ATTACHMENT_MAX_ITEMS} distinct, nonempty attachment IDs.`, {
+      messageCode: "assistant.conversation.attachmentIdsInvalid", messageParams: { max: ASSISTANT_ATTACHMENT_MAX_ITEMS }
+    });
   }
   return [...value];
 }
@@ -20,7 +23,8 @@ export function createConversationAttachmentReader({ attachments, context, conve
   return async references => {
     if (!references?.length) return { attachments: [], content: [], localFiles: [], attachmentManifest: "" };
     if (typeof attachments?.resolve !== "function") {
-      throw Object.assign(new Error("File attachments are not configured for this conversation."), { code: "conversation_unsupported", statusCode: 400 });
+      throw Object.assign(new Error("File attachments are not configured for this conversation."), { code: "conversation_unsupported", statusCode: 400,
+        messageCode: "assistant.conversation.attachmentsNotConfigured", messageParams: {} });
     }
     const receipts = [];
     const content = [];
@@ -38,16 +42,19 @@ export function createConversationAttachmentReader({ attachments, context, conve
           (local ? !Array.isArray(resolved.localFiles) || resolved.localFiles.length !== attachmentIds.length ||
             resolved.content !== undefined && (!Array.isArray(resolved.content) || resolved.content.length)
             : !Array.isArray(resolved.content) || !resolved.content.length || resolved.content.length > 100)) {
-        throw invalid("The attachment resolver must return a receipt for every requested file and bounded model content.");
+        throw invalid("The attachment resolver must return a receipt for every requested file and bounded model content.",
+          { messageCode: "assistant.conversation.attachmentResolverIncomplete" });
       }
       if (local && !types.includes("localFile")) {
-        throw invalid("This engine cannot accept local attachment files. Supply extracted text or supported image bytes.");
+        throw invalid("This engine cannot accept local attachment files. Supply extracted text or supported image bytes.",
+          { messageCode: "assistant.conversation.attachmentLocalFilesUnsupported" });
       }
       for (const [index, receipt] of resolved.attachments.entries()) {
         if (receipt?.attachmentId !== attachmentIds[index] || typeof receipt.fileName !== "string" || !receipt.fileName.trim() ||
             receipt.fileName.length > 256 || !Number.isSafeInteger(receipt.size) || receipt.size < 0 ||
             receipt.reference !== undefined && (typeof receipt.reference !== "string" || receipt.reference.length > 256)) {
-          throw invalid("Attachment receipts require the requested ID, a bounded fileName and a nonnegative size.");
+          throw invalid("Attachment receipts require the requested ID, a bounded fileName and a nonnegative size.",
+            { messageCode: "assistant.conversation.attachmentReceiptInvalid" });
         }
         receipts.push({ attachmentId: receipt.attachmentId, fileName: receipt.fileName, size: receipt.size,
           ...(receipt.reference ? { reference: receipt.reference } : {}) });
@@ -57,16 +64,18 @@ export function createConversationAttachmentReader({ attachments, context, conve
               typeof receipt.reference !== "string" || !receipt.reference.trim() || file.reference !== receipt.reference ||
               typeof file.path !== "string" || !path.isAbsolute(file.path) || file.path.includes("\0") ||
               typeof file.contentType !== "string" || !/^[\w.+-]+\/[\w.+-]+$/u.test(file.contentType)) {
-            throw invalid("Local attachment files require their exact requested receipt and an authorized absolute native path.");
+            throw invalid("Local attachment files require their exact requested receipt and an authorized absolute native path.",
+              { messageCode: "assistant.conversation.attachmentLocalFileInvalid" });
           }
           localFiles.push({ attachmentId: file.attachmentId, fileName: file.fileName, size: file.size,
             reference: file.reference, contentType: file.contentType, path: file.path });
         }
       }
       for (const part of resolved.content || []) {
-        if (!types.includes(part?.type)) throw invalid("This engine cannot accept that attachment format. Supply extracted text or a supported image.");
+        if (!types.includes(part?.type)) throw invalid("This engine cannot accept that attachment format. Supply extracted text or a supported image.",
+          { messageCode: "assistant.conversation.attachmentFormatUnsupported" });
         if (part.type === "text") {
-          if (typeof part.text !== "string" || !part.text.trim()) throw invalid("Attachment text must be nonempty.");
+          if (typeof part.text !== "string" || !part.text.trim()) throw invalid("Attachment text must be nonempty.", { messageCode: "assistant.conversation.attachmentTextEmpty" });
           bytes += Buffer.byteLength(part.text);
           content.push({ type: "text", text: part.text });
         } else {
@@ -75,19 +84,20 @@ export function createConversationAttachmentReader({ attachments, context, conve
               !/^[\w.+-]+\/[\w.+-]+$/u.test(part.mediaType) ||
               part.type === "image" && !["image/png", "image/jpeg", "image/webp", "image/gif"].includes(part.mediaType) ||
               part.filename !== undefined && (typeof part.filename !== "string" || part.filename.length > 256)) {
-            throw invalid("Attachments require authorized bytes and a supported media type; remote URLs and paths are not accepted.");
+            throw invalid("Attachments require authorized bytes and a supported media type; remote URLs and paths are not accepted.",
+              { messageCode: "assistant.conversation.attachmentBytesRequired" });
           }
           bytes += data.byteLength;
-          if (bytes > maximumBytes) throw invalid("Attachment content exceeds the configured byte limit for this request.");
+          if (bytes > maximumBytes) throw invalid("Attachment content exceeds the configured byte limit for this request.", { messageCode: "assistant.conversation.attachmentBytesExceeded" });
           content.push(part.type === "image" ? { type: "image", image: Buffer.from(data), mediaType: part.mediaType }
             : { type: "file", data: Buffer.from(data), mediaType: part.mediaType, ...(part.filename ? { filename: part.filename } : {}) });
         }
-        if (bytes > maximumBytes) throw invalid("Attachment content exceeds the configured byte limit for this request.");
+        if (bytes > maximumBytes) throw invalid("Attachment content exceeds the configured byte limit for this request.", { messageCode: "assistant.conversation.attachmentBytesExceeded" });
       }
     }
     const attachmentManifest = conversationAttachmentManifest(localFiles);
     bytes += Buffer.byteLength(attachmentManifest);
-    if (bytes > maximumBytes) throw invalid("Attachment content exceeds the configured byte limit for this request.");
+    if (bytes > maximumBytes) throw invalid("Attachment content exceeds the configured byte limit for this request.", { messageCode: "assistant.conversation.attachmentBytesExceeded" });
     await authorize();
     return { attachments: receipts, content, localFiles, attachmentManifest };
   };

package/src/server/conversation/claudeProcess.js

@@ -67,7 +67,8 @@ async function readNativeClaudeCodeAuthStatus({ env, credentialHome, command, co
     credentialHome, cwd: credentialHome.home, mode: "capture",
     timeout: 30_000, maxBuffer: 64 * 1024, ...(signal ? { signal } : {})
   });
-  const failure = { loggedIn: false, error: result.error || "Claude Code is not connected." };
+  const failure = result.error ? { loggedIn: false, error: result.error }
+    : { loggedIn: false, error: "Claude Code is not connected.", messageCode: "assistant.claude.notConnected", messageParams: {} };
   if (!result.ok && (result.exitCode !== 1 || result.timedOut || result.signal)) return failure;
   try {
     const status = JSON.parse(result.stdout || result.output);
@@ -77,7 +78,8 @@ async function readNativeClaudeCodeAuthStatus({ env, credentialHome, command, co
     return { loggedIn: status.loggedIn === true, email: String(status.email || ""),
       authMethod: String(status.authMethod || ""), subscriptionType: String(status.subscriptionType || "") };
   } catch {
-    return result.ok ? { loggedIn: false, error: "Claude Code returned an invalid account status." } : failure;
+    return result.ok ? { loggedIn: false, error: "Claude Code returned an invalid account status.",
+      messageCode: "assistant.claude.accountStatusInvalid", messageParams: {} } : failure;
   }
 }
 

package/src/server/conversation/claudeTurn.js

@@ -108,8 +108,8 @@ export async function runClaudeRenewalTurn(conversation, {
 export function createClaudeConversationGoals({ conversationId, readHistory, readState, interrupt, send, readRetainedGoal, saveRetainedGoal }) {
   // These checks run before interrupt/send. Native execution and receipt
   // failures keep their own codes and must not be treated as safe rejections.
-  const goalError = message => Object.assign(failure(message, "conversation_invalid_goal"), {
-    statusCode: 400, delivery: "not-sent"
+  const goalError = (message, { messageCode }) => Object.assign(failure(message, "conversation_invalid_goal"), {
+    statusCode: 400, delivery: "not-sent", messageCode, messageParams: {}
   });
 
   async function read(history = null) {
@@ -127,13 +127,14 @@ export function createClaudeConversationGoals({ conversationId, readHistory, rea
     const action = input.action;
     if (action !== "set" && (!goal || input.threadId !== conversationId ||
         input.createdAt !== goal.createdAt || input.objective !== goal.objective)) {
-      throw goalError("The Claude goal changed. Refresh before trying again.");
+      throw goalError("The Claude goal changed. Refresh before trying again.", { messageCode: "assistant.claude.goalChanged" });
     }
-    if (input.tokenBudget != null) throw goalError("Claude goals do not support a token budget.");
+    if (input.tokenBudget != null) throw goalError("Claude goals do not support a token budget.", { messageCode: "assistant.claude.goalTokenBudgetUnsupported" });
     if (action === "pause" || action === "block") {
       const reason = typeof input.reason === "string" ? input.reason.trim() : "";
       if (action === "block" && (!reason || reason.length > 1000 || goal.status !== "active")) {
-        throw goalError("An active Claude goal needs a blocker reason of up to 1,000 characters.");
+        throw goalError("An active Claude goal needs a blocker reason of up to 1,000 characters.",
+          { messageCode: "assistant.claude.goalBlockerReasonRequired" });
       }
       if (goal.status !== "complete") await saveRetainedGoal({ ...goal,
         status: action === "block" ? "blocked" : "paused", ...(action === "block" ? { reason } : {}) });
@@ -144,13 +145,13 @@ export function createClaudeConversationGoals({ conversationId, readHistory, rea
     } else if (action === "set" || action === "resume") {
       const objective = String((action === "set" ? input.objective : goal.objective) ?? "").trim();
       if (!objective || objective.length > 4000 || /^(clear|stop|off|reset|none|cancel)$/iu.test(objective)) {
-        throw goalError("Enter a goal condition of up to 4,000 characters.");
+        throw goalError("Enter a goal condition of up to 4,000 characters.", { messageCode: "assistant.claude.goalConditionRequired" });
       }
       if (action === "set" && goal && goal.status !== "complete") {
-        throw goalError("Cancel the existing goal before setting another.");
+        throw goalError("Cancel the existing goal before setting another.", { messageCode: "assistant.claude.goalAlreadySet" });
       }
       await sendGoal({ message: `/goal ${objective}`, signal });
-    } else throw goalError("Unknown Claude goal action.");
+    } else throw goalError("Unknown Claude goal action.", { messageCode: "assistant.claude.goalActionUnknown" });
   }
 
   return Object.freeze({ read, update });
@@ -552,7 +553,8 @@ export function createClaudeConversationOwner({
   async function compactContext(entry, input = {}) {
     input.signal?.throwIfAborted();
     if (entry.turn?.active || entry.nativeTurn.read().active) {
-      throw Object.assign(createError("Claude is still working. Wait for it to finish before freeing its context."), { statusCode: 409 });
+      throw Object.assign(createError("Claude is still working. Wait for it to finish before freeing its context."), { statusCode: 409,
+        messageCode: "assistant.claude.compactWhileWorking", messageParams: {} });
     }
     await ensureProcess(entry, input);
     input.signal?.throwIfAborted();
@@ -1684,7 +1686,8 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
       if (!active || stopped || cancelling) throw Object.assign(
         failure("Claude has no active turn for this message.", !active && !stopped && !cancelling
           ? "conversation_steer_turn_finished" : "assistant_claude_turn_failed"),
-        { delivery: "not-sent", ...(!active && !stopped && !cancelling ? { statusCode: 409 } : {}) }
+        { delivery: "not-sent", messageCode: "assistant.claude.noActiveTurn", messageParams: {},
+          ...(!active && !stopped && !cancelling ? { statusCode: 409 } : {}) }
       );
       if (!uuid || typeof accept !== "function" || admissions.has(uuid)) throw new TypeError("A distinct message id and admission writer are required.");
       clearFinalAssistantResult();
@@ -1714,7 +1717,7 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
         const completed = !active && !stopped && !cancelling && outcome?.status === "completed";
         throw Object.assign(failure("This Claude turn cannot accept steering now.", completed
           ? "conversation_steer_turn_finished" : "assistant_claude_turn_failed"),
-        { delivery: "not-sent", ...(completed ? { statusCode: 409 } : {}) });
+        { delivery: "not-sent", messageCode: "assistant.claude.steeringUnavailable", messageParams: {}, ...(completed ? { statusCode: 409 } : {}) });
       }
       // Claude Code acknowledges streamed input as queued and folds it into the
       // running turn after the current tool call, or starts it once the main

package/src/server/conversation/codexConversations.js

@@ -655,6 +655,8 @@ export function createCodexConversationCommands({
           return {
             code: `${errorPrefix}codex_detached_thread_delete_unavailable`,
             error: "Codex app-server thread deletion is not available.",
+            messageCode: "assistant.codex.threadDeleteUnavailable",
+            messageParams: {},
             ok: false,
             statusCode: 409,
             threadId
@@ -869,6 +871,8 @@ export function createCodexConversationCommands({
       return {
         code: `${errorPrefix}temporary_conversation_turn_active`,
         error: "Temporary AI is already working on this conversation.",
+        messageCode: "assistant.codex.temporaryConversationBusy",
+        messageParams: {},
         ok: false
       };
     }

package/src/server/conversation/codexGoalCommands.js

@@ -27,11 +27,11 @@ export function createCodexGoalCommands({
 
   function validateCodexAppServerGoalInput(input = {}) {
     if (!["set", "pause", "resume", "cancel"].includes(input.action)) {
-      return { ok: false, error: "Choose set, pause, resume, or cancel." };
+      return { ok: false, error: "Choose set, pause, resume, or cancel.", messageCode: "assistant.codex.goalActionInvalid", messageParams: {} };
     }
     if (input.action === "set" && (typeof input.objective !== "string" || !input.objective.trim() ||
         (input.tokenBudget !== undefined && (!Number.isSafeInteger(input.tokenBudget) || input.tokenBudget <= 0)))) {
-      return { ok: false, error: "Enter a goal objective and an optional positive whole-number token budget." };
+      return { ok: false, error: "Enter a goal objective and an optional positive whole-number token budget.", messageCode: "assistant.codex.goalObjectiveInvalid", messageParams: {} };
     }
     return null;
   }
@@ -46,11 +46,11 @@ export function createCodexGoalCommands({
     if (context.ok === false) return context;
     let threadId = context.threadId;
     if (threadId !== input.threadId || (!threadId && input.action !== "set")) {
-      return { ok: false, error: "The Codex conversation changed. Refresh the goal before trying again." };
+      return { ok: false, error: "The Codex conversation changed. Refresh the goal before trying again.", messageCode: "assistant.codex.goalConversationChanged", messageParams: {} };
     }
     if (input.action === "set") {
       if (turnState(context.session).status === "observation_lost") {
-        return { ok: false, error: "Resume or send a message to restore the stopped conversation before setting a goal." };
+        return { ok: false, error: "Resume or send a message to restore the stopped conversation before setting a goal.", messageCode: "assistant.codex.goalConversationStopped", messageParams: {} };
       }
       if (!threadId) {
         context = await prepareConversation();
@@ -59,7 +59,7 @@ export function createCodexGoalCommands({
       }
       const { goal: previousGoal } = await context.provider.readGoal(threadId);
       if (previousGoal && (previousGoal.status !== "complete" || previousGoal.createdAt !== input.createdAt)) {
-        return { ok: false, error: "The Codex goal changed. Refresh it before setting a new goal." };
+        return { ok: false, error: "The Codex goal changed. Refresh it before setting a new goal.", messageCode: "assistant.codex.goalChangedBeforeSet", messageParams: {} };
       }
       signal?.throwIfAborted();
       subscribeCodexAppServerEvents(sessionId, context.provider, threadId, context);
@@ -74,7 +74,7 @@ export function createCodexGoalCommands({
     }
     const { goal } = await context.provider.readGoal(threadId);
     if (!goal || goal.status === "complete" || goal.createdAt !== input.createdAt || goal.objective !== input.objective) {
-      return { ok: false, error: "The Codex goal changed. Refresh it before trying again." };
+      return { ok: false, error: "The Codex goal changed. Refresh it before trying again.", messageCode: "assistant.codex.goalChanged", messageParams: {} };
     }
     if (input.action === "cancel") {
       subscribeCodexAppServerEvents(sessionId, context.provider, threadId, context);
@@ -87,14 +87,14 @@ export function createCodexGoalCommands({
       return { ok: true, status: "available", threadId, goal: null };
     }
     if (input.action === "pause" && !["active", "paused"].includes(goal.status)) {
-      return { ok: false, error: "This goal is already stopped. Refresh its details." };
+      return { ok: false, error: "This goal is already stopped. Refresh its details.", messageCode: "assistant.codex.goalAlreadyStopped", messageParams: {} };
     }
     const observationLost = turnState(context.session).status === "observation_lost";
     if (observationLost && turnState(context.session).active) {
-      return { ok: false, error: "Codex has not yet confirmed a stop. Retry after the service has stopped." };
+      return { ok: false, error: "Codex has not yet confirmed a stop. Retry after the service has stopped.", messageCode: "assistant.codex.goalStopUnconfirmed", messageParams: {} };
     }
     if (input.action === "resume" && !["paused", "blocked", "usageLimited", ...(observationLost ? ["active"] : [])].includes(goal.status)) {
-      return { ok: false, error: "This goal cannot be resumed from its current status. Refresh its details." };
+      return { ok: false, error: "This goal cannot be resumed from its current status. Refresh its details.", messageCode: "assistant.codex.goalNotResumable", messageParams: {} };
     }
     subscribeCodexAppServerEvents(sessionId, context.provider, threadId, context);
     if (observationLost && input.action === "resume") {

package/src/server/conversation/codexHelperExecution.js

@@ -10,6 +10,10 @@ export function createCodexHelperOwnershipError({ applicationName = "Application
     );
     error.code = `${errorPrefix}codex_helper_ownership_blocked`;
     error.statusCode = 409;
+    if (!normalizeText(message)) {
+      error.messageCode = "assistant.codex.helperOwnershipBlocked";
+      error.messageParams = { applicationName };
+    }
     error.retryable = details.retryable !== false;
     error.details = {
       ...details,

package/src/server/conversation/codexHelperThreads.js

@@ -73,6 +73,8 @@ export function createCodexHelperThreadLifecycle({
     );
     error.code = `${errorPrefix}codex_helper_thread_unavailable`;
     error.statusCode = 409;
+    error.messageCode = "assistant.codex.helperThreadUnavailable";
+    error.messageParams = {};
     error.threadId = normalizeText(threadId);
     return error;
   }

package/src/server/conversation/codexMessageCommands.js

@@ -184,6 +184,8 @@ export function createCodexMessageCommands({
         code: steerFailedCode,
         delivered: false,
         error: "The active assistant turn is not ready to accept this message yet.",
+        messageCode: "assistant.codex.turnNotReady",
+        messageParams: {},
         ok: false,
         operationOutcome: "active_turn_not_ready",
         refreshRecommended: true,
@@ -266,7 +268,9 @@ export function createCodexMessageCommands({
     if (!userRequest && options.preparedInput === undefined) {
       return { value: {
         ok: false,
-        error: "Codex message is empty."
+        error: "Codex message is empty.",
+        messageCode: "assistant.codex.messageEmpty",
+        messageParams: {}
       } };
     }
 
@@ -363,6 +367,8 @@ export function createCodexMessageCommands({
       return { value: {
         code: steerFailedCode,
         error: "Codex message input is empty.",
+        messageCode: "assistant.codex.messageInputEmpty",
+        messageParams: {},
         ok: false,
         operationOutcome: "message_empty",
         refreshRecommended: false