@jskit-ai/assistant-runtime 0.2.8 → 0.2.10

package/README.md

@@ -19,7 +19,7 @@ Main exports by subpath:
 
 | Subpath | Provides |
 | --- | --- |
-| `@jskit-ai/assistant-runtime/server` | `AssistantFeature`, `createAssistantActions`, `registerAssistantRoutes`, `registerConversationSubscriptions`, `registerFastifyConversations` |
+| `@jskit-ai/assistant-runtime/server` | `AssistantFeature`, `createAssistantActions`, `registerAssistantRoutes`, `registerConversationSubscriptions`, `registerFastifyConversations`, `createSurfaceAwareToolCatalog` |
 | `@jskit-ai/assistant-runtime/server/actionIds` | Assistant action identifiers |
 | `@jskit-ai/assistant-runtime/client` | `AssistantConversationClientElement`, `AssistantSurfaceClientElement`, `AssistantSettingsClientElement`, `useAssistantConversation`, `configureAssistantConversations` |
 | `@jskit-ai/assistant-runtime/shared` | Assistant surface configuration helpers |

package/fixtures/canonical-conversation/main.js

@@ -10,12 +10,13 @@ import { createWebPlacementRuntime } from "../../../shell-web/src/client/placeme
 import { createFixtureSocket } from "./socket.js";
 import { assistantHttpClient, createAssistantApi } from "@jskit-ai/assistant-core/client";
 import { configureAssistantConversations, useAssistantConversation } from "../../src/client/composables/useAssistantConversation.js";
+import { silentLogger } from "@jskit-ai/kernel/shared/support/silentLogger";
 
 globalThis.__JSKIT_CLIENT_APP_CONFIG__ = {
   surfaceDefinitions: { home: { requiresWorkspace: false } },
   assistantSurfaces: { home: { settingsSurfaceId: "home", configScope: "global" } }
 };
-const placement = createWebPlacementRuntime({ components: new Map() });
+const placement = createWebPlacementRuntime({ components: new Map(), logger: silentLogger });
 placement.setContext({ user: { id: "42" }, surfaceConfig: {
   defaultSurfaceId: "home", surfacesById: { home: { id: "home", routeBase: "/", requiresWorkspace: false } }
 } });

package/fixtures/canonical-conversation/vite.config.mjs

