@jxsuite/studio 4.0.0 → 5.0.0

package/src/services/ai-import-tools.ts

@@ -1,9 +1,10 @@
 /**
  * Ai-import-tools.ts — `import_site`, the assistant's other way to bootstrap a project.
  *
- * A sibling of `create_project` (`ai-project-tools.ts`) with a different backend: it drives the
- * headless-Chrome pipeline behind `POST /__studio/import-site`, streams its progress into a record
- * the transcript draws, and then adopts the result exactly as a scaffold is adopted. Its own module
+ * A sibling of `create_project` (`ai-project-tools.ts`) with a different backend: it drives whatever
+ * import pipeline the platform's `importSite` reaches — a local headless Chrome, or a hosted one —
+ * streams its progress into a record the transcript draws, and then adopts the result exactly as a
+ * scaffold is adopted. Its own module
  * rather than an eighth tool in `ai-project-tools.ts`, which is already 650 lines under a per-file
  * coverage bar.
  *
@@ -115,6 +116,40 @@ function isAbsolutePath(path: string): boolean {
   return /^(?:[a-zA-Z]:[/\\]|\/)/.test(path);
 }
 
+/**
+ * `owner/repo`, conservatively — the destination a `createDestination: "repo"` platform writes to.
+ *
+ * Narrower than GitHub's own rules on purpose: this guards a string the MODEL may supply, and the
+ * cost of refusing an exotic-but-legal name is one clarifying question, while the cost of accepting
+ * a path-shaped or query-shaped one is a request the backend has to defend against.
+ */
+const REPO_DESTINATION = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\/[A-Za-z0-9._-]+$/;
+
+/**
+ * Whether `destination` is a shape THIS platform can write to, or the sentence saying why not.
+ *
+ * The platform's `createDestination` decides, not the string's own look: a hosted backend creates a
+ * GitHub repository and has no filesystem to hold an absolute path, and a desktop backend has no
+ * repository to create. Answering by inspecting the string would accept `owner/repo` on desktop,
+ * where it silently means a relative directory nobody named.
+ *
+ * @param {string} destination - The resolved destination, from the model or the wizard's brief
+ * @returns {string | null} The refusal, or null when it is usable
+ */
+function destinationProblem(destination: string): string | null {
+  if (getPlatform().createDestination === "repo") {
+    if (!REPO_DESTINATION.test(destination)) {
+      return `"directory" must name a repository as "owner/repo": ${destination}`;
+    }
+  } else if (!isAbsolutePath(destination)) {
+    return `"directory" must be an absolute path: ${destination}`;
+  }
+  if (destination.split(/[/\\]/).includes("..")) {
+    return `"directory" must not contain "..": ${destination}`;
+  }
+  return null;
+}
+
 /**
  * One run has already succeeded in this session.
  *
@@ -242,8 +277,10 @@ export function registerImportTools(
           directory: {
             type: "string",
             description:
-              "Absolute destination folder. Omit it when an import was started from the New " +
-              "Project form — that destination is the one the user chose, and it wins.",
+              "Where the project goes, in whichever form this studio's backend uses: an absolute " +
+              'folder on a filesystem host, or "owner/repo" on a host where a project IS a ' +
+              "repository. Omit it when an import was started from the New Project form — that " +
+              "destination is the one the user chose, and it wins.",
           },
           depth: {
             type: "number",
@@ -361,15 +398,16 @@ export function registerImportTools(
         const destination = requested || brief?.directory || "";
         if (!destination) {
           return toolError(
-            'Pass "directory" — the absolute folder to create the project in. Ask the user where ' +
-              "the project should live rather than guessing.",
+            platform.createDestination === "repo"
+              ? 'Pass "directory" — the "owner/repo" to create the project as. Ask the user which ' +
+                  "account and repository name rather than guessing."
+              : 'Pass "directory" — the absolute folder to create the project in. Ask the user ' +
+                  "where the project should live rather than guessing.",
           );
         }
-        if (!isAbsolutePath(destination)) {
-          return toolError(`"directory" must be an absolute path: ${destination}`);
-        }
-        if (destination.split(/[/\\]/).includes("..")) {
-          return toolError(`"directory" must not contain "..": ${destination}`);
+        const problem = destinationProblem(destination);
+        if (problem) {
+          return toolError(problem);
         }
 
         const id = currentToolCallId();

package/src/services/ai-models.ts

@@ -20,6 +20,16 @@ import { onSettingsChanged } from "./settings/kernel";
 export interface AiModel {
   id: string;
   name: string;
+  /**
+   * Whether the backend says the model can call tools.
+   *
+   * Absent when it did not say, which is the ordinary case for a BYOK provider — only a managed
+   * catalogue knows. `false` is therefore a statement and `undefined` is silence, and no gate may
+   * collapse the two: a Workers AI chat-only model must be labelled, an OpenAI model must not.
+   */
+  toolSupport?: boolean;
+  /** The backend's declared context window in tokens, when it declares one. */
+  contextWindow?: number;
 }
 
 /**
@@ -74,6 +84,23 @@ let proxyCode: AiModelsResponse["code"];
 let proxyProbe: Promise<void> | null = null;
 const probeListeners = new Set<() => void>();
 
+/**
+ * How long a settled probe is trusted before a window refocus re-runs it.
+ *
+ * The probe is one-shot by construction (`proxyProbe ??=`) and the only thing that re-arms it is
+ * the settings subscription below — which never fires for a HOSTED grant, because nothing about it
+ * is stored in this browser. So a Cloudflare grant that lapsed mid-session left every gate showing
+ * the reading it took at boot: the assistant reported itself configured, and every send failed. Ten
+ * minutes is well inside the hour a Cloudflare access token lives.
+ */
+export const PROBE_STALE_MS = 600_000;
+
+/** When the probe last settled (0 = never). The age {@link PROBE_STALE_MS} is measured against. */
+let probeSettledAt = 0;
+
+/** Whether {@link installProbeRefresh} has already registered its listener. */
+let probeRefreshInstalled = false;
+
 /**
  * Drop the cached list and the capability reading.
  *
@@ -93,6 +120,7 @@ export function resetModelCache() {
      would strand every gate on a permanent "unconfigured, unmanaged" reading — ensureProxyProbe
      would no-op forever and the managed option would vanish until a full reload. */
   proxyProbe = null;
