@provnai/vex-sdk 1.5.0

package/README.md

@@ -0,0 +1,33 @@
+# VEX SDK for TypeScript (v1.5.0) 🛡️js
+## Cognitive Routing & Silicon-Rooted Evidence
+
+Official TypeScript implementation of the VEX Protocol. Designed to wrap agent tool-calls in a cryptographically verifiable envelope.
+
+### Installation
+```bash
+npm install @provnai/vex-sdk
+```
+
+### 🚀 Usage
+
+```typescript
+import { VexAgent, vexMiddleware } from '@provnai/vex-sdk';
+
+const agent = new VexAgent({
+    identityKey: process.env.VEX_IDENTITY_KEY!,
+    vanguardUrl: 'https://vanguard.provn.ai'
+});
+
+// Use with Vercel AI SDK or custom tool loops
+const securedResult = await agent.execute(
+    'transfer_funds',
+    { amount: 1000, currency: 'USD' },
+    'Authorize emergency liquidation'
+);
+
+console.log(`VEX Outcome: ${securedResult.outcome}`); // ALLOWED
+```
+
+---
+**Note:** This SDK natively integrates with `@provncloud/sdk` for hardware-rooted trust.
+🛡️⚓🚀

package/dist/agent.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Copyright 2026 ProvnAI
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export interface VexConfig {
+    identityKey: string;
+    vanguardUrl: string;
+}
+export declare class VexAgent {
+    private config;
+    private sdk;
+    constructor(config: VexConfig);
+    private ensureSDK;
+    /**
+     * Executes a tool via the VEX verifiable execution loop.
+     */
+    execute(toolName: string, params: Record<string, any>, intentContext?: string): Promise<any>;
+    /**
+     * Manually construct a signed Evidence Capsule without dispatching it.
+     */
+    buildCapsule(toolName: string, params: Record<string, any>, intentContext?: string): Promise<any>;
+    /**
+     * Serializes the Evidence Capsule into the v0x03 Binary Wire format.
+     */
+    toBinary(capsule: any): Buffer;
+    private hashObject;
+}

package/dist/agent.js

