@upoch/guard 0.1.2 → 0.1.3

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.2";
+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.2";
+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,6 +1,6 @@
 {
   "name": "@upoch/guard",
-  "version": "0.1.2",
+  "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",