@jskit-ai/assistant-runtime 0.2.1 → 0.2.3

package/README.md

@@ -34,7 +34,8 @@ modes) and `packages/agent-docs/site/guide/app-extras/assistant-conversation.md`
 With the existing realtime diagnostic option (`JSKIT_REALTIME_DEBUG=1`, or
 `config.realtime.debug=true`), conversation subscriptions emit one `pending`
 warning if admission/snapshot reading has not returned within the client's
-10-second acknowledgement budget. The warning names the current stage and the
+10-second budget, after which the client shows a loading notice and keeps waiting
+(it gives up only after 120 seconds). The warning names the current stage and the
 server-generated epoch; a conversation identity is included only after its
 successful authorized open. Observer release also records the current stage and
 reason. While diagnostics are enabled, every stage transition is recorded at

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

@@ -9,7 +9,7 @@ export default defineConfig({
   plugins: [vue(), {
     name: "controlled-canonical-assistant-api",
     configureServer(server) {
-      let states, requests, held, mode, denied;
+      let states, requests, held, mode, denied, holdCancels, heldCancels;
       const pageLimits = new Map();
       // Exercise the existing page reader over this fixture's controlled rows.
       const transcript = createConversationTranscript({ storage: {
@@ -27,6 +27,7 @@ export default defineConfig({
             streaming: { revision: 0, messages: [] }, capabilities: { steering: false, goals: false, attachments: true } }];
         }));
         requests = []; held = []; mode = "accepted"; denied = false; pageLimits.clear();
+        holdCancels = false; heldCancels = [];
       }
       reset();
       function accept(state, input) {
@@ -60,6 +61,8 @@ export default defineConfig({
         if (url.pathname === "/fixture/reset") { reset(); return json({ ok: true }); }
         if (url.pathname === "/fixture/state") return json({ requests, states: Object.fromEntries(states), held: held.length });
         if (url.pathname === "/fixture/mode") { mode = input.mode; return json({ ok: true }); }
+        if (url.pathname === "/fixture/hold-cancels") { holdCancels = input.hold; return json({ ok: true }); }
+        if (url.pathname === "/fixture/answer-cancels") { for (const agree of heldCancels.splice(0)) agree(); return json({ ok: true }); }
         if (url.pathname === "/fixture/deny") { denied = input.denied; return json({ ok: true }); }
         if (url.pathname === "/fixture/error") { states.get(input.id).error = input.error; return json({ ok: true }); }
         if (url.pathname === "/fixture/interim-reply") { states.get(input.id).interimReply = input.reply; return json({ ok: true }); }
@@ -168,10 +171,27 @@ export default defineConfig({
           return json(accept(state, input), 202);
         }
         if (match[2] === "/cancel") { state.status = "ready"; return json({ stopped: true }); }
+        // The server always records a cancel and drops the unconfirmed request.
+        if (match[2].startsWith("/deliveries/") && match[2].endsWith("/cancel")) {
+          const messageId = decodeURIComponent(match[2].split("/")[2]);
+          const agree = () => {
+            state.cancelled = [...state.cancelled || [], messageId];
+            if (state.pendingRequest?.messageId === messageId) { state.pendingRequest = null; state.status = "ready"; }
+            json({ ok: true, cancelled: true, messageId });
+          };
+          if (holdCancels) heldCancels.push(agree);
+          else agree();
+          return;
+        }
         if (match[2].startsWith("/deliveries/") && match[2].endsWith("/inspect")) {
           const messageId = decodeURIComponent(match[2].split("/")[2]);
+          if (state.cancelled?.includes(messageId)) return json({ status: "cancelled", messageId });
           const receipt = state.conversationLog.find(turn => turn.user?.messageId === messageId);
-          if (!receipt && mode === "not-sent") return json({ status: "not-sent", messageId, error: "This message was not sent. Review it before sending a new message." });
+          if (!receipt && mode === "not-sent") {
+            // Like the runtime, record the proven request as unattempted: reads stop reporting it unconfirmed.
+            if (state.pendingRequest?.messageId === messageId) Object.assign(state, { status: "ready", pendingRequest: null });
+            return json({ status: "not-sent", messageId, error: "This message was not sent. Review it before sending a new message." });
+          }
           return json(receipt ? { status: "accepted", messageId, turnId: receipt.turnId } : { status: "unknown", messageId });
         }
         return json({ error: "Unknown fixture operation" }, 404);

package/locales/en.json

@@ -130,7 +130,8 @@
     },
     "errors": {
       "assistant_history_inspection_required": "This conversation has ambiguous historical SQL rows. Inspect the reported rows offline before using the common runtime; no history was changed.",
-      "assistant_subscription_transport_failed": "Chat updates could not reconnect. Retrying automatically; Reload chat to try now."
+      "assistant_subscription_transport_failed": "Chat updates could not reconnect. Retrying automatically; Reload chat to try now.",
+      "assistant_subscription_waiting": "Chat is still loading. Waiting for the server; Reload chat to try now."
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant-runtime",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "scripts": {
     "test": "node --test --test-concurrency=1"
@@ -13,19 +13,19 @@
     "./locales/en.json": "./locales/en.json"
   },
   "dependencies": {
-    "@jskit-ai/assistant-core": "0.2.1",
+    "@jskit-ai/assistant-core": "0.2.3",
     "json-rest-schema": "^1.0.17"
   },
   "peerDependencies": {
-    "@jskit-ai/http-runtime": "0.2.0",
-    "@jskit-ai/http-web": "0.2.0",
-    "@jskit-ai/kernel": "0.2.0",
-    "@jskit-ai/realtime": "0.2.0",
-    "@jskit-ai/shell-web": "0.2.0",
+    "@jskit-ai/http-runtime": "0.2.1",
+    "@jskit-ai/http-web": "0.2.2",
+    "@jskit-ai/kernel": "0.2.1",
+    "@jskit-ai/realtime": "0.2.1",
+    "@jskit-ai/shell-web": "0.2.1",
     "@tanstack/vue-query": "^5.90.5",
     "vue": "^3.5.13",
     "vuetify": "^4.0.0",
-    "@jskit-ai/database-runtime": "0.1.249"
+    "@jskit-ai/database-runtime": "0.1.250"
   },
   "description": "Capability-based assistant runtime with per-surface chat, transcripts, settings, and action tools.",
   "jskit": {

package/src/client/composables/useAssistantConversation.js

@@ -42,7 +42,8 @@ function configureAssistantConversations(app, { actorKey, api = null, request, c
 // occur after dispatch and must retain an uncertain receipt.
 const SEND_REJECTIONS = new Set([
   "ACTION_VALIDATION_FAILED", "ACTION_PERMISSION_DENIED", "ACTION_SURFACE_FORBIDDEN",
-  "conversation_invalid_message", "conversation_busy", "conversation_not_steerable", "conversation_invalid_goal", "conversation_goal_changed"
+  "conversation_invalid_message", "conversation_busy", "conversation_not_steerable", "conversation_invalid_goal", "conversation_goal_changed",
+  "conversation_message_cancelled"
 ]);
 
 function isQuestionConfiguration(value) {
@@ -116,6 +117,7 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
   const accessDenied = ref(false);
   const delivery = createAssistantMessageDelivery();
   const pendingMessages = new Map();
+  const deliveryChecks = new Map();
   const olderPages = ref([]);
   let historyRevision = 0;
   let deniedHistoryRevision = 0;
@@ -158,10 +160,14 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
       typeof message.payload?.message === "string") : [];
     const restoredMessages = messages.filter(message => !delivery.find(message.id)).map(message => {
       const status = ["failed", "accepted"].includes(message.status) ? message.status : "uncertain";
-      return { ...message, status, checking: false, error: message.error || (status === "accepted" ? "" :
+      return { ...message, status, checking: false, cancelling: false, error: message.error || (status === "accepted" ? "" :
         t("jskit.assistant.runtime.delivery.unconfirmedBeforeClose")) };
     });
     delivery.state.messages = unmatchedOptimisticMessages(turns.value, [...delivery.state.messages, ...restoredMessages], { receiptsOnly: true });
+    // A cancel the server had not agreed to before this page closed is retried.
+    for (const message of messages) {
+      if (message.cancelling || message.cancelError) delivery.cancelFailed(message.id, message.cancelError);
+    }
   } catch {
     draft.value = "";
     draftAttachments.value = [];
@@ -239,6 +245,7 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
     accessDenied.value = false;
     delivery.reconcile(state.turns);
     if (state.status === "unconfirmed" && state.pendingRequest) delivery.restoreUncertain(state.pendingRequest, state.turns);
+    retryCancels();
     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.
@@ -374,6 +381,7 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
     stopPlacement();
     for (const pending of pendingMessages.values()) pending.controller.abort();
     pendingMessages.clear();
+    for (const check of deliveryChecks.values()) check.abort();
     goalReadController?.abort();
     delivery.reset();
   });
@@ -561,11 +569,32 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
       if (current.value) subscription?.reload();
     }
   }
-  function cancelMessage(messageId) {
-    const pending = pendingMessages.get(messageId);
-    if (!pending) return false;
-    pending.controller.abort();
-    return true;
+  // Cancel means cancel, and the server decides. Cancel ends the message's
+  // unsent request and running delivery check, then asks the server, which
+  // always records the cancel. The message stays, shown as cancelling, until
+  // the server agrees; when the server cannot be reached it stays with Cancel
+  // again, and the next snapshot after reconnecting retries it.
+  async function cancelMessage(messageId) {
+    pendingMessages.get(messageId)?.controller.abort();
+    deliveryChecks.get(messageId)?.abort();
+    if (!available.value || !delivery.cancel(messageId)) return false;
+    try {
+      const result = await api.cancelConversationDelivery(identity.conversationId, messageId);
+      if (result?.ok === false) throw Object.assign(new Error(resultError(result)), { status: 409 });
+      if (!current.value) return false;
+      delivery.remove(messageId);
+      subscription?.reload();
+      return true;
+    } catch (failure) {
+      // The server's own refusal names itself; anything else did not reach it.
+      if (current.value) delivery.cancelFailed(messageId, Number.isInteger(failure?.status) && failure.status > 0 ? failureMessage(failure) : "");
+      return false;
+    }
+  }
+  function retryCancels() {
+    for (const message of delivery.state.messages) {
+      if (message.cancelError && !message.cancelling) void cancelMessage(message.id);
+    }
   }
 
   // The original history control keeps older pages separate from the live page.
@@ -653,14 +682,18 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
     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 || !goalTargetCurrent.value ||
         !["message", "control"].includes(command?.delivery) ||
-        delivery.state.messages.some(message => message.status === "uncertain")) return false;
+        !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 = delivery.find(messageId);
+    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,
@@ -669,7 +702,7 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
     goalAction.value = action;
     goalError.value = "";
     try {
-      if (retry || command.delivery === "message") {
+      if (retry || !stopping && command.delivery === "message") {
         const result = await submitRequest(retry?.payload || {
           message: action === "set" ? request.objective
             : t(action === "resume" ? "jskit.assistant.runtime.goal.resumeMessage" : "jskit.assistant.runtime.goal.cancelMessage"),
@@ -683,7 +716,8 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
         }
         return result;
       }
-      const result = await api.updateConversationGoal(identity.conversationId, request);
+      const 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"));
       return result;
     } catch (failure) {
@@ -719,6 +753,7 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
         sampledAt: Date.parse(view.goal.updatedAt) } : null,
       pending: Boolean(goalAction.value) || !goalAvailable || !available.value || delivery.state.sending ||
         delivery.state.messages.some(message => message.status === "uncertain"),
+      stopPending: Boolean(goalAction.value) || !goalAvailable || !available.value,
       error: goalError.value || goalLoadError.value || view?.error || "",
       pauseInterruptsTurn: commands.pause?.interruptsTurn === true,
       cancelInterruptsTurn: commands.cancel?.interruptsTurn === true,
@@ -740,14 +775,18 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
     if (!available.value) return false;
     const message = delivery.find(messageId);
     if (message?.checking) return false;
+    const check = new AbortController();
+    deliveryChecks.set(messageId, check);
     if (message) message.checking = true;
     try {
-      const receipt = await api.inspectConversationDelivery(identity.conversationId, messageId);
-      if (!current.value) return false;
+      const receipt = await api.inspectConversationDelivery(identity.conversationId, messageId, { signal: check.signal });
+      if (!current.value || check.signal.aborted) return false;
       if (receipt.status === "accepted") {
         delivery.accept(messageId);
         if (receipt.messageId === messageId && message?.payload.goalRequest) goalError.value = "";
       }
+      // The server recorded this message as cancelled, perhaps from another tab.
+      else if (receipt.status === "cancelled" && receipt.messageId === messageId) delivery.remove(messageId);
       else if (receipt.status === "not-sent" && receipt.messageId === messageId) delivery.rejectUnsent(messageId, resultError(receipt));
       else if (receipt.status === "unknown" && message?.status === "uncertain") {
         message.error = t("jskit.assistant.runtime.delivery.stillUnknown");
@@ -755,11 +794,15 @@ function createConversation(identity, { api, socket, actorKey, placement, reader
       subscription?.reload();
       return receipt;
     } catch (failure) {
+      if (check.signal.aborted) return false;
       if (current.value && message?.status === "uncertain") message.error = failureMessage(failure, t("jskit.assistant.runtime.delivery.checkFailed"));
       receiveError(failure);
       return false;
     }
-    finally { if (message) message.checking = false; }
+    finally {
+      if (deliveryChecks.get(messageId) === check) deliveryChecks.delete(messageId);
+      if (message) message.checking = false;
+    }
   }
 
   const runtime = { identity, current, active, editable, available, canSubmit, steerable, queueWhileSending: queueing,
@@ -1009,10 +1052,15 @@ function createConversationBinding({ conversationId, endpoint = "", surfaceId =
       } else current.draft.value = "";
     }
     onSubmit?.();
+    const dispatch = () => prepare ? current.submitPrepared(captured, { messageId, onAccepted: acknowledge, prepare })
+      : current.send(captured, { messageId, onAccepted: acknowledge });
     // A restored uncertain receipt may have no retained acceptance callback.
-    // Inspection can acknowledge it, but must never run preparation or Send.
+    // Inspection can acknowledge it. Only the server's proof that the message
+    // never reached the AI (which marks it failed) lets Retry send it again.
     if (retry?.status === "uncertain") return current.inspectDelivery(messageId).then(receipt => {
       if (!current.current.value || !isCurrent()) return false;
+      if (receipt?.status === "not-sent" && receipt.messageId === messageId &&
+          current.delivery.find(messageId)?.status === "failed") return dispatch();
       if (receipt?.status !== "accepted") {
         const error = current.error.value || t("jskit.assistant.runtime.delivery.notConfirmed");
         const pending = current.delivery.find(messageId);
@@ -1022,8 +1070,7 @@ function createConversationBinding({ conversationId, endpoint = "", surfaceId =
       acknowledge();
       return { ...receipt, ok: true };
     });
-    return prepare ? current.submitPrepared(captured, { messageId, onAccepted: acknowledge, prepare })
-      : current.send(captured, { messageId, onAccepted: acknowledge });
+    return dispatch();
   }
   const adapter = computed(() => {
     const current = runtime.value;
@@ -1050,6 +1097,8 @@ function createConversationBinding({ conversationId, endpoint = "", surfaceId =
         hasMoreBefore: current?.hasMoreBefore.value || false,
         loadingMore: current?.loadingMore.value || false, loadMoreError: current?.loadMoreError.value || "",
         loading: current?.loading.value || false, working: !current?.error.value && state?.status === "working" && !current.delivery.state.sending,
+        // The server cancels any unconfirmed message, so its Cancel is offered.
+        cancellableDelivery: true,
         assistantLabel: display.assistantLabel || t("jskit.assistant.runtime.conversation.assistantLabel"),
         welcomeMessage: display.welcomeMessage ?? t("jskit.assistant.runtime.conversation.welcomeMessage"),
         systemLabel: display.systemLabel, variant: display.variant, visible: display.visible, retainWhenHidden: display.retainWhenHidden,
@@ -1071,6 +1120,7 @@ function createConversationBinding({ conversationId, endpoint = "", surfaceId =
         else if (canDraftWhileLoading.value) initialDraft.value = value;
       }, submit,
         resend: messageId => submit({ retryMessageId: messageId }), stop: () => current?.cancel(),
+        cancel: messageId => current?.cancelMessage(messageId),
         checkDelivery: messageId => current?.inspectDelivery(messageId), loadMore: input => current?.loadMore(input), reload: () => current?.reload() }
     };
   });

package/src/client/support/subscribeAssistantConversation.js

@@ -16,6 +16,12 @@ function patchLoadedHistoryPages(pages = [], patch) {
 }
 
 const SNAPSHOT_EVENTS = new Set(["accepted", "settled", "configuration", "phase", "error", "replaced", "goal"]);
+// A connected server may need longer than the normal budget to answer (an
+// overloaded host took 15 s). Abandoning it then discards the server's work and
+// repeats it, so a slow answer only shows a loading notice; it is treated as
+// lost, unsubscribed and retried only after the much longer cap.
+const SUBSCRIPTION_NOTICE_MS = 10_000;
+const SUBSCRIPTION_LOST_MS = 120_000;
 
 function subscribeAssistantConversation({
   socket, conversationId, targetSurfaceId, hostSurfaceId, workspaceSlug,
@@ -44,6 +50,7 @@ function subscribeAssistantConversation({
   // otherwise only the next connect would recover the chat.
   let retryTimer = null;
   let retryDelay = 1_000;
+  let waitingTimer = null;
   const completed = new Map();
   const settledTurns = new Set();
   const pendingReads = new Set();
@@ -187,12 +194,14 @@ function subscribeAssistantConversation({
     if (epoch === null) pending.push(payload);
     else deliver(payload);
   }
-  function clearRetry() {
+  function clearTimers() {
     clearTimeout(retryTimer);
     retryTimer = null;
+    clearTimeout(waitingTimer);
+    waitingTimer = null;
   }
   function subscribe({ preserveHistory = false } = {}) {
-    clearRetry();
+    clearTimers();
     if (disposed || !socket.connected) return;
     const attempt = ++generation;
     epoch = null;
@@ -205,8 +214,12 @@ function subscribeAssistantConversation({
     settledTurns.clear();
     reloadInFlight = null;
     reloadQueued = false;
-    socket.timeout(10_000).emit(ASSISTANT_CONVERSATION_SUBSCRIBE, input, (error, response) => {
+    waitingTimer = setTimeout(() => onError(Object.assign(
+      new Error("Chat is still loading. Waiting for the server; Reload chat to try now."),
+      { code: "assistant_subscription_waiting" })), SUBSCRIPTION_NOTICE_MS);
+    socket.timeout(SUBSCRIPTION_LOST_MS).emit(ASSISTANT_CONVERSATION_SUBSCRIBE, input, (error, response) => {
       if (disposed || attempt !== generation) return;
+      clearTimers();
       if (error || response?.ok !== true) {
         listening = false;
         pending = [];
@@ -232,7 +245,7 @@ function subscribeAssistantConversation({
     });
   }
   function disconnected() {
-    clearRetry();
+    clearTimers();
     generation += 1;
     epoch = null;
     pending = [];
@@ -248,7 +261,7 @@ function subscribeAssistantConversation({
   function release() {
     if (disposed) return;
     disposed = true;
-    clearRetry();
+    clearTimers();
     generation += 1;
     pending = [];
     completed.clear();

package/src/server/actionIds.js

@@ -5,6 +5,7 @@ const actionIds = Object.freeze({
   conversationCancel: "assistant.conversation.cancel",
   conversationSubscribe: "assistant.conversation.subscribe",
   conversationInspectDelivery: "assistant.conversation.delivery.inspect",
+  conversationCancelDelivery: "assistant.conversation.delivery.cancel",
   conversationGoalRead: "assistant.conversation.goal.read",
   conversationGoalUpdate: "assistant.conversation.goal.update",
   conversationConfigure: "assistant.conversation.configure",

package/src/server/actions.js

@@ -225,6 +225,21 @@ function createConversationActions({ conversationRuntime, conversationDataSchema
         return conversation.inspectDelivery({ messageId: input.messageId });
       }
     },
+    {
+      id: actionIds.conversationCancelDelivery,
+      version: 1,
+      kind: "command",
+      channels: ["api", "internal"],
+      surfaces: runtimeSurfaces,
+      permission: { require: "authenticated" },
+      input: conversationInspectInputValidator,
+      output: null,
+      idempotency: "none",
+      async execute(input, context) {
+        const conversation = await openConversation(input, context);
+        return conversation.cancelDelivery({ messageId: input.messageId });
+      }
+    },
     {
       id: actionIds.conversationGoalRead,
       version: 1,

package/src/server/registerRoutes.js

@@ -385,6 +385,25 @@ function registerConversationRoutes(
     reply.code(200).send(response);
   });
 
+  router.register("POST", `${routeBase}/deliveries/:messageId/cancel`, {
+    auth: "required", visibility,
+    params: composeSchemaDefinitions([params, assistantConversationMessageIdInputValidator], {
+      mode: "patch", context: "assistant-runtime conversation delivery cancel route params"
+    }),
+    meta: { tags: ["assistant"], summary: "Cancel one unsent or unconfirmed assistant message." }
+  }, async function assistantConversationCancelDeliveryRoute(request, reply) {
+    const routeState = resolveRouteRequestState(request, {
+      resolveCurrentAppConfig, requiresWorkspace, workspaceScopeSupport
+    });
+    const response = await request.executeAction({
+      actionId: actionIds.conversationCancelDelivery,
+      surface: routeState.hostSurfaceId,
+      input: { ...routeState.actionInput, conversationId: request.input.params.conversationId,
+        messageId: request.input.params.messageId }
+    });
+    reply.code(200).send(response);
+  });
+
   for (const method of ["GET", "POST"]) {
     router.register(method, `${routeBase}/goal`, {
       auth: "required", visibility, params,