@0gfoundation/0g-agentdna 0.2.3 → 0.5.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 (255) hide show
  1. package/GUIDE.md +190 -40
  2. package/OPERATORS.md +164 -0
  3. package/OPERATORS.zh.md +141 -0
  4. package/PROVIDERS.md +6 -0
  5. package/PROVIDERS.zh.md +3 -1
  6. package/README.md +84 -11
  7. package/dist/AgentClient.d.ts +374 -26
  8. package/dist/AgentClient.d.ts.map +1 -1
  9. package/dist/AgentClient.js +323 -40
  10. package/dist/AgentClient.js.map +1 -1
  11. package/dist/AgenticID.d.ts +170 -80
  12. package/dist/AgenticID.d.ts.map +1 -1
  13. package/dist/AgenticID.js +300 -42
  14. package/dist/AgenticID.js.map +1 -1
  15. package/dist/AttestorClient.d.ts +115 -31
  16. package/dist/AttestorClient.d.ts.map +1 -1
  17. package/dist/AttestorClient.js +276 -56
  18. package/dist/AttestorClient.js.map +1 -1
  19. package/dist/Credentials.d.ts +574 -0
  20. package/dist/Credentials.d.ts.map +1 -0
  21. package/dist/Credentials.js +838 -0
  22. package/dist/Credentials.js.map +1 -0
  23. package/dist/Operators.d.ts +60 -0
  24. package/dist/Operators.d.ts.map +1 -0
  25. package/dist/Operators.js +38 -0
  26. package/dist/Operators.js.map +1 -0
  27. package/dist/Providers.d.ts +13 -0
  28. package/dist/Providers.d.ts.map +1 -1
  29. package/dist/Providers.js +20 -1
  30. package/dist/Providers.js.map +1 -1
  31. package/dist/Releases.d.ts +51 -0
  32. package/dist/Releases.d.ts.map +1 -0
  33. package/dist/Releases.js +72 -0
  34. package/dist/Releases.js.map +1 -0
  35. package/dist/ReputationClient.d.ts +47 -3
  36. package/dist/ReputationClient.d.ts.map +1 -1
  37. package/dist/ReputationClient.js +204 -78
  38. package/dist/ReputationClient.js.map +1 -1
  39. package/dist/ServeProof.d.ts +70 -23
  40. package/dist/ServeProof.d.ts.map +1 -1
  41. package/dist/ServeProof.js +94 -35
  42. package/dist/ServeProof.js.map +1 -1
  43. package/dist/ServeSession.d.ts +17 -2
  44. package/dist/ServeSession.d.ts.map +1 -1
  45. package/dist/ServeSession.js +77 -9
  46. package/dist/ServeSession.js.map +1 -1
  47. package/dist/Settings.d.ts +25 -1
  48. package/dist/Settings.d.ts.map +1 -1
  49. package/dist/Settings.js +53 -1
  50. package/dist/Settings.js.map +1 -1
  51. package/dist/TrustRegistry.d.ts +28 -0
  52. package/dist/TrustRegistry.d.ts.map +1 -0
  53. package/dist/TrustRegistry.js +67 -0
  54. package/dist/TrustRegistry.js.map +1 -0
  55. package/dist/abi.d.ts +346 -34
  56. package/dist/abi.d.ts.map +1 -1
  57. package/dist/abi.js +150 -30
  58. package/dist/abi.js.map +1 -1
  59. package/dist/cli/attach.d.ts +79 -0
  60. package/dist/cli/attach.d.ts.map +1 -0
  61. package/dist/cli/attach.js +253 -0
  62. package/dist/cli/attach.js.map +1 -0
  63. package/dist/cli/commands/cells.d.ts +45 -0
  64. package/dist/cli/commands/cells.d.ts.map +1 -1
  65. package/dist/cli/commands/cells.js +77 -0
  66. package/dist/cli/commands/cells.js.map +1 -1
  67. package/dist/cli/commands/cred.d.ts +12 -0
  68. package/dist/cli/commands/cred.d.ts.map +1 -0
  69. package/dist/cli/commands/cred.js +43 -0
  70. package/dist/cli/commands/cred.js.map +1 -0
  71. package/dist/cli/commands/doctor.d.ts.map +1 -1
  72. package/dist/cli/commands/doctor.js +44 -35
  73. package/dist/cli/commands/doctor.js.map +1 -1
  74. package/dist/cli/commands/interactive.d.ts +597 -21
  75. package/dist/cli/commands/interactive.d.ts.map +1 -1
  76. package/dist/cli/commands/interactive.js +5082 -1323
  77. package/dist/cli/commands/interactive.js.map +1 -1
  78. package/dist/cli/commands/list.d.ts +5 -5
  79. package/dist/cli/commands/list.d.ts.map +1 -1
  80. package/dist/cli/commands/list.js +21 -26
  81. package/dist/cli/commands/list.js.map +1 -1
  82. package/dist/cli/commands/providers.d.ts +4 -0
  83. package/dist/cli/commands/providers.d.ts.map +1 -1
  84. package/dist/cli/commands/providers.js +19 -5
  85. package/dist/cli/commands/providers.js.map +1 -1
  86. package/dist/cli/commands/releases.d.ts +13 -0
  87. package/dist/cli/commands/releases.d.ts.map +1 -0
  88. package/dist/cli/commands/releases.js +65 -0
  89. package/dist/cli/commands/releases.js.map +1 -0
  90. package/dist/cli/commands/settings.d.ts +5 -0
  91. package/dist/cli/commands/settings.d.ts.map +1 -1
  92. package/dist/cli/commands/settings.js +70 -24
  93. package/dist/cli/commands/settings.js.map +1 -1
  94. package/dist/cli/commands/status.d.ts +2 -1
  95. package/dist/cli/commands/status.d.ts.map +1 -1
  96. package/dist/cli/commands/status.js +22 -19
  97. package/dist/cli/commands/status.js.map +1 -1
  98. package/dist/cli/config.d.ts +48 -1
  99. package/dist/cli/config.d.ts.map +1 -1
  100. package/dist/cli/config.js +114 -5
  101. package/dist/cli/config.js.map +1 -1
  102. package/dist/cli/credentials.d.ts +179 -0
  103. package/dist/cli/credentials.d.ts.map +1 -0
  104. package/dist/cli/credentials.js +1443 -0
  105. package/dist/cli/credentials.js.map +1 -0
  106. package/dist/cli/download.d.ts +21 -0
  107. package/dist/cli/download.d.ts.map +1 -0
  108. package/dist/cli/download.js +89 -0
  109. package/dist/cli/download.js.map +1 -0
  110. package/dist/cli/env.d.ts +6 -0
  111. package/dist/cli/env.d.ts.map +1 -1
  112. package/dist/cli/env.js +18 -6
  113. package/dist/cli/env.js.map +1 -1
  114. package/dist/cli/envelope.d.ts +4 -2
  115. package/dist/cli/envelope.d.ts.map +1 -1
  116. package/dist/cli/envelope.js +10 -6
  117. package/dist/cli/envelope.js.map +1 -1
  118. package/dist/cli/errors.d.ts +45 -1
  119. package/dist/cli/errors.d.ts.map +1 -1
  120. package/dist/cli/errors.js +77 -0
  121. package/dist/cli/errors.js.map +1 -1
  122. package/dist/cli/inference.d.ts.map +1 -1
  123. package/dist/cli/inference.js +7 -0
  124. package/dist/cli/inference.js.map +1 -1
  125. package/dist/cli/inkView.d.ts +341 -0
  126. package/dist/cli/inkView.d.ts.map +1 -0
  127. package/dist/cli/inkView.js +1019 -0
  128. package/dist/cli/inkView.js.map +1 -0
  129. package/dist/cli/legacy/modelKey.d.ts +24 -0
  130. package/dist/cli/legacy/modelKey.d.ts.map +1 -0
  131. package/dist/cli/legacy/modelKey.js +32 -0
  132. package/dist/cli/legacy/modelKey.js.map +1 -0
  133. package/dist/cli/livePrompt.d.ts +212 -0
  134. package/dist/cli/livePrompt.d.ts.map +1 -0
  135. package/dist/cli/livePrompt.js +576 -0
  136. package/dist/cli/livePrompt.js.map +1 -0
  137. package/dist/cli/main.js +206 -72
  138. package/dist/cli/main.js.map +1 -1
  139. package/dist/cli/modelkey.d.ts +64 -0
  140. package/dist/cli/modelkey.d.ts.map +1 -0
  141. package/dist/cli/modelkey.js +113 -0
  142. package/dist/cli/modelkey.js.map +1 -0
  143. package/dist/cli/outboxSync.d.ts +51 -0
  144. package/dist/cli/outboxSync.d.ts.map +1 -0
  145. package/dist/cli/outboxSync.js +210 -0
  146. package/dist/cli/outboxSync.js.map +1 -0
  147. package/dist/cli/plain.d.ts +46 -0
  148. package/dist/cli/plain.d.ts.map +1 -0
  149. package/dist/cli/plain.js +260 -0
  150. package/dist/cli/plain.js.map +1 -0
  151. package/dist/cli/proofs.d.ts +5 -0
  152. package/dist/cli/proofs.d.ts.map +1 -1
  153. package/dist/cli/proofs.js +20 -0
  154. package/dist/cli/proofs.js.map +1 -1
  155. package/dist/cli/ref.d.ts.map +1 -1
  156. package/dist/cli/ref.js +3 -2
  157. package/dist/cli/ref.js.map +1 -1
  158. package/dist/cli/releaseNotice.d.ts +64 -0
  159. package/dist/cli/releaseNotice.d.ts.map +1 -0
  160. package/dist/cli/releaseNotice.js +194 -0
  161. package/dist/cli/releaseNotice.js.map +1 -0
  162. package/dist/cli/sdk.d.ts +18 -0
  163. package/dist/cli/sdk.d.ts.map +1 -1
  164. package/dist/cli/sdk.js +99 -1
  165. package/dist/cli/sdk.js.map +1 -1
  166. package/dist/cli/settings.d.ts +90 -9
  167. package/dist/cli/settings.d.ts.map +1 -1
  168. package/dist/cli/settings.js +273 -21
  169. package/dist/cli/settings.js.map +1 -1
  170. package/dist/cli/textfit.d.ts +28 -0
  171. package/dist/cli/textfit.d.ts.map +1 -0
  172. package/dist/cli/textfit.js +111 -0
  173. package/dist/cli/textfit.js.map +1 -0
  174. package/dist/constants.d.ts +1 -1
  175. package/dist/constants.js +1 -1
  176. package/dist/context.d.ts +26 -0
  177. package/dist/context.d.ts.map +1 -1
  178. package/dist/context.js +1 -0
  179. package/dist/context.js.map +1 -1
  180. package/dist/index.d.ts +19 -11
  181. package/dist/index.d.ts.map +1 -1
  182. package/dist/index.js +35 -2
  183. package/dist/index.js.map +1 -1
  184. package/dist/legacy/modelKey.d.ts +67 -0
  185. package/dist/legacy/modelKey.d.ts.map +1 -0
  186. package/dist/legacy/modelKey.js +80 -0
  187. package/dist/legacy/modelKey.js.map +1 -0
  188. package/dist/legacy/serveProofV1.d.ts +56 -0
  189. package/dist/legacy/serveProofV1.d.ts.map +1 -0
  190. package/dist/legacy/serveProofV1.js +91 -0
  191. package/dist/legacy/serveProofV1.js.map +1 -0
  192. package/dist/provider-catalog.json +3 -2
  193. package/dist/secretEnv.d.ts +18 -3
  194. package/dist/secretEnv.d.ts.map +1 -1
  195. package/dist/secretEnv.js +16 -2
  196. package/dist/secretEnv.js.map +1 -1
  197. package/dist/types.d.ts +63 -1
  198. package/dist/types.d.ts.map +1 -1
  199. package/dist/viemErrors.d.ts +30 -0
  200. package/dist/viemErrors.d.ts.map +1 -0
  201. package/dist/viemErrors.js +36 -0
  202. package/dist/viemErrors.js.map +1 -0
  203. package/package.json +5 -1
  204. package/src/AgentClient.ts +622 -68
  205. package/src/AgenticID.ts +345 -56
  206. package/src/AttestorClient.ts +330 -83
  207. package/src/Credentials.ts +1027 -0
  208. package/src/Operators.ts +71 -0
  209. package/src/Providers.ts +20 -0
  210. package/src/Releases.ts +95 -0
  211. package/src/ReputationClient.ts +231 -79
  212. package/src/ServeProof.ts +123 -39
  213. package/src/ServeSession.ts +91 -9
  214. package/src/Settings.ts +61 -1
  215. package/src/TrustRegistry.ts +75 -0
  216. package/src/abi.ts +153 -30
  217. package/src/cli/attach.ts +257 -0
  218. package/src/cli/commands/cells.ts +104 -0
  219. package/src/cli/commands/cred.ts +44 -0
  220. package/src/cli/commands/doctor.ts +45 -37
  221. package/src/cli/commands/interactive.ts +4120 -664
  222. package/src/cli/commands/list.ts +21 -30
  223. package/src/cli/commands/providers.ts +17 -4
  224. package/src/cli/commands/releases.ts +60 -0
  225. package/src/cli/commands/settings.ts +75 -28
  226. package/src/cli/commands/status.ts +24 -21
  227. package/src/cli/config.ts +119 -4
  228. package/src/cli/credentials.ts +1379 -0
  229. package/src/cli/download.ts +80 -0
  230. package/src/cli/env.ts +22 -7
  231. package/src/cli/envelope.ts +10 -6
  232. package/src/cli/errors.ts +92 -0
  233. package/src/cli/inference.ts +8 -1
  234. package/src/cli/inkView.ts +969 -0
  235. package/src/cli/legacy/modelKey.ts +35 -0
  236. package/src/cli/livePrompt.ts +615 -0
  237. package/src/cli/main.ts +206 -76
  238. package/src/cli/modelkey.ts +124 -0
  239. package/src/cli/outboxSync.ts +231 -0
  240. package/src/cli/plain.ts +260 -0
  241. package/src/cli/proofs.ts +27 -0
  242. package/src/cli/ref.ts +5 -4
  243. package/src/cli/releaseNotice.ts +200 -0
  244. package/src/cli/sdk.ts +87 -7
  245. package/src/cli/settings.ts +275 -25
  246. package/src/cli/textfit.ts +95 -0
  247. package/src/constants.ts +1 -1
  248. package/src/context.ts +28 -0
  249. package/src/index.ts +50 -7
  250. package/src/legacy/modelKey.ts +80 -0
  251. package/src/legacy/serveProofV1.ts +124 -0
  252. package/src/provider-catalog.json +3 -2
  253. package/src/secretEnv.ts +18 -3
  254. package/src/types.ts +60 -1
  255. package/src/viemErrors.ts +39 -0
