@0gfoundation/0g-agentdna 0.2.3 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/GUIDE.md +190 -40
- package/OPERATORS.md +164 -0
- package/OPERATORS.zh.md +141 -0
- package/PROVIDERS.md +6 -0
- package/PROVIDERS.zh.md +3 -1
- package/README.md +84 -11
- package/dist/AgentClient.d.ts +374 -26
- package/dist/AgentClient.d.ts.map +1 -1
- package/dist/AgentClient.js +323 -40
- package/dist/AgentClient.js.map +1 -1
- package/dist/AgenticID.d.ts +170 -80
- package/dist/AgenticID.d.ts.map +1 -1
- package/dist/AgenticID.js +300 -42
- package/dist/AgenticID.js.map +1 -1
- package/dist/AttestorClient.d.ts +115 -31
- package/dist/AttestorClient.d.ts.map +1 -1
- package/dist/AttestorClient.js +276 -56
- package/dist/AttestorClient.js.map +1 -1
- package/dist/Credentials.d.ts +574 -0
- package/dist/Credentials.d.ts.map +1 -0
- package/dist/Credentials.js +838 -0
- package/dist/Credentials.js.map +1 -0
- package/dist/Operators.d.ts +60 -0
- package/dist/Operators.d.ts.map +1 -0
- package/dist/Operators.js +38 -0
- package/dist/Operators.js.map +1 -0
- package/dist/Providers.d.ts +13 -0
- package/dist/Providers.d.ts.map +1 -1
- package/dist/Providers.js +20 -1
- package/dist/Providers.js.map +1 -1
- package/dist/Releases.d.ts +51 -0
- package/dist/Releases.d.ts.map +1 -0
- package/dist/Releases.js +72 -0
- package/dist/Releases.js.map +1 -0
- package/dist/ReputationClient.d.ts +47 -3
- package/dist/ReputationClient.d.ts.map +1 -1
- package/dist/ReputationClient.js +204 -78
- package/dist/ReputationClient.js.map +1 -1
- package/dist/ServeProof.d.ts +70 -23
- package/dist/ServeProof.d.ts.map +1 -1
- package/dist/ServeProof.js +94 -35
- package/dist/ServeProof.js.map +1 -1
- package/dist/ServeSession.d.ts +17 -2
- package/dist/ServeSession.d.ts.map +1 -1
- package/dist/ServeSession.js +77 -9
- package/dist/ServeSession.js.map +1 -1
- package/dist/Settings.d.ts +25 -1
- package/dist/Settings.d.ts.map +1 -1
- package/dist/Settings.js +53 -1
- package/dist/Settings.js.map +1 -1
- package/dist/TrustRegistry.d.ts +28 -0
- package/dist/TrustRegistry.d.ts.map +1 -0
- package/dist/TrustRegistry.js +67 -0
- package/dist/TrustRegistry.js.map +1 -0
- package/dist/abi.d.ts +346 -34
- package/dist/abi.d.ts.map +1 -1
- package/dist/abi.js +150 -30
- package/dist/abi.js.map +1 -1
- package/dist/cli/attach.d.ts +79 -0
- package/dist/cli/attach.d.ts.map +1 -0
- package/dist/cli/attach.js +253 -0
- package/dist/cli/attach.js.map +1 -0
- package/dist/cli/commands/cells.d.ts +45 -0
- package/dist/cli/commands/cells.d.ts.map +1 -1
- package/dist/cli/commands/cells.js +77 -0
- package/dist/cli/commands/cells.js.map +1 -1
- package/dist/cli/commands/cred.d.ts +12 -0
- package/dist/cli/commands/cred.d.ts.map +1 -0
- package/dist/cli/commands/cred.js +43 -0
- package/dist/cli/commands/cred.js.map +1 -0
- package/dist/cli/commands/doctor.d.ts.map +1 -1
- package/dist/cli/commands/doctor.js +44 -35
- package/dist/cli/commands/doctor.js.map +1 -1
- package/dist/cli/commands/interactive.d.ts +597 -21
- package/dist/cli/commands/interactive.d.ts.map +1 -1
- package/dist/cli/commands/interactive.js +5082 -1323
- package/dist/cli/commands/interactive.js.map +1 -1
- package/dist/cli/commands/list.d.ts +5 -5
- package/dist/cli/commands/list.d.ts.map +1 -1
- package/dist/cli/commands/list.js +21 -26
- package/dist/cli/commands/list.js.map +1 -1
- package/dist/cli/commands/providers.d.ts +4 -0
- package/dist/cli/commands/providers.d.ts.map +1 -1
- package/dist/cli/commands/providers.js +19 -5
- package/dist/cli/commands/providers.js.map +1 -1
- package/dist/cli/commands/releases.d.ts +13 -0
- package/dist/cli/commands/releases.d.ts.map +1 -0
- package/dist/cli/commands/releases.js +65 -0
- package/dist/cli/commands/releases.js.map +1 -0
- package/dist/cli/commands/settings.d.ts +5 -0
- package/dist/cli/commands/settings.d.ts.map +1 -1
- package/dist/cli/commands/settings.js +70 -24
- package/dist/cli/commands/settings.js.map +1 -1
- package/dist/cli/commands/status.d.ts +2 -1
- package/dist/cli/commands/status.d.ts.map +1 -1
- package/dist/cli/commands/status.js +22 -19
- package/dist/cli/commands/status.js.map +1 -1
- package/dist/cli/config.d.ts +48 -1
- package/dist/cli/config.d.ts.map +1 -1
- package/dist/cli/config.js +114 -5
- package/dist/cli/config.js.map +1 -1
- package/dist/cli/credentials.d.ts +179 -0
- package/dist/cli/credentials.d.ts.map +1 -0
- package/dist/cli/credentials.js +1443 -0
- package/dist/cli/credentials.js.map +1 -0
- package/dist/cli/download.d.ts +21 -0
- package/dist/cli/download.d.ts.map +1 -0
- package/dist/cli/download.js +89 -0
- package/dist/cli/download.js.map +1 -0
- package/dist/cli/env.d.ts +6 -0
- package/dist/cli/env.d.ts.map +1 -1
- package/dist/cli/env.js +18 -6
- package/dist/cli/env.js.map +1 -1
- package/dist/cli/envelope.d.ts +4 -2
- package/dist/cli/envelope.d.ts.map +1 -1
- package/dist/cli/envelope.js +10 -6
- package/dist/cli/envelope.js.map +1 -1
- package/dist/cli/errors.d.ts +45 -1
- package/dist/cli/errors.d.ts.map +1 -1
- package/dist/cli/errors.js +77 -0
- package/dist/cli/errors.js.map +1 -1
- package/dist/cli/inference.d.ts.map +1 -1
- package/dist/cli/inference.js +7 -0
- package/dist/cli/inference.js.map +1 -1
- package/dist/cli/inkView.d.ts +341 -0
- package/dist/cli/inkView.d.ts.map +1 -0
- package/dist/cli/inkView.js +1019 -0
- package/dist/cli/inkView.js.map +1 -0
- package/dist/cli/legacy/modelKey.d.ts +24 -0
- package/dist/cli/legacy/modelKey.d.ts.map +1 -0
- package/dist/cli/legacy/modelKey.js +32 -0
- package/dist/cli/legacy/modelKey.js.map +1 -0
- package/dist/cli/livePrompt.d.ts +212 -0
- package/dist/cli/livePrompt.d.ts.map +1 -0
- package/dist/cli/livePrompt.js +576 -0
- package/dist/cli/livePrompt.js.map +1 -0
- package/dist/cli/main.js +206 -72
- package/dist/cli/main.js.map +1 -1
- package/dist/cli/modelkey.d.ts +64 -0
- package/dist/cli/modelkey.d.ts.map +1 -0
- package/dist/cli/modelkey.js +113 -0
- package/dist/cli/modelkey.js.map +1 -0
- package/dist/cli/outboxSync.d.ts +51 -0
- package/dist/cli/outboxSync.d.ts.map +1 -0
- package/dist/cli/outboxSync.js +210 -0
- package/dist/cli/outboxSync.js.map +1 -0
- package/dist/cli/plain.d.ts +46 -0
- package/dist/cli/plain.d.ts.map +1 -0
- package/dist/cli/plain.js +260 -0
- package/dist/cli/plain.js.map +1 -0
- package/dist/cli/proofs.d.ts +5 -0
- package/dist/cli/proofs.d.ts.map +1 -1
- package/dist/cli/proofs.js +20 -0
- package/dist/cli/proofs.js.map +1 -1
- package/dist/cli/ref.d.ts.map +1 -1
- package/dist/cli/ref.js +3 -2
- package/dist/cli/ref.js.map +1 -1
- package/dist/cli/releaseNotice.d.ts +64 -0
- package/dist/cli/releaseNotice.d.ts.map +1 -0
- package/dist/cli/releaseNotice.js +194 -0
- package/dist/cli/releaseNotice.js.map +1 -0
- package/dist/cli/sdk.d.ts +18 -0
- package/dist/cli/sdk.d.ts.map +1 -1
- package/dist/cli/sdk.js +99 -1
- package/dist/cli/sdk.js.map +1 -1
- package/dist/cli/settings.d.ts +90 -9
- package/dist/cli/settings.d.ts.map +1 -1
- package/dist/cli/settings.js +273 -21
- package/dist/cli/settings.js.map +1 -1
- package/dist/cli/textfit.d.ts +28 -0
- package/dist/cli/textfit.d.ts.map +1 -0
- package/dist/cli/textfit.js +111 -0
- package/dist/cli/textfit.js.map +1 -0
- package/dist/constants.d.ts +1 -1
- package/dist/constants.js +1 -1
- package/dist/context.d.ts +26 -0
- package/dist/context.d.ts.map +1 -1
- package/dist/context.js +1 -0
- package/dist/context.js.map +1 -1
- package/dist/index.d.ts +19 -11
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +35 -2
- package/dist/index.js.map +1 -1
- package/dist/legacy/modelKey.d.ts +67 -0
- package/dist/legacy/modelKey.d.ts.map +1 -0
- package/dist/legacy/modelKey.js +80 -0
- package/dist/legacy/modelKey.js.map +1 -0
- package/dist/legacy/serveProofV1.d.ts +56 -0
- package/dist/legacy/serveProofV1.d.ts.map +1 -0
- package/dist/legacy/serveProofV1.js +91 -0
- package/dist/legacy/serveProofV1.js.map +1 -0
- package/dist/provider-catalog.json +3 -2
- package/dist/secretEnv.d.ts +18 -3
- package/dist/secretEnv.d.ts.map +1 -1
- package/dist/secretEnv.js +16 -2
- package/dist/secretEnv.js.map +1 -1
- package/dist/types.d.ts +63 -1
- package/dist/types.d.ts.map +1 -1
- package/dist/viemErrors.d.ts +30 -0
- package/dist/viemErrors.d.ts.map +1 -0
- package/dist/viemErrors.js +36 -0
- package/dist/viemErrors.js.map +1 -0
- package/package.json +5 -1
- package/src/AgentClient.ts +622 -68
- package/src/AgenticID.ts +345 -56
- package/src/AttestorClient.ts +330 -83
- package/src/Credentials.ts +1027 -0
- package/src/Operators.ts +71 -0
- package/src/Providers.ts +20 -0
- package/src/Releases.ts +95 -0
- package/src/ReputationClient.ts +231 -79
- package/src/ServeProof.ts +123 -39
- package/src/ServeSession.ts +91 -9
- package/src/Settings.ts +61 -1
- package/src/TrustRegistry.ts +75 -0
- package/src/abi.ts +153 -30
- package/src/cli/attach.ts +257 -0
- package/src/cli/commands/cells.ts +104 -0
- package/src/cli/commands/cred.ts +44 -0
- package/src/cli/commands/doctor.ts +45 -37
- package/src/cli/commands/interactive.ts +4120 -664
- package/src/cli/commands/list.ts +21 -30
- package/src/cli/commands/providers.ts +17 -4
- package/src/cli/commands/releases.ts +60 -0
- package/src/cli/commands/settings.ts +75 -28
- package/src/cli/commands/status.ts +24 -21
- package/src/cli/config.ts +119 -4
- package/src/cli/credentials.ts +1379 -0
- package/src/cli/download.ts +80 -0
- package/src/cli/env.ts +22 -7
- package/src/cli/envelope.ts +10 -6
- package/src/cli/errors.ts +92 -0
- package/src/cli/inference.ts +8 -1
- package/src/cli/inkView.ts +969 -0
- package/src/cli/legacy/modelKey.ts +35 -0
- package/src/cli/livePrompt.ts +615 -0
- package/src/cli/main.ts +206 -76
- package/src/cli/modelkey.ts +124 -0
- package/src/cli/outboxSync.ts +231 -0
- package/src/cli/plain.ts +260 -0
- package/src/cli/proofs.ts +27 -0
- package/src/cli/ref.ts +5 -4
- package/src/cli/releaseNotice.ts +200 -0
- package/src/cli/sdk.ts +87 -7
- package/src/cli/settings.ts +275 -25
- package/src/cli/textfit.ts +95 -0
- package/src/constants.ts +1 -1
- package/src/context.ts +28 -0
- package/src/index.ts +50 -7
- package/src/legacy/modelKey.ts +80 -0
- package/src/legacy/serveProofV1.ts +124 -0
- package/src/provider-catalog.json +3 -2
- package/src/secretEnv.ts +18 -3
- package/src/types.ts +60 -1
- package/src/viemErrors.ts +39 -0
package/GUIDE.md
CHANGED
|
@@ -126,7 +126,7 @@ const params = {
|
|
|
126
126
|
// image (the operator-maintained default; same fallback reset() uses).
|
|
127
127
|
// Pass a name only to pin/rollback (0g-sandbox calls this field `snapshot` on the wire):
|
|
128
128
|
sealedImage: process.env.SEALED_IMAGE,
|
|
129
|
-
apiKey: process.env.AGENT_API_KEY, //
|
|
129
|
+
apiKey: process.env.AGENT_API_KEY, // the model key: stored in the agent's credential set
|
|
130
130
|
},
|
|
131
131
|
};
|
|
132
132
|
|
|
@@ -214,25 +214,26 @@ await ag.agent.balanceOf(owner); // → 5n agents owned by `own
|
|
|
214
214
|
const agentSeal = await ag.agent.getAgentSeal(agentId);
|
|
215
215
|
await ag.agent.topUpAgentSeal(agentSeal, parseEther('0.01')); // → tx hash "0x…"
|
|
216
216
|
|
|
217
|
-
// runtime start / stop / reset (owner
|
|
217
|
+
// runtime start / stop / reset (owner or appointed operator; identity preserved):
|
|
218
218
|
await ag.agent.stop(sealId, sandboxId); // stop a running container
|
|
219
219
|
await ag.agent.start(sealId, sandboxId); // resume a STOPPED container
|
|
220
|
-
await ag.agent.start(sealId, { apiKey }); //
|
|
221
|
-
//
|
|
222
|
-
//
|
|
223
|
-
//
|
|
224
|
-
//
|
|
220
|
+
await ag.agent.start(sealId, { apiKey }); // owner: resume the mapped sandbox, or first
|
|
221
|
+
// provision when there is no mapping.
|
|
222
|
+
// A failed resume never implicitly creates
|
|
223
|
+
// another paid sandbox; use reset explicitly.
|
|
224
|
+
// apiKey: see "The model key" below.
|
|
225
225
|
await ag.agent.reset(sealId, { apiKey }); // recreate an EXISTING container: re-read iData
|
|
226
226
|
// from chain, reselect the framework adapter.
|
|
227
|
-
//
|
|
228
|
-
// cache the model key); sealedImage optional.
|
|
227
|
+
// sealedImage optional.
|
|
229
228
|
// A booting agent with no settings document uses the model pinned in its minted
|
|
230
|
-
// persona, which leaves the chain at its first commit. So start and reset of an
|
|
229
|
+
// persona, which leaves the chain at its first commit. So OWNER start and reset of an
|
|
231
230
|
// agent that has no document and is a clone or has provisioned before first
|
|
232
231
|
// store DEFAULT_PERSONA_INFERENCE (0g-compute) as its settings: one more owner
|
|
233
232
|
// signature, after every check that can refuse the call; an existing document is
|
|
234
233
|
// never replaced. To start such an agent on another provider, write its settings
|
|
235
234
|
// (setSettings) first. The CLI's reset applies the same rule (needsDefaultSettings).
|
|
235
|
+
// Operators call start(sealId)/stop(sealId) after owner configuration; they cannot
|
|
236
|
+
// supply model-key options or write settings/credentials. See OPERATORS.md.
|
|
236
237
|
await ag.agent.listDeployments();
|
|
237
238
|
// → [{ agentId, sealId, phase, sandboxId, url, owner, name, createdAt, lastProvisionError,
|
|
238
239
|
// containerStatus }, …]
|
|
@@ -247,7 +248,8 @@ One document per agent says which model it thinks with and how hard. It is **not
|
|
|
247
248
|
|
|
248
249
|
```ts
|
|
249
250
|
const { settings, version } = await ag.agent.getSettings(sealId);
|
|
250
|
-
// settings → { provider?, model?, thinking?: 'low'|'high'|'max',
|
|
251
|
+
// settings → { provider?, model?, thinking?: 'low'|'high'|'max', others?: <any JSON>,
|
|
252
|
+
// versions?: { sealed?, harness? } } | null
|
|
251
253
|
// null = never configured (not an error)
|
|
252
254
|
// version → what to write back against; 0 when there is no document yet
|
|
253
255
|
|
|
@@ -259,6 +261,8 @@ await ag.agent.setSettings(sealId, { ...(settings ?? {}), model: '0gm-1.0-35b-a3
|
|
|
259
261
|
|
|
260
262
|
**Whole-document write.** `setSettings` replaces the document — read it first and spread it to change one field. A `thinking` outside `low|high|max` (case-insensitive, as the container compares it) is refused before signing.
|
|
261
263
|
|
|
264
|
+
**Version picks (0g-harness).** `versions: { sealed, harness }` pins the layered runtime to a sealed program and an official harness version, each by its sha256 (`"0x"` + 64 hex; anything else is refused before signing). A pick for a layer this SDK does not know is written back as it is, as an unknown top-level field is. `ag.agent.listedVersions()` reads what the trust registry lists — `{ registry, sealed: [...], harness: [...] }` in listing order, the last the newest; `null` on a chain without a trust registry (AgenticID before 1.4.0, whose `trustRegistry()` reverts); any other failed read throws. The agent runs a pick while it is listed; a layer with no pick keeps its running version while that stays listed and otherwise moves to the newest. The container applies a pushed document at once (`pushSettingsToContainer`), every boot, and every five minutes; the other frameworks ignore `versions`.
|
|
265
|
+
|
|
262
266
|
**Who may read or write it.** Owner-signed, both directions, against the **live on-chain owner** read at request time — so a seller cannot keep configuring (or reading) an agent they already sold. The SDK signs `AgenticID.Settings.v1:<sealId>:<ts>:<base_version>:<sha256 of the document>` (EIP-191) for a write, and the same message minus the digest for a read (`GET /settings`, no body, base version 0). A rejected call is a clearly-worded HTTP 401. The document is on **no** listing tier and on no public deployment row: `getSettings` is the only way to read it.
|
|
263
267
|
|
|
264
268
|
**Compare-and-swap.** `baseVersion` is the version you read before editing. If the stored version has moved on — another client, another device, a replayed request — the write is refused with `SettingsConflictError`, which carries the live document and its version:
|
|
@@ -318,6 +322,11 @@ const data = await response.json(); // your normal response bo
|
|
|
318
322
|
// validator: "0x…" } | null
|
|
319
323
|
// (validator = the VerifiedFeedbackRegistry the proof was signed for; diagnostics
|
|
320
324
|
// only — it is not part of the on-chain proof)
|
|
325
|
+
// A 0g-harness agent on the layered runtime signs a v2 proof, which adds what
|
|
326
|
+
// each layer ran: { …, version: 2, sealedHash: "0x…", harnessHash: "0x…",
|
|
327
|
+
// inferenceURL: "https://…" (or "" when the framework dials its provider itself),
|
|
328
|
+
// model: "…" }. Without `version` it is v1 (every other image). The version picks
|
|
329
|
+
// the digest and the registry entry point; the SDK handles both.
|
|
321
330
|
// low-level escape hatch (you build the whole request): ag.reputation.capture(() => fetch(…))
|
|
322
331
|
|
|
323
332
|
// 2. verify before spending gas (signer == on-chain agentSeal, deadline, dataHashes ⊆ iData).
|
|
@@ -329,7 +338,15 @@ const data = await response.json(); // your normal response bo
|
|
|
329
338
|
// the CLI's `rate` does.
|
|
330
339
|
await ag.reputation.verifyProof(proof);
|
|
331
340
|
// → { ok: true, signerMatches: true, notExpired: true, dataOnChain: true, registryMatches: true,
|
|
332
|
-
// taskMatches: null, reasons: [] }
|
|
341
|
+
// layersListed: null, taskMatches: null, reasons: [] }
|
|
342
|
+
// layersListed: null for a v1 proof. For v2, whether the image (frameworkHash),
|
|
343
|
+
// the sealed program and the official harness version it names are all on the
|
|
344
|
+
// trust registry's lists now (AgenticID.trustRegistry(), 1.4.0+) — `ok` needs it;
|
|
345
|
+
// a version delisted since the proof was signed fails, with the layer named in
|
|
346
|
+
// reasons. The registry does not check the lists, so such a proof still redeems.
|
|
347
|
+
// A chain whose AgenticID has no trustRegistry() (it reverts) gives false with a
|
|
348
|
+
// reason; a list read that fails for any other reason throws. The envelope is
|
|
349
|
+
// read as UTF-8, so a model or URL with non-ASCII text verifies.
|
|
333
350
|
// signer attribution only. Pass { task } (the TaskExchange fetchWithProof
|
|
334
351
|
// recorded) to also get taskMatches — the proof bound to THIS exchange's
|
|
335
352
|
// bytes; ok requires the match, and task: null fails closed. Hand-rolled
|
|
@@ -368,6 +385,10 @@ await ag.reputation.verifyProof(proof);
|
|
|
368
385
|
// beyond the registry's nonce retention, state changing between the check and
|
|
369
386
|
// the attest, and non-proof tx failures (gas, RPC) — the proof stays
|
|
370
387
|
// unconsumed, so retry with attestFeedback where that can help.
|
|
388
|
+
// A v2 proof goes to attestVersionedFeedback (VerifiedFeedbackRegistry 1.3.0+;
|
|
389
|
+
// on an older registry it is refused before anything is broadcast), atomically
|
|
390
|
+
// through a batcher that has giveFeedbackAndAttestVersioned (the SDK asks it
|
|
391
|
+
// gas-free once), else on the sequential path with the same preflight.
|
|
371
392
|
// NOTE: an agent's OWNER cannot attest feedback on their own agent — the
|
|
372
393
|
// verified registry rejects it (VerifiedFeedbackSelfFeedback). Feedback must
|
|
373
394
|
// come from a different wallet than the one that owns `agentId`. Neither can
|
|
@@ -434,6 +455,7 @@ await ag.reputation.getVerifiedSummary({ agentId }); // unscoped →
|
|
|
434
455
|
await ag.reputation.getVerifiedClients(agentId); // → [ "0x…", … ] clients with ≥1 verified entry
|
|
435
456
|
await ag.reputation.getVerifiedIndexes(agentId, buyer); // → [ 1n, 2n ]
|
|
436
457
|
await ag.reputation.getServeData(agentId, buyer, idx); // → { dataHashes: ["0x…"], frameworkHash: "0x…" } (verified entries only)
|
|
458
|
+
await ag.reputation.getServeLayers(agentId, buyer, idx); // → { sealedHash: "0x…", harnessHash: "0x…" } (v2 entries; zero for v1; registry 1.3.0+)
|
|
437
459
|
|
|
438
460
|
// owner responds to a feedback entry; the client who left it can revoke
|
|
439
461
|
await ag.reputation.appendResponse({ agentId, clientAddress: buyer, feedbackIndex: idx, responseURI: 'ipfs://Qm…', responseHash: keccak256(toBytes('thanks')) });
|
|
@@ -566,10 +588,33 @@ For the router's live model catalog:
|
|
|
566
588
|
await ag.agent.listModels(); // → ['claude-opus-4-8', 'deepseek-v4-pro', …]
|
|
567
589
|
```
|
|
568
590
|
|
|
569
|
-
`sandbox.apiKey`
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
591
|
+
**The model key.** `sandbox.apiKey` (and `apiKey` of `start` / `reset` /
|
|
592
|
+
`retry`) is stored in the agent's credential set as `model.<provider>`,
|
|
593
|
+
sealed to the agent ([credentials](../../docs/credentials.md#the-model-key)):
|
|
594
|
+
`deploy` checks the key before it signs anything and stores it as soon as
|
|
595
|
+
the attestor accepts the agent, without waiting for the mint
|
|
596
|
+
(`modelKeyStored` in the result); the attestor creates the container once
|
|
597
|
+
it is stored, ten seconds after the mint without one, or after a minute at
|
|
598
|
+
the latest, so the first boot has it (`awaitCredentials`, signed with the
|
|
599
|
+
deploy). `start` / `reset` / `retry` store it after their own checks pass,
|
|
600
|
+
before the request is signed. A store asks the owner's wallet for three
|
|
601
|
+
signatures (reading the stored set, the new set, the write); `deploy`'s for
|
|
602
|
+
two, as the new agent has no set to read. A container whose image reads
|
|
603
|
+
model keys from the set takes the key from there at boot, so with one
|
|
604
|
+
stored, a `reset` on that image needs none, and a `retry` with the
|
|
605
|
+
provider's key in the set can create a container. A key given without
|
|
606
|
+
`provider` is the 0g-compute key (`model.0g-compute`): pass `provider` for
|
|
607
|
+
any other provider's key. `ag.credentials.setModelKey(sealId, provider,
|
|
608
|
+
apiKey)` sets or replaces it at any time (three signatures, a fourth to
|
|
609
|
+
push it to the running agent). Without a key, 0g-harness on 0g-compute
|
|
610
|
+
boots and its model calls fail until one is set; with no key for the
|
|
611
|
+
provider in the set, the CLI asks for one for every other framework and
|
|
612
|
+
provider, and the SDK refuses a create without one for a provider other
|
|
613
|
+
than 0g-compute.
|
|
614
|
+
|
|
615
|
+
While older images are in use, the key also travels with the request:
|
|
616
|
+
inside the owner-signed "create" envelope into the TEE container's
|
|
617
|
+
environment, of which the attestor keeps no copy.
|
|
573
618
|
|
|
574
619
|
The owner's wallet shows that envelope verbatim when it signs. When the
|
|
575
620
|
attestor's `GET /config` advertises `secret_env_scheme`, `start` / `reset` /
|
|
@@ -590,22 +635,29 @@ without `sandbox`, persist the provider/model settings, then
|
|
|
590
635
|
|
|
591
636
|
**When your app supplies the key and the user signs.** Sealing in the
|
|
592
637
|
browser still means the key reaches the user's browser. Seal it on your
|
|
593
|
-
server instead, and hand the browser only the
|
|
638
|
+
server instead, and hand the browser only the sealed key:
|
|
594
639
|
|
|
595
640
|
```ts
|
|
596
641
|
// server: a read-only client is enough (no wallet)
|
|
597
642
|
const ag = new AgentDNA({ attestorUrl, addresses, rpcUrl, chain });
|
|
598
|
-
const sealed = await ag.
|
|
643
|
+
const sealed = await ag.credentials.sealModelKey(sealId, { owner, provider, apiKey });
|
|
599
644
|
|
|
600
|
-
// browser:
|
|
601
|
-
await ag.
|
|
645
|
+
// browser: stores it in the agent's credential set, signing only its hash
|
|
646
|
+
await ag.credentials.setModelKey(sealId, provider, sealed);
|
|
647
|
+
// or with a new container, in place of apiKey
|
|
648
|
+
await ag.agent.start(sealId, { sealedModelKey: sealed });
|
|
602
649
|
```
|
|
603
650
|
|
|
604
|
-
`owner` must be the wallet that signs: the
|
|
605
|
-
|
|
606
|
-
once the agent is minted
|
|
607
|
-
|
|
608
|
-
|
|
651
|
+
`owner` must be the wallet that signs: the value is bound to it (and to the
|
|
652
|
+
agent, the chain and `model.<provider>`), so `sealModelKey` checks `ownerOf`
|
|
653
|
+
once the agent is minted, and `setModelKey` refuses a key sealed for another
|
|
654
|
+
agent, provider or wallet. From the set the key reaches every boot of the
|
|
655
|
+
agent, like the owner's own key. While older images are in use,
|
|
656
|
+
`sealed.secretEnv` holds the same key as they read it with the request;
|
|
657
|
+
`start` / `reset` / `retry` send it (it is present when the attestor
|
|
658
|
+
advertises `secret_env_scheme`). The request-only form, `agent.sealApiKey`
|
|
659
|
+
passed as `sealedSecretEnv`, still works for the request it rides and goes
|
|
660
|
+
away with the request path.
|
|
609
661
|
|
|
610
662
|
Every refusal on these paths throws `SecretEnvRefusedError` (exported) before
|
|
611
663
|
anything is signed or sent: `signed` is always `false`, and `code` names the
|
|
@@ -685,6 +737,22 @@ const agentUrl = me?.url; // null until the container is provision
|
|
|
685
737
|
if (me.phase === 'failed') await ag.agent.retry(me.sealId, { apiKey });
|
|
686
738
|
```
|
|
687
739
|
|
|
740
|
+
When a release replaces an image, your agents on the old one keep running
|
|
741
|
+
through a transition period, and the owner listing marks them: `migrate` is
|
|
742
|
+
`{ version, framework, until, urgent, state }` (`state`: `recommended`, `soon`
|
|
743
|
+
in the last 7 days, `overdue` after `until`). Reset such an agent before
|
|
744
|
+
`until`: after it the old image may be retired, and the agent's next boot is
|
|
745
|
+
then refused until it is reset. `urgent` means the image may be retired sooner
|
|
746
|
+
(a security fix).
|
|
747
|
+
`ag.agent.releases()` reads the attestor's release notices (`GET /releases`):
|
|
748
|
+
each release's `notes` (and `notesZh`) and the images it replaces.
|
|
749
|
+
|
|
750
|
+
```ts
|
|
751
|
+
const toMove = (await ag.agent.listMyDeployments()).filter((d) => d.migrate);
|
|
752
|
+
for (const d of toMove) console.log(d.agentId, d.migrate!.until, d.migrate!.state);
|
|
753
|
+
const [latest] = await ag.agent.releases(); // newest first
|
|
754
|
+
```
|
|
755
|
+
|
|
688
756
|
- **`GET {agentUrl}/hello`** — public identity card: who I am, my owner, and
|
|
689
757
|
the surface I expose. Buffered responses carry a signed `X-Agent-Proof`
|
|
690
758
|
(a framework route's SSE stream doesn't — a signature needs a complete
|
|
@@ -710,9 +778,12 @@ if (me.phase === 'failed') await ag.agent.retry(me.sealId, { apiKey });
|
|
|
710
778
|
- `routes` — the framework's declared prefixes:
|
|
711
779
|
`{ prefix, kind?, auth?, signed, description? }`, e.g. a `kind:"chat"` API
|
|
712
780
|
at `/v1/` (auth `bearer`). `auth` tells you how to present the owner token;
|
|
713
|
-
`signed` says whether responses on that route carry an `X-Agent-Proof
|
|
714
|
-
|
|
715
|
-
|
|
781
|
+
`signed` says whether responses on that route carry an `X-Agent-Proof`;
|
|
782
|
+
`description` is one plain sentence on what the route is for. Every
|
|
783
|
+
shipped framework declares a `chat` route, and `/hello` lists a
|
|
784
|
+
`responses` route next to it (the runtime serves one where the framework
|
|
785
|
+
does not); prime adds `activity`, 0g-harness `tasks`, `inbox`, `files`
|
|
786
|
+
and more. A framework could declare a UI route, but none currently do.
|
|
716
787
|
|
|
717
788
|
- **`ag.agent.client(agentId)`** — one handle (`AgentClient`) for every caller.
|
|
718
789
|
Whether it can do owner ops is inherited from `ag`, exactly like `ag`'s
|
|
@@ -765,6 +836,22 @@ if (me.phase === 'failed') await ag.agent.retry(me.sealId, { apiKey });
|
|
|
765
836
|
// is "not now", nothing changed (a compaction or a turn already running, the
|
|
766
837
|
// framework busy, or a reused signature: retry later).
|
|
767
838
|
|
|
839
|
+
// `ag.agent.restartRuntime(base, agentId, 'harness' | 'sealed', instanceId?)`
|
|
840
|
+
// (CLI `/restart`) restarts one layer of a 0g-harness runtime in place: the
|
|
841
|
+
// harness process (conversation and disk stay), or sealed itself — the loader
|
|
842
|
+
// starts it again and the agent is away for about one start. Either applies
|
|
843
|
+
// the owner's version picks and the trust registry's lists. 202 once under
|
|
844
|
+
// way; 501 where there is no such restart (other frameworks, an image without
|
|
845
|
+
// the loader), 503 while sealed is still starting, 409 for a reused signature
|
|
846
|
+
// or a displaced window.
|
|
847
|
+
|
|
848
|
+
// `ag.agent.signatures(base, agentId, { after })` (CLI `/signatures`) reads
|
|
849
|
+
// what the agent signed as itself and what the runtime refused, oldest
|
|
850
|
+
// first, whichever way the agent reached its sign socket: a message's hash
|
|
851
|
+
// and start, a typed-data digest and domain, a transaction's hash, chain,
|
|
852
|
+
// target, value, nonce and selector. The runtime keeps the last 1000.
|
|
853
|
+
// 0g-harness agents only; the other frameworks keep no record (HTTP 404).
|
|
854
|
+
|
|
768
855
|
// Chat — present ONLY if the agent declares a chat route AND this ag has a
|
|
769
856
|
// key. Streams under the hood (`stream: true`), so a long reasoning turn
|
|
770
857
|
// keeps bytes flowing and never trips an idle-timeout hop in front of the
|
|
@@ -860,15 +947,66 @@ for await (const e of agent.events!({ after: box.cursor, signal })) {
|
|
|
860
947
|
if (e.type === 'reset') { /* the agent could not serve the position: re-read the inbox */ }
|
|
861
948
|
}
|
|
862
949
|
|
|
863
|
-
const
|
|
864
|
-
// every turn (yours and the agent's), command (bash
|
|
950
|
+
const running = await agent.activities!({ status: 'active' });
|
|
951
|
+
// every turn (yours and the agent's), command (bash-<hex>) and subagent (its session id, a UUID):
|
|
865
952
|
// actor = who does the work (agent | subagent), trigger = who asked
|
|
866
|
-
await agent.
|
|
867
|
-
await agent.
|
|
868
|
-
await agent.
|
|
953
|
+
await agent.activity!(running[0].id); // a finished subagent's entry includes its answer
|
|
954
|
+
await agent.stopActivity!('bash-2'); // a turn is cancelled, a command or subagent is killed
|
|
955
|
+
await agent.stopAllActivities!(); // everything running
|
|
956
|
+
// tasks/taskInfo/stopTask/stopAllTasks are the deprecated names of these; "task"
|
|
957
|
+
// is kept for zgh-style tasks (a unit of work with its own session and outcome)
|
|
869
958
|
await agent.schedules!(); // { enabled, data }: the reminders the agent set for itself
|
|
870
959
|
```
|
|
871
960
|
|
|
961
|
+
A 0g-harness owner's `others` section also picks the agent's web search service
|
|
962
|
+
(`webSearch`: the 0G router by default, or OpenAI or Anthropic) and the further
|
|
963
|
+
models its subagents may run on (`subagentModels`, `subagentDefault`); each is
|
|
964
|
+
paid with the model key or a named owner credential, never a key the agent
|
|
965
|
+
holds. sealed's harness adapter README lists the fields; the CLI checks their
|
|
966
|
+
shape before signing.
|
|
967
|
+
|
|
968
|
+
A 0g-harness agent also takes **images and files** from its owner. Images ride
|
|
969
|
+
a message: `chat` / `chatStream` take `images: [{ mediaType, data }]` (PNG, JPEG,
|
|
970
|
+
WebP or GIF, base64; at most 8 per message, 10 MiB each, 32 MiB together),
|
|
971
|
+
sent on the last user message in the transport's own shape. Whether the model
|
|
972
|
+
sees them is what the provider's model list says (the 0G router's
|
|
973
|
+
`architecture.input_modalities`: glm-5.3 takes text only, glm-5.3-flash images
|
|
974
|
+
too); the owner's `others.modelImages` overrides it. A model that cannot view
|
|
975
|
+
images gets each one saved as a file in the agent's file inbox `~/inbox` instead; the
|
|
976
|
+
`onNotice` callback receives `{ imagesSavedAsFiles: [paths] }`. An image may
|
|
977
|
+
carry its file name (`{ mediaType, data, name: 'flag test.png' }`): the SDK
|
|
978
|
+
sends it as the part's `filename` when the agent's `GET /v1/harness` lists
|
|
979
|
+
`features.image_names` (asked once per client), so the saved file keeps that
|
|
980
|
+
name instead of `image-<ms>-<n>.png`; elsewhere the name is left out. Any other file
|
|
981
|
+
goes through `uploadFile(name, bytes)` (present when `/hello` declares kind
|
|
982
|
+
`files`; at most 25 MiB): it lands in `~/inbox` under a new name, never over
|
|
983
|
+
an existing file, and returns `{ path, bytes }` — name the path in your
|
|
984
|
+
message. Both live in the container only: a reset loses them.
|
|
985
|
+
|
|
986
|
+
**Steering a running turn** (0g-harness, present when `/hello` declares kind
|
|
987
|
+
`steer`): `agent.steer(text)` puts the owner's word into the turn that is
|
|
988
|
+
running now; the agent reads it before that turn's next model call — when the
|
|
989
|
+
current model answer or tool call finishes, not in the middle of a long
|
|
990
|
+
command. It returns `{ merged: true, id, turn }`; with no owner turn running
|
|
991
|
+
it is queued as an ordinary turn instead, `{ merged: false, queued, reason }`.
|
|
992
|
+
`agent.steerState(id)` tells what became of it: `pending`, `merged` (read in
|
|
993
|
+
`turn`), `turn` (the turn ended first, so it opened `turn`, an owner turn of
|
|
994
|
+
its own) or `dropped` (an interrupt came first).
|
|
995
|
+
|
|
996
|
+
The way back: the agent puts files for its owner in its `~/outbox`.
|
|
997
|
+
`listFiles(dir?)` lists them (`'outbox'`, the default, or `'inbox'` for the
|
|
998
|
+
owner's own files), newest first, as `{ name, bytes, mtime, sha256? }`;
|
|
999
|
+
`downloadFile(dir, name)` returns one file's bytes (at most 50 MiB; one flat
|
|
1000
|
+
name, no leading dot). A turn that leaves files new or changed in the outbox
|
|
1001
|
+
says so: `onNotice` receives `{ outboxFiles: [names] }` when the turn ends.
|
|
1002
|
+
`deleteFile(dir, name)` removes one (`'deleted'`, `'missing'`, or
|
|
1003
|
+
`'unsupported'` from a runtime without the delete route). The methods share
|
|
1004
|
+
the `files` route; an agent whose runtime predates downloads answers with an
|
|
1005
|
+
error saying so. The outbox lives in the container only, like the file
|
|
1006
|
+
inbox, and the runtime removes files older than 30 days from both and keeps
|
|
1007
|
+
the file inbox under 1 GiB. The file inbox `~/inbox` is not the message inbox
|
|
1008
|
+
(`inbox()`, what the agent said in turns it opened itself).
|
|
1009
|
+
|
|
872
1010
|
## Agents as owners (nested agents)
|
|
873
1011
|
|
|
874
1012
|
An agent inside a sealed container can run this SDK **as itself** — deploy
|
|
@@ -929,7 +1067,7 @@ The stable protocol-level constants **are** exported: `ZERO_G_TESTNET` / `ZERO_G
|
|
|
929
1067
|
|
|
930
1068
|
## Advanced
|
|
931
1069
|
|
|
932
|
-
Raw ABIs (`agenticIDAbi`, `canonicalReputationAbi`, `verifiedFeedbackAbi`, `feedbackBatcherAbi`, `cloneGateAbi`, `standardCloneAuthorizerAbi`, `tappRegistryAbi`, `sandboxServingAbi`)
|
|
1070
|
+
Raw ABIs (`agenticIDAbi`, `trustRegistryAbi`, `canonicalReputationAbi`, `verifiedFeedbackAbi`, `feedbackBatcherAbi`, `cloneGateAbi`, `standardCloneAuthorizerAbi`, `tappRegistryAbi`, `sandboxServingAbi`), serve-proof primitives (`buildServeProofMessageHash`, `buildServeProofSigningHash`, `signServeProof`, `verifyServeProofSignature`, `serveProofLayers`, `SERVE_PROOF_VERSION`, `SERVE_PROOF_V2_TAG`, and for the `taskHash` commitment `taskHashOf`, `requestUriOf`, `requestUriCandidates`) and trust-registry reads (`trustRegistryOf`, `isListed`, `listedHashes`, `TRUST_KINDS`) are exported.
|
|
933
1071
|
|
|
934
1072
|
**Serve-proof canonical digest** (for independent verifiers): two hashes.
|
|
935
1073
|
The inner `proofHash` is
|
|
@@ -948,7 +1086,19 @@ It is **not** personal_sign: a personal_sign (`0x19 0x45`) signature over
|
|
|
948
1086
|
`proofHash` is rejected, and nothing falls back to it. `buildServeProofMessageHash` /
|
|
949
1087
|
`buildServeProofSigningHash` are the TS implementation; the Go side lives in
|
|
950
1088
|
`sealed/internal/proxy/`. `npm run test:kav` pins both hashes to the
|
|
951
|
-
known-answer vectors the contracts and sealed also assert.
|
|
1089
|
+
known-answer vectors the contracts and sealed also assert.
|
|
1090
|
+
|
|
1091
|
+
That is v1, the proof without a `version`. A v2 proof (`version: 2`, signed by
|
|
1092
|
+
0g-harness agents on the layered runtime) opens its preimage with a tag and
|
|
1093
|
+
adds what each layer ran, under the same 0x00 wrap:
|
|
1094
|
+
`keccak256(abi.encode(keccak256("AgentDNA.ServeProof.v2"), chainId,
|
|
1095
|
+
identityRegistry, submitter, agentId, timestamp, deadline, taskHash,
|
|
1096
|
+
keccak256(abi.encodePacked(dataHashes)), frameworkHash, sealedHash, harnessHash,
|
|
1097
|
+
keccak256(bytes(inferenceURL)), keccak256(bytes(model))))` — 14 words against
|
|
1098
|
+
v1's 9, so neither signature verifies as the other. The builders, `signServeProof`
|
|
1099
|
+
and `verifyServeProofSignature` pick the digest by the `version` field (pass
|
|
1100
|
+
`version: 2` and the four layer fields for v2); the registry redeems v2 through
|
|
1101
|
+
`attestVersionedFeedback` (1.3.0+). `npm run test:kav` pins the v2 vector too. The sealed proxy
|
|
952
1102
|
learns the validator from `VERIFIED_FEEDBACK_ADDR` (injected by the attestor)
|
|
953
1103
|
and echoes it as the envelope's `validator` field (diagnostics only, not part
|
|
954
1104
|
of the on-chain tuple); when that variable is unset, malformed or zero — or
|
|
@@ -984,7 +1134,7 @@ The per-contract clients (`AgenticIDClient`, `ReputationClient`, `SandboxClient`
|
|
|
984
1134
|
|
|
985
1135
|
## CLI: `0g-agentdna`
|
|
986
1136
|
|
|
987
|
-
The package ships a CLI — no separate install, zero extra dependencies. Bare `0g-agentdna` opens an **interactive shell** (Claude-Code style); `doctor`/`status`/`list`/`settings`
|
|
1137
|
+
The package ships a CLI — no separate install, zero extra dependencies. Bare `0g-agentdna` opens an **interactive shell** (Claude-Code style) at its manager prompt; `doctor`/`status`/`list`/`settings`/`cred`/`providers`/`releases`/`update` are scriptable one-shot commands. A word of the shell's own (`0g-agentdna login`, `whoami`, `deploy`, …) is refused with where to type it (run `0g-agentdna`, then type it there); any other word is an unknown command, with the nearest command named when it looks like a typo.
|
|
988
1138
|
|
|
989
1139
|
```bash
|
|
990
1140
|
npm install @0gfoundation/0g-agentdna
|
|
@@ -998,9 +1148,9 @@ For the old CLI update path and automatic local-config migration, see
|
|
|
998
1148
|
|
|
999
1149
|
### Interactive shell
|
|
1000
1150
|
|
|
1001
|
-
Two levels. The **manager** (`0g-agentdna>`): `list` (
|
|
1151
|
+
Two levels. The **manager** (`0g-agentdna>`): `list` (the same columns as `0g-agentdna list`, fitted to the terminal, `⇄ #<agentId>` on agent-owned agents, an agent without an agentId yet shown by its sealId prefix, `*` marks your wallet's agents), `use <agentId|sealId>` (enter an agent's session in **any** phase; an agent still being minted is entered once it has its agentId), `hello <id> [full]` (any agent's public /hello: identity, proof check, services one per line and owner routes on one line by kind; `full` prints every field — with a wallet configured it also banks a rating ticket), `call <id> [path [json-body]]` (use an agent's registered public service as a client; bare `call <id>` lists its services; the response banks a rating ticket), `rate <id> [score] [/endpoint]` (rate an agent on-chain, spending a ticket banked by call/hello — no interaction, no rating; owners cannot rate their own agents), `deploy` (framework → provider → model wizard: a listed number or name, anything else asked again), `start`/`stop`/`reset <id>` (not on an agent still deploying), `settings <id> [key=value …]` (show or change the agent's configuration document), `balance` / `deposit [og]` / `withdraw [og]` (prepaid sandbox account; an amount is checked before any transaction, a bare `deposit`/`withdraw` asks for it with no default — Enter cancels — and `withdraw <og>` asks before restarting a pending refund's time lock), `ack`, `status <id>` / `doctor` / `providers` / `releases` (the one-shot commands), `login [provider]` (guided setup: attestor URL → owner key → each provider's model key → the default provider for new agents; each answer is checked before it is saved and asked again when wrong, Enter keeps the current value, keys echo `*`), `whoami` (bare Enter does the same), `quit`. Errors are one or two plain lines with a remedy typed at that prompt.
|
|
1002
1152
|
|
|
1003
|
-
The **session** (`agent 286 ›`): type to chat — **Esc / Ctrl-C interrupts the turn in flight** (the runtime cancels server-side on every bundled framework) and also cancels a `/start`//`/reset` wait. Slash commands: `/hello` `/balance` `/topup [og]` `/stop` `/start` `/reset` `/settings [key=value
|
|
1153
|
+
The **session** (`agent 286 ›`): type to chat — **Esc / Ctrl-C interrupts the turn in flight** (the runtime cancels server-side on every bundled framework) and also cancels a `/start`//`/reset` wait. A message can span lines: a paste stays one message (shown as pasted, sent with the next Enter, never run as a command, whatever its first line starts with), and a line ending in `\` or Option/Alt+Enter goes on to a new line; Backspace at the start of a line joins it to the line before, and Ctrl-C or Esc with text in the box clears it, all its lines. On a terminal the session is drawn with Ink like Claude Code's input area: the `❯ ` input line between two rules at the bottom, a footer under it (it also says when the agent is not running, and the way out: `stopped — /start`; a bare Enter re-reads the phase and prints nothing), a status line above it during a turn (`⠹ running a command… (14s · Esc to stop)`, with `2 notices · 1 new file` at its right), the messages sent during the turn waiting above that, and the transcript scrolling above all of it — your messages as `❯ text`, replies, command output, notices, and one line per run of the agent's tool calls (`· ran 3 commands, read a file`); what you type stays in the box and can be edited while the agent replies. `AGENTDNA_INK=off`, a terminal under 30 columns or 12 rows, CI, or an `ink` package that does not load keep readline's prompt line, which stays on screen during a turn (`agent 286 (replying, Esc stops) › `) with the reply printing above it. On a 0g-harness agent a message you finish while the agent is working goes into the running turn of owner-chat (`agent.steer(text)` over `POST /v1/steer`): the agent reads it before the turn's next model call — shown as waiting for the agent until then (in the framed view it then moves into the transcript as your message; at readline's prompt `waiting for the agent: …`, then `↳ read by the agent: …`) — not in the middle of a long command; if the turn ends first, the agent answers it in the turn after (several such messages may be answered together) and the CLI follows it; an empty Enter waits for the next turn, and Esc stops the turn, the turns that would answer what was inserted and not read with it; those messages, and the ones queued, come back to be edited as one (a command that waited runs next, on its own). Which inserted messages come back is what the agent says after the stop: the ones it dropped (0g-harness drops them with the turn); one it read just before the stop prints as read; one an older 0g-harness still holds — it gives those to its next turn — is listed under `(not put back — …)` and stays out of the box, so it is not sent twice. A command alone on its line during a turn never goes to the agent: one that only reads (`/files`, `/tasks`, `/inbox`, `/hello`, …) runs at once, any other when the turn ends; Tab completes it. A turn that ends with no text because the model's output budget ran out says so (`no answer: …`); a failed turn says in one line whether the model service failed, the model is overloaded (try again for both), or what the error says (with `/agentlog`). Tab queues what you typed instead (shown as next turn, sent as your next message when the turn ends; Esc puts it back to edit, without blank lines), and ↑ on an empty prompt takes the newest queued entry back to edit. Option+Enter needs the Option key to send Meta: in macOS Terminal, Settings → Profiles → Keyboard → "Use Option as Meta key"; in iTerm2, Profiles → Keys → Left Option key: Esc+. Other questions take one line: several pasted lines are not their answer, and a paste does not answer a yes/no question or one that signs. Piped input stays one line per command. Slash commands: `/hello [full]` `/balance` `/topup [og]` `/stop` `/start` `/reset` `/settings [key=value …|versions]` `/think [level]` `/clear` (wipe the agent's conversation and start fresh — chain-tracked memory is untouched, unlike `/reset`) `/compact` (keep the conversation but have the framework summarize its older part now — 0g-harness, and openclaw 2026.7.1 or later; one or more model calls, can take minutes) `/restart harness|sealed` (0g-harness: restart one layer of the runtime in place) `/activities` `/tasks` `/result [id]` `/cancel [id|all]` `/inbox [all]` `/schedules` `/attach [path …|clear]` (0g-harness: files and images for your next message — an image goes with it, any other file is uploaded to the agent's file inbox `~/inbox` first and the message names its path) `/files [inbox]` (0g-harness: the files the agent left for you in its `~/outbox`; with `inbox`, the ones you sent) `/download <name> [path]` (0g-harness: save one locally, never over an existing file) `/agentlog [n]` `/startuplog [n]` `/back` (alias `/unuse`) `/quit`. The framework (used by `/reset` and the chat model selector) is picked by you from the attestor's list — never guessed. On a 0g-harness agent, what the agent says on its own (a notice: a background job finished, a reminder came due) prints above the prompt as it arrives, and what came while you were away prints when you enter (`/inbox` or `/notices` lists them); files it leaves in its `~/outbox` are saved by themselves to `~/agentdna/<agentId>/outbox` on a terminal and, once verified, removed from the agent's outbox (`/files auto off` stops that), and the status line (or, at readline's prompt, the prompt) counts what waits (`2 notices · 1 new file`); `/activities` lists every turn, background command and subagent with who did it, `/cancel <id>` stops any of them and `/cancel all` everything running. On the other frameworks `/inbox` and `/schedules` say the agent has none.
|
|
1004
1154
|
|
|
1005
1155
|
Configuration persists under `~/.config/0g-agentdna/` — `config.json` (attestor URL), `credentials` (owner key + provider-scoped inference keys, JSON, chmod 600), and `proofs.json` (the **rating-ticket jar**, chmod 600): serve-proofs banked by `call`/`hello`, spent by `rate`. Ticket physics: they expire ~1 hour after the interaction (the sealed proxy sets the deadline; the chain enforces it), are single-use, capped at 5 per (agent, wallet) pair, and are redeemable ONLY by the wallet named in the proof's `submitter` — a leaked jar is useless to anyone else. `rate` checks a ticket on what the registry checks — expiry and the signature — and discards one that fails on its own merits (bad signature — e.g. one banked from a pre-1.2.0 sealed image — or expiry), but keeps one that fails only because no VerifiedFeedbackRegistry, or a different one, is configured on this side. A ticket whose data hashes the agent has since replaced (it commits state drift every 30 s) still redeems — the registry records the version that served you without comparing it to current chain state — so `rate` only notes it and goes ahead. The `AGENTIC_*` environment variables always override the files, so CI and one-off runs need no disk.
|
|
1006
1156
|
|
|
@@ -1009,9 +1159,9 @@ Configuration persists under `~/.config/0g-agentdna/` — `config.json` (attesto
|
|
|
1009
1159
|
| Command | What |
|
|
1010
1160
|
|---|---|
|
|
1011
1161
|
| `doctor` | Checks every deploy prerequisite — attestor reachable, RPC, wallet, gas, trust-root ack, sandbox balance ≥ 0.1 OG — and prints a remedy per failing item. Exit 0 when all green, 3 otherwise. |
|
|
1012
|
-
| `status <agent>` | One agent's full picture: phase, all three coordinates (agentId / sealId / agentSeal),
|
|
1162
|
+
| `status <agent>` | One agent's full picture: phase, all three coordinates (agentId / sealId / agentSeal), failure reason (`--json` also carries the container `url`). `<agent>` is a decimal agentId **or** a `0x…` sealId — the CLI converts between them. When a failed deployment's reason is withheld from the public listing (#64), a configured key makes the CLI fetch it via the owner-signed listing automatically. |
|
|
1013
1163
|
| `list [--mine] [--phase p]` | Deployment listing; `--mine` (owner-signed, needs the key) adds the owner-only fields. Empty result is `[]` + exit 0. |
|
|
1014
|
-
| `settings <agent> [k=v …]` | Show the agent's configuration document; with `key=value` assignments, change it. Keys: `provider`, `model`, `thinking` (`low\|high\|max`), `
|
|
1164
|
+
| `settings <agent> [k=v …]` | Show the agent's configuration document; with `key=value` assignments, change it. Keys: `provider`, `model`, `thinking` (`low\|high\|max`), `others` (opaque JSON — quote it: `others='{"a": 1}'`, in the REPL too), and on a 0g-harness agent `sealed` / `harness` (a version's sha256 from the trust registry's lists, which `settings <agent> versions` prints — a bare show says on one line which versions run; refused for an agent of another framework). Assignments **merge** onto the stored document; an empty value (`thinking=`) clears a field. **Both** directions are owner-signed (needs the key). A write is a compare-and-swap against the version just read: a concurrent edit by another client is refused with `SETTINGS_CONFLICT` (exit 3), never overwritten. A merged document with no `model` is refused before signing — that is the one state the container hard-fails on. The chosen model is checked against its provider's configured catalog before signing — an absence is a warning on stderr. Native providers without a catalog accept a manual model ID. A provider change requires a registered matching key and image support, then reports pending reset; execute `reset` with that provider's key. |
|
|
1015
1165
|
|
|
1016
1166
|
Environment variables (override the config files):
|
|
1017
1167
|
|
package/OPERATORS.md
ADDED
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
# Runtime operators
|
|
2
|
+
|
|
3
|
+
[中文](./OPERATORS.zh.md)
|
|
4
|
+
|
|
5
|
+
The NFT owner can appoint one agent-scoped operator to provide and pay for its
|
|
6
|
+
sandbox. The operator creates the sandbox with its own wallet, funds its own
|
|
7
|
+
provider balance, acknowledges the provider and signs runtime lifecycle calls.
|
|
8
|
+
The NFT, settings and credential set remain controlled by the owner. No sandbox
|
|
9
|
+
protocol change, NFT approval or global administrator role is required.
|
|
10
|
+
|
|
11
|
+
## Owner setup and operator hosting
|
|
12
|
+
|
|
13
|
+
```ts
|
|
14
|
+
import { AgentDNA } from '@0gfoundation/0g-agentdna';
|
|
15
|
+
import { parseEther } from 'viem';
|
|
16
|
+
import { privateKeyToAccount } from 'viem/accounts';
|
|
17
|
+
|
|
18
|
+
const owner = await AgentDNA.fromAttestor(attestorUrl, { account: ownerKey });
|
|
19
|
+
const operatorAccount = privateKeyToAccount(operatorKey);
|
|
20
|
+
const operator = await AgentDNA.fromAttestor(attestorUrl, { account: operatorAccount });
|
|
21
|
+
|
|
22
|
+
const ownerAck = await owner.ack();
|
|
23
|
+
if (ownerAck) await owner.waitForTransaction(ownerAck);
|
|
24
|
+
const { sealId } = await owner.agent.deploy(
|
|
25
|
+
{ name: 'Sage', description: 'a hosted agent' }, { wait: 'minted' },
|
|
26
|
+
);
|
|
27
|
+
|
|
28
|
+
// The owner configures the model and credentials; the operator cannot edit them.
|
|
29
|
+
const { version } = await owner.agent.getSettings(sealId);
|
|
30
|
+
await owner.agent.setSettings(sealId, { provider: '0g-compute', model: modelName }, { baseVersion: version });
|
|
31
|
+
await owner.credentials.setModelKey(sealId, '0g-compute', inferenceKey, { push: false });
|
|
32
|
+
await owner.agent.setOperator(sealId, operatorAccount.address);
|
|
33
|
+
|
|
34
|
+
// The operator supplies compute, using its own acknowledgement and balance.
|
|
35
|
+
const operatorAck = await operator.ack();
|
|
36
|
+
if (operatorAck) await operator.waitForTransaction(operatorAck);
|
|
37
|
+
await operator.waitForTransaction(await operator.deposit({ amountWei: parseEther('0.5') }));
|
|
38
|
+
await operator.agent.start(sealId); // first provision; uses the owner's stored settings and credentials
|
|
39
|
+
await operator.agent.stop(sealId);
|
|
40
|
+
await operator.agent.start(sealId); // resumes the current sandbox
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Mint-only deploy does not require the owner's wallet to hold a prepaid sandbox
|
|
44
|
+
balance. One-shot `deploy({ ..., sandbox })` retains its owner-funded behavior;
|
|
45
|
+
operator hosting starts from an owner-minted identity.
|
|
46
|
+
|
|
47
|
+
`start(sealId)` resolves the current sandbox ID. An existing mapping means resume,
|
|
48
|
+
even when the runtime is not ready or reports offline; `NOT_RESUMABLE` is surfaced
|
|
49
|
+
to the caller, without an implicit reset or another paid create. Only an empty
|
|
50
|
+
mapping selects first provision. `start(sealId, sandboxId)` still selects an
|
|
51
|
+
explicit sandbox, and `stop(sealId)` can also resolve its ID automatically.
|
|
52
|
+
|
|
53
|
+
Operator start/reset accepts compute options such as `sealedImage` or `framework`,
|
|
54
|
+
subject to the attestor's existing checks. It refuses `apiKey`, `sealedModelKey`,
|
|
55
|
+
`sealedSecretEnv`, `provider` and `keepStoredModelKey`: configure the model through
|
|
56
|
+
the owner's settings and credential APIs first. Operator calls do not seed default
|
|
57
|
+
settings or read/write the owner's credential set. Owner calls retain the normal
|
|
58
|
+
model-key storage and settings-seeding behavior.
|
|
59
|
+
|
|
60
|
+
## Grant scope and updates
|
|
61
|
+
|
|
62
|
+
`getOperator(sealId)` returns public routing metadata: `owner`, `operator`,
|
|
63
|
+
`version`, `expiresAt`, `allowRecreate` and normally `checkpoint: null`. This
|
|
64
|
+
ordinary read does not request a fresh block anchor or historical owner; it is
|
|
65
|
+
not proof that a runtime request will be authorized. The API and worker verify
|
|
66
|
+
authority independently. Before mint, it reports the deployment owner with no
|
|
67
|
+
operator; existing owner stop/reset/retry requests remain available, but operator
|
|
68
|
+
grant writes require a minted agent.
|
|
69
|
+
|
|
70
|
+
```ts
|
|
71
|
+
const grant = await owner.agent.getOperator(sealId);
|
|
72
|
+
await owner.agent.setOperator(sealId, operatorAccount.address, {
|
|
73
|
+
baseVersion: grant.version, // optional; omitted means read before signing
|
|
74
|
+
expiresAt: Math.floor(Date.now() / 1000) + 86400, // omitted/0: until replaced or revoked
|
|
75
|
+
allowRecreate: true, // default false
|
|
76
|
+
});
|
|
77
|
+
await operator.agent.start(sealId); // grant updates retire the previous runtime
|
|
78
|
+
await operator.agent.reset(sealId); // replacing an existing runtime requires allowRecreate
|
|
79
|
+
await owner.agent.revokeOperator(sealId);
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Every successful grant write, including renewal, replacement and revocation,
|
|
83
|
+
retires the current runtime, clears its sandbox mapping and schedules old-sandbox
|
|
84
|
+
cleanup through a persisted outbox. A new operator cannot assume control of the
|
|
85
|
+
previous operator's sandbox or balance. Provision again after an update.
|
|
86
|
+
|
|
87
|
+
Writes compare the signed base version. A competing write raises
|
|
88
|
+
`OperatorConflictError`. A superseded ownership checkpoint instead raises
|
|
89
|
+
`OperatorCheckpointSupersededError`, with `code: 'operator_checkpoint_superseded'`
|
|
90
|
+
and an optional `minimumBlock`. Refresh the checkpoint and explicitly approve a
|
|
91
|
+
new `setOperator()` signature; the SDK never automatically retries or re-signs.
|
|
92
|
+
Operator lifecycle
|
|
93
|
+
signatures also bind the agent, chain, contract and grant version. Old queued
|
|
94
|
+
requests do not become valid again when the same wallet is reappointed.
|
|
95
|
+
Authorization is checked again before execution; an operation already sent to the
|
|
96
|
+
provider may still complete.
|
|
97
|
+
|
|
98
|
+
Only `setOperator` requests `GET /operator?seal_id=...&checkpoint=true` for the current
|
|
99
|
+
version and a fresh end-of-block checkpoint. The owner signs that exact block
|
|
100
|
+
number and hash. The SDK rejects unsafe JavaScript block numbers, malformed hashes
|
|
101
|
+
and missing checkpoints rather than inventing one. A successful write then
|
|
102
|
+
re-reads ordinary metadata: one anchor GET, one PUT and one metadata GET, with no
|
|
103
|
+
automatic retry or re-signing if the anchor is unavailable.
|
|
104
|
+
|
|
105
|
+
`revokeOperator` reads ordinary metadata for the owner and base version, signs
|
|
106
|
+
`checkpoint: null`, then re-reads ordinary metadata after PUT. Revocation does not
|
|
107
|
+
request a new anchor or depend on Transfer-log availability; it still requires
|
|
108
|
+
the current owner's fresh, scoped signature and the matching base version.
|
|
109
|
+
A hand-written revocation with a non-null checkpoint is rejected with HTTP 400.
|
|
110
|
+
|
|
111
|
+
For appointment, the attestor verifies the owner at a fresh snapshot `T` and that
|
|
112
|
+
no Transfer occurred after the signed anchor `H` through `T`. It reads canonical
|
|
113
|
+
headers and Transfer logs, not historical state at `H`, so state pruning does not
|
|
114
|
+
shorten the five-minute `issued_at` signing window. Validation spans at most
|
|
115
|
+
10,000 blocks; an older checkpoint or an intervening Transfer requires an
|
|
116
|
+
explicit refresh and new signature. Neither grant writes nor later execution
|
|
117
|
+
require an archive RPC. The attestor records acceptance bound to the signed
|
|
118
|
+
proof, signature and grant version. Later execution uses that admission fact,
|
|
119
|
+
one canonical-header lookup, live ownership and the current grant; acceptance is
|
|
120
|
+
not an additional cryptographic proof.
|
|
121
|
+
|
|
122
|
+
New anchors use the latest block, not a delayed confirmed block. Missing headers
|
|
123
|
+
or an RPC lag return HTTP 503; a hash mismatch rejects the grant. A delayed indexer
|
|
124
|
+
event in block `H` or earlier does not erase a grant anchored to the end of `H`.
|
|
125
|
+
An indexed ownership transfer after `H` invalidates it. Revoking a transfer away
|
|
126
|
+
and back to the same wallet depends on the indexer catching up; live owner checks
|
|
127
|
+
alone cannot detect that round trip.
|
|
128
|
+
|
|
129
|
+
Each lifecycle call resolves its operator authority and deployment at most once
|
|
130
|
+
and reuses that request's data for sandbox routing and owner-only model planning.
|
|
131
|
+
The next call reads them again. This is not a grant cache, and API/worker
|
|
132
|
+
authorization checks still run independently.
|
|
133
|
+
|
|
134
|
+
Default delegation allows first provision and normal start/stop. Replacing an
|
|
135
|
+
existing runtime requires `allowRecreate`. NFT transfer, owner settings,
|
|
136
|
+
credentials, clone, retry and operator management remain owner-only. NFT transfer
|
|
137
|
+
invalidates the previous owner's delegation and boot authorization.
|
|
138
|
+
|
|
139
|
+
## Container proof and scope
|
|
140
|
+
|
|
141
|
+
The operator signs runtime requests and pays for the sandbox. Boot authorization
|
|
142
|
+
continues to name the real NFT owner. `/provision` retains the provider v3
|
|
143
|
+
certificate, pinned container identity and boot-proof checks; an operator wallet
|
|
144
|
+
signature cannot replace them. The agent key is encrypted to the verified
|
|
145
|
+
container, and owner credentials are delivered through the existing provision
|
|
146
|
+
channel.
|
|
147
|
+
|
|
148
|
+
When an accepted create finishes, the worker rechecks its owner, grant and boot
|
|
149
|
+
generation. Expiry of the original request envelope alone does not discard it.
|
|
150
|
+
If a dependency is temporarily unavailable, the worker retries within a bound
|
|
151
|
+
and retains the created sandbox durably for later revalidation. Cleanup follows
|
|
152
|
+
an explicit rejection of authority or boot generation, not a dependency outage.
|
|
153
|
+
The grant's own `expiresAt` remains a permission boundary: if it expires during
|
|
154
|
+
create, the result cannot be bound to the agent. The worker never extends it to
|
|
155
|
+
finish an operation.
|
|
156
|
+
|
|
157
|
+
This feature adds authorization, not an idle scheduler or an always-on wake
|
|
158
|
+
gateway. Stop keeps its existing semantics: it does not add a final state flush
|
|
159
|
+
or guarantee that no task is running. An application must make those decisions
|
|
160
|
+
before requesting a stop.
|
|
161
|
+
|
|
162
|
+
If the database cannot save an accepted create result after bounded retries, the
|
|
163
|
+
worker preserves the sandbox and reports its ID for attestor admin intervention.
|
|
164
|
+
Automatic recovery requires that persisted result.
|