@xnetjs/plugins 0.0.2 → 0.1.0

package/dist/index.d.ts

@@ -1,7 +1,10 @@
 import * as _xnetjs_data from '@xnetjs/data';
-import { SchemaIRI, NodeStore, NodeState } from '@xnetjs/data';
+import { SchemaIRI, NodeStore, NodeState, NodeQueryDescriptor, NodeQueryResult } from '@xnetjs/data';
 import { Extension } from '@tiptap/core';
 import { ComponentType } from 'react';
+import { PublicWriteBudgetPolicy, AbuseSurface, AISignalProvenanceInput } from '@xnetjs/abuse';
+import { InstallProvenance, TrustTier } from '@xnetjs/trust';
+export { InstallProvenance, TrustTier as PluginTrustTier, SandboxKind, deriveTrustTier, requiresCapabilityReprompt, sandboxForTier } from '@xnetjs/trust';
 
 /**
  * Core types for the plugin system
@@ -57,10 +60,256 @@ interface ExtensionStorage {
 }
 declare function createExtensionStorage(): ExtensionStorage;
 
+/**
+ * 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>;
+}
+/** Convert one contribution into an AI-surface tool. */
+declare function agentToolToExtraTool(tool: AgentToolContribution): AiExtraTool;
+/**
+ * Convert contributed agent tools into AI-surface tools, de-duped by tool name
+ * (first wins — registration order). Pass the result as the AI surface's
+ * `extraTools` so they surface in the in-app AI and the MCP server.
+ */
+declare function agentToolsAsExtraTools(tools: readonly AgentToolContribution[]): AiExtraTool[];
+
+/**
+ * @xnetjs/plugins — extensible mention/typeahead providers (exploration 0194
+ * Phase 4).
+ *
+ * The editor's `[[` / `#` / `@` typeaheads are host-callback-driven and not
+ * extensible by plugins. This contribution point lets a plugin add a new entity
+ * type to a trigger — a GitHub plugin makes `@` resolve issues, a CRM plugin
+ * makes it resolve contacts — and the host merges them with its own suggestions.
+ *
+ * `resolveMentionProviders` is the consumer logic the editor runs: it fans the
+ * query out to every provider for a trigger in parallel, merges by priority,
+ * dedups by suggestion id, and **timeout-guards** each provider so one slow or
+ * throwing provider can never block (or break) the menu.
+ */
+/** A single typeahead suggestion offered by a provider. */
+interface MentionSuggestion {
+    /** Stable id, used for dedup across providers. */
+    id: string;
+    /** Text shown in the menu. */
+    label: string;
+    /** Secondary text (e.g. a handle, path, or type). */
+    detail?: string;
+    /** The reference to insert when chosen (defaults to `id`). */
+    value?: string;
+    /** Lucide icon name. */
+    icon?: string;
+}
+/** A plugin-contributed provider for one typeahead trigger. */
+interface MentionProviderContribution {
+    /** Unique provider id. */
+    id: string;
+    /** Trigger token: `'[['` | `'#'` | `'@'`, or a plugin's own string. */
+    trigger: string;
+    /** Lower runs first when merging (default 100). */
+    priority?: number;
+    /** Resolve suggestions for a query under this trigger. */
+    getSuggestions: (query: string) => MentionSuggestion[] | Promise<MentionSuggestion[]>;
+}
+interface ResolveMentionOptions {
+    /** Per-provider timeout; a provider that exceeds it contributes nothing. */
+    timeoutMs?: number;
+    /** Cap the merged result length. */
+    limit?: number;
+}
+/**
+ * Merge the suggestions from every provider registered for `trigger`, in
+ * priority order, deduped by suggestion id, each provider timeout-guarded.
+ */
+declare function resolveMentionProviders(providers: readonly MentionProviderContribution[], trigger: string, query: string, options?: ResolveMentionOptions): Promise<MentionSuggestion[]>;
+
 /**
  * Contribution types and registry for plugin-provided extensions
  */
 
