@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/node-agent-tool/src/canisters/icrc1.ts

@@ -0,0 +1,78 @@
+// Generated by Meant from a Meant Contract. Do not edit.
+import * as $ from "@meantjs/schema";
+
+export type Account = { owner: $.Principal; subaccount: Uint8Array | null };
+const $Account: $.Schema<Account> = $.c.rec(() => $.c.record({ owner: $.c.principal, subaccount: $.c.opt($.c.blob()) }));
+export { $Account as Account };
+
+export type BlockIndex = bigint;
+const $BlockIndex: $.Schema<BlockIndex> = $.c.rec(() => $.c.nat);
+export { $BlockIndex as BlockIndex };
+
+/** Number of nanoseconds between two [Timestamp]s. */
+export type Duration = bigint;
+/** Number of nanoseconds between two [Timestamp]s. */
+const $Duration: $.Schema<Duration> = $.c.rec(() => $.c.nat64);
+export { $Duration as Duration };
+
+/** The initialization parameters of the Ledger */
+export type InitArgs = { token_symbol: string; transfer_fee: bigint; metadata: Array<[string, Value]>; minting_account: Account; initial_balances: Array<[Account, bigint]>; archive_options: { num_blocks_to_archive: bigint; trigger_threshold: bigint; max_message_size_bytes: bigint | null; cycles_for_archive_creation: bigint | null; node_max_memory_size_bytes: bigint | null; controller_id: $.Principal }; token_name: string };
+/** The initialization parameters of the Ledger */
+const $InitArgs: $.Schema<InitArgs> = $.c.rec(() => $.c.record({ token_symbol: $.c.text, transfer_fee: $.c.nat64, metadata: $.c.vec($.c.tuple([$.c.text, $Value])), minting_account: $Account, initial_balances: $.c.vec($.c.tuple([$Account, $.c.nat64])), archive_options: $.c.record({ num_blocks_to_archive: $.c.nat64, trigger_threshold: $.c.nat64, max_message_size_bytes: $.c.opt($.c.nat64), cycles_for_archive_creation: $.c.opt($.c.nat64), node_max_memory_size_bytes: $.c.opt($.c.nat64), controller_id: $.c.principal }), token_name: $.c.text }));
+export { $InitArgs as InitArgs };
+
+export type LedgerArg = { tag: "Upgrade"; value: UpgradeArgs | null } | { tag: "Init"; value: InitArgs };
+const $LedgerArg: $.Schema<LedgerArg> = $.c.rec(() => $.c.variant({ Upgrade: $.c.opt($UpgradeArgs), Init: $InitArgs }));
+export { $LedgerArg as LedgerArg };
+
+export type Subaccount = Uint8Array;
+const $Subaccount: $.Schema<Subaccount> = $.c.rec(() => $.c.blob());
+export { $Subaccount as Subaccount };
+
+/** Number of nanoseconds since the UNIX epoch in UTC timezone. */
+export type Timestamp = bigint;
+/** Number of nanoseconds since the UNIX epoch in UTC timezone. */
+const $Timestamp: $.Schema<Timestamp> = $.c.rec(() => $.c.nat64);
+export { $Timestamp as Timestamp };
+
+export type Tokens = bigint;
+const $Tokens: $.Schema<Tokens> = $.c.rec(() => $.c.nat);
+export { $Tokens as Tokens };
+
+export type TransferArg = { to: Account; fee: bigint | null; memo: Uint8Array | null; from_subaccount: Uint8Array | null; created_at_time: bigint | null; amount: bigint };
+const $TransferArg: $.Schema<TransferArg> = $.c.rec(() => $.c.record({ to: $Account, fee: $.c.opt($.c.nat), memo: $.c.opt($.c.blob()), from_subaccount: $.c.opt($.c.blob()), created_at_time: $.c.opt($.c.nat64), amount: $.c.nat }));
+export { $TransferArg as TransferArg };
+
+export type TransferError = { tag: "GenericError"; value: { message: string; error_code: bigint } } | { tag: "TemporarilyUnavailable" } | { tag: "BadBurn"; value: { min_burn_amount: bigint } } | { tag: "Duplicate"; value: { duplicate_of: bigint } } | { tag: "BadFee"; value: { expected_fee: bigint } } | { tag: "CreatedInFuture"; value: { ledger_time: bigint } } | { tag: "TooOld" } | { tag: "InsufficientFunds"; value: { balance: bigint } };
+const $TransferError: $.Schema<TransferError> = $.c.rec(() => $.c.variant({ GenericError: $.c.record({ message: $.c.text, error_code: $.c.nat }), TemporarilyUnavailable: $.c.null, BadBurn: $.c.record({ min_burn_amount: $.c.nat }), Duplicate: $.c.record({ duplicate_of: $.c.nat }), BadFee: $.c.record({ expected_fee: $.c.nat }), CreatedInFuture: $.c.record({ ledger_time: $.c.nat64 }), TooOld: $.c.null, InsufficientFunds: $.c.record({ balance: $.c.nat }) }));
+export { $TransferError as TransferError };
+
+export type TransferResult = { tag: "Ok"; value: bigint } | { tag: "Err"; value: TransferError };
+const $TransferResult: $.Schema<TransferResult> = $.c.rec(() => $.c.variant({ Ok: $.c.nat, Err: $TransferError }));
+export { $TransferResult as TransferResult };
+
+export type UpgradeArgs = { token_symbol: string | null; transfer_fee: bigint | null; metadata: Array<[string, Value]> | null; token_name: string | null };
+const $UpgradeArgs: $.Schema<UpgradeArgs> = $.c.rec(() => $.c.record({ token_symbol: $.c.opt($.c.text), transfer_fee: $.c.opt($.c.nat64), metadata: $.c.opt($.c.vec($.c.tuple([$.c.text, $Value]))), token_name: $.c.opt($.c.text) }));
+export { $UpgradeArgs as UpgradeArgs };
+
+/** The value returned from the [icrc1_metadata] endpoint. */
+export type Value = { tag: "Int"; value: bigint } | { tag: "Nat"; value: bigint } | { tag: "Blob"; value: Uint8Array } | { tag: "Text"; value: string };
+/** The value returned from the [icrc1_metadata] endpoint. */
+const $Value: $.Schema<Value> = $.c.rec(() => $.c.variant({ Int: $.c.int, Nat: $.c.nat, Blob: $.c.blob(), Text: $.c.text }));
+export { $Value as Value };
+
+const $actor: $.Schema<$.Principal> = $.c.rec(() => $.c.service({ icrc1_balance_of: $.c.func([$Account], [$.c.nat], "query"), icrc1_decimals: $.c.func([], [$.c.nat8], "query"), icrc1_fee: $.c.func([], [$.c.nat], "query"), icrc1_supported_standards: $.c.func([], [$.c.vec($.c.record({ url: $.c.text, name: $.c.text }))], "query"), icrc1_metadata: $.c.func([], [$.c.vec($.c.tuple([$.c.text, $Value]))], "query"), icrc1_symbol: $.c.func([], [$.c.text], "query"), icrc1_minting_account: $.c.func([], [$.c.opt($Account)], "query"), icrc1_name: $.c.func([], [$.c.text], "query"), icrc1_total_supply: $.c.func([], [$.c.nat], "query"), icrc1_transfer: $.c.func([$TransferArg], [$TransferResult], "update") }));
+export type Actor = {
+  icrc1_balance_of: ((arg0: Account) => Promise<bigint>) & $.WithMode<"query">;
+  icrc1_decimals: (() => Promise<number>) & $.WithMode<"query">;
+  icrc1_fee: (() => Promise<bigint>) & $.WithMode<"query">;
+  icrc1_supported_standards: (() => Promise<Array<{ url: string; name: string }>>) & $.WithMode<"query">;
+  icrc1_metadata: (() => Promise<Array<[string, Value]>>) & $.WithMode<"query">;
+  icrc1_symbol: (() => Promise<string>) & $.WithMode<"query">;
+  icrc1_minting_account: (() => Promise<Account | null>) & $.WithMode<"query">;
+  icrc1_name: (() => Promise<string>) & $.WithMode<"query">;
+  icrc1_total_supply: (() => Promise<bigint>) & $.WithMode<"query">;
+  icrc1_transfer: ((arg0: TransferArg) => Promise<TransferResult>) & $.WithMode<"update">;
+};
+export { $actor as actor };
+// Note: the actor is a service class; init args are install-time metadata not exposed here (issue #104).

