@jxsuite/studio 6.1.0 → 6.1.2

package/src/panels/ai-chat/chat-view.ts

@@ -4,15 +4,15 @@
  *
  * Message-row anatomy: user messages render as right-aligned bubbles (attached-context blocks
  * become chips), assistant messages render sanitized markdown plus tool-call chips, tool messages
- * surface failures only, the streaming tail renders as plain text with a cursor
- * (markdown parses once on finalize), and chat errors get a danger row with recovery advice and a
- * Retry. **None of that is markup here any more** — `surfaces/ai-chat.json` draws it and this
- * module decides what it says, which is the same split the file always had with a document on the
- * other side of it instead of a lit template.
+ * surface failures only, the streaming tail renders as plain text with a cursor (markdown parses
+ * once on finalize), and chat errors get a danger row with recovery advice and a Retry. **None of
+ * that is markup here any more** — `surfaces/ai-chat.json` draws it and this module decides what it
+ * says, which is the same split the file always had with a document on the other side of it instead
+ * of a lit template.
  *
- * ai.md §3.2 (the accountable turn) is why three things here are not what they were:
+ * The accountable turn (ai.md §3.2) is why three things here are not what they were:
  *
- * - **A chip renders its OUTCOME.** It reads `ToolCallRecord.result`, so a chip that said
+ * - **A chip renders its OUTCOME.** It reads `LiveToolCall.result`, so a chip that said
  *   `update_style: ["children",0]` no longer says exactly as much when the edit was refused as when
  *   it landed. The live loop attaches each result as its call finishes (`appendToolResult`), and a
  *   restored chat backfills it from the tool message that answered the call
@@ -24,48 +24,57 @@
  * - **An error offers Retry.** `chatState.retryLast()` has been implemented, exported and called by
  *   nobody; the error row is where it belongs.
  *
- * ai.md §3.0 is why the three buttons here are not callbacks any more. History, New Chat and Retry
- * were closures this module received and invoked, so the capabilities existed ONLY as buttons: the
- * `Assistant` category held zero records, and nothing could reach them from the palette, a chord,
- * the automation runner or the generated commands sheet. They are {@link projectCommand} now, in
- * the idiom `surfaces/statusbar.ts` established — the record is the definition site, and this file
- * only decides where it is drawn and with which glyph.
+ * The assistant being addressable by name (ai.md §3.0) is why the three buttons here are not
+ * callbacks any more. History, New Chat and Retry were closures this module received and invoked,
+ * so the capabilities existed ONLY as buttons: the `Assistant` category held zero records, and
+ * nothing could reach them from the palette, a chord, the automation runner or the generated
+ * commands sheet. They are {@link projectCommand} now, in the idiom `surfaces/statusbar.ts`
+ * established — the record is the definition site, and this file only decides where it is drawn and
+ * with which glyph.
  *
  * @license MIT
  */
 
-import type { Message, ToolCallRecord } from "@jxsuite/ai/chat-state";
+import type { LiveMessage, LiveToolCall } from "@jxsuite/ai/messages";
+import { isBoolean, isJsonObject, isString } from "@jxsuite/schema/guards";
+import type { JsonObject, JsonValue } from "@jxsuite/schema/types";
 import { splitAttachedContext } from "./attached-context";
 import { renderMarkdown } from "./chat-markdown";
 import { summarizeWrites, writesForTurn } from "../../services/ai-writes";
+import { ASK_TOOL } from "../../services/tool-outcomes";
 import { activeRegistry } from "../../commands/active-registry";
 
+import type { AskAnswer } from "../../services/ai-ask";
 import type { CommandRegistry } from "../../commands/registry";
 import type { ImportRunRecord } from "../../services/import-run";
-import type {
-  ChatChangeView,
-  ChatChipView,
-  ChatCommandView,
-  ChatContextChip,
-  ChatRowView,
-} from "../../surfaces/ai-chat";
+import type { ChatChipView, ChatCommandView, ChatRowView } from "../../surfaces/ai-chat";
+import type { KeyedLabel } from "../../ui/surface";
 
 // ─── Helpers (moved from ai-panel.ts) ────────────────────────────────────────
 