@@ -0,0 +1,189 @@
+"use strict";
+/**
+ * Copyright 2026 ProvnAI
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VexAgent = void 0;
+const axios_1 = __importDefault(require("axios"));
+const builder_1 = require("./builder");
+const sdk_1 = require("@provncloud/sdk");
+class VexAgent {
+    constructor(config) {
+        this.sdk = null;
+        this.config = config;
+    }
+    async ensureSDK() {
+        if (!this.sdk) {
+            await (0, sdk_1.init)();
+            this.sdk = new sdk_1.ProvnSDK();
+        }
+    }
+    /**
+     * Executes a tool via the VEX verifiable execution loop.
+     */
+    async execute(toolName, params, intentContext) {
+        await this.ensureSDK();
+        // 1. Build Capsule
+        const capsuleData = await this.buildCapsule(toolName, params, intentContext);
+        const capsuleId = capsuleData.authority.capsule_id;
+        // 2. Dispatch to Vanguard
+        try {
+            const response = await axios_1.default.post(`${this.config.vanguardUrl}/dispatch`, capsuleData, {
+                headers: { 'Content-Type': 'application/json' }
+            });
+            let result = response.data;
+            // 3. Handle AEM (ESCALATE Loop)
+            let attempts = 0;
+            const maxAttempts = 15; // ~30 seconds
+            while (result.outcome === 'ESCALATE' && attempts < maxAttempts) {
+                await new Promise(resolve => setTimeout(resolve, 2000));
+                attempts++;
+                const pollResp = await axios_1.default.get(`${this.config.vanguardUrl}/capsule/${capsuleId}/status`, {
+                    headers: { 'Accept': 'application/json' }
+                });
+                result = pollResp.data;
+            }
+            if (result.outcome === 'HALT') {
+                throw new Error(`VEX Execution HALTED: ${result.reason_code}`);
+            }
+            if (result.outcome === 'ESCALATE') {
+                throw new Error('VEX Escalated resolution timed out.');
+            }
+            // 4. Store Capability Token
+            if (result.capability_token) {
+                this.currentToken = result.capability_token;
+            }
+            return result;
+        }
+        catch (error) {
+            console.error('VEX Execution Failed:', error.response?.data || error.message);
+            throw error;
+        }
+    }
+    /**
+     * Manually construct a signed Evidence Capsule without dispatching it.
+     */
+    async buildCapsule(toolName, params, intentContext) {
+        await this.ensureSDK();
+        // This is a simplified implementation for the SDK.
+        // It demonstrates how the builder is leveraged.
+        const intent = {
+            request_sha256: this.hashObject(params),
+            confidence: 1.0,
+            capabilities: ['sdk_execution']
+        };
+        if (intentContext) {
+            intent.intent_context = intentContext;
+        }
+        const authority = {
+            capsule_id: require('crypto').randomUUID(),
+            outcome: 'ALLOW',
+            reason_code: 'SDK_GENERATED',
+            trace_root: '00'.repeat(32),
+            nonce: Date.now(),
+            prev_hash: '00'.repeat(32), // Start of chain
+            supervision: {
+                branch_completeness: 1.0,
+                contradictions: 0,
+                confidence: 1.0
+            }
+        };
+        const identity = {
+            aid: '00'.repeat(32), // Placeholder for hardware AID
+            identity_type: 'software_sim',
+            pcrs: { '0': '00'.repeat(32) }
+        };
+        const witness = {
+            chora_node_id: 'local_witness',
+            receipt_hash: '00'.repeat(32),
+            timestamp: Math.floor(Date.now() / 1000)
+        };
+        const intent_hash = builder_1.VEPBuilder.hashSegment(intent);
+        const authority_hash = builder_1.VEPBuilder.hashSegment(authority);
+        const identity_hash = builder_1.VEPBuilder.hashSegment(identity);
+        const witness_hash = builder_1.VEPBuilder.hashSegment(witness, false); // Minimal scope
+        const capsule_root = builder_1.VEPBuilder.calculateCapsuleRoot({
+            intent_hash,
+            authority_hash,
+            identity_hash,
+            witness_hash
+        });
+        // Sign the capsule_root
+        const claim = this.sdk.createClaimNow(capsule_root);
+        const keyPair = {
+            private_key: this.config.identityKey,
+            public_key: '00'.repeat(32) // In real use, this comes from the config/key derivation
+        };
+        this.sdk.setKeypair(keyPair);
+        const signedClaim = this.sdk.signClaim(claim);
+        const signature = Buffer.from(signedClaim.signature, 'hex');
+        return {
+            intent,
+            authority,
+            identity,
+            witness,
+            intent_hash,
+            authority_hash,
+            identity_hash,
+            witness_hash,
+            capsule_root,
+            crypto: {
+                algo: 'ed25519',
+                signature_scope: 'capsule_root',
+                signature_b64: signature.toString('base64'),
+                signature_raw: signature // Keep raw for binary spec
+            }
+        };
+    }
+    /**
+     * Serializes the Evidence Capsule into the v0x03 Binary Wire format.
+     */
+    toBinary(capsule) {
+        const { canonicalize } = require('json-canonicalize');
+        // --- Header (76 Bytes) ---
+        const header = Buffer.alloc(76);
+        header.write('VEP', 0);
+        header.writeUInt8(0x03, 3);
+        header.write(capsule.identity.aid.replace(/-/g, ''), 4, 'hex'); // Ensure hex
+        header.write(capsule.capsule_root, 36, 'hex');
+        header.writeBigUInt64BE(BigInt(capsule.authority.nonce), 68);
+        // --- TLV Body ---
+        const packTLV = (tag, data) => {
+            const tlv = Buffer.alloc(5 + data.length);
+            tlv.writeUInt8(tag, 0);
+            tlv.writeUInt32BE(data.length, 1);
+            data.copy(tlv, 5);
+            return tlv;
+        };
+        const segments = [
+            packTLV(0x01, Buffer.from(canonicalize(capsule.intent))),
+            packTLV(0x02, Buffer.from(canonicalize(capsule.authority))),
+            packTLV(0x03, Buffer.from(canonicalize(capsule.identity))),
+            packTLV(0x05, Buffer.from(canonicalize(capsule.witness))),
+            packTLV(0x06, capsule.crypto.signature_raw)
+        ];
+        return Buffer.concat([header, ...segments, header]);
+    }
+    hashObject(obj) {
+        const { canonicalize } = require('json-canonicalize');
+        const crypto = require('crypto');
+        const canonicalJSON = canonicalize(obj);
+        return crypto.createHash('sha256').update(canonicalJSON).digest('hex');
+    }
+}
+exports.VexAgent = VexAgent;

