@ic-reactor/mcp 0.0.0-stage → 0.0.0

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

@@ -0,0 +1,135 @@
+// Scenario 7, the cache outside React: `watch <principal>`.
+//
+// A long-running process can use the client's QueryClient the way a page
+// does, without React:
+//
+// - `client.queryClient.fetchQuery(client.queryOptions(...))` reads through
+//   the cache. Options are built by the client (keys too: never by hand), and
+//   with `staleTime: Infinity` an answer is served from the cache until it is
+//   invalidated.
+// - The symbol and the decimals never change, so they are fetched once: every
+//   later tick is answered from the cache, with no request.
+// - Each tick invalidates the balance alone, with
+//   `invalidateQueries({ queryKey: client.queryKey(ledger, method, account) })`,
+//   so the next `fetchQuery` asks the ledger again. Only a change is printed.
+// - A failed read is printed and the watch goes on: a query changes nothing,
+//   so it never "may have executed", and the last balance stays in the cache.
+// - Ctrl-C (SIGINT) disposes the client, which cancels what is in flight and
+//   clears the cache, and the command exits 0.
+import type { Context } from "../context.ts"
+import { EXIT_CODES, failureOf } from "../failure.ts"
+import { principalArg, subaccountArg } from "../input.ts"
+import { ledgerOn } from "../ledgers.ts"
+import { amount, rows } from "../output.ts"
+
+export async function watch(
+  ctx: Context,
+  ownerText: string,
+  options: { subaccount: string | undefined; intervalMs: number }
+): Promise<number> {
+  const { client, out } = ctx
+  const account = {
+    owner: principalArg(ownerText, "owner"),
+    subaccount:
+      options.subaccount === undefined
+        ? null
+        : subaccountArg(options.subaccount, "--subaccount"),
+  }
+  const ledger = ledgerOn(client, ctx.ledger.id)
+
+  const stopped = new AbortController()
+  const stopListening = ctx.onInterrupt(() => {
+    stopped.abort()
+    client.dispose()
+  })
+
+  let last: bigint | undefined
+  try {
+    out.note(
+      `watching ${account.owner} on ${ctx.ledger.name ?? ctx.ledger.id} every ${options.intervalMs} ms; Ctrl-C stops`
+    )
+    while (!stopped.signal.aborted) {
+      try {
+        const [symbol, decimals, balance] = await Promise.all([
+          client.queryClient.fetchQuery({
+            ...client.queryOptions(ledger, "icrc1_symbol"),
+            staleTime: Infinity,
+          }),
+          client.queryClient.fetchQuery({
+            ...client.queryOptions(ledger, "icrc1_decimals"),
+            staleTime: Infinity,
+          }),
+          client.queryClient.fetchQuery({
+            ...client.queryOptions(ledger, "icrc1_balance_of", account),
+            staleTime: Infinity,
+          }),
+        ])
+        if (stopped.signal.aborted) break
+        if (balance !== last) {
+          const shown = amount(balance, decimals)
+          out.result(
+            {
+              ok: true,
+              command: "watch",
+              event: last === undefined ? "balance" : "change",
+              account,
+              balance: shown,
+              ...(last === undefined
+                ? {}
+                : { change: amount(balance - last, decimals) }),
+              symbol,
+              at: new Date().toISOString(),
+            },
+            rows([
+              [
+                last === undefined ? "balance" : "changed",
+                last === undefined
+                  ? `${shown.tokens} ${symbol}`
+                  : `${shown.tokens} ${symbol} (${balance > last ? "+" : ""}${amount(balance - last, decimals).tokens})`,
+              ],
+            ])
+          )
+          last = balance
+        }
+      } catch (error) {
+        if (stopped.signal.aborted) break
+        const failure = failureOf(error)
+        out.failure(
+          {
+            ok: false,
+            command: "watch",
+            kind: failure.kind,
+            mayHaveExecuted: failure.mayHaveExecuted,
+            message: failure.message,
+          },
+          [`read failed: ${failure.kind}: ${failure.message} (still watching)`]
+        )
+      }
+      await sleep(options.intervalMs, stopped.signal)
+      if (stopped.signal.aborted) break
+      // The balance alone goes stale; the symbol and decimals stay cached.
+      await client.queryClient.invalidateQueries({
+        queryKey: client.queryKey(ledger, "icrc1_balance_of", account),
+      })
+    }
+  } finally {
+    stopListening()
+    client.dispose()
+  }
+  out.note("stopped")
+  return EXIT_CODES.ok
+}
+
+/** Waits `ms`, or less if `signal` aborts first. */
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal.aborted) return resolve()
+    const timer = setTimeout(done, ms)
+    signal.addEventListener("abort", done, { once: true })
+    function done() {
+      clearTimeout(timer)
+      signal.removeEventListener("abort", done)
+      resolve()
+    }
+  })
+}

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

