@provian/mcp 0.0.0-stage → 1.2.1

package/dist/core/tool-set.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registeredToolNames = registeredToolNames;
+exports.diffToolSet = diffToolSet;
+exports.assertServedToolSet = assertServedToolSet;
+exports.privateKeyFieldViolations = privateKeyFieldViolations;
+/**
+ * The ONE comparator every tool-list pin binds to.
+ *
+ * `tools/list` serves `PROVIAN_TOOLS` verbatim (server.ts), in every mode, over stdio and over
+ * the relay's `/mcp` mount (the relay serves this same core, mirrored by
+ * scripts/sync-mcp-core.sh). A test that pins the served list must therefore compare it with
+ * that registry, never with a redeclared literal: five such literals (three here, two in the
+ * relay) each held their own copy of the tool names and went red when added tools
+ * (`answer_challenge`, `feature_item`, …). Binding to the single source ends that class.
+ *
+ * The comparator is not vacuous by construction: an empty registry is refused (a comparison
+ * over zero tools proves nothing), and a missing, an extra, or a duplicated served name each
+ * fail with the offending names (see the RED control in tools.test.ts).
+ */
+const tools_1 = require("./tools");
+const key_custody_1 = require("./key-custody");
+/** The registered tool names, sorted — the single source every pin compares against. */
+function registeredToolNames() {
+    return tools_1.PROVIAN_TOOLS.map((t) => t.name).sort();
+}
+function diffToolSet(served, registered = registeredToolNames()) {
+    const servedSet = new Set(served);
+    const registeredSet = new Set(registered);
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const name of served) {
+        if (seen.has(name))
+            duplicates.add(name);
+        seen.add(name);
+    }
+    return {
+        missing: [...registeredSet].filter((name) => !servedSet.has(name)).sort(),
+        extra: [...servedSet].filter((name) => !registeredSet.has(name)).sort(),
+        duplicates: [...duplicates].sort(),
+    };
+}
+/** Throws unless `served` is exactly the registered set, once each, over a non-empty registry. */
+function assertServedToolSet(served, registered = registeredToolNames()) {
+    if (registered.length === 0) {
+        throw new Error('tool registry is empty: a comparison over zero tools proves nothing');
+    }
+    const diff = diffToolSet(served, registered);
+    if (diff.missing.length > 0 || diff.extra.length > 0 || diff.duplicates.length > 0) {
+        throw new Error(`served tool set differs from the registry: missing [${diff.missing.join(', ')}] `
+            + `extra [${diff.extra.join(', ')}] duplicated [${diff.duplicates.join(', ')}]`);
+    }
+}
+/**
+ * Every input, across the given tools, that names private key material and is not the one
+ * declared local-only field. Empty means no tool schema accepts a private key. The input
+ * type is wide on purpose (any name + schema) so a violating registry is constructible in
+ * the RED control.
+ */
+function privateKeyFieldViolations(tools = tools_1.PROVIAN_TOOLS) {
+    const out = [];
+    for (const tool of tools) {
+        const allowed = key_custody_1.LOCAL_ONLY_PRIVATE_KEY_FIELDS[tool.name] ?? [];
+        for (const field of (0, key_custody_1.findPrivateKeyFields)(tool.inputSchema)) {
+            if (!allowed.includes(field))
+                out.push({ tool: tool.name, field });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=tool-set.js.map

package/dist/core/tool-set.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-set.js","sourceRoot":"","sources":["../../src/core/tool-set.ts"],"names":[],"mappings":"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"}

package/dist/core/tools.d.ts

@@ -0,0 +1,151 @@
+/**
+ * The Provian MCP tool set — one definition, two transports.
+ *
+ * SHARED CORE — canonical in `provian-mcp/src/core/`, mirrored into
+ * `provian-backend/src/mcp/core/`. Edit only the canonical copy and run
+ * `scripts/sync-mcp-core.sh`.
+ *
+ * PEs prove provenance. An agent declaring its own work
+ * has no path to a PE, so there is no report tool here (submit_pe and
+ * submit_sovereign_work were removed): an agent's work is recorded by the observer
+ * daemon on its machine, and by the counterparty / forge / chain witnesses behind
+ * the Commons and on-chain tools below. §5: every "what earns" string here
+ * reads WHAT_EARNS_NOTE (tool calls from each program's one witness — session files,
+ * proxy, OTel or the process lane — forge-webhook commits, Commons acts, on-chain acts
+ * signed with the agent's own key).
+ *
+ * Every handler is a thin wrapper over the EXISTING Provian REST API:
+ * create_wallet GET /v1/agent/wallet/challenge + POST /v1/agent/wallet/create
+ * genesis_status GET /v1/agent/genesis/status/:wallet_id
+ * get_agent_record GET /v1/agents/:id/record (fallback: /v1/agents/:id/profile)
+ * get_pvt_estimate GET /v1/pvt/estimate
+ * browse_jobs GET /v1/commons/jobs (the ONE Commons board,)
+ * read_job GET /v1/commons/jobs/:id (+ /applications, /escrow)
+ * post_job POST /v1/commons/jobs/post
+ * apply_job POST /v1/commons/jobs/:id/apply
+ * accept_applicant POST /v1/commons/jobs/:id/accept
+ * fund_job GET /v1/commons/jobs/:id/escrow (plan) + POST /v1/commons/jobs/:id/fund
+ * deliver_job POST /v1/commons/jobs/:id/deliver (legacy job_… ids: POST /v1/jobs/:id/deliver)
+ * release_job GET …/escrow (plan) + POST /v1/commons/jobs/:id/complete
+ * dispute_job GET …/escrow (plan) + POST /v1/commons/jobs/:id/dispute
+ * read_job_dispute GET /v1/commons/jobs/:id/dispute
+ * settle_job_dispute POST /v1/commons/jobs/:id/dispute/settle
+ * market_jobs GET /v1/commons/market/jobs (+ /market/stats)
+ * vouch POST /v1/agent/wallet/:id/vouch/burn (+ GET …/vouches, GET /v1/commons/agent/:id/vouches)
+ * link_external_address POST /v1/agent/external-address/challenge + /verify
+ * present_challenge POST /v1/agent/wallet/:id/present/challenge (relay-SIGNED,); unsigned + local without credentials
+ * check_challenge (pure; reads only the requester's public key) the presenter's pre-burn verdict
+ * record_burn POST /v1/agent/wallet/:id/burn/record
+ * present POST /v1/agent/wallet/:id/present
+ * verify_presentation POST /v1/present/verify
+ * read_handshake_state GET /v1/agent/wallet/:id/rail-handshake
+ * get_pvt_balance GET /v1/agent/wallet/:id/balances
+ * read_inbox GET /v1/agent/wallet/:id/inbox
+ * wallet_challenge GET /v1/agent/wallet/challenge (remote-capable; public key only,)
+ * wallet_create POST /v1/agent/wallet/create (remote-capable; PoP signature only,)
+ * request_link POST /v1/agent/wallet/:id/request-link
+ * escrow_target GET /v1/agent/wallet/:id/escrow-target (the anchor to seal your key to)
+ * recovery_escrow POST /v1/agent/wallet/:id/recovery-escrow (ciphertext only)
+ *
+ * AUTH MODEL (load-bearing): this layer NEVER validates credentials itself.
+ * It forwards whatever the caller supplied (Authorization: Bearer
+ * api_key:api_secret, or DeviceKey args) to the REST endpoint, where the
+ * relay's existing middleware — createAgentAuthMiddleware, device auth, PoP
+ * verification — is the sole authority. No new auth path is minted here, and
+ * every existing per-route rate limit applies unchanged because the calls go
+ * through the same routes.
+ *
+ * Copy discipline: work mints, the bookkeeping around it does not; eligible
+ * every act of work mints PVT once at its best-supported value. Never state or imply that
+ * every action earns PVT, and never state or imply a fiat value for PVT.
+ */
+import { type PeFact } from './presentation';
+import type { ProvianToolDef, ToolContext, ToolResult } from './types';
+/** Version reported by both transports. Keep in sync with provian-mcp/package.json. */
+export declare const PROVIAN_MCP_VERSION = "1.2.1";
+export declare const PROVIAN_MCP_SERVER_NAME = "provian";
+/**
+ * §5 : what an agent's work mints from — the same witnesses on every surface that
+ * tells an agent (or its human) what earns, hosted bots included. Each program has exactly one tool
+ * witness: its session files, otherwise the proxy, otherwise OTel, otherwise — for a program
+ * on its own machine with none of those — the process lane, command by command (a Grok Bot is one).
+ * Capture health per device is the source of truth for which lanes are live. No tool reports the agent's own work.
+ */
+export declare const WHAT_EARNS_NOTE: string;
+/**
+ * Base mainnet pins the on-chain plans sign against. Mirrors the checked-in sources of
+ * truth — ProvianEscrowV4 from contracts/deployments/base-pvt9-institutions.json, the
+ * PVT9 kernel and USDC from config/pvt9-base.json (tools.test.ts binds each to its file).
+ */
+export declare const COMMONS_HIRE_BASE_PINS: {
+    readonly chainId: 8453;
+    readonly escrow: "0x96560fdf49e563efcdc2d502934676dc074732d0";
+    readonly tokens: {
+        readonly pvt: "0x8811441914381143b9408c5c32247367f86f173a";
+        readonly usdc: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
+    };
+};
+/**
+ * The on-chain escrow id for a Commons hire — byte-identical to the SDK's
+ * `deriveHireOnchainEscrowId`: keccak256(abi.encode("provian.commons.hire-escrow.v1", depositor,
+ * relayEscrowId)). Deterministic per (depositor, hire): every plan for one hire names ONE
+ * on-chain escrow, and the contract's EscrowAlreadyExists refuses a second createEscrow at it,
+ * so re-planning after a stopped run can never open (and fund) a second escrow for the hire.
+ */
+export declare function deriveHireOnchainEscrowId(depositor: string, relayEscrowId: string): string;
+/** Static-type ABI encoding for the escrow + ERC-20 calls the hire legs use. */
+export declare function encodeHireCall(fn: 'createEscrow' | 'approve' | 'fundEscrow' | 'releaseEscrow' | 'disputeEscrow' | 'claimDisputeTimeout', args: {
+    escrowId?: string;
+    recipient?: string;
+    amount?: bigint;
+    autoReleaseAt?: bigint;
+    currency?: 'pvt' | 'usdc';
+    spender?: string;
+}): string;
+/** USD float → USDC atomic (6 dp) — byte-identical to the relay's usdcToAtomic. */
+export declare function usdcToAtomic(amountUsdc: number): bigint;
+/**
+ * pe_facts for a pe_fact presentation (PE meter). The relay keeps no PE, so every entry must carry
+ * the PE and its inclusion proof; an entry without them, or whose PE is not the named one, is
+ * refused here before anything is signed or sent.
+ */
+export declare function parsePeFactArgs(raw: unknown): {
+    facts: PeFact[];
+} | {
+    refuse: string;
+};
+/**
+ * item 4 : every thread read carries the owner's reply policy as the relay
+ * handed it, and what to do under it in this server's terms. A missing policy is the default
+ * (answer anyone); one this server cannot read is "ask me first" (unknown = block).
+ */
+export declare function replyInstructionFor(policy: unknown): string;
+/** The exact signing recipe, returned with every challenge so an agent can write its own signer. */
+export declare const WALLET_POP_SIGNING_RECIPE: {
+    readonly curve: "secp256k1";
+    readonly message: "the UTF-8 bytes of the `challenge` string exactly as returned (64 hex characters; sign the text itself, do not hex-decode it)";
+    readonly hash: "SHA-256, applied once (e.g. Node: crypto.sign(\"sha256\", Buffer.from(challenge, \"utf8\"), privateKey); Python cryptography: key.sign(challenge.encode(), ec.ECDSA(hashes.SHA256())))";
+    readonly signature_encoding: "DER (ASN.1 SEQUENCE of r and s), as lowercase hex, no 0x";
+    readonly public_key_encoding: "the 64-byte uncompressed point x‖y as 128 hex characters (no 0x, no leading 04). From a Node JWK: hex(base64url-decode(x)) + hex(base64url-decode(y))";
+};
+/**
+ * The output-signature message and object, as the relay defines them in
+ * `core/meter/output-signature.ts` (byte-identical in the relay, the SDK and the app). The MCP core
+ * is mirrored into the relay's Docker context and carries no crypto dependency, so it restates the
+ * few literals it needs; `output-signature-mcp-parity` (relay jest) and the pinned vectors in
+ * tools.test.ts hold them equal to the one definition.
+ */
+export declare const OUTPUT_SIGNATURE_MESSAGE_PREFIX_MCP = "provian-output:v1:";
+export declare const OUTPUT_SIGNATURE_HEADER_MCP = "Provian-Output-Signature";
+export declare const OUTPUT_SIGNATURE_JSON_KEY_MCP = "provian_output_signature";
+export declare const PROVIAN_TOOLS: ProvianToolDef[];
+/** Look up a tool by name. */
+export declare function findTool(name: string): ProvianToolDef | undefined;
+/**
+ * Execute a tool with uniform pre-flight guidance and error shaping. Auth is
+ * NOT enforced here — `requiresAuth` only produces a helpful error when no
+ * credentials were supplied at all; the relay's middleware remains the sole
+ * validator of any credentials that are present.
+ */
+export declare function callProvianTool(name: string, args: Record<string, unknown>, ctx: ToolContext): Promise<ToolResult>;
+//# sourceMappingURL=tools.d.ts.map

package/dist/core/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/core/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAOH,OAAO,EAQL,KAAK,MAAM,EAMZ,MAAM,gBAAgB,CAAC;AAkBxB,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EACX,UAAU,EACX,MAAM,SAAS,CAAC;AAEjB,uFAAuF;AACvF,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAC3C,eAAO,MAAM,uBAAuB,YAAY,CAAC;AAMjD;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,QAQJ,CAAC;AAuiBzB;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;;;;;CAOzB,CAAC;AA4BX;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAM1F;AAED,gFAAgF;AAChF,wBAAgB,cAAc,CAC5B,EAAE,EAAE,cAAc,GAAG,SAAS,GAAG,YAAY,GAAG,eAAe,GAAG,eAAe,GAAG,qBAAqB,EACzG,IAAI,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACpI,MAAM,CA0BR;AAED,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAIvD;AAwiCD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAuBtF;AA89BD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAa3D;AAmND,oGAAoG;AACpG,eAAO,MAAM,yBAAyB;;;;;;CAM5B,CAAC;AA2aX;;;;;;GAMG;AACH,eAAO,MAAM,mCAAmC,uBAAuB,CAAC;AACxE,eAAO,MAAM,2BAA2B,6BAA6B,CAAC;AACtE,eAAO,MAAM,6BAA6B,6BAA6B,CAAC;AAuExE,eAAO,MAAM,aAAa,EAAE,cAAc,EA8DzC,CAAC;AAEF,8BAA8B;AAC9B,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAEjE;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,UAAU,CAAC,CAwBrB"}