@upoch/guard 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Upoch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# @upoch/guard: Upoch Guard
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Give your AI agent a memory and an undo button.
+
+Upoch Guard saves verifiable checkpoints of an agent's work on Robinhood Chain. If the agent crashes, gets a bad
+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:
+
+- **ElizaOS**: [@upoch/plugin-elizaos](https://www.npmjs.com/package/@upoch/plugin-elizaos)
+
+Website and debugger: https://upoch.tech. Contract (Robinhood Chain, 4663): `0x6179d9123c3c1f9e82f948101a4350cb55aa8c27`
+
+## Setup
+
+Needs Node.js 24 or later. In your own terminal:
+
+```sh
+npm install -g @upoch/guard
+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.
+
+Prefer separate steps? Run `upoch init`, then `upoch register`.
+
+## How it works
+
+Each checkpoint is encrypted on your machine and stored on IPFS. Its fingerprint is committed to the Upoch contract,
+and then the checkpoint is read back and verified. Only someone with your checkpoint key can read it, and anyone
+can check that it has not been changed. Every checkpoint opens in the
+[Time-Travel Debugger](https://upoch.tech/docs/debugger).
+
+Two keys are created on your machine and never leave it:
+
+- **Owner**: registers the agent and approves rollbacks. You fund it once.
+- **Executor**: the agent's key. It can only submit checkpoints, so the agent never holds the owner key.
+
+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.
+
+## Commands
+
+```sh
+upoch setup          # keys, funding, registration, in one go
+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
+```
+
+Settings live in `UPOCH_HOME` (default `~/.upoch`).
+
+## Safety
+
+- **Secrets are refused.** State, notes or actions that look like private keys, seed phrases, passwords or API
+  tokens are rejected before anything is stored, because checkpoints are permanent.
+- **Daily limit.** At most 100 checkpoints per UTC day by default (`maxCheckpointsPerDay` in `~/.upoch/config.json`).
+- **Terminal-only commands.** `upoch setup`, `init`, `register`, `key` and `export-owner` run only in an interactive
+  terminal, so an agent cannot run them.
+- **Keys are stored unencrypted** in `~/.upoch/secrets.json` (owner-only permissions on macOS and Linux). Keep only
+  a small amount of ETH on these keys, and back up the file: without it, nobody, including Upoch, can open your
+  checkpoints.
+- Upoch Guard signs and sends only checkpoint transactions from the executor and, during setup, the registration
+  and funding transactions from the owner.
+- The Upoch contracts have not been audited.
+
+## License
+
+MIT

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+// upoch: the Upoch Guard command line.
+//   upoch setup          init + wait for funding + register + connect, in one go (your terminal only)
+//   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 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";
+import { stdin, stdout } from "node:process";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { formatEther } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { hasSetup, loadConfig, loadSecrets, networkInfo, upochHome } from "./config.js";
+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 };
+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',
+    ...(LAUNCHED.langchain ? ["  LangChain       callbacks: [new UpochCallbackHandler()] from @upoch/langchain"] : []),
+].join("\n");
+const HELP = `Upoch Guard ${VERSION}: verifiable checkpoints, recovery and rollback for AI agents on Robinhood Chain.
+
+Setup, in your own terminal:
+  upoch setup             everything in one go: keys, funding, registration
+or step by step:
+  upoch init              create keys and settings in ${upochHome()}
+  upoch register          register your agent on-chain and fund its executor
+
+Then connect your agent with one line:
+${CONNECT}
+
+Other commands:
+  upoch status            workflow, funds and today's usage
+${LAUNCHED.mcp ? "  upoch mcp               run the MCP server (stdio)\n" : ""}  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)
+
+Settings live in UPOCH_HOME (default ~/.upoch). Keys never leave this machine.`;
+function ask(q, hidden = false) {
+    return new Promise((resolve) => {
+        stdout.write(q);
+        let buf = "";
+        const raw = stdin.isRaw;
+        if (stdin.isTTY)
+            stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding("utf8");
+        const onData = (s) => {
+            for (const ch of s) {
+                if (ch === "\r" || ch === "\n") {
+                    stdin.off("data", onData);
+                    if (stdin.isTTY)
+                        stdin.setRawMode(raw);
+                    stdin.pause();
+                    stdout.write("\n");
+                    return resolve(buf.trim());
+                }
+                if (ch === "\u0003")
+                    process.exit(130);
+                if (ch === "\u007f" || ch === "\b")
+                    buf = buf.slice(0, -1);
+                else {
+                    buf += ch;
+                    if (!hidden)
+                        stdout.write(ch);
+                }
+            }
+        };
+        stdin.on("data", onData);
+    });
+}
+/** Commands that create, move or reveal keys run only in an interactive terminal, so an agent cannot run them. */
+function requireTerminal(cmd) {
+    if (!stdin.isTTY || !stdout.isTTY) {
+        console.error(`"upoch ${cmd}" must be run by you in an interactive terminal, not by an agent or a script.`);
+        process.exit(1);
+    }
+}
+/** A numbered choice. With `required`, an empty answer asks again instead of taking option 1. */
+async function choose(q, options, required = false) {
+    console.log(q);
+    options.forEach(([, label], i) => console.log(`  ${i + 1}. ${label}`));
+    for (;;) {
+        const a = await ask(required ? `Type 1-${options.length}: ` : `Choose 1-${options.length} [1]: `);
+        if (a === "" && required)
+            continue;
+        const i = a === "" ? 0 : Number(a) - 1;
+        if (options[i])
+            return options[i][0];
+    }
+}
+async function cmdInit() {
+    requireTerminal("init");
+    if (hasSetup())
+        throw new Error(`Upoch is already set up in ${upochHome()}.`);
+    console.log(`Setting up Upoch Guard in ${upochHome()}\n`);
+    const network = await choose("Network:", [["mainnet", "Robinhood Chain mainnet (real ETH)"], ["testnet", "Robinhood Chain testnet (free test ETH, for trying it out)"]], true);
+    console.log(network === "mainnet" ? "  -> MAINNET: registration and checkpoints use real ETH." : "  -> testnet.");
+    const agentName = (await ask("Agent name (public, on-chain) [My agent]: ")) || "My agent";
+    const where = await choose("Where should encrypted checkpoints be stored?", [
+        ["filebase", "IPFS through Filebase (free account at filebase.com; needs an IPFS RPC API token)"],
+        ["kubo", "Another IPFS pinning service or node with a Kubo RPC API"],
+        ["local", "A folder on this computer (testing only: the debugger cannot read it)"],
+    ]);
+    let storage;
+    let ipfsAuthorization;
+    if (where === "filebase") {
+        const token = await ask("Filebase IPFS RPC API token (hidden): ", true);
+        if (!token)
+            throw new Error("a token is required");
+        storage = { kind: "ipfs", apiUrl: "https://rpc.filebase.io", gatewayUrl: "https://ipfs.filebase.io" };
+        ipfsAuthorization = `Bearer ${token}`;
+    }
+    else if (where === "kubo") {
+        const apiUrl = await ask("Kubo RPC API URL (e.g. http://127.0.0.1:5001): ");
+        const gatewayUrl = (await ask("Gateway URL for reading (optional): ")) || undefined;
+        const auth = await ask("Authorization header value (optional, hidden): ", true);
+        storage = { kind: "ipfs", apiUrl, ...(gatewayUrl ? { gatewayUrl } : {}) };
+        ipfsAuthorization = auth || undefined;
+    }
+    else {
+        const dir = (await ask(`Folder [${upochHome()}/checkpoints]: `)) || `${upochHome()}/checkpoints`;
+        storage = { kind: "local", dir };
+    }
+    const r = initialize({ network, agentName, storage, ipfsAuthorization });
+    console.log(`
+Done. Keys are in ${r.home}/secrets.json. Back that file up: without it, nobody (including Upoch) can open your checkpoints.
+
+  Owner     ${r.owner}   registers the agent and approves rollbacks
+  Executor  ${r.executor}   the agent's key; it only sends checkpoints`);
+    if (!chained)
+        console.log(`\nNext: send a little ETH on ${network === "mainnet" ? "Robinhood Chain" : "Robinhood Chain testnet"} to the owner address (0.001 ETH is plenty), then run:\n  upoch register`);
+}
+/** Set while `upoch setup` runs init and register in one go. */
+let chained = false;
+function fundArg(args) {
+    const i = args.indexOf("--fund");
+    return i >= 0 && args[i + 1] ? args[i + 1] : "0.0003";
+}
+/** init, wait for the owner to be funded, register, connect: everything in one command. */
+async function cmdSetup(args) {
+    requireTerminal("setup");
+    chained = true;
+    if (!hasSetup())
+        await cmdInit();
+    if (!loadConfig().workflowId) {
+        const fundEth = fundArg(args);
+        let p = await registrationPlan({ fundEth });
+        if (!p.enough) {
+            console.log(`\nSend at least ${formatEther(p.cost - p.balance)} ETH on ${p.network} to the owner (0.001 ETH is plenty):\n\n  ${p.owner}\n\nWaiting for it to arrive (Ctrl+C to stop; run "upoch setup" again to continue later)…`);
+            while (!p.enough) {
+                await new Promise((r) => setTimeout(r, 5000));
+                p = await registrationPlan({ fundEth });
+            }
+            console.log(`Received: the owner now has ${formatEther(p.balance)} ETH.\n`);
+        }
+        await cmdRegister(args);
+    }
+    else {
+        console.log(`Already registered as workflow #${loadConfig().workflowId}.`);
+    }
+    await connectClients();
+}
+/** Offers to add the MCP server to Claude Code when its CLI is installed, and prints the line for everything else. */
+async function connectClients() {
+    const claude = LAUNCHED.mcp ? spawnSync("claude", ["--version"], { stdio: "ignore", shell: process.platform === "win32" }) : null;
+    if (claude?.status === 0 && (await ask("\nAdd Upoch to Claude Code now? [Y/n]: ")).toLowerCase() !== "n") {
+        const r = spawnSync("claude", ["mcp", "add", "upoch", "--scope", "user", "--", "upoch", "mcp"], { stdio: "inherit", shell: process.platform === "win32" });
+        console.log(r.status === 0 ? "Added. Restart Claude Code to load it." : "Could not add it automatically; run the line below.");
+    }
+    console.log(`\nConnect your agent with one line:\n${CONNECT}`);
+}
+async function cmdRegister(args) {
+    requireTerminal("register");
+    const fundEth = fundArg(args);
+    const p = await registrationPlan({ fundEth });
+    const mainnet = loadConfig().network === "mainnet";
+    console.log(`Register "${loadConfig().agentName}" on ${p.network}${mainnet ? " MAINNET (real ETH)" : ""}:`);
+    console.log(`  1. The owner ${p.owner} registers a workflow with the executor ${p.executor}`);
+    console.log(`  2. The owner sends ${formatEther(p.fund)} ETH to the executor for checkpoint gas`);
+    console.log(`  Owner balance ${formatEther(p.balance)} ETH; this needs about ${formatEther(p.cost)} ETH (gas ${Number(p.gasPrice) / 1e9} gwei).`);
+    if (!p.enough)
+        throw new Error(`Not enough ETH. Send at least ${formatEther(p.cost - p.balance)} more ETH to ${p.owner} and run this again.`);
+    if ((await ask('Type "yes" to send: ')).toLowerCase() !== "yes")
+        return console.log("Nothing sent.");
+    const r = await register({ fundEth });
+    console.log(`\nRegistered workflow #${r.workflowId} (${r.registerTx}).`);
+    if (r.fundTx)
+        console.log(`Executor funded (${r.fundTx}).`);
+    if (r.debugger)
+        console.log(`Debugger: ${r.debugger}`);
+    if (!chained)
+        console.log(`\nConnect your agent with one line:\n${CONNECT}`);
+}
+async function cmdStatus() {
+    const s = await new Guard().status();
+    console.log(JSON.stringify(s, null, 2));
+}
+async function cmdMcp() {
+    const server = createServer(() => new Guard());
+    await server.connect(new StdioServerTransport());
+}
+function cmdKey() {
+    requireTerminal("key");
+    const s = loadSecrets();
+    const c = loadConfig();
+    console.log(`Checkpoint key for "${c.agentName}" (keep it private; anyone with it can read your checkpoints):\n\n  ${s.encryptionKey}\n`);
+    const url = c.workflowId ? networkInfo(c).debuggerUrl?.(c.workflowId) : undefined;
+    if (url)
+        console.log(`Paste it in the debugger to open checkpoints: ${url}`);
+}
+async function cmdExportOwner() {
+    requireTerminal("export-owner");
+    const s = loadSecrets();
+    console.log(`This prints the private key of the owner ${privateKeyToAccount(s.ownerKey).address}. Anyone who sees it controls the workflow.`);
+    if ((await ask('Type "show" to print it: ')).toLowerCase() !== "show")
+        return;
+    console.log(`\n  ${s.ownerKey}\n`);
+}
+async function main() {
+    const [cmd, ...args] = process.argv.slice(2);
+    switch (cmd) {
+        case "setup":
+            return cmdSetup(args);
+        case "init":
+            return cmdInit();
+        case "register":
+            return cmdRegister(args);
+        case "status":
+            return cmdStatus();
+        case "mcp":
+            return cmdMcp();
+        case "key":
+            return cmdKey();
+        case "export-owner":
+            return cmdExportOwner();
+        case "--version":
+        case "-v":
+            return console.log(VERSION);
+        default:
+            console.log(HELP);
+            if (cmd && cmd !== "help" && cmd !== "--help" && cmd !== "-h")
+                process.exitCode = 1;
+    }
+}
+main().catch((e) => {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exitCode = 1;
+});