package/examples/node-agent-tool/src/cli.test.ts

@@ -0,0 +1,64 @@
+// src/cli.ts itself, run by Node the way a person or an agent runs it: the
+// arguments, the streams and the exit code. Only commands that need no
+// network run here (the others are tested through run() over the in-memory
+// replica).
+import { spawnSync } from "node:child_process"
+import { fileURLToPath } from "node:url"
+import { describe, expect, it } from "vitest"
+import { SEED_VARIABLE } from "./identity.ts"
+import { generatePem } from "./test-kit.ts"
+
+const CLI = fileURLToPath(new URL("./cli.ts", import.meta.url))
+
+function node(argv: readonly string[], env: Record<string, string> = {}) {
+  const result = spawnSync(
+    process.execPath,
+    ["--disable-warning=ExperimentalWarning", CLI, ...argv],
+    {
+      encoding: "utf8",
+      env: { PATH: process.env.PATH ?? "", ...env },
+      timeout: 60_000,
+    }
+  )
+  return {
+    status: result.status,
+    stdout: result.stdout.trim(),
+    stderr: result.stderr.trim(),
+  }
+}
+
+describe("node src/cli.ts", () => {
+  it("--help exits 0 with the usage", () => {
+    const result = node(["--help"])
+    expect(result.status).toBe(0)
+    expect(result.stdout).toMatch(
+      /^node-agent-tool: read and send ICRC-1 tokens/
+    )
+  })
+
+  it("whoami --json signs as the seed in the environment, with no network", () => {
+    const key = generatePem("ed25519")
+    const result = node(["whoami", "--json"], {
+      [SEED_VARIABLE]: Buffer.from(key.seed).toString("hex"),
+    })
+    expect(result.status).toBe(0)
+    expect(result.stderr).toBe("")
+    expect(JSON.parse(result.stdout)).toMatchObject({
+      ok: true,
+      principal: key.principal,
+      status: "signed-in",
+    })
+  })
+
+  it("exits 2 for an unknown command, with the reason on stderr", () => {
+    const result = node(["send", "1"])
+    expect(result.status).toBe(2)
+    expect(result.stderr).toMatch(/^error: usage: unknown command "send"/)
+  })
+
+  it("runs the demo to exit 0", () => {
+    const result = node(["demo"])
+    expect(result.status).toBe(0)
+    expect(result.stdout).toMatch(/demo: all 10 steps ended as expected\.$/)
+  })
+})

