@0gfoundation/0g-agentdna 0.4.0 → 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 +87 -6
- package/dist/cli/settings.d.ts.map +1 -1
- package/dist/cli/settings.js +270 -18
- 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 +272 -22
- 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/OPERATORS.zh.md
ADDED
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
# 运行代理方
|
|
2
|
+
|
|
3
|
+
[English](./OPERATORS.md)
|
|
4
|
+
|
|
5
|
+
NFT owner 可以为一个 agent 指定一个 operator,由它提供沙盒并支付费用。
|
|
6
|
+
operator 使用自己的钱包创建沙盒、向自己的 provider 余额充值、acknowledge provider,
|
|
7
|
+
并签署运行环境的生命周期请求。NFT、settings 和 credential set 仍由 owner 控制。
|
|
8
|
+
这不需要修改 sandbox 协议,也不授予 NFT approval 或全局管理员权限。
|
|
9
|
+
|
|
10
|
+
## Owner 配置与 operator 托管
|
|
11
|
+
|
|
12
|
+
```ts
|
|
13
|
+
import { AgentDNA } from '@0gfoundation/0g-agentdna';
|
|
14
|
+
import { parseEther } from 'viem';
|
|
15
|
+
import { privateKeyToAccount } from 'viem/accounts';
|
|
16
|
+
|
|
17
|
+
const owner = await AgentDNA.fromAttestor(attestorUrl, { account: ownerKey });
|
|
18
|
+
const operatorAccount = privateKeyToAccount(operatorKey);
|
|
19
|
+
const operator = await AgentDNA.fromAttestor(attestorUrl, { account: operatorAccount });
|
|
20
|
+
|
|
21
|
+
const ownerAck = await owner.ack();
|
|
22
|
+
if (ownerAck) await owner.waitForTransaction(ownerAck);
|
|
23
|
+
const { sealId } = await owner.agent.deploy(
|
|
24
|
+
{ name: 'Sage', description: 'a hosted agent' }, { wait: 'minted' },
|
|
25
|
+
);
|
|
26
|
+
|
|
27
|
+
// 模型和凭证由 owner 配置,operator 没有编辑权。
|
|
28
|
+
const { version } = await owner.agent.getSettings(sealId);
|
|
29
|
+
await owner.agent.setSettings(sealId, { provider: '0g-compute', model: modelName }, { baseVersion: version });
|
|
30
|
+
await owner.credentials.setModelKey(sealId, '0g-compute', inferenceKey, { push: false });
|
|
31
|
+
await owner.agent.setOperator(sealId, operatorAccount.address);
|
|
32
|
+
|
|
33
|
+
// operator 使用自己的 acknowledgement 和预充值余额提供计算资源。
|
|
34
|
+
const operatorAck = await operator.ack();
|
|
35
|
+
if (operatorAck) await operator.waitForTransaction(operatorAck);
|
|
36
|
+
await operator.waitForTransaction(await operator.deposit({ amountWei: parseEther('0.5') }));
|
|
37
|
+
await operator.agent.start(sealId); // 首次 provision,使用 owner 存储的 settings 和 credentials
|
|
38
|
+
await operator.agent.stop(sealId);
|
|
39
|
+
await operator.agent.start(sealId); // 恢复当前沙盒
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
mint-only deploy 不要求 owner 钱包持有沙盒预充值余额。
|
|
43
|
+
一次性 `deploy({ ..., sandbox })` 保持原有的 owner 付费行为;
|
|
44
|
+
operator 托管流程从 owner 已铸造的身份开始。
|
|
45
|
+
|
|
46
|
+
`start(sealId)` 会查询当前 sandbox ID。只要映射存在,就尝试恢复,即使实例未就绪
|
|
47
|
+
或显示 offline;遇到 `NOT_RESUMABLE` 会报错,不会隐式 reset 或再创建一个付费沙盒。
|
|
48
|
+
只有映射为空时才选择首次 provision。`start(sealId, sandboxId)` 仍可以显式指定沙盒,
|
|
49
|
+
`stop(sealId)` 也可以自动查询 ID。
|
|
50
|
+
|
|
51
|
+
operator 的 start/reset 可以传入 `sealedImage`、`framework` 等计算环境选项,
|
|
52
|
+
并遵守 attestor 的既有检查。它拒绝 `apiKey`、`sealedModelKey`、`sealedSecretEnv`、
|
|
53
|
+
`provider` 和 `keepStoredModelKey`:模型应先由 owner 通过 settings 与 credential API
|
|
54
|
+
配置。operator 调用不会补写默认 settings,也不会读写 owner 的 credential set。
|
|
55
|
+
owner 调用保留原有的模型密钥存储和默认 settings 初始化行为。
|
|
56
|
+
|
|
57
|
+
## 授权范围与更新
|
|
58
|
+
|
|
59
|
+
`getOperator(sealId)` 返回公开路由信息:`owner`、`operator`、`version`、
|
|
60
|
+
`expiresAt`、`allowRecreate`,以及通常为 `null` 的 `checkpoint`。普通查询不获取
|
|
61
|
+
新的区块锚点或历史 owner;返回值不是运行请求能够通过授权的证明,API 和 worker
|
|
62
|
+
会独立校验权限。尚未 mint 时,它返回 deployment owner,operator 为 `null`;
|
|
63
|
+
已有 owner stop/reset/retry 流程仍然可用,但写入 operator 授权必须等 agent mint 完成。
|
|
64
|
+
|
|
65
|
+
```ts
|
|
66
|
+
const grant = await owner.agent.getOperator(sealId);
|
|
67
|
+
await owner.agent.setOperator(sealId, operatorAccount.address, {
|
|
68
|
+
baseVersion: grant.version, // 可选;省略时先读取当前版本再签名
|
|
69
|
+
expiresAt: Math.floor(Date.now() / 1000) + 86400, // 省略或 0:直到更换或撤销
|
|
70
|
+
allowRecreate: true, // 默认 false
|
|
71
|
+
});
|
|
72
|
+
await operator.agent.start(sealId); // 更新授权会使原运行实例退役
|
|
73
|
+
await operator.agent.reset(sealId); // 替换已有运行环境需要 allowRecreate
|
|
74
|
+
await owner.agent.revokeOperator(sealId);
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
每次成功更新授权,包括续期、更换和撤销,都会使当前运行实例退役、清除 sandbox
|
|
78
|
+
映射,并通过持久化 outbox 安排清理旧沙盒。新 operator 不能接管旧 operator 的沙盒
|
|
79
|
+
或余额。更新后需要重新 provision。
|
|
80
|
+
|
|
81
|
+
写入会比较签名中的基础版本。并发修改会抛出 `OperatorConflictError`;所有权锚点
|
|
82
|
+
被取代则抛出 `OperatorCheckpointSupersededError`,其 `code` 为
|
|
83
|
+
`operator_checkpoint_superseded`,并可能包含 `minimumBlock`。需要刷新锚点并明确
|
|
84
|
+
批准新的 `setOperator()` 签名,SDK 不会自动重试或重新签名。
|
|
85
|
+
operator 的生命周期签名还绑定 agent、chain、合约和授权版本,旧排队
|
|
86
|
+
请求不会因同一钱包被重新授权而恢复有效。执行前会再次检查授权;已经发送给
|
|
87
|
+
provider 的操作仍可能完成。
|
|
88
|
+
|
|
89
|
+
仅 `setOperator` 会请求 `GET /operator?seal_id=...&checkpoint=true`,同时取得当前版本
|
|
90
|
+
和新的块末 checkpoint;owner 签名覆盖该区块高度和 hash。SDK 会拒绝不安全的
|
|
91
|
+
JavaScript 区块整数、格式不正确的 hash 和缺失 checkpoint,不会自行补造。写入成功后
|
|
92
|
+
重新查询普通路由信息:总计一次 anchor GET、一次 PUT、一次普通 GET;锚点不可用时
|
|
93
|
+
不会自动重试或重新签名。
|
|
94
|
+
|
|
95
|
+
`revokeOperator` 只查询普通路由信息以取得 owner 和基础版本,签署 `checkpoint: null`,
|
|
96
|
+
PUT 后再次读取普通路由信息。撤销不获取新锚点,也不依赖 Transfer 日志可用;
|
|
97
|
+
它仍要求当前 owner 的新鲜、限定范围签名,并匹配基础版本。
|
|
98
|
+
手工构造的撤销请求如果包含非空 checkpoint,会返回 HTTP 400。
|
|
99
|
+
|
|
100
|
+
指定 operator 时,attestor 检查新快照 `T` 的 owner,以及签名锚点 `H` 之后到 `T`
|
|
101
|
+
之间没有发生 Transfer。它读取 canonical header 和 Transfer 日志,不查询 `H` 的
|
|
102
|
+
历史状态,因此状态剪枝不会缩短五分钟的 `issued_at` 签名窗口。校验范围最多为
|
|
103
|
+
10,000 个区块;更旧的锚点或期间发生的 Transfer 要求明确刷新并重新签名。
|
|
104
|
+
授权写入和后续执行都不需要 archive RPC。attestor 会记录与签名 proof、signature
|
|
105
|
+
和授权版本绑定的准入事实;后续执行校验该记录、一次 canonical header 查询、
|
|
106
|
+
实时 owner 和当前授权。准入事实不是额外的密码学证明。
|
|
107
|
+
|
|
108
|
+
新锚点取 latest 区块,不取滞后的 confirmed 区块。header 缺失或 RPC 落后返回
|
|
109
|
+
HTTP 503;hash 不匹配则拒绝授权。
|
|
110
|
+
锚定在区块 `H` 结束时的授权,不会被迟到的 `H` 或更早区块中的 indexer 事件删除;
|
|
111
|
+
`H` 之后的所有权转移在被 indexer 索引后使它失效。转出后又转回同一钱包的撤权
|
|
112
|
+
依赖 indexer 追上进度,实时 owner 检查本身无法识别这种往返。
|
|
113
|
+
|
|
114
|
+
每次生命周期调用只解析一次 operator 身份和 deployment,并在该次请求内复用这些
|
|
115
|
+
数据来选择沙盒、规划仅 owner 可执行的模型操作。下一次调用会重新读取,
|
|
116
|
+
不跨调用缓存授权;API 和 worker 仍各自执行授权检查。
|
|
117
|
+
|
|
118
|
+
默认授权允许首次 provision 和正常起停;替换已有运行环境需要 `allowRecreate`。
|
|
119
|
+
NFT 转移、owner settings、credentials、clone、retry 和 operator 管理仍归 owner。
|
|
120
|
+
NFT 转移会使原 owner 的委托和启动授权失效。
|
|
121
|
+
|
|
122
|
+
## 容器证明与功能边界
|
|
123
|
+
|
|
124
|
+
operator 签署运行请求并支付沙盒费用,启动授权仍记录真正的 NFT owner。
|
|
125
|
+
`/provision` 保留 provider v3 certificate、已绑定容器身份与启动证明等检查,
|
|
126
|
+
operator 钱包签名不能替代这些证明。agent 密钥只加密给验证过的容器,owner 的
|
|
127
|
+
credentials 仍通过既有 provision 通道交付。
|
|
128
|
+
|
|
129
|
+
已受理的 create 完成时,worker 会重新检查 owner、授权和 boot generation;
|
|
130
|
+
不会仅因原始请求 envelope 已过期就丢弃创建结果。
|
|
131
|
+
依赖暂时不可用时,worker 会有限次重试,并持久保留已创建的沙盒供后续重新校验;
|
|
132
|
+
只有明确的权限或 boot generation 拒绝才会安排清理,不因依赖故障直接删除结果。
|
|
133
|
+
授权本身的 `expiresAt` 仍是权限边界:若在 create 期间到期,结果就不能绑定给 agent;
|
|
134
|
+
worker 不会为了完成操作而自动延长授权。
|
|
135
|
+
|
|
136
|
+
本功能增加委托授权,不增加空闲调度或常驻唤醒网关。stop 保持现有语义,
|
|
137
|
+
不增加停机前最终状态同步,也不保证没有任务正在运行。应用需要在请求停机前
|
|
138
|
+
自行作出这些判断。
|
|
139
|
+
|
|
140
|
+
如果数据库在有限次重试后仍无法保存已受理的创建结果,worker 会保留沙盒并报告其 ID,
|
|
141
|
+
要求 attestor 管理员介入。自动恢复需要该创建结果已持久保存。
|
package/PROVIDERS.md
CHANGED
|
@@ -98,6 +98,12 @@ a provider requiring another protocol or authentication scheme still needs a
|
|
|
98
98
|
code release. Endpoints/catalogs must be HTTPS without embedded credentials,
|
|
99
99
|
query strings, or fragments. Compatibility flags belong to their provider;
|
|
100
100
|
additional managed providers do not inherit compute metadata or routing guesses.
|
|
101
|
+
An optional `webSearch` names the web search service the provider's key pays
|
|
102
|
+
for: `0g-router`, `openai` or `anthropic` (sealed's inference route calls each;
|
|
103
|
+
a 0g-harness owner picks one with `others.webSearch`). It is not part of the
|
|
104
|
+
route hash, so adding it does not re-authorize a sealed key. Without the
|
|
105
|
+
field, sealed still gives `0g-compute` the router's search and native `openai`
|
|
106
|
+
and `anthropic` their own (`providerWebSearch` returns the same).
|
|
101
107
|
`0g-compute` must remain in the registry. The only native IDs are `openai` and
|
|
102
108
|
`anthropic`; they have no custom endpoints and use framework-native wiring.
|
|
103
109
|
|
package/PROVIDERS.zh.md
CHANGED
|
@@ -83,7 +83,9 @@ await ag.admin.updateProviders(edited.providers, { baseVersion: edited.version }
|
|
|
83
83
|
仅返回 ID 的目录表示模型能力未知。协议限于已实现的 OpenAI/Anthropic 接线;
|
|
84
84
|
其他协议或特殊鉴权仍需改代码发版。endpoint 和目录必须为 HTTPS,不含内嵌凭据、
|
|
85
85
|
query 或 fragment。兼容参数仅作用于对应 provider;新增托管服务不继承 compute
|
|
86
|
-
|
|
86
|
+
的元数据或路由猜测。可选的 `webSearch` 写明该 provider 的 key 能付哪个网页搜索服务:
|
|
87
|
+
`0g-router`、`openai` 或 `anthropic`(由 sealed 的推理代理调用;0g-harness 的 owner 用
|
|
88
|
+
`others.webSearch` 选择)。它不计入路由哈希,加上它不会让已封存的 key 需要重新授权。没有这个字段时,sealed 仍让 `0g-compute` 用 router 的搜索,native 的 `openai`、`anthropic` 用各自的搜索(`providerWebSearch` 给出同样的结果)。名单必须保留 `0g-compute`。仅 `openai`、`anthropic` 可标记
|
|
87
89
|
native,使用框架自身接线,不设置自定义 endpoint。
|
|
88
90
|
|
|
89
91
|
## 发布 API
|
package/README.md
CHANGED
|
@@ -27,6 +27,7 @@ One entry point: agent, reputation, and admin namespaces + top-level ops.
|
|
|
27
27
|
|---|---|
|
|
28
28
|
| `ag.agent` | agent lifecycle (deploy / clone / transfer), reads (owner, agentSeal, iData…), agent-seal gas top-up |
|
|
29
29
|
| `ag.reputation` | capture a TEE-signed serve-proof, verify it, submit/read on-chain feedback |
|
|
30
|
+
| `ag.credentials` | the owner's credentials for an agent's sealed credential proxy: set, remove, approve requests, MCP login, audit |
|
|
30
31
|
| `ag.ack()` / `ag.ackStatus()` | acknowledge the TEE trust-root component set (attestor + kms + sandbox-provider) |
|
|
31
32
|
| `ag.deposit()` / `ag.getBalance()` | fund / read the prepaid sandbox balance (pay-as-you-go runtime) |
|
|
32
33
|
| `ag.getBalanceDetail()` / `ag.requestRefund()` / `ag.withdrawRefund()` | full 3-value account view; withdraw prepaid funds (time-locked two-step) |
|
|
@@ -119,10 +120,10 @@ await ag.agent.balanceOf(owner); // → 5n agents owned by `owne
|
|
|
119
120
|
// agent-seal gas — the agent's own on-chain-write budget
|
|
120
121
|
await ag.agent.topUpAgentSeal(await ag.agent.getAgentSeal(agentId), parseEther('0.01')); // → "0x…"
|
|
121
122
|
|
|
122
|
-
// runtime lifecycle (owner
|
|
123
|
+
// runtime lifecycle (owner or appointed operator; on-chain identity preserved)
|
|
123
124
|
await ag.agent.stop(sealId, sandboxId);
|
|
124
125
|
await ag.agent.start(sealId, sandboxId); // resume a STOPPED container
|
|
125
|
-
await ag.agent.start(sealId, { apiKey }); //
|
|
126
|
+
await ag.agent.start(sealId, { apiKey }); // owner: resume current sandbox, or first provision if no mapping
|
|
126
127
|
await ag.agent.reset(sealId, { framework, apiKey }); // recreate an EXISTING container
|
|
127
128
|
// start/reset of an agent with no settings document that is a clone or has
|
|
128
129
|
// provisioned before first store the default model (0g-compute) as its settings
|
|
@@ -130,7 +131,10 @@ await ag.agent.reset(sealId, { framework, apiKey }); // recreate an EXISTING c
|
|
|
130
131
|
await ag.agent.retry(sealId, { apiKey }); // resume a 'failed' deploy (do NOT redeploy — that orphans the mint)
|
|
131
132
|
await ag.agent.listDeployments(); // public listing; sandboxId/lastProvisionError/containerStatus null (owner+agentSeal present on minted rows)
|
|
132
133
|
await ag.agent.listMyDeployments(); // owner-signed; full detail
|
|
133
|
-
// row → { agentId, sealId, phase, sandboxId, url, owner, agentSeal, name, createdAt, lastProvisionError, containerStatus }
|
|
134
|
+
// row → { agentId, sealId, phase, sandboxId, url, owner, agentSeal, name, createdAt, lastProvisionError, containerStatus, migrate }
|
|
135
|
+
// migrate (owner listing only): { version, framework, until, urgent, state } | null — a published
|
|
136
|
+
// release replaces this agent's image: reset it by `until` (state 'recommended' | 'soon' | 'overdue').
|
|
137
|
+
await ag.agent.releases(); // the attestor's release notices, newest first (GET /releases)
|
|
134
138
|
// phase: 'deploying' | 'running' | 'stopped' | 'offline' | 'failed'
|
|
135
139
|
// containerStatus: { level, reason, at } | null — the container's last report. phase
|
|
136
140
|
// shows a 'warning' as 'running' (e.g. reason "owner settings unusable…": no model).
|
|
@@ -140,7 +144,7 @@ await ag.agent.listMyDeployments(); // owner-signed; full detail
|
|
|
140
144
|
// the container, so widening the vocabulary never needs an attestor change.
|
|
141
145
|
// Owner-signed BOTH ways — it is on no listing and on no public row.
|
|
142
146
|
const { settings, version } = await ag.agent.getSettings(sealId);
|
|
143
|
-
// settings → { provider, model, thinking,
|
|
147
|
+
// settings → { provider, model, thinking, others, versions } | null (null = never configured)
|
|
144
148
|
// version → the number to write back against (0 when there is no document)
|
|
145
149
|
await ag.agent.setSettings(sealId, { ...(settings ?? {}), model: '0gm-1.0-35b-a3b', thinking: 'high' }, {
|
|
146
150
|
baseVersion: version, // compare-and-swap: a stale one is refused, not applied
|
|
@@ -148,13 +152,20 @@ await ag.agent.setSettings(sealId, { ...(settings ?? {}), model: '0gm-1.0-35b-a3
|
|
|
148
152
|
}); // → { version }
|
|
149
153
|
```
|
|
150
154
|
|
|
151
|
-
`setSettings` writes the WHOLE document (spread the current one to change a field) and is owner-signed: the attestor verifies the signer against the **live on-chain owner**, so a seller cannot keep configuring an agent they sold — and the same signature gates the READ, because the document is the owner's, not public. It is deliberately **not** on chain — configuration is re-suppliable, where the agent's memory is not. The container picks it up on its next boot (`reset` to apply immediately) and reports success, which promotes it to last-known-good; a container that keeps coming back WITHOUT ever confirming is handed that last-known-good document instead, so a document that prevents boot costs a boot rather than the agent. `
|
|
155
|
+
`setSettings` writes the WHOLE document (spread the current one to change a field) and is owner-signed: the attestor verifies the signer against the **live on-chain owner**, so a seller cannot keep configuring an agent they sold — and the same signature gates the READ, because the document is the owner's, not public. It is deliberately **not** on chain — configuration is re-suppliable, where the agent's memory is not. The container picks it up on its next boot (`reset` to apply immediately) and reports success, which promotes it to last-known-good; a container that keeps coming back WITHOUT ever confirming is handed that last-known-good document instead, so a document that prevents boot costs a boot rather than the agent. `others` is an opaque JSON section for that framework's own knobs — the platform neither parses nor validates it. On 0g-harness, `versions: { sealed, harness }` pins the layered runtime to versions the trust registry lists (`ag.agent.listedVersions()`); the [guide](./GUIDE.md#agagent--lifecycle--reads) has the rule. `onWarn` is advisory only: an unlisted model is reported against its provider's configured catalog without blocking; native providers without a catalog accept manual model IDs. Non-compute providers require runtime image support and a provider-bound key; see [providers](./PROVIDERS.md).
|
|
152
156
|
|
|
153
157
|
Every write is a **compare-and-swap** on `baseVersion` — the version you read before editing (0 = "no document yet"). If the stored version has moved on, the write is refused with `SettingsConflictError`, which carries the document that is actually there. Re-read, re-apply, write again; do not loop on it, or the other writer's change is the one that disappears.
|
|
154
158
|
|
|
155
159
|
The [lifecycle guide](./GUIDE.md#agagent--lifecycle--reads) covers async phases, transfer teardown, mint-only vs first-provision, `apiKey` handling, and failure reasons.
|
|
156
160
|
|
|
157
|
-
|
|
161
|
+
For operator-funded hosting, the owner mints without a sandbox, configures its
|
|
162
|
+
settings and credentials, then calls `agent.setOperator(sealId, operatorAddress)`.
|
|
163
|
+
The operator funds its own sandbox balance and calls `agent.start(sealId)` /
|
|
164
|
+
`agent.stop(sealId)` without model-key options. Every grant update retires the
|
|
165
|
+
current runtime; provision again after a change. See [runtime operators](./OPERATORS.md)
|
|
166
|
+
([中文](./OPERATORS.zh.md)).
|
|
167
|
+
|
|
168
|
+
A model key given to `deploy` / `start` / `reset` / `retry` is stored in the agent's credential set. While older images are in use it also rides the request: `start` / `reset` / `retry` seal it to the agent (`SEAL_SECRET_ENV`) when the attestor advertises `secret_env_scheme`, so the owner's wallet prompt never shows it. A one-shot `deploy` with `sandbox` still signs it in clear; to avoid that, deploy without `sandbox`, then `start(sealId, { apiKey })`. When your server supplies the key and a user signs, seal it on the server with `credentials.sealModelKey(sealId, { owner, provider, apiKey })` and have the browser store the result with `credentials.setModelKey` (or pass it to `start` / `reset` / `retry` as `sealedModelKey`), so the key never reaches the browser. See the [guide](./GUIDE.md#the-runtime-image-framework-and-idata-shapes) for `secretEnv: 'sealed' | 'plaintext'` and `SecretEnvRefusedError`.
|
|
158
169
|
|
|
159
170
|
**Three IDs, same agent:**
|
|
160
171
|
|
|
@@ -209,6 +220,10 @@ if (proof) {
|
|
|
209
220
|
}
|
|
210
221
|
// optional params: valueDecimals / tag1 / tag2 / endpoint / feedbackURI / feedbackHash
|
|
211
222
|
// escape hatch: attestFeedback(agentId, idx, proof) marks an entry submitted separately
|
|
223
|
+
// a v2 proof (0g-harness on the layered runtime: version 2 + sealedHash, harnessHash,
|
|
224
|
+
// inferenceURL, model) goes to attestVersionedFeedback — VerifiedFeedbackRegistry
|
|
225
|
+
// 1.3.0+, refused before broadcast on an older one; verifyProof also checks its
|
|
226
|
+
// layers against the trust registry's lists (layersListed)
|
|
212
227
|
|
|
213
228
|
// canonical reads (raw 8004 feedback — permissionless, verified or not)
|
|
214
229
|
await ag.reputation.getLastIndex(agentId, buyer); // → 2n
|
|
@@ -224,6 +239,7 @@ await ag.reputation.getVerifiedSummary({ agentId }); // proof-backed entri
|
|
|
224
239
|
await ag.reputation.getVerifiedClients(agentId); // clients with ≥1 verified entry
|
|
225
240
|
await ag.reputation.getVerifiedIndexes(agentId, buyer); // → [1n, …]
|
|
226
241
|
await ag.reputation.getServeData(agentId, buyer, idx); // → { dataHashes, frameworkHash }
|
|
242
|
+
await ag.reputation.getServeLayers(agentId, buyer, idx); // → { sealedHash, harnessHash } (v2 proofs; zero for v1)
|
|
227
243
|
// task-receipt opening: pass `task` (method/uri/body hashes/status of the rated
|
|
228
244
|
// interaction) to giveFeedback and the contract verifies it against the proof's
|
|
229
245
|
// taskHash, recording the URI as the entry's TEE-verified endpoint
|
|
@@ -236,6 +252,32 @@ await ag.reputation.appendResponse({ agentId, clientAddress: buyer, feedbackInde
|
|
|
236
252
|
await ag.reputation.revokeFeedback(agentId, idx); // → "0x…"
|
|
237
253
|
```
|
|
238
254
|
|
|
255
|
+
## `ag.credentials` — owner credentials
|
|
256
|
+
|
|
257
|
+
The agent writes `[[credential:<name>]]` where a key goes; sealed fills the value in on the way out, only for the hosts and request positions the owner allowed, and removes it from responses. Each value is sealed to the agent's agentSeal key here, in the client; the whole set is signed once (EIP-712 `CredentialSet`), stored at the attestor (compare-and-swap) and pushed to the running agent. The full model is in [`sealed/CREDENTIALS.md`](../../sealed/CREDENTIALS.md).
|
|
258
|
+
|
|
259
|
+
```ts
|
|
260
|
+
const { version } = await ag.credentials.get(sealId); // definitions, never values; CredentialsUnverifiedError unless this wallet signed the stored set and it is no older than, nor another set at the version of, one seen before (`credentialMarks` keeps that across processes)
|
|
261
|
+
await ag.credentials.put(sealId, [
|
|
262
|
+
{ name: 'github', value: process.env.GITHUB_TOKEN, hosts: ['api.github.com'],
|
|
263
|
+
positions: [{ kind: 'header', name: 'Authorization', template: 'Bearer {v}' }] },
|
|
264
|
+
], { baseVersion: version }); // CredentialsConflictError when someone wrote meanwhile
|
|
265
|
+
|
|
266
|
+
// an MCP server: define a login entry, then open the link the agent returns
|
|
267
|
+
await ag.credentials.connect(sealId, 'linear'); // → { authorizeUrl }
|
|
268
|
+
await ag.credentials.disconnect(sealId, 'linear'); // revoke at the server (RFC 7009) when it can, then remove
|
|
269
|
+
|
|
270
|
+
// requests from the agent
|
|
271
|
+
const waiting = await ag.credentials.pending(sealId); // sealed's facts, and the agent's reason apart
|
|
272
|
+
await ag.credentials.approveOnce(sealId, waiting[0].auth_req_id); // one-time EIP-712 approval
|
|
273
|
+
await ag.credentials.deny(sealId, waiting[0].auth_req_id);
|
|
274
|
+
await ag.credentials.pendingCounts(); // across every agent you own
|
|
275
|
+
await ag.credentials.setNotifyAddress('you@example.org');
|
|
276
|
+
await ag.credentials.audit(sealId); // what the agent did, never values
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
Entries without `value` keep their stored ciphertext; `remove()` and `setAllowReveal()` re-sign the rest. A signing entry (`use: 'sign'`) takes a `signer` (`sigv4`, `hmac`, `jwt`, `wallet`); a login entry takes `mcp: { url }` and no value.
|
|
280
|
+
|
|
239
281
|
## Top-level ops
|
|
240
282
|
|
|
241
283
|
Two distinct balances: **`ag.deposit()`** funds the prepaid sandbox balance (compute runtime, pay-as-you-go), **`ag.agent.topUpAgentSeal()`** funds the agentSeal's own gas (the agent's on-chain activity). The [top-level-ops guide](./GUIDE.md#top-level-ops-not-scoped-to-one-agent) explains both in full.
|
|
@@ -321,15 +363,46 @@ await agent.cancelTask!(taskId); // stop the turn
|
|
|
321
363
|
|
|
322
364
|
// The agent's own work (0g-harness): turns it opens by itself (a background job
|
|
323
365
|
// finished, a reminder came due) and what runs in the background. Each method
|
|
324
|
-
// is present only when /hello declares its kind (inbox / events /
|
|
366
|
+
// is present only when /hello declares its kind (inbox / events / activities /
|
|
325
367
|
// schedules) and this handle holds the owner key:
|
|
326
368
|
const box = await agent.inbox!(); // unread messages + the cursor
|
|
327
369
|
if (box.data.length) await agent.ackInbox!(box.data[box.data.length - 1].seq); // read, for every client
|
|
328
|
-
for await (const e of agent.events!({ after: box.cursor, signal })) { /* inbox.message, turn.*,
|
|
329
|
-
await agent.
|
|
330
|
-
await agent.
|
|
370
|
+
for await (const e of agent.events!({ after: box.cursor, signal })) { /* inbox.message, turn.*, activity.updated, … */ }
|
|
371
|
+
await agent.activities!(); // turns, commands, subagents: who did each, who asked
|
|
372
|
+
await agent.stopActivity!('subagent-1'); // one of them; stopAllActivities() for everything running
|
|
373
|
+
// (tasks()/stopTask() are their deprecated names; zgh-style tasks are createTask() and friends, below)
|
|
331
374
|
await agent.schedules!(); // reminders the agent set for itself
|
|
332
375
|
|
|
376
|
+
// Images and files (0g-harness). Images ride the message (PNG/JPEG/WebP/GIF,
|
|
377
|
+
// base64; 8 per message, 10 MiB each). A model that cannot view images gets
|
|
378
|
+
// them as files instead, and onNotice says so. uploadFile (present when /hello
|
|
379
|
+
// declares kind "files") puts a file in the agent's file inbox ~/inbox; tell it the path:
|
|
380
|
+
const { path } = await agent.uploadFile!('report.pdf', bytes); // ≤ 25 MiB
|
|
381
|
+
for await (const d of agent.chatStream!([{ role: 'user', content: `read ${path}; what is in this screenshot?` }], {
|
|
382
|
+
images: [{ mediaType: 'image/png', data: pngBase64 }],
|
|
383
|
+
onNotice: (n) => { if (n.imagesSavedAsFiles) console.log('model cannot see images:', n.imagesSavedAsFiles); },
|
|
384
|
+
})) process.stdout.write(d);
|
|
385
|
+
|
|
386
|
+
// Steer the running turn (0g-harness, kind "steer"): read before its next model call.
|
|
387
|
+
const r = await agent.steer!('use the v2 API instead'); // { merged: true, id, turn } | { merged: false, queued, reason }
|
|
388
|
+
if (r.merged) console.log((await agent.steerState!(r.id!)).state); // pending | merged | turn | dropped
|
|
389
|
+
|
|
390
|
+
// The owner's sessions (0g-harness, kind "sessions"): each its own conversation,
|
|
391
|
+
// sharing persona, skills and memory. owner-chat is the default one behind chatStream.
|
|
392
|
+
const s = await agent.createSession!({ title: 'research' }); // or { fork: 'owner-chat', at?: n }
|
|
393
|
+
const p = await agent.promptSession!(s.id, 'look into X'); // { merged, id: response id, session }; mode 'steer' reaches a running turn
|
|
394
|
+
for await (const d of agent.followTask!(p.id)) process.stdout.write(d);
|
|
395
|
+
await agent.sessions!(); // owner-chat and the rest, newest first
|
|
396
|
+
await agent.cancelSession!(s.id); // stop its running turn
|
|
397
|
+
|
|
398
|
+
// Tasks (0g-harness, kinds "tasks" + "task-feed", zgh's task model): a piece of work
|
|
399
|
+
// in a session and workspace of its own, ending each run with an outcome record.
|
|
400
|
+
const { task, created } = await agent.createTask!({ prompt: 'migrate the db', id: 'task-migrate-1' }); // id taken → created: false
|
|
401
|
+
const t = await agent.getTask!(task.id); // state: queued | working | idle | needs-input | done | failed | archived; records, outcome
|
|
402
|
+
await agent.taskInput!(task.id, 'use option a'); // answers open questions; steers a working run ({ mode: 'next' }: its next turn)
|
|
403
|
+
for await (const e of agent.taskFeed!({ signal })) { /* { type: 'task', task } … { type: 'ready' } … */ }
|
|
404
|
+
await agent.cancelTaskRun!(task.id); // stop the run; archiveTask() puts it away
|
|
405
|
+
|
|
333
406
|
// opinionated shortcuts over client():
|
|
334
407
|
const auth = await ag.agent.authenticate(agentId); // mints the owner token up front (needs a wallet)
|
|
335
408
|
const pub = await ag.agent.connect(agentId); // explicit PUBLIC handle (never attaches a token)
|
|
@@ -341,7 +414,7 @@ const pub = await ag.agent.connect(agentId); // explicit PUBLIC handle (
|
|
|
341
414
|
|
|
342
415
|
- **[Agents as owners (nested agents)](./GUIDE.md#agents-as-owners-nested-agents)** — an in-container agent runs this SDK as itself over the sign socket (`sealAccount()`), never holding a raw key.
|
|
343
416
|
- **[Addresses](./GUIDE.md#addresses)** — a deployment artifact, not baked into the SDK; `fromAttestor` fills them. Exported constants: `ZERO_G_TESTNET` / `ZERO_G_MAINNET` / `RPC_URL` / `CHAIN_ID` / `RECEIPT_WAIT`.
|
|
344
|
-
- **[Advanced](./GUIDE.md#advanced)** — raw ABIs + serve-proof primitives (`buildServeProofMessageHash`, `buildServeProofSigningHash`, `signServeProof`, `verifyServeProofSignature`, the last three taking the VerifiedFeedbackRegistry as `validator`; `taskHashOf` / `requestUriOf` / `requestUriCandidates` for the taskHash commitment) and the canonical digest spec (EIP-191 version 0x00, intended validator = the registry; 0.2.0 is a hard cut from personal_sign).
|
|
417
|
+
- **[Advanced](./GUIDE.md#advanced)** — raw ABIs + serve-proof primitives (`buildServeProofMessageHash`, `buildServeProofSigningHash`, `signServeProof`, `verifyServeProofSignature`, the last three taking the VerifiedFeedbackRegistry as `validator`, all four picking v1 or v2 by the proof's `version`; `taskHashOf` / `requestUriOf` / `requestUriCandidates` for the taskHash commitment; trust-registry reads) and the canonical digest spec (EIP-191 version 0x00, intended validator = the registry; 0.2.0 is a hard cut from personal_sign).
|
|
345
418
|
- **[CLI](./GUIDE.md#cli-0g-agentdna)** `npx @0gfoundation/0g-agentdna` — interactive shell (deploy/use agents, chat with Esc-interruptible turns); `doctor` / `status <agent>` / `list` subcommands with `--json` for scripts.
|
|
346
419
|
|
|
347
420
|
## Notes
|