@@ -0,0 +1,36 @@
+// Scenario 1, `whoami`: the principal calls go out as, from the client itself.
+//
+// `client.authState()` answers without a network call: `"signed-in"` with the
+// key's principal for a client built with an Identity, `"anonymous"` with
+// 2vxsx-fae for one built with `identity: "anonymous"`, which refuses writes.
+import type { Context } from "../context.ts"
+import { EXIT_CODES } from "../failure.ts"
+import { rows } from "../output.ts"
+
+export async function whoami(ctx: Context): Promise<number> {
+  const { status, principal } = ctx.client.authState()
+  const canWrite = status === "signed-in"
+  ctx.out.result(
+    {
+      ok: true,
+      command: "whoami",
+      principal,
+      status,
+      canWrite,
+      identity: { algorithm: ctx.caller.algorithm, source: ctx.caller.source },
+      network: ctx.client.network,
+    },
+    rows([
+      ["principal", principal],
+      ["status", status],
+      [
+        "writes",
+        canWrite ? "signed and sent" : "refused by the client before sending",
+      ],
+      ["identity", ctx.caller.source],
+      ["network", ctx.client.network],
+      ["root key", ctx.network.rootKey],
+    ])
+  )
+  return EXIT_CODES.ok
+}

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

@@ -0,0 +1,20 @@
+// What every command runs with: one client for the whole process (one per
+// tab, one per request, one per run of a tool), and what the command line
+// chose. src/run.ts builds it; the demo builds its own over a test client.
+import type { Client } from "@ic-reactor/core"
+import type { Caller } from "./identity.ts"
+import type { LedgerChoice } from "./ledgers.ts"
+import type { NetworkChoice } from "./network.ts"
+import type { Output } from "./output.ts"
+
+export interface Context {
+  readonly client: Client
+  readonly caller: Caller
+  readonly network: NetworkChoice
+  readonly ledger: LedgerChoice
+  readonly out: Output
+  /** The time now, in nanoseconds since the epoch: a transfer's `created_at_time`. */
+  readonly now: () => bigint
+  /** Calls `stop` on Ctrl-C (SIGINT). Returns a function that stops listening. */
+  readonly onInterrupt: (stop: () => void) => () => void
+}

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

@@ -0,0 +1,70 @@
+// From a parsed command line to the command that runs it, with every failure
+// reported the same way: src/failure.ts's kind switch and exit code.
+import type { CommandLine } from "./command-line.ts"
+import { balance } from "./commands/balance.ts"
+import { info } from "./commands/info.ts"
+import { transfer } from "./commands/transfer.ts"
+import { watch } from "./commands/watch.ts"
+import { whoami } from "./commands/whoami.ts"
+import type { Context } from "./context.ts"
+import { failureOf, reportFailure } from "./failure.ts"
+import { intervalArg, UsageError } from "./input.ts"
+
+/** A command line that names a command other than `demo`, which runs on a client of its own. */
+export type ClientCommandLine = Extract<CommandLine, { help: false }>
+
+/** Runs the command `line` names on `ctx`, and returns its exit code. */
+export async function execute(
+  line: ClientCommandLine,
+  ctx: Context
+): Promise<number> {
+  try {
+    return await dispatch(line, ctx)
+  } catch (error) {
+    return reportFailure(ctx.out, line.command, failureOf(error))
+  }
+}
+
+function dispatch(line: ClientCommandLine, ctx: Context): Promise<number> {
+  const { flags } = line
+  const arg = (index: number): string => {
+    const value = line.args[index]
+    if (value === undefined)
+      throw new UsageError(`${line.command} needs more arguments`)
+    return value
+  }
+  switch (line.command) {
+    case "whoami":
+      return whoami(ctx)
+    case "info":
+      return info(ctx, { certified: flags.certified === true })
+    case "balance":
+      return balance(ctx, arg(0), {
+        subaccount: flags.subaccount,
+        certified: flags.certified === true,
+      })
+    case "transfer":
+      return transfer(ctx, {
+        to: arg(0),
+        amount: arg(1),
+        toSubaccount: flags["to-subaccount"],
+        fromSubaccount: flags["from-subaccount"],
+        memo: flags.memo,
+        fee: flags.fee,
+        createdAtTime: flags["created-at-time"],
+        resendUnknown: flags["resend-unknown"] === true,
+      })
+    case "watch":
+      return watch(ctx, arg(0), {
+        subaccount: flags.subaccount,
+        intervalMs:
+          flags.interval === undefined ? 5_000 : intervalArg(flags.interval),
+      })
+    case "demo":
+      throw new UsageError("demo runs on a client of its own")
+    default: {
+      const unhandled: never = line.command
+      throw new UsageError(`unknown command ${String(unhandled)}`)
+    }
+  }
+}

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