package/src/cli/main.ts CHANGED
@@ -14,8 +14,12 @@
14
14
  import { parseArgs } from 'node:util';
15
15
  import { readFileSync } from 'node:fs';
16
16
  import { join } from 'node:path';
17
- import { CliError, toCliError, EXIT } from './errors';
18
- import { emitError, note, print } from './envelope';
17
+ import { CliError, EXIT, isCancelled } from './errors';
18
+ import { plainCliError } from './plain';
19
+ import { parseAgentRef } from './ref';
20
+ import { didYouMean, fitLines, termWidth } from './textfit';
21
+ import { cleanCell } from './commands/cells';
22
+ import { emitError, emitOk, note, print } from './envelope';
19
23
  import { readEnv } from './env';
20
24
  import { moveRenamedAttestor } from './config';
21
25
  import type { CommandContext, CommandRun } from './types';
@@ -25,11 +29,14 @@ import { run as list } from './commands/list';
25
29
  import { run as update } from './commands/update';
26
30
  import { run as settings } from './commands/settings';
27
31
  import { run as providers } from './commands/providers';
32
+ import { run as releases } from './commands/releases';
33
+ import { dueReleaseNotice } from './releaseNotice';
34
+ import { run as cred } from './commands/cred';
28
35
  import { run as interactive } from './commands/interactive';
