agentex-creator-sdk 1.0.0

package/dist/packages/runtime/src/checkpoints.d.ts

@@ -0,0 +1,65 @@
+import { type EvidenceItem, type ResearchInput } from '../../contracts/src/index.js';
+import { type InspectionEvidenceItem, type TransactionInspectionInput } from '../../contracts/src/inspection.js';
+import { type AnyEvidenceItem, type RunInput } from '../../contracts/src/kinds.js';
+import { type SolanaTransactionInspectionInput } from '../../contracts/src/solana-inspection.js';
+import { type ToolEvidenceItem } from '../../contracts/src/workflow.js';
+import { type WatchEvidenceItem, type WatchtowerWindowInput } from '../../contracts/src/watchtower.js';
+export declare class CheckpointIntegrityError extends Error {
+    readonly code = "CHECKPOINT_INTEGRITY_FAILURE";
+    constructor();
+}
+export interface CheckpointRow {
+    id: string;
+    run_id: string;
+    version_id: string;
+    manifest_hash: string;
+    input_hash: string;
+    operation: number;
+    source_fence: number;
+    evidence: AnyEvidenceItem;
+    checkpoint_hash: string;
+    created_at: Date;
+}
+/** A stored AI analysis node result (G02), restored only after `restoreWorkflowAnalysis` re-validates it against the current run. */
+export interface StoredAnalysisResult {
+    nodeId: string;
+    stored: {
+        checkpointKey: string;
+        value: unknown;
+        evidenceIds: string[];
+        usage: {
+            modelTokens: number;
+            costMicrousd: number;
+        };
+    };
+}
+export interface RecoveryBundle<Evidence extends AnyEvidenceItem = EvidenceItem> {
+    manifestHash: string;
+    inputHash: string;
+    evidence: Evidence[];
+    analysis?: StoredAnalysisResult[];
+}
+/** `manifest` (the pinned version) lets workflow receipts be checked against declared tools; other kinds ignore it. */
+export interface CheckpointContract<Input extends RunInput = RunInput> {
+    id: string;
+    version_id: string;
+    manifest_hash: string;
+    input: Input;
+    rpc_used: number;
+    fence: number;
+    manifest?: unknown;
+}
+export declare function checkpointHash(row: Omit<CheckpointRow, 'id' | 'checkpoint_hash' | 'created_at'>): string;
+/** Check source scope independently of the executor before saving or reusing a captured response. */
+export declare function validateReceipt(evidence: unknown, input: ResearchInput): EvidenceItem;
+/** Transaction Inspector receipts may only contain reads derivable from the accepted payload (sender, target and decoded grantees). */
+export declare function validateInspectionReceipt(evidence: unknown, input: TransactionInspectionInput): InspectionEvidenceItem;
+/** Watchtower receipts may only contain identity, window headers and the exact log filters derived from the accepted rules. */
+export declare function validateWatchReceipt(evidence: unknown, input: WatchtowerWindowInput): WatchEvidenceItem;
+/** Solana inspector receipts: the declared tool, read-only allowlisted methods, the accepted cluster, and private simulation payloads. */
+export declare function validateSolanaInspectionReceipt(evidence: unknown, input: SolanaTransactionInspectionInput): ToolEvidenceItem;
+/** Kind dispatch on the accepted input shape; the worker separately checks that the input kind matches the pinned manifest kind. */
+export declare function validateRunReceipt(evidence: unknown, input: RunInput, manifest?: unknown): AnyEvidenceItem;
+/** Checks the entire envelope, not only the result's checksum. A corrupt cache is never a cache miss. */
+export declare function restoreCheckpoints(run: CheckpointContract<ResearchInput>, rows: CheckpointRow[]): RecoveryBundle<EvidenceItem>;
+export declare function restoreCheckpoints(run: CheckpointContract, rows: CheckpointRow[]): RecoveryBundle<AnyEvidenceItem>;

package/dist/packages/runtime/src/checkpoints.js

