@0gfoundation/0g-agentdna 0.2.3 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (255) hide show
  1. package/GUIDE.md +190 -40
  2. package/OPERATORS.md +164 -0
  3. package/OPERATORS.zh.md +141 -0
  4. package/PROVIDERS.md +6 -0
  5. package/PROVIDERS.zh.md +3 -1
  6. package/README.md +84 -11
  7. package/dist/AgentClient.d.ts +374 -26
  8. package/dist/AgentClient.d.ts.map +1 -1
  9. package/dist/AgentClient.js +323 -40
  10. package/dist/AgentClient.js.map +1 -1
  11. package/dist/AgenticID.d.ts +170 -80
  12. package/dist/AgenticID.d.ts.map +1 -1
  13. package/dist/AgenticID.js +300 -42
  14. package/dist/AgenticID.js.map +1 -1
  15. package/dist/AttestorClient.d.ts +115 -31
  16. package/dist/AttestorClient.d.ts.map +1 -1
  17. package/dist/AttestorClient.js +276 -56
  18. package/dist/AttestorClient.js.map +1 -1
  19. package/dist/Credentials.d.ts +574 -0
  20. package/dist/Credentials.d.ts.map +1 -0
  21. package/dist/Credentials.js +838 -0
  22. package/dist/Credentials.js.map +1 -0
  23. package/dist/Operators.d.ts +60 -0
  24. package/dist/Operators.d.ts.map +1 -0
  25. package/dist/Operators.js +38 -0
  26. package/dist/Operators.js.map +1 -0
  27. package/dist/Providers.d.ts +13 -0
  28. package/dist/Providers.d.ts.map +1 -1
  29. package/dist/Providers.js +20 -1
  30. package/dist/Providers.js.map +1 -1
  31. package/dist/Releases.d.ts +51 -0
  32. package/dist/Releases.d.ts.map +1 -0
  33. package/dist/Releases.js +72 -0
  34. package/dist/Releases.js.map +1 -0
  35. package/dist/ReputationClient.d.ts +47 -3
  36. package/dist/ReputationClient.d.ts.map +1 -1
  37. package/dist/ReputationClient.js +204 -78
  38. package/dist/ReputationClient.js.map +1 -1
  39. package/dist/ServeProof.d.ts +70 -23
  40. package/dist/ServeProof.d.ts.map +1 -1
  41. package/dist/ServeProof.js +94 -35
  42. package/dist/ServeProof.js.map +1 -1
  43. package/dist/ServeSession.d.ts +17 -2
  44. package/dist/ServeSession.d.ts.map +1 -1
  45. package/dist/ServeSession.js +77 -9
  46. package/dist/ServeSession.js.map +1 -1
  47. package/dist/Settings.d.ts +25 -1
  48. package/dist/Settings.d.ts.map +1 -1
  49. package/dist/Settings.js +53 -1
  50. package/dist/Settings.js.map +1 -1
  51. package/dist/TrustRegistry.d.ts +28 -0
  52. package/dist/TrustRegistry.d.ts.map +1 -0
  53. package/dist/TrustRegistry.js +67 -0
  54. package/dist/TrustRegistry.js.map +1 -0
  55. package/dist/abi.d.ts +346 -34
  56. package/dist/abi.d.ts.map +1 -1
  57. package/dist/abi.js +150 -30
  58. package/dist/abi.js.map +1 -1
  59. package/dist/cli/attach.d.ts +79 -0
  60. package/dist/cli/attach.d.ts.map +1 -0
  61. package/dist/cli/attach.js +253 -0
  62. package/dist/cli/attach.js.map +1 -0
  63. package/dist/cli/commands/cells.d.ts +45 -0
  64. package/dist/cli/commands/cells.d.ts.map +1 -1
  65. package/dist/cli/commands/cells.js +77 -0
  66. package/dist/cli/commands/cells.js.map +1 -1
  67. package/dist/cli/commands/cred.d.ts +12 -0
  68. package/dist/cli/commands/cred.d.ts.map +1 -0
  69. package/dist/cli/commands/cred.js +43 -0
  70. package/dist/cli/commands/cred.js.map +1 -0
  71. package/dist/cli/commands/doctor.d.ts.map +1 -1
  72. package/dist/cli/commands/doctor.js +44 -35
  73. package/dist/cli/commands/doctor.js.map +1 -1
  74. package/dist/cli/commands/interactive.d.ts +597 -21
  75. package/dist/cli/commands/interactive.d.ts.map +1 -1
  76. package/dist/cli/commands/interactive.js +5082 -1323
  77. package/dist/cli/commands/interactive.js.map +1 -1
  78. package/dist/cli/commands/list.d.ts +5 -5
  79. package/dist/cli/commands/list.d.ts.map +1 -1
  80. package/dist/cli/commands/list.js +21 -26
  81. package/dist/cli/commands/list.js.map +1 -1
  82. package/dist/cli/commands/providers.d.ts +4 -0
  83. package/dist/cli/commands/providers.d.ts.map +1 -1
  84. package/dist/cli/commands/providers.js +19 -5
  85. package/dist/cli/commands/providers.js.map +1 -1
  86. package/dist/cli/commands/releases.d.ts +13 -0
  87. package/dist/cli/commands/releases.d.ts.map +1 -0
  88. package/dist/cli/commands/releases.js +65 -0
  89. package/dist/cli/commands/releases.js.map +1 -0
  90. package/dist/cli/commands/settings.d.ts +5 -0
  91. package/dist/cli/commands/settings.d.ts.map +1 -1
  92. package/dist/cli/commands/settings.js +70 -24
  93. package/dist/cli/commands/settings.js.map +1 -1
  94. package/dist/cli/commands/status.d.ts +2 -1
  95. package/dist/cli/commands/status.d.ts.map +1 -1
  96. package/dist/cli/commands/status.js +22 -19
  97. package/dist/cli/commands/status.js.map +1 -1
  98. package/dist/cli/config.d.ts +48 -1
  99. package/dist/cli/config.d.ts.map +1 -1
  100. package/dist/cli/config.js +114 -5
  101. package/dist/cli/config.js.map +1 -1
  102. package/dist/cli/credentials.d.ts +179 -0
  103. package/dist/cli/credentials.d.ts.map +1 -0
  104. package/dist/cli/credentials.js +1443 -0
  105. package/dist/cli/credentials.js.map +1 -0
  106. package/dist/cli/download.d.ts +21 -0
  107. package/dist/cli/download.d.ts.map +1 -0
  108. package/dist/cli/download.js +89 -0
  109. package/dist/cli/download.js.map +1 -0
  110. package/dist/cli/env.d.ts +6 -0
  111. package/dist/cli/env.d.ts.map +1 -1
  112. package/dist/cli/env.js +18 -6
  113. package/dist/cli/env.js.map +1 -1
  114. package/dist/cli/envelope.d.ts +4 -2
  115. package/dist/cli/envelope.d.ts.map +1 -1
  116. package/dist/cli/envelope.js +10 -6
  117. package/dist/cli/envelope.js.map +1 -1
  118. package/dist/cli/errors.d.ts +45 -1
  119. package/dist/cli/errors.d.ts.map +1 -1
  120. package/dist/cli/errors.js +77 -0
  121. package/dist/cli/errors.js.map +1 -1
  122. package/dist/cli/inference.d.ts.map +1 -1
  123. package/dist/cli/inference.js +7 -0
  124. package/dist/cli/inference.js.map +1 -1
  125. package/dist/cli/inkView.d.ts +341 -0
  126. package/dist/cli/inkView.d.ts.map +1 -0
  127. package/dist/cli/inkView.js +1019 -0
  128. package/dist/cli/inkView.js.map +1 -0
  129. package/dist/cli/legacy/modelKey.d.ts +24 -0
  130. package/dist/cli/legacy/modelKey.d.ts.map +1 -0
  131. package/dist/cli/legacy/modelKey.js +32 -0
  132. package/dist/cli/legacy/modelKey.js.map +1 -0
  133. package/dist/cli/livePrompt.d.ts +212 -0
  134. package/dist/cli/livePrompt.d.ts.map +1 -0
  135. package/dist/cli/livePrompt.js +576 -0
  136. package/dist/cli/livePrompt.js.map +1 -0
  137. package/dist/cli/main.js +206 -72
  138. package/dist/cli/main.js.map +1 -1
  139. package/dist/cli/modelkey.d.ts +64 -0
  140. package/dist/cli/modelkey.d.ts.map +1 -0
  141. package/dist/cli/modelkey.js +113 -0
  142. package/dist/cli/modelkey.js.map +1 -0
  143. package/dist/cli/outboxSync.d.ts +51 -0
  144. package/dist/cli/outboxSync.d.ts.map +1 -0
  145. package/dist/cli/outboxSync.js +210 -0
  146. package/dist/cli/outboxSync.js.map +1 -0
  147. package/dist/cli/plain.d.ts +46 -0
  148. package/dist/cli/plain.d.ts.map +1 -0
  149. package/dist/cli/plain.js +260 -0
  150. package/dist/cli/plain.js.map +1 -0
  151. package/dist/cli/proofs.d.ts +5 -0
  152. package/dist/cli/proofs.d.ts.map +1 -1
  153. package/dist/cli/proofs.js +20 -0
  154. package/dist/cli/proofs.js.map +1 -1
  155. package/dist/cli/ref.d.ts.map +1 -1
  156. package/dist/cli/ref.js +3 -2
  157. package/dist/cli/ref.js.map +1 -1
  158. package/dist/cli/releaseNotice.d.ts +64 -0
  159. package/dist/cli/releaseNotice.d.ts.map +1 -0
  160. package/dist/cli/releaseNotice.js +194 -0
  161. package/dist/cli/releaseNotice.js.map +1 -0
  162. package/dist/cli/sdk.d.ts +18 -0
  163. package/dist/cli/sdk.d.ts.map +1 -1
  164. package/dist/cli/sdk.js +99 -1
  165. package/dist/cli/sdk.js.map +1 -1
  166. package/dist/cli/settings.d.ts +90 -9
  167. package/dist/cli/settings.d.ts.map +1 -1
  168. package/dist/cli/settings.js +273 -21
  169. package/dist/cli/settings.js.map +1 -1
  170. package/dist/cli/textfit.d.ts +28 -0
  171. package/dist/cli/textfit.d.ts.map +1 -0
  172. package/dist/cli/textfit.js +111 -0
  173. package/dist/cli/textfit.js.map +1 -0
  174. package/dist/constants.d.ts +1 -1
  175. package/dist/constants.js +1 -1
  176. package/dist/context.d.ts +26 -0
  177. package/dist/context.d.ts.map +1 -1
  178. package/dist/context.js +1 -0
  179. package/dist/context.js.map +1 -1
  180. package/dist/index.d.ts +19 -11
  181. package/dist/index.d.ts.map +1 -1
  182. package/dist/index.js +35 -2
  183. package/dist/index.js.map +1 -1
  184. package/dist/legacy/modelKey.d.ts +67 -0
  185. package/dist/legacy/modelKey.d.ts.map +1 -0
  186. package/dist/legacy/modelKey.js +80 -0
  187. package/dist/legacy/modelKey.js.map +1 -0
  188. package/dist/legacy/serveProofV1.d.ts +56 -0
  189. package/dist/legacy/serveProofV1.d.ts.map +1 -0
  190. package/dist/legacy/serveProofV1.js +91 -0
  191. package/dist/legacy/serveProofV1.js.map +1 -0
  192. package/dist/provider-catalog.json +3 -2
  193. package/dist/secretEnv.d.ts +18 -3
  194. package/dist/secretEnv.d.ts.map +1 -1
  195. package/dist/secretEnv.js +16 -2
  196. package/dist/secretEnv.js.map +1 -1
  197. package/dist/types.d.ts +63 -1
  198. package/dist/types.d.ts.map +1 -1
  199. package/dist/viemErrors.d.ts +30 -0
  200. package/dist/viemErrors.d.ts.map +1 -0
  201. package/dist/viemErrors.js +36 -0
  202. package/dist/viemErrors.js.map +1 -0
  203. package/package.json +5 -1
  204. package/src/AgentClient.ts +622 -68
  205. package/src/AgenticID.ts +345 -56
  206. package/src/AttestorClient.ts +330 -83
  207. package/src/Credentials.ts +1027 -0
  208. package/src/Operators.ts +71 -0
  209. package/src/Providers.ts +20 -0
  210. package/src/Releases.ts +95 -0
  211. package/src/ReputationClient.ts +231 -79
  212. package/src/ServeProof.ts +123 -39
  213. package/src/ServeSession.ts +91 -9
  214. package/src/Settings.ts +61 -1
  215. package/src/TrustRegistry.ts +75 -0
  216. package/src/abi.ts +153 -30
  217. package/src/cli/attach.ts +257 -0
  218. package/src/cli/commands/cells.ts +104 -0
  219. package/src/cli/commands/cred.ts +44 -0
  220. package/src/cli/commands/doctor.ts +45 -37
  221. package/src/cli/commands/interactive.ts +4120 -664
  222. package/src/cli/commands/list.ts +21 -30
  223. package/src/cli/commands/providers.ts +17 -4
  224. package/src/cli/commands/releases.ts +60 -0
  225. package/src/cli/commands/settings.ts +75 -28
  226. package/src/cli/commands/status.ts +24 -21
  227. package/src/cli/config.ts +119 -4
  228. package/src/cli/credentials.ts +1379 -0
  229. package/src/cli/download.ts +80 -0
  230. package/src/cli/env.ts +22 -7
  231. package/src/cli/envelope.ts +10 -6
  232. package/src/cli/errors.ts +92 -0
  233. package/src/cli/inference.ts +8 -1
  234. package/src/cli/inkView.ts +969 -0
  235. package/src/cli/legacy/modelKey.ts +35 -0
  236. package/src/cli/livePrompt.ts +615 -0
  237. package/src/cli/main.ts +206 -76
  238. package/src/cli/modelkey.ts +124 -0
  239. package/src/cli/outboxSync.ts +231 -0
  240. package/src/cli/plain.ts +260 -0
  241. package/src/cli/proofs.ts +27 -0
  242. package/src/cli/ref.ts +5 -4
  243. package/src/cli/releaseNotice.ts +200 -0
  244. package/src/cli/sdk.ts +87 -7
  245. package/src/cli/settings.ts +275 -25
  246. package/src/cli/textfit.ts +95 -0
  247. package/src/constants.ts +1 -1
  248. package/src/context.ts +28 -0
  249. package/src/index.ts +50 -7
  250. package/src/legacy/modelKey.ts +80 -0
  251. package/src/legacy/serveProofV1.ts +124 -0
  252. package/src/provider-catalog.json +3 -2
  253. package/src/secretEnv.ts +18 -3
  254. package/src/types.ts +60 -1
  255. package/src/viemErrors.ts +39 -0
