@xnetjs/plugins 0.0.2 → 0.1.0

package/dist/services/node.d.ts

@@ -1,3 +1,515 @@
+import { NodeQueryDescriptor, NodeQueryResult } from '@xnetjs/data';
+import { PublicWriteBudgetPolicy, AbuseSurface, AISignalProvenanceInput } from '@xnetjs/abuse';
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+/**
+ * AI surface contract types for xNet resources, tools, mutation plans, and audit events.
+ */
+type AiRiskLevel = 'low' | 'medium' | 'high' | 'critical';
+type AiScope = 'workspace.read' | 'workspace.search' | 'page.read' | 'page.propose' | 'page.write' | 'database.read' | 'database.query' | 'database.propose' | 'database.write.rows' | 'database.write.schema' | 'canvas.read' | 'canvas.propose' | 'canvas.write' | 'storage.diagnostics' | 'storage.recovery' | 'network.fetch' | 'agent.workspace.export' | 'agent.workspace.import';
+declare const AI_RISK_LEVELS: readonly AiRiskLevel[];
+declare const AI_SCOPES: readonly AiScope[];
+type AiTargetKind = 'workspace' | 'node' | 'page' | 'database' | 'databaseRows' | 'canvas' | 'storage';
+declare const AI_TARGET_KINDS: readonly AiTargetKind[];
+type AiJsonSchemaType = 'string' | 'number' | 'boolean' | 'object' | 'array';
+type AiJsonSchema = {
+    type: AiJsonSchemaType;
+    description?: string;
+    enum?: readonly string[];
+    properties?: Record<string, AiJsonSchema>;
+    required?: readonly string[];
+    items?: AiJsonSchema;
+    additionalProperties?: boolean | AiJsonSchema;
+};
+type AiResource = {
+    uri: string;
+    name: string;
+    description?: string;
+    mimeType: string;
+    risk: AiRiskLevel;
+    requiredScopes: AiScope[];
+    dynamic?: boolean;
+};
+type AiToolDefinition = {
+    name: string;
+    title: string;
+    description: string;
+    risk: AiRiskLevel;
+    requiredScopes: AiScope[];
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, AiJsonSchema>;
+        required?: readonly string[];
+    };
+};
+type AiToolCallResult = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};
+/**
+ * A tool the AI surface can list and call but whose implementation lives outside
+ * the surface (a plugin/connector contribution, exploration 0196). `invoke`
+ * returns raw data; the surface serializes it for the model, keeping contributed
+ * tools symmetric with the built-in `xnet_*` tools.
+ */
+type AiExtraTool = AiToolDefinition & {
+    invoke: (args: Record<string, unknown>) => unknown | Promise<unknown>;
+};
+type AiValidationResult = {
+    valid: boolean;
+    warnings: string[];
+    errors: string[];
+};
+type AiOperation<TArgs extends Record<string, unknown> = Record<string, unknown>> = {
+    op: string;
+    args: TArgs;
+    rationale?: string;
+};
+type AiChangeSet = {
+    targetKind: AiTargetKind;
+    targetId: string;
+    baseRevision: string;
+    operations: AiOperation[];
+};
+type AiMutationPlanStatus = 'proposed' | 'validated' | 'applied' | 'rejected';
+type AiMutationPlan = {
+    id: string;
+    workspaceId?: string;
+    actor: string;
+    intent: string;
+    risk: AiRiskLevel;
+    requiredScopes: AiScope[];
+    changes: AiChangeSet[];
+    validation: AiValidationResult;
+    createdAt: string;
+    status: AiMutationPlanStatus;
+};
+type AiAuditEvent = {
+    id: string;
+    planId: string;
+    actor: string;
+    risk: AiRiskLevel;
+    requiredScopes: AiScope[];
+    validation: AiValidationResult;
+    appliedChangeIds: string[];
+    rollbackHandle?: string;
+    createdAt: string;
+};
+type AiContextSeed = {
+    kind: AiTargetKind;
+    id: string;
+};
+type AiContextPackResource = {
+    uri: string;
+    mimeType: string;
+    text: string;
+    trust: {
+        level: 'workspace' | 'external-untrusted';
+        instructionBoundary: string;
+    };
+    citation: {
+        kind: AiTargetKind;
+        id: string;
+        revision?: string;
+    };
+};
+type AiContextPack = {
+    id: string;
+    query?: string;
+    seeds: AiContextSeed[];
+    resources: AiContextPackResource[];
+    createdAt: string;
+    limits: {
+        maxResources: number;
+        maxCharactersPerResource: number;
+    };
+};
+declare function isAiRiskLevel(value: unknown): value is AiRiskLevel;
+declare function isAiScope(value: unknown): value is AiScope;
+declare function isAiTargetKind(value: unknown): value is AiTargetKind;
+
+/**
+ * @xnetjs/plugins — agent tools contribution point (exploration 0196).
+ *
+ * 0194 Phase 2 (`contributionsAsAiTools`) let the AI call a plugin *command*.
+ * This adds first-class, model-facing tools that are NOT tied to a UI command —
+ * the shape a Connector uses to expose, say, `slack_search_mentions` that reads
+ * the governed node store. Register once via `contributes.agentTools`; the host
+ * folds them into the AI surface's `extraTools`, so they appear in the in-app
+ * AI, the MCP server, and the files-first skill alike.
+ *
+ * A tool's `invoke` returns raw data; the surface serializes it for the model,
+ * keeping contributed tools symmetric with the built-in `xnet_*` tools.
+ */
+
+/** Input schema shape, shared with `AiToolDefinition`. */
+type AgentToolInputSchema = AiToolDefinition['inputSchema'];
+/**
+ * A plugin-contributed agent tool. Registered under `id`; exposed to the model
+ * under `name` (snake_case, plugin-namespaced by convention, e.g.
+ * `slack_search_mentions`).
+ */
+interface AgentToolContribution {
+    /** Registry key, plugin-scoped (e.g. `dev.xnet.connector.slack.search`). */
+    id: string;
+    /** Model-facing tool name (snake_case), e.g. `slack_search_mentions`. */
+    name: string;
+    /** Human title for menus (defaults to `name`). */
+    title?: string;
+    /** What the tool does — shown to the model. */
+    description: string;
+    /** Risk surfaced to the agent + consent layer (default `medium`). */
+    risk?: AiRiskLevel;
+    /** AI scopes this tool requires (default none). */
+    requiredScopes?: AiScope[];
+    /** JSON schema for the tool args (default: empty object schema). */
+    inputSchema?: AgentToolInputSchema;
+    /** Execute the tool. Returns raw data; the surface serializes it for the model. */
+    invoke: (args: Record<string, unknown>) => unknown | Promise<unknown>;
+}
+
+/**
+ * Validation helpers for AI surface mutation plans.
+ */
+
+declare function createAiValidationResult(errors?: string[], warnings?: string[]): AiValidationResult;
+/**
+ * Validate a serialized mutation plan before it can be previewed or applied.
+ */
+declare function validateAiMutationPlan(plan: unknown): AiValidationResult;
+/**
+ * Return a copy of a plan with the latest validation result attached.
+ */
+declare function attachAiPlanValidation(plan: AiMutationPlan): AiMutationPlan;
+declare function serializeAiMutationPlan(plan: AiMutationPlan): string;
+declare function parseAiMutationPlan(serialized: string): {
+    plan: AiMutationPlan | null;
+    validation: AiValidationResult;
+};
+declare function createAiOperation<TArgs extends Record<string, unknown>>(op: string, args: TArgs, rationale?: string): AiOperation<TArgs>;
+declare function createAiChangeSet(input: AiChangeSet): AiChangeSet;
+
+/**
+ * AI surface service for focused resources, context packs, and plan-only tools.
+ */
+
+type AiResourceContent = {
+    uri: string;
+    mimeType: string;
+    text: string;
+};
+type AiSearchResult = {
+    id: string;
+    schemaId: string;
+    title: string;
+    snippet: string;
+    score: number;
+    revision: string;
+    updatedAt: number;
+};
+type AiSearchOptions = {
+    query: string;
+    schemaId?: string;
+    limit?: number;
+    offset?: number;
+};
+type AiSurfaceLimits = {
+    maxListLimit: number;
+    maxSearchScan: number;
+    maxSearchResults: number;
+    maxContextResources: number;
+    maxCharactersPerResource: number;
+    maxJsonCharacters: number;
+    maxCanvasObjects: number;
+    maxDatabaseRows: number;
+};
+type AiPageMarkdownApplyAdapterInput = {
+    pageId: string;
+    markdown: string;
+    bodyMarkdown: string;
+    baseRevision: string;
+    plan: AiMutationPlan;
+    operation: AiOperation;
+};
+type AiPageMarkdownApplyAdapterResult = {
+    mode: 'tiptap-yjs' | 'yjs' | 'custom';
+    yjsField?: string;
+    documentUpdate?: unknown;
+    warnings?: string[];
+};
+type AiPageMarkdownApplyAdapter = {
+    applyMarkdown(input: AiPageMarkdownApplyAdapterInput): Promise<AiPageMarkdownApplyAdapterResult>;
+};
+type AiPageMarkdownApplyResult = {
+    applied: boolean;
+    pageId: string;
+    planId: string;
+    mode: 'tiptap-yjs' | 'yjs' | 'custom' | 'node-property';
+    baseRevision: string;
+    liveRevision: string;
+    markdownHash: string;
+    bodyMarkdownHash: string;
+    validation: {
+        valid: boolean;
+        errors: string[];
+        warnings: string[];
+    };
+    auditEventId?: string;
+    rollbackHandle?: string;
+    yjsField?: string;
+    documentUpdate?: unknown;
+};
+type AiPageMarkdownRollbackResult = {
+    rolledBack: boolean;
+    pageId: string;
+    planId: string;
+    rollbackHandle: string;
+    auditEventId?: string;
+    validation: {
+        valid: boolean;
+        errors: string[];
+        warnings: string[];
+    };
+};
+/** A node surfaced by an external retriever, with optional provenance. */
+type AiRetrievedNode = {
+    nodeId: string;
+    /** Human-readable graph path back to an entry node (for citation/provenance). */
+    pathLabel?: string;
+};
+/**
+ * Optional graph-aware retriever (exploration 0211). When provided, the `query`
+ * path of `createContextPack` uses it instead of the built-in linear keyword
+ * scan — i.e. hybrid vector + keyword entry search plus bounded graph expansion,
+ * budgeted. The app injects `@xnetjs/brain`'s `retrieve` here (mapping its items
+ * to `{ nodeId, pathLabel }`); absent it, context packs fall back to `search()`
+ * with no behavior change.
+ */
+type AiContextRetriever = (query: string, options: {
+    limit: number;
+}) => Promise<AiRetrievedNode[]>;
+type AiSurfaceServiceConfig = {
+    store: NodeStoreAPI;
+    schemas: SchemaRegistryAPI;
+    limits?: Partial<AiSurfaceLimits>;
+    clock?: () => Date;
+    pageMarkdownAdapter?: AiPageMarkdownApplyAdapter;
+    /**
+     * Tools contributed from outside the surface — plugin/connector `agentTools`
+     * (exploration 0196). They are appended to `getTools()` and dispatched by
+     * `callTool()`, so every consumer (in-app AI, the MCP server, the files-first
+     * skill) sees them by registering once. A built-in `xnet_*` name always wins
+     * over a colliding extra tool.
+     */
+    extraTools?: AiExtraTool[];
+    /**
+     * Optional graph-aware context retriever (exploration 0211). Drives the
+     * `query` path of `createContextPack` when present; falls back to the built-in
+     * keyword `search()` otherwise.
+     */
+    retrieveContext?: AiContextRetriever;
+};
+declare class AiSurfaceService {
+    private readonly config;
+    private readonly limits;
+    private readonly clock;
+    private sequence;
+    private auditEvents;
+    private readonly rollbackSnapshots;
+    /** Contributed tools by name (exploration 0196), de-duped at construction. */
+    private readonly extraTools;
+    constructor(config: AiSurfaceServiceConfig);
+    /** The contributed (non-built-in) tools, with built-in name collisions removed. */
+    private getExtraTools;
+    getResources(): AiResource[];
+    /** The full tool surface: built-in `xnet_*` tools plus contributed extras. */
+    getTools(): AiToolDefinition[];
+    private builtInTools;
+    callTool(name: string, args?: Record<string, unknown>): Promise<unknown>;
+    readResource(uri: string): Promise<AiResourceContent>;
+    toJsonText(value: unknown, format?: 'concise' | 'detailed'): string;
+    private getWorkspaceSummary;
+    private getRecentNodes;
+    search(options: AiSearchOptions): Promise<Record<string, unknown>>;
+    /**
+     * Candidate node ids for a context-pack query: the injected graph-aware
+     * retriever (exploration 0211) when configured, else the built-in keyword
+     * `search()`. Order is preserved (best-first).
+     */
+    private candidateNodeIdsForQuery;
+    createContextPack(options: {
+        query?: string;
+        seeds?: AiContextSeed[];
+        limit?: number;
+    }): Promise<AiContextPack>;
+    /**
+     * Walk typed relation edges out from a node to its connected neighbors, bounded
+     * by `hops` (1–2) and a result `limit`. This is the just-in-time companion to
+     * `createContextPack` (exploration 0211): retrieval hands the agent a budgeted
+     * slice plus expandable node ids, and this lets it pull a specific node's
+     * connections on demand instead of over-fetching the whole graph up front.
+     */
+    private expandGraph;
+    private graphExpansion;
+    createExternalContextResource(options: {
+        url: string;
+        text: string;
+        mimeType?: string;
+    }): AiContextPackResource;
+    private readPageMarkdown;
+    private readPageOutline;
+    private planPagePatch;
+    private applyPageMarkdown;
+    private finalizeAppliedPageMarkdown;
+    private getAuditLog;
+    private rollbackPageMarkdown;
+    private recordAuditEvent;
+    private describeDatabase;
+    private readDatabaseViews;
+    private queryDatabase;
+    private sampleDatabase;
+    private explainDatabaseQuery;
+    private executeDatabaseQueryDescriptor;
+    private listCanvases;
+    private readCanvasObjects;
+    private readCanvasViewport;
+    private readCanvasSelection;
+    private searchCanvas;
+    private exportCanvasJsonCanvas;
+    private planCanvasJsonCanvasImport;
+    private readCanvasObject;
+    private hydrateSourcePreviews;
+    private planCanvasMutation;
+    private planDatabaseMutation;
+    private applyDatabaseMutation;
+    private applyDatabaseRowOperations;
+    private applyDatabaseRowTransactionOperation;
+    private rollbackAppliedDatabaseRowChanges;
+    private applyDatabaseSchemaOperations;
+    private planSurfaceMutation;
+    private validatedPlan;
+    private getNodeOrThrow;
+    private getNodeProjection;
+    private getSchemaSummaries;
+    private readSchemaSummary;
+    private contextResourceForSeed;
+    private jsonResource;
+    private stringifyJson;
+    private nextId;
+    private nowIso;
+}
+declare function createAiSurfaceService(config: AiSurfaceServiceConfig): AiSurfaceService;
+
+/**
+ * The xNet agent skill: a single cross-harness SKILL.md (Claude Code, Codex,
+ * Gemini CLI, Cursor) describing the vault checkout and the xnet CLI.
+ *
+ * This is the primary agent interface contract. Keep it stable between
+ * releases (prompt caching) and under the token budget guarded by
+ * agent-token-budget tests (~1k tokens).
+ */
+declare const XNET_AGENT_SKILL_MD = "---\nname: xnet\ndescription: Read, search, and edit the user's xNet workspace (pages, databases, canvases) via vault files and the xnet CLI.\n---\n\n# Working with xNet\n\nThis folder is a checkout of the user's xNet workspace. The xNet database\nstays the source of truth; these files are a working tree. Identity lives in\nfrontmatter and the manifest, never in filenames.\n\n## Layout\n\n- `Pages/<slug>.md` \u2014 pages as Markdown with YAML frontmatter\n  (`xnet.id`, `xnet.revision`). Never edit frontmatter.\n- `Databases/<slug>.schema.json` + `<slug>.rows.jsonl` \u2014 one JSON object\n  per line; edit, append, or remove lines to change rows.\n  `<slug>.tsv` sidecars are read-only fast reads.\n- `Canvases/<slug>.canvas` \u2014 JSON Canvas projections.\n- Wikilinks `[[Title]]`, `:::xnet-database` blocks, and\n  `{{xnet-ref ...}}` directives are live references \u2014 preserve them.\n\n## Workflow\n\n- Find things: Grep this checkout first; `xnet search \"<text>\"` for ranked\n  results (TSV: id, slug, title, snippet).\n- Need more data? `xnet checkout --query \"<text>\"` (or `--schema <iri>`,\n  `--kind page|database|canvas`, `--node <id>`) materializes a scoped\n  slice into this folder. Never export everything.\n- Query tables: `xnet query <database> --where field=value --format tsv`\n  (default TSV; `--format jsonl|json` when you need structure).\n- File edits become validated mutation plans. With `xnet daemon` running\n  they are picked up automatically; otherwise run `xnet commit`.\n- `xnet status` lists pending plans and conflicts. Conflicts are quarantined\n  in `.xnet/conflicts/` with a Markdown note explaining how to resolve;\n  fix the file and save again. Stale edits never silently overwrite.\n- Bulk or aggregate work: `xnet run <script.js>` executes a sandboxed\n  script with an `api` object (`api.nodes(schema)`, `api.search(text)`,\n  `api.proposeUpdate(id, props)`, `api.proposeCreate(schema, props)`).\n  Writes are proposals that flow through the same plan pipeline. Return a\n  digest, not raw rows.\n";
+
+/**
+ * Token-efficient output formats for agent-facing surfaces.
+ *
+ * TSV is ~2x cheaper than JSON for tabular reads; these helpers are shared by
+ * the workspace exporter (.tsv sidecars), the xnet CLI, and MCP responses.
+ */
+/** Render rows as TSV for cheap agent reads. Tabs/newlines collapse to spaces. */
+declare function toTsv(nodeRows: Record<string, unknown>[]): string;
+/** Database rows are node-shaped; lift `properties` to top-level TSV columns. */
+declare function flattenRowForTsv(row: Record<string, unknown>): Record<string, unknown>;
+
+/**
+ * Page Markdown validation for AI-edited xNet page projections.
+ */
+
+type XNetPageMarkdownFrontmatter = {
+    id?: string;
+    schemaId?: string;
+    revision?: string;
+    exportedAt?: string;
+};
+type XNetMarkdownDirective = {
+    kind: 'block' | 'inline' | 'wikilink';
+    name: string;
+    index: number;
+    payload?: Record<string, unknown>;
+    target?: string;
+};
+type XNetMarkdownDirectiveSpec = {
+    kind: 'block' | 'inline' | 'wikilink';
+    name: string;
+    editorExtension: string;
+    description: string;
+};
+type XNetPageMarkdownValidationOptions = {
+    pageId?: string;
+    schemaId?: string;
+    baseRevision?: string;
+};
+type XNetPageMarkdownValidation = {
+    frontmatter: XNetPageMarkdownFrontmatter | null;
+    directives: XNetMarkdownDirective[];
+    validation: AiValidationResult;
+};
+type XNetMarkdownDiffLineKind = 'context' | 'removed' | 'added';
+type XNetMarkdownDiffLine = {
+    kind: XNetMarkdownDiffLineKind;
+    text: string;
+    beforeLine?: number;
+    afterLine?: number;
+};
+type XNetMarkdownReviewDiff = {
+    kind: 'markdown-diff';
+    format: 'line';
+    beforeLineCount: number;
+    afterLineCount: number;
+    lineCount: number;
+    unifiedDiff: string;
+    lines: XNetMarkdownDiffLine[];
+};
+declare const XNET_MARKDOWN_DIRECTIVE_SPECS: readonly [{
+    readonly kind: "block";
+    readonly name: "xnet-database";
+    readonly editorExtension: "DatabaseEmbedExtension";
+    readonly description: "Embeds a database view block with JSON view configuration.";
+}, {
+    readonly kind: "block";
+    readonly name: "xnet-page";
+    readonly editorExtension: "PageEmbedExtension";
+    readonly description: "Embeds a page preview block with page identity and preview metadata.";
+}, {
+    readonly kind: "block";
+    readonly name: "xnet-embed";
+    readonly editorExtension: "EmbedExtension";
+    readonly description: "Embeds rich external media with provider metadata.";
+}, {
+    readonly kind: "inline";
+    readonly name: "xnet-ref";
+    readonly editorExtension: "SmartReferenceExtension";
+    readonly description: "Embeds an inline smart reference to an external or internal resource.";
+}, {
+    readonly kind: "inline";
+    readonly name: "xnet-db-ref";
+    readonly editorExtension: "DatabaseReferenceExtension";
+    readonly description: "Embeds an inline database reference.";
+}, {
+    readonly kind: "wikilink";
+    readonly name: "wikilink";
+    readonly editorExtension: "Wikilink";
+    readonly description: "Parses [[Page Title]] wikilinks into xNet page links.";
+}];
+declare function validateXNetPageMarkdown(markdown: string, options?: XNetPageMarkdownValidationOptions): XNetPageMarkdownValidation;
+declare function getXNetMarkdownDirectiveSpecs(): readonly XNetMarkdownDirectiveSpec[];
+declare function parseXNetPageFrontmatter(markdown: string): XNetPageMarkdownFrontmatter | null;
+declare function stripXNetPageFrontmatter(markdown: string): string;
+declare function renderMarkdownLineDiff(before: string, after: string): string;
+declare function renderMarkdownReviewDiff(before: string, after: string): XNetMarkdownReviewDiff;
+
 /**
  * Local HTTP API Server
  *
@@ -6,6 +518,16 @@
  *
  * This is designed to run in the Electron main process.
  */
