@tokamak-private-dapps/private-state-cli 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.1.3 - 2026-04-28
+
+- Installed the Groth16 runtime during `private-state-cli --install` and reported Groth16 readiness from `--doctor`.
+- Added live NVIDIA and Docker GPU probes to `--doctor`, with a hard failure when live Docker GPU readiness does not match the recorded Tokamak CLI metadata.
+- Renamed `get-my-address` to `get-my-wallet-meta`, added `get-my-l1-address`, and added `list-local-wallets`.
+- Documented the private-state CLI helper commands, common flow examples, and LLM agent guidance.
+
 ## 0.1.2 - 2026-04-28
 
 - Added `private-state-cli --doctor` to report CLI and install-time dependency versions through `tokamak-l2js`.

package/README.md

@@ -8,7 +8,8 @@ Command-line client for the Tokamak private-state DApp.
 npm install -g @tokamak-private-dapps/private-state-cli
 ```
 
-Install the local Tokamak zk-EVM runtime workspace and public private-state deployment artifacts:
+Install the local Tokamak zk-EVM runtime workspace, Groth16 runtime workspace, and public private-state deployment
+artifacts:
 
 ```bash
 private-state-cli --install
@@ -35,7 +36,7 @@ private-state-cli --doctor
 
 ## Commands
 
-The normal private-state flow is:
+A common private-state flow is:
 
 1. `create-channel`
 2. `deposit-bridge`
@@ -52,7 +53,21 @@ Use `private-state-cli --help` for the full command list and required options.
 
 `private-state-cli --doctor` reports the CLI package version, dependency versions recorded by the last
 `private-state-cli --install`, current dependency versions through `tokamak-l2js`, and Tokamak zk-EVM runtime
-install mode, Docker mode, and CUDA runtime metadata.
+install mode, Docker mode, CUDA runtime metadata, live `nvidia-smi` and Docker GPU probe results, and Groth16
+runtime health. The doctor check fails when the Tokamak Docker `useGpus` metadata does not match the live GPU probes.
+
+Local helper commands:
+
+```bash
+private-state-cli list-local-wallets --network sepolia --channel-name cuda
+private-state-cli get-my-wallet-meta --wallet <WALLET_NAME> --password <PASSWORD> --network sepolia
+private-state-cli get-my-l1-address --private-key <HEX>
+```
+
+`list-local-wallets` reads only the local workspace and prints saved wallet names that can be reused with `--wallet`.
+`get-my-wallet-meta` opens an encrypted local wallet and reports the stored L1/L2 identity metadata plus the current
+on-chain channel registration match state. `get-my-l1-address` is a simple offline helper that derives the L1 address
+for a private key.
 
 ## Workspace
 
@@ -64,6 +79,57 @@ The CLI stores user workspaces under:
 
 Wallet data is encrypted with the password supplied to `join-channel` or `recover-wallet`.
 
