@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/src/AgenticID.ts CHANGED
@@ -24,22 +24,28 @@ import { modelsForProvider, type InferenceProvider } from './Providers';
24
24
  * ```
25
25
  */
26
26
 
27
+ import { plainText } from './AgentClient';
27
28
  import type { Address, Hash, TransactionReceipt, WriteContractReturnType } from 'viem';
28
29
  import { encodeFunctionData } from 'viem';
29
30
  import { RECEIPT_WAIT, ZERO_G_TESTNET, ZERO_G_MAINNET } from './constants';
30
31
  import { AgenticIDClient, type IntelligentDataResult } from './AgenticIDClient';
31
32
  import { ReputationClient } from './ReputationClient';
32
33
  import { SandboxClient } from './SandboxClient';
33
- import { AttestorClient, type CloneParams, type DeployParams, type DeployCloneResponse } from './AttestorClient';
34
+ import { AttestorClient, deployProvider, type CloneParams, type DeployParams, type DeployCloneResponse } from './AttestorClient';
35
+ import { CredentialsApi, checkModelKeyInput, type SealedModelKey } from './Credentials';
36
+ import { requestKey, requestOnly, storeAfterMint } from './legacy/modelKey';
34
37
  import { sha256Hex, type SettingsDoc } from './Settings';
35
- import type { SecretEnvMode } from './secretEnv';
38
+ import { SecretEnvRefusedError, type SecretEnvMode } from './secretEnv';
39
+ import { assertOperatorComputeOptions, type OperatorOptions, type OperatorState } from './Operators';
36
40
  import { ServeSession, captureProof, proofFromResponse, parseServeProofHeader, type TaskExchange } from './ServeSession';
41
+ import { listedHashes, trustRegistryOf } from './TrustRegistry';
42
+ import { agentMigrationOf, fetchReleases, type AgentMigration, type ReleaseNotice } from './Releases';
37
43
  import { buildCtx, requireWallet, type AgenticIDConfig, type Ctx } from './context';
38
44
  import { makeAgentClient, type AgentClient, type AgentServiceEntry, type AgentRoute } from './AgentClient';
39
45
  import type {
40
46
  ServeProof, GiveFeedbackParams, GiveFeedbackResult, AppendResponseParams,
41
47
  ReadAllFeedbackParams, GetSummaryParams, Feedback, FeedbackSummary, ServeData,
42
- TaskReveal,
48
+ ServeLayers, TaskReveal, SignatureRecord,
43
49
  } from './types';
44
50
 
45
51
  const ZERO = '0x0000000000000000000000000000000000000000';
@@ -77,6 +83,34 @@ export const MIN_SANDBOX_BALANCE_WEI = 10n ** 17n;
77
83
  */
78
84
  export type WaitLevel = 'minted' | 'running';
79
85
 
86
+ /**
87
+ * Options of a start, reset or retry that creates a container. `apiKey` is
88
+ * the agent's model key for `provider`: stored in its credential set and,
89
+ * for older images, sent with the request (legacy/modelKey.ts).
90
+ */
91
+ export interface ModelKeyLifecycleOpts {
92
+ /** The provider `apiKey` is for. Without one the key is the 0g-compute key
93
+ * (`model.0g-compute`), whatever the agent's settings name: pass the
94
+ * provider for any other provider's key. A `sealedModelKey` names its own. */
95
+ provider?: string;
96
+ framework?: string;
97
+ sealedImage?: string;
98
+ apiKey?: string;
99
+ /** The model key sealed for this owner on an integrator's server
100
+ * (`credentials.sealModelKey`), in place of `apiKey`: stored in the set as
101
+ * it is, so the signer never has the key. Its provider is the request's. */
102
+ sealedModelKey?: SealedModelKey;
103
+ /** LEGACY(model-key): `sealApiKey`'s output, sent with this request only
104
+ * and never stored; use `sealedModelKey`. */
105
+ sealedSecretEnv?: string;
106
+ /** LEGACY(model-key): how `apiKey` travels with the request; see {@link SecretEnvMode}. */
107
+ secretEnv?: SecretEnvMode;
108
+ /** LEGACY(model-key): the credential set already holds the key: send it with the request only (older images). */
109
+ keepStoredModelKey?: boolean;
110
+ /** Told when the key could not be stored in the credential set (it still goes with the request). */
111
+ onWarn?: (warning: string) => void;
112
+ }
113
+
80
114
  /**
81
115
  * Facade-normalized deploy/clone acceptance — camelCase like every other
82
116
  * SDK return (the attestor's wire JSON speaks snake_case; the mapping
@@ -85,6 +119,10 @@ export type WaitLevel = 'minted' | 'running';
85
119
  export interface DeployAccepted {
86
120
  sealId: Hash;
87
121
  agentSealAddr: Address;
122
+ /** A key given went into the agent's credential set (`deploy`). False: an
123
+ * attestor from before sets were taken before the mint; it goes in once
124
+ * minted (a wait level, or the caller with `credentials.setModelKey`). */
125
+ modelKeyStored?: boolean;
88
126
  }
89
127
  /** deploy/clone result once the background mint is awaited (`wait: 'minted'`). */
90
128
  type MintedResponse = DeployAccepted & { agentId: bigint };
@@ -127,11 +165,94 @@ export class AgentApi {
127
165
  private readonly attestor: AttestorClient;
128
166
  private readonly infra: SandboxClient;
129
167
  private readonly ctx: Ctx;
130
- constructor(ctx: Ctx, initialConfig?: import('./context').AttestorPublicConfig) {
168
+ private readonly credentials: CredentialsApi;
169
+ constructor(ctx: Ctx, initialConfig?: import('./context').AttestorPublicConfig, credentials?: CredentialsApi) {
131
170
  this.ctx = ctx;
132
171
  this.id = new AgenticIDClient(ctx);
133
172
  this.attestor = new AttestorClient(ctx, initialConfig);
134
173
  this.infra = new SandboxClient(ctx);
174
+ this.credentials = credentials ?? new CredentialsApi(ctx, this.attestor);
175
+ }
176
+
177
+ /**
178
+ * A model key given to start/reset/retry goes into the agent's credential
179
+ * set as `model.<provider>`, stored once every check of the request has
180
+ * passed and before it is sent (`beforeWrite`), so the new container boots
181
+ * with it. (It also rides the request for older images: legacy/modelKey.ts.)
182
+ *
183
+ * The provider is the request's (0g-compute when none is given), or the
184
+ * sealed key's. `keyInCredentials`: the set holds a key for the provider,
185
+ * or is about to, so a create without one in the request is not refused;
186
+ * the key a running container got with its own create does not count, as
187
+ * the new container will not have it.
188
+ */
189
+ private async modelKeyPlan(sealId: Hash, opts: ModelKeyLifecycleOpts, ownerResolved = false): Promise<{ keyInCredentials: boolean; beforeWrite?: () => Promise<void> }> {
190
+ if (!ownerResolved && await this.attestor.isRuntimeOperator(sealId)) {
191
+ assertOperatorComputeOptions(opts);
192
+ // Owner-provisioned credentials reach the runtime through /provision.
193
+ // The operator neither reads nor writes the owner's credential set.
194
+ return { keyInCredentials: true };
195
+ }
196
+ const sealed = opts.sealedModelKey;
197
+ if (sealed && opts.apiKey) throw new SecretEnvRefusedError('conflicting_inputs', 'pass apiKey or sealedModelKey, not both');
198
+ if (sealed && opts.provider && opts.provider !== sealed.provider) {
199
+ throw new SecretEnvRefusedError('conflicting_inputs', `the sealed model key is for ${sealed.provider}, not ${opts.provider}`);
200
+ }
201
+ const provider = sealed?.provider ?? opts.provider ?? '0g-compute';
202
+ const key = sealed ?? opts.apiKey;
203
+ if (key) {
204
+ if (requestOnly(opts)) {
205
+ // LEGACY(model-key): the key goes with the request only, so it needs
206
+ // a request copy.
207
+ if (sealed && !sealed.secretEnv) {
208
+ throw new SecretEnvRefusedError('conflicting_inputs', 'keepStoredModelKey sends the key with the request only, and this sealed model key has no request copy (secretEnv)');
209
+ }
210
+ return { keyInCredentials: false };
211
+ }
212
+ // A sealed key with no request copy reaches the container only through
213
+ // the set: storing it must not fail quietly.
214
+ const required = !!sealed && !sealed.secretEnv;
215
+ return { keyInCredentials: required, beforeWrite: async () => { await this.storeModelKey(sealId, provider, key, { onWarn: opts.onWarn, required }); } };
216
+ }
217
+ if (provider === '0g-compute') return { keyInCredentials: false };
218
+ const cur = await this.credentials.get(sealId).catch(() => undefined);
219
+ return { keyInCredentials: !!cur?.definitions.some((d) => d.inference?.provider === provider) };
220
+ }
221
+
222
+ /**
223
+ * Store a model key in the set; whether it went in. A refusal is reported,
224
+ * not thrown, when the key still goes with the request; `required`: thrown.
225
+ * `newAgent`: see {@link CredentialsApi.setModelKey}. `sealedTo` hears the
226
+ * agentSeal address a key given in clear was sealed to.
227
+ */
228
+ private async storeModelKey(
229
+ sealId: Hash,
230
+ provider: string,
231
+ key: string | SealedModelKey,
232
+ opts: { onWarn?: (warning: string) => void; required?: boolean; newAgent?: boolean; sealedTo?: (address: Address) => void } = {},
233
+ ): Promise<boolean> {
234
+ try {
235
+ const stored = await this.credentials.setModelKey(sealId, provider, key, { push: false, newAgent: opts.newAgent });
236
+ if (stored.sealedTo) opts.sealedTo?.(stored.sealedTo);
237
+ return true;
238
+ } catch (e) {
239
+ if (opts.required) throw e;
240
+ 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`);
241
+ return false;
242
+ }
243
+ }
244
+
245
+ /** After a deploy's mint: the key stored before it was sealed to the agentSeal key now on chain. */
246
+ private async checkSealedTo(agentId: bigint, sealedTo: Address | undefined): Promise<void> {
247
+ if (!sealedTo) return;
248
+ const onChain = await this.id.getAgentSeal(agentId);
249
+ if (onChain.toLowerCase() !== sealedTo.toLowerCase()) {
250
+ throw new Error(
251
+ `deploy: the model key was sealed to ${sealedTo}, but agent ${agentId}'s agentSeal on chain is ${onChain}: ` +
252
+ 'the attestor named another key than the one it minted with (a relaying proxy?). The agent cannot use the stored key; ' +
253
+ 'set it again with credentials.setModelKey and replace the key at its provider',
254
+ );
255
+ }
135
256
  }