+/** The parts of a tool result message the transcript reads. */
+export interface ParsedToolResult {
+  success: boolean;
+  error?: string;
+  summary?: string;
+}
+
 /**
  * Parse a tool result message content (JSON string) into its success/error shape. Returns null if
  * the content isn't a valid tool result.
  *
  * @param {string} content
- * @returns {{ success: boolean; error?: string; summary?: string } | null}
+ * @returns {ParsedToolResult | null}
  */
-export function tryParseToolResult(
-  content: string,
-): { success: boolean; error?: string; summary?: string } | null {
+export function tryParseToolResult(content: string): ParsedToolResult | null {
   try {
-    const parsed = JSON.parse(content) as { success?: unknown; error?: string; summary?: string };
-    if (parsed && typeof parsed.success === "boolean") {
-      return parsed as { success: boolean; error?: string; summary?: string };
+    // SAFETY: JSON.parse only ever produces JSON values.
+    const parsed = JSON.parse(content) as JsonValue;
+    if (isJsonObject(parsed) && isBoolean(parsed.success)) {
+      /* SAFETY: a tool message's content is the agent loop's JSON.stringify of a ToolResult, whose
+         `error` and `summary` are strings when present; a boolean `success` is what tells that
+         envelope apart from any other JSON a message might carry. */
+      return parsed as JsonObject & ParsedToolResult;
     }
   } catch {
     /* Not JSON — not a tool result */
@@ -82,13 +91,11 @@ export function tryParseToolResult(
 export function formatToolLabel(tc: { name: string; arguments: string }): string {
   let detail = "";
   try {
-    const args = (tc.arguments ? JSON.parse(tc.arguments) : {}) as {
-      path?: unknown;
-      parentPath?: unknown;
-    };
-    if (Array.isArray(args.path)) {
+    // SAFETY: JSON.parse only ever produces JSON values.
+    const args = (tc.arguments ? JSON.parse(tc.arguments) : {}) as JsonValue;
+    if (isJsonObject(args) && Array.isArray(args.path)) {
       detail = `: ${JSON.stringify(args.path)}`;
-    } else if (Array.isArray(args.parentPath)) {
+    } else if (isJsonObject(args) && Array.isArray(args.parentPath)) {
       detail = `: ${JSON.stringify(args.parentPath)}`;
     }
   } catch {
@@ -213,9 +220,6 @@ export function tokenHint(tokens: number, overBudget: boolean): string {
 
 // ─── Tool calls ─────────────────────────────────────────────────────────────
 
-/** The tool whose chip is a question card rather than a chip. */
-const ASK_TOOL = "ask_user";
-
 /** The tool whose chip grows a live progress line while it runs. */
 const IMPORT_TOOL = "import_site";
 
@@ -233,25 +237,30 @@ interface AskArgs {
  * to render a call whose JSON is still half-written. A card with an empty question renders as an
  * ordinary chip rather than as an empty box.
  *
- * @param {ToolCallRecord} tc
+ * @param {LiveToolCall} tc
  * @returns {AskArgs | null}
  */
-export function parseAsk(tc: ToolCallRecord): AskArgs | null {
-  let parsed: { question?: unknown; options?: unknown; context?: unknown };
+export function parseAsk(tc: LiveToolCall): AskArgs | null {
+  let parsed: JsonValue;
   try {
-    parsed = tc.arguments ? (JSON.parse(tc.arguments) as typeof parsed) : {};
+    // SAFETY: JSON.parse only ever produces JSON values.
+    parsed = tc.arguments ? (JSON.parse(tc.arguments) as JsonValue) : {};
   } catch {
     return null; // Still streaming, or malformed — the generic chip is the honest fallback.
   }
-  if (typeof parsed.question !== "string" || !parsed.question.trim()) {
+  if (!isJsonObject(parsed)) {
+    return null;
+  }
+  const { context, options, question } = parsed;
+  if (!isString(question) || !question.trim()) {
     return null;
   }
   return {
-    context: typeof parsed.context === "string" ? parsed.context : "",
-    options: Array.isArray(parsed.options)
-      ? parsed.options.filter((o): o is string => typeof o === "string" && o.trim().length > 0)
+    context: isString(context) ? context : "",
+    options: Array.isArray(options)
+      ? options.filter((o): o is string => isString(o) && o.trim().length > 0)
       : [],
-    question: parsed.question,
+    question,
   };
 }
 
@@ -263,13 +272,13 @@ export function parseAsk(tc: ToolCallRecord): AskArgs | null {
  * indistinguishable from a live one and spins forever waiting for a loop that is gone. It is a
  * property of the RUN, not of the record, so the caller supplies whether this call is still live.
  *
- * @param {ToolCallRecord} tc
+ * @param {LiveToolCall} tc
  * @param {boolean} [live] - Whether the loop is still waiting on this call. Only consulted for a
  *   result-less interactive call; every other pending call belongs to a turn still in flight.
  * @returns {"pending" | "unanswered" | "ok" | "failed"}
  */
 export function toolOutcome(
-  tc: ToolCallRecord,
+  tc: LiveToolCall,
   live = true,
 ): "pending" | "unanswered" | "ok" | "failed" {
   if (!tc.result) {
@@ -285,10 +294,10 @@ export function toolOutcome(
  * is no reason the human could not have been reading it all along. A tool that failed writes
  * `error`, which was surfaced only through the separate tool-message row and only after the fact.
  *
- * @param {ToolCallRecord} tc
+ * @param {LiveToolCall} tc
  * @returns {string}
  */
-export function toolOutcomeText(tc: ToolCallRecord): string {
+export function toolOutcomeText(tc: LiveToolCall): string {
   const { result } = tc;
   if (!result) {
     return "";
@@ -313,8 +322,8 @@ export interface AskHandlers {
   importRun?: (id: string) => ImportRunRecord | null;
 }
 
-/** The empty import fields every chip carries, so a `$switch` never reads an absent path. */
-function noImport(): Pick<
+/** The import fields of a chip: empty, or projected from a running import's record. */
+type ChipImportView = Pick<
   ChatChipView,
   | "hasPhase"
   | "importCount"
@@ -325,7 +334,10 @@ function noImport(): Pick<
   | "importProgress"
   | "importSpinner"
   | "importState"
-> {
+>;
+
+/** The empty import fields every chip carries, so a `$switch` never reads an absent path. */
+function noImport(): ChipImportView {
   return {
     hasPhase: false,
     importCount: "",
@@ -354,7 +366,7 @@ function noImport(): Pick<
  * @param {ImportRunRecord} record
  * @returns {Partial<ChatChipView>}
  */
-function projectImport(record: ImportRunRecord): Partial<ChatChipView> {
+function projectImport(record: ImportRunRecord): ChipImportView {
   const running = record.status === "running";
   const determinate = record.total !== null && record.current !== null;
   const outcome =
@@ -391,17 +403,21 @@ function projectImport(record: ImportRunRecord): Partial<ChatChipView> {
  * answer are all facts about one tool call, and putting them anywhere else would give the
  * transcript two accounts of the same event that can disagree after a reload.
  *
- * @param {ToolCallRecord} tc
+ * @param {LiveToolCall} tc
  * @param {AskHandlers} handlers
  * @returns {ChatChipView}
  */
-export function projectChip(tc: ToolCallRecord, handlers: AskHandlers = {}): ChatChipView {
+export function projectChip(tc: LiveToolCall, handlers: AskHandlers = {}): ChatChipView {
   const outcome = toolOutcome(tc, tc.id === handlers.pendingId || Boolean(tc.result));
   const text = toolOutcomeText(tc);
   const run = tc.name === IMPORT_TOOL ? (handlers.importRun?.(tc.id) ?? null) : null;
   const ask = tc.name === ASK_TOOL ? parseAsk(tc) : null;
+  /* SAFETY: a successful ask_user result carries an AskAnswer (services/ai-ask.ts). Any other
+     tool's data only feeds `answer`, which the surface draws inside the ask card alone, and
+     `askState`, which is set only when `ask` is non-null, so a mistyped read never reaches the
+     screen. */
   const answered = tc.result?.success
-    ? ((tc.result.data as { answer?: string | null; skipped?: boolean } | undefined) ?? null)
+    ? ((tc.result.data as Partial<AskAnswer> | undefined) ?? null)
     : null;
   const base: ChatChipView = {
     answer: answered ? (answered.skipped ? "You decide" : (answered.answer ?? "")) : "",
@@ -419,8 +435,7 @@ export function projectChip(tc: ToolCallRecord, handlers: AskHandlers = {}): Cha
     outcomeText: text,
     question: ask?.question ?? "",
     tool: tc.name,
-    ...noImport(),
-    ...(run ? projectImport(run) : {}),
+    ...(run ? projectImport(run) : noImport()),
   };
   if (ask) {
     /* The options are a shortcut, never the whole answer — the composer is always live beneath, and
@@ -451,19 +466,11 @@ export function projectChip(tc: ToolCallRecord, handlers: AskHandlers = {}): Cha
  * one would be the same lie the model-facing caveat used to be.
  *
  * @param {string} messageId
- * @returns {{
- *   changesState: string;
- *   changesSummary: string;
- *   canRestore: boolean;
- *   changes: ChatChangeView[];
- * }}
+ * @returns {Pick<ChatRowView, "canRestore" | "changes" | "changesState" | "changesSummary">}
  */
-export function projectChanges(messageId: string): {
-  changesState: string;
-  changesSummary: string;
-  canRestore: boolean;
-  changes: ChatChangeView[];
-} {
+export function projectChanges(
+  messageId: string,
+): Pick<ChatRowView, "canRestore" | "changes" | "changesState" | "changesSummary"> {
   const writes = writesForTurn(messageId);
   const summary = writes.length > 0 ? summarizeWrites(writes) : "";
   if (!summary) {
@@ -504,12 +511,12 @@ function emptyRow(key: string, kind: string): ChatRowView {
 }
 
 /** The attached-context block on a user turn, back apart into chips. */
-function contextChips(lines: readonly string[]): ChatContextChip[] {
+function contextChips(lines: readonly string[]): KeyedLabel[] {
   return lines.map((line, index) => ({ key: `${index}:${line}`, label: line }));
 }
 
 export interface MessageListOptions {
-  messages: readonly Message[];
+  messages: readonly LiveMessage[];
   /** ChatState status — "streaming" projects the tail live. */
   status: string;
   /** The outstanding question and the import records, passed down rather than read here. */

package/src/panels/ai-chat/composer.ts

@@ -7,9 +7,9 @@
  * (precedent: createAiCredentialsForm) so draft state never leaks between hosts.
  *
  * **There is no markup here.** `surfaces/ai-chat.json` draws the composer and this module says what
- * it holds — which is what let the auto-grow go entirely: the textarea grows with
- * `field-sizing: content`, where this file used to write `scrollHeight` back into `style.height` on
- * every keystroke.
+ * it holds — which is what let the auto-grow go entirely: the textarea grows with `field-sizing:
+ * content`, where this file used to write `scrollHeight` back into `style.height` on every
+ * keystroke.
  *
  * **The draft is a controlled value now, and that is safe for the reason it was not before.** The
  * lit textarea had to be uncontrolled, because a streaming repaint re-rendered the whole panel and
@@ -24,7 +24,7 @@
  * @license MIT
  */
 
-import { displayTagName } from "@jxsuite/schema/guards";
+import { displayTagName, isNodeObject, isString } from "@jxsuite/schema/guards";
 import { getNodeAtPath } from "../../state";
 import { createModelPicker } from "../../ui/ai-model-picker";
 import { openMenu } from "../../surfaces/menu";
@@ -34,8 +34,7 @@ import { primarySelection } from "../../tabs/selection";
 import { buildMessageWithContext } from "./attached-context";
 import type { ContextChip } from "./attached-context";
 import type { ChatComposerChip } from "../../surfaces/ai-chat";
-import type { MenuHandle } from "../../surfaces/menu";
-import type { JxMutableNode } from "@jxsuite/schema/types";
+import type { MenuHandle, OpenMenuOptions } from "../../surfaces/menu";
 
 export interface ComposerOptions {
   /** Receives the full message content (typed text + serialized context). */
@@ -80,7 +79,7 @@ export interface Composer {
   send: () => void;
   clear: () => void;
   /** Open the attach menu under the button that was pressed. */
-  openAttachMenu: (anchor: unknown) => void;
+  openAttachMenu: (anchor: EventTarget | null) => void;
   /** Take a chip off, by its kind. */
   dropChip: (kind: string) => void;
   /** The model picker's host is in the page; put the picker's own element in it. */
@@ -124,27 +123,24 @@ export function createComposer(opts: ComposerOptions): Composer {
     const selection = primarySelection(tab?.session.selection);
     let selectionChip: ContextChip | null = null;
     if (tab && selection) {
-      /* No `tagName?: string` in this cast any more. It overrode the widened type — a tag may be
-         a name or a choice between names — so the compiler could not see that this chip would
-         render `[object Object]` for a chosen one. A cast that narrows a field back to what it
-         used to be is a hole the type system cannot report. */
-      const node = getNodeAtPath(tab.doc.document as JxMutableNode, selection) as
-        | (JxMutableNode & { textContent?: string })
-        | undefined;
+      /* No cast narrows `tagName` back to a string: a tag may be a name or a choice between names,
+         and `displayTagName` is what renders either. A stale selection path resolves to nothing,
+         and a string child is not a node, so both read as a bare "element". */
+      const found = getNodeAtPath(tab.doc.document, selection);
+      const node = isNodeObject(found) ? found : undefined;
       const tag = displayTagName(node?.tagName) || "element";
-      const text = typeof node?.textContent === "string" ? node.textContent.slice(0, 40) : "";
+      const textContent = node?.textContent;
+      const text = isString(textContent) ? textContent.slice(0, 40) : "";
       selectionChip = {
         detail: `Selected element at ${JSON.stringify(selection)}: <${tag}>${text ? ` "${text}"` : ""}`,
         kind: "selection",
         label: `<${tag}>`,
       };
     }
-    return {
-      pageChip: documentPath
-        ? ({ detail: `Page: ${documentPath}`, kind: "page", label: documentPath } as ContextChip)
-        : null,
-      selectionChip,
-    };
+    const pageChip: ContextChip | null = documentPath
+      ? { detail: `Page: ${documentPath}`, kind: "page", label: documentPath }
+      : null;
+    return { pageChip, selectionChip };
   }
 
   /** Add (or refresh) a chip of the given kind — one chip per kind. */
@@ -174,7 +170,7 @@ export function createComposer(opts: ComposerOptions): Composer {
    * `openMenu` rather than a popover of this module's own — the kit menu is the settled answer, and
    * it brings roving focus, typeahead, Escape and light dismissal with it.
    */
-  function openAttachMenu(anchor: unknown): void {
+  function openAttachMenu(anchor: EventTarget | null): void {
     if (menu) {
       menu.close();
       menu = null;
@@ -182,22 +178,13 @@ export function createComposer(opts: ComposerOptions): Composer {
     }
     const opener = anchor instanceof HTMLElement ? anchor : null;
     const { pageChip, selectionChip } = contextCandidates();
-    menu = openMenu({
+    const options: OpenMenuOptions = {
       label: "Attach context",
       onClosed: (handle) => {
         if (menu === handle) {
           menu = null;
         }
       },
-      ...(opener ? { opener } : {}),
-      ...(opener
-        ? {
-            place: () => {
-              const box = rectOf(opener);
-              return { x: box.left, y: box.top - 4 };
-            },
-          }
-        : { origin: { x: 0, y: 0 } }),
       region: "assistant-attach",
       rows: [
         {
@@ -227,7 +214,17 @@ export function createComposer(opts: ComposerOptions): Composer {
           title: selectionChip ? `Selected element — ${selectionChip.label}` : "Selected element",
         },
       ],
-    });
+    };
+    if (opener) {
+      options.opener = opener;
+      options.place = () => {
+        const box = rectOf(opener);
+        return { x: box.left, y: box.top - 4 };
+      };
+    } else {
+      options.origin = { x: 0, y: 0 };
+    }
+    menu = openMenu(options);
   }
 
   // ── Input ─────────────────────────────────────────────────────────────

package/src/panels/ai-chat/sessions-view.ts

@@ -14,11 +14,10 @@
  * @license MIT
  */
 
-import { now } from "../../services/clock";
+import { MINUTE, now } from "../../services/clock";
 import type { ChatSessionView } from "../../surfaces/ai-chat";
 import type { SessionMeta } from "../../services/ai-session-store";
 
-const MINUTE = 60_000;
 const HOUR = 60 * MINUTE;
 const DAY = 24 * HOUR;
 

package/src/panels/ai-panel.ts

@@ -4,9 +4,8 @@
  *
  * The assistant over the reactive document-assistant session: a view-state machine (sessions list ↔
  * chat), the transcript, the sticky composer, and the six `Assistant:` records that are the only
- * definition of what it can do. It is a Jx document over the kit now
- * (`surfaces/ai-chat.json` + `surfaces/ai-chat.ts`); this module is the flow, and everything below
- * decides rather than draws.
+ * definition of what it can do. It is a Jx document over the kit now (`surfaces/ai-chat.json` +
+ * `surfaces/ai-chat.ts`); this module is the flow, and everything below decides rather than draws.
  *
  * Credentials are NOT a state of this panel. A provider key is a roaming APPLICATION setting
  * configured once, so it lives in Preferences › Assistant (⌘,) — not in a dialog reachable only
@@ -23,8 +22,8 @@
  * nothing else — the composer is never re-rendered, so there is nothing to guard against and
  * nothing to coalesce. One `effect()` recomputes the projection; the surface follows.
  *
- * @docs studio/ai/chat
  * @license MIT
+ * @docs studio/ai/chat
  */
 
 import { effect, effectScope } from "../reactivity";
@@ -64,7 +63,7 @@ import type { AiChatSurface, AiChatView } from "../surfaces/ai-chat";
 import type { AnyCommand } from "../commands/registry";
 import type { CommandContext } from "../commands/context";
 import type { EffectScope } from "@vue/reactivity";
-import type { Message } from "@jxsuite/ai/chat-state";
+import type { LiveMessage } from "@jxsuite/ai/messages";
 
 // ─── State (module-level, persists across tab switches) ─────────────────────
 
@@ -73,9 +72,14 @@ let mounted = false;
 /** Which pane the panel shows. */
 let view: "chat" | "sessions" = "chat";
 
+declare global {
+  /** The live assistant session, for inspection from a devtools console. */
+  var assistant: ReturnType<typeof createDocumentAssistant> | undefined;
+}
+
 /** Document AST assistant session — created lazily, persists across tab switches. */
 const assistant = createDocumentAssistant();
-(globalThis as Record<string, unknown>).assistant = assistant;
+globalThis.assistant = assistant;
 let assistantScope: EffectScope | null = null;
 
 // ─── The surface ────────────────────────────────────────────────────────────
@@ -224,10 +228,10 @@ function watchAssistant() {
  * The assistant message the tool replies at the end of the transcript answer: the one whose chips a
  * running tool's result is about to change.
  *
- * @param {readonly Message[]} messages
- * @returns {Message | undefined}
+ * @param {readonly LiveMessage[]} messages
+ * @returns {LiveMessage | undefined}
  */
-function latestRequest(messages: readonly Message[]): Message | undefined {
+function latestRequest(messages: readonly LiveMessage[]): LiveMessage | undefined {
   for (let index = messages.length - 1; index >= 0; index--) {
     if (messages[index]!.role !== "tool") {
       return messages[index];
@@ -463,21 +467,20 @@ export function seedAssistantMessages(messages: SeededAssistantMessage[]): void
   for (const msg of messages) {
     seededCount += 1;
     const seq = seededCount;
-    assistant.chatState.messages.push({
+    const message: LiveMessage = {
       content: msg.content,
       id: `seeded_${seq}`,
       role: msg.role,
       timestamp: seq,
-      ...(msg.toolCalls
-        ? {
-            toolCalls: msg.toolCalls.map((tc, i) => ({
-              arguments: tc.arguments,
-              id: `seeded_${seq}_tc${i}`,
-              name: tc.name,
-            })),
-          }
-        : {}),
-    });
+    };
+    if (msg.toolCalls) {
+      message.toolCalls = msg.toolCalls.map((tc, i) => ({
+        arguments: tc.arguments,
+        id: `seeded_${seq}_tc${i}`,
+        name: tc.name,
+      }));
+    }
+    assistant.chatState.messages.push(message);
   }
   renderAiPanel();
 }