29
36
 
30
- /** Diagnostics subcommands. Anything else (bare, or a leading agent ref)
31
- * routes to the default interactive shell. */
32
- const COMMANDS: Record<string, CommandRun> = { doctor, status, list, update, settings, providers };
37
+ /** One-shot commands. Bare, an agent ref or `use <agent>` opens the
38
+ * interactive shell instead (see route). */
39
+ const COMMANDS: Record<string, CommandRun> = { doctor, status, list, update, settings, cred, providers, releases };
33
40
 
34
41
  // Help is written for LLM consumption as much as for humans: exact syntax,
35
42
  // env contract, exit-code semantics, runnable examples — it is the ground
@@ -38,62 +45,68 @@ const HELP = `0g-agentdna — 0G AgentDNA CLI for the AgenticID protocol
38
45
  (ships with @0gfoundation/0g-agentdna; no separate install)
39
46
 
40
47
  USAGE
41
- 0g-agentdna [agent] [options] interactive chat (default)
42
- 0g-agentdna <command> [options] diagnostics
43
-
44
- INTERACTIVE (default — no command)
45
- 0g-agentdna Open the manager REPL. Its commands:
46
- list agents on this attestor (* = yours)
47
- use <agentId|seal> enter YOUR agent's session, in
48
- ANY phase (lifecycle is inside)
49
- hello <agentId|seal> any agent's public /hello
50
- (identity + services + proof;
51
- banks a rating ticket if a
52
- wallet is configured)
53
- call <id> [path] use an agent's service (banks
54
- a rating ticket)
55
- rate <id> [score] rate an agent on-chain, spending
56
- a ticket from call/hello (<1h)
57
- deploy new-agent wizard, then chat
58
- start/stop/reset <id> lifecycle without entering
59
- the session (reset asks the
60
- framework + key)
61
- settings <id> [k=v] show/change the agent's
62
- configuration document
63
- balance prepaid balance + burn rate
64
- deposit [og] fund the prepaid balance
65
- withdraw [og] refund prepaid funds (time-
66
- locked; bare claims)
67
- ack acknowledge the TEE trust
68
- root (implicit in deploy/
69
- start/reset)
70
- login guided setup: attestor URL,
71
- owner key, provider, inference key (Enter
72
- keeps current; keys echo *)
73
- whoami · help · quit
74
- 0g-agentdna <agent> Shortcut: use that agent directly, then drop to
75
- the manager REPL on /back.
76
-
77
- In a session: type to talk; Esc / Ctrl-C interrupts
78
- the turn in flight (and cancels a /start or /reset
79
- wait). Slash: /hello /balance /topup [og] /stop
80
- /start /reset /settings [k=v] /agentlog [n]
81
- /startuplog [n] /back (or /unuse) /quit. The framework (for /reset
82
- and the chat model selector) is picked by you, never
83
- guessed. Config persists to ~/.config/0g-agentdna
84
- (config.json + credentials at 0600); AGENTIC_* env
85
- vars always override the files.
48
+ 0g-agentdna [agent] [options] the interactive shell (default)
49
+ 0g-agentdna <command> [options] one-shot commands (below)
50
+
51
+ INTERACTIVE SHELL (default — no command)
52
+ 0g-agentdna Open the shell at its manager prompt (0g-agentdna>).
53
+ Its commands (\`help\` there lists them all):
54
+ list agents on this attestor (* = yours)
55
+ use <agentId|seal> enter YOUR agent's session, in ANY phase
56
+ (lifecycle is inside)
57
+ hello <agentId|seal> [full]
58
+ any agent's public /hello (identity + proof,
59
+ services one per line, owner routes on one line;
60
+ full: every field; banks a rating ticket if a
61
+ wallet is set)
62
+ call <id> [path] use an agent's service (banks a rating ticket)
63
+ rate <id> [score] rate an agent on-chain, spending a ticket from
64
+ call/hello (<1h)
65
+ deploy new-agent wizard, then chat
66
+ start/stop/reset <id>
67
+ lifecycle without entering the session (reset
68
+ asks the framework + key)
69
+ settings <id> [k=v] show/change the agent's configuration document
70
+ balance prepaid balance + burn rate
71
+ deposit [og] fund the prepaid balance
72
+ withdraw [og] refund prepaid funds (time-locked; bare claims)
73
+ ack acknowledge the TEE trust root (implicit in
74
+ deploy/start/reset)
75
+ login [provider] guided setup: attestor URL, owner key, each
76
+ provider's model key (Enter keeps the current
77
+ value; keys echo *)
78
+ doctor · status <id> · providers · releases
79
+ as the one-shot commands below
80
+ whoami · help · quit
81
+ 0g-agentdna <agent> Shortcut (also \`0g-agentdna use <agent>\`): enter
82
+ that agent's session; /back drops to the manager.
83
+
84
+ In a session: type to talk; Esc / Ctrl-C
85
+ interrupts the turn in flight (and cancels a
86
+ /start or /reset wait). Slash: /hello [full]
87
+ /balance /topup [og] /stop /start /reset
88
+ /settings [k=v] /agentlog [n] /startuplog [n]
89
+ /back (or /unuse) /quit. The framework (for
90
+ /reset and the chat model selector) is picked by
91
+ you, never guessed.
92
+ Config persists to ~/.config/0g-agentdna
93
+ (config.json + credentials at 0600); AGENTIC_*
94
+ env vars always override the files.
95
+ The shell's other words (login, deploy, balance, …) are not one-shot
96
+ commands: \`0g-agentdna login\` says to run \`0g-agentdna\` and type it
97
+ there. \`0g-agentdna help\` prints this text.
86
98
 
87
99
  COMMANDS
88
100
  doctor Check every deploy prerequisite (attestor reachable, RPC,
89
101
  wallet, gas, trust-root ack, sandbox balance). Each failing
90
102
  item prints a remedy. Exit 0 all green; exit 3 otherwise,
91
103
  carrying the FIRST failing check's code. Diagnostics only:
92
- the ack/deposit remedies are transactions (they need gas)
93
- executed via the deploy console or the SDK, not this CLI.
104
+ its ack and deposit remedies are transactions you run in
105
+ the shell (\`ack\`, \`deposit\`).
94
106
  status <agent> One agent's full picture: phase, agentId/sealId/agentSeal,
95
- url, failure reason. <agent> is a decimal agentId (33) or a
96
- 0x… sealId — the CLI converts between them for you.
107
+ failure reason (--json also carries the container url).
108
+ <agent> is a decimal agentId (33) or a 0x… sealId — the
109
+ CLI converts between them for you.
97
110
  list List deployments. --mine (owner-signed, needs
98
111
  AGENTIC_PRIVATE_KEY) adds owner-only fields such as the
99
112
  failure reason and sandboxId.
@@ -102,8 +115,12 @@ COMMANDS
102
115
  thinks with, and how hard); with key=value assignments,
103
116
  change it. Keys: provider, model, thinking (low|high|max),
104
117
  others (opaque JSON for that framework's own knobs —
105
- quote it: others='{"a": 1}'). Assignments merge into the
106
- stored document; an empty value (thinking=) clears a field.
118
+ quote it: others='{"a": 1}'), and on 0g-harness sealed and
119
+ harness (a version's sha256 from the trust registry's
120
+ lists, which settings <agent> versions prints; the agent
121
+ runs a pick while it stays listed). Assignments merge into
122
+ the stored document; an empty value (thinking=) clears a
123
+ field.
107
124
  The document is the owner's, so BOTH reading and writing
108
125
  are owner-signed and need AGENTIC_PRIVATE_KEY. A write is a
109
126
  compare-and-swap against the version just read: if another
@@ -111,7 +128,54 @@ COMMANDS
111
128
  3, SETTINGS_CONFLICT) rather than overwriting them. The
112
129
  model advisory uses its provider catalog. Provider changes
113
130
  need a matching key and image support, then require reset.
131
+ cred <agent> [ls|set|rm|connect|disconnect|reveal|pending|approve|deny|log]
132
+ The owner's credentials for the agent (API keys, tokens).
133
+ The agent writes [[credential:<name>]] where a key goes;
134
+ sealed fills it in on the way out, only for the hosts and
135
+ positions you allowed, and hides it in responses. The
136
+ value is read from stdin or a prompt that does not echo,
137
+ never from an argument, and is sealed to the agent before
138
+ it leaves this machine.
139
+ cred <agent> list (never values)
140
+ cred <agent> set <name> [k=v …] add or change one.
141
+ Keys: preset=<name> (see cred presets), host=a,b,
142
+ header='Name: … {v} …', basic=<user>, query=<param>,
143
+ body=<field>, path=yes, use=inject|token_only|sign,
144
+ signer=<json> (with use=sign: sigv4, hmac, jwt or
145
+ wallet; the key is never sent, sealed signs with it),
146
+ token=<json>, writeback=yes|no, reveal=yes|no,
147
+ expires=<YYYY-MM-DD|unix>, desc=…
148
+ preset=oauth2-refresh|oauth2-client token_url=…
149
+ client_id=… api_host=… [client_secret=<entry>]
150
+ [scope=…]: sealed trades the value for access tokens
151
+ cred <agent> rm <name> remove one
152
+ cred <agent> connect <name> <mcp-url>
153
+ connect an MCP server:
154
+ log in through the link
155
+ it prints; sealed keeps
156
+ the tokens, refreshes
157
+ them
158
+ cred <agent> disconnect <name> revoke it at the server
159
+ (when it offers that)
160
+ and remove it
161
+ cred <agent> reveal <name> on|off the agent may read it
162
+ cred <agent> pending requests waiting
163
+ cred <agent> approve|deny <id> decide one (id prefix)
164
+ cred <agent> log [n] what the agent did
165
+ cred pending counts, all your agents
166
+ cred notify [<email>|off] email when one waits
167
+ cred presets presets, where to
168
+ create each key
169
+ Owner-signed (all but cred presets); needs
170
+ AGENTIC_PRIVATE_KEY. A write is a compare-and-swap like
171
+ settings (CREDENTIALS_CONFLICT, exit 3).
114
172
  providers Read the platform provider registry (--json for export).
173
+ releases The attestor's release notices: what each release
174
+ changed, the images it replaces and when their
175
+ transition period ends; with AGENTIC_PRIVATE_KEY, which
176
+ of your agents still run one (reset them before then).
177
+ Other commands print a short notice when one is due:
178
+ weekly, daily in the last 7 days (stderr, terminals only).
115
179
  update Self-update: compare against the npm registry and
116
180
  npm install -g the latest (a git-checkout/npm-link copy
117
181
  is reported, not overwritten). --json only reports.
@@ -128,11 +192,12 @@ OPTIONS
128
192
  --help Show this help.
129
193
  --version Print the package version (identical to the SDK's).
130
194
 
131
- ENVIRONMENT
132
- AGENTIC_ATTESTOR_URL required. Attestor base URL — one URL selects the
133
- whole environment (contracts, RPC, appIds).
134
- AGENTIC_PRIVATE_KEY optional. Owner key (0x… hex). Env only — there is
135
- deliberately no flag for it.
195
+ ENVIRONMENT (each overrides what \`login\` saved)
196
+ AGENTIC_ATTESTOR_URL required unless saved by login. Attestor base URL —
197
+ one URL selects the whole environment (contracts,
198
+ RPC, appIds).
199
+ AGENTIC_PRIVATE_KEY optional. Owner key (0x… hex). Env or login only —
200
+ there is deliberately no flag for it.
136
201
  AGENTIC_RPC_URL optional. Overrides the RPC the attestor advertises.
137
202
  AGENTDNA_API_KEY_PROVIDER / AGENTDNA_API_KEY
138
203
  optional, set together. Inference key for deploy/
@@ -150,15 +215,17 @@ ENVIRONMENT
150
215
  EXIT CODES
151
216
  0 success · 1 unknown · 2 usage error (incl. unknown command/agent — branch
152
217
  on error.code to tell them apart) · 3 fixable precondition (run the error's
153
- remedy, then retry) · 4 timeout (check again later) · 5 auth (stop)
218
+ remedy, then retry) · 4 timeout (check again later) · 5 auth (stop) ·
219
+ 130 cancelled at a prompt (Ctrl-C)
154
220
 
155
221
  EXAMPLES
156
- 0g-agentdna # deploy a new agent and chat
157
- 0g-agentdna 286 # attach to agent 286 and chat
222
+ 0g-agentdna # the shell: list, deploy, chat, …
223
+ 0g-agentdna 286 # straight into agent 286's session
158
224
  0g-agentdna doctor
159
225
  0g-agentdna status 33
160
226
  0g-agentdna settings 286
161
227
  0g-agentdna settings 286 model=0gm-1.0-35b-a3b thinking=high
228
+ echo "$GITHUB_TOKEN" | 0g-agentdna cred 286 set github preset=github
162
229
  0g-agentdna list --mine --phase failed --json | jq -r '.data[].sealId'`;
