@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.
- package/GUIDE.md +975 -0
- package/LICENSE +21 -0
- package/MIGRATION.md +84 -0
- package/MIGRATION.zh.md +70 -0
- package/PROVIDERS.md +273 -0
- package/PROVIDERS.zh.md +234 -0
- package/README.md +334 -2
- package/dist/AgentClient.d.ts +312 -0
- package/dist/AgentClient.d.ts.map +1 -0
- package/dist/AgentClient.js +715 -0
- package/dist/AgentClient.js.map +1 -0
- package/dist/AgenticID.d.ts +823 -0
- package/dist/AgenticID.d.ts.map +1 -0
- package/dist/AgenticID.js +1188 -0
- package/dist/AgenticID.js.map +1 -0
- package/dist/AgenticIDClient.d.ts +68 -0
- package/dist/AgenticIDClient.d.ts.map +1 -0
- package/dist/AgenticIDClient.js +198 -0
- package/dist/AgenticIDClient.js.map +1 -0
- package/dist/AttestorClient.d.ts +465 -0
- package/dist/AttestorClient.d.ts.map +1 -0
- package/dist/AttestorClient.js +1030 -0
- package/dist/AttestorClient.js.map +1 -0
- package/dist/Providers.d.ts +72 -0
- package/dist/Providers.d.ts.map +1 -0
- package/dist/Providers.js +182 -0
- package/dist/Providers.js.map +1 -0
- package/dist/ReputationClient.d.ts +213 -0
- package/dist/ReputationClient.d.ts.map +1 -0
- package/dist/ReputationClient.js +708 -0
- package/dist/ReputationClient.js.map +1 -0
- package/dist/SandboxClient.d.ts +107 -0
- package/dist/SandboxClient.d.ts.map +1 -0
- package/dist/SandboxClient.js +200 -0
- package/dist/SandboxClient.js.map +1 -0
- package/dist/ServeProof.d.ts +161 -0
- package/dist/ServeProof.d.ts.map +1 -0
- package/dist/ServeProof.js +230 -0
- package/dist/ServeProof.js.map +1 -0
- package/dist/ServeSession.d.ts +180 -0
- package/dist/ServeSession.d.ts.map +1 -0
- package/dist/ServeSession.js +336 -0
- package/dist/ServeSession.js.map +1 -0
- package/dist/Settings.d.ts +179 -0
- package/dist/Settings.d.ts.map +1 -0
- package/dist/Settings.js +247 -0
- package/dist/Settings.js.map +1 -0
- package/dist/abi.d.ts +2216 -0
- package/dist/abi.d.ts.map +1 -0
- package/dist/abi.js +1248 -0
- package/dist/abi.js.map +1 -0
- package/dist/cli/commands/cells.d.ts +62 -0
- package/dist/cli/commands/cells.d.ts.map +1 -0
- package/dist/cli/commands/cells.js +113 -0
- package/dist/cli/commands/cells.js.map +1 -0
- package/dist/cli/commands/doctor.d.ts +15 -0
- package/dist/cli/commands/doctor.d.ts.map +1 -0
- package/dist/cli/commands/doctor.js +236 -0
- package/dist/cli/commands/doctor.js.map +1 -0
- package/dist/cli/commands/interactive.d.ts +115 -0
- package/dist/cli/commands/interactive.d.ts.map +1 -0
- package/dist/cli/commands/interactive.js +3052 -0
- package/dist/cli/commands/interactive.js.map +1 -0
- package/dist/cli/commands/list.d.ts +31 -0
- package/dist/cli/commands/list.d.ts.map +1 -0
- package/dist/cli/commands/list.js +91 -0
- package/dist/cli/commands/list.js.map +1 -0
- package/dist/cli/commands/providers.d.ts +3 -0
- package/dist/cli/commands/providers.d.ts.map +1 -0
- package/dist/cli/commands/providers.js +21 -0
- package/dist/cli/commands/providers.js.map +1 -0
- package/dist/cli/commands/settings.d.ts +22 -0
- package/dist/cli/commands/settings.d.ts.map +1 -0
- package/dist/cli/commands/settings.js +188 -0
- package/dist/cli/commands/settings.js.map +1 -0
- package/dist/cli/commands/status.d.ts +16 -0
- package/dist/cli/commands/status.d.ts.map +1 -0
- package/dist/cli/commands/status.js +148 -0
- package/dist/cli/commands/status.js.map +1 -0
- package/dist/cli/commands/update.d.ts +21 -0
- package/dist/cli/commands/update.d.ts.map +1 -0
- package/dist/cli/commands/update.js +95 -0
- package/dist/cli/commands/update.js.map +1 -0
- package/dist/cli/config.d.ts +73 -0
- package/dist/cli/config.d.ts.map +1 -0
- package/dist/cli/config.js +239 -0
- package/dist/cli/config.js.map +1 -0
- package/dist/cli/env.d.ts +36 -0
- package/dist/cli/env.d.ts.map +1 -0
- package/dist/cli/env.js +74 -0
- package/dist/cli/env.js.map +1 -0
- package/dist/cli/envelope.d.ts +33 -0
- package/dist/cli/envelope.d.ts.map +1 -0
- package/dist/cli/envelope.js +62 -0
- package/dist/cli/envelope.js.map +1 -0
- package/dist/cli/errors.d.ts +48 -0
- package/dist/cli/errors.d.ts.map +1 -0
- package/dist/cli/errors.js +81 -0
- package/dist/cli/errors.js.map +1 -0
- package/dist/cli/inference.d.ts +21 -0
- package/dist/cli/inference.d.ts.map +1 -0
- package/dist/cli/inference.js +60 -0
- package/dist/cli/inference.js.map +1 -0
- package/dist/cli/logo.d.ts +21 -0
- package/dist/cli/logo.d.ts.map +1 -0
- package/dist/cli/logo.js +131 -0
- package/dist/cli/logo.js.map +1 -0
- package/dist/cli/main.d.ts +14 -0
- package/dist/cli/main.d.ts.map +1 -0
- package/dist/cli/main.js +223 -0
- package/dist/cli/main.js.map +1 -0
- package/dist/cli/proofs.d.ts +67 -0
- package/dist/cli/proofs.d.ts.map +1 -0
- package/dist/cli/proofs.js +133 -0
- package/dist/cli/proofs.js.map +1 -0
- package/dist/cli/ref.d.ts +39 -0
- package/dist/cli/ref.d.ts.map +1 -0
- package/dist/cli/ref.js +48 -0
- package/dist/cli/ref.js.map +1 -0
- package/dist/cli/sdk.d.ts +24 -0
- package/dist/cli/sdk.d.ts.map +1 -0
- package/dist/cli/sdk.js +65 -0
- package/dist/cli/sdk.js.map +1 -0
- package/dist/cli/settings.d.ts +66 -0
- package/dist/cli/settings.d.ts.map +1 -0
- package/dist/cli/settings.js +137 -0
- package/dist/cli/settings.js.map +1 -0
- package/dist/cli/tokenize.d.ts +61 -0
- package/dist/cli/tokenize.d.ts.map +1 -0
- package/dist/cli/tokenize.js +157 -0
- package/dist/cli/tokenize.js.map +1 -0
- package/dist/cli/types.d.ts +25 -0
- package/dist/cli/types.d.ts.map +1 -0
- package/dist/cli/types.js +8 -0
- package/dist/cli/types.js.map +1 -0
- package/dist/constants.d.ts +107 -0
- package/dist/constants.d.ts.map +1 -0
- package/dist/constants.js +74 -0
- package/dist/constants.js.map +1 -0
- package/dist/context.d.ts +108 -0
- package/dist/context.d.ts.map +1 -0
- package/dist/context.js +64 -0
- package/dist/context.js.map +1 -0
- package/dist/index.d.ts +45 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +118 -0
- package/dist/index.js.map +1 -0
- package/dist/provider-catalog.json +23 -0
- package/dist/seal.d.ts +47 -0
- package/dist/seal.d.ts.map +1 -0
- package/dist/seal.js +145 -0
- package/dist/seal.js.map +1 -0
- package/dist/secretEnv.d.ts +119 -0
- package/dist/secretEnv.d.ts.map +1 -0
- package/dist/secretEnv.js +199 -0
- package/dist/secretEnv.js.map +1 -0
- package/dist/taskHash.d.ts +39 -0
- package/dist/taskHash.d.ts.map +1 -0
- package/dist/taskHash.js +119 -0
- package/dist/taskHash.js.map +1 -0
- package/dist/types.d.ts +336 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +19 -0
- package/dist/types.js.map +1 -0
- package/package.json +75 -4
- package/scripts/sync-providers.cjs +8 -0
- package/src/AgentClient.ts +897 -0
- package/src/AgenticID.ts +1382 -0
- package/src/AgenticIDClient.ts +238 -0
- package/src/AttestorClient.ts +1306 -0
- package/src/Providers.ts +176 -0
- package/src/ReputationClient.ts +821 -0
- package/src/SandboxClient.ts +227 -0
- package/src/ServeProof.ts +290 -0
- package/src/ServeSession.ts +421 -0
- package/src/Settings.ts +296 -0
- package/src/abi.ts +1282 -0
- package/src/cli/commands/cells.ts +107 -0
- package/src/cli/commands/doctor.ts +235 -0
- package/src/cli/commands/interactive.ts +2738 -0
- package/src/cli/commands/list.ts +95 -0
- package/src/cli/commands/providers.ts +16 -0
- package/src/cli/commands/settings.ts +197 -0
- package/src/cli/commands/status.ts +170 -0
- package/src/cli/commands/update.ts +86 -0
- package/src/cli/config.ts +225 -0
- package/src/cli/env.ts +90 -0
- package/src/cli/envelope.ts +57 -0
- package/src/cli/errors.ts +114 -0
- package/src/cli/inference.ts +57 -0
- package/src/cli/logo.ts +125 -0
- package/src/cli/main.ts +235 -0
- package/src/cli/proofs.ts +160 -0
- package/src/cli/ref.ts +58 -0
- package/src/cli/sdk.ts +65 -0
- package/src/cli/settings.ts +153 -0
- package/src/cli/tokenize.ts +131 -0
- package/src/cli/types.ts +27 -0
- package/src/constants.ts +106 -0
- package/src/context.ts +161 -0
- package/src/index.ts +129 -0
- package/src/provider-catalog.json +23 -0
- package/src/seal.ts +163 -0
- package/src/secretEnv.ts +250 -0
- package/src/taskHash.ts +100 -0
- 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
|