@@ -0,0 +1,214 @@
+import { contentHash, EvidenceItemSchema } from '../../contracts/src/index.js';
+import { InspectionEvidenceItemSchema } from '../../contracts/src/inspection.js';
+import { runCoverageChain, runInputKind } from '../../contracts/src/kinds.js';
+import { SOLANA_INSPECTION_RPC_METHODS, SOLANA_INSPECTION_TOOL } from '../../contracts/src/solana-inspection.js';
+import { ToolEvidenceItemSchema } from '../../contracts/src/workflow.js';
+import { validateWorkflowReceipt } from './policy.js';
+import { inspectionReceiptInScope } from '../../inspector/src/scope.js';
+import { WatchEvidenceItemSchema } from '../../contracts/src/watchtower.js';
+import { watchReceiptInScope } from '../../watchtower/src/index.js';
+import { validateDeployerReceipt } from '../../contracts/src/deployer-investigation.js';
+import { validateWalletReceipt } from '../../contracts/src/wallet-analysis.js';
+import { HOLDER_ACTIVITY_METHOD, marketCallInScope, marketTransferRequestInScope } from '../../contracts/src/token-market.js';
+export class CheckpointIntegrityError extends Error {
+    code = 'CHECKPOINT_INTEGRITY_FAILURE';
+    constructor() { super('A saved research checkpoint failed integrity or run-contract validation.'); }
+}
+const STATE_METHODS = ['eth_getCode', 'eth_getStorageAt', 'eth_call', 'eth_estimateGas', 'eth_getLogs'];
+export function checkpointHash(row) {
+    return contentHash({ runId: row.run_id, versionId: row.version_id, manifestHash: row.manifest_hash, inputHash: row.input_hash,
+        operation: row.operation, sourceFence: row.source_fence, evidence: row.evidence });
+}
+/**
+ * The block parameter of a Token Researcher state read: the snapshot's hex block number, or, on Robinhood Chain (pinned by hash, EIP-1898),
+ * exactly `{ blockHash: <snapshot hash>, requireCanonical: true }` (packages/providers snapshotBlockTag).
+ */
+function pinnedBlockParameter(value, snapshot, chain) {
+    if (value === `0x${BigInt(snapshot.blockNumber).toString(16)}`)
+        return true;
+    if (chain !== 'robinhood' || value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const tag = value;
+    return Object.keys(tag).length === 2 && tag.requireCanonical === true && typeof tag.blockHash === 'string' && tag.blockHash.toLowerCase() === snapshot.blockHash.toLowerCase();
+}
+function chainIdentityMatches(receipt, chain) {
+    return receipt.chain === chain && contentHash(receipt.result) === receipt.contentHash && !((chain === 'ethereum' && receipt.chainId !== 1) || (chain === 'base' && receipt.chainId !== 8453)
+        || (chain === 'robinhood' && ![4663, 46630].includes(receipt.chainId)));
+}
+/** Check source scope independently of the executor before saving or reusing a captured response. */
+export function validateReceipt(evidence, input) {
+    try {
+        const receipt = EvidenceItemSchema.parse(evidence);
+        if (!chainIdentityMatches(receipt, input.chain))
+            throw new CheckpointIntegrityError();
+        const method = receipt.source.method;
+        const params = receipt.request;
+        if (method === 'eth_chainId') {
+            if (params.length !== 0 || receipt.snapshot !== null)
+                throw new CheckpointIntegrityError();
+        }
+        else if (method === 'eth_getBlockByNumber') {
+            // `latest` is the instant-read head; `finalized` and `safe` only admit receipts checkpointed before that rule.
+            if (params.length !== 2 || params[1] !== false || typeof params[0] !== 'string' || (!['latest', 'finalized', 'safe'].includes(params[0]) && !/^0x(?:0|[1-9a-fA-F][a-fA-F0-9]*)$/.test(params[0])))
+                throw new CheckpointIntegrityError();
+            if (receipt.snapshot && params[0] !== `0x${BigInt(receipt.snapshot.blockNumber).toString(16)}`)
+                throw new CheckpointIntegrityError();
+        }
+        else if (['eth_getCode', 'eth_getStorageAt', 'eth_call'].includes(method)) {
+            if (!receipt.snapshot || (receipt.finality !== 'sequencer-confirmed' && receipt.finality !== 'finalized'))
+                throw new CheckpointIntegrityError();
+            if (input.snapshotBlock !== undefined && receipt.snapshot.blockNumber !== input.snapshotBlock)
+                throw new CheckpointIntegrityError();
+            const target = method === 'eth_call' && typeof params[0] === 'object' && params[0] !== null && !Array.isArray(params[0])
+                ? params[0].to : params[0];
+            // Token Researcher 0.3.0: a Multicall3 read is in scope only as this token's discovery lookup or a bounded balances/pool-state read.
+            const market = method === 'eth_call' && marketCallInScope(params[0], input.address, receipt.chainId);
+            if (((typeof target !== 'string' || target.toLowerCase() !== input.address.toLowerCase()) && !market)
+                || !pinnedBlockParameter(params.at(-1), receipt.snapshot, input.chain)
+                || params.length !== (method === 'eth_getStorageAt' ? 3 : 2))
+                throw new CheckpointIntegrityError();
+        }
+        else if (method === HOLDER_ACTIVITY_METHOD) {
+            // Token Researcher 0.3.0: exactly one newest-first transfer page of this token, at or before the pinned block.
+            if (!receipt.snapshot || receipt.finality !== 'sequencer-confirmed' || !marketTransferRequestInScope(params, input.address, receipt.snapshot.blockNumber))
+                throw new CheckpointIntegrityError();
+        }
+        else
+            throw new CheckpointIntegrityError();
+        return receipt;
+    }
+    catch (error) {
+        if (error instanceof CheckpointIntegrityError)
+            throw error;
+        throw new CheckpointIntegrityError();
+    }
+}
+/** Transaction Inspector receipts may only contain reads derivable from the accepted payload (sender, target and decoded grantees). */
+export function validateInspectionReceipt(evidence, input) {
+    try {
+        const receipt = InspectionEvidenceItemSchema.parse(evidence);
+        if (!chainIdentityMatches(receipt, input.chain) || !inspectionReceiptInScope(receipt, input))
+            throw new CheckpointIntegrityError();
+        return receipt;
+    }
+    catch (error) {
+        if (error instanceof CheckpointIntegrityError)
+            throw error;
+        throw new CheckpointIntegrityError();
+    }
+}
+/** Watchtower receipts may only contain identity, window headers and the exact log filters derived from the accepted rules. */
+export function validateWatchReceipt(evidence, input) {
+    try {
+        const receipt = WatchEvidenceItemSchema.parse(evidence);
+        if (!chainIdentityMatches(receipt, input.chain) || !watchReceiptInScope(receipt, input))
+            throw new CheckpointIntegrityError();
+        return receipt;
+    }
+    catch (error) {
+        if (error instanceof CheckpointIntegrityError)
+            throw error;
+        throw new CheckpointIntegrityError();
+    }
+}
+/** Solana inspector receipts: the declared tool, read-only allowlisted methods, the accepted cluster, and private simulation payloads. */
+export function validateSolanaInspectionReceipt(evidence, input) {
+    try {
+        const receipt = ToolEvidenceItemSchema.parse(evidence);
+        if (receipt.tool !== SOLANA_INSPECTION_TOOL || receipt.capability !== 'solana.read' || !SOLANA_INSPECTION_RPC_METHODS.includes(receipt.source.method))
+            throw new CheckpointIntegrityError();
+        if (receipt.chain !== runCoverageChain(input) || contentHash(receipt.result) !== receipt.contentHash)
+            throw new CheckpointIntegrityError();
+        if (receipt.source.method === 'simulateTransaction' && receipt.privacy !== 'private-input')
+            throw new CheckpointIntegrityError();
+        return receipt;
+    }
+    catch (error) {
+        if (error instanceof CheckpointIntegrityError)
+            throw error;
+        throw new CheckpointIntegrityError();
+    }
+}
+/** Kind dispatch on the accepted input shape; the worker separately checks that the input kind matches the pinned manifest kind. */
+export function validateRunReceipt(evidence, input, manifest) {
+    const kind = runInputKind(input);
+    if (kind === 'solana-transaction-inspection')
+        return validateSolanaInspectionReceipt(evidence, input);
+    // P02/P03 indexed agents: declared tools, the read-method allowlist and the accepted chain (tool envelopes, like workflows).
+    if (kind === 'deployer-investigation' || kind === 'wallet-analysis') {
+        try {
+            return kind === 'deployer-investigation' ? validateDeployerReceipt(evidence, input) : validateWalletReceipt(evidence, input);
+        }
+        catch {
+            throw new CheckpointIntegrityError();
+        }
+    }
+    if (kind === 'workflow') {
+        const tools = manifest?.tools;
+        const connectors = manifest?.connectors;
+        try {
+            return validateWorkflowReceipt(evidence, input, Array.isArray(tools) ? { tools: tools, ...(Array.isArray(connectors) ? { connectors: connectors } : {}) } : undefined);
+        }
+        catch {
+            throw new CheckpointIntegrityError();
+        }
+    }
+    return kind === 'token-research' ? validateReceipt(evidence, input) : kind === 'watchtower' ? validateWatchReceipt(evidence, input) : validateInspectionReceipt(evidence, input);
+}
+export function restoreCheckpoints(run, rows) {
+    // Workflow and Solana receipts carry tool snapshots rather than one EVM chain id and block.
+    const inputHash = contentHash(run.input);
+    const evidence = [];
+    const workflow = ['workflow', 'solana-transaction-inspection', 'deployer-investigation', 'wallet-analysis'].includes(runInputKind(run.input));
+    const operations = new Set();
+    let snapshot = null;
+    const completedReads = new Map();
+    let identityChainId;
+    for (const row of rows) {
+        if (row.run_id !== run.id || row.version_id !== run.version_id || row.manifest_hash !== run.manifest_hash || row.input_hash !== inputHash
+            || !Number.isSafeInteger(row.operation) || row.operation <= 0 || row.operation > run.rpc_used || operations.has(row.operation)
+            || !Number.isSafeInteger(row.source_fence) || row.source_fence <= 0 || row.source_fence > run.fence || checkpointHash(row) !== row.checkpoint_hash)
+            throw new CheckpointIntegrityError();
+        operations.add(row.operation);
+        const validated = validateRunReceipt(row.evidence, run.input, run.manifest);
+        // Workflow receipts come from several tools, each with its own snapshot; reports show differing snapshots explicitly.
+        if (workflow) {
+            evidence.push(validated);
+            continue;
+        }
+        const receipt = validated;
+        if (identityChainId !== undefined && receipt.chainId !== identityChainId)
+            throw new CheckpointIntegrityError();
+        identityChainId = receipt.chainId;
+        if (receipt.snapshot) {
+            if (snapshot && (snapshot.blockNumber !== receipt.snapshot.blockNumber || snapshot.blockHash.toLowerCase() !== receipt.snapshot.blockHash.toLowerCase()))
+                throw new CheckpointIntegrityError();
+            snapshot = receipt.snapshot;
+            if (STATE_METHODS.includes(receipt.source.method)
+                && (receipt.completeness === 'complete-for-request' || receipt.contentHash === contentHash({ error: 'contract-reverted' }))) {
+                const key = contentHash({ method: receipt.source.method, request: receipt.request, snapshot: { ...receipt.snapshot, blockHash: receipt.snapshot.blockHash.toLowerCase() } });
+                const previous = completedReads.get(key);
+                if (previous && previous !== receipt.contentHash)
+                    throw new CheckpointIntegrityError();
+                completedReads.set(key, receipt.contentHash);
+            }
+        }
+        evidence.push(receipt);
+    }
+    if (snapshot) {
+        const identity = evidence.some((receipt) => receipt.source.method === 'eth_chainId' && receipt.completeness === 'complete-for-request'
+            && typeof receipt.result === 'string' && /^0x(?:0|[1-9a-fA-F][a-fA-F0-9]*)$/.test(receipt.result)
+            && BigInt(receipt.result) === BigInt(identityChainId));
+        if (!identity)
+            throw new CheckpointIntegrityError();
+        // A data read can only be reused when its selected block was actually captured during snapshot selection.
+        const header = evidence.some((receipt) => receipt.source.method === 'eth_getBlockByNumber' && receipt.completeness === 'complete-for-request'
+            && receipt.snapshot === null && typeof receipt.result === 'object' && receipt.result !== null && !Array.isArray(receipt.result)
+            && typeof receipt.result.hash === 'string' && receipt.result.hash.toLowerCase() === snapshot.blockHash.toLowerCase() && typeof receipt.result.number === 'string'
+            && /^0x(?:0|[1-9a-fA-F][a-fA-F0-9]*)$/.test(receipt.result.number)
+            && BigInt(receipt.result.number).toString() === snapshot.blockNumber);
+        if (!header)
+            throw new CheckpointIntegrityError();
+    }
+    return { manifestHash: run.manifest_hash, inputHash, evidence };
+}

package/dist/packages/runtime/src/policy.d.ts

@@ -0,0 +1,57 @@
+import { type ToolEvidenceItem, type WorkflowManifest, type WorkflowRunInput, type WorkflowToolDeclaration } from '../../contracts/src/workflow.js';
+/**
+ * Runtime permission policy for `agentex.workflow.v1` (D04). It sits between workflow nodes and the tool/transport boundary and
+ * consults only typed manifest grants: declared tool and version, capability method allowlist, chain, address/domain scope,
+ * per-tool and run budgets, and the report-only destination. Names, descriptions and listing text are never read.
+ */
+export declare class WorkflowPermissionError extends Error {
+    readonly code = "WORKFLOW_PERMISSION_DENIED";
+    constructor(message: string);
+}
+/** The only tracer a workflow may request: net balance and nonce changes, no storage or code, so a trace stays small and bounded. */
+export declare const PRESTATE_DIFF_TRACER_CONFIG: Readonly<{
+    tracer: "prestateTracer";
+    tracerConfig: Readonly<{
+        diffMode: true;
+        disableStorage: true;
+        disableCode: true;
+    }>;
+}>;
+/** Multicall3 (the same address on every supported EVM chain). A batched read targets Multicall3 and every contract inside the batch. */
+export declare const MULTICALL3 = "0xca11bde05977b3631167028862be2a173976ca11";
+/** The accepted input's address-typed values. These are the only initial address grants. */
+export declare function workflowAddressScope(manifest: Pick<WorkflowManifest, 'inputSchema'>, input: WorkflowRunInput): Set<string>;
+export interface WorkflowPermit {
+    /** Resolves the grant for a declared tool id; throws for undeclared tools or chains. */
+    grant(toolId: string): WorkflowToolDeclaration;
+    /** Before the run-wide runtime permit: method allowlist and the per-tool call ceiling. */
+    beforeCall(toolId: string, method: string): void;
+    /** Called by the guarded transport: consumes a prior permit for this method and checks address/domain scope. */
+    checkRequest(toolId: string, method: string, params: readonly unknown[]): void;
+    observe(toolId: string, method: string, outcome: {
+        result: unknown;
+    } | {
+        error: true;
+    }): void;
+    /** Accepts evidence only if it matches a response the guarded transport actually returned to this tool. */
+    admitEvidence(toolId: string, raw: unknown): ToolEvidenceItem;
+    /** Adds addresses from validated tool output when the manifest grants `input-derived` scope. */
+    derive(value: unknown): void;
+    calls(toolId: string): number;
+    scope(): string[];
+}
+/**
+ * Per-tool platform contracts. A registry tool may declare fixed, reviewed contract addresses it reads on a chain (for example DEX factories,
+ * a lending pool or Multicall3). They are in scope for that tool only; buyer inputs, tool output and descriptive text never add to them.
+ */
+export interface WorkflowPermitOptions {
+    curatedAddresses?: (toolId: string) => ReadonlySet<string>;
+}
+export declare function createWorkflowPermit(manifest: WorkflowManifest, input: WorkflowRunInput, options?: WorkflowPermitOptions): WorkflowPermit;
+/** Receipt check used by the durable run store before a workflow checkpoint is saved or restored. */
+export declare function validateWorkflowReceipt(evidence: unknown, input: WorkflowRunInput, manifest?: {
+    tools: readonly WorkflowToolDeclaration[];
+    connectors?: readonly {
+        id: string;
+    }[];
+}): ToolEvidenceItem;

package/dist/packages/runtime/src/policy.js

@@ -0,0 +1,296 @@
+import { decodeFunctionData, parseAbi } from 'viem';
+import { CONNECTOR_CALL_METHOD, connectorToolRef } from '../../contracts/src/workflow.js';
+import { contentHash } from '../../contracts/src/index.js';
+import { CAPABILITY_METHODS, ToolEvidenceItemSchema } from '../../contracts/src/workflow.js';
+/**
+ * Runtime permission policy for `agentex.workflow.v1` (D04). It sits between workflow nodes and the tool/transport boundary and
+ * consults only typed manifest grants: declared tool and version, capability method allowlist, chain, address/domain scope,
+ * per-tool and run budgets, and the report-only destination. Names, descriptions and listing text are never read.
+ */
+export class WorkflowPermissionError extends Error {
+    code = 'WORKFLOW_PERMISSION_DENIED';
+    constructor(message) { super(message); this.name = 'WorkflowPermissionError'; }
+}
+const EVM_ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+const ABI_ADDRESS_WORD = /^0x0{24}([0-9a-fA-F]{40})$/;
+const SOLANA_ADDRESS = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+const SOLANA_ADDRESS_METHODS = new Set(['getAccountInfo', 'getBalance', 'getSignaturesForAddress', 'getTokenSupply', 'getTokenLargestAccounts', 'getMultipleAccounts']);
+const ZERO_ADDRESS = `0x${'0'.repeat(40)}`;
+const MISSING_ADDRESS = Symbol('missing address');
+/** Requests that return one page of an unbounded sequence. Each counts against `limits.maximumPages`. */
+const PAGED_METHODS = new Set(['eth_getLogs', 'getSignaturesForAddress']);
+/** The only tracer a workflow may request: net balance and nonce changes, no storage or code, so a trace stays small and bounded. */
+export const PRESTATE_DIFF_TRACER_CONFIG = Object.freeze({ tracer: 'prestateTracer', tracerConfig: Object.freeze({ diffMode: true, disableStorage: true, disableCode: true }) });
+const TRANSACTION_HASH = /^0x[0-9a-fA-F]{64}$/;
+const blockNumberOf = (value) => typeof value === 'string' && /^0x(?:0|[1-9a-fA-F][0-9a-fA-F]{0,15})$/.test(value) ? BigInt(value) : null;
+const CHAIN_IDS = { ethereum: [1], base: [8453], robinhood: [4663, 46630] };
+const normalize = (value) => value === undefined ? null : JSON.parse(JSON.stringify(value, (_key, item) => typeof item === 'bigint' ? item.toString() : item));
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
+function collectStrings(value, out, depth = 0) {
+    if (out.length > 256 || depth > 6)
+        return;
+    if (typeof value === 'string')
+        out.push(value);
+    else if (Array.isArray(value))
+        for (const item of value)
+            collectStrings(item, out, depth + 1);
+    else if (value !== null && typeof value === 'object')
+        for (const item of Object.values(value))
+            collectStrings(item, out, depth + 1);
+}
+/** Addresses in arbitrary data: plain 20-byte addresses and ABI-encoded address words. Used only to widen `input-derived` scope. */
+function derivedEvmAddresses(value) {
+    const strings = [];
+    collectStrings(value, strings);
+    return strings.flatMap((item) => EVM_ADDRESS.test(item) ? [item.toLowerCase()] : ABI_ADDRESS_WORD.test(item) ? [`0x${ABI_ADDRESS_WORD.exec(item)[1].toLowerCase()}`] : []);
+}
+/** Multicall3 (the same address on every supported EVM chain). A batched read targets Multicall3 and every contract inside the batch. */
+export const MULTICALL3 = '0xca11bde05977b3631167028862be2a173976ca11';
+const AGGREGATE3 = parseAbi(['struct Call3 { address target; bool allowFailure; bytes callData; }', 'function aggregate3(Call3[] calls) payable returns ((bool success, bytes returnData)[] returnData)']);
+/** Every target of an aggregate3 batch, or a missing marker when the payload is not a plain aggregate3 call (other Multicall3 entry points are refused). */
+function multicallTargets(data) {
+    if (typeof data !== 'string' || !/^0x(?:[0-9a-fA-F]{2})*$/.test(data) || data.length > 2 + 2 * 131072)
+        return [MISSING_ADDRESS];
+    try {
+        const decoded = decodeFunctionData({ abi: AGGREGATE3, data: data });
+        const calls = decoded.args[0];
+        return calls.length > 0 && calls.length <= 256 ? calls.map((call) => call.target) : [MISSING_ADDRESS];
+    }
+    catch {
+        return [MISSING_ADDRESS];
+    }
+}
+/** Accounts an EVM read method actually targets. Unknown shapes are refused rather than ignored. */
+function evmTargets(method, params) {
+    const first = params[0];
+    const object = record(first);
+    switch (method) {
+        case 'eth_getCode':
+        case 'eth_getBalance':
+        case 'eth_getTransactionCount':
+        case 'eth_getStorageAt': return [first];
+        case 'eth_call':
+        case 'eth_estimateGas': {
+            if (!object)
+                return [first];
+            const direct = [object.to, ...(object.from === undefined ? [] : [object.from])];
+            return typeof object.to === 'string' && object.to.toLowerCase() === MULTICALL3 ? [...direct, ...multicallTargets(object.data ?? object.input)] : direct;
+        }
+        case 'eth_getLogs': {
+            if (!object)
+                return [first];
+            const topics = [];
+            collectStrings(object.topics ?? [], topics);
+            // A filter without an address matches every contract on the chain; that is never inside an address scope, so it is refused.
+            const addresses = [object.address ?? []].flat();
+            return [...(addresses.length ? addresses : [MISSING_ADDRESS]), ...topics.filter((topic) => ABI_ADDRESS_WORD.test(topic)).map((topic) => `0x${ABI_ADDRESS_WORD.exec(topic)[1]}`)];
+        }
+        default: return [];
+    }
+}
+/** The accepted input's address-typed values. These are the only initial address grants. */
+export function workflowAddressScope(manifest, input) {
+    const scope = new Set();
+    for (const [key, field] of Object.entries(manifest.inputSchema.properties)) {
+        const value = input.values[key];
+        if (typeof value !== 'string')
+            continue;
+        if (field.type === 'evm-address' && EVM_ADDRESS.test(value))
+            scope.add(value.toLowerCase());
+        if (field.type === 'solana-address' && SOLANA_ADDRESS.test(value))
+            scope.add(value);
+    }
+    return scope;
+}
+export function createWorkflowPermit(manifest, input, options = {}) {
+    const tools = new Map(manifest.tools.map((tool) => [tool.id, tool]));
+    const scope = workflowAddressScope(manifest, input);
+    const calls = new Map();
+    const pending = new Map();
+    const observed = new Map();
+    // D04 data-range and page limits: the head block is learned only from a permitted `eth_getBlockByNumber('latest')` response. No finality tag is read.
+    let headBlock = null;
+    let awaitingHead = false;
+    let pages = 0;
+    const deny = (message) => { throw new WorkflowPermissionError(message); };
+    const grant = (toolId) => {
+        const tool = tools.get(toolId) ?? deny(`Tool ${toolId} is not declared by this immutable version.`);
+        if (!manifest.chains.includes(input.chain) || !tool.chains.includes(input.chain))
+            deny(`Tool ${toolId} is not granted on ${input.chain}.`);
+        return tool;
+    };
+    const inScope = (address, toolId) => typeof address === 'string' && EVM_ADDRESS.test(address) && (address.toLowerCase() === ZERO_ADDRESS || scope.has(address.toLowerCase())
+        || (toolId !== undefined && (options.curatedAddresses?.(toolId).has(address.toLowerCase()) ?? false)));
+    const curatedSolana = (address, toolId) => typeof address === 'string' && (options.curatedAddresses?.(toolId).has(address) ?? false);
+    const derive = (value) => {
+        if (manifest.permissions.addressScope !== 'input-derived')
+            return;
+        for (const address of derivedEvmAddresses(value))
+            scope.add(address);
+        if (input.chain === 'solana') {
+            const strings = [];
+            collectStrings(value, strings);
+            for (const item of strings)
+                if (SOLANA_ADDRESS.test(item))
+                    scope.add(item);
+        }
+    };
+    return {
+        grant,
+        beforeCall(toolId, method) {
+            const tool = grant(toolId);
+            if (!CAPABILITY_METHODS[tool.capability].includes(method))
+                deny(`${method} is outside the ${tool.capability} capability of ${toolId}.`);
+            const used = calls.get(toolId) ?? 0;
+            if (used >= tool.maximumCalls)
+                deny(`Tool ${toolId} reached its declared ceiling of ${tool.maximumCalls} calls.`);
+            calls.set(toolId, used + 1);
+            pending.set(`${toolId}\n${method}`, (pending.get(`${toolId}\n${method}`) ?? 0) + 1);
+        },
+        checkRequest(toolId, method, params) {
+            const tool = grant(toolId);
+            const key = `${toolId}\n${method}`;
+            const permits = pending.get(key) ?? 0;
+            if (permits < 1)
+                deny(`${toolId} attempted ${method} without a runtime permit.`);
+            pending.set(key, permits - 1);
+            if (!Array.isArray(params) || params.length > 16)
+                deny('Request parameters are malformed.');
+            if (PAGED_METHODS.has(method)) {
+                if (pages >= manifest.limits.maximumPages)
+                    deny(`${toolId} requested page ${pages + 1} with ${method}; the version allows at most ${manifest.limits.maximumPages} paged request${manifest.limits.maximumPages === 1 ? '' : 's'} per run.`);
+                pages++;
+            }
+            if (tool.capability === 'evm.read') {
+                for (const target of evmTargets(method, params))
+                    if (!inScope(target, toolId))
+                        deny(target === MISSING_ADDRESS ? `${toolId} requested ${method} without an address; unscoped log filters are outside the ${manifest.permissions.addressScope} address scope.` : `${toolId} requested ${typeof target === 'string' ? target : 'a malformed target'}, outside the ${manifest.permissions.addressScope} address scope.`);
+                if (method === 'eth_getBlockByNumber')
+                    awaitingHead = params[0] === 'latest';
+                if (method === 'debug_traceTransaction') {
+                    const config = record(params[1]);
+                    const tracer = record(config?.tracerConfig);
+                    if (params.length !== 2 || typeof params[0] !== 'string' || !TRANSACTION_HASH.test(params[0]) || !config || Object.keys(config).length !== 2 || config.tracer !== PRESTATE_DIFF_TRACER_CONFIG.tracer
+                        || !tracer || Object.keys(tracer).length !== 3 || tracer.diffMode !== true || tracer.disableStorage !== true || tracer.disableCode !== true)
+                        deny(`${toolId} requested debug_traceTransaction without the fixed prestate-diff tracer; other tracers are not permitted.`);
+                }
+                if (method === 'eth_getLogs') {
+                    const filter = record(params[0]);
+                    const width = 'blockHash' in filter ? 1n : (() => {
+                        const resolveTag = (tag) => tag === 'latest' ? headBlock : blockNumberOf(tag);
+                        const from = resolveTag(filter.fromBlock);
+                        const to = resolveTag(filter.toBlock);
+                        if (from === null || to === null)
+                            deny(`${toolId} requested eth_getLogs from ${String(filter.fromBlock ?? 'an omitted block')} to ${String(filter.toBlock ?? 'an omitted block')}; log ranges need numeric bounds (or 'latest' after the latest head was read).`);
+                        if (to < from)
+                            deny(`${toolId} requested a descending eth_getLogs range.`);
+                        return to - from + 1n;
+                    })();
+                    if (width > BigInt(manifest.limits.maximumBlockRange))
+                        deny(`${toolId} requested eth_getLogs over ${width} block${width === 1n ? '' : 's'}; the version allows at most ${manifest.limits.maximumBlockRange}.`);
+                }
+            }
+            else if (tool.capability === 'solana.read') {
+                if (method === 'simulateTransaction')
+                    deny(`${toolId} requested simulateTransaction; the accounts of a proposed payload cannot be bound to the ${manifest.permissions.addressScope} scope, so workflows cannot simulate.`);
+                if (SOLANA_ADDRESS_METHODS.has(method))
+                    for (const address of [params[0]].flat())
+                        if (typeof address !== 'string' || !(scope.has(address) || curatedSolana(address, toolId)))
+                            deny(`${toolId} requested ${method} for ${typeof address === 'string' ? 'a Solana account' : 'no account'} outside the ${manifest.permissions.addressScope} scope.`);
+                // Validator reads are filtered to one in-scope account: an unfiltered vote-account or block-production list is refused (it is also megabytes).
+                if (method === 'getVoteAccounts' || method === 'getBlockProduction') {
+                    const config = record(params[0]);
+                    const key = method === 'getVoteAccounts' ? 'votePubkey' : 'identity';
+                    const account = config?.[key];
+                    if (params.length > 1 || typeof account !== 'string' || !(scope.has(account) || curatedSolana(account, toolId)))
+                        deny(`${toolId} requested ${method} without an in-scope ${key}; unfiltered validator lists are refused.`);
+                }
+                if (method === 'getRecentPerformanceSamples' && (params.length !== 1 || typeof params[0] !== 'number' || !Number.isInteger(params[0]) || params[0] < 1 || params[0] > 60))
+                    deny(`${toolId} requested getRecentPerformanceSamples without a limit of 1 to 60.`);
+            }
+            else {
+                let url = null;
+                try {
+                    url = new URL(String(params[0]));
+                }
+                catch {
+                    deny('HTTP reads need an absolute URL.');
+                }
+                if (url.protocol !== 'https:' || url.username || url.password || url.port || !manifest.permissions.domains.includes(url.hostname))
+                    deny(`${url.hostname || 'This URL'} is not an allowed https domain for ${toolId}.`);
+            }
+        },
+        observe(toolId, method, outcome) {
+            const key = `${toolId}\n${method}`;
+            const entry = observed.get(key) ?? { hashes: [], attempts: 0 };
+            entry.attempts++;
+            if ('result' in outcome)
+                entry.hashes.push(contentHash(normalize(outcome.result)));
+            observed.set(key, entry);
+            if (method === 'eth_getBlockByNumber' && awaitingHead && 'result' in outcome) {
+                const number = blockNumberOf(record(outcome.result)?.number);
+                if (number !== null && (headBlock === null || number > headBlock))
+                    headBlock = number;
+                awaitingHead = false;
+            }
+        },
+        admitEvidence(toolId, raw) {
+            const tool = grant(toolId);
+            const parsed = ToolEvidenceItemSchema.safeParse(raw);
+            if (!parsed.success)
+                deny(`${toolId} emitted evidence outside the shared evidence envelope.`);
+            const evidence = parsed.data;
+            if (evidence.tool !== `${tool.id}@${tool.version}` || evidence.capability !== tool.capability)
+                deny(`Evidence names ${evidence.tool} (${evidence.capability}), not the declared ${tool.id}@${tool.version}.`);
+            if (evidence.chain !== input.chain)
+                deny('Evidence chain differs from the accepted input chain.');
+            if (evidence.snapshot?.kind === 'evm-block' && !(CHAIN_IDS[input.chain] ?? []).includes(evidence.snapshot.chainId))
+                deny('Evidence block identity does not match the accepted chain.');
+            if (evidence.source.kind === 'offline') {
+                if (evidence.trust !== 'offline-decoding')
+                    deny('Offline evidence can only describe offline decoding.');
+                return evidence;
+            }
+            if (!CAPABILITY_METHODS[tool.capability].includes(evidence.source.method))
+                deny(`Evidence method ${evidence.source.method} is outside ${tool.capability}.`);
+            const entry = observed.get(`${toolId}\n${evidence.source.method}`);
+            if (!entry || entry.attempts < 1)
+                deny(`${toolId} emitted evidence for ${evidence.source.method}, which it never requested through the guarded transport.`);
+            if (evidence.completeness === 'complete-for-request' || evidence.completeness === 'empty-result') {
+                const position = entry.hashes.indexOf(evidence.contentHash);
+                if (position < 0)
+                    deny(`${toolId} emitted a result the guarded transport never returned (fabricated evidence).`);
+                entry.hashes.splice(position, 1);
+                derive(evidence.result);
+            }
+            entry.attempts--;
+            return evidence;
+        },
+        derive,
+        calls: (toolId) => calls.get(toolId) ?? 0,
+        scope: () => [...scope],
+    };
+}
+/** Receipt check used by the durable run store before a workflow checkpoint is saved or restored. */
+export function validateWorkflowReceipt(evidence, input, manifest) {
+    const receipt = ToolEvidenceItemSchema.parse(evidence);
+    if (receipt.chain !== input.chain)
+        throw new WorkflowPermissionError('Receipt chain does not match the run contract.');
+    if (receipt.snapshot?.kind === 'evm-block' && !(CHAIN_IDS[input.chain] ?? []).includes(receipt.snapshot.chainId))
+        throw new WorkflowPermissionError('Receipt network identity does not match the chain.');
+    const methodAllowed = (capability) => receipt.source.kind === 'offline' || CAPABILITY_METHODS[capability].includes(receipt.source.method);
+    if (manifest) {
+        const tool = manifest.tools.find((item) => `${item.id}@${item.version}` === receipt.tool);
+        // N03: a pinned remote connector's receipt is one metered POST envelope of untrusted third-party content.
+        const connector = tool ? undefined : manifest.connectors?.find((item) => connectorToolRef(item.id) === receipt.tool);
+        if (connector) {
+            if (receipt.capability !== 'http.read' || receipt.source.kind !== 'http' || receipt.source.method !== CONNECTOR_CALL_METHOD)
+                throw new WorkflowPermissionError('Receipt is not a metered connector call envelope.');
+        }
+        else if (!tool || tool.capability !== receipt.capability || !methodAllowed(tool.capability))
+            throw new WorkflowPermissionError('Receipt tool or method is not granted by the pinned version.');
+    }
+    else if (!methodAllowed(receipt.capability))
+        throw new WorkflowPermissionError('Receipt method is not a read method.');
+    return receipt;
+}

package/dist/packages/sdk/src/bin/agentex-buyer.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/packages/sdk/src/bin/agentex-buyer.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runBuyerCli } from '../buyer-cli.js';
+// Buyer commands use a scoped AGENTEX_API_KEY (never printed) against https://agentex.sh, or AGENTEX_API_ORIGIN / --api.
+process.exitCode = await runBuyerCli(process.argv.slice(2), { env: process.env, stdout: text => process.stdout.write(text), stderr: text => process.stderr.write(text) });

package/dist/packages/sdk/src/bin/agentex.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};