@jxsuite/studio 2.4.3 → 4.0.0

package/src/services/settings/kernel.ts

@@ -0,0 +1,335 @@
+/// <reference lib="dom" />
+/**
+ * The settings kernel — one owner for every application setting's value.
+ *
+ * **The model.** The backend store is authoritative, `localStorage` is a synchronous cache of it,
+ * and every write is a per-key patch applied by whoever owns the file. What this replaces collapsed
+ * all three roles: `localStorage` was the truth, and it was mirrored to disk by whole-map replaces
+ * computed from whichever window happened to write last. On the chromium launcher — where every
+ * window is its own process with its own browser profile, and so its own `localStorage` — a window
+ * holding no settings could therefore overwrite the shared file with an almost empty map. Nothing
+ * told the other window it had happened.
+ *
+ * **Why a Map and not just localStorage.** Reads must be synchronous: the chrome theme is read
+ * before the first paint (`shell.ts` says so explicitly — a mismatch flashes the shell), and every
+ * credential gate reads on the render path. But the authoritative copy arrives asynchronously. An
+ * in-memory Map seeded from the cache at module evaluation gives both: correct on the first frame,
+ * and reconciled by {@link hydrateSettings} the moment the backend answers.
+ *
+ * **The one deletion path.** {@link setSetting} with `""` STORES an empty string;
+ * {@link clearSetting} is the only thing that removes. Blank used to mean delete, which read as a
+ * convenience until a form that blanked its own drafts on save called the setters with them — and
+ * pressing Save a second time revoked the credentials the first press had stored. Making blank
+ * unrepresentable as a deletion is what stops that whole class, rather than fixing the one caller.
+ *
+ * @license MIT
+ */
+
+import { getPlatform, hasPlatform } from "../../platform";
+import { notify } from "../notify";
+import { ALL_SETTINGS, USER_SETTINGS } from "./definitions";
+import type { SettingDefinition } from "./definitions";
+import { createWriteQueue } from "./write-queue";
+import type { SettingsPatch } from "./write-queue";
+
+/** The synchronous source of truth. Absent key means unset — which is not the same as `""`. */
+const values = new Map<string, string>();
+
+/** Mirror a value into the cache, so the next boot is correct before the backend answers. */
+function writeCache(key: string, value: string | null): void {
+  try {
+    if (value === null) {
+      globalThis.localStorage?.removeItem(key);
+    } else {
+      globalThis.localStorage?.setItem(key, value);
+    }
+  } catch {
+    /* Storage unavailable (private mode) — the Map still serves this session. */
+  }
+}
+
+/**
+ * Seed from the cache, at module evaluation and before anything can read.
+ *
+ * This is what makes the first frame correct: the chrome theme is read before the first paint, and
+ * `shell.ts` records that a mismatch with the theme `index.html` hard-codes flashes the shell. The
+ * backend's copy arrives later and reconciles through {@link hydrateSettings}.
+ *
+ * One `try` around the whole loop rather than one per key — storage that throws throws for all of
+ * them, and a private-mode window simply starts empty.
+ */
+try {
+  for (const definition of ALL_SETTINGS) {
+    const cached = globalThis.localStorage?.getItem(definition.key);
+    if (cached !== null && cached !== undefined) {
+      values.set(definition.key, cached);
+    }
+  }
+} catch {
+  /* Storage unavailable — the map starts empty, and hydration fills it. */
+}
+
+// ─── Reading ──────────────────────────────────────────────────────────────────
+
+/**
+ * The value the user actually chose — the ONLY read. A default never stands in for silence here.
+ *
+ * There is deliberately no default-masking sibling. One existed, and every bug in this area came
+ * from a caller taking the masked value for a chosen one: a form prefilled with `"gpt-4o"` and
+ * saved it, so an install whose owner had configured a different provider was left holding
+ * `jx.ai.model: "gpt-4o"` and nothing else. A consumer that needs a fallback composes it where the
+ * fallbacks are known — see `ai-models.ts`'s `preferredModel`, which asks the backend what it
+ * prefers before reaching for a name invented here.
+ *
+ * @returns The stored value, or "" when none is stored.
+ */
+export function readStoredSetting(definition: SettingDefinition): string {
+  return values.get(definition.key) ?? "";
+}
+
+/** Whether a value is stored — as distinct from stored-and-empty, or absent-with-a-default. */
+export function hasSetting(definition: SettingDefinition): boolean {
+  return (values.get(definition.key) ?? "") !== "";
+}
+
+// ─── Change notification ──────────────────────────────────────────────────────
+
+const listeners = new Set<(keys: readonly string[]) => void>();
+
+/**
+ * Subscribe to settings changes, local or remote. Returns the unsubscribe.
+ *
+ * This is the seam that lets a surface hold no copy of a setting: the composer's model picker, the
+ * Accounts list and the New Project gates all read through the kernel and repaint on this, rather
+ * than each caching a value that another window can invalidate.
+ */
+export function onSettingsChanged(listener: (keys: readonly string[]) => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** Announce the keys that moved. Never called with an empty list. */
+function announce(keys: readonly string[]): void {
+  for (const listener of listeners) {
+    listener(keys);
+  }
+}
+
+// ─── Writing ──────────────────────────────────────────────────────────────────
+
+const queue = createWriteQueue({
+  onError(error: unknown) {
+    notify("error", "Your settings could not be saved.", {
+      detail: error instanceof Error ? error.message : String(error),
+      key: "settings-write",
+      source: "Settings",
+    });
+  },
+  async send(patch: SettingsPatch) {
+    if (!hasPlatform()) {
+      return;
+    }
+    const platform = getPlatform();
+    if (!platform.patchSettings) {
+      return;
+    }
+    /*
+     * Only the keys that actually moved go on the wire. A key this window never touched is one the
+     * backend leaves exactly as it found it — which is what stops a second window's settings being
+     * cleared by a window that happens to hold none of them.
+     *
+     * An empty value is sent as a REMOVAL. The store is what a fresh install reads back at boot, and
+     * `"jx.ai.model": ""` there would be a model choice rather than the absence of one.
+     */
+    const set: Record<string, string> = {};
+    const remove: string[] = [];
+    for (const [key, value] of Object.entries(patch)) {
+      if (value) {
+        set[key] = value;
+      } else {
+        remove.push(key);
+      }
+    }
+    await platform.patchSettings({ remove, set });
+  },
+});
+
+/** Resolves when every settings write made so far has been sent. */
+export function settingsSettled(): Promise<void> {
+  return queue.settled();
+}
+
+/**
+ * Apply a patch: `null` deletes, a string stores. Keys named by neither are untouched.
+ *
+ * Returns the keys that actually moved, so a no-op write announces nothing and schedules nothing.
+ */
+function apply(patch: SettingsPatch): string[] {
+  const moved: string[] = [];
+  for (const [key, next] of Object.entries(patch)) {
+    const before = values.get(key) ?? null;
+    if (before === next) {
+      continue;
+    }
+    if (next === null) {
+      values.delete(key);
+    } else {
+      values.set(key, next);
+    }
+    writeCache(key, next);
+    moved.push(key);
+  }
+  return moved;
+}
+
+/** Store a value. An empty string is a VALUE; {@link clearSetting} is the only deletion. */
+export function setSetting(definition: SettingDefinition, value: string): void {
+  const next = definition.normalize ? definition.normalize(value) : value;
+  const moved = apply({ [definition.key]: next });
+  if (moved.length > 0) {
+    queue.enqueue({ [definition.key]: next });
+    announce(moved);
+  }
+}
+
+/**
+ * Store several settings as one change — one announcement, one write.
+ *
+ * What a form's Save should call. Three separate `setSetting`s would coalesce into one write
+ * anyway, but they would announce three times, and each intermediate announcement describes a state
+ * the user never asked for.
+ */
+export function setSettings(entries: readonly [SettingDefinition, string][]): void {
+  const patch: SettingsPatch = {};
+  for (const [definition, value] of entries) {
+    patch[definition.key] = definition.normalize ? definition.normalize(value) : value;
+  }
+  const moved = apply(patch);
+  if (moved.length > 0) {
+    queue.enqueue(patch);
+    announce(moved);
+  }
+}
+
+/** Forget several settings as one change — the shape a Disconnect wants. */
+export function clearSettings(definitions: readonly SettingDefinition[]): void {
+  const patch: SettingsPatch = {};
+  for (const definition of definitions) {
+    patch[definition.key] = null;
+  }
+  const moved = apply(patch);
+  if (moved.length > 0) {
+    queue.enqueue(patch);
+    announce(moved);
+  }
+}
+
+// ─── Hydration ────────────────────────────────────────────────────────────────
+
+/**
+ * Reconcile with the backend store. Call once, after the platform is registered; a no-op on
+ * platforms without one (dev server, cloud), where the cache is all there is.
+ *
+ * Deliberately not awaited by the boot path — hydration must not block the first paint — which is
+ * safe because the Map is already serving cached values by then. Anything the backend holds wins;
+ * anything only this machine holds is pushed up once, so a user upgrading from a cache-only build
+ * does not lose what they had configured.
+ */
+export async function hydrateSettings(): Promise<void> {
+  if (!hasPlatform()) {
+    return;
+  }
+  const platform = getPlatform();
+  if (!platform.getSettings) {
+    return;
+  }
+  let stored: Record<string, string>;
+  try {
+    stored = await platform.getSettings();
+  } catch {
+    return;
+  }
+  const incoming: SettingsPatch = {};
+  let needsMigration = false;
+  for (const definition of USER_SETTINGS) {
+    const backendValue = stored[definition.key];
+    if (backendValue) {
+      incoming[definition.key] = backendValue;
+    } else if (values.get(definition.key)) {
+      needsMigration = true;
+    }
+  }
+  const moved = apply(incoming);
+  if (moved.length > 0) {
+    announce(moved);
+  }
+  if (needsMigration) {
+    /* Push this machine's cache-only values up, through the same queue as any other write so it
+       cannot race one the user is making at the same moment. Only the keys the backend lacks — a
+       patch says nothing about the rest, so hydration cannot echo back what it just read. */
+    const push: SettingsPatch = {};
+    for (const definition of USER_SETTINGS) {
+      const value = values.get(definition.key);
+      if (value && !stored[definition.key]) {
+        push[definition.key] = value;
+      }
+    }
+    queue.enqueue(push);
+  }
+}
+
+/**
+ * Adopt the backend store as another window (or a hand-edit) left it.
+ *
+ * Applied and announced, but never written back: this is news, not an edit, and echoing it would
+ * have two windows writing the same value at each other. A key the store no longer holds is
+ * forgotten here too, so a Disconnect in one window reaches the others.
+ *
+ * Self-echo needs no filter. Our own write reaches us through the same watch, and by then the
+ * values already match — {@link apply} reports nothing moved, so nothing is announced.
+ */
+export function adoptRemoteSettings(stored: Record<string, string>): void {
+  const patch: SettingsPatch = {};
+  for (const definition of USER_SETTINGS) {
+    patch[definition.key] = stored[definition.key] ?? null;
+  }
+  const moved = apply(patch);
+  if (moved.length > 0) {
+    announce(moved);
+  }
+}
+
+/**
+ * Subscribe to the backend store, if this platform can push. A no-op where it cannot.
+ *
+ * Called once at boot. The returned unsubscribe is not used — Studio boots this module once per
+ * window and never unwinds it — so it is deliberately dropped rather than stored somewhere nothing
+ * would read it.
+ */
+export function watchRemoteSettings(): void {
+  if (!hasPlatform()) {
+    return;
+  }
+  getPlatform().subscribeSettings?.(adoptRemoteSettings);
+}
+
+/**
+ * Drop every value this kernel holds, cache included.
+ *
+ * The `?profile=fresh` startup profile's half of the story: clearing `localStorage` alone left the
+ * Map — and the backend store — untouched, so "fresh" was not fresh. This does not write to the
+ * backend, because a clean profile must not destroy credentials that belong to the user rather than
+ * to the profile.
+ */
+export function resetSettings(): void {
+  const moved = [...values.keys()];
+  values.clear();
+  for (const key of moved) {
+    writeCache(key, null);
+  }
+  if (moved.length > 0) {
+    announce(moved);
+  }
+}

package/src/services/settings/write-queue.ts

@@ -0,0 +1,116 @@
+/**
+ * A coalescing, serializing write queue.
+ *
+ * The defect it exists to make unrepresentable: saving a provider mutates three settings through
+ * three setters, and each setter used to fire its own whole-map write. Three overlapping writes went
+ * out against one file, each reading storage at a different moment, with no ordering between them —
+ * so whichever landed last won. That was observed in the wild as a settings file holding
+ * `{"jx.ai.model": "gpt-4o"}`: the SECOND of three snapshots, landing last, a state storage itself
+ * never rested in.
+ *
+ * Two rules, and they are different guarantees:
+ *
+ * 1.  **Coalesce.** Every mutation in one synchronous burst merges into a single patch, sent once
+ *     the burst has finished. N setters produce one write, not N.
+ * 2.  **Serialize.** At most one send is in flight. A mutation made while one is out waits for it
+ *     rather than racing it, so the order the app made changes in is the order the store sees them.
+ *
+ * Generic over the transport so the kernel can hand it a platform call and a test can hand it an
+ * array. `schedule` is injectable for the same reason.
+ *
+ * @license MIT
+ */
+
+/**
+ * A set of changes to apply. `null` DELETES the key; a key named by neither map is left alone.
+ *
+ * That is the whole difference from the whole-map replace this supersedes: a writer that says
+ * nothing about a key cannot destroy it, so a window with a stale or empty view of settings can no
+ * longer clear a sibling window's.
+ */
+export type SettingsPatch = Record<string, string | null>;
+
+export interface WriteQueueOptions {
+  /** Deliver one merged patch. Rejection is reported through {@link WriteQueueOptions.onError}. */
+  send: (patch: SettingsPatch) => Promise<void>;
+  /** Called with the failure and the patch that did not land. */
+  onError?: (error: unknown, patch: SettingsPatch) => void;
+  /**
+   * Defer to the end of the current burst. Defaults to `queueMicrotask`.
+   *
+   * A microtask rather than a timer: the burst is synchronous, so the patch goes out in the same
+   * turn the user acted in, and nothing can observe a half-applied save.
+   */
+  schedule?: (run: () => void) => void;
+}
+
+export interface WriteQueue {
+  /** Merge `patch` into the pending one, scheduling a send if none is pending. */
+  enqueue: (patch: SettingsPatch) => void;
+  /** Resolves when everything enqueued so far has been sent (or has failed and been reported). */
+  settled: () => Promise<void>;
+}
+
+/**
+ * Create a queue over `send`.
+ *
+ * @param {WriteQueueOptions} opts
+ * @returns {WriteQueue}
+ */
+export function createWriteQueue(opts: WriteQueueOptions): WriteQueue {
+  const schedule = opts.schedule ?? queueMicrotask;
+
+  /** Merged changes not yet handed to `send`; null when nothing is waiting. */
+  let pending: SettingsPatch | null = null;
+
+  /**
+   * The chain every send is appended to.
+   *
+   * Always resolved — each link ends in a handler — so one failed write cannot poison the writes
+   * queued behind it.
+   */
+  let tail: Promise<void> = Promise.resolve();
+
+  /**
+   * Resolves when the most recently scheduled burst has been sent.
+   *
+   * Tracked explicitly rather than inferred from {@link tail}: a caller that enqueues and then
+   * awaits would otherwise be awaiting the tail as it stood BEFORE its own patch joined it, and
+   * whether that happens to work depends on how many turns the scheduler takes.
+   */
+  let idle: Promise<void> = Promise.resolve();
+
+  /** Hand the merged burst to `send`, appended to the chain. */
+  function flush(): Promise<void> {
+    const patch = pending;
+    pending = null;
+    if (!patch) {
+      return tail;
+    }
+    tail = tail
+      .then(() => opts.send(patch))
+      .catch((error: unknown) => {
+        opts.onError?.(error, patch);
+      });
+    return tail;
+  }
+
+  return {
+    enqueue(patch: SettingsPatch) {
+      if (pending) {
+        Object.assign(pending, patch);
+        return;
+      }
+      pending = { ...patch };
+      idle = new Promise<void>((resolve) => {
+        schedule(() => {
+          void flush().then(resolve);
+        });
+      });
+    },
+
+    settled() {
+      return idle;
+    },
+  };
+}

package/src/services/tool-executor.ts

@@ -28,9 +28,24 @@ import type { ToolRegistry } from "@jxsuite/ai/tools";
 import type { Tab } from "../tabs/tab";
 import { batchTab, beginBatch, endBatch } from "../tabs/transact";
 import { beginTurn, endTurn } from "./ai-writes";
+import { beginToolCall, beginTurnSignal, endTurnSignal } from "./ai-turn-signal";
 
 const MAX_ROUNDS = 5;
 
+/**
+ * Hard ceiling on rounds of every kind, so the loop terminates whatever the model does.
+ *
+ * {@link MAX_ROUNDS} bounds AUTONOMOUS work, and a round that ends by blocking on a person is the
+ * opposite of runaway — it cannot advance without them, which is the property the cap was ever a
+ * proxy for. So an interactive round does not spend that budget. This one is the backstop that
+ * keeps `runAgentLoop` provably terminating anyway; a human answering ten questions will have
+ * stopped it long before.
+ */
+const MAX_TOTAL_ROUNDS = 25;
+
+/** Tools that suspend the turn on a human rather than doing work. */
+const INTERACTIVE_TOOLS = new Set(["ask_user"]);
+
 interface RunAgentLoopOptions {
   chatState: ReturnType<typeof createChatState>;
   streamingClient: StreamingClient;
@@ -59,6 +74,11 @@ export async function runAgentLoop({
   const turnId = () => chatState.messages.at(-1)?.id ?? "";
   beginTurn(`turn:${chatState.messages.length}`);
 
+  /* The signal, published for the tools rather than passed to them: `ToolRegistry.execute` takes
+     none. Without it a tool that waits for a human never learns the turn was stopped, and the
+     `await` below is the whole loop. See services/ai-turn-signal.ts. */
+  beginTurnSignal(signal);
+
   // Batch all tool-call mutations into a single undo step, anchored on the tab being edited.
   if (getTab) {
     beginBatch(getTab());
@@ -83,7 +103,9 @@ export async function runAgentLoop({
   };
 
   try {
-    for (let round = 1; round <= MAX_ROUNDS; round++) {
+    /* Rounds that DID something, which is what MAX_ROUNDS bounds — see MAX_TOTAL_ROUNDS. */
+    let workRounds = 0;
+    for (let round = 1; round <= MAX_TOTAL_ROUNDS && workRounds < MAX_ROUNDS; round++) {
       const messages = chatState.toMessagesArray();
       const tools = toolRegistry.listForLLM();
 
@@ -144,8 +166,11 @@ export async function runAgentLoop({
         return;
       }
 
+      let didWork = false;
       for (const [id, call] of toolCalls) {
         let result;
+        // Published, not passed: `ToolRegistry.execute` takes the args and nothing else.
+        beginToolCall(id);
         try {
           const args = call.arguments ? (JSON.parse(call.arguments) as object) : {};
           result = await toolRegistry.execute(call.name, args);
@@ -155,6 +180,9 @@ export async function runAgentLoop({
             error: `Failed to parse arguments: ${(error as Error).message}`,
           };
         }
+        if (!INTERACTIVE_TOOLS.has(call.name)) {
+          didWork = true;
+        }
         reanchorBatch();
         if (!result.success && result.error) {
           allErrors.push(result.error);
@@ -166,7 +194,10 @@ export async function runAgentLoop({
         chatState.pushToolResultMessage(id, JSON.stringify(result));
       }
 
-      if (round < MAX_ROUNDS) {
+      if (didWork) {
+        workRounds += 1;
+      }
+      if (workRounds < MAX_ROUNDS && round < MAX_TOTAL_ROUNDS) {
         chatState.beginAssistantTurn();
       }
     }
@@ -196,6 +227,7 @@ export async function runAgentLoop({
     }
     chatState.setError(tail);
   } finally {
+    endTurnSignal();
     endBatch();
     endTurn(turnId());
   }

package/src/settings/contexts-section.ts

@@ -30,7 +30,7 @@
  * alone), parks any rejection under the control that caused it, and re-renders. §7.1's third tier:
  * a bad value belongs at its control, not in a toast that expires.
  *
- * @docs studio/projects/pages-layouts-components
+ * @docs studio/projects/settings
  */
 
 import { html, render as litRender, nothing } from "lit-html";
@@ -140,6 +140,15 @@ type ErrorTarget = string;
  */
 const errors = new WeakMap<HTMLElement, { target: ErrorTarget; message: string }>();
 
+/**
+ * Schema errors the file already had when this section last wrote to it.
+ *
+ * Reported at section level rather than under a control, because they belong to no control — and
+ * kept per container for the same reason {@link errors} is. Populated by the first write, since
+ * validating on every render would compile a schema for a section nobody is editing.
+ */
+const inheritedErrors = new WeakMap<HTMLElement, string[]>();
+
 /** Read the current failure for a container — exported for tests and for re-render helpers. */
 export function contextsError(container: HTMLElement): { target: string; message: string } | null {
   return errors.get(container) ?? null;
@@ -171,12 +180,26 @@ export function renderContextsSection(container: HTMLElement): void {
    * shape, and the disk can refuse the write. The predecessor surfaces (`Properties › Media` and
    * the CSS-variables "Enable dark scheme") did `void updateSiteConfig(...)` and dropped the
    * rejection, so a failed write read as the field snapping back for no reason.
+   *
+   * **Only the errors THIS edit introduces block it.** The candidate is the whole `project.json`,
+   * so a violation anywhere else in the file used to refuse every context edit and park the reason
+   * under whichever control had been touched — typing `1280px` into Base width reported three
+   * unevaluated-property errors about `title`, `description` and `$style`, none of which is a
+   * width. The baseline is validated first and subtracted, the same way `services/ai-tools.ts`
+   * subtracts it before blaming the model for a document it inherited. A pre-existing problem is
+   * still worth saying, so it is reported once at section level, where a whole-file problem belongs
+   * — and it is reported rather than repaired, because `project.json` is the author's file and a
+   * settings screen that silently drops keys it did not recognise is worse than one that names
+   * them.
    */
   const persistMedia = async (next: Record<string, string>, target: ErrorTarget) => {
     const candidate = { ...config, $media: next } as unknown;
     let schemaErrors: string[] = [];
+    let inherited: string[] = [];
     try {
-      schemaErrors = await validateProjectConfig(candidate);
+      inherited = await validateProjectConfig(config);
+      const found = await validateProjectConfig(candidate);
+      schemaErrors = found.filter((error) => !inherited.includes(error));
     } catch (error) {
       /* A validator that cannot compile must not block the edit — but it must not be silent
          either, so the message rides the same inline slot the schema errors would have used. */
@@ -187,6 +210,7 @@ export function renderContextsSection(container: HTMLElement): void {
       reject(target, schemaErrors.join("; "));
       return;
     }
+    inheritedErrors.set(container, inherited);
     try {
       await updateSiteConfig({ $media: next });
       errors.delete(container);
@@ -199,6 +223,24 @@ export function renderContextsSection(container: HTMLElement): void {
     renderContextsSection(container);
   };
 
+  /**
+   * What is already wrong with `project.json`, said once and not blamed on a control.
+   *
+   * It does not block anything — the edit that surfaced it went through. It is here because a file
+   * that fails its own schema will keep failing it, and until this notice existed the only place
+   * that fact appeared was as an unexplained refusal of an unrelated field.
+   */
+  const inheritedNotice = () => {
+    const inherited = inheritedErrors.get(container) ?? [];
+    return inherited.length === 0
+      ? nothing
+      : html`<p class="settings-section-notice" role="status">
+          project.json has ${inherited.length} pre-existing schema
+          ${inherited.length === 1 ? "problem" : "problems"} that this section did not cause:
+          ${inherited.join("; ")}
+        </p>`;
+  };
+
   /** The error line for one control, when that is where the current failure belongs. */
   const errorFor = (target: ErrorTarget) =>
     shown?.target === target
@@ -370,7 +412,7 @@ export function renderContextsSection(container: HTMLElement): void {
         The conditions this project's pages are rendered under. Define them once here; choose
         between them on the pane's context control while you edit.
       </p>
-      ${errorFor("section")}
+      ${errorFor("section")} ${inheritedNotice()}
 
       <div class="settings-field">
         <label class="settings-field-label">Base width</label>