@jskit-ai/assistant-runtime 0.1.234 → 0.1.235

package/src/server/services/transcriptService.js

@@ -2,12 +2,12 @@ import { AppError, 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";
+import { DEFAULT_CONVERSATION_TITLE } from "../../shared/assistantRuntimeConfig.js";
 
 const DEFAULT_PAGE_SIZE = 20;
 const MAX_PAGE_SIZE = 200;
 const DEFAULT_MESSAGES_PAGE_SIZE = 200;
 const MAX_MESSAGES_PAGE_SIZE = 500;
-const DEFAULT_CONVERSATION_TITLE = "New conversation";
 const MAX_CONVERSATION_TITLE_LENGTH = 80;
 
 function resolveWorkspaceId(workspace, { required = false } = {}) {
@@ -141,58 +141,6 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
     };
   }
 
-  async function appendMessage(assistantSurface, conversationId, payload = {}, options = {}) {
-    const resolvedAssistantSurface = requireAssistantSurface(assistantSurface);
-    const normalizedConversationId = normalizeRecordId(conversationId, { fallback: null });
-    if (!normalizedConversationId) {
-      throw new TypeError("appendMessage requires conversationId.");
-    }
-
-    const source = normalizeObject(payload);
-    const context = normalizeObject(options.context);
-    const actorUserId = normalizeRecordId(source.actorUserId, { fallback: null }) || resolveActorUserId(context.actor);
-    const workspaceId = resolveExpectedWorkspaceId(resolvedAssistantSurface, options.workspace || context.workspace);
-    return conversationsRepository.transaction(async trx => {
-      const conversation = await conversationsRepository.findByIdForActorScope(normalizedConversationId, {
-        workspaceId,
-        actorUserId,
-        surfaceId: resolvedAssistantSurface.targetSurfaceId
-      }, { trx, forUpdate: true });
-      if (!conversation) {
-        throw new AppError(404, "Conversation not found.");
-      }
-
-      const createdMessage = await messagesRepository.create({
-        conversationId: normalizedConversationId,
-        workspaceId: conversation.workspaceId,
-        role: normalizeText(source.role).toLowerCase(),
-        kind: normalizeText(source.kind).toLowerCase() || "chat",
-        clientMessageSid: normalizeText(source.clientMessageSid),
-        actorUserId,
-        contentText: source.contentText == null ? null : String(source.contentText),
-        metadata: normalizeObject(source.metadata)
-      }, { trx });
-
-      await conversationsRepository.updateById(normalizedConversationId, { messageCount: conversation.messageCount + 1 }, { trx });
-
-      const messageRole = normalizeText(source.role).toLowerCase();
-      const messageKind = normalizeText(source.kind).toLowerCase() || "chat";
-      if (messageRole === "user" && messageKind === "chat" && isDefaultConversationTitle(conversation.title)) {
-        const derivedTitle = deriveConversationTitleFromMessage(source.contentText);
-        if (derivedTitle) {
-          await conversationsRepository.updateById(normalizedConversationId, {
-            title: derivedTitle
-          }, { trx });
-        }
-      }
-
-      return {
-        conversationId: normalizedConversationId,
-        message: createdMessage
-      };
-    });
-  }
-
   async function completeConversation(assistantSurface, conversationId, payload = {}, options = {}) {
     const resolvedAssistantSurface = requireAssistantSurface(assistantSurface);
     const normalizedConversationId = normalizeRecordId(conversationId, { fallback: null });
@@ -323,7 +271,6 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
 
   return Object.freeze({
     createConversationForTurn,
-    appendMessage,
     completeConversation,
     listConversationsForUser,
     getConversationMessagesForUser

package/src/server/support/assistantErrors.js

@@ -0,0 +1,13 @@
+import { AppError } from "@jskit-ai/kernel/server/runtime";
+
+function errorStatus(error) {
+  return Number(error?.status || error?.statusCode || 500);
+}
+
+// AppError details are withheld from clients when an action permission is denied.
+function exposedAppErrorDetails(error) {
+  if (!(error instanceof AppError) || !error.details) return undefined;
+  return String(error.code || "").trim() === "ACTION_PERMISSION_DENIED" ? undefined : error.details;
+}
+
+export { errorStatus, exposedAppErrorDetails };

package/src/server/support/assistantRouteContext.js

@@ -1,7 +1,7 @@
 import { AppError } from "@jskit-ai/kernel/server/runtime";
 import { composeSchemaDefinitions } from "@jskit-ai/kernel/shared/validators";
 import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
-import { resolveAssistantSurfaceConfig } from "../../shared/assistantSurfaces.js";
+import { requireAssistantSurface } from "./assistantSurface.js";
 import { assistantSurfaceRouteParamsValidator } from "../inputSchemas.js";
 
 function requireWorkspaceAssistantRouteParams(workspaceScopeSupport = null) {
@@ -30,15 +30,6 @@ function readWorkspaceInput(request, requiresWorkspace, workspaceScopeSupport =
   return workspaceScopeSupport.buildInputFromRouteParams(request?.input?.params);
 }
 
-function requireAssistantSurface(appConfig = {}, targetSurfaceId = "") {
-  const assistantSurface = resolveAssistantSurfaceConfig(appConfig, targetSurfaceId);
-  if (assistantSurface) {
-    return assistantSurface;
-  }
-
-  throw new AppError(404, "Assistant not found.");
-}
-
 function requireHostSurfaceId(request) {
   const headerValue = Array.isArray(request?.headers?.["x-jskit-surface"])
     ? request.headers["x-jskit-surface"][0]

package/src/server/support/assistantStreamWriter.js

@@ -0,0 +1,12 @@
+// The stream writer contract shared by the chat route and the chat service.
+const ASSISTANT_STREAM_WRITER_METHODS = Object.freeze([
+  "sendMeta",
+  "sendAssistantDelta",
+  "sendAssistantMessage",
+  "sendToolCall",
+  "sendToolResult",
+  "sendError",
+  "sendDone"
+]);
+
+export { ASSISTANT_STREAM_WRITER_METHODS };

package/src/server/support/assistantSurface.js

@@ -0,0 +1,13 @@
+import { AppError } from "@jskit-ai/kernel/server/runtime";
+import { resolveAssistantSurfaceConfig } from "../../shared/assistantSurfaces.js";
+
+function requireAssistantSurface(appConfig = {}, targetSurfaceId = "") {
+  const assistantSurface = resolveAssistantSurfaceConfig(appConfig, targetSurfaceId);
+  if (assistantSurface) {
+    return assistantSurface;
+  }
+
+  throw new AppError(404, "Assistant not found.");
+}
+
+export { requireAssistantSurface };

package/src/server/support/createSurfaceAwareToolCatalog.js

@@ -21,13 +21,12 @@ function requireContextSurfaceId(context = {}) {
   throw new Error("assistant surface-aware tool catalog requires context.surface.");
 }
 
-function createSurfaceAwareToolCatalog(actions, { appConfig = {}, resolveAppConfig = null, createCatalog = createServiceToolCatalog } = {}) {
+function createSurfaceAwareToolCatalog(actions, { appConfig = {}, createCatalog = createServiceToolCatalog } = {}) {
   if (!actions || typeof actions.listDefinitions !== "function") {
     throw new Error("createSurfaceAwareToolCatalog requires runtime.actions.");
   }
 
-  const resolveCurrentAppConfig =
-    typeof resolveAppConfig === "function" ? () => normalizeObject(resolveAppConfig()) : () => normalizeObject(appConfig);
+  const normalizedAppConfig = normalizeObject(appConfig);
   const cache = new Map();
   let schemaCatalog = null;
 
@@ -36,14 +35,14 @@ function createSurfaceAwareToolCatalog(actions, { appConfig = {}, resolveAppConf
       return cache.get(surfaceId);
     }
 
-    const nextCatalog = createCatalog(actions, buildCatalogOptions(resolveCurrentAppConfig(), surfaceId));
+    const nextCatalog = createCatalog(actions, buildCatalogOptions(normalizedAppConfig, surfaceId));
     cache.set(surfaceId, nextCatalog);
     return nextCatalog;
   }
 
   return Object.freeze({
     get limits() {
-      if (!schemaCatalog) schemaCatalog = createCatalog(actions, buildCatalogOptions(resolveCurrentAppConfig(), ""));
+      if (!schemaCatalog) schemaCatalog = createCatalog(actions, buildCatalogOptions(normalizedAppConfig, ""));
       return schemaCatalog.limits;
     },
     resolveToolSet(context = {}, options) {
@@ -52,7 +51,7 @@ function createSurfaceAwareToolCatalog(actions, { appConfig = {}, resolveAppConf
     },
     toOpenAiToolSchema(tool) {
       if (!schemaCatalog) {
-        schemaCatalog = createCatalog(actions, buildCatalogOptions(resolveCurrentAppConfig(), ""));
+        schemaCatalog = createCatalog(actions, buildCatalogOptions(normalizedAppConfig, ""));
       }
 
       return schemaCatalog.toOpenAiToolSchema(tool);

package/src/shared/assistantRuntimeConfig.js

@@ -5,4 +5,6 @@ const assistantRuntimeConfig = Object.freeze({
   turnRequestsTable: "assistant_turn_requests"
 });
 
-export { assistantRuntimeConfig };
+const DEFAULT_CONVERSATION_TITLE = "New conversation";
+
+export { DEFAULT_CONVERSATION_TITLE, assistantRuntimeConfig };

package/src/shared/assistantSurfaces.js

@@ -1,3 +1,4 @@
+import { buildAssistantApiPath } from "@jskit-ai/assistant-core/shared";
 import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
 import { normalizeObject, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 
@@ -102,9 +103,26 @@ function resolveAssistantSurfaceConfig(appConfig = {}, targetSurfaceId = "") {
   });
 }
 
+/**
+ * The runtime route of one resolved surface. Only the surface decides whether
+ * a workspace segment exists, so HTTP and realtime always name the same route;
+ * a workspace slug offered for a surface without workspaces is ignored.
+ */
+function resolveAssistantRuntimeRoute(surface, workspaceSlug = "") {
+  const requiresWorkspace = surface?.runtimeSurfaceRequiresWorkspace === true;
+  const workspace = requiresWorkspace ? normalizeText(workspaceSlug) : "";
+  return Object.freeze({
+    workspaceSlug: workspace,
+    configured: Boolean(surface) && (!requiresWorkspace || Boolean(workspace)),
+    endpoint: buildAssistantApiPath({ requiresWorkspace, workspaceSlug: workspace,
+      suffix: `/${normalizeText(surface?.targetSurfaceId)}` })
+  });
+}
+
 export {
   defineAssistantSurface,
   normalizeAssistantConfigScope,
+  resolveAssistantRuntimeRoute,
   resolveAssistantSurfaceConfig,
   resolveAssistantSurfacesConfig,
   resolveSurfaceDefinitions

package/test/actionDefinitions.test.js

@@ -120,7 +120,6 @@ test("host access wraps only canonical conversation definitions and receives the
     actionIds.conversationInspectDelivery, actionIds.conversationGoalRead, actionIds.conversationGoalUpdate
   ]);
   assert.equal(findDefinition(definitions, actionIds.conversationSubscribe), undefined);
-  assert.equal(findDefinition(definitions, subscribeActionId).audit.actionName, subscribeActionId);
   for (const definition of wrapped) {
     const adapted = findDefinition(definitions, definition.id);
     assert.equal(adapted.input, definition.input);

package/test/assistantSurfaces.test.js

@@ -1,8 +1,10 @@
 import assert from "node:assert/strict";
+import { readdir, readFile } from "node:fs/promises";
 import test from "node:test";
 import {
   defineAssistantSurface,
   normalizeAssistantConfigScope,
+  resolveAssistantRuntimeRoute,
   resolveAssistantSurfaceConfig
 } from "../src/shared/assistantSurfaces.js";
 
@@ -71,3 +73,30 @@ test("single-surface shorthand preserves explicit routing, scope and disabled su
   assert.equal(resolveAssistantSurfaceConfig(defineAssistantSurface("home", { configScope: "workspace" }), "home"), null);
   assert.throws(() => defineAssistantSurface(""), /surface id is required/u);
 });
+
+test("only the surface decides the runtime route, so HTTP and realtime name the same one", () => {
+  const home = resolveAssistantSurfaceConfig(defineAssistantSurface("home"), "home");
+  const admin = resolveAssistantSurfaceConfig(defineAssistantSurface("admin", { requiresWorkspace: true }), "admin");
+  // A slug offered to a surface without workspaces is ignored rather than
+  // producing a workspace URL the server answers with 404.
+  assert.deepEqual(resolveAssistantRuntimeRoute(home, "acme"),
+    { workspaceSlug: "", configured: true, endpoint: "/api/assistant/home" });
+  assert.deepEqual(resolveAssistantRuntimeRoute(admin, " acme "),
+    { workspaceSlug: "acme", configured: true, endpoint: "/api/w/acme/assistant/admin" });
+  assert.equal(resolveAssistantRuntimeRoute(admin, "").configured, false);
+  assert.equal(resolveAssistantRuntimeRoute(null, "acme").configured, false);
+});
+
+test("client runtime code routes from surface configuration and names no application surface", async () => {
+  const root = new URL("../src/client/", import.meta.url);
+  const files = (await readdir(root, { recursive: true })).filter(file => /\.(js|vue)$/u.test(file));
+  for (const file of files) {
+    const source = await readFile(new URL(file, root), "utf8");
+    assert.doesNotMatch(source, /["']admin["']|isAdminSurface/u, `${file} hard-codes an application surface`);
+  }
+  for (const file of ["composables/useAssistantConversation.js", "composables/useAssistantRuntime.js"]) {
+    const source = await readFile(new URL(file, root), "utf8");
+    assert.match(source, /resolveAssistantRuntimeRoute\(/u);
+    assert.doesNotMatch(source, /buildAssistantApiPath\(/u, `${file} must route through resolveAssistantRuntimeRoute`);
+  }
+});

package/test/chatServiceLifecycle.test.js

@@ -122,9 +122,6 @@ function createHarness(completions, { executeToolCall = null, tools: configuredT
           }
         };
       },
-      async appendMessage(_surface, _conversationId, message) {
-        transcriptMessages.push(structuredClone(message));
-      },
       async completeConversation(_surface, _conversationId, completion) {
         completedConversations.push(structuredClone(completion));
       }
@@ -546,3 +543,15 @@ test("application-authorized attachments reach the model and survive transcript
   const legacy = createHarness([textCompletion("Must not run")], { attachments, supportsAttachments: false });
   await assert.rejects(legacy.run("Read this", { attachmentIds: ["file-one"] }), /not configured/);
 });
+
+test("attachment identifiers use the conversation runtime's shape before any file is resolved", async () => {
+  const calls = [];
+  const attachments = { async resolve(request) { calls.push(request); return { attachments: [], content: [] }; } };
+  for (const attachmentIds of [["file-one", "file-one"], ["  "], Array.from({ length: 11 }, (_, index) => `file-${index}`)]) {
+    const harness = createHarness([textCompletion("Must not run")], { attachments });
+    await assert.rejects(harness.run("Read this", { attachmentIds }), error =>
+      error.status === 400 && /Invalid attachment identifiers/u.test(error.message));
+    assert.deepEqual(harness.completionRequests, []);
+  }
+  assert.deepEqual(calls, []);
+});

package/test/turnRequests.test.js

@@ -52,7 +52,6 @@ function service(repository, { provider, transcript = [] } = {}) {
     aiClientFactory: { resolveClient: () => ({ enabled: true, provider: "test", defaultModel: "test", createChatCompletionStream: provider }) },
     transcriptService: {
       async createConversationForTurn() { return { conversation: { id: "100" } }; },
-      async appendMessage(_surface, _id, message) { transcript.push(message); },
       async completeConversation() {}
     },
     serviceToolCatalog: { limits: { maxToolArgumentBytes: 64 * 1024 }, resolveToolSet: () => ({ tools: [] }),