@jxsuite/studio 2.4.3 → 4.0.0

package/src/preview/preview-overlay.ts

@@ -0,0 +1,226 @@
+/**
+ * Publishing what the author is looking at, so a live preview shows the canvas and not the disk.
+ *
+ * A live preview composes a page from the project's working TREE, and the tree is what has been
+ * saved. The document the author is actually editing lives in a tab's reactive memory and nowhere
+ * else, so without this the one thing that makes a live preview worth having — seeing an edit
+ * before it is written — would be exactly the thing it could not show.
+ *
+ * What travels is BYTES, and specifically {@link serializeDocument}'s: the same function `saveFile`
+ * writes through, grid controllers, format round-trips, frontmatter and all. That is what makes
+ * "what the reader sees" and "what saving would produce" one answer rather than two that drift. A
+ * document object would bypass the format layer, and a `.md` page's bytes are not
+ * `JSON.stringify(doc)`.
+ *
+ * **Why an effect and not `transactDoc`.** `transact.ts` has exactly one observer slot and the
+ * collab layer owns it. More importantly a transaction hook would MISS three of the most common
+ * ways a document changes: a Monaco source commit, a content-entry field edit, and every grid edit
+ * route around `transactDoc` entirely. "I edited it in Source and the preview did not change" is
+ * the bug this shape avoids.
+ *
+ * **Why one effect over the whole tab set rather than one per tab.** Reading the map tracks
+ * additions, so a tab opened later needs no registration and a tab closed needs no teardown. And
+ * the publish is a DIFF against what was last published, which means save, close, discard and undo
+ * back to clean all resolve through the same line instead of four hooks that can each be
+ * forgotten.
+ *
+ * **Armed, not always on.** Serializing dirty documents on every edit is not free, and before the
+ * author has ever opened a preview there is nothing to publish to. Nothing happens until a preview
+ * origin exists.
+ *
+ * @docs studio/interface
+ */
+
+import { effect, effectScope } from "../reactivity";
+import { getPlatform, hasPlatform } from "../platform";
+import { serializeDocument } from "../files/serialize-document";
+import { workspace } from "../workspace/workspace";
+import type { Tab } from "../tabs/tab";
+
+/**
+ * Trailing debounce on a publish.
+ *
+ * No leading edge: a leading publish would send the first keystroke of a burst and the last, which
+ * is two reloads for one thought. The max wait is what keeps a continuous drag from starving the
+ * trailing timer forever.
+ */
+const PUBLISH_DEBOUNCE_MS = 200;
+const PUBLISH_MAX_WAIT_MS = 500;
+
+/** Bytes one document may publish before it is left showing its saved state instead. */
+const MAX_ENTRY_BYTES = 2 * 1024 * 1024;
+
+/**
+ * Path to the bytes last published for it, so identical bytes cost nothing.
+ *
+ * The TEXT rather than a digest of it. An edit that lands back on the same bytes — a character
+ * typed and deleted — must not cost the reader a reload, and comparing what was sent is exact where
+ * a hash would be a collision away from being wrong for no saving anyone can measure. Memory is
+ * bounded by the same per-entry cap the publish is.
+ */
+const published = new Map<string, string>();
+
+let armed = false;
+let scope: ReturnType<typeof effectScope> | null = null;
+let timer: ReturnType<typeof setTimeout> | null = null;
+let burstStartedAt: number | null = null;
+/** The publish in flight, so a flush awaits it rather than racing it. */
+let inFlight: Promise<void> | null = null;
+
+/** The documents whose unsaved bytes a preview needs, in the order they were opened. */
+function dirtyTabs(): Tab[] {
+  const tabs: Tab[] = [];
+  for (const tab of workspace.tabs.values()) {
+    /* Dirty only. A clean tab's bytes are on disk by definition, and publishing them would create
+       a second source of truth for identical content. */
+    if (tab.doc.dirty && tab.documentPath) {
+      tabs.push(tab);
+    }
+  }
+  return tabs;
+}
+
+/**
+ * Publish what changed and retract what no longer applies.
+ *
+ * A diff rather than a stream of events: whatever reason a document has for no longer being unsaved
+ * — saved, closed, discarded, undone back to its file — it is simply absent from this pass, and the
+ * retraction follows without anywhere else having to remember to ask for it.
+ */
+async function publish(): Promise<void> {
+  /* Not `armed` too: `flushPreviewOverlay` refuses when disarmed and `disarmPreviewOverlay` clears
+     the pending timer, so there is no path into here without it. A host with no platform at all is
+     real though — `getPlatform()` throws rather than answering null. */
+  if (!hasPlatform()) {
+    return;
+  }
+  const platform = getPlatform();
+  if (!platform.setPreviewOverlay || !platform.clearPreviewOverlay) {
+    return;
+  }
+  const live = new Set<string>();
+  for (const tab of dirtyTabs()) {
+    const path = tab.documentPath!.replace(/^\.\//, "");
+    let text: string;
+    try {
+      text = await serializeDocument(tab);
+    } catch {
+      /* A half-typed document that will not serialize is not a reason to stop previewing the layout
+         beside it. Skipped, and the next edit that does serialize publishes it. */
+      continue;
+    }
+    if (text.length > MAX_ENTRY_BYTES) {
+      continue;
+    }
+    live.add(path);
+    if (published.get(path) === text) {
+      continue;
+    }
+    published.set(path, text);
+    await platform.setPreviewOverlay(path, text);
+  }
+  for (const path of published.keys()) {
+    if (!live.has(path)) {
+      published.delete(path);
+      await platform.clearPreviewOverlay(path);
+    }
+  }
+}
+
+/** Run a publish, coalescing with any already scheduled. */
+function schedule(): void {
+  if (!armed) {
+    return;
+  }
+  const now = Date.now();
+  burstStartedAt ??= now;
+  if (timer) {
+    clearTimeout(timer);
+  }
+  const waited = now - burstStartedAt;
+  const delay = Math.max(0, Math.min(PUBLISH_DEBOUNCE_MS, PUBLISH_MAX_WAIT_MS - waited));
+  timer = setTimeout(() => {
+    timer = null;
+    burstStartedAt = null;
+    inFlight = publish().finally(() => {
+      inFlight = null;
+    });
+  }, delay);
+}
+
+/**
+ * Note an edit the reactive effect cannot see.
+ *
+ * `transactDoc` replaces the document's ROOT REFERENCE on every transaction, and a Monaco source
+ * commit assigns a fresh one, so a shallow read catches both. A content-entry field edit writes a
+ * key in place on an already-dirty tab, which changes nothing the effect reads. This is the seam
+ * for exactly that: an explicit call from the few places that mutate without swapping.
+ */
+export function notePreviewOverlayEdit(): void {
+  schedule();
+}
+
+/**
+ * Start publishing, because a preview origin now exists to publish to.
+ *
+ * Idempotent: `View: Open in Browser` calls it on every invocation and only the first does work.
+ */
+export function armPreviewOverlay(): void {
+  if (armed) {
+    return;
+  }
+  armed = true;
+  scope = effectScope();
+  scope.run(() => {
+    effect(() => {
+      for (const tab of workspace.tabs.values()) {
+        /* Two reads, both shallow. `document` is a fresh reference on every transaction — see
+           `transactDoc`, which assigns one specifically so effects re-run — so this costs a
+           property read rather than a walk of the document. */
+        void tab.doc.dirty;
+        void tab.doc.document;
+      }
+      schedule();
+    });
+  });
+}
+
+/**
+ * Stop publishing and forget what was published, without retracting it.
+ *
+ * Called when the window changes project. The published map is keyed by project-relative path, so
+ * carrying it across a switch would let one project's `pages/index.json` be read as the answer for
+ * another's — and the backend lets go of the old root's overlay on its own re-root anyway.
+ */
+export function disarmPreviewOverlay(): void {
+  armed = false;
+  if (timer) {
+    clearTimeout(timer);
+    timer = null;
+  }
+  burstStartedAt = null;
+  scope?.stop();
+  scope = null;
+  published.clear();
+}
+
+/**
+ * Publish now and wait for it.
+ *
+ * Two callers, and both are moments where the debounce is exactly wrong: on the way to opening a
+ * browser tab, so the page the author is about to look at already carries their last keystroke; and
+ * after a save, so the retraction rides with the write instead of arriving a debounce later and
+ * costing a second reload.
+ */
+export async function flushPreviewOverlay(): Promise<void> {
+  if (!armed) {
+    return;
+  }
+  if (timer) {
+    clearTimeout(timer);
+    timer = null;
+    burstStartedAt = null;
+  }
+  await inFlight;
+  await publish();
+}

package/src/services/ai-ask.ts

@@ -0,0 +1,247 @@
+/**
+ * Ai-ask.ts — the assistant's one way to stop and put a question to the author.
+ *
+ * The agent loop `await`s `toolRegistry.execute` (`services/tool-executor.ts`), so a tool that
+ * returns a pending promise suspends the turn. That is the whole mechanism: `ask_user` registers a
+ * question, hands back a promise, and the panel resolves it when the human answers. No new chat
+ * status, no pre-execution hook, and nothing in the published `@jxsuite/ai` changes —
+ * `finishStream` has already set the state to `"idle"` by the time tools run, so a suspended turn
+ * is idle by construction and this store is what "waiting" means.
+ *
+ * Two decisions are load-bearing and easy to get wrong on a rewrite:
+ *
+ * - **A skip is a SUCCESS.** "You decide" is a real answer to a question; only a stopped turn is a
+ *   failure. Reporting a skip as an error would make the model apologise for having asked.
+ * - **The answer never becomes a user message.** `toMessagesArray` serialises the array verbatim
+ *   and a provider requires a `tool` reply to follow its `tool_calls` request; a user turn spliced
+ *   between them is a 400. The answer travels as the tool result, and the chat view renders it into
+ *   the question's own chip.
+ *
+ * Exactly one question can be outstanding, because `runAgentLoop` executes a round's tool calls
+ * serially. The guard below is defensive, not load-bearing.
+ *
+ * @license MIT
+ */
+
+import { createToolDefinition, toolError, toolSuccess } from "@jxsuite/ai/tools";
+import { reactive } from "../reactivity";
+import { currentToolCallId, turnSignal } from "./ai-turn-signal";
+
+import type { ToolRegistry } from "@jxsuite/ai/tools";
+
+/** A question the assistant is waiting on. `id` is the tool-call id, so the chip and this agree. */
+export interface PendingAsk {
+  id: string;
+  question: string;
+  /** Short choices rendered as buttons. Free text is always allowed alongside them. */
+  options: string[];
+  /** One line of why-I'm-asking, rendered under the question. */
+  context: string;
+}
+
+/** How a question was settled. `answer: null` with `skipped` is the author saying "you decide". */
+export interface AskAnswer {
+  answer: string | null;
+  skipped: boolean;
+}
+
+/** Max choices rendered as buttons; beyond this the question wants free text, not a menu. */
+const MAX_OPTIONS = 6;
+
+const state = reactive<{ pending: PendingAsk | null }>({ pending: null });
+
+/** The resolver for {@link state.pending}, kept out of the reactive object (it is not render data). */
+let settle: ((answer: AskAnswer) => void) | null = null;
+
+/** Torn down with the question so a stopped turn does not leave a listener on a dead signal. */
+let detachAbort: (() => void) | null = null;
+
+function clear() {
+  state.pending = null;
+  settle = null;
+  detachAbort?.();
+  detachAbort = null;
+}
+
+/**
+ * The outstanding question, or null. Reactive — read it inside an `effect()` to repaint on it.
+ *
+ * @returns {PendingAsk | null}
+ */
+export function pendingAsk(): PendingAsk | null {
+  return state.pending;
+}
+
+/** Whether a turn is suspended on the author. The composer's Send becomes Answer on this. */
+export function isAwaitingAnswer(): boolean {
+  return state.pending !== null;
+}
+
+/**
+ * Register a question and suspend until it is settled.
+ *
+ * @param {PendingAsk} ask
+ * @returns {Promise<AskAnswer>} Resolves on an answer, a skip, or the turn being stopped (`{
+ *   answer: null, skipped: false }` — the shape the tool reports as a failure).
+ */
+export function askUser(ask: PendingAsk): Promise<AskAnswer> {
+  return new Promise<AskAnswer>((resolve) => {
+    state.pending = ask;
+    settle = resolve;
+
+    /* The turn's signal, not a parameter: `ToolRegistry.execute` has nowhere to pass one. Without
+       this, Stop would leave the loop awaiting a promise nothing could ever resolve. */
+    const signal = turnSignal();
+    if (signal?.aborted) {
+      clear();
+      resolve({ answer: null, skipped: false });
+      return;
+    }
+    if (signal) {
+      const onAbort = () => {
+        cancelAsk();
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+      detachAbort = () => signal.removeEventListener("abort", onAbort);
+    }
+  });
+}
+
+/**
+ * Answer the outstanding question.
+ *
+ * @param {string} text
+ * @returns {boolean} False when nothing was pending, so a caller can fall through to a normal send.
+ */
+export function answerAsk(text: string): boolean {
+  if (!settle) {
+    return false;
+  }
+  const resolve = settle;
+  clear();
+  resolve({ answer: text, skipped: false });
+  return true;
+}
+
+/**
+ * Decline to answer — "you decide". Settles as a success, so the turn carries on.
+ *
+ * @returns {boolean} False when nothing was pending.
+ */
+export function skipAsk(): boolean {
+  if (!settle) {
+    return false;
+  }
+  const resolve = settle;
+  clear();
+  resolve({ answer: null, skipped: true });
+  return true;
+}
+
+/** Settle an outstanding question as unanswered. Called from `stop()` and from the turn's abort. */
+export function cancelAsk(): void {
+  if (!settle) {
+    return;
+  }
+  const resolve = settle;
+  clear();
+  resolve({ answer: null, skipped: false });
+}
+
+/** Drop any outstanding question without settling a turn. For New Chat and for tests. */
+export function resetAsk(): void {
+  cancelAsk();
+  clear();
+}
+
+/**
+ * Register `ask_user` into a tool registry.
+ *
+ * The description carries the discipline the tool needs to be worth having: a question the model
+ * could have answered itself is noise, and a question about a setting the pipeline never receives
+ * is worse than noise, because the answer cannot be honoured.
+ *
+ * @param {Pick<ToolRegistry, "register">} registry
+ */
+export function registerAskTool(registry: Pick<ToolRegistry, "register">): void {
+  registry.register(
+    createToolDefinition({
+      name: "ask_user",
+      description:
+        "Pause and put a question to the user; the turn waits for their reply and resumes with " +
+        "it. Use it ONLY for a judgement that is genuinely theirs — which pages matter, whether to " +
+        "keep the original design, whether a low-fidelity page is acceptable. Never ask something " +
+        "you can decide yourself or discover with another tool, and never ask about an option you " +
+        "cannot act on. One question at a time; offer options when the sensible answers are a " +
+        "short list, and the user may always reply in their own words instead.",
+      parameters: {
+        type: "object",
+        properties: {
+          question: {
+            type: "string",
+            description: "The question, in one sentence, addressed to the user.",
+          },
+          options: {
+            type: "array",
+            items: { type: "string" },
+            description:
+              `Up to ${MAX_OPTIONS} short answers, rendered as buttons. Omit when the answer is ` +
+              "open-ended.",
+          },
+          context: {
+            type: "string",
+            description:
+              "One line of why you are asking — what you found that made this a judgement call.",
+          },
+        },
+        required: ["question"],
+      },
+      execute: async (args) => {
+        /* Everything `unknown`, and every field narrowed by `typeof` rather than by `?.`. The
+           registry's `validate()` is "a lightweight structural check, not a JSON Schema validator",
+           `strict: false` skips it entirely, and this tool may be registered into someone else's
+           registry — so an argument that is a number is a case, not an impossibility. Optional
+           chaining guards null, not type: `context?.trim()` threw on one. */
+        const { question, options, context } = args as {
+          question?: unknown;
+          options?: unknown;
+          context?: unknown;
+        };
+        if (typeof question !== "string" || !question.trim()) {
+          return toolError('Pass "question" — the question to put to the user.');
+        }
+        if (isAwaitingAnswer()) {
+          return toolError("A question is already waiting for the user.");
+        }
+        const choices = Array.isArray(options)
+          ? options
+              .filter((o): o is string => typeof o === "string" && o.trim().length > 0)
+              .slice(0, MAX_OPTIONS)
+          : [];
+
+        const { answer, skipped } = await askUser({
+          context: typeof context === "string" ? context.trim() : "",
+          /* The tool-call id, so the chip the transcript draws and the question this registers are
+             the same thing. Without it a restored, permanently unanswered question would render
+             identically to the live one. */
+          id: currentToolCallId(),
+          options: choices,
+          question: question.trim(),
+        });
+
+        if (skipped) {
+          /* A success: the model asked, and "you decide" is an answer. Rendering it as a failure
+             would have the model apologise for having asked a fair question. */
+          return toolSuccess(
+            { answer: null, skipped: true },
+            "The user declined to answer; proceed with your best judgment.",
+          );
+        }
+        if (answer === null) {
+          return toolError("The user did not answer — the turn was stopped.");
+        }
+        return toolSuccess({ answer, skipped: false }, `The user answered: "${answer}"`);
+      },
+    }),
+  );
+}