@jskit-ai/assistant-runtime 0.2.9 → 0.2.11

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/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/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.9",
+  "version": "0.2.11",
   "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.7",
+    "@jskit-ai/assistant-core": "0.2.9",
     "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: "" });

package/src/client/composables/conversationGoal.js

@@ -0,0 +1,266 @@
+import { computed, ref, shallowRef, toValue, watch } from "vue";
+import { failureMessage, isAccessDenied, resultError } from "../support/conversationFailures.js";
+import { useJskitText } from "../i18n.js";
+
+const { t } = useJskitText();
+
+/**
+ * A retained conversation's goal: the goal read for the current segment and the Set, Resume, Pause and Cancel
+ * commands. The conversation calls its lifecycle operations; it starts no watcher of its own.
+ * @param {{
+ *   api: import("@jskit-ai/assistant-core/client/types").AssistantApi,
+ *   identity: import("../types.js").ConversationIdentity,
+ *   readers: Map<symbol, import("../types.js").ConversationReader>,
+ *   goalReadEnabled: boolean,
+ *   current: import("vue").ComputedRef<boolean>,
+ *   active: import("vue").ComputedRef<boolean>,
+ *   available: import("vue").ComputedRef<boolean>,
+ *   accessDenied: import("vue").Ref<boolean>,
+ *   snapshot: import("vue").ShallowRef<any>,
+ *   delivery: import("@jskit-ai/assistant-core/client/types").AssistantMessageDelivery,
+ *   submitRequest: (payload: object, options: { messageId: string }) => Promise<any>,
+ *   receiveError: (failure: any) => void,
+ *   reloadSubscription: () => Promise<unknown> | undefined
+ * }} conversation
+ */
+function createConversationGoal({ api, identity, readers, goalReadEnabled, current, active, available, accessDenied, snapshot,
+  delivery, submitRequest, receiveError, reloadSubscription }) {
+  const goalAction = ref("");
+  // An accepted Set or Resume waiting for its goal keeps Pause and Cancel usable.
+  const goalSettling = ref(false);
+  const goalTargetCurrent = ref(false);
+  const goalError = ref("");
+  const goalView = shallowRef(null);
+  const goalLoadError = ref("");
+  let goalRead = null;
+  let goalSegment = null;
+  let goalReadController = null;
+  let goalReadQueued = false;
+  let goalCommandSequence = 0;
+  const readsGoals = computed(() => goalReadEnabled || snapshot.value?.capabilities?.goals === true ||
+    [...readers.values()].some(reader => toValue(reader.goal) === true));
+
+  /**
+   * Follows a new conversation state: a new segment needs a new goal target, and a changed goal a fresh read.
+   * @param {any} state
+   * @param {any} previous The state it replaces.
+   * @param {{ initial: boolean }} options
+   */
+  function receiveState(state, previous, { initial }) {
+    const goalChanged = JSON.stringify([previous?.goal, previous?.capabilities?.goals,
+      previous?.capabilities?.goalCommands, previous?.capabilities?.goalBudgets]) !==
+      JSON.stringify([state.goal, state.capabilities?.goals, state.capabilities?.goalCommands, state.capabilities?.goalBudgets]);
+    if (state.segmentId !== goalSegment) {
+      // Keep the open goal menu while its first native identity arrives. The
+      // pending read disables commands until it supplies the new exact target.
+      goalTargetCurrent.value = false;
+      goalLoadError.value = "";
+      abortRead();
+    }
+    if (readsGoals.value && (initial || goalChanged || state.segmentId !== goalSegment)) void refreshGoal();
+    goalSegment = state.segmentId;
+  }
+  /** Clears the goal shown with the conversation view. The open command, queued read and target stay. */
+  function clear() {
+    goalError.value = "";
+    goalView.value = null;
+    goalLoadError.value = "";
+    abortRead();
+  }
+  /** After lost access, commands wait for a target read with access again. */
+  function forgetTarget() {
+    goalTargetCurrent.value = false;
+  }
+  /** After the actor changed, no open command or queued read survives. */
+  function retire() {
+    goalAction.value = "";
+    goalSettling.value = false;
+    goalReadQueued = false;
+  }
+  /** Stops the goal read in flight. */
+  function abortRead() {
+    // readable-check: allow optional-collaborator - data: the controller of the goal read in flight, none between reads
+    goalReadController?.abort();
+  }
+  /** A goal command whose delivery was confirmed no longer shows its earlier error. */
+  function clearCommandError() {
+    goalError.value = "";
+  }
+
+  function refreshGoal() {
+    if (!active.value || !snapshot.value || !readsGoals.value || accessDenied.value) return Promise.resolve(false);
+    if (goalRead) { goalReadQueued = true; return goalRead; }
+    const segment = snapshot.value.segmentId;
+    const capabilities = snapshot.value.capabilities;
+    const controller = new AbortController();
+    goalReadController = controller;
+    const job = Promise.resolve().then(() => api.readConversationGoal(identity.conversationId, {
+      signal: AbortSignal.any([controller.signal, AbortSignal.timeout(30_000)])
+    })).then(result => {
+      if (!current.value || controller.signal.aborted || snapshot.value?.segmentId !== segment) return false;
+      // Hosts may supply a same-read target and product view. Standalone reads
+      // retain their existing goal/null contract and captured conversation target.
+      goalView.value = result && Object.hasOwn(result, "target") ? result : {
+        status: "available", goal: result, target: { segmentId: segment, capabilities }
+      };
+      // A background read does not invalidate this observation. Its supplied
+      // goal target may intentionally differ from the visible chat segment.
+      goalTargetCurrent.value = true;
+      goalLoadError.value = "";
+      return true;
+    }).catch(failure => {
+      if (current.value && !controller.signal.aborted && snapshot.value?.segmentId === segment) {
+        goalLoadError.value = failureMessage(failure, t("jskit.assistant.runtime.goal.unavailable"));
+      }
+      return false;
+    }).finally(() => {
+      if (goalRead !== job) return;
+      goalRead = null;
+      goalReadController = null;
+      if (goalReadQueued) {
+        goalReadQueued = false;
+        void refreshGoal();
+      }
+    });
+    goalRead = job;
+    return job;
+  }
+  async function changeGoal(action, input = {}, { messageId = crypto.randomUUID() } = {}) {
+    const view = goalView.value;
+    const target = view?.target;
+    const command = target?.capabilities?.goalCommands?.[action];
+    // Pause and Cancel never depend on chat delivery: each is pinned to the goal
+    // it stops and goes straight to the goal operation, even while a message is
+    // sending or its receipt is unknown. Set and Resume wait for those.
+    const stopping = action === "pause" || action === "cancel";
+    if (!available.value || view?.status !== "available" || goalLoadError.value ||
+        goalAction.value && !(stopping && goalSettling.value) || !goalTargetCurrent.value ||
+        !["message", "control"].includes(command?.delivery) ||
+        !stopping && delivery.state.messages.some(message => message.status === "uncertain")) return false;
+    if (input.tokenBudget != null && !target.capabilities.goalBudgets) {
+      goalError.value = t("jskit.assistant.runtime.goal.budgetsUnsupported");
+      return false;
+    }
+    const retry = stopping ? null : delivery.find(messageId);
+    if (retry && retry.status !== "failed") return false;
+    const request = retry?.payload.goalRequest || { action, expectedSegmentId: target.segmentId,
+      expectedGoalId: view.goal?.id || null,
+      ...(action === "set" ? { objective: String(input.objective || "").trim(),
+        ...(input.tokenBudget == null ? {} : { tokenBudget: input.tokenBudget }) } : {}) };
+    const before = view.goal ? { id: view.goal.id, status: view.goal.status } : null;
+    const sequence = ++goalCommandSequence;
+    let accepted = false;
+    goalAction.value = action;
+    goalSettling.value = false;
+    goalError.value = "";
+    try {
+      let result;
+      if (retry || !stopping && command.delivery === "message") {
+        result = await submitRequest(retry?.payload || {
+          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 || t("jskit.assistant.runtime.goal.changeFailed");
+          }
+          return false;
+        }
+      } else {
+        result = await api.updateConversationGoal(identity.conversationId,
+          command.delivery === "message" ? { ...request, messageId } : request);
+        if (result?.ok === false) throw new Error(resultError(result) || t("jskit.assistant.runtime.goal.changeFailed"));
+      }
+      accepted = true;
+      return result;
+    } catch (failure) {
+      if (current.value) {
+        goalError.value = failureMessage(failure);
+        if (isAccessDenied(failure)) receiveError(failure);
+      }
+      return false;
+    } finally {
+      // The command stays Starting, Resuming, Pausing or Cancelling until a goal
+      // read made after the server's answer arrives; until then the control
+      // shows no stale goal or enabled form. An accepted Set or Resume also
+      // waits while its goal waits behind the running turn.
+      if (current.value && goalCommandSequence === sequence) {
+        await goalRead;
+        await refreshGoal();
+        if (accepted && !stopping) await awaitGoalChange(before, sequence);
+        reloadSubscription();
+      }
+      if (goalCommandSequence === sequence) {
+        goalAction.value = "";
+        goalSettling.value = false;
+      }
+    }
+  }
+  // An accepted Set or Resume changes the server's goal, now or once the turn
+  // it waits behind has ended. When the conversation stops working without
+  // that change, a fresh read decides and the reason is shown. A later Pause
+  // or Cancel ends the wait.
+  const goalChangedFrom = before => {
+    const goal = goalView.value?.goal;
+    return Boolean(goal) && (goal.id !== before?.id || goal.status !== before?.status);
+  };
+  async function awaitGoalChange(before, sequence) {
+    const settled = () => !current.value || goalCommandSequence !== sequence || goalChangedFrom(before);
+    await reloadSubscription();
+    if (!settled()) goalSettling.value = true;
+    while (!settled() && snapshot.value?.status === "working") {
+      await new Promise(resolve => {
+        const stop = watch([goalView, () => snapshot.value?.status, current, goalAction], () => { stop(); resolve(); });
+      });
+    }
+    if (settled()) return;
+    await goalRead;
+    await refreshGoal();
+    if (!settled()) goalError.value = t("jskit.assistant.runtime.goal.notStarted");
+  }
+  const goalState = computed(() => {
+    const view = goalView.value;
+    if (!readsGoals.value) return null;
+    const capabilities = view?.target?.capabilities || {};
+    const commands = capabilities.goalCommands || {};
+    const loading = !goalTargetCurrent.value && !goalLoadError.value;
+    const goalAvailable = goalTargetCurrent.value && view?.status === "available" && !goalLoadError.value;
+    const stopPending = Boolean(goalAction.value) && !goalSettling.value || !goalAvailable || !available.value;
+    return {
+      enabled: active.value && Boolean(loading || (view?.status === "available" && !goalLoadError.value) || goalError.value || goalLoadError.value),
+      loading,
+      available: Boolean(goalAvailable),
+      action: goalAction.value,
+      working: snapshot.value?.status === "working",
+      tokenBudgetSupported: capabilities.goalBudgets === true,
+      goal: goalAvailable && view?.goal ? { ...view.goal, elapsedSeconds: view.goal.timeUsedSeconds,
+        sampledAt: Date.parse(view.goal.updatedAt) } : null,
+      pending: Boolean(goalAction.value) || stopPending || delivery.state.sending ||
+        delivery.state.messages.some(message => message.status === "uncertain"),
+      stopPending,
+      error: goalError.value || goalLoadError.value || view?.error || "",
+      pauseInterruptsTurn: commands.pause?.interruptsTurn === true,
+      cancelInterruptsTurn: commands.cancel?.interruptsTurn === true,
+      ...Object.fromEntries(["set", "resume", "pause", "cancel"].filter(action =>
+        ["message", "control"].includes(commands[action]?.delivery)).map(action => [action, input => changeGoal(action, input)]))
+    };
+  });
+
+  return {
+    readsGoals,
+    goalState,
+    goalView,
+    goalLoadError,
+    refreshGoal,
+    changeGoal,
+    receiveState,
+    clear,
+    forgetTarget,
+    retire,
+    abortRead,
+    clearCommandError
+  };
+}
+
+export { createConversationGoal };