@jxsuite/studio 8.1.0 → 10.0.0

package/src/platforms/cloud.ts

@@ -7,8 +7,9 @@
  * before Studio boots — while project-less mode (null) powers the /studio welcome screen.
  *
  * Cloud omissions (Studio degrades per @jxsuite/protocol's route table): pickDirectory, package
- * install/outdated/set-versions (package ops are manifest-only edits), multi-window, gitClone,
- * resolveClass, component discovery, code services.
+ * install and the install-on-open check (a cloud session has no `node_modules`; add, remove and
+ * set-versions update `package.json` and `package-lock.json` through the session's package
+ * service), multi-window, gitClone, resolveClass, component discovery, code services.
  */
 
 import { negotiateCollab } from "@jxsuite/collab/negotiate";
@@ -43,6 +44,8 @@ import type {
   ImportSiteOptions,
   OfferedAction,
   PackageInfo,
+  PackageOpResult,
+  PackageVersionInfo,
   ProjectListEntry,
   SiteBuildResult,
   ProjectSchemasResponse,
@@ -947,17 +950,6 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
     }
   }
 
-  async function writePackageJson(pkg: JsonObject): Promise<void> {
-    const res = await api("/file", {
-      method: "PUT",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ path: "package.json", content: `${JSON.stringify(pkg, null, 2)}\n` }),
-    });
-    if (!res.ok) {
-      throw new Error(await errorMessage(res, "Failed to update package.json"));
-    }
-  }
-
   // The bound session's /raw tree; see `documentBaseUrl` below for why both members ride together.
   const repoAssets: Pick<StudioPlatform, "assetSpace" | "documentBaseUrl"> = {};
   if (base) {
@@ -1284,10 +1276,12 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
      *
      * A Worker ships a fixed set of extension packages (specs/extensions.md §5.5), decided by the
      * platform build rather than by this repository's `extensions/` tree, so the gateway is the
-     * only thing that knows. Everything it returns is therefore `bundled: true`: enabling one is a
-     * `project.json` write alone, and an extension the Worker does not bundle is dropped from the
-     * registry before composition — advertising it would promise a toggle that silently does
-     * nothing.
+     * only thing that knows. An extension the Worker does not bundle is dropped from the registry
+     * before composition, so advertising it would promise a toggle that silently does nothing.
+     *
+     * What the Worker bundles is what it can EDIT with, not what the project gets: the site is
+     * built in Pages CI from the project's own install, so an entry the project has not declared is
+     * install-then-enable here exactly as on every other backend (specs/extensions.md §3).
      *
      * `installed` here means DECLARED. Nothing resolves a module in a Worker: `addPackage` is a
      * manifest edit and resolution happens later in Pages CI, so the manifest is the only fact this
@@ -1309,7 +1303,6 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
           ...Object.keys(dependencyBlock(pkg, "devDependencies")),
         ]);
         for (const entry of entries) {
-          entry.bundled = true;
           entry.installed = declared.has(entry.name);
         }
         return entries;
@@ -1435,28 +1428,49 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
       return null;
     },
 
-    // ─── Packages (manifest-only edits; resolution happens in Pages CI) ───
+    // ─── Packages (the session's lockfile service; nothing installs) ───
 
