@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,823 @@
1
+ import { type InferenceProvider } from './Providers';
2
+ /**
3
+ * @file AgenticID.ts
4
+ * @description The single entry point. Construct once with rpc + addresses (+
5
+ * attestorUrl + signer), then use the agent/reputation namespaces and admin operations:
6
+ * - `agent` — lifecycle (deploy / clone / transfer), reads, agent-seal gas top-up
7
+ * - `reputation` — serve-proof capture/verify + on-chain feedback
8
+ * - `admin` — attestor-wide provider publication, authorized by its Tapp owner
9
+ *
10
+ * plus top-level ops that don't belong to a single agent: `ack` / `ackStatus`
11
+ * (acknowledge the TEE trust-root component set) and `deposit` / `getBalance`
12
+ * (prepaid sandbox balance).
13
+ *
14
+ * Backends (AgenticID / Reputation / TappRegistry / SandboxServing contracts +
15
+ * attestor HTTP) are hidden behind the facade.
16
+ *
17
+ * @example
18
+ * ```typescript
19
+ * import { AgentDNA } from '@0gfoundation/0g-agentdna';
20
+ * const ag = new AgentDNA({ addresses, account }); // addresses from DEPLOYMENT.md §6 / your config
21
+ * await ag.agent.transferFrom(from, to, 33n);
22
+ * const { proof } = await ag.reputation.capture(() => fetch(`${url}/chat`, ...));
23
+ * await ag.ack();
24
+ * ```
25
+ */
26
+ import type { Address, Hash, TransactionReceipt, WriteContractReturnType } from 'viem';
27
+ import { type IntelligentDataResult } from './AgenticIDClient';
28
+ import { AttestorClient, type CloneParams, type DeployParams } from './AttestorClient';
29
+ import { type SettingsDoc } from './Settings';
30
+ import type { SecretEnvMode } from './secretEnv';
31
+ import { type TaskExchange } from './ServeSession';
32
+ import { type AgenticIDConfig, type Ctx } from './context';
33
+ import { type AgentClient, type AgentServiceEntry, type AgentRoute } from './AgentClient';
34
+ import type { ServeProof, GiveFeedbackParams, GiveFeedbackResult, AppendResponseParams, ReadAllFeedbackParams, GetSummaryParams, Feedback, FeedbackSummary, ServeData, TaskReveal } from './types';
35
+ /** waitForMint tuning shared by the deploy/clone `wait` option. */
36
+ type WaitMintOpts = {
37
+ timeoutMs?: number;
38
+ pollIntervalMs?: number;
39
+ preflight?: boolean;
40
+ };
41
+ /** 0.1 OG — the sandbox-balance floor deploys are gated on (attestor + console use the same). */
42
+ export declare const MIN_SANDBOX_BALANCE_WEI: bigint;
43
+ /**
44
+ * How long `deploy()` / `clone()` blocks before returning, in phase order:
45
+ * - omit → return on **acceptance** ({@link DeployAccepted});
46
+ * - `'minted'` → also block on the on-chain **mint** (adds `agentId`);
47
+ * - `'running'`→ also block on **provision** (adds the reachable `url`).
48
+ */
49
+ export type WaitLevel = 'minted' | 'running';
50
+ /**
51
+ * Facade-normalized deploy/clone acceptance — camelCase like every other
52
+ * SDK return (the attestor's wire JSON speaks snake_case; the mapping
53
+ * happens here so callers never see mixed casing).
54
+ */
55
+ export interface DeployAccepted {
56
+ sealId: Hash;
57
+ agentSealAddr: Address;
58
+ }
59
+ /** deploy/clone result once the background mint is awaited (`wait: 'minted'`). */
60
+ type MintedResponse = DeployAccepted & {
61
+ agentId: bigint;
62
+ };
63
+ /** deploy/clone result once the container is up (`wait: 'running'`) — adds the
64
+ * reachable base url, which `wait: 'minted'` (mint-only) does not have yet. */
65
+ type RunningResponse = MintedResponse & {
66
+ url: string;
67
+ };
68
+ /** Agent lifecycle (deploy / clone / transfer) + reads. Seal-bound today; the
69
+ * seal branch is reserved for non-seal agents. */
70
+ export declare class AgentApi {
71
+ private readonly id;
72
+ private readonly attestor;
73
+ private readonly infra;
74
+ private readonly ctx;
75
+ constructor(ctx: Ctx, initialConfig?: import('./context').AttestorPublicConfig);
76
+ /**
77
+ * Deploy/clone preflight: fail HERE, synchronously and with the fix
78
+ * named, instead of the request being accepted and dying minutes later
79
+ * as an async worker 402 with no context. Each check self-disables when
80
+ * its surface isn't configured (zero address / unknown provider), and
81
+ * read errors fail open — the attestor re-checks at accept anyway.
82
+ * Opt out per call with `{ preflight: false }`.
83
+ */
84
+ private preflightOwnerReady;
85
+ /**
86
+ * A wallet carrying an EIP-7702 delegation is code-bearing, so every
87
+ * safeMint/safeTransfer to it PROBES `onERC721Received` — a delegate that
88
+ * doesn't answer (the pre-v4 FeedbackBatcher, or any third-party delegate)
89
+ * makes the mint revert `ERC721InvalidReceiver` minutes later in the
90
+ * worker, gas spent, with no in-CLI way back. Probe HERE, name the fix.
91
+ * (feedback.md F13)
92
+ */
93
+ private preflightCanReceiveNfts;
94
+ /**
95
+ * Deploy a new agent. Async: returns `{ sealId, agentSealAddr }` once the
96
+ * attestor accepts the job. Pass `wait: 'minted'` to also block on the
97
+ * background mint (adds `agentId`) or `wait: 'running'` to also block on
98
+ * provision (adds the reachable `url`). See {@link WaitLevel}.
99
+ */
100
+ deploy(params: DeployParams, opts: {
101
+ wait: 'running';
102
+ } & WaitMintOpts): Promise<RunningResponse>;
103
+ deploy(params: DeployParams, opts: {
104
+ wait: 'minted';
105
+ } & WaitMintOpts): Promise<MintedResponse>;
106
+ deploy(params: DeployParams, opts?: {
107
+ wait?: undefined;
108
+ } & WaitMintOpts): Promise<DeployAccepted>;
109
+ /**
110
+ * Clone `sourceAgentId` to a new owner. Async like {@link deploy}: returns
111
+ * `{ sealId, agentSealAddr }` on acceptance; `wait: 'minted'` also blocks on
112
+ * the mint (adds `agentId`), `wait: 'running'` also blocks on provision.
113
+ *
114
+ * Two modes (issue #133): omit `authorization` for owner mode (the
115
+ * connected wallet must be the source's current owner); pass
116
+ * `authorization: { authData }` for contract mode — the marketplace fork
117
+ * flow, where the connected wallet IS the buyer and the source owner's
118
+ * on-chain `ICloneAuthorizer` (see {@link setCloneAuthorizer}) decides.
119
+ */
120
+ clone(params: CloneParams, opts: {
121
+ wait: 'running';
122
+ } & WaitMintOpts): Promise<RunningResponse>;
123
+ clone(params: CloneParams, opts: {
124
+ wait: 'minted';
125
+ } & WaitMintOpts): Promise<MintedResponse>;
126
+ clone(params: CloneParams, opts?: {
127
+ wait?: undefined;
128
+ } & WaitMintOpts): Promise<DeployAccepted>;
129
+ /**
130
+ * Configure (or clear, with the zero address) a token's clone authorizer —
131
+ * the `ICloneAuthorizer` contract deciding which contract-mode clones may
132
+ * mint. The publisher's one-time opt-in to marketplace forks; owner-only.
133
+ * Cleared automatically when the token changes owner.
134
+ */
135
+ setCloneAuthorizer(tokenId: bigint, authorizer: Address): Promise<WriteContractReturnType>;
136
+ /** The configured clone authorizer (`0x0` = none → contract-mode clones fail closed). */
137
+ cloneAuthorizerOf(tokenId: bigint): Promise<Address>;
138
+ /** For a clone, the agentId it was forked from (0n = not a clone; survives transfers). */
139
+ cloneSourceOf(agentId: bigint): Promise<bigint>;
140
+ /** Seller: allow `buyer` to fork this agent — a permission switch (standard policy only). */
141
+ grantClone(sourceAgentId: bigint, buyer: Address): Promise<WriteContractReturnType>;
142
+ /** Seller: close the door for `buyer` — refund or manual one-shot consumption (standard policy only). */
143
+ revokeClone(sourceAgentId: bigint, buyer: Address): Promise<WriteContractReturnType>;
144
+ /** A grant's seller + whether it is currently effective (standard policy only). */
145
+ cloneGrantOf(sourceAgentId: bigint, buyer: Address): Promise<{
146
+ grantor: Address;
147
+ effective: boolean;
148
+ }>;
149
+ transferFrom(from: Address, to: Address, tokenId: bigint): Promise<WriteContractReturnType>;
150
+ safeTransferFrom(from: Address, to: Address, tokenId: bigint, data?: `0x${string}`): Promise<WriteContractReturnType>;
151
+ /** Send native gas to an agent's agentSeal so it can self-fund on-chain writes. */
152
+ topUpAgentSeal(agentSeal: Address, amountWei: bigint): Promise<`0x${string}`>;
153
+ /**
154
+ * What this agent costs to keep running, from on-chain data alone:
155
+ * the owner's prepaid balance, the provider's price schedule, the
156
+ * agent's evolution-gas balance, and the runway those imply. `spec`
157
+ * defaults to the standard sealed container (2 CPU / 4 GB) — pass the
158
+ * actual shape if yours differs. Per-agent metered spend needs
159
+ * provider-side usage records and is not available on chain yet.
160
+ */
161
+ /**
162
+ * What WOULD an agent cost — no agent needed (pre-deploy planning).
163
+ * Provider pricing + cost/min for the spec (default 2C/4GB), plus the
164
+ * caller's prepaid balance and implied runway when an account is set.
165
+ */
166
+ estimateCosts(spec?: {
167
+ cpu?: number;
168
+ memGb?: number;
169
+ }): Promise<{
170
+ prepaidBalanceWei: bigint | null;
171
+ pricing: {
172
+ pricePerCPUPerMin: bigint;
173
+ pricePerMemGBPerMin: bigint;
174
+ createFee: bigint;
175
+ };
176
+ costPerMinWei: bigint;
177
+ estimatedRunwayMinutes: number | null;
178
+ }>;
179
+ /** estimateCosts() plus the given agent's evolution-gas balance. */
180
+ runtimeCosts(agentId: bigint, spec?: {
181
+ cpu?: number;
182
+ memGb?: number;
183
+ }): Promise<{
184
+ prepaidBalanceWei: bigint | null;
185
+ sealGasWei: bigint;
186
+ pricing: {
187
+ pricePerCPUPerMin: bigint;
188
+ pricePerMemGBPerMin: bigint;
189
+ createFee: bigint;
190
+ };
191
+ costPerMinWei: bigint;
192
+ estimatedRunwayMinutes: number | null;
193
+ }>;
194
+ /**
195
+ * Model catalog of the 0g-compute router (the `provider: '0g-compute'`
196
+ * inference path). Public endpoint, no key needed — use it to populate
197
+ * a model picker before deploy.
198
+ */
199
+ listProviders(): InferenceProvider[];
200
+ refreshProviders(): Promise<InferenceProvider[]>;
201
+ getProviderRegistry(): Promise<import("./Providers").ProviderRegistrySnapshot>;
202
+ assertProviderSupported(provider: string, options?: {
203
+ sealId?: Hash;
204
+ framework?: string;
205
+ sealedImage?: string;
206
+ }): Promise<void>;
207
+ listModels(opts?: {
208
+ provider?: string;
209
+ }): Promise<string[]>;
210
+ listModelCaps(opts?: {
211
+ provider?: string;
212
+ }): Promise<Array<{
213
+ id: string;
214
+ chat: boolean;
215
+ tools: boolean;
216
+ formats: string[];
217
+ }>>;
218
+ /**
219
+ * Get an {@link AgentClient} for a running agent — one handle for every
220
+ * caller, one argument: an `agentId` OR an `agentUrl` (whichever you have).
221
+ * The SDK fills in the other half:
222
+ * - `agentId` → on-chain `tokenURI` → the AgentCard's serve URL;
223
+ * - `agentUrl` → the agent's **signed** `/hello`, whose `X-Agent-Proof`
224
+ * envelope carries the numeric agentId (so a URL alone is enough).
225
+ *
226
+ * Whether it can do owner ops is inherited from THIS `ag`, exactly like
227
+ * {@link AgenticID}'s account gates chain writes: an `ag` with an owner key
228
+ * gets `chat`/`chatStream` (the owner token is minted on first use and
229
+ * re-minted on rotation, e.g. after a `reset` — you never pass or refresh a
230
+ * token); a read-only `ag` gets a public client (`fetch`/`fetchWithProof`
231
+ * against `/api/*`). Being the ACTUAL owner is verified only when an owner op
232
+ * runs (chat throws for a non-owner); `/hello` and `/api/*` work regardless.
233
+ *
234
+ * With an `agentUrl`, the agentId comes from `/hello`'s proof envelope — which
235
+ * is absent when the runtime signs nothing (no `VERIFIED_FEEDBACK_ADDR`).
236
+ * Callers that already know the id pass it as `opts.agentId`: it is used when
237
+ * `/hello` carries no proof, must equal the envelope's id when it does, and
238
+ * is bound to the URL on chain like a discovered id. An `ag` with a key that
239
+ * still ends up with no agentId gets a public handle and a console warning —
240
+ * never a silent downgrade.
241
+ */
242
+ client(idOrUrl: bigint | string, opts?: {
243
+ instanceId?: string;
244
+ agentId?: bigint;
245
+ }): Promise<AgentClient>;
246
+ /**
247
+ * Owner handshake, eager: like {@link client} on an `ag` with a key, but
248
+ * mints the token up front so a non-owner fails HERE, not at first chat.
249
+ * Kept for that fail-fast semantics and back-compat; requires a wallet.
250
+ *
251
+ * With an `agentUrl`, `opts.agentId` works as in {@link client}: used when
252
+ * `/hello` carries no proof (runtime without `VERIFIED_FEEDBACK_ADDR`),
253
+ * must equal the envelope's id when it does, and is bound to the URL on
254
+ * chain before anything is signed.
255
+ */
256
+ authenticate(idOrUrl: bigint | string, opts?: {
257
+ agentId?: bigint;
258
+ }): Promise<AgentClient>;
259
+ /**
260
+ * Explicit public handle — never attaches a token even if this `ag` holds a
261
+ * key. For a third party calling the agent's `/api/*` services and capturing
262
+ * the serve-proof (`client.fetchWithProof('/api/…')` → `{ response, proof }`).
263
+ */
264
+ connect(idOrUrl: bigint | string): Promise<AgentClient>;
265
+ /**
266
+ * Sign an owner control message `<tag>:<sealId>:<ts>:<audience>` (EIP-191).
267
+ * `audience` is the agent's serve base — issue #62 binds the signature to the
268
+ * endpoint it's meant for, so it can't be relayed to a different agent that
269
+ * happens to share the owner. Shared by {@link mintToken} (tag `0GSealAuth`)
270
+ * and the `/log/agent` reader (tag `0GSealLog`).
271
+ */
272
+ private signOwner;
273
+ /**
274
+ * Push a settings document into a RUNNING container, so a change takes
275
+ * effect without rebuilding it.
276
+ *
277
+ * This is the second half of a settings write and it is deliberately
278
+ * separate from the first. {@link AttestorClient.setSettings} stores the
279
+ * document — that is the authoritative act, and it is what a future boot
280
+ * reads. This call only makes the change visible NOW. If it fails, the
281
+ * document is still stored and the next boot picks it up, which is why the
282
+ * caller treats a failure here as a warning rather than an error.
283
+ *
284
+ * The signed message carries a field the other owner tags do not: the
285
+ * sha256 of the body, placed before the audience (see the comment on the
286
+ * message below for why the order is forced). Without it the signature attests only to who is
287
+ * calling, and anything able to alter the request in flight could keep a
288
+ * valid signature while substituting a different document — harmless on the
289
+ * read-only routes the tag scheme started with, not harmless on one that
290
+ * accepts a payload.
291
+ *
292
+ * Applying it restarts the framework process, so whatever the agent was
293
+ * doing is interrupted. The container says so in its response and callers
294
+ * should pass that on rather than reporting a silent success.
295
+ */
296
+ pushSettingsToContainer(base: string, agentId: bigint, doc: unknown): Promise<{
297
+ note?: string;
298
+ }>;
299
+ /**
300
+ * Take the agent's single-driver seat, WeChat-style: the claim always wins
301
+ * and whoever held the seat learns via 409 the next time they speak. Call it
302
+ * on entering a session; re-entering after being displaced claims the seat
303
+ * back. Owner-signed with the body digest bound in (tag `0GSealClaim`).
304
+ *
305
+ * Best-effort by contract: a container from before the seat existed 404s —
306
+ * callers should treat any failure as "no occupancy on this agent".
307
+ */
308
+ claimAgent(base: string, agentId: bigint, instanceId: string): Promise<{
309
+ displaced?: boolean;
310
+ }>;
311
+ /**
312
+ * Wipe the agent's ONE persisted conversation and restart its framework so
313
+ * a fresh one is presented immediately. Clears WORKING CONTEXT only — the
314
+ * chain-tracked memory (what the agent chose to keep) is untouched; that is
315
+ * the difference between /clear and a container reset. Owner-signed (tag
316
+ * `0GSealClear`, the settings-push grammar); a framework whose history is
317
+ * client-held answers 501 — there is nothing server-side to clear. Pass
318
+ * `instanceId` when the caller participates in the single-driver seat: a
319
+ * clear is a driving action and is refused (409) from a displaced window.
320
+ */
321
+ clearConversation(base: string, agentId: bigint, instanceId?: string): Promise<{
322
+ note?: string;
323
+ }>;
324
+ /**
325
+ * Compact the agent's ONE persisted conversation in place: the framework's
326
+ * own compaction replaces the older history with a summary and keeps the
327
+ * newest part verbatim (how much is the framework's: openclaw ~20K tokens,
328
+ * dsh only its newest item), so later requests carry less of it while the
329
+ * conversation goes on — the middle ground between doing nothing and
330
+ * {@link clearConversation}. No restart. The summary takes one or more
331
+ * model calls, so this can take minutes — longer than Node's fetch waits
332
+ * for an answer (300s). A connection dropped or timed out meanwhile does not
333
+ * abort it; the outcome is in the runtime log. Nothing to compact —
334
+ * including nothing said since the last compaction — is a 200 whose note
335
+ * says so. Owner-signed (tag `0GSealCompact`, the clear grammar). A
336
+ * framework, or a framework version, that cannot compact on demand answers
337
+ * 501: openclaw before 2026.7.1 has no `sessions compact` CLI command, which
338
+ * the adapter drives. A second compaction while one runs, a replayed
339
+ * signature, or a framework declining for now (busy) answers 409. Pass
340
+ * `instanceId` when the caller participates in the single-driver seat:
341
+ * compaction is a driving action and is refused (409) from a displaced
342
+ * window.
343
+ */
344
+ compactConversation(base: string, agentId: bigint, instanceId?: string): Promise<{
345
+ note?: string;
346
+ }>;
347
+ /** Sign `0GSealAuth` (audience-bound) and exchange it at `{base}/_seal/auth` for a token. */
348
+ private mintToken;
349
+ /**
350
+ * #62 defense-in-depth: verify a URL-derived agentId actually belongs to the
351
+ * URL we're talking to. Resolves the agent's canonical serve origin from chain
352
+ * (`tokenURI` → AgentCard `url`) and compares to `base`'s origin. A phishing
353
+ * endpoint whose `/hello` claims someone else's agentId is rejected here,
354
+ * before we sign anything for it. (The audience-bound signature also makes the
355
+ * real agent reject a relayed signature server-side — this just fails fast
356
+ * with a clear reason.)
357
+ */
358
+ private assertAgentIdBoundToUrl;
359
+ /** Resolve the serve base URL: a bigint agentId via on-chain tokenURI; a string URL as-is. */
360
+ private resolveBase;
361
+ /** Whether this `ag` holds a signer — so the clients it builds can do owner ops. */
362
+ private hasAccount;
363
+ /**
364
+ * Resolve an agent's live serve base URL from its on-chain identity — no
365
+ * attestor. Reads `tokenURI(agentId)` (the canonical AgentCard pointer on 0G
366
+ * storage), fetches the card, and returns the origin of its `url` (the serve
367
+ * endpoint, refreshed on storage as the container is (re)created). Throws if
368
+ * the agent isn't provisioned yet (no URI, or a card with no url).
369
+ */
370
+ private resolveAgentUrl;
371
+ /**
372
+ * Read the agent's signed `/hello` to learn its declared surface AND its
373
+ * numeric agentId — the latter from the response's `X-Agent-Proof` envelope,
374
+ * so a caller who has only the URL still gets the id needed to authenticate.
375
+ * Absent on pre-route / unprovisioned builds → empty surface + undefined id
376
+ * (fetch/fetchWithProof still work; owner ops just aren't offered).
377
+ */
378
+ private discoverSurface;
379
+ /**
380
+ * Greet a running agent and verify it in one call: GET {agentUrl}/hello,
381
+ * capture the X-Agent-Proof header, and check the proof against chain
382
+ * (signer == on-chain agentSeal, deadline, declared data hashes all on
383
+ * chain — via {@link ServeSession}). Returns the agent's self-report
384
+ * plus a structured verification. The whole "is this agent who it
385
+ * claims, running what chain says" check, without hand-rolling the
386
+ * fetch + parse + verify.
387
+ *
388
+ * The proof signature is bound to the VerifiedFeedbackRegistry, so the
389
+ * check needs `addresses.verifiedFeedback` (fromAttestor fills it from
390
+ * /config). Without it `verification.signerMatches` is false with the
391
+ * reason 'no VerifiedFeedbackRegistry configured — cannot verify
392
+ * serve-proof'.
393
+ */
394
+ sayHi(agentUrl: string): Promise<{
395
+ hello: {
396
+ agent: Address;
397
+ owner: Address;
398
+ public_url: string;
399
+ message: string;
400
+ services: AgentServiceEntry[];
401
+ routes: AgentRoute[];
402
+ };
403
+ proof: ServeProof | null;
404
+ verification: import('./ServeSession').ProofVerification | null;
405
+ }>;
406
+ private attestorBase;
407
+ /**
408
+ * Normalized view of the attestor's /deployments listing. The raw rows
409
+ * speak hex ("agent_id": "0x77") and snake_case; this returns bigint
410
+ * agentIds and camelCase so they compose with every other SDK call.
411
+ *
412
+ * `url` is the agent's public base URL (feed it to sayHi/authenticate/
413
+ * the /v1 chat API) — null until the container is provisioned.
414
+ * `lastProvisionError` is WHY a deployment is stuck (e.g. "image_hash
415
+ * not in validFrameworkHashes") — always check it before debugging a
416
+ * deployment that never reaches `running`. It is non-null only when the
417
+ * row is currently failed (any pipeline stage) or offline due to a
418
+ * genuine container failure; recovered rows report null.
419
+ *
420
+ * When `phase` is `"failed"`, try {@link AgentApi.retry} FIRST — it resumes
421
+ * the failed stages on the same identity. Redeploying instead orphans the
422
+ * already-minted agent; reset only helps once the container stage is
423
+ * reached.
424
+ *
425
+ * This is the PUBLIC listing: the attestor returns only non-sensitive fields
426
+ * for an unauthenticated GET (issue #64), so `sandboxId` and
427
+ * `lastProvisionError` come back **null** here. No tier carries the owner's
428
+ * settings document — read it with {@link AgentApi.getSettings}, which is
429
+ * owner-signed. `agentId`/`sealId`/`phase`/`url`/`name` are still
430
+ * present, and `owner` and `agentSeal` appear for MINTED rows (both
431
+ * chain-public once the agent exists — ownerOf /
432
+ * getAgentSeal; unminted rows keep them withheld). `agentSeal` is the
433
+ * agent's on-chain signing address: matching it against another row's
434
+ * `owner` is how client code spots agent-owned agents (delegation
435
+ * hierarchies, self-funded runs).
436
+ * Use {@link AgentApi.listMyDeployments} — owner-signed — to get the withheld
437
+ * fields for your own agents.
438
+ */
439
+ listDeployments(): Promise<Array<{
440
+ agentId: bigint | null;
441
+ sealId: Hash;
442
+ phase: string;
443
+ framework: string | null;
444
+ sandboxId: string | null;
445
+ url: string | null;
446
+ owner: Address | null;
447
+ name: string | null;
448
+ agentSeal: Address | null;
449
+ createdAt: string | null;
450
+ lastProvisionError: string | null;
451
+ }>>;
452
+ /**
453
+ * Owner-scoped, authenticated listing — your own agents WITH the fields the
454
+ * public {@link AgentApi.listDeployments} withholds (`sandboxId`,
455
+ * `lastProvisionError`, stages). Signs `0GDeployments:<owner>:<ts>` with
456
+ * `ctx.account` and sends it as `X-Auth-Message`/`X-Auth-Signature`; the
457
+ * attestor verifies the signer controls `<owner>` before returning its rows.
458
+ * Requires a wallet. This is how you get a container's `sandboxId` for
459
+ * {@link AgentApi.stop}/{@link AgentApi.start}.
460
+ */
461
+ listMyDeployments(): Promise<Awaited<ReturnType<AgentApi['listDeployments']>>>;
462
+ /** Map one raw attestor deployment row to the normalized SDK shape. Shared
463
+ * by the public {@link AgentApi.listDeployments} and the owner-scoped
464
+ * {@link AgentApi.listMyDeployments}; whatever the tier omits simply
465
+ * comes through as null — public tier: owner/agentSeal only on minted
466
+ * rows (agentSeal only from attestors carrying the field),
467
+ * sandboxId/lastProvisionError never; owner tier: everything present
468
+ * for your own rows, including unminted ones. */
469
+ private normalizeDeploymentRow;
470
+ /** Stop a running agent's sandbox (owner-signed). Identity is preserved. */
471
+ stop(sealId: Hash, sandboxId: string): Promise<void>;
472
+ /**
473
+ * Bring an agent's container online (owner-signed). Two shapes:
474
+ * - `start(sealId, sandboxId)` — resume a STOPPED container.
475
+ * - `start(sealId, { apiKey, sealedImage? })` — FIRST provision of a
476
+ * mint-only / never-provisioned agent (no sandbox yet): spins a fresh
477
+ * container. `apiKey` is required in practice (the fresh container needs
478
+ * the LLM key). The semantic counterpart to a sandbox-less `deploy` —
479
+ * use this, not `reset` (which means "recreate an existing container").
480
+ * The key is sealed to the agent when the attestor supports it, so the
481
+ * wallet prompt shows ciphertext, not the key (`secretEnv`, default
482
+ * `'auto'`; `'sealed'` refuses to send it in clear). When a server
483
+ * supplies the key, pass its {@link sealApiKey} output as
484
+ * `sealedSecretEnv` instead of `apiKey`, so the key never reaches the
485
+ * signer at all.
486
+ */
487
+ start(sealId: Hash, sandboxId: string): Promise<void>;
488
+ start(sealId: Hash, opts?: {
489
+ provider?: string;
490
+ framework?: string;
491
+ sealedImage?: string;
492
+ apiKey?: string;
493
+ sealedSecretEnv?: string;
494
+ secretEnv?: SecretEnvMode;
495
+ }): Promise<void>;
496
+ /**
497
+ * Reset (recreate) an agent's container, preserving its on-chain
498
+ * identity — a fresh boot that re-reads iData from chain and reselects
499
+ * the framework adapter from the binding. Owner-signed. `apiKey` is
500
+ * required in practice: without it the agent boots but cannot call
501
+ * its model. When the attestor advertises `secret_env_scheme`, the
502
+ * SDK seals the key to the agent's agentSeal key (only the TEE opens
503
+ * it) and the owner signs that ciphertext; otherwise it rides the
504
+ * signed envelope in clear (`secretEnv`, default `'auto'`; `'sealed'`
505
+ * refuses the clear path). The attestor keeps no reusable copy, which
506
+ * is WHY it must be passed again on every recreate.
507
+ */
508
+ reset(sealId: Hash, opts?: {
509
+ provider?: string;
510
+ framework?: string;
511
+ sealedImage?: string;
512
+ apiKey?: string;
513
+ sealedSecretEnv?: string;
514
+ secretEnv?: SecretEnvMode;
515
+ }): Promise<void>;
516
+ /**
517
+ * The agent's current settings document — which model it thinks with, and
518
+ * how hard — with the version to write it back against. `settings: null`
519
+ * means it has never been configured; `version: 0` then, which is exactly
520
+ * the `baseVersion` a first write takes.
521
+ *
522
+ * OWNER-SIGNED: the document is the owner's, not public, so this needs a
523
+ * wallet and the attestor checks it against the LIVE on-chain owner. It is
524
+ * not carried on {@link listDeployments} rows or anywhere else.
525
+ *
526
+ * Configuration deliberately does NOT live on chain: it is re-suppliable
527
+ * (an owner re-picks a model in ten seconds), where the agent's memory is
528
+ * not. The attestor holds this blob opaquely and hands it to the container
529
+ * on every boot.
530
+ */
531
+ getSettings(sealId: Hash): Promise<{
532
+ settings: SettingsDoc | null;
533
+ version: number;
534
+ }>;
535
+ /**
536
+ * Replace the agent's settings document (owner-signed; the attestor
537
+ * verifies the signer against the LIVE on-chain owner). Returns the new
538
+ * version.
539
+ *
540
+ * WHOLE-DOCUMENT, COMPARE-AND-SWAP write — what you pass becomes the
541
+ * document, and `baseVersion` is the version you read before editing:
542
+ *
543
+ * ```typescript
544
+ * const { settings, version } = await ag.agent.getSettings(sealId);
545
+ * await ag.agent.setSettings(
546
+ * sealId,
547
+ * { ...(settings ?? {}), model: '0gm-1.0-35b-a3b' },
548
+ * { baseVersion: version },
549
+ * );
550
+ * ```
551
+ *
552
+ * If the stored version has moved on — another client, another device — the
553
+ * write is refused with {@link SettingsConflictError}, which carries the
554
+ * document that is actually there. Show it and let a human decide; do not
555
+ * loop on it, or the other writer's change is what disappears.
556
+ *
557
+ * The container applies it on its next boot and reports back, which
558
+ * promotes it to last-known-good; a container that keeps coming back
559
+ * without ever confirming one is handed the last document a boot did
560
+ * confirm, so a document that prevents boot costs a boot, not the agent.
561
+ *
562
+ * Pass `onWarn` for the advisory model check before signing (a model
563
+ * missing from the 0G router catalog is reported, never blocked).
564
+ */
565
+ setSettings(sealId: Hash, settings: SettingsDoc, opts: {
566
+ baseVersion: number;
567
+ onWarn?: (warning: string) => void;
568
+ }): Promise<{
569
+ version: number;
570
+ }>;
571
+ /**
572
+ * Seal an inference key to one agent WITHOUT signing anything — for the
573
+ * integrator whose server supplies the key while the agent's owner signs
574
+ * in a browser. The server calls this (a read-only client is enough: no
575
+ * wallet), hands the browser only the returned ciphertext, and the browser
576
+ * calls `start` / `reset` / `retry` with `{ sealedSecretEnv }`. The key
577
+ * never reaches the browser, and the wallet prompt shows only ciphertext.
578
+ *
579
+ * `owner` must be the address that will sign; the agent's container
580
+ * applies the secret only while that address owns the agent on chain.
581
+ * Requires the attestor to advertise `secret_env_scheme`. Refusals throw
582
+ * {@link SecretEnvRefusedError}.
583
+ */
584
+ sealApiKey(sealId: Hash, opts: {
585
+ owner: Address;
586
+ apiKey: string;
587
+ provider?: string;
588
+ framework?: string;
589
+ sealedImage?: string;
590
+ }): Promise<string>;
591
+ /**
592
+ * Soft-retry a stuck deployment (owner-signed), preserving its identity.
593
+ * This is the FIRST recovery step for a `phase: "failed"` row (see
594
+ * {@link listDeployments}) — it re-runs the failed idempotent stages
595
+ * (storage upload, mint re-fetch, setAgentURI, …) against the same sealId,
596
+ * where redeploying would orphan an already-minted agent.
597
+ *
598
+ * Without opts it does idempotent stages only. Pass `apiKey` (and
599
+ * optionally `sealedImage`) to let it continue past those into container
600
+ * creation — like {@link reset}, the LLM key must be re-supplied (and is
601
+ * sealed the same way, see `secretEnv`).
602
+ */
603
+ retry(sealId: Hash, opts?: {
604
+ provider?: string;
605
+ framework?: string;
606
+ sealedImage?: string;
607
+ apiKey?: string;
608
+ sealedSecretEnv?: string;
609
+ secretEnv?: SecretEnvMode;
610
+ }): Promise<void>;
611
+ /**
612
+ * Wait for a deploy OR clone to mint on-chain, returning the new agent's
613
+ * tokenId (agentId). Both are async and return only a `seal_id` up front — the
614
+ * tokenId doesn't exist until the background mint. This polls
615
+ * `getAgentIdBySealId(sealId)` (0 until minted), no WebSocket. Throws on
616
+ * `phase: "failed"` — surfacing the owner-scoped failure reason so a pre-mint
617
+ * failure (e.g. the storage stage) reports why instead of a blank timeout —
618
+ * or on timeout.
619
+ *
620
+ * @example
621
+ * const cl = await ag.agent.clone({ sourceAgentId, targetOwner });
622
+ * const tokenId = await ag.agent.waitForMint(cl.seal_id); // → 34n once minted
623
+ */
624
+ waitForMint(sealId: Hash, opts?: {
625
+ timeoutMs?: number;
626
+ pollIntervalMs?: number;
627
+ }): Promise<bigint>;
628
+ /**
629
+ * Wait for a freshly-deployed/cloned agent's CONTAINER to come up, returning
630
+ * its agentId + reachable base url. {@link deploy}/{@link clone} with
631
+ * `wait: 'minted'` only block on the on-chain mint — the agentId exists but
632
+ * the container (and its url) is still 1–2 min out; `wait: 'running'`
633
+ * routes here to also block on provision. Polls {@link listDeployments};
634
+ * throws on `phase: "failed"` or timeout (default 300s, longer than mint
635
+ * because provision includes container start).
636
+ */
637
+ waitForRunning(sealId: Hash, opts?: {
638
+ timeoutMs?: number;
639
+ pollIntervalMs?: number;
640
+ }): Promise<{
641
+ agentId: bigint;
642
+ url: string;
643
+ }>;
644
+ getAgentSeal(agentId: bigint): Promise<Address>;
645
+ getSealId(agentId: bigint): Promise<Hash>;
646
+ getAgentIdBySealId(sealId: Hash): Promise<bigint>;
647
+ isSealIdBound(sealId: Hash): Promise<boolean>;
648
+ intelligentDatasOf(tokenId: bigint): Promise<IntelligentDataResult[]>;
649
+ sealedKeysOf(tokenId: bigint): Promise<`0x${string}`[]>;
650
+ ownerOf(tokenId: bigint): Promise<Address>;
651
+ balanceOf(owner: Address): Promise<bigint>;
652
+ waitForTransaction(txHash: Hash): Promise<TransactionReceipt>;
653
+ }
654
+ /** Reputation: serve-proof transport/verify + on-chain feedback. */
655
+ export declare class ReputationApi {
656
+ private readonly rep;
657
+ private readonly session;
658
+ constructor(ctx: Ctx);
659
+ capture(call: () => Promise<Response>): Promise<{
660
+ response: Response;
661
+ proof: ServeProof | null;
662
+ }>;
663
+ proofFromResponse(res: Response): ServeProof | null;
664
+ parseServeProofHeader(value: string): ServeProof;
665
+ /** Verify a serve-proof. Without `opts.task`: signer attribution only.
666
+ * With a task (a TaskReveal, the TaskExchange a recorder returned, or
667
+ * null for "not recorded") the verdict additionally binds the proof to
668
+ * that exchange's bytes — see ServeSession.verifyProof. */
669
+ verifyProof(proof: ServeProof, opts?: {
670
+ task?: TaskReveal | TaskExchange | null;
671
+ }): Promise<import("./ServeSession").ProofVerification>;
672
+ giveFeedback(params: GiveFeedbackParams): Promise<GiveFeedbackResult>;
673
+ attestFeedback(agentId: bigint, feedbackIndex: bigint, proof: ServeProof): Promise<WriteContractReturnType>;
674
+ attestFeedbackWithTask(agentId: bigint, feedbackIndex: bigint, proof: ServeProof, task: TaskReveal): Promise<WriteContractReturnType>;
675
+ revokeFeedback(agentId: bigint, feedbackIndex: bigint): Promise<WriteContractReturnType>;
676
+ appendResponse(params: AppendResponseParams): Promise<WriteContractReturnType>;
677
+ readFeedback(agentId: bigint, client: Address, feedbackIndex: bigint): Promise<Feedback>;
678
+ readAllFeedback(params: ReadAllFeedbackParams): Promise<Feedback[]>;
679
+ getSummary(params: GetSummaryParams): Promise<FeedbackSummary>;
680
+ getClients(agentId: bigint): Promise<Address[]>;
681
+ getLastIndex(agentId: bigint, client: Address): Promise<bigint>;
682
+ getResponseCount(agentId: bigint, client: Address, feedbackIndex: bigint, responders: Address[]): Promise<bigint>;
683
+ isVerified(agentId: bigint, client: Address, feedbackIndex: bigint): Promise<boolean>;
684
+ getVerifiedIndexes(agentId: bigint, client: Address): Promise<bigint[]>;
685
+ getVerifiedClients(agentId: bigint): Promise<Address[]>;
686
+ getVerifiedSummary(params: GetSummaryParams): Promise<FeedbackSummary>;
687
+ getVerifiedEndpoint(agentId: bigint, client: Address, feedbackIndex: bigint): Promise<string>;
688
+ getVerifiedSummaryForEndpoint(agentId: bigint, uri: string, clients?: Address[]): Promise<FeedbackSummary>;
689
+ getServeData(agentId: bigint, client: Address, feedbackIndex: bigint): Promise<ServeData>;
690
+ waitForTransaction(txHash: Hash): Promise<TransactionReceipt>;
691
+ }
692
+ /** The AgenticID SDK entry point. */
693
+ /** Attestor-wide operations, authorized by its current Tapp owner. */
694
+ export declare class AdminApi {
695
+ private readonly attestor;
696
+ constructor(attestor: AttestorClient);
697
+ updateProviders(providers: InferenceProvider[], opts: {
698
+ baseVersion: number;
699
+ }): Promise<{
700
+ version: number;
701
+ }>;
702
+ prepareProviderUpdate(providers: InferenceProvider[], opts: {
703
+ baseVersion: number;
704
+ }): Promise<{
705
+ document: string;
706
+ message: string;
707
+ owner: Address;
708
+ }>;
709
+ publishSignedProviders(update: {
710
+ document: string;
711
+ signature: `0x${string}`;
712
+ }): Promise<{
713
+ version: number;
714
+ }>;
715
+ }
716
+ export declare class AgenticID {
717
+ readonly agent: AgentApi;
718
+ readonly admin: AdminApi;
719
+ readonly reputation: ReputationApi;
720
+ private readonly infra;
721
+ /** Long-lived so its instance caches (/config: provider address, sandbox
722
+ * endpoint) are paid once per session, not per call. */
723
+ private readonly attestor;
724
+ private readonly ctx;
725
+ constructor(config: AgenticIDConfig, initialConfig?: import('./context').AttestorPublicConfig);
726
+ /**
727
+ * Block until a top-level tx (ack/deposit) is mined. `ack()`/`deposit()`
728
+ * return the hash immediately, like any writeContract — reading state
729
+ * right after (ackStatus/getBalance) can race the still-pending tx and
730
+ * see the old value. `ag.agent`/`ag.reputation` have their own
731
+ * equivalents for txs made through those namespaces.
732
+ */
733
+ waitForTransaction(txHash: Hash): Promise<TransactionReceipt>;
734
+ /**
735
+ * Bootstrap a client from ONE URL: the attestor's GET /config is the
736
+ * environment's self-description (contract set, chain RPC, component
737
+ * appIds), so `attestorUrl` alone fully determines an environment —
738
+ * switching environments is switching URLs, with no hand-copied
739
+ * address set to go stale. Explicit `overrides` win over /config for
740
+ * callers who verify addresses out-of-band rather than trusting the
741
+ * attestor. Addresses absent from /config resolve to the zero address
742
+ * (their module reads as "not deployed here").
743
+ */
744
+ static fromAttestor(attestorUrl: string, opts?: Omit<AgenticIDConfig, 'addresses' | 'attestorUrl'> & {
745
+ overrides?: Partial<import('./constants').ContractAddresses>;
746
+ }): Promise<AgenticID>;
747
+ /** Acknowledge the TEE trust-root component set in one batched tx; null if already done. */
748
+ ack(): Promise<WriteContractReturnType | null>;
749
+ /** TappRegistry details for every trust-root component (code hashes, ackVersion, nodes) — the data ack() signs off on. */
750
+ components(user?: Address): Promise<{
751
+ appId: string;
752
+ acked: boolean | null;
753
+ ackVersion: bigint;
754
+ owner: Address;
755
+ registeredAt: bigint;
756
+ composeHash: `0x${string}`;
757
+ imageHashes: `0x${string}`[];
758
+ nodes: Address[];
759
+ }[]>;
760
+ /** Which configured components `user` (or the connected account) still needs to acknowledge. */
761
+ ackStatus(user?: Address): Promise<{
762
+ allAcked: boolean;
763
+ missing: string[];
764
+ }>;
765
+ /** Fund a prepaid sandbox balance (payable). Recipient defaults to the caller; provider to the attestor /config's. */
766
+ deposit(params: {
767
+ amountWei: bigint;
768
+ provider?: Address;
769
+ recipient?: Address;
770
+ }): Promise<WriteContractReturnType>;
771
+ /**
772
+ * Read a prepaid sandbox balance (wei). User defaults to the account;
773
+ * provider to the attestor /config's. Takes an options object like
774
+ * {@link deposit} (`getBalance({ user, provider })`); the positional form
775
+ * `getBalance(user, provider)` also works.
776
+ */
777
+ getBalance(opts?: {
778
+ user?: Address;
779
+ provider?: Address;
780
+ }): Promise<bigint>;
781
+ getBalance(user?: Address, provider?: Address): Promise<bigint>;
782
+ /**
783
+ * Full prepaid-account view: spendable `balance`, plus `pendingRefund` and
784
+ * `refundUnlockAt` (funds mid-refund and when they unlock — invisible to
785
+ * {@link getBalance}, which returns only the spendable part).
786
+ */
787
+ getBalanceDetail(opts?: {
788
+ user?: Address;
789
+ provider?: Address;
790
+ }): Promise<{
791
+ balance: bigint;
792
+ pendingRefund: bigint;
793
+ refundUnlockAt: bigint;
794
+ }>;
795
+ /** The caller wallet's NATIVE gas balance (wei) — the funds that pay tx
796
+ * fees AND back a deposit's principal. A prepaid top-up can't exceed it. */
797
+ nativeBalance(address?: Address): Promise<bigint>;
798
+ /**
799
+ * The EFFECTIVE spendable balance from the sandbox provider (owner-signed):
800
+ * on-chain balance minus in-flight reservations minus outstanding off-chain
801
+ * debt — the number the provider's create/start gates actually enforce.
802
+ * {@link getBalance} (raw chain read) can be optimistic between settlements.
803
+ * Needs a wallet and an attestor /config that advertises `sandbox_endpoint`.
804
+ */
805
+ getEffectiveBalance(): Promise<{
806
+ balanceWei: bigint;
807
+ reservedWei: bigint;
808
+ outstandingDebtWei: bigint;
809
+ pendingSettlementWei: bigint;
810
+ availableWei: bigint;
811
+ }>;
812
+ /** Start withdrawing prepaid funds: moves `amountWei` into `pendingRefund` (time-locked). REPLACES any existing pending refund and restarts its lock (`amountWei` = new total). Claim with {@link withdrawRefund}. */
813
+ requestRefund(params: {
814
+ amountWei: bigint;
815
+ provider?: Address;
816
+ }): Promise<WriteContractReturnType>;
817
+ /** Claim the pending refund once `refundUnlockAt` has passed (reverts earlier); pays out to the caller's wallet. */
818
+ withdrawRefund(opts?: {
819
+ provider?: Address;
820
+ }): Promise<WriteContractReturnType>;
821
+ }
822
+ export {};
823
+ //# sourceMappingURL=AgenticID.d.ts.map