@0gfoundation/0g-agentdna 0.0.0-stage → 0.2.1

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 (206) hide show
  1. package/GUIDE.md +975 -0
  2. package/LICENSE +21 -0
  3. package/MIGRATION.md +84 -0
  4. package/MIGRATION.zh.md +70 -0
  5. package/PROVIDERS.md +273 -0
  6. package/PROVIDERS.zh.md +234 -0
  7. package/README.md +334 -2
  8. package/dist/AgentClient.d.ts +312 -0
  9. package/dist/AgentClient.d.ts.map +1 -0
  10. package/dist/AgentClient.js +715 -0
  11. package/dist/AgentClient.js.map +1 -0
  12. package/dist/AgenticID.d.ts +823 -0
  13. package/dist/AgenticID.d.ts.map +1 -0
  14. package/dist/AgenticID.js +1188 -0
  15. package/dist/AgenticID.js.map +1 -0
  16. package/dist/AgenticIDClient.d.ts +68 -0
  17. package/dist/AgenticIDClient.d.ts.map +1 -0
  18. package/dist/AgenticIDClient.js +198 -0
  19. package/dist/AgenticIDClient.js.map +1 -0
  20. package/dist/AttestorClient.d.ts +465 -0
  21. package/dist/AttestorClient.d.ts.map +1 -0
  22. package/dist/AttestorClient.js +1030 -0
  23. package/dist/AttestorClient.js.map +1 -0
  24. package/dist/Providers.d.ts +72 -0
  25. package/dist/Providers.d.ts.map +1 -0
  26. package/dist/Providers.js +182 -0
  27. package/dist/Providers.js.map +1 -0
  28. package/dist/ReputationClient.d.ts +213 -0
  29. package/dist/ReputationClient.d.ts.map +1 -0
  30. package/dist/ReputationClient.js +708 -0
  31. package/dist/ReputationClient.js.map +1 -0
  32. package/dist/SandboxClient.d.ts +107 -0
  33. package/dist/SandboxClient.d.ts.map +1 -0
  34. package/dist/SandboxClient.js +200 -0
  35. package/dist/SandboxClient.js.map +1 -0
  36. package/dist/ServeProof.d.ts +161 -0
  37. package/dist/ServeProof.d.ts.map +1 -0
  38. package/dist/ServeProof.js +230 -0
  39. package/dist/ServeProof.js.map +1 -0
  40. package/dist/ServeSession.d.ts +180 -0
  41. package/dist/ServeSession.d.ts.map +1 -0
  42. package/dist/ServeSession.js +336 -0
  43. package/dist/ServeSession.js.map +1 -0
  44. package/dist/Settings.d.ts +179 -0
  45. package/dist/Settings.d.ts.map +1 -0
  46. package/dist/Settings.js +247 -0
  47. package/dist/Settings.js.map +1 -0
  48. package/dist/abi.d.ts +2216 -0
  49. package/dist/abi.d.ts.map +1 -0
  50. package/dist/abi.js +1248 -0
  51. package/dist/abi.js.map +1 -0
  52. package/dist/cli/commands/cells.d.ts +62 -0
  53. package/dist/cli/commands/cells.d.ts.map +1 -0
  54. package/dist/cli/commands/cells.js +113 -0
  55. package/dist/cli/commands/cells.js.map +1 -0
  56. package/dist/cli/commands/doctor.d.ts +15 -0
  57. package/dist/cli/commands/doctor.d.ts.map +1 -0
  58. package/dist/cli/commands/doctor.js +236 -0
  59. package/dist/cli/commands/doctor.js.map +1 -0
  60. package/dist/cli/commands/interactive.d.ts +115 -0
  61. package/dist/cli/commands/interactive.d.ts.map +1 -0
  62. package/dist/cli/commands/interactive.js +3052 -0
  63. package/dist/cli/commands/interactive.js.map +1 -0
  64. package/dist/cli/commands/list.d.ts +31 -0
  65. package/dist/cli/commands/list.d.ts.map +1 -0
  66. package/dist/cli/commands/list.js +91 -0
  67. package/dist/cli/commands/list.js.map +1 -0
  68. package/dist/cli/commands/providers.d.ts +3 -0
  69. package/dist/cli/commands/providers.d.ts.map +1 -0
  70. package/dist/cli/commands/providers.js +21 -0
  71. package/dist/cli/commands/providers.js.map +1 -0
  72. package/dist/cli/commands/settings.d.ts +22 -0
  73. package/dist/cli/commands/settings.d.ts.map +1 -0
  74. package/dist/cli/commands/settings.js +188 -0
  75. package/dist/cli/commands/settings.js.map +1 -0
  76. package/dist/cli/commands/status.d.ts +16 -0
  77. package/dist/cli/commands/status.d.ts.map +1 -0
  78. package/dist/cli/commands/status.js +148 -0
  79. package/dist/cli/commands/status.js.map +1 -0
  80. package/dist/cli/commands/update.d.ts +21 -0
  81. package/dist/cli/commands/update.d.ts.map +1 -0
  82. package/dist/cli/commands/update.js +95 -0
  83. package/dist/cli/commands/update.js.map +1 -0
  84. package/dist/cli/config.d.ts +73 -0
  85. package/dist/cli/config.d.ts.map +1 -0
  86. package/dist/cli/config.js +239 -0
  87. package/dist/cli/config.js.map +1 -0
  88. package/dist/cli/env.d.ts +36 -0
  89. package/dist/cli/env.d.ts.map +1 -0
  90. package/dist/cli/env.js +74 -0
  91. package/dist/cli/env.js.map +1 -0
  92. package/dist/cli/envelope.d.ts +33 -0
  93. package/dist/cli/envelope.d.ts.map +1 -0
  94. package/dist/cli/envelope.js +62 -0
  95. package/dist/cli/envelope.js.map +1 -0
  96. package/dist/cli/errors.d.ts +48 -0
  97. package/dist/cli/errors.d.ts.map +1 -0
  98. package/dist/cli/errors.js +81 -0
  99. package/dist/cli/errors.js.map +1 -0
  100. package/dist/cli/inference.d.ts +21 -0
  101. package/dist/cli/inference.d.ts.map +1 -0
  102. package/dist/cli/inference.js +60 -0
  103. package/dist/cli/inference.js.map +1 -0
  104. package/dist/cli/logo.d.ts +21 -0
  105. package/dist/cli/logo.d.ts.map +1 -0
  106. package/dist/cli/logo.js +131 -0
  107. package/dist/cli/logo.js.map +1 -0
  108. package/dist/cli/main.d.ts +14 -0
  109. package/dist/cli/main.d.ts.map +1 -0
  110. package/dist/cli/main.js +223 -0
  111. package/dist/cli/main.js.map +1 -0
  112. package/dist/cli/proofs.d.ts +67 -0
  113. package/dist/cli/proofs.d.ts.map +1 -0
  114. package/dist/cli/proofs.js +133 -0
  115. package/dist/cli/proofs.js.map +1 -0
  116. package/dist/cli/ref.d.ts +39 -0
  117. package/dist/cli/ref.d.ts.map +1 -0
  118. package/dist/cli/ref.js +48 -0
  119. package/dist/cli/ref.js.map +1 -0
  120. package/dist/cli/sdk.d.ts +24 -0
  121. package/dist/cli/sdk.d.ts.map +1 -0
  122. package/dist/cli/sdk.js +65 -0
  123. package/dist/cli/sdk.js.map +1 -0
  124. package/dist/cli/settings.d.ts +66 -0
  125. package/dist/cli/settings.d.ts.map +1 -0
  126. package/dist/cli/settings.js +137 -0
  127. package/dist/cli/settings.js.map +1 -0
  128. package/dist/cli/tokenize.d.ts +61 -0
  129. package/dist/cli/tokenize.d.ts.map +1 -0
  130. package/dist/cli/tokenize.js +157 -0
  131. package/dist/cli/tokenize.js.map +1 -0
  132. package/dist/cli/types.d.ts +25 -0
  133. package/dist/cli/types.d.ts.map +1 -0
  134. package/dist/cli/types.js +8 -0
  135. package/dist/cli/types.js.map +1 -0
  136. package/dist/constants.d.ts +107 -0
  137. package/dist/constants.d.ts.map +1 -0
  138. package/dist/constants.js +74 -0
  139. package/dist/constants.js.map +1 -0
  140. package/dist/context.d.ts +108 -0
  141. package/dist/context.d.ts.map +1 -0
  142. package/dist/context.js +64 -0
  143. package/dist/context.js.map +1 -0
  144. package/dist/index.d.ts +45 -0
  145. package/dist/index.d.ts.map +1 -0
  146. package/dist/index.js +118 -0
  147. package/dist/index.js.map +1 -0
  148. package/dist/provider-catalog.json +23 -0
  149. package/dist/seal.d.ts +47 -0
  150. package/dist/seal.d.ts.map +1 -0
  151. package/dist/seal.js +145 -0
  152. package/dist/seal.js.map +1 -0
  153. package/dist/secretEnv.d.ts +119 -0
  154. package/dist/secretEnv.d.ts.map +1 -0
  155. package/dist/secretEnv.js +199 -0
  156. package/dist/secretEnv.js.map +1 -0
  157. package/dist/taskHash.d.ts +39 -0
  158. package/dist/taskHash.d.ts.map +1 -0
  159. package/dist/taskHash.js +119 -0
  160. package/dist/taskHash.js.map +1 -0
  161. package/dist/types.d.ts +336 -0
  162. package/dist/types.d.ts.map +1 -0
  163. package/dist/types.js +19 -0
  164. package/dist/types.js.map +1 -0
  165. package/package.json +75 -4
  166. package/scripts/sync-providers.cjs +8 -0
  167. package/src/AgentClient.ts +897 -0
  168. package/src/AgenticID.ts +1382 -0
  169. package/src/AgenticIDClient.ts +238 -0
  170. package/src/AttestorClient.ts +1306 -0
  171. package/src/Providers.ts +176 -0
  172. package/src/ReputationClient.ts +821 -0
  173. package/src/SandboxClient.ts +227 -0
  174. package/src/ServeProof.ts +290 -0
  175. package/src/ServeSession.ts +421 -0
  176. package/src/Settings.ts +296 -0
  177. package/src/abi.ts +1282 -0
  178. package/src/cli/commands/cells.ts +107 -0
  179. package/src/cli/commands/doctor.ts +235 -0
  180. package/src/cli/commands/interactive.ts +2738 -0
  181. package/src/cli/commands/list.ts +95 -0
  182. package/src/cli/commands/providers.ts +16 -0
  183. package/src/cli/commands/settings.ts +197 -0
  184. package/src/cli/commands/status.ts +170 -0
  185. package/src/cli/commands/update.ts +86 -0
  186. package/src/cli/config.ts +225 -0
  187. package/src/cli/env.ts +90 -0
  188. package/src/cli/envelope.ts +57 -0
  189. package/src/cli/errors.ts +114 -0
  190. package/src/cli/inference.ts +57 -0
  191. package/src/cli/logo.ts +125 -0
  192. package/src/cli/main.ts +235 -0
  193. package/src/cli/proofs.ts +160 -0
  194. package/src/cli/ref.ts +58 -0
  195. package/src/cli/sdk.ts +65 -0
  196. package/src/cli/settings.ts +153 -0
  197. package/src/cli/tokenize.ts +131 -0
  198. package/src/cli/types.ts +27 -0
  199. package/src/constants.ts +106 -0
  200. package/src/context.ts +161 -0
  201. package/src/index.ts +129 -0
  202. package/src/provider-catalog.json +23 -0
  203. package/src/seal.ts +163 -0
  204. package/src/secretEnv.ts +250 -0
  205. package/src/taskHash.ts +100 -0
  206. package/src/types.ts +357 -0
