@jskit-ai/assistant-core 0.1.165 → 0.1.167

package/src/shared/conversation/numberedQuestionSugar.js

@@ -0,0 +1,295 @@
+import { answerChoiceFromLine } from "./answerChoiceSugar.js";
+
+const UI_QUESTION_FIELD_PREFIX = "__ui_question_";
+
+function inactiveNumberedQuestionSugar() {
+  return {
+    intro: "",
+    outro: "",
+    questions: []
+  };
+}
+
+function isSingleTextareaMessageField(fields = [], fieldName = "response") {
+  return fields.length === 1 &&
+    fields[0]?.name === fieldName &&
+    fields[0]?.kind === "textarea";
+}
+
+function optionalValueMatches(actual = "", expected = "") {
+  return !expected || String(actual || "") === String(expected || "");
+}
+
+function canRenderNumberedQuestionSugar({
+  fields = [],
+  fieldName = "response",
+  intentId = "",
+  requiredIntentId = "",
+  requiredStepStatus = "",
+  stepStatus = ""
+} = {}) {
+  return Boolean(
+    isSingleTextareaMessageField(fields, fieldName) &&
+    optionalValueMatches(intentId, requiredIntentId) &&
+    optionalValueMatches(stepStatus, requiredStepStatus)
+  );
+}
+
+function numberedQuestionMarkerMatch(line = "") {
+  return String(line || "").match(/^\[(?:Q)?(\d+)\]\s+(.+)$/iu);
+}
+
+function trailingAnswerChoiceHeadingLine(line = "") {
+  return /^(possible answers|choices):$/iu.test(String(line || "").trim());
+}
+
+function trailingAnswerChoiceLine(line = "") {
+  return /^[-*]\s+.+/u.test(String(line || "").trim());
+}
+
+function numberedQuestionLabelLooksLikeQuestion(label = "") {
+  return /\?(?:[*_`”"'’)\]]*)(?:\s|$)/u.test(String(label || "").trim());
+}
+
+function validNumberedQuestions(questions = []) {
+  return questions.every((question) => (
+    question.choices.length > 0 || numberedQuestionLabelLooksLikeQuestion(question.label)
+  ));
+}
+
+function numberedQuestionChoice(line = "") {
+  const choice = answerChoiceFromLine(line);
+  if (!choice) {
+    return null;
+  }
+  const label = String(choice.label || "").trim();
+  const selectLabel = label.split(/(?:\s*[—–]\s*|\s+-\s+)/u, 1)[0].trim() || label;
+  return {
+    ...choice,
+    recommended: choice.recommended === true,
+    selectLabel
+  };
+}
+
+function trailingAnswerChoiceBlock(lines = [], startIndex = 0) {
+  if (!trailingAnswerChoiceHeadingLine(lines[startIndex])) {
+    return null;
+  }
+  const choices = [];
+  let nextIndex = startIndex + 1;
+  while (nextIndex < lines.length && trailingAnswerChoiceLine(lines[nextIndex])) {
+    const choice = numberedQuestionChoice(lines[nextIndex]);
+    if (!choice) {
+      return null;
+    }
+    choices.push(choice);
+    nextIndex += 1;
+  }
+  const uniqueValues = new Set(choices.map((choice) => choice.value));
+  if (choices.length < 2 || choices.length > 6 || uniqueValues.size !== choices.length) {
+    return null;
+  }
+  return {
+    choices,
+    nextIndex
+  };
+}
+
+function questionForMarkerMatch(match = [], index = 0) {
+  const numberText = String(match[1] || "");
+  const number = Number(numberText);
+  const label = String(match[2] || "").trim();
+  if (
+    !Number.isSafeInteger(number) ||
+    number !== index + 1 ||
+    String(number) !== numberText ||
+    !label
+  ) {
+    return null;
+  }
+  return {
+    choices: [],
+    label,
+    name: `${UI_QUESTION_FIELD_PREFIX}${number}`,
+    number
+  };
+}
+
+function parseLineNumberedQuestionPrompt(value = "") {
+  const lines = String(value || "")
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  if (!lines.length) {
+    return inactiveNumberedQuestionSugar();
+  }
+
+  const intro = [];
+  const outro = [];
+  const questions = [];
+  for (let index = 0; index < lines.length;) {
+    const line = lines[index];
+    const match = numberedQuestionMarkerMatch(line);
+    if (!match) {
+      if (!questions.length) {
+        intro.push(line);
+        index += 1;
+        continue;
+      }
+      const choiceBlock = trailingAnswerChoiceBlock(lines, index);
+      if (choiceBlock) {
+        const question = questions.at(-1);
+        if (question.choices.length) {
+          return inactiveNumberedQuestionSugar();
+        }
+        question.choices = choiceBlock.choices;
+        index = choiceBlock.nextIndex;
+        continue;
+      }
+      const trailingLines = lines.slice(index);
+      if (
+        trailingLines.some((trailingLine) => trailingAnswerChoiceHeadingLine(trailingLine)) ||
+        trailingLines.some((trailingLine) => numberedQuestionMarkerMatch(trailingLine))
+      ) {
+        return inactiveNumberedQuestionSugar();
+      }
+      outro.push(...trailingLines);
+      break;
+    }
+
+    const question = questionForMarkerMatch(match, questions.length);
+    if (!question) {
+      return inactiveNumberedQuestionSugar();
+    }
+    questions.push(question);
+    index += 1;
+  }
+
+  if (!questions.length || !validNumberedQuestions(questions)) {
+    return inactiveNumberedQuestionSugar();
+  }
+  return {
+    intro: intro.join("\n"),
+    outro: outro.join("\n"),
+    questions
+  };
+}
+
+function parseInlineNumberedQuestionPrompt(value = "") {
+  const source = String(value || "").replace(/\r\n/gu, "\n").trim();
+  const firstMarker = source.search(/\[(?:Q)?\d+\]\s+/iu);
+  if (firstMarker < 0) {
+    return inactiveNumberedQuestionSugar();
+  }
+
+  const intro = source.slice(0, firstMarker).trim();
+  const questionText = source.slice(firstMarker).trim();
+  if (!questionText || questionText.includes("\n")) {
+    return inactiveNumberedQuestionSugar();
+  }
+
+  const markerPattern = /\[(?:Q)?(\d+)\]\s+/giu;
+  const markers = [...questionText.matchAll(markerPattern)];
+  if (markers.length < 2 || markers[0].index !== 0) {
+    return inactiveNumberedQuestionSugar();
+  }
+
+  const questions = [];
+  for (const [index, match] of markers.entries()) {
+    const labelStart = match.index + match[0].length;
+    const nextMarker = markers[index + 1];
+    const labelEnd = nextMarker ? nextMarker.index : questionText.length;
+    const question = questionForMarkerMatch([
+      match[0],
+      match[1],
+      questionText.slice(labelStart, labelEnd)
+    ], questions.length);
+    if (!question) {
+      return inactiveNumberedQuestionSugar();
+    }
+    questions.push(question);
+  }
+
+  if (!validNumberedQuestions(questions)) {
+    return inactiveNumberedQuestionSugar();
+  }
+  return {
+    intro,
+    outro: "",
+    questions
+  };
+}
+
+function parseNumberedQuestionPrompt(value = "") {
+  const inlineQuestions = parseInlineNumberedQuestionPrompt(value);
+  return inlineQuestions.questions.length
+    ? inlineQuestions
+    : parseLineNumberedQuestionPrompt(value);
+}
+
+function numberedQuestionSugarForInput(interaction = {}, fields = []) {
+  return numberedQuestionSugarForMessageInput({
+    fields,
+    fieldName: "response",
+    message: interaction?.prompt
+  });
+}
+
+function numberedQuestionSugarForMessageInput({
+  fields = [],
+  fieldName = "response",
+  intentId = "",
+  message = "",
+  requiredIntentId = "",
+  requiredStepStatus = "",
+  stepStatus = ""
+} = {}) {
+  if (!canRenderNumberedQuestionSugar({
+    fields,
+    fieldName,
+    intentId,
+    requiredIntentId,
+    requiredStepStatus,
+    stepStatus
+  })) {
+    return inactiveNumberedQuestionSugar();
+  }
+  return parseNumberedQuestionPrompt(message);
+}
+
+function numberedQuestionInputFields(questions = [], options = {}) {
+  const autocomplete = String(options?.autocomplete || "").trim();
+  const density = String(options?.density || "").trim();
+  return questions.map((question) => ({
+    ...(autocomplete ? { autocomplete } : {}),
+    ...(density ? { density } : {}),
+    kind: "text",
+    label: question.label,
+    name: question.name,
+    required: true,
+    requiredMessage: `Answer question ${question.number}.`
+  }));
+}
+
+function numberedQuestionSubmissionText(questions = [], values = {}) {
+  return questions
+    .map((question) => `[${question.number}] ${String(values[question.name] || "").trim()}`)
+    .join("\n");
+}
+
+function numberedQuestionSubmissionFields(questions = [], values = {}, fieldName = "response") {
+  return {
+    [fieldName]: numberedQuestionSubmissionText(questions, values)
+  };
+}
+
+export {
+  canRenderNumberedQuestionSugar,
+  numberedQuestionInputFields,
+  numberedQuestionSubmissionFields,
+  numberedQuestionSubmissionText,
+  numberedQuestionSugarForMessageInput,
+  numberedQuestionSugarForInput,
+  parseNumberedQuestionPrompt,
+  UI_QUESTION_FIELD_PREFIX
+};

package/src/shared/conversation/scrollFollowState.js

@@ -0,0 +1,32 @@
+const DEFAULT_SCROLL_FOLLOW_THRESHOLD_PX = 48;
+
+function numericElementValue(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : 0;
+}
+
+function scrollDistanceFromBottom(element = null) {
+  if (!element) {
+    return 0;
+  }
+  return Math.max(
+    0,
+    numericElementValue(element.scrollHeight) -
+      numericElementValue(element.scrollTop) -
+      numericElementValue(element.clientHeight)
+  );
+}
+
+function scrollElementNearBottom(
+  element = null,
+  thresholdPx = DEFAULT_SCROLL_FOLLOW_THRESHOLD_PX
+) {
+  const threshold = Math.max(0, numericElementValue(thresholdPx));
+  return scrollDistanceFromBottom(element) <= threshold;
+}
+
+export {
+  DEFAULT_SCROLL_FOLLOW_THRESHOLD_PX,
+  scrollDistanceFromBottom,
+  scrollElementNearBottom
+};

package/src/shared/conversation/thinkingText.js

@@ -0,0 +1,13 @@
+const THINKING_HEADING_PATTERN = /^thinking(?:\.{3}|…|:)?$/iu;
+
+function normalizeThinkingMessageText(value = "") {
+  const lines = String(value || "").trim().split(/\r?\n/u);
+  while (lines.length && THINKING_HEADING_PATTERN.test(lines[0].trim())) {
+    lines.shift();
+  }
+  return lines.join("\n").trim();
+}
+
+export {
+  normalizeThinkingMessageText
+};

package/src/shared/conversation/turns.js

@@ -0,0 +1,30 @@
+/** Adapt ordered messages to the transcript's turn model without changing their metadata. */
+export function conversationTurnsFromMessages(messages = []) {
+  const turns = [];
+  let current = null;
+  for (const [index, source] of messages.entries()) {
+    const message = { ...source, messageId: String(source.messageId || source.id || `message-${index}`) };
+    if (message.role === "system") {
+      turns.push({ turnId: message.messageId, system: message, messages: [message] });
+      current = null;
+      continue;
+    }
+    if (message.role === "user" || !current || current.assistant) {
+      current = { turnId: message.messageId, messages: [] };
+      turns.push(current);
+    }
+    if (message.role === "user") current.user = message;
+    if (message.role === "assistant") {
+      current.pending = ["starting", "inProgress"].includes(message.status);
+      for (const [progressIndex, progress] of (message.progressUpdates || []).entries()) {
+        current.messages.push({ ...progress, role: progress.role || "thinking", messageId: `${message.messageId}:progress:${progress.id || progressIndex}` });
+      }
+      if (!message.text && ["failed", "interrupted"].includes(message.status)) {
+        message.text = message.status === "interrupted" ? "Stopped." : "Assistant stopped with an error.";
+      }
+      current.assistant = message;
+    }
+    if (message.role !== "assistant" || message.text) current.messages.push(message);
+  }
+  return turns;
+}

package/src/testing/conversationStorageContract.js

@@ -0,0 +1,35 @@
+import assert from "node:assert/strict";
+import { createConversationTranscript } from "../server/conversation/transcript.js";
+
+/** Run against an app's isolated adapter fixture; never point this at production data. */
+export async function verifyConversationStorageContract(storage) {
+  const transcript = createConversationTranscript({ storage, clock: () => new Date("2026-01-01T00:00:00Z") });
+  const scope = "actor-a:workspace-a:conversation-a";
+  const other = "actor-b:workspace-a:conversation-a";
+  const attachment = { id: "file-a", name: "notes.txt" };
+  const input = { messageId: "request-a", text: "First question", attachments: [attachment] };
+  const writes = await Promise.all(Array.from({ length: 5 }, () => transcript.writeConversationUserMessage(scope, input)));
+  assert.equal(writes.filter(Boolean).length, 1, "A retried message must create exactly one turn.");
+  const first = (await transcript.readConversationLog(scope))[0];
+  assert.equal(first.user.messageId, input.messageId);
+  assert.deepEqual(first.user.attachments, [attachment]);
+  assert.deepEqual(await transcript.readConversationLog(other), [], "Scopes must be isolated.");
+  await transcript.writeConversationThinkingMessage(scope, { messageId: "thinking-a", text: "Thinking" });
+  await transcript.writeConversationCommentaryMessage(scope, { messageId: "commentary-a", text: "Checking" });
+  await transcript.writeConversationAssistantMessage(scope, { messageId: "answer-a", text: "Initial answer" });
+  await transcript.upsertConversationAssistantMessage(scope, { turnId: first.turnId, text: "Partial answer" });
+  await transcript.upsertConversationAssistantMessage(scope, { turnId: first.turnId, text: "Final answer" });
+  await transcript.writeConversationUserMessage(scope, { messageId: "request-b", text: "Second question" });
+  const latest = await transcript.readConversationLogPage(scope, { limit: 1 });
+  assert.equal(latest.conversationLog[0].user.text, "Second question");
+  assert.equal(latest.pagination.hasMoreBefore, true);
+  const older = await transcript.readConversationLogPage(scope, { limit: 1, beforeTurnId: latest.pagination.nextBeforeTurnId });
+  assert.equal(older.pagination.hasMoreBefore, false);
+  assert.equal(older.conversationLog[0].turnId, first.turnId);
+  assert.equal(older.conversationLog[0].assistant.text, "Final answer");
+  assert.equal(older.conversationLog[0].assistant.messageId, "answer-a", "Final replacement preserves message identity.");
+  assert.deepEqual(older.conversationLog[0].messages.map((message) => message.role), ["user", "thinking", "commentary", "assistant"]);
+  older.conversationLog[0].user.text = "Client mutation";
+  assert.equal((await transcript.readConversationLog(scope))[0].user.text, "First question", "Reads must be detached snapshots.");
+  return { scope, other, transcript };
+}

package/test/conversation.test.js

@@ -0,0 +1,57 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createMemoryConversationStorage } from "../src/server/conversation/memoryStorage.js";
+import { createConversationTranscript } from "../src/server/conversation/transcript.js";
+import { conversationTurnsFromMessages } from "../src/shared/conversation/turns.js";
+import { verifyConversationStorageContract } from "../src/testing/conversationStorageContract.js";
+
+test("memory conversation storage satisfies the replaceable storage contract", async () => {
+  await verifyConversationStorageContract(createMemoryConversationStorage());
+});
+
+test("failed storage writes roll back and do not poison the next operation", async () => {
+  const storage = createMemoryConversationStorage();
+  await assert.rejects(storage.write("one", async (transaction) => {
+    await transaction.appendMessage("000001", { role: "user", text: "Uncommitted", at: "2026-01-01" });
+    throw new Error("disk full");
+  }), /disk full/);
+  const transcript = createConversationTranscript({ storage });
+  assert.deepEqual(await transcript.readConversationLog("one"), []);
+  await transcript.writeConversationUserMessage("one", { messageId: "one", text: "Retry" });
+  assert.equal((await transcript.readConversationLog("one"))[0].user.text, "Retry");
+});
+
+test("storage failures reach the caller instead of acknowledging a saved message", async () => {
+  const transcript = createConversationTranscript({ storage: {
+    read: async () => { throw new Error("read failed"); },
+    write: async () => { throw new Error("write failed"); }
+  } });
+  await assert.rejects(transcript.readConversationLog("one"), /read failed/);
+  await assert.rejects(transcript.writeConversationUserMessage("one", { text: "Question" }), /write failed/);
+});
+
+test("transient deletion is isolated and a conversation can be recreated", async () => {
+  const storage = createMemoryConversationStorage();
+  const transcript = createConversationTranscript({ storage });
+  await transcript.writeConversationUserMessage("one", { text: "One" });
+  await transcript.writeConversationUserMessage("two", { text: "Two" });
+  await storage.deleteConversation("one");
+  assert.deepEqual(await transcript.readConversationLog("one"), []);
+  assert.equal((await transcript.readConversationLog("two"))[0].user.text, "Two");
+  await transcript.writeConversationUserMessage("one", { text: "New" });
+  assert.equal((await transcript.readConversationLog("one"))[0].user.text, "New");
+});
+
+test("message adaptation retains progress, attachments, system actions and SQL metadata", () => {
+  const turns = conversationTurnsFromMessages([
+    { id: "q", role: "user", text: "Question", attachments: [{ id: "file" }] },
+    { id: "a", role: "assistant", text: "", status: "inProgress", progressUpdates: [{ id: "p", text: "Inspecting" }] },
+    { id: "s", role: "system", text: "Repair complete", repair: true },
+    { id: "sql", role: "assistant", text: "Result", sql: "select 1" }
+  ]);
+  assert.equal(turns[0].pending, true);
+  assert.equal(turns[0].messages[1].role, "thinking");
+  assert.equal(turns[0].user.attachments[0].id, "file");
+  assert.equal(turns[1].system.repair, true);
+  assert.equal(turns[2].assistant.sql, "select 1");
+});