@0gfoundation/0g-agentdna 0.4.0 → 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 +87 -6
  167. package/dist/cli/settings.d.ts.map +1 -1
  168. package/dist/cli/settings.js +270 -18
  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 +272 -22
  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
@@ -11,11 +11,11 @@
11
11
  * JSON mode: `data` IS the row array (empty list → `[]`, exit 0 — not an
12
12
  * error) and carries the FULL row (sealId, url, sandboxId, framework, whole
13
13
  * addresses, …). Human mode is the glance: the columns that identify a row
14
- * and expose nesting. Unminted rows render their sealId prefix in the
15
- * AGENTID cell (`0x` + 10 hex, the paste-back form the sealPrefix ref
16
- * resolves — an unminted row has no agentId, so the prefix is its only
17
- * handle); NAME is last and sanitized (owner-controlled JSON cannot forge
18
- * the table).
14
+ * and expose nesting, fitted to the terminal's width (./cells: listLayout).
15
+ * Unminted rows render their sealId prefix in the AGENTID cell (`0x` + 10
16
+ * hex, the paste-back form the sealPrefix ref resolves — an unminted row has
17
+ * no agentId, so the prefix is its only handle); NAME is last and sanitized
18
+ * (owner-controlled JSON cannot forge the table).
19
19
  *