+    /* Each mutation runs npm's installer lockfile-only on the platform, which writes
+       `package.json` and `package-lock.json` back into the shared tree as one change, so a commit
+       carries a lockfile a build can install from frozen (server.md §4.1). A failure changes
+       nothing and its message names the cause. */
     async addPackage(name: string) {
-      const pkg = await readPackageJson();
-      const deps = dependencyBlock(pkg, "dependencies");
-      const at = name.lastIndexOf("@");
-      const [pkgName, version] =
-        at > 0 ? [name.slice(0, at), name.slice(at + 1)] : [name, "latest"];
-      deps[pkgName] = version;
-      pkg["dependencies"] = deps;
-      await writePackageJson(pkg);
+      const res = await api("/packages/add", {
+        body: JSON.stringify({ name }),
+        headers: { "Content-Type": "application/json" },
+        method: "POST",
+      });
+      if (!res.ok) {
+        throw new Error(await errorMessage(res, `Failed to add ${name}`));
+      }
     },
 
     async removePackage(name: string) {
-      const pkg = await readPackageJson();
-      for (const key of ["dependencies", "devDependencies"]) {
-        const deps = pkg[key];
-        if (isJsonObject(deps) && name in deps) {
-          pkg[key] = Object.fromEntries(Object.entries(deps).filter(([dep]) => dep !== name));
-        }
+      const res = await api("/packages/remove", {
+        body: JSON.stringify({ name }),
+        headers: { "Content-Type": "application/json" },
+        method: "POST",
+      });
+      if (!res.ok) {
+        throw new Error(await errorMessage(res, `Failed to remove ${name}`));
+      }
+    },
+
+    async setPackageVersions(updates: { name: string; version: string; dev?: boolean }[]) {
+      const res = await api("/packages/set-versions", {
+        body: JSON.stringify({ updates }),
+        headers: { "Content-Type": "application/json" },
+        method: "POST",
+      });
+      if (!res.ok) {
+        return { log: await errorMessage(res, "Failed to update versions"), ok: false };
       }
-      await writePackageJson(pkg);
+      return readJson<PackageOpResult>(res);
+    },
+
+    async packageVersions() {
+      const res = await api("/packages/versions");
+      return res.ok ? readJson<PackageVersionInfo[]>(res) : [];
     },
 
     async listPackages(): Promise<PackageInfo[]> {

package/src/platforms/devserver.ts

@@ -2,18 +2,16 @@
  * Devserver.js — Dev Server Platform Adapter
  *
  * Implements the StudioPlatform interface for the @jxsuite/server development workflow. All file
- * I/O goes through /__studio/* REST endpoints. Project opening uses the Chrome File System Access
- * API (showDirectoryPicker).
+ * I/O goes through /__studio/* REST endpoints. There is no Open Project: a dev-server window opens
+ * a project from its `?project=` URL parameter (specs/desktop.md §8.2).
  *
  * See spec/desktop.md §8 for the full specification.
  */
 
 import { streamImport } from "../services/import-client";
-import { canPickDirectory, pickDirectoryPath } from "../services/directory-picker";
 import { negotiateCollab } from "@jxsuite/collab/negotiate";
 import type { CollabNegotiation } from "@jxsuite/collab/negotiate";
 import type { WsCollabConnection } from "@jxsuite/collab/client";
-import { isFunction } from "@jxsuite/schema/guards";
 import type { JsonObject, JsonValue, JxMutableNode, ProjectConfig } from "@jxsuite/schema/types";
 import type {
   DataConnectionsResponse,
@@ -80,16 +78,6 @@ interface FsEventBatch {
   events?: FsEvent[];
 }
 
-/** `showDirectoryPicker()` (WICG File System Access), which only Chromium-based browsers expose. */
-type ShowDirectoryPicker = (options: { mode: string }) => Promise<FileSystemDirectoryHandle>;
-
-/** True when the window implements the File System Access directory picker. */
-function hasDirectoryPicker(
-  host: Window,
-): host is Window & { showDirectoryPicker: ShowDirectoryPicker } {
-  return "showDirectoryPicker" in host && isFunction(host.showDirectoryPicker);
-}
-
 /** The options object {@link StudioPlatform.createProject} takes. */
 type CreateProjectOptions = Parameters<StudioPlatform["createProject"]>[0];
 
@@ -225,36 +213,6 @@ export function createDevServerPlatform() {
     return p.startsWith(`${_projectRoot}/`) ? p.slice(_projectRoot.length + 1) : p;
   }
 
-  /**
-   * Native folder chooser for the New Project modal's Browse… button. Present only when the browser
-   * implements `showDirectoryPicker` (Chromium-based); elsewhere the member stays undefined and the
-   * modal falls back to a typed Location field.
-   *
-   * The picked handle carries no filesystem path, so it is resolved by the id the picker tags the
-   * folder with (see `@jxsuite/studio/directory-picker`). Resolves `null` only when the user
-   * dismisses the chooser; every other failure rejects with a sentence the modal shows under
-   * Location. So `locate` keeps the helper's contract: `null` is "no folder holds this id" (the
-   * route's 200 `{ path: null }`), and a non-ok answer throws the problem the server sent rather
-   * than posing as a miss. A network failure (`TypeError: Failed to fetch`, e.g. a page that is not
-   * being served by the dev server at all) propagates as is, and the picker names it.
-   */
-  const directoryPicking: Pick<StudioPlatform, "pickDirectory"> = {};
-  if (canPickDirectory()) {
-    directoryPicking.pickDirectory = async (): Promise<string | null> =>
-      pickDirectoryPath(async ({ id, name }) => {
-        const res = await fetch(
-          `/__studio/locate-directory?name=${encodeURIComponent(name)}&id=${encodeURIComponent(id)}`,
-        );
-        if (!res.ok) {
-          // A proxy, or a `views://` host with no dev server behind it, may answer in HTML.
-          const body = await readJson<JsonValue>(res).catch(() => null);
-          throw new Error(problemMessage(body, res.status));
-        }
-        const found = await readJson<{ path?: string | null }>(res);
-        return found.path ?? null;
-      });
-  }
-
   return {
     id: "devserver",
 
@@ -293,80 +251,6 @@ export function createDevServerPlatform() {
       await postActivate(root ?? _projectRoot);
     },
 
-    // ─── Project opening ──────────────────────────────────────────────────
-
-    async openProject() {
-      // Use Chrome's showDirectoryPicker API
-      const host = window;
-      if (!hasDirectoryPicker(host)) {
-        throw new Error("showDirectoryPicker not available — use a Chromium-based browser");
-      }
-
-      let dirHandle;
-      try {
-        dirHandle = await host.showDirectoryPicker({ mode: "readwrite" });
-      } catch (error) {
-        // User cancelled the picker
-        if (error instanceof Error && error.name === "AbortError") {
-          return null;
-        }
-        throw error;
-      }
-
-      // Read project.json from the chosen directory
-      let siteHandle;
-      try {
-        siteHandle = await dirHandle.getFileHandle("project.json");
-      } catch {
-        throw new Error("No project.json found in selected folder");
-      }
-
-      const file = await siteHandle.getFile();
-      /* SAFETY: the user picked this folder as a project, and project.json is that project's own
-         config file; it is matched below against the server's parse of the same file, and every
-         adapter hands project.json to Studio as the ProjectConfig the session edits. */
-      const config = JSON.parse(await file.text()) as ProjectConfig;
-
-      // Resolve server-relative path by matching against known sites
-      const sitesRes = await fetch("/__studio/sites");
-      if (!sitesRes.ok) {
-        throw new Error("Failed to fetch site list from server");
-      }
-      const sites = await readJson<SiteEntry[]>(sitesRes);
-      const match = sites.find(
-        (s: SiteEntry) => JSON.stringify(s.config) === JSON.stringify(config),
-      );
-
-      if (!match) {
-        // Project is outside dev server root — ask the server to find it by directory name
-        const findRes = await fetch(
-          `/__studio/find-project?name=${encodeURIComponent(dirHandle.name)}`,
-        );
-        if (!findRes.ok) {
-          throw new Error("Could not locate project on disk");
-        }
-        const found = await readJson<{ path?: string }>(findRes);
-        if (!found.path) {
-          throw new Error(`Could not find project directory "${dirHandle.name}"`);
-        }
-        _projectRoot = found.path;
-      } else {
-        _projectRoot = match.path;
-      }
-
-      // Notify server of active project for static file resolution
-      await this.activate();
-
-      return {
-        config,
-        handle: {
-          name: config.name || _projectRoot.split("/").pop()!,
-          projectConfig: config,
-          root: _projectRoot,
-        },
-      };
-    },
-
     /**
      * Probe the server root to see if it is itself a site project. Used at startup to auto-detect
      * projects.
@@ -408,8 +292,6 @@ export function createDevServerPlatform() {
       return await res.json();
     },
 
-    ...directoryPicking,
-
     /** List starter templates from the dev server. */
     async listStarters(): Promise<StarterInfo[]> {
       const res = await fetch("/__studio/starters");

package/src/services/ai-ask.ts

@@ -1,12 +1,10 @@
 /**
  * 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.
+ * `ask_user` declares what it asks (`interaction`) and what its answer means (`settle`), and has no
+ * body that waits: the invoker answers `needs_input` before any tool code runs, the turn engine
+ * puts the question to the assistant's interaction store (`harness/interaction-store.ts`), and the
+ * person's answer comes back through `settle` as the call's result (specs/ai.md §3.4 and §3.11).
  *
  * Two decisions are load-bearing and easy to get wrong on a rewrite:
  *
@@ -17,29 +15,16 @@
  *   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 { JX_TOOL_FACTS } from "@jxsuite/ai/jx-tools";
 import { createToolDefinition, toolError, toolSuccess } from "@jxsuite/ai/tools";
 import { isString } from "@jxsuite/schema/guards";
-import { reactive } from "../reactivity";
-
-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;
-}
+import type { InteractionResponse, ToolRegistry } from "@jxsuite/ai/tools";
 
-/** How a question was settled. `answer: null` with `skipped` is the author saying "you decide". */
+/** What a settled question's result carries: the answer, or `null` with `skipped` for "you decide". */
 export interface AskAnswer {
   answer: string | null;
   skipped: boolean;
@@ -48,112 +33,6 @@ export interface AskAnswer {
 /** 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
- * @param {AbortSignal} [signal] - The asking call's signal. Without one the question can still be
- *   settled by {@link cancelAsk}, but a Stop would leave the turn awaiting a promise nothing could
- *   resolve.
- * @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, signal?: AbortSignal): Promise<AskAnswer> {
-  return new Promise<AskAnswer>((resolve) => {
-    state.pending = ask;
-    settle = resolve;
-
-    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.
  *
@@ -163,24 +42,12 @@ export function resetAsk(): void {
  *
  * @param {Pick<ToolRegistry, "register">} registry
  */
-/** What the host that registers the question tool may hook. */
-export interface AskToolOptions {
-  /**
-   * Called once a question has been put to the author, before the turn waits on the answer. A host
-   * saves the conversation here: a turn suspended on a person may wait for as long as they like,
-   * and a reload in the meantime must still find the question to restore as open (`specs/ai.md`
-   * §3.4).
-   */
-  onPending?: () => void;
-}
-
-export function registerAskTool(
-  registry: Pick<ToolRegistry, "register">,
-  { onPending }: AskToolOptions = {},
-): void {
+export function registerAskTool(registry: Pick<ToolRegistry, "register">): void {
   registry.register(
     createToolDefinition({
       name: "ask_user",
+      title: "Ask the user",
+      annotations: JX_TOOL_FACTS.ask_user.annotations,
       // It suspends the turn on the author, so a round that only asked spends no work budget.
       interactive: true,
       description:
@@ -212,43 +79,32 @@ export function registerAskTool(
         },
         required: ["question"],
       },
-      execute: async (args, ctx) => {
+      interaction(args) {
         /* Every field is any JSON value, narrowed by a guard 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. */
+           `validate()` is "a lightweight structural check, not a JSON Schema validator", 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;
         if (!isString(question) || !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.");
+          return { refusal: 'Pass "question" — the question to put to the user.' };
         }
         const choices = Array.isArray(options)
           ? options
               .filter((o): o is string => isString(o) && o.trim().length > 0)
               .slice(0, MAX_OPTIONS)
           : [];
-
-        const answering = askUser(
-          {
-            context: isString(context) ? 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: ctx.callId,
-            options: choices,
-            question: question.trim(),
-          },
-          ctx.signal,
-        );
-        // The question is published by now (`askUser` sets it synchronously); the answer is not.
-        if (isAwaitingAnswer()) {
-          onPending?.();
-        }
-        const { answer, skipped } = await answering;
-
+        return {
+          context: isString(context) ? context.trim() : "",
+          kind: "question",
+          options: choices,
+          question: question.trim(),
+        };
+      },
+      settle(_args, response) {
+        /* SAFETY: `ask_user` only ever asks a question, so the response the invoker hands back is
+           the answer to one. */
+        const { answer, skipped } = response as Extract<InteractionResponse, { kind: "question" }>;
         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. */
@@ -262,6 +118,8 @@ export function registerAskTool(
         }
         return toolSuccess({ answer, skipped: false }, `The user answered: "${answer}"`);
       },
+      // Never reached through the invoker, which settles an interaction instead of executing it.
+      execute: () => toolError("ask_user needs a person, and none is available here."),
     }),
   );
 }