@jskit-ai/assistant-runtime 0.1.238 → 0.2.0

package/src/client/composables/useAssistantConversation.js

@@ -15,8 +15,17 @@ import { resolveAssistantRuntimeRoute, resolveAssistantSurfaceConfig } from "../
 import { useWorkspaceWebScopeSupport } from "../support/workspaceScopeSupport.js";
 import { isAccessDenied } from "../support/accessDenied.js";
 import { subscribeAssistantConversation, refreshedHistoryPages, patchLoadedHistoryPages } from "../support/subscribeAssistantConversation.js";
+import { useJskitText } from "../i18n.js";
 
 const text = value => String(toValue(value) ?? "").trim();
+const { serverMessage, t } = useJskitText();
+// A failure in the active language when its code or messageCode is JSKIT's English;
+// otherwise its message as sent. A result's error text is read the same way.
+const failureMessage = (failure, fallback = "") => failure?.message ? serverMessage(failure) : fallback;
+const resultError = result => failureMessage({ ...result, message: result?.error });
+// A conversation snapshot's error names its runtime sentence with errorMessageCode.
+const stateError = state => failureMessage({ message: state?.error,
+  messageCode: state?.errorMessageCode, messageParams: state?.errorMessageParams });
 // Keep the injection key stable across optimized package and raw Vue imports.
 const conversationDefaultsKey = Symbol.for("jskit.assistant-runtime.conversation.defaults");
 const compareTurnIds = (left, right) => String(left).localeCompare(String(right), undefined, { numeric: true });
