@upoch/guard 0.1.1 → 0.1.3

package/README.md

@@ -6,9 +6,15 @@ Upoch Guard saves verifiable checkpoints of an agent's work on Robinhood Chain.
 prompt or makes a bad trade, it restores the last good state, checked against the chain, or rolls back to the
 checkpoint before the mistake and keeps going. It also knows which of its actions already happened.
 
-This package is the `upoch` command you set Upoch up with, and the engine behind the Upoch framework plugins:
+This package is the `upoch` command you set Upoch up with, an MCP server, and the engine behind the Upoch
+framework plugins:
 
-- **ElizaOS**: [@upoch/plugin-elizaos](https://www.npmjs.com/package/@upoch/plugin-elizaos)
+| Agent | One line |
+|---|---|
+| Claude Code | `claude mcp add upoch -- upoch mcp` |
+| Cursor, Codex, Claude Desktop, any MCP client | an MCP server with the command `upoch mcp` (stdio) |
+| ElizaOS | `plugins: ["@upoch/plugin-elizaos"]` in your character ([@upoch/plugin-elizaos](https://www.npmjs.com/package/@upoch/plugin-elizaos)) |
+| LangChain / LangGraph | `callbacks: [new UpochCallbackHandler()]` ([@upoch/langchain](https://www.npmjs.com/package/@upoch/langchain)) |
 
 Website and debugger: https://upoch.tech. Contract (Robinhood Chain, 4663): `0x6179d9123c3c1f9e82f948101a4350cb55aa8c27`
 
@@ -22,8 +28,8 @@ upoch setup
 ```
 
 `upoch setup` creates your keys in `~/.upoch`, shows the owner address, and waits while you send it a little ETH on
-Robinhood Chain (0.001 ETH is plenty). Then it registers your agent. After that, connecting an agent is one line,
-for example `plugins: ["@upoch/plugin-elizaos"]` in an ElizaOS character.
+Robinhood Chain (0.001 ETH is plenty). Then it registers your agent and, if Claude Code is installed, offers to
+add the MCP server to it. After that, connecting an agent is one line (table above).
 
 Prefer separate steps? Run `upoch init`, then `upoch register`.
 
@@ -42,10 +48,28 @@ Two keys are created on your machine and never leave it:
 A rollback restores the agent's state and memory. It cannot reverse transactions that already happened on-chain;
 those are listed so the agent can account for them.
 
+## MCP tools
+
+| Tool | What it does | On-chain |
+|---|---|---|
+| `upoch_restore` | Restores the latest checkpoint after verifying it: state, note, completed and unresolved actions | read |
+| `upoch_checkpoint` | Saves the current state as a checkpoint (`progress`, `before_action`, `after_action`, `manual`) | 1 transaction |
+| `upoch_record_action` | Records an external action (planned, submitted, confirmed, failed) with its transaction hash | no (goes into the next checkpoint) |
+| `upoch_rollback` | Goes back to an earlier checkpoint (e.g. before a bad trade) and continues from it; lists actions since then that were not undone on-chain | 1 transaction |
+| `upoch_complete` | Saves a final checkpoint and marks the run finished | 1 transaction |
+| `upoch_history` | Lists recent checkpoints | read |
+| `upoch_verify` | Verifies one checkpoint without restoring it | read |
+| `upoch_status` | Shows the workflow, executor funds and today's usage | read |
+
+The server tells the agent when to use them: restore at the start, checkpoint after meaningful progress and before
+consequential actions, record each action as planned and then as confirmed, roll back when something went wrong,
+and complete at the end.
+
 ## Commands
 
 ```sh
 upoch setup          # keys, funding, registration, in one go
+upoch mcp            # run the MCP server (stdio); your MCP client starts it
 upoch status         # workflow, funds and today's usage
 upoch key            # print the checkpoint key, to open checkpoints in the debugger
 upoch export-owner   # print the owner private key, to import it into a wallet

package/dist/cli.js

@@ -4,7 +4,7 @@
 //   upoch init           create keys and settings (your terminal only)
 //   upoch register       register the agent's workflow on-chain and fund its executor (your terminal only)
 //   upoch status         show the workflow, funds and usage
-//   upoch mcp            run the MCP server (stdio) for Claude Code, Cursor, Codex and other MCP clients (see LAUNCHED)
+//   upoch mcp            run the MCP server (stdio) for Claude Code, Cursor, Codex and other MCP clients
 //   upoch key            print the checkpoint key, to open checkpoints in the debugger (your terminal only)
 //   upoch export-owner   print the owner private key, to import it into a wallet (your terminal only)
 import { spawnSync } from "node:child_process";
@@ -16,11 +16,8 @@ import { hasSetup, loadConfig, loadSecrets, networkInfo, upochHome } from "./con
 import { Guard } from "./guard.js";
 import { createServer, VERSION } from "./server.js";
 import { initialize, register, registrationPlan } from "./setup.js";
-/**
- * Integrations announced so far. The MCP server (`upoch mcp`) and LangChain already work; help and setup output list
- * them only once they launch. Flip these at launch.
- */
-const LAUNCHED = { mcp: false, langchain: false };
+/** Integrations listed in help and setup output. */
+const LAUNCHED = { mcp: true, langchain: true };
 const CONNECT = [
     ...(LAUNCHED.mcp ? ["  Claude Code     claude mcp add upoch -- upoch mcp", "  Cursor, Codex   add an MCP server with the command: upoch mcp"] : []),
     '  ElizaOS         plugins: ["@upoch/plugin-elizaos"] in your character',

package/dist/guard.d.ts

@@ -1,7 +1,34 @@
-import { LocalKeySigner, type Eip1193Provider } from "@upoch/sdk";
+import { LocalKeySigner, type Eip1193Provider, type StorageAdapter } from "@upoch/sdk";
 import { type NetworkInfo, type UpochConfig } from "./config.ts";
 export type CheckpointKind = "progress" | "before_action" | "after_action" | "manual";
 export type ActionStatus = "planned" | "submitted" | "confirmed" | "failed";
+/** An action that ran after a rollback's target checkpoint; rolling back does not reverse it. */
+export type NotUndone = {
+    operationId: string;
+    status: string;
+    transactionHash?: string;
+};
+/**
+ * IPFS that reads through the gateway and, when the gateway refuses or fails, through the authenticated RPC `cat`.
+ * Found on mainnet: Filebase's gateway intermittently answers 403 "CDN proxying is not allowed" (behind VPNs such as
+ * Cloudflare WARP), which would otherwise fail a restore or the verification after a commit.
+ */
+export declare class IpfsWithFallback implements StorageAdapter {
+    readonly provider: "ipfs";
+    readonly developmentOnly = false;
+    private readonly gateway;
+    private readonly rpc;
+    constructor(o: {
+        apiUrl: string;
+        gatewayUrl: string;
+        authorization?: string;
+    });
+    upload(bytes: Uint8Array): Promise<import("@upoch/sdk").StoredObject>;
+    retrieve(contentId: string): Promise<Uint8Array<ArrayBufferLike>>;
+    isAvailable(contentId: string): Promise<boolean>;
+    health(): Promise<import("@upoch/sdk").StorageHealth>;
+    locator(contentId: string): string;
+}
 /** A refusal the agent can act on (wrong input, a limit, missing funds). Distinct from unexpected failures. */
 export declare class GuardError extends Error {
     readonly code: string;
@@ -12,6 +39,8 @@ export interface GuardOptions {
     /** Overrides the RPC provider (tests). */
     provider?: Eip1193Provider;
     now?: () => Date;
+    /** Waits before retrying a checkpoint whose submission failed transiently (default 3 s, then 8 s). */
+    retryDelaysMs?: number[];
 }
 export declare class Guard {
     readonly home: string;
@@ -23,6 +52,7 @@ export declare class Guard {
     private readonly reader;
     private readonly journal;
     private readonly now;
+    private readonly retryDelaysMs;
     private readonly principal;
     private parts?;
     constructor(o?: GuardOptions);
@@ -69,6 +99,7 @@ export declare class Guard {
         state: unknown;
         note?: string;
         kind?: CheckpointKind;
+        notUndone?: NotUndone[];
     }, executionStatus?: "RUNNING" | "COMPLETED"): Promise<any>;
     /** Records an external action (a swap, a transfer, an API call) so the next checkpoint and any recovery know about it. */
     recordAction(a: {
@@ -101,11 +132,7 @@ export declare class Guard {
     rollback(o: {
         sequence: number;
         reason: string;
-        annotate?: (state: unknown, actionsSince: {
-            operationId: string;
-            status: string;
-            transactionHash?: string;
-        }[]) => unknown;
+        annotate?: (state: unknown, actionsSince: NotUndone[]) => unknown;
     }): Promise<any>;
     /** The most recent checkpoints on-chain, newest first. Read-only. */
     history(o?: {

package/dist/guard.js

@@ -10,6 +10,52 @@ const CHECKPOINT_GAS = 230000n;
 const HASH = /^0x[0-9a-fA-F]{64}$/;
 const TYPES = { progress: "SAFE_BOUNDARY", before_action: "PRE_ACTION", after_action: "POST_ACTION", manual: "MANUAL" };
 const STATUSES = { planned: "PENDING", submitted: "SUBMITTED", confirmed: "CONFIRMED", failed: "FAILED" };
+/**
+ * IPFS that reads through the gateway and, when the gateway refuses or fails, through the authenticated RPC `cat`.
+ * Found on mainnet: Filebase's gateway intermittently answers 403 "CDN proxying is not allowed" (behind VPNs such as
+ * Cloudflare WARP), which would otherwise fail a restore or the verification after a commit.
+ */
+export class IpfsWithFallback {
+    provider = "ipfs";
+    developmentOnly = false;
+    gateway;
+    rpc;
+    constructor(o) {
+        this.gateway = new IpfsStorageAdapter(o);
+        this.rpc = new IpfsStorageAdapter({ apiUrl: o.apiUrl, ...(o.authorization ? { authorization: o.authorization } : {}) });
+    }
+    upload(bytes) {
+        return this.rpc.upload(bytes);
+    }
+    async retrieve(contentId) {
+        try {
+            return await this.gateway.retrieve(contentId);
+        }
+        catch (gatewayError) {
+            try {
+                return await this.rpc.retrieve(contentId);
+            }
+            catch {
+                throw gatewayError;
+            }
+        }
+    }
+    async isAvailable(contentId) {
+        try {
+            await this.retrieve(contentId);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    health() {
+        return this.rpc.health();
+    }
+    locator(contentId) {
+        return this.gateway.locator(contentId);
+    }
+}
 /** A refusal the agent can act on (wrong input, a limit, missing funds). Distinct from unexpected failures. */
 export class GuardError extends Error {
     code;
@@ -29,6 +75,7 @@ export class Guard {
     reader;
     journal;
     now;
+    retryDelaysMs;
     principal;
     parts;
     constructor(o = {}) {
@@ -42,6 +89,7 @@ export class Guard {
         this.reader = new EpochReader(this.provider, this.network.ledger);
         this.journal = new FileJournal(journalPath(this.home));
         this.now = o.now ?? (() => new Date());
+        this.retryDelaysMs = o.retryDelaysMs ?? [3000, 8000];
         this.principal = { kind: "agent", id: this.config.agentId };
         // Built lazily (needs a registered workflow); the secrets stay inside these closures, never on `this`.
         this.build = () => {
@@ -52,7 +100,9 @@ export class Guard {
             const s = this.config.storage;
             const storage = new ReplicatedStorage([
                 s.kind === "ipfs"
-                    ? new IpfsStorageAdapter({ apiUrl: s.apiUrl, gatewayUrl: s.gatewayUrl, authorization: secrets.ipfsAuthorization })
+                    ? s.gatewayUrl
+                        ? new IpfsWithFallback({ apiUrl: s.apiUrl, gatewayUrl: s.gatewayUrl, ...(secrets.ipfsAuthorization ? { authorization: secrets.ipfsAuthorization } : {}) })
+                        : new IpfsStorageAdapter({ apiUrl: s.apiUrl, authorization: secrets.ipfsAuthorization })
                     : new LocalStorageAdapter(s.dir),
             ]);
             const encryption = new LocalAesGcmProvider(Buffer.from(secrets.encryptionKey, "hex"));
@@ -146,15 +196,24 @@ export class Guard {
             ...(r.transactionHash ? { transactionHash: r.transactionHash } : {}),
             ...(r.resultCommitment ? { resultHash: r.resultCommitment } : {}),
         }));
-        const rec = await this.p.manager.create({
+        const create = () => this.p.manager.create({
             executionId: exec.executionId,
             checkpointSequence: exec.nextSequence,
             checkpointType: TYPES[input.kind ?? "progress"],
             state: input.state,
-            context: input.note ? { note: input.note } : {},
+            context: { ...(input.note ? { note: input.note } : {}), ...(input.notUndone?.length ? { notUndone: input.notUndone } : {}) },
             actions,
             executionStatus,
         });
+        let rec = await create();
+        // Found on mainnet: a transient RPC failure fails the submission before anything is sent. Retrying is safe: each
+        // attempt re-reads the head, and the chain adapter checks for an identical committed checkpoint before sending.
+        for (const wait of this.retryDelaysMs) {
+            if (rec.status !== "SUBMISSION_FAILED" || rec.error?.code !== "CHAIN_SUBMISSION_FAILED")
+                break;
+            await new Promise((r) => setTimeout(r, wait));
+            rec = await create();
+        }
         const committed = rec.status === "COMMITTED" || rec.status === "VERIFIED_RECOVERY_POINT";
         if (committed) {
             const after = this.session();
@@ -221,6 +280,9 @@ export class Guard {
             saveSession(cp.executionStatus === "RUNNING" ? { ...s, executionId: cp.manifest.executionId, nextSequence: cp.manifest.checkpointSequence + 1 } : { day: s.day, checkpointsToday: s.checkpointsToday }, this.home);
         }
         const note = cp.context?.note;
+        // Saved by a rollback: actions that happened after the restored checkpoint, so a restart still knows them.
+        const notUndone = cp.context?.notUndone;
+        const hasNotUndone = Array.isArray(notUndone) && notUndone.length > 0;
         return bigintSafe({
             status: r.status,
             sequence: cp.sequence,
@@ -233,11 +295,14 @@ export class Guard {
             actions: cp.manifest.actions,
             completedActions: r.completed.map((c) => c.operationId),
             unresolvedActions: r.unresolved,
+            ...(hasNotUndone ? { notUndone } : {}),
             ...(isHead ? {} : { warning: "This is an older checkpoint, read for inspection only. To go back to it and continue from it, call upoch_rollback with this sequence." }),
             next: r.status === "HALTED_FOR_REVIEW"
                 ? "Some actions have an unknown outcome. Check them (for example by transaction hash) before doing anything else, then record their real status."
                 : cp.executionStatus === "RUNNING"
-                    ? "Continue from this state. Do not repeat completed actions."
+                    ? hasNotUndone
+                        ? "Continue from this state. It was restored by a rollback: the actions in notUndone happened after it and were NOT undone on-chain. Do not repeat them; check their effects (balances, positions) before acting."
+                        : "Continue from this state. Do not repeat completed actions."
                     : "That run had finished. A new checkpoint starts a new run.",
         });
     }
@@ -282,7 +347,7 @@ export class Guard {
         const note = `Rolled back to checkpoint #${o.sequence}: ${o.reason.trim()}`.slice(0, 500);
         const actionsSince = [...since.values()];
         const state = o.annotate ? o.annotate(structuredClone(cp.state), actionsSince) : cp.state;
-        const committed = await this.checkpoint({ state, note, kind: "manual" });
+        const committed = await this.checkpoint({ state, note, kind: "manual", notUndone: actionsSince });
         if (committed.status !== "VERIFIED_RECOVERY_POINT" && committed.status !== "COMMITTED")
             return { ...committed, rolledBackTo: o.sequence, state: undefined };
         return bigintSafe({

package/dist/server.d.ts

@@ -1,5 +1,5 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { Guard } from "./guard.ts";
-export declare const VERSION = "0.1.1";
+export declare const VERSION = "0.1.3";
 export declare const INSTRUCTIONS = "Upoch Guard saves verifiable checkpoints of your work on Robinhood Chain, so a crash, a bad prompt or a bad trade can be recovered from the last good state.\n\nWhen to use it:\n- At the start of a task, call upoch_restore. If a run was interrupted, continue from the returned state and do not repeat its completed actions.\n- After meaningful progress, call upoch_checkpoint with the state you would need to continue (plan, step, positions, results so far). Not after every small step: each checkpoint is an on-chain transaction.\n- Before a consequential external action (a swap, a transfer, a deployment), call upoch_record_action with status \"planned\" and then upoch_checkpoint with kind \"before_action\". After it settles, record it again as \"confirmed\" (with its transaction hash) or \"failed\".\n- If something went wrong (a bad trade, a bad instruction, corrupted state), use upoch_history to find the last good checkpoint and upoch_rollback to go back to it and continue. Rolling back restores your state; it does not undo on-chain transactions, so check the actions it lists.\n- When the task is finished, call upoch_complete.\n\nNever put private keys, seed phrases, passwords or API tokens in the state, notes or actions: checkpoints are permanent. Upoch refuses state that looks like it contains them. Setup (keys, registration, funding) is done by the user in their own terminal with the upoch command; never run \"upoch init\", \"upoch register\", \"upoch key\" or \"upoch export-owner\" yourself.";
 export declare function createServer(guard: Guard | (() => Guard)): McpServer;

package/dist/server.js

@@ -3,7 +3,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { Guard, GuardError } from "./guard.js";
-export const VERSION = "0.1.1";
+export const VERSION = "0.1.3";
 export const INSTRUCTIONS = `Upoch Guard saves verifiable checkpoints of your work on Robinhood Chain, so a crash, a bad prompt or a bad trade can be recovered from the last good state.
 
 When to use it:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@upoch/guard",
-  "version": "0.1.1",
-  "description": "Upoch Guard: verifiable checkpoints, recovery and rollback for AI agents on Robinhood Chain. The upoch command and the engine behind the Upoch framework plugins.",
+  "version": "0.1.3",
+  "description": "Upoch Guard: verifiable checkpoints, recovery and rollback for AI agents on Robinhood Chain. The upoch command, an MCP server for Claude Code, Cursor and Codex, and the engine behind the Upoch plugins for ElizaOS and LangChain.",
   "keywords": [
     "upoch",
     "ai-agents",
@@ -9,7 +9,10 @@
     "recovery",
     "rollback",
     "robinhood-chain",
-    "elizaos"
+    "elizaos",
+    "langchain",
+    "mcp",
+    "model-context-protocol"
   ],
   "homepage": "https://upoch.tech/docs",
   "license": "MIT",