@0gfoundation/0g-agentdna 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (206) hide show
  1. package/GUIDE.md +975 -0
  2. package/LICENSE +21 -0
  3. package/MIGRATION.md +84 -0
  4. package/MIGRATION.zh.md +70 -0
  5. package/PROVIDERS.md +273 -0
  6. package/PROVIDERS.zh.md +234 -0
  7. package/README.md +334 -2
  8. package/dist/AgentClient.d.ts +312 -0
  9. package/dist/AgentClient.d.ts.map +1 -0
  10. package/dist/AgentClient.js +715 -0
  11. package/dist/AgentClient.js.map +1 -0
  12. package/dist/AgenticID.d.ts +823 -0
  13. package/dist/AgenticID.d.ts.map +1 -0
  14. package/dist/AgenticID.js +1188 -0
  15. package/dist/AgenticID.js.map +1 -0
  16. package/dist/AgenticIDClient.d.ts +68 -0
  17. package/dist/AgenticIDClient.d.ts.map +1 -0
  18. package/dist/AgenticIDClient.js +198 -0
  19. package/dist/AgenticIDClient.js.map +1 -0
  20. package/dist/AttestorClient.d.ts +465 -0
  21. package/dist/AttestorClient.d.ts.map +1 -0
  22. package/dist/AttestorClient.js +1030 -0
  23. package/dist/AttestorClient.js.map +1 -0
  24. package/dist/Providers.d.ts +72 -0
  25. package/dist/Providers.d.ts.map +1 -0
  26. package/dist/Providers.js +182 -0
  27. package/dist/Providers.js.map +1 -0
  28. package/dist/ReputationClient.d.ts +213 -0
  29. package/dist/ReputationClient.d.ts.map +1 -0
  30. package/dist/ReputationClient.js +708 -0
  31. package/dist/ReputationClient.js.map +1 -0
  32. package/dist/SandboxClient.d.ts +107 -0
  33. package/dist/SandboxClient.d.ts.map +1 -0
  34. package/dist/SandboxClient.js +200 -0
  35. package/dist/SandboxClient.js.map +1 -0
  36. package/dist/ServeProof.d.ts +161 -0
  37. package/dist/ServeProof.d.ts.map +1 -0
  38. package/dist/ServeProof.js +230 -0
  39. package/dist/ServeProof.js.map +1 -0
  40. package/dist/ServeSession.d.ts +180 -0
  41. package/dist/ServeSession.d.ts.map +1 -0
  42. package/dist/ServeSession.js +336 -0
  43. package/dist/ServeSession.js.map +1 -0
  44. package/dist/Settings.d.ts +179 -0
  45. package/dist/Settings.d.ts.map +1 -0
  46. package/dist/Settings.js +247 -0
  47. package/dist/Settings.js.map +1 -0
  48. package/dist/abi.d.ts +2216 -0
  49. package/dist/abi.d.ts.map +1 -0
  50. package/dist/abi.js +1248 -0
  51. package/dist/abi.js.map +1 -0
  52. package/dist/cli/commands/cells.d.ts +34 -0
  53. package/dist/cli/commands/cells.d.ts.map +1 -0
  54. package/dist/cli/commands/cells.js +66 -0
  55. package/dist/cli/commands/cells.js.map +1 -0
  56. package/dist/cli/commands/doctor.d.ts +15 -0
  57. package/dist/cli/commands/doctor.d.ts.map +1 -0
  58. package/dist/cli/commands/doctor.js +236 -0
  59. package/dist/cli/commands/doctor.js.map +1 -0
  60. package/dist/cli/commands/interactive.d.ts +107 -0
  61. package/dist/cli/commands/interactive.d.ts.map +1 -0
  62. package/dist/cli/commands/interactive.js +3034 -0
  63. package/dist/cli/commands/interactive.js.map +1 -0
  64. package/dist/cli/commands/list.d.ts +31 -0
  65. package/dist/cli/commands/list.d.ts.map +1 -0
  66. package/dist/cli/commands/list.js +115 -0
  67. package/dist/cli/commands/list.js.map +1 -0
  68. package/dist/cli/commands/providers.d.ts +3 -0
  69. package/dist/cli/commands/providers.d.ts.map +1 -0
  70. package/dist/cli/commands/providers.js +21 -0
  71. package/dist/cli/commands/providers.js.map +1 -0
  72. package/dist/cli/commands/settings.d.ts +22 -0
  73. package/dist/cli/commands/settings.d.ts.map +1 -0
  74. package/dist/cli/commands/settings.js +188 -0
  75. package/dist/cli/commands/settings.js.map +1 -0
  76. package/dist/cli/commands/status.d.ts +16 -0
  77. package/dist/cli/commands/status.d.ts.map +1 -0
  78. package/dist/cli/commands/status.js +148 -0
  79. package/dist/cli/commands/status.js.map +1 -0
  80. package/dist/cli/commands/update.d.ts +21 -0
  81. package/dist/cli/commands/update.d.ts.map +1 -0
  82. package/dist/cli/commands/update.js +95 -0
  83. package/dist/cli/commands/update.js.map +1 -0
  84. package/dist/cli/config.d.ts +73 -0
  85. package/dist/cli/config.d.ts.map +1 -0
  86. package/dist/cli/config.js +239 -0
  87. package/dist/cli/config.js.map +1 -0
  88. package/dist/cli/env.d.ts +36 -0
  89. package/dist/cli/env.d.ts.map +1 -0
  90. package/dist/cli/env.js +74 -0
  91. package/dist/cli/env.js.map +1 -0
  92. package/dist/cli/envelope.d.ts +33 -0
  93. package/dist/cli/envelope.d.ts.map +1 -0
  94. package/dist/cli/envelope.js +62 -0
  95. package/dist/cli/envelope.js.map +1 -0
  96. package/dist/cli/errors.d.ts +48 -0
  97. package/dist/cli/errors.d.ts.map +1 -0
  98. package/dist/cli/errors.js +81 -0
  99. package/dist/cli/errors.js.map +1 -0
  100. package/dist/cli/inference.d.ts +21 -0
  101. package/dist/cli/inference.d.ts.map +1 -0
  102. package/dist/cli/inference.js +60 -0
  103. package/dist/cli/inference.js.map +1 -0
  104. package/dist/cli/logo.d.ts +21 -0
  105. package/dist/cli/logo.d.ts.map +1 -0
  106. package/dist/cli/logo.js +131 -0
  107. package/dist/cli/logo.js.map +1 -0
  108. package/dist/cli/main.d.ts +14 -0
  109. package/dist/cli/main.d.ts.map +1 -0
  110. package/dist/cli/main.js +223 -0
  111. package/dist/cli/main.js.map +1 -0
  112. package/dist/cli/proofs.d.ts +67 -0
  113. package/dist/cli/proofs.d.ts.map +1 -0
  114. package/dist/cli/proofs.js +133 -0
  115. package/dist/cli/proofs.js.map +1 -0
  116. package/dist/cli/ref.d.ts +39 -0
  117. package/dist/cli/ref.d.ts.map +1 -0
  118. package/dist/cli/ref.js +48 -0
  119. package/dist/cli/ref.js.map +1 -0
  120. package/dist/cli/sdk.d.ts +24 -0
  121. package/dist/cli/sdk.d.ts.map +1 -0
  122. package/dist/cli/sdk.js +65 -0
  123. package/dist/cli/sdk.js.map +1 -0
  124. package/dist/cli/settings.d.ts +66 -0
  125. package/dist/cli/settings.d.ts.map +1 -0
  126. package/dist/cli/settings.js +137 -0
  127. package/dist/cli/settings.js.map +1 -0
  128. package/dist/cli/tokenize.d.ts +61 -0
  129. package/dist/cli/tokenize.d.ts.map +1 -0
  130. package/dist/cli/tokenize.js +157 -0
  131. package/dist/cli/tokenize.js.map +1 -0
  132. package/dist/cli/types.d.ts +25 -0
  133. package/dist/cli/types.d.ts.map +1 -0
  134. package/dist/cli/types.js +8 -0
  135. package/dist/cli/types.js.map +1 -0
  136. package/dist/constants.d.ts +107 -0
  137. package/dist/constants.d.ts.map +1 -0
  138. package/dist/constants.js +74 -0
  139. package/dist/constants.js.map +1 -0
  140. package/dist/context.d.ts +108 -0
  141. package/dist/context.d.ts.map +1 -0
  142. package/dist/context.js +64 -0
  143. package/dist/context.js.map +1 -0
  144. package/dist/index.d.ts +45 -0
  145. package/dist/index.d.ts.map +1 -0
  146. package/dist/index.js +118 -0
  147. package/dist/index.js.map +1 -0
  148. package/dist/provider-catalog.json +23 -0
  149. package/dist/seal.d.ts +47 -0
  150. package/dist/seal.d.ts.map +1 -0
  151. package/dist/seal.js +145 -0
  152. package/dist/seal.js.map +1 -0
  153. package/dist/secretEnv.d.ts +119 -0
  154. package/dist/secretEnv.d.ts.map +1 -0
  155. package/dist/secretEnv.js +199 -0
  156. package/dist/secretEnv.js.map +1 -0
  157. package/dist/taskHash.d.ts +39 -0
  158. package/dist/taskHash.d.ts.map +1 -0
  159. package/dist/taskHash.js +119 -0
  160. package/dist/taskHash.js.map +1 -0
  161. package/dist/types.d.ts +336 -0
  162. package/dist/types.d.ts.map +1 -0
  163. package/dist/types.js +19 -0
  164. package/dist/types.js.map +1 -0
  165. package/package.json +75 -4
  166. package/scripts/sync-providers.cjs +8 -0
  167. package/src/AgentClient.ts +897 -0
  168. package/src/AgenticID.ts +1382 -0
  169. package/src/AgenticIDClient.ts +238 -0
  170. package/src/AttestorClient.ts +1306 -0
  171. package/src/Providers.ts +176 -0
  172. package/src/ReputationClient.ts +821 -0
  173. package/src/SandboxClient.ts +227 -0
  174. package/src/ServeProof.ts +290 -0
  175. package/src/ServeSession.ts +421 -0
  176. package/src/Settings.ts +296 -0
  177. package/src/abi.ts +1282 -0
  178. package/src/cli/commands/cells.ts +61 -0
  179. package/src/cli/commands/doctor.ts +235 -0
  180. package/src/cli/commands/interactive.ts +2715 -0
  181. package/src/cli/commands/list.ts +117 -0
  182. package/src/cli/commands/providers.ts +16 -0
  183. package/src/cli/commands/settings.ts +197 -0
  184. package/src/cli/commands/status.ts +170 -0
  185. package/src/cli/commands/update.ts +86 -0
  186. package/src/cli/config.ts +225 -0
  187. package/src/cli/env.ts +90 -0
  188. package/src/cli/envelope.ts +57 -0
  189. package/src/cli/errors.ts +114 -0
  190. package/src/cli/inference.ts +57 -0
  191. package/src/cli/logo.ts +125 -0
  192. package/src/cli/main.ts +235 -0
  193. package/src/cli/proofs.ts +160 -0
  194. package/src/cli/ref.ts +58 -0
  195. package/src/cli/sdk.ts +65 -0
  196. package/src/cli/settings.ts +153 -0
  197. package/src/cli/tokenize.ts +131 -0
  198. package/src/cli/types.ts +27 -0
  199. package/src/constants.ts +106 -0
  200. package/src/context.ts +161 -0
  201. package/src/index.ts +129 -0
  202. package/src/provider-catalog.json +23 -0
  203. package/src/seal.ts +163 -0
  204. package/src/secretEnv.ts +250 -0
  205. package/src/taskHash.ts +100 -0
  206. package/src/types.ts +357 -0