+## LLM Agent Guidance
+
+You may act as an interactive guide for users who do not understand this CLI or the private-state DApp. Assume the
+user only knows that the DApp is a way to send funds privately. Translate the user's intent into safe, step-by-step CLI
+actions.
+
+Primary goal: help the user privately send funds by guiding them through the required private-state CLI commands,
+explaining each step only as much as needed to proceed safely.
+
+Operating rules:
+
+- Do not ask the user to reveal raw private keys in chat. Use environment variable placeholders such as `$ADDR6`,
+  `$CREATOR`, or `$PRIVATE_STATE_TEST_PK`.
+- Prefer testnet examples unless the user explicitly asks for mainnet.
+- Before any proof-backed or bridge-facing workflow, ask the user to run `private-state-cli --doctor` and inspect
+  whether the runtime, Docker mode, CUDA/GPU probes, Groth16 runtime, and deployment artifacts are healthy.
+- Use `private-state-cli list-local-wallets` to discover local wallet names instead of asking the user to inspect
+  filesystem paths manually.
+- Use `private-state-cli get-my-l1-address --private-key "$KEY_ENV"` to derive the L1 address for a private-key
+  environment variable when wallet ownership needs to be identified.
+- Use `private-state-cli get-my-wallet-meta --wallet <WALLET> --password <PASSWORD> --network <NETWORK>` to inspect
+  local wallet metadata and on-chain channel registration state.
+- Use `private-state-cli get-my-bridge-fund` and `private-state-cli get-my-channel-fund` to check balances before
+  telling the user to move funds.
+- Explain that wallet names are local CLI identifiers, while private transfers use notes owned by L2 addresses
+  registered in the channel.
+- Do not present one fixed command sequence as universally correct. Some flows start from an existing channel or wallet,
+  while others require creating or joining a channel first.
+- When the user asks for a transfer, first determine whether the sender has minted notes available. If not, guide them
+  through funding the bridge, joining or recovering the channel wallet, depositing into the channel, and minting notes.
+- When generating commands, use placeholders for secrets and explicit values for public fields. Show one command at a
+  time unless the user asks for a batch.
+
+Suggested interaction flow:
+
+1. Identify the target network, usually `sepolia` for testing.
+2. Identify whether a channel already exists.
+3. Identify the sender and recipient wallets or private-key environment variables.
+4. Run `--doctor`.
+5. Run `list-local-wallets` and relevant metadata or balance checks.
+6. If needed, guide the user through `create-channel`, `deposit-bridge`, `join-channel`, `deposit-channel`, and
+   `mint-notes`.
+7. For a private transfer, select available note IDs from `get-my-notes`, find the recipient L2 address from
+   `get-my-wallet-meta`, then build `transfer-notes`.
+8. After transfer, guide the recipient to run `get-my-notes` to recover received notes from event logs.
+
+Example style: if the user says, "ADDR6 sends 10 tokens privately to ADDR8", do not assume the required note exists.
+First ask or check which channel and network to use, whether ADDR6 and ADDR8 are already joined, what the local wallet
+names are, and whether ADDR6 has an unused note worth exactly 10 or notes that sum to 10. Then provide the next concrete
+command.
+
 ## Artifacts
 
 Proof-backed commands require installed bridge, DApp, and Groth16 artifacts. Run `private-state-cli --install` before