@@ -110,6 +110,12 @@ export default defineConfig({
           for (const pending of held.splice(0)) pending.respond(pending.receipt);
           return json({ ok: true });
         }
+        if (url.pathname === "/fixture/start-queued-goal") {
+          const state = states.get(input.id);
+          changeGoal(state, state.queuedGoal);
+          state.queuedGoal = null;
+          return json({ ok: true });
+        }
         if (url.pathname === "/fixture/finish") {
           const state = states.get(input.id);
           state.status = "ready";
@@ -145,6 +151,11 @@ export default defineConfig({
           }
           const receipt = command.delivery === "message" ? accept(state, { messageId: input.messageId,
             text: input.objective || (input.action === "resume" ? "Resume the goal." : "Cancel the goal.") }) : null;
+          // The command is accepted behind the running turn; its goal changes later.
+          if (receipt && mode === "queue-goal") {
+            state.queuedGoal = input;
+            return json(receipt);
+          }
           changeGoal(state, input);
           const result = receipt || state.goal || null;
           return json(result, result === null ? 204 : 200);

package/fixtures/conversation/main.js

@@ -8,6 +8,7 @@ import { aliases, mdi } from "vuetify/iconsets/mdi-svg";
 import "vuetify/styles";
 import App from "./App.vue";
 import { createWebPlacementRuntime } from "../../../shell-web/src/client/placement/runtime.js";
+import { silentLogger } from "@jskit-ai/kernel/shared/support/silentLogger";
 
 globalThis.__JSKIT_CLIENT_APP_CONFIG__ = {
   surfaceDefinitions: { admin: { requiresWorkspace: true }, console: { requiresWorkspace: false } },
@@ -18,7 +19,7 @@ globalThis.__JSKIT_CLIENT_APP_CONFIG__ = {
 };
 const router = createRouter({ history: createWebHistory(), routes: [{ path: "/:pathMatch(.*)*", component: App }] });
 const app = createApp(App);
-const placement = createWebPlacementRuntime({ components: new Map() });
+const placement = createWebPlacementRuntime({ components: new Map(), logger: silentLogger });
 placement.setContext({ user: { id: "1" }, surfaceConfig: {
   defaultSurfaceId: "admin",
   surfacesById: { admin: { id: "admin", routeBase: "/", requiresWorkspace: false } }

package/fixtures/conversation/vite.config.mjs

@@ -3,6 +3,7 @@ import { createChatService } from "../../src/server/services/chatService.js";
 import { ASSISTANT_STREAM_WRITER_METHODS } from "../../src/server/support/assistantStreamWriter.js";
 import { createAssistantConversationRuntime } from "../../src/server/createAssistantRuntime.js";
 import { createMemoryAssistantRows } from "../../test/support/memoryAssistantRows.js";
+import { createScriptedModel } from "../../test/support/scriptedModel.js";
 import { defineConfig } from "vite";
 import vue from "@vitejs/plugin-vue";
 import { fileURLToPath } from "node:url";
@@ -66,14 +67,14 @@ export default defineConfig({
               turnRequests,
               aiClientFactory: { async resolveClient(_surface, { integrationId }) {
                 return { enabled: true, provider: "fixture", defaultModel: integrationId, supportsAttachments: true,
-                  async *createChatCompletionStream({ messages }) {
+                  model: createScriptedModel(async function* ({ messages }) {
                     stream.receivedFiles = messages.at(-1).content;
                     await nextChunk();
                     yield { choices: [{ delta: { content: "Partial answer" } }] };
                     await nextChunk();
                     yield { choices: [{ delta: { content: " completed." } }] };
                     yield { choices: [{ delta: {}, finish_reason: "stop" }] };
-                  }
+                  }, { model: integrationId })
                 };
               } },
               attachments: { async resolve({ attachmentIds }) {
@@ -118,7 +119,7 @@ export default defineConfig({
           const older = url.searchParams.has("page[cursor]");
           return json({ data: [{ type: "assistant-conversations", id: older ? "2" : "1", attributes: {
             title: older ? "Older conversation" : "Saved conversation", status: "completed", startedAt: "2026-09-01T00:00:00Z"
-          } }], meta: { page: { nextCursor: older ? null : "older" } } });
+          } }], meta: { pagination: { cursor: { next: older ? null : "older" } } } });
         }
         res.statusCode = 404;
         json({ error: "Unknown fixture request" });

package/locales/en.json

@@ -74,6 +74,7 @@
         "goal": {
           "budgetsUnsupported": "This conversation does not support goal token budgets.",
           "changeFailed": "Could not change the goal.",
+          "notStarted": "The goal did not start. Check the chat before starting it again.",
           "unavailable": "Goal status is unavailable.",
           "resumeMessage": "Resume the goal.",
           "cancelMessage": "Cancel the goal."

package/migrations/assistant_config_initial.cjs

@@ -1,16 +1,12 @@
 exports.up = async function up(knex) {
   const hasTable = await knex.schema.hasTable("assistant_config");
   if (!hasTable) {
-    const hasWorkspacesTable = await knex.schema.hasTable("workspaces");
-
     await knex.schema.createTable("assistant_config", (table) => {
       table.bigIncrements("id").primary();
       table.string("target_surface_id", 64).notNullable();
       table.string("scope_key", 160).notNullable();
+      // constraints/assistant_workspaces_foreign_keys.cjs adds the workspaces key when that table exists.
       table.bigInteger("workspace_id").unsigned().nullable();
-      if (hasWorkspacesTable) {
-        table.foreign("workspace_id").references("id").inTable("workspaces").onDelete("CASCADE");
-      }
       table.text("system_prompt").notNullable().defaultTo("");
       table.timestamp("created_at").notNullable().defaultTo(knex.fn.now());
       table.timestamp("updated_at").notNullable().defaultTo(knex.fn.now());

package/migrations/assistant_transcripts_initial.cjs

@@ -1,14 +1,11 @@
+// constraints/ adds the users keys, and the workspaces keys when that table exists.
 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.bigIncrements("id").primary();
       table.bigInteger("workspace_id").unsigned().nullable();
-      if (hasWorkspacesTable) {
-        table.foreign("workspace_id").references("id").inTable("workspaces").onDelete("CASCADE");
-      }
-      table.bigInteger("created_by_user_id").unsigned().nullable().references("id").inTable("users").onDelete("SET NULL").index();
+      table.bigInteger("created_by_user_id").unsigned().nullable().index();
       table.string("title", 160).notNullable().defaultTo("New conversation");
       table.string("status", 32).notNullable().defaultTo("active");
       table.string("provider", 64).notNullable().defaultTo("");
@@ -33,14 +30,11 @@ exports.up = async function up(knex) {
       table.bigIncrements("id").primary();
       table.bigInteger("conversation_id").unsigned().notNullable().references("id").inTable("assistant_conversations").onDelete("CASCADE");
       table.bigInteger("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.bigInteger("actor_user_id").unsigned().nullable().references("id").inTable("users").onDelete("SET NULL").index();
+      table.bigInteger("actor_user_id").unsigned().nullable().index();
       table.text("content_text").nullable();
       table.text("metadata_json").nullable();
       table.timestamp("created_at").notNullable().defaultTo(knex.fn.now());

package/migrations/assistant_transcripts_summary.cjs

@@ -0,0 +1,28 @@
+// A long conversation keeps one compaction summary next to its messages, which are never
+// deleted: the summary text and the last turn it covers. transcript_revision changes on
+// every saved transcript change, so a server can keep reusing the rows it already read.
+const COLUMNS = ["summary_text", "summary_through_turn_id", "transcript_revision"];
+
+exports.up = async function up(knex) {
+  const missing = [];
+  for (const column of COLUMNS) {
+    if (!await knex.schema.hasColumn("assistant_conversations", column)) missing.push(column);
+  }
+  if (!missing.length) return;
+  await knex.schema.alterTable("assistant_conversations", table => {
+    if (missing.includes("summary_text")) table.text("summary_text", "longtext").nullable();
+    if (missing.includes("summary_through_turn_id")) table.string("summary_through_turn_id", 64).nullable();
+    if (missing.includes("transcript_revision")) table.string("transcript_revision", 36).nullable();
+  });
+};
+
+exports.down = async function down(knex) {
+  const present = [];
+  for (const column of COLUMNS) {
+    if (await knex.schema.hasColumn("assistant_conversations", column)) present.push(column);
+  }
+  if (!present.length) return;
+  await knex.schema.alterTable("assistant_conversations", table => {
+    table.dropColumns(...present);
+  });
+};

package/migrations/assistant_turn_requests.cjs

@@ -2,7 +2,8 @@ exports.up = async function up(knex) {
   if (await knex.schema.hasTable("assistant_turn_requests")) return;
   await knex.schema.createTable("assistant_turn_requests", table => {
     table.bigIncrements("id").primary();
-    table.bigInteger("actor_user_id").unsigned().notNullable().references("id").inTable("users").onDelete("CASCADE");
+    // constraints/assistant_users_foreign_keys.cjs adds the users key once the users table exists.
+    table.bigInteger("actor_user_id").unsigned().notNullable();
     table.string("scope_key", 128).notNullable();
     table.string("message_sid", 128).notNullable();
     table.string("claim_token", 36).notNullable();

package/migrations/constraints/assistant_users_foreign_keys.cjs

@@ -0,0 +1,22 @@
+// The users table can come from the application's own migrations, which run after every
+// package's table migrations, so the assistant tables get their users keys in this later phase.
+// A database migrated before this file already has them from the table migrations.
+const USER_KEYS = [
+  { tableName: "assistant_conversations", columnName: "created_by_user_id", parentTable: "users", onDelete: "SET NULL" },
+  { tableName: "assistant_messages", columnName: "actor_user_id", parentTable: "users", onDelete: "SET NULL" },
+  { tableName: "assistant_turn_requests", columnName: "actor_user_id", parentTable: "users", onDelete: "CASCADE" }
+];
+
+exports.up = async function up(knex) {
+  const { addMissingForeignKey } = await import("@jskit-ai/database-runtime/server/foreignKeyMigrations");
+  for (const key of USER_KEYS) {
+    await addMissingForeignKey(knex, key);
+  }
+};
+
+exports.down = async function down(knex) {
+  const { dropForeignKeyIfPresent } = await import("@jskit-ai/database-runtime/server/foreignKeyMigrations");
+  for (const key of USER_KEYS) {
+    await dropForeignKeyIfPresent(knex, key);
+  }
+};

package/migrations/constraints/assistant_workspaces_foreign_keys.cjs

@@ -0,0 +1,26 @@
+// workspaces-core's migrations run after assistant-runtime's, and an application may create
+// workspaces itself, so the assistant tables get their workspaces keys in this later phase, when
+// that table exists; an application without workspaces gets none.
+// A database migrated before this file may already have them from the table migrations.
+const WORKSPACE_KEYS = [
+  { tableName: "assistant_config", columnName: "workspace_id", parentTable: "workspaces", onDelete: "CASCADE" },
+  { tableName: "assistant_conversations", columnName: "workspace_id", parentTable: "workspaces", onDelete: "CASCADE" },
+  { tableName: "assistant_messages", columnName: "workspace_id", parentTable: "workspaces", onDelete: "CASCADE" }
+];
+
+exports.up = async function up(knex) {
+  if (!(await knex.schema.hasTable("workspaces"))) {
+    return;
+  }
+  const { addMissingForeignKey } = await import("@jskit-ai/database-runtime/server/foreignKeyMigrations");
+  for (const key of WORKSPACE_KEYS) {
+    await addMissingForeignKey(knex, key);
+  }
+};
+
+exports.down = async function down(knex) {
+  const { dropForeignKeyIfPresent } = await import("@jskit-ai/database-runtime/server/foreignKeyMigrations");
+  for (const key of WORKSPACE_KEYS) {
+    await dropForeignKeyIfPresent(knex, key);
+  }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant-runtime",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "type": "module",
   "scripts": {
     "test": "node --test --test-concurrency=1"
@@ -10,22 +10,23 @@
     "./shared": "./src/shared/index.js",
     "./server/actionIds": "./src/server/actionIds.js",
     "./server": "./src/server/index.js",
+    "./server/types": "./src/server/types.js",
     "./locales/en.json": "./locales/en.json"
   },
   "dependencies": {
-    "@jskit-ai/assistant-core": "0.2.6",
+    "@jskit-ai/assistant-core": "0.2.8",
     "json-rest-schema": "^1.0.17"
   },
   "peerDependencies": {
-    "@jskit-ai/http-runtime": "0.2.3",
-    "@jskit-ai/http-web": "0.2.7",
-    "@jskit-ai/kernel": "0.2.3",
-    "@jskit-ai/realtime": "0.2.6",
-    "@jskit-ai/shell-web": "0.2.3",
+    "@jskit-ai/http-runtime": "0.2.4",
+    "@jskit-ai/http-web": "0.2.8",
+    "@jskit-ai/kernel": "0.2.4",
+    "@jskit-ai/realtime": "0.2.7",
+    "@jskit-ai/shell-web": "0.2.4",
     "@tanstack/vue-query": "^5.90.5",
     "vue": "^3.5.13",
     "vuetify": "^4.0.0",
-    "@jskit-ai/database-runtime": "0.1.252"
+    "@jskit-ai/database-runtime": "0.1.253"
   },
   "description": "Capability-based assistant runtime with per-surface chat, transcripts, settings, and action tools.",
   "jskit": {
@@ -38,8 +39,10 @@
         "runtime.actions",
         "runtime.config",
         "runtime.env",
+        "runtime.events",
         "runtime.http",
-        "runtime.http-web"
+        "runtime.http-web",
+        "runtime.logger"
       ]
     },
     "runtime": {
@@ -95,7 +98,11 @@
           },
           {
             "subpath": "./server",
-            "summary": "Provides conversation routes, authorized shared realtime subscriptions, explicit Fastify hosting shorthand and optional database integration."
+            "summary": "Provides conversation routes, authorized shared realtime subscriptions, explicit Fastify hosting shorthand, optional database integration and the per-surface assistant tool catalogue."
+          },
+          {
+            "subpath": "./server/types",
+            "summary": "Type of the assistant.runtime capability, and the contracts of the optional capabilities it reads."
           }
         ],
         "capabilities": [

package/patterns/assistant-surface/example/src/ApplicationAiFeature.js

@@ -1,3 +1,4 @@
+import { resolveActorId } from "@jskit-ai/kernel/server/actions/actionContributorHelpers";
 import { defineFeature } from "@jskit-ai/kernel/server/features";
 import { createAiConnectionResolver } from "@jskit-ai/connectors-catalog/server/ai";
 import { createEnvironmentReferenceResolver } from "@jskit-ai/connectors-core/server";
@@ -10,9 +11,10 @@ export const ApplicationAiFeature = defineFeature({
     return { ai: createAiConnectionResolver({
       configuration,
       authorize(context) {
-        if (!context.actor?.id) return null;
+        const actorId = resolveActorId(context);
+        if (!actorId) return null;
         // Apply the app's AI-use policy here; the actor comes from authentication.
-        return { applicationId: "my-app", subjectId: String(context.actor.id) };
+        return { applicationId: "my-app", subjectId: actorId };
       },
       resolveReference: createEnvironmentReferenceResolver(env)
     }) };

package/src/client/components/AssistantConversationClientElement.vue

@@ -4,6 +4,11 @@ import { AssistantConversationElement } from "@jskit-ai/assistant-core/client/co
 import { useAssistantConversation } from "../composables/useAssistantConversation.js";
 import { useJskitText } from "../i18n.js";
 
+/** @typedef {import("@jskit-ai/assistant-core/client/types").AssistantApi} AssistantApi */
+/** @typedef {import("@jskit-ai/assistant-core/client/types").AssistantAttachments} AssistantAttachments */
+/** @typedef {import("@jskit-ai/assistant-core/client/types").AssistantSuggestions} AssistantSuggestions */
+/** @typedef {import("@jskit-ai/assistant-core/client/types").AssistantModelChoices} AssistantModelChoices */
+
 const props = defineProps({
   conversationId: { type: String, required: true },
   endpoint: { type: String, default: "" },
@@ -11,7 +16,8 @@ const props = defineProps({
   hostSurfaceId: { type: String, default: "" },
   workspaceSlug: { type: String, default: undefined },
   actorKey: { type: String, default: undefined },
-  api: { type: Object, default: null },
+  // An application's own assistant API; without one the binding uses the surface's standard API.
+  api: { type: /** @type {import("vue").PropType<AssistantApi>} */ (Object), default: null },
   active: { type: Boolean, default: true },
   clearDraftOn: { type: String, default: undefined, validator: value => ["dispatch", "accepted"].includes(value) },
   // Unset texts follow the active language; an application's own text is shown as given.
@@ -20,9 +26,9 @@ const props = defineProps({
   placeholder: { type: String, default: undefined },
   layout: { type: String, default: "compact", validator: value => ["page", "compact"].includes(value) },
   data: { type: Object, default: undefined },
-  attachments: { type: Object, default: null },
-  suggestions: { type: Object, default: null },
-  models: { type: Object, default: null },
+  attachments: { type: /** @type {import("vue").PropType<AssistantAttachments>} */ (Object), default: null },
+  suggestions: { type: /** @type {import("vue").PropType<AssistantSuggestions>} */ (Object), default: null },
+  models: { type: /** @type {import("vue").PropType<AssistantModelChoices>} */ (Object), default: null },
   questions: { type: [Boolean, Object], default: null },
   goal: { type: [Boolean, Object], default: null },
   avatarSize: { type: String, default: "compact", validator: (value) => ["hidden", "compact", "standard", "large"].includes(value) }

package/src/client/components/AssistantSurfaceClientElement.vue

@@ -6,6 +6,10 @@ import { mapAssistantConversationTurns, toolStatusText } from "../support/assist
 import { DEFAULT_CONVERSATION_TITLE } from "../../shared/assistantRuntimeConfig.js";
 import { useJskitText } from "../i18n.js";
 
+/** @typedef {import("@jskit-ai/assistant-core/client/types").AssistantConversationAdapter} AssistantConversationAdapter */
+/** @typedef {import("@jskit-ai/assistant-core/client/types").AssistantAttachments} AssistantAttachments */
+/** @typedef {import("@jskit-ai/assistant-core/client/types").AssistantSuggestions} AssistantSuggestions */
+
 const props = defineProps({
   surfaceId: { type: String, required: true },
   layout: { type: String, default: "page", validator: (value) => ["page", "compact"].includes(value) },
@@ -15,10 +19,10 @@ const props = defineProps({
   placeholder: { type: String, default: undefined },
   showToolActivity: { type: Boolean, default: true },
   connections: { type: Array, default: () => [] },
-  attachments: { type: Object, default: null },
-  suggestions: { type: Object, default: null },
-  goal: { type: Object, default: null },
-  activity: { type: Object, default: undefined },
+  attachments: { type: /** @type {import("vue").PropType<AssistantAttachments>} */ (Object), default: null },
+  suggestions: { type: /** @type {import("vue").PropType<AssistantSuggestions>} */ (Object), default: null },
+  goal: { type: /** @type {import("vue").PropType<AssistantConversationAdapter["goal"]>} */ (Object), default: null },
+  activity: { type: /** @type {import("vue").PropType<AssistantConversationAdapter["activity"]>} */ (Object), default: undefined },
   configurationMode: { type: String, default: "editable", validator: value => ["hidden", "readonly", "editable"].includes(value) }
 });
 const integrationId = defineModel("integrationId", { type: String, default: "" });