@agent-wire/terminal 1.7.7 → 1.7.10

package/dist/api-token.d.ts

@@ -0,0 +1,9 @@
+interface TokenConfig {
+    apiToken: string;
+    apiTokenFile?: string;
+}
+/** Shared saved credentials are never a server's own MCP identity. */
+export declare function hasExplicitApiToken(): boolean;
+/** Explicit environment token > environment file > saved configuration. */
+export declare function resolveApiToken(config: TokenConfig, allowInvalidTokenFile?: boolean): TokenConfig;
+export {};

package/dist/api-token.js

@@ -0,0 +1,46 @@
+import { readFileSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+// Capture credentials for this process; rotating a token file requires a restart.
+const envToken = process.env.WIRE_API_TOKEN;
+const envTokenFile = process.env.WIRE_API_TOKEN_FILE;
+const fileTokens = new Map();
+/** Shared saved credentials are never a server's own MCP identity. */
+export function hasExplicitApiToken() {
+    return !!envToken || envTokenFile !== undefined;
+}
+/** Explicit environment token > environment file > saved configuration. */
+export function resolveApiToken(config, allowInvalidTokenFile = false) {
+    if (envToken)
+        return { apiToken: envToken, apiTokenFile: undefined };
+    const path = envTokenFile ?? config.apiTokenFile;
+    if (path === undefined)
+        return { apiToken: config.apiToken, apiTokenFile: undefined };
+    let token = fileTokens.get(path);
+    if (token === undefined) {
+        if (!isAbsolute(path)) {
+            token = new Error('WIRE_API_TOKEN_FILE must be an absolute path to a file containing only your token');
+        }
+        else {
+            try {
+                token = readFileSync(path, 'utf8').trim();
+                if (!token)
+                    token = new Error('The file referenced by WIRE_API_TOKEN_FILE is empty; it must contain only your token');
+            }
+            catch (error) {
+                // Only expose the OS code, never file contents or an arbitrary error message.
+                const code = error.code ?? 'read failed';
+                token = new Error(`Cannot read the file referenced by WIRE_API_TOKEN_FILE (${code}); set it to an absolute path to a file containing only your token`);
+            }
+        }
+        fileTokens.set(path, token);
+    }
+    if (token instanceof Error) {
+        // Public help/discovery may proceed anonymously; authenticated callers retry
+        // this same cached result and receive the error without exposing the value.
+        if (allowInvalidTokenFile)
+            return { apiToken: '', apiTokenFile: path };
+        throw token;
+    }
+    return { apiToken: token, apiTokenFile: path };
+}
+//# sourceMappingURL=api-token.js.map

package/dist/api-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-token.js","sourceRoot":"","sources":["../src/api-token.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAOvC,kFAAkF;AAClF,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;AAC5C,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;AACrD,MAAM,UAAU,GAAG,IAAI,GAAG,EAA0B,CAAC;AAErD,sEAAsE;AACtE,MAAM,UAAU,mBAAmB;IACjC,OAAO,CAAC,CAAC,QAAQ,IAAI,YAAY,KAAK,SAAS,CAAC;AAClD,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,eAAe,CAAC,MAAmB,EAAE,qBAAqB,GAAG,KAAK;IAChF,IAAI,QAAQ;QAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC;IACrE,MAAM,IAAI,GAAG,YAAY,IAAI,MAAM,CAAC,YAAY,CAAC;IACjD,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC;IAEtF,IAAI,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACtB,KAAK,GAAG,IAAI,KAAK,CAAC,mFAAmF,CAAC,CAAC;QACzG,CAAC;aAAM,CAAC;YACN,IAAI,CAAC;gBACH,KAAK,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;gBAC1C,IAAI,CAAC,KAAK;oBAAE,KAAK,GAAG,IAAI,KAAK,CAAC,sFAAsF,CAAC,CAAC;YACxH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,8EAA8E;gBAC9E,MAAM,IAAI,GAAI,KAA+B,CAAC,IAAI,IAAI,aAAa,CAAC;gBACpE,KAAK,GAAG,IAAI,KAAK,CAAC,2DAA2D,IAAI,oEAAoE,CAAC,CAAC;YACzJ,CAAC;QACH,CAAC;QACD,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC9B,CAAC;IACD,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,6EAA6E;QAC7E,4EAA4E;QAC5E,IAAI,qBAAqB;YAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;QACvE,MAAM,KAAK,CAAC;IACd,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;AACjD,CAAC"}

package/dist/api.d.ts

@@ -1,6 +1,7 @@
 import type { CreditAmount } from './contracts/credit-amount.js';
 import type { WireNodeConfig } from './config.js';
 import type { MarketNativeDocsIngestMode, RemoteDocument } from './sync/types.js';
+export declare function normalizeWireApiUrl(value: string): string;
 export declare class RegistrationError extends Error {
     readonly status: number;
     constructor(status: number, message: string);
@@ -21,6 +22,7 @@ export interface MeshScopeParams {
     circle_id?: string;
 }
 export interface QueryParams {
+    count?: 'exact';
     text?: string;
     types?: string | string[];
     type?: string;
@@ -39,6 +41,7 @@ export interface QueryParams {
 }
 export interface ContributeParams {
     type: string;
+    original?: boolean;
     contribution_type?: 'mechanical' | 'intelligence';
     title: string;
     body: string;
@@ -84,6 +87,7 @@ export interface ContributeParams {
     }>;
 }
 export interface ActionCreateParams {
+    scope?: 'fleet' | 'unscoped';
     title: string;
     body: string;
     action_definition: Record<string, unknown>;
@@ -103,6 +107,9 @@ export interface BrowseParams {
     include_definition?: boolean;
     definition_purpose?: string;
     definition_scope?: string;
+    cursor?: string;
+    limit?: number;
+    offset?: number;
 }
 export interface FlagParams {
     item_id: string;
@@ -178,6 +185,15 @@ export interface PinPreview {
     derivative_count: number;
 }
 export interface RetractionResult {
+    deposit_fee?: CreditAmount;
+    deposit_refunded_amount?: CreditAmount;
+    deposit_fee_payers?: Array<{
+        operator_id: string;
+        refunded_amount: CreditAmount;
+        fee: CreditAmount;
+    }>;
+    deposit_case?: string;
+    deposit_message?: string | null;
     retracted: boolean;
     contribution_id: string;
     deposit_refund: CreditAmount;
@@ -293,7 +309,14 @@ export declare const __wireApiTestInternals: {
     parseSseBlock: typeof parseSseBlock;
 };
 declare function parseSseBlock(block: string): WireEventStreamMessage | null;
+/** Keep actionable server refusals intact across MCP and terminal transports. */
+export declare class WireApiRefusal extends Error {
+    readonly status: number;
+    readonly body: Record<string, unknown>;
+    constructor(status: number, body: Record<string, unknown>);
+}
 export declare class WireAPI {
+    private httpFetch?;
     claims(params: Record<string, unknown>): Promise<unknown>;
     private baseUrl;
     private token;
@@ -303,7 +326,7 @@ export declare class WireAPI {
     private localNodeEnabled;
     private localNodeToken;
     private localContributionRouteStatus;
-    constructor(config: WireNodeConfig, threadId?: string);
+    constructor(config: WireNodeConfig, threadId?: string, httpFetch?: typeof fetch | undefined);
     /** Set or update the thread ID (used for mesh coordination) */
     setThreadId(id: string): void;
     request<T>(method: string, path: string, body?: unknown, timeoutMs?: number): Promise<T>;
@@ -314,10 +337,15 @@ export declare class WireAPI {
     requestUnwrap<T>(method: string, path: string, body?: unknown, timeoutMs?: number): Promise<T>;
     unwrapEnvelopeOrPlain<T>(response: unknown): T;
     getMe(): Promise<Record<string, unknown>>;
-    registerNode(name: string, capabilities: string[]): Promise<{
+    registerNode(name: string, capabilities: string[], options?: {
+        node_handle?: string;
+        app_version?: string;
+    }): Promise<{
         node_id: string;
         name: string;
         status: string;
+        registration_notice?: string;
+        legacy_nodes_not_resumed?: number;
     }>;
     /**
      * Register a new Wire agent (unauthenticated — no token required).
@@ -334,6 +362,8 @@ export declare class WireAPI {
         pseudo_id: string;
         agent_id: string;
         verification_status: string;
+        welcome_grant?: Record<string, unknown>;
+        pool_credits?: number;
     }>;
     pollWork(nodeId: string): Promise<{
         work: {
@@ -367,13 +397,16 @@ export declare class WireAPI {
     flag(params: FlagParams): Promise<Record<string, unknown>>;
     /**
      * Retract your own contribution (voluntary self-takedown).
-     * Economics: full deposit refund during grace window; half refund + half forfeit + bounty clawback after grace window.
+     * Economics: held deposits use the age-based forfeit and cap; refunded deposits apply the same rule to each actual refund recipient. No refund leg means no fee. Bounty recovery still applies.
      */
     retract(contributionId: string): Promise<Record<string, unknown>>;
     /**
      * Access a contribution (detail endpoint). Accessing IS purchasing for priced items.
      */
-    accessContribution(contributionId: string): Promise<Record<string, unknown>>;
+    accessContribution(input: string | {
+        contribution_id: string;
+        [key: string]: unknown;
+    }, acceptPrice?: CreditAmount): Promise<Record<string, unknown>>;
     private verifyLocalContributionReadRoute;
     private localHeaders;
     private localAuthToken;
@@ -547,11 +580,13 @@ export declare class WireAPI {
      */
     previewPin(nodeId: string, targetType: string, targetId: string): Promise<PinPreview>;
     /**
-     * Retract a contribution as an operator during the grace window.
-     * Requires operator-level authentication (the API token must belong
-     * to an operator, not a regular agent).
+     * Retract a contribution as an operator at any age. To correct a contribution,
+     * supersede it. Retraction uses the current window, rates and late refund cap.
+     * After settlement, the same rule applies to each actual refund recipient.
+     * Use operator authentication or the specific author agent token;
+     * sibling agent tokens cannot retract another agent's contribution.
      *
-     * Economics: full deposit refund during grace window; half refund + half forfeit + bounty clawback after grace window.
+     * Economics: held deposits use the age-based forfeit and cap; refunded deposits apply the same rule to each actual refund recipient. No refund leg means no fee. Bounty recovery still applies.
      *
      * @param agentId - The agent that owns the contribution
      * @param contributionId - The contribution to retract
@@ -639,6 +674,7 @@ export declare class WireAPI {
         input?: Record<string, unknown>;
         chain_id?: string;
         quote_id?: string;
+        idempotency_key?: string;
         max_credits?: number;
         entry_mode?: 'start' | 'direct';
         entry?: {
@@ -651,7 +687,7 @@ export declare class WireAPI {
     pollChainRun(params: {
         run_id?: string;
         run_handle_path?: string;
-        chain: string;
+        chain?: string;
         include_steps?: boolean;
     }): Promise<Record<string, unknown>>;
     resolveHandlePath(handlePath: string): Promise<Record<string, unknown>>;
@@ -728,6 +764,10 @@ export declare class WireAPI {
         offset?: number;
     }): Promise<Record<string, unknown>>;
     getDocumentBody(documentId: string): Promise<string>;
+    downloadDocumentBody(documentId: string): Promise<{
+        body: string;
+        content_sha256: string | null;
+    }>;
     getDocumentGraph(documentId: string): Promise<Record<string, unknown>>;
     listDocumentSpans(documentId: string): Promise<Record<string, unknown>>;
     createDocumentSpan(documentId: string, span: {
@@ -745,7 +785,7 @@ export declare class WireAPI {
         material_class?: string;
         visibility?: string;
         themes?: string[];
-        attestation_tier?: string;
+        attestation_tier: 'ownership' | 'authorization' | 'good_faith';
         authorizing_party?: string;
         authorization_basis?: string;
         rights_basis?: string;

package/dist/api.js

@@ -1,3 +1,15 @@
+const normalizedUrlNotices = new Set();
+export function normalizeWireApiUrl(value) {
+    const url = new URL(value);
+    if (url.pathname === '/' || !url.pathname) {
+        url.pathname = '/api/v1';
+        if (!normalizedUrlNotices.has(value)) {
+            console.error('[wire] WIRE_API_URL has no API path; appended /api/v1.');
+            normalizedUrlNotices.add(value);
+        }
+    }
+    return url.toString().replace(/\/+$/, '');
+}
 const DEFAULT_TRUSTED_CHAIN_TIMEOUT_MS = 600_000;
 const TRUSTED_CHAIN_CLIENT_GRACE_MS = 5_000;
 const DEFAULT_WIRE_SYNC_TIMEOUT_MS = DEFAULT_TRUSTED_CHAIN_TIMEOUT_MS + TRUSTED_CHAIN_CLIENT_GRACE_MS;
@@ -145,7 +157,18 @@ function parseSseBlock(block) {
         return { event, data: rawData };
     }
 }
+/** Keep actionable server refusals intact across MCP and terminal transports. */
+export class WireApiRefusal extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(JSON.stringify(body));
+        this.status = status;
+        this.body = body;
+    }
+}
 export class WireAPI {
+    httpFetch;
     async claims(params) {
         const { action, claim_id } = params;
         if (action === 'get' || action === 'list') {
@@ -161,8 +184,9 @@ export class WireAPI {
     localNodeEnabled;
     localNodeToken;
     localContributionRouteStatus;
-    constructor(config, threadId) {
-        this.baseUrl = config.apiUrl;
+    constructor(config, threadId, httpFetch) {
+        this.httpFetch = httpFetch;
+        this.baseUrl = normalizeWireApiUrl(config.apiUrl);
         this.token = config.apiToken;
         this.nodeId = config.nodeId;
         this.threadId = threadId || null;
@@ -184,7 +208,7 @@ export class WireAPI {
         if (this.threadId) {
             headers['X-Wire-Thread'] = this.threadId;
         }
-        const res = await fetch(url, {
+        const res = await (this.httpFetch ?? fetch)(url, {
             method,
             headers,
             body: body ? JSON.stringify(body) : undefined,
@@ -192,6 +216,8 @@ export class WireAPI {
         });
         if (!res.ok) {
             const err = await res.json().catch(() => ({ error: res.statusText }));
+            if (err.code === 'confirm_original' || err.code === 'source_hash_selector_private')
+                throw new WireApiRefusal(res.status, err);
             throw new Error(`API ${method} ${path} failed (${res.status}): ${err.error || res.statusText}`);
         }
         return res.json();
@@ -205,7 +231,7 @@ export class WireAPI {
         if (this.threadId) {
             headers['X-Wire-Thread'] = this.threadId;
         }
-        const res = await fetch(url, {
+        const res = await (this.httpFetch ?? fetch)(url, {
             method,
             headers,
             body: body ? JSON.stringify(body) : undefined,
@@ -213,6 +239,8 @@ export class WireAPI {
         });
         if (!res.ok) {
             const err = await res.json().catch(() => ({ error: res.statusText }));
+            if (err.code === 'source_hash_selector_private')
+                throw new WireApiRefusal(res.status, err);
             const msg = err.error || res.statusText;
             if (res.status === 429 && msg.toLowerCase().includes('pending')) {
                 const retryAfter = res.headers.get('Retry-After') || '60';
@@ -246,8 +274,8 @@ export class WireAPI {
     async getMe() {
         return this.unwrapEnvelopeOrPlain(await this.request('GET', '/me'));
     }
-    async registerNode(name, capabilities) {
-        return this.request('POST', '/node/register', { name, capabilities });
+    async registerNode(name, capabilities, options = {}) {
+        return this.request('POST', '/node/register', { name, capabilities, ...options });
     }
     /**
      * Register a new Wire agent (unauthenticated — no token required).
@@ -256,7 +284,7 @@ export class WireAPI {
     async registerAgent(params) {
         // Registration doesn't require auth — use a raw fetch
         const url = `${this.baseUrl}/register`;
-        const res = await fetch(url, {
+        const res = await (this.httpFetch ?? fetch)(url, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify(params),
@@ -348,6 +376,8 @@ export class WireAPI {
         return results;
     }
     async browse(params) {
+        if (params.cursor && (params.item_id || params.entity))
+            throw new Error('cursor applies to item-list browsing; omit item_id/entity.');
         if (params.item_id) {
             if (params.include_definition) {
                 const qs = new URLSearchParams({ mode: 'inspect', include_definition: 'true' });
@@ -365,17 +395,23 @@ export class WireAPI {
                 qs.set('arc', params.arc);
             return this.request('GET', `/wire/entities?${qs.toString()}`);
         }
-        if (params.arc) {
-            return this.request('GET', `/wire/items?arc=${encodeURIComponent(params.arc)}`);
-        }
-        return this.request('GET', '/wire/items');
+        const qs = new URLSearchParams();
+        if (params.arc)
+            qs.set('arc', params.arc);
+        if (params.cursor)
+            qs.set('cursor', params.cursor);
+        if (params.limit !== undefined)
+            qs.set('limit', String(params.limit));
+        if (params.offset !== undefined)
+            qs.set('offset', String(params.offset));
+        return this.request('GET', `/wire/items${qs.size ? '?' + qs : ''}`);
     }
     async flag(params) {
         return this.request('POST', '/flag', params);
     }
     /**
      * Retract your own contribution (voluntary self-takedown).
-     * Economics: full deposit refund during grace window; half refund + half forfeit + bounty clawback after grace window.
+     * Economics: held deposits use the age-based forfeit and cap; refunded deposits apply the same rule to each actual refund recipient. No refund leg means no fee. Bounty recovery still applies.
      */
     async retract(contributionId) {
         return this.request('POST', '/retract', { contribution_id: contributionId });
@@ -383,7 +419,9 @@ export class WireAPI {
     /**
      * Access a contribution (detail endpoint). Accessing IS purchasing for priced items.
      */
-    async accessContribution(contributionId) {
+    async accessContribution(input, acceptPrice) {
+        const { contribution_id: contributionId, ...readParams } = typeof input === 'string'
+            ? { contribution_id: input, ...(acceptPrice === undefined ? {} : { accept_price: acceptPrice }) } : input;
         let identifier = contributionId;
         const localResult = await this.tryLocalContributionRead(identifier);
         if (localResult) {
@@ -412,7 +450,8 @@ export class WireAPI {
                 return localResolvedResult;
             }
         }
-        return this.request('GET', `/wire/contribution/${encodeURIComponent(identifier)}`);
+        const query = new URLSearchParams(Object.entries(readParams).filter(([, value]) => value !== undefined).map(([key, value]) => [key, String(value)]));
+        return this.request('GET', `/wire/contribution/${encodeURIComponent(identifier)}${query.size ? `?${query}` : ''}`);
     }
     async verifyLocalContributionReadRoute() {
         if (!this.localNodeEnabled)
@@ -422,7 +461,7 @@ export class WireAPI {
         if (this.localContributionRouteStatus)
             return this.localContributionRouteStatus;
         try {
-            const health = await fetch(`${this.localNodeUrl}/health`, {
+            const health = await (this.httpFetch ?? fetch)(`${this.localNodeUrl}/health`, {
                 method: 'GET',
                 signal: AbortSignal.timeout(2_000),
             });
@@ -430,7 +469,7 @@ export class WireAPI {
                 this.localContributionRouteStatus = 'unavailable';
                 return this.localContributionRouteStatus;
             }
-            const probe = await fetch(`${this.localNodeUrl}${localContributionReadPath('__wire_terminal_route_probe__')}`, {
+            const probe = await (this.httpFetch ?? fetch)(`${this.localNodeUrl}${localContributionReadPath('__wire_terminal_route_probe__')}`, {
                 method: 'GET',
                 headers: this.localHeaders(),
                 signal: AbortSignal.timeout(2_000),
@@ -464,7 +503,7 @@ export class WireAPI {
             return null;
         const path = localContributionReadPath(identifier);
         try {
-            const res = await fetch(`${this.localNodeUrl}${path}`, {
+            const res = await (this.httpFetch ?? fetch)(`${this.localNodeUrl}${path}`, {
                 method: 'GET',
                 headers: this.localHeaders(),
                 signal: AbortSignal.timeout(10_000),
@@ -498,7 +537,7 @@ export class WireAPI {
      * parsed JSON body on success, throws a descriptive error on non-2xx.
      */
     async localNodeFetch(method, path, body, timeoutMs = 15_000) {
-        const res = await fetch(`${this.localNodeUrl}${path}`, {
+        const res = await (this.httpFetch ?? fetch)(`${this.localNodeUrl}${path}`, {
             method,
             headers: this.localHeaders(),
             body: body !== undefined ? JSON.stringify(body) : undefined,
@@ -796,11 +835,13 @@ export class WireAPI {
     }
     // ── Operator Methods ───────────────────────────────────────
     /**
-     * Retract a contribution as an operator during the grace window.
-     * Requires operator-level authentication (the API token must belong
-     * to an operator, not a regular agent).
+     * Retract a contribution as an operator at any age. To correct a contribution,
+     * supersede it. Retraction uses the current window, rates and late refund cap.
+     * After settlement, the same rule applies to each actual refund recipient.
+     * Use operator authentication or the specific author agent token;
+     * sibling agent tokens cannot retract another agent's contribution.
      *
-     * Economics: full deposit refund during grace window; half refund + half forfeit + bounty clawback after grace window.
+     * Economics: held deposits use the age-based forfeit and cap; refunded deposits apply the same rule to each actual refund recipient. No refund leg means no fee. Bounty recovery still applies.
      *
      * @param agentId - The agent that owns the contribution
      * @param contributionId - The contribution to retract
@@ -884,7 +925,7 @@ export class WireAPI {
         if (this.threadId) {
             headers['X-Wire-Thread'] = this.threadId;
         }
-        const res = await fetch(url.toString(), {
+        const res = await (this.httpFetch ?? fetch)(url.toString(), {
             method: 'GET',
             headers,
             signal: options.signal,
@@ -923,6 +964,7 @@ export class WireAPI {
             }
         }
         finally {
+            await reader.cancel().catch(() => { });
             reader.releaseLock();
         }
     }
@@ -1047,7 +1089,9 @@ export class WireAPI {
         const runIdentifier = params.run_handle_path ?? params.run_id;
         if (!runIdentifier)
             throw new Error('pollChainRun requires run_handle_path or run_id');
-        const qs = new URLSearchParams({ chain: params.chain });
+        const qs = new URLSearchParams();
+        if (params.chain)
+            qs.set('chain', params.chain);
         if (params.include_steps)
             qs.set('include_steps', 'true');
         return this.request('GET', `/wire/chains/runs/${encodeURIComponent(runIdentifier)}?${qs.toString()}`, undefined, 30_000);
@@ -1072,7 +1116,7 @@ export class WireAPI {
     async executeSupersession(targetId, newContributionId, allowTypeChange) {
         // allow_type_change forwards to the REST endpoint (which already honors it) so a CROSS-TYPE
         // supersession is reachable via the CLI/MCP, not only via raw REST (WI playful/170/177).
-        const body = { new_contribution_id: newContributionId };
+        const body = { contribution_id: newContributionId };
         if (allowTypeChange)
             body.allow_type_change = true;
         return this.request('POST', `/wire/contributions/${encodeURIComponent(targetId)}/supersede`, body);
@@ -1244,6 +1288,9 @@ export class WireAPI {
         return this.requestUnwrap('GET', `/wire/documents${queryString ? '?' + queryString : ''}`);
     }
     async getDocumentBody(documentId) {
+        return (await this.downloadDocumentBody(documentId)).body;
+    }
+    async downloadDocumentBody(documentId) {
         const url = `${this.baseUrl}/wire/documents/${documentId}/body`;
         const headers = {
             'Authorization': `Bearer ${this.token}`,
@@ -1251,12 +1298,12 @@ export class WireAPI {
         if (this.threadId) {
             headers['X-Wire-Thread'] = this.threadId;
         }
-        const res = await fetch(url, { method: 'GET', headers, signal: AbortSignal.timeout(30_000) });
+        const res = await (this.httpFetch ?? fetch)(url, { method: 'GET', headers, signal: AbortSignal.timeout(30_000) });
         if (!res.ok) {
             const err = await res.json().catch(() => ({ error: res.statusText }));
             throw new Error(`API GET /wire/documents/${documentId}/body failed (${res.status}): ${err.error || res.statusText}`);
         }
-        return res.text();
+        return { body: await res.text(), content_sha256: res.headers.get('X-Body-Hash') };
     }
     async getDocumentGraph(documentId) {
         return this.request('GET', `/wire/documents/${documentId}/graph`);
@@ -1314,7 +1361,7 @@ export class WireAPI {
         const body = { email, device_fingerprint: deviceFingerprint };
         if (agentMessage)
             body.agent_message = agentMessage;
-        const res = await fetch(url, {
+        const res = await (this.httpFetch ?? fetch)(url, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify(body),
@@ -1330,7 +1377,7 @@ export class WireAPI {
     async verifyDeviceCode(email, deviceFingerprint, code) {
         // No auth required — raw fetch
         const url = `${this.baseUrl}/wire/device-auth`;
-        const res = await fetch(url, {
+        const res = await (this.httpFetch ?? fetch)(url, {
             method: 'PUT',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({ email, device_fingerprint: deviceFingerprint, code }),
@@ -1348,7 +1395,7 @@ export class WireAPI {
             url.searchParams.set('harness', harness);
         if (hintName)
             url.searchParams.set('hint_name', hintName);
-        const res = await fetch(url.toString(), {
+        const res = await (this.httpFetch ?? fetch)(url.toString(), {
             headers: { 'X-Wire-Device-Secret': deviceSecret },
             signal: AbortSignal.timeout(15_000),
         });
@@ -1360,7 +1407,7 @@ export class WireAPI {
         return json.data || json;
     }
     async resumeAgent(agentName, deviceSecret, nonce) {
-        const res = await fetch(`${this.baseUrl}/wire/agent/resume`, {
+        const res = await (this.httpFetch ?? fetch)(`${this.baseUrl}/wire/agent/resume`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',