@@ -0,0 +1,59 @@
+// Scenario 5: one exit code per ReactorError kind, read from errors the real
+// client produced. (Every kind a transfer can end in is also run end to end
+// in src/commands/transfer.test.ts.)
+import { createTestClient } from "@ic-reactor/core/testing"
+import { describe, expect, it } from "vitest"
+import { EXIT_CODES, failureOf } from "./failure.ts"
+import { UsageError } from "./input.ts"
+import { LEDGERS, ledgerOn } from "./ledgers.ts"
+
+describe("exit codes", () => {
+  it("are one per outcome, and none is shared", () => {
+    expect(EXIT_CODES).toEqual({
+      ok: 0,
+      unexpected: 1,
+      usage: 2,
+      invalid_args: 3,
+      unauthenticated: 4,
+      not_delivered: 5,
+      outcome_unknown: 6,
+      rejected: 7,
+      invalid_reply: 8,
+      canister_err: 9,
+      cancelled: 10,
+    })
+    expect(new Set(Object.values(EXIT_CODES)).size).toBe(11)
+  })
+
+  it("10 cancelled: a call on a client that was disposed is never sent", async () => {
+    const { client, requests } = createTestClient()
+    const ledger = ledgerOn(client, LEDGERS.icp)
+    client.dispose()
+    const error: unknown = await ledger.icrc1_fee().then(
+      () => undefined,
+      (rejection: unknown) => rejection
+    )
+    expect(failureOf(error)).toMatchObject({
+      kind: "cancelled",
+      mayHaveExecuted: false,
+      exitCode: 10,
+      details: { code: "client_disposed" },
+    })
+    expect(requests.filter((r) => r.endpoint !== "status")).toEqual([])
+  })
+
+  it("2 usage and 1 unexpected, for what is not a ReactorError", () => {
+    expect(failureOf(new UsageError("no"))).toMatchObject({
+      kind: "usage",
+      exitCode: 2,
+      mayHaveExecuted: false,
+    })
+    expect(failureOf(new Error("bug"))).toMatchObject({
+      kind: "unexpected",
+      exitCode: 1,
+      mayHaveExecuted: false,
+    })
+    // After a write was sent, a failure that proves nothing may have executed.
+    expect(failureOf(new Error("bug"), true).mayHaveExecuted).toBe(true)
+  })
+})

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

