@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/dist/AgenticID.js CHANGED
@@ -2,16 +2,47 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.AgenticID = exports.AdminApi = exports.ReputationApi = exports.AgentApi = exports.MIN_SANDBOX_BALANCE_WEI = void 0;
4
4
  const Providers_1 = require("./Providers");
5
+ /**
6
+ * @file AgenticID.ts
7
+ * @description The single entry point. Construct once with rpc + addresses (+
8
+ * attestorUrl + signer), then use the agent/reputation namespaces and admin operations:
9
+ * - `agent` — lifecycle (deploy / clone / transfer), reads, agent-seal gas top-up
10
+ * - `reputation` — serve-proof capture/verify + on-chain feedback
11
+ * - `admin` — attestor-wide provider publication, authorized by its Tapp owner
12
+ *
13
+ * plus top-level ops that don't belong to a single agent: `ack` / `ackStatus`
14
+ * (acknowledge the TEE trust-root component set) and `deposit` / `getBalance`
15
+ * (prepaid sandbox balance).
16
+ *
17
+ * Backends (AgenticID / Reputation / TappRegistry / SandboxServing contracts +
18
+ * attestor HTTP) are hidden behind the facade.
19
+ *
20
+ * @example
21
+ * ```typescript
22
+ * import { AgentDNA } from '@0gfoundation/0g-agentdna';
23
+ * const ag = new AgentDNA({ addresses, account }); // addresses from DEPLOYMENT.md §6 / your config
24
+ * await ag.agent.transferFrom(from, to, 33n);
25
+ * const { proof } = await ag.reputation.capture(() => fetch(`${url}/chat`, ...));
26
+ * await ag.ack();
27
+ * ```
28
+ */
29
+ const AgentClient_1 = require("./AgentClient");
5
30
  const viem_1 = require("viem");
6
31
  const constants_1 = require("./constants");
7
32
  const AgenticIDClient_1 = require("./AgenticIDClient");
8
33
  const ReputationClient_1 = require("./ReputationClient");
9
34
  const SandboxClient_1 = require("./SandboxClient");
10
35
  const AttestorClient_1 = require("./AttestorClient");
36
+ const Credentials_1 = require("./Credentials");
37
+ const modelKey_1 = require("./legacy/modelKey");
11
38
  const Settings_1 = require("./Settings");
39
+ const secretEnv_1 = require("./secretEnv");
40
+ const Operators_1 = require("./Operators");
12
41
  const ServeSession_1 = require("./ServeSession");
42
+ const TrustRegistry_1 = require("./TrustRegistry");
43
+ const Releases_1 = require("./Releases");
13
44
  const context_1 = require("./context");
14
- const AgentClient_1 = require("./AgentClient");
45
+ const AgentClient_2 = require("./AgentClient");
15
46
  const ZERO = '0x0000000000000000000000000000000000000000';