@@ -0,0 +1,465 @@
1
+ /**
2
+ * @file AttestorClient.ts
3
+ * @description Internal client for attestor HTTP endpoints: seal-bound deploy +
4
+ * clone. Consumers use the `AgenticID` facade's `agent` namespace.
5
+ *
6
+ * Neither is an on-chain call. The owner signs a canonical envelope (EIP-191) and
7
+ * POSTs it; the attestor verifies the signer and drives the mint. Deploy also
8
+ * carries a sandbox "create" envelope the attestor relays to the sandbox provider.
9
+ */
10
+ import type { Address } from 'viem';
11
+ import { type Ctx, type AttestorPublicConfig } from './context';
12
+ import { type InferenceProvider, type ProviderRegistrySnapshot } from './Providers';
13
+ import { type SettingsDoc } from './Settings';
14
+ import { type SecretEnvMode } from './secretEnv';
15
+ export declare const CLONE_DOMAIN = "AgenticID.Clone.v1";
16
+ export declare const CLONE_CONTRACT_DOMAIN = "AgenticID.CloneContract.v1";
17
+ export declare const DEPLOY_DOMAIN = "AgenticID.Deploy.v1";
18
+ export interface CloneParams {
19
+ sourceAgentId: bigint;
20
+ targetOwner: Address;
21
+ /**
22
+ * Idempotency key. Optional — the SDK generates a random one per call. Pass
23
+ * your own stable key to make a retry dedupe server-side (same key → returns
24
+ * the existing clone instead of minting a duplicate).
25
+ */
26
+ idempotencyKey?: string;
27
+ /**
28
+ * Contract-mode credentials (issue #133 marketplace fork flow). Omit for the
29
+ * original owner mode — the connected wallet must then be the source's
30
+ * current on-chain owner.
31
+ *
32
+ * In contract mode the connected wallet is the BUYER (`targetOwner`): it
33
+ * signs a clone-intent (domain `AgenticID.CloneContract.v1`), and the
34
+ * source owner's on-chain `ICloneAuthorizer` decides whether the clone may
35
+ * mint. `authData` is opaque bytes forwarded to the authorizer — the
36
+ * marketplace defines its shape (e.g. abi-encoded purchase id).
37
+ *
38
+ * The intent binds the FULL policy context: `keccak256(authData)` and the
39
+ * authorizer address are signed alongside the operation fields, so a
40
+ * relayer can transport the request but cannot resubmit it under
41
+ * different auth data (each variant would be a fresh, buyer-billed clone)
42
+ * or carry it across a policy rotation. `authorizer` is optional here —
43
+ * omitted, the SDK reads it live via `cloneAuthorizerOf`; pass it
44
+ * explicitly to stay offline or pin the read.
45
+ */
46
+ authorization?: {
47
+ /** Opaque bytes forwarded to the source's `ICloneAuthorizer.canClone`. */
48
+ authData: `0x${string}`;
49
+ /**
50
+ * The authorizer the intent will be signed under. Optional — read live
51
+ * from `cloneAuthorizerOf(sourceAgentId)` when omitted. Must be
52
+ * non-zero; the attestor cross-checks it against its own live read.
53
+ */
54
+ authorizer?: Address;
55
+ };
56
+ }
57
+ /** One intelligent-data input (role + opaque JSON plaintext + extra description fields). */
58
+ export interface IDataInput {
59
+ role: string;
60
+ plaintext: unknown;
61
+ extra?: Record<string, unknown>;
62
+ }
63
+ /** Inputs for {@link defaultIData}. */
64
+ export interface DefaultIDataParams {
65
+ /** Framework name for the binding; default "openclaw". */
66
+ framework?: string;
67
+ name: string;
68
+ description: string;
69
+ /** Persona inference pin; default 0g-compute/0gm-1.0-35b-a3b (the 0G router's own model). */
70
+ inference?: {
71
+ provider: string;
72
+ model: string;
73
+ };
74
+ }
75
+ /**
76
+ * The canonical two-entry default iData — the same shape the attestor
77
+ * used to synthesize server-side before the WYSIWYS API change:
78
+ *
79
+ * - a VERSION-LESS framework binding `{name, schema_version}` (the
80
+ * sealed adapter resolves the missing version to its validated
81
+ * whitelistMax), and
82
+ * - the `persona` protocol seed `{system_prompt, inference}` that every
83
+ * adapter translates into its own config (FRAMEWORK_ADAPTER.md §5.4).
84
+ *
85
+ * Owners sign these exact bytes: defaults are now part of the signed
86
+ * content rather than a server-side template.
87
+ */
88
+ export declare function defaultIData(p: DefaultIDataParams): IDataInput[];
89
+ export interface DeployParams {
90
+ /**
91
+ * Idempotency key. Optional — the SDK generates a random one per call. Pass
92
+ * your own stable key to make a retry dedupe server-side (same key → returns
93
+ * the existing deploy instead of minting a duplicate).
94
+ */
95
+ idempotencyKey?: string;
96
+ name: string;
97
+ description: string;
98
+ image?: string;
99
+ /**
100
+ * The agent's complete iData, exactly as it will be encrypted and
101
+ * minted — WYSIWYS: the bytes you sign here are the bytes that get
102
+ * sealed; the attestor synthesizes nothing. Must include a
103
+ * `role="framework"` binding (`{name, schema_version}`). Omit (or pass
104
+ * empty) and the SDK builds `defaultIData()` for you from
105
+ * name/description/framework/inference below.
106
+ */
107
+ iData?: IDataInput[];
108
+ /**
109
+ * Agent-framework name for the SDK-built default iData ("openclaw"
110
+ * default). Must be one of the names your attestor's `GET /config`
111
+ * advertises in `frameworks[]` — the attestor rejects unsupported names
112
+ * pre-mint. The SDK also resolves this framework's sealed image from
113
+ * `frameworks[]` when you don't pass `sandbox.sealedImage`, so you never
114
+ * need to know a framework's image. CLIENT-SIDE for the binding: it feeds
115
+ * `defaultIData()` when `iData` is omitted — the on-chain binding inside
116
+ * i_data is the single source of truth (validated against `GET /config`'s
117
+ * `frameworks[]` before mint). Ignored when you pass your own `iData`.
118
+ */
119
+ framework?: string;
120
+ /** Inference pin for the SDK-built default persona (defaults to
121
+ * 0g-compute/0gm-1.0-35b-a3b). Ignored when you pass your own `iData`. */
122
+ inference?: {
123
+ provider: string;
124
+ model: string;
125
+ };
126
+ /** Sandbox "create" payload the attestor relays to the provider. OPTIONAL:
127
+ * omit it entirely to MINT WITHOUT provisioning a container — the agent
128
+ * lands Offline (minted, no runtime), brought online later via start().
129
+ * The "mint-only" deploy. */
130
+ sandbox?: {
131
+ /** The sealed runtime image name (0g-sandbox's own field is called
132
+ * `snapshot`; the SDK sends it verbatim under that wire name).
133
+ * Omit (or pass '') to use the attestor /config's current image —
134
+ * the operator-maintained default. */
135
+ sealedImage?: string;
136
+ /** Inference API key. On this one-shot path the create envelope is
137
+ * signed before the agent (and its agentSeal key) exists, so the key
138
+ * cannot be sealed and rides the envelope in clear: the wallet prompt
139
+ * shows it. To keep it out of the prompt, deploy without `sandbox`,
140
+ * wait for the mint, then `start(sealId, { apiKey })`. */
141
+ apiKey: string;
142
+ /** See {@link SecretEnvMode}. `'sealed'` makes this call throw before
143
+ * anything is signed, because a one-shot deploy cannot seal the key. */
144
+ secretEnv?: SecretEnvMode;
145
+ sealed?: boolean;
146
+ resourceId?: string;
147
+ };
148
+ /** Seconds the sandbox envelope stays valid. Default 180. */
149
+ envelopeTtlSec?: number;
150
+ }
151
+ export interface DeployCloneResponse {
152
+ seal_id: `0x${string}`;
153
+ agent_seal_addr: Address;
154
+ }
155
+ /**
156
+ * base64 of a string's UTF-8 bytes — on every runtime.
157
+ *
158
+ * The global `btoa` is LATIN-1: it takes a binary string, one byte per code
159
+ * unit. Handing it a JS string directly throws `InvalidCharacterError` on
160
+ * anything above U+00FF (so any CJK payload died outright), and silently
161
+ * encodes the WRONG bytes for U+0080..U+00FF — "café" shipped `Y2Fm6Q==`
162
+ * where the signature covered the UTF-8 `Y2Fmw6k=`. The attestor then
163
+ * recovered a different signer and reported the misleading
164
+ * "signer mismatch". So encode to UTF-8 first and feed btoa the bytes, the
165
+ * same form the attestor's own console uses (attestor/crates/api/web/index.html).
166
+ */
167
+ export declare function b64encode(s: string): string;
168
+ export declare class AttestorClient {
169
+ private readonly ctx;
170
+ /** In-memory half of the secret-env sticky pin (see secretEnvScheme). */
171
+ private schemeSeen;
172
+ constructor(ctx: Ctx, initialConfig?: AttestorPublicConfig);
173
+ private baseUrl;
174
+ /**
175
+ * The EFFECTIVE spendable balance, from the sandbox provider's
176
+ * owner-signed `GET /api/balance`: on-chain balance minus in-flight
177
+ * reservations minus outstanding off-chain debt (accrued fees not yet
178
+ * settled). This is the number the provider's create/start gates actually
179
+ * enforce — the on-chain `getBalance` alone can be wildly optimistic
180
+ * (observed live: 3.6 OG on chain, 25 OG outstanding debt, available 0).
181
+ * Requires the attestor /config to advertise `sandbox_endpoint`.
182
+ */
183
+ getEffectiveBalance(): Promise<{
184
+ balanceWei: bigint;
185
+ reservedWei: bigint;
186
+ outstandingDebtWei: bigint;
187
+ pendingSettlementWei: bigint;
188
+ availableWei: bigint;
189
+ }>;
190
+ /**
191
+ * Owner-signed sandbox action envelope. The sandbox runtime verifies
192
+ * every lifecycle action against the owner wallet; field order must
193
+ * match its `signedRequest` struct exactly
194
+ * ({action, expires_at, nonce, payload, resource_id}) or the recovered
195
+ * signer won't match.
196
+ */
197
+ /** One cached /config fetch per client instance — the provider address
198
+ * (0g-sandbox#93 envelope binding), sandbox endpoint (effective balance),
199
+ * and future needs ride the same round-trip. {} on failure: every
200
+ * consumer already degrades on missing fields. */
201
+ private cfgPromise;
202
+ private attestorConfig;
203
+ private resolveProviderAddr;
204
+ private signEnvelope;
205
+ /**
206
+ * Resolve the sealed image name: an explicit value wins; otherwise the
207
+ * image `GET /config` declares for `framework` (frameworks whose runtime
208
+ * isn't in the default snapshot — hermes etc. — carry their own image);
209
+ * failing that, the default `sandbox_snapshot`. So a caller who passes a
210
+ * `framework` never needs to know its image. An empty snapshot in the
211
+ * create envelope makes the provider fail ("sealed containers require an
212
+ * image or snapshot"), so /config is the source of truth.
213
+ */
214
+ private resolveSealedImage;
215
+ private providerRegistry?;
216
+ private remoteRegistrySeen;
217
+ listProviders(): InferenceProvider[];
218
+ getProviderRegistry(): Promise<ProviderRegistrySnapshot>;
219
+ providerDefinition(id: string): Promise<InferenceProvider>;
220
+ /** Build an owner-authorized publication request. Contract-wallet owners
221
+ * can obtain their signature externally and call publishSignedProviders. */
222
+ prepareProviderUpdate(providers: InferenceProvider[], baseVersion: number): Promise<{
223
+ document: string;
224
+ message: string;
225
+ owner: Address;
226
+ }>;
227
+ publishSignedProviders(update: {
228
+ document: string;
229
+ signature: `0x${string}`;
230
+ }): Promise<{
231
+ version: number;
232
+ }>;
233
+ updateProviders(providers: InferenceProvider[], baseVersion: number): Promise<{
234
+ version: number;
235
+ }>;
236
+ private credentialRoute;
237
+ /** Verify support for an exact runtime image before signing an owner action. */
238
+ assertProviderSupported(provider: string, options?: {
239
+ sealId?: `0x${string}`;
240
+ framework?: string;
241
+ sealedImage?: string;
242
+ }): Promise<void>;
243
+ /**
244
+ * The agent's agentSeal public key (compressed hex), verified before
245
+ * anything is sealed to it: the answer must be for `sealId`, the key must
246
+ * hash to the `agent_seal_addr` the attestor reports and, once the agent is
247
+ * minted, to the agentSeal on chain (`getAgentSeal`), so a relaying proxy
248
+ * cannot substitute its own key. Throws {@link SecretEnvRefusedError}.
249
+ */
250
+ agentSealPubkey(sealId: `0x${string}`): Promise<`0x${string}`>;
251
+ private verifiedAgentSeal;
252
+ /**
253
+ * Seal an inference key for one agent without signing anything, for the
254
+ * integrator whose server supplies the key while a user's wallet signs
255
+ * (issue #166): the server calls this and hands the browser only the
256
+ * returned ciphertext, which the browser passes to `start` / `reset` /
257
+ * `retry` as `sealedSecretEnv`. The key never reaches the browser, and the
258
+ * wallet prompt shows only ciphertext.
259
+ *
260
+ * Needs no wallet: a read-only client (`attestorUrl`, `addresses`, RPC) is
261
+ * enough. `owner` is the address that will sign the envelope; the agent's
262
+ * container applies the secret only while that address is its on-chain
263
+ * owner, so once the agent is minted this checks `ownerOf` first. It also
264
+ * requires the attestor to advertise `secret_env_scheme` (a fresh read of
265
+ * `GET /config`) and verifies the agentSeal key as {@link agentSealPubkey}
266
+ * does. Throws {@link SecretEnvRefusedError}; returns the base64 value for
267
+ * `env.SEAL_SECRET_ENV`.
268
+ */
269
+ sealApiKey(params: {
270
+ sealId: `0x${string}`;
271
+ owner: Address;
272
+ apiKey: string;
273
+ provider?: string;
274
+ framework?: string;
275
+ sealedImage?: string;
276
+ }): Promise<string>;
277
+ /** On-chain agentId + agentSeal of a minted agent; null before the mint
278
+ * (or when this client has no chain context, e.g. a bare AttestorClient
279
+ * in tests). A failed read throws: an unanswered check is not a pass. */
280
+ private onChainAgent;
281
+ /**
282
+ * A FRESH read of `GET /config` for the seal-or-not decision, so turning
283
+ * the flag ON reaches long-lived clients on their next call. The other
284
+ * direction is deliberately NOT symmetric: after this client (or machine)
285
+ * has seen the scheme once, its absence throws `scheme_withdrawn` — see
286
+ * the sticky pin below. Returns the scheme ('' when never seen and not
287
+ * advertised); throws when /config cannot be read at all.
288
+ */
289
+ private secretEnvScheme;
290
+ private requireSecretEnvScheme;
291
+ /** env block for a sandbox create payload: the inference key (sealed or in
292
+ * clear, see {@link keyEnv}), and nothing else. Reasoning depth used to
293
+ * ride here as `SEAL_OWNER_THINKING`; it does not any more — the container
294
+ * reads `thinking` from the owner's settings document, which reaches it on
295
+ * EVERY boot (including a resume, which a create-time variable misses) and
296
+ * can be changed without a recreate. See {@link SettingsDoc}. */
297
+ private sandboxEnv;
298
+ /**
299
+ * How the inference key rides the create payload (issue #166):
300
+ * - `sealedSecretEnv` (sealed elsewhere, e.g. by an integrator's server
301
+ * with {@link sealApiKey}): placed verbatim as `SEAL_SECRET_ENV`, only
302
+ * when the attestor advertises `secret_env_scheme`; there is no clear
303
+ * fallback, because there is no key here to fall back to;
304
+ * - `apiKey`, sealed here to the agent as `SEAL_SECRET_ENV` (see
305
+ * secretEnv.ts) when the agent already exists (`sealId`) and the
306
+ * attestor advertises `secret_env_scheme`, so the wallet prompt shows
307
+ * ciphertext only;
308
+ * - otherwise `apiKey` in clear as `API_KEY` (older attestors and images,
309
+ * and a one-shot `deploy`, whose agent does not exist when it signs),
310
+ * unless `mode` is `'sealed'`, which throws instead.
311
+ * Once sealing is chosen, every error throws: nothing falls back to clear
312
+ * text after the fact. Every throw is a {@link SecretEnvRefusedError}
313
+ * raised before anything is signed.
314
+ */
315
+ private keyEnv;
316
+ /** Sandbox "create" envelope for deploy (relayed to the provider). */
317
+ private sandboxEnvelope;
318
+ /**
319
+ * Lifecycle op on a deployed agent's sandbox. `stop`/`start` act on the
320
+ * existing container (resourceId = sandbox_id); `reset` is an
321
+ * unconditional recreate (action="create", empty resource_id) that
322
+ * preserves the on-chain identity and replaces only the container —
323
+ * the way to force a fresh boot (e.g. after a new sealed image, or
324
+ * stuck-state recovery). All are owner-signed; the attestor + sandbox
325
+ * both re-verify.
326
+ */
327
+ lifecycle(op: 'stop' | 'start' | 'reset', params: {
328
+ sealId: `0x${string}`;
329
+ sandboxId?: string;
330
+ /** Framework name for `reset`/first `start` — the SDK resolves its
331
+ * sealed image from GET /config's frameworks[] (same as deploy), so a
332
+ * non-default framework doesn't need `sealedImage` passed. */
333
+ framework?: string;
334
+ /** The sealed runtime image name (0g-sandbox's own field is called
335
+ * `snapshot`; only relevant for `reset`). Explicit wins over the
336
+ * framework-resolved image. */
337
+ sealedImage?: string;
338
+ /** Inference API key for `reset` — the fresh container needs a fresh
339
+ * env (the attestor doesn't cache the LLM key). Without it the agent
340
+ * comes back alive but can't call its model. Sealed to the agent when
341
+ * the attestor supports it (see `secretEnv`). */
342
+ apiKey?: string;
343
+ /** Credential provider; defaults to legacy compute. */
344
+ provider?: string;
345
+ /** The key already sealed to this agent (the value {@link sealApiKey}
346
+ * returned, e.g. on an integrator's server), in place of `apiKey`:
347
+ * signed verbatim as `SEAL_SECRET_ENV`, so the key never has to reach
348
+ * the signer. Requires the attestor to advertise `secret_env_scheme`. */
349
+ sealedSecretEnv?: string;
350
+ /** How `apiKey` travels; see {@link SecretEnvMode}. Default `'auto'`. */
351
+ secretEnv?: SecretEnvMode;
352
+ envelopeTtlSec?: number;
353
+ }): Promise<void>;
354
+ /**
355
+ * The agent's current settings document, as the attestor is holding it, plus
356
+ * the version to write it back against. `settings: null` means the agent has
357
+ * never been configured — not an error — and `version: 0` is exactly the
358
+ * `baseVersion` such a first write takes.
359
+ *
360
+ * OWNER-SIGNED, like the write, and against the same LIVE on-chain owner:
361
+ * the document is the owner's, it can name a private endpoint or a paid
362
+ * model, and it is no more public than the wallet that authored it. It is
363
+ * therefore NOT on the deployment row and NOT in any listing —
364
+ * `GET /settings?seal_id=…` with an owner signature is the only way to read
365
+ * it. The message is the write's minus the digest (there is no body), so it
366
+ * ends at the base version, which a reader sends as 0.
367
+ *
368
+ * Requires a wallet.
369
+ */
370
+ getSettings(sealId: `0x${string}`): Promise<{
371
+ settings: SettingsDoc | null;
372
+ version: number;
373
+ }>;
374
+ /**
375
+ * Write a new settings document (owner-signed, compare-and-swap).
376
+ *
377
+ * The wire contract, exactly:
378
+ * - body `{"seal_id": "0x…", "base_version": <n>, "settings": <the document>}`
379
+ * - header `X-Auth-Message: AgenticID.Settings.v1:0x<sealId>:<ts>:<base_version>:<sha256-hex>`
380
+ * - header `X-Auth-Signature: 0x<65-byte EIP-191 signature over that message>`
381
+ *
382
+ * `baseVersion` is the version {@link getSettings} returned before the edit
383
+ * (0 = "there is no document yet"). The attestor refuses with HTTP 409 when
384
+ * it no longer matches, which this method surfaces as
385
+ * {@link SettingsConflictError} carrying the re-read document. It never
386
+ * retries: a silent retry is precisely how the other writer's change
387
+ * vanishes.
388
+ *
389
+ * The signature covers a DIGEST of the document rather than the document
390
+ * itself — the signed statement rides a header, so it has to stay short and
391
+ * ASCII. The digest and the body are produced from ONE serialization
392
+ * ({@link canonicalSettings}, spliced into the body verbatim below): hashing
393
+ * one string and sending another is how a correct signature turns into a
394
+ * phantom "signer mismatch". The server side has to match that: hash the
395
+ * RAW `settings` slice of the body it received (serde_json's `&RawValue`),
396
+ * never a re-serialization of the parsed value — which is also the form
397
+ * that keeps the blob opaque to it.
398
+ *
399
+ * Pass `onWarn` to run the advisory model check BEFORE signing — a model
400
+ * absent from the 0G router catalog is reported, never blocked (a framework
401
+ * built-in is legitimately absent, and the container is the real gate). Omit
402
+ * it and no catalog request is made at all.
403
+ */
404
+ setSettings(params: {
405
+ sealId: `0x${string}`;
406
+ settings: SettingsDoc;
407
+ /** The version {@link getSettings} returned before this edit; 0 for a
408
+ * first write. A mismatch is an HTTP 409 → {@link SettingsConflictError}. */
409
+ baseVersion: number;
410
+ onWarn?: (warning: string) => void;
411
+ }): Promise<{
412
+ version: number;
413
+ }>;
414
+ /**
415
+ * Soft-retry a stuck deployment (owner-signed) instead of redeploying —
416
+ * which would orphan an already-minted identity. The attestor re-runs every
417
+ * failed idempotent stage (storage upload from persisted ciphertext, mint
418
+ * receipt re-fetch, setAgentURI, …) against the SAME seal_id.
419
+ *
420
+ * Without `apiKey`: posts `{ seal_id, owner }` — idempotent stages only, no
421
+ * container work (the cheap owner-field auth path). With `apiKey` or
422
+ * `sealedSecretEnv` (and optionally `sealedImage`): attaches the same
423
+ * owner-signed "create" envelope reset uses (the key sealed to the agent when the attestor
424
+ * supports it, see `secretEnv`), so the worker may continue past the
425
+ * idempotent stages into container creation. The attestor keeps no copy of
426
+ * the key outside that job, so — as with reset — continuing into a
427
+ * container needs it re-supplied.
428
+ */
429
+ retry(params: {
430
+ sealId: `0x${string}`;
431
+ /** Framework name — resolves the sealed image from /config's frameworks[]
432
+ * (same as deploy) when `sealedImage` isn't given. */
433
+ framework?: string;
434
+ sealedImage?: string;
435
+ apiKey?: string;
436
+ provider?: string;
437
+ /** In place of `apiKey`: the key already sealed to this agent; see
438
+ * {@link lifecycle}'s `sealedSecretEnv`. */
439
+ sealedSecretEnv?: string;
440
+ /** How `apiKey` travels; see {@link SecretEnvMode}. Default `'auto'`. */
441
+ secretEnv?: SecretEnvMode;
442
+ envelopeTtlSec?: number;
443
+ }): Promise<void>;
444
+ /**
445
+ * Deploy a new agent. The connected wallet is the owner. Returns the new
446
+ * agent's identity; it drives storage → mint → setAgentURI and (given the
447
+ * sandbox envelope) brings a container online.
448
+ */
449
+ deploy(params: DeployParams): Promise<DeployCloneResponse>;
450
+ /**
451
+ * Clone `sourceAgentId` to `targetOwner`. Lands Offline for the target owner.
452
+ *
453
+ * Owner mode (default): the connected wallet must be the current on-chain
454
+ * owner of the source. Contract mode (`authorization`): the connected
455
+ * wallet is the BUYER — it signs a `AgenticID.CloneContract.v1` intent, and
456
+ * the source owner's on-chain authorizer decides. The intent signature is
457
+ * transported by the marketplace backend verbatim (relayer can submit, not
458
+ * alter).
459
+ */
460
+ /** CloneGate address, required for contract-mode clones. */
461
+ private cloneGateAddr;
462
+ clone(params: CloneParams): Promise<DeployCloneResponse>;
463
+ private post;
464
+ }
465
+ //# sourceMappingURL=AttestorClient.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"AttestorClient.d.ts","sourceRoot":"","sources":["../src/AttestorClient.ts"],"names":[],"mappings":"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"}