@jskit-ai/assistant-runtime 0.2.8 → 0.2.10

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 };

package/src/client/composables/conversationHistory.js

@@ -0,0 +1,215 @@
+import { computed, ref } from "vue";
+import {
+  conversationTurnMessages,
+  mergeConversationLogPages,
+  mergeConversationStream,
+  normalizeConversationLogPage,
+  normalizeConversationLogPagination
+} from "@jskit-ai/assistant-core/shared/conversation";
+import { failureMessage, isAccessDenied } from "../support/conversationFailures.js";
+import { patchLoadedHistoryPages, refreshedHistoryPages } from "../support/subscribeAssistantConversation.js";
+import { useJskitText } from "../i18n.js";
+
+const { t } = useJskitText();
+const compareTurnIds = (left, right) => String(left).localeCompare(String(right), undefined, { numeric: true });
+
+/** A Load older request whose view does not follow the result. */
+function ignoreLoadResult() {}
+
+/**
+ * The saved history a conversation's views have loaded: the live page from its subscription plus the older pages a
+ * reader asked for, kept apart so a canonical read can refresh both.
+ * @param {{
+ *   api: import("@jskit-ai/assistant-core/client/types").AssistantApi,
+ *   identity: import("../types.js").ConversationIdentity,
+ *   snapshot: import("vue").ShallowRef<any>,
+ *   current: import("vue").ComputedRef<boolean>,
+ *   listening: import("vue").ComputedRef<boolean>,
+ *   available: import("vue").ComputedRef<boolean>,
+ *   receiveError: (failure: any) => void
+ * }} conversation
+ */
+function createConversationHistory({ api, identity, snapshot, current, listening, available, receiveError }) {
+  const olderPages = ref([]);
+  let historyRevision = 0;
+  let deniedHistoryRevision = 0;
+  const loadingMore = ref(false);
+  const loadMoreError = ref("");
+  const turns = computed(() => {
+    const saved = mergeConversationLogPages([
+      ...olderPages.value, { conversationLog: snapshot.value?.conversationLog || [] }
+    ]).conversationLog;
+    // Use the original overlay against the full loaded saved span. A synthetic
+    // live older turn must not replace its authored request or saved progress.
+    const messages = (snapshot.value?.turns || []).flatMap(conversationTurnMessages);
+    return mergeConversationStream(saved, { messages });
+  });
+  const oldestLoadedPage = computed(() => olderPages.value[0] || snapshot.value);
+  const hasMoreBefore = computed(() => normalizeConversationLogPagination(oldestLoadedPage.value?.pagination).hasMoreBefore);
+
+  /**
+   * Takes the older pages a new state brings, before the live page is replaced by it.
+   * @param {any} state
+   * @param {any} previous The live page the state replaces.
+   * @param {{ initial: boolean, canonical: boolean }} options
+   */
+  function receiveState(state, previous, { initial, canonical }) {
+    if (canonical) {
+      historyRevision += 1;
+      olderPages.value = initial ? [] : state[refreshedHistoryPages] || [];
+      loadMoreError.value = "";
+    } else if (olderPages.value.length) {
+      // Transcript patches may evict the head of the bounded live page before
+      // its canonical read completes. Retain saved rows, never display overlays.
+      const first = state.conversationLog?.[0]?.turnId;
+      const evicted = first ? (previous?.conversationLog || []).filter(turn => compareTurnIds(turn.turnId, first) < 0) : [];
+      if (evicted.length) {
+        historyRevision += 1;
+        olderPages.value = [...olderPages.value, normalizeConversationLogPage({ conversationLog: evicted })];
+      }
+    }
+  }
+  /**
+   * Applies a transcript event to the older page that holds its turn.
+   * @param {any} event
+   */
+  function receivePatch(event) {
+    if (event.type === "transcript" && olderPages.value.some(page =>
+      page.conversationLog.some(turn => turn.turnId === event.patch?.turn?.turnId))) {
+      historyRevision += 1;
+      olderPages.value = patchLoadedHistoryPages(olderPages.value, event.patch);
+    }
+  }
+  /** Drops the older pages, as when the view is cleared. */
+  function clear() {
+    historyRevision += 1;
+    olderPages.value = [];
+  }
+  /** Makes a read in flight stale, as when the subscription restarts. */
+  function invalidate() {
+    historyRevision += 1;
+  }
+  /** Makes a read in flight fail as denied, after the viewer lost access. */
+  function deny() {
+    deniedHistoryRevision += 1;
+  }
+
+  /**
+   * Rereads the live page and every older page already loaded, for the subscription's canonical read.
+   * @param {{ current: () => boolean }} read Whether the subscription still wants this read.
+   */
+  async function readLoadedHistory({ current: subscriptionCurrent }) {
+    const denial = deniedHistoryRevision;
+    const valid = () => {
+      if (denial !== deniedHistoryRevision) {
+        throw Object.assign(new Error("Access denied."), { status: 403, messageCode: "assistant.runtime.accessDenied" });
+      }
+      return current.value && listening.value && subscriptionCurrent();
+    };
+    // A concurrent Load older operation extends the desired span. Retry one
+    // refresh in this same read, rather than dropping that newly loaded page.
+    while (valid()) {
+      const revision = historyRevision;
+      const oldestTurn = olderPages.value[0]?.conversationLog?.[0];
+      const oldest = oldestTurn?.turnId;
+      const oldestCursor = olderPages.value[0]?.pagination?.nextBeforeTurnId || oldest;
+      const latest = await api.readConversation(identity.conversationId);
+      if (!valid()) return latest;
+      const pages = [];
+      let page = normalizeConversationLogPage(latest);
+      const cursors = new Set();
+      while (oldest && page.pagination.hasMoreBefore) {
+        const cursor = page.pagination.nextBeforeTurnId || page.pagination.oldestTurnId;
+        const reachedFullOldestTurn = page.pagination.oldestTurnId === oldest && !page.conversationLog[0]?.paginationPartial;
+        const passedOldestTurn = compareTurnIds(page.pagination.oldestTurnId, oldest) < 0;
+        if (cursor && (cursor === oldestCursor || passedOldestTurn || reachedFullOldestTurn)) break;
+        if (!cursor || cursors.has(cursor)) {
+          throw Object.assign(new Error("Older conversation history could not be refreshed. Reload chat to try again."), {
+            messageCode: "assistant.runtime.history.refreshFailed"
+          });
+        }
+        cursors.add(cursor);
+        page = normalizeConversationLogPage(await api.readConversation(identity.conversationId, {
+          beforeTurnId: cursor, limit: latest.pagination.limit
+        }));
+        if (!valid()) return latest;
+        // A removed oldest row can make this page reach farther back than the
+        // reader loaded. Keep the original visible boundary and page metadata.
+        const saved = page.conversationLog.filter(turn => compareTurnIds(turn.turnId, oldest) >= 0).map(turn => {
+          if (turn.turnId !== oldest || !oldestTurn.paginationPartial) return turn;
+          const roles = ["system", "user", "assistant"];
+          const excluded = roles.slice(0, roles.findIndex(role => oldestTurn[role]));
+          return { ...turn, paginationPartial: true,
+            ...Object.fromEntries(excluded.map(role => [role, null])),
+            messages: turn.messages?.filter(message => !excluded.includes(message.role)) };
+        });
+        pages.unshift(normalizeConversationLogPage({ ...page, conversationLog: saved, pagination: {
+          ...page.pagination, count: saved.length, oldestTurnId: saved[0]?.turnId || "",
+          hasMoreBefore: page.pagination.hasMoreBefore || saved.length < page.conversationLog.length
+        } }));
+      }
+      if (revision !== historyRevision) continue;
+      return { ...latest, [refreshedHistoryPages]: pages.filter(page => page.conversationLog.length) };
+    }
+    return null;
+  }
+
+  /**
+   * Loads the page before the oldest loaded turn, kept separate from the live page.
+   * @param {{ complete?: (result: { changed: boolean, loaded: boolean }) => void }} [options]
+   */
+  async function loadMore({ complete = ignoreLoadResult } = {}) {
+    const pagination = normalizeConversationLogPagination(oldestLoadedPage.value?.pagination);
+    const beforeTurnId = pagination.nextBeforeTurnId || pagination.oldestTurnId ||
+      String(turns.value[0]?.turnId || "").trim();
+    if (!available.value || !hasMoreBefore.value || loadingMore.value || !beforeTurnId) {
+      complete({ changed: false, loaded: false });
+      return false;
+    }
+    const revision = historyRevision;
+    loadingMore.value = true;
+    loadMoreError.value = "";
+    try {
+      const page = await api.readConversation(identity.conversationId, {
+        beforeTurnId, limit: snapshot.value.pagination.limit
+      });
+      if (!available.value || revision !== historyRevision) {
+        complete({ changed: false, loaded: false });
+        return false;
+      }
+      const previousOldestTurnId = String(turns.value[0]?.turnId || "").trim();
+      const previousMessageCount = turns.value.reduce((count, turn) => count + (turn.messages?.length || 0), 0);
+      historyRevision += 1;
+      olderPages.value = [normalizeConversationLogPage(page), ...olderPages.value];
+      const nextOldestTurnId = String(turns.value[0]?.turnId || "").trim();
+      const nextMessageCount = turns.value.reduce((count, turn) => count + (turn.messages?.length || 0), 0);
+      const changed = Boolean(nextOldestTurnId && (nextOldestTurnId !== previousOldestTurnId ||
+        nextMessageCount !== previousMessageCount));
+      complete({ changed, loaded: true });
+      return true;
+    } catch (failure) {
+      if (current.value) {
+        loadMoreError.value = String(failureMessage(failure) || failure || t("jskit.assistant.runtime.history.loadFailed"));
+        if (isAccessDenied(failure)) receiveError(failure);
+      }
+      complete({ changed: false, loaded: false });
+      return false;
+    } finally { loadingMore.value = false; }
+  }
+
+  return {
+    turns,
+    hasMoreBefore,
+    loadingMore,
+    loadMoreError,
+    receiveState,
+    receivePatch,
+    clear,
+    invalidate,
+    deny,
+    readLoadedHistory,
+    loadMore
+  };
+}
+
+export { createConversationHistory };