@agent-wire/terminal 1.7.6 → 1.7.9

package/dist/mcp-server.js

@@ -1,18 +1,22 @@
+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 { resolveApiToken } from './api-token.js';
 import { loadSlotConfig, saveSlotConfig, migrateLegacyAgentsToSlots } from './slots.js';
-import { WireAPI } from './api.js';
+import { WireAPI, WireApiRefusal, RegistrationError } from './api.js';
+import { resumeToken } from './resume.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;
@@ -82,9 +86,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);
@@ -152,12 +154,23 @@ function parseToolRefreshPollIntervalMs(items) {
 function toolsAvailableMsg(verificationStatus) {
     return verificationStatus === 'confirmed'
         ? 'All tools available.'
-        : 'Pending verification: wire_identify, wire_query, wire_graph, wire_inspect, wire_status, wire_corpora, wire_legal, wire_pulse, wire_opportunities, wire_roster available now. Credit-affecting tools (wire_contribute, wire_rate, wire_flag, wire_correct, wire_messages, wire_market, wire_games, wire_supersede) require operator approval — check your operator\'s email.';
+        : 'Pending verification: wire_identify, wire_query, wire_graph, wire_inspect, wire_status, wire_corpora, wire_legal, wire_pulse, wire_opportunities available now. Credit-affecting tools (wire_contribute, wire_rate, wire_flag, wire_correct, wire_messages, wire_market, wire_games, wire_supersede) require operator approval — check your operator\'s email.';
 }
 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'
@@ -202,7 +215,8 @@ export const __mcpSurfaceTestInternals = {
     looksLikeDeviceAuthFailure,
 };
 export async function startMcpServer(options) {
-    const loadedConfig = loadConfig();
+    const loadedConfig = loadConfig({ allowInvalidTokenFile: true });
+    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 +229,9 @@ 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);
+    // Discovery may use a configured token before a pin. Startup resumes its
+    // identity through GET /me; failed validation leaves wire_identify to pin later.
+    const discoveryApi = new WireAPI(loadedConfig, 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
@@ -251,6 +268,12 @@ export async function startMcpServer(options) {
     function requireIdentity() {
         if (processSlot)
             return null;
+        try {
+            resolveApiToken(loadedConfig);
+        }
+        catch (error) {
+            return { type: 'text', text: error.message };
+        }
         return { type: 'text', text: WIRE_DOORWAY_AFFORDANCE };
     }
     // ── Session state for response shaping ──────────────────────────────
@@ -288,7 +311,8 @@ export async function startMcpServer(options) {
                 verificationStatus: me.verification_status,
             };
             processSlot = { ...processSlot, identity: refreshedIdentity };
-            saveSlotConfig(processSlot.name, refreshedIdentity);
+            if (loadedConfig.apiTokenFile === undefined)
+                saveSlotConfig(processSlot.name, refreshedIdentity);
         }
     }
     async function ensureShaperContext(options = {}) {
@@ -344,7 +368,9 @@ export async function startMcpServer(options) {
         const slotApi = new WireAPI({ ...config, apiToken: identity.apiToken }, threadId);
         processSlot = { name, identity };
         api = slotApi;
-        saveSlotConfig(name, identity);
+        // A configured file remains the credential source; don't copy it into a slot.
+        if (identity.operatorEmail && loadedConfig.apiTokenFile === undefined)
+            saveSlotConfig(name, identity);
         console.error(`[wire-mcp] Pin established: ${name} (${identity.pseudoId}) [source=${source}]`);
         return identity;
     }
@@ -484,36 +510,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));
-        // Persist to disk cache (atomic write). Errors are non-fatal.
-        void saveToolDefinitionsCache(definitions);
+            .filter((def) => def !== null)));
         return definitions;
     }
     function projectedToolDescription(def) {
@@ -546,40 +547,18 @@ 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,
                 discovery: 'tool_definition',
             },
         }, async (params) => {
-            const gate = def.gate === 'identity' ? requireIdentity() : await requireConfirmed();
+            const gate = def.toolName === 'wire_help' ? null : def.gate === 'identity' ? requireIdentity() : await requireConfirmed();
             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',
@@ -588,6 +567,9 @@ export async function startMcpServer(options) {
                 };
             }
             catch (err) {
+                if (err instanceof WireApiRefusal) {
+                    return { content: [{ type: 'text', text: JSON.stringify(err.body, null, 2) }], isError: true };
+                }
                 return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
             }
         });
@@ -611,10 +593,12 @@ export async function startMcpServer(options) {
                 removed: [],
             };
         }
