@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
@@ -14,14 +14,17 @@ exports.deploymentFactsOf = deploymentFactsOf;
14
14
  exports.needsDefaultSettings = needsDefaultSettings;
15
15
  exports.storeDefaultSettings = storeDefaultSettings;
16
16
  exports.defaultIData = defaultIData;
17
+ exports.deployProvider = deployProvider;
17
18
  exports.b64encode = b64encode;
18
19
  const viem_1 = require("viem");
19
20
  const context_1 = require("./context");
20
21
  const Providers_1 = require("./Providers");
21
22
  const constants_1 = require("./constants");
23
+ const Operators_1 = require("./Operators");
22
24
  const abi_1 = require("./abi");
23
25
  const Settings_1 = require("./Settings");
24
26
  const secretEnv_1 = require("./secretEnv");
27
+ const modelKey_1 = require("./legacy/modelKey");
25
28
  exports.CLONE_DOMAIN = 'AgenticID.Clone.v1';
26
29
  exports.CLONE_CONTRACT_DOMAIN = 'AgenticID.CloneContract.v1';
27
30
  exports.DEPLOY_DOMAIN = 'AgenticID.Deploy.v1';
@@ -100,6 +103,12 @@ function iDataFramework(iData) {
100
103
  const name = typeof binding?.name === 'string' ? binding.name.trim() : '';
101
104
  return name || undefined;
102
105
  }
106
+ /** The provider a deploy's model key is for: the persona's (the caller's own
107
+ * `iData`), else the SDK-built persona's (`inference`), else 0g-compute. */
108
+ function deployProvider(params) {
109
+ const seed = params.iData?.find((entry) => entry.role === 'persona')?.plaintext;
110
+ return seed?.inference?.provider ?? params.inference?.provider ?? '0g-compute';
111
+ }
103
112
  // NOTE: the attestor's JSON also carries `subscribe_url` (a ws:// progress feed
104
113
  // its own frontend renders). It's omitted here — programmatic callers track
105
114
  // completion by polling instead (getAgentIdBySealId(seal_id) / GET /deployment).