package/GUIDE.md CHANGED
@@ -126,7 +126,7 @@ const params = {
126
126
  // image (the operator-maintained default; same fallback reset() uses).
127
127
  // Pass a name only to pin/rollback (0g-sandbox calls this field `snapshot` on the wire):
128
128
  sealedImage: process.env.SEALED_IMAGE,
129
- apiKey: process.env.AGENT_API_KEY, // injected into the container as an env secret
129
+ apiKey: process.env.AGENT_API_KEY, // the model key: stored in the agent's credential set
130
130
  },
131
131
  };
132
132
 
@@ -214,25 +214,26 @@ await ag.agent.balanceOf(owner); // → 5n agents owned by `own
214
214
  const agentSeal = await ag.agent.getAgentSeal(agentId);
215
215
  await ag.agent.topUpAgentSeal(agentSeal, parseEther('0.01')); // → tx hash "0x…"
216
216
 
217
- // runtime start / stop / reset (owner-signed; on-chain identity preserved):
217
+ // runtime start / stop / reset (owner or appointed operator; identity preserved):
218
218
  await ag.agent.stop(sealId, sandboxId); // stop a running container
219
219
  await ag.agent.start(sealId, sandboxId); // resume a STOPPED container
220
- await ag.agent.start(sealId, { apiKey }); // FIRST provision: bring a mint-only /
221
- // never-provisioned agent online with a fresh
222
- // container (apiKey required in practice). The
223
- // semantic counterpart to a sandbox-less deploy;
224
- // distinct from reset ("recreate an EXISTING one").
220
+ await ag.agent.start(sealId, { apiKey }); // owner: resume the mapped sandbox, or first
221
+ // provision when there is no mapping.
222
+ // A failed resume never implicitly creates
223
+ // another paid sandbox; use reset explicitly.
224
+ // apiKey: see "The model key" below.
225
225
  await ag.agent.reset(sealId, { apiKey }); // recreate an EXISTING container: re-read iData