package/dist/builder.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Copyright 2026 ProvnAI
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export interface IntentSegment {
+    request_sha256: string;
+    confidence: number;
+    capabilities: string[];
+    magpie_source?: string;
+}
+export interface AuthoritySegment {
+    capsule_id: string;
+    outcome: 'ALLOW' | 'HALT' | 'ESCALATE';
+    reason_code: string;
+    trace_root: string;
+    nonce: number;
+    prev_hash?: string;
+    supervision?: {
+        branch_completeness?: number;
+        contradictions?: number;
+        confidence?: number;
+    };
+    gate_sensors?: Record<string, any>;
+}
+export interface IdentitySegment {
+    aid: string;
+    identity_type: string;
+    pcrs: Record<string, string>;
+}
+export interface WitnessSegment {
+    chora_node_id: string;
+    receipt_hash: string;
+    timestamp: number;
+}
+export interface VexPillars {
+    intent: IntentSegment;
+    authority: AuthoritySegment;
+    identity: IdentitySegment;
+    witness: WitnessSegment;
+}
+export declare class VEPBuilder {
+    /**
+     * Computes the SHA-256 hash of a JCS canonicalized object.
+     */
+    static hashSegment(segment: any, inclusive?: boolean): string;
+    /**
+     * Calculates the capsule_root commitment using a 4-leaf binary Merkle tree
+     * with domain separation (0x00 for leaves, 0x01 for internal nodes).
+     * Pillar Order: Intent, Authority, Identity, Witness.
+     */
+    static calculateCapsuleRoot(hashes: {
+        intent_hash: string;
+        authority_hash: string;
+        identity_hash: string;
+        witness_hash: string;
+    }): string;
+}

package/dist/builder.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * Copyright 2026 ProvnAI
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VEPBuilder = void 0;
+const crypto = __importStar(require("crypto"));
+const { canonicalize } = require('json-canonicalize');
+class VEPBuilder {
+    /**
+     * Computes the SHA-256 hash of a JCS canonicalized object.
+     */
+    static hashSegment(segment, inclusive = true) {
+        let dataToHash = segment;
+        if (!inclusive) {
+            // Witness pillar uses Minimal scope (Explicit fields only, EXCLUDING receipt_hash)
+            const minimal = {
+                chora_node_id: segment.chora_node_id,
+                timestamp: segment.timestamp
+            };
+            dataToHash = minimal;
+        }
+        const canonicalJSON = canonicalize(dataToHash);
+        return crypto.createHash('sha256').update(canonicalJSON).digest('hex');
+    }
+    /**
+     * Calculates the capsule_root commitment using a 4-leaf binary Merkle tree
+     * with domain separation (0x00 for leaves, 0x01 for internal nodes).
+     * Pillar Order: Intent, Authority, Identity, Witness.
+     */
+    static calculateCapsuleRoot(hashes) {
+        const hashLeaf = (data_hex) => {
+            const leaf = Buffer.concat([Buffer.from([0x00]), Buffer.from(data_hex, 'hex')]);
+            return crypto.createHash('sha256').update(leaf).digest();
+        };
+        const hashInternal = (left, right) => {
+            const internal = Buffer.concat([Buffer.from([0x01]), left, right]);
+            return crypto.createHash('sha256').update(internal).digest();
+        };
+        // 1. Leaf Hashes
+        const hi = hashLeaf(hashes.intent_hash);
+        const ha = hashLeaf(hashes.authority_hash);
+        const hid = hashLeaf(hashes.identity_hash);
+        const hw = hashLeaf(hashes.witness_hash);
+        // 2. Layer 1 (Internal Nodes)
+        const h12 = hashInternal(hi, ha);
+        const h34 = hashInternal(hid, hw);
+        // 3. Root
+        const rootDigest = hashInternal(h12, h34);
+        return rootDigest.toString('hex');
+    }
+}
+exports.VEPBuilder = VEPBuilder;

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright 2026 ProvnAI
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export * from './agent';
+export * from './builder';
+export * from './middleware';
+export type { VexConfig } from './agent';
+export type { IntentSegment, AuthoritySegment, IdentitySegment, WitnessSegment, VexPillars } from './builder';

package/dist/index.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * Copyright 2026 ProvnAI
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./agent"), exports);
+__exportStar(require("./builder"), exports);
+__exportStar(require("./middleware"), exports);

package/dist/middleware.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Copyright 2026 ProvnAI
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Vercel AI SDK compatible middleware for VEX-secured tool execution.
+ */
+export declare const vexMiddleware: (config: {
+    identityKey: string;
+    vanguardUrl: string;
+}) => {
+    onToolCall({ toolName, args }: {
+        toolName: string;
+        args: any;
+    }): Promise<{
+        status: string;
+        vex_root: any;
+    }>;
+};

