@jskit-ai/assistant-runtime 0.1.1

package/templates/migrations/assistant_transcripts_initial.cjs

@@ -0,0 +1,58 @@
+exports.up = async function up(knex) {
+  const hasWorkspacesTable = await knex.schema.hasTable("workspaces");
+  const hasConversationsTable = await knex.schema.hasTable("assistant_conversations");
+  if (!hasConversationsTable) {
+    await knex.schema.createTable("assistant_conversations", (table) => {
+      table.increments("id").unsigned().primary();
+      table.integer("workspace_id").unsigned().nullable();
+      if (hasWorkspacesTable) {
+        table.foreign("workspace_id").references("id").inTable("workspaces").onDelete("CASCADE");
+      }
+      table.integer("created_by_user_id").unsigned().nullable().references("id").inTable("users").onDelete("SET NULL").index();
+      table.string("title", 160).notNullable().defaultTo("New conversation");
+      table.string("status", 32).notNullable().defaultTo("active");
+      table.string("provider", 64).notNullable().defaultTo("");
+      table.string("model", 128).notNullable().defaultTo("");
+      table.string("surface_id", 32).notNullable();
+      table.integer("message_count").unsigned().notNullable().defaultTo(0);
+      table.text("metadata_json").nullable();
+      table.timestamp("started_at").notNullable().defaultTo(knex.fn.now());
+      table.timestamp("ended_at").nullable();
+      table.timestamp("created_at").notNullable().defaultTo(knex.fn.now());
+      table.timestamp("updated_at").notNullable().defaultTo(knex.fn.now());
+
+      table.index(["surface_id", "started_at"], "idx_assistant_conversations_surface_started_at");
+      table.index(["workspace_id", "started_at"], "idx_assistant_conversations_workspace_started_at");
+      table.index(["created_by_user_id", "started_at"], "idx_assistant_conversations_creator_started_at");
+    });
+  }
+
+  const hasMessagesTable = await knex.schema.hasTable("assistant_messages");
+  if (!hasMessagesTable) {
+    await knex.schema.createTable("assistant_messages", (table) => {
+      table.increments("id").unsigned().primary();
+      table.integer("conversation_id").unsigned().notNullable().references("id").inTable("assistant_conversations").onDelete("CASCADE");
+      table.integer("workspace_id").unsigned().nullable();
+      if (hasWorkspacesTable) {
+        table.foreign("workspace_id").references("id").inTable("workspaces").onDelete("CASCADE");
+      }
+      table.integer("seq").unsigned().notNullable();
+      table.string("role", 32).notNullable();
+      table.string("kind", 32).notNullable().defaultTo("chat");
+      table.string("client_message_sid", 128).notNullable().defaultTo("");
+      table.integer("actor_user_id").unsigned().nullable().references("id").inTable("users").onDelete("SET NULL").index();
+      table.text("content_text").nullable();
+      table.text("metadata_json").nullable();
+      table.timestamp("created_at").notNullable().defaultTo(knex.fn.now());
+
+      table.unique(["conversation_id", "seq"], "uq_assistant_messages_conversation_seq");
+      table.index(["conversation_id", "created_at"], "idx_assistant_messages_conversation_created_at");
+      table.index(["workspace_id"], "idx_assistant_messages_workspace");
+    });
+  }
+};
+
+exports.down = async function down(knex) {
+  await knex.schema.dropTableIfExists("assistant_messages");
+  await knex.schema.dropTableIfExists("assistant_conversations");
+};

package/test/assistantServerConfig.test.js

