@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
@@ -0,0 +1,200 @@
1
+ /**
2
+ * @file releaseNotice.ts
3
+ * @description The CLI's release notice: a few lines, printed after a command
4
+ * (and when the interactive shell starts), saying what the newest release is
5
+ * and which of the owner's agents it asks to move, by when.
6
+ *
7
+ * How often: with agents to move, once a week, and every day in the last 7
8
+ * days of their transition period and after it; with none (or no wallet to
9
+ * ask with), once per release, for 30 days after it is published. Remembered
10
+ * per attestor and kind in `release-notice.json` in the config directory. Silent on
11
+ * any failure: a release notice never blocks or fails a command.
12
+ */
13
+
14
+ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
15
+ import { join } from 'node:path';
16
+ import { privateKeyToAccount } from 'viem/accounts';
17
+ import { agentMigrationOf, fetchReleases, type AgentMigration, type ReleaseNotice } from '../Releases';
18
+ import { configPaths } from './config';
19
+ import { currentSurface } from './errors';
20
+ import type { CliEnv } from './env';
21
+
22
+ /** One of the owner's agents that a release asks to move. */
23
+ export interface AffectedAgent {
24
+ /** The agentId, or the sealId's 0x+10-hex prefix for an unminted row. */
25
+ agent: string;
26
+ migrate: AgentMigration;
27
+ }
28
+
29
+ export interface NoticeStamp {
30
+ /** What was shown: the release, and for agents to move, their state. */
31
+ key: string;
32
+ /** ISO time it was shown. */
33
+ at: string;
34
+ }
35
+
36
+ const DAY_MS = 86_400_000;
37
+ const INFO_DAYS = 30;
38
+
39
+ /** True when the user's locale asks for Chinese (`LC_ALL`, `LC_MESSAGES`, `LANG`). */
40
+ export function zhLocale(env: NodeJS.ProcessEnv = process.env): boolean {
41
+ return /^zh/i.test(env.LC_ALL || env.LC_MESSAGES || env.LANG || '');
42
+ }
43
+
44
+ /** A release's notes in the user's language, when the release has them. */
45
+ export function notesOf(r: ReleaseNotice, zh: boolean): string {
46
+ return (zh && r.notesZh?.trim() ? r.notesZh : r.notes).trim();
47
+ }
48
+
49
+ /** `YYYY-MM-DD` of an ISO time (the input itself when unparsable). */
50
+ export function dateOf(iso: string): string {
51
+ const t = Date.parse(iso);
52
+ return Number.isNaN(t) ? iso : new Date(t).toISOString().slice(0, 10);
53
+ }
54
+
55
+ function firstLine(s: string): string {
56
+ const line = s.split('\n').find((l) => l.trim())?.trim() ?? '';
57
+ return line.length > 160 ? `${line.slice(0, 157)}...` : line;
58
+ }
59
+
60
+ function names(agents: AffectedAgent[]): string {
61
+ const shown = agents.slice(0, 6).map((a) => a.agent).join(', ');
62
+ return agents.length > 6 ? `${shown} and ${agents.length - 6} more` : shown;
63
+ }
64
+
65
+ /**
66
+ * What to print now, and the stamp to keep once it is printed; null when
67
+ * nothing is due. Pure: `now` and `stamp` come from the caller.
68
+ */
69
+ export function planReleaseNotice(p: {
70
+ releases: ReleaseNotice[];
71
+ agents: AffectedAgent[];
72
+ now: Date;
73
+ stamp: NoticeStamp | null;
74
+ zh: boolean;
75
+ /** Printed inside the interactive shell: its commands are named as typed
76
+ * there (`reset <agent>`, `releases`), not as one-shot commands. */
77
+ shell?: boolean;
78
+ }): { lines: string[]; stamp: NoticeStamp } | null {
79
+ const details = p.shell ? 'Details: `releases`' : 'Details: 0g-agentdna releases';
80
+ const shownAgo = p.stamp ? p.now.getTime() - Date.parse(p.stamp.at) : Infinity;
81
+ if (p.agents.length) {
82
+ const worst = p.agents.some((a) => a.migrate.state === 'overdue')
83
+ ? 'overdue'
84
+ : p.agents.some((a) => a.migrate.state === 'soon')
85
+ ? 'soon'
86
+ : 'recommended';
87
+ const earliest = p.agents.reduce((a, b) => (Date.parse(b.migrate.until) < Date.parse(a.migrate.until) ? b : a));
88
+ const version = earliest.migrate.version;
89
+ const key = `${version}|${worst}`;
90
+ const every = worst === 'recommended' ? 7 * DAY_MS : DAY_MS;
91
+ if (p.stamp?.key === key && shownAgo < every) return null;
92
+ const release = p.releases.find((r) => r.version === version);
93
+ const until = dateOf(earliest.migrate.until);
94
+ const left = Math.ceil((Date.parse(earliest.migrate.until) - p.now.getTime()) / DAY_MS);
95
+ const lines = [
96
+ release ? `AgentDNA ${version} is out: ${firstLine(notesOf(release, p.zh))}` : `AgentDNA ${version} is out.`,
97
+ worst === 'overdue'
98
+ ? `Agent(s) ${names(p.agents)} still run the previous version, whose transition period ended ${until}: it may be retired any time, and their next boot is then refused until they are reset.`
99
+ : `Agent(s) ${names(p.agents)} still run the previous version. They keep running; please reset them onto the new one by ${until} (${left} day${left === 1 ? '' : 's'} left).`,
100
+ p.shell
101
+ ? 'To reset one: `reset <agent>` (persona, skills, settings and memory stay).'
102
+ : 'To reset one: run 0g-agentdna, then `reset <agent>` (persona, skills, settings and memory stay).',
103
+ ];
104
+ if (p.agents.some((a) => a.migrate.urgent)) lines.push('This release fixes a security issue: the previous version may be retired sooner.');
105
+ lines.push(details);
106
+ return { lines, stamp: { key, at: p.now.toISOString() } };
107
+ }
108
+ const latest = p.releases[0];
109
+ if (!latest || p.now.getTime() - Date.parse(latest.publishedAt) > INFO_DAYS * DAY_MS) return null;
110
+ const key = `${latest.version}|info`;
111
+ if (p.stamp?.key === key) return null;
112
+ return {
113
+ lines: [`AgentDNA ${latest.version} is out: ${firstLine(notesOf(latest, p.zh))}`, details],
114
+ stamp: { key, at: p.now.toISOString() },
115
+ };
116
+ }
117
+
118
+ /**
119
+ * The owner's agents that a published release asks to move, from the
120
+ * owner-signed listing (signed locally with the CLI's key; no prompt).
121
+ */
122
+ export async function myMigrations(attestorUrl: string, privateKey: `0x${string}`, signal?: AbortSignal): Promise<AffectedAgent[]> {
123
+ const account = privateKeyToAccount(privateKey);
124
+ const message = `0GDeployments:${account.address}:${Math.floor(Date.now() / 1000)}`;
125
+ const signature = await account.signMessage({ message });
126
+ const res = await fetch(`${attestorUrl.replace(/\/+$/, '')}/deployments?owner=${account.address}&slim=1`, {
127
+ headers: { 'X-Auth-Message': message, 'X-Auth-Signature': signature },
128
+ signal: signal ?? AbortSignal.timeout(10_000),
129
+ });
130
+ if (!res.ok) throw new Error(`owner listing: HTTP ${res.status}`);
131
+ const rows = (await res.json()) as Array<Record<string, unknown>>;
132
+ const out: AffectedAgent[] = [];
133
+ for (const r of Array.isArray(rows) ? rows : []) {
134
+ const migrate = agentMigrationOf(r.migrate);
135
+ if (!migrate) continue;
136
+ // The owner tier sends agent_id as a U256 hex string ("0x210"); the
137
+ // shell's `reset` takes the decimal agentId.
138
+ let agent = String(r.seal_id ?? '').slice(0, 12);
139
+ if (r.agent_id != null) {
140
+ try { agent = BigInt(r.agent_id as string).toString(); } catch { agent = String(r.agent_id); }
141
+ }
142
+ out.push({ agent, migrate });
143
+ }
144
+ return out;
145
+ }
146
+
147
+ function stampFile(): string {
148
+ return join(configPaths().dir, 'release-notice.json');
149
+ }
150
+
151
+ /** Stamps are kept per attestor and per kind of notice (`agents`: with the
152
+ * owner's agents to move; `news`: the release alone), so running with and
153
+ * without a key does not reset each other's cadence. */
154
+ function stampKey(attestorUrl: string, kind: 'agents' | 'news'): string {
155
+ return `${attestorUrl}|${kind}`;
156
+ }
157
+
158
+ function readStamp(key: string): NoticeStamp | null {
159
+ try {
160
+ const all = JSON.parse(readFileSync(stampFile(), 'utf8')) as Record<string, NoticeStamp>;
161
+ const s = all[key];
162
+ return s && typeof s.key === 'string' && typeof s.at === 'string' ? s : null;
163
+ } catch {
164
+ return null;
165
+ }
166
+ }
167
+
168
+ function writeStamp(key: string, stamp: NoticeStamp): void {
169
+ try {
170
+ let all: Record<string, NoticeStamp> = {};
171
+ try { all = JSON.parse(readFileSync(stampFile(), 'utf8')) as Record<string, NoticeStamp>; } catch { /* first time */ }
172
+ all[key] = stamp;
173
+ mkdirSync(configPaths().dir, { recursive: true });
174
+ writeFileSync(stampFile(), JSON.stringify(all));
175
+ } catch { /* an unwritable stamp only means the notice may repeat */ }
176
+ }
177
+
178
+ /**
179
+ * The notice due now for this environment, with `shown()` to call once it is
180
+ * printed (so a notice computed too late to print is not counted). Null when
181
+ * nothing is due or anything fails.
182
+ */
183
+ export async function dueReleaseNotice(env: CliEnv, signal?: AbortSignal): Promise<{ lines: string[]; shown: () => void } | null> {
184
+ try {
185
+ const url = env.attestorUrl;
186
+ if (!url) return null;
187
+ const releases = await fetchReleases(url, { signal: signal ?? AbortSignal.timeout(4000) });
188
+ if (!releases.length) return null;
189
+ let agents: AffectedAgent[] = [];
190
+ if (env.privateKey && /^0x[0-9a-fA-F]{64}$/.test(env.privateKey)) {
191
+ try { agents = await myMigrations(url, env.privateKey, signal); } catch { /* releases alone */ }
192
+ }
193
+ const key = stampKey(url, agents.length ? 'agents' : 'news');
194
+ const plan = planReleaseNotice({ releases, agents, now: new Date(), stamp: readStamp(key), zh: zhLocale(), shell: currentSurface() === 'shell' });
195
+ if (!plan) return null;
196
+ return { lines: plan.lines, shown: () => writeStamp(key, plan.stamp) };
197
+ } catch {
198
+ return null;
199
+ }
200
+ }
package/src/cli/sdk.ts CHANGED
@@ -8,9 +8,10 @@
8
8
  */