package/dist/config.d.ts

@@ -0,0 +1,60 @@
+export type NetworkName = "mainnet" | "testnet" | "custom";
+export interface StorageConfig {
+    kind: "ipfs" | "local";
+    /** IPFS (Kubo RPC API), e.g. https://rpc.filebase.io. */
+    apiUrl?: string;
+    gatewayUrl?: string;
+    /** Local folder (development only: the debugger on upoch.tech cannot read it). */
+    dir?: string;
+}
+export interface UpochConfig {
+    network: NetworkName;
+    /** Only for "custom" (a local chain in tests); mainnet and testnet use the published deployments. */
+    custom?: {
+        rpcUrl: string;
+        ledger: `0x${string}`;
+        chainId: number;
+        startBlock?: string;
+    };
+    /** Set by `upoch register`. */
+    workflowId?: string;
+    agentId: string;
+    agentName: string;
+    storage: StorageConfig;
+    /** Each checkpoint is an on-chain transaction; this caps how many the agent can send per UTC day. */
+    maxCheckpointsPerDay: number;
+}
+export interface UpochSecrets {
+    ownerKey: `0x${string}`;
+    executorKey: `0x${string}`;
+    /** 32 bytes, hex, no 0x. Opens checkpoints in the debugger. */
+    encryptionKey: string;
+    /** Authorization header value for the IPFS API, e.g. "Bearer …". */
+    ipfsAuthorization?: string;
+}
+export interface Session {
+    executionId?: string;
+    nextSequence?: number;
+    day?: string;
+    checkpointsToday?: number;
+}
+export interface NetworkInfo {
+    name: string;
+    chainId: number;
+    ledger: `0x${string}`;
+    rpcUrl: string;
+    startBlock: bigint;
+    /** Public debugger page for a workflow, when one exists for this network. */
+    debuggerUrl?: (workflowId: string) => string;
+}
+export declare function upochHome(): string;
+export declare function loadConfig(home?: string): UpochConfig;
+export declare function saveConfig(c: UpochConfig, home?: string): void;
+export declare function loadSecrets(home?: string): UpochSecrets;
+export declare function saveSecrets(s: UpochSecrets, home?: string): void;
+export declare function newSecrets(ipfsAuthorization?: string): UpochSecrets;
+export declare function loadSession(home?: string): Session;
+export declare function saveSession(s: Session, home?: string): void;
+export declare const journalPath: (home?: string) => string;
+export declare function hasSetup(home?: string): boolean;
+export declare function networkInfo(c: UpochConfig): NetworkInfo;

