@agent-wire/terminal 1.7.5 → 1.7.7

package/dist/mcp-server.js

@@ -1,18 +1,20 @@
+import { isCreditValue } from './contracts/credit-amount.js';
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { createServer } from 'node:http';
 import { z } from 'zod';
+const creditAmountSchema = (minimum) => z.union([z.number().int(), z.string()]).refine(value => isCreditValue(value, minimum), 'Expected safe integer or int64 decimal credit string');
 import { hostname } from 'os';
 import { createHash, randomUUID } from 'crypto';
 import { readFile, writeFile, rename as fsRename, mkdir as fsMkdir, stat as fsStat } from 'fs/promises';
 import { join, isAbsolute } from 'path';
 import { loadConfig, saveConfig, CONFIG_DIR } from './config.js';
 import { loadSlotConfig, saveSlotConfig, migrateLegacyAgentsToSlots } from './slots.js';
-import { WireAPI } from './api.js';
+import { WireAPI, RegistrationError } from './api.js';
 import { shapeStatus, shapeRead, shapeInspect, shapeGraph, shapeCorpora, shapeMyContributions, shapeEarnings, shapeOpportunities, shapeRate, shapePatrolScan, shapeNotifications, shapeTasks, shapeMessages, } from './response-shaper.js';
 import { startBackgroundWorkLoop } from './background-worker.js';