package/examples/node-agent-tool/src/cli.ts

@@ -0,0 +1,23 @@
+// The entry point: `node src/cli.ts <command> ...` (Node 22.18 or newer runs
+// the TypeScript as is). The only file that touches `process`: it hands the
+// arguments, the environment, the streams, the clock, Ctrl-C and the real
+// `createClient` to src/run.ts, and exits with the code it returns.
+import { readFileSync } from "node:fs"
+import { createClient } from "@ic-reactor/core"
+import { run } from "./run.ts"
+
+process.exitCode = await run({
+  argv: process.argv.slice(2),
+  env: process.env,
+  io: {
+    stdout: (line) => process.stdout.write(`${line}\n`),
+    stderr: (line) => process.stderr.write(`${line}\n`),
+  },
+  connect: createClient,
+  now: () => BigInt(Date.now()) * 1_000_000n,
+  readFile: (path) => readFileSync(path, "utf8"),
+  onInterrupt: (stop) => {
+    process.once("SIGINT", stop)
+    return () => process.off("SIGINT", stop)
+  },
+})

package/examples/node-agent-tool/src/command-line.ts

@@ -0,0 +1,159 @@
+// The command line: `node:util`'s parseArgs, one table of flags, and which
+// command takes which. No CLI framework: an agent reads the usage text below,
+// and a flag a command does not take is refused, never ignored.
+import { parseArgs } from "node:util"
+import { UsageError } from "./input.ts"
+
+const FLAGS = {
+  network: { type: "string" },
+  "root-key": { type: "string" },
+  ledger: { type: "string" },
+  pem: { type: "string" },
+  json: { type: "boolean" },
+  help: { type: "boolean", short: "h" },
+  certified: { type: "boolean" },
+  subaccount: { type: "string" },
+  "to-subaccount": { type: "string" },
+  "from-subaccount": { type: "string" },
+  memo: { type: "string" },
+  fee: { type: "string" },
+  "created-at-time": { type: "string" },
+  "resend-unknown": { type: "boolean" },
+  interval: { type: "string" },
+} as const
+
+export type Flag = keyof typeof FLAGS
+
+/** The values of the flags given; absent ones are missing. */
+export type Flags = {
+  readonly [F in Flag]?: (typeof FLAGS)[F]["type"] extends "string"
+    ? string
+    : boolean
+}
+
+/** The flags every command but `demo` takes. */
+const GLOBAL: readonly Flag[] = ["network", "root-key", "ledger", "pem", "json"]
+
+/** Each command: its positional arguments and its own flags. */
+export const COMMANDS = {
+  whoami: { args: [], flags: [...GLOBAL] },
+  info: { args: [], flags: [...GLOBAL, "certified"] },
+  balance: {
+    args: ["principal"],
+    flags: [...GLOBAL, "subaccount", "certified"],
+  },
+  transfer: {
+    args: ["to", "amount"],
+    flags: [
+      ...GLOBAL,
+      "to-subaccount",
+      "from-subaccount",
+      "memo",
+      "fee",
+      "created-at-time",
+      "resend-unknown",
+    ],
+  },
+  watch: { args: ["principal"], flags: [...GLOBAL, "subaccount", "interval"] },
+  demo: { args: [], flags: ["json"] },
+} as const satisfies Record<
+  string,
+  { args: readonly string[]; flags: readonly Flag[] }
+>
+
+export type CommandName = keyof typeof COMMANDS
+
+/** A parsed command line. */
+export type CommandLine =
+  | { readonly help: true; readonly json: boolean }
+  | {
+      readonly help: false
+      readonly command: CommandName
+      readonly args: readonly string[]
+      readonly flags: Flags
+      readonly json: boolean
+    }
+
+export const USAGE = `node-agent-tool: read and send ICRC-1 tokens from a terminal or an AI agent,
+on @ic-reactor/core.
+
+Usage: node src/cli.ts <command> [arguments] [flags]
+
+Commands
+  whoami                    the principal calls are signed as
+  info                      name, symbol, decimals, fee and total supply
+  balance <principal>       an account's balance
+  transfer <to> <amount>    send tokens; <amount> in tokens, such as 1.5
+  watch <principal>         print an account's balance when it changes, until Ctrl-C
+  demo                      every failure mode, on an in-memory replica (no network)
+
+Flags of every command but demo
+  --network ic|local|<url>  where the ledger runs (default: ic). A <url> that is
+                            not this machine needs --root-key <hex>
+  --ledger icp|ckbtc|cketh|<canister id>   which ICRC-1 ledger (default: icp)
+  --pem <file>              sign as this Ed25519 or secp256k1 key; else the seed in
+                            NODE_AGENT_TOOL_SEED; else anonymous, which only reads
+  --json                    one JSON document per line on stdout (demo too)
+
+  info, balance             --certified: read with replicated calls, certified replies
+  balance, watch            --subaccount <hex>
+  transfer                  --to-subaccount <hex>  --from-subaccount <hex>  --memo <hex>
+                            --fee <amount>  --created-at-time <ns>  --resend-unknown
+  watch                     --interval <ms> (default: 5000)
+
+Exit codes: 0 ok, 1 unexpected, 2 usage, 3 invalid_args, 4 unauthenticated,
+5 not_delivered, 6 outcome_unknown, 7 rejected, 8 invalid_reply, 9 canister_err,
+10 cancelled.`
+
+const isCommand = (text: string): text is CommandName =>
+  Object.hasOwn(COMMANDS, text)
+
+function parse(argv: readonly string[]): {
+  values: Flags
+  positionals: string[]
+} {
+  try {
+    return parseArgs({
+      args: [...argv],
+      options: FLAGS,
+      allowPositionals: true,
+      strict: true,
+    })
+  } catch (error) {
+    throw new UsageError(error instanceof Error ? error.message : String(error))
+  }
+}
+
+/**
+ * Parses `argv` (the arguments after `node src/cli.ts`).
+ *
+ * @throws UsageError for an unknown command or flag, a flag the command does
+ * not take, or the wrong number of arguments.
+ */
+export function parseCommandLine(argv: readonly string[]): CommandLine {
+  const { values: flags, positionals } = parse(argv)
+  const json = flags.json === true
+  if (flags.help === true) return { help: true, json }
+
+  const [name, ...args] = positionals
+  if (name === undefined) throw new UsageError("no command given")
+  if (!isCommand(name)) {
+    throw new UsageError(`unknown command ${JSON.stringify(name)}`)
+  }
+
+  const spec: { args: readonly string[]; flags: readonly Flag[] } =
+    COMMANDS[name]
+  for (const given of Object.keys(flags)) {
+    if (!spec.flags.some((flag) => flag === given)) {
+      throw new UsageError(`${name} does not take --${given}`, name)
+    }
+  }
+  if (args.length !== spec.args.length) {
+    const wanted = spec.args.map((arg) => `<${arg}>`).join(" ")
+    throw new UsageError(
+      `${name} takes ${spec.args.length === 0 ? "no arguments" : wanted}, got ${args.length}`,
+      name
+    )
+  }
+  return { help: false, command: name, args, flags, json }
+}