@@ -81,7 +147,8 @@ Release order matters for npm publication. `@tokamak-private-dapps/common-librar
 ### What does this package install?
 
 It installs the `private-state-cli` terminal command and the local files needed by that command.
-It does not install bridge contracts, app contracts, or local deployment outputs.
+It does not install bridge contracts, app contracts, or local deployment outputs. The `private-state-cli --install`
+command provisions the local Tokamak zk-EVM and Groth16 runtime workspaces used by proof-backed commands.
 
 ### When should I run `private-state-cli --install`?
 

package/cli-assistant.html

@@ -528,7 +528,9 @@
         { id: "get-my-bridge-fund", description: "Read the current bridge-vault balance.", fields: ["network", "privateKey", "alchemyApiKey"] },
         { id: "join-channel", description: "Bind the caller to a channel-specific L2 identity.", fields: ["channelName", "password", "network", "privateKey", "alchemyApiKey"] },
         { id: "recover-wallet", description: "Rebuild the recoverable portion of a wallet.", fields: ["channelName", "password", "network", "privateKey", "alchemyApiKey"] },
-        { id: "get-my-address", description: "Check whether a saved wallet matches on-chain registration.", fields: ["wallet", "password", "network"] },
+        { id: "get-my-wallet-meta", description: "Check whether a saved wallet matches on-chain registration.", fields: ["wallet", "password", "network"] },
+        { id: "get-my-l1-address", description: "Derive the L1 address for a private key.", fields: ["privateKey"] },
+        { id: "list-local-wallets", description: "List saved local wallet names that can be reused with --wallet.", fields: ["network", "channelName"] },
         { id: "deposit-channel", description: "Move bridged funds into the channel L2 accounting balance.", fields: ["wallet", "password", "network", "amount"] },
         { id: "withdraw-channel", description: "Move channel L2 balance back into the shared bridge vault.", fields: ["wallet", "password", "network", "amount"] },
         { id: "get-my-channel-fund", description: "Read the current channel L2 accounting balance.", fields: ["wallet", "password", "network"] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamak-private-dapps/private-state-cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Command-line client for the Tokamak private-state DApp.",
   "license": "MIT OR Apache-2.0",
   "author": "Tokamak Network",

package/private-state-bridge-cli.mjs

@@ -90,6 +90,8 @@ const tokamakCliInvocation = buildTokamakCliInvocation();
 const tokamakCliCommand = tokamakCliInvocation.command;
 const tokamakCliBaseArgs = tokamakCliInvocation.args;
 const flatDeploymentArtifactPathsByChainId = new Map();
+const DOCKER_CUDA_PROBE_IMAGE = "nvidia/cuda:12.2.0-base-ubuntu22.04";
+const DOCTOR_GPU_PROBE_TIMEOUT_MS = 120000;
 
 const abiCoder = AbiCoder.defaultAbiCoder();
 const erc20MetadataAbi = [
@@ -231,6 +233,18 @@ async function main() {
     return;
   }
 
+  if (args.command === "get-my-l1-address") {
+    assertGetMyL1AddressArgs(args);
+    handleGetMyL1Address({ args });
+    return;
+  }
+
+  if (args.command === "list-local-wallets") {
+    assertListLocalWalletsArgs(args);
+    handleListLocalWallets({ args });
+    return;
+  }
+
   const walletCommandHandlers = {
     "mint-notes": {
       assert: assertMintNotesArgs,
@@ -256,9 +270,9 @@ async function main() {
       assert: (parsedArgs) => assertWalletChannelMoveArgs(parsedArgs, "withdraw-channel"),
       run: ({ provider }) => handleGrothVaultMove({ args, provider, direction: "withdraw" }),
     },
-    "get-my-address": {
-      assert: assertGetMyAddressArgs,
-      run: ({ provider }) => handleGetMyAddress({ args, provider }),
+    "get-my-wallet-meta": {
+      assert: assertGetMyWalletMetaArgs,
+      run: ({ provider }) => handleGetMyWalletMeta({ args, provider }),
     },
     "get-my-channel-fund": {
       assert: assertGetMyChannelFundArgs,
@@ -942,6 +956,9 @@ async function handleInstallZkEvm({ args }) {
   }
   run(tokamakCliCommand, installArgs);
   const tokamakRuntimeRoot = resolveTokamakCliRuntimeRoot();
+  const groth16Runtime = installGroth16RuntimeForPrivateState({
+    docker: Boolean(args.docker),
+  });
   const localDeploymentBaseRoot = args.includeLocalArtifacts ? process.cwd() : null;
   const deploymentArtifacts = await installPrivateStateCliArtifacts({
     dappName: PRIVATE_STATE_DAPP_LABEL,
@@ -952,11 +969,13 @@ async function handleInstallZkEvm({ args }) {
     includeLocalArtifacts: Boolean(args.includeLocalArtifacts),
     localDeploymentBaseRoot,
     deploymentArtifacts,
+    groth16Runtime,
   });
   printJson({
     action: "install",
     tokamakCli: tokamakCliBaseArgs[0],
     runtimeRoot: tokamakRuntimeRoot,
+    groth16Runtime,
     docker: Boolean(args.docker),
     includeLocalArtifacts: Boolean(args.includeLocalArtifacts),
     localDeploymentBaseRoot,
@@ -997,7 +1016,38 @@ async function handleDoctor() {
   }
 }
 
-async function handleGetMyAddress({ args, provider }) {
+function handleGetMyL1Address({ args }) {
+  const privateKey = normalizePrivateKey(requireArg(args.privateKey, "--private-key"));
+  const signer = new Wallet(privateKey);
+  printJson({
+    action: "get-my-l1-address",
+    l1Address: signer.address,
+  });
+}
+
+function handleListLocalWallets({ args }) {
+  const networkFilter = args.network ? requireNetworkName(args) : null;
+  if (networkFilter) {
+    resolveCliNetwork(networkFilter);
+  }
+  const channelFilter = args.channelName ? slugifyPathComponent(requireArg(args.channelName, "--channel-name")) : null;
+  const wallets = listLocalWallets({
+    networkFilter,
+    channelFilter,
+  });
+
+  printJson({
+    action: "list-local-wallets",
+    workspaceRoot,
+    filters: {
+      network: networkFilter,
+      channelName: args.channelName ?? null,
+    },
+    wallets,
+  });
+}
+
+async function handleGetMyWalletMeta({ args, provider }) {
   const { wallet, walletMetadata } = loadUnlockedWalletWithMetadata(args);
   const { signer, l2Identity } = restoreWalletParticipant(wallet, provider);
   const context = await loadChannelContext({
@@ -1015,7 +1065,7 @@ async function handleGetMyAddress({ args, provider }) {
       === ethers.toBigInt(normalizeBytes32Hex(expectedStorageKey));
 
   printJson({
-    action: "get-my-address",
+    action: "get-my-wallet-meta",
     wallet: wallet.walletName,
     network: walletMetadata.network,
     channelName: walletMetadata.channelName,
@@ -4377,6 +4427,48 @@ function resolveWalletPathCandidates(walletName) {
   return candidates;
 }
 
+function listLocalWallets({ networkFilter = null, channelFilter = null } = {}) {
+  if (!fs.existsSync(workspaceRoot)) {
+    return [];
+  }
+
+  const wallets = [];
+  for (const networkEntry of fs.readdirSync(workspaceRoot, { withFileTypes: true })) {
+    if (!networkEntry.isDirectory() || (networkFilter && networkEntry.name !== slugifyPathComponent(networkFilter))) {
+      continue;
+    }
+    const networkDir = path.join(workspaceRoot, networkEntry.name);
+    for (const channelEntry of fs.readdirSync(networkDir, { withFileTypes: true })) {
+      if (!channelEntry.isDirectory() || (channelFilter && channelEntry.name !== channelFilter)) {
+        continue;
+      }
+      const walletsDir = path.join(networkDir, channelEntry.name, "wallets");
+      if (!fs.existsSync(walletsDir)) {
+        continue;
+      }
+      for (const walletEntry of fs.readdirSync(walletsDir, { withFileTypes: true })) {
+        if (!walletEntry.isDirectory()) {
+          continue;
+        }
+        const walletDir = path.join(walletsDir, walletEntry.name);
+        wallets.push({
+          wallet: walletEntry.name,
+          network: networkEntry.name,
+          channelName: channelEntry.name,
+          walletDir,
+          metadataPath: walletMetadataPath(walletDir),
+          hasMetadata: fs.existsSync(walletMetadataPath(walletDir)),
+          hasEncryptedWallet: walletConfigExists(walletDir),
+        });
+      }
+    }
+  }
+  return wallets.sort((left, right) =>
+    [left.network, left.channelName, left.wallet].join("\0")
+      .localeCompare([right.network, right.channelName, right.wallet].join("\0")),
+  );
+}
+
 function channelDataPath(workspaceDir) {
   return workspaceChannelDir(workspaceDir);
 }
@@ -4566,8 +4658,33 @@ function assertJoinChannelArgs(args) {
   assertExplicitSignerPasswordCommandArgs(args, "join-channel");
 }
 
-function assertGetMyAddressArgs(args) {
-  assertWalletPasswordArgs(args, "get-my-address", [], "--wallet, --password, and --network");
+function assertGetMyWalletMetaArgs(args) {
+  assertWalletPasswordArgs(args, "get-my-wallet-meta", [], "--wallet, --password, and --network");
+}
+
+function assertGetMyL1AddressArgs(args) {
+  requireArg(args.privateKey, "--private-key");
+  assertAllowedCommandKeys(
+    args,
+    "get-my-l1-address",
+    new Set(["command", "positional", "privateKey"]),
+    "--private-key",
+  );
+}
+
+function assertListLocalWalletsArgs(args) {
+  if (args.network !== undefined) {
+    requireNetworkName(args);
+  }
+  if (args.channelName !== undefined) {
+    requireArg(args.channelName, "--channel-name");
+  }
+  assertAllowedCommandKeys(
+    args,
+    "list-local-wallets",
+    new Set(["command", "positional", "network", "channelName"]),
+    "optional --network and --channel-name",
+  );
 }
 
 function assertWithdrawBridgeArgs(args) {
@@ -4629,8 +4746,8 @@ function printHelp() {
   console.log(`
 Commands:
   --install [--docker] [--include-local-artifacts]