@@ -0,0 +1,72 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  resolveAssistantAiConfig,
+  resolveAssistantServerConfig
+} from "../src/server/support/assistantServerConfig.js";
+
+test("assistant server config resolves per-surface AI config without legacy global fallback", () => {
+  const appConfig = {
+    assistantServer: {
+      admin: {
+        aiConfigPrefix: "ADMIN_ASSISTANT",
+        provider: "anthropic",
+        apiKey: "config-key",
+        baseUrl: "https://config.example.test",
+        model: "claude-config",
+        timeoutMs: 45_000,
+        barredActionIds: ["demo.admin.secret"],
+        toolSkipActionPrefixes: ["demo.hidden."]
+      }
+    },
+    assistant: {
+      provider: "openai",
+      apiKey: "legacy-key"
+    }
+  };
+  const env = {
+    ADMIN_ASSISTANT_AI_PROVIDER: "deepseek",
+    ADMIN_ASSISTANT_AI_API_KEY: "surface-key",
+    AI_PROVIDER: "openai",
+    AI_API_KEY: "legacy-env-key"
+  };
+
+  assert.deepEqual(resolveAssistantServerConfig(appConfig, "admin"), {
+    aiConfigPrefix: "ADMIN_ASSISTANT",
+    provider: "anthropic",
+    apiKey: "config-key",
+    baseUrl: "https://config.example.test",
+    model: "claude-config",
+    timeoutMs: 45_000,
+    barredActionIds: ["demo.admin.secret"],
+    toolSkipActionPrefixes: ["demo.hidden."]
+  });
+  assert.deepEqual(resolveAssistantAiConfig({ appConfig, env }, "admin"), {
+    aiConfigPrefix: "ADMIN_ASSISTANT",
+    ai: {
+      enabled: true,
+      provider: "deepseek",
+      apiKey: "surface-key",
+      baseUrl: "https://config.example.test",
+      model: "claude-config",
+      timeoutMs: 45_000
+    }
+  });
+});
+
+test("assistant server config requires explicit aiConfigPrefix for each surface", () => {
+  assert.throws(
+    () =>
+      resolveAssistantAiConfig(
+        {
+          appConfig: {},
+          env: {
+            AI_PROVIDER: "anthropic",
+            AI_API_KEY: "legacy-env-key"
+          }
+        },
+        "admin"
+      ),
+    /requires assistantServer\.admin\.aiConfigPrefix/
+  );
+});

package/test/assistantSurfaces.test.js

@@ -0,0 +1,50 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  normalizeAssistantConfigScope,
+  resolveAssistantSurfaceConfig
+} from "../src/shared/assistantSurfaces.js";
+
+test("assistant surface config resolves runtime/settings surface requirements from app config", () => {
+  const appConfig = {
+    surfaceDefinitions: {
+      admin: { id: "admin", enabled: true, requiresWorkspace: true, accessPolicyId: "workspace_member" },
+      console: { id: "console", enabled: true, requiresWorkspace: false, accessPolicyId: "console_owner" }
+    },
+    assistantSurfaces: {
+      admin: {
+        settingsSurfaceId: "console",
+        configScope: "global"
+      }
+    }
+  };
+
+  const assistantSurface = resolveAssistantSurfaceConfig(appConfig, "admin");
+  assert.deepEqual(assistantSurface, {
+    targetSurfaceId: "admin",
+    settingsSurfaceId: "console",
+    configScope: "global",
+    runtimeSurfaceRequiresWorkspace: true,
+    settingsSurfaceRequiresWorkspace: false,
+    settingsSurfaceRequiresConsoleOwner: true
+  });
+});
+
+test("assistant surface config rejects invalid workspace-scoped assistant combinations", () => {
+  const appConfig = {
+    surfaceDefinitions: {
+      home: { id: "home", enabled: true, requiresWorkspace: false, accessPolicyId: "public" },
+      console: { id: "console", enabled: true, requiresWorkspace: false, accessPolicyId: "console_owner" }
+    },
+    assistantSurfaces: {
+      home: {
+        settingsSurfaceId: "console",
+        configScope: "workspace"
+      }
+    }
+  };
+
+  assert.equal(resolveAssistantSurfaceConfig(appConfig, "home"), null);
+  assert.equal(normalizeAssistantConfigScope("workspace"), "workspace");
+  assert.equal(normalizeAssistantConfigScope("weird"), "global");
+});

package/test/createSurfaceAwareToolCatalog.test.js

@@ -0,0 +1,77 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createSurfaceAwareToolCatalog } from "../src/server/support/createSurfaceAwareToolCatalog.js";
+
+test("surface-aware tool catalog applies per-surface skip and barred configuration", async () => {
+  const observed = [];
+  const catalog = createSurfaceAwareToolCatalog(
+    {},
+    {
+      appConfig: {
+        assistantServer: {
+          admin: {
+            barredActionIds: ["demo.admin.secret"],
+            toolSkipActionPrefixes: ["demo.admin."]
+          },
+          console: {
+            barredActionIds: ["demo.console.secret"]
+          }
+        }
+      },
+      createCatalog(_scope, options = {}) {
+        observed.push(options);
+        return {
+          resolveToolSet(context = {}) {
+            return {
+              tools: [
+                {
+                  name: `tool:${String(context.surface || "default")}`
+                }
+              ],
+              byName: new Map()
+            };
+          },
+          toOpenAiToolSchema(tool) {
+            return {
+              tool
+            };
+          },
+          async executeToolCall(payload = {}) {
+            return {
+              ok: true,
+              payload,
+              options
+            };
+          }
+        };
+      }
+    }
+  );
+
+  assert.deepEqual(catalog.resolveToolSet({ surface: "admin" }).tools, [{ name: "tool:admin" }]);
+  assert.deepEqual(catalog.resolveToolSet({ surface: "console" }).tools, [{ name: "tool:console" }]);
+  assert.throws(() => catalog.resolveToolSet({}), /requires context\.surface/);
+
+  const execution = await catalog.executeToolCall({
+    toolName: "demo",
+    context: {
+      surface: "admin"
+    }
+  });
+  assert.throws(() => catalog.executeToolCall({ toolName: "demo", context: {} }), /requires context\.surface/);
+
+  assert.deepEqual(observed, [
+    {
+      barredActionIds: ["demo.admin.secret"],
+      skipActionPrefixes: ["assistant.", "demo.admin."]
+    },
+    {
+      barredActionIds: ["demo.console.secret"],
+      skipActionPrefixes: ["assistant."]
+    }
+  ]);
+  assert.deepEqual(execution.options, {
+    barredActionIds: ["demo.admin.secret"],
+    skipActionPrefixes: ["assistant.", "demo.admin."]
+  });
+});