20
20
  * Nesting visibility (follow-up to #187 / #183-c4): the AGENTSEAL and OWNER
21
21
  * columns use the same short form, so an agent-owned agent is visible at a
@@ -28,7 +28,8 @@
28
28
  */
29
29
 
30
30
  import { buildClient } from '../sdk';
31
- import { cellText, ownerCellText, sealToAgentMap, shortAddr, trustedCell } from './cells';
31
+ import { cleanCell, listCells, listHeader, listLayout, ownerColumnWidth, sealToAgentMap } from './cells';
32
+ import { termWidth } from '../textfit';
32
33
  import { CliError } from '../errors';
33
34
  import { emitOk, print } from '../envelope';
34
35
  import type { CommandContext } from '../types';
@@ -39,6 +40,14 @@ const PHASES = ['deploying', 'running', 'stopped', 'offline', 'failed'];
39
40
  export async function run(ctx: CommandContext): Promise<void> {
40
41
  // Validate --phase BEFORE any network work: a typo'd phase must be a loud
41
42
  // exit-2, not a plausible-looking empty success (agent-walkthrough finding).
43
+ if (ctx.positionals.length) {
44
+ // An agent ref there wants that agent's picture; anything else, the help.
45
+ const word = cleanCell(ctx.positionals[0]);
46
+ const isRef = /^(?:\d+|0x[0-9a-fA-F]{8,64})$/.test(ctx.positionals[0]);
47
+ throw new CliError('BAD_FLAG', `list takes no argument (got "${word}")`, {
48
+ remedy: isRef ? `0g-agentdna status ${word} # one agent's full picture` : '0g-agentdna --help',
49
+ });
50
+ }
42
51
  if (ctx.flags.phase && !PHASES.includes(ctx.flags.phase)) {
43
52
  throw new CliError('BAD_FLAG', `--phase must be one of ${PHASES.join('|')}, got "${ctx.flags.phase}"`, {
44
53
  remedy: '0g-agentdna list --phase failed',
@@ -65,31 +74,13 @@ export async function run(ctx: CommandContext): Promise<void> {
65
74
  // Nesting annotation map, built from `all`, not `rows`: a --phase filter
66
75
  // must not strip the annotation off a child row whose parent falls outside
67
76
  // the filtered view (./cells: sealToAgentMap). The OWNER cell pads but
68
- // never truncates its trusted annotation (./cells: trustedCell).
77
+ // never truncates its trusted annotation (./cells: trustedCell). Cells are
78
+ // sanitized in ./cells (shared with the shell's listing — a name must not
79
+ // be able to forge a row in either), and the columns fit the terminal.
69
80
  const sealToAgent = sealToAgentMap(all);
70
- const ownerCell = (owner: string | null | undefined): string => ownerCellText(owner, sealToAgent);
71
- // Sanitising lives in ./cells (shared with the REPL's listing — a name
72
- // must not be able to forge a row in either): sequence bodies stripped
73
- // before control bytes, newlines → space, code-point truncation.
74
- const cell = cellText;
75
- // An unminted row has no agentId, owner, agentSeal or name — its sealId
76
- // prefix is the only handle (F12: paste it back into any command; the
77
- // sealPrefix ref resolves it uniquely). Render it in the AGENTID cell so
78
- // two unminted rows stay distinguishable in human mode.
79
- const idCell = (r: { agentId: bigint | number | null; sealId: string }): string => {
80
- if (r.agentId != null) return cell(r.agentId, 13);
81
- return cell(`0x${r.sealId.slice(2, 12)}`, 13);
82
- };
83
- print(
84
- `${'AGENTID'.padEnd(13)}${'PHASE'.padEnd(11)}${'FRAMEWORK'.padEnd(12)}` +
85
- `${'AGENTSEAL'.padEnd(13)}${'OWNER'.padEnd(24)}NAME`,
86
- );
87
- for (const r of rows) {
88
- print(
89
- `${idCell(r)}${cell(r.phase, 11)}${cell(r.framework, 12)}` +
90
- `${cell(shortAddr(r.agentSeal), 13)}${trustedCell(ownerCell(r.owner), 24)}${cell(r.name, 19)}`,
91
- );
92
- }
81
+ const layout = listLayout(termWidth(), 0, ownerColumnWidth(rows.map((r) => r.owner), sealToAgent), 19);
82
+ print(listHeader(layout));
83
+ for (const r of rows) print(listCells(r, r.owner, sealToAgent, layout));
93
84
  print('');
94
85
  print(`${rows.length} deployment(s)${ctx.flags.phase ? ` (phase=${ctx.flags.phase})` : ''}${ctx.flags.mine ? ' — owner tier' : ''}`);
95
86
  }
@@ -1,16 +1,29 @@
1
1
  /** Read-only discovery of the platform provider registry. */
2
2
  import { buildClient } from '../sdk';
3
+ import { providerWebSearch, type InferenceProvider } from '../../Providers';
3
4
  import { CliError } from '../errors';
4
5
  import { emitOk, print } from '../envelope';
6
+ import { cleanCell } from './cells';
7
+ import { termWidth } from '../textfit';
5
8
  import type { CommandContext } from '../types';
6
9
 
10
+ /** The registry as an aligned table: id, name, formats, web search. On a
11
+ * terminal narrower than the table, NAME (the id says it) goes first. */
12
+ export function renderProviders(providers: readonly InferenceProvider[], width?: number): string[] {
13
+ const all = [
14
+ ['ID', 'NAME', 'FORMATS', 'WEB SEARCH'],
15
+ ...providers.map((p) => [p.id, p.name, p.formats.join(', '), providerWebSearch(p) ?? '-'].map((c) => cleanCell(c))),
16
+ ];
17
+ const span = (rs: string[][]): number => rs[0].reduce((n, _, i) => n + Math.max(...rs.map((r) => [...r[i]].length)) + 2, 0);
18
+ const rows = width && span(all) > width ? all.map((r) => r.filter((_, i) => i !== 1)) : all;
19
+ const widths = rows[0].map((_, i) => Math.max(...rows.map((r) => [...r[i]].length)));
20
+ return rows.map((r) => r.map((c, i) => (i === r.length - 1 ? c : c.padEnd(widths[i] + 2))).join('').trimEnd());
21
+ }
22
+
7
23
  export async function run(ctx: CommandContext): Promise<void> {
8
24
  if (ctx.positionals.length) throw new CliError('BAD_FLAG', 'usage: providers (read-only)');
9
25
  const ag = await buildClient(ctx.env);
10
26
  const current = await ag.agent.getProviderRegistry();
11
27
  if (ctx.json) emitOk(current);
12
- else {
13
- print(`provider registry version ${current.version}`);
14
- for (const provider of current.providers) print(`${provider.id}\t${provider.name}\t${provider.formats.join(', ')}`);
15
- }
28
+ else for (const line of renderProviders(current.providers, termWidth())) print(line);
16
29
  }
@@ -0,0 +1,60 @@
1
+ /**
2
+ * @file releases.ts
3
+ * @description `0g-agentdna releases` — the attestor's release notices,
4
+ * newest first (what changed, the images each release replaces and the end
5
+ * of their transition period), and, with AGENTIC_PRIVATE_KEY, which of your
6
+ * agents still run a replaced image and by when to reset them.
7
+ *
8
+ * JSON mode: `data` is `{ releases, agents }`; `agents` is null without a
9
+ * wallet, else `[{ agent, migrate }]`.
10
+ */
11
+
12
+ import { fetchReleases } from '../../Releases';
13
+ import { CliError, shellTo } from '../errors';
14
+ import { attestorUnreachable } from '../sdk';
15
+ import { emitOk, print } from '../envelope';
16
+ import { requireAttestorUrl } from '../env';
17
+ import { dateOf, myMigrations, notesOf, zhLocale, type AffectedAgent } from '../releaseNotice';
18
+ import type { CommandContext } from '../types';
19
+
20
+ const STATE_TEXT: Record<string, string> = {
21
+ recommended: 'please move',
22
+ soon: '7 days or less left',
23
+ overdue: 'transition period over: its next boot may be refused',
24
+ };
25
+
26
+ export async function run(ctx: CommandContext): Promise<void> {
27
+ if (ctx.positionals.length) throw new CliError('BAD_FLAG', 'usage: releases (read-only)');
28
+ const url = requireAttestorUrl(ctx.env);
29
+ const releases = await fetchReleases(url).catch((e: unknown) => { throw attestorUnreachable(ctx.env, e); });
30
+ let agents: AffectedAgent[] | null = null;
31
+ const key = ctx.env.privateKey;
32
+ if (key && /^0x[0-9a-fA-F]{64}$/.test(key)) agents = await myMigrations(url, key);
33
+ if (ctx.json) {
34
+ emitOk({ releases, agents });
35
+ return;
36
+ }
37
+ if (!releases.length) {
38
+ print('no release notices on this attestor');
39
+ return;
40
+ }
41
+ const zh = zhLocale();
42
+ for (const r of releases) {
43
+ print(`AgentDNA ${r.version} (${dateOf(r.publishedAt)})`);
44
+ for (const line of notesOf(r, zh).split('\n')) print(` ${line}`);
45
+ for (const m of r.migrate) {
46
+ print(` replaces the ${m.framework} image ${m.imageHash.slice(0, 10)}…: move by ${dateOf(m.until)}${m.urgent ? ' (security fix: may be retired sooner)' : ''}`);
47
+ }
48
+ print('');
49
+ }
50
+ if (agents === null) {
51
+ print('Set AGENTIC_PRIVATE_KEY to see which of your agents to move.');
52
+ } else if (!agents.length) {
53
+ print('Your agents: none runs a replaced image.');
54
+ } else {
55
+ print(`Your agents to move — they keep running meanwhile; ${shellTo('reset <agent>', 'move one')}:`);
56
+ for (const a of agents) {
57
+ print(` ${a.agent} ${a.migrate.framework} by ${dateOf(a.migrate.until)} ${STATE_TEXT[a.migrate.state] ?? a.migrate.state}${a.migrate.urgent ? ', security fix' : ''}`);
58
+ }
59
+ }
60
+ }
@@ -21,19 +21,24 @@
21
21
  import type { Hash } from 'viem';
22
22
  import type { AgenticID } from '../../AgenticID';
23
23
  import { buildClient } from '../sdk';
24
- import { CliError } from '../errors';
24
+ import { CliError, cmdStep, setAgentAtHand, shellStep } from '../errors';
25
+ import { explainError } from '../plain';
25
26
  import { emitOk, note, print } from '../envelope';
26
27
  import { parseAgentRef, type AgentRef } from '../ref';
27
- import { applyAssignments, assertModelPresent, assertOthersFitFramework, parseAssignments, renderSettings } from '../settings';
28
+ import {
29
+ VERSION_KEYS, applyAssignments, assertModelFitsFramework, touchesModel, assertModelPresent, assertSubagentDefaultOffered, assertOthersFitFramework, assertVersionsFitFramework,
30
+ isHarnessFramework, renderListedVersions, renderSettings, renderVersionsLine, settingsArgs,
31
+ } from '../settings';
28
32
  import { SettingsConflictError } from '../../Settings';
29
33
  import type { CommandContext } from '../types';
30
34
  import { changesProvider } from '../../Providers';
31
- import { requireConfiguredInferenceKey, requiresProviderReset } from '../inference';
35
+ import { configuredInferenceKey, requireConfiguredInferenceKey, requiresProviderReset } from '../inference';
36
+ import { commandKeyPrompt, ensureModelKey, readSecret } from '../credentials';
32
37
 
33
38
  const ZERO_HASH = `0x${'0'.repeat(64)}` as Hash;
34
39
 
35
40
  /** agentId | sealId | unique sealId prefix → the sealId the attestor keys on. */
36
- async function resolveSealId(ag: AgenticID, ref: AgentRef, raw: string): Promise<Hash> {
41
+ export async function resolveSealId(ag: AgenticID, ref: AgentRef, raw: string): Promise<Hash> {
37
42
  if (ref.kind === 'sealId') return ref.sealId;
38
43
  if (ref.kind === 'sealPrefix') {
39
44
  const hits = (await ag.agent.listDeployments()).filter((r) =>
@@ -44,8 +49,8 @@ async function resolveSealId(ag: AgenticID, ref: AgentRef, raw: string): Promise
44
49
  hits.length ? 'BAD_AGENT_REF' : 'AGENT_NOT_FOUND',
45
50
  hits.length
46
51
  ? `"${raw}" matches ${hits.length} agents — add more hex chars`
47
- : `no agent matching ${raw} on this attestor`,
48
- { remedy: '0g-agentdna list # to discover existing agents' },
52
+ : `agent ${raw} does not exist on this attestor`,
53
+ { remedy: `${cmdStep('list')} shows the agents here` },
49
54
  );
50
55
  }
51
56
  return hits[0].sealId;
@@ -53,7 +58,7 @@ async function resolveSealId(ag: AgenticID, ref: AgentRef, raw: string): Promise
53
58
  const seal = await ag.agent.getSealId(ref.agentId).catch(() => ZERO_HASH);
54
59
  if (seal === ZERO_HASH) {
55
60
  throw new CliError('AGENT_NOT_FOUND', `agent ${ref.agentId} has no sealId on chain`, {
56
- remedy: '0g-agentdna list # to discover existing agents',
61
+ remedy: `${cmdStep('list')} shows the agents here`,
57
62
  });
58
63
  }
59
64
  return seal;
@@ -62,8 +67,10 @@ async function resolveSealId(ag: AgenticID, ref: AgentRef, raw: string): Promise
62
67
  export async function run(ctx: CommandContext): Promise<void> {
63
68
  const raw = ctx.positionals[0];
64
69
  const ref = parseAgentRef(raw);
70
+ setAgentAtHand(raw ?? null);
65
71
  // Grammar errors are usage errors — raise them before any network work.
66
- const assignments = parseAssignments(ctx.positionals.slice(1));
72
+ // `versions` alone asks for the versions to pick from.
73
+ const { versions: versionsView, assignments } = settingsArgs(ctx.positionals.slice(1));
67
74
  const writing = assignments.length > 0;
68
75
 
69
76
  // The document is owner-gated in both directions, so a show needs the key
@@ -74,41 +81,82 @@ export async function run(ctx: CommandContext): Promise<void> {
74
81
  // No row for this seal — a wrong attestor or a wrong id, not an internal fault.
75
82
  if (/HTTP 404/.test(e.message)) {
76
83
  throw new CliError('AGENT_NOT_FOUND', `no deployment for seal ${sealId} on this attestor`, {
77
- remedy: '0g-agentdna list # to discover existing agents',
84
+ remedy: `${cmdStep('list')} shows the agents here`,
78
85
  });
79
86
  }
80
87
  throw e;
81
88
  });
82
89
 
83
90
  if (!writing) {
91
+ // A 0g-harness agent can be pinned to versions the trust registry lists:
92
+ // the show says which it runs on one line, `versions` lists them all.
93
+ // Advisory: no registry, or an unreadable one, shows nothing.
94
+ const framework = await frameworkOf(ctx.env.attestorUrl, sealId);
95
+ const harness = isHarnessFramework(framework);
96
+ const listed = harness ? await ag.agent.listedVersions().catch(() => null) : null;
84
97
  if (ctx.json) {
85
- emitOk({ sealId, settings: current, version });
98
+ emitOk({ sealId, settings: current, version, ...(listed ? { listedVersions: { sealed: listed.sealed, harness: listed.harness } } : {}) });
99
+ return;
100
+ }
101
+ if (versionsView) {
102
+ if (!harness) print(`this agent runs ${framework ?? 'another framework'} — only a 0g-harness agent has versions to pick`);
103
+ else if (!listed) print('the trust registry could not be read — no versions to show');
104
+ else for (const line of renderListedVersions(listed, current?.versions)) print(line);
86
105
  return;
87
106
  }
88
107
  for (const line of renderSettings(current)) print(line);
108
+ if (listed) {
109
+ print(renderVersionsLine(listed, current?.versions));
110
+ print(`pin a version: 0g-agentdna settings ${raw} versions`);
111
+ }
89
112
  return;
90
113
  }
91
114
 
92
- // Before anything is signed: a 0g-harness switch in others= for an agent that runs
93
- // another framework does nothing there, or worse (cli/settings.ts).
94
- if (assignments.some((a) => a.key === 'others' && a.value !== undefined)) {
95
- assertOthersFitFramework(assignments, await frameworkOf(ctx.env.attestorUrl, sealId));
115
+ // Before anything is signed: a 0g-harness switch in others=, or a version
116
+ // pick, for an agent that runs another framework does nothing there, or
117
+ // worse (cli/settings.ts).
118
+ const frameworkBound = assignments.some(
119
+ (a) => (a.key === 'others' || (VERSION_KEYS as readonly string[]).includes(a.key)) && a.value !== undefined,
120
+ );
121
+ if (frameworkBound) {
122
+ const framework = await frameworkOf(ctx.env.attestorUrl, sealId);
123
+ assertOthersFitFramework(assignments, framework);
124
+ assertVersionsFitFramework(assignments, framework);
96
125
  }
97
126
  const next = applyAssignments(current, assignments);
98
127
  // Before anything is signed: a document with no model is the one state the
99
- // container cannot boot from and last-known-good cannot cover.
128
+ // container cannot boot from and last-known-good cannot cover; a model
129
+ // that cannot call tools fails every turn of a tool-driven framework.
100
130
  assertModelPresent(next, current !== null);
101
- let pendingReset = changesProvider(current, next);
102
- if (pendingReset) requireConfiguredInferenceKey(next.provider ?? '0g-compute');
131
+ assertSubagentDefaultOffered(next);
132
+ await assertModelFitsFramework(assignments, next, await frameworkOf(ctx.env.attestorUrl, sealId), (provider) => ag.agent.listModelCaps({ provider }));
133
+ const base = await runningServeBase(ctx.env.attestorUrl, sealId);
134
+ // The agent takes a provider switch only with a key for the new provider
135
+ // in its credential set: asked for (Enter takes the key login saved) and
136
+ // stored first. An image from before model keys in the set takes it at a
137
+ // reset with the key.
138
+ let pendingReset = false;
139
+ if (changesProvider(current, next)) {
140
+ const provider = next.provider ?? '0g-compute';
141
+ const keyIO = { json: ctx.json, out: note, secret: readSecret, keyPrompt: commandKeyPrompt(ctx.json, note, { readPipe: false }) };
142
+ if (await ensureModelKey(ag, sealId, provider, keyIO, base ? { agentUrl: base } : undefined) === 'unsupported') {
143
+ requireConfiguredInferenceKey(provider);
144
+ pendingReset = true;
145
+ }
146
+ }
103
147
  const warnings: string[] = [];
104
148
  // The catalog advisory runs inside setSettings, before it signs.
105
149
  const written = await ag.agent
106
150
  .setSettings(sealId, next, {
107
151
  baseVersion: version,
108
- onWarn: (w) => {
109
- warnings.push(w);
110
- note(`warning: ${w}`);
111
- },
152
+ // Only a write that sets the model or the provider: the advisory is
153
+ // about that choice, not repeated on every later write.
154
+ ...(touchesModel(assignments) ? {
155
+ onWarn: (w: string) => {
156
+ warnings.push(w);
157
+ note(`warning: ${w}`);
158
+ },
159
+ } : {}),
112
160
  })
113
161
  .catch((e: unknown) => {
114
162
  // Someone else wrote this document since the read a moment ago. Report
@@ -134,7 +182,6 @@ export async function run(ctx: CommandContext): Promise<void> {
134
182
  // the agent stays on its last-known-good. Telling the owner "applies next
135
183
  // boot" for a rejection is a lie that hides an un-bootable document.
136
184
  let rejected = false;
137
- const base = await runningServeBase(ctx.env.attestorUrl, sealId);
138
185
  if (base && !pendingReset) {
139
186
  const agentId = await ag.agent.getAgentIdBySealId(sealId);
140
187
  await ag.agent
@@ -147,11 +194,11 @@ export async function run(ctx: CommandContext): Promise<void> {
147
194
  pendingReset = true;
148
195
  return;
149
196
  }
150
- const msg = e instanceof Error ? e.message : String(e);
197
+ const msg = explainError(e).message;
151
198
  // pushSettingsToContainer throws `… HTTP <n>: …` when the container
152
199
  // ANSWERED and refused; a bare fetch failure (no HTTP status) means
153
200
  // it was unreachable.
154
- rejected = /HTTP \d/.test(msg);
201
+ rejected = /HTTP \d/.test(e instanceof Error ? e.message : String(e));
155
202
  const w = rejected
156
203
  ? `stored, but the running container REFUSED it: ${msg} — a refused document does not boot, so the agent keeps its current configuration until you store one it accepts (e.g. an openai-format model for hermes)`
157
204
  : `stored, but the running container was unreachable: ${msg} — it applies on the next boot`;
@@ -167,12 +214,12 @@ export async function run(ctx: CommandContext): Promise<void> {
167
214
  for (const line of renderSettings(next)) print(line);
168
215
  note(
169
216
  pendingReset
170
- ? `written — version ${written.version}; provider change pending — run reset ${raw} with the ${next.provider} key`
217
+ ? `saved; provider change pending — reset agent ${raw} with the ${next.provider} key (${shellStep(`reset ${raw}`)})`
171
218
  : applied
172
- ? `written — version ${written.version}; ${applied}`
219
+ ? `saved; ${applied}`
173
220
  : rejected
174
- ? `written — version ${written.version}, but the running container refused it (see the warning above); it will not boot as-is.`
175
- : `written — version ${written.version}. The container applies it on its next boot.`,
221
+ ? 'saved, but the running container refused it (see the warning above); it will not boot as-is.'
222
+ : 'saved. The container applies it on its next boot.',
176
223
  );
177
224
  }
178
225
 
@@ -2,7 +2,8 @@
2
2
  * @file status.ts
3
3
  * @description `0g-agentdna status <agent>` — one agent's full picture
4
4
  * (spec v0.03 §3.2): all three coordinates (agentId / sealId / agentSeal),
5
- * phase, url, and the FOLDED failure reason. `<agent>` is a decimal agentId
5
+ * phase, and the FOLDED failure reason (`--json` also carries the container
6
+ * url, which the human output leaves out). `<agent>` is a decimal agentId
6
7
  * or a 0x… sealId; the command resolves the other coordinates from chain +
7
8
  * the attestor listing.
8
9
  *
@@ -15,7 +16,9 @@
15
16
  import type { Address, Hash } from 'viem';
16
17
  import type { AgenticID } from '../../AgenticID';
17
18
  import { buildClient } from '../sdk';
18
- import { CliError } from '../errors';
19
+ import { CliError, cmdStep, shellTo } from '../errors';
20
+ import { explainError } from '../plain';
21
+ import { cleanCell } from './cells';
19
22
  import { emitOk, note, print } from '../envelope';
20
23
  import { parseAgentRef } from '../ref';
21
24
  import type { CommandContext } from '../types';
@@ -55,8 +58,8 @@ export async function run(ctx: CommandContext): Promise<void> {
55
58
  hits.length ? 'BAD_AGENT_REF' : 'AGENT_NOT_FOUND',
56
59
  hits.length
57
60
  ? `"${ctx.positionals[0]}" matches ${hits.length} agents — add more hex chars`
58
- : `no agent matching ${ctx.positionals[0]} on this attestor`,
59
- { remedy: '0g-agentdna list # to discover existing agents' },
61
+ : `agent ${cleanCell(ctx.positionals[0])} does not exist on this attestor`,
62
+ { remedy: `${cmdStep('list')} shows the agents here` },
60
63
  );
61
64
  }
62
65
  ref = { kind: 'sealId', sealId: hits[0].sealId as Hash };
@@ -71,8 +74,8 @@ export async function run(ctx: CommandContext): Promise<void> {
71
74
  try {
72
75
  await ag.agent.ownerOf(agentId);
73
76
  } catch {
74
- throw new CliError('AGENT_NOT_FOUND', `agent ${agentId} not found on chain`, {
75
- remedy: '0g-agentdna list # to discover existing agents',
77
+ throw new CliError('AGENT_NOT_FOUND', `agent ${agentId} does not exist on this attestor's chain`, {
78
+ remedy: `${cmdStep('list')} shows the agents here`,
76
79
  });
77
80
  }
78
81
  try {
@@ -99,13 +102,13 @@ export async function run(ctx: CommandContext): Promise<void> {
99
102
  try {
100
103
  row = bySeal(await ag.agent.listDeployments());
101
104
  } catch (e) {
102
- note(`attestor listing unavailable (${(e as Error).message}) — chain-only view`);
105
+ note(`attestor listing unavailable (${explainError(e).message}) — chain-only view`);
103
106
  }
104
107
 
105
108
  // Not minted AND no deployment row → the sealId leads nowhere.
106
109
  if (!row && agentId === null) {
107
110
  throw new CliError('AGENT_NOT_FOUND', `seal ${sealId} has no deployment and no minted agent`, {
108
- remedy: '0g-agentdna list # to discover existing agents',
111
+ remedy: `${cmdStep('list')} shows the agents here`,
109
112
  });
110
113
  }
111
114
 
@@ -115,10 +118,10 @@ export async function run(ctx: CommandContext): Promise<void> {
115
118
  try {
116
119
  row = bySeal(await ag.agent.listMyDeployments()) ?? row;
117
120
  } catch (e) {
118
- note(`could not fetch the owner-tier failure reason (${(e as Error).message})`);
121
+ note(`could not fetch the owner-tier failure reason (${explainError(e).message})`);
119
122
  }
120
123
  } else {
121
- note('failure reason is owner-only — set AGENTIC_PRIVATE_KEY to see it');
124
+ note(`the failure reason is owner-only: ${shellTo('login', 'save your owner key')} (or set AGENTIC_PRIVATE_KEY), then look again`);
122
125
  }
123
126
  }
124
127
  }
@@ -149,22 +152,22 @@ export async function run(ctx: CommandContext): Promise<void> {
149
152
  };
150
153
  if (data.phase === 'failed') {
151
154
  // retry preserves the minted identity; a redeploy would orphan it.
152
- data.hint = 'recover with retry (keeps the on-chain identity) — SDK: await ag.agent.retry(sealId); do NOT redeploy';
155
+ data.hint = `${shellTo(`retry ${agentId ?? data.agentId ?? `0x${(sealId ?? '').slice(2, 12)}`}`, 'recover it under the same on-chain identity')} — do not redeploy`;
153
156
  }
154
157
 
155
158
  if (ctx.json) {
156
159
  emitOk(data);
157
160
  return;
158
161
  }
162
+ // An 11-column label: the 66-character sealId line fits 80 columns.
159
163
  const show = (v: unknown): string => (v === null || v === undefined ? '—' : String(v));
160
- print(`agentId: ${show(data.agentId)}`);
161
- print(`sealId: ${show(data.sealId)}`);
162
- print(`agentSeal: ${show(data.agentSeal)}`);
163
- print(`owner: ${show(data.owner)}`);
164
- print(`phase: ${show(data.phase)}`);
165
- print(`url: ${show(data.url)}`);
166
- print(`name: ${show(data.name)}`);
167
- print(`createdAt: ${show(data.createdAt)}`);
168
- print(`failureReason: ${show(data.failureReason)}`);
169
- if (data.hint) print(`hint: ${data.hint}`);
164
+ print(`agentId: ${show(data.agentId)}`);
165
+ print(`sealId: ${show(data.sealId)}`);
166
+ print(`agentSeal: ${show(data.agentSeal)}`);
167
+ print(`owner: ${show(data.owner)}`);
168
+ print(`phase: ${show(data.phase)}`);
169
+ print(`name: ${show(data.name)}`);
170
+ print(`createdAt: ${show(data.createdAt)}`);
171
+ print(`failure: ${show(data.failureReason)}`);
172
+ if (data.hint) print(`hint: ${data.hint}`);
170
173
  }
package/src/cli/config.ts CHANGED
@@ -21,11 +21,14 @@ import { readFileSync, writeFileSync, mkdirSync, chmodSync, existsSync, renameSy
21
21
  import { randomUUID } from 'node:crypto';
22
22
  import { homedir } from 'node:os';
23
23
  import { join } from 'node:path';
24
+ import { CliError } from './errors';
24
25
 
25
26
  export interface FileConfig {
26
27
  attestorUrl?: string;
27
28
  rpcUrl?: string;
28
29
  inferenceProvider?: string;
30
+ /** `off`: new files from an agent are not saved by themselves (`/files auto off`). */
31
+ filesAuto?: 'off';
29
32
  }
30
33
 
31
34
  /** Resolve on-disk locations and move an existing legacy directory once.
@@ -59,6 +62,7 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): FileConfig {
59
62
  attestorUrl: c.attestorUrl?.replace(/\/$/, ''),
60
63
  rpcUrl: c.rpcUrl,
61
64
  inferenceProvider: c.inferenceProvider,
65
+ filesAuto: c.filesAuto === 'off' ? 'off' : undefined,
62
66
  };
63
67
  } catch {
64
68
  return {};
@@ -71,6 +75,8 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): FileConfig {
71
75
  * tampering instead of silently downgrading to a clear-text key — across
72
76
  * CLI invocations, not just within one process. One small file so the
73
77
  * existing config.json load/save semantics stay untouched.
78
+ * LEGACY(model-key): the scheme seals only the request copy of a key; the
79
+ * pins, recordSecretEnvPin and the pin move in moveRenamedAttestor go with it.
74
80
  */
75
81
  export function loadSecretEnvPins(env: NodeJS.ProcessEnv = process.env): Record<string, true> {
76
82
  const file = join(configPaths(env).dir, 'secret-env-pins.json');
@@ -96,6 +102,105 @@ export function recordSecretEnvPin(attestorUrl: string, env: NodeJS.ProcessEnv =
96
102
  }
97
103
  }
98
104
 
105
+ type CredentialMark = { epoch: number; version: number; digest?: string };
106
+
107
+ /**
108
+ * Which model key this machine last stored for an agent and provider: the
109
+ * stored entry's value hash and a fingerprint of the key (a hash salted with
110
+ * the agent and provider, never the key), so storing the same key again can
111
+ * be told apart and skipped. Not secret: one small file, 0600. A file that
112
+ * does not parse reads as empty.
113
+ */
114
+ export type ModelKeyMark = { valueHash: string; keyMark: string };
115
+
116
+ function modelKeyMarksPath(env: NodeJS.ProcessEnv = process.env): string {
117
+ return join(configPaths(env).dir, 'model-key-marks.json');
118
+ }
119
+
120
+ export function loadModelKeyMarks(env: NodeJS.ProcessEnv = process.env): Record<string, ModelKeyMark> {
121
+ try {
122
+ const all = JSON.parse(readFileSync(modelKeyMarksPath(env), 'utf8')) as unknown;
123
+ if (!all || typeof all !== 'object' || Array.isArray(all)) return {};
124
+ const out: Record<string, ModelKeyMark> = {};
125
+ for (const [k, m] of Object.entries(all as Record<string, ModelKeyMark>)) {
126
+ if (m && typeof m.valueHash === 'string' && typeof m.keyMark === 'string') out[k] = { valueHash: m.valueHash, keyMark: m.keyMark };
127
+ }
128
+ return out;
129
+ } catch {
130
+ return {};
131
+ }
132
+ }
133
+
134
+ export function recordModelKeyMark(key: string, mark: ModelKeyMark, env: NodeJS.ProcessEnv = process.env): void {
135
+ try {
136
+ const { dir } = configPaths(env);
137
+ mkdirSync(dir, { recursive: true });
138
+ const marks = { ...loadModelKeyMarks(env), [key]: mark };
139
+ const file = modelKeyMarksPath(env);
140
+ const tmp = `${file}.${process.pid}.${randomUUID()}.tmp`;
141
+ writeFileSync(tmp, `${JSON.stringify(marks, null, 2)}\n`, { mode: 0o600 });
142
+ renameSync(tmp, file);
143
+ } catch {
144
+ /* best-effort */
145
+ }
146
+ }
147
+
148
+ /** Where the newest credential set seen per agent is kept. */
149
+ export function credentialMarksPath(env: NodeJS.ProcessEnv = process.env): string {
150
+ return join(configPaths(env).dir, 'credential-marks.json');
151
+ }
152
+
153
+ /**
154
+ * The newest credential set (ownership epoch, version, digest) this machine
155
+ * has seen per agent, so an older one, or another at the same version, that
156
+ * an attestor serves again is refused rather than signed anew
157
+ * (Credentials.get). Not secret: one small file, 0644. A file that does not
158
+ * parse reads as empty.
159
+ */
160
+ export function loadCredentialMarks(env: NodeJS.ProcessEnv = process.env): Record<string, CredentialMark> {
161
+ const file = credentialMarksPath(env);
162
+ if (!existsSync(file)) return {};
163
+ try {
164
+ const all = JSON.parse(readFileSync(file, 'utf8')) as unknown;
165
+ if (!all || typeof all !== 'object' || Array.isArray(all)) return {};
166
+ const out: Record<string, CredentialMark> = {};
167
+ for (const [k, m] of Object.entries(all as Record<string, unknown>)) {
168
+ const c = m as CredentialMark;
169
+ if (c && Number.isSafeInteger(c.epoch) && Number.isSafeInteger(c.version)) {
170
+ out[k] = { epoch: c.epoch, version: c.version, ...(typeof c.digest === 'string' ? { digest: c.digest } : {}) };
171
+ }
172
+ }
173
+ return out;
174
+ } catch {
175
+ return {};
176
+ }
177
+ }
178
+
179
+ /**
180
+ * Record a newer credential set for `key`, unless the file already holds a
181
+ * newer one for it (another run may have written meanwhile). Written to a
182
+ * temporary file and renamed, so a reader never sees half of it; two runs
183
+ * writing at the same moment can still lose one's record, which that run
184
+ * keeps in memory. Best-effort, as recordSecretEnvPin.
185
+ */
186
+ export function recordCredentialMark(key: string, mark: CredentialMark, env: NodeJS.ProcessEnv = process.env): void {
187
+ try {
188
+ const { dir } = configPaths(env);
189
+ mkdirSync(dir, { recursive: true });
190
+ const marks = loadCredentialMarks(env);
191
+ const had = marks[key];
192
+ const later = !had || had.epoch < mark.epoch || (had.epoch === mark.epoch && (had.version < mark.version || (had.version === mark.version && !had.digest)));
193
+ if (!later) return;
194
+ marks[key] = { epoch: mark.epoch, version: mark.version, ...(mark.digest ? { digest: mark.digest } : {}) };
195
+ const file = credentialMarksPath(env);
196
+ const tmp = `${file}.${process.pid}.${randomUUID()}.tmp`;
197
+ writeFileSync(tmp, `${JSON.stringify(marks, null, 2)}\n`, { mode: 0o644 });
198
+ renameSync(tmp, file);
199
+ } catch {
200
+ /* best-effort */
201
+ }
202
+ }
203
+
99
204
  /** Merge a patch into config.json (creating the dir), 0644. */
100
205
  export function saveConfig(patch: FileConfig, env: NodeJS.ProcessEnv = process.env): void {
101
206
  const { dir, config } = configPaths(env);
@@ -129,7 +234,7 @@ export function moveRenamedAttestor(env: NodeJS.ProcessEnv = process.env): { fro
129
234
  const to = from ? renamedAttestor(from) : undefined;
130
235
  if (!from || !to) return null;
131
236
  // Pin first: a failed write then leaves the earlier address saved, never
132
- // the current one without its pin.
237
+ // the current one without its pin. LEGACY(model-key): goes with the pins.
133
238
  if (loadSecretEnvPins(env)[from]) {
134
239
  recordSecretEnvPin(to, env);
135
240
  if (!loadSecretEnvPins(env)[to]) return null;
@@ -250,12 +355,22 @@ export function saveApiKey(providerOrKey: string, keyOrEnv?: string | NodeJS.Pro
250
355
  saveCredentials({ inferenceKeys: { [provider]: key } }, source);
251
356
  }
252
357
 
253
- /** Global legacy variables only belong to compute; new overrides are bound. */
358
+ /**
359
+ * A model key from the environment: `AGENTDNA_API_KEY` for the provider
360
+ * `AGENTDNA_API_KEY_PROVIDER` names, or the legacy compute-only
361
+ * `AGENTIC_API_KEY`. A generic `API_KEY` is never read — it belongs to
362
+ * whatever else set it, not to this CLI. A key without its provider is
363
+ * refused (the remedy says how to set both).
364
+ */
254
365
  export function inferenceKeyFromEnv(provider: string, env: NodeJS.ProcessEnv = process.env): string | null {
255
366
  const key = env.AGENTDNA_API_KEY?.trim();
256
367
  const binding = env.AGENTDNA_API_KEY_PROVIDER?.trim();
257
- if (key && !binding) throw new Error('AGENTDNA_API_KEY requires AGENTDNA_API_KEY_PROVIDER');
368
+ if (key && !binding) {
369
+ throw new CliError('INFERENCE_KEY_REQUIRED', 'AGENTDNA_API_KEY is set without AGENTDNA_API_KEY_PROVIDER — the CLI cannot tell which provider the key is for', {
370
+ remedy: 'export AGENTDNA_API_KEY_PROVIDER=<provider> (e.g. openai) with it, or unset AGENTDNA_API_KEY',
371
+ });
372
+ }
258
373
  if (key && binding === provider) return key;
259
- if (provider === '0g-compute') return env.AGENTIC_API_KEY?.trim() || env.API_KEY?.trim() || null;
374
+ if (provider === '0g-compute') return env.AGENTIC_API_KEY?.trim() || null;
260
375
  return null;
261
376
  }