@jxsuite/studio 2.4.3 → 4.0.0

package/src/services/context-manager.ts

@@ -198,3 +198,92 @@ export function trimContext(
 
   return { estimatedTokens: newTotal, droppedCount };
 }
+
+// ─── Orphaned tool calls ────────────────────────────────────────────────────
+
+/** What a synthesized result says, so a reader and the model see the same reason. */
+const UNANSWERED_TOOL_RESULT = JSON.stringify({
+  success: false,
+  error:
+    "This tool call was never completed — the session was reloaded or the history was trimmed.",
+});
+
+/**
+ * Repair tool-call pairing in place, and report how many messages it touched.
+ *
+ * `toMessagesArray()` serializes the array verbatim: an assistant message with `tool_calls` becomes
+ * a `tool_calls` request, and a `tool` message becomes a reply carrying `tool_call_id`. Providers
+ * require the two to come in pairs, and **three ordinary things break the pairing**:
+ *
+ * 1. `saveSession` persists `msgs.slice(-MAX_PERSIST_MESSAGES)` and `restoreChat` pushes the result
+ *    back, so a session longer than the cap can be restored starting mid-pair.
+ * 2. {@link trimContext} splices from the front for the token budget, with no more regard for pairs.
+ * 3. A turn that stopped while a tool was still running — which `ask_user` makes routine, because its
+ *    tool is _designed_ to be outstanding — leaves a request with no reply.
+ *
+ * Each of those produced a 400 on the NEXT send, from a conversation the user could see was fine.
+ * So the repair belongs on the send path, after trimming, rather than at any one of the three
+ * sites: a request with no reply gets a synthesized failure (keeping the assistant's text, which
+ * dropping the message would lose), and a reply with no request is dropped.
+ *
+ * @param {ReturnType<typeof createChatState>} chatState
+ * @returns {{ sealed: number; dropped: number }}
+ */
+export function pruneOrphanToolMessages(chatState: ReturnType<typeof createChatState>): {
+  sealed: number;
+  dropped: number;
+} {
+  const { messages } = chatState;
+
+  const requested = new Set<string>();
+  const answered = new Set<string>();
+  for (const msg of messages) {
+    if (msg.role === "assistant" && msg.toolCalls) {
+      for (const call of msg.toolCalls) {
+        requested.add(call.id);
+      }
+    } else if (msg.role === "tool" && msg.toolCallId) {
+      answered.add(msg.toolCallId);
+    }
+  }
+
+  // Replies with no request, and replies with no id at all — neither can be serialized into a
+  // Well-formed pair, and a reply is the half that carries no author text worth keeping.
+  let dropped = 0;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i]!;
+    if (msg.role === "tool" && (!msg.toolCallId || !requested.has(msg.toolCallId))) {
+      messages.splice(i, 1);
+      dropped += 1;
+    }
+  }
+
+  /* Requests with no reply. Walk backwards so each insertion is past the indices still to visit,
+     and seal immediately after the requesting message — `toMessagesArray` emits in array order, so
+     that is the only position the pair is adjacent in. */
+  let sealed = 0;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i]!;
+    if (msg.role !== "assistant" || !msg.toolCalls) {
+      continue;
+    }
+    const missing = msg.toolCalls.filter((call) => !answered.has(call.id));
+    if (missing.length === 0) {
+      continue;
+    }
+    messages.splice(
+      i + 1,
+      0,
+      ...missing.map((call, n) => ({
+        content: UNANSWERED_TOOL_RESULT,
+        id: `sealed_${call.id}_${n}`,
+        role: "tool" as const,
+        timestamp: msg.timestamp,
+        toolCallId: call.id,
+      })),
+    );
+    sealed += missing.length;
+  }
+
+  return { dropped, sealed };
+}

package/src/services/document-assistant.ts

@@ -20,14 +20,18 @@ import type { Tab } from "../tabs/tab";
 import { componentRegistry } from "../files/components";
 import { activeRegistry } from "../commands/active-registry";
 import { registerAiTools } from "./ai-tools";
+import { cancelAsk, registerAskTool, resetAsk } from "./ai-ask";
 import { registerProjectTools } from "./ai-project-tools";
+import { registerImportTools, resetImportGuard } from "./ai-import-tools";
 import { createGatedToolRegistry } from "./gated-registry";
 import type { ToolAvailability } from "./gated-registry";
 import { adoptProject } from "./project-adoption";
+import { abortImportRun, resetImportRuns } from "./import-run";
 import { runAgentLoop } from "./tool-executor";
