otto-intel-mcp 0.1.2 → 0.1.4

package/dist/execution-delegation-finality.js

@@ -0,0 +1,90 @@
+import { parseTransaction } from 'viem';
+import { refuse } from './execution-errors.js';
+function exactDelegatedChainTransaction(chain, operation, step) {
+    try {
+        const expected = parseTransaction(step.request.transaction);
+        return (expected.type === 'eip1559' && chain.type === expected.type && expected.chainId === 8453 &&
+            chain.hash.toLowerCase() === step.transactionHash.toLowerCase() &&
+            chain.from.toLowerCase() === operation.account.toLowerCase() &&
+            chain.to?.toLowerCase() === expected.to?.toLowerCase() &&
+            chain.input.toLowerCase() === expected.data?.toLowerCase() &&
+            chain.value === (expected.value ?? 0n) && chain.nonce === expected.nonce &&
+            chain.gas === expected.gas && chain.maxFeePerGas === expected.maxFeePerGas &&
+            chain.maxPriorityFeePerGas === expected.maxPriorityFeePerGas && chain.chainId === expected.chainId &&
+            JSON.stringify(chain.accessList ?? []) === JSON.stringify(expected.accessList ?? []) &&
+            step.request.userId === operation.userId &&
+            step.request.address.toLowerCase() === operation.account.toLowerCase() && step.request.network === 'base');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * One exact finality rule for both the live worker and crash reconciliation. Ordinary canonical
+ * inclusion is not enough to release the cross-rail claim: the finalized head, canonical block,
+ * transaction request, and durable receipt must all agree.
+ */
+export async function verifyDelegatedStepFinality(pub, operation, step) {
+    const receiptBackedTerminal = (step.state === 'confirmed' || step.state === 'failed') && step.receipt !== undefined;
+    if (step.state === 'failed' && !step.receipt)
+        return { outcome: 'verified' };
+    if (step.state !== 'submitted' && !receiptBackedTerminal)
+        return { outcome: 'unverified' };
+    if (!step.transactionHash)
+        return refuse('DELEGATION_REPLAY_MISMATCH', `the receipt-bearing delegated step ${step.index} has no durable transaction hash`);
+    let receipt;
+    try {
+        receipt = await pub.getTransactionReceipt({ hash: step.transactionHash });
+    }
+    catch {
+        return { outcome: 'unverified' };
+    }
+    let finalized;
+    try {
+        finalized = await pub.getBlock({ blockTag: 'finalized' });
+    }
+    catch {
+        return { outcome: 'unverified' };
+    }
+    if (finalized.number === null || finalized.hash === null || receipt.blockNumber > finalized.number)
+        return { outcome: 'unverified' };
+    let canonical;
+    let transaction;
+    try {
+        [canonical, transaction] = await Promise.all([
+            pub.getBlock({ blockNumber: receipt.blockNumber }),
+            pub.getTransaction({ hash: step.transactionHash }),
+        ]);
+    }
+    catch {
+        return { outcome: 'unverified' };
+    }
+    if (canonical.number !== receipt.blockNumber ||
+        canonical.hash?.toLowerCase() !== receipt.blockHash.toLowerCase() ||
+        (receipt.blockNumber === finalized.number &&
+            receipt.blockHash.toLowerCase() !== finalized.hash.toLowerCase()) ||
+        receipt.transactionHash.toLowerCase() !== step.transactionHash.toLowerCase() ||
+        receipt.from.toLowerCase() !== operation.account.toLowerCase() ||
+        transaction.blockHash?.toLowerCase() !== receipt.blockHash.toLowerCase() ||
+        transaction.blockNumber !== receipt.blockNumber ||
+        !exactDelegatedChainTransaction(transaction, operation, step) ||
+        receipt.to?.toLowerCase() !== transaction.to?.toLowerCase())
+        return refuse('DELEGATION_REPLAY_MISMATCH', `the finalized Base transaction or receipt for step ${step.index} does not match its durable request`);
+    const observed = {
+        transactionHash: step.transactionHash,
+        status: receipt.status,
+        blockNumber: receipt.blockNumber.toString(),
+        blockHash: receipt.blockHash,
+        gasUsed: receipt.gasUsed.toString(),
+    };
+    if (step.receipt && (step.receipt.transactionHash.toLowerCase() !== observed.transactionHash.toLowerCase() ||
+        step.receipt.status !== observed.status ||
+        step.receipt.blockNumber !== observed.blockNumber ||
+        step.receipt.blockHash.toLowerCase() !== observed.blockHash.toLowerCase() ||
+        step.receipt.gasUsed !== observed.gasUsed))
+        return refuse('DELEGATION_REPLAY_MISMATCH', `the canonical receipt for delegated step ${step.index} changed from its durable receipt`);
+    return step.state === 'submitted'
+        ? { outcome: 'seal', receipt: observed }
+        : { outcome: 'verified' };
+}
+//# sourceMappingURL=execution-delegation-finality.js.map

package/dist/execution-delegation-operation-store.d.ts

@@ -0,0 +1,129 @@
+import { type DelegatedSendResult } from './execution-delegated-definition.js';
+/** Public Base response version; the shared on-disk schema is versioned independently. */
+export declare const DELEGATION_OPERATION_JOURNAL_SCHEMA_VERSION: 2;
+export declare const DELEGATION_OPERATION_DB_FILE: "operations.db";
+export declare const DELEGATION_OPERATION_HISTORY_LIMIT: 20;
+/**
+ * SQLite's WAL-reset race is fixed in the maintained 3.44 and 3.50 branches and
+ * in the 3.51 line from 3.51.3 onward. Durable multi-process claims must refuse
+ * runtimes outside those known-safe release lines rather than rely on a deploy
+ * convention that an old worker can silently violate.
+ */
+export declare function sqliteWalRuntimeIsSafe(version: string | undefined): boolean;
+export declare const DELEGATION_OPERATION_STATES: readonly ["prepared", "submitted", "confirmed", "failed", "unknown"];
+export type DelegationOperationState = (typeof DELEGATION_OPERATION_STATES)[number];
+export declare const DELEGATION_OPERATION_STEP_STATES: readonly ["prepared", "submitted", "confirmed", "failed", "unknown"];
+export type DelegationOperationStepState = (typeof DELEGATION_OPERATION_STEP_STATES)[number];
+export declare const DELEGATION_OPERATION_STEP_KINDS: readonly ["approve_reset", "approve", "call", "allowance_clear"];
+export type DelegationOperationStepKind = (typeof DELEGATION_OPERATION_STEP_KINDS)[number];
+export interface DelegationOperationBinding {
+    readonly artifactId: string;
+    readonly userId: string;
+    readonly account: string;
+    readonly chainId: 8453;
+    readonly fingerprint: string;
+}
+export interface DelegationOperationJournalStatus {
+    readonly schemaVersion: typeof DELEGATION_OPERATION_JOURNAL_SCHEMA_VERSION;
+    readonly ready: boolean;
+    readonly coverageStartedAt: string | null;
+}
+export interface DelegationOperationStep {
+    readonly index: number;
+    readonly kind: DelegationOperationStepKind;
+    readonly state: DelegationOperationStepState;
+    readonly transactionHash?: string;
+}
+export interface DelegationOperationRecoveryStep extends DelegationOperationStep {
+    readonly request: DelegationCdpSendRequest;
+    readonly idempotencyKey: string;
+    readonly receipt?: DelegationOperationReceipt;
+}
+/** Static success fields sealed before the signer can hand the first request to CDP. */
+export type DelegationOperationRecoveryContext = Omit<DelegatedSendResult, 'steps' | 'replayed'>;
+export interface DelegationOperationRecoveryRecord extends Omit<DelegationOperationRecord, 'steps'> {
+    readonly steps: readonly DelegationOperationRecoveryStep[];
+    /** Missing only on rows written by a pre-recovery build; those rows cannot be promoted to success. */
+    readonly recoveryContext?: DelegationOperationRecoveryContext;
+}
+export interface DelegationOperationRecord extends DelegationOperationBinding {
+    readonly state: DelegationOperationState;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly steps: readonly DelegationOperationStep[];
+    readonly result?: unknown;
+}
+/** The exact request handed to `cdp.endUser.sendEvmTransaction`. Never returned by the read tool. */
+export interface DelegationCdpSendRequest {
+    readonly userId: string;
+    readonly address: string;
+    readonly transaction: `0x${string}`;
+    readonly network: 'base';
+    readonly idempotencyKey: string;
+}
+export interface DelegationOperationReceipt {
+    readonly transactionHash: string;
+    readonly status: 'success' | 'reverted';
+    readonly blockNumber: string;
+    readonly blockHash: string;
+    readonly gasUsed: string;
+}
+export type BeginDelegationOperation = {
+    readonly outcome: 'started';
+    readonly record: DelegationOperationRecord;
+} | {
+    readonly outcome: 'existing';
+    readonly record: DelegationOperationRecord;
+} | {
+    readonly outcome: 'busy';
+    readonly record: DelegationOperationRecord;
+} | {
+    readonly outcome: 'conflict';
+    readonly kind: 'mint' | 'exit' | 'native' | 'sponsored';
+    readonly claimId: string;
+} | {
+    readonly outcome: 'mismatch';
+};
+export interface DelegationOperationSnapshot {
+    readonly journal: DelegationOperationJournalStatus;
+    /** Global for this user, even when `artifactId` selected one terminal row. */
+    readonly unresolved: boolean;
+    readonly operations: readonly DelegationOperationRecord[];
+}
+export interface DelegationOperationStore {
+    readonly available: boolean;
+    readonly unavailableReason?: string;
+    journalStatus(): Promise<DelegationOperationJournalStatus>;
+    /** Explicit rollout transition. Call only after every pre-journal worker has drained. */
+    markReadyAfterLegacyDrain(nowMs: number): Promise<DelegationOperationJournalStatus>;
+    begin(binding: DelegationOperationBinding, nowMs: number): Promise<BeginDelegationOperation>;
+    /** Seal the non-transaction result fields before any signer/CDP work begins. Idempotent only byte-for-byte. */
+    setRecoveryContext(binding: DelegationOperationBinding, context: DelegationOperationRecoveryContext, nowMs: number): Promise<void>;
+    readArtifact(artifactId: string): Promise<DelegationOperationRecord | undefined>;
+    /** Private server-only recovery view. Serialized requests and idempotency keys never reach MCP output. */
+    readRecoveryArtifact(artifactId: string): Promise<DelegationOperationRecoveryRecord | undefined>;
+    snapshotForUser(userId: string, artifactId?: string, terminalLimit?: number): Promise<DelegationOperationSnapshot>;
+    prepareStep(binding: DelegationOperationBinding, index: number, kind: DelegationOperationStepKind, request: DelegationCdpSendRequest, nowMs: number): Promise<void>;
+    markStepSubmitted(binding: DelegationOperationBinding, index: number, idempotencyKey: string, transactionHash: string, nowMs: number): Promise<void>;
+    markStepUnknown(binding: DelegationOperationBinding, index: number, idempotencyKey: string, nowMs: number): Promise<void>;
+    /** A final local guard refused after journaling and before the CDP call; zero sends are known. */
+    markStepNotSubmitted(binding: DelegationOperationBinding, index: number, idempotencyKey: string, nowMs: number): Promise<void>;
+    markStepReceipt(binding: DelegationOperationBinding, index: number, idempotencyKey: string, receipt: DelegationOperationReceipt, nowMs: number): Promise<void>;
+    finalizeSuccess(binding: DelegationOperationBinding, result: unknown, nowMs: number): Promise<void>;
+    /** Terminal only when every attempted CDP request has a known terminal outcome (or none was attempted). */
+    finalizeFailure(binding: DelegationOperationBinding, failureCode: string, nowMs: number): Promise<DelegationOperationRecord>;
+    close?(): void;
+}
+export declare class DelegationOperationJournalNotReadyError extends Error {
+    constructor();
+}
+/** A stable UUID-v4-form key accepted by CDP, derived only from the bound artifact and step. */
+export declare function delegationOperationIdempotencyKey(artifactId: string, index: number): string;
+export declare function unavailableDelegationOperationStore(reason: string): DelegationOperationStore;
+export declare function openDelegationOperationStore(root: string, nowMs?: number): Promise<DelegationOperationStore>;
+export declare function createDelegationOperationStore(env?: NodeJS.ProcessEnv): Promise<DelegationOperationStore>;
+/** Test/local implementation with the same binding and unresolved-operation semantics. */
+export declare function inMemoryDelegationOperationStore(options?: {
+    readonly ready?: boolean;
+    readonly nowMs?: number;
+}): DelegationOperationStore;