163
230
 
164
231
  /** Package version, read at runtime from the SDK's own package.json
@@ -168,6 +235,44 @@ function packageVersion(): string {
168
235
  return (JSON.parse(raw) as { version: string }).version;
169
236
  }
170
237
 
238
+ /** The interactive shell's words that are not one-shot commands. */
239
+ const SHELL_WORDS = [
240
+ 'login', 'whoami', 'deploy', 'balance', 'deposit', 'withdraw', 'ack', 'hello', 'call', 'rate',
241
+ 'start', 'stop', 'reset', 'retry', 'clone', 'transfer', 'authorizer', 'grant', 'revoke', 'quit',
242
+ ];
243
+
244
+ /**
245
+ * Which command runs: a one-shot command by name; the interactive shell for
246
+ * nothing, an agent reference (an agentId is decimal and a sealId 0x…, so
247
+ * neither collides with a command name) or `use <agent>`. A word of the
248
+ * shell's is refused with where to type it; any other word is an unknown
249
+ * command, with the nearest known one when it looks like a typo.
250
+ */
251
+ function route(positionals: string[]): { run: CommandRun; rest: string[]; command?: string } {
252
+ const [first, ...rest] = positionals;
253
+ if (!first) return { run: interactive, rest: [] };
254
+ if (Object.prototype.hasOwnProperty.call(COMMANDS, first)) return { run: COMMANDS[first], rest, command: first };
255
+ if (first === 'use') {
256
+ parseAgentRef(rest[0]);
257
+ return { run: interactive, rest };
258
+ }
259
+ if (/^(?:\d+|0x[0-9a-fA-F]*)$/.test(first)) return { run: interactive, rest: positionals };
260
+ const typed = cleanCell(first);
261
+ if (SHELL_WORDS.includes(first)) {
262
+ throw new CliError('UNKNOWN_COMMAND', `\`${typed}\` is a command of the interactive shell, not a one-shot one`, {
263
+ remedy: `run \`0g-agentdna\` and type \`${cleanCell(positionals.join(' '))}\` there`,
264
+ });
265
+ }
266
+ const near = didYouMean(first, ['help', ...Object.keys(COMMANDS), ...SHELL_WORDS]);
267
+ throw new CliError('UNKNOWN_COMMAND', `unknown command: ${typed}`, {
268
+ remedy: near === undefined
269
+ ? '0g-agentdna --help lists the commands'
270
+ : SHELL_WORDS.includes(near)
271
+ ? `did you mean \`${near}\`? It is a shell command: run \`0g-agentdna\` and type it there`
272
+ : `did you mean \`0g-agentdna ${near}\`?`,
273
+ });
274
+ }
275
+
171
276
  async function main(): Promise<number> {
172
277
  // parseArgs throws on unknown/malformed flags — surfaced as exit 2 below.
173
278
  const { values, positionals } = parseArgs({
@@ -184,7 +289,8 @@ async function main(): Promise<number> {
184
289
  });
185
290
 
186
291
  if (values.version) {
187
- print(packageVersion());
292
+ if (values.json) emitOk({ version: packageVersion() });
293
+ else print(packageVersion());
188
294
  return EXIT.OK;
189
295
  }
190
296
  if (values.help) {
@@ -192,14 +298,12 @@ async function main(): Promise<number> {
192
298
  return EXIT.OK;
193
299
  }
194
300
 
195
- // Claude-Code-style default: bare `0g-agentdna` (or with just an agent
196
- // ref, e.g. `0g-agentdna 286`) enters the interactive chat. The
197
- // diagnostics commands (doctor/status/list) are the only reserved words;
198
- // an agentId is decimal and a sealId is 0x…, so neither collides with a
199
- // command name — anything that isn't a known command routes to chat.
200
- const [first, ...rest] = positionals;
201
- const isCommand = !!first && first in COMMANDS;
202
- const run = isCommand ? COMMANDS[first] : interactive;
301
+ if (positionals[0] === 'help') {
302
+ print(HELP);
303
+ return EXIT.OK;
304
+ }
305
+ const { run, rest, command } = route(positionals);
306
+ const isCommand = command !== undefined;
203
307
 
204
308
  // The public attestors were renamed: a saved earlier address moves to the
205
309
  // current one before the environment is read.
@@ -209,10 +313,29 @@ async function main(): Promise<number> {
209
313
  const ctx: CommandContext = {
210
314
  env: readEnv(),
211
315
  json: values.json,
212
- positionals: isCommand ? rest : positionals,
316
+ positionals: rest,
213
317
  flags: { mine: values.mine, phase: values.phase },
214
318
  };
215
- await run(ctx);
319
+ // The release notice runs alongside a one-shot command and prints after it,
320
+ // on stderr, in a terminal only; it waits at most 1.5 s past the command.
321
+ const noticeAbort = new AbortController();
322
+ const notice = isCommand && command !== 'releases' && command !== 'update' && !ctx.json && process.stderr.isTTY
323
+ ? dueReleaseNotice(ctx.env, noticeAbort.signal)
324
+ : null;
325
+ try {
326
+ await run(ctx);
327
+ } catch (e) {
328
+ noticeAbort.abort();
329
+ throw e;
330
+ }
331
+ if (notice) {
332
+ const due = await Promise.race([notice, new Promise<null>((r) => setTimeout(() => r(null), 1500).unref())]);
333
+ noticeAbort.abort();
334
+ if (due) {
335
+ process.stderr.write(`\n${fitLines(due.lines.map((l) => ` ${l}`).join('\n'), termWidth(process.stderr))}\n`);
336
+ due.shown();
337
+ }
338
+ }
216
339
  return EXIT.OK;
217
340
  }
218
341
 
@@ -227,6 +350,13 @@ main()
227
350
  process.exitCode = code;
228
351
  })
229
352
  .catch((e: unknown) => {
353
+ // Ctrl-C at a one-shot command's prompt: the owner stopped it, nothing
354
+ // failed. 130 is the shell's code for an interrupted command.
355
+ if (isCancelled(e) && !wantJson) {
356
+ process.stderr.write('cancelled\n');
357
+ process.exitCode = 130;
358
+ return;
359
+ }
230
360
  // node:util's parseArgs errors carry ERR_PARSE_ARGS_* codes — usage, exit 2.
231
361
  const nodeCode = (e as { code?: string }).code ?? '';
232
362
  // Own wording, not node:util's raw parseArgs prose (its "place it at the
@@ -240,6 +370,6 @@ main()
240
370
  : 'malformed command-line arguments',
241
371
  { remedy: '0g-agentdna --help' },
242
372
  )
243
- : toCliError(e);
373
+ : plainCliError(e);
244
374
  process.exitCode = emitError(err, wantJson);
245
375
  });