package/dist/config.js

@@ -0,0 +1,70 @@
+// Local configuration for Upoch Guard. Everything lives in one folder (default ~/.upoch, or UPOCH_HOME):
+//   config.json   network, workflow, storage and limits (no secrets)
+//   secrets.json  owner and executor keys, the checkpoint encryption key, the IPFS token (file mode 600)
+//   session.json  the open execution and today's checkpoint count
+//   journal.jsonl the action journal
+import { randomBytes } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { ROBINHOOD_MAINNET, ROBINHOOD_TESTNET } from "@upoch/sdk";
+import { generatePrivateKey } from "viem/accounts";
+export function upochHome() {
+    return process.env.UPOCH_HOME || path.join(homedir(), ".upoch");
+}
+const file = (home, name) => path.join(home, name);
+function readJson(p) {
+    if (!existsSync(p))
+        return undefined;
+    return JSON.parse(readFileSync(p, "utf8"));
+}
+/** Atomic write; secrets are written owner-only (enforced on POSIX; on Windows the folder's ACL applies). */
+function writeJson(p, v, secret = false) {
+    const tmp = `${p}.${randomBytes(4).toString("hex")}.tmp`;
+    writeFileSync(tmp, JSON.stringify(v, null, 2) + "\n", { mode: secret ? 0o600 : 0o644 });
+    renameSync(tmp, p);
+    if (secret)
+        chmodSync(p, 0o600);
+}
+export function loadConfig(home = upochHome()) {
+    const c = readJson(file(home, "config.json"));
+    if (!c)
+        throw new Error(`Upoch is not set up yet. Run "upoch init" in your own terminal (looked in ${home}).`);
+    return c;
+}
+export function saveConfig(c, home = upochHome()) {
+    mkdirSync(home, { recursive: true });
+    writeJson(file(home, "config.json"), c);
+}
+export function loadSecrets(home = upochHome()) {
+    const s = readJson(file(home, "secrets.json"));
+    if (!s)
+        throw new Error(`No keys found in ${home}. Run "upoch init" in your own terminal.`);
+    return s;
+}
+export function saveSecrets(s, home = upochHome()) {
+    mkdirSync(home, { recursive: true });
+    writeJson(file(home, "secrets.json"), s, true);
+}
+export function newSecrets(ipfsAuthorization) {
+    return { ownerKey: generatePrivateKey(), executorKey: generatePrivateKey(), encryptionKey: randomBytes(32).toString("hex"), ...(ipfsAuthorization ? { ipfsAuthorization } : {}) };
+}
+export function loadSession(home = upochHome()) {
+    return readJson(file(home, "session.json")) ?? {};
+}
+export function saveSession(s, home = upochHome()) {
+    writeJson(file(home, "session.json"), s);
+}
+export const journalPath = (home = upochHome()) => file(home, "journal.jsonl");
+export function hasSetup(home = upochHome()) {
+    return existsSync(file(home, "config.json")) && existsSync(file(home, "secrets.json"));
+}
+export function networkInfo(c) {
+    if (c.network === "mainnet")
+        return { ...ROBINHOOD_MAINNET, debuggerUrl: (id) => `https://upoch.tech/app/agents/${id}/debugger` };
+    if (c.network === "testnet")
+        return { ...ROBINHOOD_TESTNET };
+    if (!c.custom)
+        throw new Error('config.json: network "custom" needs a "custom" section');
+    return { name: "Custom chain", chainId: c.custom.chainId, ledger: c.custom.ledger.toLowerCase(), rpcUrl: c.custom.rpcUrl, startBlock: BigInt(c.custom.startBlock ?? "0") };
+}