-      Install the Tokamak zk-EVM CLI runtime workspace and private-state deployment artifacts
-      Use --docker on Linux to forward tokamak-cli --install --docker
+      Install the Tokamak zk-EVM CLI runtime, Groth16 runtime, and private-state deployment artifacts
+      Use --docker on Linux to forward Docker mode to the Tokamak zk-EVM and Groth16 runtimes
       Use --include-local-artifacts to also install local deployment/ artifacts from the current working directory
 
   uninstall-zk-evm
@@ -4660,9 +4777,15 @@ Commands:
   join-channel --channel-name <NAME> --password <PASSWORD> --network <NAME> --private-key <HEX> --alchemy-api-key <KEY>
       Pay the channel join fee and bind a wallet to a channel-specific L2 identity
 
-  get-my-address --wallet <NAME> --password <PASSWORD> --network <NAME>
+  get-my-wallet-meta --wallet <NAME> --password <PASSWORD> --network <NAME>
       Check whether a wallet matches the on-chain channel registration
 
+  get-my-l1-address --private-key <HEX>
+      Derive the L1 address for a private key
+
+  list-local-wallets [--network <NAME>] [--channel-name <NAME>]
+      List saved local wallet names that can be reused with --wallet
+
   deposit-channel --wallet <NAME> --password <PASSWORD> --network <NAME> --amount <TOKENS>
       Move bridged funds into the channel L2 accounting balance
 