+
+type LocalAPITokenScope = 'health.read' | 'nodes.read' | 'nodes.write' | 'schemas.read' | 'events.read' | 'ai.read' | 'ai.write' | 'admin';
+type LocalAPITokenConfig = {
+    token: string;
+    label?: string;
+    scopes: LocalAPITokenScope[];
+    aiScopes?: AiScope[];
+    createdAt?: string;
+};
+type LocalAPITokenSummary = Omit<LocalAPITokenConfig, 'token'>;
 /**
  * Node store interface (minimal subset needed by API)
  */
@@ -16,6 +538,7 @@ interface NodeStoreAPI {
         limit?: number;
         offset?: number;
     }): Promise<NodeData[]>;
+    query?(descriptor: NodeQueryDescriptor): Promise<NodeQueryResult>;
     create(options: {
         schemaId: string;
         properties: Record<string, unknown>;
@@ -72,6 +595,8 @@ interface LocalAPIConfig {
     host?: string;
     /** API token for authentication (optional) */
     token?: string;
+    /** Scoped API tokens for local-only integrations. */
+    tokens?: LocalAPITokenConfig[];
     /**
      * Allowed CORS origins (default: none).
      * Set to specific origins like ['http://localhost:3000'] for local dev,
@@ -83,6 +608,10 @@ interface LocalAPIConfig {
     store: NodeStoreAPI;
     /** SchemaRegistry instance */
     schemas: SchemaRegistryAPI;
+    /** Shared AI surface service. A default service is created when omitted. */
+    aiSurface?: AiSurfaceService;
+    /** Optional output and pagination limits for the default AI surface. */
+    aiLimits?: Partial<AiSurfaceLimits>;
 }
 /**
  * Local HTTP API server for xNet integrations.
@@ -109,6 +638,18 @@ declare class LocalAPIServer {
      * Check if server is running
      */
     get isRunning(): boolean;
+    /**
+     * Return redacted token metadata for UI permission management.
+     */
+    getTokenSummaries(): LocalAPITokenSummary[];
+    /**
+     * Replace scoped local API tokens.
+     */
+    setTokens(tokens: LocalAPITokenConfig[]): LocalAPITokenSummary[];
+    /**
+     * Rotate to a new single scoped token.
+     */
+    rotateToken(token: string, options?: Partial<Omit<LocalAPITokenConfig, 'token'>>): LocalAPITokenSummary;
     private handleRequest;
     private handleHealth;
     private handleListNodes;
@@ -120,6 +661,13 @@ declare class LocalAPIServer {
     private handleGetEvents;
     private handleListSchemas;
     private handleGetSchema;
+    private handleListAIResources;
+    private handleReadAIResource;
+    private handleCallAITool;
+    private handleAISearch;
+    private handleAIContextPack;
+    private handleAIPlanValidation;
+    private authenticateRequest;
     private parseBody;
     private sendJSON;
     private sendError;
@@ -144,6 +692,92 @@ declare class LocalAPIServer {
  */
 declare function createLocalAPI(config: LocalAPIConfig): LocalAPIServer;
 
+/**
+ * Write guardrail for the MCP server (exploration 0175, "boundary hardening").
+ *
+ * The 0175 pitch is that xNet's guardrail makes an autonomous agent safe to
+ * point at a workspace. But the generic `xnet_create/update/delete` tools used
+ * to mutate the store directly, bypassing the mutation-plan guardrail that the
+ * page/database tools enforce. This closes that gap for *every* MCP client
+ * (OpenClaw, Claude Code, …) at the boundary, independent of the client's own
+ * (often weak) safety model:
+ *
+ * - **Risk classification.** Deletes are `high`; creating an outward-facing node
+ *   (e.g. a chat message — "sending") is `high`; ordinary creates/updates are
+ *   `low`.
+ * - **Confirmation gate.** `high`/`critical` and outward-facing writes return
+ *   `needs-confirmation` instead of mutating, until the caller re-issues with
+ *   `confirm: true` (after the human approves — see the ClawHub skill).
+ * - **Cost budget.** Writes are charged against a per-surface budget
+ *   (`@xnetjs/abuse`); a runaway agent is throttled, not unbounded.
+ * - **Provenance + audit.** Applied writes are recorded with their risk and an
+ *   optional AI-provenance evidence ref, queryable for review.
+ */
+
+type McpWriteKind = 'create' | 'update' | 'delete';
+interface McpWriteRequest {
+    kind: McpWriteKind;
+    /** Schema IRI (for create). Used to detect outward-facing writes. */
+    schemaId?: string;
+    /** Target node id (for update/delete). */
+    nodeId?: string;
+    /** Caller confirmation; required to apply high-risk / outward-facing writes. */
+    confirm?: boolean;
+    /** Optional provenance from the calling agent (model that authored the write). */
+    provenance?: AISignalProvenanceInput;
+}
+type McpWriteVerdict = {
+    decision: 'allow';
+    risk: AiRiskLevel;
+    outwardFacing: boolean;
+    provenanceRef: string | null;
+} | {
+    decision: 'needs-confirmation';
+    risk: AiRiskLevel;
+    outwardFacing: boolean;
+    reason: string;
+} | {
+    decision: 'blocked';
+    risk: AiRiskLevel;
+    reason: string;
+};
+interface McpWriteAuditEvent {
+    kind: McpWriteKind;
+    risk: AiRiskLevel;
+    outwardFacing: boolean;
+    schemaId?: string;
+    nodeId?: string;
+    provenanceRef?: string;
+    at: number;
+}
+interface McpWriteGuardrailOptions {
+    /** Schema IRIs whose creation is outward-facing (raises risk, requires confirm). */
+    outwardFacingSchemas?: readonly string[];
+    /** Cost budget policy. Defaults to 120 writes / 60s on the surface. */
+    budgetPolicy?: PublicWriteBudgetPolicy;
+    /** Abuse surface for budget keys. Defaults to `localApi`. */
+    surface?: AbuseSurface;
+    /** Injectable clock (ms). Defaults to `Date.now`. */
+    clock?: () => number;
+}
+declare class McpWriteGuardrail {
+    private readonly outward;
+    private readonly policy;
+    private readonly surface;
+    private readonly now;
+    private usage;
+    private auditLog;
+    constructor(options?: McpWriteGuardrailOptions);
+    /** Classify and gate a write. Does not mutate anything; charges budget only on `allow`. */
+    evaluate(req: McpWriteRequest): McpWriteVerdict;
+    /** Record an applied write for audit/rollback review. Returns the event. */
+    recordApplied(req: McpWriteRequest, verdict: Extract<McpWriteVerdict, {
+        decision: 'allow';
+    }>, nodeId?: string): McpWriteAuditEvent;
+    getAuditLog(limit?: number): McpWriteAuditEvent[];
+    private classify;
+}
+
 /**
  * MCP Server for xNet
  *
@@ -158,7 +792,15 @@ declare function createLocalAPI(config: LocalAPIConfig): LocalAPIServer;
  */
 interface MCPTool {
     name: string;
+    title?: string;
     description: string;
+    risk?: string;
+    requiredScopes?: string[];
+    /**
+     * Tool Search Tool hint (advanced-tool-use): deferred tools are discovered
+     * on demand instead of paying their definition tokens on every turn.
+     */
+    defer_loading?: boolean;
     inputSchema: {
         type: 'object';
         properties: Record<string, MCPPropertySchema>;
@@ -171,7 +813,11 @@ interface MCPTool {
 interface MCPPropertySchema {
     type: 'string' | 'number' | 'boolean' | 'object' | 'array';
     description?: string;
+    enum?: readonly string[];
+    properties?: Record<string, MCPPropertySchema>;
+    required?: string[];
     items?: MCPPropertySchema;
+    additionalProperties?: boolean | MCPPropertySchema;
 }
 /**
  * MCP Resource definition
@@ -181,6 +827,9 @@ interface MCPResource {
     name: string;
     description?: string;
     mimeType?: string;
+    risk?: string;
+    requiredScopes?: string[];
+    dynamic?: boolean;
 }
 /**
  * MCP Request from client
@@ -210,6 +859,23 @@ interface MCPResponse {
 interface MCPServerConfig {
     store: NodeStoreAPI;
     schemas: SchemaRegistryAPI;
+    /** Shared AI surface service. A default service is created when omitted. */
+    aiSurface?: AiSurfaceService;
+    /** Optional output and pagination limits for the default AI surface. */
+    aiLimits?: Partial<AiSurfaceLimits>;
+    /**
+     * Plugin/connector agent tools to expose (exploration 0196). Folded into the
+     * default AI surface's `extraTools`, so they appear in `tools/list` (deferred,
+     * since not in {@link MCP_CORE_TOOL_NAMES}) and dispatch through `tools/call`.
+     * Ignored when a pre-built `aiSurface` is supplied — wire `extraTools` there.
+     */
+    agentTools?: AgentToolContribution[];
+    /**
+     * Write guardrail for the generic + first-class write tools. A default
+     * guardrail (delete/outward writes need confirmation, cost budget, audit) is
+     * created when omitted. Pass a configured instance to tune it.
+     */
+    guardrail?: McpWriteGuardrail;
     /** Server name (default: 'xnet') */
     name?: string;
     /** Server version (default: '1.0.0') */
@@ -240,6 +906,7 @@ interface MCPServerConfig {
 declare class MCPServer {
     private config;
     private tools;
+    private aiToolNames;
     private running;
     constructor(config: MCPServerConfig);
     /**
@@ -273,12 +940,22 @@ declare class MCPServer {
      * Reads JSON-RPC requests from stdin and writes responses to stdout.
      */
     startStdio(): Promise<void>;
+    /** Parse one stdin line as a JSON-RPC request and write the response. */
+    private handleStdioLine;
     /**
      * Stop the stdio server
      */
     stop(): void;
     private registerTools;
     private handleToolCall;
+    /**
+     * Route a write through the guardrail. Returns a gate result
+     * (`requiresConfirmation` / `blocked`) without mutating, or applies + records
+     * an audit entry and returns the applied value.
+     */
+    private guardedWrite;
+    /** Shared create path for the first-class write tools. */
+    private createNode;
     private handleResourceRead;
 }
 /**
@@ -300,6 +977,535 @@ declare class MCPServer {
  */
 declare function createMCPServer(config: MCPServerConfig): MCPServer;
 
+/**
+ * HTTP transport for the xNet MCP server (exploration 0175).
+ *
+ * The {@link MCPServer} ships a stdio transport for process-spawned clients
+ * (Claude Code, Codex, OpenClaw `mcp.servers` with `transport: "stdio"`). A
+ * browser or an HTTP-only MCP client (OpenClaw `transport: "streamable-http"`)
+ * cannot speak stdio, so this exposes the same `handleRequest` JSON-RPC surface
+ * over HTTP.
+ *
+ * Because the same surface can mutate a user's workspace, the transport is a
+ * trust boundary and is hardened accordingly (exploration 0175, "boundary
+ * hardening"):
+ *
+ * - **Loopback only.** Binds `127.0.0.1`/`::1`; refuses to start on a
+ *   non-loopback host so the substrate is never exposed to the network the way
+ *   OpenClaw's own `0.0.0.0:18789` default famously is.
+ * - **Pairing token.** Every JSON-RPC request must carry the shared
+ *   `x-xnet-pairing` secret; compared in constant time.
+ * - **Origin allowlist.** Browser requests (those carrying an `Origin`) must
+ *   match the allowlist; never reflects `*`. Non-browser clients (no `Origin`)
+ *   are allowed through to the token check.
+ * - **Private Network Access.** Emits `Access-Control-Allow-Private-Network`
+ *   and answers `OPTIONS` preflights so Chrome's Local Network Access flow can
+ *   reach a loopback substrate from an https origin.
+ *
+ * The guardrail itself (mutation plans, approval, audit) lives in the
+ * `AiSurfaceService` behind `MCPServer`, so it is preserved across transports —
+ * this layer only governs *who* may talk to the server.
+ */
+
+interface McpHttpServerConfig {
+    /** The MCP server whose `handleRequest` is exposed over HTTP. */
+    server: MCPServer;
+    /**
+     * Shared secret required in the `x-xnet-pairing` header. A cryptographically
+     * random token is generated when omitted; read it back from
+     * {@link McpHttpServerHandle.pairingToken} to hand to the client.
+     */
+    pairingToken?: string;
+    /**
+     * Browser origins permitted to call the server. Requests that send an
+     * `Origin` header not in this list are rejected with 403. Requests without an
+     * `Origin` (CLI/native MCP clients) bypass this check and are gated by the
+     * pairing token alone. Defaults to none (browser-less).
+     */
+    allowedOrigins?: readonly string[];
+    /** Loopback host to bind. Defaults to `127.0.0.1`. Non-loopback hosts throw. */
+    host?: string;
+    /** Port to bind. Defaults to `31416`; pass `0` for an ephemeral port. */
+    port?: number;
+    /** JSON-RPC endpoint path. Defaults to `/mcp`. */
+    path?: string;
+}
+interface McpHttpServerHandle {
+    /** Resolved base URL, e.g. `http://127.0.0.1:31416`. Valid after `start()`. */
+    readonly url: string;
+    /** Bound port. Valid after `start()` (reflects the OS-assigned port if 0). */
+    readonly port: number;
+    /** The pairing token clients must present. */
+    readonly pairingToken: string;
+    /** JSON-RPC endpoint path. */
+    readonly path: string;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** The raw Node request handler — exposed for tests and embedding. */
+    readonly handler: (req: IncomingMessage, res: ServerResponse) => void;
+}
+/**
+ * Create (but do not start) an HTTP transport for an {@link MCPServer}.
+ *
+ * @throws if `host` is not a loopback address.
+ */
+declare function createMcpHttpServer(config: McpHttpServerConfig): McpHttpServerHandle;
+
+/**
+ * Node-only AI workspace folder exporter.
+ */
+
+type AiWorkspaceExportKind = 'page' | 'database' | 'canvas' | 'node';
+type AiWorkspaceExportScope = {
+    nodeIds?: string[];
+    schemaIds?: string[];
+    /** Search query; matching nodes are materialized into the checkout. */
+    query?: string;
+    /** Folder-style scope: export every node of these kinds (bounded by limit). */
+    kinds?: AiWorkspaceExportKind[];
+    limit?: number;
+};
+type AiWorkspaceExportOptions = {
+    rootDir: string;
+    workspaceName?: string;
+    scope?: AiWorkspaceExportScope;
+};
+type AiWorkspaceCheckoutOptions = {
+    rootDir: string;
+    workspaceName?: string;
+    /** Required scope: a checkout always materializes an explicit slice. */
+    scope: AiWorkspaceExportScope;
+};
+type AiWorkspaceManifestEntry = {
+    path: string;
+    kind: AiWorkspaceExportKind;
+    id: string;
+    schemaId: string;
+    revision: string;
+    sha256: string;
+    exportedAt: string;
+};
+type AiWorkspaceExportResult = {
+    rootDir: string;
+    files: string[];
+    manifestEntries: AiWorkspaceManifestEntry[];
+    exportedAt: string;
+    incremental: boolean;
+    skippedNodeIds: string[];
+};
+type AiWorkspaceExporterConfig = {
+    store: NodeStoreAPI;
+    schemas: SchemaRegistryAPI;
+    aiSurface?: AiSurfaceService;
+    clock?: () => Date;
+    /**
+     * Generate a read-optimized `.tsv` sidecar for databases with at least this
+     * many rows. JSONL stays the write format; sidecars are read-only.
+     */
+    tsvSidecarMinRows?: number;
+};
+type AiWorkspaceChangedFileStatus = 'modified' | 'missing';
+type AiWorkspaceChangedFile = {
+    path: string;
+    kind: AiWorkspaceExportKind;
+    id: string;
+    status: AiWorkspaceChangedFileStatus;
+    previousSha256: string;
+    currentSha256?: string;
+};
+type AiWorkspacePendingPlan = {
+    path: string;
+    planPath: string;
+    plan: AiMutationPlan;
+    currentSha256: string;
+};
+type AiWorkspaceConflictKind = 'missing-file' | 'stale-export' | 'invalid-json' | 'invalid-jsonl' | 'invalid-plan' | 'validation-warning' | 'unsupported-change' | 'tool-error';
+type AiWorkspaceConflict = {
+    kind: AiWorkspaceConflictKind;
+    path: string;
+    id?: string;
+    message: string;
+    conflictPath?: string;
+    /** Human/agent-readable Markdown note with resolution instructions. */
+    notePath?: string;
+    detectedAt: string;
+};
+type AiWorkspaceReviewStatus = 'needs-review';
+type AiWorkspaceReviewAction = 'approve' | 'reject' | 'request-revision';
+type AiWorkspaceReviewEntryKind = 'pending-plan' | 'conflict';
+type AiWorkspaceReviewEntry = {
+    kind: AiWorkspaceReviewEntryKind;
+    status: AiWorkspaceReviewStatus;
+    path: string;
+    id?: string;
+    title: string;
+    message: string;
+    artifactPath?: string;
+    planId?: string;
+    planPath?: string;
+    conflictKind?: AiWorkspaceConflictKind;
+    conflictPath?: string;
+    risk?: AiRiskLevel;
+    requiredScopes?: AiScope[];
+    suggestedActions: AiWorkspaceReviewAction[];
+    createdAt: string;
+};
+type AiWorkspaceReviewIndex = {
+    rootDir: string;
+    generatedAt: string;
+    entries: AiWorkspaceReviewEntry[];
+};
+type AiWorkspaceWatcherScanOptions = {
+    rootDir: string;
+    actor?: string;
+    writePendingPlans?: boolean;
+    writeConflicts?: boolean;
+    writeReviewIndex?: boolean;
+};
+type AiWorkspaceWatcherScanResult = {
+    rootDir: string;
+    scannedAt: string;
+    changedFiles: AiWorkspaceChangedFile[];
+    pendingPlans: AiWorkspacePendingPlan[];
+    conflicts: AiWorkspaceConflict[];
+    review: AiWorkspaceReviewIndex;
+};
+type AiWorkspaceWatchOptions = AiWorkspaceWatcherScanOptions & {
+    /** Force interval polling instead of fs.watch (reliable cross-platform). */
+    usePolling?: boolean;
+    /** Poll interval when polling is active. Defaults to 2000ms. */
+    pollIntervalMs?: number;
+};
+type AiWorkspaceWatchHandle = {
+    close(): void;
+    /** True when the handle fell back to (or was configured for) polling. */
+    isPolling(): boolean;
+};
+declare class AiWorkspaceExporter {
+    private readonly config;
+    private readonly aiSurface;
+    private readonly clock;
+    constructor(config: AiWorkspaceExporterConfig);
+    exportWorkspace(options: AiWorkspaceExportOptions): Promise<AiWorkspaceExportResult>;
+    exportWorkspaceIncremental(options: AiWorkspaceExportOptions): Promise<AiWorkspaceExportResult>;
+    /**
+     * Lazily materialize an explicit slice of the workspace into the checkout.
+     *
+     * Unlike exportWorkspace there is no default "export everything up to the
+     * limit" behavior: a checkout always names what it wants (query, schema,
+     * node ids, or kind folders). Repeated checkouts are incremental and merge
+     * with whatever is already checked out.
+     */
+    checkout(options: AiWorkspaceCheckoutOptions): Promise<AiWorkspaceExportResult>;
+    private exportWorkspaceProjection;
+    private resolveNodes;
+    private resolveNodeIdScope;
+    private resolveSchemaScope;
+    private resolveQueryScope;
+    private resolveKindScope;
+    private ensureBaseFolders;
+    private writeSupportFiles;
+    private exportPage;
+    private exportDatabase;
+    private exportCanvas;
+    private exportNode;
+    private writeManifest;
+    private writeText;
+}
+declare class AiWorkspaceWatcher {
+    private readonly config;
+    private readonly aiSurface;
+    private readonly clock;
+    constructor(config: AiWorkspaceExporterConfig);
+    scanChangedFiles(options: AiWorkspaceWatcherScanOptions): Promise<AiWorkspaceWatcherScanResult>;
+    watchWorkspace(options: AiWorkspaceWatchOptions, onScan: (result: AiWorkspaceWatcherScanResult) => void | Promise<void>): AiWorkspaceWatchHandle;
+    private planChangedFile;
+    private createStaleExportConflict;
+    private planDatabaseProjection;
+    private planCanvasProjection;
+    private createGenericProjectionPlan;
+    private expectPlan;
+    private writePendingPlan;
+    private createConflict;
+    private writeReviewIndex;
+}
+declare function createAiWorkspaceExporter(config: AiWorkspaceExporterConfig): AiWorkspaceExporter;
+declare function createAiWorkspaceWatcher(config: AiWorkspaceExporterConfig): AiWorkspaceWatcher;
+
+/**
+ * ScriptContext - Safe API surface for user scripts
+ *
+ * Provides a frozen, read-only context with utility functions.
+ * Scripts cannot modify nodes directly - they return values/mutations
+ * that the runtime applies.
+ */
+/**
+ * A flat node representation (simplified for script access)
+ */
+interface FlatNode {
+    id: string;
+    schemaIRI: string;
+    [key: string]: unknown;
+}
+/**
+ * Format helper functions (no side effects)
+ */
+interface FormatHelpers {
+    /** Format a timestamp as a date string */
+    date: (timestamp: number, options?: Intl.DateTimeFormatOptions) => string;
+    /** Format a number with options */
+    number: (value: number, options?: Intl.NumberFormatOptions) => string;
+    /** Format a number as currency */
+    currency: (value: number, currency?: string, locale?: string) => string;
+    /** Format a timestamp as relative time (e.g., "5m ago") */
+    relative: (timestamp: number) => string;
+    /** Format bytes as human-readable size */
+    bytes: (bytes: number) => string;
+}
+/**
+ * Math helper functions (pure functions)
+ */
+interface MathHelpers {
+    /** Sum an array of numbers */
+    sum: (values: number[]) => number;
+    /** Average of an array of numbers */
+    avg: (values: number[]) => number;
+    /** Minimum value */
+    min: (values: number[]) => number;
+    /** Maximum value */
+    max: (values: number[]) => number;
+    /** Round to decimal places */
+    round: (value: number, decimals?: number) => number;
+    /** Clamp value between min and max */
+    clamp: (value: number, min: number, max: number) => number;
+    /** Absolute value */
+    abs: (value: number) => number;
+    /** Floor */
+    floor: (value: number) => number;
+    /** Ceiling */
+    ceil: (value: number) => number;
+}
+/**
+ * Text helper functions (pure functions)
+ */
+interface TextHelpers {
+    /** Convert to URL-safe slug */
+    slugify: (text: string) => string;
+    /** Truncate with ellipsis */
+    truncate: (text: string, maxLength: number) => string;
+    /** Capitalize first letter */
+    capitalize: (text: string) => string;
+    /** Title case */
+    titleCase: (text: string) => string;
+    /** Check if text contains search (case-insensitive) */
+    contains: (text: string, search: string) => boolean;
+    /** Simple template substitution: {key} replaced by vars[key] */
+    template: (template: string, vars: Record<string, unknown>) => string;
+    /** Trim whitespace */
+    trim: (text: string) => string;
+    /** Convert to lowercase */
+    lower: (text: string) => string;
+    /** Convert to uppercase */
+    upper: (text: string) => string;
+}
+/**
+ * Array helper functions (pure functions)
+ */
+interface ArrayHelpers {
+    /** Get first element */
+    first: <T>(items: T[]) => T | undefined;
+    /** Get last element */
+    last: <T>(items: T[]) => T | undefined;
+    /** Sort by property */
+    sortBy: <T>(items: T[], key: keyof T, desc?: boolean) => T[];
+    /** Group by property */
+    groupBy: <T>(items: T[], key: keyof T) => Record<string, T[]>;
+    /** Unique values */
+    unique: <T>(items: T[]) => T[];
+    /** Count items */
+    count: <T>(items: T[]) => number;
+    /** Filter truthy */
+    compact: <T>(items: (T | null | undefined)[]) => T[];
+}
+/**
+ * The context object passed to scripts.
+ * All properties and nested objects are frozen (immutable).
+ */
+interface ScriptContext {
+    /** The current node being processed (read-only, frozen) */
+    node: Readonly<FlatNode>;
+    /**
+     * Query sibling nodes by schema.
+     * Returns a frozen array of frozen nodes.
+     */
+    nodes: (schemaIRI?: string) => ReadonlyArray<Readonly<FlatNode>>;
+    /** Current timestamp in milliseconds */
+    now: () => number;
+    /** Format helpers */
+    format: Readonly<FormatHelpers>;
+    /** Math helpers */
+    math: Readonly<MathHelpers>;
+    /** Text helpers */
+    text: Readonly<TextHelpers>;
+    /** Array helpers */
+    array: Readonly<ArrayHelpers>;
+}
+
+/**
+ * @xnet/agent-api - Code-execution surface for agent scripts (`xnet run`).
+ *
+ * Extends the read-only ScriptContext with an `api` object that can query the
+ * loaded workspace slice and *propose* writes. Proposals never mutate the
+ * store directly; they are lifted into mutation plans that flow through the
+ * same plan/validate/apply pipeline as file edits and MCP tools.
+ */
+
+type AgentSearchResult = {
+    id: string;
+    schemaIRI: string;
+    title: string;
+    snippet: string;
+};
+type AgentWriteProposal = {
+    kind: 'update';
+    nodeId: string;
+    properties: Record<string, unknown>;
+    baseRevision: string;
+    rationale?: string;
+} | {
+    kind: 'create';
+    schemaId: string;
+    properties: Record<string, unknown>;
+    rationale?: string;
+};
+interface AgentApi {
+    /** Query the loaded workspace slice by schema IRI. */
+    nodes(schemaIRI?: string): ReadonlyArray<Readonly<FlatNode>>;
+    /** Search titles and string properties of the loaded slice. */
+    search(text: string): ReadonlyArray<Readonly<AgentSearchResult>>;
+    /** Propose a property update; becomes a mutation plan, never a direct write. */
+    proposeUpdate(nodeId: string, properties: Record<string, unknown>, rationale?: string): void;
+    /** Propose a new node; becomes a mutation plan, never a direct write. */
+    proposeCreate(schemaId: string, properties: Record<string, unknown>, rationale?: string): void;
+}
+type AgentScriptContext = ScriptContext & {
+    api: Readonly<AgentApi>;
+};
+type CreateAgentScriptContextInput = {
+    /** Workspace slice available to the script (already bounded by the caller). */
+    nodes: FlatNode[];
+    /** Optional current node; defaults to a synthetic agent-script node. */
+    node?: FlatNode;
+    /** Cap on proposals per run; guards against runaway scripts. */
+    maxProposals?: number;
+};
+type AgentScriptSession = {
+    context: AgentScriptContext;
+    getProposals(): AgentWriteProposal[];
+    /** Lift accumulated proposals into a validated mutation plan (or none). */
+    toMutationPlan(input: {
+        actor: string;
+        intent?: string;
+        clock?: () => Date;
+    }): AiMutationPlan | null;
+};
+declare function createAgentScriptContext(input: CreateAgentScriptContextInput): AgentScriptSession;
+
+/**
+ * ScriptSandbox - Isolated execution environment for user scripts
+ *
+ * Executes scripts with:
+ * - AST validation before execution
+ * - Timeout protection
+ * - Global shadowing to prevent escape
+ * - Output sanitization
+ */
+
+/**
+ * Duck-typed telemetry interface to avoid circular dependencies.
+ */
+interface TelemetryReporter {
+    reportPerformance(metricName: string, durationMs: number): void;
+    reportUsage(metricName: string, count: number): void;
+    reportCrash(error: Error, context?: Record<string, unknown>): void;
+}
+interface SandboxOptions {
+    /** Maximum execution time in milliseconds (default: 1000) */
+    timeoutMs?: number;
+    /** Whether to run AST validation (default: true) */
+    validateAST?: boolean;
+    /** Optional telemetry reporter */
+    telemetry?: TelemetryReporter;
+}
+/**
+ * Sandbox for executing user scripts safely.
+ *
+ * Scripts are validated via AST analysis and executed in an environment
+ * where dangerous globals are shadowed to undefined.
+ *
+ * @example
+ * ```typescript
+ * const sandbox = new ScriptSandbox({ timeoutMs: 500 })
+ *
+ * const context = createScriptContext(node, queryFn)
+ * const result = await sandbox.execute('(node) => node.amount * 1.08', context)
+ * ```
+ */
+declare class ScriptSandbox {
+    private options;
+    constructor(options?: SandboxOptions);
+    /**
+     * Execute a script in the sandbox.
+     *
+     * @param code - JavaScript code (expression or arrow function)
+     * @param context - The frozen ScriptContext
+     * @returns The script's return value (sanitized)
+     * @throws ScriptValidationError if AST validation fails
+     * @throws ScriptTimeoutError if execution exceeds timeout
+     * @throws ScriptError for other execution errors
+     */
+    execute(code: string, context: ScriptContext): Promise<unknown>;
+    /**
+     * Execute a script synchronously (for computed columns).
+     * Use with caution - no timeout protection in sync mode.
+     */
+    executeSync(code: string, context: ScriptContext): unknown;
+    /**
+     * Create an isolated function from user code.
+     *
+     * The function receives context values as arguments and has dangerous
+     * globals shadowed to undefined in its scope.
+     */
+    private createIsolatedFunction;
+    /**
+     * Execute a function with a timeout.
+     */
+    private executeWithTimeout;
+    /**
+     * Sanitize script output to ensure only safe values are returned.
+     *
+     * Allowed types: null, undefined, string, number, boolean, plain objects, arrays
+     * Stripped: functions, symbols, circular references, dunder properties
+     */
+    private sanitizeOutput;
+}
+
+/**
+ * In-memory NodeStore/SchemaRegistry backend.
+ *
+ * Shared by tests, the agent-surface benchmark, and CLI fixtures so each
+ * consumer does not re-implement the same mock store.
+ */
+
+type MemoryNodeStore = NodeStoreAPI & {
+    /** Test helper: update properties and bump updatedAt without going through update(). */
+    setNode(id: string, properties: Record<string, unknown>): void;
+};
+declare function createMemoryNodeStore(initialNodes: NodeData[]): MemoryNodeStore;
+declare function createMemorySchemaRegistry(schemas: SchemaData[]): SchemaRegistryAPI;
+/** The Page/Database/Canvas schema set most agent-surface fixtures use. */
+declare function createWorkspaceFixtureSchemas(): SchemaRegistryAPI;
+
 /**
  * Service Plugin Types
  *
@@ -580,4 +1786,4 @@ declare const SERVICE_IPC_CHANNELS: {
     readonly OUTPUT: "xnet:service:output";
 };
 
-export { type IProcessManager, type LocalAPIConfig, LocalAPIServer, type MCPPropertySchema, type MCPRequest, type MCPResource, type MCPResponse, MCPServer, type MCPServerConfig, type MCPTool, type NodeChangeEventData, type NodeData, type NodeStoreAPI, ProcessManager, type ProcessManagerEvents, SERVICE_IPC_CHANNELS, type SchemaData, type SchemaRegistryAPI, type ServiceClient, type ServiceCommunication, type ServiceDefinition, type ServiceHealthCheck, type ServiceLifecycle, type ServiceOutputEvent, type ServiceProcessConfig, type ServiceProvides, type ServiceState, type ServiceStatus, type ServiceStatusEvent, createLocalAPI, createMCPServer };
+export { AI_RISK_LEVELS, AI_SCOPES, AI_TARGET_KINDS, type AgentApi, type AgentScriptContext, type AgentScriptSession, type AgentSearchResult, type AgentWriteProposal, type AiAuditEvent, type AiChangeSet, type AiContextPack, type AiContextPackResource, type AiContextSeed, type AiJsonSchema, type AiJsonSchemaType, type AiMutationPlan, type AiMutationPlanStatus, type AiOperation, type AiPageMarkdownApplyAdapter, type AiPageMarkdownApplyAdapterInput, type AiPageMarkdownApplyAdapterResult, type AiPageMarkdownApplyResult, type AiPageMarkdownRollbackResult, type AiResource, type AiResourceContent, type AiRiskLevel, type AiScope, type AiSearchOptions, type AiSearchResult, type AiSurfaceLimits, AiSurfaceService, type AiSurfaceServiceConfig, type AiTargetKind, type AiToolCallResult, type AiToolDefinition, type AiValidationResult, type AiWorkspaceChangedFile, type AiWorkspaceChangedFileStatus, type AiWorkspaceCheckoutOptions, type AiWorkspaceConflict, type AiWorkspaceConflictKind, type AiWorkspaceExportKind, type AiWorkspaceExportOptions, type AiWorkspaceExportResult, type AiWorkspaceExportScope, AiWorkspaceExporter, type AiWorkspaceExporterConfig, type AiWorkspaceManifestEntry, type AiWorkspacePendingPlan, type AiWorkspaceReviewAction, type AiWorkspaceReviewEntry, type AiWorkspaceReviewEntryKind, type AiWorkspaceReviewIndex, type AiWorkspaceReviewStatus, type AiWorkspaceWatchHandle, type AiWorkspaceWatchOptions, AiWorkspaceWatcher, type AiWorkspaceWatcherScanOptions, type AiWorkspaceWatcherScanResult, type CreateAgentScriptContextInput, type FlatNode, type IProcessManager, type LocalAPIConfig, LocalAPIServer, type LocalAPITokenConfig, type LocalAPITokenScope, type LocalAPITokenSummary, type MCPPropertySchema, type MCPRequest, type MCPResource, type MCPResponse, MCPServer, type MCPServerConfig, type MCPTool, type McpHttpServerConfig, type McpHttpServerHandle, type MemoryNodeStore, type NodeChangeEventData, type NodeData, type NodeStoreAPI, ProcessManager, type ProcessManagerEvents, SERVICE_IPC_CHANNELS, type SchemaData, type SchemaRegistryAPI, ScriptSandbox, type ServiceClient, type ServiceCommunication, type ServiceDefinition, type ServiceHealthCheck, type ServiceLifecycle, type ServiceOutputEvent, type ServiceProcessConfig, type ServiceProvides, type ServiceState, type ServiceStatus, type ServiceStatusEvent, XNET_AGENT_SKILL_MD, XNET_MARKDOWN_DIRECTIVE_SPECS, type XNetMarkdownDiffLine, type XNetMarkdownDiffLineKind, type XNetMarkdownDirective, type XNetMarkdownDirectiveSpec, type XNetMarkdownReviewDiff, type XNetPageMarkdownFrontmatter, type XNetPageMarkdownValidation, type XNetPageMarkdownValidationOptions, attachAiPlanValidation, createAgentScriptContext, createAiChangeSet, createAiOperation, createAiSurfaceService, createAiValidationResult, createAiWorkspaceExporter, createAiWorkspaceWatcher, createLocalAPI, createMCPServer, createMcpHttpServer, createMemoryNodeStore, createMemorySchemaRegistry, createWorkspaceFixtureSchemas, flattenRowForTsv, getXNetMarkdownDirectiveSpecs, isAiRiskLevel, isAiScope, isAiTargetKind, parseAiMutationPlan, parseXNetPageFrontmatter, renderMarkdownLineDiff, renderMarkdownReviewDiff, serializeAiMutationPlan, stripXNetPageFrontmatter, toTsv, validateAiMutationPlan, validateXNetPageMarkdown };