9
9
 
10
10
  import { AgenticID } from '../AgenticID';
11
- import { CliError } from './errors';
12
- import { loadSecretEnvPins, recordSecretEnvPin } from './config';
11
+ import { CliError, shellTo } from './errors';
12
+ import { credentialMarksPath, loadCredentialMarks, loadSecretEnvPins, recordCredentialMark, recordSecretEnvPin } from './config';
13
13
  import { requireAttestorUrl, requirePrivateKey, type CliEnv } from './env';
14
+ import { explainError } from './plain';
14
15
 
15
16
  /**
16
17
  * Build an SDK facade from the CLI environment.
@@ -24,6 +25,8 @@ import { requireAttestorUrl, requirePrivateKey, type CliEnv } from './env';
24
25
  */
25
26
  export async function buildClient(env: CliEnv, opts: { withWallet?: boolean } = {}): Promise<AgenticID> {
26
27
  const attestorUrl = requireAttestorUrl(env);
28
+ // An address that is not http(s) is refused before anything is sent to it.
29
+ if (!isWebAddress(attestorUrl)) throw attestorUnreachable(env, new Error('Invalid URL'));
27
30
  // Wallet-requiring callers get the strict check (named error + remedy).
28
31
  // Read-only callers proceed WALLETLESS on a malformed key instead of dying —
29
32
  // public surfaces like `list`/`hello` must not be hostage to a bad env var.
@@ -49,17 +52,94 @@ export async function buildClient(env: CliEnv, opts: { withWallet?: boolean } =
49
52
  ...(Object.keys(overrides).length ? { overrides } : {}),
50
53
  // Once this machine has seen an attestor advertise secret_env_scheme,
51
54
  // its absence is tampering, not a downgrade (issue #166).
55
+ // LEGACY(model-key): the scheme seals only the request copy of a key.
52
56
  secretEnvPin: {
53
57
  seen: (url) => !!loadSecretEnvPins()[url],
54
58
  record: (url) => recordSecretEnvPin(url),
55
59
  },
60
+ // An older credential set served again is refused, across runs too.
61
+ credentialMarks: {
62
+ seen: (key) => loadCredentialMarks()[key],
63
+ record: (key, mark) => recordCredentialMark(key, mark),
64
+ where: credentialMarksPath(),
65
+ },
56
66
  });