package/examples/node-agent-tool/src/commands/balance.ts

@@ -0,0 +1,73 @@
+// Scenario 4, direct calls (no cache): `balance <principal>`.
+//
+// The owner is typed text, so it becomes a Principal through `principal(text)`
+// (src/input.ts) or is refused before anything is sent. The balance comes
+// back in base units and is shown with `formatUnits`, never `Number()`.
+//
+// With `--certified` the balance is read through the certified canister
+// object for the same id (`{ id, certified: true }`), while the decimals and
+// the symbol, which only label it, stay plain queries: the output says which
+// read was which.
+import type { Context } from "../context.ts"
+import { EXIT_CODES } from "../failure.ts"
+import { principalArg, subaccountArg, toHex } from "../input.ts"
+import { ledgerOn } from "../ledgers.ts"
+import { amount, rows } from "../output.ts"
+
+export async function balance(
+  ctx: Context,
+  ownerText: string,
+  options: { subaccount: string | undefined; certified: boolean }
+): Promise<number> {
+  const account = {
+    owner: principalArg(ownerText, "owner"),
+    subaccount:
+      options.subaccount === undefined
+        ? null
+        : subaccountArg(options.subaccount, "--subaccount"),
+  }
+  const plain = ledgerOn(ctx.client, ctx.ledger.id)
+  const source = options.certified
+    ? ledgerOn(ctx.client, ctx.ledger.id, true)
+    : plain
+  const [units, decimals, symbol] = await Promise.all([
+    source.icrc1_balance_of(account),
+    plain.icrc1_decimals(),
+    plain.icrc1_symbol(),
+  ])
+  const shown = amount(units, decimals)
+  const how = options.certified ? "certified" : "query"
+  ctx.out.result(
+    {
+      ok: true,
+      command: "balance",
+      network: ctx.client.network,
+      ledger: { id: ctx.ledger.id, name: ctx.ledger.name },
+      account,
+      balance: shown,
+      symbol,
+      decimals,
+      reads: {
+        icrc1_balance_of: how,
+        icrc1_decimals: "query",
+        icrc1_symbol: "query",
+      },
+    },
+    rows([
+      [
+        "account",
+        account.subaccount === null
+          ? account.owner
+          : `${account.owner} subaccount ${toHex(account.subaccount)}`,
+      ],
+      ["balance", `${shown.tokens} ${symbol} (${units} base units)`],
+      [
+        "reads",
+        options.certified
+          ? "icrc1_balance_of certified (a replicated call); icrc1_decimals and icrc1_symbol plain queries"
+          : "plain queries, not certified (--certified to certify the balance)",
+      ],
+    ])
+  )
+  return EXIT_CODES.ok
+}