@@ -0,0 +1,124 @@
1
+ /**
2
+ * @file modelkey.ts
3
+ * @description One model key per provider, wherever the owner first gives it.
4
+ *
5
+ * The key `login` keeps on this machine (the draft) is what every other entry
6
+ * point offers first; a key given anywhere replaces it. Deploy, reset,
7
+ * `cred <agent> set model` and a settings switch all ask through
8
+ * {@link pickModelKey}, so the owner meets the same question everywhere.
9
+ *
10
+ * A script (stdin piped, `--json`) is asked nothing: a key it pipes in is the
11
+ * new key, otherwise the draft is used.
12
+ */
13
+
14
+ import { modelKeyName } from '../Credentials';
15
+ import { saveApiKey } from './config';
16
+ import { CliError } from './errors';
17
+ import { configuredInferenceKey } from './inference';
18
+ import { resetKeyForOlderImages } from './legacy/modelKey';
19
+
20
+ /** How {@link pickModelKey} talks to whoever runs the CLI. */
21
+ export interface KeyPrompt {
22
+ /** A person answers at a terminal. False for a script: nothing is asked. */
23
+ interactive: boolean;
24
+ out(line: string): void;
25
+ /** Read a value without echoing it; for a script, what it piped in ('' for nothing). */
26
+ secret(prompt: string): Promise<string>;
27
+ /** A yes/no question; Enter answers `def`. Asked only when interactive. */
28
+ confirm(question: string, def: boolean): Promise<boolean>;
29
+ /** The draft store; defaults to the CLI's (`login`'s) on this machine. */
30
+ draft?: { get(provider: string): string | null; save(provider: string, key: string): void };
31
+ }
32
+
33
+ const machineDraft = {
34
+ get: (provider: string) => configuredInferenceKey(provider),
35
+ save: (provider: string, key: string) => saveApiKey(provider, key),
36
+ };
37
+
38
+ /**
39
+ * The model key for `provider`: the draft when the owner takes it, or a new
40
+ * key, which then replaces the draft. Null only when `optional` and the owner
41
+ * gives none (an agent that starts without a model key); otherwise a missing
42
+ * key is an error.
43
+ */
44
+ export async function pickModelKey(provider: string, io: KeyPrompt, opts: { optional?: boolean } = {}): Promise<string | null> {
45
+ const draft = io.draft ?? machineDraft;
46
+ const saved = draft.get(provider);
47
+ const keep = (key: string): string => {
48
+ // Checked before it replaces the key on this machine: a script's stray
49
+ // input must not.
50
+ if (/[\u0000-\u001f\u007f]/.test(key)) {
51
+ throw new CliError('BAD_FLAG', 'a model key is one line of printable characters', { remedy: `give the ${provider} key alone` });
52
+ }
53
+ draft.save(provider, key);
54
+ if (io.interactive) io.out(`saved as your ${provider} key on this machine`);
55
+ // An environment variable (API_KEY, AGENTDNA_API_KEY…) still wins over it.
56
+ if (draft.get(provider) !== key) io.out(`note: an environment variable sets the ${provider} key and takes precedence over the saved one`);
57
+ return key;
58
+ };
59
+ if (!io.interactive) {
60
+ const piped = (await io.secret('')).trim();
61
+ if (piped) return keep(piped);
62
+ if (saved) return saved;
63
+ if (opts.optional) return null;
64
+ throw missing(provider);
65
+ }
66
+ if (saved && await io.confirm(`use the ${provider} key saved on this machine?`, true)) return saved;
67
+ const typed = (await io.secret(`${provider} model key (${opts.optional ? 'Enter: none for now, ' : ''}Ctrl-C cancels): `)).trim();
68
+ if (typed) return keep(typed);
69
+ if (opts.optional) return null;
70
+ throw missing(provider);
71
+ }
72
+
73
+ /**
74
+ * Whether an agent may be created or reset with no model key: 0g-harness on
75
+ * 0g-compute starts without one (its model calls fail until one is set). On
76
+ * another provider sealed refuses a key it lacks, and the other frameworks
77
+ * need one.
78
+ */
79
+ export function mayGoKeyless(framework: string, provider: string): boolean {
80
+ return framework === '0g-harness' && provider === '0g-compute';
81
+ }
82
+
83
+ /**
84
+ * The model key a reset takes.
85
+ *
86
+ * The credential set holding the provider's key: the new container gets it
87
+ * from the set (older images: cli/legacy/modelKey.ts). Otherwise the owner is
88
+ * asked as everywhere (see mayGoKeyless for skipping). LEGACY(model-key):
89
+ * `keepStoredModelKey` in the result goes with the older images.
90
+ */
91
+ export async function resetModelKey(
92
+ cred: { get(sealId: `0x${string}`): Promise<{ definitions: Array<{ name: string }> }> },
93
+ sealId: `0x${string}`,
94
+ provider: string,
95
+ framework: string,
96
+ io: KeyPrompt,
97
+ ): Promise<{ apiKey?: string; keepStoredModelKey: boolean }> {
98
+ const name = modelKeyName(provider);
99
+ const cur = await cred.get(sealId).catch(() => undefined);
100
+ if (cur?.definitions.some((d) => d.name === name)) {
101
+ return resetKeyForOlderImages(provider, name, (io.draft ?? machineDraft).get(provider), io.out, () => pickModelKey(provider, io, { optional: true }));
102
+ }
103
+ const key = await pickModelKey(provider, io, { optional: mayGoKeyless(framework, provider) });
104
+ return { apiKey: key ?? undefined, keepStoredModelKey: false };
105
+ }
106
+
107
+ function missing(provider: string): CliError {
108
+ return new CliError('INFERENCE_KEY_REQUIRED', `no ${provider} model key`, {
109
+ remedy: `give one at the prompt, pipe it in, or save it with login ${provider}`,
110
+ });
111
+ }
112
+
113
+ /** The prompt of a REPL: questions through `ask`, secrets through `secret`. */
114
+ export function replKeyPrompt(ask: (q: string) => Promise<string>, secret: (p: string) => Promise<string>, out: (line: string) => void): KeyPrompt {
115
+ return {
116
+ interactive: true,
117
+ out,
118
+ secret,
119
+ confirm: async (question, def) => {
120
+ const a = (await ask(`${question} [${def ? 'Y/n' : 'y/N'}] `)).trim().toLowerCase();
121
+ return a ? a.startsWith('y') : def;
122
+ },
123
+ };
124
+ }