226
226
  // from chain, reselect the framework adapter.
227
- // apiKey required in practice (attestor doesn't
228
- // cache the model key); sealedImage optional.
227
+ // sealedImage optional.
229
228
  // A booting agent with no settings document uses the model pinned in its minted
230
- // persona, which leaves the chain at its first commit. So start and reset of an
229
+ // persona, which leaves the chain at its first commit. So OWNER start and reset of an
231
230
  // agent that has no document and is a clone or has provisioned before first
232
231
  // store DEFAULT_PERSONA_INFERENCE (0g-compute) as its settings: one more owner
233
232
  // signature, after every check that can refuse the call; an existing document is
234
233
  // never replaced. To start such an agent on another provider, write its settings
235
234
  // (setSettings) first. The CLI's reset applies the same rule (needsDefaultSettings).
235
+ // Operators call start(sealId)/stop(sealId) after owner configuration; they cannot
236
+ // supply model-key options or write settings/credentials. See OPERATORS.md.
236
237
  await ag.agent.listDeployments();
237
238
  // → [{ agentId, sealId, phase, sandboxId, url, owner, name, createdAt, lastProvisionError,
238
239
  // containerStatus }, …]
@@ -247,7 +248,8 @@ One document per agent says which model it thinks with and how hard. It is **not
247
248
 
248
249
  ```ts
249
250
  const { settings, version } = await ag.agent.getSettings(sealId);
250
- // settings → { provider?, model?, thinking?: 'low'|'high'|'max', framework?: <any JSON> } | null
251
+ // settings → { provider?, model?, thinking?: 'low'|'high'|'max', others?: <any JSON>,
252
+ // versions?: { sealed?, harness? } } | null
251
253
  // null = never configured (not an error)
252
254
  // version → what to write back against; 0 when there is no document yet
253
255
 
@@ -259,6 +261,8 @@ await ag.agent.setSettings(sealId, { ...(settings ?? {}), model: '0gm-1.0-35b-a3
259
261
 
260
262
  **Whole-document write.** `setSettings` replaces the document — read it first and spread it to change one field. A `thinking` outside `low|high|max` (case-insensitive, as the container compares it) is refused before signing.
261
263
 
264
+ **Version picks (0g-harness).** `versions: { sealed, harness }` pins the layered runtime to a sealed program and an official harness version, each by its sha256 (`"0x"` + 64 hex; anything else is refused before signing). A pick for a layer this SDK does not know is written back as it is, as an unknown top-level field is. `ag.agent.listedVersions()` reads what the trust registry lists — `{ registry, sealed: [...], harness: [...] }` in listing order, the last the newest; `null` on a chain without a trust registry (AgenticID before 1.4.0, whose `trustRegistry()` reverts); any other failed read throws. The agent runs a pick while it is listed; a layer with no pick keeps its running version while that stays listed and otherwise moves to the newest. The container applies a pushed document at once (`pushSettingsToContainer`), every boot, and every five minutes; the other frameworks ignore `versions`.
265
+
262
266
  **Who may read or write it.** Owner-signed, both directions, against the **live on-chain owner** read at request time — so a seller cannot keep configuring (or reading) an agent they already sold. The SDK signs `AgenticID.Settings.v1:<sealId>:<ts>:<base_version>:<sha256 of the document>` (EIP-191) for a write, and the same message minus the digest for a read (`GET /settings`, no body, base version 0). A rejected call is a clearly-worded HTTP 401. The document is on **no** listing tier and on no public deployment row: `getSettings` is the only way to read it.
263
267
 
264
268
  **Compare-and-swap.** `baseVersion` is the version you read before editing. If the stored version has moved on — another client, another device, a replayed request — the write is refused with `SettingsConflictError`, which carries the live document and its version:
@@ -318,6 +322,11 @@ const data = await response.json(); // your normal response bo
318
322
  // validator: "0x…" } | null
319
323
  // (validator = the VerifiedFeedbackRegistry the proof was signed for; diagnostics
320
324
  // only — it is not part of the on-chain proof)
325
+ // A 0g-harness agent on the layered runtime signs a v2 proof, which adds what
326
+ // each layer ran: { …, version: 2, sealedHash: "0x…", harnessHash: "0x…",
327
+ // inferenceURL: "https://…" (or "" when the framework dials its provider itself),
328
+ // model: "…" }. Without `version` it is v1 (every other image). The version picks
329
+ // the digest and the registry entry point; the SDK handles both.
321
330
  // low-level escape hatch (you build the whole request): ag.reputation.capture(() => fetch(…))
322
331
 
323
332
  // 2. verify before spending gas (signer == on-chain agentSeal, deadline, dataHashes ⊆ iData).
@@ -329,7 +338,15 @@ const data = await response.json(); // your normal response bo
329
338
  // the CLI's `rate` does.
330
339
  await ag.reputation.verifyProof(proof);
331
340
  // → { ok: true, signerMatches: true, notExpired: true, dataOnChain: true, registryMatches: true,
332
- // taskMatches: null, reasons: [] }
341
+ // layersListed: null, taskMatches: null, reasons: [] }
342
+ // layersListed: null for a v1 proof. For v2, whether the image (frameworkHash),
343
+ // the sealed program and the official harness version it names are all on the
344
+ // trust registry's lists now (AgenticID.trustRegistry(), 1.4.0+) — `ok` needs it;
345
+ // a version delisted since the proof was signed fails, with the layer named in
346
+ // reasons. The registry does not check the lists, so such a proof still redeems.
347
+ // A chain whose AgenticID has no trustRegistry() (it reverts) gives false with a
348
+ // reason; a list read that fails for any other reason throws. The envelope is
349
+ // read as UTF-8, so a model or URL with non-ASCII text verifies.
333
350
  // signer attribution only. Pass { task } (the TaskExchange fetchWithProof
334
351
  // recorded) to also get taskMatches — the proof bound to THIS exchange's
335
352
  // bytes; ok requires the match, and task: null fails closed. Hand-rolled
@@ -368,6 +385,10 @@ await ag.reputation.verifyProof(proof);
368
385
  // beyond the registry's nonce retention, state changing between the check and
369
386
  // the attest, and non-proof tx failures (gas, RPC) — the proof stays
370
387
  // unconsumed, so retry with attestFeedback where that can help.
388
+ // A v2 proof goes to attestVersionedFeedback (VerifiedFeedbackRegistry 1.3.0+;
389
+ // on an older registry it is refused before anything is broadcast), atomically
390
+ // through a batcher that has giveFeedbackAndAttestVersioned (the SDK asks it
391
+ // gas-free once), else on the sequential path with the same preflight.
371
392
  // NOTE: an agent's OWNER cannot attest feedback on their own agent — the
372
393
  // verified registry rejects it (VerifiedFeedbackSelfFeedback). Feedback must
373
394
  // come from a different wallet than the one that owns `agentId`. Neither can
@@ -434,6 +455,7 @@ await ag.reputation.getVerifiedSummary({ agentId }); // unscoped →
434
455
  await ag.reputation.getVerifiedClients(agentId); // → [ "0x…", … ] clients with ≥1 verified entry
435
456
  await ag.reputation.getVerifiedIndexes(agentId, buyer); // → [ 1n, 2n ]
436
457
  await ag.reputation.getServeData(agentId, buyer, idx); // → { dataHashes: ["0x…"], frameworkHash: "0x…" } (verified entries only)
458
+ await ag.reputation.getServeLayers(agentId, buyer, idx); // → { sealedHash: "0x…", harnessHash: "0x…" } (v2 entries; zero for v1; registry 1.3.0+)
437
459
 
438
460
  // owner responds to a feedback entry; the client who left it can revoke
439
461
  await ag.reputation.appendResponse({ agentId, clientAddress: buyer, feedbackIndex: idx, responseURI: 'ipfs://Qm…', responseHash: keccak256(toBytes('thanks')) });
@@ -566,10 +588,33 @@ For the router's live model catalog:
566
588
  await ag.agent.listModels(); // → ['claude-opus-4-8', 'deepseek-v4-pro', …]
567
589
  ```
568
590
 