+  probeSettledAt = 0;
 }
 
 /** The keys whose value changes what a provider would answer with. */
@@ -117,6 +145,33 @@ export function cachedModels(credentials: AiCredentials): AiModel[] | null {
   return cache && cacheKey === fingerprint(credentials) ? cache : null;
 }
 
+/**
+ * A model's entry in whatever list is cached, by id.
+ *
+ * Deliberately NOT keyed by credentials, unlike {@link cachedModels}. That key exists because
+ * SHOWING one provider's catalogue under another's credentials is a lie about what is available;
+ * asking "what did the backend say about this id" is not — the answer is either recorded or it is
+ * not, and a mismatched key just yields `undefined`, which every caller already has to handle.
+ */
+function cachedModel(id: string): AiModel | undefined {
+  return cache?.find((model) => model.id === id);
+}
+
+/**
+ * Whether the backend said this model can call tools — `undefined` when it said nothing.
+ *
+ * The distinction is the whole point: a chat-only model is a legitimate choice, so this labels and
+ * warns rather than gating, and silence must read as "no opinion" rather than as "no tools".
+ */
+export function modelToolSupport(id: string): boolean | undefined {
+  return cachedModel(id)?.toolSupport;
+}
+
+/** The backend's declared context window for a model, in tokens — `undefined` when it declared none. */
+export function modelContextWindow(id: string): number | undefined {
+  return cachedModel(id)?.contextWindow;
+}
+
 /**
  * Run the capability probe once, repainting `onSettled` when it lands. Idempotent: concurrent and
  * repeated callers share the single in-flight fetch, and every registered host is notified. Probe
@@ -133,12 +188,50 @@ export function ensureProxyProbe(onSettled?: () => void) {
       // Unreachable proxy — the key gate stays up.
     })
     .then(() => {
+      probeSettledAt = Date.now();
       for (const notify of probeListeners) {
         notify();
       }
     });
 }
 
+/**
+ * Re-run the capability probe when it is older than {@link PROBE_STALE_MS} and the backend holds
+ * the credentials. Returns whether it re-armed, so a caller (and a test) can see that it did.
+ *
+ * Managed-only on purpose. A BYOK reading changes only when the stored key does, and the settings
+ * subscription already covers that; a hosted grant expires on a clock this browser cannot see.
+ */
+export function refreshStaleProbe(): boolean {
+  if (!proxyManaged || probeSettledAt === 0 || Date.now() - probeSettledAt < PROBE_STALE_MS) {
+    return false;
+  }
+  proxyProbe = null;
+  probeSettledAt = 0;
+  ensureProxyProbe();
+  return true;
+}
+
+/**
+ * Re-check the probe whenever the window regains focus, which is where a lapsed grant is noticed.
+ *
+ * `focus` rather than a timer: the reading only matters when somebody is looking at Studio, and the
+ * OAuth reconnect the stale reading would have hidden happens in another tab — so coming back IS
+ * the event. Idempotent, and a no-op outside a browser so the module stays importable under a
+ * bare-`bun` runner.
+ */
+export function installProbeRefresh(): void {
+  if (typeof window === "undefined" || probeRefreshInstalled) {
+    return;
+  }
+  probeRefreshInstalled = true;
+  window.addEventListener("focus", () => {
+    refreshStaleProbe();
+  });
+}
+
+installProbeRefresh();
+
 /**
  * Whether the assistant can run at all: a key stored in this browser, or a backend that holds
  * credentials itself (managed cloud platforms, env-keyed dev servers). Every credentials gate must
@@ -263,7 +356,21 @@ export async function fetchAvailableModels(
   proxyManaged = data.managed === true;
   proxyDefaultModel = data.defaultModel ?? "";
   proxyCode = data.code;
-  cache = (data.models || []).map((m) => ({ id: m.id, name: m.name || m.id }));
+  /* Capabilities are kept, not dropped. The backend has reported `toolSupport` all along and the
+     ingest mapped `{id, name}` only, so a Workers AI model that cannot call tools looked exactly
+     like one that can — the agent loop ran, called nothing, and answered as if that were normal.
+     The keys are OMITTED rather than set to undefined: absent means "the backend said nothing",
+     which is a third state both consumers depend on. */
+  cache = (data.models || []).map((m) => {
+    const model: AiModel = { id: m.id, name: m.name || m.id };
+    if (typeof m.contextWindow === "number") {
+      model.contextWindow = m.contextWindow;
+    }
+    if (typeof m.toolSupport === "boolean") {
+      model.toolSupport = m.toolSupport;
+    }
+    return model;
+  });
   cacheKey = key;
   return cache;
 }

