@jxsuite/studio 6.1.1 → 8.0.0

package/src/services/data-service.ts

@@ -8,6 +8,7 @@
  * (specs/extensions.md §13).
  */
 
+import { isFunction } from "@jxsuite/schema/guards";
 import { getPlatform } from "../platform";
 import type {
   DataConnectionsResponse,
@@ -18,7 +19,7 @@ import type {
   DataRowsQuery,
   DataRowsResult,
   DataRowUpdate,
-  SecretsSetRequest,
+  KeyValuePatch,
   SecretsSetResponse,
   StudioPlatform,
 } from "../types";
@@ -34,18 +35,18 @@ function platformOrNull(): StudioPlatform | null {
 
 /** True when the platform serves the data grid (the family's gating member is dataRows). */
 export function dataSurfaceAvailable(): boolean {
-  return typeof platformOrNull()?.dataRows === "function";
+  return isFunction(platformOrNull()?.dataRows);
 }
 
 /** True when the platform can store secret values (backs the "secret" form control). */
 export function secretsAvailable(): boolean {
-  return typeof platformOrNull()?.setSecrets === "function";
+  return isFunction(platformOrNull()?.setSecrets);
 }
 
 /** Connections with configured state and table names; null when the backend lacks the route. */
 export async function fetchConnections(): Promise<DataConnectionsResponse | null> {
   const platform = platformOrNull();
-  if (typeof platform?.dataConnections !== "function") {
+  if (!isFunction(platform?.dataConnections)) {
     return null;
   }
   return platform.dataConnections();
@@ -54,7 +55,7 @@ export async function fetchConnections(): Promise<DataConnectionsResponse | null
 /** Probe one connection; degrades to an error result instead of throwing. */
 export async function testConnection(connection: string): Promise<DataConnectionTestResult> {
   const platform = platformOrNull();
-  if (typeof platform?.dataConnectionTest !== "function") {
+  if (!isFunction(platform?.dataConnectionTest)) {
     return { error: "Connection tests are not supported by this backend", ok: false };
   }
   try {
@@ -70,7 +71,7 @@ export async function pushSchema(opts?: {
   dryRun?: boolean;
 }): Promise<DataPushResult> {
   const platform = platformOrNull();
-  if (typeof platform?.dataPush !== "function") {
+  if (!isFunction(platform?.dataPush)) {
     return { applied: false, errors: ["Schema push is not supported by this backend"], plan: [] };
   }
   try {
@@ -88,10 +89,10 @@ export async function pushSchema(opts?: {
 function requireMember<K extends keyof StudioPlatform>(name: K): NonNullable<StudioPlatform[K]> {
   const platform = platformOrNull();
   const member = platform?.[name];
-  if (member === undefined || member === null) {
+  if (member === undefined) {
     throw new Error(`The ${String(name)} surface is not supported by this backend`);
   }
-  return member as NonNullable<StudioPlatform[K]>;
+  return member;
 }
 
 /** Page a table's rows (grid callers handle errors per load). */
@@ -99,11 +100,13 @@ export function fetchRows(query: DataRowsQuery): Promise<DataRowsResult> {
   return requireMember("dataRows")(query);
 }
 
-export function insertRow(req: DataRowInsert): Promise<{ row: Record<string, unknown> }> {
+/** Insert one row; the platform answers with the row as stored. */
+export function insertRow(req: DataRowInsert) {
   return requireMember("dataInsertRow")(req);
 }
 
-export function updateRow(req: DataRowUpdate): Promise<{ row: Record<string, unknown> }> {
+/** Update one row; the platform answers with the row as stored. */
+export function updateRow(req: DataRowUpdate) {
   return requireMember("dataUpdateRow")(req);
 }
 
@@ -114,14 +117,14 @@ export function deleteRow(req: DataRowDelete): Promise<{ ok: boolean }> {
 /** Configured secret env-var NAMES; null when the backend has no secrets surface. */
 export async function listSecretNames(): Promise<string[] | null> {
   const platform = platformOrNull();
-  if (typeof platform?.listSecrets !== "function") {
+  if (!isFunction(platform?.listSecrets)) {
     return null;
   }
   return platform.listSecrets();
 }
 
 /** Write/remove secrets through the platform store (values flow in, names come back). */
-export function saveSecrets(req: SecretsSetRequest): Promise<SecretsSetResponse> {
+export function saveSecrets(req: KeyValuePatch): Promise<SecretsSetResponse> {
   return requireMember("setSecrets")(req);
 }
 
@@ -147,9 +150,10 @@ export function deriveSecretEnvName(
       .replaceAll(/[^A-Za-z0-9]+/g, "_")
       .replaceAll(/^_+|_+$/g, "")
       .toUpperCase();
-  const parts = [entryKey ?? sectionKey, fieldKey.replace(/Env$/, "")]
-    .map((part) => constant(part))
-    .filter(Boolean);
+  const parts = [entryKey ?? sectionKey, fieldKey.replace(/Env$/, "")].flatMap((part) => {
+    const segment = constant(part);
+    return segment ? [segment] : [];
+  });
   const name = parts.join("_") || "SECRET";
   return /^\d/.test(name) ? `JX_${name}` : name;
 }

package/src/services/directory-picker.ts

@@ -25,13 +25,14 @@
  * cancel, and Browse… a button that silently did nothing.
  *
  * Only the plain dev-server browser session needs this. Every packaged build has a real native
- * dialog that returns a path directly and keeps it — electrobun's `Utils.openFileDialog`, and the
- * NixOS chromium build's XDG desktop portal.
+ * dialog that returns a path directly and keeps it — the Electron app's native folder dialog, and
+ * the NixOS chromium build's XDG desktop portal.
  *
  * @docs studio/projects/create
  */
 
 import { LOCATION_ID_FILE } from "@jxsuite/protocol/routes";
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
 import { errorMessage } from "@jxsuite/schema/parse";
 
 /** Re-exported so a caller wiring up `locate` need not also reach into the protocol package. */
@@ -57,11 +58,20 @@ type ShowDirectoryPicker = (opts?: {
   startIn?: string;
 }) => Promise<DirectoryHandle>;
 
+/** A realm that exposes the File System Access API's folder chooser. */
+type DirectoryPickerRealm = typeof globalThis & { showDirectoryPicker: ShowDirectoryPicker };
+
+/**
+ * Whether a realm carries `showDirectoryPicker`. The DOM lib this package compiles against does not
+ * declare it (the API is Chromium-only), so the global is probed rather than read.
+ */
+function hasDirectoryPicker(realm: typeof globalThis): realm is DirectoryPickerRealm {
+  return "showDirectoryPicker" in realm && typeof realm.showDirectoryPicker === "function";
+}
+
 /** Whether this browser can open a native folder chooser at all. */
 export function canPickDirectory(): boolean {
-  return (
-    typeof (globalThis as { showDirectoryPicker?: unknown }).showDirectoryPicker === "function"
-  );
+  return hasDirectoryPicker(globalThis);
 }
 
 /** A location id: URL-safe, unguessable enough that a concurrent pick cannot collide. */
@@ -76,13 +86,8 @@ function newLocationId(): string {
  * `showDirectoryPicker`, a test double) is not `instanceof Error` here, but it still says what it
  * is.
  */
-function nameOf(error: unknown): string {
-  return typeof error === "object" &&
-    error !== null &&
-    "name" in error &&
-    typeof error.name === "string"
-    ? error.name
-    : "";
+function nameOf(cause: unknown): string {
+  return isNonNullObject(cause) && "name" in cause && isString(cause.name) ? cause.name : "";
 }
 
 /**
@@ -111,12 +116,13 @@ function nameOf(error: unknown): string {
 export async function pickDirectoryPath(
   locate: (query: { name: string; id: string }) => Promise<string | null>,
 ): Promise<string | null> {
-  const show = (globalThis as { showDirectoryPicker?: ShowDirectoryPicker }).showDirectoryPicker;
-  if (typeof show !== "function") {
+  const realm = globalThis;
+  if (!hasDirectoryPicker(realm)) {
     throw new TypeError(
       "This browser has no folder chooser. Type the folder's path into Location instead.",
     );
   }
+  const show = realm.showDirectoryPicker;
 
   let handle: DirectoryHandle;
   try {

package/src/services/document-assistant.ts

@@ -42,6 +42,7 @@ import { getBaseUrl, getOpenAiKey } from "./ai-settings";
 import { preferredModel } from "./ai-models";
 import { pruneOrphanToolMessages, trimContext } from "./context-manager";
 import { renderCheck } from "./render-critic";
+import type { CandidateDocument, RenderVerdict } from "./ai-write-report";
 import { validateDoc } from "./jx-validate";
 import { reloadFileInTab } from "../files/files";
 import { getExtensionCatalog, refreshExtensionUi } from "../format/format-host";
@@ -59,6 +60,20 @@ function projectRoot() {
   return workspace.projectRoot || "";
 }
 
+/**
+ * The open project's configuration.
+ *
+ * @returns {ProjectConfig | null}
+ */
+function projectConfig(): ProjectConfig | null {
+  return workspace.projectConfig;
+}
+
+/* SAFETY: renderCheck runs the whole render inside a try and answers `{ ok: false, error }` for
+   anything it cannot render, so JSON that is not (yet) a valid document is exactly what it is safe
+   to hand; its JxDocument parameter names what renders, not what may be probed. */
+const probeRender = renderCheck as (doc: CandidateDocument) => Promise<RenderVerdict>;
+
 /**
  * Create a document-assistant session bound to the currently active tab.
  *
@@ -82,8 +97,10 @@ export function createDocumentAssistant() {
      `ctx.session`. New Chat starts over; a new session id keeps what the conversation knew. */
   let sessionFacts = createSessionFacts();
 
-  const getProjectStyle = () =>
-    (workspace.projectConfig as ProjectConfig | null)?.style as Record<string, string> | undefined;
+  /* SAFETY: the token tools read only the top-level `--*` keys of the project style block, and skip
+     any whose value is not a string, so the nested rule blocks a JxStyle may also hold are never
+     read as tokens. */
+  const getProjectStyle = () => projectConfig()?.style as Record<string, string> | undefined;
 
   const findOpenTab = (path: string): Tab | null => {
     for (const tab of workspace.tabs.values()) {
@@ -106,9 +123,7 @@ export function createDocumentAssistant() {
       const plat = getPlatform();
       await plat.writeFile(relPath, content);
     },
-    renderCheck: renderCheck as (
-      doc: unknown,
-    ) => Promise<{ ok: true } | { ok: false; error: string }>,
+    renderCheck: probeRender,
     getProjectStyle,
     findOpenTab,
     reloadTab: reloadFileInTab,
@@ -126,9 +141,7 @@ export function createDocumentAssistant() {
   });
   registerProjectTools(innerRegistry, {
     getTab: () => activeTab.value,
-    renderCheck: renderCheck as (
-      doc: unknown,
-    ) => Promise<{ ok: true } | { ok: false; error: string }>,
+    renderCheck: probeRender,
     getProjectStyle,
     findOpenTab,
     reloadTab: reloadFileInTab,
@@ -221,9 +234,7 @@ export function createDocumentAssistant() {
   const commandTools = createCommandToolRegistry({
     getProjectStyle,
     getTab: () => activeTab.value,
-    renderCheck: renderCheck as (
-      doc: unknown,
-    ) => Promise<{ ok: true } | { ok: false; error: string }>,
+    renderCheck: probeRender,
     validate: validateDoc,
   });
   const toolRegistry = composeToolRegistries(
@@ -263,16 +274,21 @@ export function createDocumentAssistant() {
        be two answers to "what can this project turn on". */
     const catalog: ExtensionCatalogSummary[] = [];
     for (const entry of getExtensionCatalog()) {
-      catalog.push({
+      const summary: ExtensionCatalogSummary = {
         name: entry.name,
         sections: entry.sections.map((section) => section.key),
-        ...(entry.title === undefined ? {} : { title: entry.title }),
-        ...(entry.description === undefined ? {} : { description: entry.description }),
-      });
+      };
+      if (entry.title !== undefined) {
+        summary.title = entry.title;
+      }
+      if (entry.description !== undefined) {
+        summary.description = entry.description;
+      }
+      catalog.push(summary);
     }
     return buildSystemPrompt({
       document: tab ? toRaw(tab.doc.document) : undefined,
-      projectConfig: (workspace.projectConfig as ProjectConfig | null) || undefined,
+      projectConfig: projectConfig() || undefined,
       components: componentRegistry.length > 0 ? componentRegistry : undefined,
       projectRoot: workspace.projectRoot || undefined,
       hasProject: Boolean(workspace.projectRoot),
@@ -285,8 +301,9 @@ export function createDocumentAssistant() {
       /* Read per turn from the live registry — a projected tool the gate will honour this round is
          listed this round, and one it will not is not. */
       commandTools: commandToolBlurbs(activeRegistry()),
-      ...(inventory && inventory.length > 0 ? { fileInventory: inventory } : {}),
-      ...(catalog.length > 0 ? { extensionCatalog: catalog } : {}),
+      // Absent and undefined read the same: every option is destructured without a default.
+      fileInventory: inventory && inventory.length > 0 ? inventory : undefined,
+      extensionCatalog: catalog.length > 0 ? catalog : undefined,
     });
   }
 
@@ -347,7 +364,7 @@ export function createDocumentAssistant() {
         baseUrl: getBaseUrl() || undefined,
         /* The persisted conversation, so the backend can keep its rounds on one warm prompt cache.
            Sent to the backend only, which hashes it before any provider sees it (specs/ai.md §2.5). */
-        sessionId: sessionId ?? undefined,
+        sessionId,
       });
 
       if (sessionFacts.sessionId !== sessionId) {
@@ -480,6 +497,9 @@ export function createDocumentAssistant() {
    */
   function pushRestoredMessages(msgs: sessionStore.PersistedMessage[]) {
     for (const m of backfillToolResults(msgs)) {
+      /* SAFETY: every persisted message was written by persistChat from a live message (its role,
+         tool calls and timestamp included) and its call results were restored by
+         backfillToolResults above; only the id a legacy entry may lack is synthesized here. */
       chatState.messages.push({
         ...m,
         id: m.id || `restored_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`,

package/src/services/gated-registry.ts

@@ -13,7 +13,7 @@
  * @license MIT
  */
 
-import type { ToolContext, ToolDefinition, ToolRegistry } from "@jxsuite/ai/tools";
+import type { ToolArguments, ToolContext, ToolDefinition, ToolRegistry } from "@jxsuite/ai/tools";
 
 export interface ToolAvailability {
   /** Whether the tool is currently advertised/executable. */
@@ -48,17 +48,21 @@ export function createGatedToolRegistry(
     },
     listForLLM() {
       const available = new Set(this.list().map((t) => t.name));
-      return inner
-        .listForLLM()
-        .filter((t) => available.has((t as { function?: { name?: string } }).function?.name ?? ""));
+      return inner.listForLLM().filter((t) => {
+        /* SAFETY: a @jxsuite/ai registry lists each tool in OpenAI function-calling form,
+           `{ type: "function", function: { name, … } }`; the registry interface types the entries
+           as bare objects, and the optional chain still answers "" for any other shape. */
+        const tool = t as { function?: { name?: string } };
+        return available.has(tool.function?.name ?? "");
+      });
     },
     getDefinition(toolName: string) {
       return inner.getDefinition(toolName);
     },
-    validate(toolName: string, args: object) {
+    validate(toolName: string, args: ToolArguments) {
       return inner.validate(toolName, args);
     },
-    async execute(toolName: string, args: object, ctx?: ToolContext) {
+    async execute(toolName: string, args: ToolArguments, ctx?: ToolContext) {
       if (inner.getDefinition(toolName) && !isAvailable(toolName)) {
         const gate = availability.get(toolName);
         return {

package/src/services/harness/chat-reducer.ts

@@ -11,11 +11,30 @@
 
 import type { createChatState } from "@jxsuite/ai/chat-state";
 import type { HarnessEvent, TurnOutcome } from "@jxsuite/ai/harness";
+import { isJsonObject, isNumber, isString } from "@jxsuite/schema/guards";
 import type { ImportProgressEvent } from "../../types";
 import { recordImportProgress } from "../import-run";
 
 type ChatStore = ReturnType<typeof createChatState>;
 
+/**
+ * Whether a tool's progress payload is an import progress line. The engine carries progress as
+ * opaque JSON; only the import tool reports any, and only in this shape. Exported so the test
+ * harness's tool context records exactly what this reducer records.
+ */
+export function isImportProgressEvent(value: unknown): value is ImportProgressEvent {
+  if (!isJsonObject(value)) {
+    return false;
+  }
+  const { phase, message, current, total } = value;
+  return (
+    isString(phase) &&
+    isString(message) &&
+    (current === undefined || isNumber(current)) &&
+    (total === undefined || isNumber(total))
+  );
+}
+
 /** How a turn's end reads in the transcript: the cap message, an error row, or nothing more. */
 function applyOutcome(chat: ChatStore, outcome: TurnOutcome): void {
   switch (outcome.kind) {
@@ -96,7 +115,10 @@ export function applyHarnessEvent(chat: ChatStore, event: HarnessEvent): void {
       break;
     }
     case "tool_progress": {
-      recordImportProgress(event.callId, event.progress as unknown as ImportProgressEvent);
+      // A call that is not an import run has no record to update either way.
+      if (isImportProgressEvent(event.progress)) {
+        recordImportProgress(event.callId, event.progress);
+      }
       break;
     }
     case "tool_result": {

package/src/services/import-client.ts

@@ -18,6 +18,7 @@ import type {
   ImportSiteOptions,
   ImportSiteSummary,
 } from "../types";
+import { isJsonObject } from "@jxsuite/schema/guards";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 
 /**
@@ -29,6 +30,34 @@ import type { ProjectConfig } from "@jxsuite/schema/types";
  */
 export const IMPORT_WARNING_PHASE = "warning";
 
+/** The request headers: JSON, plus the caller's AI credentials when it has them. */
+interface ImportRequestHeaders {
+  "Content-Type": string;
+  "X-Api-Key"?: string;
+  "X-Api-Base-URL"?: string;
+}
+
+/** The JSON body the import-site route reads; `model` travels as `aiModel`. */
+interface ImportRequestBody {
+  url: string;
+  directory: string;
+  depth: number;
+  maxPages: number;
+  aiComponents: boolean;
+  breakpoints?: ImportSiteOptions["breakpoints"];
+  aiModel?: ImportSiteOptions["model"];
+  verify?: boolean;
+  verifyThreshold?: number;
+  verifyMinFidelity?: number;
+}
+
+/** What a `done` line settles the stream with. */
+export interface ImportStreamResult {
+  root: string;
+  config: ProjectConfig;
+  result?: ImportSiteSummary;
+}
+
 interface StreamLine {
   type: string;
   phase?: string;
@@ -58,8 +87,8 @@ export async function streamImport(
   onProgress: (evt: ImportProgressEvent) => void,
   signal?: AbortSignal,
   onReady?: (evt: ImportReadyEvent) => void,
-): Promise<{ root: string; config: ProjectConfig; result?: ImportSiteSummary }> {
-  const headers: Record<string, string> = { "Content-Type": "application/json" };
+): Promise<ImportStreamResult> {
+  const headers: ImportRequestHeaders = { "Content-Type": "application/json" };
   if (opts.apiKey) {
     headers["X-Api-Key"] = opts.apiKey;
   }
@@ -67,32 +96,46 @@ export async function streamImport(
     headers["X-Api-Base-URL"] = opts.baseUrl;
   }
 
-  const res = await fetch(endpoint, {
-    body: JSON.stringify({
-      url: opts.url,
-      directory: opts.directory,
-      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,
+  const request: ImportRequestBody = {
+    url: opts.url,
+    directory: opts.directory,
+    depth: opts.depth,
+    maxPages: opts.maxPages,
+    aiComponents: opts.aiComponents,
+  };
+  if (opts.breakpoints !== undefined) {
+    request.breakpoints = opts.breakpoints;
+  }
+  if (opts.model !== undefined) {
+    request.aiModel = opts.model;
+  }
+  if (opts.verify !== undefined) {
+    request.verify = opts.verify;
+  }
+  if (opts.verifyThreshold !== undefined) {
+    request.verifyThreshold = opts.verifyThreshold;
+  }
+  if (opts.verifyMinFidelity !== undefined) {
+    request.verifyMinFidelity = opts.verifyMinFidelity;
+  }
+  // The spread is a plain record copy: an interface is not assignable to the `HeadersInit` record.
+  const init: RequestInit = {
+    body: JSON.stringify(request),
+    headers: { ...headers },
     method: "POST",
-    ...(signal === undefined ? {} : { signal }),
-  });
+  };
+  if (signal !== undefined) {
+    init.signal = signal;
+  }
+  const res = await fetch(endpoint, init);
 
   if (!res.ok) {
     let message = `Import failed (${res.status})`;
     try {
-      const body = (await res.json()) as { error?: string };
-      if (body.error) {
-        message = body.error;
+      const body: unknown = await res.json();
+      // `new Error()` stringifies a non-string message, so String() keeps any `error` value's text.
+      if (isJsonObject(body) && body.error) {
+        message = String(body.error);
       }
     } catch {
       /* Non-JSON error body — keep the status message. */
@@ -106,7 +149,7 @@ export async function streamImport(
   const reader = res.body.getReader();
   const decoder = new TextDecoder();
   let buffer = "";
-  let result: { root: string; config: ProjectConfig; result?: ImportSiteSummary } | null = null;
+  let result: ImportStreamResult | 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
@@ -115,37 +158,47 @@ export async function streamImport(
    */
   let unreadable = 0;
 
-  const handleLine = (line: string) => {
+  /** Apply one line; a `done` line's result is returned for the read loop to keep. */
+  const handleLine = (line: string): ImportStreamResult | undefined => {
     const trimmed = line.trim();
     if (!trimmed) {
-      return;
+      return undefined;
     }
     let parsed: StreamLine;
     try {
+      /* SAFETY: the import-site route writes every line as JSON.stringify of one stream line
+         object with a string `type`, and every other member is optional; each branch below
+         compares `type` to a literal and checks the members it reads before using them. */
       parsed = JSON.parse(trimmed) as StreamLine;
     } catch {
       unreadable += 1;
-      return; // Tolerate a mangled line rather than killing the whole import.
+      return undefined; // Tolerate a mangled line rather than killing the whole import.
     }
     if (parsed.type === "progress") {
-      onProgress({
+      const progress: ImportProgressEvent = {
         phase: parsed.phase ?? "",
         message: parsed.message ?? "",
-        ...(parsed.current === undefined ? {} : { current: parsed.current }),
-        ...(parsed.total === undefined ? {} : { total: parsed.total }),
-      });
+      };
+      if (parsed.current !== undefined) {
+        progress.current = parsed.current;
+      }
+      if (parsed.total !== undefined) {
+        progress.total = parsed.total;
+      }
+      onProgress(progress);
     } 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,
-        ...(parsed.result === undefined ? {} : { result: parsed.result }),
-      };
+      const settled: ImportStreamResult = { root: parsed.root, config: parsed.config };
+      if (parsed.result !== undefined) {
+        settled.result = parsed.result;
+      }
+      return settled;
     } else if (parsed.type === "error") {
       throw new Error(parsed.error || "Import failed");
     }
     // Heartbeats and unknown line types are ignored.
+    return undefined;
   };
 
   try {
@@ -159,10 +212,10 @@ export async function streamImport(
       const lines = buffer.split("\n");
       buffer = lines.pop() ?? "";
       for (const line of lines) {
-        handleLine(line);
+        result = handleLine(line) ?? result;
       }
     }
-    handleLine(buffer);
+    result = handleLine(buffer) ?? result;
   } finally {
     try {
       await reader.cancel();

package/src/services/import-seed.ts

@@ -5,8 +5,8 @@
  * 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
+ * **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
@@ -18,6 +18,12 @@
 
 import type { ImportBreakpointPolicy } from "../types";
 
+/**
+ * The deepest crawl the import pipeline accepts: the bound `packages/server/src/import-api.ts`
+ * clamps to, which both the wizard's depth field and `import_site` honour.
+ */
+export const MAX_IMPORT_DEPTH = 5;
+
 /** What the wizard gathered, as the tool needs it. */
 export interface ImportBrief {
   /** Absolute http(s) URL of the site to clone. */