@nyte-ai/plugin 0.0.24 → 0.0.25-nightly.20261025.2

package/dist/src/canvas/canvas-protocol.d.ts

@@ -48,24 +48,24 @@ export declare const TINTS: readonly ["blue", "pink", "orange", "teal", "red", "
  * answers any other import of `nyte/canvas` with a positioned error.
  */
 export declare const KIT: {
-    readonly Stack: "{ direction?: \"row\" | \"column\" = \"column\", gap?: 0 | 1 | 2 | 3 | 4 | 6 = 2 (×4 px), align?: \"start\" | \"center\" | \"end\" | \"stretch\", justify?: \"start\" | \"center\" | \"end\" | \"between\", wrap?: boolean, children }: flex layout";
-    readonly Grid: "{ columns?: number | \"auto\" = \"auto\", minWidth?: number = 160 (px, with \"auto\"), gap?: 0 | 1 | 2 | 3 | 4 | 6 = 2, children }: equal columns";
+    readonly Stack: '{ direction?: "row" | "column" = "column", gap?: 0 | 1 | 2 | 3 | 4 | 6 = 2 (×4 px), align?: "start" | "center" | "end" | "stretch", justify?: "start" | "center" | "end" | "between", wrap?: boolean, children }: flex layout';
+    readonly Grid: '{ columns?: number | "auto" = "auto", minWidth?: number = 160 (px, with "auto"), gap?: 0 | 1 | 2 | 3 | 4 | 6 = 2, children }: equal columns';
     readonly Divider: "{}: a hairline";
     readonly Heading: "{ level?: 1 | 2 | 3 = 2, children }";
-    readonly Text: "{ size?: \"xs\" | \"sm\" | \"base\" | \"lg\", tone?: \"primary\" | \"secondary\" | \"tertiary\", weight?: \"normal\" | \"medium\" | \"semibold\", mono?: boolean, truncate?: boolean, align?: \"start\" | \"center\" | \"end\", children }";
+    readonly Text: '{ size?: "xs" | "sm" | "base" | "lg", tone?: "primary" | "secondary" | "tertiary", weight?: "normal" | "medium" | "semibold", mono?: boolean, truncate?: boolean, align?: "start" | "center" | "end", children }';
     readonly Code: "{ block?: boolean, children: string }: monospace, inline or a block";
-    readonly Stat: "{ label: string, value: ReactNode, detail?: ReactNode, tone?: \"neutral\" | \"success\" | \"warning\" | \"danger\" }: a labelled number";
-    readonly Badge: "{ tone?: \"neutral\" | \"info\" | \"success\" | \"warning\" | \"danger\", children }";
-    readonly Meter: "{ value: number, max?: number = 100, label?: string, tone?: \"primary\" | \"success\" | \"warning\" | \"danger\" = \"primary\" }: a thin filled bar with the value beside the label";
-    readonly Table: "{ columns: { key: string, label: ReactNode, align?: \"start\" | \"end\", width?: number | string }[], rows: Record<string, ReactNode>[], caption?: string }: rows are keyed by column key; a cell can hold a Sparkline or a Badge";
-    readonly Callout: "{ tone?: \"info\" | \"success\" | \"warning\" | \"danger\", title?: string, children }";
+    readonly Stat: '{ label: string, value: ReactNode, detail?: ReactNode, tone?: "neutral" | "success" | "warning" | "danger" }: a labelled number';
+    readonly Badge: '{ tone?: "neutral" | "info" | "success" | "warning" | "danger", children }';
+    readonly Meter: '{ value: number, max?: number = 100, label?: string, tone?: "primary" | "success" | "warning" | "danger" = "primary" }: a thin filled bar with the value beside the label';
+    readonly Table: '{ columns: { key: string, label: ReactNode, align?: "start" | "end", width?: number | string }[], rows: Record<string, ReactNode>[], caption?: string }: rows are keyed by column key; a cell can hold a Sparkline or a Badge';
+    readonly Callout: '{ tone?: "info" | "success" | "warning" | "danger", title?: string, children }';
     readonly Card: "{ title?: ReactNode, actions?: ReactNode, padding?: 0 | 2 | 3 | 4 = 4, children }: an elevated bordered surface";
     readonly StackedBars: "{ label: string, series: { key: string, label: string, tint: Tint }[], buckets: { key: string, label: string, values: number[] }[], format: (value: number) => string, height?: number = 88, ticks?: number = 5 }: compact stacked bars without axes, a readout on pointer or arrow keys; the numbers live in the copy around it. Preferred beside a Stat or a heading figure";
     readonly Sparkline: "{ values: number[], tint?: Tint, label?: string, width?: number = 72, height?: number = 20 }: a row's trend scaled to its own peak, for a Table cell beside the row's number";
-    readonly LineChart: "{ series: { id: string, data: { x: number | string, y: number }[], tint?: Tint }[], height?: number = 240, xFormat?: (x) => string, yFormat?: (y) => string, curve?: \"linear\" | \"monotone\" | \"step\", area?: boolean, legend?: boolean }: a full chart with axes and a readout";
-    readonly BarChart: "{ data: Record<string, number | string>[], keys: (string | { key: string, label?: string, tint?: Tint })[], indexBy: string, height?: number = 240, layout?: \"vertical\" | \"horizontal\", mode?: \"grouped\" | \"stacked\" = \"stacked\", valueFormat?: (value: number) => string, legend?: boolean }: a full chart with axes and a readout with the total";
+    readonly LineChart: '{ series: { id: string, data: { x: number | string, y: number }[], tint?: Tint }[], height?: number = 240, xFormat?: (x) => string, yFormat?: (y) => string, curve?: "linear" | "monotone" | "step", area?: boolean, legend?: boolean }: a full chart with axes and a readout';
+    readonly BarChart: '{ data: Record<string, number | string>[], keys: (string | { key: string, label?: string, tint?: Tint })[], indexBy: string, height?: number = 240, layout?: "vertical" | "horizontal", mode?: "grouped" | "stacked" = "stacked", valueFormat?: (value: number) => string, legend?: boolean }: a full chart with axes and a readout with the total';
     readonly PieChart: "{ data: { id: string, value: number, label?: string, tint?: Tint }[], height?: number = 240, donut?: boolean, valueFormat?: (value: number) => string, legend?: boolean }";
-    readonly Button: "{ variant?: \"solid\" | \"outline\" | \"ghost\", pill?: boolean, size?: \"2xs\" | \"xs\" | \"sm\" | \"md\" | \"lg\" | \"xl\", tone?: \"neutral\" | \"primary\" | \"success\" | \"warning\" | \"danger\", loading?: boolean, disabled?: boolean, onClick, children }";
+    readonly Button: '{ variant?: "solid" | "outline" | "ghost", pill?: boolean, size?: "2xs" | "xs" | "sm" | "md" | "lg" | "xl", tone?: "neutral" | "primary" | "success" | "warning" | "danger", loading?: boolean, disabled?: boolean, onClick, children }';
     readonly Tabs: "Tabs.Root { value?, defaultValue?, onValueChange? } > Tabs.List { children: Tabs.Tab { value, children }[] } + Tabs.Panel { value, children }";
     readonly Select: "Select { value?, defaultValue?, onValueChange? } > SelectTrigger { children: <SelectValue /> } + SelectContent { children: SelectItem[] }";
     readonly SelectTrigger: "see Select";
@@ -83,7 +83,7 @@ export declare const KIT: {
     readonly Collapsible: "Collapsible.Root { open?, defaultOpen?, onOpenChange? } > Collapsible.Trigger { children } + Collapsible.Panel { children }";
     readonly Kbd: "{ keys: string[] }";
     readonly Spinner: "{}";
-    readonly useColorScheme: "(): \"light\" | \"dark\"";
+    readonly useColorScheme: '(): "light" | "dark"';
 };
 /** Every name `nyte/canvas` exports, in `KIT` order. */
 export declare const KIT_EXPORTS: readonly string[];

package/dist/src/canvas/canvas.d.ts

@@ -1,18 +1,27 @@
 import type { CanvasPreviewer } from "./canvas-preview.ts";
 import type { Plugin } from "@nyte-ai/plugin/core";
 export declare const canvas: import("@nyte-ai/core").PartDefinition<{
-    code: string;
     runtime: number;
     title: string;
-    error: string | null;
     height: number | null;
+    code: string;
+    error: string | null;
+    revisions?: {
+        runtime: number;
+        title: string;
+        height: number | null;
+        number: number;
+        blob: import("@nyte-ai/schema").Id<"blob">;
+        at: number;
+    }[] | undefined;
 }, {
     replace: {
         input: import("@nyte-ai/schema").Schema<{
-            code: string;
             runtime: number;
             title: string;
             height: number | null;
+            code: string;
+            blob: import("@nyte-ai/schema").Id<"blob">;
         }>;
     };
     report: {

package/dist/src/canvas/canvas.js

@@ -18,8 +18,10 @@ import {
   describeCanvasPreview2
 } from "../../chunks/bash-description-yyd9jznf.js";
 import {
+  CANVAS_RENDER_TOOL2,
+  CANVAS_REVISIONS_KEPT2,
   canvas2
-} from "../../chunks/bash-description-qnwggxq3.js";
+} from "../../chunks/bash-description-1neewp76.js";
 
 // src/canvas/canvas.ts
 import { definePart, followedTrace, traced } from "@nyte-ai/core";
@@ -27,7 +29,24 @@ import { asId, standard } from "@nyte-ai/schema";
 import { Type } from "typebox";
 var handlers = {
   async replace(input, context) {
-    const outcome = await context.part.update(() => ({ ...input, error: null }));
+    const outcome = await context.part.update((current) => ({
+      runtime: input.runtime,
+      title: input.title,
+      code: input.code,
+      height: input.height,
+      error: null,
+      revisions: [
+        ...current.revisions ?? [],
+        {
+          number: (current.revisions?.at(-1)?.number ?? 1) + 1,
+          blob: input.blob,
+          runtime: input.runtime,
+          title: input.title,
+          height: input.height,
+          at: Date.now()
+        }
+      ].slice(-CANVAS_REVISIONS_KEPT2)
+    }));
     if (outcome.kind !== "updated")
       throw new Error(`The canvas could not be replaced: ${outcome.kind}.`);
   },
@@ -99,7 +118,7 @@ ${describeErrors(compiled.errors)}`);
 var PREVIEW_FIRST = "Before rendering, call `canvas_preview` with the same `source` and `files`: it shows you the canvas and its errors, console and height without the user seeing it. Fix what it shows, then render once.";
 function renderTool(previewing) {
   return {
-    name: "canvas_render",
+    name: CANVAS_RENDER_TOOL2,
     description: previewing ? `${PREVIEW_FIRST}
 
 ${CANVAS_DESCRIPTION}` : CANVAS_DESCRIPTION,
@@ -113,15 +132,18 @@ ${CANVAS_DESCRIPTION}` : CANVAS_DESCRIPTION,
     replay: "safe",
     async execute(args, invocation) {
       const compiled = await compile(args, invocation);
-      const next = {
-        runtime: compiled.runtime,
-        title: args.title,
-        code: compiled.code,
-        height: args.height ?? null
-      };
+      const drawn = { runtime: compiled.runtime, title: args.title, height: args.height ?? null };
+      const blob = await invocation.env.files.upload(async function* () {
+        yield encoder.encode(compiled.code);
+      }());
       if (args.canvas === undefined) {
         const part = await invocation.session.parts.create(canvas, {
-          state: { ...next, error: null },
+          state: {
+            ...drawn,
+            code: compiled.code,
+            error: null,
+            revisions: [{ number: 1, blob, ...drawn, at: Date.now() }]
+          },
           placement: { kind: "transcript", role: "answer" }
         });
         return {
@@ -129,7 +151,7 @@ ${CANVAS_DESCRIPTION}` : CANVAS_DESCRIPTION,
           parts: [part.id]
         };
       }
-      const outcome = await invocation.session.part(asId(args.canvas)).act("replace", next);
+      const outcome = await invocation.session.part(asId(args.canvas)).act("replace", { ...drawn, code: compiled.code, blob });
       if (outcome.kind !== "ok")
         throw new Error(`Canvas ${args.canvas} was not replaced: ${outcome.kind}.`);
       return {

package/dist/src/canvas/schema.d.ts

@@ -1,41 +1,81 @@
 import type { Infer } from "@nyte-ai/schema";
+/**
+ * The tool that renders a canvas and replaces one in place.
+ *
+ * @category plugins
+ * @since 0.1.0
+ */
+export declare const CANVAS_RENDER_TOOL = "canvas_render";
+/**
+ * How many revisions a canvas lists; a replace past it drops the oldest.
+ *
+ * @category plugins
+ * @since 0.1.0
+ */
+export declare const CANVAS_REVISIONS_KEPT = 50;
 declare const state: import("@nyte-ai/schema").Schema<{
-    code: string;
     runtime: number;
     title: string;
-    error: string | null;
     height: number | null;
+    code: string;
+    error: string | null;
+    revisions?: {
+        runtime: number;
+        title: string;
+        height: number | null;
+        number: number;
+        blob: import("@nyte-ai/schema").Id<"blob">;
+        at: number;
+    }[] | undefined;
 }>;
 /**
  * Returns a canvas part's state: the compiled module, the runtime it needs,
- * its title, the agent's height hint and the last error a client reported.
+ * its title, the agent's height hint, the last error a client reported, and
+ * its revisions, oldest first, the last one being the module itself.
  *
  * @category plugins
  * @since 0.1.0
  */
 export type CanvasState = Infer<typeof state>;
+/**
+ * One revision of a canvas: its compiled module stored as a blob, with what
+ * drawing it needs besides the code.
+ *
+ * @category plugins
+ * @since 0.1.0
+ */
+export type CanvasRevision = NonNullable<CanvasState["revisions"]>[number];
 /**
  * A canvas part: a React module the agent wrote, compiled on the host and
  * drawn by a client inside the sandboxed runtime shell. `replace` swaps the
- * module in place; `report` records a load or render error a client saw,
- * which the model reads in the fallback.
+ * module in place and lists it as the next revision; `report` records a load
+ * or render error a client saw, which the model reads in the fallback.
  *
  * @category plugins
  * @since 0.1.0
  */
 export declare const canvas: import("@nyte-ai/core").PartDefinition<{
-    code: string;
     runtime: number;
     title: string;
-    error: string | null;
     height: number | null;
+    code: string;
+    error: string | null;
+    revisions?: {
+        runtime: number;
+        title: string;
+        height: number | null;
+        number: number;
+        blob: import("@nyte-ai/schema").Id<"blob">;
+        at: number;
+    }[] | undefined;
 }, {
     replace: {
         input: import("@nyte-ai/schema").Schema<{
-            code: string;
             runtime: number;
             title: string;
             height: number | null;
+            code: string;
+            blob: import("@nyte-ai/schema").Id<"blob">;
         }>;
     };
     report: {

package/dist/src/canvas/schema.js

@@ -1,8 +1,12 @@
 import {
+  CANVAS_RENDER_TOOL2,
+  CANVAS_REVISIONS_KEPT2,
   canvas2
-} from "../../chunks/bash-description-qnwggxq3.js";
+} from "../../chunks/bash-description-1neewp76.js";
 import"../../chunks/bash-description-dnvgk30y.js";
 import"../../chunks/bash-description-zfpm2rt0.js";
 export {
+  CANVAS_RENDER_TOOL2 as CANVAS_RENDER_TOOL,
+  CANVAS_REVISIONS_KEPT2 as CANVAS_REVISIONS_KEPT,
   canvas2 as canvas
 };

package/dist/src/claude-code-sdk/index.d.ts

@@ -20,7 +20,7 @@ export declare function claudeCodeSdk(start?: StartQuery): {
             readonly contribute: import("@nyte-ai/core").Registries<"core">;
             readonly storage: import("@nyte-ai/core").PluginStorage;
             readonly signal: AbortSignal;
-            hook<N extends "session_activated" | "before_send" | "run_started" | "transform_transcript" | "before_compaction" | "before_request" | "before_tool" | "after_tool" | "after_request" | "run_ended">(name: N, entry: import("@nyte-ai/core").HookEntry<"core", N>): import("@nyte-ai/schema").Disposer;
+            hook<N extends import("@nyte-ai/core").HookName<"core">>(name: N, entry: import("@nyte-ai/core").HookEntry<"core", N>): import("@nyte-ai/schema").Disposer;
             report(issue: import("@nyte-ai/schema").ValidationIssue): void;
             reload(): void;
         } & {

package/dist/src/claude-code-sdk/index.js

@@ -54,6 +54,7 @@ var CLAUDE_CODE_HAS_ITS_OWN = new Set([
   "edit",
   "list",
   "web_search",
+  "web_fetch",
   "question"
 ]);
 var ultracodeSetting = {

package/dist/src/client/notifications.d.ts

@@ -22,7 +22,7 @@ declare const _default: {
                 readonly contribute: import("@nyte-ai/core").Registries<"client">;
                 readonly storage: import("@nyte-ai/core").PluginStorage;
                 readonly signal: AbortSignal;
-                hook<N extends "run_ended_anywhere" | "app_ready" | "session_opened" | "before_submit" | "session_closed" | "app_closing">(name: N, entry: import("@nyte-ai/core").HookEntry<"client", N>): import("@nyte-ai/schema").Disposer;
+                hook<N extends import("@nyte-ai/core").HookName<"client">>(name: N, entry: import("@nyte-ai/core").HookEntry<"client", N>): import("@nyte-ai/schema").Disposer;
                 report(issue: import("@nyte-ai/schema").ValidationIssue): void;
                 reload(): void;
             } & import("@nyte-ai/plugin/client").ClientApi;

package/dist/src/client/presentation.d.ts

@@ -1,6 +1,6 @@
 import { text, thinking } from "@nyte-ai/core";
 import type { PartState } from "@nyte-ai/core";
-import type { Execution, Failure, HeadInfo, Message, MessageSource, SessionInfo, ToolClass, ToolPartState, UserContent, UserStatus } from "@nyte-ai/schema";
+import type { Execution, Failure, HeadInfo, Message, MessageSource, SessionInfo, ToolClass, ToolPartState, UserContent } from "@nyte-ai/schema";
 /**
  * A message the user sent, or one a child, job or action delivered for them.
  *
@@ -92,32 +92,6 @@ export declare function readRawPart(message: PartMessage): RawPart;
  * @category presentation
  */
 export declare function showsReport(message: UserMessage): message is ReportMessage;
-type PendingStatus = Extract<UserStatus, {
-    readonly kind: "pending";
-}>;
-/**
- * A message that waits in the queue: unsent, or pending for a later turn. A pending steer sent
- * while idle or joining the live run is never one.
- *
- * @category presentation
- */
-export type QueuedMessage = UserMessage & {
-    readonly status: Extract<UserStatus, {
-        readonly kind: "unsent";
-    }> | (PendingStatus & {
-        readonly schedule: Exclude<PendingStatus["schedule"], {
-            readonly kind: "joined";
-        }>;
-    });
-};
-/**
- * Whether a message waits in the queue rather than showing in the transcript. A retrying send
- * always waits. Reports, joined steers and steers sent while idle stay in the transcript.
- * Other messages wait only while a run is active.
- *
- * @category presentation
- */
-export declare function waitsInQueue(message: UserMessage, running: boolean): message is QueuedMessage;
 /**
  * What a user message shows: an action's label in place of the prompt it sent.
  *

package/dist/src/client/presentation.js

@@ -21,23 +21,6 @@ function readRawPart(message) {
 function showsReport(message) {
   return message.source.kind === "child" || message.source.kind === "job";
 }
-function waitsInQueue(message, running) {
-  const { status } = message;
-  if (showsReport(message))
-    return false;
-  switch (status.kind) {
-    case "landed":
-      return false;
-    case "unsent":
-      return status.retrying !== null || running && message.delivery !== "steer";
-    case "pending":
-      return running && status.schedule.kind !== "joined" && !(message.delivery === "steer" && status.schedule.kind === "next-turn" && status.schedule.reason === "idle");
-    default: {
-      const _exhaustive = status;
-      return _exhaustive;
-    }
-  }
-}
 function shownContent(message) {
   return message.source.kind === "action" ? message.source.label : message.content;
 }
@@ -386,6 +369,5 @@ export {
   toolStatus,
   toolSubject,
   toolTitle,
-  toolVerbs,
-  waitsInQueue
+  toolVerbs
 };

package/dist/src/codemode.js

@@ -1,7 +1,14 @@
+import {
+  DEFAULT_SEARCH_LIMIT2,
+  createToolSearchDocument2,
+  rankTools2
+} from "../chunks/bash-description-b78pre8c.js";
+
 // src/codemode.ts
 import { CodemodeSandbox } from "@earendil-works/pi-codemode";
-import { renderToolSample } from "@earendil-works/pi-codemode/declarations";
+import { renderToolSample, toCodemodeIdentifier } from "@earendil-works/pi-codemode/declarations";
 import { CODEMODE_SOURCE_GRAMMAR, parseCodemodeSource } from "@earendil-works/pi-codemode/source";
+import { estimateTextTokens } from "@nyte-ai/ai/utils/estimate";
 import { dev } from "@nyte-ai/core";
 import { isJson, isJsonObject, SdkError, standard } from "@nyte-ai/schema";
 import { Type } from "typebox";
@@ -9,8 +16,8 @@ var DESCRIPTION = `Run JavaScript that calls other tools. The input is raw JavaS
 - \`await tools.<name>({ ...args })\` resolves to the tool's output, or its text, and rejects with an Error on failure.
 - Optional first line: \`// @options: {"timeout_ms": 60000}\`
 - \`text(value)\`, \`console.log(...)\` and \`return\` add output; \`store(key, value)\` and \`load(key)\` keep JSON values across codemode calls in this session.
-- \`ALL_TOOLS\`, \`searchTools(query, { limit?, namespace? })\` and \`describeTool(name)\` find tools and their declarations.`;
-var SUMMARY_CHARS = 160;
+- \`ALL_TOOLS\`, \`await searchTools(query, { limit?, namespace? })\`, \`await describeTool(name)\` and \`await describeNamespace(name)\` find unlisted tools, such as MCP tools, and their declarations.`;
+var LISTING_TOKENS = 3000;
 var parameters = standard(Type.Object({ code: Type.String({ description: "Raw JavaScript source." }) }));
 function codemodePlugin(runtime) {
   return {
@@ -18,32 +25,94 @@ function codemodePlugin(runtime) {
     activate(api) {
       api.contribute.tools.add(codemode(api, runtime));
       api.contribute.prompt.add((draft, siblings) => {
-        const reachable = siblings.tools.list().flatMap((tool) => tool.exposure === "code" || tool.exposure === "deferred" ? [`- ${tool.name}: ${summarize(tool.description)}`] : []).toSorted();
-        if (reachable.length === 0)
-          return;
-        draft.set("codemode", {
-          id: "codemode",
-          order: 96,
-          text: [
-            "Tools you reach only from a codemode script, as `await tools.<name>(args)`; `describeTool(name)` inside a script returns a tool's arguments:",
-            ...reachable
-          ].join(`
-`)
-        });
+        const text = listTools(siblings.tools.list());
+        if (text !== null)
+          draft.set("codemode", { id: "codemode", order: 96, text });
       });
     }
   };
 }
-function summarize(description) {
-  const [line = ""] = description.trim().split(`
+function listTools(definitions) {
+  const sections = definitions.flatMap((definition) => {
+    if (definition.exposure !== "code")
+      return [];
+    const inputSchema = toJsonSchema(definition.parameters, "input");
+    const outputSchema = definition.output === undefined ? { type: "string" } : toJsonSchema(definition.output, "output");
+    if (inputSchema === null || outputSchema === null)
+      return [];
+    const id = toCodemodeIdentifier(definition.name);
+    const sample = renderToolSample({
+      name: definition.name,
+      description: definition.description,
+      inputSchema,
+      outputSchema
+    }).trim();
+    const section = `### \`${id}\`${id === definition.name ? "" : ` (\`${definition.name}\`)`}
+${sample}`;
+    return [
+      {
+        namespace: definition.namespace,
+        name: definition.name,
+        section,
+        cost: estimateTextTokens(section)
+      }
+    ];
+  });
+  if (sections.length === 0)
+    return null;
+  const groups = [
+    ...Map.groupBy(sections, (entry) => entry.namespace?.name ?? "").entries()
+  ].toSorted((left, right) => left[0].localeCompare(right[0])).map((pair) => ({ namespace: pair[1][0]?.namespace, entries: pair[1] }));
+  const shown = selectListed(groups, LISTING_TOKENS);
+  return [
+    "Tools you reach only from a codemode script, as `await tools.<name>(args)`:",
+    ...groups.flatMap((group) => {
+      const visible = group.entries.filter((entry) => shown.has(entry.name));
+      if (group.namespace === undefined)
+        return visible.map((entry) => entry.section);
+      const listing = visible.length === group.entries.length ? "" : visible.length === 0 ? " (tools not listed)" : " (some tools not listed)";
+      const description = group.namespace.description?.trim() ?? "";
+      return [
+        `## ${group.namespace.name}${listing}${description === "" ? "" : `
+${description}`}`,
+        ...visible.map((entry) => entry.section)
+      ];
+    })
+  ].join(`
+
 `);
-  return line.length > SUMMARY_CHARS ? `${line.slice(0, SUMMARY_CHARS)}…` : line;
+}
+function selectListed(groups, budget) {
+  const queues = groups.map((group) => group.entries.toSorted((a, b) => a.cost - b.cost));
+  const shown = new Set;
+  let remaining = budget;
+  let active = queues.filter((queue) => queue.length > 0);
+  while (active.length > 0)
+    active = active.filter((queue) => {
+      const next = queue[0];
+      if (next === undefined || next.cost > remaining)
+        return false;
+      remaining -= next.cost;
+      shown.add(next.name);
+      queue.shift();
+      return queue.length > 0;
+    });
+  return shown;
+}
+function toJsonSchema(schema, direction) {
+  try {
+    const converted = schema["~standard"].jsonSchema[direction]({ target: "draft-2020-12" });
+    return isJson(converted) && isJsonObject(converted) ? converted : null;
+  } catch {
+    return null;
+  }
 }
 function codemode(api, runtime) {
   return {
     name: "codemode",
     description: DESCRIPTION,
     parameters,
+    exposure: "model-only",
     grammar: { kind: "lark", source: CODEMODE_SOURCE_GRAMMAR },
     class: () => ({ kind: "custom", label: "Running a script" }),
     effects: "none",
@@ -51,14 +120,24 @@ function codemode(api, runtime) {
     replay: "never",
     async execute(args, invocation) {
       const { code, options } = parseCodemodeSource(args.code);
-      const callable = invocation.tools.list().filter((info) => info.name !== "codemode" && info.exposure !== "hidden");
+      const callable = invocation.tools.list().filter((info) => info.exposure !== "model-only" && info.exposure !== "hidden");
       const stored = await api.storage.get("store");
       if (stored !== undefined && !isJsonObject(stored))
         throw new SdkError("internal", "Codemode's stored values are not a JSON object.");
+      const namespaces = new Map(api.contribute.tools.list().flatMap((definition) => definition.namespace === undefined ? [] : [[definition.name, definition.namespace]]));
+      const samples = new Map(callable.map((info) => [
+        info.name,
+        renderToolSample({
+          name: info.name,
+          description: info.description,
+          inputSchema: info.parameters,
+          outputSchema: info.output ?? { type: "string" }
+        })
+      ]));
       const sandbox = new CodemodeSandbox({
         ...runtime,
-        tools: callable.map((info) => bridge(info, invocation)),
-        globals: discovery(callable),
+        tools: callable.map((info) => bridge(info, samples.get(info.name) ?? "", invocation)),
+        globals: discovery(callable, samples, namespaces),
         timeoutMs: options.timeoutMs ?? 300000,
         memoryLimitBytes: 256 * 1024 * 1024
       });
@@ -102,11 +181,11 @@ ${calls(result)}`);
     }
   };
 }
-function bridge(info, invocation) {
+function bridge(info, sample, invocation) {
   let sequence = 0;
   return {
     name: info.name,
-    description: info.description,
+    description: sample,
     inputSchema: info.parameters,
     outputSchema: info.output ?? { type: "string" },
     async execute(args, { signal }) {
@@ -121,42 +200,70 @@ function unwrapToolOutcome(outcome) {
 `);
   throw new Error(outcome.kind === "failed" ? outcome.message : outcome.kind === "rejected" ? `Rejected: ${outcome.reason}` : `The call was ${outcome.kind}.`);
 }
-function discovery(tools) {
+function discovery(tools, samples, namespaces) {
   return [
     {
       name: "searchTools",
       spread: true,
       execute(args) {
         const [query, options] = Array.isArray(args) ? args : [];
-        const words = new Set(String(query).toLowerCase().split(/[^a-z0-9]+/).filter((word) => word.length > 1));
-        const limit = typeof options === "object" && options !== null && "limit" in options && typeof options.limit === "number" ? options.limit : 8;
-        const namespace = typeof options === "object" && options !== null && "namespace" in options && typeof options.namespace === "string" ? options.namespace : null;
-        return tools.filter((info) => namespace === null || info.namespace === namespace).map((info) => ({
-          info,
-          score: `${info.name} ${info.description}`.toLowerCase().split(/[^a-z0-9]+/).filter((word) => words.has(word)).length
-        })).filter((entry) => entry.score > 0).toSorted((left, right) => right.score - left.score).slice(0, limit).map(({ info }) => ({
-          name: info.name,
-          namespace: info.namespace,
-          description: info.description
+        if (typeof query !== "string")
+          throw new Error("searchTools() expects a query string");
+        const limit = isJsonObject(options) ? options.limit ?? null : null;
+        const namespace = isJsonObject(options) ? options.namespace ?? null : null;
+        if (limit !== null && (typeof limit !== "number" || !Number.isInteger(limit) || limit <= 0))
+          throw new Error("searchTools() limit must be a positive integer");
+        if (namespace !== null && typeof namespace !== "string")
+          throw new Error("searchTools() namespace must be a string");
+        const documents = tools.flatMap((info) => {
+          const found = namespaces.get(info.name);
+          if (namespace !== null && (found === undefined || !matchesNamespace(found, namespace)))
+            return [];
+          return [createToolSearchDocument2(info, found)];
+        });
+        return rankTools2(query, documents, limit ?? DEFAULT_SEARCH_LIMIT2).map((name) => ({
+          name: toCodemodeIdentifier(name),
+          description: samples.get(name) ?? ""
         }));
       }
     },
     {
       name: "describeTool",
       execute(name) {
-        const info = tools.find((candidate) => candidate.name === name);
+        if (typeof name !== "string")
+          throw new Error("describeTool() expects a tool name");
+        const info = tools.find((candidate) => candidate.name === name || toCodemodeIdentifier(candidate.name) === name);
         if (info === undefined)
-          throw new Error(`No tool is named ${String(name)}.`);
-        return renderToolSample({
-          name: info.name,
-          description: info.description,
-          inputSchema: info.parameters,
-          outputSchema: info.output ?? { type: "string" }
+          throw new Error(`No tool is named ${name}.`);
+        return samples.get(info.name) ?? "";
+      }
+    },
+    {
+      name: "describeNamespace",
+      execute(name) {
+        if (typeof name !== "string")
+          throw new Error("describeNamespace() expects a namespace name");
+        const members = tools.filter((info) => {
+          const found = namespaces.get(info.name);
+          return found !== undefined && matchesNamespace(found, name);
         });
+        const namespace = members[0] === undefined ? undefined : namespaces.get(members[0].name);
+        if (namespace === undefined)
+          throw new Error(`No namespace is named ${name}.`);
+        return {
+          name: namespace.name,
+          ...namespace.description === undefined ? {} : { description: namespace.description },
+          ...namespace.instructions === undefined ? {} : { instructions: namespace.instructions },
+          tools: members.map((info) => toCodemodeIdentifier(info.name))
+        };
       }
     }
   ];
 }
+function matchesNamespace(namespace, query) {
+  const id = toCodemodeIdentifier(query);
+  return [namespace.name, ...namespace.aliases ?? []].some((name) => name === query || toCodemodeIdentifier(name) === id);
+}
 function calls(result) {
   return result.calls.length === 0 ? "No tool calls were made." : `Tool calls made before the failure (not undone): ${result.calls.map((call) => `${call.name} (${call.status})`).join(", ")}`;
 }

package/dist/src/core.d.ts

@@ -1,6 +1,6 @@
 import type { HookEntry as SideHookEntry, HookHandler as SideHookHandler, HookName as SideHookName, Plugin as CorePlugin, PluginApi as CorePluginApi } from "@nyte-ai/core";
 export { branchSummary, compaction, definePart, isPart, text, thinking, tool } from "@nyte-ai/core";
-export type { ActionContext, Agent, Command, Durable, HookTable, ModelContextPolicy, Part, PartDefinition, PartState, PromptSection, Setting, SettingDefinition, Skill, ToolDefinition, ToolInvocation, } from "@nyte-ai/core";
+export type { ActionContext, Agent, Command, Durable, HookTable, ModelContextPolicy, Part, PartDefinition, PartState, PromptSection, SearchProvider, SearchResult, Setting, SettingDefinition, Skill, ToolDefinition, ToolInvocation, } from "@nyte-ai/core";
 export type { CompactionPlan, Decision, ModelRequest, Submission, ToolCall, Transcript, } from "@nyte-ai/schema";
 /**
  * A core plugin: per session on the host, with tools, prompt sections,