package/test/lazyAppConfig.test.js

@@ -0,0 +1,248 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { AppError } from "@jskit-ai/kernel/server/runtime";
+import { registerRoutes } from "../src/server/registerRoutes.js";
+import { createChatService } from "../src/server/services/chatService.js";
+
+function createAssistantAppConfig() {
+  return {
+    surfaceDefinitions: {
+      admin: {
+        id: "admin",
+        enabled: true,
+        requiresWorkspace: true,
+        accessPolicyId: "workspace_member"
+      }
+    },
+    assistantSurfaces: {
+      admin: {
+        settingsSurfaceId: "admin",
+        configScope: "workspace"
+      }
+    }
+  };
+}
+
+test("registerRoutes resolves appConfig lazily when handlers run", async () => {
+  const routes = [];
+  let currentAppConfig = null;
+
+  const router = {
+    register(method, path, options, handler) {
+      routes.push({ method, path, options, handler });
+    }
+  };
+
+  const app = {
+    make(token) {
+      if (token === "jskit.http.router") {
+        return router;
+      }
+      if (token === "appConfig") {
+        return currentAppConfig;
+      }
+      throw new Error(`Unexpected token: ${token}`);
+    },
+    has(token) {
+      return token === "appConfig" ? Boolean(currentAppConfig) : token === "jskit.http.router";
+    }
+  };
+
+  registerRoutes(app);
+  currentAppConfig = createAssistantAppConfig();
+
+  const route = routes.find(
+    (entry) =>
+      entry.method === "GET" &&
+      entry.path === "/api/w/:workspaceSlug/assistant/:surfaceId/conversations"
+  );
+
+  assert.ok(route, "Expected workspace assistant conversations route to be registered.");
+
+  let capturedInput = null;
+  const reply = {
+    statusCode: 0,
+    payload: null,
+    code(statusCode) {
+      this.statusCode = statusCode;
+      return this;
+    },
+    send(payload) {
+      this.payload = payload;
+      return this;
+    }
+  };
+
+  await route.handler(
+    {
+      headers: {
+        "x-jskit-surface": "admin"
+      },
+      input: {
+        params: {
+          workspaceSlug: "dogandgroom",
+          surfaceId: "admin"
+        },
+        query: {
+          limit: 20
+        }
+      },
+      executeAction: async ({ input }) => {
+        capturedInput = input;
+        return {
+          entries: [],
+          pagination: {
+            cursor: null,
+            nextCursor: null,
+            limit: 20,
+            hasMore: false
+          }
+        };
+      }
+    },
+    reply
+  );
+
+  assert.equal(reply.statusCode, 200);
+  assert.equal(capturedInput?.targetSurfaceId, "admin");
+  assert.equal(capturedInput?.workspaceSlug, "dogandgroom");
+});
+
+test("registerRoutes returns clear AppError payload for pre-stream assistant failures", async () => {
+  const routes = [];
+  let currentAppConfig = null;
+
+  const router = {
+    register(method, path, options, handler) {
+      routes.push({ method, path, options, handler });
+    }
+  };
+
+  const app = {
+    make(token) {
+      if (token === "jskit.http.router") {
+        return router;
+      }
+      if (token === "appConfig") {
+        return currentAppConfig;
+      }
+      throw new Error(`Unexpected token: ${token}`);
+    },
+    has(token) {
+      return token === "appConfig" ? Boolean(currentAppConfig) : token === "jskit.http.router";
+    }
+  };
+
+  registerRoutes(app);
+  currentAppConfig = createAssistantAppConfig();
+
+  const route = routes.find(
+    (entry) =>
+      entry.method === "POST" &&
+      entry.path === "/api/w/:workspaceSlug/assistant/:surfaceId/chat/stream"
+  );
+
+  assert.ok(route, "Expected workspace assistant chat stream route to be registered.");
+
+  const reply = {
+    statusCode: 0,
+    payload: null,
+    code(statusCode) {
+      this.statusCode = statusCode;
+      return this;
+    },
+    send(payload) {
+      this.payload = payload;
+      return this;
+    },
+    header() {
+      return this;
+    }
+  };
+
+  await route.handler(
+    {
+      raw: {
+        on() {},
+        off() {}
+      },
+      headers: {
+        "x-jskit-surface": "admin"
+      },
+      input: {
+        params: {
+          workspaceSlug: "dogandgroom",
+          surfaceId: "admin"
+        },
+        body: {
+          messageId: "msg_1",
+          input: "hello",
+          history: []
+        }
+      },
+      executeAction: async () => {
+        throw new AppError(503, "Assistant provider is not configured.");
+      }
+    },
+    reply
+  );
+
+  assert.equal(reply.statusCode, 503);
+  assert.deepEqual(reply.payload, {
+    error: "Assistant provider is not configured.",
+    code: "APP_ERROR"
+  });
+});
+
+test("chat service resolves appConfig lazily when conversations are listed", async () => {
+  let currentAppConfig = {};
+
+  const chatService = createChatService({
+    aiClientFactory: {
+      resolveClient() {
+        throw new Error("resolveClient should not be called when listing conversations.");
+      }
+    },
+    transcriptService: {
+      async listConversationsForUser(assistantSurface, workspace, actor, query, options = {}) {
+        return {
+          assistantSurface,
+          workspace,
+          actor,
+          query,
+          options
+        };
+      }
+    },
+    serviceToolCatalog: {},
+    assistantConfigService: {},
+    resolveAppConfig: () => currentAppConfig
+  });
+
+  currentAppConfig = createAssistantAppConfig();
+
+  const response = await chatService.listConversations(
+    {
+      limit: 20
+    },
+    {
+      input: {
+        targetSurfaceId: "admin",
+        workspaceSlug: "dogandgroom"
+      },
+      context: {
+        actor: {
+          authenticated: true,
+          userId: 42
+        },
+        workspace: {
+          id: 7,
+          slug: "dogandgroom"
+        }
+      }
+    }
+  );
+
+  assert.equal(response.assistantSurface.targetSurfaceId, "admin");
+  assert.equal(response.workspace.slug, "dogandgroom");
+});