136
257
 
137
258
  /**
@@ -142,7 +263,7 @@ export class AgentApi {
142
263
  * read errors fail open — the attestor re-checks at accept anyway.
143
264
  * Opt out per call with `{ preflight: false }`.
144
265
  */
145
- private async preflightOwnerReady(): Promise<void> {
266
+ private async preflightOwnerReady(checkSandboxBalance = true): Promise<void> {
146
267
  const who = this.ctx.account?.address;
147
268
  if (!who) return; // browser-wallet flows preflight in their own UI
148
269
  if (this.ctx.addresses.tappRegistry !== ZERO) {
@@ -158,7 +279,7 @@ export class AgentApi {
158
279
  // chain read failed — fail open, attestor re-checks at accept
159
280
  }
160
281
  }
161
- if (this.ctx.addresses.sandboxServing !== ZERO) {
282
+ if (checkSandboxBalance && this.ctx.addresses.sandboxServing !== ZERO) {
162
283
  try {
163
284
  // Prefer the provider's EFFECTIVE balance (on-chain minus reservations
164
285
  // minus outstanding off-chain debt) — the number its create/start
@@ -244,7 +365,13 @@ export class AgentApi {
244
365
  * Deploy a new agent. Async: returns `{ sealId, agentSealAddr }` once the
245
366
  * attestor accepts the job. Pass `wait: 'minted'` to also block on the
246
367
  * background mint (adds `agentId`) or `wait: 'running'` to also block on
247
- * provision (adds the reachable `url`). See {@link WaitLevel}.
368
+ * provision (adds the reachable `url`); `timeoutMs` covers the whole wait.
369
+ * See {@link WaitLevel}.
370
+ *
371
+ * A model key (`sandbox.apiKey`) is checked before anything is signed and
372
+ * goes into the agent's credential set right after the attestor accepts
373
+ * the deploy (two owner signatures). With a wait level, the key is also
374
+ * checked to be sealed to the agentSeal key the agent was minted with.
248
375
  */
249
376
  deploy(params: DeployParams, opts: { wait: 'running' } & WaitMintOpts): Promise<RunningResponse>;
250
377
  deploy(params: DeployParams, opts: { wait: 'minted' } & WaitMintOpts): Promise<MintedResponse>;
@@ -255,14 +382,42 @@ export class AgentApi {
255
382
  "deploy: wait:'running' needs a sandbox to provision — a mint-only deploy (no sandbox) has no container to wait on; use wait:'minted'",
256
383
  );
257
384
  }
258
- if (opts?.preflight !== false) await this.preflightOwnerReady();
259
- const accepted = acceptedOf(await this.attestor.deploy(params));
385
+ if (opts?.preflight !== false) await this.preflightOwnerReady(!!params.sandbox);
386
+ // The key goes into the credential set as the agent is created: the
387
+ // attestor takes the deploying owner's set before the mint, and holds
388
+ // the container until it is stored (`awaitCredentials`), so the first
389
+ // boot gets it. It is checked first, so a key the store would refuse
390
+ // fails before the deploy is signed. (It also rides the create request
391
+ // for older images: legacy/modelKey.ts.)
392
+ const key = params.sandbox?.apiKey;
393
+ const provider = deployProvider(params);
394
+ if (key) checkModelKeyInput(provider, key);
395
+ const created = acceptedOf(await this.attestor.deploy(key ? { ...params, awaitCredentials: true } : params));
396
+ let sealedTo: Address | undefined;
397
+ const store = (sealId: Hash) =>
398
+ this.storeModelKey(sealId, provider, key as string, { newAgent: true, sealedTo: (address) => { sealedTo = address; } });
399
+ const accepted: DeployAccepted = key ? { ...created, modelKeyStored: await store(created.sealId) } : created;
260
400
  if (!opts?.wait) return accepted;
261
401
  // 'minted' → block on the on-chain mint only (agentId, no url yet).
262
- // 'running' → also block on provision (container up + reachable url).
263
- if (opts.wait === 'running') return { ...accepted, ...(await this.waitForRunning(accepted.sealId, opts)) };
264
- const agentId = await this.waitForMint(accepted.sealId, opts);
265
- return { ...accepted, agentId };
402
+ // 'running' → block on provision (container up + reachable url), and on
403
+ // the mint before it only when the key goes in after the mint.
404
+ // One timeout covers both waits.
405
+ const deadline = Date.now() + (opts.timeoutMs ?? (opts.wait === 'running' ? 300_000 : 180_000));
406
+ const left = () => ({ ...opts, timeoutMs: Math.max(0, deadline - Date.now()) });
407
+ let agentId: bigint | undefined;
408
+ if (opts.wait === 'minted' || (key && !accepted.modelKeyStored)) {
409
+ agentId = await this.waitForMint(accepted.sealId, left());
410
+ if (key) await storeAfterMint(accepted, () => store(accepted.sealId));
411
+ }
412
+ if (opts.wait === 'running') {
413
+ const running = await this.waitForRunning(accepted.sealId, left());
414
+ await this.checkSealedTo(running.agentId, sealedTo);
415
+ if (key) await this.credentials.resyncModelKey(accepted.sealId, { agentUrl: running.url }).catch(() => undefined);
416
+ return { ...accepted, ...running };
417
+ }
418
+ const minted = agentId as bigint;
419
+ await this.checkSealedTo(minted, sealedTo);
420
+ return { ...accepted, agentId: minted };
266
421
  }
267
422
 
268
423
  /**
@@ -578,7 +733,7 @@ export class AgentApi {
578
733
  },
579
734
  body,
580
735
  });
581
- if (!r.ok) throw new Error(`pushSettingsToContainer: HTTP ${r.status}: ${await r.text()}`);
736
+ if (!r.ok) throw new Error(`pushSettingsToContainer: HTTP ${r.status}: ${plainText(await r.text())}`);
582
737
  return (await r.json().catch(() => ({}))) as { note?: string };
583
738
  }
584
739
 
@@ -604,7 +759,7 @@ export class AgentApi {
604
759
  headers: { 'X-Auth-Message': message, 'X-Auth-Signature': signature, 'content-type': 'application/json' },
605
760
  body,
606
761
  });
607
- if (!r.ok) throw new Error(`claimAgent: HTTP ${r.status}: ${await r.text()}`);
762
+ if (!r.ok) throw new Error(`claimAgent: HTTP ${r.status}: ${plainText(await r.text())}`);
608
763
  return (await r.json().catch(() => ({}))) as { displaced?: boolean };
609
764
  }
610
765
 
@@ -636,7 +791,7 @@ export class AgentApi {
636
791
  },
637
792
  body,
638
793
  });
639
- if (!r.ok) throw new Error(`clearConversation: HTTP ${r.status}: ${await r.text()}`);
794
+ if (!r.ok) throw new Error(`clearConversation: HTTP ${r.status}: ${plainText(await r.text())}`);
640
795
  return (await r.json().catch(() => ({}))) as { note?: string };
641
796
  }
642
797
 
@@ -678,10 +833,92 @@ export class AgentApi {
678
833
  },
679
834
  body,
680
835
  });
681
- if (!r.ok) throw new Error(`compactConversation: HTTP ${r.status}: ${await r.text()}`);
836
+ if (!r.ok) throw new Error(`compactConversation: HTTP ${r.status}: ${plainText(await r.text())}`);
837
+ return (await r.json().catch(() => ({}))) as { note?: string };
838
+ }
839
+
840
+ /**
841
+ * Restart one layer of a 0g-harness agent's runtime, in place: `harness`
842
+ * restarts the harness process (the conversation and the disk stay);
843
+ * `sealed` ends sealed, and the loader starts it again — the agent is away
844
+ * for about one start, the disk stays. Either applies the owner's version
845
+ * picks and the trust registry's lists as a start does (sealed/LAYERS.md
846
+ * §3). Owner-signed (tag `0GSealRestart`, the clear grammar, the body
847
+ * `{"layer": …}` bound by its digest). Answers 202 once the restart is
848
+ * under way. 501: the framework has no owner restart, or a `sealed`
849
+ * restart on an image without the loader; 503: sealed is still starting;
850
+ * 409: a replayed signature, or a displaced window when `instanceId` is
851
+ * passed (a restart is a driving action).
852
+ */
853
+ async restartRuntime(
854
+ base: string,
855
+ agentId: bigint,
856
+ layer: 'harness' | 'sealed',
857
+ instanceId?: string,
858
+ ): Promise<{ note?: string }> {
859
+ const { walletClient, account } = requireWallet(this.ctx);
860
+ const sealId = await this.id.getSealId(agentId);
861
+ const body = JSON.stringify({ layer });
862
+ const digest = await sha256Hex(body);
863
+ const audience = new URL(base).origin;
864
+ const message = `0GSealRestart:${sealId}:${Math.floor(Date.now() / 1000)}:${digest}:${audience}`;
865
+ const signature = await walletClient.signMessage({ account, message });
866
+ const r = await fetch(`${base}/_seal/restart`, {
867
+ method: 'POST',
868
+ headers: {
869
+ 'X-Auth-Message': message,
870
+ 'X-Auth-Signature': signature,
871
+ 'content-type': 'application/json',
872
+ ...(instanceId ? { 'X-Client-Instance': instanceId } : {}),
873
+ },
874
+ body,
875
+ });
876
+ if (!r.ok) throw new Error(`restartRuntime: HTTP ${r.status}: ${plainText(await r.text())}`);
682
877
  return (await r.json().catch(() => ({}))) as { note?: string };
683
878
  }
684
879
 
880
+ /**
881
+ * The versions of the layered runtime (0g-harness) the trust registry
882
+ * lists, each list in listing order. An agent runs its owner's pick while
883
+ * it is listed — picked through the settings document's `versions` —
884
+ * otherwise keeps its running version while that stays listed, and
885
+ * otherwise moves to the last entry, the newest (sealed/LAYERS.md §10).
886
+ * LEGACY(pre-1.4.0): null when the chain has no trust registry (AgenticID
887
+ * before 1.4.0).
888
+ */
889
+ async listedVersions(): Promise<{ registry: Address; sealed: Hash[]; harness: Hash[] } | null> {
890
+ const registry = await trustRegistryOf(this.ctx.publicClient, this.ctx.addresses.agenticID);
891
+ // LEGACY(pre-1.4.0)
892
+ if (!registry) return null;
893
+ const [sealed, harness] = await Promise.all([
894
+ listedHashes(this.ctx.publicClient, registry, 'sealed'),
895
+ listedHashes(this.ctx.publicClient, registry, 'harness'),
896
+ ]);
897
+ return { registry, sealed, harness };
898
+ }
899
+
900
+ /**
901
+ * What the agent's sign socket signed, and what its rules refused, oldest
902
+ * first: one record per signature or refusal, with what identifies it (a
903
+ * message's hash and start, a typed-data digest and domain, a transaction's
904
+ * hash, chain, target, value, nonce and selector). The runtime keeps the
905
+ * last 1000 and keeps them across its restarts; it records every request,
906
+ * whichever way the agent reached the socket. Only a 0g-harness agent's
907
+ * runtime keeps the record; the other frameworks answer 404. `after` is a
908
+ * record number (`seq`): only newer records come back. Owner-signed (tag
909
+ * `0GSealSignatures`, the read-only grammar).
910
+ */
911
+ async signatures(base: string, agentId: bigint, opts?: { after?: number }): Promise<SignatureRecord[]> {
912
+ const { message, signature } = await this.signOwner('0GSealSignatures', base, agentId);
913
+ const query = opts?.after !== undefined ? `?after=${opts.after}` : '';
914
+ const r = await fetch(`${base}/_seal/signatures${query}`, {
915
+ headers: { 'X-Auth-Message': message, 'X-Auth-Signature': signature },
916
+ signal: AbortSignal.timeout(20_000),
917
+ });
918
+ if (!r.ok) throw new Error(`signatures: HTTP ${r.status}: ${plainText(await r.text())}`);
919
+ return (await r.json()) as SignatureRecord[];
920
+ }
921
+
685
922
  /** Sign `0GSealAuth` (audience-bound) and exchange it at `{base}/_seal/auth` for a token. */
686
923
  private async mintToken(base: string, agentId: bigint): Promise<string> {
687
924
  const { message, signature } = await this.signOwner('0GSealAuth', base, agentId);
@@ -689,7 +926,7 @@ export class AgentApi {
689
926
  method: 'POST',
690
927
  headers: { 'X-Auth-Message': message, 'X-Auth-Signature': signature },
691
928
  });
692
- if (!r.ok) throw new Error(`authenticate: HTTP ${r.status}: ${await r.text()}`);
929
+ if (!r.ok) throw new Error(`authenticate: HTTP ${r.status}: ${plainText(await r.text())}`);
693
930
  return ((await r.json()) as { token: string }).token;
694
931
  }
695
932
 
@@ -860,6 +1097,7 @@ export class AgentApi {
860
1097
  agentSeal: Address | null;
861
1098
  createdAt: string | null; lastProvisionError: string | null;
862
1099
  containerStatus: ContainerStatus | null;
1100
+ migrate: AgentMigration | null;
863
1101
  }>> {
864
1102
  // slim=1 drops the embedded avatar data-URIs (~95% of the payload); servers
865
1103
  // predating the param ignore it.
@@ -867,6 +1105,17 @@ export class AgentApi {
867
1105
  return rows.map((r) => this.normalizeDeploymentRow(r));
868
1106
  }
869
1107
 
1108
+ /**
1109
+ * The attestor's published release notices, newest first: what each
1110
+ * release changed, and the images it replaces with the end of their
1111
+ * transition period. Which of your agents run one of those images is on
1112
+ * {@link AgentApi.listMyDeployments} (`migrate`). Empty from an attestor
1113
+ * without release notices.
1114
+ */
1115
+ async releases(): Promise<ReleaseNotice[]> {
1116
+ return fetchReleases(this.attestorBase());
1117
+ }
1118
+
870
1119
  /**
871
1120
  * Owner-scoped, authenticated listing — your own agents WITH the fields the
872
1121
  * public {@link AgentApi.listDeployments} withholds (`sandboxId`,
@@ -902,6 +1151,7 @@ export class AgentApi {
902
1151
  agentSeal: Address | null;
903
1152
  createdAt: string | null; lastProvisionError: string | null;
904
1153
  containerStatus: ContainerStatus | null;
1154
+ migrate: AgentMigration | null;
905
1155
  } {
906
1156
  const card = (r.agent_card as Record<string, unknown>) ?? {};
907
1157
  // The card's url points at the /hello card endpoint; the base (origin)
@@ -945,6 +1195,9 @@ export class AgentApi {
945
1195
  createdAt: (r.created_at as string) ?? null,
946
1196
  lastProvisionError: failureReason,
947
1197
  containerStatus: containerStatusOf(r.container_status),
1198
+ // Owner tier only: the release that asks this agent to move to a
1199
+ // newer image, and by when (GET /releases has the notes).
1200
+ migrate: agentMigrationOf(r.migrate),
948
1201
  // No `settings`: the owner's configuration document is owner-gated on
949
1202
  // READ as well as write and is served only by {@link getSettings}. No
950
1203
  // listing tier carries it, so advertising it here would have meant a
@@ -952,52 +1205,72 @@ export class AgentApi {
952
1205
  };
953
1206
  }
954
1207
 
955
- /** Stop a running agent's sandbox (owner-signed). Identity is preserved. */
956
- stop(sealId: Hash, sandboxId: string): Promise<void> {
957
- return this.attestor.lifecycle('stop', { sealId, sandboxId });
1208
+ /** Public runtime delegation. NFT ownership and private settings are not delegated. */
1209
+ getOperator(sealId: Hash): Promise<OperatorState> {
1210
+ return this.attestor.getOperator(sealId);
1211
+ }
1212
+
1213
+ /** Owner-only. Updating a grant retires the current runtime; its controller must provision again. */
1214
+ setOperator(sealId: Hash, operator: Address, opts: OperatorOptions = {}): Promise<OperatorState> {
1215
+ return this.attestor.setOperator(sealId, operator, opts);
1216
+ }
1217
+
1218
+ /** Owner-only. Revokes the operator and retires the current runtime. */
1219
+ revokeOperator(sealId: Hash, opts: { baseVersion?: number } = {}): Promise<OperatorState> {
1220
+ return this.attestor.revokeOperator(sealId, opts);
1221
+ }
1222
+
1223
+ /** Stop a running sandbox with its controller wallet (the owner or appointed, paying operator). */
1224
+ async stop(sealId: Hash, sandboxId?: string): Promise<void> {
1225
+ await this.attestor.lifecycle('stop', { sealId, sandboxId, resolveSandbox: !sandboxId });
958
1226
  }
959
1227
  /**
960
- * Bring an agent's container online (owner-signed). Two shapes:
1228
+ * Bring an agent online with its owner or appointed operator wallet.
1229
+ * The signing wallet controls and pays for the sandbox. Two shapes:
961
1230
  * - `start(sealId, sandboxId)` — resume a STOPPED container.
962
- * - `start(sealId, { apiKey, sealedImage? })` — FIRST provision of a
963
- * mint-only / never-provisioned agent (no sandbox yet): spins a fresh
964
- * container. `apiKey` is required in practice (the fresh container needs
965
- * the LLM key). The semantic counterpart to a sandbox-less `deploy` —
1231
+ * - `start(sealId, options?)` — resumes the mapped sandbox, or first
1232
+ * provisions a mint-only agent when there is no sandbox mapping. It never
1233
+ * resets a mapped sandbox automatically after a failed resume.
1234
+ * A first provision spins a fresh
1235
+ * container. The semantic counterpart to a sandbox-less `deploy` —
966
1236
  * use this, not `reset` (which means "recreate an existing container").
967
- * The key is sealed to the agent when the attestor supports it, so the
968
- * wallet prompt shows ciphertext, not the key (`secretEnv`, default
969
- * `'auto'`; `'sealed'` refuses to send it in clear). When a server
970
- * supplies the key, pass its {@link sealApiKey} output as
971
- * `sealedSecretEnv` instead of `apiKey`, so the key never reaches the
972
- * signer at all.
1237
+ * `apiKey`, the model key, goes into the agent's credential set (see
1238
+ * {@link ModelKeyLifecycleOpts}); a set that holds one already needs
1239
+ * none. When a server supplies the key, pass its
1240
+ * `credentials.sealModelKey` output as `sealedModelKey` instead of
1241
+ * `apiKey`, so the key never reaches the signer at all.
973
1242
  *
974
- * Both shapes, like {@link reset}, first store the default model
1243
+ * Owner calls, like {@link reset}, first store the default model
975
1244
  * (`DEFAULT_PERSONA_INFERENCE`) as the agent's settings document when it
976
1245
  * has none and could boot without a model: a clone, or an agent that has
977
1246
  * provisioned before (`needsDefaultSettings`). That write is one more
978
1247
  * owner signature, made after every check that can refuse the call; an
979
- * existing document is never replaced.
1248
+ * existing document is never replaced. Operator calls do not write settings
1249
+ * or credentials; the owner must configure the model before delegation.
980
1250
  */
981
1251
  start(sealId: Hash, sandboxId: string): Promise<void>;
982
- start(sealId: Hash, opts?: { provider?: string; framework?: string; sealedImage?: string; apiKey?: string; sealedSecretEnv?: string; secretEnv?: SecretEnvMode }): Promise<void>;
983
- start(sealId: Hash, arg?: string | { provider?: string; framework?: string; sealedImage?: string; apiKey?: string; sealedSecretEnv?: string; secretEnv?: SecretEnvMode }): Promise<void> {
1252
+ start(sealId: Hash, opts?: ModelKeyLifecycleOpts): Promise<void>;
1253
+ async start(sealId: Hash, arg?: string | ModelKeyLifecycleOpts): Promise<void> {
984
1254
  if (typeof arg === 'string') return this.attestor.lifecycle('start', { sealId, sandboxId: arg });
985
1255
  // `framework` resolves the right sealed image for a first provision (a
986
1256
  // mint-only hermes/prime agent otherwise boots the default snapshot) —
987
1257
  // same resolution deploy/reset use. (review #154 opportunity)
988
- return this.attestor.lifecycle('start', { sealId, provider: arg?.provider, framework: arg?.framework, sealedImage: arg?.sealedImage, apiKey: arg?.apiKey, sealedSecretEnv: arg?.sealedSecretEnv, secretEnv: arg?.secretEnv });
1258
+ return this.attestor.lifecycle('start', { sealId, resolveSandbox: true,
1259
+ provider: arg?.provider ?? arg?.sealedModelKey?.provider, framework: arg?.framework, sealedImage: arg?.sealedImage,
1260
+ ...requestKey(arg ?? {}), operatorOptions: arg ?? {},
1261
+ prepareModelKey: () => this.modelKeyPlan(sealId, arg ?? {}, true) });
989
1262
  }
990
1263
  /**
991
1264
  * Reset (recreate) an agent's container, preserving its on-chain
992
1265
  * identity — a fresh boot that re-reads iData from chain and reselects
993
- * the framework adapter from the binding. Owner-signed. `apiKey` is
994
- * required in practice: without it the agent boots but cannot call
995
- * its model. When the attestor advertises `secret_env_scheme`, the
996
- * SDK seals the key to the agent's agentSeal key (only the TEE opens
997
- * it) and the owner signs that ciphertext; otherwise it rides the
998
- * signed envelope in clear (`secretEnv`, default `'auto'`; `'sealed'`
999
- * refuses the clear path). The attestor keeps no reusable copy, which
1000
- * is WHY it must be passed again on every recreate.
1266
+ * the framework adapter from the binding. An operator needs the owner's
1267
+ * `allowRecreate` permission and cannot supply model or credential changes. The new
1268
+ * container takes its model key from the agent's credential set at boot:
1269
+ * a key held there needs no `apiKey`. A given `apiKey` (or
1270
+ * `sealedModelKey`) is stored there first, as for {@link start}.
1271
+ * LEGACY(model-key): for older images it also rides the request, sealed
1272
+ * to the agent's agentSeal key when the attestor advertises
1273
+ * `secret_env_scheme`, else in clear (`secretEnv`).
1001
1274
  *
1002
1275
  * An agent with no settings document boots on the model pinned in its
1003
1276
  * minted persona, which leaves the chain at its first commit. So when the
@@ -1009,8 +1282,11 @@ export class AgentApi {
1009
1282
  * reset onto another `provider` until its settings name one: write them
1010
1283
  * with {@link setSettings} first.
1011
1284
  */
1012
- reset(sealId: Hash, opts?: { provider?: string; framework?: string; sealedImage?: string; apiKey?: string; sealedSecretEnv?: string; secretEnv?: SecretEnvMode }): Promise<void> {
1013
- return this.attestor.lifecycle('reset', { sealId, provider: opts?.provider, framework: opts?.framework, sealedImage: opts?.sealedImage, apiKey: opts?.apiKey, sealedSecretEnv: opts?.sealedSecretEnv, secretEnv: opts?.secretEnv });
1285
+ async reset(sealId: Hash, opts?: ModelKeyLifecycleOpts): Promise<void> {
1286
+ return this.attestor.lifecycle('reset', { sealId, provider: opts?.provider ?? opts?.sealedModelKey?.provider,
1287
+ framework: opts?.framework, sealedImage: opts?.sealedImage, ...requestKey(opts ?? {}),
1288
+ operatorOptions: opts ?? {},
1289
+ prepareModelKey: () => this.modelKeyPlan(sealId, opts ?? {}, true) });
1014
1290
  }
1015
1291
 
1016
1292
  /**
@@ -1065,8 +1341,11 @@ export class AgentApi {
1065
1341
  async setSettings(
1066
1342
  sealId: Hash,
1067
1343
  settings: SettingsDoc,
1068
- opts: { baseVersion: number; onWarn?: (warning: string) => void },
1344
+ opts: { baseVersion: number; onWarn?: (warning: string) => void; modelKey?: string },
1069
1345
  ): Promise<{ version: number }> {
1346
+ // A provider switch takes the new provider's key with it: stored (and
1347
+ // pushed to the running agent) first, so the agent can switch to it.
1348
+ if (opts.modelKey) await this.credentials.setModelKey(sealId, settings.provider ?? '0g-compute', opts.modelKey);
1070
1349
  return this.attestor.setSettings({
1071
1350
  sealId,
1072
1351
  settings,
@@ -1076,6 +1355,10 @@ export class AgentApi {
1076
1355
  }
1077
1356
 
1078
1357
  /**
1358
+ * LEGACY(model-key): use `credentials.sealModelKey`, whose key goes into
1359
+ * the agent's credential set and reaches every boot; this one reaches only
1360
+ * the request it is sent with.
1361
+ *
1079
1362
  * Seal an inference key to one agent WITHOUT signing anything — for the
1080
1363
  * integrator whose server supplies the key while the agent's owner signs
1081
1364
  * in a browser. The server calls this (a read-only client is enough: no
@@ -1099,13 +1382,14 @@ export class AgentApi {
1099
1382
  * (storage upload, mint re-fetch, setAgentURI, …) against the same sealId,
1100
1383
  * where redeploying would orphan an already-minted agent.
1101
1384
  *
1102
- * Without opts it does idempotent stages only. Pass `apiKey` (and
1103
- * optionally `sealedImage`) to let it continue past those into container
1104
- * creation — like {@link reset}, the LLM key must be re-supplied (and is
1105
- * sealed the same way, see `secretEnv`).
1385
+ * The owner signs a create envelope, so when the container failed or was
1386
+ * stopped it continues past those stages into container creation,
1387
+ * optionally on `sealedImage`. A model key given (`apiKey` or
1388
+ * `sealedModelKey`) is stored in the credential set as with {@link reset}.
1106
1389
  */
1107
- retry(sealId: Hash, opts?: { provider?: string; framework?: string; sealedImage?: string; apiKey?: string; sealedSecretEnv?: string; secretEnv?: SecretEnvMode }): Promise<void> {
1108
- return this.attestor.retry({ sealId, provider: opts?.provider, framework: opts?.framework, sealedImage: opts?.sealedImage, apiKey: opts?.apiKey, sealedSecretEnv: opts?.sealedSecretEnv, secretEnv: opts?.secretEnv });
1390
+ async retry(sealId: Hash, opts?: ModelKeyLifecycleOpts): Promise<void> {
1391
+ const key = await this.modelKeyPlan(sealId, opts ?? {});
1392
+ return this.attestor.retry({ sealId, provider: opts?.provider ?? opts?.sealedModelKey?.provider, framework: opts?.framework, sealedImage: opts?.sealedImage, ...requestKey(opts ?? {}), ...key });
1109
1393
  }
1110
1394
 
1111
1395
  /**
@@ -1278,6 +1562,8 @@ export class ReputationApi {
1278
1562
  getVerifiedEndpoint(agentId: bigint, client: Address, feedbackIndex: bigint): Promise<string> { return this.rep.getVerifiedEndpoint(agentId, client, feedbackIndex); }
1279
1563
  getVerifiedSummaryForEndpoint(agentId: bigint, uri: string, clients?: Address[]): Promise<FeedbackSummary> { return this.rep.getVerifiedSummaryForEndpoint(agentId, uri, clients); }
1280
1564
  getServeData(agentId: bigint, client: Address, feedbackIndex: bigint): Promise<ServeData> { return this.rep.getServeData(agentId, client, feedbackIndex); }
1565
+ /** The sealed program and official harness version a verified entry's v2 proof named; zero for a v1 entry (registry 1.3.0+). */
1566
+ getServeLayers(agentId: bigint, client: Address, feedbackIndex: bigint): Promise<ServeLayers> { return this.rep.getServeLayers(agentId, client, feedbackIndex); }
1281
1567
  waitForTransaction(txHash: Hash): Promise<TransactionReceipt> { return this.rep.waitForTransaction(txHash); }
1282
1568
  }
1283
1569
 
@@ -1298,6 +1584,8 @@ export class AgenticID {
1298
1584
  readonly agent: AgentApi;
1299
1585
  readonly admin: AdminApi;
1300
1586
  readonly reputation: ReputationApi;
1587
+ /** Owner credentials served by the agent's sealed credential proxy. */
1588
+ readonly credentials: CredentialsApi;
1301
1589
  private readonly infra: SandboxClient;
1302
1590
  /** Long-lived so its instance caches (/config: provider address, sandbox
1303
1591
  * endpoint) are paid once per session, not per call. */
@@ -1307,10 +1595,11 @@ export class AgenticID {
1307
1595
  constructor(config: AgenticIDConfig, initialConfig?: import('./context').AttestorPublicConfig) {
1308
1596
  const ctx = buildCtx(config);
1309
1597
  this.ctx = ctx;
1310
- this.agent = new AgentApi(ctx, initialConfig);
1598
+ this.attestor = new AttestorClient(ctx, initialConfig);
1599
+ this.credentials = new CredentialsApi(ctx, this.attestor);
1600
+ this.agent = new AgentApi(ctx, initialConfig, this.credentials);
1311
1601
  this.reputation = new ReputationApi(ctx);
1312
1602
  this.infra = new SandboxClient(ctx);
1313
- this.attestor = new AttestorClient(ctx, initialConfig);
1314
1603
  this.admin = new AdminApi(this.attestor);
1315
1604
  }
1316
1605