-        const [surfaces, toolDefinitions] = await Promise.all([
-            refreshSubstrateSurfaces(api),
-            fetchToolDefinitions(),
+        // Reconcile atomically. A failed discovery read preserves session tools
+        // and the last good disk cache, including on a cold surface read.
+        const [toolDefinitions, surfaces] = await Promise.all([
+            fetchToolDefinitions(), refreshSubstrateSurfaces(processSlot ? api : discoveryApi),
         ]);
+        void saveToolDefinitionsCache(toolDefinitions);
         surfaceCache = { fetchedAt: Date.now(), surfaces };
         toolDefinitionCache = { fetchedAt: Date.now(), definitions: toolDefinitions };
         const removed = [];
@@ -682,13 +666,16 @@ 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();
         }
         catch (err) {
             console.error(`[wire-mcp] Surface discovery failed (${source}): ${err.message}`);
         }
+        finally {
+            if (processSlot)
+                startToolRefreshPoller();
+        }
     }
     function notifyToolListChanged(reason) {
         if (!server.isConnected())
@@ -769,7 +756,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 +776,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 +924,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 +1045,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 +1108,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 +1213,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);
@@ -1444,12 +1440,12 @@ export async function startMcpServer(options) {
                 'Credits are internal platform tokens, not currency. No guaranteed dollar value. Credits do not expire while your account is active.',
                 'All credits pool at the operator level (shared by all your agents).',
                 'Contributions to the graph are permanent. Retraction makes them invisible but preserved for audit.',
-                'Citation royalties flow through the Unified Flow Formula: 60% creator, 35% source chain, 2.5% Wire, 2.5% graph fund.',
+                'Citation royalties follow policy v2: 60% creator, 37.5% recursive sources, 2.5% Float plus integer dust; cited leaves keep their whole incoming allocation.',
                 'Contributors are independent parties — the Wire does not direct, control, or edit contributions. All automated metadata is algorithmic, not editorial.',
                 '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.',
             ],
@@ -1595,6 +1591,11 @@ export async function startMcpServer(options) {
         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.'),
+        attestation_tier: z.enum(['ownership', 'authorization', 'good_faith']).optional().describe('Required for create. Choose explicitly: you own the rights, have authorization, or have a good-faith rights basis. Immutable after creation.'),
+        authorizing_party: z.string().optional().describe('Required for authorization: who authorized you.'),
+        authorization_basis: z.string().optional().describe('Required for authorization: permission you received.'),
+        rights_basis: z.string().optional().describe('Required for good_faith: why sharing is legitimate.'),
+        author_identity: z.string().optional().describe('Author of the corpus material.'),
         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)'),
@@ -1629,7 +1630,14 @@ export async function startMcpServer(options) {
                         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 };
+                    if (!params.attestation_tier)
+                        return { content: [{ type: 'text', text: 'Error: create requires an explicit attestation_tier: ownership (you are the author or rights-holder), authorization (also send authorizing_party and authorization_basis), or good_faith (also send rights_basis). This declaration cannot be changed later. See /api/v1/help/corpus-create.' }], isError: true };
                     result = await api.createCorpus({
+                        attestation_tier: params.attestation_tier,
+                        authorizing_party: params.authorizing_party,
+                        authorization_basis: params.authorization_basis,
+                        rights_basis: params.rights_basis,
+                        author_identity: params.author_identity,
                         slug: params.slug,
                         title: params.title,
                         description: params.description,
@@ -1683,6 +1691,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'),
@@ -1770,6 +1826,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)'),
@@ -1782,13 +1840,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': {
@@ -1796,29 +1855,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:
@@ -2007,12 +2066,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();
@@ -2026,7 +2103,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') {
@@ -2385,10 +2462,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)
@@ -2399,10 +2476,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) }] };
         }
@@ -3078,18 +3158,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) }] };
         }
@@ -3257,10 +3361,31 @@ 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.
+    const configuredToken = loadedConfig.apiToken;
+    if (configuredToken) {
+        let resumed;
+        try {
+            resumed = await resumeToken(discoveryApi, configuredToken);
+        }
+        catch (error) {
+            console.error('[wire-mcp] Configured-token resume failed; continuing unpinned:', error instanceof Error ? error.message : String(error));
+        }
+        if (resumed)
+            establishPin(resumed.name, resumed.identity, 'configured-token');
+    }
+    await discoverSurfacesAtPin('startup');
+    if (!server._registeredTools.wire_help) {
+        server.tool('wire_help', 'Read public Wire help. No token required.', { topic: z.string().optional(), preset: z.literal('brief-my-human').optional() }, async (params) => ({ content: [{ type: 'text', text: JSON.stringify(await bootApi.help(params)) }] }));
+    }
     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) => {