package/dist/middleware.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * Copyright 2026 ProvnAI
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vexMiddleware = void 0;
+const agent_1 = require("./agent");
+/**
+ * Vercel AI SDK compatible middleware for VEX-secured tool execution.
+ */
+const vexMiddleware = (config) => {
+    const agent = new agent_1.VexAgent(config);
+    return {
+        // This is a pattern used by Vercel AI SDK to intercept tool calls
+        async onToolCall({ toolName, args }) {
+            console.log(`[VEX] Securing tool call: ${toolName}`);
+            try {
+                const result = await agent.execute(toolName, args, `Vercel AI SDK forced verification for ${toolName}`);
+                // If execute doesn't throw, it means Vanguard/VEX sidecar allowed it
+                return {
+                    status: 'verified',
+                    vex_root: result.capsule_root
+                };
+            }
+            catch (error) {
+                console.error(`[VEX] Blocked tool execution: ${toolName}`);
+                throw new Error(`VEX Verification Failed: ${toolName} execution not authorized. Reason: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    };
+};
+exports.vexMiddleware = vexMiddleware;

package/eslint.config.js

@@ -0,0 +1,36 @@
+const tsParser = require('@typescript-eslint/parser');
+const tsPlugin = require('@typescript-eslint/eslint-plugin');
+const js = require('@eslint/js');
+
+module.exports = [
+  js.configs.recommended,
+  {
+    files: ['src/**/*.ts'],
+    languageOptions: {
+      parser: tsParser,
+      globals: {
+        node: true,
+        jest: true,
+        process: true,
+        console: true,
+        Buffer: true,
+        setTimeout: true,
+        Math: true,
+        require: true,
+        module: true
+      }
+    },
+    plugins: {
+      '@typescript-eslint': tsPlugin
+    },
+    rules: {
+      ...tsPlugin.configs.recommended.rules,
+      '@typescript-eslint/no-explicit-any': 'warn',
+      '@typescript-eslint/no-unused-vars': 'warn',
+      '@typescript-eslint/no-require-imports': 'off',
+      'no-console': 'off',
+      'semi': ['error', 'always'],
+      'quotes': ['error', 'single']
+    }
+  }
+];

package/jest.config.js

@@ -0,0 +1,5 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['**/tests/**/*.test.ts'],
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@provnai/vex-sdk",
+  "version": "1.5.0",
+  "description": "High-level routing and cognitive abstraction SDK for the VEX Protocol",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "lint": "eslint src/**/*.ts"
+  },
+  "dependencies": {
+    "@provncloud/sdk": "^0.3.0",
+    "axios": "^1.6.0",
+    "json-canonicalize": "^1.0.4"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.57.1",
+    "@typescript-eslint/parser": "^8.57.1",
+    "@eslint/js": "^9.39.4",
+    "eslint": "^9.11.0",
+    "jest": "^29.5.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/agent.ts

@@ -0,0 +1,217 @@
+/**
+ * Copyright 2026 ProvnAI
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import axios from 'axios';
+import { VEPBuilder, VexPillars } from './builder';
+import { ProvnSDK, init } from '@provncloud/sdk';
+
+export interface VexConfig {
+    identityKey: string;     // Hex or Base64 Ed25519 private key
+    vanguardUrl: string;     // Target proxy endpoint (McpVanguard/VEX sidecar)
+}
+
+export class VexAgent {
+    private config: VexConfig;
+    private sdk: ProvnSDK | null = null;
+
+    constructor(config: VexConfig) {
+        this.config = config;
+    }
+
+    private async ensureSDK() {
+        if (!this.sdk) {
+            await init();
+            this.sdk = new ProvnSDK();
+        }
+    }
+
+    /**
+     * Executes a tool via the VEX verifiable execution loop.
+     */
+    async execute(toolName: string, params: Record<string, any>, intentContext?: string): Promise<any> {
+        await this.ensureSDK();
+
+        // 1. Build Capsule
+        const capsuleData = await this.buildCapsule(toolName, params, intentContext);
+        const capsuleId = capsuleData.authority.capsule_id;
+
+        // 2. Dispatch to Vanguard
+        try {
+            const response = await axios.post(`${this.config.vanguardUrl}/dispatch`, capsuleData, {
+                headers: { 'Content-Type': 'application/json' }
+            });
+            let result = response.data;
+
+            // 3. Handle AEM (ESCALATE Loop)
+            let attempts = 0;
+            const maxAttempts = 15; // ~30 seconds
+
+            while (result.outcome === 'ESCALATE' && attempts < maxAttempts) {
+                await new Promise(resolve => setTimeout(resolve, 2000));
+                attempts++;
+
+                const pollResp = await axios.get(`${this.config.vanguardUrl}/capsule/${capsuleId}/status`, {
+                    headers: { 'Accept': 'application/json' }
+                });
+                result = pollResp.data;
+            }
+
+            if (result.outcome === 'HALT') {
+                throw new Error(`VEX Execution HALTED: ${result.reason_code}`);
+            }
+
+            if (result.outcome === 'ESCALATE') {
+                throw new Error('VEX Escalated resolution timed out.');
+            }
+
+            // 4. Store Capability Token
+            if (result.capability_token) {
+                (this as any).currentToken = result.capability_token;
+            }
+
+            return result;
+        } catch (error: any) {
+            console.error('VEX Execution Failed:', error.response?.data || error.message);
+            throw error;
+        }
+    }
+
+    /**
+     * Manually construct a signed Evidence Capsule without dispatching it.
+     */
+    async buildCapsule(toolName: string, params: Record<string, any>, intentContext?: string): Promise<any> {
+        await this.ensureSDK();
+        // This is a simplified implementation for the SDK.
+        // It demonstrates how the builder is leveraged.
+        
+        const intent: any = {
+            request_sha256: this.hashObject(params),
+            confidence: 1.0,
+            capabilities: ['sdk_execution']
+        };
+        if (intentContext) {
+            intent.intent_context = intentContext;
+        }
+
+        const authority = {
+            capsule_id: require('crypto').randomUUID(),
+            outcome: 'ALLOW',
+            reason_code: 'SDK_GENERATED',
+            trace_root: '00'.repeat(32),
+            nonce: Date.now(),
+            prev_hash: '00'.repeat(32), // Start of chain
+            supervision: {
+                branch_completeness: 1.0,
+                contradictions: 0,
+                confidence: 1.0
+            }
+        };
+
+        const identity = {
+            aid: '00'.repeat(32), // Placeholder for hardware AID
+            identity_type: 'software_sim',
+            pcrs: { '0': '00'.repeat(32) }
+        };
+
+        const witness = {
+            chora_node_id: 'local_witness',
+            receipt_hash: '00'.repeat(32),
+            timestamp: Math.floor(Date.now() / 1000)
+        };
+
+        const intent_hash = VEPBuilder.hashSegment(intent);
+        const authority_hash = VEPBuilder.hashSegment(authority);
+        const identity_hash = VEPBuilder.hashSegment(identity);
+        const witness_hash = VEPBuilder.hashSegment(witness, false); // Minimal scope
+
+        const capsule_root = VEPBuilder.calculateCapsuleRoot({
+            intent_hash,
+            authority_hash,
+            identity_hash,
+            witness_hash
+        });
+
+        // Sign the capsule_root
+        const claim = this.sdk!.createClaimNow(capsule_root);
+        const keyPair = { 
+            private_key: this.config.identityKey, 
+            public_key: '00'.repeat(32) // In real use, this comes from the config/key derivation
+        };
+        this.sdk!.setKeypair(keyPair);
+        const signedClaim = this.sdk!.signClaim(claim);
+        const signature = Buffer.from(signedClaim.signature, 'hex');
+
+        return {
+            intent,
+            authority,
+            identity,
+            witness,
+            intent_hash,
+            authority_hash,
+            identity_hash,
+            witness_hash,
+            capsule_root,
+            crypto: {
+                algo: 'ed25519',
+                signature_scope: 'capsule_root',
+                signature_b64: signature.toString('base64'),
+                signature_raw: signature // Keep raw for binary spec
+            }
+        };
+    }
+
+    /**
+     * Serializes the Evidence Capsule into the v0x03 Binary Wire format.
+     */
+    toBinary(capsule: any): Buffer {
+        const { canonicalize } = require('json-canonicalize');
+        
+        // --- Header (76 Bytes) ---
+        const header = Buffer.alloc(76);
+        header.write('VEP', 0);
+        header.writeUInt8(0x03, 3);
+        header.write(capsule.identity.aid.replace(/-/g, ''), 4, 'hex'); // Ensure hex
+        header.write(capsule.capsule_root, 36, 'hex');
+        header.writeBigUInt64BE(BigInt(capsule.authority.nonce), 68);
+
+        // --- TLV Body ---
+        const packTLV = (tag: number, data: Buffer) => {
+            const tlv = Buffer.alloc(5 + data.length);
+            tlv.writeUInt8(tag, 0);
+            tlv.writeUInt32BE(data.length, 1);
+            data.copy(tlv, 5);
+            return tlv;
+        };
+
+        const segments = [
+            packTLV(0x01, Buffer.from(canonicalize(capsule.intent))),
+            packTLV(0x02, Buffer.from(canonicalize(capsule.authority))),
+            packTLV(0x03, Buffer.from(canonicalize(capsule.identity))),
+            packTLV(0x05, Buffer.from(canonicalize(capsule.witness))),
+            packTLV(0x06, capsule.crypto.signature_raw)
+        ];
+
+        return Buffer.concat([header, ...segments, header]);
+    }
+
+    private hashObject(obj: any): string {
+        const { canonicalize } = require('json-canonicalize');
+        const crypto = require('crypto');
+        const canonicalJSON = canonicalize(obj);
+        return crypto.createHash('sha256').update(canonicalJSON).digest('hex');
+    }
+}
+

package/src/builder.ts

@@ -0,0 +1,117 @@
+/**
+ * Copyright 2026 ProvnAI
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as crypto from 'crypto';
+const { canonicalize } = require('json-canonicalize');
+
+export interface IntentSegment {
+    request_sha256: string;
+    confidence: number;
+    capabilities: string[];
+    magpie_source?: string;
+}
+
+export interface AuthoritySegment {
+    capsule_id: string;
+    outcome: 'ALLOW' | 'HALT' | 'ESCALATE';
+    reason_code: string;
+    trace_root: string;
+    nonce: number;
+    prev_hash?: string;       // VEX Ledger Link
+    supervision?: {           // MCS Signals
+        branch_completeness?: number;
+        contradictions?: number;
+        confidence?: number;
+    };
+    gate_sensors?: Record<string, any>;
+}
+
+export interface IdentitySegment {
+    aid: string;
+    identity_type: string;
+    pcrs: Record<string, string>;
+}
+
+export interface WitnessSegment {
+    chora_node_id: string;
+    receipt_hash: string;
+    timestamp: number;
+}
+
+export interface VexPillars {
+    intent: IntentSegment;
+    authority: AuthoritySegment;
+    identity: IdentitySegment;
+    witness: WitnessSegment;
+}
+
+export class VEPBuilder {
+    /**
+     * Computes the SHA-256 hash of a JCS canonicalized object.
+     */
+    static hashSegment(segment: any, inclusive: boolean = true): string {
+        let dataToHash = segment;
+        
+        if (!inclusive) {
+            // Witness pillar uses Minimal scope (Explicit fields only, EXCLUDING receipt_hash)
+            const minimal = {
+                chora_node_id: segment.chora_node_id,
+                timestamp: segment.timestamp
+            };
+            dataToHash = minimal;
+        }
+
+        const canonicalJSON = canonicalize(dataToHash);
+        return crypto.createHash('sha256').update(canonicalJSON).digest('hex');
+    }
+
+    /**
+     * Calculates the capsule_root commitment using a 4-leaf binary Merkle tree
+     * with domain separation (0x00 for leaves, 0x01 for internal nodes).
+     * Pillar Order: Intent, Authority, Identity, Witness.
+     */
+    static calculateCapsuleRoot(hashes: {
+        intent_hash: string;
+        authority_hash: string;
+        identity_hash: string;
+        witness_hash: string;
+    }): string {
+        const hashLeaf = (data_hex: string) => {
+            const leaf = Buffer.concat([Buffer.from([0x00]), Buffer.from(data_hex, 'hex')]);
+            return crypto.createHash('sha256').update(leaf).digest();
+        };
+
+        const hashInternal = (left: Buffer, right: Buffer) => {
+            const internal = Buffer.concat([Buffer.from([0x01]), left, right]);
+            return crypto.createHash('sha256').update(internal).digest();
+        };
+
+        // 1. Leaf Hashes
+        const hi = hashLeaf(hashes.intent_hash);
+        const ha = hashLeaf(hashes.authority_hash);
+        const hid = hashLeaf(hashes.identity_hash);
+        const hw = hashLeaf(hashes.witness_hash);
+
+        // 2. Layer 1 (Internal Nodes)
+        const h12 = hashInternal(hi, ha);
+        const h34 = hashInternal(hid, hw);
+
+        // 3. Root
+        const rootDigest = hashInternal(h12, h34);
+        return rootDigest.toString('hex');
+    }
+}
+

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Copyright 2026 ProvnAI
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { VexAgent } from './agent';
+import { VEPBuilder } from './builder';
+
+export * from './agent';
+export * from './builder';
+export * from './middleware';
+
+// Explicit type exports for better IDE support
+export type { VexConfig } from './agent';
+export type { 
+    IntentSegment, 
+    AuthoritySegment, 
+    IdentitySegment, 
+    WitnessSegment, 
+    VexPillars 
+} from './builder';
+

package/src/middleware.ts

@@ -0,0 +1,47 @@
+/**
+ * Copyright 2026 ProvnAI
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { VexAgent } from './agent';
+
+/**
+ * Vercel AI SDK compatible middleware for VEX-secured tool execution.
+ */
+export const vexMiddleware = (config: { identityKey: string, vanguardUrl: string }) => {
+    const agent = new VexAgent(config);
+
+    return {
+        // This is a pattern used by Vercel AI SDK to intercept tool calls
+        async onToolCall({ toolName, args }: { toolName: string, args: any }) {
+            console.log(`[VEX] Securing tool call: ${toolName}`);
+            
+            try {
+                const result = await agent.execute(toolName, args, `Vercel AI SDK forced verification for ${toolName}`);
+                
+                // If execute doesn't throw, it means Vanguard/VEX sidecar allowed it
+                return {
+                    status: 'verified',
+                    vex_root: result.capsule_root
+                };
+            } catch (error) {
+                console.error(`[VEX] Blocked tool execution: ${toolName}`);
+                throw new Error(
+                    `VEX Verification Failed: ${toolName} execution not authorized. Reason: ${error instanceof Error ? error.message : String(error)}`
+                );
+            }
+        }
+    };
+};
+

package/tests/agent.test.ts

@@ -0,0 +1,50 @@
+import { VexAgent, VexConfig } from '../src/agent';
+import axios from 'axios';
+
+jest.mock('axios');
+jest.mock('@provncloud/sdk', () => ({
+    ProvnSDK: jest.fn().mockImplementation(() => ({
+        generateKeypair: jest.fn(),
+        setKeypair: jest.fn(),
+        createClaimNow: jest.fn().mockReturnValue({ data: 'root', timestamp: 123 }),
+        signClaim: jest.fn().mockReturnValue({ signature: '66616b655f7369675f686578' })
+    })),
+    init: jest.fn().mockResolvedValue(undefined)
+}));
+const mockedAxios = axios as jest.Mocked<typeof axios>;
+
+describe('VexAgent', () => {
+    const config: VexConfig = {
+        identityKey: 'fake_key',
+        vanguardUrl: 'http://localhost:3000'
+    };
+
+    test('execute() constructs a capsule and sends it via POST', async () => {
+        const agent = new VexAgent(config);
+        
+        mockedAxios.post.mockResolvedValue({ data: { status: 'verified' } });
+
+        const result = await agent.execute('test_tool', { foo: 'bar' });
+
+        expect(mockedAxios.post).toHaveBeenCalledWith(
+            `${config.vanguardUrl}/dispatch`,
+            expect.objectContaining({
+                intent_hash: expect.any(String),
+                capsule_root: expect.any(String)
+            }),
+            expect.any(Object)
+        );
+        expect(result.status).toBe('verified');
+    });
+
+    test('buildCapsule() produces expected structure', async () => {
+        const agent = new VexAgent(config);
+        const capsule = await agent.buildCapsule('test_tool', { foo: 'bar' });
+
+        expect(capsule).toHaveProperty('intent');
+        expect(capsule).toHaveProperty('authority');
+        expect(capsule).toHaveProperty('identity');
+        expect(capsule).toHaveProperty('witness');
+        expect(capsule).toHaveProperty('capsule_root');
+    });
+});

package/tests/binary_parity.test.ts

@@ -0,0 +1,48 @@
+import { VexAgent } from '../src/agent';
+
+jest.mock('@provncloud/sdk', () => ({
+    ProvnSDK: jest.fn().mockImplementation(() => ({
+        generateKeypair: jest.fn(),
+        setKeypair: jest.fn(),
+        createClaimNow: jest.fn().mockReturnValue({ data: 'root', timestamp: 123 }),
+        signClaim: jest.fn().mockReturnValue({ signature: '00'.repeat(64) })
+    })),
+    init: jest.fn().mockResolvedValue(undefined)
+}));
+
+describe('Binary Parity', () => {
+    test('produces deterministic binary hex', async () => {
+        const config = {
+            identityKey: '0'.repeat(64),
+            vanguardUrl: 'http://localhost:3000'
+        };
+        const agent = new VexAgent(config as any);
+
+        // Mock Date.now and crypto.randomUUID
+        const fixedNow = 1710500000000;
+        jest.spyOn(Date, 'now').mockReturnValue(fixedNow);
+        
+        const crypto = require('crypto');
+        jest.spyOn(crypto, 'randomUUID').mockReturnValue('0'.repeat(64));
+
+        // Mock SDK signing
+        const mockSDK = {
+            createClaimNow: jest.fn().mockReturnValue({}),
+            setKeypair: jest.fn(),
+            signClaim: jest.fn().mockReturnValue({ signature: '00'.repeat(64) })
+        };
+        (agent as any).sdk = mockSDK;
+        (agent as any).ensureSDK = jest.fn().mockResolvedValue(undefined);
+
+        const capsule = await agent.buildCapsule('test_tool', { foo: 'bar' });
+        const binary = agent.toBinary(capsule);
+
+        require('fs').writeFileSync('../python/ts_payload.hex', binary.toString('hex'));
+        expect(binary.subarray(0, 4).toString()).toBe('VEP\x03');
+        // Forensic Footer Check
+        const header = binary.subarray(0, 76);
+        const footer = binary.subarray(binary.length - 76);
+        expect(footer.equals(header)).toBe(true);
+        expect(binary.length).toBeGreaterThan(152);
+    });
+});

package/tests/parity.test.ts

@@ -0,0 +1,48 @@
+import { VEPBuilder } from '../src/builder';
+
+describe('VEX SDK Parity Verification', () => {
+    test('calculateCapsuleRoot matches Rust test vector (v1.5.0 Merkle Shift)', () => {
+        // Test hashes provided in COWORKER_HANDOFF.md.resolved
+        const parityHashes = {
+            authority_hash: "6fac0de31355fc1dfe36eee1e0c226f7cc36dd58eaad0aca0c2d3873b4784d35",
+            identity_hash: "7869bae0249b33e09b881a0b44faba6ee3f4bab7edcc2aa5a5e9290e2563c828",
+            intent_hash: "e02504ea88bd9f05a744cd8a462a114dc2045eb7210ea8c6f5ff2679663c92cb",
+            witness_hash: "174dfb80917cca8a8d4760b82656e78df0778cb3aadd60b51cd018b3313d5733"
+        };
+
+        // Recalculated for 4-leaf Merkle Tree with 0x00/0x01 domain separation (Definitive v1.5.0)
+        const expectedRoot = "8acf6d45aedaf61c61142ea8f9f7a89bc90994532313f20fcc1493a95e36d405";
+
+        const calculatedRoot = VEPBuilder.calculateCapsuleRoot(parityHashes);
+        expect(calculatedRoot).toBe(expectedRoot);
+    });
+
+    test('calculateCapsuleRoot matches Rust test vector (Empty Tree)', () => {
+        const hashes = {
+            intent_hash: '00'.repeat(32),
+            authority_hash: '00'.repeat(32),
+            identity_hash: '00'.repeat(32),
+            witness_hash: '00'.repeat(32)
+        };
+        const root = VEPBuilder.calculateCapsuleRoot(hashes);
+        expect(root).toBe('b46fd516fa6c7dcddd52ac2be2a014d8a8de4eaa059f79ccfcff4b8afc4e7ddc');
+    });
+
+    test('hashSegment matches expected output (Verification of JCS + SHA256)', () => {
+        // Intent Pillar (Inclusive)
+        const intent = {
+            request_sha256: "e02504ea88bd9f05a744cd8a462a114dc2045eb7210ea8c6f5ff2679663c92cb",
+            confidence: 0.95,
+            capabilities: ["filesystem", "network"]
+        };
+        // This is a sanity check that JCS stable-sorting works
+        const hash1 = VEPBuilder.hashSegment(intent);
+        const hash2 = VEPBuilder.hashSegment({
+            capabilities: ["filesystem", "network"],
+            confidence: 0.95,
+            request_sha256: "e02504ea88bd9f05a744cd8a462a114dc2045eb7210ea8c6f5ff2679663c92cb"
+        });
+        
+        expect(hash1).toBe(hash2);
+    });
+});

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "declaration": true,
+    "outDir": "./dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "node"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "**/*.test.ts"]
+}