@jskit-ai/assistant-core 0.2.6 → 0.2.8

package/src/client/lib/assistantApi.js

@@ -1,4 +1,5 @@
 import { appendQueryString } from "@jskit-ai/kernel/shared/support";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
 import { encodeJsonApiResourceQueryObject } from "@jskit-ai/http-runtime/shared";
 import {
   ASSISTANT_CONVERSATIONS_TRANSPORT,
@@ -9,8 +10,6 @@ import {
   normalizeAssistantStreamEventType
 } from "../../shared/index.js";
 
-const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
-
 // A stream error event keeps its code and English message, plus the params and
 // messageCode useJskitText().serverMessage(error) needs to show it in the active language.
 function buildStreamEventError(event) {
@@ -60,8 +59,8 @@ function normalizeSurfaceHeaderValue(value) {
   return String(value || "").trim().toLowerCase();
 }
 
-function resolveAssistantRequestHeaders(resolveSurfaceId) {
-  if (typeof resolveSurfaceId !== "function") {
+function resolveAssistantRequestHeaders(resolveSurfaceId, sendsSurface) {
+  if (!sendsSurface) {
     return null;
   }
 
@@ -88,183 +87,215 @@ function resolveRequiredBasePath(resolveBasePath) {
   return resolved;
 }
 
-function createAssistantApi({ request, requestStream, resolveBasePath, resolveSurfaceId = null } = {}) {
+/** Ignores a stream event when the caller passed no onEvent. */
+function ignoreStreamEvent() {}
+
+/**
+ * The assistant's HTTP API for one application: its conversations, their messages and goals, its chat stream and its
+ * settings, all under the base path `resolveBasePath()` returns.
+ * @param {{
+ *   request: (url: string, options: object) => Promise<any>,
+ *   requestStream?: (url: string, options: object, handlers: object) => Promise<void>,
+ *   resolveBasePath: () => string,
+ *   resolveSurfaceId?: (() => string) | null
+ * }} transport
+ */
+function createAssistantApi({ request, requestStream, resolveBasePath, resolveSurfaceId }) {
+  // readable-check: allow method-probe - input validation: an application builds its API with the request() it sends through
   if (typeof request !== "function") {
     throw new Error("createAssistantApi requires request().");
   }
+  // readable-check: allow method-probe - optional operation: an API built without requestStream has no chat stream, so streamChat() rejects
+  const streams = typeof requestStream === "function";
+  // readable-check: allow method-probe - optional operation: an API built without resolveSurfaceId sends no surface header
+  const sendsSurface = typeof resolveSurfaceId === "function";
 
   function requestConversation(conversationId, suffix, options) {
     const basePath = resolveRequiredBasePath(resolveBasePath);
     const encodedId = encodeURIComponent(String(conversationId || "").trim());
-    const headers = resolveAssistantRequestHeaders(resolveSurfaceId);
+    const headers = resolveAssistantRequestHeaders(resolveSurfaceId, sendsSurface);
     return request(`${basePath}/conversations/${encodedId}${suffix}`, {
       ...options,
       ...(headers ? { headers } : {})
     });
   }
 
-  return Object.freeze({
-    readConversation(conversationId, { signal, beforeTurnId, limit } = {}) {
-      const params = new URLSearchParams();
-      appendQueryParam(params, "beforeTurnId", beforeTurnId);
-      appendQueryParam(params, "limit", limit);
-      return requestConversation(conversationId, params.size ? `?${params}` : "", { method: "GET", signal });
-    },
-
-    sendConversationMessage(conversationId, payload, { signal } = {}) {
-      return requestConversation(conversationId, "/messages", {
-        method: "POST", signal,
-        body: {
-          messageId: payload.messageId,
-          text: payload.text,
-          ...(Object.hasOwn(payload, "data") ? { data: payload.data } : {}),
-          ...(Object.hasOwn(payload, "attachmentIds") ? { attachmentIds: payload.attachmentIds } : {}),
-          ...(Object.hasOwn(payload, "steer") ? { steer: payload.steer } : {})
-        }
-      });
-    },
-
-    cancelConversation(conversationId, { signal } = {}) {
-      return requestConversation(conversationId, "/cancel", { method: "POST", signal });
-    },
-
-    inspectConversationDelivery(conversationId, messageId, { signal } = {}) {
-      const encodedMessageId = encodeURIComponent(String(messageId || "").trim());
-      return requestConversation(conversationId, `/deliveries/${encodedMessageId}/inspect`, { method: "POST", signal });
-    },
-
-    cancelConversationDelivery(conversationId, messageId, { signal } = {}) {
-      const encodedMessageId = encodeURIComponent(String(messageId || "").trim());
-      return requestConversation(conversationId, `/deliveries/${encodedMessageId}/cancel`, { method: "POST", signal });
-    },
-
-    readConversationGoal(conversationId, { signal } = {}) {
-      return requestConversation(conversationId, "/goal", { method: "GET", signal });
-    },
-
-    updateConversationGoal(conversationId, payload, { signal } = {}) {
-      const body = {};
-      for (const key of ["action", "expectedSegmentId", "expectedGoalId", "messageId", "objective", "tokenBudget", "attachmentIds"]) {
-        if (Object.hasOwn(payload, key)) body[key] = payload[key];
+  function readConversation(conversationId, { signal, beforeTurnId, limit } = {}) {
+    const params = new URLSearchParams();
+    appendQueryParam(params, "beforeTurnId", beforeTurnId);
+    appendQueryParam(params, "limit", limit);
+    return requestConversation(conversationId, params.size ? `?${params}` : "", { method: "GET", signal });
+  }
+
+  function sendConversationMessage(conversationId, payload, { signal } = {}) {
+    return requestConversation(conversationId, "/messages", {
+      method: "POST", signal,
+      body: {
+        messageId: payload.messageId,
+        text: payload.text,
+        ...(Object.hasOwn(payload, "data") ? { data: payload.data } : {}),
+        ...(Object.hasOwn(payload, "attachmentIds") ? { attachmentIds: payload.attachmentIds } : {}),
+        ...(Object.hasOwn(payload, "steer") ? { steer: payload.steer } : {})
       }
-      return requestConversation(conversationId, "/goal", { method: "POST", signal, body });
-    },
-
-    configureConversation(conversationId, configuration, { signal } = {}) {
-      return requestConversation(conversationId, "/configuration", {
-        method: "PATCH", signal, body: { configuration }
-      });
-    },
-
-    selectConversation(conversationId, selection, { signal } = {}) {
-      return requestConversation(conversationId, "/selection", {
-        method: "POST", signal, body: { selection }
-      });
-    },
-
-    replaceConversation(conversationId, replacement, { signal } = {}) {
-      return requestConversation(conversationId, "/replacement", {
-        method: "POST", signal, body: { replacement }
-      });
-    },
-
-    async streamChat(payload, { signal, onEvent, onMalformedLine, rejectOnErrorEvent = true } = {}) {
-      if (typeof requestStream !== "function") throw new TypeError("streamChat requires requestStream().");
-      const basePath = resolveRequiredBasePath(resolveBasePath);
-      let streamEventError = null;
-      const requestHeaders = resolveAssistantRequestHeaders(resolveSurfaceId);
-
-      const streamHandlers = {
-        onEvent(event) {
-          const eventType = normalizeAssistantStreamEventType(event?.type, "");
-          if (rejectOnErrorEvent && eventType === ASSISTANT_STREAM_EVENT_TYPES.ERROR && !streamEventError) {
-            streamEventError = buildStreamEventError(event);
-          }
-
-          if (typeof onEvent === "function") {
-            onEvent(event);
-          }
+    });
+  }
+
+  function cancelConversation(conversationId, { signal } = {}) {
+    return requestConversation(conversationId, "/cancel", { method: "POST", signal });
+  }
+
+  function inspectConversationDelivery(conversationId, messageId, { signal } = {}) {
+    const encodedMessageId = encodeURIComponent(String(messageId || "").trim());
+    return requestConversation(conversationId, `/deliveries/${encodedMessageId}/inspect`, { method: "POST", signal });
+  }
+
+  function cancelConversationDelivery(conversationId, messageId, { signal } = {}) {
+    const encodedMessageId = encodeURIComponent(String(messageId || "").trim());
+    return requestConversation(conversationId, `/deliveries/${encodedMessageId}/cancel`, { method: "POST", signal });
+  }
+
+  function readConversationGoal(conversationId, { signal } = {}) {
+    return requestConversation(conversationId, "/goal", { method: "GET", signal });
+  }
+
+  function updateConversationGoal(conversationId, payload, { signal } = {}) {
+    const body = {};
+    for (const key of ["action", "expectedSegmentId", "expectedGoalId", "messageId", "objective", "tokenBudget", "attachmentIds"]) {
+      if (Object.hasOwn(payload, key)) body[key] = payload[key];
+    }
+    return requestConversation(conversationId, "/goal", { method: "POST", signal, body });
+  }
+
+  function configureConversation(conversationId, configuration, { signal } = {}) {
+    return requestConversation(conversationId, "/configuration", {
+      method: "PATCH", signal, body: { configuration }
+    });
+  }
+
+  function selectConversation(conversationId, selection, { signal } = {}) {
+    return requestConversation(conversationId, "/selection", {
+      method: "POST", signal, body: { selection }
+    });
+  }
+
+  function replaceConversation(conversationId, replacement, { signal } = {}) {
+    return requestConversation(conversationId, "/replacement", {
+      method: "POST", signal, body: { replacement }
+    });
+  }
+
+  async function streamChat(payload, { signal, onEvent = ignoreStreamEvent, onMalformedLine, rejectOnErrorEvent = true } = {}) {
+    if (!streams) throw new TypeError("streamChat requires requestStream().");
+    const basePath = resolveRequiredBasePath(resolveBasePath);
+    let streamEventError = null;
+    const requestHeaders = resolveAssistantRequestHeaders(resolveSurfaceId, sendsSurface);
+
+    const streamHandlers = {
+      onEvent(event) {
+        const eventType = normalizeAssistantStreamEventType(event?.type, "");
+        if (rejectOnErrorEvent && eventType === ASSISTANT_STREAM_EVENT_TYPES.ERROR && !streamEventError) {
+          streamEventError = buildStreamEventError(event);
         }
+
+        onEvent(event);
+      }
+    };
+
+    if (typeof onMalformedLine === "function") {
+      streamHandlers.onMalformedLine = (line, parseError) => {
+        onMalformedLine(line, parseError);
       };
+    }
+
+    await requestStream(
+      `${basePath}/chat/stream`,
+      {
+        method: "POST",
+        ...(requestHeaders ? { headers: requestHeaders } : {}),
+        body: payload,
+        signal
+      },
+      streamHandlers
+    );
+
+    if (streamEventError) {
+      throw streamEventError;
+    }
+  }
 
-      if (typeof onMalformedLine === "function") {
-        streamHandlers.onMalformedLine = (line, parseError) => {
-          onMalformedLine(line, parseError);
-        };
+  function listConversations(query = {}) {
+    const basePath = resolveRequiredBasePath(resolveBasePath);
+    const params = createAssistantQueryParams(query, ASSISTANT_CONVERSATIONS_TRANSPORT);
+    const requestHeaders = resolveAssistantRequestHeaders(resolveSurfaceId, sendsSurface);
+
+    return request(
+      appendQueryString(`${basePath}/conversations`, params.toString()),
+      {
+        ...(requestHeaders ? { headers: requestHeaders } : {}),
+        transport: ASSISTANT_CONVERSATIONS_TRANSPORT
       }
+    );
+  }
 
-      await requestStream(
-        `${basePath}/chat/stream`,
-        {
-          method: "POST",
-          ...(requestHeaders ? { headers: requestHeaders } : {}),
-          body: payload,
-          signal
-        },
-        streamHandlers
-      );
-
-      if (streamEventError) {
-        throw streamEventError;
+  function getConversationMessages(conversationId, query = {}) {
+    const basePath = resolveRequiredBasePath(resolveBasePath);
+    const encodedConversationId = encodeURIComponent(String(conversationId || "").trim());
+    const params = createAssistantQueryParams(query, ASSISTANT_CONVERSATION_MESSAGES_TRANSPORT);
+    const requestHeaders = resolveAssistantRequestHeaders(resolveSurfaceId, sendsSurface);
+
+    return request(
+      appendQueryString(`${basePath}/conversations/${encodedConversationId}/messages`, params.toString()),
+      {
+        ...(requestHeaders ? { headers: requestHeaders } : {}),
+        transport: ASSISTANT_CONVERSATION_MESSAGES_TRANSPORT
       }
-    },
-
-    listConversations(query = {}) {
-      const basePath = resolveRequiredBasePath(resolveBasePath);
-      const params = createAssistantQueryParams(query, ASSISTANT_CONVERSATIONS_TRANSPORT);
-      const requestHeaders = resolveAssistantRequestHeaders(resolveSurfaceId);
-
-      return request(
-        appendQueryString(`${basePath}/conversations`, params.toString()),
-        {
-          ...(requestHeaders ? { headers: requestHeaders } : {}),
-          transport: ASSISTANT_CONVERSATIONS_TRANSPORT
-        }
-      );
-    },
-
-    getConversationMessages(conversationId, query = {}) {
-      const basePath = resolveRequiredBasePath(resolveBasePath);
-      const encodedConversationId = encodeURIComponent(String(conversationId || "").trim());
-      const params = createAssistantQueryParams(query, ASSISTANT_CONVERSATION_MESSAGES_TRANSPORT);
-      const requestHeaders = resolveAssistantRequestHeaders(resolveSurfaceId);
-
-      return request(
-        appendQueryString(`${basePath}/conversations/${encodedConversationId}/messages`, params.toString()),
-        {
-          ...(requestHeaders ? { headers: requestHeaders } : {}),
-          transport: ASSISTANT_CONVERSATION_MESSAGES_TRANSPORT
-        }
-      );
-    },
-
-    getSettings() {
-      const basePath = resolveRequiredBasePath(resolveBasePath);
-      const requestHeaders = resolveAssistantRequestHeaders(resolveSurfaceId);
-
-      return request(
-        `${basePath}/settings`,
-        {
-          ...(requestHeaders ? { headers: requestHeaders } : {}),
-          transport: ASSISTANT_SETTINGS_TRANSPORT
-        }
-      );
-    },
-
-    updateSettings(payload = {}) {
-      const basePath = resolveRequiredBasePath(resolveBasePath);
-      const requestHeaders = resolveAssistantRequestHeaders(resolveSurfaceId);
-
-      return request(
-        `${basePath}/settings`,
-        {
-          method: "PATCH",
-          ...(requestHeaders ? { headers: requestHeaders } : {}),
-          body: payload,
-          transport: ASSISTANT_SETTINGS_UPDATE_TRANSPORT
-        }
-      );
-    }
+    );
+  }
+
+  function getSettings() {
+    const basePath = resolveRequiredBasePath(resolveBasePath);
+    const requestHeaders = resolveAssistantRequestHeaders(resolveSurfaceId, sendsSurface);
+
+    return request(
+      `${basePath}/settings`,
+      {
+        ...(requestHeaders ? { headers: requestHeaders } : {}),
+        transport: ASSISTANT_SETTINGS_TRANSPORT
+      }
+    );
+  }
+
+  function updateSettings(payload = {}) {
+    const basePath = resolveRequiredBasePath(resolveBasePath);
+    const requestHeaders = resolveAssistantRequestHeaders(resolveSurfaceId, sendsSurface);
+
+    return request(
+      `${basePath}/settings`,
+      {
+        method: "PATCH",
+        ...(requestHeaders ? { headers: requestHeaders } : {}),
+        body: payload,
+        transport: ASSISTANT_SETTINGS_UPDATE_TRANSPORT
+      }
+    );
+  }
+
+  return Object.freeze({
+    readConversation,
+    sendConversationMessage,
+    cancelConversation,
+    inspectConversationDelivery,
+    cancelConversationDelivery,
+    readConversationGoal,
+    updateConversationGoal,
+    configureConversation,
+    selectConversation,
+    replaceConversation,
+    streamChat,
+    listConversations,
+    getConversationMessages,
+    getSettings,
+    updateSettings
   });
 }
 

package/src/client/types.js

@@ -0,0 +1,110 @@
+// The values the assistant's client code hands out and receives across files: what its composables and factories
+// return, and the contracts an application implements to supply uploads, a goal and a whole conversation.
+
+/** @typedef {ReturnType<typeof import("./conversation/useAssistantAttachments.js").useAssistantAttachments>} AssistantAttachments */
+/** @typedef {ReturnType<typeof import("./conversation/useAssistantSuggestions.js").useAssistantSuggestions>} AssistantSuggestions */
+/** @typedef {ReturnType<typeof import("./conversation/useAssistantQuestions.js").useAssistantQuestions>} AssistantQuestions */
+/** @typedef {ReturnType<typeof import("./conversation/messageDelivery.js").createAssistantMessageDelivery>} AssistantMessageDelivery */
+/** @typedef {ReturnType<typeof import("./lib/assistantApi.js").createAssistantApi>} AssistantApi */
+
+/**
+ * What the application's storage returns for one uploaded file, completed by the queue with its client id, session
+ * and size.
+ * @typedef {object} AssistantAttachmentReceipt
+ * @property {string} attachmentId
+ * @property {string} clientId
+ * @property {string} fileName
+ * @property {string} sessionId
+ * @property {number} size
+ */
+
+/**
+ * Uploads one file for a session. It returns the stored file's receipt, as a promise, or as `{ promise }` with the
+ * `abort()` or `cancel()` that stops the upload.
+ * @typedef {(
+ *   sessionId: string,
+ *   file: File,
+ *   options: { onProgress: (progress: unknown, total?: number) => void, signal: AbortSignal }
+ * ) => unknown} AssistantAttachmentUpload
+ */
+
+/**
+ * Deletes an uploaded file no message will send. A response with `ok: false` reports a failed deletion.
+ * @typedef {(sessionId: string, attachmentId: string) => unknown} AssistantAttachmentDeletion
+ */
+
+/**
+ * The goal a conversation is working towards, as AssistantGoalControl shows and changes it.
+ * @typedef {object} AssistantGoalState
+ * @property {boolean} [enabled] False hides the control's menu and stops its clock.
+ * @property {boolean} [loading]
+ * @property {boolean} [available] False while the conversation offers no goals.
+ * @property {string} [action] "set" while a new goal is starting.
+ * @property {boolean} [working]
+ * @property {boolean} [pending]
+ * @property {boolean} [stopPending]
+ * @property {boolean} [pauseBlocked] True when a blocked goal can still be paused.
+ * @property {boolean} [pauseInterruptsTurn]
+ * @property {boolean} [cancelInterruptsTurn]
+ * @property {boolean} [tokenBudgetSupported]
+ * @property {string} [error]
+ * @property {{ status: string, objective?: string, elapsedSeconds?: number, sampledAt?: number, createdAt?: string } | null} [goal]
+ * @property {((input: { objective: string, tokenBudget?: number }) => unknown) | null} [set]
+ *   Starts a goal; absent while starting one is not allowed, so Start stays disabled.
+ * @property {() => unknown} [pause]
+ * @property {() => unknown} [resume]
+ * @property {() => unknown} [cancel]
+ */
+
+/**
+ * What an application supplies to AssistantConversationElement. Only `conversation` is required; each other part
+ * adds its controls when present.
+ * @typedef {object} AssistantConversationAdapter
+ * @property {Record<string, any> & { turns: any[] }} conversation The transcript's props, plus its preview messages
+ *   (`previewMessage`, `previewMessages`) and the reply still streaming (`interimReply`).
+ * @property {Record<string, any>} [composer] The prompt input's props, plus `draft`, `canSend`, `canStop`,
+ *   `stopPending`, `queueWhileSending` and the `payload` every message carries.
+ * @property {AssistantConversationActions} [actions]
+ * @property {AssistantMessageDelivery} [delivery] Present when the element sends and tracks messages itself.
+ * @property {import("vue").UnwrapNestedRefs<AssistantAttachments> & {
+ *   enabled?: boolean,
+ *   accept?: string,
+ *   open?: (attachment: unknown) => void
+ * }} [attachments]
+ * @property {import("vue").UnwrapNestedRefs<AssistantSuggestions>} [suggestions]
+ * @property {import("vue").UnwrapNestedRefs<AssistantQuestions>} [questions]
+ * @property {AssistantModelChoices} [models]
+ * @property {AssistantGoalState} [goal]
+ * @property {{ label: string }} [activity] Replaces the sending and working status line.
+ */
+
+/**
+ * What the application does for the conversation. The element sends, resends, edits and cancels through its
+ * delivery when the application supplies no action of its own; it leaves out the controls of the others.
+ * @typedef {object} AssistantConversationActions
+ * @property {(draft: string) => void} [setDraft]
+ * @property {(input: { configuration: object, attachments: object[] }) => unknown} [submit]
+ * @property {(messageId: string) => unknown} [resend]
+ * @property {(messageId: string) => unknown} [cancel]
+ * @property {(messageId: string) => unknown} [edit]
+ * @property {() => unknown} [stop]
+ * @property {(messageId: string) => unknown} [checkDelivery]
+ * @property {(request: { complete: (result?: { changed?: boolean }) => void }) => unknown} [loadMore]
+ * @property {() => unknown} [reload]
+ * @property {(link: unknown) => unknown} [openLink]
+ * @property {(configuration: object) => unknown} [updateConfiguration]
+ */
+
+/**
+ * The model menu's rows and choices: AssistantModelControl's props, and what applying or changing them does.
+ * @typedef {Record<string, any> & {
+ *   enabled?: boolean,
+ *   apply: () => unknown,
+ *   selectModel?: (modelId: string) => unknown,
+ *   selectProvider?: (providerId: string) => unknown,
+ *   selectVariant?: (variantId: string) => unknown,
+ *   reload?: () => unknown
+ * }} AssistantModelChoices
+ */
+
+export {};

package/src/server/conversation/attachments.js

@@ -1,11 +1,20 @@
+import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
 import path from "node:path";
 import { ASSISTANT_ATTACHMENT_ID_MAX_LENGTH, ASSISTANT_ATTACHMENT_MAX_ITEMS, conversationAttachmentManifest } from "../../shared/conversation/attachments.js";
 
 // messageCode names the sentence; the shared code stays for callers.
 function invalid(message, { messageCode, messageParams = {} }) {
-  return Object.assign(new Error(message), { code: "conversation_invalid_attachments", statusCode: 400, messageCode, messageParams });
+  return new AppError(400, message, { code: "conversation_invalid_attachments", messageCode, messageParams });
 }
 
+/** The attachments of an application that offers none: every file it is asked to resolve is refused. */
+export const NO_ATTACHMENTS = Object.freeze({
+  resolve() {
+    throw new AppError(400, "File attachments are not configured for this conversation.", { code: "conversation_attachments_not_configured",
+      messageCode: "assistant.conversation.attachmentsNotConfigured" });
+  }
+});
+
 export function conversationAttachmentIds(value = []) {
   if (!Array.isArray(value) || value.length > ASSISTANT_ATTACHMENT_MAX_ITEMS ||
       value.some(id => typeof id !== "string" || !id.trim() || id.length > ASSISTANT_ATTACHMENT_ID_MAX_LENGTH) ||
@@ -17,15 +26,21 @@ export function conversationAttachmentIds(value = []) {
   return [...value];
 }
 
-/** Resolve app-owned files for one dispatch. Only receipts enter the transcript. */
+/**
+ * Resolve app-owned files for one dispatch. Only receipts enter the transcript.
+ * @param {object} options
+ * @param {import("../types.js").ConversationAttachments} options.attachments The application's resolver, or NO_ATTACHMENTS.
+ * @param {object} options.context
+ * @param {string} options.conversationId
+ * @param {AbortSignal} options.signal
+ * @param {() => Promise<void>} options.authorize Rechecks admission before each resolver call.
+ * @param {readonly string[]} options.types The file types the engine accepts.
+ * @param {number} options.maximumBytes
+ */
 export function createConversationAttachmentReader({ attachments, context, conversationId, signal, authorize, types, maximumBytes }) {
   let bytes = 0;
   return async references => {
     if (!references?.length) return { attachments: [], content: [], localFiles: [], attachmentManifest: "" };
-    if (typeof attachments?.resolve !== "function") {
-      throw Object.assign(new Error("File attachments are not configured for this conversation."), { code: "conversation_unsupported", statusCode: 400,
-        messageCode: "assistant.conversation.attachmentsNotConfigured", messageParams: {} });
-    }
     const receipts = [];
     const content = [];
     const localFiles = [];

package/src/server/conversation/boundedToolLoop.js

@@ -109,6 +109,7 @@ async function runBoundedAssistantToolLoop({ prompt, signal, policy, complete, o
         if (decision !== "end") throw new TypeError("Invalid completed-response settlement decision.");
         return response.text;
       }
+      // readable-check: allow method-probe - input validation: an application's completed response carries its durable tools
       if (typeof result?.tools?.execute !== "function") {
         throw new TypeError("Completed application operations require the current durable tools.");
       }