-import { AI_TOOL_TIERS, buildSystemPrompt, tierActive } from "./ai-system-prompt";
-import { getBaseUrl, getModel, getOpenAiKey } from "./ai-settings";
-import { trimContext } from "./context-manager";
+import { AI_TOOL_TIERS, buildSystemPrompt, toolActive } from "./ai-system-prompt";
+import { getBaseUrl, getOpenAiKey } from "./ai-settings";
+import { preferredModel } from "./ai-models";
+import { pruneOrphanToolMessages, trimContext } from "./context-manager";
 import { renderCheck } from "./render-critic";
 import { openFileInTab, reloadFileInTab } from "../files/files";
 import { refreshExtensionUi } from "../format/format-host";
@@ -58,7 +62,7 @@ function projectRoot() {
  * }}
  */
 export function createDocumentAssistant() {
-  const chatState = createChatState({ model: getModel() });
+  const chatState = createChatState({ model: preferredModel() });
 
   /** The persisted session backing the live chat; null = fresh unsaved chat. */
   let sessionId: string | null = null;
@@ -76,6 +80,8 @@ export function createDocumentAssistant() {
   };
 
   const innerRegistry = createToolRegistry();
+  // Ungated: a question is not a function of what happens to be open.
+  registerAskTool(innerRegistry);
   registerAiTools(innerRegistry, {
     getTab: () => activeTab.value,
     saveFile: async (relPath: string, content: string) => {
@@ -90,6 +96,17 @@ export function createDocumentAssistant() {
     findOpenTab,
     reloadTab: reloadFileInTab,
   });
+  registerImportTools(innerRegistry, {
+    adoptProject,
+    getTab: () => activeTab.value,
+    // Same re-keying as `create_project`: an import bootstraps a project, so the bootstrap
+    // Conversation has to follow it out of the unscoped store.
+    onProjectAdopted: (root: string) => {
+      if (sessionId) {
+        sessionStore.moveSession("", root, sessionId);
+      }
+    },
+  });
   registerProjectTools(innerRegistry, {
     getTab: () => activeTab.value,
     renderCheck: renderCheck as (
@@ -125,6 +142,9 @@ export function createDocumentAssistant() {
    * every agent-loop round, so a mid-loop create_project unlocks the higher tiers immediately.
    */
   const TIER_REQUIREMENTS = {
+    /* Never refused, so the sentence is unreachable — it exists because the map is derived from
+       the tier union, and a tier without one would not compile. */
+    always: "nothing",
     "no-project": "no project to be open (it bootstraps one)",
     project: "an open project",
     document: "an open document (use open_document first)",
@@ -154,12 +174,18 @@ export function createDocumentAssistant() {
       t.name,
       {
         when: () =>
-          tierActive(t.tier, {
+          toolActive(t, {
+            /* The platform's own answer, read live rather than captured: the assistant is
+               constructed at module load, before a platform is registered in some hosts. */
+            canImport: Boolean(getPlatform().importSite),
             hasDocument: Boolean(activeTab.value),
             hasProject: Boolean(workspace.projectRoot),
             treeEditable: treeEditable(),
           }),
-        requires: TIER_REQUIREMENTS[t.tier],
+        requires:
+          t.capability === "importSite"
+            ? "a platform with a site-import backend"
+            : TIER_REQUIREMENTS[t.tier],
       },
     ]),
   );
@@ -181,6 +207,7 @@ export function createDocumentAssistant() {
       components: componentRegistry.length > 0 ? componentRegistry : undefined,
       projectRoot: workspace.projectRoot || undefined,
       hasProject: Boolean(workspace.projectRoot),
+      canImport: Boolean(getPlatform().importSite),
       ...(inventory && inventory.length > 0 ? { fileInventory: inventory } : {}),
     });
   }
@@ -204,6 +231,11 @@ export function createDocumentAssistant() {
       chatState.setTokenCount(trimmed.estimatedTokens);
     }
 
+    /* AFTER the trim, not before: the trim splices from the front and is itself one of the three
+       ways a tool_calls request loses its reply (see pruneOrphanToolMessages). Repairing first
+       would leave the very pair the trim then broke. */
+    pruneOrphanToolMessages(chatState);
+
     // Persist after trimming so the saved history reflects what's actually sent.
     persistChat();
 
@@ -212,7 +244,7 @@ export function createDocumentAssistant() {
       const chatUrl = await Promise.resolve(plat.aiChatUrl());
       // Re-read the persisted model each send: the session is constructed once at module load
       // (before the user sets a key/model), so the picker's choice must be picked up here.
-      chatState.setModel(getModel());
+      chatState.setModel(preferredModel());
       const streamingClient = createProxyStreamingClient({
         chatUrl,
         model: chatState.model,
@@ -247,11 +279,19 @@ export function createDocumentAssistant() {
 
   function stop() {
     controller?.abort();
+    /* The abort settles an outstanding question through the turn signal, but only when the turn
+       HAS one — the evals runner and several tests drive the loop without. Settling here as well
+       is what makes Stop terminal in every case rather than in most of them. */
+    cancelAsk();
+    abortImportRun();
     chatState.cancelStream();
   }
 
   function newChat() {
     stop();
+    resetAsk();
+    resetImportRuns();
+    resetImportGuard();
     chatState.clearChat();
     sessionId = null;
     sessionStore.setActiveSession(projectRoot(), null);
@@ -271,6 +311,7 @@ export function createDocumentAssistant() {
       return;
     }
     stop();
+    resetAsk();
     chatState.clearChat();
     pushRestoredMessages(msgs);
     sessionId = id;
@@ -282,6 +323,7 @@ export function createDocumentAssistant() {
     sessionStore.deleteSession(projectRoot(), id);
     if (sessionId === id) {
       stop();
+      resetAsk();
       chatState.clearChat();
       sessionId = null;
     }

package/src/services/idle.ts

@@ -27,6 +27,9 @@
  *    duplicate of `platform`: an activity spans a whole operation (an install, a deploy, a clone)
  *    across many PAL calls, so the gaps between them look quiet at the seam while the operation is
  *    plainly mid-flight. A finished entry never blocks — the list stays on screen forever.
+ * 7. `grid-idle.gridIdleBlockers()` — tables still building, or built but not yet showing the
+ *    selection range `selectableRange: 1` gives them. Nothing else covered Tabulator: a grid
+ *    command resolves when the panel mounts, which is several frames before the table is drawn.
  *
  * The consumers are the `packages/studio:verify` skill, the screenshot runner and P4.2's Activity
  * tracker (this is a read-only projection of the same in-flight set that dock renders).
@@ -38,6 +41,7 @@ import { pendingSchedulers } from "../panels/panel-scheduler";
 import { canvasIdleBlockers } from "../canvas/iframe-host";
 import { platformInFlight } from "../platform";
 import { overlayIdleBlockers } from "../ui/layers";
+import { gridIdleBlockers } from "../grid/grid-idle";
 
 /** One subsystem that can be outstanding, and its account of why. */
 export interface IdleSource {
@@ -69,7 +73,7 @@ export class NotIdleError extends Error {
 }
 
 /**
- * The six live sources.
+ * The seven live sources.
  *
  * Built per call rather than held in a module constant so a test can substitute one without
  * unpicking the others, and so a second window's hosts are never read through the first window's
@@ -101,6 +105,7 @@ export function defaultIdleSources(): IdleSource[] {
     },
     { blockers: overlayIdleBlockers, name: "overlay" },
     { blockers: activityIdleBlockers, name: "activity" },
+    { blockers: gridIdleBlockers, name: "grid" },
   ];
 }
 

package/src/services/import-client.ts

@@ -3,11 +3,21 @@
  * streaming fetch to some URL" — the dev server posts to its own origin, the desktop platforms post
  * to their token-gated loopback servers — so the request/parse/settle logic lives here once.
  *
- * The endpoint emits one JSON object per line: `progress` lines (forwarded to onProgress),
- * `heartbeat` keep-alives (ignored), and a terminal `done` ({root, config}) or `error` line.
+ * The endpoint emits one JSON object per line: `progress` lines (forwarded to onProgress), a
+ * `ready` line the moment the destination is an openable project (forwarded to onReady),
+ * `heartbeat` keep-alives (ignored), and a terminal `done` ({root, config, result}) or `error`
+ * line. `result` is optional — a backend that does not send one is not broken, and every caller
+ * treats its absence as "the run happened, and it did not say what it found". `ready` is optional
+ * for the same reason: an older backend simply never sends one, and the caller opens the project at
+ * the end as it always did.
  */
 
-import type { ImportProgressEvent, ImportSiteOptions } from "../types";
+import type {
+  ImportProgressEvent,
+  ImportReadyEvent,
+  ImportSiteOptions,
+  ImportSiteSummary,
+} from "../types";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 
 /**
@@ -27,6 +37,7 @@ interface StreamLine {
   total?: number;
   root?: string;
   config?: ProjectConfig;
+  result?: ImportSiteSummary;
   error?: string;
 }
 
@@ -37,13 +48,17 @@ interface StreamLine {
  * @param {ImportSiteOptions} opts — the import request; `apiKey`/`baseUrl` travel as headers
  * @param {(evt: ImportProgressEvent) => void} onProgress
  * @param {AbortSignal} [signal]
+ * @param {(evt: ImportReadyEvent) => void} [onReady] — fires once, as soon as the destination holds
+ *   an openable project. Minutes before `done` on a real crawl, which is the whole reason it
+ *   exists.
  */
 export async function streamImport(
   endpoint: string,
   opts: ImportSiteOptions,
   onProgress: (evt: ImportProgressEvent) => void,
   signal?: AbortSignal,
-): Promise<{ root: string; config: ProjectConfig }> {
+  onReady?: (evt: ImportReadyEvent) => void,
+): Promise<{ root: string; config: ProjectConfig; result?: ImportSiteSummary }> {
   const headers: Record<string, string> = { "Content-Type": "application/json" };
   if (opts.apiKey) {
     headers["X-Api-Key"] = opts.apiKey;
@@ -59,7 +74,13 @@ export async function streamImport(
       depth: opts.depth,
       maxPages: opts.maxPages,
       aiComponents: opts.aiComponents,
+      ...(opts.breakpoints === undefined ? {} : { breakpoints: opts.breakpoints }),
       ...(opts.model === undefined ? {} : { aiModel: opts.model }),
+      ...(opts.verify === undefined ? {} : { verify: opts.verify }),
+      ...(opts.verifyThreshold === undefined ? {} : { verifyThreshold: opts.verifyThreshold }),
+      ...(opts.verifyMinFidelity === undefined
+        ? {}
+        : { verifyMinFidelity: opts.verifyMinFidelity }),
     }),
     headers,
     method: "POST",
@@ -85,7 +106,7 @@ export async function streamImport(
   const reader = res.body.getReader();
   const decoder = new TextDecoder();
   let buffer = "";
-  let result: { root: string; config: ProjectConfig } | null = null;
+  let result: { root: string; config: ProjectConfig; result?: ImportSiteSummary } | null = null;
   /*
    * Lines the parser could not read. Tolerating one is right — an import that ran for two minutes
    * should not die on a garbled progress line — but doing it *silently* is not: the import then
@@ -113,8 +134,14 @@ export async function streamImport(
         ...(parsed.current === undefined ? {} : { current: parsed.current }),
         ...(parsed.total === undefined ? {} : { total: parsed.total }),
       });
+    } else if (parsed.type === "ready" && parsed.root !== undefined) {
+      onReady?.({ root: parsed.root });
     } else if (parsed.type === "done" && parsed.root !== undefined && parsed.config) {
-      result = { root: parsed.root, config: parsed.config };
+      result = {
+        root: parsed.root,
+        config: parsed.config,
+        ...(parsed.result === undefined ? {} : { result: parsed.result }),
+      };
     } else if (parsed.type === "error") {
       throw new Error(parsed.error || "Import failed");
     }

package/src/services/import-run.ts

@@ -0,0 +1,158 @@
+/**
+ * Import-run.ts — the live state of a site import, for the transcript to draw.
+ *
+ * An import takes minutes and reports a line at a time. Those lines used to render into the New
+ * Project modal and die with it: a successful import destroyed its own account of what it had done
+ * at the moment it handed off. Now the run belongs to a tool call, so the record is keyed by that
+ * call's id and the chip and its progress are one thing rather than two.
+ *
+ * Reactive, so `panels/ai-panel.ts`'s watcher repaints on it through the same rAF coalescer that
+ * carries streaming tokens — a crawl emitting a line per page cannot outrun the frame rate.
+ *
+ * @license MIT
+ */
+
+import { reactive } from "../reactivity";
+
+import type { ImportProgressEvent } from "../types";
+
+/**
+ * Lines kept per run.
+ *
+ * A wide crawl emits one per page plus one per asset batch, and every line is also held in the
+ * session's localStorage budget once the tool result lands — so there is a ceiling, and it is here.
+ * It was 200 back when the view showed the last SIX of them and the rest existed only to be
+ * summarised; the transcript now renders the whole log in a scroller the reader owns, so the number
+ * that matters is how far back they can scroll.
+ */
+export const MAX_LOG_LINES = 500;
+
+export interface ImportRunRecord {
+  /** The tool-call id — the join key with the chip the transcript draws. */
+  id: string;
+  url: string;
+  directory: string;
+  phase: string;
+  message: string;
+  current: number | null;
+  total: number | null;
+  log: ImportProgressEvent[];
+  /** Lines the pipeline marked with `⚠`, kept apart so the summary can name them. */
+  warnings: string[];
+  status: "running" | "done" | "failed" | "stopped";
+  error: string;
+}
+
+/**
+ * One run at a time, because one project is created at a time and `import_site` is `no-project`
+ * tiered. Keyed rather than bare so a finished run still renders under its own chip after the next
+ * one starts, which is what makes the transcript readable after two attempts.
+ */
+const runs = reactive<{ records: ImportRunRecord[] }>({ records: [] });
+
+/** Runs kept before the oldest is dropped. Two attempts and a retry is the realistic ceiling. */
+const MAX_RUNS = 5;
+
+/** Aborts the in-flight run. Owned here because `ToolRegistry.execute` cannot be handed a signal. */
+let controller: AbortController | null = null;
+
+/**
+ * Open a run record and return the signal its request should carry.
+ *
+ * @param {string} id - The tool-call id.
+ * @param {{ url: string; directory: string }} init
+ * @returns {AbortSignal}
+ */
+export function beginImportRun(id: string, init: { url: string; directory: string }): AbortSignal {
+  controller?.abort();
+  controller = new AbortController();
+  runs.records.push({
+    current: null,
+    directory: init.directory,
+    error: "",
+    id,
+    log: [],
+    message: "Starting…",
+    phase: "start",
+    status: "running",
+    total: null,
+    url: init.url,
+    warnings: [],
+  });
+  if (runs.records.length > MAX_RUNS) {
+    runs.records.shift();
+  }
+  return controller.signal;
+}
+
+/**
+ * Record one progress line against a run.
+ *
+ * @param {string} id
+ * @param {ImportProgressEvent} evt
+ */
+export function recordImportProgress(id: string, evt: ImportProgressEvent): void {
+  const record = runs.records.find((r) => r.id === id);
+  if (!record) {
+    return;
+  }
+  record.phase = evt.phase;
+  record.message = evt.message;
+  record.current = evt.current ?? null;
+  record.total = evt.total ?? null;
+  record.log.push(evt);
+  if (record.log.length > MAX_LOG_LINES) {
+    record.log.shift();
+  }
+  /* The pipeline reports a soft failure by prefixing its progress line, and `ImportSiteResult`'s
+     own `warnings` array does not cross the HTTP boundary — so this is the only place they can be
+     recovered from, and the summary needs them to be honest about what was skipped. */
+  if (evt.message.startsWith("⚠")) {
+    record.warnings.push(evt.message.replace(/^⚠\s*/, ""));
+  }
+}
+
+/**
+ * Close a run.
+ *
+ * @param {string} id
+ * @param {{ status: Exclude<ImportRunRecord["status"], "running">; error?: string }} outcome
+ */
+export function finishImportRun(
+  id: string,
+  outcome: { status: Exclude<ImportRunRecord["status"], "running">; error?: string },
+): void {
+  const record = runs.records.find((r) => r.id === id);
+  if (record) {
+    record.status = outcome.status;
+    record.error = outcome.error ?? "";
+  }
+  controller = null;
+}
+
+/**
+ * The record for one tool call, or null. Reactive — read it inside an `effect()` to repaint on it.
+ *
+ * @param {string} id
+ * @returns {ImportRunRecord | null}
+ */
+export function importRun(id: string): ImportRunRecord | null {
+  return runs.records.find((r) => r.id === id) ?? null;
+}
+
+/** The run still going, or null. What the panel's watcher tracks. */
+export function activeImportRun(): ImportRunRecord | null {
+  return runs.records.find((r) => r.status === "running") ?? null;
+}
+
+/** Abort the in-flight run. Called from `assistant.stop`, which cannot reach the tool directly. */
+export function abortImportRun(): void {
+  controller?.abort();
+  controller = null;
+}
+
+/** Drop every record. For New Chat and for tests. */
+export function resetImportRuns(): void {
+  abortImportRun();
+  runs.records.length = 0;
+}

package/src/services/import-seed.ts

@@ -0,0 +1,120 @@
+/**
+ * Import-seed.ts — the New Project Import form's hand-off to the assistant.
+ *
+ * The wizard collects a URL, crawl options, a model and a brief, then closes; the assistant takes
+ * the turn and runs the import as a tool call. This holds what the form gathered for the one turn
+ * that consumes it.
+ *
+ * **Module state, and deliberately NOT a copy of `agent-seed.ts`.** That one uses localStorage keyed
+ * by project root because the project it seeds opens in a NEW WINDOW, and the key is the
+ * cross-window channel. Neither half of that applies here: the project does not exist yet at
+ * hand-off time, so there is no root to key on, and the assistant taking the turn is in this window
+ * — `import_site` is `no-project` tiered precisely because it runs before there is a project. A
+ * localStorage clone would be a channel with nothing on the other end and a key that cannot be
+ * computed.
+ *
+ * @license MIT
+ */
+
+import type { ImportBreakpointPolicy } from "../types";
+
+/** What the wizard gathered, as the tool needs it. */
+export interface ImportBrief {
+  /** Absolute http(s) URL of the site to clone. */
+  url: string;
+  /** Human project name (the wizard prefills it from the hostname). */
+  name: string;
+  /** Absolute destination directory, already resolved from Location + folder name. */
+  directory: string;
+  depth: number;
+  maxPages: number;
+  /**
+   * How many of the site's declared breakpoints the project keeps.
+   *
+   * A real site declares as many as it has accumulated frameworks — nine is ordinary — and each one
+   * is a canvas size in Studio and a column in every style editor. The wizard defaults this to
+   * three because that is the complaint it answers, not because three is a magic number.
+   */
+  breakpoints: ImportBreakpointPolicy;
+  aiComponents: boolean;
+  /** Build and screenshot-diff the result. Off by default — it roughly doubles the run. */
+  verify: boolean;
+  /**
+   * The average fidelity, 0..100, the clone has to reach for `verify` to report success.
+   *
+   * Only meaningful when `verify` is on. A finding rather than a failure here: the project is
+   * written and opened either way, and the assistant says the bar was missed.
+   */
+  minFidelity: number;
+  /** Empty means "whatever the assistant would use" (`preferredModel()`). */
+  model: string;
+  /** What the user wants done with the site once it is cloned. May be empty. */
+  prompt: string;
+}
+
+let _brief: ImportBrief | null = null;
+
+/**
+ * Store the brief the assistant's next turn will act on.
+ *
+ * @param {ImportBrief} brief
+ */
+export function setPendingImportBrief(brief: ImportBrief): void {
+  _brief = brief;
+}
+
+/**
+ * The brief without consuming it — what `import_site` reads to fill in a destination the model was
+ * never told and must not invent.
+ *
+ * @returns {ImportBrief | null}
+ */
+export function pendingImportBrief(): ImportBrief | null {
+  return _brief;
+}
+
+/**
+ * Forget the brief.
+ *
+ * There is deliberately no consume-on-read here, unlike `agent-seed.ts`. TWO readers need the same
+ * brief and they read at different moments: the panel, to compose the turn, and `import_site`, for
+ * the destination — which is minutes later, after the model has decided to call it. A read that
+ * cleared would leave the tool inventing a path the user never chose. The tool clears it once the
+ * import has actually run.
+ */
+export function clearPendingImportBrief(): void {
+  _brief = null;
+}
+
+// ─── The hand-off itself ────────────────────────────────────────────────────
+
+/**
+ * The assistant's side of the hand-off, registered at boot.
+ *
+ * A late-bound slot for the same reason `services/project-adoption.ts` is one: the New Project
+ * wizard must not import `panels/ai-panel.ts`. That import is not just a layering preference — the
+ * panel constructs a `DocumentAssistant` singleton at module load, so reaching for it from
+ * `new-project/` drags a live assistant into every surface that opens the wizard.
+ */
+let _handoff: ((brief: ImportBrief) => Promise<void>) | null = null;
+
+/**
+ * Register the assistant's hand-off (studio.ts boot).
+ *
+ * @param {(brief: ImportBrief) => Promise<void>} fn
+ */
+export function setImportHandoff(fn: (brief: ImportBrief) => Promise<void>): void {
+  _handoff = fn;
+}
+
+/**
+ * Start the import as an assistant turn.
+ *
+ * A no-op with nothing registered — a reduced host (a test fixture, an embedder without the
+ * assistant) would otherwise crash on a button the wizard should simply not have offered.
+ *
+ * @param {ImportBrief} brief
+ */
+export async function runImportHandoff(brief: ImportBrief): Promise<void> {
+  await _handoff?.(brief);
+}