@@ -0,0 +1,176 @@
+// Scenario 5 (and every command): one switch over the ReactorError kind.
+//
+// Every rejection a client call produces is a ReactorError: test with
+// `isReactorError(error)`, then read `kind`, and `mayHaveExecuted` for whether
+// a write may have taken effect anyway (packages/core/llms.txt, Errors). This
+// file turns that into what a person or an agent acts on: an exit code per
+// kind, the library's message, and what to do next. A kind the switch does
+// not handle fails the type check (`never` below).
+//
+// Exit codes (the README's table):
+//   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
+import { isReactorError, type ReactorErrorKind } from "@ic-reactor/core"
+import { SEED_VARIABLE } from "./identity.ts"
+import { UsageError } from "./input.ts"
+import type { FailureDoc, Json, Output } from "./output.ts"
+
+/** A ReactorError kind, or a refusal of this tool's own ("usage"), or a bug ("unexpected"). */
+export type FailureKind = ReactorErrorKind | "usage" | "unexpected"
+
+/** The process exit code of each outcome. */
+export const EXIT_CODES = {
+  ok: 0,
+  unexpected: 1,
+  usage: 2,
+  invalid_args: 3,
+  unauthenticated: 4,
+  not_delivered: 5,
+  outcome_unknown: 6,
+  rejected: 7,
+  invalid_reply: 8,
+  canister_err: 9,
+  cancelled: 10,
+} as const satisfies Record<"ok" | FailureKind, number>
+
+/** A failure, read once. */
+export interface Failure {
+  readonly kind: FailureKind
+  /** Whether a write may have taken effect although it failed. */
+  readonly mayHaveExecuted: boolean
+  readonly message: string
+  /** What to do next, in a sentence or two. */
+  readonly advice: string
+  readonly exitCode: number
+  /** The ReactorError fields an agent may branch on, when there are any. */
+  readonly details: {
+    readonly code?: string
+    readonly rejectCode?: number
+    readonly httpStatus?: number
+  }
+}
+
+/**
+ * Reads any thrown value as a {@link Failure}.
+ *
+ * @param sent - Whether the failure came from sending a write: a value that is
+ * not a ReactorError then cannot prove the write did not happen.
+ */
+export function failureOf(error: unknown, sent = false): Failure {
+  if (error instanceof UsageError) {
+    return {
+      kind: "usage",
+      mayHaveExecuted: false,
+      message: error.message,
+      advice:
+        "The input was refused before any write was sent. Run with --help for the commands and flags.",
+      exitCode: EXIT_CODES.usage,
+      details: {},
+    }
+  }
+  if (!isReactorError(error)) {
+    return {
+      kind: "unexpected",
+      mayHaveExecuted: sent,
+      message: error instanceof Error ? error.message : String(error),
+      advice: sent
+        ? "This is a bug in the tool, and the write may have gone out: read the balance before anything else."
+        : "This is a bug in the tool.",
+      exitCode: EXIT_CODES.unexpected,
+      details: {},
+    }
+  }
+
+  const { kind, mayHaveExecuted, rejectCode } = error
+  let advice: string
+  switch (kind) {
+    case "invalid_args":
+      advice =
+        "The arguments did not encode, so nothing was sent. Fix the input."
+      break
+    case "unauthenticated":
+      advice =
+        `This command writes, and the client has no identity to sign with, so it refused before sending. ` +
+        `Pass --pem <file> or set ${SEED_VARIABLE}.`
+      break
+    case "not_delivered":
+      advice =
+        "Nothing ran that changed anything: the request was refused or never got in, or it was a read that got no answer " +
+        "(the client already sent it again where that was safe). It is safe to run again."
+      break
+    case "outcome_unknown":
+      advice =
+        "It went out and no trustworthy answer came back, so it may have executed. Read the state back before anything else; never send a new one blindly."
+      break
+    case "rejected":
+      advice = mayHaveExecuted
+        ? `Reject code ${rejectCode}: the canister rejected or trapped, possibly after changing state. Read the state back before anything else.`
+        : rejectCode === 4 || rejectCode === 5
+          ? `Reject code ${rejectCode}: the canister rejected or trapped a read, which changes nothing. Is it an ICRC-1 ledger?`
+          : `Reject code ${rejectCode}: refused before any canister code ran, so nothing executed.`
+      break
+    case "invalid_reply":
+      advice = mayHaveExecuted
+        ? "The write ran, but its reply did not decode. Read the state back."
+        : "The reply did not decode as this method's result: is the canister an ICRC-1 ledger?"
+      break
+    case "canister_err":
+      advice =
+        "The canister ran the call and answered Err: that answer is final."
+      break
+    case "cancelled":
+      advice = mayHaveExecuted
+        ? "The call was abandoned after it went out, so it may have executed. Read the state back."
+        : "The call was cancelled before it was sent."
+      break
+    default: {
+      const unhandled: never = kind
+      throw new Error(`unhandled kind ${String(unhandled)}`)
+    }
+  }
+
+  return {
+    kind,
+    mayHaveExecuted,
+    message: error.message,
+    advice,
+    exitCode: EXIT_CODES[kind],
+    details: {
+      ...(error.code === undefined ? {} : { code: error.code }),
+      ...(rejectCode === undefined ? {} : { rejectCode }),
+      ...(error.httpStatus === undefined
+        ? {}
+        : { httpStatus: error.httpStatus }),
+    },
+  }
+}
+
+/**
+ * Prints a failure and returns its exit code. `extra` adds fields to the JSON
+ * document, `lines` lines for a person after the standard ones.
+ */
+export function reportFailure(
+  out: Output,
+  command: string | null,
+  failure: Failure,
+  extra: { readonly [field: string]: Json | undefined } = {},
+  lines: readonly string[] = []
+): number {
+  const doc: FailureDoc = {
+    ok: false,
+    command,
+    kind: failure.kind,
+    mayHaveExecuted: failure.mayHaveExecuted,
+    message: failure.message,
+    ...failure.details,
+    ...extra,
+  }
+  out.failure(doc, [
+    `error: ${failure.kind}: ${failure.message}`,
+    `  may have executed: ${failure.mayHaveExecuted ? "yes" : "no"}`,
+    `  ${failure.advice}`,
+    ...lines.map((line) => `  ${line}`),
+  ])
+  return failure.exitCode
+}