@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/node-agent-tool/README.md

@@ -0,0 +1,165 @@
+# Node agent tool on ic-reactor 4
+
+A command-line tool for ICRC-1 ledgers that a person or an AI agent runs:
+`whoami`, `info`, `balance`, `transfer`, `watch`, and a narrated `demo`. It is
+`@ic-reactor/core` outside React: one `createClient({ network, identity })` per
+run, direct calls, certified reads, the `QueryClient` in a long-running
+process, every failure read through `isReactorError` and its `kind`, and
+`mayHaveExecuted` after a write. Each scenario is one file whose header says
+which rule it shows. Node 22.18 or newer runs the TypeScript as it is; there is
+no build step and no CLI framework (`node:util`'s `parseArgs`).
+
+## Run it
+
+From the repository root, after `pnpm install` and `pnpm build`:
+
+```sh
+pnpm --filter node-agent-tool demo    # every way a transfer ends, in memory: no network, no funds
+cd examples/node-agent-tool
+node src/cli.ts info --ledger ckbtc   # mainnet, anonymous
+node src/cli.ts balance rkp4c-7iaaa-aaaaa-aaaca-cai --certified --json
+node src/cli.ts transfer rkp4c-7iaaa-aaaaa-aaaca-cai 1   # refused: exit 4, the write is never sent
+node src/cli.ts whoami --pem ~/.config/icp-agent-tool.pem   # see "Which identity" below
+node src/cli.ts watch rkp4c-7iaaa-aaaaa-aaaca-cai --interval 2000   # Ctrl-C stops
+node src/cli.ts --help
+pnpm test        # every scenario, on createTestClient(): no network
+pnpm typecheck
+pnpm gen:check   # fails if src/canisters/ is stale against icrc1.did
+```
+
+`pnpm --silent cli <command>` is `node src/cli.ts` without Node's
+type-stripping warning (and, with `--silent`, without pnpm's banner on
+stdout). `src/canisters/icrc1.ts` is generated from `icrc1.did` by `pnpm gen`
+(`meant gen`), committed, and never edited.
+
+## Which identity
+
+Give the tool, and any agent that runs it, an identity of its own that holds
+little and controls nothing, never your default identity or one that controls
+a canister. Keep its key outside the project, readable by you alone:
+
+```sh
+mkdir -p ~/.config
+# on a machine without a keyring, add --storage password
+(umask 077 && pnpm exec icp identity new agent-tool --output-seed ~/.config/icp-agent-tool.seed)
+(umask 077 && pnpm exec icp identity export agent-tool > ~/.config/icp-agent-tool.pem)
+```
+
+Without `--output-seed`, `icp identity new` prints the identity's seed phrase,
+and an agent that runs the command keeps it in its context. Run these yourself,
+not through an agent. Each subshell's `umask 077` creates its file readable by
+you alone from the start.
+
+A key exported into the project is one `git add .` away from being published;
+the example's `.gitignore` ignores `*.pem`, but a copy of the example made
+another way may not. An agent's process can read its own environment, so
+`NODE_AGENT_TOOL_SEED` is no more private from the agent than a key file it
+can open: whatever the tool can sign with, the agent can too. That variable is
+a raw Ed25519 seed in hex, not an icp-cli identity or seed phrase; for the
+identity above, pass `--pem`.
+
+## Scenarios
+
+| Scenario                                                                                                                                                                                                                               | File                                              | See it                                                                            | Tests                                                                                 |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| 1. **Identity**: `--pem` (Ed25519 or secp256k1, dfx's form too), else the hex seed in `NODE_AGENT_TOOL_SEED`, else `identity: "anonymous"`, whose writes the client refuses                                                            | `src/identity.ts`, `src/commands/whoami.ts`       | `whoami`, `whoami --pem <file>`, an anonymous `transfer`                          | `src/identity.test.ts`                                                                |
+| 2. **Networks**: `--network ic\|local\|<url>`; a root key is fetched only from this machine, a remote URL needs `--root-key <hex>`                                                                                                     | `src/network.ts`                                  | `info --network https://example.org` (refused), `--network http://127.0.0.1:8001` | `src/network.test.ts`                                                                 |
+| 3. **Many ledgers, one interface**: `--ledger icp\|ckbtc\|cketh\|<id>`, each `client.canister<Actor>(actor, { id })`                                                                                                                   | `src/ledgers.ts`                                  | `info --ledger cketh`                                                             | `src/ledgers.test.ts`                                                                 |
+| 4. **Direct calls**: `info` (five reads in parallel) and `balance`; `--certified` reads through `{ id, certified: true }` and says which reads were certified                                                                          | `src/commands/info.ts`, `src/commands/balance.ts` | `info --certified`, `balance <p> --certified`                                     | `src/commands/reads.test.ts`                                                          |
+| 5. **Writes**: `parseUnits` at the ledger's decimals, its fee, `created_at_time`; a `kind` switch with an exit code per kind; after `mayHaveExecuted`, a re-read and the exact same-argument re-send (`--resend-unknown` does it once) | `src/commands/transfer.ts`, `src/failure.ts`      | `pnpm demo`, steps 2 to 10                                                        | `src/commands/transfer.test.ts`, `src/commands/resend.test.ts`, `src/failure.test.ts` |
+| 6. **JSON for agents**: `--json` on every command, one stable shape                                                                                                                                                                    | `src/output.ts`                                   | any command with `--json`                                                         | `src/output.test.ts`                                                                  |
+| 7. **The cache outside React**: `watch` reads through `client.queryClient.fetchQuery(client.queryOptions(...))`, invalidates the balance alone each interval, prints only changes, disposes the client on Ctrl-C                       | `src/commands/watch.ts`                           | `watch <p>`                                                                       | `src/commands/watch.test.ts`                                                          |
+| 8. **Every failure, narrated**: `demo` runs the commands above on `createTestClient()` with a mocked ledger, arms one failure per step, and shows what the replica saw                                                                 | `src/commands/demo.ts`, `src/mock-ledger.ts`      | `pnpm demo`, `pnpm demo --json`                                                   | `src/commands/demo.test.ts`, `src/cli.test.ts`                                        |
+
+`pnpm demo` walks through: a transfer; the ledger's `InsufficientFunds`; a
+lost reply (`outcome_unknown`), its re-read and printed re-send, which the
+ledger answers `Duplicate`; the same with `--resend-unknown`; an HTTP 429 the
+client re-sends by itself; reject code 4; a signed-out write; input refused
+before sending (`principal()`, `parseUnits`, and a `nat64` the client will not
+encode). It exits 1 if any step ends otherwise.
+
+## Exit codes
+
+| Code | `kind`            | `mayHaveExecuted` | What to do                                                                      |
+| ---- | ----------------- | ----------------- | ------------------------------------------------------------------------------- |
+| 0    |                   |                   | Done. A transfer the ledger answers `Duplicate` had gone through: also 0.       |
+| 1    | `unexpected`      | after a send: yes | A bug in the tool.                                                              |
+| 2    | `usage`           | no                | Bad flags or input, refused before any write was sent.                          |
+| 3    | `invalid_args`    | no                | The client could not encode the arguments; the write was not sent.              |
+| 4    | `unauthenticated` | no                | A write without a key: pass `--pem` or set `NODE_AGENT_TOOL_SEED`.              |
+| 5    | `not_delivered`   | no                | Refused before it got in (the client already re-sent where safe). Run it again. |
+| 6    | `outcome_unknown` | yes               | Run the printed re-send command, never a new transfer.                          |
+| 7    | `rejected`        | write, code 4/5   | Read `rejectCode`; when it may have executed, as for 6.                         |
+| 8    | `invalid_reply`   | a write: yes      | Not the ledger it should be, or as for 6 after a write.                         |
+| 9    | `canister_err`    | no                | The ledger's `Err` (`err.tag`): `InsufficientFunds`, `BadFee`, `TooOld`, ...    |
+| 10   | `cancelled`       | rarely            | The client was disposed or the call aborted.                                    |
+
+## JSON output
+
+With `--json`, stdout carries one JSON object per line (one per command; one
+per event for `watch` and `demo`), and nothing else. Every object has `ok` and
+`command`. A transfer that went through has `outcome` (`"sent"`, or
+`"duplicate"` when the ledger had it already), `block`, `resent`, and after a
+re-send `firstAttempt` (the first failure). A failure is
+`{ "ok": false, "command", "kind", "mayHaveExecuted", "message" }`, plus
+`code`, `rejectCode`, `httpStatus` when the `ReactorError` has them, and for a
+transfer `err` (the ledger's `Err`), `balance.before`/`after`, `resend` (the
+argv that re-sends the same argument) and `dedupUntil`. A transfer whose
+re-send failed also has `firstAttempt` and `resendAttempt` (each `kind`,
+`mayHaveExecuted`, `message`, `code`, `rejectCode` and `httpStatus` when the
+`ReactorError` has them, and `err` for an `Err`); its own `kind` and exit
+code are those of an attempt that may have executed. A bigint is a decimal
+string, bytes are hex, and an amount is `{ "units": "150000000", "tokens": "1.5" }`.
+`--help --json` is `{ "ok": true, "command": "help", "usage" }`. No message
+quotes `NODE_AGENT_TOOL_SEED`: a malformed seed is refused by what is wrong with
+it, since an agent feeds stdout back into its context.
+
+```text
+{"ok":true,"command":"balance","network":"ic","ledger":{"id":"ryjl3-tyaaa-aaaaa-aaaba-cai","name":"icp"},"account":{"owner":"rkp4c-7iaaa-aaaaa-aaaca-cai","subaccount":null},"balance":{"units":"3023466972","tokens":"30.23466972"},"symbol":"ICP","decimals":8,"reads":{"icrc1_balance_of":"certified","icrc1_decimals":"query","icrc1_symbol":"query"}}
+{"ok":false,"command":"balance","kind":"usage","mayHaveExecuted":false,"message":"owner \"x\" is not a principal (principal(): \"x\" is not canonical principal text)"}
+```
+
+## Text from the ledger
+
+A token's name and symbol and a ledger's error messages are the ledger's own
+text, and a terminal acts on some characters instead of showing them. Without
+`--json`, each control character and bidirectional formatting character is
+printed spelled out: an escape as `\u{1b}`, a line break as `\u{a}`, a
+right-to-left override as `\u{202e}`. A ledger can't move the cursor, rewrite
+earlier lines, add a line that looks like the tool's own or reverse an
+amount. With `--json` they are `\u` escapes, and the text parses back
+unchanged (`printable` and `stringify` in `src/output.ts`).
+
+## An unknown outcome, and the re-send
+
+ICRC-1 ledgers deduplicate: the same sender sending the same argument
+(`created_at_time` included) within about 24 hours gets
+`Duplicate { duplicate_of }` and moves nothing. So after `outcome_unknown` the
+tool never builds a new transfer: it reads the balance back and prints the
+command that sends the very same one (`--fee` and `--created-at-time` pinned,
+the same `--pem`). Run it: `Duplicate` means the first went through, a block
+index means it had not and now has. `--resend-unknown` does this once by
+itself. A re-send that does not go through (an HTTP 429 three times, a reject
+before the ledger ran it, an `Err` other than `Duplicate`) moved nothing, and
+that says nothing about the first attempt: the tool still reports the first
+attempt's unknown outcome and exit code, and prints the same re-send command.
+After the window the ledger answers `TooOld`, and only the balance or the
+ledger's history can tell.
+
+## A real local ledger
+
+`icp.yaml` starts an icp-cli network with the NNS (the ICP ledger at its
+mainnet id) on port 8001; icp-cli is a devDependency, pinned at 1.2.0.
+
+```sh
+pnpm exec icp network start -d
+pnpm exec icp token transfer 100 <your principal> --identity anonymous   # icp-cli seeds the anonymous account
+node src/cli.ts transfer <principal> 1.5 --pem ~/.config/icp-agent-tool.pem --network http://127.0.0.1:8001
+node src/cli.ts watch <principal> --network http://127.0.0.1:8001 --interval 1000
+pnpm exec icp network stop
+```
+
+Run the same `transfer` twice with one `--created-at-time` and the second
+answers `Duplicate`; `--fee 0.001` gives `BadFee`, an old `--created-at-time`
+`TooOld`. The client fetches this replica's root key because `127.0.0.1` is
+this machine; for any other host the tool asks for `--root-key`.

package/examples/node-agent-tool/icp.yaml

@@ -0,0 +1,11 @@
+# The optional local run of the README: an icp-cli network with the NNS
+# canisters, the ICP ledger among them, at its mainnet id. Gateway on 8001.
+networks:
+  - name: local
+    mode: managed
+    # The network launcher is pinned, as in e2e/icp.yaml: "latest" asks the
+    # GitHub API which release that is.
+    version: v16.0.0-2026-09-18-03-28
+    gateway:
+      port: 8001
+    nns: true

package/examples/node-agent-tool/icrc1.did

@@ -0,0 +1,88 @@
+type BlockIndex = nat;
+type Subaccount = blob;
+// Number of nanoseconds since the UNIX epoch in UTC timezone.
+type Timestamp = nat64;
+// Number of nanoseconds between two [Timestamp]s.
+type Duration = nat64;
+type Tokens = nat;
+
+type Account = record {
+    owner : principal;
+    subaccount : opt Subaccount;
+};
+
+type TransferArg = record {
+    from_subaccount : opt Subaccount;
+    to : Account;
+    amount : Tokens;
+    fee : opt Tokens;
+    memo : opt blob;
+    created_at_time: opt Timestamp;
+};
+
+type TransferError = variant {
+    BadFee : record { expected_fee : Tokens };
+    BadBurn : record { min_burn_amount : Tokens };
+    InsufficientFunds : record { balance : Tokens };
+    TooOld;
+    CreatedInFuture : record { ledger_time : nat64 };
+    TemporarilyUnavailable;
+    Duplicate : record { duplicate_of : BlockIndex };
+    GenericError : record { error_code : nat; message : text };
+};
+
+type TransferResult = variant {
+    Ok : BlockIndex;
+    Err : TransferError;
+};
+
+// The value returned from the [icrc1_metadata] endpoint.
+type Value = variant {
+    Nat : nat;
+    Int : int;
+    Text : text;
+    Blob : blob;
+};
+
+// The initialization parameters of the Ledger
+type InitArgs = record {
+    minting_account : Account;
+    transfer_fee : nat64;
+    token_symbol : text;
+    token_name : text;
+    metadata : vec record { text; Value };
+    initial_balances : vec record { Account; nat64 };
+    archive_options : record {
+        num_blocks_to_archive : nat64;
+        trigger_threshold : nat64;
+        max_message_size_bytes : opt nat64;
+        cycles_for_archive_creation : opt nat64;
+        node_max_memory_size_bytes : opt nat64;
+        controller_id : principal;
+    };
+};
+
+type UpgradeArgs = record {
+    metadata : opt vec record { text; Value };
+    token_symbol : opt text;
+    token_name : opt text;
+    transfer_fee : opt nat64;
+};
+
+type LedgerArg = variant {
+    Init: InitArgs;
+    Upgrade: opt UpgradeArgs;
+};
+
+service : (ledger_arg : LedgerArg) -> {
+    icrc1_name : () -> (text) query;
+    icrc1_symbol : () -> (text) query;
+    icrc1_decimals : () -> (nat8) query;
+    icrc1_metadata : () -> (vec record { text; Value }) query;
+    icrc1_total_supply : () -> (Tokens) query;
+    icrc1_fee : () -> (Tokens) query;
+    icrc1_minting_account : () -> (opt Account) query;
+    icrc1_balance_of : (Account) -> (Tokens) query;
+    icrc1_transfer : (TransferArg) -> (TransferResult);
+    icrc1_supported_standards : () -> (vec record { name : text; url : text }) query;
+}

package/examples/node-agent-tool/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "node-agent-tool",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "engines": {
+    "node": ">=22.18"
+  },
+  "scripts": {
+    "cli": "node --disable-warning=ExperimentalWarning src/cli.ts",
+    "demo": "node --disable-warning=ExperimentalWarning src/cli.ts demo",
+    "build": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "gen": "meant gen icrc1.did -o src/canisters",
+    "gen:check": "meant gen icrc1.did -o src/canisters --check"
+  },
+  "dependencies": {
+    "@meantjs/schema": "0.6.0",
+    "@ic-reactor/core": "^4.1.1",
+    "@icp-sdk/core": "^6.1.0",
+    "@noble/curves": "^2.2.0",
+    "@tanstack/query-core": "^5.102.8"
+  },
+  "devDependencies": {
+    "@meantjs/cli": "0.5.1",
+    "@icp-sdk/icp-cli": "1.2.0",
+    "@types/node": "^26.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.0"
+  }
+}