package/test/packageDescriptor.test.js

@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import descriptor from "../package.descriptor.mjs";
+
+function findTextMutation(id) {
+  const mutations = Array.isArray(descriptor?.mutations?.text) ? descriptor.mutations.text : [];
+  return mutations.find((entry) => String(entry?.id || "") === id) || null;
+}
+
+function findFileMutation(id) {
+  const mutations = Array.isArray(descriptor?.mutations?.files) ? descriptor.mutations.files : [];
+  return mutations.find((entry) => String(entry?.id || "") === id) || null;
+}
+
+test("assistant-runtime descriptor registers runtime providers and initializes assistant config roots", () => {
+  assert.equal(descriptor.kind, "runtime");
+  assert.equal(descriptor.packageId, "@jskit-ai/assistant-runtime");
+  assert.equal(descriptor.runtime?.server?.providers?.[0]?.entrypoint, "src/server/AssistantProvider.js");
+  assert.equal(descriptor.runtime?.client?.providers?.[0]?.entrypoint, "src/client/providers/AssistantClientProvider.js");
+
+  const publicInit = findTextMutation("assistant-runtime-public-surface-registry-init");
+  const serverInit = findTextMutation("assistant-runtime-server-surface-registry-init");
+
+  assert.match(String(publicInit?.value || ""), /config\.assistantSurfaces \|\|= \{\};/);
+  assert.match(String(serverInit?.value || ""), /config\.assistantServer \|\|= \{\};/);
+});
+
+test("assistant-runtime descriptor ships common assistant migrations", () => {
+  const configMigration = findFileMutation("assistant-runtime-config-initial-schema");
+  const transcriptMigration = findFileMutation("assistant-runtime-transcripts-initial-schema");
+
+  assert.equal(configMigration?.from, "templates/migrations/assistant_config_initial.cjs");
+  assert.equal(transcriptMigration?.from, "templates/migrations/assistant_transcripts_initial.cjs");
+});