package/dist/guard.d.ts

@@ -0,0 +1,123 @@
+import { LocalKeySigner, type Eip1193Provider } 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";
+/** 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;
+    constructor(code: string, message: string);
+}
+export interface GuardOptions {
+    home?: string;
+    /** Overrides the RPC provider (tests). */
+    provider?: Eip1193Provider;
+    now?: () => Date;
+}
+export declare class Guard {
+    readonly home: string;
+    readonly config: UpochConfig;
+    readonly network: NetworkInfo;
+    readonly executor: LocalKeySigner;
+    readonly ownerAddress: `0x${string}`;
+    private readonly provider;
+    private readonly reader;
+    private readonly journal;
+    private readonly now;
+    private readonly principal;
+    private parts?;
+    constructor(o?: GuardOptions);
+    private readonly build;
+    private get p();
+    private get workflowId();
+    private session;
+    private today;
+    private openExecution;
+    /** Workflow, executor funds, the open execution and today's usage. Read-only. */
+    status(): Promise<{
+        workflow: null;
+        next: string;
+        network: string;
+        chainId: number;
+        contract: `0x${string}`;
+        agentId: string;
+        executor: `0x${string}`;
+        executorBalanceEth: string;
+        checkpointsToday: string;
+        openExecution: string | null;
+        storage: string;
+    } | {
+        debugger?: string | undefined;
+        workflow: {
+            id: string;
+            status: import("@upoch/sdk").WorkflowStatus;
+            checkpoints: string;
+            headSequence: string | null;
+            headHash: `0x${string}` | null;
+        };
+        network: string;
+        chainId: number;
+        contract: `0x${string}`;
+        agentId: string;
+        executor: `0x${string}`;
+        executorBalanceEth: string;
+        checkpointsToday: string;
+        openExecution: string | null;
+        storage: string;
+    }>;
+    /** Commits a verified checkpoint of `state`. Refuses state that looks like it holds secrets. */
+    checkpoint(input: {
+        state: unknown;
+        note?: string;
+        kind?: CheckpointKind;
+    }, 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: {
+        operationId: string;
+        type: string;
+        status: ActionStatus;
+        transactionHash?: string;
+        input?: unknown;
+        result?: unknown;
+    }): Promise<{
+        recorded: boolean;
+        operationId: string;
+        status: ActionStatus;
+        executionId: string;
+        note: string;
+    }>;
+    /**
+     * Restores the latest verified checkpoint (or `sequence`): checks it against the chain, decrypts it and
+     * reconciles recorded actions. Continues that execution when it was still running.
+     */
+    restore(o?: {
+        sequence?: number;
+    }): Promise<any>;
+    /**
+     * Rolls the agent back to an earlier checkpoint and continues from it: verifies that checkpoint, then commits its
+     * state again as a new MANUAL checkpoint ("rolled back to #n"), so every later restore starts from it. The run
+     * continues as a new execution. On-chain effects since then (trades, transfers) are not undone; they are listed so
+     * the agent can account for them.
+     */
+    rollback(o: {
+        sequence: number;
+        reason: string;
+        annotate?: (state: unknown, actionsSince: {
+            operationId: string;
+            status: string;
+            transactionHash?: string;
+        }[]) => unknown;
+    }): Promise<any>;
+    /** The most recent checkpoints on-chain, newest first. Read-only. */
+    history(o?: {
+        limit?: number;
+    }): Promise<any>;
+    /** Independently verifies one checkpoint without restoring it. Read-only. */
+    verify(o: {
+        sequence: number;
+    }): Promise<any>;
+    /** Final checkpoint marking the run finished; the next checkpoint starts a new execution. */
+    complete(input: {
+        state: unknown;
+        note?: string;
+    }): Promise<any>;
+}