@@ -150,7 +159,7 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
     const restoredMessages = messages.filter(message => !delivery.find(message.id)).map(message => {
       const status = ["failed", "accepted"].includes(message.status) ? message.status : "uncertain";
       return { ...message, status, checking: false, error: message.error || (status === "accepted" ? "" :
-        "Delivery was not confirmed before this page closed. Check the conversation before retrying.") };
+        t("jskit.assistant.runtime.delivery.unconfirmedBeforeClose")) };
     });
     delivery.state.messages = unmatchedOptimisticMessages(turns.value, [...delivery.state.messages, ...restoredMessages], { receiptsOnly: true });
   } catch {
@@ -243,7 +252,7 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
   function receiveError(failure) {
     if (!current.value) return;
     loading.value = false;
-    error.value = failure.message;
+    error.value = failureMessage(failure);
     accessDenied.value = isAccessDenied(failure);
     if (accessDenied.value) {
       deniedHistoryRevision += 1;
@@ -286,7 +295,9 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
   async function readLoadedHistory({ current: subscriptionCurrent }) {
     const denial = deniedHistoryRevision;
     const valid = () => {
-      if (denial !== deniedHistoryRevision) throw Object.assign(new Error("Access denied."), { status: 403 });
+      if (denial !== deniedHistoryRevision) {
+        throw Object.assign(new Error("Access denied."), { status: 403, messageCode: "assistant.runtime.accessDenied" });
+      }
       return current.value && active.value && subscriptionCurrent();
     };
     // A concurrent Load older operation extends the desired span. Retry one
@@ -306,7 +317,11 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
         const reachedFullOldestTurn = page.pagination.oldestTurnId === oldest && !page.conversationLog[0]?.paginationPartial;
         const passedOldestTurn = compareTurnIds(page.pagination.oldestTurnId, oldest) < 0;
         if (cursor && (cursor === oldestCursor || passedOldestTurn || reachedFullOldestTurn)) break;
-        if (!cursor || cursors.has(cursor)) throw new Error("Older conversation history could not be refreshed. Reload chat to try again.");
+        if (!cursor || cursors.has(cursor)) {
+          throw Object.assign(new Error("Older conversation history could not be refreshed. Reload chat to try again."), {
+            messageCode: "assistant.runtime.history.refreshFailed"
+          });
+        }
         cursors.add(cursor);
         page = normalizeConversationLogPage(await api.readConversation(identity.conversationId, {
           beforeTurnId: cursor, limit: latest.pagination.limit
@@ -469,14 +484,14 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
               await subscription?.reload();
               if (error.value) return false;
               if (snapshot.value.status === "working" && !steerable.value) {
-                delivery.wait(messageId, "Waiting for the assistant to finish this step");
+                delivery.wait(messageId, t("jskit.assistant.runtime.delivery.waitingForStep"));
               }
               admission = await waitForAdmission(pending);
               delivery.wait(messageId, "");
               if (!admission || controller.signal.aborted || !available.value ||
                   snapshot.value.status !== (admission === "steer" ? "working" : "ready")) return false;
               if (submission.displayAttachments?.length && snapshot.value.capabilities?.attachments !== true) {
-                return { ok: false, error: "This conversation no longer accepts attachments." };
+                return { ok: false, error: t("jskit.assistant.runtime.attachments.noLongerAccepted") };
               }
             }
             let request = prepare ? await prepare(submission, { signal: controller.signal }) : submission.request;
@@ -520,14 +535,14 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
           }
           catch (failure) {
             if (controller.signal.aborted) return false;
-            if (prepare && !pending.dispatched) return { ok: false, error: failure.message,
+            if (prepare && !pending.dispatched) return { ok: false, error: failureMessage(failure),
               ...(failure.code ? { code: failure.code } : {}) };
             const rejection = failure.details?.delivery;
             const notSent = Number.isInteger(failure.status) && failure.status >= 400 && failure.status < 500 &&
               rejection && !Array.isArray(rejection) && rejection.status === "not-sent" && rejection.messageId === messageId;
             // A definite rejection keeps its code so the application can offer
             // the matching recovery, such as freeing assistant context.
-            if (notSent || SEND_REJECTIONS.has(failure.code) || failure.code === "conversation_steer_turn_finished" && failure.status === 409 && !failure.details?.delivery) return { ok: false, error: failure.message,
+            if (notSent || SEND_REJECTIONS.has(failure.code) || failure.code === "conversation_steer_turn_finished" && failure.status === 409 && !failure.details?.delivery) return { ok: false, error: failureMessage(failure),
               ...(failure.code ? { code: failure.code } : {}) };
             throw failure;
           } finally {
@@ -538,7 +553,7 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
       return result;
     } catch (failure) {
       // Delivery keeps its exact authored payload until an explicit receipt check.
-      if (prepare) return { ok: false, status: "uncertain", error: failure.message,
+      if (prepare) return { ok: false, status: "uncertain", error: failureMessage(failure),
         ...(failure.code ? { code: failure.code } : {}) };
       return false;
     } finally {
@@ -588,7 +603,7 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
       return true;
     } catch (failure) {
       if (current.value) {
-        loadMoreError.value = String(failure?.message || failure || "Older conversation history could not be loaded.");
+        loadMoreError.value = String(failureMessage(failure) || failure || t("jskit.assistant.runtime.history.loadFailed"));
         if (isAccessDenied(failure)) receiveError(failure);
       }
       finish({ changed: false, loaded: false });
@@ -619,7 +634,7 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
       return true;
     }).catch(failure => {
       if (current.value && !controller.signal.aborted && snapshot.value?.segmentId === segment) {
-        goalLoadError.value = failure.message || "Goal status is unavailable.";
+        goalLoadError.value = failureMessage(failure, t("jskit.assistant.runtime.goal.unavailable"));
       }
       return false;
     }).finally(() => {
@@ -642,7 +657,7 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
         !["message", "control"].includes(command?.delivery) ||
         delivery.state.messages.some(message => message.status === "uncertain")) return false;
     if (input.tokenBudget != null && !target.capabilities.goalBudgets) {
-      goalError.value = "This conversation does not support goal token budgets.";
+      goalError.value = t("jskit.assistant.runtime.goal.budgetsUnsupported");
       return false;
     }
     const retry = delivery.find(messageId);
@@ -656,21 +671,24 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
     try {
       if (retry || command.delivery === "message") {
         const result = await submitRequest(retry?.payload || {
-          message: action === "set" ? request.objective : action === "resume" ? "Resume the goal." : "Cancel the goal.",
+          message: action === "set" ? request.objective
+            : t(action === "resume" ? "jskit.assistant.runtime.goal.resumeMessage" : "jskit.assistant.runtime.goal.cancelMessage"),
           goalRequest: request
         }, { messageId });
         if (result === false || result?.ok === false) {
-          if (current.value) goalError.value = result?.error || delivery.find(messageId)?.error || "Could not change the goal.";
+          if (current.value) {
+            goalError.value = result?.error || delivery.find(messageId)?.error || t("jskit.assistant.runtime.goal.changeFailed");
+          }
           return false;
         }
         return result;
       }
       const result = await api.updateConversationGoal(identity.conversationId, request);
-      if (result?.ok === false) throw new Error(result.error || "Could not change the goal.");
+      if (result?.ok === false) throw new Error(resultError(result) || t("jskit.assistant.runtime.goal.changeFailed"));
       return result;
     } catch (failure) {
       if (current.value) {
-        goalError.value = failure.message;
+        goalError.value = failureMessage(failure);
         if (isAccessDenied(failure)) receiveError(failure);
       }
       return false;
@@ -730,14 +748,14 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
         delivery.accept(messageId);
         if (receipt.messageId === messageId && message?.payload.goalRequest) goalError.value = "";
       }
-      else if (receipt.status === "not-sent" && receipt.messageId === messageId) delivery.rejectUnsent(messageId, receipt.error);
+      else if (receipt.status === "not-sent" && receipt.messageId === messageId) delivery.rejectUnsent(messageId, resultError(receipt));
       else if (receipt.status === "unknown" && message?.status === "uncertain") {
-        message.error = "Delivery is still unknown. Retry to check again.";
+        message.error = t("jskit.assistant.runtime.delivery.stillUnknown");
       }
       subscription?.reload();
       return receipt;
     } catch (failure) {
-      if (current.value && message?.status === "uncertain") message.error = failure.message || "Delivery could not be checked.";
+      if (current.value && message?.status === "uncertain") message.error = failureMessage(failure, t("jskit.assistant.runtime.delivery.checkFailed"));
       receiveError(failure);
       return false;
     }
@@ -790,7 +808,7 @@ function useBoundedTask({ command, endpoint, scope, input, result, onResult }, {
     return {
       conversation: {
         turns: conversationTurnsFromMessages(messages.value.map(message => ({ ...message, text: message.content }))),
-        assistantLabel: display.assistantLabel || "Assistant", welcomeMessage: display.welcomeMessage,
+        assistantLabel: display.assistantLabel || t("jskit.assistant.runtime.conversation.assistantLabel"), welcomeMessage: display.welcomeMessage,
         visible: display.visible, retainWhenHidden: display.retainWhenHidden, variant: display.variant, scrollKey: toValue(scope)
       },
       composer: {
@@ -979,7 +997,7 @@ function createConversationBinding({ conversationId, endpoint = "", surfaceId =
         current.draftAttachments.value = current.draftAttachments.value.filter(file => !attachmentIds.includes(file.attachmentId));
         if (runtime.value === current) {
           try { attachments?.clearAttachments({ accepted: true, attachmentIds }); }
-          catch (failure) { current.error.value = failure?.message || "Accepted attachments could not be cleared from the composer."; }
+          catch (failure) { current.error.value = failureMessage(failure, t("jskit.assistant.runtime.attachments.clearFailed")); }
         }
       }
       onAccepted?.();
@@ -996,7 +1014,7 @@ function createConversationBinding({ conversationId, endpoint = "", surfaceId =
     if (retry?.status === "uncertain") return current.inspectDelivery(messageId).then(receipt => {
       if (!current.current.value || !isCurrent()) return false;
       if (receipt?.status !== "accepted") {
-        const error = current.error.value || "Message delivery is not confirmed.";
+        const error = current.error.value || t("jskit.assistant.runtime.delivery.notConfirmed");
         const pending = current.delivery.find(messageId);
         if (pending) pending.error = error;
         return { ok: false, status: "uncertain", error };
@@ -1027,12 +1045,13 @@ function createConversationBinding({ conversationId, endpoint = "", surfaceId =
       models: current?.available.value ? modelOwner.value : null, questions: prompts,
       goal: (toValue(goal) === true ? null : toValue(goal)) || current?.goalState.value || null,
       conversation: { turns: current?.turns.value || [], interimReply: state?.interimReply || null,
-        error: current?.error.value || state?.error || "", errorReloadable: Boolean(current) && !current.accessDenied.value,
+        error: current?.error.value || stateError(state), errorReloadable: Boolean(current) && !current.accessDenied.value,
         scrollKey: JSON.stringify(identity.value),
         hasMoreBefore: current?.hasMoreBefore.value || false,
         loadingMore: current?.loadingMore.value || false, loadMoreError: current?.loadMoreError.value || "",
         loading: current?.loading.value || false, working: !current?.error.value && state?.status === "working" && !current.delivery.state.sending,
-        assistantLabel: display.assistantLabel || "Assistant", welcomeMessage: display.welcomeMessage ?? "What would you like to do?",
+        assistantLabel: display.assistantLabel || t("jskit.assistant.runtime.conversation.assistantLabel"),
+        welcomeMessage: display.welcomeMessage ?? t("jskit.assistant.runtime.conversation.welcomeMessage"),
         systemLabel: display.systemLabel, variant: display.variant, visible: display.visible, retainWhenHidden: display.retainWhenHidden,
         userMessageFormat: display.userMessageFormat, progressPreviewLimit: display.progressPreviewLimit,
         previewMessage: current?.available.value ? display.previewMessage : null },
@@ -1042,10 +1061,10 @@ function createConversationBinding({ conversationId, endpoint = "", surfaceId =
         canStop: state?.status === "working" || state?.status === "unavailable", stopPending: current?.stopping.value || false,
         queueWhileSending: current?.queueWhileSending.value || false,
         ariaLabel: display.ariaLabel, submitAriaLabel: display.submitAriaLabel, submitLabel: display.submitLabel,
-        placeholder: formatsQuestions && prompts.questions?.length ? "Optional additional context…"
-          : formatsQuestions && prompts.choices?.length ? "Choose an answer above, or type another answer…"
-            : display.placeholder || "Message the assistant…",
-        hint: formatsQuestions && prompts.active ? "Answer the assistant, then send one combined reply." : "",
+        placeholder: formatsQuestions && prompts.questions?.length ? t("jskit.assistant.runtime.composer.questionsPlaceholder")
+          : formatsQuestions && prompts.choices?.length ? t("jskit.assistant.runtime.composer.choicesPlaceholder")
+            : display.placeholder || t("jskit.assistant.runtime.conversation.placeholder"),
+        hint: formatsQuestions && prompts.active ? t("jskit.assistant.runtime.composer.questionsHint") : "",
         rows: display.rows ?? 2, density: display.layout === "compact" ? "compact" : "default", submitOnEnter: true, submitOnModifierEnter: true },
       actions: { setDraft(value) {
         if (current) current.draft.value = value;
@@ -1055,7 +1074,7 @@ function createConversationBinding({ conversationId, endpoint = "", surfaceId =
         checkDelivery: messageId => current?.inspectDelivery(messageId), loadMore: input => current?.loadMore(input), reload: () => current?.reload() }
     };
   });
-  return { runtime, adapter, submitPrepared, error: computed(() => runtime.value?.error.value || runtime.value?.snapshot.value?.error || "") };
+  return { runtime, adapter, submitPrepared, error: computed(() => runtime.value?.error.value || stateError(runtime.value?.snapshot.value)) };
 }
 
 /** The standard element and custom text/voice presentation share the supplied binding. */

package/src/client/composables/useAssistantRuntime.js

@@ -33,6 +33,7 @@ import {
   resolveConversationRestorePolicy
 } from "../support/conversationRestoreSupport.js";
 import { useWorkspaceWebScopeSupport } from "../support/workspaceScopeSupport.js";
+import { useJskitText } from "../i18n.js";
 
 const DEFAULT_STREAM_TIMEOUT_MS = 120_000;
 const DEFAULT_HISTORY_PAGE_SIZE = 20;
@@ -92,17 +93,15 @@ function normalizeConversationStatus(value) {
 }
 
 function formatConversationStartedAt(value) {
+  const { formatDateTime, t } = useJskitText();
   const source = normalizeText(value);
-  if (!source) {
-    return "unknown";
-  }
-
-  const date = new Date(source);
-  if (Number.isNaN(date.getTime())) {
-    return "unknown";
-  }
+  return (source && formatDateTime(source)) || t("jskit.assistant.runtime.conversation.startedAtUnknown");
+}
 
-  return date.toLocaleString();
+// A failure or stream error event in the active language when its code is JSKIT's;
+// otherwise its message as sent.
+function failureText(failure) {
+  return failure?.message ? normalizeText(useJskitText().serverMessage(failure)) : "";
 }
 
 function resolveRuntimePolicy() {
@@ -143,6 +142,7 @@ function useAssistantRuntime({ api = null, surfaceId = "", integrationId = "" }
   const workspaceScopeSupport = useWorkspaceWebScopeSupport();
   const { placementContext, currentSurfaceId } = routeContext;
   const appConfig = getClientAppConfig();
+  const { t } = useJskitText();
 
   const messages = ref([]);
   const input = ref("");
@@ -226,7 +226,7 @@ function useAssistantRuntime({ api = null, surfaceId = "", integrationId = "" }
       refetchOnMount: false,
       refetchOnWindowFocus: false
     },
-    fallbackLoadError: "Unable to load conversation history."
+    fallbackLoadError: t("jskit.assistant.runtime.history.listFailed")
   });
 
   const conversationHistory = conversationHistoryCollection.items;
@@ -376,7 +376,7 @@ function useAssistantRuntime({ api = null, surfaceId = "", integrationId = "" }
         writeStoredActiveConversationId(scope, "");
       }
       if (!input.value) input.value = previousDraft;
-      setRuntimeError(normalizeText(loadError?.message) || "Unable to load conversation.");
+      setRuntimeError(failureText(loadError) || t("jskit.assistant.runtime.history.conversationLoadFailed"));
     } finally {
       if (version === restoreVersion) isRestoringConversation.value = false;
     }
@@ -441,7 +441,7 @@ function useAssistantRuntime({ api = null, surfaceId = "", integrationId = "" }
         deliver(submission) {
           const admission = Promise.withResolvers();
           runStream(submission, { onAccepted, admission }).then(
-            () => admission.reject(new Error("Assistant did not confirm this message.")),
+            () => admission.reject(new Error(t("jskit.assistant.runtime.request.notConfirmed"))),
             admission.reject
           );
           return admission.promise;
@@ -554,11 +554,11 @@ function useAssistantRuntime({ api = null, surfaceId = "", integrationId = "" }
 
             if (eventType === ASSISTANT_STREAM_EVENT_TYPES.ERROR) {
               if (!accepted) {
-                admissionError = normalizeText(event?.message) || "Assistant request failed.";
+                admissionError = failureText(event) || t("jskit.assistant.runtime.request.failed");
                 return;
               }
               setRuntimeError(
-                normalizeText(event?.message) || "Assistant request failed.",
+                failureText(event) || t("jskit.assistant.runtime.request.failed"),
                 "assistant.runtime:stream-event-error"
               );
               updateMessage(assistantMessageId, {
@@ -575,13 +575,13 @@ function useAssistantRuntime({ api = null, surfaceId = "", integrationId = "" }
       );
 
       if (!ownsStream()) return;
-      if (!accepted) throw new Error(admissionError || "Assistant did not confirm this message.");
+      if (!accepted) throw new Error(admissionError || t("jskit.assistant.runtime.request.notConfirmed"));
       if (streamAbortController.signal.aborted) streamDoneStatus = "aborted";
       const assistantMessage = findMessage(assistantMessageId);
       const assistantMessageText = normalizeText(assistantMessage?.text);
       if (!assistantMessageText && streamDoneStatus !== "aborted") {
         if (!error.value) {
-          setRuntimeError("Assistant returned no output.", "assistant.runtime:empty-output");
+          setRuntimeError(t("jskit.assistant.runtime.request.noOutput"), "assistant.runtime:empty-output");
         }
         updateMessage(assistantMessageId, {
           status: "error"
@@ -603,7 +603,7 @@ function useAssistantRuntime({ api = null, surfaceId = "", integrationId = "" }
           status: "canceled"
         });
       } else {
-        setRuntimeError(normalizeText(streamError?.message) || "Assistant request failed.");
+        setRuntimeError(failureText(streamError) || t("jskit.assistant.runtime.request.failed"));
         updateMessage(assistantMessageId, {
           status: "error"
         });
@@ -631,7 +631,7 @@ function useAssistantRuntime({ api = null, surfaceId = "", integrationId = "" }
     const user = normalizeObject(placementSnapshot.value.user);
 
     return {
-      displayName: normalizeText(user.displayName || user.name) || "You",
+      displayName: normalizeText(user.displayName || user.name) || t("jskit.assistant.runtime.viewer.you"),
       avatarUrl: normalizeText(user.avatarUrl)
     };
   });

package/src/client/i18n.js

@@ -0,0 +1,10 @@
+import { registerJskitMessages, useJskitText } from "@jskit-ai/kernel/client";
+// The runtime client also shows assistant-core's conversation errors, so it
+// registers that catalog too.
+import coreEnglish from "@jskit-ai/assistant-core/locales/en.json" with { type: "json" };
+import en from "../../locales/en.json" with { type: "json" };
+
+registerJskitMessages(coreEnglish);
+registerJskitMessages(en);
+
+export { useJskitText };

package/src/client/support/assistantRuntimeState.js

@@ -6,6 +6,7 @@ import {
   parseJsonObject
 } from "@jskit-ai/assistant-core/shared";
 import { conversationTurnsFromMessages } from "@jskit-ai/assistant-core/shared/conversation";
+import { useJskitText } from "../i18n.js";
 
 const CONVERSATION_MESSAGE_STATUS = Object.freeze({
   streaming: "inProgress",
@@ -14,14 +15,25 @@ const CONVERSATION_MESSAGE_STATUS = Object.freeze({
   canceled: "interrupted"
 });
 
+const TOOL_STATUS_KEY = "jskit.assistant.runtime.tool.status.";
+
+/** A tool event's status in the active language; an unknown status is shown as given. */
+function toolStatusText(status) {
+  const { hasMessage, t } = useJskitText();
+  const key = `${TOOL_STATUS_KEY}${status}`;
+  return hasMessage(key) ? t(key) : String(status ?? "");
+}
+
 function mapAssistantConversationTurns(messages, toolEvents = [], { showToolActivity = true } = {}) {
+  const { t } = useJskitText();
   return conversationTurnsFromMessages(messages.map((message) => ({
     ...message,
     messageId: String(message.id),
     status: CONVERSATION_MESSAGE_STATUS[message.status],
     progressUpdates: showToolActivity ? toolEvents
       .filter((event) => event.messageId === message.id)
-      .map((event) => ({ id: event.id, text: `${event.name} — ${event.status}` })) : []
+      .map((event) => ({ id: event.id,
+        text: t("jskit.assistant.runtime.tool.progress", { name: event.name, status: toolStatusText(event.status) }) })) : []
   })));
 }
 
@@ -172,5 +184,6 @@ export {
   interruptPendingToolEvents,
   mapTranscriptEntriesToAssistantState,
   mapAssistantConversationTurns,
-  normalizeToolName
+  normalizeToolName,
+  toolStatusText
 };

package/src/client/support/subscribeAssistantConversation.js

@@ -218,7 +218,9 @@ function subscribeAssistantConversation({
         onError(error ? Object.assign(new Error("Chat updates could not reconnect. Retrying automatically; Reload chat to try now.", { cause: error }), {
           code: "assistant_subscription_transport_failed"
         }) : Object.assign(new Error(response?.error || "Conversation subscription failed."), {
-          code: response?.code, statusCode: response?.status
+          code: response?.code, statusCode: response?.status, params: response?.params,
+          ...(response?.error ? { messageCode: response.messageCode, messageParams: response.messageParams }
+            : { messageCode: "assistant.runtime.subscription.failed" })
         }));
         return;
       }

package/src/server/actions.js

@@ -117,7 +117,7 @@ function createConversationActions({ conversationRuntime, conversationDataSchema
         throw new Error("Assistant conversation actions require workspace server scope support.");
       }
       const workspace = workspaceScopeSupport.resolveWorkspace(context, { workspaceSlug: input.workspaceSlug });
-      if (!workspace?.id) throw new AppError(409, "Workspace selection required.");
+      if (!workspace?.id) throw new AppError(409, "Workspace selection required.", { code: "assistant.runtime.workspace.selectionRequired" });
       conversationContext = { ...context, workspace };
     }
     return conversationRuntime.open({ id: input.conversationId, context: conversationContext });

package/src/server/createAssistantRuntime.js

@@ -26,13 +26,15 @@ function createAssistantAiClientFactory(config = {}) {
       if (surfaceConfig.aiIntegrationId) {
         const selected = integrationId || surfaceConfig.aiIntegrationId;
         if (![surfaceConfig.aiIntegrationId, ...surfaceConfig.aiIntegrationIds].includes(selected)) {
-          throw new AppError(403, "This AI connection is not available in this assistant.");
+          throw new AppError(403, "This AI connection is not available in this assistant.", { code: "assistant.runtime.connection.unavailable" });
         }
         if (!config.aiConnections?.resolve) throw new Error("The assistant requires an authorized AI connection resolver.");
         const connection = await config.aiConnections.resolve({ context, integrationId: selected });
         return createAiConnectionClient(connection, { timeoutMs: surfaceConfig.timeoutMs });
       }
-      if (integrationId) throw new AppError(403, "This assistant does not allow selecting an AI connection.");
+      if (integrationId) throw new AppError(403, "This assistant does not allow selecting an AI connection.", {
+        code: "assistant.runtime.connection.selectionNotAllowed"
+      });
 
       if (cache.has(normalizedTargetSurfaceId)) {
         return cache.get(normalizedTargetSurfaceId);

package/src/server/registerConversationSubscriptions.js

@@ -3,7 +3,7 @@ import { attachDirectRequestActionExecutor } from "@jskit-ai/kernel/server/http"
 import { AppError } from "@jskit-ai/kernel/server/runtime";
 import { actionIds } from "./actionIds.js";
 import { resolveRouteRequestState } from "./support/assistantRouteContext.js";
-import { errorStatus } from "./support/assistantErrors.js";
+import { errorMessageFields, errorStatus } from "./support/assistantErrors.js";
 import { requireAssistantSurface } from "./support/assistantSurface.js";
 import {
   ASSISTANT_CONVERSATION_EVENT,
@@ -13,17 +13,21 @@ import {
 
 function requireSubscriptionId(input) {
   if (typeof input?.subscriptionId !== "string" || !input.subscriptionId.trim() || input.subscriptionId.length > 128) {
-    throw new AppError(400, "A conversation subscription id is required.");
+    throw new AppError(400, "A conversation subscription id is required.", { code: "assistant.runtime.subscription.idRequired" });
   }
   return input.subscriptionId;
 }
 
 function subscriptionError(error) {
   const status = errorStatus(error);
+  const exposed = status < 500 && Boolean(error.message);
+  const code = String(error?.code || "assistant_subscription_failed");
   return {
     ok: false,
-    error: status < 500 ? String(error.message || "Conversation subscription failed.") : "Conversation subscription failed.",
-    code: String(error?.code || "assistant_subscription_failed"),
+    error: exposed ? String(error.message) : "Conversation subscription failed.",
+    code,
+    ...(exposed ? errorMessageFields(error, { expose: code !== "ACTION_PERMISSION_DENIED" })
+      : { params: {}, messageCode: "assistant.runtime.subscription.failed", messageParams: {} }),
     status
   };
 }

package/src/server/registerFastifyConversations.js

@@ -24,7 +24,7 @@ async function registerFastifyConversations(app, {
   async function requestContext(request) {
     const context = await authenticate(request);
     if (!context || typeof context !== "object" || Array.isArray(context)) {
-      throw new AppError(401, "Authentication required.");
+      throw new AppError(401, "Authentication required.", { code: "assistant.runtime.authenticationRequired" });
     }
     return context;
   }

package/src/server/registerRoutes.js

@@ -27,7 +27,7 @@ import {
   assistantSurfaceRouteParamsValidator
 } from "./inputSchemas.js";
 import { registerSettingsRoutes } from "./registerSettingsRoutes.js";
-import { errorStatus, exposedAppErrorDetails } from "./support/assistantErrors.js";
+import { errorMessageFields, errorStatus, exposedAppErrorDetails } from "./support/assistantErrors.js";
 import { ASSISTANT_STREAM_WRITER_METHODS } from "./support/assistantStreamWriter.js";
 import { requireWorkspaceAssistantRouteParams, resolveRouteRequestState } from "./support/assistantRouteContext.js";
 
@@ -35,11 +35,13 @@ function sendPreStreamErrorResponse(reply, error) {
   const statusCode = errorStatus(error);
   const safeStatusCode = Number.isInteger(statusCode) && statusCode >= 400 && statusCode <= 599 ? statusCode : 500;
 
+  // The kernel API error payload, so clients read one shape before and after streaming.
   if (error instanceof AppError) {
     const appErrorCode = String(error?.code || "app_error").trim() || "app_error";
     const payload = {
       error: error.message,
-      code: appErrorCode
+      code: appErrorCode,
+      ...errorMessageFields(error, { expose: appErrorCode !== "ACTION_PERMISSION_DENIED" })
     };
 
     const details = exposedAppErrorDetails(error);
@@ -60,8 +62,11 @@ function sendPreStreamErrorResponse(reply, error) {
     return;
   }
 
+  const exposed = safeStatusCode < 500;
   reply.code(safeStatusCode).send({
-    error: safeStatusCode >= 500 ? "Internal server error." : String(error?.message || "Request failed.")
+    error: exposed ? String(error?.message || "Request failed.") : "Internal server error.",
+    code: String(error?.code || "").trim() || (exposed ? "request_failed" : "internal_server_error"),
+    ...errorMessageFields(exposed ? error : null)
   });
 }
 

package/src/server/services/assistantConfigService.js

@@ -62,7 +62,7 @@ function createService({
     const resolvedWorkspace = workspace || workspaceScopeSupport.resolveWorkspace(context, input);
     const workspaceId = normalizeRecordId(resolvedWorkspace?.id, { fallback: null });
     if (!workspaceId) {
-      throw new AppError(409, "Workspace selection required.");
+      throw new AppError(409, "Workspace selection required.", { code: "assistant.runtime.workspace.selectionRequired" });
     }
 
     return workspaceId;