16
47
  /**
17
48
  * The agentId for a URL-form handle (`client` / `authenticate`): the one
@@ -49,11 +80,89 @@ function containerStatusOf(raw) {
49
80
  };
50
81
  }
51
82
  class AgentApi {
52
- constructor(ctx, initialConfig) {
83
+ constructor(ctx, initialConfig, credentials) {
53
84
  this.ctx = ctx;
54
85
  this.id = new AgenticIDClient_1.AgenticIDClient(ctx);
55
86
  this.attestor = new AttestorClient_1.AttestorClient(ctx, initialConfig);
56
87
  this.infra = new SandboxClient_1.SandboxClient(ctx);
88
+ this.credentials = credentials ?? new Credentials_1.CredentialsApi(ctx, this.attestor);
89
+ }
90
+ /**
91
+ * A model key given to start/reset/retry goes into the agent's credential
92
+ * set as `model.<provider>`, stored once every check of the request has
93
+ * passed and before it is sent (`beforeWrite`), so the new container boots
94
+ * with it. (It also rides the request for older images: legacy/modelKey.ts.)
95
+ *
96
+ * The provider is the request's (0g-compute when none is given), or the
97
+ * sealed key's. `keyInCredentials`: the set holds a key for the provider,
98
+ * or is about to, so a create without one in the request is not refused;
99
+ * the key a running container got with its own create does not count, as
100
+ * the new container will not have it.
101
+ */
102
+ async modelKeyPlan(sealId, opts, ownerResolved = false) {
103
+ if (!ownerResolved && await this.attestor.isRuntimeOperator(sealId)) {
104
+ (0, Operators_1.assertOperatorComputeOptions)(opts);
105
+ // Owner-provisioned credentials reach the runtime through /provision.
106
+ // The operator neither reads nor writes the owner's credential set.
107
+ return { keyInCredentials: true };
108
+ }
109
+ const sealed = opts.sealedModelKey;
110
+ if (sealed && opts.apiKey)
111
+ throw new secretEnv_1.SecretEnvRefusedError('conflicting_inputs', 'pass apiKey or sealedModelKey, not both');
112
+ if (sealed && opts.provider && opts.provider !== sealed.provider) {
113
+ throw new secretEnv_1.SecretEnvRefusedError('conflicting_inputs', `the sealed model key is for ${sealed.provider}, not ${opts.provider}`);
114
+ }
115
+ const provider = sealed?.provider ?? opts.provider ?? '0g-compute';
116
+ const key = sealed ?? opts.apiKey;
117
+ if (key) {
118
+ if ((0, modelKey_1.requestOnly)(opts)) {
119
+ // LEGACY(model-key): the key goes with the request only, so it needs
120
+ // a request copy.
121
+ if (sealed && !sealed.secretEnv) {
122
+ throw new secretEnv_1.SecretEnvRefusedError('conflicting_inputs', 'keepStoredModelKey sends the key with the request only, and this sealed model key has no request copy (secretEnv)');
123
+ }
124
+ return { keyInCredentials: false };
125
+ }
126
+ // A sealed key with no request copy reaches the container only through
127
+ // the set: storing it must not fail quietly.
128
+ const required = !!sealed && !sealed.secretEnv;
129
+ return { keyInCredentials: required, beforeWrite: async () => { await this.storeModelKey(sealId, provider, key, { onWarn: opts.onWarn, required }); } };
130
+ }
131
+ if (provider === '0g-compute')
132
+ return { keyInCredentials: false };
133
+ const cur = await this.credentials.get(sealId).catch(() => undefined);
134
+ return { keyInCredentials: !!cur?.definitions.some((d) => d.inference?.provider === provider) };
135
+ }
136
+ /**
137
+ * Store a model key in the set; whether it went in. A refusal is reported,
138
+ * not thrown, when the key still goes with the request; `required`: thrown.
139
+ * `newAgent`: see {@link CredentialsApi.setModelKey}. `sealedTo` hears the
140
+ * agentSeal address a key given in clear was sealed to.
141
+ */
142
+ async storeModelKey(sealId, provider, key, opts = {}) {
143
+ try {
144
+ const stored = await this.credentials.setModelKey(sealId, provider, key, { push: false, newAgent: opts.newAgent });
145
+ if (stored.sealedTo)
146
+ opts.sealedTo?.(stored.sealedTo);
147
+ return true;
148
+ }
149
+ catch (e) {
150
+ if (opts.required)
151
+ throw e;
152
+ opts.onWarn?.(`the model key was not stored in the agent's credential set (${e instanceof Error ? e.message : String(e)}); this boot gets it with the request only`);
153
+ return false;
154
+ }
155
+ }
156
+ /** After a deploy's mint: the key stored before it was sealed to the agentSeal key now on chain. */
157
+ async checkSealedTo(agentId, sealedTo) {
158
+ if (!sealedTo)
159
+ return;
160
+ const onChain = await this.id.getAgentSeal(agentId);
161
+ if (onChain.toLowerCase() !== sealedTo.toLowerCase()) {
162
+ throw new Error(`deploy: the model key was sealed to ${sealedTo}, but agent ${agentId}'s agentSeal on chain is ${onChain}: ` +
163
+ 'the attestor named another key than the one it minted with (a relaying proxy?). The agent cannot use the stored key; ' +
164
+ 'set it again with credentials.setModelKey and replace the key at its provider');
165
+ }
57
166
  }