package/examples/node-agent-tool/src/commands/demo.test.ts

@@ -0,0 +1,51 @@
+// Scenario 8: the narrated demo runs to the end, every step as it says.
+import { describe, expect, it } from "vitest"
+import { createCli } from "../test-kit.ts"
+
+describe("demo", () => {
+  it("runs every step, and each ends as expected", async () => {
+    const { cli } = createCli()
+    const result = await cli(["demo"])
+    expect(result.exitCode).toBe(0)
+    expect(result.stderr).toEqual([])
+    const text = result.stdout.join("\n")
+    for (const title of [
+      "[1/10] Who calls",
+      "[2/10] A transfer",
+      "[3/10] The ledger says no",
+      "[4/10] The reply is lost",
+      "[5/10] The same transfer, sent again",
+      "[6/10] Lost again, with --resend-unknown",
+      "[7/10] Throttled once (HTTP 429)",
+      "[8/10] The canister rejects (reject code 4)",
+      "[9/10] Nobody signed in",
+      "[10/10] Input that cannot be sent",
+    ]) {
+      expect(text).toContain(title)
+    }
+    expect(text).not.toContain("NOT AS EXPECTED")
+    expect(text).toContain(
+      "call icrc1_transfer (refused: refuseNext(429) answered the request with HTTP 429), call icrc1_transfer"
+    )
+    expect(text).toContain("call icrc1_transfer (reply lost)")
+    expect(result.stdout.at(-1)).toBe("demo: all 10 steps ended as expected.")
+  })
+
+  it("--json: a document per step, then a summary", async () => {
+    const { cli } = createCli()
+    const result = await cli(["demo", "--json"])
+    expect(result.exitCode).toBe(0)
+    expect(result.docs).toHaveLength(11)
+    expect(result.docs.slice(0, 10).map((doc) => doc.asExpected)).toEqual(
+      Array.from({ length: 10 }, () => true)
+    )
+    expect(result.docs.at(-1)).toEqual({ ok: true, command: "demo", steps: 10 })
+  })
+
+  it("takes no network, ledger or key: it brings its own", async () => {
+    const { cli } = createCli()
+    const result = await cli(["demo", "--network", "local"])
+    expect(result.exitCode).toBe(2)
+    expect(result.options).toBeUndefined()
+  })
+})