@jskit-ai/assistant-runtime 0.1.144 → 0.1.145

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant-runtime",
-  "version": "0.1.144",
+  "version": "0.1.145",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -11,15 +11,15 @@
     "./server/actionIds": "./src/server/actionIds.js"
   },
   "dependencies": {
-    "@jskit-ai/assistant-core": "0.1.149",
-    "@jskit-ai/database-runtime": "0.1.173",
+    "@jskit-ai/assistant-core": "0.1.150",
+    "@jskit-ai/database-runtime": "0.1.174",
     "json-rest-schema": "^1.0.17"
   },
   "peerDependencies": {
-    "@jskit-ai/http-runtime": "0.1.171",
-    "@jskit-ai/http-web": "0.1.18",
-    "@jskit-ai/kernel": "0.1.173",
-    "@jskit-ai/shell-web": "0.1.177",
+    "@jskit-ai/http-runtime": "0.1.172",
+    "@jskit-ai/http-web": "0.1.19",
+    "@jskit-ai/kernel": "0.1.174",
+    "@jskit-ai/shell-web": "0.1.178",
     "@tanstack/vue-query": "^5.90.5",
     "vue": "^3.5.13",
     "vuetify": "^4.0.0"

package/src/client/composables/useAssistantRuntime.js

@@ -29,13 +29,15 @@ import {
   normalizeToolName
 } from "../support/assistantRuntimeState.js";
 import { insertTextAtSelection } from "../support/composerInputSupport.js";
+import {
+  loadConversationTranscript,
+  resolveConversationRestorePolicy
+} from "../support/conversationRestoreSupport.js";
 import { useWorkspaceWebScopeSupport } from "../support/workspaceScopeSupport.js";
 
 const DEFAULT_STREAM_TIMEOUT_MS = 120_000;
 const DEFAULT_HISTORY_PAGE_SIZE = 20;
-const DEFAULT_MESSAGES_PAGE_SIZE = 200;
 const DEFAULT_HISTORY_STALE_TIME_MS = 60_000;
-const RESTORE_MESSAGES_PAGE = 1;
 
 function toNonNegativeInteger(value, fallback = 0) {
   const parsed = Number(value);
@@ -106,11 +108,16 @@ function formatConversationStartedAt(value) {
 function resolveRuntimePolicy() {
   const appConfig = getClientAppConfig();
   const assistantConfig = normalizeObject(appConfig?.assistant);
+  const conversationRestorePolicy = resolveConversationRestorePolicy({
+    pageSize: assistantConfig.restoreMessagesPageSize,
+    maxEntries: assistantConfig.restoreMessagesMaxEntries
+  });
 
   return Object.freeze({
     timeoutMs: toPositiveInteger(assistantConfig.timeoutMs, DEFAULT_STREAM_TIMEOUT_MS),
     historyPageSize: toPositiveInteger(assistantConfig.historyPageSize, DEFAULT_HISTORY_PAGE_SIZE),
-    restoreMessagesPageSize: toPositiveInteger(assistantConfig.restoreMessagesPageSize, DEFAULT_MESSAGES_PAGE_SIZE),
+    restoreMessagesPageSize: conversationRestorePolicy.pageSize,
+    restoreMessagesMaxEntries: conversationRestorePolicy.maxEntries,
     historyStaleTimeMs: toNonNegativeInteger(assistantConfig.historyStaleTimeMs, DEFAULT_HISTORY_STALE_TIME_MS)
   });
 }
@@ -370,19 +377,23 @@ function useAssistantRuntime({ api = null, surfaceId = "" } = {}) {
     setRuntimeError("");
 
     try {
-      const response = await queryClient.fetchQuery({
-        queryKey: assistantConversationMessagesQueryKey(runtimeScope.value, parsedConversationId, {
-          page: RESTORE_MESSAGES_PAGE,
-          pageSize: runtimePolicy.restoreMessagesPageSize
-        }),
-        queryFn: () =>
-          runtimeApi.getConversationMessages(parsedConversationId, {
-            page: RESTORE_MESSAGES_PAGE,
-            pageSize: runtimePolicy.restoreMessagesPageSize
-          })
+      const transcript = await loadConversationTranscript({
+        pageSize: runtimePolicy.restoreMessagesPageSize,
+        maxEntries: runtimePolicy.restoreMessagesMaxEntries,
+        fetchPage: (page, pageSize) => queryClient.fetchQuery({
+          queryKey: assistantConversationMessagesQueryKey(runtimeScope.value, parsedConversationId, {
+            page,
+            pageSize
+          }),
+          queryFn: () => runtimeApi.getConversationMessages(parsedConversationId, {
+            page,
+            pageSize
+          }),
+          staleTime: runtimePolicy.historyStaleTimeMs
+        })
       });
 
-      const restored = mapTranscriptEntriesToAssistantState(response?.entries);
+      const restored = mapTranscriptEntriesToAssistantState(transcript.entries);
       messages.value = restored.messages;
       pendingToolEvents.value = restored.pendingToolEvents;
       input.value = "";

package/src/client/support/conversationRestoreSupport.js

@@ -0,0 +1,75 @@
+import { MAX_MESSAGE_PAGE_SIZE } from "@jskit-ai/assistant-core/shared";
+
+const DEFAULT_RESTORE_MESSAGES_PAGE_SIZE = 200;
+const DEFAULT_RESTORE_MESSAGES_MAX_ENTRIES = 2000;
+const MAX_RESTORE_MESSAGES_MAX_ENTRIES = 5000;
+
+function normalizeBoundedPositiveInteger(value, fallback, maximum) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    return fallback;
+  }
+
+  return Math.min(parsed, maximum);
+}
+
+function normalizeTotalPages(value) {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : 1;
+}
+
+function resolveConversationRestorePolicy({ pageSize, maxEntries } = {}) {
+  return Object.freeze({
+    pageSize: normalizeBoundedPositiveInteger(
+      pageSize,
+      DEFAULT_RESTORE_MESSAGES_PAGE_SIZE,
+      MAX_MESSAGE_PAGE_SIZE
+    ),
+    maxEntries: normalizeBoundedPositiveInteger(
+      maxEntries,
+      DEFAULT_RESTORE_MESSAGES_MAX_ENTRIES,
+      MAX_RESTORE_MESSAGES_MAX_ENTRIES
+    )
+  });
+}
+
+async function loadConversationTranscript({
+  fetchPage,
+  pageSize = DEFAULT_RESTORE_MESSAGES_PAGE_SIZE,
+  maxEntries = DEFAULT_RESTORE_MESSAGES_MAX_ENTRIES
+} = {}) {
+  if (typeof fetchPage !== "function") {
+    throw new TypeError("loadConversationTranscript requires fetchPage().");
+  }
+
+  const restorePolicy = resolveConversationRestorePolicy({ pageSize, maxEntries });
+  const normalizedPageSize = restorePolicy.pageSize;
+  const normalizedMaxEntries = restorePolicy.maxEntries;
+  const firstResponse = await fetchPage(1, normalizedPageSize);
+  const totalPages = normalizeTotalPages(firstResponse?.totalPages);
+  const restoredPageCount = Math.max(1, Math.ceil(normalizedMaxEntries / normalizedPageSize));
+  const firstRestoredPage = Math.max(1, totalPages - restoredPageCount + 1);
+  const entries = firstRestoredPage === 1 && Array.isArray(firstResponse?.entries)
+    ? [...firstResponse.entries]
+    : [];
+
+  for (let page = Math.max(2, firstRestoredPage); page <= totalPages; page += 1) {
+    const response = await fetchPage(page, normalizedPageSize);
+    if (Array.isArray(response?.entries)) {
+      entries.push(...response.entries);
+    }
+  }
+
+  return Object.freeze({
+    entries: Object.freeze(entries.slice(-normalizedMaxEntries)),
+    firstRestoredPage,
+    pageSize: normalizedPageSize,
+    totalPages,
+    truncated: firstRestoredPage > 1
+  });
+}
+
+export {
+  loadConversationTranscript,
+  resolveConversationRestorePolicy
+};

package/src/server/services/chatService.js

@@ -12,6 +12,7 @@ const MAX_INPUT_CHARS = 8000;
 const MAX_TOOL_ROUNDS = 16;
 const MAX_RECOVERY_PASSES = 3;
 const MAX_TOOL_RESULT_FALLBACK_CHARS = 4000;
+const CURRENT_TIME_PREFLIGHT_INTENT = "current-time";
 const CLOCK_INSTRUCTION = "For current or relative date and time questions, first use any available authoritative workspace clock action; never infer the current date or time from model knowledge.";
 const COMPLETION_INSTRUCTION = "Do not narrate future work or describe what you are about to do. Either call the required available tool now or provide the completed final answer.";
 
@@ -95,6 +96,36 @@ function isAbortError(error) {
   return String(error.name || "").trim() === "AbortError";
 }
 
+function requiresCurrentTime(value = "") {
+  const text = normalizeText(value);
+  if (!text) {
+    return false;
+  }
+
+  return [
+    /\b(?:now|today|tomorrow|yesterday|tonight)\b/iu,
+    /\b(?:current|local)\s+(?:date|day|time|date\s+and\s+time)\b/iu,
+    /\bwhat(?:'s|\s+is)\s+(?:the\s+)?(?:date|day|time)\b/iu,
+    /\b(?:this|next|last)\s+(?:day|week|month|year|monday|tuesday|wednesday|thursday|friday|saturday|sunday)\b/iu
+  ].some((pattern) => pattern.test(text));
+}
+
+function resolvePreflightTools(toolDescriptors = [], input = "") {
+  if (!requiresCurrentTime(input)) {
+    return [];
+  }
+
+  const currentTimeTool = toolDescriptors.find((tool) => {
+    const intents = Array.isArray(tool?.preflight) ? tool.preflight : [];
+    const requiredParameters = Array.isArray(tool?.parameters?.required)
+      ? tool.parameters.required
+      : [];
+    return requiredParameters.length < 1 && intents.includes(CURRENT_TIME_PREFLIGHT_INTENT);
+  });
+
+  return currentTimeTool ? [currentTimeTool] : [];
+}
+
 function extractTextDelta(deltaContent) {
   if (typeof deltaContent === "string") {
     return deltaContent;
@@ -195,7 +226,11 @@ function buildRecoveryPrompt({ reason = "", toolFailures = [], toolSuccesses = [
   return `Tool-call rounds were exhausted. Provide the best direct answer with available context and successful results only. ${COMPLETION_INSTRUCTION}${failureSuffix}${successSuffix}`;
 }
 
-function buildRecoveryFallbackAnswer({ toolFailures = [], toolSuccesses = [] } = {}) {
+function buildRecoveryFallbackAnswer({ reason = "", toolFailures = [], toolSuccesses = [] } = {}) {
+  if (normalizeText(reason).toLowerCase() === "max_tool_rounds") {
+    return "Limit reached. Start a new conversation.";
+  }
+
   return buildToolOutcomeFallbackAnswer({
     toolFailures,
     toolSuccesses
@@ -743,6 +778,26 @@ function createChatService({
       const toolFailures = [];
       const toolSuccesses = [];
 
+      const preflightTools = resolvePreflightTools(toolSet.tools, source.input);
+      for (const [index, tool] of preflightTools.entries()) {
+        const toolCall = {
+          id: `assistant_preflight_${index + 1}`,
+          name: tool.name,
+          arguments: "{}"
+        };
+        messages.push(buildAssistantToolCallMessage([toolCall]));
+        const preflightFailures = await executeToolCalls([toolCall], {
+          toolFailures,
+          toolSuccesses
+        });
+        for (const failure of preflightFailures) {
+          const toolName = normalizeText(failure?.name);
+          if (toolName) {
+            excludedToolNames.add(toolName);
+          }
+        }
+      }
+
       for (let round = 0; round < MAX_TOOL_ROUNDS; round += 1) {
         const roundToolDescriptors = toolSet.tools.filter(
           (tool) => !excludedToolNames.has(normalizeText(tool.name))

package/test/chatServiceLifecycle.test.js

@@ -69,22 +69,24 @@ async function* completionStream(completion = {}) {
   }
 }
 
-function createHarness(completions, { executeToolCall = null } = {}) {
+function createHarness(completions, { executeToolCall = null, tools: configuredTools = null } = {}) {
   const pendingCompletions = [...completions];
   const completionRequests = [];
   const transcriptMessages = [];
   const completedConversations = [];
   const executedTools = [];
   const streamEvents = [];
-  const tools = ["action_search", "action_contract", "action_execute"].map((name) => ({
-    name,
-    parameters: {
-      type: "object"
-    },
-    outputSchema: {
-      type: "object"
-    }
-  }));
+  const tools = Array.isArray(configuredTools)
+    ? configuredTools
+    : ["action_search", "action_contract", "action_execute"].map((name) => ({
+        name,
+        parameters: {
+          type: "object"
+        },
+        outputSchema: {
+          type: "object"
+        }
+      }));
 
   const chatService = createChatService({
     aiClientFactory: {
@@ -206,14 +208,44 @@ function assistantMessages(events) {
 }
 
 test("progress-only output is retried silently and current-time prompts require a workspace clock", async () => {
-  const harness = createHarness([
-    textCompletion("Let me query the current time."),
-    textCompletion("<think>This must remain private.</think>\nIt is Tuesday in the workspace timezone.")
-  ]);
+  const harness = createHarness(
+    [
+      textCompletion("Let me query the current time."),
+      textCompletion("<think>This must remain private.</think>\nIt is Tuesday in the workspace timezone.")
+    ],
+    {
+      tools: [{
+        name: "workspace_clock",
+        parameters: {
+          type: "object",
+          additionalProperties: false,
+          properties: {}
+        },
+        outputSchema: { type: "object" },
+        preflight: ["current-time"]
+      }],
+      executeToolCall() {
+        return {
+          ok: true,
+          result: {
+            localDateTime: "2026-08-25T11:15:00+08:00",
+            timeZone: "Australia/Perth"
+          }
+        };
+      }
+    }
+  );
 
   const result = await harness.run("What day is it today?");
 
   assert.equal(result.status, "completed");
+  assert.deepEqual(harness.executedTools.map((request) => request.toolName), ["workspace_clock"]);
+  assert.equal(
+    harness.completionRequests[0].messages.some((message) => (
+      message.role === "tool" && /Australia\/Perth/u.test(message.content)
+    )),
+    true
+  );
   assert.deepEqual(assistantMessages(harness.streamEvents), ["It is Tuesday in the workspace timezone."]);
   assert.equal(harness.streamEvents.some((event) => event.method === "sendAssistantDelta"), false);
   assert.match(
@@ -236,6 +268,50 @@ test("progress-only output is retried silently and current-time prompts require
   );
 });
 
+test("current-time preflight does not run for unrelated prompts", async () => {
+  const harness = createHarness(
+    [textCompletion("There are three active bookings.")],
+    {
+      tools: [{
+        name: "workspace_clock",
+        parameters: { type: "object", properties: {} },
+        outputSchema: { type: "object" },
+        preflight: ["current-time"]
+      }]
+    }
+  );
+
+  await harness.run("How many active bookings are there?");
+
+  assert.deepEqual(harness.executedTools, []);
+  assert.deepEqual(assistantMessages(harness.streamEvents), ["There are three active bookings."]);
+});
+
+test("current-time preflight does not invent required tool input", async () => {
+  const harness = createHarness(
+    [textCompletion("Choose a timezone before asking for its local time.")],
+    {
+      tools: [{
+        name: "timezone_clock",
+        parameters: {
+          type: "object",
+          required: ["timeZone"],
+          properties: {
+            timeZone: { type: "string" }
+          }
+        },
+        outputSchema: { type: "object" },
+        preflight: ["current-time"]
+      }]
+    }
+  );
+
+  await harness.run("What time is it now?");
+
+  assert.deepEqual(harness.executedTools, []);
+  assert.deepEqual(assistantMessages(harness.streamEvents), ["Choose a timezone before asking for its local time."]);
+});
+
 test("native search, contract, and execution workflows can exceed four silent tool rounds", async () => {
   const harness = createHarness([
     toolCompletion("action_search", 1, { text: "I'll search first." }),
@@ -261,7 +337,7 @@ test("native search, contract, and execution workflows can exceed four silent to
   assert.equal(assistantToolMessages.every((message) => message.content === ""), true);
 });
 
-test("tool-loop exhaustion returns the latest successful result with a hard output cap", async () => {
+test("tool-loop exhaustion gives the concise new-conversation instruction", async () => {
   const mainRounds = Array.from({ length: 16 }, (_, index) =>
     toolCompletion("action_execute", index + 1)
   );
@@ -290,11 +366,50 @@ test("tool-loop exhaustion returns the latest successful result with a hard outp
   const finalMessages = assistantMessages(harness.streamEvents);
   assert.equal(harness.executedTools.length, 16);
   assert.equal(harness.completionRequests.length, 19);
-  assert.equal(finalMessages.length, 1);
-  assert.ok(finalMessages[0].length <= 4000);
-  assert.match(finalMessages[0], /Latest successful result from action_execute/u);
-  assert.match(finalMessages[0], /"sequence": 16/u);
-  assert.match(finalMessages[0], /…\[truncated\]$/u);
-  assert.doesNotMatch(finalMessages[0], /Please narrow the request/u);
+  assert.deepEqual(finalMessages, ["Limit reached. Start a new conversation."]);
   assert.equal(harness.streamEvents.some((event) => event.method === "sendAssistantDelta"), false);
 });
+
+test("tool-failure recovery retains the bounded latest successful result", async () => {
+  const mainRounds = Array.from({ length: 16 }, (_, index) =>
+    toolCompletion(index === 1 ? "action_search" : "action_execute", index + 1)
+  );
+  const harness = createHarness(
+    [
+      ...mainRounds,
+      textCompletion("Let me prepare the answer."),
+      textCompletion("I'll summarize the result."),
+      textCompletion("Checking the final output.")
+    ],
+    {
+      executeToolCall(request, sequence) {
+        if (request.toolName === "action_search") {
+          return {
+            ok: false,
+            error: {
+              code: "assistant_tool_failed",
+              message: "Tool call failed."
+            }
+          };
+        }
+        return {
+          ok: true,
+          result: {
+            sequence,
+            payload: sequence === 16 ? "x".repeat(10_000) : "ok"
+          }
+        };
+      }
+    }
+  );
+
+  await harness.run();
+
+  const [fallback] = assistantMessages(harness.streamEvents);
+  assert.equal(harness.executedTools.length, 16);
+  assert.ok(fallback.length <= 4000);
+  assert.match(fallback, /Latest successful result from action_execute/u);
+  assert.match(fallback, /"sequence": 16/u);
+  assert.match(fallback, /…\[truncated\]$/u);
+  assert.doesNotMatch(fallback, /Limit reached/u);
+});

package/test/conversationRestoreSupport.test.js

@@ -0,0 +1,110 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { QueryClient } from "@tanstack/vue-query";
+
+import { assistantConversationMessagesQueryKey } from "@jskit-ai/assistant-core/shared";
+import {
+  loadConversationTranscript,
+  resolveConversationRestorePolicy
+} from "../src/client/support/conversationRestoreSupport.js";
+
+test("conversation restore includes completed replies beyond the first transcript page", async () => {
+  const requests = [];
+  const pages = new Map([
+    [1, {
+      total: 201,
+      totalPages: 2,
+      entries: [
+        { id: "199", role: "assistant", kind: "tool_result" },
+        { id: "200", role: "user", kind: "chat", contentText: "What is happening today?" }
+      ]
+    }],
+    [2, {
+      total: 201,
+      totalPages: 2,
+      entries: [
+        { id: "201", role: "assistant", kind: "chat", contentText: "There are 17 bookings today." }
+      ]
+    }]
+  ]);
+
+  const transcript = await loadConversationTranscript({
+    async fetchPage(page, pageSize) {
+      requests.push({ page, pageSize });
+      return pages.get(page);
+    }
+  });
+
+  assert.deepEqual(requests, [
+    { page: 1, pageSize: 200 },
+    { page: 2, pageSize: 200 }
+  ]);
+  assert.deepEqual(transcript.entries.map((entry) => entry.id), ["199", "200", "201"]);
+  assert.equal(transcript.entries.at(-1).contentText, "There are 17 bookings today.");
+  assert.equal(transcript.truncated, false);
+});
+
+test("conversation restore keeps the newest bounded transcript pages", async () => {
+  const requests = [];
+  const pages = new Map([
+    [1, { total: 12, totalPages: 6, entries: [{ id: "1" }, { id: "2" }] }],
+    [5, { total: 12, totalPages: 6, entries: [{ id: "9" }, { id: "10" }] }],
+    [6, { total: 12, totalPages: 6, entries: [{ id: "11" }, { id: "12" }] }]
+  ]);
+
+  const transcript = await loadConversationTranscript({
+    pageSize: 2,
+    maxEntries: 4,
+    async fetchPage(page) {
+      requests.push(page);
+      return pages.get(page);
+    }
+  });
+
+  assert.deepEqual(requests, [1, 5, 6]);
+  assert.deepEqual(transcript.entries.map((entry) => entry.id), ["9", "10", "11", "12"]);
+  assert.equal(transcript.firstRestoredPage, 5);
+  assert.equal(transcript.truncated, true);
+});
+
+test("conversation restore reuses every cached transcript page after remount", async () => {
+  const backendRequests = [];
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false,
+        staleTime: 60_000
+      }
+    }
+  });
+  const scope = { targetSurfaceId: "admin", workspaceId: "7" };
+  const pages = new Map([
+    [1, { total: 201, totalPages: 2, entries: [{ id: "200" }] }],
+    [2, { total: 201, totalPages: 2, entries: [{ id: "201" }] }]
+  ]);
+  const fetchPage = (page, pageSize) => queryClient.fetchQuery({
+    queryKey: assistantConversationMessagesQueryKey(scope, "41", { page, pageSize }),
+    queryFn: async () => {
+      backendRequests.push(page);
+      return pages.get(page);
+    },
+    staleTime: 60_000
+  });
+
+  const firstRestore = await loadConversationTranscript({ fetchPage });
+  const warmRestore = await loadConversationTranscript({ fetchPage });
+
+  assert.deepEqual(firstRestore.entries.map((entry) => entry.id), ["200", "201"]);
+  assert.deepEqual(warmRestore.entries.map((entry) => entry.id), ["200", "201"]);
+  assert.deepEqual(backendRequests, [1, 2]);
+});
+
+test("conversation restore policy caps page and transcript sizes", () => {
+  assert.deepEqual(resolveConversationRestorePolicy({
+    pageSize: 100_000,
+    maxEntries: 100_000
+  }), {
+    pageSize: 500,
+    maxEntries: 5000
+  });
+});