@xnetjs/plugins 0.2.0 → 0.3.0

package/dist/services/node.js

@@ -180,6 +180,86 @@ function hasWriteScope(plan) {
   );
 }
 
+// src/ai-surface/args.ts
+function readRequiredString(record, key) {
+  const value = record[key];
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`${key} must be a non-empty string`);
+  }
+  return value;
+}
+function readRequiredRecord(record, key) {
+  const value = record[key];
+  if (!isRecord2(value)) {
+    throw new Error(`${key} must be an object`);
+  }
+  return value;
+}
+function readRequiredStringArray(value, key) {
+  const result = readStringArray(value);
+  if (result.length === 0) {
+    throw new Error(`${key} must contain at least one string`);
+  }
+  return result;
+}
+function readStringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((item) => typeof item === "string" && item.trim() !== "");
+}
+function readCsvStringArray(value) {
+  if (!value) return [];
+  return value.split(",").map((item) => item.trim()).filter(Boolean);
+}
+function readOptionalString(record, key) {
+  const value = record[key];
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
+function readOptionalRecord(record, key) {
+  return readRecord(record, key);
+}
+function readOptionalNumber(record, key) {
+  const value = record[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function readOptionalBoolean(record, key) {
+  const value = record[key];
+  return typeof value === "boolean" ? value : void 0;
+}
+function readUrlNumber(params, key) {
+  const value = params.get(key);
+  if (value === null) return void 0;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : void 0;
+}
+function readRecordString(record, key) {
+  const value = record[key];
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
+function readRecord(record, key) {
+  const value = record[key];
+  return isRecord2(value) ? value : void 0;
+}
+function readRecordNumber(record, key) {
+  const value = record[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function readRecordBoolean(record, key) {
+  const value = record[key];
+  return typeof value === "boolean" ? value : void 0;
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readContextSeeds(value) {
+  if (!Array.isArray(value)) return [];
+  return value.map((seed) => {
+    if (!isRecord2(seed)) return null;
+    const kind = typeof seed.kind === "string" ? seed.kind : null;
+    const id = typeof seed.id === "string" ? seed.id : null;
+    return kind && id ? { kind, id } : null;
+  }).filter((seed) => seed !== null);
+}
+
 // src/ai-surface/page-markdown.ts
 var XNET_MARKDOWN_DIRECTIVE_SPECS = [
   {
@@ -415,7 +495,7 @@ function findJsonPayloadEnd(src, startIndex) {
 function parseJsonObject(rawPayload, label, errors) {
   try {
     const parsed = JSON.parse(rawPayload);
-    if (isRecord2(parsed)) return parsed;
+    if (isRecord3(parsed)) return parsed;
     errors.push(`${label} payload must be a JSON object`);
     return null;
   } catch {
@@ -449,7 +529,7 @@ function unquoteYamlScalar(value) {
     return trimmed.slice(1, -1);
   }
 }
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function markdownDiffPrefix(kind) {
@@ -458,900 +538,1094 @@ function markdownDiffPrefix(kind) {
   return " ";
 }
 
-// src/ai-surface/service.ts
-var DEFAULT_LIMITS = {
-  maxListLimit: 100,
-  maxSearchScan: 500,
-  maxSearchResults: 20,
-  maxContextResources: 12,
-  maxCharactersPerResource: 12e3,
-  maxJsonCharacters: 24e3,
-  maxCanvasObjects: 200,
-  maxDatabaseRows: 100
-};
-var AiSurfaceService = class {
-  constructor(config) {
-    this.config = config;
-    this.limits = { ...DEFAULT_LIMITS, ...config.limits };
-    this.clock = config.clock ?? (() => /* @__PURE__ */ new Date());
-    for (const tool of config.extraTools ?? []) {
-      if (!this.extraTools.has(tool.name)) this.extraTools.set(tool.name, tool);
+// src/ai-surface/resources/router.ts
+var XNET_URI_PREFIX = "xnet://";
+var PARAM_SEGMENT_PATTERN = /^\{([a-zA-Z][a-zA-Z0-9]*)\}(.*)$/;
+function createAiResourceRouter() {
+  const routes = [];
+  const router = {
+    register(template, handler) {
+      routes.push(compileRoute(template, handler));
+      return router;
+    },
+    async resolve(host, uri) {
+      const parsed = parseXNetUri(uri);
+      for (const route of routes) {
+        const params = matchRoute(route, parsed);
+        if (params) {
+          return await route.handler(host, { uri, params, searchParams: parsed.searchParams });
+        }
+      }
+      throw new Error(`Resource not found: ${uri}`);
     }
+  };
+  return router;
+}
+function parseXNetUri(uri) {
+  let parsed;
+  try {
+    parsed = new URL(uri);
+  } catch {
+    throw new Error(`Invalid xNet resource URI: ${uri}`);
   }
-  limits;
-  clock;
-  sequence = 0;
-  auditEvents = [];
-  rollbackSnapshots = /* @__PURE__ */ new Map();
-  /** Contributed tools by name (exploration 0196), de-duped at construction. */
-  extraTools = /* @__PURE__ */ new Map();
-  /** The contributed (non-built-in) tools, with built-in name collisions removed. */
-  getExtraTools() {
-    const builtIn = new Set(this.builtInTools().map((t) => t.name));
-    return [...this.extraTools.values()].filter((t) => !builtIn.has(t.name));
+  if (parsed.protocol !== "xnet:") {
+    throw new Error(`Invalid xNet resource URI: ${uri}`);
   }
-  getResources() {
-    return [
-      createResource(
-        "xnet://workspace/summary",
-        "Workspace Summary",
-        "High-level schema counts, recent nodes, and AI surface capabilities.",
-        "application/json",
-        "low",
-        ["workspace.read"]
-      ),
-      createResource(
-        "xnet://workspace/recent",
-        "Recent Workspace Nodes",
-        "Recent nodes with ids, schemas, titles, and revisions.",
-        "application/json",
-        "low",
-        ["workspace.read"]
-      ),
-      createResource(
-        "xnet://nodes",
-        "All Nodes",
-        "Limited list of nodes in the local store.",
-        "application/json",
-        "low",
-        ["workspace.read"]
-      ),
-      createResource(
-        "xnet://schemas",
-        "All Schemas",
-        "List of available schemas and property metadata.",
-        "application/json",
-        "low",
-        ["workspace.read"]
-      ),
-      createResource(
-        "xnet://page/{pageId}.md",
-        "Page Markdown",
-        "Markdown projection for a page, including xNet frontmatter identity.",
-        "text/markdown",
-        "low",
-        ["page.read"],
-        true
-      ),
-      createResource(
-        "xnet://page/{pageId}/outline",
-        "Page Outline",
-        "Page heading outline extracted from the Markdown projection.",
-        "application/json",
-        "low",
-        ["page.read"],
-        true
-      ),
-      createResource(
-        "xnet://database/{databaseId}/schema",
-        "Database Schema",
-        "Database node metadata, declared properties, and known column descriptors.",
-        "application/json",
-        "low",
-        ["database.read"],
-        true
-      ),
-      createResource(
-        "xnet://database/{databaseId}/views",
-        "Database Views",
-        "Known database view descriptors from the database node projection.",
-        "application/json",
-        "low",
-        ["database.read"],
-        true
-      ),
-      createResource(
-        "xnet://database/{databaseId}/sample?limit=10",
-        "Database Sample Rows",
-        "Bounded sample of rows for a database using NodeQueryDescriptor semantics.",
-        "application/json",
-        "low",
-        ["database.read", "database.query"],
-        true
-      ),
-      createResource(
-        "xnet://canvas/{canvasId}/viewport?x=0&y=0&w=1000&h=800",
-        "Canvas Viewport",
-        "Viewport-scoped canvas objects and edges.",
-        "application/json",
-        "low",
-        ["canvas.read"],
-        true
-      ),
-      createResource(
-        "xnet://canvas/{canvasId}/objects",
-        "Canvas Objects",
-        "Bounded list of canvas objects and connectors.",
-        "application/json",
-        "low",
-        ["canvas.read"],
-        true
-      ),
-      createResource(
-        "xnet://canvas/{canvasId}/selection?ids=object-1,object-2",
-        "Canvas Selection",
-        "Selection-scoped canvas objects, edges, and source previews.",
-        "application/json",
-        "low",
-        ["canvas.read"],
-        true
-      ),
-      createResource(
-        "xnet://canvas/{canvasId}/json-canvas",
-        "Canvas JSON Canvas",
-        "JSON Canvas projection with xNet source metadata sidecars.",
-        "application/json",
-        "low",
-        ["canvas.read"],
-        true
-      )
-    ];
+  return {
+    host: parsed.hostname,
+    parts: parsed.pathname.split("/").filter(Boolean).map((part) => decodeURIComponent(part)),
+    searchParams: parsed.searchParams
+  };
+}
+function compileRoute(template, handler) {
+  if (!template.startsWith(XNET_URI_PREFIX)) {
+    throw new Error(`Resource route template must start with ${XNET_URI_PREFIX}: ${template}`);
   }
-  /** The full tool surface: built-in `xnet_*` tools plus contributed extras. */
-  getTools() {
-    const extras = this.getExtraTools().map(
-      ({ invoke: _invoke, ...def }) => def
-    );
-    return [...this.builtInTools(), ...extras];
+  const [path] = template.slice(XNET_URI_PREFIX.length).split("?");
+  const [host, ...rawSegments] = path.split("/").filter(Boolean);
+  if (!host) {
+    throw new Error(`Resource route template must include a host: ${template}`);
   }
-  builtInTools() {
-    return [
-      {
-        name: "xnet_search",
-        title: "Search xNet workspace",
-        description: "Search node titles and searchable properties with pagination and limits.",
-        risk: "low",
-        requiredScopes: ["workspace.search"],
-        inputSchema: {
-          type: "object",
-          properties: {
-            query: { type: "string", description: "Search text." },
-            schemaId: { type: "string", description: "Optional schema IRI filter." },
-            limit: { type: "number", description: "Maximum result count." },
-            offset: { type: "number", description: "Result offset for pagination." }
-          },
-          required: ["query"]
-        }
-      },
-      {
-        name: "xnet_graph_expand",
-        title: "Expand a node along its relations",
-        description: "Walk typed relation edges out from a node to its connected neighbors (bounded by hops and a result limit). Use for just-in-time expansion: fetch a specific node\u2019s connections only when you need them, instead of pulling the whole graph into context.",
-        risk: "low",
-        requiredScopes: ["workspace.read"],
-        inputSchema: {
-          type: "object",
-          properties: {
-            nodeId: { type: "string", description: "The node to expand from." },
-            hops: {
-              type: "number",
-              description: "How many relation hops to walk (1\u20132, default 1)."
-            },
-            limit: { type: "number", description: "Maximum neighbors to return." }
-          },
-          required: ["nodeId"]
-        }
+  return {
+    host,
+    segments: rawSegments.map((segment) => {
+      const param = PARAM_SEGMENT_PATTERN.exec(segment);
+      return param ? { kind: "param", name: param[1], suffix: param[2] } : { kind: "literal", value: segment };
+    }),
+    handler
+  };
+}
+function matchRoute(route, parsed) {
+  if (parsed.host !== route.host) return null;
+  if (parsed.parts.length !== route.segments.length) return null;
+  const params = {};
+  for (const [index, segment] of route.segments.entries()) {
+    const part = parsed.parts[index];
+    if (segment.kind === "literal") {
+      if (part !== segment.value) return null;
+      continue;
+    }
+    if (segment.suffix && !part.endsWith(segment.suffix)) return null;
+    params[segment.name] = segment.suffix ? part.slice(0, -segment.suffix.length) : part;
+  }
+  return params;
+}
+
+// src/ai-surface/resources/routes.ts
+function createBuiltInResourceRouter() {
+  return createAiResourceRouter().register(
+    "xnet://nodes",
+    async (host, { uri }) => host.jsonResource(uri, await host.listNodes())
+  ).register(
+    "xnet://schemas",
+    async (host, { uri }) => host.jsonResource(uri, await host.listSchemas())
+  ).register(
+    "xnet://workspace/summary",
+    async (host, { uri }) => host.jsonResource(uri, await host.getWorkspaceSummary())
+  ).register(
+    "xnet://workspace/recent",
+    async (host, { uri }) => host.jsonResource(uri, await host.getRecentNodes())
+  ).register(
+    "xnet://workspace/search",
+    async (host, { uri, searchParams }) => host.jsonResource(
+      uri,
+      await host.search({
+        query: searchParams.get("q") ?? "",
+        schemaId: searchParams.get("schema") ?? void 0,
+        limit: readUrlNumber(searchParams, "limit"),
+        offset: readUrlNumber(searchParams, "offset")
+      })
+    )
+  ).register(
+    "xnet://node/{nodeId}",
+    async (host, { uri, params }) => host.jsonResource(uri, await host.getNodeProjection(params.nodeId))
+  ).register(
+    "xnet://page/{pageId}.md",
+    async (host, { uri, params }) => await host.readPageMarkdown(params.pageId, true, uri)
+  ).register(
+    "xnet://page/{pageId}",
+    async (host, { uri, params }) => await host.readPageMarkdown(params.pageId, true, uri)
+  ).register(
+    "xnet://page/{pageId}/outline",
+    async (host, { uri, params }) => host.jsonResource(uri, await host.readPageOutline(params.pageId))
+  ).register(
+    "xnet://page/{pageId}/context-pack",
+    async (host, { uri, params }) => host.jsonResource(
+      uri,
+      await host.createContextPack({ seeds: [{ kind: "page", id: params.pageId }] })
+    )
+  ).register(
+    "xnet://database/{databaseId}/schema",
+    async (host, { uri, params }) => host.jsonResource(uri, await host.describeDatabase(params.databaseId))
+  ).register(
+    "xnet://database/{databaseId}/views",
+    async (host, { uri, params }) => host.jsonResource(uri, await host.readDatabaseViews(params.databaseId))
+  ).register(
+    "xnet://database/{databaseId}/sample",
+    async (host, { uri, params, searchParams }) => host.jsonResource(
+      uri,
+      await host.sampleDatabase({
+        databaseId: params.databaseId,
+        sampleSize: readUrlNumber(searchParams, "limit")
+      })
+    )
+  ).register(
+    "xnet://database/{databaseId}/query",
+    async (host, { uri, params, searchParams }) => host.jsonResource(
+      uri,
+      await host.queryDatabase({
+        databaseId: params.databaseId,
+        schemaId: searchParams.get("schema") ?? void 0,
+        search: searchParams.get("q") ?? void 0,
+        materializedView: searchParams.get("view") ? { viewId: searchParams.get("view") ?? "" } : void 0,
+        limit: readUrlNumber(searchParams, "limit"),
+        offset: readUrlNumber(searchParams, "offset")
+      })
+    )
+  ).register(
+    "xnet://canvas/{canvasId}/viewport",
+    async (host, { uri, params, searchParams }) => host.jsonResource(
+      uri,
+      await host.readCanvasViewport({
+        canvasId: params.canvasId,
+        x: readUrlNumber(searchParams, "x"),
+        y: readUrlNumber(searchParams, "y"),
+        w: readUrlNumber(searchParams, "w"),
+        h: readUrlNumber(searchParams, "h"),
+        tileSize: readUrlNumber(searchParams, "tileSize"),
+        tileIds: readCsvStringArray(searchParams.get("tileIds")),
+        includeSourcePreviews: searchParams.get("includeSourcePreviews") === "true"
+      })
+    )
+  ).register(
+    "xnet://canvas/{canvasId}/objects",
+    async (host, { uri, params }) => host.jsonResource(uri, await host.readCanvasObjects(params.canvasId))
+  ).register(
+    "xnet://canvas/{canvasId}/selection",
+    async (host, { uri, params, searchParams }) => host.jsonResource(
+      uri,
+      await host.readCanvasSelection({
+        canvasId: params.canvasId,
+        objectIds: readCsvStringArray(searchParams.get("ids")),
+        includeSourcePreviews: searchParams.get("includeSourcePreviews") !== "false"
+      })
+    )
+  ).register(
+    "xnet://canvas/{canvasId}/json-canvas",
+    async (host, { uri, params, searchParams }) => host.jsonResource(
+      uri,
+      await host.exportCanvasJsonCanvas({
+        canvasId: params.canvasId,
+        includeXNetMetadata: searchParams.get("includeXNetMetadata") !== "false"
+      })
+    )
+  ).register(
+    "xnet://canvas/{canvasId}/object/{objectId}",
+    async (host, { uri, params }) => host.jsonResource(uri, await host.readCanvasObject(params.canvasId, params.objectId))
+  );
+}
+
+// src/ai-surface/tools/audit.ts
+var getAuditLogTool = {
+  definition: {
+    name: "xnet_get_audit_log",
+    title: "Read AI audit log",
+    description: "Read recent AI mutation audit events with optional plan filtering.",
+    risk: "low",
+    requiredScopes: ["workspace.read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        planId: { type: "string", description: "Optional mutation plan id filter." },
+        limit: { type: "number", description: "Maximum audit events to return." }
+      }
+    }
+  },
+  execute: (host, args) => host.getAuditLog({
+    planId: readOptionalString(args, "planId"),
+    limit: readOptionalNumber(args, "limit")
+  })
+};
+var validateMutationPlanTool = {
+  definition: {
+    name: "xnet_validate_mutation_plan",
+    title: "Validate mutation plan",
+    description: "Validate a serialized mutation plan and return errors or warnings.",
+    risk: "medium",
+    requiredScopes: ["workspace.read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        plan: { type: "object", description: "Mutation plan object to validate." }
       },
-      {
-        name: "xnet_create_context_pack",
-        title: "Create context pack",
-        description: "Create a bounded context pack from seeds and optional search results.",
-        risk: "low",
-        requiredScopes: ["workspace.read", "workspace.search"],
-        inputSchema: {
-          type: "object",
-          properties: {
-            query: { type: "string", description: "Optional search query." },
-            seeds: {
-              type: "array",
-              description: "Seed resources such as pages, databases, canvases, or nodes.",
-              items: {
-                type: "object",
-                properties: {
-                  kind: { type: "string", description: "Seed kind." },
-                  id: { type: "string", description: "Seed id." }
-                }
-              }
-            },
-            limit: { type: "number", description: "Maximum resources to include." }
-          }
+      required: ["plan"]
+    }
+  },
+  execute: (_host, args) => {
+    const validation = validateAiMutationPlan(args.plan);
+    return { validation };
+  }
+};
+
+// src/ai-surface/tools/canvas.ts
+var canvasListTool = {
+  definition: {
+    name: "xnet_canvas_list",
+    title: "List canvases",
+    description: "List canvas nodes visible to the AI surface.",
+    risk: "low",
+    requiredScopes: ["canvas.read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "number", description: "Maximum canvas count." },
+        offset: { type: "number", description: "Canvas offset." }
+      }
+    }
+  },
+  execute: async (host, args) => await host.listCanvases({
+    limit: readOptionalNumber(args, "limit"),
+    offset: readOptionalNumber(args, "offset")
+  })
+};
+var canvasReadViewportTool = {
+  definition: {
+    name: "xnet_canvas_read_viewport",
+    title: "Read canvas viewport",
+    description: "Read canvas objects and edges intersecting a viewport.",
+    risk: "low",
+    requiredScopes: ["canvas.read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        canvasId: { type: "string", description: "Canvas node id." },
+        x: { type: "number", description: "Viewport x." },
+        y: { type: "number", description: "Viewport y." },
+        w: { type: "number", description: "Viewport width." },
+        h: { type: "number", description: "Viewport height." },
+        includeSourcePreviews: {
+          type: "boolean",
+          description: "Include previews for source-backed objects."
+        },
+        tileSize: { type: "number", description: "Optional tile size for tile scoping." },
+        tileIds: {
+          type: "array",
+          description: "Optional tile ids such as 0/1/-2 to constrain the read.",
+          items: { type: "string" }
         }
       },
-      {
-        name: "xnet_create_external_context_resource",
-        title: "Create untrusted external context resource",
-        description: "Wrap externally fetched content as an untrusted context-pack resource with an explicit instruction boundary.",
-        risk: "medium",
-        requiredScopes: ["network.fetch"],
-        inputSchema: {
-          type: "object",
-          properties: {
-            url: { type: "string", description: "External source URL." },
-            text: { type: "string", description: "Fetched external text content." },
-            mimeType: { type: "string", description: "Source MIME type. Defaults to text/plain." }
-          },
-          required: ["url", "text"]
+      required: ["canvasId"]
+    }
+  },
+  execute: async (host, args) => await host.readCanvasViewport({
+    canvasId: readRequiredString(args, "canvasId"),
+    x: readOptionalNumber(args, "x"),
+    y: readOptionalNumber(args, "y"),
+    w: readOptionalNumber(args, "w"),
+    h: readOptionalNumber(args, "h"),
+    tileSize: readOptionalNumber(args, "tileSize"),
+    tileIds: readStringArray(args.tileIds),
+    includeSourcePreviews: readOptionalBoolean(args, "includeSourcePreviews") ?? false
+  })
+};
+var canvasReadSelectionTool = {
+  definition: {
+    name: "xnet_canvas_read_selection",
+    title: "Read canvas selection",
+    description: "Read selected canvas objects, connected edges, and optional source previews.",
+    risk: "low",
+    requiredScopes: ["canvas.read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        canvasId: { type: "string", description: "Canvas node id." },
+        objectIds: {
+          type: "array",
+          description: "Selected object ids.",
+          items: { type: "string" }
+        },
+        includeSourcePreviews: {
+          type: "boolean",
+          description: "Include previews for source-backed objects."
         }
       },
-      {
-        name: "xnet_read_page_markdown",
-        title: "Read page Markdown",
-        description: "Read a page as Markdown with optional xNet frontmatter.",
-        risk: "low",
-        requiredScopes: ["page.read"],
-        inputSchema: {
-          type: "object",
-          properties: {
-            pageId: { type: "string", description: "Page node id." },
-            includeFrontmatter: {
-              type: "boolean",
-              description: "Include xNet identity frontmatter. Defaults to true."
-            }
-          },
-          required: ["pageId"]
-        }
+      required: ["canvasId", "objectIds"]
+    }
+  },
+  execute: async (host, args) => await host.readCanvasSelection({
+    canvasId: readRequiredString(args, "canvasId"),
+    objectIds: readRequiredStringArray(args.objectIds, "objectIds"),
+    includeSourcePreviews: readOptionalBoolean(args, "includeSourcePreviews") ?? false
+  })
+};
+var canvasSearchTool = {
+  definition: {
+    name: "xnet_canvas_search",
+    title: "Search canvas",
+    description: "Search canvas object text, labels, ids, and source metadata.",
+    risk: "low",
+    requiredScopes: ["canvas.read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        canvasId: { type: "string", description: "Canvas node id." },
+        query: { type: "string", description: "Search text." },
+        limit: { type: "number", description: "Maximum result count." }
       },
-      {
-        name: "xnet_validate_page_markdown",
-        title: "Validate page Markdown",
-        description: "Validate xNet page frontmatter and supported xNet Markdown directives.",
-        risk: "low",
-        requiredScopes: ["page.read"],
-        inputSchema: {
-          type: "object",
-          properties: {
-            pageId: { type: "string", description: "Optional target page node id." },
-            baseRevision: { type: "string", description: "Optional expected base revision." },
-            markdown: { type: "string", description: "Markdown to validate." }
-          },
-          required: ["markdown"]
-        }
+      required: ["canvasId", "query"]
+    }
+  },
+  execute: async (host, args) => await host.searchCanvas({
+    canvasId: readRequiredString(args, "canvasId"),
+    query: readRequiredString(args, "query"),
+    limit: readOptionalNumber(args, "limit")
+  })
+};
+var canvasExportJsonCanvasTool = {
+  definition: {
+    name: "xnet_canvas_export_json_canvas",
+    title: "Export canvas as JSON Canvas",
+    description: "Export a canvas or viewport as JSON Canvas with xNet source metadata.",
+    risk: "low",
+    requiredScopes: ["canvas.read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        canvasId: { type: "string", description: "Canvas node id." },
+        includeXNetMetadata: {
+          type: "boolean",
+          description: "Include xNet source metadata. Defaults to true."
+        },
+        x: { type: "number", description: "Optional viewport x." },
+        y: { type: "number", description: "Optional viewport y." },
+        w: { type: "number", description: "Optional viewport width." },
+        h: { type: "number", description: "Optional viewport height." }
       },
-      {
-        name: "xnet_plan_page_patch",
-        title: "Plan page Markdown patch",
-        description: "Validate an edited Markdown page and return a mutation plan without applying it.",
-        risk: "medium",
-        requiredScopes: ["page.read", "page.propose"],
-        inputSchema: {
-          type: "object",
-          properties: {
-            pageId: { type: "string", description: "Page node id." },
-            baseRevision: { type: "string", description: "Revision the patch was based on." },
-            markdown: { type: "string", description: "Proposed full Markdown replacement." },
-            intent: { type: "string", description: "User or agent intent for the patch." },
-            actor: { type: "string", description: "Agent or user creating the plan." }
-          },
-          required: ["pageId", "markdown"]
-        }
+      required: ["canvasId"]
+    }
+  },
+  execute: async (host, args) => await host.exportCanvasJsonCanvas({
+    canvasId: readRequiredString(args, "canvasId"),
+    includeXNetMetadata: readOptionalBoolean(args, "includeXNetMetadata") ?? true,
+    x: readOptionalNumber(args, "x"),
+    y: readOptionalNumber(args, "y"),
+    w: readOptionalNumber(args, "w"),
+    h: readOptionalNumber(args, "h")
+  })
+};
+var canvasPlanJsonCanvasImportTool = {
+  definition: {
+    name: "xnet_canvas_plan_json_canvas_import",
+    title: "Plan JSON Canvas import",
+    description: "Convert a JSON Canvas document into a plan-only canvas mutation.",
+    risk: "medium",
+    requiredScopes: ["canvas.read", "canvas.propose"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        canvasId: { type: "string", description: "Canvas node id." },
+        document: { type: "object", description: "JSON Canvas document." },
+        baseRevision: { type: "string", description: "Revision the import was based on." },
+        actor: { type: "string", description: "Agent or user creating the plan." },
+        intent: { type: "string", description: "User or agent intent for the import." }
       },
-      {
-        name: "xnet_apply_page_markdown",
-        title: "Apply page Markdown plan",
-        description: "Apply a validated page Markdown mutation plan through the configured TipTap/Yjs document adapter, with a node-property fallback.",
-        risk: "high",
-        requiredScopes: ["page.read", "page.write"],
-        inputSchema: {
-          type: "object",
-          properties: {
-            plan: { type: "object", description: "Validated page Markdown mutation plan." },
-            confirmApply: {
-              type: "boolean",
-              description: "Must be true to apply the page Markdown plan."
-            },
-            allowStale: {
-              type: "boolean",
-              description: "Allow applying when the plan base revision differs from the live node."
-            }
-          },
-          required: ["plan", "confirmApply"]
-        }
+      required: ["canvasId", "document"]
+    }
+  },
+  execute: async (host, args) => await host.planCanvasJsonCanvasImport(args)
+};
+var planCanvasMutationTool = {
+  definition: {
+    name: "xnet_plan_canvas_mutation",
+    title: "Plan canvas mutation",
+    description: "Create a canvas mutation plan for later review without applying it.",
+    risk: "medium",
+    requiredScopes: ["canvas.read", "canvas.propose"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        canvasId: { type: "string", description: "Canvas node id." },
+        baseRevision: { type: "string", description: "Revision the mutation was based on." },
+        operations: { type: "array", description: "Canvas operations to validate." },
+        intent: { type: "string", description: "User or agent intent for the mutation." },
+        actor: { type: "string", description: "Agent or user creating the plan." }
       },
-      {
-        name: "xnet_get_audit_log",
-        title: "Read AI audit log",
-        description: "Read recent AI mutation audit events with optional plan filtering.",
-        risk: "low",
-        requiredScopes: ["workspace.read"],
-        inputSchema: {
-          type: "object",
-          properties: {
-            planId: { type: "string", description: "Optional mutation plan id filter." },
-            limit: { type: "number", description: "Maximum audit events to return." }
-          }
+      required: ["canvasId", "operations"]
+    }
+  },
+  execute: async (host, args) => await host.planCanvasMutation(args)
+};
+var canvasToolEntries = [
+  canvasListTool,
+  canvasReadViewportTool,
+  canvasReadSelectionTool,
+  canvasSearchTool,
+  canvasExportJsonCanvasTool,
+  canvasPlanJsonCanvasImportTool,
+  planCanvasMutationTool
+];
+
+// src/ai-surface/tools/database.ts
+var databaseDescribeTool = {
+  definition: {
+    name: "xnet_database_describe",
+    title: "Describe database",
+    description: "Describe database schema, columns, views, row schema, and row counts.",
+    risk: "low",
+    requiredScopes: ["database.read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        databaseId: { type: "string", description: "Database node id." },
+        includeSample: {
+          type: "boolean",
+          description: "Include a small descriptor-backed row sample."
         }
       },
-      {
-        name: "xnet_rollback_page_markdown",
-        title: "Rollback page Markdown apply",
-        description: "Rollback a previously applied page Markdown plan by rollback handle.",
-        risk: "high",
-        requiredScopes: ["page.write"],
-        inputSchema: {
+      required: ["databaseId"]
+    }
+  },
+  execute: async (host, args) => await host.describeDatabase(readRequiredString(args, "databaseId"), {
+    includeSample: readOptionalBoolean(args, "includeSample") ?? false
+  })
+};
+var databaseQueryTool = {
+  definition: {
+    name: "xnet_database_query",
+    title: "Query database rows",
+    description: "Read a bounded page of database rows using NodeQueryDescriptor-compatible options.",
+    risk: "low",
+    requiredScopes: ["database.read", "database.query"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        databaseId: { type: "string", description: "Database node id." },
+        schemaId: { type: "string", description: "Optional row schema IRI." },
+        descriptor: {
           type: "object",
-          properties: {
-            rollbackHandle: { type: "string", description: "Rollback handle from apply result." },
-            confirmRollback: {
-              type: "boolean",
-              description: "Must be true to perform the rollback."
-            }
-          },
-          required: ["rollbackHandle", "confirmRollback"]
-        }
-      },
-      {
-        name: "xnet_database_describe",
-        title: "Describe database",
-        description: "Describe database schema, columns, views, row schema, and row counts.",
-        risk: "low",
-        requiredScopes: ["database.read"],
-        inputSchema: {
+          description: "Optional NodeQueryDescriptor-compatible query shape."
+        },
+        where: {
           type: "object",
-          properties: {
-            databaseId: { type: "string", description: "Database node id." },
-            includeSample: {
-              type: "boolean",
-              description: "Include a small descriptor-backed row sample."
-            }
-          },
-          required: ["databaseId"]
-        }
-      },
-      {
-        name: "xnet_database_query",
-        title: "Query database rows",
-        description: "Read a bounded page of database rows using NodeQueryDescriptor-compatible options.",
-        risk: "low",
-        requiredScopes: ["database.read", "database.query"],
-        inputSchema: {
+          description: "Optional exact property filters for row nodes."
+        },
+        search: {
           type: "object",
-          properties: {
-            databaseId: { type: "string", description: "Database node id." },
-            schemaId: { type: "string", description: "Optional row schema IRI." },
-            descriptor: {
-              type: "object",
-              description: "Optional NodeQueryDescriptor-compatible query shape."
-            },
-            where: {
-              type: "object",
-              description: "Optional exact property filters for row nodes."
-            },
-            search: {
-              type: "object",
-              description: "Optional NodeQueryDescriptor search filter."
-            },
-            orderBy: {
-              type: "object",
-              description: "Optional NodeQueryDescriptor order map."
-            },
-            materializedView: {
-              type: "object",
-              description: "Optional materialized view query options."
-            },
-            count: { type: "string", description: "Page count mode: exact, estimate, or none." },
-            limit: { type: "number", description: "Maximum row count." },
-            offset: { type: "number", description: "Row offset." }
-          },
-          required: ["databaseId"]
-        }
-      },
-      {
-        name: "xnet_database_sample",
-        title: "Sample database rows",
-        description: "Return a small deterministic sample for schema and content inspection.",
-        risk: "low",
-        requiredScopes: ["database.read", "database.query"],
-        inputSchema: {
+          description: "Optional NodeQueryDescriptor search filter."
+        },
+        orderBy: {
           type: "object",
-          properties: {
-            databaseId: { type: "string", description: "Database node id." },
-            schemaId: { type: "string", description: "Optional row schema IRI." },
-            sampleSize: { type: "number", description: "Sample row count." },
-            descriptor: {
-              type: "object",
-              description: "Optional NodeQueryDescriptor-compatible query shape."
-            }
-          },
-          required: ["databaseId"]
-        }
-      },
-      {
-        name: "xnet_database_explain_query",
-        title: "Explain database query",
-        description: "Explain descriptor, pagination, materialized view, and storage plan metadata.",
-        risk: "low",
-        requiredScopes: ["database.read", "database.query", "storage.diagnostics"],
-        inputSchema: {
+          description: "Optional NodeQueryDescriptor order map."
+        },
+        materializedView: {
           type: "object",
-          properties: {
-            databaseId: { type: "string", description: "Database node id." },
-            schemaId: { type: "string", description: "Optional row schema IRI." },
-            descriptor: {
-              type: "object",
-              description: "Optional NodeQueryDescriptor-compatible query shape."
-            },
-            limit: { type: "number", description: "Maximum row count for the dry-run query." },
-            offset: { type: "number", description: "Row offset." }
-          },
-          required: ["databaseId"]
-        }
+          description: "Optional materialized view query options."
+        },
+        count: { type: "string", description: "Page count mode: exact, estimate, or none." },
+        limit: { type: "number", description: "Maximum row count." },
+        offset: { type: "number", description: "Row offset." }
       },
-      {
-        name: "xnet_plan_database_mutation",
-        title: "Plan database mutation",
-        description: "Create a database mutation plan for later review without applying it.",
-        risk: "medium",
-        requiredScopes: ["database.read", "database.propose"],
-        inputSchema: {
+      required: ["databaseId"]
+    }
+  },
+  execute: async (host, args) => await host.queryDatabase({
+    databaseId: readRequiredString(args, "databaseId"),
+    schemaId: readOptionalString(args, "schemaId"),
+    descriptor: readOptionalRecord(args, "descriptor"),
+    where: readOptionalRecord(args, "where"),
+    search: args.search,
+    orderBy: readOptionalRecord(args, "orderBy"),
+    materializedView: args.materializedView,
+    count: readOptionalString(args, "count"),
+    limit: readOptionalNumber(args, "limit"),
+    offset: readOptionalNumber(args, "offset")
+  })
+};
+var databaseSampleTool = {
+  definition: {
+    name: "xnet_database_sample",
+    title: "Sample database rows",
+    description: "Return a small deterministic sample for schema and content inspection.",
+    risk: "low",
+    requiredScopes: ["database.read", "database.query"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        databaseId: { type: "string", description: "Database node id." },
+        schemaId: { type: "string", description: "Optional row schema IRI." },
+        sampleSize: { type: "number", description: "Sample row count." },
+        descriptor: {
           type: "object",
-          properties: {
-            databaseId: { type: "string", description: "Database node id." },
-            baseRevision: { type: "string", description: "Revision the mutation was based on." },
-            operations: { type: "array", description: "Database operations to validate." },
-            intent: { type: "string", description: "User or agent intent for the mutation." },
-            actor: { type: "string", description: "Agent or user creating the plan." }
-          },
-          required: ["databaseId", "operations"]
+          description: "Optional NodeQueryDescriptor-compatible query shape."
         }
       },
-      {
-        name: "xnet_apply_database_mutation",
-        title: "Apply database mutation plan",
-        description: "Apply a validated database row/schema mutation plan with transactional row rollback and audit logging.",
-        risk: "high",
-        requiredScopes: ["database.read", "database.write.rows", "database.write.schema"],
-        inputSchema: {
+      required: ["databaseId"]
+    }
+  },
+  execute: async (host, args) => await host.sampleDatabase({
+    databaseId: readRequiredString(args, "databaseId"),
+    schemaId: readOptionalString(args, "schemaId"),
+    descriptor: readOptionalRecord(args, "descriptor"),
+    sampleSize: readOptionalNumber(args, "sampleSize")
+  })
+};
+var databaseExplainQueryTool = {
+  definition: {
+    name: "xnet_database_explain_query",
+    title: "Explain database query",
+    description: "Explain descriptor, pagination, materialized view, and storage plan metadata.",
+    risk: "low",
+    requiredScopes: ["database.read", "database.query", "storage.diagnostics"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        databaseId: { type: "string", description: "Database node id." },
+        schemaId: { type: "string", description: "Optional row schema IRI." },
+        descriptor: {
           type: "object",
-          properties: {
-            plan: { type: "object", description: "Validated database mutation plan." },
-            confirmApply: {
-              type: "boolean",
-              description: "Must be true to apply the database mutation plan."
-            },
-            allowStale: {
-              type: "boolean",
-              description: "Allow applying when the plan base revision differs from the live database node."
-            }
-          },
-          required: ["plan", "confirmApply"]
-        }
+          description: "Optional NodeQueryDescriptor-compatible query shape."
+        },
+        limit: { type: "number", description: "Maximum row count for the dry-run query." },
+        offset: { type: "number", description: "Row offset." }
       },
-      {
-        name: "xnet_canvas_list",
-        title: "List canvases",
-        description: "List canvas nodes visible to the AI surface.",
-        risk: "low",
-        requiredScopes: ["canvas.read"],
-        inputSchema: {
-          type: "object",
-          properties: {
-            limit: { type: "number", description: "Maximum canvas count." },
-            offset: { type: "number", description: "Canvas offset." }
-          }
-        }
+      required: ["databaseId"]
+    }
+  },
+  execute: async (host, args) => await host.explainDatabaseQuery({
+    databaseId: readRequiredString(args, "databaseId"),
+    schemaId: readOptionalString(args, "schemaId"),
+    descriptor: readOptionalRecord(args, "descriptor"),
+    limit: readOptionalNumber(args, "limit"),
+    offset: readOptionalNumber(args, "offset")
+  })
+};
+var planDatabaseMutationTool = {
+  definition: {
+    name: "xnet_plan_database_mutation",
+    title: "Plan database mutation",
+    description: "Create a database mutation plan for later review without applying it.",
+    risk: "medium",
+    requiredScopes: ["database.read", "database.propose"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        databaseId: { type: "string", description: "Database node id." },
+        baseRevision: { type: "string", description: "Revision the mutation was based on." },
+        operations: { type: "array", description: "Database operations to validate." },
+        intent: { type: "string", description: "User or agent intent for the mutation." },
+        actor: { type: "string", description: "Agent or user creating the plan." }
       },
-      {
-        name: "xnet_canvas_read_viewport",
-        title: "Read canvas viewport",
-        description: "Read canvas objects and edges intersecting a viewport.",
-        risk: "low",
-        requiredScopes: ["canvas.read"],
-        inputSchema: {
-          type: "object",
-          properties: {
-            canvasId: { type: "string", description: "Canvas node id." },
-            x: { type: "number", description: "Viewport x." },
-            y: { type: "number", description: "Viewport y." },
-            w: { type: "number", description: "Viewport width." },
-            h: { type: "number", description: "Viewport height." },
-            includeSourcePreviews: {
-              type: "boolean",
-              description: "Include previews for source-backed objects."
-            },
-            tileSize: { type: "number", description: "Optional tile size for tile scoping." },
-            tileIds: {
-              type: "array",
-              description: "Optional tile ids such as 0/1/-2 to constrain the read.",
-              items: { type: "string" }
-            }
-          },
-          required: ["canvasId"]
+      required: ["databaseId", "operations"]
+    }
+  },
+  execute: async (host, args) => await host.planDatabaseMutation(args)
+};
+var applyDatabaseMutationTool = {
+  definition: {
+    name: "xnet_apply_database_mutation",
+    title: "Apply database mutation plan",
+    description: "Apply a validated database row/schema mutation plan with transactional row rollback and audit logging.",
+    risk: "high",
+    requiredScopes: ["database.read", "database.write.rows", "database.write.schema"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        plan: { type: "object", description: "Validated database mutation plan." },
+        confirmApply: {
+          type: "boolean",
+          description: "Must be true to apply the database mutation plan."
+        },
+        allowStale: {
+          type: "boolean",
+          description: "Allow applying when the plan base revision differs from the live database node."
         }
       },
-      {
-        name: "xnet_canvas_read_selection",
-        title: "Read canvas selection",
-        description: "Read selected canvas objects, connected edges, and optional source previews.",
-        risk: "low",
-        requiredScopes: ["canvas.read"],
-        inputSchema: {
-          type: "object",
-          properties: {
-            canvasId: { type: "string", description: "Canvas node id." },
-            objectIds: {
-              type: "array",
-              description: "Selected object ids.",
-              items: { type: "string" }
-            },
-            includeSourcePreviews: {
-              type: "boolean",
-              description: "Include previews for source-backed objects."
-            }
-          },
-          required: ["canvasId", "objectIds"]
+      required: ["plan", "confirmApply"]
+    }
+  },
+  execute: async (host, args) => await host.applyDatabaseMutation(args)
+};
+var databaseToolEntries = [
+  databaseDescribeTool,
+  databaseQueryTool,
+  databaseSampleTool,
+  databaseExplainQueryTool,
+  planDatabaseMutationTool,
+  applyDatabaseMutationTool
+];
+
+// src/ai-surface/tools/page-mutation.ts
+var readPageMarkdownTool = {
+  definition: {
+    name: "xnet_read_page_markdown",
+    title: "Read page Markdown",
+    description: "Read a page as Markdown with optional xNet frontmatter.",
+    risk: "low",
+    requiredScopes: ["page.read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        pageId: { type: "string", description: "Page node id." },
+        includeFrontmatter: {
+          type: "boolean",
+          description: "Include xNet identity frontmatter. Defaults to true."
         }
       },
-      {
-        name: "xnet_canvas_search",
-        title: "Search canvas",
-        description: "Search canvas object text, labels, ids, and source metadata.",
-        risk: "low",
-        requiredScopes: ["canvas.read"],
-        inputSchema: {
-          type: "object",
-          properties: {
-            canvasId: { type: "string", description: "Canvas node id." },
-            query: { type: "string", description: "Search text." },
-            limit: { type: "number", description: "Maximum result count." }
-          },
-          required: ["canvasId", "query"]
-        }
+      required: ["pageId"]
+    }
+  },
+  execute: async (host, args) => {
+    const content = await host.readPageMarkdown(
+      readRequiredString(args, "pageId"),
+      readOptionalBoolean(args, "includeFrontmatter") ?? true
+    );
+    return { markdown: content.text, mimeType: content.mimeType, uri: content.uri };
+  }
+};
+var validatePageMarkdownTool = {
+  definition: {
+    name: "xnet_validate_page_markdown",
+    title: "Validate page Markdown",
+    description: "Validate xNet page frontmatter and supported xNet Markdown directives.",
+    risk: "low",
+    requiredScopes: ["page.read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        pageId: { type: "string", description: "Optional target page node id." },
+        baseRevision: { type: "string", description: "Optional expected base revision." },
+        markdown: { type: "string", description: "Markdown to validate." }
       },
-      {
-        name: "xnet_canvas_export_json_canvas",
-        title: "Export canvas as JSON Canvas",
-        description: "Export a canvas or viewport as JSON Canvas with xNet source metadata.",
-        risk: "low",
-        requiredScopes: ["canvas.read"],
-        inputSchema: {
-          type: "object",
-          properties: {
-            canvasId: { type: "string", description: "Canvas node id." },
-            includeXNetMetadata: {
-              type: "boolean",
-              description: "Include xNet source metadata. Defaults to true."
-            },
-            x: { type: "number", description: "Optional viewport x." },
-            y: { type: "number", description: "Optional viewport y." },
-            w: { type: "number", description: "Optional viewport width." },
-            h: { type: "number", description: "Optional viewport height." }
-          },
-          required: ["canvasId"]
-        }
+      required: ["markdown"]
+    }
+  },
+  execute: async (host, args) => {
+    const pageId = readOptionalString(args, "pageId");
+    const node = pageId ? await host.getNodeOrThrow(pageId) : null;
+    return validateXNetPageMarkdown(readRequiredString(args, "markdown"), {
+      pageId,
+      schemaId: node?.schemaId,
+      baseRevision: readOptionalString(args, "baseRevision")
+    });
+  }
+};
+var planPagePatchTool = {
+  definition: {
+    name: "xnet_plan_page_patch",
+    title: "Plan page Markdown patch",
+    description: "Validate an edited Markdown page and return a mutation plan without applying it.",
+    risk: "medium",
+    requiredScopes: ["page.read", "page.propose"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        pageId: { type: "string", description: "Page node id." },
+        baseRevision: { type: "string", description: "Revision the patch was based on." },
+        markdown: { type: "string", description: "Proposed full Markdown replacement." },
+        intent: { type: "string", description: "User or agent intent for the patch." },
+        actor: { type: "string", description: "Agent or user creating the plan." }
       },
-      {
-        name: "xnet_canvas_plan_json_canvas_import",
-        title: "Plan JSON Canvas import",
-        description: "Convert a JSON Canvas document into a plan-only canvas mutation.",
-        risk: "medium",
-        requiredScopes: ["canvas.read", "canvas.propose"],
-        inputSchema: {
-          type: "object",
-          properties: {
-            canvasId: { type: "string", description: "Canvas node id." },
-            document: { type: "object", description: "JSON Canvas document." },
-            baseRevision: { type: "string", description: "Revision the import was based on." },
-            actor: { type: "string", description: "Agent or user creating the plan." },
-            intent: { type: "string", description: "User or agent intent for the import." }
-          },
-          required: ["canvasId", "document"]
+      required: ["pageId", "markdown"]
+    }
+  },
+  execute: async (host, args) => await host.planPagePatch(args)
+};
+var applyPageMarkdownTool = {
+  definition: {
+    name: "xnet_apply_page_markdown",
+    title: "Apply page Markdown plan",
+    description: "Apply a validated page Markdown mutation plan through the configured TipTap/Yjs document adapter, with a node-property fallback.",
+    risk: "high",
+    requiredScopes: ["page.read", "page.write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        plan: { type: "object", description: "Validated page Markdown mutation plan." },
+        confirmApply: {
+          type: "boolean",
+          description: "Must be true to apply the page Markdown plan."
+        },
+        allowStale: {
+          type: "boolean",
+          description: "Allow applying when the plan base revision differs from the live node."
         }
       },
-      {
-        name: "xnet_plan_canvas_mutation",
-        title: "Plan canvas mutation",
-        description: "Create a canvas mutation plan for later review without applying it.",
-        risk: "medium",
-        requiredScopes: ["canvas.read", "canvas.propose"],
-        inputSchema: {
-          type: "object",
-          properties: {
-            canvasId: { type: "string", description: "Canvas node id." },
-            baseRevision: { type: "string", description: "Revision the mutation was based on." },
-            operations: { type: "array", description: "Canvas operations to validate." },
-            intent: { type: "string", description: "User or agent intent for the mutation." },
-            actor: { type: "string", description: "Agent or user creating the plan." }
-          },
-          required: ["canvasId", "operations"]
+      required: ["plan", "confirmApply"]
+    }
+  },
+  execute: async (host, args) => await host.applyPageMarkdown(args)
+};
+var rollbackPageMarkdownTool = {
+  definition: {
+    name: "xnet_rollback_page_markdown",
+    title: "Rollback page Markdown apply",
+    description: "Rollback a previously applied page Markdown plan by rollback handle.",
+    risk: "high",
+    requiredScopes: ["page.write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        rollbackHandle: { type: "string", description: "Rollback handle from apply result." },
+        confirmRollback: {
+          type: "boolean",
+          description: "Must be true to perform the rollback."
         }
       },
-      {
-        name: "xnet_validate_mutation_plan",
-        title: "Validate mutation plan",
-        description: "Validate a serialized mutation plan and return errors or warnings.",
-        risk: "medium",
-        requiredScopes: ["workspace.read"],
-        inputSchema: {
-          type: "object",
-          properties: {
-            plan: { type: "object", description: "Mutation plan object to validate." }
-          },
-          required: ["plan"]
-        }
+      required: ["rollbackHandle", "confirmRollback"]
+    }
+  },
+  execute: async (host, args) => await host.rollbackPageMarkdown(args)
+};
+
+// src/ai-surface/tools/search.ts
+var searchTool = {
+  definition: {
+    name: "xnet_search",
+    title: "Search xNet workspace",
+    description: "Search node titles and searchable properties with pagination and limits.",
+    risk: "low",
+    requiredScopes: ["workspace.search"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search text." },
+        schemaId: { type: "string", description: "Optional schema IRI filter." },
+        limit: { type: "number", description: "Maximum result count." },
+        offset: { type: "number", description: "Result offset for pagination." }
+      },
+      required: ["query"]
+    }
+  },
+  execute: async (host, args) => await host.search({
+    query: readRequiredString(args, "query"),
+    schemaId: readOptionalString(args, "schemaId") ?? readOptionalString(args, "schema"),
+    limit: readOptionalNumber(args, "limit"),
+    offset: readOptionalNumber(args, "offset")
+  })
+};
+var graphExpandTool = {
+  definition: {
+    name: "xnet_graph_expand",
+    title: "Expand a node along its relations",
+    description: "Walk typed relation edges out from a node to its connected neighbors (bounded by hops and a result limit). Use for just-in-time expansion: fetch a specific node\u2019s connections only when you need them, instead of pulling the whole graph into context.",
+    risk: "low",
+    requiredScopes: ["workspace.read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        nodeId: { type: "string", description: "The node to expand from." },
+        hops: {
+          type: "number",
+          description: "How many relation hops to walk (1\u20132, default 1)."
+        },
+        limit: { type: "number", description: "Maximum neighbors to return." }
+      },
+      required: ["nodeId"]
+    }
+  },
+  execute: async (host, args) => await host.expandGraph({
+    nodeId: readRequiredString(args, "nodeId"),
+    hops: readOptionalNumber(args, "hops"),
+    limit: readOptionalNumber(args, "limit")
+  })
+};
+var createContextPackTool = {
+  definition: {
+    name: "xnet_create_context_pack",
+    title: "Create context pack",
+    description: "Create a bounded context pack from seeds and optional search results.",
+    risk: "low",
+    requiredScopes: ["workspace.read", "workspace.search"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Optional search query." },
+        seeds: {
+          type: "array",
+          description: "Seed resources such as pages, databases, canvases, or nodes.",
+          items: {
+            type: "object",
+            properties: {
+              kind: { type: "string", description: "Seed kind." },
+              id: { type: "string", description: "Seed id." }
+            }
+          }
+        },
+        limit: { type: "number", description: "Maximum resources to include." }
       }
+    }
+  },
+  execute: async (host, args) => await host.createContextPack({
+    query: readOptionalString(args, "query"),
+    seeds: readContextSeeds(args.seeds),
+    limit: readOptionalNumber(args, "limit")
+  })
+};
+var createExternalContextResourceTool = {
+  definition: {
+    name: "xnet_create_external_context_resource",
+    title: "Create untrusted external context resource",
+    description: "Wrap externally fetched content as an untrusted context-pack resource with an explicit instruction boundary.",
+    risk: "medium",
+    requiredScopes: ["network.fetch"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: { type: "string", description: "External source URL." },
+        text: { type: "string", description: "Fetched external text content." },
+        mimeType: { type: "string", description: "Source MIME type. Defaults to text/plain." }
+      },
+      required: ["url", "text"]
+    }
+  },
+  execute: (host, args) => host.createExternalContextResource({
+    url: readRequiredString(args, "url"),
+    text: readRequiredString(args, "text"),
+    mimeType: readOptionalString(args, "mimeType")
+  })
+};
+var searchToolEntries = [
+  searchTool,
+  graphExpandTool,
+  createContextPackTool,
+  createExternalContextResourceTool
+];
+
+// src/ai-surface/tools/index.ts
+var BUILT_IN_TOOL_ENTRIES = [
+  ...searchToolEntries,
+  readPageMarkdownTool,
+  validatePageMarkdownTool,
+  planPagePatchTool,
+  applyPageMarkdownTool,
+  getAuditLogTool,
+  rollbackPageMarkdownTool,
+  ...databaseToolEntries,
+  ...canvasToolEntries,
+  validateMutationPlanTool
+];
+var BUILT_IN_TOOLS_BY_NAME = new Map(
+  BUILT_IN_TOOL_ENTRIES.map((entry) => [entry.definition.name, entry])
+);
+
+// src/ai-surface/service.ts
+var DEFAULT_LIMITS = {
+  maxListLimit: 100,
+  maxSearchScan: 500,
+  maxSearchResults: 20,
+  maxContextResources: 12,
+  maxCharactersPerResource: 12e3,
+  maxJsonCharacters: 24e3,
+  maxCanvasObjects: 200,
+  maxDatabaseRows: 100
+};
+var BUILT_IN_RESOURCE_ROUTES = createBuiltInResourceRouter();
+var AiSurfaceService = class {
+  constructor(config) {
+    this.config = config;
+    this.limits = { ...DEFAULT_LIMITS, ...config.limits };
+    this.clock = config.clock ?? (() => /* @__PURE__ */ new Date());
+    for (const tool of config.extraTools ?? []) {
+      if (!this.extraTools.has(tool.name)) this.extraTools.set(tool.name, tool);
+    }
+  }
+  limits;
+  clock;
+  sequence = 0;
+  auditEvents = [];
+  rollbackSnapshots = /* @__PURE__ */ new Map();
+  /** Contributed tools by name (exploration 0196), de-duped at construction. */
+  extraTools = /* @__PURE__ */ new Map();
+  /**
+   * The narrow surface handed to built-in tool handlers and resource routes
+   * (`tools/`, `resources/`): closures over the private methods, so the class
+   * stays the facade and its public type is unchanged. The closures are lazy —
+   * nothing here runs until a tool call or resource read arrives.
+   */
+  host = {
+    search: (options) => this.search(options),
+    expandGraph: (options) => this.expandGraph(options),
+    createContextPack: (options) => this.createContextPack(options),
+    createExternalContextResource: (options) => this.createExternalContextResource(options),
+    getWorkspaceSummary: () => this.getWorkspaceSummary(),
+    getRecentNodes: () => this.getRecentNodes(),
+    listNodes: async () => {
+      const nodes = await this.config.store.list({ limit: this.limits.maxListLimit });
+      return { nodes, count: nodes.length, limit: this.limits.maxListLimit };
+    },
+    listSchemas: async () => ({ schemas: await this.getSchemaSummaries(true) }),
+    getNodeOrThrow: (id) => this.getNodeOrThrow(id),
+    getNodeProjection: (id) => this.getNodeProjection(id),
+    readPageMarkdown: (pageId, includeFrontmatter, uri) => this.readPageMarkdown(pageId, includeFrontmatter, uri),
+    readPageOutline: (pageId) => this.readPageOutline(pageId),
+    planPagePatch: (args) => this.planPagePatch(args),
+    applyPageMarkdown: (args) => this.applyPageMarkdown(args),
+    rollbackPageMarkdown: (args) => this.rollbackPageMarkdown(args),
+    getAuditLog: (options) => this.getAuditLog(options),
+    describeDatabase: (databaseId, options) => this.describeDatabase(databaseId, options),
+    readDatabaseViews: (databaseId) => this.readDatabaseViews(databaseId),
+    queryDatabase: (options) => this.queryDatabase(options),
+    sampleDatabase: (options) => this.sampleDatabase(options),
+    explainDatabaseQuery: (options) => this.explainDatabaseQuery(options),
+    planDatabaseMutation: (args) => this.planDatabaseMutation(args),
+    applyDatabaseMutation: (args) => this.applyDatabaseMutation(args),
+    listCanvases: (options) => this.listCanvases(options),
+    readCanvasViewport: (options) => this.readCanvasViewport(options),
+    readCanvasObjects: (canvasId) => this.readCanvasObjects(canvasId),
+    readCanvasSelection: (options) => this.readCanvasSelection(options),
+    searchCanvas: (options) => this.searchCanvas(options),
+    exportCanvasJsonCanvas: (options) => this.exportCanvasJsonCanvas(options),
+    readCanvasObject: (canvasId, objectId) => this.readCanvasObject(canvasId, objectId),
+    planCanvasJsonCanvasImport: (args) => this.planCanvasJsonCanvasImport(args),
+    planCanvasMutation: (args) => this.planCanvasMutation(args),
+    jsonResource: (uri, value) => this.jsonResource(uri, value)
+  };
+  /** The contributed (non-built-in) tools, with built-in name collisions removed. */
+  getExtraTools() {
+    const builtIn = new Set(this.builtInTools().map((t) => t.name));
+    return [...this.extraTools.values()].filter((t) => !builtIn.has(t.name));
+  }
+  getResources() {
+    return [
+      createResource(
+        "xnet://workspace/summary",
+        "Workspace Summary",
+        "High-level schema counts, recent nodes, and AI surface capabilities.",
+        "application/json",
+        "low",
+        ["workspace.read"]
+      ),
+      createResource(
+        "xnet://workspace/recent",
+        "Recent Workspace Nodes",
+        "Recent nodes with ids, schemas, titles, and revisions.",
+        "application/json",
+        "low",
+        ["workspace.read"]
+      ),
+      createResource(
+        "xnet://nodes",
+        "All Nodes",
+        "Limited list of nodes in the local store.",
+        "application/json",
+        "low",
+        ["workspace.read"]
+      ),
+      createResource(
+        "xnet://schemas",
+        "All Schemas",
+        "List of available schemas and property metadata.",
+        "application/json",
+        "low",
+        ["workspace.read"]
+      ),
+      createResource(
+        "xnet://page/{pageId}.md",
+        "Page Markdown",
+        "Markdown projection for a page, including xNet frontmatter identity.",
+        "text/markdown",
+        "low",
+        ["page.read"],
+        true
+      ),
+      createResource(
+        "xnet://page/{pageId}/outline",
+        "Page Outline",
+        "Page heading outline extracted from the Markdown projection.",
+        "application/json",
+        "low",
+        ["page.read"],
+        true
+      ),
+      createResource(
+        "xnet://database/{databaseId}/schema",
+        "Database Schema",
+        "Database node metadata, declared properties, and known column descriptors.",
+        "application/json",
+        "low",
+        ["database.read"],
+        true
+      ),
+      createResource(
+        "xnet://database/{databaseId}/views",
+        "Database Views",
+        "Known database view descriptors from the database node projection.",
+        "application/json",
+        "low",
+        ["database.read"],
+        true
+      ),
+      createResource(
+        "xnet://database/{databaseId}/sample?limit=10",
+        "Database Sample Rows",
+        "Bounded sample of rows for a database using NodeQueryDescriptor semantics.",
+        "application/json",
+        "low",
+        ["database.read", "database.query"],
+        true
+      ),
+      createResource(
+        "xnet://canvas/{canvasId}/viewport?x=0&y=0&w=1000&h=800",
+        "Canvas Viewport",
+        "Viewport-scoped canvas objects and edges.",
+        "application/json",
+        "low",
+        ["canvas.read"],
+        true
+      ),
+      createResource(
+        "xnet://canvas/{canvasId}/objects",
+        "Canvas Objects",
+        "Bounded list of canvas objects and connectors.",
+        "application/json",
+        "low",
+        ["canvas.read"],
+        true
+      ),
+      createResource(
+        "xnet://canvas/{canvasId}/selection?ids=object-1,object-2",
+        "Canvas Selection",
+        "Selection-scoped canvas objects, edges, and source previews.",
+        "application/json",
+        "low",
+        ["canvas.read"],
+        true
+      ),
+      createResource(
+        "xnet://canvas/{canvasId}/json-canvas",
+        "Canvas JSON Canvas",
+        "JSON Canvas projection with xNet source metadata sidecars.",
+        "application/json",
+        "low",
+        ["canvas.read"],
+        true
+      )
     ];
   }
+  /** The full tool surface: built-in `xnet_*` tools plus contributed extras. */
+  getTools() {
+    const extras = this.getExtraTools().map(
+      ({ invoke: _invoke, ...def }) => def
+    );
+    return [...this.builtInTools(), ...extras];
+  }
+  builtInTools() {
+    return BUILT_IN_TOOL_ENTRIES.map((entry) => entry.definition);
+  }
+  /**
+   * Dispatch a tool call: the built-in registry first (a built-in `xnet_*`
+   * name always wins), then contributed tools (plugin/connector `agentTools`,
+   * exploration 0196).
+   */
   async callTool(name, args = {}) {
-    switch (name) {
-      case "xnet_search":
-        return await this.search({
-          query: readRequiredString(args, "query"),
-          schemaId: readOptionalString(args, "schemaId") ?? readOptionalString(args, "schema"),
-          limit: readOptionalNumber(args, "limit"),
-          offset: readOptionalNumber(args, "offset")
-        });
-      case "xnet_graph_expand":
-        return await this.expandGraph({
-          nodeId: readRequiredString(args, "nodeId"),
-          hops: readOptionalNumber(args, "hops"),
-          limit: readOptionalNumber(args, "limit")
-        });
-      case "xnet_create_context_pack":
-        return await this.createContextPack({
-          query: readOptionalString(args, "query"),
-          seeds: readContextSeeds(args.seeds),
-          limit: readOptionalNumber(args, "limit")
-        });
-      case "xnet_create_external_context_resource":
-        return this.createExternalContextResource({
-          url: readRequiredString(args, "url"),
-          text: readRequiredString(args, "text"),
-          mimeType: readOptionalString(args, "mimeType")
-        });
-      case "xnet_read_page_markdown": {
-        const content = await this.readPageMarkdown(
-          readRequiredString(args, "pageId"),
-          readOptionalBoolean(args, "includeFrontmatter") ?? true
-        );
-        return { markdown: content.text, mimeType: content.mimeType, uri: content.uri };
-      }
-      case "xnet_validate_page_markdown": {
-        const pageId = readOptionalString(args, "pageId");
-        const node = pageId ? await this.getNodeOrThrow(pageId) : null;
-        return validateXNetPageMarkdown(readRequiredString(args, "markdown"), {
-          pageId,
-          schemaId: node?.schemaId,
-          baseRevision: readOptionalString(args, "baseRevision")
-        });
-      }
-      case "xnet_plan_page_patch":
-        return await this.planPagePatch(args);
-      case "xnet_apply_page_markdown":
-        return await this.applyPageMarkdown(args);
-      case "xnet_get_audit_log":
-        return this.getAuditLog({
-          planId: readOptionalString(args, "planId"),
-          limit: readOptionalNumber(args, "limit")
-        });
-      case "xnet_rollback_page_markdown":
-        return await this.rollbackPageMarkdown(args);
-      case "xnet_database_describe":
-        return await this.describeDatabase(readRequiredString(args, "databaseId"), {
-          includeSample: readOptionalBoolean(args, "includeSample") ?? false
-        });
-      case "xnet_database_query":
-        return await this.queryDatabase({
-          databaseId: readRequiredString(args, "databaseId"),
-          schemaId: readOptionalString(args, "schemaId"),
-          descriptor: readOptionalRecord(args, "descriptor"),
-          where: readOptionalRecord(args, "where"),
-          search: args.search,
-          orderBy: readOptionalRecord(args, "orderBy"),
-          materializedView: args.materializedView,
-          count: readOptionalString(args, "count"),
-          limit: readOptionalNumber(args, "limit"),
-          offset: readOptionalNumber(args, "offset")
-        });
-      case "xnet_database_sample":
-        return await this.sampleDatabase({
-          databaseId: readRequiredString(args, "databaseId"),
-          schemaId: readOptionalString(args, "schemaId"),
-          descriptor: readOptionalRecord(args, "descriptor"),
-          sampleSize: readOptionalNumber(args, "sampleSize")
-        });
-      case "xnet_database_explain_query":
-        return await this.explainDatabaseQuery({
-          databaseId: readRequiredString(args, "databaseId"),
-          schemaId: readOptionalString(args, "schemaId"),
-          descriptor: readOptionalRecord(args, "descriptor"),
-          limit: readOptionalNumber(args, "limit"),
-          offset: readOptionalNumber(args, "offset")
-        });
-      case "xnet_plan_database_mutation":
-        return await this.planDatabaseMutation(args);
-      case "xnet_apply_database_mutation":
-        return await this.applyDatabaseMutation(args);
-      case "xnet_canvas_list":
-        return await this.listCanvases({
-          limit: readOptionalNumber(args, "limit"),
-          offset: readOptionalNumber(args, "offset")
-        });
-      case "xnet_canvas_read_viewport":
-        return await this.readCanvasViewport({
-          canvasId: readRequiredString(args, "canvasId"),
-          x: readOptionalNumber(args, "x"),
-          y: readOptionalNumber(args, "y"),
-          w: readOptionalNumber(args, "w"),
-          h: readOptionalNumber(args, "h"),
-          tileSize: readOptionalNumber(args, "tileSize"),
-          tileIds: readStringArray(args.tileIds),
-          includeSourcePreviews: readOptionalBoolean(args, "includeSourcePreviews") ?? false
-        });
-      case "xnet_canvas_read_selection":
-        return await this.readCanvasSelection({
-          canvasId: readRequiredString(args, "canvasId"),
-          objectIds: readRequiredStringArray(args.objectIds, "objectIds"),
-          includeSourcePreviews: readOptionalBoolean(args, "includeSourcePreviews") ?? false
-        });
-      case "xnet_canvas_search":
-        return await this.searchCanvas({
-          canvasId: readRequiredString(args, "canvasId"),
-          query: readRequiredString(args, "query"),
-          limit: readOptionalNumber(args, "limit")
-        });
-      case "xnet_canvas_export_json_canvas":
-        return await this.exportCanvasJsonCanvas({
-          canvasId: readRequiredString(args, "canvasId"),
-          includeXNetMetadata: readOptionalBoolean(args, "includeXNetMetadata") ?? true,
-          x: readOptionalNumber(args, "x"),
-          y: readOptionalNumber(args, "y"),
-          w: readOptionalNumber(args, "w"),
-          h: readOptionalNumber(args, "h")
-        });
-      case "xnet_canvas_plan_json_canvas_import":
-        return await this.planCanvasJsonCanvasImport(args);
-      case "xnet_plan_canvas_mutation":
-        return await this.planCanvasMutation(args);
-      case "xnet_validate_mutation_plan": {
-        const validation = validateAiMutationPlan(args.plan);
-        return { validation };
-      }
-      default: {
-        const extra = this.extraTools.get(name);
-        if (extra) return await extra.invoke(args);
-        throw new Error(`Unknown AI surface tool: ${name}`);
-      }
-    }
+    const builtIn = BUILT_IN_TOOLS_BY_NAME.get(name);
+    if (builtIn) return await builtIn.execute(this.host, args);
+    const extra = this.extraTools.get(name);
+    if (extra) return await extra.invoke(args);
+    throw new Error(`Unknown AI surface tool: ${name}`);
   }
   async readResource(uri) {
-    const parsed = parseXNetUri(uri);
-    if (uri === "xnet://nodes") {
-      const nodes = await this.config.store.list({ limit: this.limits.maxListLimit });
-      return this.jsonResource(uri, { nodes, count: nodes.length, limit: this.limits.maxListLimit });
-    }
-    if (uri === "xnet://schemas") {
-      return this.jsonResource(uri, { schemas: await this.getSchemaSummaries(true) });
-    }
-    if (parsed.host === "workspace" && parsed.parts[0] === "summary") {
-      return this.jsonResource(uri, await this.getWorkspaceSummary());
-    }
-    if (parsed.host === "workspace" && parsed.parts[0] === "recent") {
-      return this.jsonResource(uri, await this.getRecentNodes());
-    }
-    if (parsed.host === "workspace" && parsed.parts[0] === "search") {
-      return this.jsonResource(
-        uri,
-        await this.search({
-          query: parsed.searchParams.get("q") ?? "",
-          schemaId: parsed.searchParams.get("schema") ?? void 0,
-          limit: readUrlNumber(parsed.searchParams, "limit"),
-          offset: readUrlNumber(parsed.searchParams, "offset")
-        })
-      );
-    }
-    if (parsed.host === "node" && parsed.parts[0]) {
-      return this.jsonResource(uri, await this.getNodeProjection(parsed.parts[0]));
-    }
-    if (parsed.host === "page" && parsed.parts[0]) {
-      const pageId = parsed.parts[0].endsWith(".md") ? parsed.parts[0].slice(0, -".md".length) : parsed.parts[0];
-      if (parsed.parts.length === 1 || parsed.parts[0].endsWith(".md")) {
-        return await this.readPageMarkdown(pageId, true, uri);
-      }
-      if (parsed.parts[1] === "outline") {
-        return this.jsonResource(uri, await this.readPageOutline(pageId));
-      }
-      if (parsed.parts[1] === "context-pack") {
-        return this.jsonResource(
-          uri,
-          await this.createContextPack({ seeds: [{ kind: "page", id: pageId }] })
-        );
-      }
-    }
-    if (parsed.host === "database" && parsed.parts[0]) {
-      const databaseId = parsed.parts[0];
-      if (parsed.parts[1] === "schema") {
-        return this.jsonResource(uri, await this.describeDatabase(databaseId));
-      }
-      if (parsed.parts[1] === "views") {
-        return this.jsonResource(uri, await this.readDatabaseViews(databaseId));
-      }
-      if (parsed.parts[1] === "sample") {
-        return this.jsonResource(
-          uri,
-          await this.sampleDatabase({
-            databaseId,
-            sampleSize: readUrlNumber(parsed.searchParams, "limit")
-          })
-        );
-      }
-      if (parsed.parts[1] === "query") {
-        return this.jsonResource(
-          uri,
-          await this.queryDatabase({
-            databaseId,
-            schemaId: parsed.searchParams.get("schema") ?? void 0,
-            search: parsed.searchParams.get("q") ?? void 0,
-            materializedView: parsed.searchParams.get("view") ? { viewId: parsed.searchParams.get("view") ?? "" } : void 0,
-            limit: readUrlNumber(parsed.searchParams, "limit"),
-            offset: readUrlNumber(parsed.searchParams, "offset")
-          })
-        );
-      }
-    }
-    if (parsed.host === "canvas" && parsed.parts[0]) {
-      const canvasId = parsed.parts[0];
-      if (parsed.parts[1] === "viewport") {
-        return this.jsonResource(
-          uri,
-          await this.readCanvasViewport({
-            canvasId,
-            x: readUrlNumber(parsed.searchParams, "x"),
-            y: readUrlNumber(parsed.searchParams, "y"),
-            w: readUrlNumber(parsed.searchParams, "w"),
-            h: readUrlNumber(parsed.searchParams, "h"),
-            tileSize: readUrlNumber(parsed.searchParams, "tileSize"),
-            tileIds: readCsvStringArray(parsed.searchParams.get("tileIds")),
-            includeSourcePreviews: parsed.searchParams.get("includeSourcePreviews") === "true"
-          })
-        );
-      }
-      if (parsed.parts[1] === "objects") {
-        return this.jsonResource(uri, await this.readCanvasObjects(canvasId));
-      }
-      if (parsed.parts[1] === "selection") {
-        return this.jsonResource(
-          uri,
-          await this.readCanvasSelection({
-            canvasId,
-            objectIds: readCsvStringArray(parsed.searchParams.get("ids")),
-            includeSourcePreviews: parsed.searchParams.get("includeSourcePreviews") !== "false"
-          })
-        );
-      }
-      if (parsed.parts[1] === "json-canvas") {
-        return this.jsonResource(
-          uri,
-          await this.exportCanvasJsonCanvas({
-            canvasId,
-            includeXNetMetadata: parsed.searchParams.get("includeXNetMetadata") !== "false"
-          })
-        );
-      }
-      if (parsed.parts[1] === "object" && parsed.parts[2]) {
-        return this.jsonResource(uri, await this.readCanvasObject(canvasId, parsed.parts[2]));
-      }
-    }
-    throw new Error(`Resource not found: ${uri}`);
+    return await BUILT_IN_RESOURCE_ROUTES.resolve(this.host, uri);
   }
   toJsonText(value, format = "concise") {
     return this.stringifyJson(value, format);
@@ -1448,7 +1722,7 @@ var AiSurfaceService = class {
     const results = Array.isArray(search.results) ? search.results : [];
     const ids = [];
     for (const result of results) {
-      if (isRecord3(result) && typeof result.id === "string") ids.push(result.id);
+      if (isRecord2(result) && typeof result.id === "string") ids.push(result.id);
     }
     return ids;
   }
@@ -2090,8 +2364,8 @@ var AiSurfaceService = class {
       h: options.h,
       includeSourcePreviews: false
     });
-    const objects = Array.isArray(viewport.objects) ? viewport.objects.filter(isRecord3) : [];
-    const edges = Array.isArray(viewport.edges) ? viewport.edges.filter(isRecord3) : [];
+    const objects = Array.isArray(viewport.objects) ? viewport.objects.filter(isRecord2) : [];
+    const edges = Array.isArray(viewport.edges) ? viewport.edges.filter(isRecord2) : [];
     return {
       canvasId: options.canvasId,
       revision: viewport.revision,
@@ -2133,7 +2407,7 @@ var AiSurfaceService = class {
     });
     const objects = Array.isArray(viewport.objects) ? viewport.objects : [];
     const object = objects.find(
-      (candidate) => isRecord3(candidate) && readRecordString(candidate, "id") === objectId
+      (candidate) => isRecord2(candidate) && readRecordString(candidate, "id") === objectId
     );
     if (!object) throw new Error(`Canvas object not found: ${objectId}`);
     return {
@@ -2609,7 +2883,7 @@ function invalidPageApplyResult(plan, validation) {
   return {
     applied: false,
     pageId: "unknown",
-    planId: isRecord3(plan) && typeof plan.id === "string" ? plan.id : "unknown",
+    planId: isRecord2(plan) && typeof plan.id === "string" ? plan.id : "unknown",
     mode: "node-property",
     baseRevision: "unknown",
     liveRevision: "unknown",
@@ -2632,7 +2906,7 @@ function rejectedPageApplyResult(input) {
   };
 }
 function isMutationPlan(value) {
-  return isRecord3(value) && typeof value.id === "string" && typeof value.actor === "string" && typeof value.intent === "string" && Array.isArray(value.changes) && isRecord3(value.validation);
+  return isRecord2(value) && typeof value.id === "string" && typeof value.actor === "string" && typeof value.intent === "string" && Array.isArray(value.changes) && isRecord2(value.validation);
 }
 function createResource(uri, name, description, mimeType, risk, requiredScopes, dynamic = false) {
   return {
@@ -2645,22 +2919,6 @@ function createResource(uri, name, description, mimeType, risk, requiredScopes,
     dynamic
   };
 }
-function parseXNetUri(uri) {
-  let parsed;
-  try {
-    parsed = new URL(uri);
-  } catch {
-    throw new Error(`Invalid xNet resource URI: ${uri}`);
-  }
-  if (parsed.protocol !== "xnet:") {
-    throw new Error(`Invalid xNet resource URI: ${uri}`);
-  }
-  return {
-    host: parsed.hostname,
-    parts: parsed.pathname.split("/").filter(Boolean).map((part) => decodeURIComponent(part)),
-    searchParams: parsed.searchParams
-  };
-}
 function renderPageMarkdown(node, includeFrontmatter, exportedAt) {
   const title = readStringProperty(node, "title") ?? "Untitled Page";
   const body = readMarkdownBody(node);
@@ -2687,7 +2945,7 @@ function readMarkdownBody(node) {
   const value = readStringProperty(node, "markdown") ?? readStringProperty(node, "content") ?? readStringProperty(node, "body") ?? readStringProperty(node, "text") ?? readStringProperty(node, "description");
   if (value) return value;
   const richContent = node.properties.content;
-  if (isRecord3(richContent)) {
+  if (isRecord2(richContent)) {
     return `\`\`\`json
 ${JSON.stringify(richContent, null, 2)}
 \`\`\``;
@@ -2748,7 +3006,7 @@ function relationFieldNames(schema) {
   if (!schema) return [];
   const fields = [];
   for (const [name, definition] of Object.entries(schema.properties)) {
-    if (isRecord3(definition) && definition.type === "relation") fields.push(name);
+    if (isRecord2(definition) && definition.type === "relation") fields.push(name);
   }
   return fields;
 }
@@ -2778,7 +3036,7 @@ function readArrayProperty(node, property) {
 }
 function readNestedArrayProperty(node, objectProperty, arrayProperty) {
   const value = node.properties[objectProperty];
-  return isRecord3(value) && Array.isArray(value[arrayProperty]) ? value[arrayProperty] : void 0;
+  return isRecord2(value) && Array.isArray(value[arrayProperty]) ? value[arrayProperty] : void 0;
 }
 function belongsToDatabase(node, databaseId) {
   return readStringProperty(node, "databaseId") === databaseId || readStringProperty(node, "database") === databaseId || readStringProperty(node, "parentDatabaseId") === databaseId;
@@ -2837,7 +3095,7 @@ function normalizeQuerySearch(value) {
     const text = value.trim();
     return text ? { text } : void 0;
   }
-  if (!isRecord3(value) || typeof value.text !== "string" || !value.text.trim()) {
+  if (!isRecord2(value) || typeof value.text !== "string" || !value.text.trim()) {
     return void 0;
   }
   const fields = Array.isArray(value.fields) ? value.fields.filter(
@@ -2853,7 +3111,7 @@ function normalizeQueryMaterializedView(value) {
     const viewId2 = value.trim();
     return viewId2 ? { viewId: viewId2 } : void 0;
   }
-  if (!isRecord3(value)) return void 0;
+  if (!isRecord2(value)) return void 0;
   const viewId = readRecordString(value, "viewId");
   if (!viewId) return void 0;
   const maxAgeMs = readRecordNumber(value, "maxAgeMs");
@@ -3126,7 +3384,7 @@ function invalidDatabaseApplyResult(plan, validation) {
   return {
     applied: false,
     databaseId: "unknown",
-    planId: isRecord3(plan) && typeof plan.id === "string" ? plan.id : "unknown",
+    planId: isRecord2(plan) && typeof plan.id === "string" ? plan.id : "unknown",
     baseRevision: "unknown",
     liveRevision: "unknown",
     appliedChangeIds: [],
@@ -3144,7 +3402,7 @@ function readTransactionOperations(operation) {
   );
 }
 function readTransactionOperation(value, path) {
-  if (!isRecord3(value)) throw new Error(`${path} must be an object`);
+  if (!isRecord2(value)) throw new Error(`${path} must be an object`);
   if (value.type === "create") {
     const options = readRecord(value, "options");
     const schemaId = options ? readRecordString(options, "schemaId") : void 0;
@@ -3237,15 +3495,15 @@ function databaseEntityMatchesId(entity, id) {
 }
 function readRecordArrayProperty(record, key) {
   const value = record[key];
-  return Array.isArray(value) ? value.filter(isRecord3) : [];
+  return Array.isArray(value) ? value.filter(isRecord2) : [];
 }
 function isCanvasNode(node) {
   return node.schemaId.includes("/Canvas") || node.schemaId.includes("Canvas@") || Array.isArray(node.properties.objects) || Array.isArray(node.properties.nodes);
 }
 function readCanvasScene(canvas) {
   return {
-    objects: (readArrayProperty(canvas, "objects") ?? readArrayProperty(canvas, "nodes") ?? []).filter(isRecord3).map(normalizeCanvasObject),
-    edges: (readArrayProperty(canvas, "edges") ?? readArrayProperty(canvas, "connectors") ?? []).filter(isRecord3).map(normalizeCanvasEdge)
+    objects: (readArrayProperty(canvas, "objects") ?? readArrayProperty(canvas, "nodes") ?? []).filter(isRecord2).map(normalizeCanvasObject),
+    edges: (readArrayProperty(canvas, "edges") ?? readArrayProperty(canvas, "connectors") ?? []).filter(isRecord2).map(normalizeCanvasEdge)
   };
 }
 function normalizeCanvasObject(object) {
@@ -3388,8 +3646,8 @@ function canvasObjectFile(object) {
   return readRecordString(object, "file") ?? readRecordString(object, "filePath") ?? readRecordString(properties ?? {}, "file") ?? readRecordString(properties ?? {}, "filePath");
 }
 function jsonCanvasDocumentToCanvasOperations(document) {
-  const nodes = Array.isArray(document.nodes) ? document.nodes.filter(isRecord3) : [];
-  const edges = Array.isArray(document.edges) ? document.edges.filter(isRecord3) : [];
+  const nodes = Array.isArray(document.nodes) ? document.nodes.filter(isRecord2) : [];
+  const edges = Array.isArray(document.edges) ? document.edges.filter(isRecord2) : [];
   const nodeIds = new Set(nodes.map((node) => readRecordString(node, "id")).filter(Boolean));
   const warnings = edges.flatMap((edge) => {
     const fromNode = readRecordString(edge, "fromNode");
@@ -3621,10 +3879,10 @@ function readOperations(value) {
     throw new Error("operations must contain at least one operation");
   }
   return value.map((operation, index) => {
-    if (!isRecord3(operation) || typeof operation.op !== "string") {
+    if (!isRecord2(operation) || typeof operation.op !== "string") {
       throw new Error(`operations[${index}].op must be a string`);
     }
-    const args = isRecord3(operation.args) ? operation.args : {};
+    const args = isRecord2(operation.args) ? operation.args : {};
     return createAiOperation(
       operation.op,
       args,
@@ -3632,15 +3890,6 @@ function readOperations(value) {
     );
   });
 }
-function readContextSeeds(value) {
-  if (!Array.isArray(value)) return [];
-  return value.map((seed) => {
-    if (!isRecord3(seed)) return null;
-    const kind = typeof seed.kind === "string" ? seed.kind : null;
-    const id = typeof seed.id === "string" ? seed.id : null;
-    return kind && id ? { kind, id } : null;
-  }).filter((seed) => seed !== null);
-}
 function uriForSeed(seed) {
   switch (seed.kind) {
     case "node":
@@ -3700,75 +3949,6 @@ function stringifyTruncatedJson(text, maxCharacters) {
 function quoteYaml(value) {
   return JSON.stringify(value);
 }
-function readRequiredString(record, key) {
-  const value = record[key];
-  if (typeof value !== "string" || !value.trim()) {
-    throw new Error(`${key} must be a non-empty string`);
-  }
-  return value;
-}
-function readRequiredRecord(record, key) {
-  const value = record[key];
-  if (!isRecord3(value)) {
-    throw new Error(`${key} must be an object`);
-  }
-  return value;
-}
-function readRequiredStringArray(value, key) {
-  const result = readStringArray(value);
-  if (result.length === 0) {
-    throw new Error(`${key} must contain at least one string`);
-  }
-  return result;
-}
-function readStringArray(value) {
-  if (!Array.isArray(value)) return [];
-  return value.filter((item) => typeof item === "string" && item.trim() !== "");
-}
-function readCsvStringArray(value) {
-  if (!value) return [];
-  return value.split(",").map((item) => item.trim()).filter(Boolean);
-}
-function readOptionalString(record, key) {
-  const value = record[key];
-  return typeof value === "string" && value.trim() ? value : void 0;
-}
-function readOptionalRecord(record, key) {
-  return readRecord(record, key);
-}
-function readOptionalNumber(record, key) {
-  const value = record[key];
-  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
-}
-function readOptionalBoolean(record, key) {
-  const value = record[key];
-  return typeof value === "boolean" ? value : void 0;
-}
-function readUrlNumber(params, key) {
-  const value = params.get(key);
-  if (value === null) return void 0;
-  const parsed = Number(value);
-  return Number.isFinite(parsed) ? parsed : void 0;
-}
-function readRecordString(record, key) {
-  const value = record[key];
-  return typeof value === "string" && value.trim() ? value : void 0;
-}
-function readRecord(record, key) {
-  const value = record[key];
-  return isRecord3(value) ? value : void 0;
-}
-function readRecordNumber(record, key) {
-  const value = record[key];
-  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
-}
-function readRecordBoolean(record, key) {
-  const value = record[key];
-  return typeof value === "boolean" ? value : void 0;
-}
-function isRecord3(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 
 // src/ai-surface/skill.ts
 var XNET_AGENT_SKILL_MD = `---