@@ -160,6 +169,15 @@ function versionInBody(text) {
160
169
  const SEALED_NEEDS_AGENT = "secretEnv 'sealed': a deploy with `sandbox` signs its create envelope before the agent " +
161
170
  '(and its agentSeal key) exists, so the key cannot be sealed. Deploy without `sandbox`, ' +
162
171
  'wait for the mint, then call start(sealId, { apiKey }).';
172
+ /**
173
+ * An HTTP refusal from the attestor or the sandbox provider. The message is
174
+ * `<what>[ failed]: HTTP <status> <body>` as before; the answer is also kept
175
+ * apart (`httpStatus`, `httpWhat`, `httpBody`), so a caller that shows it to
176
+ * a person (the CLI) can say what the server said instead of its raw body.
177
+ */
178
+ function httpRefusal(what, status, body, failed = true) {
179
+ return Object.assign(new Error(`${what}${failed ? ' failed' : ''}: HTTP ${status} ${body}`), { httpStatus: status, httpWhat: what, httpBody: body });
180
+ }
163
181
  function errMsg(e) {
164
182
  return e instanceof Error ? e.message : String(e);
165
183
  }
@@ -176,7 +194,7 @@ function schemeUnsupported(what) {
176
194
  class AttestorClient {
177
195
  constructor(ctx, initialConfig) {
178
196
  this.ctx = ctx;
179
- /** In-memory half of the secret-env sticky pin (see secretEnvScheme). */
197
+ /** LEGACY(model-key): in-memory half of the secret-env sticky pin (see secretEnvScheme). */
180
198
  this.schemeSeen = false;
181
199
  this.remoteRegistrySeen = false;
182
200
  this.remoteRegistrySeen = initialConfig?.provider_registry_schema === 1;
@@ -211,7 +229,7 @@ class AttestorClient {
211
229
  signal: AbortSignal.timeout(10000),
212
230
  });
213
231
  if (!r.ok)
214
- throw new Error(`provider /api/balance: HTTP ${r.status} ${await r.text().catch(() => '')}`);
232
+ throw httpRefusal('provider /api/balance', r.status, await r.text().catch(() => ''), false);
215
233
  const b = (await r.json());
216
234
  return {
217
235
  balanceWei: BigInt(b.balance ?? '0'),
@@ -244,7 +262,7 @@ class AttestorClient {
244
262
  async resolveProviderAddr() {
245
263
  return (await this.attestorConfig()).sandbox_provider_addr ?? '';
246
264
  }
247
- async signEnvelope(action, resourceId, payload, ttlSec) {
265
+ async signEnvelope(action, resourceId, payload, ttlSec, agenticBinding) {
248
266
  const { walletClient, account } = (0, context_1.requireWallet)(this.ctx);
249
267
  // Provider binding (0g-sandbox#93, anti cross-provider replay): inserted
250
268
  // between payload and resource_id (alphabetical), omitted when unknown —
@@ -252,6 +270,7 @@ class AttestorClient {
252
270
  const provider = await this.resolveProviderAddr();
253
271
  const canonical = JSON.stringify({
254
272
  action,
273
+ ...(agenticBinding ? { agentic_id: agenticBinding } : {}),
255
274
  expires_at: Math.floor(Date.now() / 1000) + ttlSec,
256
275
  nonce: randHex(16),
257
276
  payload,
@@ -265,6 +284,140 @@ class AttestorClient {
265
284
  wallet_signature: signature,
266
285
  };
267
286
  }
287
+ /** Public routing metadata; runtime requests are independently authorized by the attestor. */
288
+ async getOperator(sealId) {
289
+ return this.fetchOperator(sealId);
290
+ }
291
+ async fetchOperator(sealId, checkpoint = false) {
292
+ const res = await fetch(`${this.baseUrl()}/operator?seal_id=${encodeURIComponent(sealId)}${checkpoint ? '&checkpoint=true' : ''}`, {
293
+ signal: AbortSignal.timeout(10000),
294
+ });
295
+ if (!res.ok) {
296
+ const error = httpRefusal('/operator', res.status, await res.text().catch(() => ''));
297
+ Object.assign(error, { status: res.status });
298
+ throw error;
299
+ }
300
+ const body = await res.json();
301
+ const anchor = body.checkpoint;
302
+ if (!(0, viem_1.isAddress)(body.owner) || (body.operator !== null && !(0, viem_1.isAddress)(body.operator)) ||
303
+ !Number.isSafeInteger(body.version) || body.version < 0 ||
304
+ !Number.isSafeInteger(body.expires_at) || body.expires_at < 0 ||
305
+ typeof body.allow_recreate !== 'boolean' ||
306
+ (anchor != null && (!Number.isSafeInteger(anchor.number) || Number(anchor.number) < 0 ||
307
+ typeof anchor.hash !== 'string' || !/^0x[0-9a-fA-F]{64}$/.test(anchor.hash)))) {
308
+ throw new Error('/operator returned an invalid authorization summary');
309
+ }
310
+ return {
311
+ sealId, owner: (0, viem_1.getAddress)(body.owner), operator: body.operator === null ? null : (0, viem_1.getAddress)(body.operator),
312
+ version: body.version, allowRecreate: body.allow_recreate, expiresAt: body.expires_at,
313
+ checkpoint: anchor == null ? null : {
314
+ number: anchor.number, hash: anchor.hash,
315
+ },
316
+ };
317
+ }
318
+ /** Owner-only. A successful grant update retires the current runtime; provision again with its controller wallet. */
319
+ async setOperator(sealId, operator, opts = {}) {
320
+ if (!(0, viem_1.isAddress)(operator) || /^0x0{40}$/i.test(operator))
321
+ throw new Error('setOperator: operator must be a nonzero wallet address');
322
+ return this.writeOperator(sealId, (0, viem_1.getAddress)(operator), opts);
323
+ }
324
+ /** Owner-only. Revokes future operations and retires the current runtime. */
325
+ async revokeOperator(sealId, opts = {}) {
326
+ return this.writeOperator(sealId, null, opts);
327
+ }
328
+ async writeOperator(sealId, operator, opts) {
329
+ const { account, walletClient } = (0, context_1.requireWallet)(this.ctx);
330
+ const current = await this.fetchOperator(sealId, operator !== null);
331
+ if ((0, viem_1.getAddress)(account.address) !== current.owner)
332
+ throw new Error('operator authorization requires the current NFT owner');
333
+ if (operator !== null && !current.checkpoint) {
334
+ throw new Error('operator authorization requires a minted agent and an ownership checkpoint from the attestor');
335
+ }
336
+ const base = opts.baseVersion ?? current.version;
337
+ const expiry = operator === null ? 0 : opts.expiresAt ?? 0;
338
+ if (!Number.isSafeInteger(base) || base < 0)
339
+ throw new Error('operator baseVersion must be a nonnegative safe integer');
340
+ if (!Number.isSafeInteger(expiry) || expiry < 0 || (expiry !== 0 && expiry <= Math.floor(Date.now() / 1000))) {
341
+ throw new Error('operator expiresAt must be 0 or a future Unix timestamp');
342
+ }
343
+ if (opts.allowRecreate !== undefined && typeof opts.allowRecreate !== 'boolean') {
344
+ throw new Error('operator allowRecreate must be a boolean');
345
+ }
346
+ const contract = this.ctx.addresses?.agenticID;
347
+ const chainId = this.ctx.chain?.id;
348
+ if (!contract || !(0, viem_1.isAddress)(contract) || !Number.isSafeInteger(chainId) || chainId <= 0) {
349
+ throw new Error('operator authorization requires an AgenticID contract and chain');
350
+ }
351
+ const canonical = JSON.stringify({
352
+ domain: Operators_1.OPERATOR_DOMAIN, chain_id: chainId, contract, seal_id: sealId,
353
+ owner: account.address, base_version: base, operator,
354
+ allow_recreate: operator === null ? false : opts.allowRecreate ?? false,
355
+ expires_at: expiry, issued_at: Math.floor(Date.now() / 1000),
356
+ checkpoint: operator === null ? null : current.checkpoint,
357
+ });
358
+ const signature = await walletClient.signMessage({ account, message: canonical });
359
+ const res = await fetch(`${this.baseUrl()}/operator`, {
360
+ method: 'PUT', headers: { 'content-type': 'application/json' },
361
+ body: JSON.stringify({ seal_id: sealId, signed_message_b64: b64encode(canonical), signature }),
362
+ });
363
+ if (!res.ok) {
364
+ const text = await res.text().catch(() => '');
365
+ if (res.status === 409) {
366
+ let body;
367
+ try {
368
+ body = JSON.parse(text);
369
+ }
370
+ catch { /* Preserve the ordinary conflict for non-JSON responses. */ }
371
+ if (body?.error?.code === 'operator_checkpoint_superseded') {
372
+ const minimum = body.minimum_block;
373
+ throw new Operators_1.OperatorCheckpointSupersededError(sealId, base, text, Number.isSafeInteger(minimum) && Number(minimum) >= 0 ? minimum : undefined);
374
+ }
375
+ throw new Operators_1.OperatorConflictError(sealId, base, text);
376
+ }
377
+ throw httpRefusal('/operator', res.status, text);
378
+ }
379
+ // Re-read public routing metadata after the write.
380
+ return this.getOperator(sealId);
381
+ }
382
+ async runtimeAuthority(sealId) {
383
+ const { account } = (0, context_1.requireWallet)(this.ctx);
384
+ let state;
385
+ try {
386
+ state = await this.getOperator(sealId);
387
+ }
388
+ catch (e) {
389
+ // Older attestors have no operator route and remain owner-only. Other
390
+ // failures must not produce an unbound operator envelope.
391
+ if (e.status === 404)
392
+ return { owner: account.address };
393
+ throw e;
394
+ }
395
+ if (state.owner === (0, viem_1.getAddress)(account.address))
396
+ return { owner: state.owner };
397
+ if (state.operator !== (0, viem_1.getAddress)(account.address) || (state.expiresAt !== 0 && state.expiresAt <= Math.floor(Date.now() / 1000))) {
398
+ throw new Error('connected wallet is neither the current NFT owner nor its active operator');
399
+ }
400
+ const contract = this.ctx.addresses?.agenticID;
401
+ const chainId = this.ctx.chain?.id;
402
+ if (!contract || !(0, viem_1.isAddress)(contract) || !Number.isSafeInteger(chainId) || chainId <= 0) {
403
+ throw new Error('operator lifecycle requires an AgenticID contract and chain');
404
+ }
405
+ return { owner: state.owner, binding: {
406
+ chain_id: chainId, contract, seal_id: sealId, operator_version: state.version,
407
+ } };
408
+ }
409
+ /** Whether the connected wallet is this agent's effective, paying operator. */
410
+ async isRuntimeOperator(sealId) {
411
+ return !!(await this.runtimeAuthority(sealId)).binding;
412
+ }
413
+ /** Public deployment routing, for callers that only retain the agent's seal. */
414
+ async currentSandboxId(sealId) {
415
+ const res = await fetch(`${this.baseUrl()}/deployment/${sealId}`, { signal: AbortSignal.timeout(10000) });
416
+ if (!res.ok)
417
+ throw new Error(`/deployment/${sealId} failed: HTTP ${res.status}`);
418
+ const row = await res.json();
419
+ return row.sandbox_id || null;
420
+ }
268
421
  /**
269
422
  * The agent's public deployment row (`GET /deployment/:sealId`). An
270
423
  * unreadable row refuses, naming `purpose`: the call that needs it posts to
@@ -409,6 +562,8 @@ class AttestorClient {
409
562
  const signature = await walletClient.signMessage({ account, message: prepared.message });
410
563
  return this.publishSignedProviders({ document: prepared.document, signature });
411
564
  }
565
+ /** LEGACY(model-key): the route a request key is bound to (`keyEnv`,
566
+ * `sealApiKey`); a key in the set is bound by {@link modelKeyBinding}. */
412
567
  async credentialRoute(provider, image, sealId) {
413
568
  const accepted = await this.getProviderRegistry();
414
569
  const definition = accepted.providers.find((p) => p.id === provider);
@@ -427,7 +582,27 @@ class AttestorClient {
427
582
  return capable && sealId ? { hash: (0, Providers_1.routeHash)(definition), registry: { version: accepted.version,
428
583
  ...(accepted.version > 0 ? { digest: (0, Providers_1.acceptedRegistryDigest)(accepted.document, accepted.signature) } : {}) } } : undefined;
429
584
  }
430
- /** Verify support for an exact runtime image before signing an owner action. */
585
+ /**
586
+ * Where a model key set through the credential set may go
587
+ * (Credentials.setModelKey): the provider's route in the registry version
588
+ * the attestor serves now, which sealed reads back and checks before it uses
589
+ * the key; with no registry published, the image's built-in route (nothing
590
+ * to bind). The agent's image must support the provider.
591
+ */
592
+ async modelKeyBinding(provider, sealId) {
593
+ await this.assertProviderSupported(provider, { sealId });
594
+ const accepted = await this.getProviderRegistry();
595
+ const definition = accepted.providers.find((p) => p.id === provider);
596
+ if (!definition)
597
+ throw new Error(`UNSUPPORTED_INFERENCE_PROVIDER: ${provider}`);
598
+ if (accepted.version === 0)
599
+ return {};
600
+ return { route_hash: (0, Providers_1.routeHash)(definition), registry: { version: accepted.version, digest: (0, Providers_1.acceptedRegistryDigest)(accepted.document, accepted.signature) } };
601
+ }
602
+ /** Verify support for an exact runtime image before signing an owner
603
+ * action: the image's capabilities the attestor advertises. Whether the
604
+ * request copy of a key can be sealed (`secret_env_scheme`) is not part of
605
+ * it; {@link keyEnv} checks that for the copy it builds. */
431
606
  async assertProviderSupported(provider, options = {}) {
432
607
  const definition = await this.providerDefinition(provider);
433
608
  const builtin = (0, Providers_1.listInferenceProviders)().find((entry) => entry.id === provider);
@@ -437,7 +612,7 @@ class AttestorClient {
437
612
  const cfg = await this.attestorConfig({ fresh: true });
438
613
  const image = await this.resolveSealedImage(options.sealedImage, options.framework, options.sealId);
439
614
  const capabilities = Array.isArray(cfg.inference_capabilities) ? cfg.inference_capabilities : [];
440
- const supported = !!image && cfg.secret_env_scheme === secretEnv_1.SECRET_ENV_SCHEME && capabilities.some((entry) => entry.image === image && ((!changed && entry.providers.includes(provider) && entry.secret_env_versions.includes(2)) ||
615
+ const supported = !!image && capabilities.some((entry) => entry.image === image && ((!changed && entry.providers.includes(provider) && entry.secret_env_versions.includes(2)) ||
441
616
  (entry.secret_env_versions.includes(3) && (definition.native ? entry.providers.includes(provider) : definition.formats.every((format) => entry.formats?.includes(format))))));
442
617
  if (!supported)
443
618
  throw new secretEnv_1.SecretEnvRefusedError('provider_binding_unsupported', `image ${image || '(unknown)'} does not advertise provider-bound credentials for ${provider}; upgrade the sealed image and its attestor capabilities first`);
@@ -481,6 +656,8 @@ class AttestorClient {
481
656
  return { pubkey, onChain };
482
657
  }
483
658
  /**
659
+ * LEGACY(model-key): the request-only form of `credentials.sealModelKey`.
660
+ *
484
661
  * Seal an inference key for one agent without signing anything, for the
485
662
  * integrator whose server supplies the key while a user's wallet signs
486
663
  * (issue #166): the server calls this and hands the browser only the
@@ -507,7 +684,18 @@ class AttestorClient {
507
684
  await this.assertProviderSupported(provider, params);
508
685
  const image = await this.resolveSealedImage(params.sealedImage, params.framework, params.sealId);
509
686
  const boundRoute = await this.credentialRoute(provider, image, params.sealId);
510
- const { pubkey, onChain } = await this.verifiedAgentSeal(params.sealId);
687
+ const pubkey = await this.agentSealPubkeyFor(params.sealId, params.owner, 'sealApiKey');
688
+ return (0, secretEnv_1.sealSecretEnv)(pubkey, params.owner, { API_KEY: params.apiKey }, boundRoute || provider !== '0g-compute' ? provider : undefined, boundRoute?.hash, boundRoute?.registry);
689
+ }
690
+ /**
691
+ * The agent's agentSeal public key, verified as {@link agentSealPubkey}
692
+ * does, for a value sealed on behalf of `owner` without its wallet. The
693
+ * container takes such a value only while `owner` owns the agent, so once
694
+ * the agent is minted `owner` must be its on-chain owner. `what` names the
695
+ * caller in a refusal. Throws {@link SecretEnvRefusedError}.
696
+ */
697
+ async agentSealPubkeyFor(sealId, owner, what) {
698
+ const { pubkey, onChain } = await this.verifiedAgentSeal(sealId);
511
699
  if (onChain) {
512
700
  let chainOwner;
513
701
  try {
@@ -519,14 +707,14 @@ class AttestorClient {
519
707
  }));
520
708
  }
521
709
  catch (e) {
522
- throw new secretEnv_1.SecretEnvRefusedError('chain_read_failed', `sealApiKey: ownerOf failed: ${errMsg(e)}`, { cause: e });
710
+ throw new secretEnv_1.SecretEnvRefusedError('chain_read_failed', `${what}: ownerOf failed: ${errMsg(e)}`, { cause: e });
523
711
  }
524
- if ((0, viem_1.getAddress)(chainOwner) !== (0, viem_1.getAddress)(params.owner)) {
525
- throw new secretEnv_1.SecretEnvRefusedError('owner_mismatch', `sealApiKey: ${(0, viem_1.getAddress)(params.owner)} is not the agent's on-chain owner (${(0, viem_1.getAddress)(chainOwner)}); ` +
712
+ if ((0, viem_1.getAddress)(chainOwner) !== (0, viem_1.getAddress)(owner)) {
713
+ throw new secretEnv_1.SecretEnvRefusedError('owner_mismatch', `${what}: ${(0, viem_1.getAddress)(owner)} is not the agent's on-chain owner (${(0, viem_1.getAddress)(chainOwner)}); ` +
526
714
  'its container would refuse the secret');
527
715
  }
528
716
  }
529
- return (0, secretEnv_1.sealSecretEnv)(pubkey, params.owner, { API_KEY: params.apiKey }, boundRoute || provider !== '0g-compute' ? provider : undefined, boundRoute?.hash, boundRoute?.registry);
717
+ return pubkey;
530
718
  }
531
719
  /** On-chain agentId + agentSeal of a minted agent; null before the mint
532
720
  * (or when this client has no chain context, e.g. a bare AttestorClient
@@ -566,6 +754,8 @@ class AttestorClient {
566
754
  }
567
755
  }
568
756
  /**
757
+ * LEGACY(model-key): only the request copy of a key is sealed this way.
758
+ *
569
759
  * A FRESH read of `GET /config` for the seal-or-not decision, so turning
570
760
  * the flag ON reaches long-lived clients on their next call. The other
571
761
  * direction is deliberately NOT symmetric: after this client (or machine)
@@ -602,12 +792,14 @@ class AttestorClient {
602
792
  }
603
793
  return '';
604
794
  }
795
+ /** LEGACY(model-key): the scheme the request copy of a key needs. */
605
796
  async requireSecretEnvScheme(what) {
606
797
  if (!(await this.secretEnvScheme()))
607
798
  throw schemeUnsupported(what);
608
799
  }
609
- /** env block for a sandbox create payload: the inference key (sealed or in
610
- * clear, see {@link keyEnv}), and nothing else. Reasoning depth used to
800
+ /** LEGACY(model-key): env block for a sandbox create payload: the
801
+ * inference key (sealed or in clear, see {@link keyEnv}), and nothing
802
+ * else; without the request copy a create carries no env. Reasoning depth used to
611
803
  * ride here as `SEAL_OWNER_THINKING`; it does not any more — the container
612
804
  * reads `thinking` from the owner's settings document, which reaches it on
613
805
  * EVERY boot (including a resume, which a create-time variable misses) and
@@ -620,6 +812,9 @@ class AttestorClient {
620
812
  return env;
621
813
  }
622
814
  /**
815
+ * LEGACY(model-key): the key sent with the request, for images that read
816
+ * only that (the credential set is the main path; legacy/modelKey.ts).
817
+ *
623
818
  * How the inference key rides the create payload (issue #166):
624
819
  * - `sealedSecretEnv` (sealed elsewhere, e.g. by an integrator's server
625
820
  * with {@link sealApiKey}): placed verbatim as `SEAL_SECRET_ENV`, only
@@ -690,7 +885,7 @@ class AttestorClient {
690
885
  snapshot,
691
886
  sealed: sandbox.sealed ?? true,
692
887
  // No sealId: the agent does not exist until /deploy answers.
693
- env: await this.sandboxEnv({ apiKey: sandbox.apiKey, mode: sandbox.secretEnv }),
888
+ env: await this.sandboxEnv((0, modelKey_1.deployRequestKey)(sandbox)),
694
889
  }, ttlSec);
695
890
  }
696
891
  /**
@@ -713,15 +908,34 @@ class AttestorClient {
713
908
  * name one: the call refuses before anything is written or signed.
714
909
  */
715
910
  async lifecycle(op, params) {
716
- const { account } = (0, context_1.requireWallet)(this.ctx);
911
+ // Resolve identity and deployment once for this call. Never reuse a grant
912
+ // across calls; API and worker still revalidate at their own boundaries.
913
+ const deploymentPurpose = op === 'stop' ? 'resolve the sandbox'
914
+ : (op === 'reset' || !params.sandboxId) && !params.sealedImage && !params.framework
915
+ ? "pick the sealed image and check the agent's settings" : "check the agent's settings";
916
+ const [authority, row] = await Promise.all([
917
+ this.runtimeAuthority(params.sealId),
918
+ op !== 'stop' || (params.resolveSandbox && !params.sandboxId)
919
+ ? this.deploymentRow(params.sealId, deploymentPurpose)
920
+ : Promise.resolve(undefined),
921
+ ]);
922
+ const operator = !!authority.binding;
923
+ if (operator) {
924
+ (0, Operators_1.assertOperatorComputeOptions)(params);
925
+ (0, Operators_1.assertOperatorComputeOptions)(params.operatorOptions ?? {});
926
+ }
927
+ const keyPlan = operator ? undefined : await params.prepareModelKey?.();
928
+ const keyInCredentials = keyPlan?.keyInCredentials ?? params.keyInCredentials;
929
+ const sandboxId = params.sandboxId ?? (params.resolveSandbox ? row?.sandbox_id : undefined);
717
930
  const ttl = params.envelopeTtlSec ?? 180;
718
931
  // `reset`, OR a first-time `start` of a never-provisioned (mint-only)
719
932
  // agent: both spin a FRESH container via the `create` envelope. A `start`
720
933
  // WITH a sandboxId resumes an existing (stopped) container instead.
721
- const create = op === 'reset' || (op === 'start' && !params.sandboxId);
722
- if (!create && !params.sandboxId)
934
+ const create = op === 'reset' || (op === 'start' && !sandboxId);
935
+ if (!create && !sandboxId)
723
936
  throw new Error(`${op}: sandboxId is required`);
724
- if (create && params.provider && params.provider !== '0g-compute' && !params.apiKey && params.sealedSecretEnv === undefined) {
937
+ const requestKey = (0, modelKey_1.carriesRequestKey)(params);
938
+ if (create && !operator && params.provider && params.provider !== '0g-compute' && !requestKey && !keyInCredentials) {
725
939
  throw new secretEnv_1.SecretEnvRefusedError('invalid_input', `reset/start for ${params.provider} requires its API key`);
726
940
  }
727
941
  // Every boot a start or reset brings about is served the agent's settings
@@ -729,19 +943,15 @@ class AttestorClient {
729
943
  // one stored first (see needsDefaultSettings). The row is read, and every
730
944
  // check below that can refuse runs, before anything is written or signed.
731
945
  let seed = null;
732
- let row;
733
946
  if (op !== 'stop') {
734
- row = await this.deploymentRow(params.sealId, create && !params.sealedImage && !params.framework
735
- ? "pick the sealed image and check the agent's settings"
736
- : "check the agent's settings");
737
- seed = this.defaultSettingsFor(row);
947
+ seed = operator ? null : this.defaultSettingsFor(row);
738
948
  if (seed && params.provider && params.provider !== seed.provider) {
739
949
  throw new Error(`${op}: agent ${params.sealId} has no settings document and could boot with no model; ` +
740
950
  `write its settings (provider ${params.provider} and a model) with setSettings first`);
741
951
  }
742
952
  }
743
953
  let action = op;
744
- let resourceId = params.sandboxId ?? '';
954
+ let resourceId = sandboxId ?? '';
745
955
  let payload = {};
746
956
  if (create) {
747
957
  const snapshot = await this.resolveSealedImage(params.sealedImage, params.framework, params.sealId, row);
@@ -750,7 +960,9 @@ class AttestorClient {
750
960
  payload = {
751
961
  snapshot,
752
962
  sealed: true,
753
- ...(params.apiKey || params.sealedSecretEnv !== undefined
963
+ // LEGACY(model-key): the request copy; a key in the set reaches the
964
+ // container through /provision.
965
+ ...(requestKey
754
966
  ? {
755
967
  env: await this.sandboxEnv({
756
968
  sealId: params.sealId,
@@ -764,10 +976,14 @@ class AttestorClient {
764
976
  : {}),
765
977
  };
766
978
  }
979
+ if (!operator) {
980
+ await params.beforeWrite?.();
981
+ await keyPlan?.beforeWrite?.();
982
+ }
767
983
  if (seed) {
768
984
  await storeDefaultSettings({ setSettings: (sealId, settings, opts) => this.setSettings({ sealId, settings, baseVersion: opts.baseVersion }) }, params.sealId);
769
985
  }
770
- const envelope = await this.signEnvelope(action, resourceId, payload, ttl);
986
+ const envelope = await this.signEnvelope(action, resourceId, payload, ttl, authority.binding);
771
987
  // A no-sandboxId `start` still POSTs /start; the attestor dispatches on the
772
988
  // envelope action (create → fresh provision, start → resume).
773
989
  const path = op === 'reset' ? '/reset' : `/${op}`;
@@ -777,11 +993,11 @@ class AttestorClient {
777
993
  // `framework` rides along so the attestor can keep the row's recorded
778
994
  // framework in sync when a reset switches harness (review #154 F1) —
779
995
  // optional; old attestors ignore unknown fields.
780
- body: JSON.stringify({ seal_id: params.sealId, owner: account.address, sandbox_envelope: envelope, ...(params.framework ? { framework: params.framework } : {}) }),
996
+ body: JSON.stringify({ seal_id: params.sealId, owner: authority.owner, sandbox_envelope: envelope, ...(params.framework ? { framework: params.framework } : {}) }),
781
997
  });
782
998
  if (!res.ok) {
783
999
  const text = await res.text().catch(() => '');
784
- throw new Error(`${path} failed: HTTP ${res.status} ${text}`);
1000
+ throw httpRefusal(path, res.status, text);
785
1001
  }
786
1002
  }
787
1003
  // ── owner settings ──────────────────────────────────────────────────────
@@ -865,6 +1081,9 @@ class AttestorClient {
865
1081
  && !Settings_1.THINKING_LEVELS.includes(thinking.trim().toLowerCase())) {
866
1082
  throw new Error(`setSettings: thinking must be one of ${Settings_1.THINKING_LEVELS.join('|')}, got "${thinking}"`);
867
1083
  }
1084
+ const versionsProblem = (0, Settings_1.versionPicksProblem)(params.settings.versions);
1085
+ if (versionsProblem)
1086
+ throw new Error(`setSettings: ${versionsProblem}`);
868
1087
  if (params.settings.provider)
869
1088
  await this.assertProviderSupported(params.settings.provider, { sealId: params.sealId });
870
1089
  if (params.onWarn) {
@@ -915,7 +1134,7 @@ class AttestorClient {
915
1134
  detail: live ? undefined : `could not re-read the current document: ${text.slice(0, 200)}`,
916
1135
  });
917
1136
  }
918
- throw new Error(`/settings failed: HTTP ${res.status} ${text}`);
1137
+ throw httpRefusal('/settings', res.status, text);
919
1138
  }
920
1139
  const body = (await res.json());
921
1140
  return { version: Number(body.version ?? 0) };
@@ -926,36 +1145,35 @@ class AttestorClient {
926
1145
  * failed idempotent stage (storage upload from persisted ciphertext, mint
927
1146
  * receipt re-fetch, setAgentURI, …) against the SAME seal_id.
928
1147
  *
929
- * Without `apiKey`: posts `{ seal_id, owner }` — idempotent stages only, no
930
- * container work (the cheap owner-field auth path). With `apiKey` or
931
- * `sealedSecretEnv` (and optionally `sealedImage`): attaches the same
932
- * owner-signed "create" envelope reset uses (the key sealed to the agent when the attestor
933
- * supports it, see `secretEnv`), so the worker may continue past the
934
- * idempotent stages into container creation. The attestor keeps no copy of
935
- * the key outside that job, so — as with reset — continuing into a
936
- * container needs it re-supplied.
1148
+ * Every retry carries the same owner-signed "create" envelope reset uses
1149
+ * (optionally with `sealedImage`); the attestor refuses a retry without
1150
+ * it. When the container failed or was stopped, the worker continues past
1151
+ * the idempotent stages into container creation with that envelope; the
1152
+ * container takes the model key from the credential set at its boot.
1153
+ * LEGACY(model-key): `apiKey` / `sealedSecretEnv` also ride the request.
937
1154
  */
938
1155
  async retry(params) {
939
- if (params.provider && params.provider !== '0g-compute' && !params.apiKey && params.sealedSecretEnv === undefined) {
1156
+ const requestKey = (0, modelKey_1.carriesRequestKey)(params);
1157
+ if (params.provider && params.provider !== '0g-compute' && !requestKey && !params.keyInCredentials) {
940
1158
  throw new secretEnv_1.SecretEnvRefusedError('invalid_input', `retry for ${params.provider} requires its API key`);
941
1159
  }
942
1160
  const { account } = (0, context_1.requireWallet)(this.ctx);
943
1161
  const body = { seal_id: params.sealId, owner: account.address };
944
- if (params.apiKey || params.sealedSecretEnv !== undefined) {
945
- const snapshot = await this.resolveSealedImage(params.sealedImage, params.framework, params.sealId);
946
- body.sandbox_envelope = await this.signEnvelope('create', '', {
947
- snapshot,
948
- sealed: true,
949
- env: await this.sandboxEnv({
950
- sealId: params.sealId,
951
- provider: params.provider,
952
- image: snapshot,
953
- apiKey: params.apiKey,
954
- sealedSecretEnv: params.sealedSecretEnv,
955
- mode: params.secretEnv,
956
- }),
957
- }, params.envelopeTtlSec ?? 180);
958
- }
1162
+ const snapshot = await this.resolveSealedImage(params.sealedImage, params.framework, params.sealId);
1163
+ // LEGACY(model-key): the request copy; a key in the set reaches the
1164
+ // container through /provision.
1165
+ const env = requestKey
1166
+ ? await this.sandboxEnv({
1167
+ sealId: params.sealId,
1168
+ provider: params.provider,
1169
+ image: snapshot,
1170
+ apiKey: params.apiKey,
1171
+ sealedSecretEnv: params.sealedSecretEnv,
1172
+ mode: params.secretEnv,
1173
+ })
1174
+ : undefined;
1175
+ await params.beforeWrite?.();
1176
+ body.sandbox_envelope = await this.signEnvelope('create', '', { snapshot, sealed: true, ...(env ? { env } : {}) }, params.envelopeTtlSec ?? 180);
959
1177
  const res = await fetch(`${this.baseUrl()}/retry`, {
960
1178
  method: 'POST',
961
1179
  headers: { 'content-type': 'application/json' },
@@ -963,7 +1181,7 @@ class AttestorClient {
963
1181
  });
964
1182
  if (!res.ok) {
965
1183
  const text = await res.text().catch(() => '');
966
- throw new Error(`/retry failed: HTTP ${res.status} ${text}`);
1184
+ throw httpRefusal('/retry', res.status, text);
967
1185
  }
968
1186
  }
969
1187
  /**
@@ -976,8 +1194,7 @@ class AttestorClient {
976
1194
  // Fail before the first signature: a one-shot deploy signs its create
977
1195
  // envelope before the agent exists, so it can never seal the key.
978
1196
  assertSecretEnvMode(params.sandbox?.secretEnv);
979
- const seed = params.iData?.find((entry) => entry.role === 'persona')?.plaintext;
980
- const provider = seed?.inference?.provider ?? params.inference?.provider ?? '0g-compute';
1197
+ const provider = deployProvider(params);
981
1198
  await this.providerDefinition(provider);
982
1199
  if (params.sandbox && provider !== '0g-compute')
983
1200
  throw new secretEnv_1.SecretEnvRefusedError('sealed_needs_agent', SEALED_NEEDS_AGENT);
@@ -1007,6 +1224,7 @@ class AttestorClient {
1007
1224
  const framework = bound ?? params.framework;
1008
1225
  // Owner canonical — must match CanonicalDeploy (order is irrelevant; the
1009
1226
  // attestor deserializes then re-checks each field).
1227
+ const awaitCredentials = !!(params.awaitCredentials && params.sandbox);
1010
1228
  const canonical = JSON.stringify({
1011
1229
  domain: exports.DEPLOY_DOMAIN,
1012
1230
  idempotency_key: idempotencyKey,
@@ -1015,6 +1233,7 @@ class AttestorClient {
1015
1233
  description: params.description,
1016
1234
  image: params.image ?? null,
1017
1235
  i_data: iData,
1236
+ ...(awaitCredentials ? { await_credentials: true } : {}),
1018
1237
  });
1019
1238
  const ownerSig = await walletClient.signMessage({ account, message: canonical });
1020
1239
  // Provision only when a sandbox is given; omit it → mint-only deploy
@@ -1032,6 +1251,7 @@ class AttestorClient {
1032
1251
  image: params.image ?? null,
1033
1252
  i_data: iData,
1034
1253
  ...(sandbox_envelope ? { sandbox_envelope } : {}),
1254
+ ...(awaitCredentials ? { await_credentials: true } : {}),
1035
1255
  });
1036
1256
  }
1037
1257
  /**
@@ -1147,7 +1367,7 @@ class AttestorClient {
1147
1367
  if (res.ok)
1148
1368
  return (await res.json());
1149
1369
  const text = await res.text().catch(() => '');
1150
- const err = new Error(`${path} failed: HTTP ${res.status} ${text}`);
1370
+ const err = httpRefusal(path, res.status, text);
1151
1371
  if (res.status < 500)
1152
1372
  throw err; // 4xx — client/business error, retry won't help
1153
1373
  lastErr = err; // 5xx — server transient, retry