-import { parseToolDefinition, dedupeToolDefinitions, fingerprintToolDefinitions, jsonSchemaToZodShape, } from './tool-projection.js';
+import { parseToolDefinition, fetchCatalogDefinitionItems, invokeToolDefinition, dedupeToolDefinitions, withToolDefinitionAliases, fingerprintToolDefinitions, jsonSchemaToZodShape, } from './tool-projection.js';
 import { 
 // Mission #1.5-rev2: agents/ cache fully retired. loadAgentIdentity /
 // saveAgentIdentity / deleteAgentIdentity are no longer imported here;
@@ -21,7 +23,7 @@ import {
 // migration window.
 loadDeviceRecord, saveDeviceRecord, deleteDeviceRecord, loadAuthPending, saveAuthPending, deleteAuthPending, getStableDeviceFingerprint, hasAnyLocalIdentityForEmail, acquireIdentityLock, releaseIdentityLock, } from './identity.js';
 import { acquireLock, releaseLock, isWorkerRunning } from './lockfile.js';
-import { walkDirectory, computeDiff, pushFiles, pullFiles, parseManifest, serializeManifest, updateManifest, paginateAll, } from './sync/index.js';
+import { walkDirectory, computeDiff, pushFiles, pullFiles, parseManifest, serializeManifest, updateManifest, paginateAll, generatePreviewJson, } from './sync/index.js';
 import { WIRE_HELP_POINTER } from './help-pointer.js';
 import { pullLocalSubscriptions } from './local-pull.js';
 const SURFACE_REFRESH_TTL_MS = 60_000;
@@ -82,9 +84,7 @@ function normalizeApiRootPath(path) {
     return withSlash.replace(/^\/api\/v1(?=\/|$)/, '') || '/';
 }
 async function fetchSurfaceConfigItems(api) {
-    const queries = ['surface_config', 'dispatcher_bound_surface_config', 'lookup_surface'];
-    const responses = await Promise.all(queries.map((text) => api.query({ text, domain: 'all', limit: 100, sort: 'recency' })));
-    return responses.flatMap(extractQueryItems);
+    return fetchCatalogDefinitionItems(api, 'surface');
 }
 async function refreshSubstrateSurfaces(api) {
     const items = await fetchSurfaceConfigItems(api);
@@ -157,7 +157,18 @@ function toolsAvailableMsg(verificationStatus) {
 function looksLikeDeviceAuthFailure(error) {
     if (!error)
         return false;
-    return /\b(401|410)\b|revoked|device authorization|device secret|unauthorized/i.test(error.message);
+    if (/\b410\b|wire_roster_deleted/i.test(error.message))
+        return false;
+    // Endpoint removal (410) does not revoke device authorization.
+    return /\b401\b|revoked|device authorization|device secret|unauthorized/i.test(error.message);
+}
+function looksLikeRetiredRoster(error) {
+    if (!error)
+        return false;
+    // The /wire/roster endpoint was intentionally retired (server returns 410 wire_roster_deleted,
+    // "use activity observations instead"). A 410 here is EXPECTED, not a fault — callers should
+    // degrade quietly rather than surface it as a failure. (patent-guy doorbell #4)
+    return /wire_roster_deleted|\b410\b/i.test(error.message);
 }
 function buildResumeResponse(params) {
     const resumedStatus = typeof params.verificationStatus === 'string'
@@ -203,6 +214,7 @@ export const __mcpSurfaceTestInternals = {
 };
 export async function startMcpServer(options) {
     const loadedConfig = loadConfig();
+    loadedConfig.apiUrl = process.env.WIRE_API_URL ?? loadedConfig.apiUrl;
     // MCP identity is slot-owned now. Keep node/base config, but deliberately
     // strip any legacy config/env agent token before constructing pre-pin APIs.
     const config = { ...loadedConfig, apiToken: '' };
@@ -215,6 +227,10 @@ export async function startMcpServer(options) {
     // tool handlers go through the `api` closure variable below — bootApi
     // is for identity-resolution operations only.
     const bootApi = new WireAPI(config, threadId);
+    // A configured token can discover tools before identify, but cannot select
+    // this process's identity. Calls still require the explicit slot pin.
+    const discoveryApi = new WireAPI({ ...config,
+        apiToken: process.env.WIRE_API_TOKEN ?? loadedConfig.apiToken }, threadId);
     // `api` starts as bootApi (no agent token). Tool handlers MUST gate
     // through requireIdentity() before using it; that gate ensures the
     // closure has been promoted to the slot's authenticated WireAPI by
@@ -484,34 +500,11 @@ export async function startMcpServer(options) {
         dynamicSurfaceTools.set(surface.toolName, { ...registered, surface });
     }
     async function fetchToolDefinitions() {
-        const response = await api.query({ text: 'tool_definition', domain: 'all', limit: 100, sort: 'recency' });
-        const items = extractQueryItems(response);
-        const toolItems = items.filter((item) => item.type === 'tool_definition');
-        // Query items are teasers — structured_data is absent. Hydrate each
-        // tool_definition item with a full contribution read so parseToolDefinition
-        // receives the complete structured_data payload.
-        const hydrated = await Promise.all(toolItems.map(async (item) => {
-            const identifier = item.handle_path ?? item.id;
-            if (!identifier)
-                return null;
-            try {
-                const full = await api.accessContribution(identifier);
-                return {
-                    type: full.type,
-                    title: full.title,
-                    handle_path: (full.handle_path ?? identifier),
-                    structured_data: full.structured_data,
-                };
-            }
-            catch (err) {
-                console.error(`[wire-mcp] fetchToolDefinitions: failed to hydrate ${identifier}: ${err.message}`);
-                return null;
-            }
-        }));
-        const definitions = dedupeToolDefinitions(hydrated
+        const hydrated = await fetchCatalogDefinitionItems(processSlot ? api : discoveryApi, 'tool_definition');
+        const definitions = withToolDefinitionAliases(dedupeToolDefinitions(hydrated
             .filter((item) => item !== null)
             .map((item) => parseToolDefinition(item))
-            .filter((def) => def !== null));
+            .filter((def) => def !== null)));
         // Persist to disk cache (atomic write). Errors are non-fatal.
         void saveToolDefinitionsCache(definitions);
         return definitions;
@@ -546,7 +539,7 @@ export async function startMcpServer(options) {
         const registered = server.registerTool(def.toolName, {
             title: def.toolName,
             description: projectedToolDescription(def),
-            inputSchema: jsonSchemaToZodShape(def.parameterSchema),
+            inputSchema: z.object(jsonSchemaToZodShape(def.parameterSchema)).strict(),
             _meta: {
                 tool_definition_handle: def.configHandle,
                 binding: def.binding,
@@ -557,29 +550,7 @@ export async function startMcpServer(options) {
             if (gate)
                 return { content: [gate], isError: true };
             try {
-                let result;
-                if (def.binding.kind === 'api_method') {
-                    const method = api[def.binding.method ?? ''];
-                    if (typeof method !== 'function') {
-                        throw new Error(`tool_definition ${def.configHandle ?? def.toolName} binds to unknown adapter method '${def.binding.method}'`);
-                    }
-                    result = await method.call(api, params);
-                }
-                else {
-                    const httpMethod = def.binding.http_method ?? 'POST';
-                    if (def.binding.params === 'query' || httpMethod === 'GET') {
-                        const qs = new URLSearchParams();
-                        for (const [key, value] of Object.entries(params)) {
-                            if (value !== undefined)
-                                qs.set(key, String(value));
-                        }
-                        const suffix = qs.toString() ? `?${qs.toString()}` : '';
-                        result = await api.request(httpMethod, `${normalizeApiRootPath(def.binding.path ?? '/')}${suffix}`);
-                    }
-                    else {
-                        result = await api.request(httpMethod, normalizeApiRootPath(def.binding.path ?? '/'), params);
-                    }
-                }
+                const result = await invokeToolDefinition(def, api, params);
                 return {
                     content: [{
                             type: 'text',
@@ -611,10 +582,12 @@ export async function startMcpServer(options) {
                 removed: [],
             };
         }
-        const [surfaces, toolDefinitions] = await Promise.all([
-            refreshSubstrateSurfaces(api),
-            fetchToolDefinitions(),
-        ]);
+        // Surface discovery must not hide the core graph tools if it fails.
+        const toolDefinitions = await fetchToolDefinitions();
+        const surfaces = await refreshSubstrateSurfaces(processSlot ? api : discoveryApi).catch(err => {
+            console.error(`[wire-mcp] Surface discovery failed: ${err.message}`);
+            return surfaceCache?.surfaces ?? [];
+        });
         surfaceCache = { fetchedAt: Date.now(), surfaces };
         toolDefinitionCache = { fetchedAt: Date.now(), definitions: toolDefinitions };
         const removed = [];
@@ -682,9 +655,10 @@ export async function startMcpServer(options) {
             console.error(`[wire-mcp] tool-definitions-cache: warm-booted ${cachedDefs.length} projected tool(s) from disk`);
         }
         try {
-            const result = await refreshDynamicSurfaceTools(false);
+            const result = await refreshDynamicSurfaceTools(true);
             console.error(`[wire-mcp] Surface discovery (${source}): ${result.surfaces.length} surface_config tools registered`);
-            startToolRefreshPoller();
+            if (processSlot)
+                startToolRefreshPoller();
         }
         catch (err) {
             console.error(`[wire-mcp] Surface discovery failed (${source}): ${err.message}`);
@@ -769,7 +743,7 @@ export async function startMcpServer(options) {
         }, null, 2);
     }
     // ── Tool: wire_identify ──────────────────────────────────────────
-    server.tool('wire_pull', 'Pull subscribed Wire contribution bodies into local cache/skill files using ~/.wire-node/sync-manifest.json. Mirrors the agent-wire-terminal pull CLI.', {
+    server.tool('wire_pull', 'Pull subscribed Wire contribution bodies into local cache/skill files using ~/.wire-node/sync-manifest.json. Mirrors the @agent-wire/terminal pull CLI.', {
         manifest_path: z.string().optional().describe('Optional manifest path. Defaults to ~/.wire-node/sync-manifest.json.'),
         dry_run: z.boolean().optional().describe('Preview target writes without modifying local files.'),
         init: z.boolean().optional().describe('Create a default manifest first if one does not exist.'),
@@ -789,6 +763,25 @@ export async function startMcpServer(options) {
             return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
         }
     });
+    async function beginDeviceAuthorization(params) {
+        const fingerprint = getStableDeviceFingerprint();
+        await bootApi.requestDeviceAuth(params.operator_email, fingerprint, params.agent_message);
+        saveAuthPending(params.operator_email, {
+            email: params.operator_email,
+            deviceFingerprint: fingerprint,
+            requestedAt: new Date().toISOString(),
+            createNew: params.create_new || undefined,
+            agentName: params.name,
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify({
+                        status: 'check_email',
+                        message: `Device authorization code sent to ${params.operator_email}. Ask the operator for the 6-digit code from their email.`,
+                        next_step: 'Call wire_identify again with the same name and email, plus the device_code parameter containing the 6-digit code.',
+                        expires_in_minutes: 15,
+                    }, null, 2) }],
+        };
+    }
     server.tool('wire_identify', 'Identify yourself to the Wire. Must be called before any other Wire tools. ' +
         'First call: provide name + operator_email. If this is a new device, you will receive a ' +
         '"check_email" response — ask the operator for the 6-digit code from their email, ' +
@@ -918,7 +911,7 @@ export async function startMcpServer(options) {
                 catch { /* token dead */ }
                 if (me) {
                     // 1A: Verify cached identity matches requested name
-                    const serverName = me.name;
+                    const serverName = (me.identity?.name ?? me.name);
                     if (serverName && params.name && serverName.toLowerCase() !== params.name.toLowerCase()) {
                         // Stale slot file — server-side name doesn't match what
                         // the local file claims. Skip the slot file (it's
@@ -1039,13 +1032,24 @@ export async function startMcpServer(options) {
                         client: process.env.MCP_CLIENT_NAME || 'unknown',
                         session_started: new Date().toISOString(),
                     };
-                    const result = await bootApi.registerAgent({
-                        name: params.name,
-                        operator_email: params.operator_email,
-                        domains: ['all'],
-                        session_metadata: sessionMetadata,
-                        agent_message: params.agent_message,
-                    });
+                    let result;
+                    try {
+                        result = await bootApi.registerAgent({
+                            name: params.name,
+                            operator_email: params.operator_email,
+                            domains: ['all'],
+                            session_metadata: sessionMetadata,
+                            agent_message: params.agent_message,
+                        });
+                    }
+                    catch (err) {
+                        // An empty local cache says nothing about the operator's hub
+                        // identities. A conflict starts authorization on this new device.
+                        if (err instanceof RegistrationError && err.status === 409) {
+                            return await beginDeviceAuthorization({ ...params, create_new: false });
+                        }
+                        throw err;
+                    }
                     if (!result.api_token || !result.pseudo_id || !result.agent_id) {
                         const missing = [
                             !result.api_token && 'api_token', !result.pseudo_id && 'pseudo_id', !result.agent_id && 'agent_id',
@@ -1091,35 +1095,7 @@ export async function startMcpServer(options) {
                 }
                 // EXISTING OPERATOR, NEW DEVICE: initiate device auth
                 console.error(`[wire-mcp] Existing operator, no device secret — initiating device auth`);
-                const fingerprint = getStableDeviceFingerprint();
-                try {
-                    await bootApi.requestDeviceAuth(params.operator_email, fingerprint, params.agent_message);
-                }
-                catch (err) {
-                    return {
-                        content: [{ type: 'text', text: JSON.stringify({
-                                    status: 'error',
-                                    error: `Failed to request device authorization: ${err.message}`,
-                                }, null, 2) }],
-                        isError: true,
-                    };
-                }
-                saveAuthPending(params.operator_email, {
-                    email: params.operator_email,
-                    deviceFingerprint: fingerprint,
-                    requestedAt: new Date().toISOString(),
-                    createNew: params.create_new || undefined,
-                    agentName: params.name,
-                });
-                return {
-                    content: [{ type: 'text', text: JSON.stringify({
-                                status: 'check_email',
-                                message: `Device authorization code sent to ${params.operator_email}. Ask the operator for the 6-digit code from their email.`,
-                                next_step: 'Call wire_identify again with the same name and email, plus the device_code parameter containing the 6-digit code.',
-                                expires_in_minutes: 15,
-                                note: 'After authorization, your agent name will be verified against the roster.',
-                            }, null, 2) }],
-                };
+                return await beginDeviceAuthorization(params);
             }
             // ── 5. Have device secret — resume/register without requiring roster ─
             if (deviceRecord) {
@@ -1224,14 +1200,21 @@ export async function startMcpServer(options) {
                             lastSessionAt: null,
                             lastAccessedContributionId: null,
                         };
-                        return { content: [{ type: 'text', text: JSON.stringify({
-                                        status: 'registered',
-                                        identity: `${params.name} (pseudo-ID: ${result.pseudo_id})`,
-                                        verification_status: result.verification_status,
-                                        roster_warning: `Roster lookup failed (${rosterError.message}); registered directly via /register.`,
-                                        help: WIRE_HELP_POINTER,
-                                        tools_available: toolsAvailableMsg(result.verification_status),
-                                    }, null, 2) }] };
+                        const registered = {
+                            status: 'registered',
+                            identity: `${params.name} (pseudo-ID: ${result.pseudo_id})`,
+                            verification_status: result.verification_status,
+                            help: WIRE_HELP_POINTER,
+                            tools_available: toolsAvailableMsg(result.verification_status),
+                        };
+                        // The /wire/roster endpoint is intentionally retired (410 wire_roster_deleted), so
+                        // registering directly via /register is now the NORMAL path, not a fallback from a
+                        // fault — don't alarm the caller with a roster_warning for an expected 410. Surface a
+                        // warning only for an UNEXPECTED roster failure. (patent-guy doorbell #4)
+                        if (!looksLikeRetiredRoster(rosterError)) {
+                            registered.roster_warning = `Roster lookup failed (${rosterError.message}); registered directly via /register.`;
+                        }
+                        return { content: [{ type: 'text', text: JSON.stringify(registered, null, 2) }] };
                     }
                     if (looksLikeDeviceAuthFailure(resumeError) && looksLikeDeviceAuthFailure(rosterError)) {
                         deleteDeviceRecord(params.operator_email);
@@ -1449,7 +1432,7 @@ export async function startMcpServer(options) {
                 'Reputation is algorithmic and never manually adjusted.',
                 'Pseudo-IDs protect agent privacy. Master identity mappings are never publicly disclosed.',
                 'Self-dealing between your own agents is prohibited.',
-                'Credit purchases are final. Sell-back requires Stripe Connect verification. 15-minute rate lock on initiated sales.',
+                'Operators buy 1,000,000 credits per US dollar, in whole-dollar quantities from $4 to $1,000. New operators receive 5,000,000 welcome credits once. Refunds and disputes reverse the recorded purchase mint. Buyback is unimplemented and unavailable; its future ceiling is $0.50 per 1,000,000 credits, eligible only after the platform holds $200,000 cash.',
                 'AI-generated content may contain errors — independently verify important information.',
                 'Dispute resolution via binding arbitration (Delaware). 30-day opt-out window available.',
             ],
@@ -1591,9 +1574,21 @@ export async function startMcpServer(options) {
         }
     });
     // ── Tool: wire_corpora (split from wire_discover — corpus browser) ──
-    server.tool('wire_corpora', 'Browse source corpora. List all corpora, or list documents within a specific corpus. Filter by visibility. FREE.', {
+    server.tool('wire_corpora', 'Browse or create source corpora. List corpora, list documents within a corpus, inspect health/revenue, or create a corpus. FREE except writes require approval.', {
+        action: z.enum(['list', 'documents', 'create', 'health', 'revenue', 'bulk_ingest']).optional().describe('Action to perform. Defaults to documents when slug is present, otherwise list.'),
         slug: z.string().optional().describe('Corpus slug to browse. Omit to list all corpora.'),
+        title: z.string().optional().describe('Corpus title for create.'),
+        description: z.string().optional().describe('Corpus description for create.'),
+        material_class: z.string().optional().describe('Corpus material class for create.'),
         visibility: z.enum(['public', 'private', 'all']).optional().describe('Filter by visibility (default: public)'),
+        themes: z.array(z.string()).optional().describe('Optional corpus themes for create.'),
+        default_author_share: z.number().optional().describe('Default author revenue share for create.'),
+        default_steward_share: z.number().optional().describe('Default steward revenue share for create.'),
+        split_justification: z.string().optional().describe('Revenue split justification for create.'),
+        provenance_note: z.string().optional().describe('Provenance note for create.'),
+        manifest: z.record(z.unknown()).optional().describe('Optional corpus manifest for create.'),
+        days: z.number().optional().describe('Revenue lookback days for revenue action.'),
+        documents: z.array(z.record(z.unknown())).optional().describe('Documents for bulk_ingest action.'),
         limit: z.number().optional().describe('Max results'),
         offset: z.number().optional().describe('Pagination offset'),
     }, async (params) => {
@@ -1602,13 +1597,54 @@ export async function startMcpServer(options) {
             return { content: [gate], isError: true };
         try {
             let result;
-            if (params.slug) {
-                result = await api.getCorpusDocuments(params.slug, params.limit, params.offset);
-            }
-            else {
-                result = await api.listCorpora();
+            const action = params.action ?? (params.slug ? 'documents' : 'list');
+            switch (action) {
+                case 'list':
+                    result = await api.listCorpora();
+                    break;
+                case 'documents':
+                    if (!params.slug)
+                        return { content: [{ type: 'text', text: 'Error: slug is required for documents action' }], isError: true };
+                    result = await api.getCorpusDocuments(params.slug, params.limit, params.offset);
+                    break;
+                case 'create':
+                    if (!params.slug)
+                        return { content: [{ type: 'text', text: 'Error: slug is required for create action' }], isError: true };
+                    if (!params.title)
+                        return { content: [{ type: 'text', text: 'Error: title is required for create action' }], isError: true };
+                    result = await api.createCorpus({
+                        slug: params.slug,
+                        title: params.title,
+                        description: params.description,
+                        material_class: params.material_class,
+                        visibility: params.visibility === 'all' ? undefined : params.visibility,
+                        themes: params.themes,
+                        default_author_share: params.default_author_share,
+                        default_steward_share: params.default_steward_share,
+                        split_justification: params.split_justification,
+                        provenance_note: params.provenance_note,
+                        manifest: params.manifest,
+                    });
+                    break;
+                case 'health':
+                    if (!params.slug)
+                        return { content: [{ type: 'text', text: 'Error: slug is required for health action' }], isError: true };
+                    result = await api.getCorpusHealth(params.slug);
+                    break;
+                case 'revenue':
+                    if (!params.slug)
+                        return { content: [{ type: 'text', text: 'Error: slug is required for revenue action' }], isError: true };
+                    result = await api.getCorpusRevenue(params.slug, params.days);
+                    break;
+                case 'bulk_ingest':
+                    if (!params.slug)
+                        return { content: [{ type: 'text', text: 'Error: slug is required for bulk_ingest action' }], isError: true };
+                    if (!params.documents)
+                        return { content: [{ type: 'text', text: 'Error: documents is required for bulk_ingest action' }], isError: true };
+                    result = await api.bulkIngestDocuments(params.slug, params.documents);
+                    break;
             }
-            const shaped = shapeCorpora(result, params.slug);
+            const shaped = action === 'list' || action === 'documents' ? shapeCorpora(result, action === 'documents' ? params.slug : undefined) : result;
             return { content: [{ type: 'text', text: JSON.stringify(shaped, null, 2) }] };
         }
         catch (err) {
@@ -1630,6 +1666,54 @@ export async function startMcpServer(options) {
             return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
         }
     });
+    // ── Tools: pyramid consume-head proxies (spec green playful/176/24) ──────
+    // Thin HTTP proxies to the local AWN node's read-time pyramid routes. No new
+    // logic, no LLM. pyramid_map orients; pyramid_hydrate pulls one node/region;
+    // pyramid_ask runs cheap mechanical retrieval. JSON returned as-is.
+    server.tool('pyramid_map', 'Orient first at boot — apex synthesis + freshness (current/superseded counts) + nav skeleton + unresolved gaps for a pyramid. GET /pyramid/{slug}/map. Use this before pyramid_hydrate so you have the apex framing and the nav node ids to drill into.', {
+        slug: z.string().describe('Pyramid slug to map.'),
+    }, async (params) => {
+        const gate = requireIdentity();
+        if (gate)
+            return { content: [gate], isError: true };
+        try {
+            const result = await api.getPyramidMap(params.slug);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+        }
+    });
+    server.tool('pyramid_hydrate', "Pull one node/region's full content after orienting via pyramid_map nav. GET /pyramid/{slug}/drill/{node_id}. Returns the node (headline/distilled/narrative) plus children, evidence, gaps, and web edges.", {
+        slug: z.string().describe('Pyramid slug.'),
+        node_id: z.string().describe('Node id to hydrate (from pyramid_map nav).'),
+    }, async (params) => {
+        const gate = requireIdentity();
+        if (gate)
+            return { content: [gate], isError: true };
+        try {
+            const result = await api.getPyramidDrill(params.slug, params.node_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+        }
+    });
+    server.tool('pyramid_ask', 'Cheap (<5s, no-LLM) retrieval answer over the existing pyramid with node-id citations. POST /pyramid/{slug}/question. Mechanical retrieval only — does not build or call an LLM.', {
+        slug: z.string().describe('Pyramid slug to query.'),
+        question: z.string().describe('Natural-language question to retrieve an answer for.'),
+    }, async (params) => {
+        const gate = requireIdentity();
+        if (gate)
+            return { content: [gate], isError: true };
+        try {
+            const result = await api.askPyramid(params.slug, params.question);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+        }
+    });
     // ── Tool: wire_retract ────────────────────────────────────────────────
     server.tool('wire_retract', 'Retract your own contribution (voluntary self-takedown). Half your deposit is refunded, half is forfeited to the graph fund, and any bounty credits are clawed back. The contribution becomes invisible on the Wire but is preserved for audit. This is irreversible.', {
         contribution_id: z.string().describe('UUID of your contribution to retract'),
@@ -1717,6 +1801,8 @@ export async function startMcpServer(options) {
     // ── Tool: wire_mesh (merged: wire_mesh_status + wire_mesh_board + wire_mesh_intent) ──
     server.tool('wire_mesh', 'Coordinate with sibling threads. Actions: status (see active threads), board_read/board_write/board_delete (shared blackboard), intent_declare/intent_release/intent_list (coordination intents).', {
         action: z.enum(['status', 'board_read', 'board_write', 'board_delete', 'intent_declare', 'intent_release', 'intent_list']).describe('Mesh action to perform'),
+        scope: z.enum(['agent', 'fleet', 'circle']).optional().describe('Shared mesh scope; defaults to agent.'),
+        circle_id: z.string().optional().describe('Circle UUID required for circle scope.'),
         key: z.string().optional().describe('Board key (for board_write/board_delete)'),
         value: z.unknown().optional().describe('Board value (for board_write)'),
         ttl: z.number().optional().describe('TTL in seconds (for board_write: default 3600, max 86400; for intent_declare: default 300, max 3600)'),
@@ -1729,13 +1815,14 @@ export async function startMcpServer(options) {
         if (gate)
             return { content: [gate], isError: true };
         try {
+            const scope = { scope: params.scope, circle_id: params.circle_id };
             switch (params.action) {
                 case 'status': {
-                    const result = await api.meshStatus();
+                    const result = await api.meshStatus(scope);
                     return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
                 }
                 case 'board_read': {
-                    const result = await api.meshBoardRead();
+                    const result = await api.meshBoardRead(scope);
                     return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
                 }
                 case 'board_write': {
@@ -1743,29 +1830,29 @@ export async function startMcpServer(options) {
                         return { content: [{ type: 'text', text: 'key is required for board_write' }], isError: true };
                     if (params.value === undefined)
                         return { content: [{ type: 'text', text: 'value is required for board_write' }], isError: true };
-                    const result = await api.meshBoardWrite(params.key, params.value, params.ttl);
+                    const result = await api.meshBoardWrite(params.key, params.value, params.ttl, scope);
                     return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
                 }
                 case 'board_delete': {
                     if (!params.key)
                         return { content: [{ type: 'text', text: 'key is required for board_delete' }], isError: true };
-                    const result = await api.meshBoardDelete(params.key);
+                    const result = await api.meshBoardDelete(params.key, scope);
                     return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
                 }
                 case 'intent_declare': {
                     if (!params.intent_action)
                         return { content: [{ type: 'text', text: 'intent_action is required for intent_declare' }], isError: true };
-                    const result = await api.meshDeclareIntent(params.intent_action, params.domain, params.meta, params.ttl);
+                    const result = await api.meshDeclareIntent(params.intent_action, params.domain, params.meta, params.ttl, scope);
                     return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
                 }
                 case 'intent_release': {
                     if (!params.intent_id)
                         return { content: [{ type: 'text', text: 'intent_id is required for intent_release' }], isError: true };
-                    const result = await api.meshReleaseIntent(params.intent_id);
+                    const result = await api.meshReleaseIntent(params.intent_id, scope);
                     return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
                 }
                 case 'intent_list': {
-                    const result = await api.meshGetIntents();
+                    const result = await api.meshGetIntents(scope);
                     return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
                 }
                 default:
@@ -1783,6 +1870,7 @@ export async function startMcpServer(options) {
         action: z.enum(['diff', 'push', 'pull', 'preview']).describe('Sync action to perform'),
         publish: z.boolean().optional().describe('Legacy push only: publish new document versions instead of drafts'),
         market_native_docs_ingest: z.enum(['off', 'auto', 'all']).optional().describe('Push only: route through /wire/sync and dispatch market-native docs ingest. auto sends docs without wire rear-matter or docs over the inline body budget; all sends every pushed doc. Oversized docs are dispatched as 8000-token windows with 2000-token overlap.'),
+        include_content: z.boolean().optional().describe('Diff/preview only: include full local file bodies. Defaults false; previews normally return hash + sizeBytes only.'),
     }, async (params) => {
         const gate = await requireConfirmed();
         if (gate)
@@ -1791,6 +1879,7 @@ export async function startMcpServer(options) {
             const { dir, corpus, action } = params;
             const publish = params.publish ?? false;
             const marketNativeDocsIngest = (params.market_native_docs_ingest ?? 'off');
+            const includeContent = params.include_content === true;
             // ── Path traversal protection ──
             if (!isAbsolute(dir)) {
                 return { content: [{ type: 'text', text: 'Error: dir must be an absolute path' }], isError: true };
@@ -1828,7 +1917,7 @@ export async function startMcpServer(options) {
             const remoteDocs = await paginateAll(async (page, pageSize) => {
                 const offset = (page - 1) * pageSize;
                 const result = await api.getCorpusDocuments(corpus, pageSize, offset);
-                return result.documents || [];
+                return result.documents || result.items || [];
             });
             // 4. Compute diff
             const diff = await computeDiff(localFiles, remoteDocs, manifest);
@@ -1843,11 +1932,15 @@ export async function startMcpServer(options) {
                     conflicts: diff.conflicts.length,
                 };
                 const output = {
+                    ...generatePreviewJson({
+                        corpus_slug: corpus,
+                        local_dir: dir,
+                        diff,
+                        summary,
+                    }, { includeContent }),
                     corpus_slug: corpus,
                     local_dir: dir,
                     action,
-                    diff,
-                    summary,
                 };
                 return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] };
             }
@@ -1948,12 +2041,30 @@ export async function startMcpServer(options) {
             return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
         }
     });
+    server.tool('wire_claim', 'File, dispatch, report and settle a verifiable claim. Bond/reward are escrowed; faculty delivers through the work market. See wire_help topic claims.', {
+        action: z.enum(['file', 'dispatch', 'report', 'settle', 'cancel', 'get', 'list']),
+        claim_id: z.string().uuid().optional(), idempotency_key: z.string().min(1).max(256).optional(),
+        claim_body: z.string().optional(), claim_type: z.string().optional(), domain: z.string().optional(),
+        evidence_handles: z.array(z.string()).optional(), bond: creditAmountSchema(0).optional(),
+        reward: creditAmountSchema(0).optional(), faculty_handle: z.string().optional(), offer_id: z.string().optional(),
+    }, async (params) => {
+        const gate = await requireConfirmed();
+        if (gate)
+            return { content: [gate], isError: true };
+        try {
+            return { content: [{ type: 'text', text: JSON.stringify(await api.claims(params), null, 2) }] };
+        }
+        catch (error) {
+            return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true };
+        }
+    });
     // ── Tool: wire_market ──────────────────────────────────────────────────
     server.tool('wire_market', 'Interact with prediction markets on Wire contributions. Stake credits on claims (agree/disagree), check market status and your positions, or get market norms for calibrating seeds. Staking costs credits — the amount is deducted atomically.', {
         action: z.enum(['stake', 'status', 'norms']).describe('Action to perform'),
         contribution_id: z.string().optional().describe('Contribution UUID (required for stake, status)'),
         side: z.enum(['agree', 'disagree']).optional().describe('Side to stake on (required for stake)'),
-        amount: z.number().int().positive().optional().describe('Credits to stake (required for stake, must be positive integer)'),
+        amount: creditAmountSchema(1).optional().describe('Credits to stake (required for stake, must be positive integer)'),
+        request_id: z.string().uuid().optional().describe('Stable operation UUID for a stake; reuse on retry, change for an additional stake'),
         domain: z.string().optional().describe('Domain filter for norms (optional)'),
     }, async (params) => {
         const gate = await requireConfirmed();
@@ -1967,7 +2078,7 @@ export async function startMcpServer(options) {
                     return { content: [{ type: 'text', text: 'Error: side is required for stake' }], isError: true };
                 if (!params.amount)
                     return { content: [{ type: 'text', text: 'Error: amount is required for stake' }], isError: true };
-                const result = await api.stakeMarket(params.contribution_id, params.side, params.amount);
+                const result = await api.stakeMarket(params.contribution_id, params.side, params.amount, params.request_id);
                 return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
             }
             if (params.action === 'status') {
@@ -2200,7 +2311,7 @@ export async function startMcpServer(options) {
     server.tool('wire_wait', 'Block the live MCP session until a matching Wire coordination event arrives or the timeout elapses. Layer 1 uses SSE + cursor replay; durable wire_watch is not included.', {
         triggers: z.array(z.string()).max(20).optional().describe('Event triggers to wait for, e.g. message.unread, task.assigned, task.moved, board.changed, circle.message. Supports prefix wildcards such as message.*. Omit to wait on any message.*, task.*, board.*, or circle.* event addressable to you.'),
         filters: z.record(z.unknown()).optional().describe('Composable filters such as {from, column, key_prefix, assignee, created_by, target_type, task_id, task_handle, message_handle, from_handle, to_handle, circle, circle_id, written_by_thread}. Agent filters accept "me", agent UUID, or pseudo-ID when available. Handle filters match the corresponding event payload field exactly.'),
-        timeout_seconds: z.number().int().min(0).max(1800).optional().describe('Maximum seconds to block. Defaults to 30; max 1800. Use 0 for immediate replay/query behavior.'),
+        timeout_seconds: z.number().int().min(-1).max(86400).optional().describe('Maximum seconds to block. Defaults to 30; max 86400 (24h). Use 0 for immediate replay/query; use -1 to park INDEFINITELY until an event (no re-arm cycles) — the SSE hair-trigger still delivers instantly.'),
         cursor: z.string().optional().describe('Opaque next_cursor from a prior wire_wait or wire_events response. Legacy integer id cursors are accepted. If omitted, wait starts at the current high-water mark.'),
         limit: z.number().int().min(1).max(200).optional().describe('Maximum events to return when triggered. Defaults to 50.'),
     }, async (params) => {
@@ -2289,6 +2400,7 @@ export async function startMcpServer(options) {
         action: z.enum(['supersede', 'propose', 'accept', 'reject']).describe('supersede = direct supersession authorized by target scope, propose = propose supersession (5-credit deposit), accept = approve a proposal, reject = deny a proposal'),
         target_id: z.string().describe('Target contribution UUID (the one being superseded for supersede/propose, or the proposal UUID for accept/reject)'),
         contribution_id: z.string().optional().describe('Your replacement contribution UUID (required for supersede and propose)'),
+        allow_type_change: z.boolean().optional().describe('For action=supersede: allow a CROSS-TYPE supersession (successor type != target type). Without this a cross-type supersede 400s ("type-filtered consumers silently drop cross-type successors"). Pass true only when the type change is deliberate.'),
     }, async (params) => {
         const gate = await requireConfirmed();
         if (gate)
@@ -2312,7 +2424,7 @@ export async function startMcpServer(options) {
                     if (!params.contribution_id) {
                         return { content: [{ type: 'text', text: 'contribution_id is required for supersede' }], isError: true };
                     }
-                    result = await api.executeSupersession(params.target_id, params.contribution_id);
+                    result = await api.executeSupersession(params.target_id, params.contribution_id, params.allow_type_change);
                     break;
                 default:
                     return { content: [{ type: 'text', text: 'Invalid action' }], isError: true };
@@ -2325,10 +2437,10 @@ export async function startMcpServer(options) {
     });
     // ── Tool: wire_correct ─────────────────────────────────────────────
     server.tool('wire_correct', 'Submit or endorse corrections to contributions. Corrections require a deposit (returned if correction is accepted). Endorsements add weight to existing corrections.', {
-        action: z.enum(['correct', 'endorse']).describe('correct = file a new correction, endorse = support an existing correction'),
+        action: z.enum(['correct', 'endorse', 'withdraw']).describe('correct = file a new correction, withdraw = withdraw your endorsement and refund its deposit; endorse = support an existing correction'),
         target_id: z.string().describe('For correct: contribution UUID being corrected. For endorse: correction contribution UUID.'),
         correction_contribution_id: z.string().optional().describe('Your correction contribution UUID (required for correct)'),
-        deposit_amount: z.number().int().min(1).describe('Credits to deposit (positive integer, returned if accepted)'),
+        deposit_amount: creditAmountSchema(1).optional().describe('Credits to deposit (positive integer, returned if accepted)'),
     }, async (params) => {
         const gate = await requireConfirmed();
         if (gate)
@@ -2339,10 +2451,13 @@ export async function startMcpServer(options) {
                 if (!params.correction_contribution_id) {
                     return { content: [{ type: 'text', text: 'correction_contribution_id is required for correct' }], isError: true };
                 }
-                result = await api.submitCorrection(params.target_id, params.correction_contribution_id, params.deposit_amount);
+                result = await api.submitCorrection(params.target_id, params.correction_contribution_id, params.deposit_amount ?? 0);
+            }
+            else if (params.action === 'withdraw') {
+                result = await api.withdrawCorrection(params.target_id);
             }
             else {
-                result = await api.endorseCorrection(params.target_id, params.deposit_amount);
+                result = await api.endorseCorrection(params.target_id, params.deposit_amount ?? 0);
             }
             return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
         }
@@ -3018,18 +3133,42 @@ export async function startMcpServer(options) {
         }
     });
     // ── Tool: wire_feedback ──────────────────────────────────────────────
-    server.tool('wire_feedback', 'Submit bug reports or feature suggestions to the Wire operator.', {
+    const BUG_CATEGORIES = ['api_error', 'data_quality', 'economic', 'auth', 'other'];
+    const SUGGESTION_CATEGORIES = ['feature', 'economic', 'ux', 'documentation', 'other'];
+    server.tool('wire_feedback', 'Submit a bug report or feature suggestion to the Wire operator. Only action and message are required; category and severity are optional (a bug without them is filed as category "other", severity "minor"). GET /wire/feedback lists your reports and the operator\'s responses.', {
         action: z.enum(['bug', 'suggestion']).describe('Type of feedback to submit'),
         message: z.string().describe('Description of the bug or suggestion'),
+        category: z.enum(['api_error', 'data_quality', 'economic', 'auth', 'feature', 'ux', 'documentation', 'other']).optional()
+            .describe('bug: api_error | data_quality | economic | auth | other. suggestion: feature | economic | ux | documentation | other. Defaults to other.'),
+        severity: z.enum(['critical', 'major', 'minor', 'cosmetic']).optional().describe('Bugs only. Defaults to minor.'),
+        title: z.string().optional().describe('Short title (suggestions)'),
+        endpoint: z.string().optional().describe('The endpoint that misbehaved (bugs)'),
+        steps_to_reproduce: z.string().optional().describe('How to trigger it (bugs)'),
+        expected_behavior: z.string().optional().describe('What you expected (bugs)'),
+        actual_behavior: z.string().optional().describe('What happened (bugs)'),
         context: z.string().optional().describe('Additional detail or context'),
     }, async (params) => {
         const gate = requireIdentity();
         if (gate)
             return { content: [gate], isError: true };
+        const allowed = params.action === 'bug' ? BUG_CATEGORIES : SUGGESTION_CATEGORIES;
+        if (params.category && !allowed.includes(params.category)) {
+            return {
+                content: [{ type: 'text', text: `Error: category "${params.category}" is not valid for a ${params.action}; use one of: ${allowed.join(', ')}` }],
+                isError: true,
+            };
+        }
         try {
+            const description = params.context ? `${params.message}\n\n${params.context}` : params.message;
             const result = await api.request('POST', `/wire/feedback/${params.action}`, {
-                message: params.message,
-                ...(params.context ? { context: params.context } : {}),
+                description,
+                ...(params.category ? { category: params.category } : {}),
+                ...(params.action === 'bug' && params.severity ? { severity: params.severity } : {}),
+                ...(params.action === 'suggestion' && params.title ? { title: params.title } : {}),
+                ...(params.action === 'bug' && params.endpoint ? { endpoint: params.endpoint } : {}),
+                ...(params.action === 'bug' && params.steps_to_reproduce ? { steps_to_reproduce: params.steps_to_reproduce } : {}),
+                ...(params.action === 'bug' && params.expected_behavior ? { expected_behavior: params.expected_behavior } : {}),
+                ...(params.action === 'bug' && params.actual_behavior ? { actual_behavior: params.actual_behavior } : {}),
             });
             return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
         }
@@ -3197,10 +3336,16 @@ export async function startMcpServer(options) {
         console.error('[wire-mcp] Background worker pending until wire_identify establishes a slot pin.');
     }
     // ── Connect transport ────────────────────────────────────────────────
+    // Discover before the first tools/list. Without credentials, retry at pin.
+    await discoverSurfacesAtPin('startup');
     if (options?.transport === 'http') {
         const port = options?.port ?? 3200;
         const httpTransport = new StreamableHTTPServerTransport({
-            sessionIdGenerator: undefined, // stateless — identity is per-token, not per-session
+            // This server retains its pinned identity across requests. The SDK's
+            // stateless transport is single-use; a session keeps identify -> list ->
+            // call usable on this same local process.
+            sessionIdGenerator: () => randomUUID(),
+            enableJsonResponse: true,
         });
         await server.connect(httpTransport);
         const httpServer = createServer(async (req, res) => {