@jskit-ai/assistant-runtime 0.1.238 → 0.2.0

package/src/server/services/chatService.js

@@ -1,10 +1,10 @@
 import { isDeepStrictEqual } from "node:util";
-import { AppError } from "@jskit-ai/kernel/server/runtime";
+import { AppError, createValidationError } from "@jskit-ai/kernel/server/runtime";
 import { normalizeObject, normalizeRecordId, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import { resolveWorkspaceSlug } from "@jskit-ai/assistant-core/server";
 import { conversationAttachmentIds } from "@jskit-ai/assistant-core/server/conversation";
 import { ASSISTANT_STREAM_EVENT_TYPES, MAX_HISTORY_MESSAGES, MAX_INPUT_CHARS, isAssistantProgressOnlyText } from "@jskit-ai/assistant-core/shared";
-import { exposedAppErrorDetails, errorStatus } from "../support/assistantErrors.js";
+import { errorMessageFields, exposedAppErrorDetails, errorStatus } from "../support/assistantErrors.js";
 import { requireAssistantSurface } from "../support/assistantSurface.js";
 import { ASSISTANT_STREAM_WRITER_METHODS } from "../support/assistantStreamWriter.js";
 
@@ -44,21 +44,13 @@ function normalizeStreamInput(payload = {}) {
   const messageId = normalizeText(source.messageId);
   const input = normalizeText(source.input).slice(0, MAX_INPUT_CHARS);
   if (!messageId || messageId.length > 128) {
-    throw new AppError(400, "Validation failed.", {
-      details: {
-        fieldErrors: {
-          messageId: "messageId is required and must be at most 128 characters."
-        }
-      }
+    throw createValidationError({
+      messageId: { code: "assistant.runtime.request.messageIdInvalid", message: "messageId is required and must be at most 128 characters." }
     });
   }
   if (!input) {
-    throw new AppError(400, "Validation failed.", {
-      details: {
-        fieldErrors: {
-          input: "input is required."
-        }
-      }
+    throw createValidationError({
+      input: { code: "assistant.runtime.request.inputRequired", message: "input is required." }
     });
   }
 
@@ -75,6 +67,19 @@ function hasStreamWriter(streamWriter) {
   return ASSISTANT_STREAM_WRITER_METHODS.every(name => typeof streamWriter?.[name] === "function");
 }
 
+// A saved failure keeps its translation fields, except where the kernel would
+// withhold them, so a replay shows the same message in the user's language.
+function savedMessageFields(error) {
+  if (!error?.message) return { messageCode: "assistant.runtime.request.failed", messageParams: {} };
+  const { params, ...fields } = errorMessageFields(error, { expose: error.code !== "ACTION_PERMISSION_DENIED" });
+  return { ...(Object.keys(params).length ? { params } : {}), ...fields };
+}
+
+function streamErrorMessageFields(error, aborted) {
+  if (aborted) return { params: {}, messageCode: "assistant.runtime.request.cancelled", messageParams: {} };
+  return error?.message ? errorMessageFields(error) : { params: {}, messageCode: "assistant.runtime.request.failed", messageParams: {} };
+}
+
 function isAbortError(error) {
   if (!error) {
     return false;
@@ -187,18 +192,20 @@ function createChatService({
 
   function replayRequest(record, request, writer) {
     if (!isDeepStrictEqual(record.request, JSON.parse(JSON.stringify(request)))) {
-      throw new AppError(409, "This message ID belongs to a different request.");
+      throw new AppError(409, "This message ID belongs to a different request.", { code: "assistant.runtime.request.messageIdConflict" });
     }
     const response = record.response || {};
     if (record.status === "running") {
       if (response.meta) writer.sendMeta(response.meta);
       writer.sendError({ type: ASSISTANT_STREAM_EVENT_TYPES.ERROR, code: "assistant_request_unconfirmed",
-        message: "This message was already submitted. Its completion is not confirmed; check conversation history before sending new work." });
+        message: "This message was already submitted. Its completion is not confirmed; check conversation history before sending new work.",
+        messageCode: "assistant.runtime.request.unconfirmed", messageParams: {} });
       writer.sendDone({ type: ASSISTANT_STREAM_EVENT_TYPES.DONE, messageId: request.messageId, status: "unconfirmed" });
       return { conversationId: response.meta?.conversationId, messageId: request.messageId, status: "unconfirmed" };
     }
     if (response.failure && !response.meta) throw new AppError(response.failure.status, response.failure.message, {
-      code: response.failure.code, details: response.failure.details
+      code: response.failure.code, params: response.failure.params, details: response.failure.details,
+      messageCode: response.failure.messageCode, messageParams: response.failure.messageParams
     });
     if (response.meta) writer.sendMeta(response.meta);
     if (response.answer) writer.sendAssistantMessage(response.answer);
@@ -216,7 +223,7 @@ function createChatService({
     const source = normalizeStreamInput(payload);
     const actor = context.actor;
     const actorUserId = normalizeRecordId(actor?.id, { fallback: null });
-    if (!actorUserId) throw new AppError(401, "Authentication required.");
+    if (!actorUserId) throw new AppError(401, "Authentication required.", { code: "assistant.runtime.authenticationRequired" });
     if (!hasStreamWriter(options.streamWriter)) throw new Error("assistant.chat.stream requires streamWriter methods.");
     const scope = { actorUserId, surfaceId: assistantSurface.targetSurfaceId,
       workspaceId: normalizeRecordId(workspace?.id || workspace, { fallback: null }) };
@@ -226,7 +233,7 @@ function createChatService({
     const aiClient = await aiClientFactory.resolveClient(assistantSurface.targetSurfaceId, {
       context: assistantContext, integrationId: payload.integrationId
     });
-    if (!aiClient.enabled) throw new AppError(503, "Assistant provider is not configured.");
+    if (!aiClient.enabled) throw new AppError(503, "Assistant provider is not configured.", { code: "assistant.runtime.provider.notConfigured" });
     const claim = await turnRequests.claim(scope, request);
     if (!claim.acquired) return replayRequest(claim, request, options.streamWriter);
     const response = {};
@@ -251,7 +258,8 @@ function createChatService({
       response.failure = { message: String(error?.message || "Assistant request failed."),
         status: errorStatus(error),
         ...(error instanceof AppError ? { code: error.code,
-          ...(exposedAppErrorDetails(error) ? { details: error.details } : {}) } : {}) };
+          ...(exposedAppErrorDetails(error) ? { details: error.details } : {}) } : {}),
+        ...savedMessageFields(error) };
       await turnRequests.update(claim, response, "failed");
       throw error;
     }
@@ -280,16 +288,18 @@ function createChatService({
       const conversation = conversationResult.conversation;
       const conversationId = conversation?.id;
       if (!conversationId) {
-        throw new AppError(500, "Assistant failed to create conversation.");
+        throw new AppError(500, "Assistant failed to create conversation.", { code: "assistant.runtime.conversation.createFailed" });
       }
 
       const resolvedAttachments = [];
       async function prepareAttachments(attachmentIds) {
         if (attachmentIds === undefined || (Array.isArray(attachmentIds) && !attachmentIds.length)) return;
         try { conversationAttachmentIds(attachmentIds); }
-        catch { throw new AppError(400, "Invalid attachment identifiers."); }
+        catch { throw new AppError(400, "Invalid attachment identifiers.", { code: "assistant.runtime.attachments.invalidIds" }); }
         if (!attachments?.resolve || !aiClient.supportsAttachments) {
-          throw new AppError(400, "File attachments are not configured for this assistant.");
+          throw new AppError(400, "File attachments are not configured for this assistant.", {
+            code: "assistant.runtime.attachments.notConfigured"
+          });
         }
         // Preserve the facade's existing pre-admission authorization order.
         // Only these server-resolved materials reach the common file reader.
@@ -360,12 +370,14 @@ function createChatService({
         const turn = snapshot.conversationLog.find(entry => entry.turnId === turnId);
         const status = turn?.metadata?.runtime?.status;
         if (status !== "complete") {
-          const error = new Error(turn?.metadata?.runtime?.error || snapshot.error || "Assistant request failed.");
+          const reason = turn?.metadata?.runtime?.error || snapshot.error;
+          const error = reason ? new Error(reason) : Object.assign(new Error("Assistant request failed."), {
+            messageCode: "assistant.runtime.request.failed", messageParams: {} });
           if (status === "cancelled") error.name = "AbortError";
           throw error;
         }
         const text = normalizeText(turn.assistant?.text);
-        if (!text) throw new AppError(502, "Assistant returned no output.");
+        if (!text) throw new AppError(502, "Assistant returned no output.", { code: "assistant.runtime.request.noOutput" });
         await transcriptService.completeConversation(assistantSurface, conversationId,
           { status: "completed", metadata: turn.metadata?.completion || {} }, { context: assistantContext, workspace });
         streamWriter.sendAssistantMessage({ type: ASSISTANT_STREAM_EVENT_TYPES.ASSISTANT_MESSAGE, text });
@@ -379,6 +391,7 @@ function createChatService({
         streamWriter.sendError({ type: ASSISTANT_STREAM_EVENT_TYPES.ERROR, messageId: source.messageId,
           code: aborted ? "assistant_stream_aborted" : String(error?.code || "assistant_stream_failed"),
           message: aborted ? "Assistant request was cancelled." : String(error?.message || "Assistant request failed."),
+          ...streamErrorMessageFields(error, aborted),
           status: aborted ? 499 : errorStatus(error) });
         streamWriter.sendDone({ type: ASSISTANT_STREAM_EVENT_TYPES.DONE, messageId: source.messageId, status });
         return { conversationId, messageId: source.messageId, status };

package/src/server/services/transcriptService.js

@@ -1,4 +1,4 @@
-import { AppError, parsePositiveInteger } from "@jskit-ai/kernel/server/runtime";
+import { AppError, createValidationError, parsePositiveInteger } from "@jskit-ai/kernel/server/runtime";
 import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
 import { normalizeObject, normalizeRecordId, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import { normalizeConversationStatus } from "@jskit-ai/assistant-core/shared";
@@ -13,7 +13,7 @@ const MAX_CONVERSATION_TITLE_LENGTH = 80;
 function resolveWorkspaceId(workspace, { required = false } = {}) {
   const workspaceId = normalizeRecordId(workspace?.id || workspace, { fallback: null });
   if (!workspaceId && required) {
-    throw new AppError(409, "Workspace selection required.");
+    throw new AppError(409, "Workspace selection required.", { code: "assistant.runtime.workspace.selectionRequired" });
   }
 
   return workspaceId;
@@ -22,7 +22,7 @@ function resolveWorkspaceId(workspace, { required = false } = {}) {
 function resolveActorUserId(user, { required = false } = {}) {
   const actorUserId = normalizeRecordId(user?.id, { fallback: null });
   if (!actorUserId && required) {
-    throw new AppError(401, "Authentication required.");
+    throw new AppError(401, "Authentication required.", { code: "assistant.runtime.authenticationRequired" });
   }
 
   return actorUserId;
@@ -101,7 +101,7 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
         surfaceId: resolvedAssistantSurface.targetSurfaceId
       });
       if (!existing) {
-        throw new AppError(404, "Conversation not found.");
+        throw new AppError(404, "Conversation not found.", { code: "assistant.runtime.conversation.notFound" });
       }
 
       if (existing.status !== "active") {
@@ -161,7 +161,7 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
         surfaceId: resolvedAssistantSurface.targetSurfaceId
       }, { trx, forUpdate: true });
       if (!existing) {
-        throw new AppError(404, "Conversation not found.");
+        throw new AppError(404, "Conversation not found.", { code: "assistant.runtime.conversation.notFound" });
       }
 
       return conversationsRepository.updateById(normalizedConversationId, {
@@ -215,12 +215,8 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
     });
     const normalizedConversationId = normalizeRecordId(conversationId, { fallback: null });
     if (!normalizedConversationId) {
-      throw new AppError(400, "Validation failed.", {
-        details: {
-          fieldErrors: {
-            conversationId: "conversationId must be a valid record id."
-          }
-        }
+      throw createValidationError({
+        conversationId: { code: "assistant.runtime.conversation.idInvalid", message: "conversationId must be a valid record id." }
       });
     }
 
@@ -233,7 +229,7 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
       }
     );
     if (!conversation) {
-      throw new AppError(404, "Conversation not found.");
+      throw new AppError(404, "Conversation not found.", { code: "assistant.runtime.conversation.notFound" });
     }
 
     const pagination = normalizePagination(query, {

package/src/server/sqlConversationStorage.js

@@ -93,7 +93,7 @@ function requireUnambiguous(projection) {
 function createSqlConversationStorage({ conversationsRepository, messagesRepository }) {
   async function load(id, trx, write = false) {
     const conversation = await conversationsRepository.findById(id, { trx, forUpdate: write });
-    if (!conversation) throw new AppError(404, "Conversation not found.");
+    if (!conversation) throw new AppError(404, "Conversation not found.", { code: "assistant.runtime.conversation.notFound" });
     const rows = [];
     for (let page = 1; ; page += 1) {
       const batch = await messagesRepository.listByConversationScope(id, { workspaceId: conversation.workspaceId }, { page, pageSize: 500 }, { trx });

package/src/server/support/assistantErrors.js

@@ -10,4 +10,19 @@ function exposedAppErrorDetails(error) {
   return String(error.code || "").trim() === "ACTION_PERMISSION_DENIED" ? undefined : error.details;
 }
 
-export { errorStatus, exposedAppErrorDetails };
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+// The kernel error payload's translation fields: the code's params and, where one
+// code covers several sentences, the sentence's own messageCode.
+function errorMessageFields(error, { expose = true } = {}) {
+  return {
+    params: expose && isRecord(error?.params) ? error.params : {},
+    ...(expose && error?.messageCode
+      ? { messageCode: String(error.messageCode), messageParams: isRecord(error.messageParams) ? error.messageParams : {} }
+      : {})
+  };
+}
+
+export { errorStatus, exposedAppErrorDetails, errorMessageFields };

package/src/server/support/assistantRouteContext.js

@@ -39,7 +39,9 @@ function requireHostSurfaceId(request) {
     return hostSurfaceId;
   }
 
-  throw new AppError(400, "Assistant surface header x-jskit-surface is required.");
+  throw new AppError(400, "Assistant surface header x-jskit-surface is required.", {
+    code: "assistant.runtime.route.surfaceHeaderRequired"
+  });
 }
 
 function resolveRouteRequestState(
@@ -63,10 +65,10 @@ function resolveRouteRequestState(
     : assistantSurface.targetSurfaceId;
 
   if (expectsWorkspace !== (requiresWorkspace === true)) {
-    throw new AppError(404, "Assistant route not found.");
+    throw new AppError(404, "Assistant route not found.", { code: "assistant.runtime.route.notFound" });
   }
   if (hostSurfaceId !== expectedHostSurfaceId) {
-    throw new AppError(403, "Assistant route is not available on this surface.");
+    throw new AppError(403, "Assistant route is not available on this surface.", { code: "assistant.runtime.route.surfaceForbidden" });
   }
 
   return Object.freeze({

package/src/server/support/assistantSurface.js

@@ -7,7 +7,7 @@ function requireAssistantSurface(appConfig = {}, targetSurfaceId = "") {
     return assistantSurface;
   }
 
-  throw new AppError(404, "Assistant not found.");
+  throw new AppError(404, "Assistant not found.", { code: "assistant.runtime.route.assistantNotFound" });
 }
 
 export { requireAssistantSurface };

package/test/assistantRuntimeState.test.js

@@ -179,3 +179,19 @@ test("restored tool calls retain their association with the reply they preceded"
   assert.equal(turn.messages[1].text, "Search — done");
   assert.doesNotMatch(JSON.stringify(turn), /secret|private/);
 });
+
+test("tool activity follows the application's active language and keeps unknown statuses as sent", async (t) => {
+  const { createI18n } = await import("vue-i18n");
+  const { setJskitI18n } = await import("@jskit-ai/kernel/client");
+  const { mapAssistantConversationTurns, toolStatusText } = await import("../src/client/support/assistantRuntimeState.js");
+  const i18n = createI18n({ legacy: false, locale: "fr", missingWarn: false, fallbackWarn: false, messages: {
+    fr: { jskit: { assistant: { runtime: { tool: { progress: "{status} : {name}", status: { pending: "en attente" } } } } } }
+  } });
+  setJskitI18n(i18n);
+  t.after(() => setJskitI18n(null));
+  const messages = [{ id: "answer-1", role: "assistant", status: "streaming", text: "" }];
+  const tools = [{ id: "tool-1", messageId: "answer-1", name: "Search records", status: "pending" }];
+  assert.equal(mapAssistantConversationTurns(messages, tools)[0].messages.at(-1).text, "en attente : Search records");
+  assert.equal(toolStatusText("done"), "done");
+  assert.equal(toolStatusText("paused"), "paused");
+});

package/test/i18nCatalog.test.js

@@ -0,0 +1,16 @@
+import assert from "node:assert/strict";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { evaluateI18nCatalogContract } from "../../../tooling/test-support/i18nCatalogContract.mjs";
+
+const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(TEST_DIRECTORY, "..", "..", "..");
+
+test("assistant-runtime English catalog matches its source", () => {
+  const { problems } = evaluateI18nCatalogContract({
+    repoRoot: REPO_ROOT,
+    packageDir: path.join(REPO_ROOT, "packages", "assistant-runtime")
+  });
+  assert.deepEqual(problems, []);
+});

package/test/lazyAppConfig.test.js

@@ -317,7 +317,7 @@ test("registerRoutes returns clear AppError payload for pre-stream assistant fai
       },
       executeAction: async ({ input }) => {
         capturedInput = input;
-        throw new AppError(503, "Assistant provider is not configured.");
+        throw new AppError(503, "Assistant provider is not configured.", { code: "assistant.runtime.provider.notConfigured" });
       }
     },
     reply
@@ -326,7 +326,8 @@ test("registerRoutes returns clear AppError payload for pre-stream assistant fai
   assert.equal(reply.statusCode, 503);
   assert.deepEqual(reply.payload, {
     error: "Assistant provider is not configured.",
-    code: "APP_ERROR"
+    code: "assistant.runtime.provider.notConfigured",
+    params: {}
   });
   assert.deepEqual(capturedInput, {
     targetSurfaceId: "admin",
@@ -335,6 +336,27 @@ test("registerRoutes returns clear AppError payload for pre-stream assistant fai
     input: "hello",
     history: []
   });
+
+  // Coded conversation failures keep their per-sentence messageCode, like the kernel payload.
+  const busy = Object.assign(new Error("Wait for the current turn."), {
+    code: "conversation_busy", statusCode: 409, messageCode: "assistant.conversation.waitForTurn", messageParams: {}
+  });
+  const hidden = Object.assign(new Error("Private storage detail."), {
+    code: "conversation_storage_unavailable", statusCode: 503, messageCode: "assistant.conversation.private", messageParams: {}
+  });
+  for (const [failure, status, payload] of [
+    [busy, 409, { error: busy.message, code: "conversation_busy", params: {}, messageCode: busy.messageCode, messageParams: {} }],
+    [hidden, 503, { error: "Internal server error.", code: "conversation_storage_unavailable", params: {} }]
+  ]) {
+    await route.handler({
+      raw: { on() {}, off() {} },
+      headers: { "x-jskit-surface": "admin" },
+      input: { params: { workspaceSlug: "dogandgroom", surfaceId: "admin" }, body: { messageId: "msg_2", input: "hello", history: [] } },
+      executeAction: async () => { throw failure; }
+    }, reply);
+    assert.equal(reply.statusCode, status);
+    assert.deepEqual(reply.payload, payload);
+  }
 });
 
 test("chat service uses explicit app config when conversations are listed", async () => {

package/test/turnRequests.test.js

@@ -117,7 +117,9 @@ test("an interrupted claim is never stolen after restart, and provider failures
   await repository.claim(scope, { ...request, conversationId: null, integrationId: "" });
   let calls = 0;
   const chat = service(createRepository(connect()), { provider: () => { calls++; throw new Error("Provider failed."); } });
-  assert.equal((await run(chat)).status, "unconfirmed");
+  const unconfirmed = [];
+  assert.equal((await run(chat, request, { events: unconfirmed })).status, "unconfirmed");
+  assert.equal(unconfirmed.find(item => item.method === "sendError").event.messageCode, "assistant.runtime.request.unconfirmed");
   assert.equal(calls, 0);
   const failure = { ...request, messageId: "failing-message" };
   assert.equal((await run(chat, failure)).status, "failed");
@@ -125,6 +127,14 @@ test("an interrupted claim is never stolen after restart, and provider failures
   assert.equal((await run(chat, failure, { events: replay })).status, "failed");
   assert.equal(calls, 1);
   assert.match(replay.find(item => item.method === "sendError").event.message, /Provider failed/);
-  await assert.rejects(run(chat, { ...request, messageId: "x".repeat(129) }), /Validation failed/);
+  await assert.rejects(run(chat, { ...request, messageId: "x".repeat(129) }), error => {
+    assert.equal(error.message, "Validation failed.");
+    assert.equal(error.code, "validation_failed");
+    assert.deepEqual(error.details, {
+      fieldErrors: { messageId: "messageId is required and must be at most 128 characters." },
+      fieldErrorCodes: { messageId: { code: "assistant.runtime.request.messageIdInvalid", params: {} } }
+    });
+    return true;
+  });
   assert.equal(calls, 1);
 });