@@ -0,0 +1,61 @@
1
+ /**
2
+ * @file cells.ts
3
+ * @description Shared cell sanitising for human-mode listings — used by
4
+ * `list` and the REPL's own listing so a name cannot forge a row in EITHER.
5
+ *
6
+ * Untrusted cells (NAME is owner-controlled JSON; PHASE/FRAMEWORK come from
7
+ * the attestor) must not be able to forge a table. Order matters:
8
+ *
9
+ * 1. Sequence BODIES first, while the ESC that anchors them is still
10
+ * present: CSI (`ESC [ … final`), OSC (`ESC ] … BEL|ST` — hyperlinks),
11
+ * and the C1 CSI (0x9b … final). Stripping control bytes first would
12
+ * remove the ESC and leave the body printing as text (`a␛[31mRED␛[0mb`
13
+ * would render `a[31mRED[0mb`, an OSC-8 link would print its URL).
14
+ * 2. Newlines and line/paragraph separators become a space — a `\n` in a
15
+ * name renders a convincing fake row, and dropping it entirely would
16
+ * glue two words together (`nice\n466` must render `nice 466`, not
17
+ * `nice466`).
18
+ * 3. Remaining control bytes (C0/C1) go.
19
+ *
20
+ * Truncation slices CODE POINTS (UTF-16 slicing splits an emoji at the
21
+ * surrogate pair and prints U+FFFD) and format characters (\p{Cf} —
22
+ * zero-width joiners, bidi marks) are removed outright: they are invisible
23
+ * but change rendering direction and grouping. U+2028/2029 are handled as
24
+ * newlines above.
25
+ */
26
+
27
+ /** The sanitized text of a cell — no truncation, no padding. */
28
+ export function cleanCell(v: unknown): string {
29
+ return String(v ?? '')
30
+ // 1. sequence bodies (ESC-anchored) — must run before control stripping.
31
+ // ECMA-48 classes, so exotic forms don't print as text:
32
+ // CSI: (ESC [ | 0x9b) params [0-?]* intermediates [ -/]* final [@-~]
33
+ // — covers [1 q (space intermediate), [2~ (~ final), [38:5:196m
34
+ // OSC: ESC ] … terminated by BEL, ST (ESC \) or C1 ST (0x9c)
35
+ // DCS/APC/PM/SOS: ESC P/X/^/_ … terminated by ST or C1 ST
36
+ .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, '')
37
+ .replace(/\u009b[0-?]*[ -/]*[@-~]/g, '')
38
+ .replace(/\u001b\][^\u0007\u001b\u009c]*(?:\u0007|\u001b\\|\u009c)?/g, '')
39
+ .replace(/\u001b[PX^_][^\u001b\u009c]*(?:\u001b\\|\u009c)?/g, '')
40
+ // 2. line breaks become a space (visible, but cannot forge a row)
41
+ .replace(/[\n\r\u2028\u2029]/g, ' ')
42
+ // eslint-disable-next-line no-control-regex
43
+ .replace(/[\u0000-\u001f\u007f-\u009f]/g, '') // 3. remaining C0/C1
44
+ // invisible format characters: bidi marks, zero-width joiners
45
+ .replace(/\p{Cf}/gu, '');
46
+ }
47
+
48
+ /**
49
+ * A cell of width `w`: null/undefined renders the em-dash placeholder;
50
+ * over-long text truncates by CODE POINTS with an ellipsis so a long name
51
+ * cannot run into the next column.
52
+ */
53
+ export function cellText(v: unknown, w: number): string {
54
+ if (v === null || v === undefined) return '—'.padEnd(w);
55
+ const t = cleanCell(v);
56
+ const cps = [...t];
57
+ // padEnd on the truncated form too — without it a truncated cell is w-1
58
+ // wide and the next column glues on.
59
+ if (cps.length >= w) return `${cps.slice(0, Math.max(0, w - 2)).join('')}…`.padEnd(w);
60
+ return t.padEnd(w);
61
+ }
@@ -0,0 +1,235 @@
1
+ /**
2
+ * @file doctor.ts
3
+ * @description `0g-agentdna doctor` — six-point environment health check
4
+ * (spec v0.03 §3.1): attestor, RPC, wallet, gas, trust-root ack, sandbox
5
+ * balance. ALL six checks are always reported (pass/fail/skip) so even a
6
+ * broken environment yields the full picture; a check whose prerequisite
7
+ * failed is marked `skip`, never crashes the run.
8
+ *
9
+ * Exit: 0 when everything passes; 3 otherwise (the aggregated error takes
10
+ * the FIRST failing check's code + remedy, and `details.checks` carries all
11
+ * six results for machine consumers).
12
+ */
13
+
14
+ import { createPublicClient, http, formatEther, type PublicClient } from 'viem';
15
+ import { privateKeyToAccount } from 'viem/accounts';
16
+ import { MIN_SANDBOX_BALANCE_WEI, type AgenticID } from '../../AgenticID';
17
+ import { RPC_URL } from '../../constants';
18
+ import { buildClient } from '../sdk';
19
+ import { CliError, type ErrorCode } from '../errors';
20
+ import { emitOk, print } from '../envelope';
21
+ import type { CommandContext } from '../types';
22
+
23
+ type Status = 'pass' | 'fail' | 'skip';
24
+
25
+ /** One check's result — serialized as-is under `details.checks` / `data.checks`. */
26
+ interface Check {
27
+ name: string;
28
+ status: Status;
29
+ detail: string;
30
+ remedy?: string;
31
+ /** Present on fail; the aggregated CliError uses the first fail's code. */
32
+ code?: ErrorCode;
33
+ }
34
+
35
+ /** GET a JSON document with a hard timeout (a hung attestor must not hang doctor). */
36
+ async function fetchJson(url: string, timeoutMs = 10_000): Promise<Record<string, string | undefined>> {
37
+ const ac = new AbortController();
38
+ const timer = setTimeout(() => ac.abort(), timeoutMs);
39
+ try {
40
+ const res = await fetch(url, { signal: ac.signal });
41
+ if (!res.ok) throw new Error(`HTTP ${res.status}`);
42
+ return (await res.json()) as Record<string, string | undefined>;
43
+ } finally {
44
+ clearTimeout(timer);
45
+ }
46
+ }
47
+
48
+ /** Zero/absent contract address → that module is "not deployed here". */
49
+ function isZeroAddr(a?: string): boolean {
50
+ return !a || a.length !== 42 || /^0x0+$/i.test(a);
51
+ }
52
+
53
+ export async function run(ctx: CommandContext): Promise<void> {
54
+ const { env, json } = ctx;
55
+ const checks: Check[] = [];
56
+ const skip = (name: string, why: string): void => {
57
+ checks.push({ name, status: 'skip', detail: `skipped (${why})` });
58
+ };
59
+
60
+ // 1 — attestor reachable
61
+ let cfg: Record<string, string | undefined> | null = null;
62
+ if (!env.attestorUrl) {
63
+ checks.push({
64
+ name: 'attestor', status: 'fail', code: 'MISSING_ATTESTOR_URL',
65
+ detail: 'AGENTIC_ATTESTOR_URL is not set',
66
+ remedy: 'export AGENTIC_ATTESTOR_URL=https://agenticid.0g.ai # or your own attestor',
67
+ });
68
+ } else {
69
+ try {
70
+ cfg = await fetchJson(`${env.attestorUrl}/config`);
71
+ checks.push({ name: 'attestor', status: 'pass', detail: env.attestorUrl });
72
+ } catch (e) {
73
+ checks.push({
74
+ name: 'attestor', status: 'fail', code: 'ATTESTOR_UNREACHABLE',
75
+ detail: `GET ${env.attestorUrl}/config failed: ${(e as Error).message}`,
76
+ remedy: 'verify AGENTIC_ATTESTOR_URL and your network, then retry',
77
+ });
78
+ }
79
+ }
80
+
81
+ // 2 — RPC connectivity (explicit-wins: env override > attestor /config > SDK default)
82
+ const rpcUrl = env.rpcUrl ?? cfg?.chain_rpc ?? RPC_URL;
83
+ const publicClient: PublicClient = createPublicClient({ transport: http(rpcUrl) });
84
+ let rpcOk = false;
85
+ try {
86
+ const chainId = await publicClient.getChainId();
87
+ rpcOk = true;
88
+ checks.push({ name: 'rpc', status: 'pass', detail: `${rpcUrl} (chainId ${chainId})` });
89
+ } catch (e) {
90
+ checks.push({
91
+ name: 'rpc', status: 'fail', code: 'RPC_UNREACHABLE',
92
+ detail: `${rpcUrl}: ${(e as Error).message}`,
93
+ remedy: 'set AGENTIC_RPC_URL to a reachable 0G RPC (an attestor /config may advertise an internal-only one)',
94
+ });
95
+ }
96
+
97
+ // 3 — wallet configured. Absent = skip (matching gas/ack/sandboxBalance,
98
+ // which also skip without it — feedback.md F21); malformed stays a fail.
99
+ let owner: `0x${string}` | undefined;
100
+ if (!env.privateKey) {
101
+ checks.push({
102
+ name: 'wallet', status: 'skip', code: 'WALLET_REQUIRED',
103
+ detail: 'no owner key configured (owner checks skipped)',
104
+ remedy: 'run `login`, or export AGENTIC_PRIVATE_KEY=0x… # env only — no flag, by design',
105
+ });
106
+ } else if (!/^0x[0-9a-fA-F]{64}$/.test(env.privateKey)) {
107
+ checks.push({
108
+ name: 'wallet', status: 'fail', code: 'WALLET_REQUIRED',
109
+ detail: 'the configured owner key is malformed (expected 64 hex chars, 0x prefix optional)',
110
+ remedy: 'export AGENTIC_PRIVATE_KEY=0x<64 hex chars>',
111
+ });
112
+ } else {
113
+ owner = privateKeyToAccount(env.privateKey).address;
114
+ checks.push({ name: 'wallet', status: 'pass', detail: `${owner} (from AGENTIC_PRIVATE_KEY)` });
115
+ }
116
+
117
+ // 4 — gas: the owner must be able to pay for ack/deposit txs at all
118
+ if (!owner) skip('gas', 'needs wallet');
119
+ else if (!rpcOk) skip('gas', 'needs rpc');
120
+ else {
121
+ try {
122
+ const bal = await publicClient.getBalance({ address: owner });
123
+ if (bal > 0n) {
124
+ checks.push({ name: 'gas', status: 'pass', detail: `${formatEther(bal)} OG` });
125
+ } else {
126
+ checks.push({
127
+ name: 'gas', status: 'fail', code: 'PREFLIGHT_GAS',
128
+ detail: '0 OG — the owner wallet cannot pay for ack/deposit transactions',
129
+ remedy: `fund ${owner} with testnet OG (0G faucet), then retry`,
130
+ });
131
+ }
132
+ } catch (e) {
133
+ checks.push({
134
+ name: 'gas', status: 'fail', code: 'PREFLIGHT_GAS',
135
+ detail: `could not read balance: ${(e as Error).message}`,
136
+ remedy: 'check RPC connectivity, then retry',
137
+ });
138
+ }
139
+ }
140
+
141
+ // 5 + 6 need the attestor config, the owner address, and an SDK client.
142
+ if (!cfg) {
143
+ skip('ack', 'needs attestor /config');
144
+ skip('sandboxBalance', 'needs attestor /config');
145
+ } else if (!owner) {
146
+ skip('ack', 'needs wallet');
147
+ skip('sandboxBalance', 'needs wallet');
148
+ } else {
149
+ let ag: AgenticID | null = null;
150
+ let agErr = '';
151
+ try {
152
+ ag = await buildClient(env);
153
+ } catch (e) {
154
+ agErr = (e as Error).message;
155
+ }
156
+
157
+ // 5 — trust-root ack
158
+ if (isZeroAddr(cfg.tapp_registry_addr)) skip('ack', 'TappRegistry not deployed in this environment');
159
+ else if (!ag) checks.push({ name: 'ack', status: 'fail', code: 'PREFLIGHT_ACK', detail: agErr, remedy: 'verify the attestor environment, then retry' });
160
+ else {
161
+ try {
162
+ const { allAcked, missing } = await ag.ackStatus(owner);
163
+ if (allAcked) checks.push({ name: 'ack', status: 'pass', detail: 'all trust-root components acknowledged' });
164
+ else {
165
+ checks.push({
166
+ name: 'ack', status: 'fail', code: 'PREFLIGHT_ACK',
167
+ detail: `not acknowledged: ${missing.join(', ')}`,
168
+ // Stage-0 exception (spec §2.2): no `ack` CLI command yet — the
169
+ // remedy is guidance text until stage 1 promotes it to a command.
170
+ remedy: 'run `ack` in the interactive shell (or SDK: await ag.ack())',
171
+ });
172
+ }
173
+ } catch (e) {
174
+ checks.push({
175
+ name: 'ack', status: 'fail', code: 'PREFLIGHT_ACK',
176
+ detail: `could not read ack status: ${(e as Error).message}`,
177
+ remedy: 'verify the attestor environment, then retry',
178
+ });
179
+ }
180
+ }
181
+
182
+ // 6 — prepaid sandbox balance ≥ 0.1 OG
183
+ if (isZeroAddr(cfg.sandbox_serving_addr)) skip('sandboxBalance', 'SandboxServing not deployed in this environment');
184
+ else if (!ag) checks.push({ name: 'sandboxBalance', status: 'fail', code: 'PREFLIGHT_BALANCE', detail: agErr, remedy: 'verify the attestor environment, then retry' });
185
+ else {
186
+ try {
187
+ const bal = await ag.getBalance({ user: owner });
188
+ if (bal >= MIN_SANDBOX_BALANCE_WEI) {
189
+ checks.push({ name: 'sandboxBalance', status: 'pass', detail: `${formatEther(bal)} OG (≥ 0.1 floor)` });
190
+ } else {
191
+ checks.push({
192
+ name: 'sandboxBalance', status: 'fail', code: 'PREFLIGHT_BALANCE',
193
+ detail: `${formatEther(bal)} OG — below the 0.1 OG deploy floor`,
194
+ remedy: "run `deposit` in the interactive shell (or SDK: await ag.deposit({ amountWei: parseEther('0.1') }))",
195
+ });
196
+ }
197
+ } catch (e) {
198
+ checks.push({
199
+ name: 'sandboxBalance', status: 'fail', code: 'PREFLIGHT_BALANCE',
200
+ detail: `could not read sandbox balance: ${(e as Error).message}`,
201
+ remedy: 'verify the attestor environment, then retry',
202
+ });
203
+ }
204
+ }
205
+ }
206
+
207
+ // — render + aggregate —
208
+ const failed = checks.filter((c) => c.status === 'fail');
209
+ const summary = {
210
+ checks,
211
+ passed: checks.filter((c) => c.status === 'pass').length,
212
+ failed: failed.length,
213
+ skipped: checks.filter((c) => c.status === 'skip').length,
214
+ };
215
+
216
+ if (!json) {
217
+ const SYMBOL: Record<Status, string> = { pass: '✓', fail: '✗', skip: '⊘' };
218
+ for (const c of checks) {
219
+ print(`${SYMBOL[c.status]} ${c.name.padEnd(15)} ${c.detail}`);
220
+ if (c.status === 'fail' && c.remedy) print(`${''.padEnd(2)}fix: ${c.remedy}`);
221
+ }
222
+ print('');
223
+ print(`${summary.passed} passed, ${summary.failed} failed, ${summary.skipped} skipped`);
224
+ }
225
+
226
+ if (failed.length === 0) {
227
+ if (json) emitOk(summary);
228
+ return;
229
+ }
230
+ const first = failed[0];
231
+ throw new CliError(first.code ?? 'UNKNOWN', `${failed.length} of ${checks.length} checks failed`, {
232
+ remedy: first.remedy,
233
+ details: summary,
234
+ });
235
+ }