@truealter/sdk 0.2.2 → 0.4.1

package/dist/index.d.ts

@@ -406,6 +406,24 @@ interface MCPClientOptions {
     clientInfo?: MCPClientInfo;
     /** Optional x402 client for automatic premium tool payment. */
     x402?: X402Client;
+    /**
+     * Q5c per-invocation signing. When present, every `tools/call` is
+     * ES256-signed and submitted with the `Mcp-Invocation-Signature`
+     * header. The public half of `privateKey` MUST have been
+     * registered via `POST /api/v1/agents/keys` against the same API
+     * key configured here. Required whenever `apiKey` is set and the
+     * server is in production / staging (hard-required from
+     * 2026-04-20).
+     */
+    signing?: MCPSigningOptions;
+}
+interface MCPSigningOptions {
+    /** The signing-key id pre-registered with the server. */
+    kid: string;
+    /** ES256 P-256 private key: 32-byte scalar or PEM. */
+    privateKey: Uint8Array | string;
+    /** The caller's bound ~handle. */
+    handle: string;
 }
 interface MCPCallOptions {
     /** Override the configured x402 client for this single call. */
@@ -454,6 +472,7 @@ declare class MCPClient {
     private readonly maxRetries;
     private readonly clientInfo;
     private readonly x402?;
+    private readonly signing?;
     private requestCounter;
     private initialised;
     constructor(opts?: MCPClientOptions);
@@ -476,6 +495,12 @@ declare class MCPClient {
      */
     rpc(method: string, params: Record<string, unknown> | unknown[] | undefined): Promise<unknown>;
     private buildHeaders;
+    /**
+     * Produce the `Mcp-Invocation-Signature` header for a `tools/call`
+     * payload, when signing is configured. Returns `undefined` when no
+     * signing key is attached or the method is not `tools/call`.
+     */
+    private buildSignatureHeader;
     private extractPaymentEnvelope;
     private guessToolName;
     private backoff;
@@ -536,6 +561,36 @@ interface MCPResponse<T> {
     };
     _meta?: MCPMeta;
 }
+/** (free) hello_agent — First handshake: returns server version, auth status, trust tier, tool counts */
+interface HelloAgentInput {
+}
+/** (free) hello_agent — output */
+interface HelloAgentOutput {
+    ok: boolean;
+    server?: string;
+    version?: string;
+    authenticated?: boolean;
+    tier?: string;
+    tools?: {
+        free?: number;
+        premium?: number;
+        messaging?: number;
+    };
+}
+/** (free) alter_resolve_handle — Resolve a ~handle (e.g. ~drew) to canonical form and kind */
+interface AlterResolveHandleInput {
+    query: string;
+}
+/** (free) alter_resolve_handle — output */
+interface AlterResolveHandleOutput {
+    ok: boolean;
+    handle: string | null;
+    kind?: "system" | "personal" | "role_alias" | string;
+    status: "found" | "not_found" | "invalid_format";
+    addressable: boolean;
+    default_visibility?: string;
+    query?: string;
+}
 /** (free) list_archetypes — List all 12 ALTER identity archetypes */
 interface ListArchetypesInput {
 }
@@ -647,31 +702,6 @@ interface GetCompetenciesOutput {
         awarded_at: string;
     }>;
 }
-/** (free) create_identity_stub — Create an anonymous identity stub for a human (consent required) */
-interface CreateIdentityStubInput {
-    source: string;
-    consent_acknowledged: boolean;
-    erc8004_agent_id?: string;
-}
-/** (free) create_identity_stub — output */
-interface CreateIdentityStubOutput {
-    ok: boolean;
-    stub_id: string;
-    claim_code: string;
-    expires_at: string;
-}
-/** (free) submit_context — Submit text context for an identity stub (PII redacted, raw text never stored) */
-interface SubmitContextInput {
-    stub_id: string;
-    text: string;
-    source_type?: "resume" | "work_sample" | "conversation" | "cover_letter" | "linkedin" | "portfolio" | "reference" | "interview_notes" | "performance_review" | "project_summary" | "general";
-}
-/** (free) submit_context — output */
-interface SubmitContextOutput {
-    ok: boolean;
-    traits_extracted: number;
-    confidence_cap: number;
-}
 /** (free) search_identities — Search identity stubs and profiles by trait criteria (max 5 results, no PII) */
 interface SearchIdentitiesInput {
     trait_criteria: Record<string, {
@@ -800,18 +830,6 @@ interface GetPrivacyBudgetOutput {
     query_count: number;
     window_hours: number;
 }
-/** (free) dispute_attestation — Dispute an attestation on a person's identity */
-interface DisputeAttestationInput {
-    attestation_id: string;
-    reason: string;
-}
-/** (free) dispute_attestation — output */
-interface DisputeAttestationOutput {
-    ok: boolean;
-    dispute_id: string;
-    attestation_id: string;
-    flagged_for_review: boolean;
-}
 /** (free) golden_thread_status — Check the Golden Thread program status */
 interface GoldenThreadStatusInput {
 }
@@ -984,71 +1002,6 @@ interface GenerateMatchNarrativeOutput {
     strengths: string[];
     growth_areas: string[];
 }
-/** (premium L2) submit_batch_context — Submit multiple context items in a single call (max 10) ($0.01) */
-interface SubmitBatchContextInput {
-    stub_id: string;
-    items: Array<{
-        text: string;
-        source_type?: string;
-    }>;
-    consent_acknowledged: boolean;
-    _payment?: ProvenanceToken;
-}
-/** (premium L2) submit_batch_context — output */
-interface SubmitBatchContextOutput {
-    ok: boolean;
-    items_processed: number;
-    traits_extracted: number;
-}
-/** (premium L1) submit_structured_profile — Submit structured profile data (name, skills, experience) ($0.005) */
-interface SubmitStructuredProfileInput {
-    stub_id: string;
-    name?: string;
-    skills?: string[];
-    experience?: string;
-    education?: string;
-    certifications?: string[];
-    consent_acknowledged: boolean;
-    _payment?: ProvenanceToken;
-}
-/** (premium L1) submit_structured_profile — output */
-interface SubmitStructuredProfileOutput {
-    ok: boolean;
-    stub_id: string;
-    traits_extracted: number;
-}
-/** (premium L1) submit_social_links — Submit social profile URLs (max 5) ($0.005) */
-interface SubmitSocialLinksInput {
-    stub_id: string;
-    urls: string[];
-    consent_acknowledged: boolean;
-    _payment?: ProvenanceToken;
-}
-/** (premium L1) submit_social_links — output */
-interface SubmitSocialLinksOutput {
-    ok: boolean;
-    stub_id: string;
-    urls_fetched: number;
-    urls_blocked: number;
-    traits_extracted: number;
-}
-/** (premium L1) attest_domain — Attest that a human has competence in a specific domain ($0.005) */
-interface AttestDomainInput {
-    candidate_id: string;
-    domain_label: string;
-    confidence: number;
-    evidence_type: "OBSERVED" | "INFERRED" | "REPORTED";
-    evidence_summary?: string;
-    _payment?: ProvenanceToken;
-}
-/** (premium L1) attest_domain — output */
-interface AttestDomainOutput {
-    ok: boolean;
-    attestation_id: string;
-    candidate_id: string;
-    domain_label: string;
-    weighted_confidence: number;
-}
 /** (premium L2) get_side_quest_graph — Get a person's Side Quest Graph (DP noise ε=1.0) ($0.01) */
 interface GetSideQuestGraphInput {
     candidate_id: string;
@@ -1088,13 +1041,15 @@ interface QueryGraphSimilarityOutput {
     complementarity: number;
     privacy_epsilon: number;
 }
-/** Free (L0 / L1 with first-100-free) tool names — readonly tuple */
-declare const FREE_TOOL_NAMES: readonly ["list_archetypes", "verify_identity", "initiate_assessment", "get_engagement_level", "get_profile", "query_matches", "get_competencies", "create_identity_stub", "submit_context", "search_identities", "get_identity_earnings", "get_network_stats", "recommend_tool", "get_identity_trust_score", "check_assessment_status", "get_earning_summary", "get_agent_trust_tier", "get_agent_portfolio", "get_privacy_budget", "dispute_attestation", "golden_thread_status", "begin_golden_thread", "complete_knot", "check_golden_thread", "thread_census"];
-/** Premium (x402-gated) tool names — readonly tuple */
-declare const PREMIUM_TOOL_NAMES: readonly ["assess_traits", "get_trait_snapshot", "get_full_trait_vector", "compute_belonging", "get_match_recommendations", "generate_match_narrative", "submit_batch_context", "submit_structured_profile", "submit_social_links", "attest_domain", "get_side_quest_graph", "query_graph_similarity"];
-/** Union of all 40 tool names */
+/** Free (L0) tool names — readonly tuple. Mirrors the live server's `tools/list` free set. */
+declare const FREE_TOOL_NAMES: readonly ["hello_agent", "alter_resolve_handle", "list_archetypes", "verify_identity", "initiate_assessment", "get_engagement_level", "get_profile", "query_matches", "get_competencies", "search_identities", "get_identity_earnings", "get_network_stats", "recommend_tool", "get_identity_trust_score", "check_assessment_status", "get_earning_summary", "get_agent_trust_tier", "get_agent_portfolio", "get_privacy_budget", "golden_thread_status", "begin_golden_thread", "complete_knot", "check_golden_thread", "thread_census"];
+/** Premium (x402-gated, L1-L5) tool names — readonly tuple. Mirrors the live server's `tools/list` premium set. */
+declare const PREMIUM_TOOL_NAMES: readonly ["assess_traits", "get_trait_snapshot", "get_full_trait_vector", "compute_belonging", "get_match_recommendations", "generate_match_narrative", "get_side_quest_graph", "query_graph_similarity"];
+/** Union of all 32 tool names */
 type ToolName = (typeof FREE_TOOL_NAMES)[number] | (typeof PREMIUM_TOOL_NAMES)[number];
 interface ToolInputs {
+    hello_agent: HelloAgentInput;
+    alter_resolve_handle: AlterResolveHandleInput;
     list_archetypes: ListArchetypesInput;
     verify_identity: VerifyIdentityInput;
     initiate_assessment: InitiateAssessmentInput;
@@ -1102,8 +1057,6 @@ interface ToolInputs {
     get_profile: GetProfileInput;
     query_matches: QueryMatchesInput;
     get_competencies: GetCompetenciesInput;
-    create_identity_stub: CreateIdentityStubInput;
-    submit_context: SubmitContextInput;
     search_identities: SearchIdentitiesInput;
     get_identity_earnings: GetIdentityEarningsInput;
     get_network_stats: GetNetworkStatsInput;
@@ -1114,7 +1067,6 @@ interface ToolInputs {
     get_agent_trust_tier: GetAgentTrustTierInput;
     get_agent_portfolio: GetAgentPortfolioInput;
     get_privacy_budget: GetPrivacyBudgetInput;
-    dispute_attestation: DisputeAttestationInput;
     golden_thread_status: GoldenThreadStatusInput;
     begin_golden_thread: BeginGoldenThreadInput;
     complete_knot: CompleteKnotInput;
@@ -1126,14 +1078,12 @@ interface ToolInputs {
     compute_belonging: ComputeBelongingInput;
     get_match_recommendations: GetMatchRecommendationsInput;
     generate_match_narrative: GenerateMatchNarrativeInput;
-    submit_batch_context: SubmitBatchContextInput;
-    submit_structured_profile: SubmitStructuredProfileInput;
-    submit_social_links: SubmitSocialLinksInput;
-    attest_domain: AttestDomainInput;
     get_side_quest_graph: GetSideQuestGraphInput;
     query_graph_similarity: QueryGraphSimilarityInput;
 }
 interface ToolOutputs {
+    hello_agent: HelloAgentOutput;
+    alter_resolve_handle: AlterResolveHandleOutput;
     list_archetypes: ListArchetypesOutput;
     verify_identity: VerifyIdentityOutput;
     initiate_assessment: InitiateAssessmentOutput;
@@ -1141,8 +1091,6 @@ interface ToolOutputs {
     get_profile: GetProfileOutput;
     query_matches: QueryMatchesOutput;
     get_competencies: GetCompetenciesOutput;
-    create_identity_stub: CreateIdentityStubOutput;
-    submit_context: SubmitContextOutput;
     search_identities: SearchIdentitiesOutput;
     get_identity_earnings: GetIdentityEarningsOutput;
     get_network_stats: GetNetworkStatsOutput;
@@ -1153,7 +1101,6 @@ interface ToolOutputs {
     get_agent_trust_tier: GetAgentTrustTierOutput;
     get_agent_portfolio: GetAgentPortfolioOutput;
     get_privacy_budget: GetPrivacyBudgetOutput;
-    dispute_attestation: DisputeAttestationOutput;
     golden_thread_status: GoldenThreadStatusOutput;
     begin_golden_thread: BeginGoldenThreadOutput;
     complete_knot: CompleteKnotOutput;
@@ -1165,10 +1112,6 @@ interface ToolOutputs {
     compute_belonging: ComputeBelongingOutput;
     get_match_recommendations: GetMatchRecommendationsOutput;
     generate_match_narrative: GenerateMatchNarrativeOutput;
-    submit_batch_context: SubmitBatchContextOutput;
-    submit_structured_profile: SubmitStructuredProfileOutput;
-    submit_social_links: SubmitSocialLinksOutput;
-    attest_domain: AttestDomainOutput;
     get_side_quest_graph: GetSideQuestGraphOutput;
     query_graph_similarity: QueryGraphSimilarityOutput;
 }
@@ -1194,8 +1137,8 @@ declare const TOOL_BLAST_RADIUS: Record<ToolName, "low" | "medium" | "high">;
  *
  * This is the entry point most consumers will use. It bundles
  * {@link MCPClient}, {@link X402Client}, discovery, and provenance
- * verification into a single ergonomic surface that mirrors the 40
- * tools exposed at https://mcp.truealter.com.
+ * verification into a single ergonomic surface that mirrors the 32
+ * tools exposed at https://mcp.truealter.com/api/v1/mcp.
  *
  * Free tier methods require no authentication. Premium methods accept
  * an `X402Client` (or fall back to throwing {@link AlterPaymentRequired}
@@ -1259,6 +1202,10 @@ declare class AlterClient {
      * you want fail-fast behaviour.
      */
     initialize(): Promise<void>;
+    /** First handshake — confirms the connection, returns trust tier and tool counts. */
+    helloAgent(): Promise<MCPCallToolResult>;
+    /** Resolve a ~handle (e.g. ~drew) to its canonical form and kind. No auth required. */
+    resolveHandle(args: AlterResolveHandleInput | string): Promise<MCPCallToolResult>;
     /** Verify a person is registered with ALTER (handle or id). */
     verify(handleOrId: string, claims?: VerifyIdentityInput['claims']): Promise<MCPCallToolResult>;
     /** List the 12 ALTER identity archetypes. */
@@ -1272,8 +1219,6 @@ declare class AlterClient {
     getProfile(args: GetProfileInput): Promise<MCPCallToolResult>;
     queryMatches(args: QueryMatchesInput): Promise<MCPCallToolResult>;
     getCompetencies(args: GetCompetenciesInput): Promise<MCPCallToolResult>;
-    createIdentityStub(args: CreateIdentityStubInput): Promise<MCPCallToolResult>;
-    submitContext(args: SubmitContextInput): Promise<MCPCallToolResult>;
     searchIdentities(args: SearchIdentitiesInput): Promise<MCPCallToolResult>;
     getIdentityEarnings(args: GetIdentityEarningsInput): Promise<MCPCallToolResult>;
     getIdentityTrustScore(args: GetIdentityTrustScoreInput): Promise<MCPCallToolResult>;
@@ -1282,7 +1227,6 @@ declare class AlterClient {
     getAgentTrustTier(): Promise<MCPCallToolResult>;
     getAgentPortfolio(): Promise<MCPCallToolResult>;
     getPrivacyBudget(args: GetPrivacyBudgetInput): Promise<MCPCallToolResult>;
-    disputeAttestation(args: DisputeAttestationInput): Promise<MCPCallToolResult>;
     goldenThreadStatus(): Promise<MCPCallToolResult>;
     beginGoldenThread(args?: BeginGoldenThreadInput): Promise<MCPCallToolResult>;
     completeKnot(args: CompleteKnotInput): Promise<MCPCallToolResult>;
@@ -1294,10 +1238,6 @@ declare class AlterClient {
     computeBelonging(args: ComputeBelongingInput, opts?: MCPCallOptions): Promise<MCPCallToolResult>;
     getMatchRecommendations(args: GetMatchRecommendationsInput, opts?: MCPCallOptions): Promise<MCPCallToolResult>;
     generateMatchNarrative(args: GenerateMatchNarrativeInput, opts?: MCPCallOptions): Promise<MCPCallToolResult>;
-    submitBatchContext(args: SubmitBatchContextInput, opts?: MCPCallOptions): Promise<MCPCallToolResult>;
-    submitStructuredProfile(args: SubmitStructuredProfileInput, opts?: MCPCallOptions): Promise<MCPCallToolResult>;
-    submitSocialLinks(args: SubmitSocialLinksInput, opts?: MCPCallOptions): Promise<MCPCallToolResult>;
-    attestDomain(args: AttestDomainInput, opts?: MCPCallOptions): Promise<MCPCallToolResult>;
     getSideQuestGraph(args: GetSideQuestGraphInput, opts?: MCPCallOptions): Promise<MCPCallToolResult>;
     queryGraphSimilarity(args: QueryGraphSimilarityInput, opts?: MCPCallOptions): Promise<MCPCallToolResult>;
     /** Send a direct message to another tilde handle. */
@@ -1357,6 +1297,76 @@ declare class AlterClient {
     fetchPublicKeys(): Promise<unknown>;
 }
 
+/**
+ * Stable stringify mirroring Python's
+ *   `json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False)`.
+ *
+ * Rules:
+ *   - object keys are sorted ascending by codepoint
+ *   - no whitespace
+ *   - `ensure_ascii=False` — non-ASCII characters pass through verbatim
+ *     (not re-encoded as \\uXXXX). UTF-8 encoding happens at the byte
+ *     layer before hashing.
+ *
+ * This is RFC-8785 adjacent; it is NOT a full JCS implementation
+ * (numeric canonicalisation is delegated to the caller).
+ */
+declare function canonicalStringify(value: unknown): string;
+/**
+ * Hex SHA-256 of the canonical JSON encoding of `toolArgs`. Matches
+ * `canonical_args_sha256` in the server-side verifier.
+ */
+declare function canonicalArgsSha256(toolArgs: Record<string, unknown>): string;
+/**
+ * Load an ES256 P-256 private key.
+ *
+ * Accepts:
+ *   - a 32-byte `Uint8Array` containing the raw d-scalar
+ *   - a PEM string (PKCS#8 or SEC1). Node's `crypto.createPrivateKey`
+ *     is used when available to parse the PEM; on non-Node runtimes
+ *     only the raw-bytes form is supported.
+ */
+declare function loadPrivateKey(key: Uint8Array | string): Uint8Array;
+interface InvocationClaims {
+    /** Tool name — must equal the `tools/call` `params.name`. */
+    tool: string;
+    /** Hex SHA-256 of canonical-JSON `tool_args`. */
+    args_sha256: string;
+    /** Random string, at least ~16 bytes of entropy (base64url). */
+    nonce: string;
+    /** Epoch seconds. Server accepts ±60s skew. */
+    iat: number;
+    /** The caller's bound ~handle. */
+    iss: string;
+}
+interface SignInvocationOptions {
+    /** The signing-key id pre-registered on the server. */
+    kid: string;
+    /** P-256 private key (32-byte Uint8Array or PEM string). */
+    privateKey: Uint8Array | string;
+    /** The caller's bound ~handle. */
+    handle: string;
+    /** Override nonce (tests). Defaults to 24 random bytes base64url. */
+    nonce?: string;
+    /** Override iat (tests). Defaults to now. */
+    iatSeconds?: number;
+}
+/**
+ * Produce the `Mcp-Invocation-Signature` header value for a single
+ * `tools/call`. The returned string is a compact JWS:
+ *   `base64url(header) . base64url(payload) . base64url(signature)`
+ *
+ * Usage:
+ *
+ * ```ts
+ * const header = signInvocation("get_profile", { candidate_id: "abc" }, {
+ *   kid, privateKey, handle: "~tester",
+ * });
+ * fetch(url, { headers: { "Mcp-Invocation-Signature": header } });
+ * ```
+ */
+declare function signInvocation(toolName: string, toolArgs: Record<string, unknown>, options: SignInvocationOptions): string;
+
 interface McpServerConfig {
     url: string;
     transport: 'streamable-http';
@@ -1401,22 +1411,202 @@ declare function generateClaudeConfig(opts?: GenerateMcpConfigOptions): GenericM
 declare function generateCursorConfig(opts?: GenerateMcpConfigOptions): GenericMcpConfig;
 
 /**
- * @truealter/sdk — ALTER Identity SDK
+ * Claude Desktop MCP config helper.
+ *
+ * Claude Desktop speaks stdio only — it does not currently dial
+ * Streamable-HTTP MCP servers directly. The canonical bridge is our
+ * own `alter-mcp-bridge` binary, which is published alongside this CLI
+ * in the same npm package. Desktop hosts then spawn the bridge as a
+ * child process and read JSON-RPC over stdin/stdout.
+ *
+ * Config file path varies by platform and is resolved in
+ * `src/wire/paths.ts`. This adapter only produces the config *shape*.
+ */
+interface ClaudeDesktopServerConfig {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    description?: string;
+}
+interface ClaudeDesktopConfig {
+    mcpServers: Record<string, ClaudeDesktopServerConfig>;
+}
+interface GenerateClaudeDesktopOptions {
+    /** Override the MCP endpoint the bridge dials. Defaults to DEFAULT_ENDPOINT. */
+    endpoint?: string;
+    /** Optional API key passed via `ALTER_API_KEY` env so it never lands in argv. */
+    apiKey?: string;
+    /** Identifier used by Claude Desktop for this server. Default: `alter`. */
+    serverName?: string;
+    /** Override the bridge command (e.g. `npx alter-mcp-bridge`). Default: bare `alter-mcp-bridge`. */
+    bridgeCommand?: string;
+    /** Extra args appended after the default bridge args. */
+    extraArgs?: string[];
+}
+declare function generateClaudeDesktopConfig(opts?: GenerateClaudeDesktopOptions): ClaudeDesktopConfig;
+
+type ClientId = 'claude-code' | 'cursor' | 'claude-desktop' | 'vscode';
+interface ClientPaths {
+    id: ClientId;
+    /** Human-readable label. */
+    label: string;
+    /** The config file the wire step will mutate (or null if the client uses a CLI-only handoff). */
+    configPath: string | null;
+    /** A sibling directory whose presence counts as "the client is installed on this box". */
+    probeDir: string;
+    /** The `mcpServers`-shaped root key under which our entry is written. Defaults to `mcpServers`. */
+    rootKey: string;
+}
+declare const CLAUDE_CODE: ClientPaths;
+declare const CURSOR: ClientPaths;
+declare const CLAUDE_DESKTOP: ClientPaths;
+declare const VSCODE: ClientPaths;
+declare const ALL_CLIENTS: readonly ClientPaths[];
+
+/**
+ * Detect which MCP-aware clients are installed on this machine.
+ *
+ * Probe signals, per client:
+ *   - claude-code   : `claude` binary resolvable on PATH (spawn `--version`)
+ *   - cursor        : `~/.cursor/` directory exists
+ *   - claude-desktop: platform config directory exists
+ *   - vscode        : VS Code user data directory exists
+ *
+ * The probe is deliberately permissive — "the config directory exists"
+ * means either the app is installed or was recently installed. Wire
+ * will still refuse if the config file ends up on a synced volume.
+ */
+
+interface ProbeResult {
+    client: ClientPaths;
+    installed: boolean;
+    /** Only present for claude-code — records `claude --version` output when resolvable. */
+    version?: string;
+    /** Diagnostic trail — why we said installed/not. */
+    reason: string;
+}
+declare function probeClaudeCode(): ProbeResult;
+declare function probeByDir(id: ClientId): ProbeResult;
+declare function probeAll(): ProbeResult[];
+
+/**
+ * `wire-state.json` provenance artefact.
+ *
+ * Written to `$XDG_CONFIG_HOME/alter/wire-state.json` after every wire
+ * run. Holds everything `unwire` needs to reverse the operation without
+ * guessing, plus enough metadata (SDK version, timestamps, SHAs pre and
+ * post) to make the operation auditable.
+ *
+ * Append-only semantics: a new wire run rewrites this file in full.
+ * Prior state is not retained — the backup siblings on disk are the
+ * canonical rollback surface, not this file.
+ */
+
+declare const WIRE_STATE_VERSION = 1;
+type WireTargetStatus = 'written' | 'already-wired' | 'skipped' | 'failed';
+interface WireTargetFile {
+    client: ClientId;
+    method: 'file';
+    status: WireTargetStatus;
+    path: string;
+    backupPath: string | null;
+    rootKey: string;
+    serverName: string;
+    preSha256: string | null;
+    postSha256: string;
+    reason?: string;
+}
+interface WireTargetCli {
+    client: ClientId;
+    method: 'cli';
+    status: WireTargetStatus;
+    command: string;
+    stdout?: string;
+    stderr?: string;
+    reason?: string;
+}
+type WireTarget = WireTargetFile | WireTargetCli;
+interface WireState {
+    version: typeof WIRE_STATE_VERSION;
+    sdkVersion: string;
+    writtenAt: string;
+    endpoint: string;
+    targets: WireTarget[];
+}
+declare function readWireState(): WireState | null;
+declare function writeWireState(state: WireState): void;
+
+/**
+ * Refuse to wire any client whose config sits on a synced volume.
  *
- * Query the continuous identity field from any JavaScript/TypeScript
- * environment. Wraps the ALTER MCP server (29 invokable read tools at
- * this stage). Write tools (submit_*, attest_domain, dispute_attestation,
- * create_identity_stub) and alter-to-alter messaging tools are not
- * advertised to public callers — they re-enable as the consent
- * architecture and per-peer grant model land. First-class TypeScript
- * types, x402 micropayment support, and ES256 provenance verification.
+ * Writing MCP config under iCloud / OneDrive / Dropbox / Google Drive
+ * silently propagates the same `mcpServers.alter` entry (and API key
+ * headers) to every other device the user syncs. That is a consent
+ * violation — wire consent is per-device.
  *
- * The ALTER endpoint discovery anchor is `truealter.com` — see
- * `discover()` for the cascade. The default MCP endpoint is
- * `https://mcp.truealter.com`.
+ * The check is a prefix match against the resolved absolute path; it
+ * is deliberately broader than strictly necessary so that users who
+ * symlink their home directory into a synced volume (a known Mac
+ * pattern) are also caught.
  */
+interface SyncedVolumeHit {
+    refused: true;
+    matchedPrefix: string;
+    resolvedPath: string;
+}
+/**
+ * Returns a hit record if the resolved path lives under a known synced
+ * volume, null otherwise. Normalises path separators so the check is
+ * Windows-safe without hardcoding `\`.
+ */
+declare function detectSyncedVolume(path: string): SyncedVolumeHit | null;
+
+declare function sha256(bytes: string | Buffer): string;
 
+/**
+ * Public `wire` / `unwire` entry points.
+ *
+ * `wire()` probes for installed MCP clients, merges the ALTER entry
+ * into each client's config (via atomic JSON merge or CLI handoff),
+ * writes a `wire-state.json` provenance artefact, and returns a
+ * structured report. `unwire()` reads that artefact and reverses
+ * every target.
+ *
+ * Synchronous throughout — the CLI path is sequential and the
+ * deterministic ordering is worth the tiny blocking cost.
+ */
+
+interface WireOptions {
+    /** Override the endpoint written into every client config. Defaults to DEFAULT_ENDPOINT. */
+    endpoint?: string;
+    /** Optional API key written into `headers['X-ALTER-API-Key']` for each target. */
+    apiKey?: string;
+    /** Restrict to a subset of client ids. Default: every detected client. */
+    only?: readonly ClientId[];
+    /** Skip any client whose probe said "not installed" even if the caller passed it via `only`. */
+    skipMissing?: boolean;
+}
+interface WireReport {
+    state: WireState;
+    probes: ProbeResult[];
+}
+declare function wire(opts?: WireOptions): WireReport;
+interface UnwireReport {
+    state: WireState | null;
+    undone: Array<{
+        client: ClientId;
+        action: 'restored' | 'removed' | 'cli-removed' | 'skipped' | 'failed';
+        reason?: string;
+    }>;
+}
+declare function unwire(): UnwireReport;
+
+/**
+ * Package metadata — kept in a standalone module so deep imports from
+ * `src/wire/` can reference version constants without creating a
+ * circular dependency through `src/index.ts`.
+ */
 declare const SDK_NAME = "@truealter/sdk";
-declare const SDK_VERSION = "0.1.1";
+declare const SDK_VERSION = "0.3.0";
 
-export { AlterAuthError, AlterClient, type AlterClientOptions, AlterDiscoveryError, AlterError, type AlterErrorCode, AlterInvalidResponse, AlterNetworkError, AlterPaymentRequired, AlterProvenanceError, AlterRateLimited, AlterTimeoutError, AlterToolError, type ApiKeyConfig, type Archetype, type AssessTraitsInput, type AssessTraitsOutput, type AttestDomainInput, type AttestDomainOutput, type BeginGoldenThreadInput, type BeginGoldenThreadOutput, type CheckAssessmentStatusInput, type CheckAssessmentStatusOutput, type CheckGoldenThreadInput, type CheckGoldenThreadOutput, type CompleteKnotInput, type CompleteKnotOutput, type ComputeBelongingInput, type ComputeBelongingOutput, type CreateIdentityStubInput, type CreateIdentityStubOutput, DEFAULT_DOMAIN, DEFAULT_ENDPOINT, DEFAULT_VERIFY_AT_ALLOWLIST, type DiscoveryOptions, type DiscoveryResult, type DisputeAttestationInput, type DisputeAttestationOutput, type Ed25519Keypair, type EngagementLevel, FREE_TOOL_NAMES, type GenerateMatchNarrativeInput, type GenerateMatchNarrativeOutput, type GetAgentPortfolioInput, type GetAgentPortfolioOutput, type GetAgentTrustTierInput, type GetAgentTrustTierOutput, type GetCompetenciesInput, type GetCompetenciesOutput, type GetEarningSummaryInput, type GetEarningSummaryOutput, type GetEngagementLevelInput, type GetEngagementLevelOutput, type GetFullTraitVectorInput, type GetFullTraitVectorOutput, type GetIdentityEarningsInput, type GetIdentityEarningsOutput, type GetIdentityTrustScoreInput, type GetIdentityTrustScoreOutput, type GetMatchRecommendationsInput, type GetMatchRecommendationsOutput, type GetNetworkStatsInput, type GetNetworkStatsOutput, type GetPrivacyBudgetInput, type GetPrivacyBudgetOutput, type GetProfileInput, type GetProfileOutput, type GetSideQuestGraphInput, type GetSideQuestGraphOutput, type GetTraitSnapshotInput, type GetTraitSnapshotOutput, type GoldenThreadStatusInput, type GoldenThreadStatusOutput, type InitiateAssessmentInput, type InitiateAssessmentOutput, type JsonWebKey, type JwksDocument, type ListArchetypesInput, type ListArchetypesOutput, type MCPCallOptions, type MCPCallToolResult, MCPClient, type MCPClientInfo, type MCPClientOptions, type MCPContentBlock, type MCPListToolsResult, type MCPMeta, type MCPResponse, type MCPToolDefinition, MCP_PROTOCOL_VERSION, type MatchTier, type McpServerConfig, PREMIUM_TOOL_NAMES, type PaymentEnvelope, type ProvenanceEnvelope, type ProvenancePayload, type ProvenanceToken, type ProvenanceVerification, type QueryGraphSimilarityInput, type QueryGraphSimilarityOutput, type QueryMatchesInput, type QueryMatchesOutput, type RecommendToolInput, type RecommendToolOutput, SDK_NAME, SDK_VERSION, type SearchIdentitiesInput, type SearchIdentitiesOutput, type SignedToolDefinition, type SubmitBatchContextInput, type SubmitBatchContextOutput, type SubmitContextInput, type SubmitContextOutput, type SubmitSocialLinksInput, type SubmitSocialLinksOutput, type SubmitStructuredProfileInput, type SubmitStructuredProfileOutput, TOOL_BLAST_RADIUS, TOOL_COSTS, TOOL_TIERS, type ThreadCensusInput, type ThreadCensusOutput, type ToolInputs, type ToolName, type ToolOutputs, type ToolSignatureMap, type VerifyIdentityInput, type VerifyIdentityOutput, type VerifyProvenanceOptions, X402Client, type X402ClientOptions, type X402Settlement, type X402Signer, base64urlDecode, base64urlEncode, clearDiscoveryCache, decodeDid, discover, encodeDid, fetchPublicKeys, generateClaudeConfig, generateCursorConfig, generateGenericMcpConfig, generateKeypair, keypairFromPrivateKey, parsePaymentHeader, resolveVerifyAt, sign, verify, verifyProvenance, verifyToolSignatures };
+export { ALL_CLIENTS, AlterAuthError, AlterClient, type AlterClientOptions, AlterDiscoveryError, AlterError, type AlterErrorCode, AlterInvalidResponse, AlterNetworkError, AlterPaymentRequired, AlterProvenanceError, AlterRateLimited, type AlterResolveHandleInput, type AlterResolveHandleOutput, AlterTimeoutError, AlterToolError, type ApiKeyConfig, type Archetype, type AssessTraitsInput, type AssessTraitsOutput, type BeginGoldenThreadInput, type BeginGoldenThreadOutput, CLAUDE_CODE, CLAUDE_DESKTOP, CURSOR, type CheckAssessmentStatusInput, type CheckAssessmentStatusOutput, type CheckGoldenThreadInput, type CheckGoldenThreadOutput, type ClaudeDesktopConfig, type ClaudeDesktopServerConfig, type ClientId, type ClientPaths, type CompleteKnotInput, type CompleteKnotOutput, type ComputeBelongingInput, type ComputeBelongingOutput, DEFAULT_DOMAIN, DEFAULT_ENDPOINT, DEFAULT_VERIFY_AT_ALLOWLIST, type DiscoveryOptions, type DiscoveryResult, type Ed25519Keypair, type EngagementLevel, FREE_TOOL_NAMES, type GenerateClaudeDesktopOptions, type GenerateMatchNarrativeInput, type GenerateMatchNarrativeOutput, type GetAgentPortfolioInput, type GetAgentPortfolioOutput, type GetAgentTrustTierInput, type GetAgentTrustTierOutput, type GetCompetenciesInput, type GetCompetenciesOutput, type GetEarningSummaryInput, type GetEarningSummaryOutput, type GetEngagementLevelInput, type GetEngagementLevelOutput, type GetFullTraitVectorInput, type GetFullTraitVectorOutput, type GetIdentityEarningsInput, type GetIdentityEarningsOutput, type GetIdentityTrustScoreInput, type GetIdentityTrustScoreOutput, type GetMatchRecommendationsInput, type GetMatchRecommendationsOutput, type GetNetworkStatsInput, type GetNetworkStatsOutput, type GetPrivacyBudgetInput, type GetPrivacyBudgetOutput, type GetProfileInput, type GetProfileOutput, type GetSideQuestGraphInput, type GetSideQuestGraphOutput, type GetTraitSnapshotInput, type GetTraitSnapshotOutput, type GoldenThreadStatusInput, type GoldenThreadStatusOutput, type HelloAgentInput, type HelloAgentOutput, type InitiateAssessmentInput, type InitiateAssessmentOutput, type InvocationClaims, type JsonWebKey, type JwksDocument, type ListArchetypesInput, type ListArchetypesOutput, type MCPCallOptions, type MCPCallToolResult, MCPClient, type MCPClientInfo, type MCPClientOptions, type MCPContentBlock, type MCPListToolsResult, type MCPMeta, type MCPResponse, type MCPSigningOptions, type MCPToolDefinition, MCP_PROTOCOL_VERSION, type MatchTier, type McpServerConfig, PREMIUM_TOOL_NAMES, type PaymentEnvelope, type ProbeResult, type ProvenanceEnvelope, type ProvenancePayload, type ProvenanceToken, type ProvenanceVerification, type QueryGraphSimilarityInput, type QueryGraphSimilarityOutput, type QueryMatchesInput, type QueryMatchesOutput, type RecommendToolInput, type RecommendToolOutput, SDK_NAME, SDK_VERSION, type SearchIdentitiesInput, type SearchIdentitiesOutput, type SignInvocationOptions, type SignedToolDefinition, TOOL_BLAST_RADIUS, TOOL_COSTS, TOOL_TIERS, type ThreadCensusInput, type ThreadCensusOutput, type ToolInputs, type ToolName, type ToolOutputs, type ToolSignatureMap, type UnwireReport, VSCODE, type VerifyIdentityInput, type VerifyIdentityOutput, type VerifyProvenanceOptions, type WireOptions, type WireReport, type WireState, type WireTarget, type WireTargetCli, type WireTargetFile, X402Client, type X402ClientOptions, type X402Settlement, type X402Signer, base64urlDecode, base64urlEncode, canonicalArgsSha256, canonicalStringify, clearDiscoveryCache, decodeDid, detectSyncedVolume, discover, encodeDid, fetchPublicKeys, generateClaudeConfig, generateClaudeDesktopConfig, generateCursorConfig, generateGenericMcpConfig, generateKeypair, keypairFromPrivateKey, loadPrivateKey, parsePaymentHeader, probeAll, probeByDir, probeClaudeCode, readWireState, resolveVerifyAt, sha256, sign, signInvocation, unwire, verify, verifyProvenance, verifyToolSignatures, wire, writeWireState };