569
- `sandbox.apiKey` is required in practice — without it the agent boots but
570
- cannot reach its model. It travels inside the owner-signed "create"
571
- envelope into the TEE container's environment, and the attestor keeps no
572
- reusable copy (which is why `reset()` needs it again).
591
+ **The model key.** `sandbox.apiKey` (and `apiKey` of `start` / `reset` /
592
+ `retry`) is stored in the agent's credential set as `model.<provider>`,
593
+ sealed to the agent ([credentials](../../docs/credentials.md#the-model-key)):
594
+ `deploy` checks the key before it signs anything and stores it as soon as
595
+ the attestor accepts the agent, without waiting for the mint
596
+ (`modelKeyStored` in the result); the attestor creates the container once
597
+ it is stored, ten seconds after the mint without one, or after a minute at
598
+ the latest, so the first boot has it (`awaitCredentials`, signed with the
599
+ deploy). `start` / `reset` / `retry` store it after their own checks pass,
600
+ before the request is signed. A store asks the owner's wallet for three
601
+ signatures (reading the stored set, the new set, the write); `deploy`'s for
602
+ two, as the new agent has no set to read. A container whose image reads
603
+ model keys from the set takes the key from there at boot, so with one
604
+ stored, a `reset` on that image needs none, and a `retry` with the
605
+ provider's key in the set can create a container. A key given without
606
+ `provider` is the 0g-compute key (`model.0g-compute`): pass `provider` for
607
+ any other provider's key. `ag.credentials.setModelKey(sealId, provider,
608
+ apiKey)` sets or replaces it at any time (three signatures, a fourth to
609
+ push it to the running agent). Without a key, 0g-harness on 0g-compute
610
+ boots and its model calls fail until one is set; with no key for the
611
+ provider in the set, the CLI asks for one for every other framework and
612
+ provider, and the SDK refuses a create without one for a provider other
613
+ than 0g-compute.
614
+
615
+ While older images are in use, the key also travels with the request:
616
+ inside the owner-signed "create" envelope into the TEE container's
617
+ environment, of which the attestor keeps no copy.
573
618
 
574
619
  The owner's wallet shows that envelope verbatim when it signs. When the
575
620
  attestor's `GET /config` advertises `secret_env_scheme`, `start` / `reset` /
@@ -590,22 +635,29 @@ without `sandbox`, persist the provider/model settings, then
590
635
 
591
636
  **When your app supplies the key and the user signs.** Sealing in the
592
637
  browser still means the key reaches the user's browser. Seal it on your
593
- server instead, and hand the browser only the ciphertext:
638
+ server instead, and hand the browser only the sealed key:
594
639
 
595
640
  ```ts
596
641
  // server: a read-only client is enough (no wallet)
597
642
  const ag = new AgentDNA({ attestorUrl, addresses, rpcUrl, chain });
598
- const sealed = await ag.agent.sealApiKey(sealId, { owner, apiKey });
643
+ const sealed = await ag.credentials.sealModelKey(sealId, { owner, provider, apiKey });
599
644
 
600
- // browser: signs ciphertext only; the key never reaches it
601
- await ag.agent.start(sealId, { sealedSecretEnv: sealed });
645
+ // browser: stores it in the agent's credential set, signing only its hash
646
+ await ag.credentials.setModelKey(sealId, provider, sealed);
647
+ // or with a new container, in place of apiKey
648
+ await ag.agent.start(sealId, { sealedModelKey: sealed });
602
649
  ```
603
650
 
604
- `owner` must be the wallet that signs: the container applies the secret only
605
- while that address owns the agent on chain, so `sealApiKey` checks `ownerOf`
606
- once the agent is minted. `sealedSecretEnv` is accepted by `start` / `reset`
607
- / `retry`, requires the attestor to advertise `secret_env_scheme`, and never
608
- falls back to `API_KEY`.
651
+ `owner` must be the wallet that signs: the value is bound to it (and to the
652
+ agent, the chain and `model.<provider>`), so `sealModelKey` checks `ownerOf`
653
+ once the agent is minted, and `setModelKey` refuses a key sealed for another
654
+ agent, provider or wallet. From the set the key reaches every boot of the
655
+ agent, like the owner's own key. While older images are in use,
656
+ `sealed.secretEnv` holds the same key as they read it with the request;
657
+ `start` / `reset` / `retry` send it (it is present when the attestor
658
+ advertises `secret_env_scheme`). The request-only form, `agent.sealApiKey`
659
+ passed as `sealedSecretEnv`, still works for the request it rides and goes
660
+ away with the request path.
609
661
 
610
662
  Every refusal on these paths throws `SecretEnvRefusedError` (exported) before
611
663
  anything is signed or sent: `signed` is always `false`, and `code` names the
@@ -685,6 +737,22 @@ const agentUrl = me?.url; // null until the container is provision
685
737
  if (me.phase === 'failed') await ag.agent.retry(me.sealId, { apiKey });
686
738
  ```
687
739
 
740
+ When a release replaces an image, your agents on the old one keep running
741
+ through a transition period, and the owner listing marks them: `migrate` is
742
+ `{ version, framework, until, urgent, state }` (`state`: `recommended`, `soon`
743
+ in the last 7 days, `overdue` after `until`). Reset such an agent before
744
+ `until`: after it the old image may be retired, and the agent's next boot is
745
+ then refused until it is reset. `urgent` means the image may be retired sooner
746
+ (a security fix).
747
+ `ag.agent.releases()` reads the attestor's release notices (`GET /releases`):
748
+ each release's `notes` (and `notesZh`) and the images it replaces.
749
+
750
+ ```ts
751
+ const toMove = (await ag.agent.listMyDeployments()).filter((d) => d.migrate);
752
+ for (const d of toMove) console.log(d.agentId, d.migrate!.until, d.migrate!.state);
753
+ const [latest] = await ag.agent.releases(); // newest first
754
+ ```
755
+
688
756
  - **`GET {agentUrl}/hello`** — public identity card: who I am, my owner, and
689
757
  the surface I expose. Buffered responses carry a signed `X-Agent-Proof`
690
758
  (a framework route's SSE stream doesn't — a signature needs a complete
@@ -710,9 +778,12 @@ if (me.phase === 'failed') await ag.agent.retry(me.sealId, { apiKey });
710
778
  - `routes` — the framework's declared prefixes:
711
779
  `{ prefix, kind?, auth?, signed, description? }`, e.g. a `kind:"chat"` API
712
780
  at `/v1/` (auth `bearer`). `auth` tells you how to present the owner token;
713
- `signed` says whether responses on that route carry an `X-Agent-Proof`.
714
- Shipped frameworks are chat-only; a framework could declare a UI route,
715
- but none currently do.
781
+ `signed` says whether responses on that route carry an `X-Agent-Proof`;
782
+ `description` is one plain sentence on what the route is for. Every
783
+ shipped framework declares a `chat` route, and `/hello` lists a
784
+ `responses` route next to it (the runtime serves one where the framework
785
+ does not); prime adds `activity`, 0g-harness `tasks`, `inbox`, `files`
786
+ and more. A framework could declare a UI route, but none currently do.
716
787
 
717
788
  - **`ag.agent.client(agentId)`** — one handle (`AgentClient`) for every caller.
718
789
  Whether it can do owner ops is inherited from `ag`, exactly like `ag`'s
@@ -765,6 +836,22 @@ if (me.phase === 'failed') await ag.agent.retry(me.sealId, { apiKey });
765
836
  // is "not now", nothing changed (a compaction or a turn already running, the
766
837
  // framework busy, or a reused signature: retry later).
767
838
 
839
+ // `ag.agent.restartRuntime(base, agentId, 'harness' | 'sealed', instanceId?)`
840
+ // (CLI `/restart`) restarts one layer of a 0g-harness runtime in place: the
841
+ // harness process (conversation and disk stay), or sealed itself — the loader
842
+ // starts it again and the agent is away for about one start. Either applies
843
+ // the owner's version picks and the trust registry's lists. 202 once under
844
+ // way; 501 where there is no such restart (other frameworks, an image without
845
+ // the loader), 503 while sealed is still starting, 409 for a reused signature
846
+ // or a displaced window.
847
+
848
+ // `ag.agent.signatures(base, agentId, { after })` (CLI `/signatures`) reads
849
+ // what the agent signed as itself and what the runtime refused, oldest
850
+ // first, whichever way the agent reached its sign socket: a message's hash
851
+ // and start, a typed-data digest and domain, a transaction's hash, chain,
852
+ // target, value, nonce and selector. The runtime keeps the last 1000.
853
+ // 0g-harness agents only; the other frameworks keep no record (HTTP 404).
854
+
768
855
  // Chat — present ONLY if the agent declares a chat route AND this ag has a
769
856
  // key. Streams under the hood (`stream: true`), so a long reasoning turn
770
857
  // keeps bytes flowing and never trips an idle-timeout hop in front of the
@@ -860,15 +947,66 @@ for await (const e of agent.events!({ after: box.cursor, signal })) {
860
947
  if (e.type === 'reset') { /* the agent could not serve the position: re-read the inbox */ }
861
948
  }
862
949
 
863
- const tasks = await agent.tasks!({ status: 'active' });
864
- // every turn (yours and the agent's), command (bash-N) and subagent (subagent-N):
950
+ const running = await agent.activities!({ status: 'active' });
951
+ // every turn (yours and the agent's), command (bash-<hex>) and subagent (its session id, a UUID):
865
952
  // actor = who does the work (agent | subagent), trigger = who asked
866
- await agent.taskInfo!('subagent-1'); // includes a finished subagent's answer
867
- await agent.stopTask!('bash-2'); // a turn is cancelled, a command or subagent is killed
868
- await agent.stopAllTasks!(); // everything running
953
+ await agent.activity!(running[0].id); // a finished subagent's entry includes its answer
954
+ await agent.stopActivity!('bash-2'); // a turn is cancelled, a command or subagent is killed
955
+ await agent.stopAllActivities!(); // everything running
956
+ // tasks/taskInfo/stopTask/stopAllTasks are the deprecated names of these; "task"
957
+ // is kept for zgh-style tasks (a unit of work with its own session and outcome)
869
958
  await agent.schedules!(); // { enabled, data }: the reminders the agent set for itself
870
959
  ```
871
960
 
961
+ A 0g-harness owner's `others` section also picks the agent's web search service
962
+ (`webSearch`: the 0G router by default, or OpenAI or Anthropic) and the further
963
+ models its subagents may run on (`subagentModels`, `subagentDefault`); each is
964
+ paid with the model key or a named owner credential, never a key the agent
965
+ holds. sealed's harness adapter README lists the fields; the CLI checks their
966
+ shape before signing.
967
+
968
+ A 0g-harness agent also takes **images and files** from its owner. Images ride
969
+ a message: `chat` / `chatStream` take `images: [{ mediaType, data }]` (PNG, JPEG,
970
+ WebP or GIF, base64; at most 8 per message, 10 MiB each, 32 MiB together),
971
+ sent on the last user message in the transport's own shape. Whether the model
972
+ sees them is what the provider's model list says (the 0G router's
973
+ `architecture.input_modalities`: glm-5.3 takes text only, glm-5.3-flash images
974
+ too); the owner's `others.modelImages` overrides it. A model that cannot view
975
+ images gets each one saved as a file in the agent's file inbox `~/inbox` instead; the
976
+ `onNotice` callback receives `{ imagesSavedAsFiles: [paths] }`. An image may
977
+ carry its file name (`{ mediaType, data, name: 'flag test.png' }`): the SDK
978
+ sends it as the part's `filename` when the agent's `GET /v1/harness` lists
979
+ `features.image_names` (asked once per client), so the saved file keeps that
980
+ name instead of `image-<ms>-<n>.png`; elsewhere the name is left out. Any other file
981
+ goes through `uploadFile(name, bytes)` (present when `/hello` declares kind
982
+ `files`; at most 25 MiB): it lands in `~/inbox` under a new name, never over
983
+ an existing file, and returns `{ path, bytes }` — name the path in your
984
+ message. Both live in the container only: a reset loses them.
985
+
986
+ **Steering a running turn** (0g-harness, present when `/hello` declares kind
987
+ `steer`): `agent.steer(text)` puts the owner's word into the turn that is
988
+ running now; the agent reads it before that turn's next model call — when the
989
+ current model answer or tool call finishes, not in the middle of a long
990
+ command. It returns `{ merged: true, id, turn }`; with no owner turn running
991
+ it is queued as an ordinary turn instead, `{ merged: false, queued, reason }`.
992
+ `agent.steerState(id)` tells what became of it: `pending`, `merged` (read in
993
+ `turn`), `turn` (the turn ended first, so it opened `turn`, an owner turn of
994
+ its own) or `dropped` (an interrupt came first).
995
+
996
+ The way back: the agent puts files for its owner in its `~/outbox`.
997
+ `listFiles(dir?)` lists them (`'outbox'`, the default, or `'inbox'` for the
998
+ owner's own files), newest first, as `{ name, bytes, mtime, sha256? }`;
999
+ `downloadFile(dir, name)` returns one file's bytes (at most 50 MiB; one flat
1000
+ name, no leading dot). A turn that leaves files new or changed in the outbox
1001
+ says so: `onNotice` receives `{ outboxFiles: [names] }` when the turn ends.
1002
+ `deleteFile(dir, name)` removes one (`'deleted'`, `'missing'`, or
1003
+ `'unsupported'` from a runtime without the delete route). The methods share
1004
+ the `files` route; an agent whose runtime predates downloads answers with an
1005
+ error saying so. The outbox lives in the container only, like the file
1006
+ inbox, and the runtime removes files older than 30 days from both and keeps
1007
+ the file inbox under 1 GiB. The file inbox `~/inbox` is not the message inbox
1008
+ (`inbox()`, what the agent said in turns it opened itself).
1009
+
872
1010
  ## Agents as owners (nested agents)
873
1011
 
874
1012
  An agent inside a sealed container can run this SDK **as itself** — deploy
@@ -929,7 +1067,7 @@ The stable protocol-level constants **are** exported: `ZERO_G_TESTNET` / `ZERO_G
929
1067
 
930
1068
  ## Advanced
931
1069
 
932
- Raw ABIs (`agenticIDAbi`, `canonicalReputationAbi`, `verifiedFeedbackAbi`, `feedbackBatcherAbi`, `cloneGateAbi`, `standardCloneAuthorizerAbi`, `tappRegistryAbi`, `sandboxServingAbi`) and serve-proof primitives (`buildServeProofMessageHash`, `buildServeProofSigningHash`, `signServeProof`, `verifyServeProofSignature`, and for the `taskHash` commitment `taskHashOf`, `requestUriOf`, `requestUriCandidates`) are exported.
1070
+ Raw ABIs (`agenticIDAbi`, `trustRegistryAbi`, `canonicalReputationAbi`, `verifiedFeedbackAbi`, `feedbackBatcherAbi`, `cloneGateAbi`, `standardCloneAuthorizerAbi`, `tappRegistryAbi`, `sandboxServingAbi`), serve-proof primitives (`buildServeProofMessageHash`, `buildServeProofSigningHash`, `signServeProof`, `verifyServeProofSignature`, `serveProofLayers`, `SERVE_PROOF_VERSION`, `SERVE_PROOF_V2_TAG`, and for the `taskHash` commitment `taskHashOf`, `requestUriOf`, `requestUriCandidates`) and trust-registry reads (`trustRegistryOf`, `isListed`, `listedHashes`, `TRUST_KINDS`) are exported.
933
1071
 
934
1072
  **Serve-proof canonical digest** (for independent verifiers): two hashes.
935
1073
  The inner `proofHash` is
@@ -948,7 +1086,19 @@ It is **not** personal_sign: a personal_sign (`0x19 0x45`) signature over
948
1086
  `proofHash` is rejected, and nothing falls back to it. `buildServeProofMessageHash` /
949
1087
  `buildServeProofSigningHash` are the TS implementation; the Go side lives in
950
1088
  `sealed/internal/proxy/`. `npm run test:kav` pins both hashes to the
951
- known-answer vectors the contracts and sealed also assert. The sealed proxy
1089
+ known-answer vectors the contracts and sealed also assert.
1090
+
1091
+ That is v1, the proof without a `version`. A v2 proof (`version: 2`, signed by
1092
+ 0g-harness agents on the layered runtime) opens its preimage with a tag and
1093
+ adds what each layer ran, under the same 0x00 wrap:
1094
+ `keccak256(abi.encode(keccak256("AgentDNA.ServeProof.v2"), chainId,
1095
+ identityRegistry, submitter, agentId, timestamp, deadline, taskHash,
1096
+ keccak256(abi.encodePacked(dataHashes)), frameworkHash, sealedHash, harnessHash,
1097
+ keccak256(bytes(inferenceURL)), keccak256(bytes(model))))` — 14 words against
1098
+ v1's 9, so neither signature verifies as the other. The builders, `signServeProof`
1099
+ and `verifyServeProofSignature` pick the digest by the `version` field (pass
1100
+ `version: 2` and the four layer fields for v2); the registry redeems v2 through
1101
+ `attestVersionedFeedback` (1.3.0+). `npm run test:kav` pins the v2 vector too. The sealed proxy
952
1102
  learns the validator from `VERIFIED_FEEDBACK_ADDR` (injected by the attestor)
953
1103
  and echoes it as the envelope's `validator` field (diagnostics only, not part
954
1104
  of the on-chain tuple); when that variable is unset, malformed or zero — or
@@ -984,7 +1134,7 @@ The per-contract clients (`AgenticIDClient`, `ReputationClient`, `SandboxClient`
984
1134
 
985
1135
  ## CLI: `0g-agentdna`
986
1136
 
987
- The package ships a CLI — no separate install, zero extra dependencies. Bare `0g-agentdna` opens an **interactive shell** (Claude-Code style); `doctor`/`status`/`list`/`settings` remain scriptable diagnostics subcommands.
1137
+ The package ships a CLI — no separate install, zero extra dependencies. Bare `0g-agentdna` opens an **interactive shell** (Claude-Code style) at its manager prompt; `doctor`/`status`/`list`/`settings`/`cred`/`providers`/`releases`/`update` are scriptable one-shot commands. A word of the shell's own (`0g-agentdna login`, `whoami`, `deploy`, …) is refused with where to type it (run `0g-agentdna`, then type it there); any other word is an unknown command, with the nearest command named when it looks like a typo.
988
1138
 
989
1139
  ```bash
990
1140
  npm install @0gfoundation/0g-agentdna
@@ -998,9 +1148,9 @@ For the old CLI update path and automatic local-config migration, see
998
1148
 
999
1149
  ### Interactive shell
1000
1150
 
1001
- Two levels. The **manager** (`0g-agentdna>`): `list` (public listing with sealIds and the same FRAMEWORK/AGENTSEAL/OWNER columns as `0g-agentdna list`, `⇄ #<agentId>` on agent-owned agents, `*` marks your wallet's agents), `use <agentId|sealId>` (enter an agent's session in **any** phase), `hello <id>` (any agent's public /hello — with a wallet configured it also banks a rating ticket), `call <id> [path [json-body]]` (use an agent's registered public service as a client; bare `call <id>` lists its services; the response banks a rating ticket), `rate <id> [score] [/endpoint]` (rate an agent on-chain, spending a ticket banked by call/hello — no interaction, no rating; owners cannot rate their own agents), `deploy` (framework + model wizard), `start`/`stop`/`reset <id>`, `settings <id> [key=value …]` (show or change the agent's configuration document), `balance` / `deposit [og]` / `withdraw [og]` (prepaid sandbox account), `ack`, `login [provider]` (guided setup: attestor URL → owner key → provider → inference key; Enter keeps the current value, keys echo `*`), `whoami` (bare Enter does the same), `quit`.
1151
+ Two levels. The **manager** (`0g-agentdna>`): `list` (the same columns as `0g-agentdna list`, fitted to the terminal, `⇄ #<agentId>` on agent-owned agents, an agent without an agentId yet shown by its sealId prefix, `*` marks your wallet's agents), `use <agentId|sealId>` (enter an agent's session in **any** phase; an agent still being minted is entered once it has its agentId), `hello <id> [full]` (any agent's public /hello: identity, proof check, services one per line and owner routes on one line by kind; `full` prints every field — with a wallet configured it also banks a rating ticket), `call <id> [path [json-body]]` (use an agent's registered public service as a client; bare `call <id>` lists its services; the response banks a rating ticket), `rate <id> [score] [/endpoint]` (rate an agent on-chain, spending a ticket banked by call/hello — no interaction, no rating; owners cannot rate their own agents), `deploy` (framework → provider → model wizard: a listed number or name, anything else asked again), `start`/`stop`/`reset <id>` (not on an agent still deploying), `settings <id> [key=value …]` (show or change the agent's configuration document), `balance` / `deposit [og]` / `withdraw [og]` (prepaid sandbox account; an amount is checked before any transaction, a bare `deposit`/`withdraw` asks for it with no default — Enter cancels — and `withdraw <og>` asks before restarting a pending refund's time lock), `ack`, `status <id>` / `doctor` / `providers` / `releases` (the one-shot commands), `login [provider]` (guided setup: attestor URL → owner key → each provider's model key → the default provider for new agents; each answer is checked before it is saved and asked again when wrong, Enter keeps the current value, keys echo `*`), `whoami` (bare Enter does the same), `quit`. Errors are one or two plain lines with a remedy typed at that prompt.
1002
1152
 
1003
- The **session** (`agent 286 ›`): type to chat — **Esc / Ctrl-C interrupts the turn in flight** (the runtime cancels server-side on every bundled framework) and also cancels a `/start`//`/reset` wait. Slash commands: `/hello` `/balance` `/topup [og]` `/stop` `/start` `/reset` `/settings [key=value …]` `/think [level]` `/clear` (wipe the agent's conversation and start fresh — chain-tracked memory is untouched, unlike `/reset`) `/compact` (keep the conversation but have the framework summarize its older part now — 0g-harness, and openclaw 2026.7.1 or later; one or more model calls, can take minutes) `/tasks` `/result [id]` `/cancel [id|all]` `/inbox [all]` `/schedules` `/agentlog [n]` `/startuplog [n]` `/back` (alias `/unuse`) `/quit`. The framework (used by `/reset` and the chat model selector) is picked by you from the attestor's list — never guessed. On a 0g-harness agent, what the agent says on its own (a background job finished, a reminder came due) prints above the prompt as it arrives, and what came while you were away prints when you enter; `/tasks` lists every turn, background command and subagent with who did it, `/cancel <id>` stops any of them and `/cancel all` everything running. On the other frameworks `/inbox` and `/schedules` say the agent has none.
1153
+ The **session** (`agent 286 ›`): type to chat — **Esc / Ctrl-C interrupts the turn in flight** (the runtime cancels server-side on every bundled framework) and also cancels a `/start`//`/reset` wait. A message can span lines: a paste stays one message (shown as pasted, sent with the next Enter, never run as a command, whatever its first line starts with), and a line ending in `\` or Option/Alt+Enter goes on to a new line; Backspace at the start of a line joins it to the line before, and Ctrl-C or Esc with text in the box clears it, all its lines. On a terminal the session is drawn with Ink like Claude Code's input area: the `❯ ` input line between two rules at the bottom, a footer under it (it also says when the agent is not running, and the way out: `stopped — /start`; a bare Enter re-reads the phase and prints nothing), a status line above it during a turn (`⠹ running a command… (14s · Esc to stop)`, with `2 notices · 1 new file` at its right), the messages sent during the turn waiting above that, and the transcript scrolling above all of it — your messages as `❯ text`, replies, command output, notices, and one line per run of the agent's tool calls (`· ran 3 commands, read a file`); what you type stays in the box and can be edited while the agent replies. `AGENTDNA_INK=off`, a terminal under 30 columns or 12 rows, CI, or an `ink` package that does not load keep readline's prompt line, which stays on screen during a turn (`agent 286 (replying, Esc stops) › `) with the reply printing above it. On a 0g-harness agent a message you finish while the agent is working goes into the running turn of owner-chat (`agent.steer(text)` over `POST /v1/steer`): the agent reads it before the turn's next model call — shown as waiting for the agent until then (in the framed view it then moves into the transcript as your message; at readline's prompt `waiting for the agent: …`, then `↳ read by the agent: …`) — not in the middle of a long command; if the turn ends first, the agent answers it in the turn after (several such messages may be answered together) and the CLI follows it; an empty Enter waits for the next turn, and Esc stops the turn, the turns that would answer what was inserted and not read with it; those messages, and the ones queued, come back to be edited as one (a command that waited runs next, on its own). Which inserted messages come back is what the agent says after the stop: the ones it dropped (0g-harness drops them with the turn); one it read just before the stop prints as read; one an older 0g-harness still holds — it gives those to its next turn — is listed under `(not put back — …)` and stays out of the box, so it is not sent twice. A command alone on its line during a turn never goes to the agent: one that only reads (`/files`, `/tasks`, `/inbox`, `/hello`, …) runs at once, any other when the turn ends; Tab completes it. A turn that ends with no text because the model's output budget ran out says so (`no answer: …`); a failed turn says in one line whether the model service failed, the model is overloaded (try again for both), or what the error says (with `/agentlog`). Tab queues what you typed instead (shown as next turn, sent as your next message when the turn ends; Esc puts it back to edit, without blank lines), and ↑ on an empty prompt takes the newest queued entry back to edit. Option+Enter needs the Option key to send Meta: in macOS Terminal, Settings → Profiles → Keyboard → "Use Option as Meta key"; in iTerm2, Profiles → Keys → Left Option key: Esc+. Other questions take one line: several pasted lines are not their answer, and a paste does not answer a yes/no question or one that signs. Piped input stays one line per command. Slash commands: `/hello [full]` `/balance` `/topup [og]` `/stop` `/start` `/reset` `/settings [key=value …|versions]` `/think [level]` `/clear` (wipe the agent's conversation and start fresh — chain-tracked memory is untouched, unlike `/reset`) `/compact` (keep the conversation but have the framework summarize its older part now — 0g-harness, and openclaw 2026.7.1 or later; one or more model calls, can take minutes) `/restart harness|sealed` (0g-harness: restart one layer of the runtime in place) `/activities` `/tasks` `/result [id]` `/cancel [id|all]` `/inbox [all]` `/schedules` `/attach [path …|clear]` (0g-harness: files and images for your next message — an image goes with it, any other file is uploaded to the agent's file inbox `~/inbox` first and the message names its path) `/files [inbox]` (0g-harness: the files the agent left for you in its `~/outbox`; with `inbox`, the ones you sent) `/download <name> [path]` (0g-harness: save one locally, never over an existing file) `/agentlog [n]` `/startuplog [n]` `/back` (alias `/unuse`) `/quit`. The framework (used by `/reset` and the chat model selector) is picked by you from the attestor's list — never guessed. On a 0g-harness agent, what the agent says on its own (a notice: a background job finished, a reminder came due) prints above the prompt as it arrives, and what came while you were away prints when you enter (`/inbox` or `/notices` lists them); files it leaves in its `~/outbox` are saved by themselves to `~/agentdna/<agentId>/outbox` on a terminal and, once verified, removed from the agent's outbox (`/files auto off` stops that), and the status line (or, at readline's prompt, the prompt) counts what waits (`2 notices · 1 new file`); `/activities` lists every turn, background command and subagent with who did it, `/cancel <id>` stops any of them and `/cancel all` everything running. On the other frameworks `/inbox` and `/schedules` say the agent has none.
1004
1154
 
1005
1155
  Configuration persists under `~/.config/0g-agentdna/` — `config.json` (attestor URL), `credentials` (owner key + provider-scoped inference keys, JSON, chmod 600), and `proofs.json` (the **rating-ticket jar**, chmod 600): serve-proofs banked by `call`/`hello`, spent by `rate`. Ticket physics: they expire ~1 hour after the interaction (the sealed proxy sets the deadline; the chain enforces it), are single-use, capped at 5 per (agent, wallet) pair, and are redeemable ONLY by the wallet named in the proof's `submitter` — a leaked jar is useless to anyone else. `rate` checks a ticket on what the registry checks — expiry and the signature — and discards one that fails on its own merits (bad signature — e.g. one banked from a pre-1.2.0 sealed image — or expiry), but keeps one that fails only because no VerifiedFeedbackRegistry, or a different one, is configured on this side. A ticket whose data hashes the agent has since replaced (it commits state drift every 30 s) still redeems — the registry records the version that served you without comparing it to current chain state — so `rate` only notes it and goes ahead. The `AGENTIC_*` environment variables always override the files, so CI and one-off runs need no disk.
1006
1156
 
@@ -1009,9 +1159,9 @@ Configuration persists under `~/.config/0g-agentdna/` — `config.json` (attesto
1009
1159
  | Command | What |
1010
1160
  |---|---|
1011
1161
  | `doctor` | Checks every deploy prerequisite — attestor reachable, RPC, wallet, gas, trust-root ack, sandbox balance ≥ 0.1 OG — and prints a remedy per failing item. Exit 0 when all green, 3 otherwise. |
1012
- | `status <agent>` | One agent's full picture: phase, all three coordinates (agentId / sealId / agentSeal), url, failure reason. `<agent>` is a decimal agentId **or** a `0x…` sealId — the CLI converts between them. When a failed deployment's reason is withheld from the public listing (#64), a configured key makes the CLI fetch it via the owner-signed listing automatically. |
1162
+ | `status <agent>` | One agent's full picture: phase, all three coordinates (agentId / sealId / agentSeal), failure reason (`--json` also carries the container `url`). `<agent>` is a decimal agentId **or** a `0x…` sealId — the CLI converts between them. When a failed deployment's reason is withheld from the public listing (#64), a configured key makes the CLI fetch it via the owner-signed listing automatically. |
1013
1163
  | `list [--mine] [--phase p]` | Deployment listing; `--mine` (owner-signed, needs the key) adds the owner-only fields. Empty result is `[]` + exit 0. |
1014
- | `settings <agent> [k=v …]` | Show the agent's configuration document; with `key=value` assignments, change it. Keys: `provider`, `model`, `thinking` (`low\|high\|max`), `framework` (opaque JSON — quote it: `framework='{"a": 1}'`, in the REPL too). Assignments **merge** onto the stored document; an empty value (`thinking=`) clears a field. **Both** directions are owner-signed (needs the key). A write is a compare-and-swap against the version just read: a concurrent edit by another client is refused with `SETTINGS_CONFLICT` (exit 3), never overwritten. A merged document with no `model` is refused before signing — that is the one state the container hard-fails on. The chosen model is checked against its provider's configured catalog before signing — an absence is a warning on stderr. Native providers without a catalog accept a manual model ID. A provider change requires a registered matching key and image support, then reports pending reset; execute `reset` with that provider's key. |
1164
+ | `settings <agent> [k=v …]` | Show the agent's configuration document; with `key=value` assignments, change it. Keys: `provider`, `model`, `thinking` (`low\|high\|max`), `others` (opaque JSON — quote it: `others='{"a": 1}'`, in the REPL too), and on a 0g-harness agent `sealed` / `harness` (a version's sha256 from the trust registry's lists, which `settings <agent> versions` prints — a bare show says on one line which versions run; refused for an agent of another framework). Assignments **merge** onto the stored document; an empty value (`thinking=`) clears a field. **Both** directions are owner-signed (needs the key). A write is a compare-and-swap against the version just read: a concurrent edit by another client is refused with `SETTINGS_CONFLICT` (exit 3), never overwritten. A merged document with no `model` is refused before signing — that is the one state the container hard-fails on. The chosen model is checked against its provider's configured catalog before signing — an absence is a warning on stderr. Native providers without a catalog accept a manual model ID. A provider change requires a registered matching key and image support, then reports pending reset; execute `reset` with that provider's key. |
1015
1165
 
1016
1166
  Environment variables (override the config files):
1017
1167
 
package/OPERATORS.md ADDED
@@ -0,0 +1,164 @@
1
+ # Runtime operators
2
+
3
+ [中文](./OPERATORS.zh.md)
4
+
5
+ The NFT owner can appoint one agent-scoped operator to provide and pay for its
6
+ sandbox. The operator creates the sandbox with its own wallet, funds its own
7
+ provider balance, acknowledges the provider and signs runtime lifecycle calls.
8
+ The NFT, settings and credential set remain controlled by the owner. No sandbox
9
+ protocol change, NFT approval or global administrator role is required.
10
+
11
+ ## Owner setup and operator hosting
12
+
13
+ ```ts
14
+ import { AgentDNA } from '@0gfoundation/0g-agentdna';
15
+ import { parseEther } from 'viem';
16
+ import { privateKeyToAccount } from 'viem/accounts';
17
+
18
+ const owner = await AgentDNA.fromAttestor(attestorUrl, { account: ownerKey });
19
+ const operatorAccount = privateKeyToAccount(operatorKey);
20
+ const operator = await AgentDNA.fromAttestor(attestorUrl, { account: operatorAccount });
21
+
22
+ const ownerAck = await owner.ack();
23
+ if (ownerAck) await owner.waitForTransaction(ownerAck);
24
+ const { sealId } = await owner.agent.deploy(
25
+ { name: 'Sage', description: 'a hosted agent' }, { wait: 'minted' },
26
+ );
27
+
28
+ // The owner configures the model and credentials; the operator cannot edit them.
29
+ const { version } = await owner.agent.getSettings(sealId);
30
+ await owner.agent.setSettings(sealId, { provider: '0g-compute', model: modelName }, { baseVersion: version });
31
+ await owner.credentials.setModelKey(sealId, '0g-compute', inferenceKey, { push: false });
32
+ await owner.agent.setOperator(sealId, operatorAccount.address);
33
+
34
+ // The operator supplies compute, using its own acknowledgement and balance.
35
+ const operatorAck = await operator.ack();
36
+ if (operatorAck) await operator.waitForTransaction(operatorAck);
37
+ await operator.waitForTransaction(await operator.deposit({ amountWei: parseEther('0.5') }));
38
+ await operator.agent.start(sealId); // first provision; uses the owner's stored settings and credentials
39
+ await operator.agent.stop(sealId);
40
+ await operator.agent.start(sealId); // resumes the current sandbox
41
+ ```
42
+
43
+ Mint-only deploy does not require the owner's wallet to hold a prepaid sandbox
44
+ balance. One-shot `deploy({ ..., sandbox })` retains its owner-funded behavior;
45
+ operator hosting starts from an owner-minted identity.
46
+
47
+ `start(sealId)` resolves the current sandbox ID. An existing mapping means resume,
48
+ even when the runtime is not ready or reports offline; `NOT_RESUMABLE` is surfaced
49
+ to the caller, without an implicit reset or another paid create. Only an empty
50
+ mapping selects first provision. `start(sealId, sandboxId)` still selects an
51
+ explicit sandbox, and `stop(sealId)` can also resolve its ID automatically.
52
+
53
+ Operator start/reset accepts compute options such as `sealedImage` or `framework`,
54
+ subject to the attestor's existing checks. It refuses `apiKey`, `sealedModelKey`,
55
+ `sealedSecretEnv`, `provider` and `keepStoredModelKey`: configure the model through
56
+ the owner's settings and credential APIs first. Operator calls do not seed default
57
+ settings or read/write the owner's credential set. Owner calls retain the normal
58
+ model-key storage and settings-seeding behavior.
59
+
60
+ ## Grant scope and updates
61
+
62
+ `getOperator(sealId)` returns public routing metadata: `owner`, `operator`,
63
+ `version`, `expiresAt`, `allowRecreate` and normally `checkpoint: null`. This
64
+ ordinary read does not request a fresh block anchor or historical owner; it is
65
+ not proof that a runtime request will be authorized. The API and worker verify
66
+ authority independently. Before mint, it reports the deployment owner with no
67
+ operator; existing owner stop/reset/retry requests remain available, but operator
68
+ grant writes require a minted agent.
69
+
70
+ ```ts
71
+ const grant = await owner.agent.getOperator(sealId);
72
+ await owner.agent.setOperator(sealId, operatorAccount.address, {
73
+ baseVersion: grant.version, // optional; omitted means read before signing
74
+ expiresAt: Math.floor(Date.now() / 1000) + 86400, // omitted/0: until replaced or revoked
75
+ allowRecreate: true, // default false
76
+ });
77
+ await operator.agent.start(sealId); // grant updates retire the previous runtime
78
+ await operator.agent.reset(sealId); // replacing an existing runtime requires allowRecreate
79
+ await owner.agent.revokeOperator(sealId);
80
+ ```
81
+
82
+ Every successful grant write, including renewal, replacement and revocation,
83
+ retires the current runtime, clears its sandbox mapping and schedules old-sandbox
84
+ cleanup through a persisted outbox. A new operator cannot assume control of the
85
+ previous operator's sandbox or balance. Provision again after an update.
86
+
87
+ Writes compare the signed base version. A competing write raises
88
+ `OperatorConflictError`. A superseded ownership checkpoint instead raises
89
+ `OperatorCheckpointSupersededError`, with `code: 'operator_checkpoint_superseded'`
90
+ and an optional `minimumBlock`. Refresh the checkpoint and explicitly approve a
91
+ new `setOperator()` signature; the SDK never automatically retries or re-signs.
92
+ Operator lifecycle
93
+ signatures also bind the agent, chain, contract and grant version. Old queued
94
+ requests do not become valid again when the same wallet is reappointed.
95
+ Authorization is checked again before execution; an operation already sent to the
96
+ provider may still complete.
97
+
98
+ Only `setOperator` requests `GET /operator?seal_id=...&checkpoint=true` for the current
99
+ version and a fresh end-of-block checkpoint. The owner signs that exact block
100
+ number and hash. The SDK rejects unsafe JavaScript block numbers, malformed hashes
101
+ and missing checkpoints rather than inventing one. A successful write then
102
+ re-reads ordinary metadata: one anchor GET, one PUT and one metadata GET, with no
103
+ automatic retry or re-signing if the anchor is unavailable.
104
+
105
+ `revokeOperator` reads ordinary metadata for the owner and base version, signs
106
+ `checkpoint: null`, then re-reads ordinary metadata after PUT. Revocation does not
107
+ request a new anchor or depend on Transfer-log availability; it still requires
108
+ the current owner's fresh, scoped signature and the matching base version.
109
+ A hand-written revocation with a non-null checkpoint is rejected with HTTP 400.
110
+
111
+ For appointment, the attestor verifies the owner at a fresh snapshot `T` and that
112
+ no Transfer occurred after the signed anchor `H` through `T`. It reads canonical
113
+ headers and Transfer logs, not historical state at `H`, so state pruning does not
114
+ shorten the five-minute `issued_at` signing window. Validation spans at most
115
+ 10,000 blocks; an older checkpoint or an intervening Transfer requires an
116
+ explicit refresh and new signature. Neither grant writes nor later execution
117
+ require an archive RPC. The attestor records acceptance bound to the signed
118
+ proof, signature and grant version. Later execution uses that admission fact,
119
+ one canonical-header lookup, live ownership and the current grant; acceptance is
120
+ not an additional cryptographic proof.
121
+
122
+ New anchors use the latest block, not a delayed confirmed block. Missing headers
123
+ or an RPC lag return HTTP 503; a hash mismatch rejects the grant. A delayed indexer
124
+ event in block `H` or earlier does not erase a grant anchored to the end of `H`.
125
+ An indexed ownership transfer after `H` invalidates it. Revoking a transfer away
126
+ and back to the same wallet depends on the indexer catching up; live owner checks
127
+ alone cannot detect that round trip.
128
+
129
+ Each lifecycle call resolves its operator authority and deployment at most once
130
+ and reuses that request's data for sandbox routing and owner-only model planning.
131
+ The next call reads them again. This is not a grant cache, and API/worker
132
+ authorization checks still run independently.
133
+
134
+ Default delegation allows first provision and normal start/stop. Replacing an
135
+ existing runtime requires `allowRecreate`. NFT transfer, owner settings,
136
+ credentials, clone, retry and operator management remain owner-only. NFT transfer
137
+ invalidates the previous owner's delegation and boot authorization.
138
+
139
+ ## Container proof and scope
140
+
141
+ The operator signs runtime requests and pays for the sandbox. Boot authorization
142
+ continues to name the real NFT owner. `/provision` retains the provider v3
143
+ certificate, pinned container identity and boot-proof checks; an operator wallet
144
+ signature cannot replace them. The agent key is encrypted to the verified
145
+ container, and owner credentials are delivered through the existing provision
146
+ channel.
147
+
148
+ When an accepted create finishes, the worker rechecks its owner, grant and boot
149
+ generation. Expiry of the original request envelope alone does not discard it.
150
+ If a dependency is temporarily unavailable, the worker retries within a bound
151
+ and retains the created sandbox durably for later revalidation. Cleanup follows
152
+ an explicit rejection of authority or boot generation, not a dependency outage.
153
+ The grant's own `expiresAt` remains a permission boundary: if it expires during
154
+ create, the result cannot be bound to the agent. The worker never extends it to
155
+ finish an operation.
156
+
157
+ This feature adds authorization, not an idle scheduler or an always-on wake
158
+ gateway. Stop keeps its existing semantics: it does not add a final state flush
159
+ or guarantee that no task is running. An application must make those decisions
160
+ before requesting a stop.
161
+
162
+ If the database cannot save an accepted create result after bounded retries, the
163
+ worker preserves the sandbox and reports its ID for attestor admin intervention.
164
+ Automatic recovery requires that persisted result.