package/src/services/ai-session-store.ts

@@ -45,6 +45,12 @@ export interface PersistedMessage {
   id?: string;
   role: string;
   content: string;
+  /**
+   * A thinking model's chain-of-thought for the turn. Persisted because the provider requires it
+   * back: a restored DeepSeek conversation whose reasoning was dropped on the way to storage is one
+   * the next send cannot replay (see `@jxsuite/ai`'s `toMessagesArray`).
+   */
+  reasoningContent?: string;
   toolCalls?: unknown[];
   toolCallId?: string;
   timestamp?: number;

package/src/services/ai-system-prompt.ts

@@ -29,6 +29,14 @@ interface BuildSystemPromptOptions {
    * prompt-shape tests — advertises the same list it always did.
    */
   treeEditable?: boolean | undefined;
+  /**
+   * The blurbs of the tools projected from command records this round —
+   * `services/ai-command-tools.ts`'s `commandToolBlurbs(activeRegistry())`. Rendered after the hand
+   * tools under every "Tools available right now" heading, one line each. Passed in rather than
+   * read here so this stays a pure function of its options: a caller that passes none sees the hand
+   * list it always did, and only `document-assistant.ts`, which holds the registry, adds them.
+   */
+  commandTools?: readonly string[] | undefined;
   /**
    * Whether the platform can import a site. Defaults TRUE so this stays a pure function of what it
    * is given — a caller that knows nothing about the platform gets the full list, and only
@@ -37,11 +45,32 @@ interface BuildSystemPromptOptions {
   canImport?: boolean | undefined;
   /** Project-relative file paths for the inventory section (project modes; capped). */
   fileInventory?: string[] | undefined;
+  /**
+   * What this backend can run, enabled or not.
+   *
+   * Passed in rather than read here, because it comes from the PLATFORM and this builder is a pure
+   * function of its options. Without it the model can only discover an extension by being told
+   * about one, which is how a request for a blog gets a hand-built Markdown pipeline instead of
+   * `@jxsuite/parser`.
+   */
+  extensionCatalog?: readonly ExtensionCatalogSummary[] | undefined;
+}
+
+/** One extension this backend can run — the prompt's view of a catalogue entry. */
+export interface ExtensionCatalogSummary {
+  name: string;
+  title?: string | undefined;
+  description?: string | undefined;
+  /** `project.json` keys that become legal once it is enabled. */
+  sections?: readonly string[] | undefined;
 }
 
 /** Max file paths embedded in the prompt's inventory section. */
 const FILE_INVENTORY_CAP = 100;
 
+/** Max catalogue entries listed in the prompt. */
+const EXTENSION_CATALOG_CAP = 20;
+
 // ─── Tool tiers (single source of truth for prompt AND gating) ──────────────
 
 /** Studio state a tool tier requires. Used by the gating registry AND the prompt tool list. */
@@ -54,9 +83,14 @@ const FILE_INVENTORY_CAP = 100;
  * with Project Settings open, `project.json` drawn as a layer tree. The assistant's tier asked only
  * whether a tab existed, so in that exact state the agent was advertised `remove_node` and
  * `move_node` and executed them against the file that defines the project, while the human's
- * `delete_node` was refused. `remove_node` self-refuses only the document root (`path.length < 2`),
+ * `delete_node` was refused. `remove_node` self-refused only the document root (`path.length < 2`),
  * a weaker test than `structurallyEditable`, so a repeater template or `$switch` case was removable
- * by the agent and not by the person.
+ * by the agent and not by the person. A tier was the first fix; the second predicate went with
+ * `remove_node` itself, which is now `delete_node`, the projection of `selection.delete`
+ * (`services/ai-command-tools.ts`) — one record, one gate, and no tier row here at all.
+ *
+ * This union is the HAND table's vocabulary and nothing a record declares: a projected command's
+ * tier is derived from its `level` by the bridge.
  */
 export type AiToolTier = "always" | "no-project" | "project" | "document" | "document-tree";
 
@@ -76,9 +110,15 @@ export interface AiToolInfo {
 }
 
 /**
- * Every assistant tool with its availability tier and prompt blurb. document-assistant.ts derives
- * the gating predicates from the same rows, so the advertised tool list and the executable tool
- * list cannot drift (a test asserts the names match the registered tools).
+ * Every HAND-REGISTERED assistant tool with its availability tier and prompt blurb.
+ * document-assistant.ts derives the gating predicates from the same rows, so the advertised tool
+ * list and the executable tool list cannot drift (a test asserts the names match the registered
+ * tools, and that none is also a command record's projection).
+ *
+ * The other kind of tool is not here and must not be added here: a command record that declares
+ * `aiTool` is projected by `services/ai-command-tools.ts`, gated by the record's own `when` /
+ * `enablement`, and described by the record. `enable_extension`, `disable_extension` and
+ * `delete_node` (né `remove_node`) left this table for that one.
  */
 export const AI_TOOL_TIERS: AiToolInfo[] = [
   // Always — a question is not gated on what happens to be open
@@ -181,11 +221,6 @@ export const AI_TOOL_TIERS: AiToolInfo[] = [
     blurb:
       "add_child(parentPath, index, node) — insert a new node into the children of parentPath at index.",
   },
-  {
-    name: "remove_node",
-    tier: "document-tree",
-    blurb: "remove_node(path) — remove the node at path.",
-  },
   {
     name: "move_node",
     tier: "document-tree",
@@ -644,17 +679,24 @@ export function buildSystemPrompt({
   hasProject = Boolean(projectRoot),
   treeEditable = true,
   canImport = true,
+  commandTools = [],
   fileInventory,
+  extensionCatalog,
 }: BuildSystemPromptOptions = {}) {
   const hasDocument = Boolean(document);
 
   // 1. Role, state-appropriate workflow, and the tool list for the current state.
   // The list the model is TOLD about and the list the gate will honour are the same filter, so a
-  // Refusal is never a surprise to it.
-  const toolList = AI_TOOL_TIERS.filter((t) =>
-    toolActive(t, { canImport, hasDocument, hasProject, treeEditable }),
-  )
-    .map((t) => `- ${t.blurb}`)
+  // Refusal is never a surprise to it. The command-projected tools arrive already filtered by
+  // Their records' own gates, for the same reason — one function answers both the prompt and the
+  // Executor (`advertisedCommandTools`).
+  const toolList = [
+    ...AI_TOOL_TIERS.filter((t) =>
+      toolActive(t, { canImport, hasDocument, hasProject, treeEditable }),
+    ).map((t) => t.blurb),
+    ...commandTools,
+  ]
+    .map((blurb) => `- ${blurb}`)
     .join("\n");
 
   const role = `You are an expert Jx builder assistant embedded in Jx Studio. You help users build websites, components, pages, and layouts using the Jx JSON schema. The live jxsuite.com marketing site is built entirely with Jx — you can produce production-quality Jx code.`;
@@ -722,7 +764,12 @@ Be concise. Don't explain what Jx is unless asked. Just build.`;
 
   // 6. Project context
   if (hasProject && (projectConfig || components || projectRoot)) {
-    const projectSummary = buildProjectSummary({ projectConfig, components, projectRoot });
+    const projectSummary = buildProjectSummary({
+      components,
+      extensionCatalog,
+      projectConfig,
+      projectRoot,
+    });
     if (projectSummary) {
       sections.push(`## Project Context\n\n${projectSummary}`);
     }
@@ -744,7 +791,7 @@ Be concise. Don't explain what Jx is unless asked. Just build.`;
 If a tool call fails (returns { success: false }):
 1. Read the error message carefully — it includes a "→ Fix:" hint telling you exactly how to correct the error.
 2. Each error points to a specific path in the document and a specific rule violation.
-3. Apply the suggested fix using set_property, remove_node, or add_child as appropriate.
+3. Apply the suggested fix using set_property, delete_node, or add_child as appropriate.
 4. Do NOT re-issue the exact same tool call with the same arguments — you must CHANGE something.
 5. If you see the SAME error after 2 attempts, try a completely different approach (e.g., remove and re-add the node instead of patching it).
 
@@ -762,7 +809,7 @@ If a tool call fails (returns { success: false }):
 
 ### If you keep getting errors:
 - Call read_document again — the document may have changed since you last read it.
-- Remove the problematic node entirely with remove_node, then re-create it correctly with add_child.
+- Remove the problematic node entirely with delete_node, then re-create it correctly with add_child.
 - If the error message points to a different path than you expected, the node might have moved due to previous edits.`);
 
   return sections.join("\n\n---\n\n");
@@ -841,6 +888,7 @@ function buildProjectSummary({
   projectConfig,
   components,
   projectRoot,
+  extensionCatalog,
 }: Omit<BuildSystemPromptOptions, "document">) {
   const lines: string[] = [];
 
@@ -852,6 +900,13 @@ function buildProjectSummary({
     lines.push(`Root: ${projectRoot}`);
   }
 
+  /* One line, closing a gap that was pure oversight: this function has always received the whole
+     `projectConfig`, `extensions` included, and dropped it on the floor. */
+  const enabled = projectConfig?.extensions ?? [];
+  if (enabled.length > 0) {
+    lines.push(`Extensions enabled: ${enabled.join(", ")}`);
+  }
+
   // Available components — tag + purpose so the model can reuse them
   if (components && components.length > 0) {
     lines.push(`Available components (reuse these instead of rebuilding):`);
@@ -898,6 +953,43 @@ function buildProjectSummary({
     }
   }
 
+  /*
+   * The catalogue, last, so the design-token block keeps its prominence. The guidance names
+   * CAPABILITIES rather than packages on purpose: the capability-to-package mapping is what each
+   * entry's own description is for, and hardcoding "@jxsuite/parser" here would be a second,
+   * staler copy of the backend's answer.
+   */
+  if (extensionCatalog && extensionCatalog.length > 0) {
+    const enabledSet = new Set(enabled);
+    lines.push(
+      `Extensions available. Turn one on with enable_extension BEFORE writing the project.json ` +
+        `section it owns: a section belonging to a disabled extension is a schema error, and an ` +
+        `"extensions" entry whose package is not installed fails the build. When a request needs ` +
+        `a capability the core does not have (a blog or any folder of Markdown, a search box, a ` +
+        `feed, sign-ins, a database table), look for it below rather than hand-building it.`,
+    );
+    for (const entry of extensionCatalog.slice(0, EXTENSION_CATALOG_CAP)) {
+      const parts = [`  ${entry.name}`];
+      if (entry.title) {
+        parts.push(` — ${entry.title}.`);
+      }
+      if (entry.description) {
+        parts.push(` ${entry.description}`);
+      }
+      if (entry.sections && entry.sections.length > 0) {
+        parts.push(` Contributes: ${entry.sections.join(", ")}.`);
+      }
+      if (enabledSet.has(entry.name)) {
+        parts.push(" [enabled]");
+      }
+      lines.push(parts.join(""));
+    }
+    if (extensionCatalog.length > EXTENSION_CATALOG_CAP) {
+      const more = extensionCatalog.length - EXTENSION_CATALOG_CAP;
+      lines.push(`  … and ${more} more (open_settings { section: "extensions" })`);
+    }
+  }
+
   // Breakpoints — surfaced prominently so the model uses @--breakpoint responsive overrides
   if (projectConfig?.$media) {
     const breakpoints = Object.entries(projectConfig.$media)