58
167
  /**
59
168
  * Deploy/clone preflight: fail HERE, synchronously and with the fix
@@ -63,7 +172,7 @@ class AgentApi {
63
172
  * read errors fail open — the attestor re-checks at accept anyway.
64
173
  * Opt out per call with `{ preflight: false }`.
65
174
  */
66
- async preflightOwnerReady() {
175
+ async preflightOwnerReady(checkSandboxBalance = true) {
67
176
  const who = this.ctx.account?.address;
68
177
  if (!who)
69
178
  return; // browser-wallet flows preflight in their own UI
@@ -80,7 +189,7 @@ class AgentApi {
80
189
  // chain read failed — fail open, attestor re-checks at accept
81
190
  }
82
191
  }
83
- if (this.ctx.addresses.sandboxServing !== ZERO) {
192
+ if (checkSandboxBalance && this.ctx.addresses.sandboxServing !== ZERO) {
84
193
  try {
85
194
  // Prefer the provider's EFFECTIVE balance (on-chain minus reservations
86
195
  // minus outstanding off-chain debt) — the number its create/start
@@ -166,16 +275,45 @@ class AgentApi {
166
275
  throw new Error("deploy: wait:'running' needs a sandbox to provision — a mint-only deploy (no sandbox) has no container to wait on; use wait:'minted'");
167
276
  }
168
277
  if (opts?.preflight !== false)
169
- await this.preflightOwnerReady();
170
- const accepted = acceptedOf(await this.attestor.deploy(params));
278
+ await this.preflightOwnerReady(!!params.sandbox);
279
+ // The key goes into the credential set as the agent is created: the
280
+ // attestor takes the deploying owner's set before the mint, and holds
281
+ // the container until it is stored (`awaitCredentials`), so the first
282
+ // boot gets it. It is checked first, so a key the store would refuse
283
+ // fails before the deploy is signed. (It also rides the create request
284
+ // for older images: legacy/modelKey.ts.)
285
+ const key = params.sandbox?.apiKey;
286
+ const provider = (0, AttestorClient_1.deployProvider)(params);
287
+ if (key)
288
+ (0, Credentials_1.checkModelKeyInput)(provider, key);
289
+ const created = acceptedOf(await this.attestor.deploy(key ? { ...params, awaitCredentials: true } : params));
290
+ let sealedTo;
291
+ const store = (sealId) => this.storeModelKey(sealId, provider, key, { newAgent: true, sealedTo: (address) => { sealedTo = address; } });
292
+ const accepted = key ? { ...created, modelKeyStored: await store(created.sealId) } : created;
171
293
  if (!opts?.wait)
172
294
  return accepted;
173
295
  // 'minted' → block on the on-chain mint only (agentId, no url yet).
174
- // 'running' → also block on provision (container up + reachable url).
175
- if (opts.wait === 'running')
176
- return { ...accepted, ...(await this.waitForRunning(accepted.sealId, opts)) };
177
- const agentId = await this.waitForMint(accepted.sealId, opts);
178
- return { ...accepted, agentId };
296
+ // 'running' → block on provision (container up + reachable url), and on
297
+ // the mint before it only when the key goes in after the mint.
298
+ // One timeout covers both waits.
299
+ const deadline = Date.now() + (opts.timeoutMs ?? (opts.wait === 'running' ? 300000 : 180000));
300
+ const left = () => ({ ...opts, timeoutMs: Math.max(0, deadline - Date.now()) });
301
+ let agentId;
302
+ if (opts.wait === 'minted' || (key && !accepted.modelKeyStored)) {
303
+ agentId = await this.waitForMint(accepted.sealId, left());
304
+ if (key)
305
+ await (0, modelKey_1.storeAfterMint)(accepted, () => store(accepted.sealId));
306
+ }
307
+ if (opts.wait === 'running') {
308
+ const running = await this.waitForRunning(accepted.sealId, left());
309
+ await this.checkSealedTo(running.agentId, sealedTo);
310
+ if (key)
311
+ await this.credentials.resyncModelKey(accepted.sealId, { agentUrl: running.url }).catch(() => undefined);
312
+ return { ...accepted, ...running };
313
+ }
314
+ const minted = agentId;
315
+ await this.checkSealedTo(minted, sealedTo);
316
+ return { ...accepted, agentId: minted };
179
317
  }
180
318
  async clone(params, opts) {
181
319
  if (opts?.preflight !== false)
@@ -338,7 +476,7 @@ class AgentApi {
338
476
  const owner = agentId !== undefined && this.hasAccount();
339
477
  const reauth = owner ? () => this.mintToken(base, agentId) : undefined;
340
478
  const logAuth = owner ? () => this.signOwner('0GSealLog', base, agentId) : undefined;
341
- return (0, AgentClient_1.makeAgentClient)({ base, services: disc.services, routes: disc.routes, reauth, logAuth, clientAddress: this.ctx.account?.address, instanceId: opts?.instanceId });
479
+ return (0, AgentClient_2.makeAgentClient)({ base, services: disc.services, routes: disc.routes, reauth, logAuth, clientAddress: this.ctx.account?.address, instanceId: opts?.instanceId });
342
480
  }
343
481
  /**
344
482
  * Owner handshake, eager: like {@link client} on an `ag` with a key, but
@@ -364,7 +502,7 @@ class AgentApi {
364
502
  if (fromUrl)
365
503
  await this.assertAgentIdBoundToUrl(agentId, base);
366
504
  const token = await this.mintToken(base, agentId); // eager → throws if not owner
367
- return (0, AgentClient_1.makeAgentClient)({
505
+ return (0, AgentClient_2.makeAgentClient)({
368
506
  base, services: disc.services, routes: disc.routes, token,
369
507
  reauth: () => this.mintToken(base, agentId),
370
508
  logAuth: () => this.signOwner('0GSealLog', base, agentId),
@@ -381,7 +519,7 @@ class AgentApi {
381
519
  const disc = await this.discoverSurface(base);
382
520
  // Public handle (no token), but still declare the caller as redeemer so a
383
521
  // captured serve-proof is bound to and redeemable by them.
384
- return (0, AgentClient_1.makeAgentClient)({ base, services: disc.services, routes: disc.routes, clientAddress: this.ctx.account?.address });
522
+ return (0, AgentClient_2.makeAgentClient)({ base, services: disc.services, routes: disc.routes, clientAddress: this.ctx.account?.address });
385
523
  }
386
524
  /**
387
525
  * Sign an owner control message `<tag>:<sealId>:<ts>:<audience>` (EIP-191).
@@ -446,7 +584,7 @@ class AgentApi {
446
584
  body,
447
585
  });
448
586
  if (!r.ok)
449
- throw new Error(`pushSettingsToContainer: HTTP ${r.status}: ${await r.text()}`);
587
+ throw new Error(`pushSettingsToContainer: HTTP ${r.status}: ${(0, AgentClient_1.plainText)(await r.text())}`);
450
588
  return (await r.json().catch(() => ({})));
451
589
  }
452
590
  /**
@@ -472,7 +610,7 @@ class AgentApi {
472
610
  body,
473
611
  });
474
612
  if (!r.ok)
475
- throw new Error(`claimAgent: HTTP ${r.status}: ${await r.text()}`);
613
+ throw new Error(`claimAgent: HTTP ${r.status}: ${(0, AgentClient_1.plainText)(await r.text())}`);
476
614
  return (await r.json().catch(() => ({})));
477
615
  }
478
616
  /**
@@ -504,7 +642,7 @@ class AgentApi {
504
642
  body,
505
643
  });
506
644
  if (!r.ok)
507
- throw new Error(`clearConversation: HTTP ${r.status}: ${await r.text()}`);
645
+ throw new Error(`clearConversation: HTTP ${r.status}: ${(0, AgentClient_1.plainText)(await r.text())}`);
508
646
  return (await r.json().catch(() => ({})));
509
647
  }
510
648
  /**
@@ -546,9 +684,86 @@ class AgentApi {
546
684
  body,
547
685
  });
548
686
  if (!r.ok)
549
- throw new Error(`compactConversation: HTTP ${r.status}: ${await r.text()}`);
687
+ throw new Error(`compactConversation: HTTP ${r.status}: ${(0, AgentClient_1.plainText)(await r.text())}`);
688
+ return (await r.json().catch(() => ({})));
689
+ }
690
+ /**
691
+ * Restart one layer of a 0g-harness agent's runtime, in place: `harness`
692
+ * restarts the harness process (the conversation and the disk stay);
693
+ * `sealed` ends sealed, and the loader starts it again — the agent is away
694
+ * for about one start, the disk stays. Either applies the owner's version
695
+ * picks and the trust registry's lists as a start does (sealed/LAYERS.md
696
+ * §3). Owner-signed (tag `0GSealRestart`, the clear grammar, the body
697
+ * `{"layer": …}` bound by its digest). Answers 202 once the restart is
698
+ * under way. 501: the framework has no owner restart, or a `sealed`
699
+ * restart on an image without the loader; 503: sealed is still starting;
700
+ * 409: a replayed signature, or a displaced window when `instanceId` is
701
+ * passed (a restart is a driving action).
702
+ */
703
+ async restartRuntime(base, agentId, layer, instanceId) {
704
+ const { walletClient, account } = (0, context_1.requireWallet)(this.ctx);
705
+ const sealId = await this.id.getSealId(agentId);
706
+ const body = JSON.stringify({ layer });
707
+ const digest = await (0, Settings_1.sha256Hex)(body);
708
+ const audience = new URL(base).origin;
709
+ const message = `0GSealRestart:${sealId}:${Math.floor(Date.now() / 1000)}:${digest}:${audience}`;
710
+ const signature = await walletClient.signMessage({ account, message });
711
+ const r = await fetch(`${base}/_seal/restart`, {
712
+ method: 'POST',
713
+ headers: {
714
+ 'X-Auth-Message': message,
715
+ 'X-Auth-Signature': signature,
716
+ 'content-type': 'application/json',
717
+ ...(instanceId ? { 'X-Client-Instance': instanceId } : {}),
718
+ },
719
+ body,
720
+ });
721
+ if (!r.ok)
722
+ throw new Error(`restartRuntime: HTTP ${r.status}: ${(0, AgentClient_1.plainText)(await r.text())}`);
550
723
  return (await r.json().catch(() => ({})));
551
724
  }
725
+ /**
726
+ * The versions of the layered runtime (0g-harness) the trust registry
727
+ * lists, each list in listing order. An agent runs its owner's pick while
728
+ * it is listed — picked through the settings document's `versions` —
729
+ * otherwise keeps its running version while that stays listed, and
730
+ * otherwise moves to the last entry, the newest (sealed/LAYERS.md §10).
731
+ * LEGACY(pre-1.4.0): null when the chain has no trust registry (AgenticID
732
+ * before 1.4.0).
733
+ */
734
+ async listedVersions() {
735
+ const registry = await (0, TrustRegistry_1.trustRegistryOf)(this.ctx.publicClient, this.ctx.addresses.agenticID);
736
+ // LEGACY(pre-1.4.0)
737
+ if (!registry)
738
+ return null;
739
+ const [sealed, harness] = await Promise.all([
740
+ (0, TrustRegistry_1.listedHashes)(this.ctx.publicClient, registry, 'sealed'),
741
+ (0, TrustRegistry_1.listedHashes)(this.ctx.publicClient, registry, 'harness'),
742
+ ]);
743
+ return { registry, sealed, harness };
744
+ }
745
+ /**
746
+ * What the agent's sign socket signed, and what its rules refused, oldest
747
+ * first: one record per signature or refusal, with what identifies it (a
748
+ * message's hash and start, a typed-data digest and domain, a transaction's
749
+ * hash, chain, target, value, nonce and selector). The runtime keeps the
750
+ * last 1000 and keeps them across its restarts; it records every request,
751
+ * whichever way the agent reached the socket. Only a 0g-harness agent's
752
+ * runtime keeps the record; the other frameworks answer 404. `after` is a
753
+ * record number (`seq`): only newer records come back. Owner-signed (tag
754
+ * `0GSealSignatures`, the read-only grammar).
755
+ */
756
+ async signatures(base, agentId, opts) {
757
+ const { message, signature } = await this.signOwner('0GSealSignatures', base, agentId);
758
+ const query = opts?.after !== undefined ? `?after=${opts.after}` : '';
759
+ const r = await fetch(`${base}/_seal/signatures${query}`, {
760
+ headers: { 'X-Auth-Message': message, 'X-Auth-Signature': signature },
761
+ signal: AbortSignal.timeout(20000),
762
+ });
763
+ if (!r.ok)
764
+ throw new Error(`signatures: HTTP ${r.status}: ${(0, AgentClient_1.plainText)(await r.text())}`);
765
+ return (await r.json());
766
+ }
552
767
  /** Sign `0GSealAuth` (audience-bound) and exchange it at `{base}/_seal/auth` for a token. */
553
768
  async mintToken(base, agentId) {
554
769
  const { message, signature } = await this.signOwner('0GSealAuth', base, agentId);
@@ -557,7 +772,7 @@ class AgentApi {
557
772
  headers: { 'X-Auth-Message': message, 'X-Auth-Signature': signature },
558
773
  });
559
774
  if (!r.ok)
560
- throw new Error(`authenticate: HTTP ${r.status}: ${await r.text()}`);
775
+ throw new Error(`authenticate: HTTP ${r.status}: ${(0, AgentClient_1.plainText)(await r.text())}`);
561
776
  return (await r.json()).token;
562
777
  }
563
778
  /**
@@ -713,6 +928,16 @@ class AgentApi {
713
928
  const rows = (await (await fetch(`${this.attestorBase()}/deployments?slim=1`)).json());
714
929
  return rows.map((r) => this.normalizeDeploymentRow(r));
715
930
  }
931
+ /**
932
+ * The attestor's published release notices, newest first: what each
933
+ * release changed, and the images it replaces with the end of their
934
+ * transition period. Which of your agents run one of those images is on
935
+ * {@link AgentApi.listMyDeployments} (`migrate`). Empty from an attestor
936
+ * without release notices.
937
+ */
938
+ async releases() {
939
+ return (0, Releases_1.fetchReleases)(this.attestorBase());
940
+ }
716
941
  /**
717
942
  * Owner-scoped, authenticated listing — your own agents WITH the fields the
718
943
  * public {@link AgentApi.listDeployments} withholds (`sandboxId`,
@@ -787,35 +1012,53 @@ class AgentApi {
787
1012
  createdAt: r.created_at ?? null,
788
1013
  lastProvisionError: failureReason,
789
1014
  containerStatus: containerStatusOf(r.container_status),
1015
+ // Owner tier only: the release that asks this agent to move to a
1016
+ // newer image, and by when (GET /releases has the notes).
1017
+ migrate: (0, Releases_1.agentMigrationOf)(r.migrate),
790
1018
  // No `settings`: the owner's configuration document is owner-gated on
791
1019
  // READ as well as write and is served only by {@link getSettings}. No
792
1020
  // listing tier carries it, so advertising it here would have meant a
793
1021
  // field that is null even for a configured agent.
794
1022
  };
795
1023
  }
796
- /** Stop a running agent's sandbox (owner-signed). Identity is preserved. */
797
- stop(sealId, sandboxId) {
798
- return this.attestor.lifecycle('stop', { sealId, sandboxId });
1024
+ /** Public runtime delegation. NFT ownership and private settings are not delegated. */
1025
+ getOperator(sealId) {
1026
+ return this.attestor.getOperator(sealId);
1027
+ }
1028
+ /** Owner-only. Updating a grant retires the current runtime; its controller must provision again. */
1029
+ setOperator(sealId, operator, opts = {}) {
1030
+ return this.attestor.setOperator(sealId, operator, opts);
1031
+ }
1032
+ /** Owner-only. Revokes the operator and retires the current runtime. */
1033
+ revokeOperator(sealId, opts = {}) {
1034
+ return this.attestor.revokeOperator(sealId, opts);
799
1035
  }
800
- start(sealId, arg) {
1036
+ /** Stop a running sandbox with its controller wallet (the owner or appointed, paying operator). */
1037
+ async stop(sealId, sandboxId) {
1038
+ await this.attestor.lifecycle('stop', { sealId, sandboxId, resolveSandbox: !sandboxId });
1039
+ }
1040
+ async start(sealId, arg) {
801
1041
  if (typeof arg === 'string')
802
1042
  return this.attestor.lifecycle('start', { sealId, sandboxId: arg });
803
1043
  // `framework` resolves the right sealed image for a first provision (a
804
1044
  // mint-only hermes/prime agent otherwise boots the default snapshot) —
805
1045
  // same resolution deploy/reset use. (review #154 opportunity)
806
- return this.attestor.lifecycle('start', { sealId, provider: arg?.provider, framework: arg?.framework, sealedImage: arg?.sealedImage, apiKey: arg?.apiKey, sealedSecretEnv: arg?.sealedSecretEnv, secretEnv: arg?.secretEnv });
1046
+ return this.attestor.lifecycle('start', { sealId, resolveSandbox: true,
1047
+ provider: arg?.provider ?? arg?.sealedModelKey?.provider, framework: arg?.framework, sealedImage: arg?.sealedImage,
1048
+ ...(0, modelKey_1.requestKey)(arg ?? {}), operatorOptions: arg ?? {},
1049
+ prepareModelKey: () => this.modelKeyPlan(sealId, arg ?? {}, true) });
807
1050
  }
808
1051
  /**
809
1052
  * Reset (recreate) an agent's container, preserving its on-chain
810
1053
  * identity — a fresh boot that re-reads iData from chain and reselects
811
- * the framework adapter from the binding. Owner-signed. `apiKey` is
812
- * required in practice: without it the agent boots but cannot call
813
- * its model. When the attestor advertises `secret_env_scheme`, the
814
- * SDK seals the key to the agent's agentSeal key (only the TEE opens
815
- * it) and the owner signs that ciphertext; otherwise it rides the
816
- * signed envelope in clear (`secretEnv`, default `'auto'`; `'sealed'`
817
- * refuses the clear path). The attestor keeps no reusable copy, which
818
- * is WHY it must be passed again on every recreate.
1054
+ * the framework adapter from the binding. An operator needs the owner's
1055
+ * `allowRecreate` permission and cannot supply model or credential changes. The new
1056
+ * container takes its model key from the agent's credential set at boot:
1057
+ * a key held there needs no `apiKey`. A given `apiKey` (or
1058
+ * `sealedModelKey`) is stored there first, as for {@link start}.
1059
+ * LEGACY(model-key): for older images it also rides the request, sealed
1060
+ * to the agent's agentSeal key when the attestor advertises
1061
+ * `secret_env_scheme`, else in clear (`secretEnv`).
819
1062
  *
820
1063
  * An agent with no settings document boots on the model pinned in its
821
1064
  * minted persona, which leaves the chain at its first commit. So when the
@@ -827,8 +1070,11 @@ class AgentApi {
827
1070
  * reset onto another `provider` until its settings name one: write them
828
1071
  * with {@link setSettings} first.
829
1072
  */
830
- reset(sealId, opts) {
831
- return this.attestor.lifecycle('reset', { sealId, provider: opts?.provider, framework: opts?.framework, sealedImage: opts?.sealedImage, apiKey: opts?.apiKey, sealedSecretEnv: opts?.sealedSecretEnv, secretEnv: opts?.secretEnv });
1073
+ async reset(sealId, opts) {
1074
+ return this.attestor.lifecycle('reset', { sealId, provider: opts?.provider ?? opts?.sealedModelKey?.provider,
1075
+ framework: opts?.framework, sealedImage: opts?.sealedImage, ...(0, modelKey_1.requestKey)(opts ?? {}),
1076
+ operatorOptions: opts ?? {},
1077
+ prepareModelKey: () => this.modelKeyPlan(sealId, opts ?? {}, true) });
832
1078
  }
833
1079
  /**
834
1080
  * The agent's current settings document — which model it thinks with, and
@@ -879,6 +1125,10 @@ class AgentApi {
879
1125
  * missing from the 0G router catalog is reported, never blocked).
880
1126
  */
881
1127
  async setSettings(sealId, settings, opts) {
1128
+ // A provider switch takes the new provider's key with it: stored (and
1129
+ // pushed to the running agent) first, so the agent can switch to it.
1130
+ if (opts.modelKey)
1131
+ await this.credentials.setModelKey(sealId, settings.provider ?? '0g-compute', opts.modelKey);
882
1132
  return this.attestor.setSettings({
883
1133
  sealId,
884
1134
  settings,
@@ -887,6 +1137,10 @@ class AgentApi {
887
1137
  });
888
1138
  }
889
1139
  /**
1140
+ * LEGACY(model-key): use `credentials.sealModelKey`, whose key goes into
1141
+ * the agent's credential set and reaches every boot; this one reaches only
1142
+ * the request it is sent with.
1143
+ *
890
1144
  * Seal an inference key to one agent WITHOUT signing anything — for the
891
1145
  * integrator whose server supplies the key while the agent's owner signs
892
1146
  * in a browser. The server calls this (a read-only client is enough: no
@@ -909,13 +1163,14 @@ class AgentApi {
909
1163
  * (storage upload, mint re-fetch, setAgentURI, …) against the same sealId,
910
1164
  * where redeploying would orphan an already-minted agent.
911
1165
  *
912
- * Without opts it does idempotent stages only. Pass `apiKey` (and
913
- * optionally `sealedImage`) to let it continue past those into container
914
- * creation — like {@link reset}, the LLM key must be re-supplied (and is
915
- * sealed the same way, see `secretEnv`).
1166
+ * The owner signs a create envelope, so when the container failed or was
1167
+ * stopped it continues past those stages into container creation,
1168
+ * optionally on `sealedImage`. A model key given (`apiKey` or
1169
+ * `sealedModelKey`) is stored in the credential set as with {@link reset}.
916
1170
  */
917
- retry(sealId, opts) {
918
- return this.attestor.retry({ sealId, provider: opts?.provider, framework: opts?.framework, sealedImage: opts?.sealedImage, apiKey: opts?.apiKey, sealedSecretEnv: opts?.sealedSecretEnv, secretEnv: opts?.secretEnv });
1171
+ async retry(sealId, opts) {
1172
+ const key = await this.modelKeyPlan(sealId, opts ?? {});
1173
+ return this.attestor.retry({ sealId, provider: opts?.provider ?? opts?.sealedModelKey?.provider, framework: opts?.framework, sealedImage: opts?.sealedImage, ...(0, modelKey_1.requestKey)(opts ?? {}), ...key });
919
1174
  }
920
1175
  /**
921
1176
  * Wait for a deploy OR clone to mint on-chain, returning the new agent's
@@ -1080,6 +1335,8 @@ class ReputationApi {
1080
1335
  getVerifiedEndpoint(agentId, client, feedbackIndex) { return this.rep.getVerifiedEndpoint(agentId, client, feedbackIndex); }
1081
1336
  getVerifiedSummaryForEndpoint(agentId, uri, clients) { return this.rep.getVerifiedSummaryForEndpoint(agentId, uri, clients); }
1082
1337
  getServeData(agentId, client, feedbackIndex) { return this.rep.getServeData(agentId, client, feedbackIndex); }
1338
+ /** The sealed program and official harness version a verified entry's v2 proof named; zero for a v1 entry (registry 1.3.0+). */
1339
+ getServeLayers(agentId, client, feedbackIndex) { return this.rep.getServeLayers(agentId, client, feedbackIndex); }
1083
1340
  waitForTransaction(txHash) { return this.rep.waitForTransaction(txHash); }
1084
1341
  }
1085
1342
  exports.ReputationApi = ReputationApi;
@@ -1099,10 +1356,11 @@ class AgenticID {
1099
1356
  constructor(config, initialConfig) {
1100
1357
  const ctx = (0, context_1.buildCtx)(config);
1101
1358
  this.ctx = ctx;
1102
- this.agent = new AgentApi(ctx, initialConfig);
1359
+ this.attestor = new AttestorClient_1.AttestorClient(ctx, initialConfig);
1360
+ this.credentials = new Credentials_1.CredentialsApi(ctx, this.attestor);
1361
+ this.agent = new AgentApi(ctx, initialConfig, this.credentials);
1103
1362
  this.reputation = new ReputationApi(ctx);
1104
1363
  this.infra = new SandboxClient_1.SandboxClient(ctx);
1105
- this.attestor = new AttestorClient_1.AttestorClient(ctx, initialConfig);
1106
1364
  this.admin = new AdminApi(this.attestor);
1107
1365
  }
1108
1366
  /**