@upoch/guard 0.0.0-stage → 0.1.1

package/dist/guard.js

@@ -0,0 +1,332 @@
+// Upoch Guard: the checkpoint, journal and recovery operations an agent framework calls (MCP tools now,
+// framework plugins later). One open execution at a time, kept in session.json so it survives restarts of the
+// MCP client. Every checkpoint is verified after commit: retrieved, decrypted and hashed against the chain.
+import { randomBytes } from "node:crypto";
+import { ActionGate, CheckpointManager, EpochReader, FileJournal, IpfsStorageAdapter, LocalAesGcmProvider, LocalKeySigner, LocalStorageAdapter, RecoveryCoordinator, ReplicatedStorage, RpcCheckpointChain, StateSerializer, canonicalBytes, httpProvider, isEpochError, keccak256, } from "@upoch/sdk";
+import { journalPath, loadConfig, loadSecrets, loadSession, networkInfo, saveSession, upochHome } from "./config.js";
+import { findSecrets } from "./secrets-scan.js";
+/** Gas one checkpoint uses on Robinhood Chain, with headroom (measured: about 180k). */
+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" };
+/** A refusal the agent can act on (wrong input, a limit, missing funds). Distinct from unexpected failures. */
+export class GuardError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+const bigintSafe = (v) => JSON.parse(JSON.stringify(v, (_k, x) => (typeof x === "bigint" ? x.toString() : x)));
+export class Guard {
+    home;
+    config;
+    network;
+    executor;
+    ownerAddress;
+    provider;
+    reader;
+    journal;
+    now;
+    principal;
+    parts;
+    constructor(o = {}) {
+        this.home = o.home ?? upochHome();
+        this.config = loadConfig(this.home);
+        const secrets = loadSecrets(this.home);
+        this.network = networkInfo(this.config);
+        this.provider = o.provider ?? httpProvider(this.network.rpcUrl, { timeoutMs: 60_000 });
+        this.executor = new LocalKeySigner(secrets.executorKey, this.provider);
+        this.ownerAddress = new LocalKeySigner(secrets.ownerKey, this.provider).address;
+        this.reader = new EpochReader(this.provider, this.network.ledger);
+        this.journal = new FileJournal(journalPath(this.home));
+        this.now = o.now ?? (() => new Date());
+        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 = () => {
+            if (!this.config.workflowId)
+                throw new GuardError("NOT_REGISTERED", 'No workflow is registered yet. Run "upoch register" in your own terminal.');
+            const workflowId = BigInt(this.config.workflowId);
+            const chain = new RpcCheckpointChain({ provider: this.provider, ledger: this.network.ledger, workflowId, sender: this.executor, fromBlock: this.network.startBlock, pollMs: 1500, confirmationTimeoutMs: 240_000 });
+            const s = this.config.storage;
+            const storage = new ReplicatedStorage([
+                s.kind === "ipfs"
+                    ? new IpfsStorageAdapter({ apiUrl: s.apiUrl, gatewayUrl: s.gatewayUrl, authorization: secrets.ipfsAuthorization })
+                    : new LocalStorageAdapter(s.dir),
+            ]);
+            const encryption = new LocalAesGcmProvider(Buffer.from(secrets.encryptionKey, "hex"));
+            const serializer = new StateSerializer({ applicationVersion: `upoch-guard/${this.config.agentId}`, schemaVersion: 1 });
+            const gate = new ActionGate({ journal: this.journal });
+            const coordinator = new RecoveryCoordinator({ agentId: this.config.agentId, chain, storage, encryption, serializer, journal: this.journal, gate });
+            const manager = new CheckpointManager({
+                agentId: this.config.agentId, chain, storage, encryption, serializer,
+                policy: { checkpointPolicy: { afterConfirmedAction: true, beforeExternalAction: true, everySteps: 0 }, failurePolicy: "halt", partialEffects: "keep" },
+                model: { provider: "mcp", id: "agent-reported" },
+                verify: async (seq) => void (await coordinator.verifyCheckpoint(seq, this.principal)),
+            });
+            return { chain, coordinator, manager };
+        };
+    }
+    build;
+    get p() {
+        return (this.parts ??= this.build());
+    }
+    get workflowId() {
+        if (!this.config.workflowId)
+            throw new GuardError("NOT_REGISTERED", 'No workflow is registered yet. Run "upoch register" in your own terminal.');
+        return BigInt(this.config.workflowId);
+    }
+    session() {
+        return loadSession(this.home);
+    }
+    today() {
+        return this.now().toISOString().slice(0, 10);
+    }
+    openExecution() {
+        const s = this.session();
+        if (s.executionId)
+            return { executionId: s.executionId, nextSequence: s.nextSequence ?? 0 };
+        const fresh = { executionId: `exec_${randomBytes(12).toString("hex")}`, nextSequence: 0 };
+        saveSession({ ...s, ...fresh }, this.home);
+        return fresh;
+    }
+    /** Workflow, executor funds, the open execution and today's usage. Read-only. */
+    async status() {
+        const balance = BigInt((await this.provider.request({ method: "eth_getBalance", params: [this.executor.address, "latest"] })));
+        const s = this.session();
+        const usedToday = s.day === this.today() ? (s.checkpointsToday ?? 0) : 0;
+        const base = {
+            network: this.network.name,
+            chainId: this.network.chainId,
+            contract: this.network.ledger,
+            agentId: this.config.agentId,
+            executor: this.executor.address,
+            executorBalanceEth: (Number(balance) / 1e18).toFixed(8),
+            checkpointsToday: `${usedToday} of ${this.config.maxCheckpointsPerDay}`,
+            openExecution: s.executionId ?? null,
+            storage: this.config.storage.kind === "ipfs" ? "IPFS" : "local folder (development only)",
+        };
+        if (!this.config.workflowId)
+            return { ...base, workflow: null, next: 'Run "upoch register" in your own terminal.' };
+        const w = await this.reader.getWorkflow(this.workflowId);
+        return {
+            ...base,
+            workflow: {
+                id: this.config.workflowId,
+                status: w.status,
+                checkpoints: w.checkpointCount.toString(),
+                headSequence: w.checkpointCount > 0n ? w.headSequence.toString() : null,
+                headHash: w.checkpointCount > 0n ? w.headHash : null,
+            },
+            ...(this.network.debuggerUrl ? { debugger: this.network.debuggerUrl(this.config.workflowId) } : {}),
+        };
+    }
+    /** Commits a verified checkpoint of `state`. Refuses state that looks like it holds secrets. */
+    async checkpoint(input, executionStatus = "RUNNING") {
+        const found = findSecrets(input.state);
+        if (found.length > 0)
+            throw new GuardError("SECRET_IN_STATE", `Refused: the state looks like it contains secrets at ${found.slice(0, 5).join(", ")}. Remove keys, seed phrases, passwords and tokens from the state; checkpoints are permanent.`);
+        if (input.note && findSecrets({ note: input.note }).length > 0)
+            throw new GuardError("SECRET_IN_STATE", "Refused: the note looks like it contains a secret.");
+        const s = this.session();
+        const day = this.today();
+        const used = s.day === day ? (s.checkpointsToday ?? 0) : 0;
+        const cap = loadConfig(this.home).maxCheckpointsPerDay; // re-read: the owner can change it without a restart
+        if (used >= cap)
+            throw new GuardError("DAILY_LIMIT", `Daily limit reached: ${used} of ${cap} checkpoints today (UTC). The owner can raise maxCheckpointsPerDay in ${this.home}/config.json.`);
+        const gasPrice = BigInt((await this.provider.request({ method: "eth_gasPrice", params: [] })));
+        const balance = BigInt((await this.provider.request({ method: "eth_getBalance", params: [this.executor.address, "latest"] })));
+        if (balance < CHECKPOINT_GAS * gasPrice)
+            throw new GuardError("LOW_FUNDS", `The executor ${this.executor.address} has too little ETH for a checkpoint on ${this.network.name}. Ask the owner to send it a little ETH.`);
+        const exec = this.openExecution();
+        const actions = (await this.journal.list(exec.executionId)).map((r) => ({
+            operationId: r.operationId,
+            status: r.status,
+            ...(r.transactionHash ? { transactionHash: r.transactionHash } : {}),
+            ...(r.resultCommitment ? { resultHash: r.resultCommitment } : {}),
+        }));
+        const rec = await this.p.manager.create({
+            executionId: exec.executionId,
+            checkpointSequence: exec.nextSequence,
+            checkpointType: TYPES[input.kind ?? "progress"],
+            state: input.state,
+            context: input.note ? { note: input.note } : {},
+            actions,
+            executionStatus,
+        });
+        const committed = rec.status === "COMMITTED" || rec.status === "VERIFIED_RECOVERY_POINT";
+        if (committed) {
+            const after = this.session();
+            saveSession(executionStatus === "COMPLETED"
+                ? { day, checkpointsToday: used + 1 }
+                : { ...after, executionId: exec.executionId, nextSequence: exec.nextSequence + 1, day, checkpointsToday: used + 1 }, this.home);
+        }
+        return bigintSafe({
+            status: rec.status,
+            verified: rec.status === "VERIFIED_RECOVERY_POINT",
+            sequence: rec.sequence,
+            checkpointId: rec.checkpointId,
+            transactionHash: rec.transactionHash,
+            executionId: exec.executionId,
+            executionStatus,
+            ...(rec.error ? { error: rec.error } : {}),
+        });
+    }
+    /** Records an external action (a swap, a transfer, an API call) so the next checkpoint and any recovery know about it. */
+    async recordAction(a) {
+        if (!/^[A-Za-z0-9._:-]{1,128}$/.test(a.operationId))
+            throw new GuardError("INVALID_ARGUMENT", "operationId must be 1–128 characters: letters, digits, . _ : -");
+        if (a.transactionHash && !HASH.test(a.transactionHash))
+            throw new GuardError("INVALID_ARGUMENT", "transactionHash must be 0x followed by 64 hex digits");
+        const found = [...findSecrets(a.input ?? null), ...findSecrets(a.result ?? null)];
+        if (found.length > 0)
+            throw new GuardError("SECRET_IN_STATE", `Refused: the action looks like it contains secrets at ${found.slice(0, 5).join(", ")}.`);
+        const exec = this.openExecution();
+        const prev = await this.journal.get(a.operationId);
+        if (prev && prev.executionId !== exec.executionId)
+            throw new GuardError("INVALID_ARGUMENT", `operationId ${a.operationId} was already used in another execution; use a new one.`);
+        if (prev?.status === "CONFIRMED" && a.status !== "confirmed")
+            throw new GuardError("INVALID_ARGUMENT", `${a.operationId} is already confirmed; a confirmed action cannot change status.`);
+        const rec = {
+            operationId: a.operationId,
+            executionId: exec.executionId,
+            operationType: a.type,
+            inputCommitment: prev?.inputCommitment ?? keccak256(canonicalBytes((a.input ?? {}))),
+            attempt: prev?.attempt ?? 1,
+            status: STATUSES[a.status],
+            ...(a.transactionHash ? { transactionHash: a.transactionHash.toLowerCase() } : prev?.transactionHash ? { transactionHash: prev.transactionHash } : {}),
+            ...(a.result !== undefined ? { result: a.result, resultCommitment: keccak256(canonicalBytes(a.result)) } : {}),
+            compensation: "NONE",
+            updatedAt: this.now().getTime(),
+        };
+        await this.journal.put(rec);
+        return { recorded: true, operationId: a.operationId, status: a.status, executionId: exec.executionId, note: "Saved locally. The next checkpoint puts it on-chain." };
+    }
+    /**
+     * 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.
+     */
+    async restore(o = {}) {
+        const w = await this.reader.getWorkflow(this.workflowId);
+        if (w.checkpointCount === 0n)
+            return { status: "NOTHING_TO_RESTORE", message: "This workflow has no checkpoints yet. Start fresh." };
+        const r = await this.p.coordinator.recover({ principal: this.principal, ...(o.sequence !== undefined ? { sequence: BigInt(o.sequence) } : {}), partialEffects: "keep" });
+        if (r.status === "FAILED" || !r.checkpoint)
+            return bigintSafe({ status: "FAILED", error: r.error });
+        const cp = r.checkpoint;
+        const isHead = cp.sequence === w.headSequence;
+        if (isHead) {
+            const s = this.session();
+            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;
+        return bigintSafe({
+            status: r.status,
+            sequence: cp.sequence,
+            checkpointId: cp.checkpointId,
+            executionId: cp.manifest.executionId,
+            executionStatus: cp.executionStatus,
+            checkpointType: cp.manifest.checkpointType,
+            state: cp.state,
+            ...(typeof note === "string" ? { note } : {}),
+            actions: cp.manifest.actions,
+            completedActions: r.completed.map((c) => c.operationId),
+            unresolvedActions: r.unresolved,
+            ...(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."
+                    : "That run had finished. A new checkpoint starts a new run.",
+        });
+    }
+    /**
+     * 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.
+     */
+    async rollback(o) {
+        if (!o.reason?.trim())
+            throw new GuardError("INVALID_ARGUMENT", "Give a short reason for the rollback; it is saved in the checkpoint.");
+        const w = await this.reader.getWorkflow(this.workflowId);
+        if (w.checkpointCount === 0n)
+            throw new GuardError("NOTHING_TO_RESTORE", "This workflow has no checkpoints yet.");
+        const target = BigInt(o.sequence);
+        if (target >= w.checkpointCount)
+            throw new GuardError("CHECKPOINT_NOT_FOUND", `There is no checkpoint #${o.sequence}; the latest is #${w.headSequence}.`);
+        if (target === w.headSequence)
+            throw new GuardError("INVALID_ARGUMENT", `#${o.sequence} is already the latest checkpoint; use upoch_restore.`);
+        if (!(await this.p.coordinator.isCanonical(target)))
+            throw new GuardError("INVALID_CHECKPOINT_LINEAGE", `#${o.sequence} is not on this agent's current history.`);
+        let cp, head;
+        try {
+            [cp, head] = [await this.p.coordinator.verifyCheckpoint(target, this.principal), await this.p.coordinator.verifyCheckpoint(w.headSequence, this.principal)];
+        }
+        catch (e) {
+            if (isEpochError(e))
+                throw new GuardError(e.code, `Cannot roll back: ${e.message}`);
+            throw e;
+        }
+        // Actions that settled after the target: rolling back the agent's memory does not reverse them.
+        const settledThen = new Set(cp.manifest.actions.filter((a) => a.status === "CONFIRMED").map((a) => a.operationId));
+        const since = new Map();
+        for (const a of [...head.manifest.actions, ...(await this.journal.list(head.manifest.executionId)).map((r) => ({ operationId: r.operationId, status: r.status, ...(r.transactionHash ? { transactionHash: r.transactionHash } : {}) }))]) {
+            if (!settledThen.has(a.operationId))
+                since.set(a.operationId, a);
+        }
+        // Start a new execution from the restored state, then make it the head.
+        const s = this.session();
+        saveSession({ day: s.day, checkpointsToday: s.checkpointsToday }, this.home);
+        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" });
+        if (committed.status !== "VERIFIED_RECOVERY_POINT" && committed.status !== "COMMITTED")
+            return { ...committed, rolledBackTo: o.sequence, state: undefined };
+        return bigintSafe({
+            status: "ROLLED_BACK",
+            rolledBackTo: cp.sequence,
+            newCheckpoint: committed.sequence,
+            transactionHash: committed.transactionHash,
+            executionId: committed.executionId,
+            state,
+            actionsSince,
+            next: actionsSince.length > 0
+                ? "Continue from this state. These actions happened after that checkpoint and were NOT undone on-chain: check their effects (balances, positions) before acting."
+                : "Continue from this state.",
+        });
+    }
+    /** The most recent checkpoints on-chain, newest first. Read-only. */
+    async history(o = {}) {
+        const w = await this.reader.getWorkflow(this.workflowId);
+        const total = w.checkpointCount;
+        const limit = BigInt(Math.min(Math.max(o.limit ?? 10, 1), 50));
+        const start = total > limit ? total - limit : 0n;
+        const rows = total === 0n ? [] : await this.reader.getCheckpoints(this.workflowId, start, total - start);
+        return bigintSafe({
+            workflowId: this.config.workflowId,
+            total,
+            checkpoints: rows
+                .map((c, i) => ({ sequence: start + BigInt(i), checkpointId: c.checkpointHash, parentSequence: c.parentHash === "0x" + "0".repeat(64) ? null : c.parentSequence, submitter: c.submitter, time: new Date(Number(c.timestamp) * 1000).toISOString(), head: start + BigInt(i) === w.headSequence }))
+                .reverse(),
+        });
+    }
+    /** Independently verifies one checkpoint without restoring it. Read-only. */
+    async verify(o) {
+        try {
+            const cp = await this.p.coordinator.verifyCheckpoint(BigInt(o.sequence), this.principal);
+            return bigintSafe({ ok: true, sequence: cp.sequence, checkpointId: cp.checkpointId, executionId: cp.manifest.executionId, checkpointType: cp.manifest.checkpointType, executionStatus: cp.executionStatus, actions: cp.manifest.actions.length, checks: "lineage, locator digest, manifest digest, payload digest, decryption, state hash and context hash all match" });
+        }
+        catch (e) {
+            if (isEpochError(e))
+                return { ok: false, code: e.code, message: e.message };
+            throw e;
+        }
+    }
+    /** Final checkpoint marking the run finished; the next checkpoint starts a new execution. */
+    async complete(input) {
+        return this.checkpoint({ ...input, kind: "progress" }, "COMPLETED");
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/** Upoch Guard: checkpoint and recovery tools for any AI agent, as an MCP server or as a library for plugins. */
+export { Guard, GuardError, type ActionStatus, type CheckpointKind, type GuardOptions } from "./guard.ts";
+export { createServer, INSTRUCTIONS, VERSION } from "./server.ts";
+export { initialize, register, registrationPlan, type InitOptions } from "./setup.ts";
+export { upochHome, loadConfig, type UpochConfig, type StorageConfig, type NetworkName } from "./config.ts";
+export { findSecrets } from "./secrets-scan.ts";

package/dist/index.js

@@ -0,0 +1,6 @@
+/** Upoch Guard: checkpoint and recovery tools for any AI agent, as an MCP server or as a library for plugins. */
+export { Guard, GuardError } from "./guard.js";
+export { createServer, INSTRUCTIONS, VERSION } from "./server.js";
+export { initialize, register, registrationPlan } from "./setup.js";
+export { upochHome, loadConfig } from "./config.js";
+export { findSecrets } from "./secrets-scan.js";

package/dist/secrets-scan.d.ts

@@ -0,0 +1,2 @@
+/** JSON paths whose values look like secrets (empty when none). */
+export declare function findSecrets(value: unknown): string[];

package/dist/secrets-scan.js

@@ -0,0 +1,45 @@
+// Refuses state that looks like it holds credentials before it becomes a permanent checkpoint. The same secret
+// rules as the debugger's security scan (web/src/lib/debugger/scan.ts); returns JSON paths only, never values.
+const SECRET_KEY = /(private[_-]?key|secret|seed|mnemonic|passw(or)?d|api[_-]?key|access[_-]?token|auth[_-]?token|bearer|credential)/i;
+const HEX32 = /^(0x)?[0-9a-fA-F]{64}$/;
+const API_KEYS = [
+    /\bsk-ant-[A-Za-z0-9_-]{20,}/,
+    /\bsk-(proj-)?[A-Za-z0-9_-]{32,}/,
+    /\bAKIA[0-9A-Z]{16}\b/,
+    /\bgh[pousr]_[A-Za-z0-9]{36,}\b/,
+    /\bxox[abpr]-[A-Za-z0-9-]{10,}/,
+    /\bAIza[0-9A-Za-z_-]{35}\b/,
+    /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/,
+    /-----BEGIN (RSA |EC |OPENSSH |)PRIVATE KEY-----/,
+];
+function looksLikeMnemonic(s) {
+    const words = s.trim().split(/\s+/);
+    return [12, 15, 18, 21, 24].includes(words.length) && words.every((w) => /^[a-z]{3,8}$/.test(w));
+}
+function walk(v, path, key, out) {
+    if (out.length >= 20)
+        return;
+    if (Array.isArray(v))
+        return v.forEach((x, i) => walk(x, `${path}[${i}]`, key, out));
+    if (v !== null && typeof v === "object") {
+        for (const [k, x] of Object.entries(v))
+            walk(x, path ? `${path}.${k}` : k, k, out);
+        return;
+    }
+    if (typeof v !== "string")
+        return;
+    const secret = (SECRET_KEY.test(key) && v.length >= 8) ||
+        (HEX32.test(v) && /key|priv|signer|wallet/i.test(key)) ||
+        looksLikeMnemonic(v) ||
+        API_KEYS.some((re) => re.test(v)) ||
+        /^https?:\/\/[^/\s:@]+:[^/\s@]+@/i.test(v) ||
+        /[?&](api[_-]?key|token|secret|access_token|key)=[^&\s]{8,}/i.test(v);
+    if (secret)
+        out.push(path || "(root)");
+}
+/** JSON paths whose values look like secrets (empty when none). */
+export function findSecrets(value) {
+    const out = [];
+    walk(value, "state", "", out);
+    return out;
+}

package/dist/server.d.ts

@@ -0,0 +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 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

@@ -0,0 +1,81 @@
+// The Upoch Guard MCP server: eight tools over a Guard. Read-only tools are marked so clients can run them
+// without asking; checkpoint and complete send one on-chain transaction each.
+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 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:
+- 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.
+- 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.
+- 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".
+- 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.
+- When the task is finished, call upoch_complete.
+
+Never 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.`;
+async function run(f) {
+    try {
+        return { content: [{ type: "text", text: JSON.stringify(await f(), null, 2) }] };
+    }
+    catch (e) {
+        const message = e instanceof GuardError ? `${e.code}: ${e.message}` : e instanceof Error ? e.message : String(e);
+        return { content: [{ type: "text", text: message }], isError: true };
+    }
+}
+const readOnly = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
+const writes = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true };
+export function createServer(guard) {
+    let g = typeof guard === "function" ? undefined : guard;
+    // Loaded on first use, so the server starts (and explains what to do) even before "upoch init".
+    const get = () => (g ??= guard());
+    const server = new McpServer({ name: "upoch", title: "Upoch Guard", version: VERSION }, { instructions: INSTRUCTIONS });
+    server.registerTool("upoch_status", { title: "Upoch status", description: "Shows the agent's Upoch workflow: network, checkpoint count and head, executor funds, the open run and today's checkpoint usage.", inputSchema: {}, annotations: readOnly }, () => run(() => get().status()));
+    server.registerTool("upoch_checkpoint", {
+        title: "Save a checkpoint",
+        description: "Saves the current state as an encrypted checkpoint (stored off-chain, committed on Robinhood Chain, then verified). Sends one transaction. Use after meaningful progress and before consequential actions.",
+        inputSchema: {
+            state: z.unknown().describe("Everything needed to continue the task from here, as JSON. No secrets."),
+            note: z.string().max(500).optional().describe("A short note on what just happened, shown in the debugger."),
+            kind: z.enum(["progress", "before_action", "after_action", "manual"]).optional().describe('Default "progress". Use "before_action" right before a consequential action.'),
+        },
+        annotations: writes,
+    }, ({ state, note, kind }) => run(() => get().checkpoint({ state: state ?? null, note, kind })));
+    server.registerTool("upoch_record_action", {
+        title: "Record an action",
+        description: "Records an external action (swap, transfer, API call) in the local journal, so the next checkpoint and any recovery know whether it happened. Record it as planned before it runs, then as confirmed or failed.",
+        inputSchema: {
+            operationId: z.string().describe("A unique id for this action, reused for each status update (e.g. swap-2026-11-05-1)."),
+            type: z.string().max(64).describe('What kind of action, e.g. "swap", "transfer", "deploy".'),
+            status: z.enum(["planned", "submitted", "confirmed", "failed"]),
+            transactionHash: z.string().optional().describe("The on-chain transaction hash, when there is one."),
+            input: z.unknown().optional().describe("The action's parameters, as JSON. No secrets."),
+            result: z.unknown().optional().describe("The outcome, as JSON, once known."),
+        },
+        annotations: { ...writes, openWorldHint: false },
+    }, (a) => run(() => get().recordAction(a)));
+    server.registerTool("upoch_restore", {
+        title: "Restore the last checkpoint",
+        description: "Restores the latest checkpoint after verifying it against the chain: returns its state, note and which recorded actions completed or are still unresolved. Call at the start of a task.",
+        inputSchema: { sequence: z.number().int().min(0).optional().describe("A specific checkpoint to read (default: the latest).") },
+        annotations: readOnly,
+    }, ({ sequence }) => run(() => get().restore({ sequence })));
+    server.registerTool("upoch_rollback", {
+        title: "Roll back to a checkpoint",
+        description: "Goes back to an earlier checkpoint and continues from it (for example after a bad trade or a bad prompt). Verifies it, saves it again as the latest checkpoint with your reason, and lists actions since then that were not undone on-chain. Sends one transaction.",
+        inputSchema: {
+            sequence: z.number().int().min(0).describe("The checkpoint to go back to (see upoch_history)."),
+            reason: z.string().min(1).max(300).describe("Why you are rolling back, saved in the checkpoint."),
+        },
+        annotations: writes,
+    }, ({ sequence, reason }) => run(() => get().rollback({ sequence, reason })));
+    server.registerTool("upoch_history", { title: "Checkpoint history", description: "Lists the most recent checkpoints on-chain, newest first.", inputSchema: { limit: z.number().int().min(1).max(50).optional() }, annotations: readOnly }, ({ limit }) => run(() => get().history({ limit })));
+    server.registerTool("upoch_verify", { title: "Verify a checkpoint", description: "Independently verifies one checkpoint (lineage, storage digests, decryption and state hash) without restoring it.", inputSchema: { sequence: z.number().int().min(0) }, annotations: readOnly }, ({ sequence }) => run(() => get().verify({ sequence })));
+    server.registerTool("upoch_complete", {
+        title: "Finish the run",
+        description: "Saves a final checkpoint marking the task finished, so the next start begins a new run instead of resuming. Sends one transaction.",
+        inputSchema: { state: z.unknown().describe("The final state, as JSON. No secrets."), note: z.string().max(500).optional() },
+        annotations: writes,
+    }, ({ state, note }) => run(() => get().complete({ state: state ?? null, note })));
+    return server;
+}

package/dist/setup.d.ts

@@ -0,0 +1,46 @@
+import { type Eip1193Provider } from "@upoch/sdk";
+import { type NetworkName, type StorageConfig, type UpochConfig } from "./config.ts";
+export interface InitOptions {
+    home?: string;
+    network: NetworkName;
+    custom?: UpochConfig["custom"];
+    agentName: string;
+    storage: StorageConfig;
+    ipfsAuthorization?: string;
+    maxCheckpointsPerDay?: number;
+}
+export declare function slug(name: string): string;
+/** Creates config.json and secrets.json. Never overwrites existing keys: losing them loses access to the checkpoints. */
+export declare function initialize(o: InitOptions): {
+    home: string;
+    owner: string;
+    executor: string;
+    agentId: string;
+};
+/** What registration will cost, for the confirmation prompt. */
+export declare function registrationPlan(o: {
+    home?: string;
+    fundEth: string;
+    provider?: Eip1193Provider;
+}): Promise<{
+    network: string;
+    owner: string;
+    executor: string;
+    balance: bigint;
+    gasPrice: bigint;
+    fund: bigint;
+    cost: bigint;
+    enough: boolean;
+}>;
+/** Registers the workflow from the owner key and sends `fundEth` to the executor for checkpoint gas. */
+export declare function register(o: {
+    home?: string;
+    fundEth: string;
+    provider?: Eip1193Provider;
+}): Promise<{
+    workflowId: string;
+    registerTx: `0x${string}`;
+    fundTx: `0x${string}` | undefined;
+    owner: `0x${string}`;
+    debugger: string | undefined;
+}>;

package/dist/setup.js

@@ -0,0 +1,113 @@
+// One-time setup the user runs in their own terminal: create keys, register a workflow, fund the executor.
+// The owner key registers and owns the workflow (it approves rollbacks); the executor key is the agent's and only
+// submits checkpoints. The contract requires them to be different accounts.
+import { EpochReader, httpProvider } from "@upoch/sdk";
+import { createPublicClient, createWalletClient, custom, decodeEventLog, defineChain, encodeFunctionData, parseAbi, parseEther } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { hasSetup, loadConfig, loadSecrets, networkInfo, newSecrets, saveConfig, saveSecrets, upochHome } from "./config.js";
+const ABI = parseAbi([
+    "function registerWorkflow(address[] executors, address[] guardians, (uint8 guardianThreshold, bool ownerApprovalRequired, uint32 ownerFallbackDelay, uint32 timelock, uint32 approvalWindow, uint32 executionWindow) policy, string metadataURI) returns (uint256)",
+    "event WorkflowRegistered(uint256 indexed workflowId, address indexed owner, string metadataURI)",
+]);
+/** Owner approval alone, no timelock: the simplest policy the contract accepts (no guardians needed). */
+const POLICY = { guardianThreshold: 0, ownerApprovalRequired: true, ownerFallbackDelay: 0, timelock: 0, approvalWindow: 86400, executionWindow: 86400 };
+const REGISTER_GAS = 400000n;
+const TRANSFER_GAS = 30000n;
+export function slug(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 48) || "agent";
+}
+/** Creates config.json and secrets.json. Never overwrites existing keys: losing them loses access to the checkpoints. */
+export function initialize(o) {
+    const home = o.home ?? upochHome();
+    if (hasSetup(home))
+        throw new Error(`Upoch is already set up in ${home}. Delete that folder only if you are sure you no longer need its keys.`);
+    if (o.storage.kind === "ipfs" && !o.storage.apiUrl)
+        throw new Error("IPFS storage needs an API URL");
+    if (o.storage.kind === "local" && !o.storage.dir)
+        throw new Error("local storage needs a folder");
+    const secrets = newSecrets(o.ipfsAuthorization);
+    const config = {
+        network: o.network,
+        ...(o.custom ? { custom: o.custom } : {}),
+        agentId: `${slug(o.agentName)}-${secrets.executorKey.slice(-6)}`,
+        agentName: o.agentName,
+        storage: o.storage,
+        maxCheckpointsPerDay: o.maxCheckpointsPerDay ?? 100,
+    };
+    saveSecrets(secrets, home);
+    saveConfig(config, home);
+    return { home, owner: privateKeyToAccount(secrets.ownerKey).address.toLowerCase(), executor: privateKeyToAccount(secrets.executorKey).address.toLowerCase(), agentId: config.agentId };
+}
+function clients(config, key, provider) {
+    const n = networkInfo(config);
+    const chain = defineChain({ id: n.chainId, name: n.name, nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 }, rpcUrls: { default: { http: [n.rpcUrl] } } });
+    const transport = custom(provider ?? httpProvider(n.rpcUrl, { timeoutMs: 60_000 }));
+    const account = privateKeyToAccount(key);
+    return { n, account, pub: createPublicClient({ chain, transport }), wallet: createWalletClient({ chain, transport, account }) };
+}
+function metadataURI(config) {
+    const json = JSON.stringify({ name: config.agentName, agentType: "AI agent (Upoch Guard)", description: `Checkpointed with Upoch Guard. Agent id ${config.agentId}.` });
+    const uri = `data:application/json;base64,${Buffer.from(json).toString("base64")}`;
+    if (uri.length > 512)
+        throw new Error("the agent name is too long for the on-chain metadata (512 bytes)");
+    return uri;
+}
+/** What registration will cost, for the confirmation prompt. */
+export async function registrationPlan(o) {
+    const home = o.home ?? upochHome();
+    const config = loadConfig(home);
+    if (config.workflowId)
+        throw new Error(`Already registered as workflow #${config.workflowId}.`);
+    const secrets = loadSecrets(home);
+    const { n, account, pub } = clients(config, secrets.ownerKey, o.provider);
+    const chainId = await pub.getChainId();
+    if (chainId !== n.chainId)
+        throw new Error(`The RPC is chain ${chainId}, expected ${n.chainId}`);
+    const [balance, gasPrice] = await Promise.all([pub.getBalance({ address: account.address }), pub.getGasPrice()]);
+    const fund = parseEther(o.fundEth);
+    const cost = (REGISTER_GAS + (fund > 0n ? TRANSFER_GAS : 0n)) * gasPrice + fund;
+    return { network: n.name, owner: account.address.toLowerCase(), executor: privateKeyToAccount(secrets.executorKey).address.toLowerCase(), balance, gasPrice, fund, cost, enough: balance >= cost };
+}
+/** Registers the workflow from the owner key and sends `fundEth` to the executor for checkpoint gas. */
+export async function register(o) {
+    const home = o.home ?? upochHome();
+    const config = loadConfig(home);
+    if (config.workflowId)
+        throw new Error(`Already registered as workflow #${config.workflowId}.`);
+    const secrets = loadSecrets(home);
+    const { n, pub, wallet } = clients(config, secrets.ownerKey, o.provider);
+    const executor = privateKeyToAccount(secrets.executorKey).address;
+    const data = encodeFunctionData({ abi: ABI, functionName: "registerWorkflow", args: [[executor], [], POLICY, metadataURI(config)] });
+    await pub.call({ account: wallet.account, to: n.ledger, data }); // simulate first: a rejection sends nothing
+    const hash = await wallet.sendTransaction({ to: n.ledger, data });
+    const receipt = await pub.waitForTransactionReceipt({ hash, timeout: 240_000 });
+    if (receipt.status !== "success")
+        throw new Error(`registration reverted: ${hash}`);
+    let workflowId;
+    for (const log of receipt.logs) {
+        if (log.address.toLowerCase() !== n.ledger)
+            continue;
+        try {
+            const ev = decodeEventLog({ abi: ABI, data: log.data, topics: log.topics });
+            if (ev.eventName === "WorkflowRegistered")
+                workflowId = ev.args.workflowId;
+        }
+        catch {
+            /* another event */
+        }
+    }
+    if (workflowId === undefined)
+        throw new Error(`no WorkflowRegistered event in ${hash}`);
+    config.workflowId = workflowId.toString();
+    saveConfig(config, home);
+    let fundTx;
+    const fund = parseEther(o.fundEth);
+    if (fund > 0n) {
+        fundTx = await wallet.sendTransaction({ to: executor, value: fund });
+        const r = await pub.waitForTransactionReceipt({ hash: fundTx, timeout: 240_000 });
+        if (r.status !== "success")
+            throw new Error(`funding the executor failed: ${fundTx}`);
+    }
+    const w = await new EpochReader(o.provider ?? httpProvider(n.rpcUrl), n.ledger).getWorkflow(workflowId);
+    return { workflowId: workflowId.toString(), registerTx: hash, fundTx, owner: w.owner, debugger: n.debuggerUrl?.(workflowId.toString()) };
+}