57
67
  } catch (e) {
58
68
  if (e instanceof CliError) throw e;
59
- throw new CliError(
60
- 'ATTESTOR_UNREACHABLE',
61
- `could not bootstrap from ${attestorUrl}/config: ${(e as Error).message}`,
62
- { remedy: 'verify AGENTIC_ATTESTOR_URL points at a reachable attestor, then retry' },
63
- );
69
+ throw attestorUnreachable(env, e);
70
+ }
71
+ }
72
+
73
+ /**
74
+ * The attestor did not answer (or answered something that is not an
75
+ * attestor's /config): one line naming it, and the remedy where its URL came
76
+ * from — the env var the owner set, or `login`, which saved it. The full
77
+ * reason stays in `details.cause` for `--json`.
78
+ */
79
+ export function attestorUnreachable(env: Pick<CliEnv, 'attestorUrl' | 'attestorUrlSource'>, e: unknown): CliError {
80
+ const url = env.attestorUrl ?? '(unset)';
81
+ const why = unreachableReason(e);
82
+ const notUrl = !isWebAddress(url) || why === 'not a valid URL';
83
+ const fromEnv = env.attestorUrlSource === 'env';
84
+ return new CliError('ATTESTOR_UNREACHABLE', notUrl
85
+ ? `"${url}" is not a web address (https://… or http://…) — an attestor's is like https://agentdna.0g.ai`
86
+ : `the attestor at ${url} did not answer (${why})`, {
87
+ remedy: notUrl
88
+ ? (fromEnv ? 'set AGENTIC_ATTESTOR_URL to the attestor\'s address' : shellTo('login', 'set the address again'))
89
+ : fromEnv
90
+ ? 'check AGENTIC_ATTESTOR_URL and your network, then try again'
91
+ : `check your network and try again, or ${shellTo('login', 'change the address')}`,
92
+ details: { cause: e instanceof Error ? e.message : String(e) },
93
+ });
94
+ }
95
+
96
+ /** An http(s) URL with a host: the only kind of address an attestor has. */
97
+ export function isWebAddress(url: string): boolean {
98
+ try {
99
+ const u = new URL(url);
100
+ return (u.protocol === 'https:' || u.protocol === 'http:') && !!u.hostname;
101
+ } catch {
102
+ return false;
103
+ }
104
+ }
105
+
106
+ /** Why a request to a URL got nowhere, in a few words. */
107
+ export function unreachableReason(e: unknown): string {
108
+ const msg = e instanceof Error ? e.message : String(e);
109
+ // The system error's code sits somewhere down the cause chain (fetch wraps
110
+ // it; the SDK may wrap fetch).
111
+ let code: string | undefined;
112
+ let badPort = false;
113
+ for (let x = e as { cause?: unknown; code?: unknown; message?: unknown } | undefined, i = 0; x && i < 6 && !code; x = x.cause as typeof x, i++) {
114
+ if (typeof x.code === 'string' && /^E[A-Z_]+$|^UND_ERR/.test(x.code)) code = x.code;
115
+ if (x.message === 'bad port') badPort = true;
116
+ }
117
+ if (badPort) return 'a port web requests are not allowed to use';
118
+ if (/Failed to parse URL|Invalid URL/i.test(msg)) return 'not a valid URL';
119
+ if (code === 'ECONNREFUSED') return 'connection refused';
120
+ if (code === 'ENOTFOUND' || code === 'EAI_AGAIN') return 'unknown host';
121
+ if (/abort|timeout|timed out/i.test(msg) || code === 'UND_ERR_CONNECT_TIMEOUT') return 'no answer in time';
122
+ if (/^fetch failed$/i.test(msg.trim())) return 'no answer';
123
+ if (/JSON|Unexpected token/i.test(msg)) return 'what answered is not an attestor';
124
+ return explainError(e).message;
125
+ }
126
+
127
+ /**
128
+ * Whether `url` is an attestor: its /config answers JSON with the fields one
129
+ * serves. null when it is; otherwise the reason in a few words (`login`
130
+ * checks an address with this before saving it).
131
+ */
132
+ export async function probeAttestor(url: string, timeoutMs = 8000): Promise<string | null> {
133
+ if (!/^https?:\/\/[^\s/]+/i.test(url) || !isWebAddress(url)) return 'not a web address (https://… or http://…)';
134
+ try {
135
+ const r = await fetch(`${url.replace(/\/+$/, '')}/config`, { signal: AbortSignal.timeout(timeoutMs) });
136
+ if (!r.ok) return `its /config answered HTTP ${r.status}`;
137
+ const c = (await r.json().catch(() => null)) as Record<string, unknown> | null;
138
+ if (!c || typeof c !== 'object' || !('chain_id' in c || 'agentic_id_addr' in c || 'chain_rpc' in c)) {
139
+ return 'what answered is not an attestor';
140
+ }
141
+ return null;
142
+ } catch (e) {
143
+ return unreachableReason(e);
64
144
  }
65
145
  }