@jxsuite/studio 6.1.0 → 6.1.2

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

@@ -2,29 +2,30 @@
  * Ai-command-tools.ts — the assistant's tools that ARE command records.
  *
  * A `ToolRegistry` that is a VIEW over this window's active command registry, in the idiom of
- * `services/automation.ts`'s `scriptableCommands()`: nothing is registered here, ever. Every call to
- * `listForLLM()` enumerates the records that carry an `aiTool` projection and builds one function
- * schema per record whose `parameters` is the record's own `args` object — by reference, so a
- * `derivedEnumProperty` getter serialises live on every agent-loop round — whose `description` is
- * the record's, and which is advertised exactly while `registry.isEnabled(id)` holds. `execute` is
- * `registry.run(id, args)`.
+ * `services/automation.ts`'s `scriptableCommands()`: nothing is registered here, ever. Every call
+ * to `listForLLM()` enumerates the records that carry an `aiTool` projection and builds one
+ * function schema per record whose `parameters` is the record's own `args` object — by reference,
+ * so a `derivedEnumProperty` getter serialises live on every agent-loop round — whose `description`
+ * is the record's, and which is advertised exactly while `registry.isEnabled(id)` holds. `execute`
+ * is `registry.run(id, args)`.
  *
  * **Why a view and not a registration.** `const assistant = createDocumentAssistant()` runs at
  * module load of `panels/ai-panel.ts`, before the bootstrap composes the registry, so a
  * registration step would have to import `app-commands.ts` (every command module into the
- * assistant's import graph) and read `report` from a record built with `noopCommandDeps` — a
- * second instance of every record, whose closures are not the app's. A view has neither problem,
- * and it cannot be dormant: issue 273 was forty-seven declarations that reached the assistant from
- * none of them, because each waited on a hand-registered tool nobody wrote. There is no
- * registration step between `aiTool` and the tool, so there is nothing to omit.
+ * assistant's import graph) and read `report` from a record built with `noopCommandDeps` — a second
+ * instance of every record, whose closures are not the app's. A view has neither problem, and it
+ * cannot be dormant: issue 273 was forty-seven declarations that reached the assistant from none of
+ * them, because each waited on a hand-registered tool nobody wrote. There is no registration step
+ * between `aiTool` and the tool, so there is nothing to omit.
  *
- * **What the model reads.** A refusal is the person's own sentence: `CommandUnavailableError.message`
- * IS `refusalSentence`, and a `RangeError` from `coerceArgs` (which `registry.run` applies for
- * every caller) or from inside `run` already names the value and the declared list. Both pass
- * through untouched. There is deliberately no pre-check with `refusalMessage` — `run` refuses with
- * the same sentence, and a second call site for one predicate is precisely the divergence
- * `specs/studio-ui-guidelines.md` §12.4 is about. And because this module owns `execute`,
- * `@jxsuite/ai`'s `Tool "<name>" execution error:` prefix never wraps a refusal.
+ * **What the model reads.** A refusal is the person's own sentence:
+ * `CommandUnavailableError.message` IS `refusalSentence`, and a `RangeError` from `coerceArgs`
+ * (which `registry.run` applies for every caller) or from inside `run` already names the value and
+ * the declared list. Both pass through untouched. There is deliberately no pre-check with
+ * `refusalMessage` — `run` refuses with the same sentence, and a second call site for one predicate
+ * is precisely the divergence `specs/studio-ui-guidelines.md` §12.4 is about. And because this
+ * module owns `execute`, `@jxsuite/ai`'s `Tool "<name>" execution error:` prefix never wraps a
+ * refusal.
  *
  * **The write witness.** A record with `undo: "document"` is held to having written: `transactDoc`
  * replaces the document's root reference on every applied transaction (`tabs/transact.ts`), so an
@@ -36,11 +37,11 @@
  * a transaction on the configuration document (`tabs/project-config.ts`), whose bind effect keeps
  * `projectState.projectConfig` equal to `toRaw(document.doc.document)` — so a record with `undo:
  * "project"` that left that reference alone wrote nothing, whatever its report says. The ledger
- * then files nothing (`wrote: []`, mechanically, for every project record), and a report that
- * named no `wrote` of its own — one with no latch to know it was a no-op — has its sentence
- * replaced by "changed nothing", because "Wrote project.json" over an untouched file is the
- * phantom the ledger exists to keep out. A record whose report answered `wrote: []` itself is one
- * that KNEW, and its sentence ("already enabled") is the one the witness cannot write. That is why
+ * then files nothing (`wrote: []`, mechanically, for every project record), and a report that named
+ * no `wrote` of its own — one with no latch to know it was a no-op — has its sentence replaced by
+ * "changed nothing", because "Wrote project.json" over an untouched file is the phantom the ledger
+ * exists to keep out. A record whose report answered `wrote: []` itself is one that KNEW, and its
+ * sentence ("already enabled") is the one the witness cannot write. That is why
  * `add_project_locale` keeps its latch: the sentence, not the ledger, is what the latch is for.
  *
  * **A tool with nothing it could be called with is withheld.** A `derivedEnumProperty` on a
@@ -52,8 +53,8 @@
  * the coercion's own refusal (`is not declared — declared: none`) rather than `Unknown tool`.
  *
  * **`validate()` is a no-op, on purpose.** `@jxsuite/ai`'s validator never checks `enum` and treats
- * a required `null` as missing (`packages/ai/src/tools.ts`), which would refuse `select_node
- * { path: null }`. The registry's coercion is the single validator, so every projected tool is
+ * a required `null` as missing (`packages/ai/src/tools.ts`), which would refuse `select_node {
+ * path: null }`. The registry's coercion is the single validator, so every projected tool is
  * `strict: false`.
  *
  * @license MIT
@@ -61,14 +62,18 @@
 
 import { createToolContext, toolError } from "@jxsuite/ai/tools";
 import type {
+  ToolArguments,
   ToolContext,
   ToolDefinition,
   ToolRegistry,
   ToolResult,
   WriteLedger,
 } from "@jxsuite/ai/tools";
+import { isString } from "@jxsuite/schema/guards";
+import type { ProjectConfig } from "@jxsuite/schema/types";
 import { activeRegistry } from "../commands/active-registry";
 import { argsSchema } from "../commands/command-args";
+import type { CommandArgsSchema, PropertySchema } from "../commands/command-args";
 import { inCanvas } from "../commands/context";
 import { toRaw } from "../reactivity";
 import { projectState } from "../state";
@@ -99,12 +104,6 @@ export interface CommandToolDeps extends WriteReportDeps {
 /** Schema for a record that declares no `args`: an empty object, so the wire shape is uniform. */
 const EMPTY_ARGS = argsSchema({});
 
-/** The loosely-typed view of a record's `args` this module reads. */
-interface ArgsShape {
-  properties?: Record<string, { enum?: unknown }>;
-  required?: readonly string[];
-}
-
 /**
  * Whether a required argument's choice list is empty right now.
  *
@@ -112,10 +111,10 @@ interface ArgsShape {
  * runs on the wire — so this is the same answer the model would have been shown. Only a REQUIRED
  * property counts: an optional enum that is empty is an argument the model can leave out.
  */
-function hasEmptyRequiredEnum(args: object | undefined): boolean {
-  const shape = (args ?? EMPTY_ARGS) as ArgsShape;
-  return (shape.required ?? []).some((key) => {
-    const declared = shape.properties?.[key]?.enum;
+function hasEmptyRequiredEnum(args: CommandArgsSchema | undefined): boolean {
+  const view = args ?? EMPTY_ARGS;
+  return (view.required ?? []).some((key) => {
+    const declared = view.properties?.[key]?.enum;
     return Array.isArray(declared) && declared.length === 0;
   });
 }
@@ -125,9 +124,8 @@ function hasEmptyRequiredEnum(args: object | undefined): boolean {
  * description the model reads is the selector's. `undefined` when the selector is not registered,
  * in which case no selection-level record can be composed and none is projected.
  */
-function pathsProperty(registry: CommandRegistry): object | undefined {
-  const args = registry.get(SELECTOR)?.args as ArgsShape | undefined;
-  return args?.properties?.paths;
+function pathsProperty(registry: CommandRegistry): PropertySchema | undefined {
+  return registry.get(SELECTOR)?.args?.properties?.paths;
 }
 
 /**
@@ -136,8 +134,8 @@ function pathsProperty(registry: CommandRegistry): object | undefined {
  * selection verb with an argument of its own compose without a rule change — and `register()`
  * refuses a selection-level record that declares `paths` itself, so the two cannot collide.
  */
-function withPaths(paths: object, args: object | undefined): object {
-  const own = (args ?? EMPTY_ARGS) as ArgsShape;
+function withPaths(paths: PropertySchema, args: CommandArgsSchema | undefined): CommandArgsSchema {
+  const own = args ?? EMPTY_ARGS;
   return {
     additionalProperties: false,
     properties: { paths, ...own.properties },
@@ -203,10 +201,10 @@ function projected(registry: CommandRegistry): AnyCommand[] {
 function definitionOf(
   registry: CommandRegistry,
   command: AnyCommand,
-  execute: (name: string, args: object, ctx: ToolContext) => Promise<ToolResult>,
+  execute: (name: string, args: ToolArguments, ctx: ToolContext) => Promise<ToolResult>,
 ): ToolDefinition | undefined {
   const tool = command.aiTool!;
-  let parameters: object;
+  let parameters: CommandArgsSchema;
   if (command.level === "selection") {
     const paths = pathsProperty(registry);
     if (paths === undefined) {
@@ -219,6 +217,11 @@ function definitionOf(
   return {
     name: tool.name,
     description: `${tool.description}${undoSuffix(command)}`,
+    /* SAFETY: `parameters` is an `argsSchema()` object (or the selector's composed from one), a
+       JSON Schema object whose only departures from `JSONSchema` are readonly arrays and a
+       property `type` that may be a list — neither of which the registry's validator ever reads,
+       because every projected tool is `strict: false`. It is passed by reference so a
+       `derivedEnumProperty` getter still serialises live on the wire. */
     parameters: parameters as ToolDefinition["parameters"],
     strict: false,
     llmStrict: false,
@@ -233,15 +236,16 @@ function definitionOf(
  * what the gate will honour — one function, not two that agree until someone edits one.
  *
  * @param {CommandRegistry} registry
- * @param {(name: string, args: object) => Promise<ToolResult>} [execute] What each definition's
- *   `execute` calls. Defaults to a refusal, so a caller that only reads definitions cannot run
- *   one.
+ * @param {(name: string, args: ToolArguments) => Promise<ToolResult>} [execute] What each
+ *   definition's `execute` calls. Defaults to a refusal, so a caller that only reads definitions
+ *   cannot run one.
  * @returns {ToolDefinition[]}
  */
 export function advertisedCommandTools(
   registry: CommandRegistry,
-  execute: (name: string, args: object, ctx: ToolContext) => Promise<ToolResult> = async (name) =>
-    toolError(`Tool "${name}" was listed without an executor.`),
+  execute: (name: string, args: ToolArguments, ctx: ToolContext) => Promise<ToolResult> = async (
+    name,
+  ) => toolError(`Tool "${name}" was listed without an executor.`),
 ): ToolDefinition[] {
   const definitions: ToolDefinition[] = [];
   for (const command of projected(registry)) {
@@ -257,10 +261,9 @@ export function advertisedCommandTools(
 }
 
 /** The parameter list a prompt blurb prints: `a, b?` — required names bare, optional ones marked. */
-function signatureOf(parameters: object): string {
-  const shape = parameters as ArgsShape;
-  const required = new Set(shape.required);
-  return Object.keys(shape.properties ?? {})
+function signatureOf(parameters: ToolDefinition["parameters"]): string {
+  const required = new Set(parameters.required);
+  return Object.keys(parameters.properties ?? {})
     .map((key) => (required.has(key) ? key : `${key}?`))
     .join(", ");
 }
@@ -290,7 +293,7 @@ export function commandToolBlurbs(registry: CommandRegistry | null): string[] {
 
 /** A `report` return, normalised: a bare string is a summary alone. */
 function normaliseReport(report: string | AiToolReport): AiToolReport {
-  return typeof report === "string" ? { summary: report } : report;
+  return isString(report) ? { summary: report } : report;
 }
 
 /**
@@ -301,9 +304,9 @@ function normaliseReport(report: string | AiToolReport): AiToolReport {
  * configuration document is a new reference here — and an unchanged reference is a run that never
  * transacted, however the record's report reads.
  */
-function projectConfigRef(): object | null {
+function projectConfigRef(): ProjectConfig | null {
   const config = projectState?.projectConfig;
-  return config ? toRaw(config as unknown as object) : null;
+  return config ? toRaw(config) : null;
 }
 
 /**
@@ -362,12 +365,12 @@ export function createCommandToolRegistry(deps: CommandToolDeps): ToolRegistry {
    * Run one projected record as the agent — the whole of `ai.md` §3.6.
    *
    * @param {string} name
-   * @param {object} received
+   * @param {ToolArguments} args
    * @returns {Promise<ToolResult>}
    */
   async function execute(
     name: string,
-    received: object,
+    args: ToolArguments,
     ctx: ToolContext = createToolContext(),
   ): Promise<ToolResult> {
     const registry = activeRegistry();
@@ -380,7 +383,6 @@ export function createCommandToolRegistry(deps: CommandToolDeps): ToolRegistry {
         : { error: `Cannot run "${name}" — this window has no command registry.`, success: false };
     }
     const tool = command.aiTool!;
-    const args = received as Record<string, unknown>;
 
     /* The witness and the snapshot, only for a record that writes the document: `rootBefore` is
        what `transactDoc` replaces, and the snapshot is what the verdict compares against. */
@@ -434,6 +436,10 @@ export function createCommandToolRegistry(deps: CommandToolDeps): ToolRegistry {
     const after = registry.context();
     let report: AiToolReport;
     try {
+      /* SAFETY: `AnyCommand` erases the record's argument type to `never` (see its declaration), so
+         `report` cannot be called without one assertion. Every key here was just accepted by
+         `registry.run` — `paths` by the selector, the rest by this record's own `coerceArgs` pass
+         against its `args` schema — and a refusal threw into the catch above, which returned. */
       report = normaliseReport(tool.report({ after, args: args as never, before }));
     } catch (error) {
       /* `run` has resolved, so the write HAPPENED; a report that throws must not make it vanish.
@@ -465,11 +471,11 @@ export function createCommandToolRegistry(deps: CommandToolDeps): ToolRegistry {
       /* A success verdict may have appended the token hints; the report's sentence is kept. */
       summary = verdict.summary ?? summary;
     }
-    return {
-      success: true,
-      summary,
-      ...(report.data === undefined ? {} : { data: report.data }),
-    };
+    const result: ToolResult = { success: true, summary };
+    if (report.data !== undefined) {
+      result.data = report.data;
+    }
+    return result;
   }
 
   return {

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

@@ -1,19 +1,18 @@
 /**
  * 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 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.
+ * 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.
  *
  * Two things it does NOT do are the point:
  *
  * - **It does not invent a destination.** `create_project` requires the model to supply `location`
  *   and refuses without one — correct when a bare chat bootstraps a project, a regression on the
- *   wizard path where the Location field already has a folder picker, validation and a live preview.
- *   The destination comes from the pending brief; a model-supplied one must match it.
+ *   wizard path where the Location field already has a folder picker, validation and a live
+ *   preview. The destination comes from the pending brief; a model-supplied one must match it.
  * - **It does not decide what the crawl found.** The pipeline is one-way: it reports and finishes.
  *   Everything worth a human's opinion — which skipped pages matter, whether the components it
  *   extracted are really components — is in the summary for the model to raise with `ask_user`
@@ -23,23 +22,26 @@
  */
 
 import { createToolDefinition, toolError, toolSuccess } from "@jxsuite/ai/tools";
+import { IMPORT_MAX_PAGES } from "@jxsuite/protocol";
+import { isBoolean, isNumber, isString } from "@jxsuite/schema/guards";
 import { getPlatform } from "../platform";
 import { workspace } from "../workspace/workspace";
 import { getBaseUrl, getOpenAiKey } from "./ai-settings";
 import { preferredModel } from "./ai-models";
-import { clearPendingImportBrief, pendingImportBrief } from "./import-seed";
+import { MAX_IMPORT_DEPTH, clearPendingImportBrief, pendingImportBrief } from "./import-seed";
 import type { ImportBrief } from "./import-seed";
 import { abortImportRun, beginImportRun, finishImportRun, importRun } from "./import-run";
 import { adoptCreatedProject } from "./project-adoption";
-import type { AdoptOutcome } from "./project-adoption";
+import type { AdoptCreatedOptions, AdoptOutcome } from "./project-adoption";
 
 import type { JsonValue, ToolRegistry } from "@jxsuite/ai/tools";
 import type { Tab } from "../tabs/tab";
-import type { ImportBreakpointPolicy, ImportReadyEvent, ImportSiteSummary } from "../types";
-
-/** The same bounds `packages/server/src/import-api.ts` clamps to. */
-const MAX_DEPTH = 5;
-const MAX_PAGES = 100;
+import type {
+  ImportBreakpointPolicy,
+  ImportReadyEvent,
+  ImportSiteOptions,
+  ImportSiteSummary,
+} from "../types";
 
 /** Log lines quoted back on a hard failure — enough to see WHICH phase died. */
 const FAILURE_TAIL = 5;
@@ -73,6 +75,15 @@ export interface ImportToolsCtx {
   brief?: { read: () => ImportBrief | null; clear: () => void };
 }
 
+/**
+ * The adoption a `ready` line started, if one did. A holder rather than a `let`, because the
+ * assignment happens inside the `onReady` callback and control-flow analysis cannot see it: a plain
+ * `let` reads as always-`null` after the run.
+ */
+interface EarlyAdoption {
+  pending: Promise<AdoptOutcome> | null;
+}
+
 function clamp(value: number, min: number, max: number): number {
   return Math.min(max, Math.max(min, Math.trunc(value)));
 }
@@ -89,7 +100,11 @@ function clamp(value: number, min: number, max: number): number {
  * @returns {ImportBreakpointPolicy | undefined}
  */
 function breakpointPolicyFor(
-  args: { maxBreakpoints?: unknown; widths?: unknown; rounding?: unknown },
+  args: {
+    maxBreakpoints: JsonValue | undefined;
+    widths: JsonValue | undefined;
+    rounding: JsonValue | undefined;
+  },
   fromBrief: ImportBreakpointPolicy | undefined,
 ): ImportBreakpointPolicy | undefined {
   const rounding =
@@ -100,7 +115,7 @@ function breakpointPolicyFor(
   if (Array.isArray(args.widths) && args.widths.length > 0) {
     return { mode: "explicit", rounding, widths: args.widths.map(Number) };
   }
-  if (typeof args.maxBreakpoints === "number" && Number.isFinite(args.maxBreakpoints)) {
+  if (isNumber(args.maxBreakpoints) && Number.isFinite(args.maxBreakpoints)) {
     // Zero is the only spelling a count has for "keep all", and it is worth accepting: it is what
     // A model reaches for when a person says "keep them all".
     return args.maxBreakpoints <= 0
@@ -346,18 +361,7 @@ export function registerImportTools(
           maxBreakpoints,
           breakpointWidths,
           breakpointRounding,
-        } = args as {
-          url?: unknown;
-          directory?: unknown;
-          depth?: unknown;
-          maxPages?: unknown;
-          aiComponents?: unknown;
-          verify?: unknown;
-          minFidelity?: unknown;
-          maxBreakpoints?: unknown;
-          breakpointWidths?: unknown;
-          breakpointRounding?: unknown;
-        };
+        } = args;
 
         if (workspace.projectRoot) {
           return toolError(
@@ -386,7 +390,7 @@ export function registerImportTools(
         }
 
         const brief = briefStore.read();
-        const requested = typeof directory === "string" ? directory.trim() : "";
+        const requested = isString(directory) ? directory.trim() : "";
         if (requested && brief && requested !== brief.directory) {
           /* The wizard's Location field is the user's answer to "where does this go". A model that
              disagrees with it is guessing at a decision that was already made in front of them. */
@@ -450,44 +454,56 @@ export function registerImportTools(
          * failure here is not the run's failure: the import continues either way, and the terminal
          * path below reports honestly on whichever state the window ended up in.
          */
-        let adoption: Promise<AdoptOutcome> | null = null;
+        const adoptOptions: AdoptCreatedOptions = { getTab };
+        if (adoptProject) {
+          adoptOptions.adopt = adoptProject;
+        }
+        const early: EarlyAdoption = { pending: null };
         const onReady = ({ root }: ImportReadyEvent) => {
-          adoption ??= adoptCreatedProject(root, {
-            getTab,
-            ...(adoptProject ? { adopt: adoptProject } : {}),
-          });
+          early.pending ??= adoptCreatedProject(root, adoptOptions);
+        };
+
+        const options: ImportSiteOptions = {
+          aiComponents: isBoolean(aiComponents) ? aiComponents : (brief?.aiComponents ?? true),
+          depth: clamp(Number(depth ?? brief?.depth ?? 1) || 0, 0, MAX_IMPORT_DEPTH),
+          directory: destination,
+          maxPages: clamp(Number(maxPages ?? brief?.maxPages ?? 20) || 1, 1, IMPORT_MAX_PAGES),
+          name: brief?.name || target.hostname.replace(/^www\./, ""),
+          url: target.href,
         };
+        if (breakpoints !== undefined) {
+          options.breakpoints = breakpoints;
+        }
+        if (isBoolean(verify)) {
+          options.verify = verify;
+        } else if (brief?.verify !== undefined) {
+          options.verify = brief.verify;
+        }
+        /* The wizard's number is the user's own answer to "how close is close enough"; the model
+           may only override it when it was told to. */
+        options.verifyMinFidelity = clamp(
+          Number(minFidelity ?? brief?.minFidelity ?? DEFAULT_MIN_FIDELITY) || 0,
+          0,
+          MAX_FIDELITY,
+        );
+        if (apiKey) {
+          options.apiKey = apiKey;
+        }
+        if (baseUrl) {
+          options.baseUrl = baseUrl;
+        }
+        if (model) {
+          options.model = model;
+        }
 
         let result: { root: string; result?: ImportSiteSummary };
         try {
           result = await platform.importSite(
-            {
-              aiComponents:
-                typeof aiComponents === "boolean" ? aiComponents : (brief?.aiComponents ?? true),
-              depth: clamp(Number(depth ?? brief?.depth ?? 1) || 0, 0, MAX_DEPTH),
-              directory: destination,
-              maxPages: clamp(Number(maxPages ?? brief?.maxPages ?? 20) || 1, 1, MAX_PAGES),
-              name: brief?.name || target.hostname.replace(/^www\./, ""),
-              url: target.href,
-              ...(breakpoints === undefined ? {} : { breakpoints }),
-              ...(typeof verify === "boolean"
-                ? { verify }
-                : brief?.verify === undefined
-                  ? {}
-                  : { verify: brief.verify }),
-              /* The wizard's number is the user's own answer to "how close is close enough"; the
-                 model may only override it when it was told to. */
-              verifyMinFidelity: clamp(
-                Number(minFidelity ?? brief?.minFidelity ?? DEFAULT_MIN_FIDELITY) || 0,
-                0,
-                MAX_FIDELITY,
-              ),
-              ...(apiKey ? { apiKey } : {}),
-              ...(baseUrl ? { baseUrl } : {}),
-              ...(model ? { model } : {}),
-            },
+            options,
             (evt) => {
-              ctx.progress(evt as unknown as JsonValue);
+              /* The spread is the event's own fields as an object literal, which TypeScript lets
+                 stand as a JSON object where the named interface cannot. */
+              ctx.progress({ ...evt });
             },
             signal,
             onReady,
@@ -522,15 +538,12 @@ export function registerImportTools(
 
         /* The early adoption if there was one, otherwise adopt now: a backend that sends no `ready`
            line is not broken, it is older, and the project must still open. */
-        const { adopted, error: adoptionError } = await (adoption ??
-          adoptCreatedProject(result.root, {
-            getTab,
-            ...(adoptProject ? { adopt: adoptProject } : {}),
-          }));
+        const { adopted, error: adoptionError } = await (early.pending ??
+          adoptCreatedProject(result.root, adoptOptions));
         if (adopted) {
           onProjectAdopted?.(result.root);
           return toolSuccess(
-            { root: result.root, ...(result.result ? { summary: result.result } : {}) },
+            result.result ? { root: result.root, summary: result.result } : { root: result.root },
             describeRun(id, result.root, result.result),
           );
         }

package/src/services/ai-models.ts

@@ -10,7 +10,9 @@
  * @license MIT
  */
 
+import type { AiCredentials } from "@jxsuite/ai/streaming-client";
 import type { AiModelsResponse, OfferedAction } from "@jxsuite/protocol";
+import { isBoolean, isNumber, isString } from "@jxsuite/schema/guards";
 import { getPlatform } from "../platform";
 import { offeredActions } from "../platform-errors";
 import { getBaseUrl, getOpenAiKey, hasOpenAiKey, storedModel } from "./ai-settings";
@@ -38,10 +40,7 @@ export interface AiModel {
  * Two fields, taken together or not at all. The per-field overrides this replaces let a caller pass
  * a draft key with a stored base URL, which is a pair that was never configured anywhere.
  */
-export interface AiCredentials {
-  apiKey: string;
-  baseUrl: string;
-}
+export type { AiCredentials } from "@jxsuite/ai/streaming-client";
 
 /** The credentials the app is configured with right now. */
 export function aiConnection(): AiCredentials {
@@ -380,19 +379,24 @@ export async function fetchAvailableModels(
   if (!resp.ok) {
     throw new Error(`HTTP ${resp.status}`);
   }
+  /* SAFETY: this route is served by a Studio backend answering with `AiModelsResponse`
+     (`@jxsuite/protocol`); `Partial` because an older backend omits members. The members that
+     decide a gate (`configured`, `managed`, `code`, `detail`, a model's capabilities) are each
+     compared to a literal or guarded below before use; the rest are passed through as display text. */
   const data = (await resp.json()) as Partial<AiModelsResponse>;
   proxyConfigured = data.configured === true;
   proxyManaged = data.managed === true;
   proxyDefaultModel = data.defaultModel ?? "";
   proxyCode = data.code;
   proxyModelsError = data.upstreamError !== undefined ? (data.upstreamMessage ?? "") : "";
-  proxyAction =
-    data.code === "action_required"
-      ? {
-          actions: offeredActions(data.actions),
-          ...(typeof data.detail === "string" && data.detail ? { detail: data.detail } : {}),
-        }
-      : null;
+  proxyAction = null;
+  if (data.code === "action_required") {
+    const offer: ProxyActionOffer = { actions: offeredActions(data.actions) };
+    if (isString(data.detail) && data.detail) {
+      offer.detail = data.detail;
+    }
+    proxyAction = offer;
+  }
   /* 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.
@@ -400,10 +404,10 @@ export async function fetchAvailableModels(
      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") {
+    if (isNumber(m.contextWindow)) {
       model.contextWindow = m.contextWindow;
     }
-    if (typeof m.toolSupport === "boolean") {
+    if (isBoolean(m.toolSupport)) {
       model.toolSupport = m.toolSupport;
     }
     return model;