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

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 +62 -0
  53. package/dist/cli/commands/cells.d.ts.map +1 -0
  54. package/dist/cli/commands/cells.js +113 -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 +115 -0
  61. package/dist/cli/commands/interactive.d.ts.map +1 -0
  62. package/dist/cli/commands/interactive.js +3052 -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 +91 -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 +107 -0
  179. package/src/cli/commands/doctor.ts +235 -0
  180. package/src/cli/commands/interactive.ts +2738 -0
  181. package/src/cli/commands/list.ts +95 -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,95 @@
1
+ /**
2
+ * @file list.ts
3
+ * @description `0g-agentdna list [--mine] [--phase <p>]` — deployment
4
+ * listing (spec v0.03 §3.3). Default is the attestor's PUBLIC tier; minted
5
+ * rows carry owner and agentSeal there (#183-c4 — both are chain-public
6
+ * once minted). `--mine` switches to the owner-signed listing (needs
7
+ * AGENTIC_PRIVATE_KEY) whose rows carry the withheld owner-only fields
8
+ * (sandboxId, failure reasons — #64) AND owner on unminted rows.
9
+ * `--phase` filters client-side.
10
+ *
11
+ * JSON mode: `data` IS the row array (empty list → `[]`, exit 0 — not an
12
+ * error) and carries the FULL row (sealId, url, sandboxId, framework, whole
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).
19
+ *
20
+ * Nesting visibility (follow-up to #187 / #183-c4): the AGENTSEAL and OWNER
21
+ * columns use the same short form, so an agent-owned agent is visible at a
22
+ * glance — its OWNER matches another row's AGENTSEAL. The OWNER cell also
23
+ * carries an explicit `⇄ #<agentId>` annotation when the owner is another
24
+ * listed agent's seal (the map is built from the FULL fetch, so a --phase
25
+ * filter never hides the annotation); an owner that is an agent deployed
26
+ * via a different attestor annotates as nothing (no cross-attestor reverse
27
+ * map exists). Both columns are display-only: zero extra chain reads.
28
+ */
29
+
30
+ import { buildClient } from '../sdk';
31
+ import { cellText, ownerCellText, sealToAgentMap, shortAddr, trustedCell } from './cells';
32
+ import { CliError } from '../errors';
33
+ import { emitOk, print } from '../envelope';
34
+ import type { CommandContext } from '../types';
35
+
36
+ /** The deployment phases derive_phase() can produce — the valid --phase values. */
37
+ const PHASES = ['deploying', 'running', 'stopped', 'offline', 'failed'];
38
+
39
+ export async function run(ctx: CommandContext): Promise<void> {
40
+ // Validate --phase BEFORE any network work: a typo'd phase must be a loud
41
+ // exit-2, not a plausible-looking empty success (agent-walkthrough finding).
42
+ if (ctx.flags.phase && !PHASES.includes(ctx.flags.phase)) {
43
+ throw new CliError('BAD_FLAG', `--phase must be one of ${PHASES.join('|')}, got "${ctx.flags.phase}"`, {
44
+ remedy: '0g-agentdna list --phase failed',
45
+ });
46
+ }
47
+ // --mine is an owner-signed surface: withWallet makes a missing key fail
48
+ // here as WALLET_REQUIRED (exit 3 + remedy), before any request is made.
49
+ const ag = await buildClient(ctx.env, { withWallet: ctx.flags.mine });
50
+ const all = ctx.flags.mine
51
+ ? await ag.agent.listMyDeployments()
52
+ : await ag.agent.listDeployments();
53
+ let rows = all;
54
+ if (ctx.flags.phase) rows = rows.filter((r) => r.phase === ctx.flags.phase);
55
+
56
+ if (ctx.json) {
57
+ emitOk(rows);
58
+ return;
59
+ }
60
+
61
+ if (rows.length === 0) {
62
+ print('(no deployments)');
63
+ return;
64
+ }
65
+ // Nesting annotation map, built from `all`, not `rows`: a --phase filter
66
+ // must not strip the annotation off a child row whose parent falls outside
67
+ // the filtered view (./cells: sealToAgentMap). The OWNER cell pads but
68
+ // never truncates its trusted annotation (./cells: trustedCell).
69
+ 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
+ }
93
+ print('');
94
+ print(`${rows.length} deployment(s)${ctx.flags.phase ? ` (phase=${ctx.flags.phase})` : ''}${ctx.flags.mine ? ' — owner tier' : ''}`);
95
+ }
@@ -0,0 +1,16 @@
1
+ /** Read-only discovery of the platform provider registry. */
2
+ import { buildClient } from '../sdk';
3
+ import { CliError } from '../errors';
4
+ import { emitOk, print } from '../envelope';
5
+ import type { CommandContext } from '../types';
6
+
7
+ export async function run(ctx: CommandContext): Promise<void> {
8
+ if (ctx.positionals.length) throw new CliError('BAD_FLAG', 'usage: providers (read-only)');
9
+ const ag = await buildClient(ctx.env);
10
+ const current = await ag.agent.getProviderRegistry();
11
+ 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
+ }
16
+ }
@@ -0,0 +1,197 @@
1
+ /**
2
+ * @file settings.ts
3
+ * @description `0g-agentdna settings <agent> [key=value …]` — show or change
4
+ * the agent's configuration document (which model it thinks with, and how
5
+ * hard).
6
+ *
7
+ * BOTH DIRECTIONS ARE OWNER-SIGNED, against the LIVE on-chain owner: the
8
+ * document is the owner's — it can name a private endpoint or a paid model —
9
+ * so reading it needs AGENTIC_PRIVATE_KEY exactly as writing it does.
10
+ *
11
+ * The write is a whole document — assignments merge onto whatever is stored,
12
+ * so `settings 286 model=x` changes the model and leaves everything else
13
+ * alone — and it is a compare-and-swap against the version just read, so a
14
+ * concurrent edit by another client is refused rather than silently lost.
15
+ * Before signing, model advisories use the selected provider's catalog.
16
+ * Native providers without a catalog accept manual model IDs. Provider
17
+ * changes require a matching local key and runtime capability, then wait
18
+ * for reset to deliver that key rather than pushing the old credential.
19
+ */
20
+
21
+ import type { Hash } from 'viem';
22
+ import type { AgenticID } from '../../AgenticID';
23
+ import { buildClient } from '../sdk';
24
+ import { CliError } from '../errors';
25
+ import { emitOk, note, print } from '../envelope';
26
+ import { parseAgentRef, type AgentRef } from '../ref';
27
+ import { applyAssignments, assertModelPresent, parseAssignments, renderSettings } from '../settings';
28
+ import { SettingsConflictError } from '../../Settings';
29
+ import type { CommandContext } from '../types';
30
+ import { changesProvider } from '../../Providers';
31
+ import { requireConfiguredInferenceKey, requiresProviderReset } from '../inference';
32
+
33
+ const ZERO_HASH = `0x${'0'.repeat(64)}` as Hash;
34
+
35
+ /** agentId | sealId | unique sealId prefix → the sealId the attestor keys on. */
36
+ async function resolveSealId(ag: AgenticID, ref: AgentRef, raw: string): Promise<Hash> {
37
+ if (ref.kind === 'sealId') return ref.sealId;
38
+ if (ref.kind === 'sealPrefix') {
39
+ const hits = (await ag.agent.listDeployments()).filter((r) =>
40
+ r.sealId?.toLowerCase().startsWith(ref.prefix),
41
+ );
42
+ if (hits.length !== 1) {
43
+ throw new CliError(
44
+ hits.length ? 'BAD_AGENT_REF' : 'AGENT_NOT_FOUND',
45
+ hits.length
46
+ ? `"${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' },
49
+ );
50
+ }
51
+ return hits[0].sealId;
52
+ }
53
+ const seal = await ag.agent.getSealId(ref.agentId).catch(() => ZERO_HASH);
54
+ if (seal === ZERO_HASH) {
55
+ throw new CliError('AGENT_NOT_FOUND', `agent ${ref.agentId} has no sealId on chain`, {
56
+ remedy: '0g-agentdna list # to discover existing agents',
57
+ });
58
+ }
59
+ return seal;
60
+ }
61
+
62
+ export async function run(ctx: CommandContext): Promise<void> {
63
+ const raw = ctx.positionals[0];
64
+ const ref = parseAgentRef(raw);
65
+ // Grammar errors are usage errors — raise them before any network work.
66
+ const assignments = parseAssignments(ctx.positionals.slice(1));
67
+ const writing = assignments.length > 0;
68
+
69
+ // The document is owner-gated in both directions, so a show needs the key
70
+ // just as a write does.
71
+ const ag = await buildClient(ctx.env, { withWallet: true });
72
+ const sealId = await resolveSealId(ag, ref, raw!);
73
+ const { settings: current, version } = await ag.agent.getSettings(sealId).catch((e: Error) => {
74
+ // No row for this seal — a wrong attestor or a wrong id, not an internal fault.
75
+ if (/HTTP 404/.test(e.message)) {
76
+ throw new CliError('AGENT_NOT_FOUND', `no deployment for seal ${sealId} on this attestor`, {
77
+ remedy: '0g-agentdna list # to discover existing agents',
78
+ });
79
+ }
80
+ throw e;
81
+ });
82
+
83
+ if (!writing) {
84
+ if (ctx.json) {
85
+ emitOk({ sealId, settings: current, version });
86
+ return;
87
+ }
88
+ for (const line of renderSettings(current)) print(line);
89
+ return;
90
+ }
91
+
92
+ const next = applyAssignments(current, assignments);
93
+ // Before anything is signed: a document with no model is the one state the
94
+ // container cannot boot from and last-known-good cannot cover.
95
+ assertModelPresent(next, current !== null);
96
+ let pendingReset = changesProvider(current, next);
97
+ if (pendingReset) requireConfiguredInferenceKey(next.provider ?? '0g-compute');
98
+ const warnings: string[] = [];
99
+ // The catalog advisory runs inside setSettings, before it signs.
100
+ const written = await ag.agent
101
+ .setSettings(sealId, next, {
102
+ baseVersion: version,
103
+ onWarn: (w) => {
104
+ warnings.push(w);
105
+ note(`warning: ${w}`);
106
+ },
107
+ })
108
+ .catch((e: unknown) => {
109
+ // Someone else wrote this document since the read a moment ago. Report
110
+ // what is actually stored and stop — re-applying the edit on top would
111
+ // be this command deciding to discard their change.
112
+ if (e instanceof SettingsConflictError) {
113
+ throw new CliError('SETTINGS_CONFLICT', e.message, {
114
+ remedy: `re-run the same command to apply your change on top of version ${e.currentVersion}`,
115
+ details: { currentVersion: e.currentVersion, current: e.current, baseVersion: e.baseVersion },
116
+ });
117
+ }
118
+ throw e;
119
+ });
120
+
121
+ // Stored is the authoritative act; the push below only makes it visible now.
122
+ // A failure there is a warning, never an error: the document is already
123
+ // saved and the next boot reads it, so reporting the write as failed would
124
+ // be wrong and would tempt the owner into writing it again.
125
+ let applied: string | undefined;
126
+ // A REJECTION (the container answered and refused to render this document)
127
+ // is not the same as an UNREACHABLE container: the latter applies on the
128
+ // next boot, the former will refuse identically on the next boot too and
129
+ // the agent stays on its last-known-good. Telling the owner "applies next
130
+ // boot" for a rejection is a lie that hides an un-bootable document.
131
+ let rejected = false;
132
+ const base = await runningServeBase(ctx.env.attestorUrl, sealId);
133
+ if (base && !pendingReset) {
134
+ const agentId = await ag.agent.getAgentIdBySealId(sealId);
135
+ await ag.agent
136
+ .pushSettingsToContainer(base, agentId, next)
137
+ .then((r) => {
138
+ applied = r.note ?? 'applied to the running container';
139
+ })
140
+ .catch((e: unknown) => {
141
+ if (requiresProviderReset(e)) {
142
+ pendingReset = true;
143
+ return;
144
+ }
145
+ const msg = e instanceof Error ? e.message : String(e);
146
+ // pushSettingsToContainer throws `… HTTP <n>: …` when the container
147
+ // ANSWERED and refused; a bare fetch failure (no HTTP status) means
148
+ // it was unreachable.
149
+ rejected = /HTTP \d/.test(msg);
150
+ const w = rejected
151
+ ? `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)`
152
+ : `stored, but the running container was unreachable: ${msg} — it applies on the next boot`;
153
+ warnings.push(w);
154
+ note(`warning: ${w}`);
155
+ });
156
+ }
157
+
158
+ if (ctx.json) {
159
+ emitOk({ sealId, settings: next, version: written.version, warnings, applied: applied ?? null, rejected, pendingReset });
160
+ return;
161
+ }
162
+ for (const line of renderSettings(next)) print(line);
163
+ note(
164
+ pendingReset
165
+ ? `written — version ${written.version}; provider change pending — run reset ${raw} with the ${next.provider} key`
166
+ : applied
167
+ ? `written — version ${written.version}; ${applied}`
168
+ : rejected
169
+ ? `written — version ${written.version}, but the running container refused it (see the warning above); it will not boot as-is.`
170
+ : `written — version ${written.version}. The container applies it on its next boot.`,
171
+ );
172
+ }
173
+
174
+ /**
175
+ * The running container's serve base, or undefined when there is nothing live
176
+ * to push to.
177
+ *
178
+ * Deliberately best-effort and short-timeout: this only decides whether the
179
+ * change can be applied NOW. The document is already stored by the time this
180
+ * runs, so a wrong answer costs a boot's delay, never the change itself.
181
+ *
182
+ * Mirrors how the REPL resolves the same thing (cli/commands/interactive.ts):
183
+ * prefer the attestor's own `url`, fall back to the agent card's (stripping
184
+ * the /hello path some builds leave on it).
185
+ */
186
+ async function runningServeBase(attestorUrl: string | undefined, sealId: string): Promise<string | undefined> {
187
+ if (!attestorUrl) return undefined;
188
+ try {
189
+ const r = await fetch(`${attestorUrl}/deployment/${sealId}`, { signal: AbortSignal.timeout(5000) });
190
+ if (!r.ok) return undefined;
191
+ const d = (await r.json()) as { phase?: string; url?: string; agent_card?: { url?: string } };
192
+ if (d.phase !== 'running') return undefined;
193
+ return d.url ?? d.agent_card?.url?.replace(/\/hello$/, '') ?? undefined;
194
+ } catch {
195
+ return undefined;
196
+ }
197
+ }
@@ -0,0 +1,170 @@
1
+ /**
2
+ * @file status.ts
3
+ * @description `0g-agentdna status <agent>` — one agent's full picture
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
6
+ * or a 0x… sealId; the command resolves the other coordinates from chain +
7
+ * the attestor listing.
8
+ *
9
+ * Failure folding: the public /deployments listing withholds failure reasons
10
+ * (owner-only since #64). When phase=failed and a wallet is configured, this
11
+ * command silently does the owner-signed listing to surface the reason —
12
+ * the step that otherwise requires a hand-written signing script.
13
+ */
14
+
15
+ import type { Address, Hash } from 'viem';
16
+ import type { AgenticID } from '../../AgenticID';
17
+ import { buildClient } from '../sdk';
18
+ import { CliError } from '../errors';
19
+ import { emitOk, note, print } from '../envelope';
20
+ import { parseAgentRef } from '../ref';
21
+ import type { CommandContext } from '../types';
22
+
23
+ const ZERO_ADDR = '0x0000000000000000000000000000000000000000';
24
+ const ZERO_HASH = `0x${'0'.repeat(64)}`;
25
+
26
+ /** The status payload — field names are part of the output contract. */
27
+ interface StatusData {
28
+ agentId: bigint | null;
29
+ sealId: Hash | null;
30
+ agentSeal: Address | null;
31
+ owner: Address | null;
32
+ phase: string | null;
33
+ url: string | null;
34
+ name: string | null;
35
+ createdAt: string | null;
36
+ failureReason: string | null;
37
+ /** Present only when phase=failed: the recommended recovery action. */
38
+ hint?: string;
39
+ }
40
+
41
+ type Row = Awaited<ReturnType<AgenticID['agent']['listDeployments']>>[number];
42
+
43
+ export async function run(ctx: CommandContext): Promise<void> {
44
+ let ref = parseAgentRef(ctx.positionals[0]);
45
+ const ag = await buildClient(ctx.env);
46
+
47
+ // A truncated sealId (as printed by `list`) resolves against the listing —
48
+ // unique prefix or bust.
49
+ if (ref.kind === 'sealPrefix') {
50
+ const prefix = ref.prefix;
51
+ const rows = await ag.agent.listDeployments();
52
+ const hits = rows.filter((r) => r.sealId?.toLowerCase().startsWith(prefix));
53
+ if (hits.length !== 1) {
54
+ throw new CliError(
55
+ hits.length ? 'BAD_AGENT_REF' : 'AGENT_NOT_FOUND',
56
+ hits.length
57
+ ? `"${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' },
60
+ );
61
+ }
62
+ ref = { kind: 'sealId', sealId: hits[0].sealId as Hash };
63
+ }
64
+
65
+ // — resolve the coordinate pair (either direction) —
66
+ let agentId: bigint | null = null;
67
+ let sealId: Hash | null = null;
68
+ if (ref.kind === 'agentId') {
69
+ agentId = ref.agentId;
70
+ // ownerOf is the existence oracle: ERC-721 reverts for unknown tokens.
71
+ try {
72
+ await ag.agent.ownerOf(agentId);
73
+ } catch {
74
+ throw new CliError('AGENT_NOT_FOUND', `agent ${agentId} not found on chain`, {
75
+ remedy: '0g-agentdna list # to discover existing agents',
76
+ });
77
+ }
78
+ try {
79
+ const s = await ag.agent.getSealId(agentId);
80
+ sealId = s === ZERO_HASH ? null : s;
81
+ } catch {
82
+ sealId = null; // non-seal-bound agent — chain-only picture below
83
+ }
84
+ } else {
85
+ sealId = ref.sealId;
86
+ try {
87
+ const id = await ag.agent.getAgentIdBySealId(sealId);
88
+ agentId = id === 0n ? null : id; // 0 = accepted but not minted yet
89
+ } catch {
90
+ agentId = null;
91
+ }
92
+ }
93
+
94
+ // — attestor deployment row (by sealId), public tier first —
95
+ let row: Row | undefined;
96
+ if (sealId) {
97
+ const bySeal = (rows: Row[]): Row | undefined =>
98
+ rows.find((r) => r.sealId.toLowerCase() === sealId!.toLowerCase());
99
+ try {
100
+ row = bySeal(await ag.agent.listDeployments());
101
+ } catch (e) {
102
+ note(`attestor listing unavailable (${(e as Error).message}) — chain-only view`);
103
+ }
104
+
105
+ // Not minted AND no deployment row → the sealId leads nowhere.
106
+ if (!row && agentId === null) {
107
+ throw new CliError('AGENT_NOT_FOUND', `seal ${sealId} has no deployment and no minted agent`, {
108
+ remedy: '0g-agentdna list # to discover existing agents',
109
+ });
110
+ }
111
+
112
+ // — failure folding: owner-tier reason when the public one is withheld —
113
+ if (row && row.phase === 'failed' && !row.lastProvisionError) {
114
+ if (ctx.env.privateKey) {
115
+ try {
116
+ row = bySeal(await ag.agent.listMyDeployments()) ?? row;
117
+ } catch (e) {
118
+ note(`could not fetch the owner-tier failure reason (${(e as Error).message})`);
119
+ }
120
+ } else {
121
+ note('failure reason is owner-only — set AGENTIC_PRIVATE_KEY to see it');
122
+ }
123
+ }
124
+ }
125
+
126
+ // — chain-side fields for a minted agent —
127
+ let owner: Address | null = row?.owner ?? null;
128
+ let agentSeal: Address | null = null;
129
+ if (agentId !== null) {
130
+ try {
131
+ owner = await ag.agent.ownerOf(agentId);
132
+ } catch { /* keep row owner */ }
133
+ try {
134
+ const s = await ag.agent.getAgentSeal(agentId);
135
+ agentSeal = s === ZERO_ADDR ? null : s;
136
+ } catch { /* stays null */ }
137
+ }
138
+
139
+ const data: StatusData = {
140
+ agentId: agentId ?? row?.agentId ?? null,
141
+ sealId,
142
+ agentSeal,
143
+ owner,
144
+ phase: row?.phase ?? null,
145
+ url: row?.url ?? null,
146
+ name: row?.name ?? null,
147
+ createdAt: row?.createdAt ?? null,
148
+ failureReason: row?.lastProvisionError ?? null,
149
+ };
150
+ if (data.phase === 'failed') {
151
+ // 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';
153
+ }
154
+
155
+ if (ctx.json) {
156
+ emitOk(data);
157
+ return;
158
+ }
159
+ 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}`);
170
+ }
@@ -0,0 +1,86 @@
1
+ /**
2
+ * @file update.ts
3
+ * @description `0g-agentdna update` — self-update the CLI (it ships inside
4
+ * the SDK npm package). Compares the running version against the npm
5
+ * registry's latest and runs `npm install -g <pkg>@<latest>` when behind.
6
+ *
7
+ * A development copy (git checkout / npm link — resolved path outside any
8
+ * node_modules) is never npm-overwritten: the command reports the versions
9
+ * and tells you to `git pull && npm run build` instead.
10
+ */
11
+
12
+ import { spawnSync } from 'node:child_process';
13
+ import { readFileSync, realpathSync } from 'node:fs';
14
+ import { dirname, join } from 'node:path';
15
+ import { CliError } from '../errors';
16
+ import { emitOk, note, print } from '../envelope';
17
+ import type { CommandContext } from '../types';
18
+
19
+ /** The legacy launcher owns the global bin links when installed through the
20
+ * old package's updater. Update that package so npm can replace its own links
21
+ * and bring along the matching AgentDNA dependency without EEXIST collisions. */
22
+ export function selfPackage(entrypoint: string | undefined = process.argv[1]): { name: string; version: string; dir: string } {
23
+ if (entrypoint) {
24
+ try {
25
+ const dir = dirname(realpathSync(entrypoint));
26
+ const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as {
27
+ name: string; version: string; agentdnaLegacyBridge?: boolean;
28
+ };
29
+ if (pkg.name === '@0gfoundation/0g-agenticid-sdk' && pkg.agentdnaLegacyBridge === true) {
30
+ return { name: pkg.name, version: pkg.version, dir };
31
+ }
32
+ } catch { /* regular CLI entrypoints do not sit next to a bridge manifest */ }
33
+ }
34
+ const dir = join(__dirname, '..', '..', '..'); // dist/cli/commands → package root
35
+ const raw = readFileSync(join(dir, 'package.json'), 'utf8');
36
+ const pkg = JSON.parse(raw) as { name: string; version: string };
37
+ return { name: pkg.name, version: pkg.version, dir };
38
+ }
39
+
40
+ export async function run(ctx: CommandContext): Promise<void> {
41
+ const self = selfPackage();
42
+ note(`checking ${self.name} against the npm registry…`);
43
+ const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(self.name)}/latest`).catch((e: Error) => {
44
+ throw new CliError('UNKNOWN', `npm registry unreachable: ${e.message}`, { remedy: 'check network and retry' });
45
+ });
46
+ if (!res.ok) {
47
+ throw new CliError('UNKNOWN', `npm registry returned HTTP ${res.status} for ${self.name}`, { remedy: 'retry later' });
48
+ }
49
+ const latest = ((await res.json()) as { version?: string }).version;
50
+ if (!latest) throw new CliError('UNKNOWN', 'npm registry response had no version field');
51
+
52
+ // numeric x.y.z compare: <0 behind, 0 equal, >0 ahead of the registry
53
+ const cmp = ((a: string, b: string): number => {
54
+ const pa = a.split('.').map(Number);
55
+ const pb = b.split('.').map(Number);
56
+ for (let i = 0; i < 3; i++) if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) - (pb[i] ?? 0);
57
+ return 0;
58
+ })(self.version, latest);
59
+
60
+ const dev = !self.dir.includes('node_modules');
61
+ if (cmp >= 0) {
62
+ if (ctx.json) { emitOk({ name: self.name, current: self.version, latest, updated: false, dev }); return; }
63
+ if (cmp === 0) print(`up to date — ${self.name} ${self.version}`);
64
+ else print(`ahead of the registry — running ${self.version}, npm latest is ${latest} (not yet published)`);
65
+ return;
66
+ }
67
+ if (dev) {
68
+ if (ctx.json) { emitOk({ name: self.name, current: self.version, latest, updated: false, dev }); return; }
69
+ print(`current ${self.version} · latest ${latest}`);
70
+ print(`this is a development copy (${self.dir}) — update it with: git pull && npm run build`);
71
+ return;
72
+ }
73
+ if (ctx.json) {
74
+ // --json is machine mode: report, don't spawn an interactive installer.
75
+ emitOk({ name: self.name, current: self.version, latest, updated: false, dev, remedy: `npm install -g ${self.name}@${latest}` });
76
+ return;
77
+ }
78
+ print(`current ${self.version} · latest ${latest} — updating…`);
79
+ const r = spawnSync('npm', ['install', '-g', `${self.name}@${latest}`], { stdio: 'inherit' });
80
+ if (r.status !== 0) {
81
+ throw new CliError('UNKNOWN', `npm install -g exited with ${r.status ?? 'signal'}`, {
82
+ remedy: `run manually: npm install -g ${self.name}@${latest} (may need elevated permissions)`,
83
+ });
84
+ }
85
+ print(`updated ${self.name} ${self.version} → ${latest}`);
86
+ }