+/**
+ * How a command opts in to being callable by the AI agent as a tool
+ * (exploration 0194 Phase 2). Absent / `aiExposed:false` → the AI never sees it.
+ */
+interface AiCommandExposure {
+    /** Expose this command to the AI agent as a callable tool. Opt-in. */
+    aiExposed?: boolean;
+    /** JSON schema for the tool's args (defaults to an empty object schema). */
+    aiInputSchema?: {
+        type: 'object';
+        properties: Record<string, AiJsonSchema>;
+        required?: readonly string[];
+    };
+    /** Risk level surfaced to the agent + consent (default `medium`). */
+    aiRisk?: AiRiskLevel;
+    /** AI scopes this command requires (checked against the plugin's grant; default none). */
+    aiScopes?: AiScope[];
+    /** Arg-taking AI invocation; falls back to `execute()` when absent. */
+    aiInvoke?: (args: Record<string, unknown>) => unknown | Promise<unknown>;
+}
 interface ViewContribution {
     /** Unique view type identifier */
     type: string;
@@ -77,7 +326,7 @@ interface ViewProps {
     nodeId: string;
     schemaId: string;
 }
-interface CommandContribution {
+interface CommandContribution extends AiCommandExposure {
     /** Unique command ID */
     id: string;
     /** Display name */
@@ -143,6 +392,24 @@ interface EditorContribution {
     /** Priority for extension ordering (lower = earlier, default: 100) */
     priority?: number;
 }
+/**
+ * Status bar item contributed by a plugin (0166 workbench).
+ * Left side = workspace scope; right side = view scope.
+ */
+interface StatusBarContribution {
+    /** Unique item ID */
+    id: string;
+    /** Static text, or a getter polled on render */
+    text: string | (() => string);
+    /** Which side of the status bar (default 'left') */
+    side?: 'left' | 'right';
+    /** Tooltip */
+    tooltip?: string;
+    /** Command id (CommandRegistry) to run on click */
+    command?: string;
+    /** Priority within the side (lower = earlier) */
+    priority?: number;
+}
 interface SidebarContribution {
     /** Unique item ID */
     id: string;
@@ -163,6 +430,73 @@ interface SidebarContribution {
     /** Optional panel component to render */
     panel?: ComponentType;
 }
+/**
+ * Dashboard widget contribution (0162).
+ *
+ * Mirrors WidgetDefinition from @xnetjs/dashboard structurally (kept
+ * dependency-free here, like ViewContribution). The host assigns the trust
+ * tier from the plugin's install source — plugins never self-declare it —
+ * and registers the widget into the dashboard WidgetRegistry.
+ */
+interface WidgetContribution {
+    /** Widget registry key, e.g. 'com.example.burndown' (plugin-scoped) */
+    type: string;
+    /** Display name shown in the widget picker */
+    name: string;
+    /** Lucide icon name or component */
+    icon?: string | ComponentType;
+    /** Short description for the picker */
+    description?: string;
+    /** Config fields driving the auto-generated editor */
+    configFields?: WidgetContributionConfigField[];
+    /** Default + minimum tile size in 12-column grid units */
+    defaultSize: {
+        w: number;
+        h: number;
+        minW?: number;
+        minH?: number;
+    };
+    /** Sensible defaults so a freshly added widget renders immediately */
+    getStubConfig: (ctx: {
+        schemas: string[];
+    }) => {
+        config: Record<string, unknown>;
+        query?: unknown;
+    };
+    /** The renderer (runs in the tier-appropriate host) */
+    component: ComponentType<WidgetContributionProps>;
+}
+interface WidgetContributionConfigField {
+    key: string;
+    label: string;
+    type: 'property-select' | 'select' | 'number' | 'checkbox' | 'text' | 'color';
+    options?: Array<{
+        label: string;
+        value: string;
+    }>;
+    required?: boolean;
+    description?: string;
+    defaultValue?: unknown;
+}
+interface WidgetContributionProps {
+    config: Record<string, unknown>;
+    data: {
+        rows: Array<Record<string, unknown> & {
+            id: string;
+        }>;
+        aggregates: unknown;
+        queries: Record<string, Array<Record<string, unknown> & {
+            id: string;
+        }>>;
+        loading: boolean;
+        error: Error | null;
+    };
+    width: number;
+    height: number;
+    variables: Readonly<Record<string, unknown>>;
+    onConfigChange?: (next: Record<string, unknown>) => void;
+    onOpenNode?: (nodeId: string, schemaId: string) => void;
+}
 interface PropertyHandlerContribution {
     /** Property type this handler manages */
     type: string;
@@ -228,6 +562,128 @@ interface SchemaContribution {
     /** The schema definition */
     schema: unknown;
 }
+type CanvasPreviewTier = 'summary' | 'thumbnail' | 'shell' | 'live';
+type CanvasIngestInputKind = 'url' | 'file' | 'data-transfer' | 'text' | 'node' | 'custom';
+type CanvasToolGroup = 'select' | 'create' | 'connect' | 'annotate' | 'layout' | 'custom';
+type CanvasLayoutScope = 'selection' | 'frame' | 'canvas' | 'query-results' | 'mind-map' | 'custom';
+type CanvasInspectorPlacement = 'popover' | 'side-panel' | 'bottom-panel';
+type CanvasTemplateCategory = 'planning' | 'research' | 'operations' | 'diagramming' | 'erp' | 'custom';
+type CanvasContributionPermission = 'canvas.read' | 'canvas.write' | 'canvas.ingest' | 'canvas.render' | 'canvas.layout' | 'network' | 'storage' | 'clipboard';
+interface CanvasContributionBase {
+    /** Unique contribution ID, preferably plugin-scoped */
+    id: string;
+    /** Contribution discriminator for validation and registry routing */
+    type: string;
+    /** Display name shown in canvas menus, toolbars, or inspectors */
+    name?: string;
+    /** Short help text for command palettes and plugin management */
+    description?: string;
+    /** Lucide icon name or plugin-owned icon token */
+    icon?: string;
+    /** Lower values win when multiple plugin contributions match */
+    priority?: number;
+    /** Fine-grained capabilities requested by this canvas contribution */
+    permissions?: CanvasContributionPermission[];
+}
+interface CanvasCardContribution extends CanvasContributionBase {
+    type: 'canvas.card';
+    /** Source schema this card knows how to render */
+    schemaId?: string;
+    /** External-reference provider ID, such as youtube, spotify, github, or crm */
+    provider?: string;
+    /** Canvas object kinds supported by this card */
+    canvasKinds?: string[];
+    /** LOD tiers this card can satisfy */
+    previewTiers?: CanvasPreviewTier[];
+    /** Sandboxed renderer module/function ID */
+    rendererEntrypoint: string;
+    /** Optional deterministic thumbnail/summary entrypoint */
+    previewEntrypoint?: string;
+    /** Human-readable fallback label when renderer is unavailable */
+    fallbackLabel?: string;
+}
+interface CanvasIngestorContribution extends CanvasContributionBase {
+    type: 'canvas.ingestor';
+    input: CanvasIngestInputKind;
+    /** MIME types accepted by file/data-transfer ingestors */
+    mimeTypes?: string[];
+    /** File extensions accepted by file ingestors */
+    fileExtensions?: string[];
+    /** URL patterns or provider tokens matched by URL ingestors */
+    urlPatterns?: string[];
+    /** Sandboxed matcher entrypoint */
+    matchEntrypoint: string;
+    /** Sandboxed ingestion entrypoint */
+    ingestEntrypoint: string;
+}
+interface CanvasToolContribution extends CanvasContributionBase {
+    type: 'canvas.tool';
+    group?: CanvasToolGroup;
+    keybinding?: string;
+    cursor?: string;
+    /** Sandboxed activation entrypoint that returns a tool controller */
+    activationEntrypoint: string;
+}
+interface CanvasLayoutContribution extends CanvasContributionBase {
+    type: 'canvas.layout';
+    scope: CanvasLayoutScope;
+    supportedKinds?: string[];
+    supportedSchemas?: string[];
+    /** Sandboxed layout function entrypoint */
+    applyEntrypoint: string;
+}
+interface CanvasEdgeContribution extends CanvasContributionBase {
+    type: 'canvas.edge';
+    label: string;
+    directed: boolean;
+    allowedSourceSchemas?: string[];
+    allowedTargetSchemas?: string[];
+    style?: 'solid' | 'dashed' | 'dotted';
+}
+interface CanvasInspectorContribution extends CanvasContributionBase {
+    type: 'canvas.inspector';
+    placement: CanvasInspectorPlacement;
+    supportedKinds?: string[];
+    supportedSchemas?: string[];
+    supportedProviders?: string[];
+    /** Sandboxed panel renderer entrypoint */
+    panelEntrypoint: string;
+}
+interface CanvasTemplateContribution extends CanvasContributionBase {
+    type: 'canvas.template';
+    category: CanvasTemplateCategory;
+    tags?: string[];
+    /** Sandboxed template instantiation entrypoint */
+    instantiateEntrypoint: string;
+    /** Optional preview renderer entrypoint */
+    previewEntrypoint?: string;
+}
+type CanvasContribution = CanvasCardContribution | CanvasIngestorContribution | CanvasToolContribution | CanvasLayoutContribution | CanvasEdgeContribution | CanvasInspectorContribution | CanvasTemplateContribution;
+/**
+ * Importer contribution (exploration 0189).
+ *
+ * A data-export / source importer — e.g. an Instagram or YouTube archive
+ * importer. Mirrors `@xnetjs/social`'s `SocialImportAdapter` *structurally* so
+ * the first-party social adapters can register through the plugin system
+ * without `@xnetjs/plugins` depending on `@xnetjs/social` (dependency direction
+ * stays social → plugins). The `adapter` is opaque to the registry; the consumer
+ * (the import flow) casts it to its known importer shape. This is the same
+ * "defined now, consumed later" pattern as the canvas contributions.
+ */
+interface ImporterContribution {
+    /** Unique importer ID, preferably plugin-scoped (e.g. 'fyi.xnet.import.instagram'). */
+    id: string;
+    /** Source platform/system this importer handles (e.g. 'instagram', 'youtube'). */
+    platform: string;
+    /** Importer version. */
+    version: string;
+    /** Human-readable label for the import picker. */
+    name?: string;
+    /** Lucide icon name. */
+    icon?: string;
+    /** The importer adapter implementation (structurally a `SocialImportAdapter`). */
+    adapter: unknown;
+}
 /**
  * A registry for typed contributions with change notifications
  */
@@ -252,19 +708,151 @@ declare class TypedRegistry<T extends {
  */
 declare class ContributionRegistry {
     readonly views: TypedRegistry<ViewContribution>;
+    readonly widgets: TypedRegistry<WidgetContribution>;
     readonly commands: TypedRegistry<CommandContribution>;
     readonly slashCommands: TypedRegistry<SlashCommandContribution>;
     readonly sidebar: TypedRegistry<SidebarContribution>;
+    readonly statusBar: TypedRegistry<StatusBarContribution>;
     readonly editor: TypedRegistry<EditorContribution>;
     readonly propertyHandlers: TypedRegistry<PropertyHandlerContribution>;
     readonly blocks: TypedRegistry<BlockContribution>;
     readonly settings: TypedRegistry<SettingContribution>;
+    readonly canvasCards: TypedRegistry<CanvasCardContribution>;
+    readonly canvasIngestors: TypedRegistry<CanvasIngestorContribution>;
+    readonly canvasTools: TypedRegistry<CanvasToolContribution>;
+    readonly canvasLayouts: TypedRegistry<CanvasLayoutContribution>;
+    readonly canvasEdges: TypedRegistry<CanvasEdgeContribution>;
+    readonly canvasInspectors: TypedRegistry<CanvasInspectorContribution>;
+    readonly canvasTemplates: TypedRegistry<CanvasTemplateContribution>;
+    readonly importers: TypedRegistry<ImporterContribution>;
+    readonly mentionProviders: TypedRegistry<MentionProviderContribution>;
+    readonly agentTools: TypedRegistry<AgentToolContribution>;
     /**
      * Clear all registries (for cleanup/testing)
      */
     clear(): void;
 }
 
+/**
+ * Canvas plugin permission policy helpers.
+ */
+
+type CanvasPluginPermissionDecisionStatus = 'allowed' | 'prompt-required' | 'blocked';
+type CanvasPluginPromptMode = 'allow-once' | 'allow-workspace' | 'deny';
+type CanvasPluginWorkspacePolicy = {
+    allowUnknownPlugins?: boolean;
+    trustedPluginIds?: string[];
+    blockedPluginIds?: string[];
+    allowedPermissions?: CanvasContributionPermission[] | '*';
+    blockedPermissions?: CanvasContributionPermission[];
+    promptPermissions?: CanvasContributionPermission[];
+    allowedNetworkDomains?: string[];
+    blockedNetworkDomains?: string[];
+};
+type CanvasPluginPermissionGateInput = {
+    pluginId: string;
+    contributionId: string;
+    contributionName?: string;
+    requestedPermissions?: CanvasContributionPermission[];
+    requestedNetworkDomains?: string[];
+    policy?: CanvasPluginWorkspacePolicy | null;
+};
+type CanvasPluginPermissionPromptOption = {
+    mode: CanvasPluginPromptMode;
+    label: string;
+    description: string;
+    persistsDecision: boolean;
+};
+type CanvasPluginPermissionPrompt = {
+    pluginId: string;
+    contributionId: string;
+    title: string;
+    message: string;
+    requestedPermissions: CanvasContributionPermission[];
+    requestedNetworkDomains: string[];
+    options: CanvasPluginPermissionPromptOption[];
+};
+type CanvasPluginPermissionGateDecision = {
+    status: CanvasPluginPermissionDecisionStatus;
+    allowed: boolean;
+    prompt: CanvasPluginPermissionPrompt | null;
+    grantedPermissions: CanvasContributionPermission[];
+    pendingPermissions: CanvasContributionPermission[];
+    blockedPermissions: CanvasContributionPermission[];
+    blockedNetworkDomains: string[];
+    pendingNetworkDomains: string[];
+    issues: string[];
+};
+declare function evaluateCanvasPluginPermissionGate(input: CanvasPluginPermissionGateInput): CanvasPluginPermissionGateDecision;
+declare function createCanvasPluginPermissionPrompt(input: {
+    pluginId: string;
+    contributionId: string;
+    contributionName?: string;
+    requestedPermissions: CanvasContributionPermission[];
+    requestedNetworkDomains: string[];
+}): CanvasPluginPermissionPrompt;
+declare function normalizeCanvasPluginWorkspacePolicy(policy?: CanvasPluginWorkspacePolicy | null): Required<CanvasPluginWorkspacePolicy>;
+
+/**
+ * @xnetjs/plugins — FeatureModule (exploration 0189).
+ *
+ * A `FeatureModule` is the uniform shape every first-party integration and
+ * community plugin can take: a superset of `XNetExtension` (the client
+ * contributions) that also **declares its capability surface** and, by
+ * convention via a shared `id`, links to a hub-side feature mounted through
+ * `@xnetjs/hub`'s feature registry.
+ *
+ * The client stays hub-free on purpose: `hub` here is a *declarative pointer*
+ * (an id), not server code. The actual hub routes/secrets live in the hub
+ * package's `HubFeature`, and the hub's capability/secret broker is what
+ * enforces `capabilities.secrets`. This keeps the dependency direction clean
+ * (no `@xnetjs/plugins` → `@xnetjs/hub` edge) while letting one manifest
+ * document the full two-sided surface — billing, GitHub, importers, and
+ * eventually core surfaces all expressed the same way.
+ */
+
+/**
+ * The capability surface a module declares. The install UI renders this as a
+ * consent dialog; the hub broker injects only the declared `secrets`; the
+ * client sandbox exposes only the declared `endowments`.
+ */
+interface ModuleCapabilities {
+    /**
+     * Env secret keys the module's hub half is permitted to read. Supports exact
+     * keys (`STRIPE_SECRET_KEY`) and `PREFIX_*` globs (`BTCPAY_*`). First-party
+     * tier only — community modules never receive raw secrets.
+     */
+    secrets?: string[];
+    /** Schema IRIs the module may write. */
+    schemaWrite?: string[];
+    /** Schema IRIs the module may read. */
+    schemaRead?: string[];
+    /** Network domains the module may reach (allowlist), e.g. for unfurl/proxy. */
+    network?: string[];
+    /** Host APIs the client sandbox should expose to the module's code. */
+    endowments?: string[];
+}
+/**
+ * A two-sided feature module. Inherits all client `contributes` (including the
+ * new `importers` point) from `XNetExtension`, and adds the capability
+ * declaration + the hub linkage.
+ */
+interface FeatureModule extends XNetExtension {
+    /** Declared capability surface (client + hub). The hub broker enforces `secrets`. */
+    capabilities?: ModuleCapabilities;
+    /**
+     * Declarative pointer to a hub-side feature. By convention the hub feature is
+     * registered under the same `id` and mounted at `/x/<featureId>` (or, for the
+     * bundled first-party features, at their legacy path). Absence means the
+     * module is client-only.
+     */
+    hub?: {
+        featureId: string;
+    };
+}
+/** Define a feature module with type checking (mirrors `defineExtension`). */
+declare function defineFeatureModule(module: FeatureModule): FeatureModule;
+
 /**
  * NodeStore middleware chain for pre/post change hooks
  */
@@ -369,6 +957,8 @@ interface ExtensionContext {
     registerSchema(schema: unknown): Disposable$1;
     /** Register a custom view type */
     registerView(view: ViewContribution): Disposable$1;
+    /** Register a dashboard widget (trust tier assigned by the host) */
+    registerWidget(widget: WidgetContribution): Disposable$1;
     /** Register a property type handler */
     registerPropertyHandler(type: string, handler: PropertyHandlerContribution['handler']): Disposable$1;
     /** Register a command */
@@ -381,6 +971,26 @@ interface ExtensionContext {
     registerSlashCommand(cmd: SlashCommandContribution): Disposable$1;
     /** Register a custom block type */
     registerBlockType(block: BlockContribution): Disposable$1;
+    /** Register a canvas card renderer descriptor */
+    registerCanvasCard(card: CanvasCardContribution): Disposable$1;
+    /** Register a canvas ingestor descriptor */
+    registerCanvasIngestor(ingestor: CanvasIngestorContribution): Disposable$1;
+    /** Register a canvas tool descriptor */
+    registerCanvasTool(tool: CanvasToolContribution): Disposable$1;
+    /** Register a canvas layout descriptor */
+    registerCanvasLayout(layout: CanvasLayoutContribution): Disposable$1;
+    /** Register a canvas edge relationship descriptor */
+    registerCanvasEdge(edge: CanvasEdgeContribution): Disposable$1;
+    /** Register a canvas inspector descriptor */
+    registerCanvasInspector(inspector: CanvasInspectorContribution): Disposable$1;
+    /** Register a canvas template descriptor */
+    registerCanvasTemplate(template: CanvasTemplateContribution): Disposable$1;
+    /** Register a data-export / source importer (exploration 0189) */
+    registerImporter(importer: ImporterContribution): Disposable$1;
+    /** Register a mention/typeahead provider (exploration 0194) */
+    registerMentionProvider(provider: MentionProviderContribution): Disposable$1;
+    /** Register a model-facing agent tool (exploration 0196) */
+    registerAgentTool(tool: AgentToolContribution): Disposable$1;
     /** Add middleware to NodeStore */
     addMiddleware(middleware: NodeStoreMiddleware): Disposable$1;
     /** Plugin-private storage */
@@ -398,6 +1008,13 @@ interface CreateContextOptions {
     middlewareChain?: {
         add(middleware: NodeStoreMiddleware): Disposable$1;
     };
+    /**
+     * Declared capability grant (exploration 0192). When present, the plugin's
+     * `store` handle is wrapped so writes outside `schemaWrite` throw — turning the
+     * declaration into an enforced gate at the one choke point a plugin can't
+     * route around. Absent/empty → the store is handed through unguarded.
+     */
+    capabilities?: ModuleCapabilities;
 }
 /**
  * Create an ExtensionContext for a plugin
@@ -408,6 +1025,29 @@ declare function createExtensionContext(options: CreateContextOptions): Extensio
  * Plugin manifest types and validation
  */
 
+/**
+ * How a plugin is monetized (exploration 0196). `free` is the default when
+ * `pricing` is absent. Paid plugins (`one-time`/`subscription`) are gated at
+ * install by a license check (see `PluginRegistry.install`'s `checkLicense`).
+ */
+interface PluginPricing {
+    /** `free` — no license required. `one-time`/`subscription` — license-gated. */
+    mode: 'free' | 'one-time' | 'subscription';
+    /** Price in integer minor units (e.g. cents). Omitted/0 for free. */
+    amountMinor?: number;
+    /** ISO-4217 currency code (e.g. `USD`). Required when `amountMinor` > 0. */
+    currency?: string;
+    /**
+     * Who runs checkout: `managed` = the xNet marketplace via Stripe Connect (the
+     * platform takes its fee); `byo` = the author hosts their own checkout and
+     * mints their own license (xNet takes 0%). Default `managed`.
+     */
+    billing?: 'managed' | 'byo';
+    /** Free-trial length in days (subscriptions). */
+    trialDays?: number;
+}
+/** True when a pricing descriptor denotes a paid plugin that needs a license. */
+declare function isPaidPricing(pricing: PluginPricing | undefined): boolean;
 /**
  * Plugin manifest - defines what a plugin provides and how it integrates
  */
@@ -422,12 +1062,31 @@ interface XNetExtension {
     description?: string;
     /** Author name or organization */
     author?: string;
-    /** Minimum compatible xNet version */
+    /** Minimum compatible xNet version (semver range, e.g. ">=0.6.0") */
     xnetVersion?: string;
     /** Platforms this plugin supports (default: all) */
     platforms?: Platform[];
     /** Permission declarations */
     permissions?: PluginPermissions;
+    /**
+     * Other plugins this one requires, as `{ '<pluginId>': '<versionRange>' }`
+     * (exploration 0192). Resolved at install time — see `ecosystem/dependencies`.
+     */
+    dependencies?: Record<string, string>;
+    /**
+     * SPDX license id (exploration 0196). Paid plugins must declare a license the
+     * marketplace pre-approves — `FSL-1.1-MIT` / `FSL-1.1-Apache-2.0` (source-
+     * available, auto-opens after 2 years) or an OSI id (`MIT`, `Apache-2.0`, …).
+     * Defaults to `MIT` when absent.
+     */
+    license?: string;
+    /** How this plugin is monetized (exploration 0196). Absent = free. */
+    pricing?: PluginPricing;
+    /**
+     * The publisher's DID. Supersedes the bare `author` string for paid plugins —
+     * licenses, payouts, and provenance attach to this identity (exploration 0196).
+     */
+    publisherDid?: string;
     /** Static contributions declared in manifest */
     contributes?: PluginContributions;
     /** Called when plugin is activated */
@@ -441,6 +1100,8 @@ interface XNetExtension {
 interface PluginContributions {
     schemas?: SchemaContribution[];
     views?: ViewContribution[];
+    /** Dashboard widgets (0162); trust tier is host-assigned at registration */
+    widgets?: WidgetContribution[];
     editorExtensions?: EditorContribution[];
     propertyHandlers?: PropertyHandlerContribution[];
     blocks?: BlockContribution[];
@@ -448,6 +1109,19 @@ interface PluginContributions {
     settings?: SettingContribution[];
     sidebarItems?: SidebarContribution[];
     slashCommands?: SlashCommandContribution[];
+    canvasCards?: CanvasCardContribution[];
+    canvasIngestors?: CanvasIngestorContribution[];
+    canvasTools?: CanvasToolContribution[];
+    canvasLayouts?: CanvasLayoutContribution[];
+    canvasEdges?: CanvasEdgeContribution[];
+    canvasInspectors?: CanvasInspectorContribution[];
+    canvasTemplates?: CanvasTemplateContribution[];
+    /** Data-export / source importers (exploration 0189). */
+    importers?: ImporterContribution[];
+    /** Mention/typeahead providers — extend `[[`/`#`/`@` (exploration 0194). */
+    mentionProviders?: MentionProviderContribution[];
+    /** Model-facing agent tools — what a Connector exposes (exploration 0196). */
+    agentTools?: AgentToolContribution[];
 }
 declare class PluginValidationError extends Error {
     readonly issues: string[];
@@ -463,6 +1137,148 @@ declare function validateManifest(manifest: unknown): XNetExtension;
  */
 declare function defineExtension(manifest: XNetExtension): XNetExtension;
 
+/**
+ * @xnetjs/plugins — importer resolution (exploration 0189).
+ *
+ * Consumer-side helpers for the `importers` contribution point: pull the adapter
+ * objects out of plugin contributions, and merge them with a set of built-in
+ * importers (deduped by id — a plugin-contributed importer overrides a built-in
+ * with the same id). Kept generic and adapter-shape-agnostic so the social
+ * import flow (or any importer host) can call it without `@xnetjs/plugins`
+ * depending on `@xnetjs/social`.
+ */
+
+/** The adapter objects carried by importer contributions (opaque to the registry). */
+declare function importerAdapters(contributions: readonly ImporterContribution[]): unknown[];
+/**
+ * Merge built-in importer adapters with contributed ones, deduped by `id`. A
+ * contributed importer with the same id as a built-in overrides it (so a plugin
+ * can replace a first-party importer). The consumer casts the result to its own
+ * importer-adapter type.
+ */
+declare function resolveImporters<A extends {
+    id: string;
+}>(builtIns: readonly A[], contributed: readonly A[]): A[];
+
+/**
+ * Fake canvas plugin fixtures for CRM, ERP, and media-provider cards.
+ */
+
+type CanvasPluginFixtureKind = 'crm' | 'erp' | 'media-provider';
+type CanvasPluginFixtureCardSample = {
+    id: string;
+    pluginId: string;
+    contributionId: string;
+    title: string;
+    subtitle: string;
+    schemaId?: `xnet://${string}/${string}`;
+    provider?: string;
+    canvasKind: string;
+    previewTier: 'summary' | 'thumbnail' | 'shell' | 'live';
+    properties: Record<string, unknown>;
+};
+type CanvasPluginFixture = {
+    kind: CanvasPluginFixtureKind;
+    manifest: XNetExtension;
+    sampleCards: CanvasPluginFixtureCardSample[];
+};
+declare const CRM_CANVAS_PLUGIN_FIXTURE: CanvasPluginFixture;
+declare const ERP_CANVAS_PLUGIN_FIXTURE: CanvasPluginFixture;
+declare const MEDIA_PROVIDER_CANVAS_PLUGIN_FIXTURE: CanvasPluginFixture;
+declare const CANVAS_PLUGIN_FIXTURES: CanvasPluginFixture[];
+declare function getCanvasPluginFixture(kind: CanvasPluginFixtureKind): CanvasPluginFixture | undefined;
+declare function createCanvasPluginFixtureManifests(): XNetExtension[];
+declare function createCanvasPluginFixtureCards(): CanvasPluginFixtureCardSample[];
+
+/**
+ * Sample ERP canvas prototype built from the ERP canvas plugin fixture.
+ */
+
+type CanvasErpPrototypeEntityKind = 'purchase-order' | 'inventory-item';
+type CanvasErpPrototypeRisk = 'low' | 'medium' | 'high';
+type CanvasErpPrototypeStatus = 'awaiting-shipment' | 'in-transit' | 'qa-hold' | 'stockout-risk' | 'healthy' | 'receiving';
+type CanvasErpPrototypeLayoutKind = 'supply-chain' | 'procurement-kanban' | 'inventory-risk-grid' | 'receiving-timeline';
+type CanvasErpPrototypeAuditOperation = 'created' | 'moved' | 'resized' | 'field-updated' | 'bulk-updated' | 'synced';
+type CanvasErpPrototypeAuditSource = 'user' | 'plugin' | 'external-system';
+type CanvasErpPrototypeRect = {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+};
+type CanvasErpPrototypeCard = Omit<CanvasPluginFixtureCardSample, 'properties'> & {
+    readonly sourceNodeId: `xnet://fixtures.erp/${string}`;
+    readonly entityKind: CanvasErpPrototypeEntityKind;
+    readonly status: CanvasErpPrototypeStatus;
+    readonly risk: CanvasErpPrototypeRisk;
+    readonly position: CanvasErpPrototypeRect;
+    readonly tags: readonly string[];
+    readonly properties: Record<string, unknown>;
+};
+type CanvasErpPrototypeEdge = {
+    readonly id: string;
+    readonly contributionId: 'erp.supplies' | 'erp.delayed-by';
+    readonly sourceCardId: string;
+    readonly targetCardId: string;
+    readonly label: string;
+    readonly directed: true;
+    readonly style: 'solid' | 'dotted';
+    readonly properties: Record<string, unknown>;
+};
+type CanvasErpPrototypeQueryPredicate = {
+    readonly field: string;
+    readonly operator: 'equals' | 'not-equals' | 'less-than' | 'greater-than' | 'contains';
+    readonly value: unknown;
+};
+type CanvasErpPrototypeQueryFrame = {
+    readonly id: string;
+    readonly title: string;
+    readonly layoutKind: CanvasErpPrototypeLayoutKind;
+    readonly bounds: CanvasErpPrototypeRect;
+    readonly schemaIds: readonly `xnet://${string}/${string}`[];
+    readonly predicates: readonly CanvasErpPrototypeQueryPredicate[];
+    readonly cardIds: readonly string[];
+};
+type CanvasErpPrototypeCommand = {
+    readonly id: string;
+    readonly label: string;
+    readonly scope: 'single-card' | 'multi-card' | 'frame';
+    readonly requiredPermissions: readonly ('canvas.read' | 'canvas.write' | 'canvas.layout')[];
+    readonly supportedEntityKinds: readonly CanvasErpPrototypeEntityKind[];
+};
+type CanvasErpPrototypeAuditEntry = {
+    readonly id: string;
+    readonly cardId: string;
+    readonly operation: CanvasErpPrototypeAuditOperation;
+    readonly source: CanvasErpPrototypeAuditSource;
+    readonly actor: string;
+    readonly at: string;
+    readonly summary: string;
+    readonly batchId?: string;
+};
+type CanvasErpPrototypeRiskSummary = {
+    readonly total: number;
+    readonly low: number;
+    readonly medium: number;
+    readonly high: number;
+};
+type CanvasErpPrototypeScenario = {
+    readonly id: string;
+    readonly title: string;
+    readonly pluginManifest: XNetExtension;
+    readonly templateId: 'erp.procurement-war-room';
+    readonly cards: readonly CanvasErpPrototypeCard[];
+    readonly edges: readonly CanvasErpPrototypeEdge[];
+    readonly queryFrames: readonly CanvasErpPrototypeQueryFrame[];
+    readonly commands: readonly CanvasErpPrototypeCommand[];
+    readonly auditEntries: readonly CanvasErpPrototypeAuditEntry[];
+    readonly riskSummary: CanvasErpPrototypeRiskSummary;
+};
+declare function createCanvasErpPrototypeRiskSummary(cards: readonly CanvasErpPrototypeCard[]): CanvasErpPrototypeRiskSummary;
+declare function createCanvasErpPrototypeScenario(): CanvasErpPrototypeScenario;
+declare function getCanvasErpPrototypeCardsForFrame(scenario: CanvasErpPrototypeScenario, frameId: string): CanvasErpPrototypeCard[];
+declare function getCanvasErpPrototypeAuditEntriesForCard(scenario: CanvasErpPrototypeScenario, cardId: string): CanvasErpPrototypeAuditEntry[];
+
 /**
  * Keyboard Shortcut Manager
  *
@@ -551,14 +1367,1525 @@ declare class ShortcutManager {
     clear(): void;
 }
 /**
- * Get or create the global ShortcutManager instance.
+ * Get or create the global ShortcutManager instance.
+ */
+declare function getShortcutManager(): ShortcutManager;
+/**
+ * Install the global shortcut manager on the window.
+ * Call this once at app startup.
+ */
+declare function installShortcutHandler(): () => void;
+
+/**
+ * Workspace Command Registry
+ *
+ * One registry for every keyboard-driven verb in the workspace
+ * (exploration 0161, phase 3). Generalizes ShortcutManager with:
+ *
+ * - **Scopes**: commands belong to a scope ('global', 'surface:grid',
+ *   'task-focused', …). Surfaces activate their scope on focus/mount and
+ *   dispose on blur/unmount; only commands in active scopes fire. The most
+ *   recently activated scope wins key conflicts (global loses to all).
+ * - **Single-key verbs**: Linear-style bindings ('s', 'a', 'p') that are
+ *   automatically suppressed while any input/textarea/contenteditable has
+ *   focus — modifier combos can opt into editors via `allowInInput`.
+ * - **Chords**: 'g t'-style two-step sequences with a pending-step timeout.
+ *
+ * Surfaces register commands instead of owning their own key handling, so
+ * the palette can list every available action with its binding.
+ */
+
+type CommandScope = 'global' | (string & NonNullable<unknown>);
+interface CommandContext {
+    /** The scope the command was resolved in */
+    scope: CommandScope;
+    /** The triggering keyboard event (absent when run from the palette) */
+    event?: KeyboardEvent;
+}
+interface WorkspaceCommand {
+    /** Unique id, e.g. 'task.setStatus' */
+    id: string;
+    /** Palette title, e.g. 'Change status…' */
+    title: string;
+    /** Scope this command belongs to (default 'global') */
+    scope?: CommandScope;
+    /**
+     * Key binding: a single key ('s', '?'), a modifier combo ('Mod-K'),
+     * or a space-separated chord ('g t'). Omit for palette-only commands.
+     */
+    key?: string;
+    /** Allow firing while an input/editor has focus (modifier combos only) */
+    allowInInput?: boolean;
+    /** Availability guard checked at dispatch and palette-listing time */
+    when?: () => boolean;
+    run: (context: CommandContext) => void | Promise<void>;
+}
+declare class CommandRegistry {
+    private commands;
+    /** Active scopes in activation order ('global' is always index 0) */
+    private scopeStack;
+    private pendingSteps;
+    private pendingTimer;
+    private enabled;
+    register(command: WorkspaceCommand): Disposable$1;
+    /**
+     * Activate a scope (e.g. when a surface mounts or a task row gains
+     * focus). Re-activating moves it to the top of the priority stack.
+     */
+    activateScope(scope: CommandScope): Disposable$1;
+    isScopeActive(scope: CommandScope): boolean;
+    getActiveScopes(): CommandScope[];
+    /** Commands available right now (active scope + passing when()) */
+    getAvailableCommands(): WorkspaceCommand[];
+    getAllCommands(): WorkspaceCommand[];
+    /**
+     * Commands declared in any of the given scopes (passing `when()`),
+     * regardless of whether those scopes are currently active. Lets a
+     * context-aware command menu surface, say, the focused-task verbs even
+     * when its own input has stolen scope focus.
+     */
+    commandsForScopes(scopes: readonly CommandScope[]): WorkspaceCommand[];
+    getCommand(id: string): WorkspaceCommand | undefined;
+    runCommand(id: string): Promise<boolean>;
+    setEnabled(enabled: boolean): void;
+    /**
+     * Handle a keydown. Returns true when a command fired (or a chord step
+     * was consumed); callers should attach exactly one handler per window.
+     */
+    handleKeyDown(event: KeyboardEvent): boolean;
+    /** Format a binding for display ('Mod-K' → '⌘K' on Mac). */
+    formatForDisplay(binding: string): string;
+    clear(): void;
+    private clearPending;
+}
+declare function getCommandRegistry(): CommandRegistry;
+/**
+ * Install the global command handler on the window.
+ * Call once at app startup.
+ */
+declare function installCommandHandler(): () => void;
+
+/**
+ * Editor schema-skew guard for plugin contributions (exploration 0205).
+ *
+ * A plugin editor contribution whose TipTap extension is a Node or Mark changes
+ * the PERSISTED document schema. Under Yjs collaboration, if some collaborators
+ * have the plugin and others don't, ProseMirror silently drops the unknown
+ * content and the corruption syncs without any error. Behavior-only extensions
+ * (commands, keymaps, decorations, slash items) are skew-safe.
+ *
+ * This module classifies a plugin's editor contributions so the registry can
+ * warn loudly in development. It mirrors `@xnetjs/editor`'s extension-tiers
+ * classifier but lives here so the plugins package needs no editor dependency.
+ */
+
+interface EditorSchemaRisk {
+    /** The contribution id. */
+    id: string;
+    /** 'node' | 'mark' (the skew-sensitive kinds). */
+    kind: string;
+    /** The TipTap extension name. */
+    name: string;
+}
+/** True if the extension defines persisted document schema (a Node or Mark). */
+declare function isSchemaDefiningExtension(ext: {
+    type?: string;
+}): boolean;
+/**
+ * Of a plugin's editor contributions, return those that add persisted schema
+ * and therefore risk silent Yjs content loss across version skew. Empty array
+ * means the contributions are skew-safe.
+ */
+declare function findEditorSchemaRisks(contributions: readonly EditorContribution[]): EditorSchemaRisk[];
+/**
+ * Warn (in development) when a plugin's editor contributions add schema. Returns
+ * the detected risks so callers can also gate or surface them.
+ */
+declare function warnOnEditorSchemaRisks(pluginId: string, contributions: readonly EditorContribution[]): EditorSchemaRisk[];
+
+/**
+ * @xnetjs/plugins — the Connector primitive (exploration 0196).
+ *
+ * A Connector is xNet's answer to the agent-native CLI (Printing Press / OpenClaw):
+ * instead of giving the agent a credentialed shell, it syncs an external service
+ * into governed XNet nodes and exposes agent-callable tools over them. It is a
+ * `FeatureModule` subtype that bundles three things:
+ *
+ *   1. a `capabilities` manifest — `secrets` (held by the hub broker, never the
+ *      agent), `schemaWrite` (what it may materialize), `network` (where it may
+ *      reach);
+ *   2. a server-side `sync` adapter that pulls the external API into nodes; and
+ *   3. `agentTools` the model can call over the synced, policy-evaluated store.
+ *
+ * `defineConnector` produces the `FeatureModule` (so it installs, consents, and
+ * ships through the marketplace like any plugin) plus the sync spec and tools.
+ * The hub half is wired by convention under `<id>.sync` (see the hub
+ * `connectorSyncFeature`). The guards are enforced by composition — `guardStore`,
+ * `guardedFetch`, `scopedEnv`, the policy evaluator — not by new code here.
+ */
+
+/** How often a connector re-syncs. `manual` = only on explicit/agent trigger. */
+type ConnectorCadence = 'manual' | 'hourly' | 'daily' | {
+    everyMs: number;
+};
+/** The minimal node store surface a connector's `pull` writes through. */
+interface ConnectorStore {
+    create(options: {
+        schemaId: string;
+        properties: Record<string, unknown>;
+    }): Promise<{
+        id: string;
+        schemaId: string;
+    }>;
+    get(id: string): Promise<{
+        schemaId: string;
+    } | null>;
+    update(id: string, options: {
+        properties: Record<string, unknown>;
+    }): Promise<unknown>;
+}
+/** A `fetch`-like the connector reaches the network through (host-allowlisted). */
+type ConnectorFetch = (input: string | {
+    url: string;
+}, init?: unknown) => Promise<unknown>;
+/** Context handed to `pull`: scoped secrets, guarded fetch + store, target space. */
+interface ConnectorSyncContext {
+    /** Broker-scoped env — only the keys declared in `capabilities.secrets`. */
+    env: Record<string, string | undefined>;
+    /** Guarded fetch — egress limited to `capabilities.network`. */
+    fetch: ConnectorFetch;
+    /** Guarded store — writes limited to `capabilities.schemaWrite`, space-stamped. */
+    store: ConnectorStore;
+    /** The target Space id every synced node is scoped to (the cascade boundary). */
+    space: string;
+}
+interface ConnectorSyncResult {
+    /** Number of nodes written this run. */
+    written: number;
+    [key: string]: unknown;
+}
+interface ConnectorSyncSpec {
+    /** Schema IRIs this connector materializes (must be a subset of `schemaWrite`). */
+    schemas: string[];
+    /**
+     * The relation property each synced node carries the target Space in (default
+     * `space`). The runner stamps it so an author cannot forget — that stamp is
+     * what makes the space cascade (and thus cross-contamination protection) hold.
+     */
+    spaceProperty?: string;
+    /** Re-sync cadence (default `manual`). */
+    cadence?: ConnectorCadence;
+    /** Pull external data into nodes. Runs hub-side with scoped secrets. */
+    pull(ctx: ConnectorSyncContext): Promise<ConnectorSyncResult>;
+}
+interface ConnectorDefinition {
+    /** Reverse-domain id, e.g. `dev.xnet.connector.slack`. */
+    id: string;
+    /** Human-readable name. */
+    name: string;
+    /** Semantic version (default `0.1.0`). */
+    version?: string;
+    author?: string;
+    description?: string;
+    /** The capability surface — enforced, not advisory. `network` is required. */
+    capabilities: ModuleCapabilities & {
+        schemaWrite: string[];
+        network: string[];
+    };
+    /** Server-side sync adapter. */
+    sync: ConnectorSyncSpec;
+    /** Model-facing tools over the synced store. */
+    agentTools?: AgentToolContribution[];
+}
+/** The product of {@link defineConnector}: a module plus its runnable parts. */
+interface DefinedConnector {
+    /** The installable, consent-gated, marketplace-shippable feature module. */
+    module: FeatureModule;
+    /** The sync adapter (run by the hub `connectorSyncFeature`). */
+    sync: ConnectorSyncSpec;
+    /** The contributed agent tools. */
+    agentTools: AgentToolContribution[];
+    /** The original definition. */
+    definition: ConnectorDefinition;
+}
+declare class ConnectorDefinitionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Define a Connector. Validates the capability/sync coherence (every synced
+ * schema is writable; a network host is declared) and produces a `FeatureModule`
+ * whose `hub.featureId` points at the sync feature mounted under `<id>.sync`.
+ *
+ * @throws {ConnectorDefinitionError} when the definition is incoherent.
+ */
+declare function defineConnector(def: ConnectorDefinition): DefinedConnector;
+
+/**
+ * @xnetjs/plugins — plugin contributions as AI tools (exploration 0194 Phase 2).
+ *
+ * The AI agent can read/write the workspace (the `AiSurfaceService` tools), but
+ * until now it could not invoke a *plugin command*. This exposes opted-in
+ * commands as `AiToolDefinition`s with an `invoke`, so the agent's tool surface
+ * grows with installed plugins — composable, the way MCP made the 2026 ecosystem.
+ *
+ * Opt-in is explicit (`aiExposed: true`) and capability-scoped (`aiScopes`): a
+ * command the AI shouldn't touch simply never opts in, and a high-risk one is
+ * surfaced as such so the agent/consent layer can gate it.
+ */
+
+/** An `AiToolDefinition` that can actually be called. */
+type AiCallableTool = AiToolDefinition & {
+    invoke: (args: Record<string, unknown>) => Promise<AiToolCallResult>;
+};
+/**
+ * Wrap the opted-in plugin commands as capability-scoped, callable AI tools.
+ * Only commands with `aiExposed: true` are included — exposure is never implicit.
+ */
+declare function contributionsAsAiTools(commands: readonly CommandContribution[]): AiCallableTool[];
+
+/**
+ * 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;
+
+/**
+ * Local HTTP API Server
+ *
+ * Provides a REST API for external integrations (N8N, MCP, etc.) to interact
+ * with xNet data. Runs on localhost only (port 31415 by default).
+ *
+ * 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)
+ */
+interface NodeStoreAPI {
+    get(id: string): Promise<NodeData | null>;
+    list(options?: {
+        schemaId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<NodeData[]>;
+    query?(descriptor: NodeQueryDescriptor): Promise<NodeQueryResult>;
+    create(options: {
+        schemaId: string;
+        properties: Record<string, unknown>;
+    }): Promise<NodeData>;
+    update(id: string, options: {
+        properties: Record<string, unknown>;
+    }): Promise<NodeData>;
+    delete(id: string): Promise<void>;
+    subscribe(listener: (event: NodeChangeEventData) => void): () => void;
+}
+/**
+ * Schema registry interface (minimal subset needed by API)
+ */
+interface SchemaRegistryAPI {
+    getAllIRIs(): string[];
+    get(iri: string): Promise<SchemaData | null>;
+}
+/**
+ * Node data returned by API
+ */
+interface NodeData {
+    id: string;
+    schemaId: string;
+    properties: Record<string, unknown>;
+    deleted: boolean;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Schema data returned by API
+ */
+interface SchemaData {
+    iri: string;
+    name: string;
+    properties: Record<string, unknown>;
+}
+/**
+ * Node change event data
+ */
+interface NodeChangeEventData {
+    change: {
+        type: string;
+    };
+    node: NodeData | null;
+    isRemote: boolean;
+}
+/**
+ * API configuration
+ */
+interface LocalAPIConfig {
+    /** Port to listen on (default: 31415) */
+    port?: number;
+    /** Host to bind to (default: '127.0.0.1') */
+    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,
+     * or ['*'] to allow all origins (not recommended for production).
+     * Empty array or undefined disables CORS entirely.
+     */
+    allowedOrigins?: string[];
+    /** NodeStore instance */
+    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>;
+}
+
+/**
+ * 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[];
+    };
+};
+type AiDatabaseMutationApplyResult = {
+    applied: boolean;
+    databaseId: string;
+    planId: string;
+    baseRevision: string;
+    liveRevision: string;
+    appliedChangeIds: string[];
+    rolledBackChangeIds: string[];
+    validation: {
+        valid: boolean;
+        errors: string[];
+        warnings: string[];
+    };
+    auditEventId?: 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;
+
+/**
+ * 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;
+
+/**
+ * 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;
+}
+
+/**
+ * @xnetjs/plugins — connector sync runner (exploration 0196).
+ *
+ * Runs a connector's `pull` with the guardrails composed, so the *author* writes
+ * plain `store.create(...)` / `fetch(...)` and the *framework* guarantees:
+ *
+ *   - **egress containment** — `fetch` is `guardedFetch`, limited to the declared
+ *     `capabilities.network`;
+ *   - **schema-write containment** — `store` is `guardStore`, limited to the
+ *     declared `capabilities.schemaWrite`;
+ *   - **space scoping** — every created node is stamped with the target Space, so
+ *     the authorization cascade keeps one space's synced data invisible to agents
+ *     working in another (no cross-contamination);
+ *   - **budget** — writes are charged against the `connector` surface, separate
+ *     from the interactive agent's `localApi` budget, so a bulk backfill is
+ *     throttled rather than unbounded.
+ *
+ * Secret scoping is the hub's job: `mountFeatures` hands `pull` a `scopedEnv`, so
+ * this runner never sees (or needs) the full process env — keeping the dependency
+ * direction clean (no `@xnetjs/plugins` → `@xnetjs/hub` edge).
+ */
+
+declare class ConnectorSyncError extends Error {
+    constructor(message: string);
+}
+/** A node store with the methods the runner guards (create/get/update). */
+type GuardableConnectorStore = ConnectorStore;
+interface RunConnectorSyncPorts {
+    /** Broker-scoped env (the hub scopes it; tests pass a minimal object). */
+    env: Record<string, string | undefined>;
+    /** Underlying fetch — wrapped in `guardedFetch` before reaching `pull`. */
+    fetch: ConnectorFetch;
+    /** Underlying store — wrapped in `guardStore` + space-stamp before `pull`. */
+    store: GuardableConnectorStore;
+    /** Target Space id. Required unless `allowUnscoped` is set. */
+    space: string | null;
+    /** Write guardrail; defaults to a fresh `connector`-surface guardrail. */
+    guardrail?: McpWriteGuardrail;
+    /** Opt out of the space requirement (personal / intentionally unscoped sync). */
+    allowUnscoped?: boolean;
+}
+/**
+ * Run a connector's sync with all guards composed. The connector author's `pull`
+ * sees a guarded fetch + store and a target space; it cannot reach undeclared
+ * hosts, write undeclared schemas, leak across spaces, or exceed its budget.
+ *
+ * @throws {ConnectorSyncError} when a target space is required but missing.
+ */
+declare function runConnectorSync(def: ConnectorDefinition, ports: RunConnectorSyncPorts): Promise<ConnectorSyncResult>;
+
+/**
+ * @xnetjs/plugins — marketplace index + search (exploration 0192).
+ *
+ * The data layer behind the 0047 GitHub-backed registry: the shape of a
+ * `registry.json` entry, pure browse/search/sort over it, rating aggregation,
+ * and a `MarketplaceClient` whose network access is injected (a `fetchJson`
+ * port) so it is unit-testable without a server. The in-app Marketplace view
+ * renders on top of this; the view itself is app-side.
+ */
+
+/** A single entry in the marketplace index (`registry.json`). */
+interface MarketplaceEntry {
+    id: string;
+    name: string;
+    description: string;
+    version: string;
+    author: string;
+    /** Search keywords / tags. */
+    keywords?: string[];
+    /** Coarse category for filtering (`productivity`, `finance`, `social`, …). */
+    category?: string;
+    /** Capabilities the plugin requests (drives the consent preview). */
+    capabilities?: ModuleCapabilities;
+    /** URL the full manifest is fetched from at install. */
+    manifestUrl: string;
+    /** Lifetime install count (trust signal). */
+    installs?: number;
+    /** GitHub stars / community signal. */
+    stars?: number;
+    /** SPDX license id (exploration 0196) — shown as a badge; gated by CI policy. */
+    license?: string;
+    /** Monetization (exploration 0196). Absent = free. */
+    pricing?: PluginPricing;
+    /** Publisher identity for paid listings (exploration 0196). */
+    publisherDid?: string;
+    /** Provenance reference for verification (see `./provenance`). */
+    provenance?: {
+        sigstoreBundleUrl?: string;
+        sourceRepo?: string;
+        sourceCommit?: string;
+    };
+}
+/** How a marketplace listing is sorted. */
+type MarketplaceSort = 'relevance' | 'installs' | 'stars' | 'name';
+/** Filter an index by free-text query (name/description/keywords/author/category). */
+declare function searchMarketplace(index: readonly MarketplaceEntry[], query: string): MarketplaceEntry[];
+/** Sort a marketplace listing. `relevance` requires the originating `query`. */
+declare function sortMarketplace(entries: readonly MarketplaceEntry[], sort: MarketplaceSort, query?: string): MarketplaceEntry[];
+/** Filter by category (case-insensitive); empty/undefined category returns all. */
+declare function filterByCategory(entries: readonly MarketplaceEntry[], category: string | undefined): MarketplaceEntry[];
+/** A weighted signal about what the user works with (from workspace usage). */
+interface UsageSignal {
+    /** A category the user engages with (e.g. `finance`). */
+    category?: string;
+    /** A keyword the user engages with (e.g. `invoice`). */
+    keyword?: string;
+    /** Relative strength (default 1). */
+    weight?: number;
+}
+interface RecommendOptions {
+    /** Ids already installed — excluded from recommendations. */
+    installedIds?: readonly string[];
+    /** Cap the number of recommendations (default 5). */
+    limit?: number;
+}
+/**
+ * Recommend extensions from the marketplace index for a user, given weighted
+ * usage signals (category/keyword affinity). Excludes already-installed ids and
+ * ranks by match score, with install-count as a tiebreaker. Pure — the "AI
+ * brain" decides the signals; this turns them into a ranked shortlist.
+ */
+declare function recommendExtensions(index: readonly MarketplaceEntry[], signals: readonly UsageSignal[], options?: RecommendOptions): MarketplaceEntry[];
+/** A single rating (one node per rating; aggregated for display). */
+interface PluginRating {
+    pluginId: string;
+    /** 1–5 stars. */
+    stars: number;
+    authorDID: string;
+    review?: string;
+}
+interface RatingSummary {
+    count: number;
+    average: number;
+    /** Histogram indexed 1..5. */
+    histogram: Record<1 | 2 | 3 | 4 | 5, number>;
+}
+/** Aggregate ratings into a summary (rounds stars to 1..5, ignores invalid). */
+declare function aggregateRatings(ratings: readonly PluginRating[]): RatingSummary;
+/** Injected network port so the client is testable without a real fetch. */
+type FetchJson = <T>(url: string) => Promise<T>;
+interface MarketplaceClientOptions {
+    /** URL of the registry index (`registry.json`). */
+    indexUrl: string;
+    /** How to fetch JSON (defaults to `globalThis.fetch`). */
+    fetchJson?: FetchJson;
+}
+/**
+ * A thin client over the registry index: fetch once (cached), then browse/search
+ * in memory. The marketplace stays offline-friendly — the index is small JSON.
+ */
+declare class MarketplaceClient {
+    private readonly options;
+    private cache;
+    private readonly fetchJson;
+    constructor(options: MarketplaceClientOptions);
+    /** Fetch (and cache) the registry index. */
+    load(force?: boolean): Promise<MarketplaceEntry[]>;
+    /** Search + sort the index in one call. */
+    search(query: string, opts?: {
+        sort?: MarketplaceSort;
+        category?: string;
+    }): Promise<MarketplaceEntry[]>;
+}
+/** The provenance an install should pass to the registry (marketplace tier). */
+declare const MARKETPLACE_PROVENANCE: InstallProvenance;
+
+/**
+ * @xnetjs/plugins — connector artifacts + interop (exploration 0196).
+ *
+ * A Connector is governed *inside* xNet, but it should also be a good citizen of
+ * the wider CLI/MCP ecosystem. From one definition this emits:
+ *
+ *   - a `connectors`-category marketplace entry (so it ships like any plugin);
+ *   - per-tool descriptors for advertisement (what the user's own harness, e.g.
+ *     `xnet mcp serve`, exposes to Claude Code / Codex / OpenClaw);
+ *   - a per-connector `SKILL.md` fragment for external/files-first harnesses; and
+ *   - an `ImporterContribution`-shaped adapter, so a connector's sync doubles as
+ *     a one-shot importer (generalizing the dormant 0189 importers point).
+ *
+ * All pure — no I/O — so the marketplace publisher, the MCP server, and the CLI
+ * each consume what they need.
+ */
+
+/** The marketplace category every Connector lists under. */
+declare const CONNECTOR_CATEGORY = "connectors";
+/** A model-facing descriptor of one connector tool (for tool advertisement). */
+interface ConnectorToolDescriptor {
+    name: string;
+    description: string;
+    risk: string;
+}
+interface ConnectorArtifacts {
+    /** Tool descriptors the user's harness advertises (MCP `tools/list`-style). */
+    agentTools: ConnectorToolDescriptor[];
+    /** A per-connector SKILL.md fragment for external / files-first harnesses. */
+    skillMarkdown: string;
+    /** A `connectors`-category marketplace entry. */
+    marketplaceEntry: MarketplaceEntry;
+}
+/** Build a `connectors`-category marketplace entry from a connector. */
+declare function connectorMarketplaceEntry(connector: DefinedConnector, options?: {
+    manifestUrl?: string;
+}): MarketplaceEntry;
+/**
+ * Expose a connector's sync as an `ImporterContribution` — the connector's
+ * `pull` doubles as a one-shot importer for the source platform. The adapter is
+ * opaque to the importers registry (the import flow casts it), matching the 0189
+ * "defined now, consumed later" shape.
+ */
+declare function connectorAsImporter(connector: DefinedConnector): ImporterContribution;
+/**
+ * Emit the portable artifacts for a connector: tool descriptors, a SKILL.md
+ * fragment, and a marketplace entry. One definition → every surface.
+ */
+declare function emitConnectorArtifacts(connector: DefinedConnector, options?: {
+    manifestUrl?: string;
+}): ConnectorArtifacts;
+
+/**
+ * @xnetjs/plugins — capability consent (exploration 0192).
+ *
+ * Turns a `ModuleCapabilities` declaration into human-readable consent lines for
+ * the install dialog, and decides whether a given install even needs a consent
+ * prompt (wiring `requiresCapabilityReprompt` into the install flow). The React
+ * dialog is app-side; this is the headless logic it renders and obeys.
+ *
+ * Design note: a `*` (all-schemas) or raw-secret grant is rendered as `danger`
+ * so the UI can shout — the npm-permissions failure mode is consent fatigue, so
+ * broad grants must look different from narrow ones.
+ */
+
+/** A single human-readable line in the consent dialog. */
+interface ConsentLine {
+    /** Coarse icon hint for the UI (`edit`, `eye`, `globe`, `key`, `plug`). */
+    icon: 'edit' | 'eye' | 'globe' | 'key' | 'plug';
+    /** Human sentence, e.g. "Modify your Task data". */
+    text: string;
+    /** Whether this grant is broad/sensitive enough to warrant a warning. */
+    danger: boolean;
+}
+/** Short, human label for a schema IRI: `xnet://xnet.fyi/Task@1.0.0` → `Task`. */
+declare function shortSchemaName(iri: string): string;
+/** Describe a capability grant as consent lines (one per declared capability). */
+declare function describeCapabilities(caps: ModuleCapabilities | undefined): ConsentLine[];
+/** The decision the install path makes about consent for a given install. */
+interface ConsentDecision {
+    /** Provenance-derived trust tier this plugin will run at. */
+    tier: TrustTier;
+    /** Whether the user must be prompted before activation. */
+    needsPrompt: boolean;
+    /** The lines to show, if prompted. */
+    lines: ConsentLine[];
+    /** True if any requested grant is broad/sensitive. */
+    hasDanger: boolean;
+}
+/**
+ * Decide whether an install needs consent and what to show. `needsPrompt` is
+ * true only when provenance requires a re-prompt AND the plugin actually
+ * requests capabilities — a capability-free marketplace plugin still installs
+ * into the marketplace sandbox tier but has nothing to consent to.
+ */
+declare function evaluateInstallConsent(provenance: InstallProvenance, caps: ModuleCapabilities | undefined): ConsentDecision;
+
+/**
+ * @xnetjs/plugins — connector install gate (exploration 0196).
+ *
+ * Connectors flow through the same provenance→trust + consent machinery as any
+ * plugin, with one extra rule: **a connector that requests secrets can never be
+ * auto-trusted on `ai-generated` provenance.** "The model authored it" must not
+ * be sufficient to hand it a credential — a human promotes it (re-authoring or
+ * publishing it, which changes the provenance) before it can hold a token.
+ */
+
+interface ConnectorInstallGate {
+    /** The normal capability-consent decision (lines, danger, reprompt). */
+    consent: ConsentDecision;
+    /** Whether the connector may install after the normal consent flow. */
+    installable: boolean;
+    /** Why it is not installable (requires manual promotion), when blocked. */
+    blockedReason?: string;
+}
+/**
+ * Evaluate whether a connector may install given its provenance + capabilities.
+ * Returns the consent decision plus a hard gate that blocks secret-holding
+ * AI-generated connectors from auto-install.
+ */
+declare function evaluateConnectorInstall(provenance: InstallProvenance, capabilities: ModuleCapabilities | undefined): ConnectorInstallGate;
+
+/**
+ * @xnetjs/plugins — wrap an external CLI as a Connector (exploration 0196).
+ *
+ * The interop play: an existing agent-native CLI (e.g. a Printing Press tool)
+ * becomes a governed Connector by running it and mapping its output into nodes.
+ * The wrapper governs the **output mapping** — the synced schema, the target
+ * Space, the write budget — so the agent reads policy-evaluated nodes instead of
+ * the raw CLI.
+ *
+ * Honest caveat: the wrapped CLI is a subprocess that reaches the network itself,
+ * so its *egress* is NOT enforced by `guardedFetch`. `network` here is for the
+ * consent/marketplace display; a wrapped CLI should be a trusted, clearly-labeled
+ * tier. The `runCli` port is injected (no `@xnetjs/devkit` edge here), so the
+ * caller decides how the CLI actually runs (and can sandbox it).
+ */
+
+interface WrapCliConnectorOptions {
+    /** Reverse-domain id, e.g. `dev.acme.connector.wikipedia-cli`. */
+    id: string;
+    name: string;
+    version?: string;
+    author?: string;
+    description?: string;
+    /** The schema each parsed record is materialized as. */
+    schema: string;
+    /** Hosts the CLI reaches — for display only (subprocess egress is not enforced). */
+    network: string[];
+    /** Secrets the CLI needs (held by the hub broker). */
+    secrets?: string[];
+    /** The Space relation property to stamp (default `space`). */
+    spaceProperty?: string;
+    /** Run the external CLI and return its stdout. Injected (e.g. a CommandRunner). */
+    runCli: () => Promise<string>;
+    /** Parse the CLI stdout into records; each becomes one node's properties. */
+    parse: (stdout: string) => Array<Record<string, unknown>>;
+    /** Optional agent tools over the synced nodes. */
+    agentTools?: AgentToolContribution[];
+}
+/**
+ * Produce a governed Connector that runs an external CLI and maps its output
+ * into nodes. The CLI runs once per sync; each parsed record is written through
+ * the guarded, space-stamped, budget-charged store.
+ */
+declare function wrapCliConnector(options: WrapCliConnectorOptions): DefinedConnector;
+
+/**
+ * @xnetjs/plugins — the Slack migration connector (exploration 0198).
+ *
+ * "Switch from Slack to XNet and bring my data with me." This is the Half-1
+ * answer from exploration 0198: a {@link defineConnector} that pulls a Slack
+ * workspace's channels and message history into XNet's native `Channel` and
+ * `ChatMessage` nodes, through the guarded connector store (egress-contained to
+ * `slack.com`, space-stamped, budget-charged). The Slack token lives in the hub
+ * broker and never reaches the agent — it only ever sees the synced nodes.
+ *
+ * Message bodies are translated to GitHub-flavored markdown via
+ * `@xnetjs/slack-compat` (Block Kit first, then `mrkdwn`), so they render
+ * natively in XNet chat. Pagination, DMs, files and reactions are deferred (see
+ * the exploration's checklist).
+ */
+
+/** Default reverse-domain id; matches the worked example in the connector docs. */
+declare const SLACK_CONNECTOR_ID = "dev.xnet.connector.slack";
+declare const CHANNEL_SCHEMA = "xnet://xnet.fyi/Channel@1.0.0";
+declare const CHAT_MESSAGE_SCHEMA = "xnet://xnet.fyi/ChatMessage@1.0.0";
+interface SlackConnectorOptions {
+    /** Override the connector id (default {@link SLACK_CONNECTOR_ID}). */
+    id?: string;
+    /**
+     * Backing for the `slack_search_messages` agent tool. When provided, the
+     * connector contributes a model-facing search over the imported messages;
+     * when omitted, no agent tool is contributed (pull-only migration).
+     */
+    search?: (args: {
+        query: string;
+    }) => unknown | Promise<unknown>;
+}
+/**
+ * Build the Slack migration connector. The `pull` imports channels +
+ * history into `Channel`/`ChatMessage` nodes via the guarded store.
+ */
+declare function buildSlackConnector(options?: SlackConnectorOptions): DefinedConnector;
+
+/**
+ * @xnetjs/plugins — the RSS / Atom connector (exploration 0213).
+ *
+ * The zero-auth, hobbyist-loved integration: poll a feed URL and materialize
+ * each entry as a governed `FeedItem` node through the guarded connector store.
+ * The parser is dependency-free (a small, defensive RSS+Atom extractor) so the
+ * package keeps its no-runtime-deps posture. `guid` carries the feed entry's
+ * stable id so a host can de-duplicate across polls.
+ */
+
+declare const RSS_CONNECTOR_ID = "dev.xnet.connector.rss";
+declare const FEED_ITEM_SCHEMA = "xnet://xnet.fyi/FeedItem@1.0.0";
+/** One normalized feed entry (RSS `<item>` or Atom `<entry>`). */
+interface FeedEntry {
+    title: string;
+    link?: string;
+    guid?: string;
+    summary?: string;
+    publishedAt?: number;
+}
+/**
+ * Parse an RSS or Atom document into normalized entries. Defensive by design:
+ * malformed or unknown markup yields fewer entries rather than throwing, and the
+ * scan is linear so a hostile feed cannot pin the event loop.
+ */
+declare function parseFeed(xml: string): FeedEntry[];
+interface RssConnectorOptions {
+    /** The RSS/Atom feed URL to poll. Its host becomes the sole `network` grant. */
+    feedUrl: string;
+    /** Override the connector id (default {@link RSS_CONNECTOR_ID}). */
+    id?: string;
+    /** The `Feed` node id every item links back to (optional). */
+    feedNodeId?: string;
+    /** Backing for an optional `rss_search_items` agent tool. */
+    search?: (args: {
+        query: string;
+    }) => unknown | Promise<unknown>;
+}
+/**
+ * Build the RSS/Atom connector. The `pull` polls one feed URL and materializes
+ * its entries into `FeedItem` nodes via the guarded store.
+ */
+declare function buildRssConnector(options: RssConnectorOptions): DefinedConnector;
+
+/**
+ * @xnetjs/plugins — API pull connectors: GitHub, Notion, Airtable
+ * (exploration 0213).
+ *
+ * The API-key tier of the integration catalog. Each polls a service's REST API
+ * and materializes objects into the generic, governed `ExternalItem` node
+ * (source / kind / externalId / title / url / status / raw), through the guarded
+ * connector store — the credential stays in the hub broker; the agent only ever
+ * sees the synced nodes. Schema IRIs are inlined (matching `slack-migration`) so
+ * the package keeps no `@xnetjs/data` dependency.
+ *
+ * Robustness (0213 review): each pull (1) requires its declared secret to be
+ * present (a misconfiguration is a loud error, not a silent `Bearer ` request),
+ * (2) throws on a non-2xx response instead of returning `{ written: 0 }`, and
+ * (3) follows the provider's pagination so it doesn't silently cap at one page.
+ */
+
+declare const EXTERNAL_ITEM_SCHEMA = "xnet://xnet.fyi/ExternalItem@1.0.0";
+interface ApiConnectorBaseOptions {
+    id?: string;
+    search?: (args: {
+        query: string;
+    }) => unknown | Promise<unknown>;
+}
+declare const GITHUB_CONNECTOR_ID = "dev.xnet.connector.github";
+interface GithubConnectorOptions extends ApiConnectorBaseOptions {
+    /** Repository owner (user or org). */
+    owner: string;
+    /** Repository name. */
+    repo: string;
+}
+/**
+ * Build the GitHub connector. Imports a repo's issues and pull requests
+ * (`state=all`, all pages) into `ExternalItem` nodes via the GitHub REST API
+ * (`GITHUB_TOKEN`).
+ */
+declare function buildGithubConnector(options: GithubConnectorOptions): DefinedConnector;
+declare const NOTION_CONNECTOR_ID = "dev.xnet.connector.notion";
+type NotionConnectorOptions = ApiConnectorBaseOptions;
+/**
+ * Build the Notion connector. Imports pages the integration token can see (via
+ * `/v1/search`, following `has_more`) into `ExternalItem` nodes (`NOTION_TOKEN`).
+ */
+declare function buildNotionConnector(options?: NotionConnectorOptions): DefinedConnector;
+declare const AIRTABLE_CONNECTOR_ID = "dev.xnet.connector.airtable";
+interface AirtableConnectorOptions extends ApiConnectorBaseOptions {
+    /** The Airtable base id (`app...`). */
+    baseId: string;
+    /** The table id or name. */
+    tableId: string;
+}
+/**
+ * Build the Airtable connector. Imports a table's records (following the
+ * `offset` cursor) into `ExternalItem` nodes, preserving each record's fields in
+ * `raw` (`AIRTABLE_TOKEN`).
+ */
+declare function buildAirtableConnector(options: AirtableConnectorOptions): DefinedConnector;
+declare const LINEAR_CONNECTOR_ID = "dev.xnet.connector.linear";
+type LinearConnectorOptions = ApiConnectorBaseOptions;
+/**
+ * Build the Linear connector. Imports issues via Linear's GraphQL API (following
+ * the `pageInfo` cursor) into `ExternalItem` nodes (`LINEAR_API_KEY`). Personal
+ * API keys go in the `Authorization` header verbatim (no `Bearer` prefix).
+ */
+declare function buildLinearConnector(options?: LinearConnectorOptions): DefinedConnector;
+
+/**
+ * @xnetjs/plugins — network endowment (exploration 0192).
+ *
+ * The capability guard ({@link ../ecosystem/capability-guard}) closes the
+ * `schemaWrite` hole at the store boundary. This closes the `network` hole at
+ * the fetch boundary: a plugin that wants to reach the network gets a
+ * `guardedFetch` whose every request is checked against its declared `network`
+ * allowlist (`isNetworkAllowed`), so a plugin can only talk to the hosts it
+ * declared — and a plugin that declared none gets no egress at all.
+ *
+ * Like `guardStore`, this is the one handle a plugin should receive instead of
+ * the ambient `fetch`; the host injects it as the `network` endowment.
+ */
+
+/** The subset of the `fetch` signature we wrap (kept structural, no DOM types). */
+type FetchLike = (input: string | {
+    url: string;
+}, init?: unknown) => Promise<unknown>;
+/**
+ * Wrap a `fetch` implementation so every request host is checked against the
+ * plugin's declared `network` capability. Throws `CapabilityError` before the
+ * request leaves if the host isn't allowed. A plugin with no `network` grant
+ * can reach nothing (closed by default) — the wrapper still returns, but every
+ * call throws until a host is declared.
+ *
+ * @param caps the plugin's declared capability grant
+ * @param pluginId for error attribution
+ * @param fetchImpl the underlying fetch (defaults to `globalThis.fetch`)
+ */
+declare function guardedFetch(caps: ModuleCapabilities | undefined, pluginId: string, fetchImpl?: FetchLike): FetchLike;
+
+/**
+ * @xnetjs/plugins — the outbound Action primitive (exploration 0213).
+ *
+ * Connectors *pull* an external service into nodes; an Action is the reverse —
+ * "when something happens in xNet, reach out." It is the other half of the
+ * Zapier/IFTTT story (post to Discord on task close, send an email, hit a
+ * webhook) and the symmetric twin of {@link ../connectors/define-connector}:
+ *
+ *   1. a `capabilities` manifest — `network` (where it may POST, closed by
+ *      default) and `secrets` (held by the hub broker, e.g. a Discord webhook
+ *      URL or a bot token);
+ *   2. a `trigger` declaring what fires it (a node change on given schemas, a
+ *      schedule, or manual); and
+ *   3. a `dispatch(event, ctx)` that does the outbound call through a guarded,
+ *      SSRF-checked `fetch`.
+ *
+ * Like a Connector it produces a `FeatureModule` (so it installs, consents, and
+ * ships through the marketplace), with the hub half wired by convention under
+ * `<id>.trigger`. The guards are enforced by composition in the action runner
+ * (see {@link ./runner}); this module is just the shape + validation.
+ */
+
+/** What fires an action. */
+type ActionTrigger = {
+    kind: 'schema-change';
+    schemas: string[];
+} | {
+    kind: 'schedule';
+    cadence: ConnectorCadence;
+} | {
+    kind: 'manual';
+};
+/** The change that triggered a dispatch (schema-change triggers carry a node). */
+interface ActionEvent {
+    trigger: 'schema-change' | 'schedule' | 'manual';
+    /** Change kind for schema-change events. */
+    change?: 'create' | 'update' | 'delete';
+    /** The affected node for schema-change events. */
+    node?: {
+        id: string;
+        schemaId: string;
+        properties?: Record<string, unknown>;
+    };
+}
+/** Context handed to `dispatch`: scoped secrets + a guarded, SSRF-checked fetch. */
+interface ActionContext {
+    /** Broker-scoped env — only the keys declared in `capabilities.secrets`. */
+    env: Record<string, string | undefined>;
+    /** Guarded fetch — egress limited to `capabilities.network`, SSRF-checked. */
+    fetch: FetchLike;
+}
+interface ActionDefinition {
+    /** Reverse-domain id, e.g. `dev.xnet.action.discord`. */
+    id: string;
+    name: string;
+    version?: string;
+    author?: string;
+    description?: string;
+    /** Capability surface — `network` is required (closed by default). */
+    capabilities: ModuleCapabilities & {
+        network: string[];
+    };
+    /** What fires this action. */
+    trigger: ActionTrigger;
+    /** Perform the outbound call. Runs hub-side with scoped secrets. */
+    dispatch(event: ActionEvent, ctx: ActionContext): Promise<void>;
+    /** Optional model-facing tools (e.g. a manual "send now"). */
+    agentTools?: AgentToolContribution[];
+}
+/** The product of {@link defineAction}. */
+interface DefinedAction {
+    module: FeatureModule;
+    trigger: ActionTrigger;
+    dispatch: ActionDefinition['dispatch'];
+    agentTools: AgentToolContribution[];
+    definition: ActionDefinition;
+}
+declare class ActionDefinitionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Whether `action`'s trigger should fire for `event`. The "when X happens"
+ * decision, kept pure so a host can fan an event out to matching actions.
  */
-declare function getShortcutManager(): ShortcutManager;
+declare function shouldDispatch(trigger: ActionTrigger, event: ActionEvent): boolean;
 /**
- * Install the global shortcut manager on the window.
- * Call this once at app startup.
+ * Define an outbound Action. Validates the capability/trigger coherence (a
+ * network host is declared; a schema-change trigger lists schemas) and produces
+ * a `FeatureModule` whose `hub.featureId` points at `<id>.trigger`.
+ *
+ * @throws {ActionDefinitionError} when the definition is incoherent.
  */
-declare function installShortcutHandler(): () => void;
+declare function defineAction(def: ActionDefinition): DefinedAction;
+
+/**
+ * @xnetjs/plugins — outbound action runner (exploration 0213).
+ *
+ * Runs an action's `dispatch` with the guards composed, so the *author* writes a
+ * plain `fetch(...)` and the *framework* guarantees:
+ *
+ *   - **egress containment** — `fetch` is `guardedFetch`, limited to the declared
+ *     `capabilities.network`;
+ *   - **SSRF protection** — every request URL is `assertPublicUrl`-checked, so a
+ *     user-configured target cannot reach localhost, RFC-1918, or cloud metadata
+ *     even if the host was allowlisted via the configured URL.
+ *
+ * Secret scoping is the hub's job (a `scopedEnv` is passed in), keeping the
+ * dependency direction clean (no `@xnetjs/plugins` → `@xnetjs/hub` edge).
+ */
+
+declare class ActionDispatchError extends Error {
+    constructor(message: string);
+}
+interface RunActionPorts {
+    /** Broker-scoped env (the hub scopes it; tests pass a minimal object). */
+    env: Record<string, string | undefined>;
+    /** Underlying fetch — wrapped (network allowlist + SSRF) before `dispatch`. */
+    fetch: FetchLike;
+}
+/**
+ * Wrap a fetch so every outbound action request is (1) within the declared
+ * `network` allowlist and (2) not pointed at a non-public host (SSRF).
+ */
+declare function guardedActionFetch(def: Pick<ActionDefinition, 'id' | 'capabilities'>, fetchImpl: FetchLike): FetchLike;
+/**
+ * Run one action's `dispatch` with the guards composed. The author never sees
+ * the raw fetch or the full env.
+ */
+declare function runAction(action: DefinedAction, event: ActionEvent, ports: RunActionPorts): Promise<void>;
+
+/**
+ * @xnetjs/plugins — SSRF guard for outbound actions (exploration 0213).
+ *
+ * Outbound actions POST to URLs that may be user-configured (a generic
+ * webhook-out target). Even when the host is "allowlisted" (the action derived
+ * its `network` grant from the configured URL), a user could point it at an
+ * internal target — `http://169.254.169.254/` (cloud metadata), `localhost`, a
+ * private RFC-1918 range — to exfiltrate credentials or reach internal
+ * services. {@link assertPublicUrl} rejects those before the request leaves.
+ *
+ * The literal-host check itself lives in `@xnetjs/core`; this module keeps the
+ * action-specific {@link ActionSsrfError} contract that callers/tests depend on.
+ */
+declare class ActionSsrfError extends Error {
+    readonly url: string;
+    constructor(message: string, url: string);
+}
+/**
+ * Throw {@link ActionSsrfError} unless `rawUrl` is a plausibly-public HTTP(S)
+ * endpoint: rejects non-http(s) schemes, localhost, `.local`/`.internal`
+ * suffixes, the cloud metadata host, and private/loopback/link-local IP
+ * literals (v4 and v6).
+ */
+declare function assertPublicUrl(rawUrl: string): void;
+
+/**
+ * @xnetjs/plugins — first-party outbound actions (exploration 0213).
+ *
+ * The Top-5/Top-10 notification sinks built on {@link defineAction}: Discord and
+ * Slack incoming webhooks, Telegram bots, transactional email (Resend), and a
+ * generic webhook-out that bridges Zapier/Make/n8n. Each reads its credential
+ * from the broker-scoped env, renders the triggering event to a message, and
+ * POSTs through the guarded, SSRF-checked fetch. Hosts are declared at build
+ * time so egress stays closed-by-default; the generic webhook-out locks its
+ * `network` grant to the configured URL's host.
+ */
+
+/** A compact, human-readable summary of the triggering event. */
+declare function renderEvent(event: ActionEvent): string;
+interface BaseActionOptions {
+    /** Override the connector-style id. */
+    id?: string;
+    /** What fires the action (default: manual). */
+    trigger?: ActionTrigger;
+    /** Render the event to a message (default {@link renderEvent}). */
+    render?: (event: ActionEvent) => string;
+}
+/** Discord: POST `{ content }` to an incoming-webhook URL (`DISCORD_WEBHOOK_URL`). */
+declare function buildDiscordAction(options?: BaseActionOptions): DefinedAction;
+/** Slack: POST `{ text }` to an incoming-webhook URL (`SLACK_WEBHOOK_URL`). */
+declare function buildSlackWebhookAction(options?: BaseActionOptions): DefinedAction;
+/** Telegram: send a message via the Bot API (`TELEGRAM_BOT_TOKEN`/`TELEGRAM_CHAT_ID`). */
+declare function buildTelegramAction(options?: BaseActionOptions): DefinedAction;
+interface EmailActionOptions extends BaseActionOptions {
+    /** Verified sender, e.g. `xNet <alerts@example.com>`. */
+    from: string;
+    /** Recipient address(es). */
+    to: string | string[];
+    /** Subject line (default: a short event summary). */
+    subject?: string;
+}
+/** Email (Resend): send a transactional email (`RESEND_API_KEY`). */
+declare function buildEmailAction(options: EmailActionOptions): DefinedAction;
+interface WebhookOutOptions extends BaseActionOptions {
+    /** The destination URL. Its host becomes the action's sole `network` grant. */
+    url: string;
+    /** Transform the event into the POST body (default: the event itself). */
+    transform?: (event: ActionEvent) => unknown;
+    /** Extra request headers. */
+    headers?: Record<string, string>;
+}
+/**
+ * Generic webhook-out: POST each triggering event as JSON to a configured URL —
+ * the escape hatch that bridges Zapier/Make/n8n/IFTTT. The `network` grant is
+ * locked to the URL's host (and the SSRF guard still blocks internal targets).
+ */
+declare function buildWebhookOutAction(options: WebhookOutOptions): DefinedAction;
 
 /**
  * PluginRegistry - Central coordinator for plugin lifecycle
@@ -570,10 +2897,49 @@ interface RegisteredPlugin {
     status: PluginStatus;
     context?: ExtensionContext;
     error?: Error;
+    /** Where this plugin was installed from — derives its trust tier (0192). */
+    provenance?: InstallProvenance;
+    /** Provenance-derived execution trust tier (0192). */
+    trustTier?: TrustTier;
+}
+/**
+ * Result of a paid-plugin license check (exploration 0196). The host wires this
+ * to `@xnetjs/licenses`' `checkLicenseFor`; the plugin package stays free of a
+ * hard dependency on the license verifier.
+ */
+interface LicenseCheckResult {
+    /** `true` if the buyer holds a valid license for this plugin. */
+    ok: boolean;
+    /** Why it failed (`no-license`, `expired`, `bad-signature`, …) — surfaced to UI. */
+    reason?: string;
+}
+/** Options for {@link PluginRegistry.install} (all optional, back-compatible). */
+interface InstallOptions {
+    /** Where the plugin came from. Drives trust tier + consent. Default `imported`. */
+    provenance?: InstallProvenance;
+    /** Host app version, for the `xnetVersion` compatibility gate. Skipped if absent. */
+    hostVersion?: string;
+    /**
+     * Consent callback. Called only when provenance requires a re-prompt and the
+     * plugin actually requests capabilities. Return `false` to abort the install.
+     */
+    onConsent?: (decision: ConsentDecision) => boolean | Promise<boolean>;
+    /**
+     * Paid-license callback (exploration 0196). Called only when the manifest's
+     * `pricing` is non-free. Return `{ ok: false }` to block the install with a
+     * {@link LicenseRequiredError}. Absent ⇒ paid plugins are blocked (fail-closed).
+     */
+    checkLicense?: (manifest: XNetExtension) => LicenseCheckResult | Promise<LicenseCheckResult>;
 }
 declare class PluginError extends Error {
     constructor(message: string);
 }
+/** Thrown when a paid plugin is installed without a valid license (0196). */
+declare class LicenseRequiredError extends PluginError {
+    readonly pluginId: string;
+    readonly reason: string;
+    constructor(pluginId: string, reason: string);
+}
 /**
  * Manages plugin lifecycle: install, activate, deactivate, uninstall
  */
@@ -586,9 +2952,15 @@ declare class PluginRegistry {
     private listeners;
     constructor(store: NodeStore, platform: Platform);
     /**
-     * Install and activate a plugin
+     * Install and activate a plugin.
+     *
+     * Beyond manifest/platform validation, install runs the 0192 trust gates:
+     * host-version compatibility, dependency resolution, and (for non-local
+     * provenance) capability consent. Provenance derives the plugin's trust tier.
      */
-    install(manifest: XNetExtension): Promise<void>;
+    install(manifest: XNetExtension, options?: InstallOptions): Promise<void>;
+    /** Dependencies of `manifest` not satisfied by currently installed plugins. */
+    private missingDependencies;
     /**
      * Activate an installed plugin
      */
@@ -649,6 +3021,530 @@ declare class PluginRegistry {
     loadFromStore(): Promise<void>;
 }
 
+/**
+ * @xnetjs/plugins — capability enforcement (exploration 0192).
+ *
+ * 0189 added `ModuleCapabilities` (`schemaWrite`/`schemaRead`/`network`/…) as a
+ * *declaration*. This module makes the declaration load-bearing: it turns the
+ * declared grant into runtime gates.
+ *
+ * The enforcement point is the `NodeStore` handle a plugin receives in its
+ * `ExtensionContext`. Plugins call `ctx.store.create/update/delete` directly, so
+ * wrapping that handle is the one choke point a plugin cannot route around. We
+ * wrap with a `Proxy` (rather than re-implementing the store) so the guard keeps
+ * working as `NodeStore` grows methods — only `create`/`update`/`delete`/`get`/
+ * `list` are intercepted; everything else passes straight through.
+ *
+ * A grant with neither `schemaWrite` nor `schemaRead` is unconstrained (the guard
+ * returns the store untouched) — first-party/host code is meant to be unguarded.
+ */
+
+/** Thrown when a plugin tries to act outside its declared capability grant. */
+declare class CapabilityError extends Error {
+    readonly pluginId: string;
+    readonly capability: 'schemaWrite' | 'schemaRead' | 'network';
+    readonly target: string;
+    constructor(message: string, pluginId: string, capability: 'schemaWrite' | 'schemaRead' | 'network', target: string);
+}
+/**
+ * Match a schema IRI against a capability pattern. Supports:
+ * - exact: `xnet://xnet.fyi/Task@1.0.0`
+ * - all: `*`
+ * - version wildcard: `xnet://xnet.fyi/Task@*` (any version of Task)
+ * - prefix wildcard: `xnet://xnet.fyi/*` (any schema under an authority)
+ */
+declare function matchSchemaIri(pattern: string, iri: string): boolean;
+/** Whether the grant permits writing the given schema IRI. */
+declare function isSchemaWriteAllowed(caps: ModuleCapabilities | undefined, iri: string): boolean;
+/**
+ * Whether the grant permits reading the given schema IRI. A grant that declares
+ * no `schemaRead` does not restrict reads (reads are lower risk than writes;
+ * restricting them is opt-in by declaring `schemaRead`).
+ */
+declare function isSchemaReadAllowed(caps: ModuleCapabilities | undefined, iri: string): boolean;
+/**
+ * Whether the grant permits a network request to the given URL/host. A
+ * `network` entry may be an exact host (`api.stripe.com`) or a leading-dot
+ * suffix (`.stripe.com`, matching any subdomain). No declared `network` → no
+ * egress permitted (closed by default).
+ */
+declare function isNetworkAllowed(caps: ModuleCapabilities | undefined, urlOrHost: string): boolean;
+/** Assert a schema write is permitted, or throw {@link CapabilityError}. */
+declare function assertSchemaWrite(caps: ModuleCapabilities | undefined, iri: string, pluginId: string): void;
+/** Assert a network request is permitted, or throw {@link CapabilityError}. */
+declare function assertNetwork(caps: ModuleCapabilities | undefined, urlOrHost: string, pluginId: string): void;
+/**
+ * Wrap a NodeStore so writes are checked against the plugin's grant. Returns the
+ * store unchanged when the grant constrains nothing. Generic over the concrete
+ * store type so callers keep their `NodeStore` typing.
+ */
+declare function guardStore<T extends object>(store: T, caps: ModuleCapabilities | undefined, pluginId: string): T;
+
+/**
+ * @xnetjs/plugins — version compatibility (exploration 0192).
+ *
+ * A tiny, dependency-free semver subset — enough to gate plugin installs on the
+ * host's `xnetVersion` and to detect available updates. We deliberately avoid
+ * pulling in `semver` (a node-centric dep) for what is a handful of comparisons;
+ * the manifest already only accepts `\d+\.\d+\.\d+`-shaped versions.
+ *
+ * Supported range syntax: `*` / `x` (any), exact `1.2.3`, `>=1.2.3`, `>1.2.3`,
+ * `<=1.2.3`, `<1.2.3`, caret `^1.2.3`, tilde `~1.2.3`. Pre-release/build
+ * metadata is ignored (compared on major.minor.patch only).
+ */
+interface SemVer {
+    major: number;
+    minor: number;
+    patch: number;
+}
+/** Parse `1.2.3` (ignoring any `-pre`/`+build` suffix). Returns null if invalid. */
+declare function parseVersion(input: string): SemVer | null;
+/** Compare two versions: negative if a<b, 0 if equal, positive if a>b. */
+declare function compareVersions(a: SemVer, b: SemVer): number;
+/**
+ * Whether `version` satisfies `range`. Unknown/unparseable ranges are treated as
+ * "any" (`true`) so a missing `xnetVersion` never blocks an install; an explicit
+ * but malformed bound also fails open by design (we cannot prove incompatibility).
+ */
+declare function satisfiesRange(version: string, range: string): boolean;
+/**
+ * Whether a plugin declaring `requiredHostRange` (its `xnetVersion`) is
+ * compatible with `hostVersion`. A plugin with no declared requirement is
+ * always compatible.
+ */
+declare function isHostCompatible(requiredHostRange: string | undefined, hostVersion: string): boolean;
+/**
+ * Whether `available` is a newer version than `installed` (a real update is
+ * offerable). Returns false when either side is unparseable.
+ */
+declare function hasUpdate(installed: string, available: string): boolean;
+
+/**
+ * @xnetjs/plugins — inter-plugin dependencies (exploration 0192).
+ *
+ * A plugin may declare `dependencies: { '<pluginId>': '<versionRange>' }` in its
+ * manifest. These helpers resolve a safe install order (topological sort),
+ * detect cycles, and report missing/incompatible dependencies — the pure logic
+ * an installer runs before activating a set of plugins.
+ *
+ * Kept structural (operates on a minimal `{ id, version, dependencies }` shape)
+ * so it works for `XNetExtension` and `FeatureModule` alike.
+ */
+/** The minimal manifest shape the dependency resolver needs. */
+interface DependencyNode {
+    id: string;
+    version: string;
+    dependencies?: Record<string, string>;
+}
+/** A dependency that is absent or version-incompatible among installed plugins. */
+interface MissingDependency {
+    /** The plugin that declares the requirement. */
+    dependent: string;
+    /** The required plugin id. */
+    required: string;
+    /** The required version range. */
+    range: string;
+    /** Why it is unsatisfied. */
+    reason: 'not-installed' | 'version-mismatch';
+    /** The installed version, when present but mismatched. */
+    installedVersion?: string;
+}
+/**
+ * Report dependencies of `target` that are not satisfied by `installed`.
+ * Satisfied = a plugin with the required id is installed AND its version
+ * satisfies the declared range.
+ */
+declare function findMissingDependencies(target: DependencyNode, installed: readonly DependencyNode[]): MissingDependency[];
+/** Thrown when a dependency graph contains a cycle. */
+declare class DependencyCycleError extends Error {
+    readonly cycle: string[];
+    constructor(cycle: string[]);
+}
+/**
+ * Return the ids in a safe install order (dependencies before dependents).
+ * Only edges *within the provided set* are ordered; dependencies on plugins not
+ * in the set are ignored here (use {@link findMissingDependencies} for those).
+ *
+ * @throws {DependencyCycleError} if the graph cannot be linearised.
+ */
+declare function resolveInstallOrder(nodes: readonly DependencyNode[]): string[];
+
+/**
+ * @xnetjs/plugins — supply-chain provenance verification (exploration 0192).
+ *
+ * The 2025–26 marketplace-malware wave (GlassWorm, OctoRAT, typosquats) taught
+ * the field one thing: "Verified Publisher" badges verify domain ownership, not
+ * code safety. The answer the JS ecosystem converged on is Sigstore-style
+ * **provenance** — a keyless attestation that a package was built from a known
+ * source by a known builder, logged in a transparency ledger (Rekor).
+ *
+ * This module defines the verification *contract* and a **fail-closed** default.
+ * The actual Sigstore bundle verification (cosign/rekor) is a pluggable
+ * `ProvenanceVerifier` — wired in where the crypto deps are acceptable
+ * (publishing CI / desktop). The substrate is safe by default: with no verifier,
+ * everything is reported `unverified`, and the install UI decides what to do
+ * with that (warn / block) — it never silently treats unsigned code as trusted.
+ */
+/** A provenance attestation attached to a marketplace package. */
+interface Provenance {
+    /** The Sigstore bundle (or a URL to it). */
+    sigstoreBundle?: string;
+    /** Rekor transparency-log index, if logged. */
+    rekorLogIndex?: number;
+    /** DID/identity of the builder (CI workflow identity). */
+    builderDID?: string;
+    /** Source repository the artifact was built from. */
+    sourceRepo?: string;
+    /** Source commit SHA. */
+    sourceCommit?: string;
+    /** SHA-256 digest of the manifest/artifact being attested. */
+    artifactDigest?: string;
+}
+/** The outcome of verifying provenance for an artifact. */
+interface ProvenanceResult {
+    /** True only when a verifier cryptographically confirmed the attestation. */
+    verified: boolean;
+    /** Why verification failed or what could not be confirmed. */
+    reason?: string;
+    /** Source repo, when confirmed. */
+    sourceRepo?: string;
+    /** Builder identity, when confirmed. */
+    builderDID?: string;
+}
+/** The input to a verification: the attestation plus the artifact it covers. */
+interface VerifyProvenanceInput {
+    provenance?: Provenance;
+    /** SHA-256 digest computed locally over the fetched manifest/artifact. */
+    artifactDigest: string;
+}
+/** A pluggable verifier (cosign/rekor under the hood). */
+interface ProvenanceVerifier {
+    verify(input: VerifyProvenanceInput): Promise<ProvenanceResult>;
+}
+/**
+ * The default verifier: **fails closed**. Absent a real cryptographic verifier,
+ * nothing is "verified" — unsigned/unattested packages are reported as such so
+ * the UI surfaces an explicit "unverified build" state rather than a false green.
+ */
+declare const failClosedVerifier: ProvenanceVerifier;
+/**
+ * Verify provenance, defaulting to the fail-closed verifier. A convenience
+ * wrapper so callers always get a `ProvenanceResult` (never an exception) and
+ * unverified is the safe default.
+ */
+declare function verifyProvenance(input: VerifyProvenanceInput, verifier?: ProvenanceVerifier): Promise<ProvenanceResult>;
+/** A one-line human summary of a provenance result, for the consent dialog. */
+declare function summarizeProvenance(result: ProvenanceResult): string;
+
+/**
+ * @xnetjs/plugins — plugin authoring test kit (exploration 0192).
+ *
+ * A zero-setup harness so plugin authors can unit-test a manifest without a real
+ * NodeStore or the app: spin up an in-memory store, install the plugin into a
+ * real `PluginRegistry`, and assert on the contributions it registered. This is
+ * the "@xnetjs/plugin-testing" surface, kept in-package to avoid a new workspace
+ * dependency.
+ */
+
+interface MemNode {
+    id: string;
+    schemaId: string;
+    properties: Record<string, unknown>;
+    deleted?: boolean;
+}
+type Listener = (event: unknown) => void;
+/** A minimal in-memory NodeStore good enough for plugin lifecycle tests. */
+interface TestNodeStore {
+    create(options: {
+        schemaId: string;
+        properties?: Record<string, unknown>;
+    }): Promise<MemNode>;
+    get(id: string): Promise<MemNode | null>;
+    update(id: string, options: {
+        properties?: Record<string, unknown>;
+    }): Promise<MemNode>;
+    delete(id: string): Promise<void>;
+    list(options?: {
+        schemaId?: string;
+    }): Promise<MemNode[]>;
+    subscribe(listener: Listener): () => void;
+    /** Test helper: how many live nodes exist (optionally for one schema). */
+    count(schemaId?: string): number;
+}
+declare function createTestNodeStore(initial?: MemNode[]): TestNodeStore;
+interface TestPluginHarness {
+    registry: PluginRegistry;
+    store: TestNodeStore;
+    /** Install a plugin and return its registered record. */
+    install(manifest: XNetExtension): Promise<void>;
+}
+interface TestHarnessOptions {
+    platform?: Platform;
+    initialNodes?: MemNode[];
+}
+/**
+ * Build a ready-to-use plugin test harness: an in-memory store wired into a real
+ * `PluginRegistry`. Use it to install a plugin and assert on
+ * `registry.getContributions()` or `registry.get(id)?.status`.
+ *
+ * @example
+ * const h = createTestPluginHarness()
+ * await h.install(MyPlugin)
+ * expect(h.registry.get('com.me.plugin')?.status).toBe('active')
+ * expect(h.registry.getContributions().slashCommands.getAll()).toHaveLength(1)
+ */
+declare function createTestPluginHarness(options?: TestHarnessOptions): TestPluginHarness;
+
+/**
+ * @xnetjs/plugins — plugin project scaffolder (exploration 0192).
+ *
+ * The pure core behind `create-xnet-plugin`: given a small spec, produce the
+ * full set of project files (manifest, tests, package.json, README) as a
+ * path→content map. Keeping it pure means it's unit-testable without touching
+ * disk; a thin CLI writes the map out.
+ *
+ * Templates mirror the authoring tracks in the explorations: `client`
+ * (contributions only), `two-sided` (client + a hub feature + declared
+ * capabilities), `ai-script` (a script-backed slash command), and `connector`
+ * (0196 — sync an external service into governed nodes + expose agent tools).
+ */
+
+type ScaffoldTemplate = 'client' | 'two-sided' | 'ai-script' | 'connector';
+interface ScaffoldSpec {
+    /** Reverse-domain plugin id, e.g. `com.acme.kanban`. */
+    id: string;
+    /** Human-readable name. */
+    name: string;
+    /** Which starter template to generate. */
+    template: ScaffoldTemplate;
+    author?: string;
+    description?: string;
+    /** Declared capability grant (two-sided templates surface this in the manifest). */
+    capabilities?: ModuleCapabilities;
+    /** SPDX license id (exploration 0196). Defaults to FSL-1.1-MIT. */
+    license?: string;
+    /** Monetization (exploration 0196). When paid, the manifest declares `pricing`. */
+    pricing?: PluginPricing;
+    /** Publisher DID for paid plugins (exploration 0196). */
+    publisherDid?: string;
+    /** Copyright year for the generated LICENSE (defaults supplied by the caller). */
+    year?: number;
+}
+interface ScaffoldResult {
+    /** Project files keyed by relative path. */
+    files: Record<string, string>;
+}
+declare class ScaffoldError extends Error {
+    constructor(message: string);
+}
+/** `com.acme.kanban-board` → `KanbanBoard` (a safe JS identifier). */
+declare function pascalCase(id: string): string;
+/** `com.acme.kanban` → `acme-kanban` (an npm-safe package name). */
+declare function packageName(id: string): string;
+/**
+ * Scaffold a plugin project as a path→content map. Pure: write the result to
+ * disk with a thin CLI, or assert on it in tests.
+ *
+ * @throws {ScaffoldError} if the spec is invalid.
+ */
+declare function scaffoldPlugin(spec: ScaffoldSpec): ScaffoldResult;
+
+/**
+ * @xnetjs/plugins — paid-plugin license policy (exploration 0196).
+ *
+ * The marketplace pre-approves a small, fixed set of licenses so a paid plugin
+ * needs no per-listing legal review. The default is **FSL-1.1-MIT** — source-
+ * available, forbids only a competing marketplace, and auto-converts to MIT two
+ * years after each version ships (mirrors `@xnetjs/cloud`'s FSL). Plain OSI
+ * licenses are allowed too. This module is the single source of truth for the
+ * allowed set and for generating the `LICENSE` file the scaffolder emits;
+ * `scripts/check-plugin-licenses.sh` enforces the same set in CI.
+ */
+/** SPDX ids a paid plugin may declare. */
+declare const ALLOWED_PLUGIN_LICENSES: readonly ["FSL-1.1-MIT", "FSL-1.1-Apache-2.0", "MIT", "Apache-2.0", "AGPL-3.0-only"];
+type AllowedPluginLicense = (typeof ALLOWED_PLUGIN_LICENSES)[number];
+/** The default license suggested by the scaffolder for a new plugin. */
+declare const DEFAULT_PLUGIN_LICENSE: AllowedPluginLicense;
+/** True if `spdx` is one of the marketplace-approved licenses. */
+declare function isAllowedPluginLicense(spdx: string): spdx is AllowedPluginLicense;
+/**
+ * Generate the `LICENSE` file body for a plugin, or `null` for an unrecognized
+ * license (the scaffolder then omits the file and the author supplies their own).
+ */
+declare function pluginLicenseText(spdx: string, year: number, holder: string): string | null;
+
+/**
+ * @xnetjs/plugins — AI-authored plugin transform (exploration 0192).
+ *
+ * The hard part of AI authoring already ships (`@xnetjs/plugins/ai`:
+ * NL → AST-validated script + provider routing). The missing headless step is
+ * turning a generated script into an *installable* plugin: this wraps a
+ * validated `GeneratedScript` into a `FeatureModule` whose command runs the
+ * script, stamped with `ai-generated` provenance so the install path sandboxes
+ * it at the `user` tier and still routes its capability requests through consent.
+ *
+ * It deliberately **refuses unvalidated code** — "the AI made it" never bypasses
+ * the safety gate.
+ */
+
+/** The subset of `@xnetjs/plugins/ai`'s `AIScriptResponse` this transform needs. */
+interface GeneratedScript {
+    code: string;
+    suggestedName: string;
+    validated: boolean;
+    explanation?: string;
+}
+/** Runs the generated script body (injected so this stays decoupled from the sandbox). */
+type ScriptExecutor = (code: string) => void | Promise<void>;
+interface ScriptToManifestInput {
+    /** Reverse-domain id for the new plugin. */
+    id: string;
+    /** The validated generated script. */
+    script: GeneratedScript;
+    author?: string;
+    /** Capabilities the script needs (default: none — Layer-1 scripts are sandboxed). */
+    capabilities?: ModuleCapabilities;
+    /** How to run the script when the command fires (default: throws until wired). */
+    run?: ScriptExecutor;
+}
+interface AiAuthoredPlugin {
+    manifest: FeatureModule;
+    /** Always `ai-generated` — the install path derives the `user` trust tier from it. */
+    provenance: InstallProvenance;
+    /** The raw script body, for persistence/audit. */
+    code: string;
+}
+declare class AiAuthoringError extends Error {
+    constructor(message: string);
+}
+/**
+ * Wrap a validated generated script into an installable, `ai-generated` plugin.
+ *
+ * @throws {AiAuthoringError} if the id is malformed or the script is unvalidated.
+ */
+declare function scriptToPluginManifest(input: ScriptToManifestInput): AiAuthoredPlugin;
+
+/**
+ * @xnetjs/plugins — run plugin code on the labs runtime ladder (0194 Phase 1).
+ *
+ * The unification the exploration calls for: instead of plugins maintaining their
+ * own sandbox, user/marketplace-tier plugin code runs on the *same* runtime
+ * ladder `@xnetjs/labs` uses (SES/QuickJS for `sandbox`, an iframe for `app`).
+ * One sandbox, one security audit — and plugins gain the ladder's Python/server
+ * tiers for free.
+ *
+ * The ladder is taken as a **structural port** (`PluginRuntimeLadder`), not an
+ * `@xnetjs/labs` import: labs already depends on `@xnetjs/plugins`, so a direct
+ * edge here would cycle. The host (web/electron) passes its concrete labs ladder.
+ *
+ * First-party code is trusted and runs in the host realm, NOT through the ladder
+ * — `runPluginCode` rejects a first-party tier so a caller can't accidentally
+ * sandbox (and slow) trusted code.
+ */
+
+/** The labs runtime tiers a plugin can target. */
+type LadderRuntimeTier = 'sandbox' | 'app' | 'server';
+/** A single run on the ladder. */
+interface PluginRunInput {
+    language: 'javascript' | 'typescript';
+    tier: LadderRuntimeTier;
+    code: string;
+    /** Host bridge the sandbox may call (capability-gated by the host). */
+    host?: unknown;
+}
+interface PluginRunResult {
+    ok: boolean;
+    value?: unknown;
+    logs?: string[];
+    error?: string;
+}
+/** The minimal slice of the labs `RuntimeLadder` this adapter needs. */
+interface PluginRuntimeLadder {
+    run(input: PluginRunInput): Promise<PluginRunResult>;
+}
+declare class PluginRuntimeError extends Error {
+    constructor(message: string);
+}
+/**
+ * Map a plugin's trust tier to the ladder rung its code should run on. `user`
+ * code runs in the deterministic `sandbox` (SES/QuickJS); `marketplace` code in
+ * the `app` (iframe) rung. `first-party` has no ladder rung — it runs in the
+ * host realm — so this throws for it.
+ */
+declare function ladderTierForTrust(tier: TrustTier): LadderRuntimeTier;
+interface RunPluginCodeInput {
+    code: string;
+    trustTier: TrustTier;
+    language?: 'javascript' | 'typescript';
+    host?: unknown;
+}
+/**
+ * Run user/marketplace-tier plugin code on the labs ladder, choosing the rung by
+ * trust tier. Throws `PluginRuntimeError` for first-party (which belongs in the
+ * host realm). Returns the ladder's result unchanged.
+ */
+declare function runPluginCode(ladder: PluginRuntimeLadder, input: RunPluginCodeInput): Promise<PluginRunResult>;
+
+/**
+ * @xnetjs/plugins — the AI→Lab→Plugin assembly line (exploration 0194 Phase 2).
+ *
+ * Closes the authoring loop: the AI *generates* a script, the script *runs* in a
+ * Lab so the AI (and the user) see real output, and only after a human approves
+ * is it *published* as a plugin. Each hop is an injected port, so this is pure
+ * orchestration — testable without the AI provider, the labs ladder, or the
+ * registry, and free of the `plugins → labs` dependency edge.
+ *
+ * It never auto-publishes: publishing is always gated on `consent`. The script
+ * must be validated before it becomes a plugin (`scriptToPluginManifest` refuses
+ * unvalidated code), so "the AI made it" never bypasses the gate.
+ */
+
+/** The result of running a generated script in a Lab. */
+interface LabRunOutcome {
+    ok: boolean;
+    output?: string;
+    error?: string;
+}
+/** The injected capabilities the pipeline orchestrates. */
+interface AiPluginPipelinePorts {
+    /** Generate a (validated) script from natural-language intent. */
+    generate: (intent: string) => Promise<GeneratedScript>;
+    /** Run the script in a Lab and report the real result. */
+    runLab: (code: string) => Promise<LabRunOutcome>;
+    /** Ask the human to approve publishing, given the plugin + its run output. */
+    consent: (plugin: AiAuthoredPlugin, run: LabRunOutcome) => Promise<boolean>;
+    /** Publish the approved plugin (e.g. `publishLabAsExtension` / `registry.install`). */
+    publish: (plugin: AiAuthoredPlugin) => Promise<void>;
+}
+interface AiPluginPipelineInput {
+    /** Natural-language description of the plugin to build. */
+    intent: string;
+    /** Reverse-domain id for the new plugin. */
+    id: string;
+    author?: string;
+}
+type AiPluginPipelineResult = {
+    status: 'generation-invalid';
+    reason: string;
+} | {
+    status: 'run-failed';
+    plugin: AiAuthoredPlugin;
+    run: LabRunOutcome;
+} | {
+    status: 'declined';
+    plugin: AiAuthoredPlugin;
+    run: LabRunOutcome;
+} | {
+    status: 'published';
+    plugin: AiAuthoredPlugin;
+    run: LabRunOutcome;
+};
+/**
+ * Run the generate → lab-test → consent → publish pipeline. Returns a tagged
+ * result at whichever stage it stops; only `published` means the plugin landed.
+ */
+declare function runAiPluginPipeline(input: AiPluginPipelineInput, ports: AiPluginPipelinePorts): Promise<AiPluginPipelineResult>;
+
 /**
  * Plugin schema - stores plugin metadata as Nodes for P2P sync
  */
@@ -1187,6 +4083,65 @@ declare class ScriptRunner {
     private handleScriptChange;
 }
 
+/**
+ * Canvas Plugin Sandbox
+ *
+ * Policy helpers for plugin-owned canvas renderers and preview generators.
+ */
+
+type CanvasPluginSandboxKind = 'renderer' | 'preview';
+type CanvasPluginSandboxDomAccess = 'none' | 'isolated-iframe';
+type CanvasPluginSandboxNetworkAccess = 'none' | 'workspace-approved';
+type CanvasPluginSandboxMutationAccess = 'none';
+type CanvasPluginSandboxOutputKind = 'view-model' | 'html-fragment' | 'summary' | 'thumbnail' | 'template-draft';
+type CanvasPluginSandboxPolicy = {
+    kind: CanvasPluginSandboxKind;
+    timeoutMs: number;
+    maxOutputBytes: number;
+    domAccess: CanvasPluginSandboxDomAccess;
+    networkAccess: CanvasPluginSandboxNetworkAccess;
+    mutationAccess: CanvasPluginSandboxMutationAccess;
+    allowedOutputKinds: CanvasPluginSandboxOutputKind[];
+    blockedGlobals: string[];
+};
+type CanvasPluginSandboxRequest = {
+    pluginId: string;
+    contributionId: string;
+    kind: CanvasPluginSandboxKind;
+    entrypoint: string;
+    permissions?: CanvasContributionPermission[];
+    requestedNetworkDomains?: string[];
+};
+type CanvasPluginSandboxDecision = {
+    allowed: boolean;
+    policy: CanvasPluginSandboxPolicy;
+    issues: string[];
+};
+type CanvasPluginSandboxOutput = {
+    kind: CanvasPluginSandboxOutputKind;
+    payload?: unknown;
+    html?: string;
+    bytes?: number;
+};
+type CanvasPluginSandboxOutputValidation = {
+    valid: boolean;
+    issues: string[];
+};
+type CanvasRendererSandboxContribution = CanvasCardContribution | CanvasInspectorContribution | CanvasTemplateContribution;
+declare function createCanvasPluginSandboxPolicy(kind: CanvasPluginSandboxKind, permissions?: CanvasContributionPermission[]): CanvasPluginSandboxPolicy;
+declare function evaluateCanvasPluginSandboxRequest(request: CanvasPluginSandboxRequest): CanvasPluginSandboxDecision;
+declare function createCanvasRendererSandboxRequest(input: {
+    pluginId: string;
+    contribution: CanvasRendererSandboxContribution;
+    entrypoint?: string;
+}): CanvasPluginSandboxRequest;
+declare function createCanvasPreviewSandboxRequest(input: {
+    pluginId: string;
+    contribution: CanvasCardContribution | CanvasTemplateContribution;
+    entrypoint?: string;
+}): CanvasPluginSandboxRequest;
+declare function validateCanvasPluginSandboxOutput(output: CanvasPluginSandboxOutput, policy: CanvasPluginSandboxPolicy): CanvasPluginSandboxOutputValidation;
+
 /**
  * AI Prompt Builder for Script Generation
  *
@@ -1264,10 +4219,100 @@ declare function buildRetryPrompt(originalPrompt: string, errors: string[]): str
  * AI Provider Abstraction
  *
  * Defines a common interface for AI providers and includes
- * implementations for Anthropic, OpenAI, and local (Ollama).
+ * implementations for Anthropic, OpenAI-compatible endpoints, OpenAI,
+ * and local (Ollama).
  */
+type AIMessageRole = 'system' | 'user' | 'assistant' | 'tool';
+type AIMessage = {
+    role: AIMessageRole;
+    content: string;
+    name?: string;
+    toolCallId?: string;
+};
+type AIToolSpec = {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+};
+type AIPrivacyLevel = 'local' | 'cloud' | 'proxy';
+type AIModelQuality = 'local' | 'balanced' | 'strong';
+type AICostModel = {
+    inputPerMillion: number;
+    outputPerMillion: number;
+    currency: 'USD';
+};
+type AIModelCapabilities = {
+    tools: boolean;
+    structuredOutputs: boolean;
+    streaming: boolean;
+    contextWindow: number;
+    local: boolean;
+    privacy: AIPrivacyLevel;
+    quality: AIModelQuality;
+    cost?: AICostModel;
+};
+type AIRiskLevel = 'low' | 'medium' | 'high' | 'critical';
+type AIComplexityLevel = 'low' | 'medium' | 'high';
+type AIGenerateRequest = {
+    prompt?: string;
+    messages?: AIMessage[];
+    tools?: AIToolSpec[];
+    responseSchema?: Record<string, unknown>;
+    stream?: boolean;
+    risk?: AIRiskLevel;
+    complexity?: AIComplexityLevel;
+    maxTokens?: number;
+    temperature?: number;
+    preferredProvider?: string;
+    metadata?: Record<string, unknown>;
+};
+type AIToolCall = {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+};
+type AIUsage = {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    estimatedCostUsd?: number;
+};
+type AIGenerateResponse = {
+    text: string;
+    provider: string;
+    model: string;
+    toolCalls?: AIToolCall[];
+    usage?: AIUsage;
+};
+type AIStreamChunk = {
+    type: 'text';
+    text: string;
+    provider: string;
+    model: string;
+} | {
+    type: 'tool_call';
+    toolCall: AIToolCall;
+    provider: string;
+    model: string;
+} | {
+    type: 'usage';
+    usage: AIUsage;
+    provider: string;
+    model: string;
+} | {
+    type: 'done';
+    provider: string;
+    model: string;
+};
+type AIProviderUsage = {
+    requests: number;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    estimatedCostUsd: number;
+};
 /**
- * Common interface for AI text generation providers
+ * Common interface for AI text generation providers.
  */
 interface AIProvider {
     /** Provider name for display/logging */
@@ -1280,9 +4325,21 @@ interface AIProvider {
      * @throws Error if generation fails
      */
     generate(prompt: string): Promise<string>;
+    /**
+     * Generate a response with optional tool and structured-output metadata.
+     */
+    generateWithTools?(request: AIGenerateRequest): Promise<AIGenerateResponse>;
+    /**
+     * Stream model output and tool events.
+     */
+    stream?(request: AIGenerateRequest): AsyncIterable<AIStreamChunk>;
+    /**
+     * Describe model/provider capabilities for routing.
+     */
+    getCapabilities?(): AIModelCapabilities;
 }
 /**
- * Options for configuring AI providers
+ * Options for configuring AI providers.
  */
 interface AIProviderOptions {
     /** API key (for cloud providers) */
@@ -1295,20 +4352,40 @@ interface AIProviderOptions {
     maxTokens?: number;
     /** Temperature (0-1, higher = more creative) */
     temperature?: number;
+    /** Display name for OpenAI-compatible providers */
+    providerName?: string;
+    /** Additional HTTP headers for compatible proxies */
+    defaultHeaders?: Record<string, string>;
+    /** Whether an API key is required */
+    apiKeyRequired?: boolean;
+    /** Capability overrides for routing */
+    capabilities?: Partial<AIModelCapabilities>;
+    /**
+     * Send the Anthropic browser-CORS header
+     * (`anthropic-dangerous-direct-browser-access`) so a bring-your-own-key call
+     * succeeds from browser JavaScript. Only `AnthropicProvider` reads this.
+     * Defaults to `true` when a DOM is present (`typeof window !== 'undefined'`).
+     */
+    allowBrowser?: boolean;
 }
+type OpenAICompatibleProviderOptions = AIProviderOptions;
 /**
- * AI provider type identifier
+ * AI provider type identifier.
  */
-type AIProviderType = 'anthropic' | 'openai' | 'ollama' | 'custom';
+type AIProviderType = 'anthropic' | 'openai' | 'ollama' | 'openai-compatible' | 'openrouter' | 'ollama-openai' | 'lmstudio' | 'vllm' | 'litellm' | 'managed' | 'custom';
 /**
- * Configuration for selecting an AI provider
+ * Configuration for selecting an AI provider.
  */
 interface AIProviderConfig {
     type: AIProviderType;
     options: AIProviderOptions;
 }
+type AIProviderRouterOptions = {
+    preferLocalRiskLevels?: AIRiskLevel[];
+    strongModelRiskLevels?: AIRiskLevel[];
+};
 /**
- * Error thrown when AI generation fails
+ * Error thrown when AI generation fails.
  */
 declare class AIGenerationError extends Error {
     readonly provider: string;
@@ -1331,8 +4408,34 @@ declare class AnthropicProvider implements AIProvider {
     private model;
     private maxTokens;
     private temperature;
+    private allowBrowser;
     constructor(options: AIProviderOptions);
+    getCapabilities(): AIModelCapabilities;
+    generate(prompt: string): Promise<string>;
+}
+/**
+ * Tool-capable adapter for OpenAI-compatible chat completion endpoints.
+ *
+ * Works with OpenAI, OpenRouter, Ollama's `/v1` compatibility API,
+ * LM Studio, vLLM, and LiteLLM.
+ */
+declare class OpenAICompatibleProvider implements AIProvider {
+    readonly name: string;
+    private apiKey?;
+    private baseUrl;
+    private model;
+    private maxTokens;
+    private temperature;
+    private defaultHeaders;
+    private capabilities;
+    constructor(options?: OpenAICompatibleProviderOptions);
+    getCapabilities(): AIModelCapabilities;
     generate(prompt: string): Promise<string>;
+    generateWithTools(request: AIGenerateRequest): Promise<AIGenerateResponse>;
+    stream(request: AIGenerateRequest): AsyncIterable<AIStreamChunk>;
+    private createHeaders;
+    private createPayload;
+    private parseToolCalls;
 }
 /**
  * AI provider for OpenAI's GPT models.
@@ -1343,15 +4446,8 @@ declare class AnthropicProvider implements AIProvider {
  * const response = await provider.generate('Hello!')
  * ```
  */
-declare class OpenAIProvider implements AIProvider {
-    readonly name = "OpenAI";
-    private apiKey;
-    private baseUrl;
-    private model;
-    private maxTokens;
-    private temperature;
+declare class OpenAIProvider extends OpenAICompatibleProvider {
     constructor(options: AIProviderOptions);
-    generate(prompt: string): Promise<string>;
 }
 /**
  * AI provider for local Ollama instance.
@@ -1368,8 +4464,85 @@ declare class OllamaProvider implements AIProvider {
     private model;
     private temperature;
     constructor(options?: AIProviderOptions);
+    getCapabilities(): AIModelCapabilities;
+    generate(prompt: string): Promise<string>;
+}
+declare class AIProviderRouter implements AIProvider {
+    readonly name = "AIProviderRouter";
+    private providers;
+    private options;
+    private usageByProvider;
+    constructor(providers: AIProvider[], options?: AIProviderRouterOptions);
+    getCapabilities(): AIModelCapabilities;
+    getUsage(): Record<string, AIProviderUsage>;
+    selectProvider(request: AIGenerateRequest): AIProvider;
+    generate(prompt: string): Promise<string>;
+    generateWithTools(request: AIGenerateRequest): Promise<AIGenerateResponse>;
+    stream(request: AIGenerateRequest): AsyncIterable<AIStreamChunk>;
+    private canHandle;
+    private shouldPreferLocal;
+    private shouldPreferStrong;
+    private getProviderCapabilities;
+    private recordUsage;
+}
+/** The live budget snapshot a managed call reports back (drives the panel gauge). */
+interface ManagedBudgetSnapshot {
+    /** Marked-up spend accrued this billing period, in USD. */
+    spendThisPeriodUsd: number;
+    /** Free included allotment for the period, in USD. */
+    includedUsd: number;
+    /** Hard monthly cap, in USD — requests stop here. */
+    budgetUsd: number;
+    /** Coarse state driving the gauge colour. */
+    budgetState: 'included' | 'overage' | 'near-cap' | 'over-cap';
+}
+/** Thrown when managed AI returns `402` — the surprise-bill hard stop. */
+declare class AiBudgetError extends Error {
+    readonly spentUsd: number;
+    readonly budgetUsd: number;
+    constructor(spentUsd: number, budgetUsd: number);
+}
+type ManagedProviderOptions = AIProviderOptions & {
+    /** Injected fetch for tests; defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Receives the live budget after each managed call (drives the panel gauge). */
+    onBudget?: (snapshot: ManagedBudgetSnapshot) => void;
+};
+/**
+ * XNet Cloud **managed** AI provider (exploration 0208).
+ *
+ * Posts to the hub's `/ai/chat`, which forwards to the metered control-plane
+ * gateway (OpenRouter behind a per-tenant budgeted key). Unlike every other cloud
+ * provider it carries **no API key** — the hub injects the per-tenant credential
+ * server-side — so it is the only cloud tier safe to use without the user pasting
+ * a secret. It surfaces the live budget (so the panel can render "used / included
+ * / cap") and turns a `402` into a typed {@link AiBudgetError} the UI can act on.
+ *
+ * Model switching is per-instance: the configured `model` is sent on every call,
+ * so changing the picker rebuilds the provider (same pattern as the BYO tiers).
+ * No `stream` method, so the runtime uses the request/response path.
+ */
+declare class ManagedProvider implements AIProvider {
+    readonly name = "XNet Cloud";
+    private readonly baseUrl;
+    private readonly model?;
+    private readonly fetchImpl;
+    private readonly onBudget?;
+    constructor(options?: ManagedProviderOptions);
+    getCapabilities(): AIModelCapabilities;
     generate(prompt: string): Promise<string>;
+    generateWithTools(request: AIGenerateRequest): Promise<AIGenerateResponse>;
+    /**
+     * Stream the managed completion over SSE (`/ai/chat/stream`). Yields a `text`
+     * chunk per delta, then `usage` + `done`; emits the live budget from the terminal
+     * `done` event. A `402` (pre-stream) or an `ai_budget_exceeded` error event
+     * becomes an {@link AiBudgetError} (exploration 0244).
+     */
+    stream(request: AIGenerateRequest): AsyncIterable<AIStreamChunk>;
+    private emitBudget;
 }
+/** Build a {@link ManagedProvider} (parallels `createPromptApiProvider`). */
+declare const createManagedProvider: (options?: ManagedProviderOptions) => ManagedProvider;
 /**
  * Create an AI provider from configuration.
  *
@@ -1385,6 +4558,7 @@ declare class OllamaProvider implements AIProvider {
  * ```
  */
 declare function createAIProvider(config: AIProviderConfig): AIProvider;
+declare function createAIProviderRouter(providers: AIProvider[], options?: AIProviderRouterOptions): AIProviderRouter;
 /**
  * Check if Ollama is available locally.
  *
@@ -1498,6 +4672,556 @@ declare class ScriptGenerator {
  */
 declare function generateScript(provider: AIProvider, request: AIScriptRequest): Promise<AIScriptResponse>;
 
+/**
+ * In-app AI agent runtime for persistent threads, approvals, events, and telemetry.
+ */
+
+type AiAgentOrchestratorMode = 'custom' | 'codex-app-server' | 'hybrid';
+/**
+ * How the assistant relates to the user's work (xNet Humane Internet Charter
+ * §Agency). `scaffold` — the default — keeps the human as the author: the model
+ * proposes and cites, the user writes and owns. It is a guard against the
+ * cognitive-debt / deskilling effect of LLM-authored work (MIT Media Lab,
+ * arXiv:2506.08872). `draft`, where the model produces finished prose, must be
+ * opted into explicitly. Either way the resulting turn is tagged `ai-generated`.
+ */
+type AiAssistMode = 'scaffold' | 'draft';
+type AiAgentThreadStatus = 'idle' | 'running' | 'waiting-approval' | 'cancelled' | 'failed';
+type AiAgentTurnRole = 'system' | 'user' | 'assistant' | 'tool';
+type AiAgentTurnStatus = 'pending' | 'streaming' | 'completed' | 'cancelled' | 'failed';
+type AiAgentApprovalStatus = 'pending' | 'approved' | 'rejected' | 'revision-requested';
+type AiAgentBackgroundJobStatus = 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
+type AiAgentEventType = 'thread.created' | 'turn.created' | 'model.delta' | 'model.completed' | 'tool.call' | 'usage' | 'approval.requested' | 'approval.resolved' | 'run.cancelled' | 'run.completed' | 'run.failed' | 'run.steered' | 'background.started' | 'background.completed' | 'background.failed' | 'background.cancelled';
+type AiAgentThread = {
+    id: string;
+    title: string;
+    mode: AiAgentOrchestratorMode;
+    status: AiAgentThreadStatus;
+    createdAt: string;
+    updatedAt: string;
+    metadata?: Record<string, unknown>;
+};
+type AiAgentTurn = {
+    id: string;
+    threadId: string;
+    role: AiAgentTurnRole;
+    status: AiAgentTurnStatus;
+    content: string;
+    createdAt: string;
+    updatedAt: string;
+    provider?: string;
+    model?: string;
+    usage?: AIUsage;
+    toolCalls?: AIToolCall[];
+    error?: string;
+    metadata?: Record<string, unknown>;
+};
+type AiAgentApproval = {
+    id: string;
+    threadId: string;
+    turnId?: string;
+    planId: string;
+    risk: AiRiskLevel;
+    requiredScopes: AiScope[];
+    status: AiAgentApprovalStatus;
+    createdAt: string;
+    resolvedAt?: string;
+    note?: string;
+    plan: AiMutationPlan;
+};
+type AiAgentBackgroundJob = {
+    id: string;
+    kind: 'export' | 'analysis' | 'custom';
+    title: string;
+    status: AiAgentBackgroundJobStatus;
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    result?: unknown;
+    error?: string;
+    metadata?: Record<string, unknown>;
+};
+type AiAgentEvent = {
+    id: string;
+    threadId?: string;
+    turnId?: string;
+    type: AiAgentEventType;
+    createdAt: string;
+    payload: Record<string, unknown>;
+};
+type AiAgentTelemetrySnapshot = {
+    runsStarted: number;
+    runsCompleted: number;
+    runsCancelled: number;
+    runsFailed: number;
+    totalLatencyMs: number;
+    lastLatencyMs?: number;
+    acceptedChanges: number;
+    rejectedChanges: number;
+    revisionRequests: number;
+    toolFailures: number;
+    backgroundJobsStarted: number;
+    backgroundJobsCompleted: number;
+    backgroundJobsFailed: number;
+};
+type AiAgentRuntimeSnapshot = {
+    threads: AiAgentThread[];
+    turns: AiAgentTurn[];
+    approvals: AiAgentApproval[];
+    backgroundJobs: AiAgentBackgroundJob[];
+    events: AiAgentEvent[];
+    telemetry: AiAgentTelemetrySnapshot;
+};
+type AiAgentRuntimeStorage = {
+    load(): Promise<AiAgentRuntimeSnapshot | null>;
+    save(snapshot: AiAgentRuntimeSnapshot): Promise<void>;
+};
+/**
+ * Builds extra messages (workspace context, retrieved resources, …) to inject
+ * before the conversation history on each run. Returned messages are placed
+ * after {@link AiAgentRuntimeConfig.systemPrompt} and before the thread
+ * history, so the model sees grounding context ahead of the dialogue. Resolve
+ * to `[]` (or throw — failures are swallowed) to skip context for a turn.
+ */
+type AiAgentContextProvider = (input: {
+    threadId: string;
+    content: string;
+}) => AIMessage[] | Promise<AIMessage[]>;
+type AiAgentRuntimeConfig = {
+    provider: AIProvider;
+    storage?: AiAgentRuntimeStorage;
+    clock?: () => Date;
+    mode?: AiAgentOrchestratorMode;
+    maxEvents?: number;
+    /** Optional system prompt prepended to every run. */
+    systemPrompt?: string;
+    /** Optional hook injecting grounding context messages before the history. */
+    contextProvider?: AiAgentContextProvider;
+    /**
+     * Assist mode (default `scaffold`). Tags every assistant turn's provenance and
+     * is exposed via {@link AiAgentRuntime.getAssistMode}; apps compose the
+     * scaffold guard into their system prompt with {@link composeAssistSystemPrompt}.
+     * `draft` is never the default — it must be set explicitly.
+     */
+    assistMode?: AiAssistMode;
+};
+type AiAgentThreadCreateInput = {
+    title: string;
+    mode?: AiAgentOrchestratorMode;
+    metadata?: Record<string, unknown>;
+};
+type AiAgentRunTurnInput = {
+    threadId: string;
+    content: string;
+    request?: Omit<AIGenerateRequest, 'prompt' | 'messages'>;
+    metadata?: Record<string, unknown>;
+};
+type AiAgentSelectionKind = 'page-text' | 'database-rows' | 'canvas-objects' | 'nodes';
+type AiAgentSelectionContext = {
+    kind: AiAgentSelectionKind;
+    label?: string;
+    pageId?: string;
+    databaseId?: string;
+    canvasId?: string;
+    nodeIds?: string[];
+    rowIds?: string[];
+    objectIds?: string[];
+    text?: string;
+    range?: {
+        from: number;
+        to: number;
+    };
+};
+type AiAgentRunSelectionTurnInput = Omit<AiAgentRunTurnInput, 'content'> & {
+    instruction: string;
+    selection: AiAgentSelectionContext;
+};
+type AiAgentRunTurnResult = {
+    runId: string;
+    userTurn: AiAgentTurn;
+    assistantTurn: AiAgentTurn;
+};
+type AiAgentApprovalRequestInput = {
+    threadId: string;
+    turnId?: string;
+    plan: AiMutationPlan;
+};
+type AiAgentApprovalResolveInput = {
+    approvalId: string;
+    status: Exclude<AiAgentApprovalStatus, 'pending'>;
+    note?: string;
+};
+type AiAgentBackgroundJobInput = {
+    kind: AiAgentBackgroundJob['kind'];
+    title: string;
+    metadata?: Record<string, unknown>;
+};
+type AiAgentBackgroundJobRunner = (signal: AbortSignal) => Promise<unknown>;
+type AiAgentRuntimeListener = (event: AiAgentEvent, snapshot: AiAgentRuntimeSnapshot) => void;
+type AiAgentDisplayStateKind = 'read-only-answer' | 'proposed-change' | 'applied-change';
+type AiAgentDisplayState = {
+    kind: AiAgentDisplayStateKind;
+    label: string;
+    planId?: string;
+    approvalId?: string;
+    auditEventId?: string;
+};
+declare class AiAgentRuntime {
+    private readonly config;
+    private snapshot;
+    private readonly storage;
+    private readonly clock;
+    private readonly mode;
+    private readonly assistMode;
+    private readonly maxEvents;
+    private sequence;
+    private loaded;
+    private readonly listeners;
+    private readonly activeRuns;
+    private readonly activeJobs;
+    constructor(config: AiAgentRuntimeConfig);
+    /** The active assist mode (`scaffold` by default; `draft` is opt-in only). */
+    getAssistMode(): AiAssistMode;
+    load(): Promise<AiAgentRuntimeSnapshot>;
+    getSnapshot(): AiAgentRuntimeSnapshot;
+    subscribe(listener: AiAgentRuntimeListener): () => void;
+    createThread(input: AiAgentThreadCreateInput): Promise<AiAgentThread>;
+    runTurn(input: AiAgentRunTurnInput): Promise<AiAgentRunTurnResult>;
+    runSelectionTurn(input: AiAgentRunSelectionTurnInput): Promise<AiAgentRunTurnResult>;
+    cancelRun(runId: string): Promise<boolean>;
+    steerRun(runId: string, message: string): Promise<boolean>;
+    requestApproval(input: AiAgentApprovalRequestInput): Promise<AiAgentApproval>;
+    resolveApproval(input: AiAgentApprovalResolveInput): Promise<AiAgentApproval>;
+    startBackgroundJob(input: AiAgentBackgroundJobInput, runner: AiAgentBackgroundJobRunner): Promise<AiAgentBackgroundJob>;
+    cancelBackgroundJob(jobId: string): Promise<boolean>;
+    /**
+     * Compose the messages sent to the provider for a run: the optional system
+     * prompt, then optional grounding context, then the thread's prior
+     * user/assistant turns in chronological order (which already include the
+     * just-created user message). The in-flight (empty) assistant turn is
+     * excluded. Context is best-effort — a throwing provider never fails the run.
+     */
+    private buildRunMessages;
+    private completeRun;
+    private completeStreamingRun;
+    private applyGenerateResponse;
+    private applyStreamChunk;
+    private appendAssistantText;
+    private appendToolCall;
+    private finishRun;
+    private failRun;
+    private completeBackgroundJob;
+    private finishBackgroundJob;
+    private failBackgroundJob;
+    private createTurn;
+    private updateThread;
+    private updateTurn;
+    private updateJob;
+    private emit;
+    private persist;
+    private ensureLoaded;
+    private getThreadOrThrow;
+    private getTurnOrThrow;
+    private nowIso;
+    private nextId;
+}
+declare function createAiAgentRuntime(config: AiAgentRuntimeConfig): AiAgentRuntime;
+declare function createMemoryAiAgentRuntimeStorage(initial?: AiAgentRuntimeSnapshot): AiAgentRuntimeStorage & {
+    snapshot(): AiAgentRuntimeSnapshot;
+};
+/** Provenance tag stamped on every assistant turn (xNet trust tiers). */
+declare const AI_GENERATED_PROVENANCE: "ai-generated";
+/**
+ * The cognitive-debt guard appended to the system prompt in scaffold mode. It
+ * asks the model to help the user think rather than think for them — an answer
+ * to the deskilling effect of LLM-authored work (MIT, arXiv:2506.08872).
+ */
+declare const SCAFFOLD_SYSTEM_GUARD: string;
+/**
+ * Compose the system prompt for an assist mode. In `scaffold` mode the guard is
+ * appended so the assistant scaffolds rather than substitutes; in `draft` mode
+ * the base prompt passes through unchanged. Returned to apps so the runtime's
+ * own message composition stays backward-compatible.
+ */
+declare function composeAssistSystemPrompt(base: string | undefined, mode: AiAssistMode): string | undefined;
+/** Metadata stamped on an assistant turn so its provenance is always legible. */
+declare function assistTurnProvenance(mode: AiAssistMode): {
+    provenance: typeof AI_GENERATED_PROVENANCE;
+    assistMode: AiAssistMode;
+};
+declare function renderSelectionPrompt(instruction: string, selection: AiAgentSelectionContext): string;
+declare function classifyAiAgentDisplayState(input: {
+    plan?: AiMutationPlan;
+    approval?: AiAgentApproval;
+    auditEventId?: string;
+}): AiAgentDisplayState;
+
+/**
+ * Bring-Your-Own-Model connector contract (exploration 0174).
+ *
+ * No single transport reaches a model from a sandboxed HTTPS tab everywhere, so
+ * the app probes a tiered set of "connectors" and degrades gracefully. Each
+ * connector ultimately produces an {@link AIProvider} (see `../providers`); this
+ * module only models *detection and selection* — which tiers are usable right
+ * now and how capable each is — so it stays pure and unit-testable without a
+ * GPU, Ollama, a key, or a browser.
+ */
+/** The model-access tiers, from the exploration's options A–E (+ managed, 0208). */
+type ConnectorTier = 'managed' | 'webllm' | 'local-server' | 'prompt-api' | 'cloud-key' | 'bridge';
+/**
+ * How reliably the tier's model can call tools. This is the gate the
+ * exploration identifies: `reliable` → full agentic writes; otherwise writes
+ * must downgrade to "propose a plan, human applies" (see {@link writeModeFor}).
+ */
+type ToolCallingFidelity = 'reliable' | 'weak' | 'none';
+/** Whether the agent may apply writes itself, or must only propose them. */
+type WriteMode = 'agentic' | 'propose-only';
+/**
+ * Injectable probes so detection is testable and host-agnostic. Every field has
+ * a sensible default in {@link detectConnectors}; tests and non-browser hosts
+ * override what they need.
+ */
+interface ConnectorEnv {
+    /**
+     * Probe XNet Cloud managed AI: GET `${managedUrl}/ai/health` is `ok` and the
+     * tenant has AI enabled. Default: a same-origin fetch (returns false off-cloud).
+     */
+    probeManaged?: (baseUrl: string) => Promise<boolean>;
+    /** Base URL the hub serves the managed `/ai` routes from. Default: `''` (same origin). */
+    managedUrl?: string;
+    /** WebGPU present (enables in-tab models). Default: `navigator.gpu` check. */
+    hasWebGpu?: () => boolean | Promise<boolean>;
+    /**
+     * Whether the host can actually build an in-tab WebLLM engine (the heavy
+     * `@mlc-ai/web-llm` import is host-supplied, see the panel). The `webllm` tier
+     * is reported available only when this AND {@link hasWebGpu} are true —
+     * detecting WebGPU alone would advertise a tier the host can't instantiate,
+     * leaving the composer silently disabled. Default: `false` (no engine wired).
+     */
+    hasWebLLMEngine?: () => boolean | Promise<boolean>;
+    /**
+     * Chrome built-in `LanguageModel` is present *and the model is ready to use*.
+     * Default: probes `LanguageModel.availability()` and reports ready only for
+     * `'available'` — mere API presence (`'downloadable'`) means a session can't
+     * be created without a user-gesture download first (see the panel's gesture).
+     */
+    hasPromptApi?: () => boolean | Promise<boolean>;
+    /** Local model endpoints to probe, in priority order. Default: Ollama, LM Studio. */
+    localServerProbes?: readonly LocalServerProbe[];
+    /** Whether a cloud API key is stored locally. Default: `false` (host wires this). */
+    hasCloudKey?: () => boolean | Promise<boolean>;
+    /** Probe a local bridge daemon. Default: GET `${bridgeUrl}/health`. */
+    probeBridge?: (baseUrl: string) => Promise<boolean>;
+    /** Bridge daemon base URL. Default: `http://127.0.0.1:31416`. */
+    bridgeUrl?: string;
+}
+/** A named local model endpoint and how to detect it. */
+interface LocalServerProbe {
+    label: string;
+    baseUrl: string;
+    probe: (baseUrl: string) => Promise<boolean>;
+}
+/** The result of probing one tier. */
+interface ConnectorDetection {
+    tier: ConnectorTier;
+    label: string;
+    available: boolean;
+    /** Extra context when available (e.g. the reachable endpoint or model). */
+    detail?: string;
+    /** When unavailable: why, and how to enable it. */
+    setupHint?: string;
+    /** Tool-calling fidelity → gates agentic vs propose-only writes. */
+    toolCalling: ToolCallingFidelity;
+    /** Preference rank; lower is more capable/preferred. */
+    preference: number;
+}
+/** Map tool-calling fidelity to the safe write mode for that tier. */
+declare function writeModeFor(toolCalling: ToolCallingFidelity): WriteMode;
+
+/**
+ * Connector detection (exploration 0174).
+ *
+ * Probes the model-access tiers in parallel and returns them ranked by
+ * capability so the chat panel can prefer the most capable available tier and
+ * fall back gracefully. Pure given its {@link ConnectorEnv}; the defaults touch
+ * `navigator`/`fetch` but every probe is overridable.
+ */
+
+interface ConnectorMeta {
+    label: string;
+    toolCalling: ToolCallingFidelity;
+    /** Lower = more capable/preferred. Mirrors the exploration: E > D > B > A > C. */
+    preference: number;
+}
+/** Stable per-tier metadata. Keep ordering aligned with the recommendation. */
+declare const CONNECTOR_META: Record<ConnectorTier, ConnectorMeta>;
+/** Default local-model endpoints: Ollama (`/api/tags`) and LM Studio (`/v1/models`). */
+declare function defaultLocalServerProbes(): LocalServerProbe[];
+/** Probe an OpenAI-compatible server's `/v1/models`. Used for LM Studio etc. */
+declare function probeOpenAiCompatible(baseUrl: string): Promise<boolean>;
+/**
+ * Detect which model connectors are usable right now, ranked by preference
+ * (most capable first). Runs all probes concurrently.
+ */
+declare function detectConnectors(env?: ConnectorEnv): Promise<ConnectorDetection[]>;
+/** The most-preferred *available* connector, or null if none are usable. */
+declare function pickBestConnector(detections: readonly ConnectorDetection[]): ConnectorDetection | null;
+
+/**
+ * WebLLM provider adapter (exploration 0174, tier A).
+ *
+ * Wraps an in-tab WebGPU model (`@mlc-ai/web-llm`) behind the `AIProvider`
+ * contract. To keep `@xnetjs/plugins` dependency-free and node-safe, the heavy
+ * library is **not** a dependency here: the provider runs against a structural
+ * {@link WebLLMEngineLike} interface, and `createWebLLMProvider` takes an
+ * already-created engine. The web app supplies a real engine via a lazy
+ * `import('@mlc-ai/web-llm')` + `CreateMLCEngine(...)` (see the "Connect a
+ * model" guide); tests inject a fake.
+ *
+ * WebLLM exposes an OpenAI-compatible chat-completions surface. In-tab tool
+ * calling is unreliable, so this reports `tools: false` — the chat panel routes
+ * its writes through propose-only mode (see `writeModeFor`).
+ */
+
+/** Minimal shape of an `@mlc-ai/web-llm` MLCEngine, structurally typed. */
+interface WebLLMEngineLike {
+    chat: {
+        completions: WebLLMCompletions;
+    };
+}
+interface WebLLMCompletions {
+    create(request: WebLLMRequest & {
+        stream?: false;
+    }): Promise<WebLLMResponse>;
+    create(request: WebLLMRequest & {
+        stream: true;
+    }): Promise<AsyncIterable<WebLLMChunk>>;
+}
+interface WebLLMRequest {
+    messages: Array<{
+        role: string;
+        content: string;
+    }>;
+    stream?: boolean;
+    temperature?: number;
+    max_tokens?: number;
+}
+interface WebLLMResponse {
+    choices: Array<{
+        message: {
+            content: string | null;
+        };
+    }>;
+    usage?: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+        total_tokens?: number;
+    };
+}
+interface WebLLMChunk {
+    choices: Array<{
+        delta: {
+            content?: string;
+        };
+    }>;
+    usage?: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+        total_tokens?: number;
+    };
+}
+interface WebLLMProviderOptions {
+    engine: WebLLMEngineLike;
+    /** Model id loaded into the engine (for reporting). */
+    model: string;
+    /** Context window of the loaded model, for capability reporting. */
+    contextWindow?: number;
+}
+declare class WebLLMProvider implements AIProvider {
+    readonly name = "webllm";
+    private readonly engine;
+    private readonly model;
+    private readonly contextWindow;
+    constructor(options: WebLLMProviderOptions);
+    generate(prompt: string): Promise<string>;
+    stream(request: AIGenerateRequest): AsyncIterable<AIStreamChunk>;
+    getCapabilities(): AIModelCapabilities;
+}
+declare function createWebLLMProvider(options: WebLLMProviderOptions): WebLLMProvider;
+
+/**
+ * Chrome built-in AI provider adapter (exploration 0174, tier C).
+ *
+ * Wraps the browser's on-device `LanguageModel` (Gemini Nano) behind the
+ * `AIProvider` contract. The API is Chrome-only and not yet in the DOM lib
+ * types, so it is structurally typed here ({@link LanguageModelLike}); the
+ * provider takes an injected session so it's testable without a browser, and
+ * `createPromptApiProvider` resolves one from `globalThis.LanguageModel`.
+ *
+ * The Prompt API has no tool calling, so this reports `tools: false` →
+ * propose-only writes (see `writeModeFor`).
+ */
+
+/** Minimal shape of a Chrome `LanguageModel` session. */
+interface LanguageModelSessionLike {
+    prompt(input: string): Promise<string>;
+    promptStreaming(input: string): AsyncIterable<string>;
+}
+/** The four states Chrome's `LanguageModel.availability()` can report. */
+type PromptApiAvailability = 'unavailable' | 'downloadable' | 'downloading' | 'available';
+/** A download-progress monitor passed to `create({ monitor })`. */
+interface LanguageModelMonitor {
+    addEventListener(type: 'downloadprogress', listener: (event: {
+        loaded: number;
+    }) => void): void;
+}
+/** Minimal shape of the global `LanguageModel` factory. */
+interface LanguageModelLike {
+    availability(): Promise<PromptApiAvailability>;
+    create(options?: {
+        initialPrompts?: Array<{
+            role: string;
+            content: string;
+        }>;
+        /** Observe the on-device model download (fires `downloadprogress`). */
+        monitor?: (monitor: LanguageModelMonitor) => void;
+    }): Promise<LanguageModelSessionLike>;
+}
+interface PromptApiProviderOptions {
+    session: LanguageModelSessionLike;
+    model?: string;
+}
+declare class PromptApiProvider implements AIProvider {
+    readonly name = "prompt-api";
+    private readonly session;
+    private readonly model;
+    constructor(options: PromptApiProviderOptions);
+    generate(prompt: string): Promise<string>;
+    stream(request: AIGenerateRequest): AsyncIterable<AIStreamChunk>;
+    getCapabilities(): AIModelCapabilities;
+}
+/**
+ * Resolve a provider from the global `LanguageModel`, downloading the model if
+ * needed. Returns null if the API is unavailable (not Chrome, or no model).
+ */
+declare function createPromptApiProvider(factory?: LanguageModelLike): Promise<PromptApiProvider | null>;
+/**
+ * Raw availability of the on-device model, or `'unavailable'` when the API is
+ * absent (not Chrome) or the probe throws. Unlike `createPromptApiProvider`,
+ * this distinguishes `'downloadable'`/`'downloading'` from `'available'` so the
+ * UI can offer a download gesture instead of silently reporting "unavailable".
+ */
+declare function promptApiAvailability(factory?: LanguageModelLike): Promise<PromptApiAvailability>;
+/**
+ * Trigger the on-device model download from a **user gesture**, reporting
+ * progress as a fraction in [0, 1]. Chrome gates the download behind a user
+ * activation, so this must be called from a click handler — not an effect.
+ * Resolves `true` once a session is creatable; the runtime rebuilds its own
+ * session once detection re-flips to `'available'`. Returns `false` when the
+ * API is absent; throws (for the caller to `.catch`) if `create()` rejects.
+ */
+declare function downloadPromptApiModel(onProgress?: (fraction: number) => void, factory?: LanguageModelLike): Promise<boolean>;
+
 /**
  * Service Plugin Types
  *
@@ -1692,93 +5416,6 @@ interface IProcessManager {
     off<K extends keyof ProcessManagerEvents>(event: K, listener: ProcessManagerEvents[K]): void;
 }
 
-/**
- * Local HTTP API Server
- *
- * Provides a REST API for external integrations (N8N, MCP, etc.) to interact
- * with xNet data. Runs on localhost only (port 31415 by default).
- *
- * This is designed to run in the Electron main process.
- */
-/**
- * Node store interface (minimal subset needed by API)
- */
-interface NodeStoreAPI {
-    get(id: string): Promise<NodeData | null>;
-    list(options?: {
-        schemaId?: string;
-        limit?: number;
-        offset?: number;
-    }): Promise<NodeData[]>;
-    create(options: {
-        schemaId: string;
-        properties: Record<string, unknown>;
-    }): Promise<NodeData>;
-    update(id: string, options: {
-        properties: Record<string, unknown>;
-    }): Promise<NodeData>;
-    delete(id: string): Promise<void>;
-    subscribe(listener: (event: NodeChangeEventData) => void): () => void;
-}
-/**
- * Schema registry interface (minimal subset needed by API)
- */
-interface SchemaRegistryAPI {
-    getAllIRIs(): string[];
-    get(iri: string): Promise<SchemaData | null>;
-}
-/**
- * Node data returned by API
- */
-interface NodeData {
-    id: string;
-    schemaId: string;
-    properties: Record<string, unknown>;
-    deleted: boolean;
-    createdAt: number;
-    updatedAt: number;
-}
-/**
- * Schema data returned by API
- */
-interface SchemaData {
-    iri: string;
-    name: string;
-    properties: Record<string, unknown>;
-}
-/**
- * Node change event data
- */
-interface NodeChangeEventData {
-    change: {
-        type: string;
-    };
-    node: NodeData | null;
-    isRemote: boolean;
-}
-/**
- * API configuration
- */
-interface LocalAPIConfig {
-    /** Port to listen on (default: 31415) */
-    port?: number;
-    /** Host to bind to (default: '127.0.0.1') */
-    host?: string;
-    /** API token for authentication (optional) */
-    token?: string;
-    /**
-     * Allowed CORS origins (default: none).
-     * Set to specific origins like ['http://localhost:3000'] for local dev,
-     * or ['*'] to allow all origins (not recommended for production).
-     * Empty array or undefined disables CORS entirely.
-     */
-    allowedOrigins?: string[];
-    /** NodeStore instance */
-    store: NodeStoreAPI;
-    /** SchemaRegistry instance */
-    schemas: SchemaRegistryAPI;
-}
-
 /**
  * Service Client
  *
@@ -1986,7 +5623,15 @@ declare function createWebhookEmitter(store: NodeStoreAPI): WebhookEmitter;
  */
 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>;
@@ -1999,7 +5644,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
@@ -2009,6 +5658,9 @@ interface MCPResource {
     name: string;
     description?: string;
     mimeType?: string;
+    risk?: string;
+    requiredScopes?: string[];
+    dynamic?: boolean;
 }
 /**
  * MCP Request from client
@@ -2038,10 +5690,85 @@ 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') */
     version?: string;
 }
 
-export { AIGenerationError, type AIProvider, type AIProviderConfig, type AIProviderOptions, type AIProviderType, type AIScriptRequest, type AIScriptResponse, AnthropicProvider, type ArrayHelpers, type BlockContribution, type BlockProps, type CommandContribution, ContributionRegistry, type DeliveryResult, type Disposable$1 as Disposable, type EditorContribution, type ExtensionContext, type ExtensionStorage, type FlatNode, type FormatHelpers, type IProcessManager, type LocalAPIConfig, type MCPPropertySchema, type MCPRequest, type MCPResource, type MCPResponse, type MCPServerConfig, type MCPTool, type MathHelpers, MiddlewareChain, type NodeChangeEvent, type NodeChangeEventData, type NodeData, type NodeStoreAPI, type NodeStoreMiddleware, OllamaProvider, OpenAIProvider, type PendingChange, type Platform, type PlatformCapabilities, type PluginContributions, PluginError, type PluginNode, type PluginNodeChangeEvent, type PluginNodeChangeListener, type PluginPermissions, PluginRegistry, PluginSchema, type PluginStatus, PluginValidationError, type ProcessManagerEvents, type PropertyCellProps, type PropertyEditorProps, type PropertyHandler, type PropertyHandlerContribution, type QueryFilter, type RegisteredPlugin, SERVICE_IPC_CHANNELS, type SandboxOptions, type SchemaContribution, type SchemaData, type SchemaDefinition, type SchemaProperty, type SchemaRegistryAPI, type ScriptContext, ScriptError, type ScriptExecutionResult, ScriptGenerationError, ScriptGenerator, type ScriptGeneratorOptions, type ScriptNode, type ScriptNodeChangeEvent, type ScriptOutputType, ScriptRunner, type ScriptRunnerOptions, ScriptSandbox, ScriptSchema, type ScriptStore, ScriptTimeoutError, type ScriptTriggerType, ScriptValidationError, type ServiceClient, type ServiceCommunication, type ServiceDefinition, type ServiceHealthCheck, type ServiceLifecycle, type ServiceOutputEvent, type ServiceProcessConfig, type ServiceProvides, type ServiceState, type ServiceStatus, type ServiceStatusEvent, type SettingContribution, type SettingsPanelProps, ShortcutManager, type SidebarContribution, type SlashCommandContext, type SlashCommandContribution, type TelemetryReporter, type TextHelpers, type ToolbarContribution, TypedRegistry, type ValidationResult, type ViewContribution, type ViewProps, type WebhookConfig, WebhookEmitter, type WebhookPayload, type XNetExtension, buildRetryPrompt, buildScriptPrompt, createAIProvider, createExtensionContext, createExtensionStorage, createScriptContext, createServiceClient, createWebhookEmitter, defineExtension, executeScript, generateScript, getPlatformCapabilities, getShortcutManager, installShortcutHandler, isOllamaAvailable, isScriptNode, isServiceClientAvailable, listOllamaModels, quickSafetyCheck, validateManifest, validateScript, validateScriptAST };
+/**
+ * Right to Leave (xNet Humane Internet Charter §Exit, exploration 0234).
+ *
+ * Leaving is a right, not a retention funnel. `leaveWithEverything` bundles
+ * everything you'd need to recreate yourself elsewhere — your whole workspace,
+ * your portable identity, and a README on how to re-import — into one archive.
+ * `deleteDay` is the honest, irreversible version: stop feeding the system.
+ *
+ * This module is the orchestration; the app injects the real capabilities
+ * (AiWorkspaceExporter for the workspace, the identity keystore, hub purge, OPFS
+ * destroy, consent-gated telemetry). Keeping them as ports makes the policy —
+ * "no confirmshaming, take everything, the local copy is yours" — testable in
+ * isolation.
+ */
+/** The capabilities the app wires in. Only `exportWorkspace`/`exportIdentity` are required. */
+interface RightToLeavePorts {
+    /** The full workspace as relative-path → file-content (e.g. via AiWorkspaceExporter). */
+    exportWorkspace(): Promise<Record<string, string>>;
+    /** The portable identity bundle (did:key + recovery), JSON-serializable. */
+    exportIdentity(): Promise<unknown>;
+    /** Tombstone the user's copies on every connected hub. Absent ⇒ offline-only user. */
+    purgeRemoteCopies?(): Promise<void>;
+    /** Wipe the local master copy (OPFS/SQLite). Absent ⇒ nothing local to wipe. */
+    destroyLocal?(): Promise<void>;
+    /** Record a non-identifying `account.left` signal (consent-gated). */
+    recordLeft?(): void;
+}
+interface LeaveBundle {
+    /** relative path → file content; a complete, portable copy of you. */
+    files: Record<string, string>;
+    exportedAt: string;
+}
+interface DeleteDayOptions {
+    /** Keep the local master copy on this device (export-and-go) vs. full wipe. */
+    keepLocal: boolean;
+    /** Injected timestamp (ISO) — no implicit clock, so the result is deterministic. */
+    now: string;
+}
+interface DeleteDayResult {
+    remotePurged: boolean;
+    localWiped: boolean;
+    recordedLeft: boolean;
+}
+declare const LEAVE_README = "# Your xNet data \u2014 yours to keep\n\nThis archive is a complete, portable copy of your workspace.\n\n- `workspace/` \u2014 every page, database, canvas, and node, plus a manifest.\n- `identity.did.json` \u2014 your portable did:key identity and recovery material.\n\nTo continue elsewhere: run your own hub (`xnet-hub start`) or any xNet-compatible\nbackend, then import this archive. Your did:key works on any hub \u2014 there is no\naccount to transfer and nothing held back. You don't need our permission to leave.\n";
+/**
+ * Everything you'd need to recreate yourself elsewhere, in one bundle. There is
+ * deliberately no "are you sure you'll miss out?" — this is a right, not a funnel.
+ */
+declare function leaveWithEverything(ports: RightToLeavePorts, opts: {
+    now: string;
+}): Promise<LeaveBundle>;
+/**
+ * Delete Day: stop feeding the system, for real. Tombstones remote copies on
+ * every hub and (unless `keepLocal`) wipes the local master too. The only signal
+ * emitted is an anonymous `account.left` — never anything that identifies who.
+ */
+declare function deleteDay(ports: RightToLeavePorts, opts: DeleteDayOptions): Promise<DeleteDayResult>;
+
+export { type AIComplexityLevel, type AICostModel, type AIGenerateRequest, type AIGenerateResponse, AIGenerationError, type AIMessage, type AIMessageRole, type AIModelCapabilities, type AIModelQuality, type AIPrivacyLevel, type AIProvider, type AIProviderConfig, type AIProviderOptions, AIProviderRouter, type AIProviderRouterOptions, type AIProviderType, type AIProviderUsage, AIRTABLE_CONNECTOR_ID, type AIRiskLevel, type AIScriptRequest, type AIScriptResponse, type AIStreamChunk, type AIToolCall, type AIToolSpec, type AIUsage, AI_GENERATED_PROVENANCE, AI_RISK_LEVELS, AI_SCOPES, AI_TARGET_KINDS, ALLOWED_PLUGIN_LICENSES, type ActionContext, type ActionDefinition, ActionDefinitionError, ActionDispatchError, type ActionEvent, ActionSsrfError, type ActionTrigger, type AgentToolContribution, type AgentToolInputSchema, type AiAgentApproval, type AiAgentApprovalRequestInput, type AiAgentApprovalResolveInput, type AiAgentApprovalStatus, type AiAgentBackgroundJob, type AiAgentBackgroundJobInput, type AiAgentBackgroundJobRunner, type AiAgentBackgroundJobStatus, type AiAgentDisplayState, type AiAgentDisplayStateKind, type AiAgentEvent, type AiAgentEventType, type AiAgentOrchestratorMode, type AiAgentRunSelectionTurnInput, type AiAgentRunTurnInput, type AiAgentRunTurnResult, AiAgentRuntime, type AiAgentRuntimeConfig, type AiAgentRuntimeListener, type AiAgentRuntimeSnapshot, type AiAgentRuntimeStorage, type AiAgentSelectionContext, type AiAgentSelectionKind, type AiAgentTelemetrySnapshot, type AiAgentThread, type AiAgentThreadCreateInput, type AiAgentThreadStatus, type AiAgentTurn, type AiAgentTurnRole, type AiAgentTurnStatus, type AiAssistMode, type AiAuditEvent, type AiAuthoredPlugin, AiAuthoringError, AiBudgetError, type AiCallableTool, type AiChangeSet, type AiCommandExposure, type AiContextPack, type AiContextPackResource, type AiContextRetriever, type AiContextSeed, type AiDatabaseMutationApplyResult, type AiExtraTool, type AiJsonSchema, type AiJsonSchemaType, type AiMutationPlan, type AiMutationPlanStatus, type AiOperation, type AiPageMarkdownApplyAdapter, type AiPageMarkdownApplyAdapterInput, type AiPageMarkdownApplyAdapterResult, type AiPageMarkdownApplyResult, type AiPageMarkdownRollbackResult, type AiPluginPipelineInput, type AiPluginPipelinePorts, type AiPluginPipelineResult, type AiResource, type AiResourceContent, type AiRetrievedNode, type AiRiskLevel, type AiScope, type AiSearchOptions, type AiSearchResult, type AiSurfaceLimits, AiSurfaceService, type AiSurfaceServiceConfig, type AiTargetKind, type AiToolCallResult, type AiToolDefinition, type AiValidationResult, type AirtableConnectorOptions, type AllowedPluginLicense, AnthropicProvider, type ArrayHelpers, type BlockContribution, type BlockProps, CANVAS_PLUGIN_FIXTURES, CHANNEL_SCHEMA, CHAT_MESSAGE_SCHEMA, CONNECTOR_CATEGORY, CONNECTOR_META, CRM_CANVAS_PLUGIN_FIXTURE, type CanvasCardContribution, type CanvasContribution, type CanvasContributionBase, type CanvasContributionPermission, type CanvasEdgeContribution, type CanvasErpPrototypeAuditEntry, type CanvasErpPrototypeAuditOperation, type CanvasErpPrototypeAuditSource, type CanvasErpPrototypeCard, type CanvasErpPrototypeCommand, type CanvasErpPrototypeEdge, type CanvasErpPrototypeEntityKind, type CanvasErpPrototypeLayoutKind, type CanvasErpPrototypeQueryFrame, type CanvasErpPrototypeQueryPredicate, type CanvasErpPrototypeRect, type CanvasErpPrototypeRisk, type CanvasErpPrototypeRiskSummary, type CanvasErpPrototypeScenario, type CanvasErpPrototypeStatus, type CanvasIngestInputKind, type CanvasIngestorContribution, type CanvasInspectorContribution, type CanvasInspectorPlacement, type CanvasLayoutContribution, type CanvasLayoutScope, type CanvasPluginFixture, type CanvasPluginFixtureCardSample, type CanvasPluginFixtureKind, type CanvasPluginPermissionDecisionStatus, type CanvasPluginPermissionGateDecision, type CanvasPluginPermissionGateInput, type CanvasPluginPermissionPrompt, type CanvasPluginPermissionPromptOption, type CanvasPluginPromptMode, type CanvasPluginSandboxDecision, type CanvasPluginSandboxDomAccess, type CanvasPluginSandboxKind, type CanvasPluginSandboxMutationAccess, type CanvasPluginSandboxNetworkAccess, type CanvasPluginSandboxOutput, type CanvasPluginSandboxOutputKind, type CanvasPluginSandboxOutputValidation, type CanvasPluginSandboxPolicy, type CanvasPluginSandboxRequest, type CanvasPluginWorkspacePolicy, type CanvasPreviewTier, type CanvasRendererSandboxContribution, type CanvasTemplateCategory, type CanvasTemplateContribution, type CanvasToolContribution, type CanvasToolGroup, CapabilityError, type CommandContext, type CommandContribution, CommandRegistry, type CommandScope, type ConnectorArtifacts, type ConnectorCadence, type ConnectorDefinition, ConnectorDefinitionError, type ConnectorDetection, type ConnectorEnv, type ConnectorFetch, type ConnectorInstallGate, type ConnectorStore, type ConnectorSyncContext, ConnectorSyncError, type ConnectorSyncResult, type ConnectorSyncSpec, type ConnectorTier, type ConnectorToolDescriptor, type ConsentDecision, type ConsentLine, ContributionRegistry, DEFAULT_PLUGIN_LICENSE, type DefinedAction, type DefinedConnector, type DeleteDayOptions, type DeleteDayResult, type DeliveryResult, DependencyCycleError, type DependencyNode, type Disposable$1 as Disposable, ERP_CANVAS_PLUGIN_FIXTURE, EXTERNAL_ITEM_SCHEMA, type EditorContribution, type EditorSchemaRisk, type EmailActionOptions, type ExtensionContext, type ExtensionStorage, FEED_ITEM_SCHEMA, type FeatureModule, type FeedEntry, type FetchJson, type FetchLike, type FlatNode, type FormatHelpers, GITHUB_CONNECTOR_ID, type GeneratedScript, type GithubConnectorOptions, type GuardableConnectorStore, type IProcessManager, type ImporterContribution, type InstallOptions, LEAVE_README, LINEAR_CONNECTOR_ID, type LabRunOutcome, type LadderRuntimeTier, type LanguageModelLike, type LanguageModelMonitor, type LanguageModelSessionLike, type LeaveBundle, type LicenseCheckResult, LicenseRequiredError, type LinearConnectorOptions, type LocalAPIConfig, type LocalAPITokenConfig, type LocalAPITokenScope, type LocalAPITokenSummary, type LocalServerProbe, MARKETPLACE_PROVENANCE, type MCPPropertySchema, type MCPRequest, type MCPResource, type MCPResponse, type MCPServerConfig, type MCPTool, MEDIA_PROVIDER_CANVAS_PLUGIN_FIXTURE, type ManagedBudgetSnapshot, ManagedProvider, type ManagedProviderOptions, MarketplaceClient, type MarketplaceClientOptions, type MarketplaceEntry, type MarketplaceSort, type MathHelpers, type MentionProviderContribution, type MentionSuggestion, MiddlewareChain, type MissingDependency, type ModuleCapabilities, NOTION_CONNECTOR_ID, type NodeChangeEvent, type NodeChangeEventData, type NodeData, type NodeStoreAPI, type NodeStoreMiddleware, type NotionConnectorOptions, OllamaProvider, OpenAICompatibleProvider, type OpenAICompatibleProviderOptions, OpenAIProvider, type PendingChange, type Platform, type PlatformCapabilities, type PluginContributions, PluginError, type PluginNode, type PluginNodeChangeEvent, type PluginNodeChangeListener, type PluginPermissions, type PluginPricing, type PluginRating, PluginRegistry, type PluginRunInput, type PluginRunResult, PluginRuntimeError, type PluginRuntimeLadder, PluginSchema, type PluginStatus, PluginValidationError, type ProcessManagerEvents, type PromptApiAvailability, PromptApiProvider, type PromptApiProviderOptions, type PropertyCellProps, type PropertyEditorProps, type PropertyHandler, type PropertyHandlerContribution, type Provenance, type ProvenanceResult, type ProvenanceVerifier, type QueryFilter, RSS_CONNECTOR_ID, type RatingSummary, type RecommendOptions, type RegisteredPlugin, type ResolveMentionOptions, type RightToLeavePorts, type RssConnectorOptions, type RunActionPorts, type RunConnectorSyncPorts, type RunPluginCodeInput, SCAFFOLD_SYSTEM_GUARD, SERVICE_IPC_CHANNELS, SLACK_CONNECTOR_ID, type SandboxOptions, ScaffoldError, type ScaffoldResult, type ScaffoldSpec, type ScaffoldTemplate, type SchemaContribution, type SchemaData, type SchemaDefinition, type SchemaProperty, type SchemaRegistryAPI, type ScriptContext, ScriptError, type ScriptExecutionResult, type ScriptExecutor, ScriptGenerationError, ScriptGenerator, type ScriptGeneratorOptions, type ScriptNode, type ScriptNodeChangeEvent, type ScriptOutputType, ScriptRunner, type ScriptRunnerOptions, ScriptSandbox, ScriptSchema, type ScriptStore, ScriptTimeoutError, type ScriptToManifestInput, type ScriptTriggerType, ScriptValidationError, type SemVer, type ServiceClient, type ServiceCommunication, type ServiceDefinition, type ServiceHealthCheck, type ServiceLifecycle, type ServiceOutputEvent, type ServiceProcessConfig, type ServiceProvides, type ServiceState, type ServiceStatus, type ServiceStatusEvent, type SettingContribution, type SettingsPanelProps, ShortcutManager, type SidebarContribution, type SlackConnectorOptions, type SlashCommandContext, type SlashCommandContribution, type StatusBarContribution, type TelemetryReporter, type TestHarnessOptions, type TestNodeStore, type TestPluginHarness, type TextHelpers, type ToolCallingFidelity, type ToolbarContribution, TypedRegistry, type UsageSignal, type ValidationResult, type VerifyProvenanceInput, type ViewContribution, type ViewProps, type WebLLMEngineLike, WebLLMProvider, type WebLLMProviderOptions, type WebhookConfig, WebhookEmitter, type WebhookOutOptions, type WebhookPayload, type WidgetContribution, type WidgetContributionConfigField, type WidgetContributionProps, type WorkspaceCommand, type WrapCliConnectorOptions, type WriteMode, XNET_MARKDOWN_DIRECTIVE_SPECS, type XNetExtension, type XNetMarkdownDiffLine, type XNetMarkdownDiffLineKind, type XNetMarkdownDirective, type XNetMarkdownDirectiveSpec, type XNetMarkdownReviewDiff, type XNetPageMarkdownFrontmatter, type XNetPageMarkdownValidation, type XNetPageMarkdownValidationOptions, agentToolToExtraTool, agentToolsAsExtraTools, aggregateRatings, assertNetwork, assertPublicUrl, assertSchemaWrite, assistTurnProvenance, attachAiPlanValidation, buildAirtableConnector, buildDiscordAction, buildEmailAction, buildGithubConnector, buildLinearConnector, buildNotionConnector, buildRetryPrompt, buildRssConnector, buildScriptPrompt, buildSlackConnector, buildSlackWebhookAction, buildTelegramAction, buildWebhookOutAction, classifyAiAgentDisplayState, compareVersions, composeAssistSystemPrompt, connectorAsImporter, connectorMarketplaceEntry, contributionsAsAiTools, createAIProvider, createAIProviderRouter, createAiAgentRuntime, createAiChangeSet, createAiOperation, createAiSurfaceService, createAiValidationResult, createCanvasErpPrototypeRiskSummary, createCanvasErpPrototypeScenario, createCanvasPluginFixtureCards, createCanvasPluginFixtureManifests, createCanvasPluginPermissionPrompt, createCanvasPluginSandboxPolicy, createCanvasPreviewSandboxRequest, createCanvasRendererSandboxRequest, createExtensionContext, createExtensionStorage, createManagedProvider, createMemoryAiAgentRuntimeStorage, createPromptApiProvider, createScriptContext, createServiceClient, createTestNodeStore, createTestPluginHarness, createWebLLMProvider, createWebhookEmitter, defaultLocalServerProbes, defineAction, defineConnector, defineExtension, defineFeatureModule, deleteDay, describeCapabilities, detectConnectors, downloadPromptApiModel, emitConnectorArtifacts, evaluateCanvasPluginPermissionGate, evaluateCanvasPluginSandboxRequest, evaluateConnectorInstall, evaluateInstallConsent, executeScript, failClosedVerifier, filterByCategory, findEditorSchemaRisks, findMissingDependencies, generateScript, getCanvasErpPrototypeAuditEntriesForCard, getCanvasErpPrototypeCardsForFrame, getCanvasPluginFixture, getCommandRegistry, getPlatformCapabilities, getShortcutManager, getXNetMarkdownDirectiveSpecs, guardStore, guardedActionFetch, guardedFetch, hasUpdate, importerAdapters, installCommandHandler, installShortcutHandler, isAiRiskLevel, isAiScope, isAiTargetKind, isAllowedPluginLicense, isHostCompatible, isNetworkAllowed, isOllamaAvailable, isPaidPricing, isSchemaDefiningExtension, isSchemaReadAllowed, isSchemaWriteAllowed, isScriptNode, isServiceClientAvailable, ladderTierForTrust, leaveWithEverything, listOllamaModels, matchSchemaIri, normalizeCanvasPluginWorkspacePolicy, packageName, parseAiMutationPlan, parseFeed, parseVersion, parseXNetPageFrontmatter, pascalCase, pickBestConnector, pluginLicenseText, probeOpenAiCompatible, promptApiAvailability, quickSafetyCheck, recommendExtensions, renderEvent, renderMarkdownLineDiff, renderMarkdownReviewDiff, renderSelectionPrompt, resolveImporters, resolveInstallOrder, resolveMentionProviders, runAction, runAiPluginPipeline, runConnectorSync, runPluginCode, satisfiesRange, scaffoldPlugin, scriptToPluginManifest, searchMarketplace, serializeAiMutationPlan, shortSchemaName, shouldDispatch, sortMarketplace, stripXNetPageFrontmatter, summarizeProvenance, validateAiMutationPlan, validateCanvasPluginSandboxOutput, validateManifest, validateScript, validateScriptAST, validateXNetPageMarkdown, verifyProvenance, warnOnEditorSchemaRisks, wrapCliConnector, writeModeFor };