@@ -4927,6 +5050,7 @@ function writePrivateStateCliInstallManifest({
   includeLocalArtifacts,
   localDeploymentBaseRoot,
   deploymentArtifacts,
+  groth16Runtime,
 }) {
   const manifestPath = privateStateCliInstallManifestPath(deploymentArtifacts.cacheBaseRoot);
   const manifest = {
@@ -4941,6 +5065,7 @@ function writePrivateStateCliInstallManifest({
       includeLocalArtifacts,
       localDeploymentBaseRoot,
       artifactCacheRoot: deploymentArtifacts.cacheBaseRoot,
+      groth16Runtime,
       installedDeploymentArtifacts: deploymentArtifacts.installed.map((entry) => ({
         chainId: entry.chainId,
         source: entry.source,
@@ -4966,6 +5091,8 @@ function buildDoctorReport() {
   const installManifest = readJsonIfExists(installManifestPath);
   const dependencyReports = collectDependencyPackageReports(installManifest);
   const tokamakCli = inspectTokamakCliRuntime();
+  const groth16Runtime = inspectGroth16Runtime();
+  const gpuDockerReadiness = inspectGpuDockerReadiness(tokamakCli);
   const checks = [
     {
       name: "dependency package versions",
@@ -4993,6 +5120,28 @@ function buildDoctorReport() {
         })),
       },
     },
+    {
+      name: "tokamak docker gpu readiness",
+      ok: gpuDockerReadiness.ok,
+      details: {
+        expectedUseGpus: gpuDockerReadiness.expectedUseGpus,
+        liveUseGpus: gpuDockerReadiness.liveUseGpus,
+        mismatch: gpuDockerReadiness.mismatch,
+        mismatchError: gpuDockerReadiness.mismatchError,
+        hostNvidiaSmi: summarizeProbeResult(gpuDockerReadiness.hostNvidiaSmi),
+        dockerNvidiaSmi: summarizeProbeResult(gpuDockerReadiness.dockerNvidiaSmi),
+      },
+    },
+    {
+      name: "groth16 runtime",
+      ok: groth16Runtime.installed,
+      details: {
+        packageRoot: groth16Runtime.packageRoot,
+        workspaceRoot: groth16Runtime.workspaceRoot,
+        doctorStatus: groth16Runtime.doctor.status,
+        checks: groth16Runtime.checks,
+      },
+    },
   ];
 
   return {
@@ -5012,10 +5161,25 @@ function buildDoctorReport() {
     },
     dependencies: dependencyReports,
     tokamakCli,
+    groth16Runtime,
+    gpuDockerReadiness,
     checks,
   };
 }
 
+function installGroth16RuntimeForPrivateState({ docker }) {
+  const packageRoot = resolveGroth16PackageRoot();
+  const entryPath = resolveGroth16CliEntryPath(packageRoot);
+  const args = [entryPath, "--install"];
+  if (docker) {
+    args.push("--docker");
+  }
+  run(process.execPath, args, { cwd: packageRoot });
+  const runtime = inspectGroth16Runtime();
+  expect(runtime.installed, "Groth16 runtime install completed, but tokamak-groth16 --doctor still reports an unhealthy runtime.");
+  return runtime;
+}
+
 function collectDependencyPackageReports(installManifest = null) {
   const installVersions = new Map(
     Array.isArray(installManifest?.dependencies)
@@ -5087,6 +5251,35 @@ function findPackageJsonForName(startDir, expectedName) {
   throw new Error(`Cannot locate package.json for ${expectedName} above ${startDir}.`);
 }
 
+function resolveGroth16PackageRoot() {
+  const publicDriveCrsPath = require.resolve("@tokamak-private-dapps/groth16/public-drive-crs");
+  return path.dirname(findPackageJsonForName(path.dirname(publicDriveCrsPath), "@tokamak-private-dapps/groth16"));
+}
+
+function resolveGroth16CliEntryPath(packageRoot = resolveGroth16PackageRoot()) {
+  return path.join(packageRoot, "cli", "tokamak-groth16-cli.mjs");
+}
+
+function inspectGroth16Runtime() {
+  const packageRoot = resolveGroth16PackageRoot();
+  const entryPath = resolveGroth16CliEntryPath(packageRoot);
+  const doctor = runCaptured(process.execPath, [entryPath, "--doctor", "--verbose"], { cwd: packageRoot });
+  const stdout = stripAnsi(doctor.stdout).trim();
+  const stderr = stripAnsi(doctor.stderr).trim();
+  const report = parseJsonReport(stdout);
+  return {
+    installed: doctor.status === 0 && report?.ok === true,
+    packageRoot,
+    workspaceRoot: report?.workspaceRoot ?? null,
+    checks: report?.checks ?? [],
+    doctor: {
+      status: doctor.status,
+      stdout,
+      stderr,
+    },
+  };
+}
+
 function inspectTokamakCliRuntime() {
   const doctor = runCaptured(tokamakCliCommand, [...tokamakCliBaseArgs, "--doctor"], {
     cwd: resolveTokamakCliPackageRoot(),
@@ -5118,6 +5311,84 @@ function inspectTokamakCliRuntime() {
   };
 }
 
+function inspectGpuDockerReadiness(tokamakCli) {
+  const hostNvidiaSmi = runProbe("nvidia-smi", ["--query-gpu=name,driver_version", "--format=csv,noheader"]);
+  const dockerNvidiaSmi = runProbe("docker", [
+    "run",
+    "--rm",
+    "--gpus",
+    "all",
+    DOCKER_CUDA_PROBE_IMAGE,
+    "nvidia-smi",
+  ]);
+  const expectedUseGpus = Boolean(tokamakCli.cudaCompatible);
+  const liveUseGpus = hostNvidiaSmi.ok && dockerNvidiaSmi.ok;
+  const mismatch = expectedUseGpus !== liveUseGpus;
+  return {
+    ok: !mismatch,
+    expectedUseGpus,
+    liveUseGpus,
+    mismatch,
+    mismatchError: mismatch
+      ? [
+        "Tokamak CLI Docker GPU metadata does not match live NVIDIA/Docker GPU probes.",
+        `metadata useGpus=${expectedUseGpus}; live useGpus=${liveUseGpus}.`,
+      ].join(" ")
+      : null,
+    probeImage: DOCKER_CUDA_PROBE_IMAGE,
+    hostNvidiaSmi,
+    dockerNvidiaSmi,
+  };
+}
+
+function runProbe(command, args) {
+  const result = spawnSync(command, args, {
+    encoding: "utf8",
+    timeout: DOCTOR_GPU_PROBE_TIMEOUT_MS,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  return {
+    command,
+    args,
+    ok: !result.error && result.status === 0,
+    status: result.status,
+    signal: result.signal,
+    error: result.error ? result.error.message : null,
+    stdout: stripAnsi(result.stdout ?? "").trim(),
+    stderr: stripAnsi(result.stderr ?? "").trim(),
+    timedOut: result.error?.code === "ETIMEDOUT",
+  };
+}
+
+function summarizeProbeResult(result) {
+  return {
+    command: [result.command, ...result.args].join(" "),
+    ok: result.ok,
+    status: result.status,
+    signal: result.signal,
+    error: result.error,
+    timedOut: result.timedOut,
+    stdout: truncateText(result.stdout, 2000),
+    stderr: truncateText(result.stderr, 2000),
+  };
+}
+
+function truncateText(value, maxLength) {
+  const text = String(value ?? "");
+  if (text.length <= maxLength) {
+    return text;
+  }
+  return `${text.slice(0, maxLength)}...`;
+}
+
+function parseJsonReport(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+
 function resolveTokamakCliCacheRoot() {
   return path.resolve(process.env.TOKAMAK_ZKEVM_CLI_CACHE_DIR ?? path.join(os.homedir(), ".tokamak-zk-evm"));
 }