@0gfoundation/0g-agentdna 0.0.0-stage → 0.2.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.
Files changed (206) hide show
  1. package/GUIDE.md +975 -0
  2. package/LICENSE +21 -0
  3. package/MIGRATION.md +84 -0
  4. package/MIGRATION.zh.md +70 -0
  5. package/PROVIDERS.md +273 -0
  6. package/PROVIDERS.zh.md +234 -0
  7. package/README.md +334 -2
  8. package/dist/AgentClient.d.ts +312 -0
  9. package/dist/AgentClient.d.ts.map +1 -0
  10. package/dist/AgentClient.js +715 -0
  11. package/dist/AgentClient.js.map +1 -0
  12. package/dist/AgenticID.d.ts +823 -0
  13. package/dist/AgenticID.d.ts.map +1 -0
  14. package/dist/AgenticID.js +1188 -0
  15. package/dist/AgenticID.js.map +1 -0
  16. package/dist/AgenticIDClient.d.ts +68 -0
  17. package/dist/AgenticIDClient.d.ts.map +1 -0
  18. package/dist/AgenticIDClient.js +198 -0
  19. package/dist/AgenticIDClient.js.map +1 -0
  20. package/dist/AttestorClient.d.ts +465 -0
  21. package/dist/AttestorClient.d.ts.map +1 -0
  22. package/dist/AttestorClient.js +1030 -0
  23. package/dist/AttestorClient.js.map +1 -0
  24. package/dist/Providers.d.ts +72 -0
  25. package/dist/Providers.d.ts.map +1 -0
  26. package/dist/Providers.js +182 -0
  27. package/dist/Providers.js.map +1 -0
  28. package/dist/ReputationClient.d.ts +213 -0
  29. package/dist/ReputationClient.d.ts.map +1 -0
  30. package/dist/ReputationClient.js +708 -0
  31. package/dist/ReputationClient.js.map +1 -0
  32. package/dist/SandboxClient.d.ts +107 -0
  33. package/dist/SandboxClient.d.ts.map +1 -0
  34. package/dist/SandboxClient.js +200 -0
  35. package/dist/SandboxClient.js.map +1 -0
  36. package/dist/ServeProof.d.ts +161 -0
  37. package/dist/ServeProof.d.ts.map +1 -0
  38. package/dist/ServeProof.js +230 -0
  39. package/dist/ServeProof.js.map +1 -0
  40. package/dist/ServeSession.d.ts +180 -0
  41. package/dist/ServeSession.d.ts.map +1 -0
  42. package/dist/ServeSession.js +336 -0
  43. package/dist/ServeSession.js.map +1 -0
  44. package/dist/Settings.d.ts +179 -0
  45. package/dist/Settings.d.ts.map +1 -0
  46. package/dist/Settings.js +247 -0
  47. package/dist/Settings.js.map +1 -0
  48. package/dist/abi.d.ts +2216 -0
  49. package/dist/abi.d.ts.map +1 -0
  50. package/dist/abi.js +1248 -0
  51. package/dist/abi.js.map +1 -0
  52. package/dist/cli/commands/cells.d.ts +34 -0
  53. package/dist/cli/commands/cells.d.ts.map +1 -0
  54. package/dist/cli/commands/cells.js +66 -0
  55. package/dist/cli/commands/cells.js.map +1 -0
  56. package/dist/cli/commands/doctor.d.ts +15 -0
  57. package/dist/cli/commands/doctor.d.ts.map +1 -0
  58. package/dist/cli/commands/doctor.js +236 -0
  59. package/dist/cli/commands/doctor.js.map +1 -0
  60. package/dist/cli/commands/interactive.d.ts +107 -0
  61. package/dist/cli/commands/interactive.d.ts.map +1 -0
  62. package/dist/cli/commands/interactive.js +3034 -0
  63. package/dist/cli/commands/interactive.js.map +1 -0
  64. package/dist/cli/commands/list.d.ts +31 -0
  65. package/dist/cli/commands/list.d.ts.map +1 -0
  66. package/dist/cli/commands/list.js +115 -0
  67. package/dist/cli/commands/list.js.map +1 -0
  68. package/dist/cli/commands/providers.d.ts +3 -0
  69. package/dist/cli/commands/providers.d.ts.map +1 -0
  70. package/dist/cli/commands/providers.js +21 -0
  71. package/dist/cli/commands/providers.js.map +1 -0
  72. package/dist/cli/commands/settings.d.ts +22 -0
  73. package/dist/cli/commands/settings.d.ts.map +1 -0
  74. package/dist/cli/commands/settings.js +188 -0
  75. package/dist/cli/commands/settings.js.map +1 -0
  76. package/dist/cli/commands/status.d.ts +16 -0
  77. package/dist/cli/commands/status.d.ts.map +1 -0
  78. package/dist/cli/commands/status.js +148 -0
  79. package/dist/cli/commands/status.js.map +1 -0
  80. package/dist/cli/commands/update.d.ts +21 -0
  81. package/dist/cli/commands/update.d.ts.map +1 -0
  82. package/dist/cli/commands/update.js +95 -0
  83. package/dist/cli/commands/update.js.map +1 -0
  84. package/dist/cli/config.d.ts +73 -0
  85. package/dist/cli/config.d.ts.map +1 -0
  86. package/dist/cli/config.js +239 -0
  87. package/dist/cli/config.js.map +1 -0
  88. package/dist/cli/env.d.ts +36 -0
  89. package/dist/cli/env.d.ts.map +1 -0
  90. package/dist/cli/env.js +74 -0
  91. package/dist/cli/env.js.map +1 -0
  92. package/dist/cli/envelope.d.ts +33 -0
  93. package/dist/cli/envelope.d.ts.map +1 -0
  94. package/dist/cli/envelope.js +62 -0
  95. package/dist/cli/envelope.js.map +1 -0
  96. package/dist/cli/errors.d.ts +48 -0
  97. package/dist/cli/errors.d.ts.map +1 -0
  98. package/dist/cli/errors.js +81 -0
  99. package/dist/cli/errors.js.map +1 -0
  100. package/dist/cli/inference.d.ts +21 -0
  101. package/dist/cli/inference.d.ts.map +1 -0
  102. package/dist/cli/inference.js +60 -0
  103. package/dist/cli/inference.js.map +1 -0
  104. package/dist/cli/logo.d.ts +21 -0
  105. package/dist/cli/logo.d.ts.map +1 -0
  106. package/dist/cli/logo.js +131 -0
  107. package/dist/cli/logo.js.map +1 -0
  108. package/dist/cli/main.d.ts +14 -0
  109. package/dist/cli/main.d.ts.map +1 -0
  110. package/dist/cli/main.js +223 -0
  111. package/dist/cli/main.js.map +1 -0
  112. package/dist/cli/proofs.d.ts +67 -0
  113. package/dist/cli/proofs.d.ts.map +1 -0
  114. package/dist/cli/proofs.js +133 -0
  115. package/dist/cli/proofs.js.map +1 -0
  116. package/dist/cli/ref.d.ts +39 -0
  117. package/dist/cli/ref.d.ts.map +1 -0
  118. package/dist/cli/ref.js +48 -0
  119. package/dist/cli/ref.js.map +1 -0
  120. package/dist/cli/sdk.d.ts +24 -0
  121. package/dist/cli/sdk.d.ts.map +1 -0
  122. package/dist/cli/sdk.js +65 -0
  123. package/dist/cli/sdk.js.map +1 -0
  124. package/dist/cli/settings.d.ts +66 -0
  125. package/dist/cli/settings.d.ts.map +1 -0
  126. package/dist/cli/settings.js +137 -0
  127. package/dist/cli/settings.js.map +1 -0
  128. package/dist/cli/tokenize.d.ts +61 -0
  129. package/dist/cli/tokenize.d.ts.map +1 -0
  130. package/dist/cli/tokenize.js +157 -0
  131. package/dist/cli/tokenize.js.map +1 -0
  132. package/dist/cli/types.d.ts +25 -0
  133. package/dist/cli/types.d.ts.map +1 -0
  134. package/dist/cli/types.js +8 -0
  135. package/dist/cli/types.js.map +1 -0
  136. package/dist/constants.d.ts +107 -0
  137. package/dist/constants.d.ts.map +1 -0
  138. package/dist/constants.js +74 -0
  139. package/dist/constants.js.map +1 -0
  140. package/dist/context.d.ts +108 -0
  141. package/dist/context.d.ts.map +1 -0
  142. package/dist/context.js +64 -0
  143. package/dist/context.js.map +1 -0
  144. package/dist/index.d.ts +45 -0
  145. package/dist/index.d.ts.map +1 -0
  146. package/dist/index.js +118 -0
  147. package/dist/index.js.map +1 -0
  148. package/dist/provider-catalog.json +23 -0
  149. package/dist/seal.d.ts +47 -0
  150. package/dist/seal.d.ts.map +1 -0
  151. package/dist/seal.js +145 -0
  152. package/dist/seal.js.map +1 -0
  153. package/dist/secretEnv.d.ts +119 -0
  154. package/dist/secretEnv.d.ts.map +1 -0
  155. package/dist/secretEnv.js +199 -0
  156. package/dist/secretEnv.js.map +1 -0
  157. package/dist/taskHash.d.ts +39 -0
  158. package/dist/taskHash.d.ts.map +1 -0
  159. package/dist/taskHash.js +119 -0
  160. package/dist/taskHash.js.map +1 -0
  161. package/dist/types.d.ts +336 -0
  162. package/dist/types.d.ts.map +1 -0
  163. package/dist/types.js +19 -0
  164. package/dist/types.js.map +1 -0
  165. package/package.json +75 -4
  166. package/scripts/sync-providers.cjs +8 -0
  167. package/src/AgentClient.ts +897 -0
  168. package/src/AgenticID.ts +1382 -0
  169. package/src/AgenticIDClient.ts +238 -0
  170. package/src/AttestorClient.ts +1306 -0
  171. package/src/Providers.ts +176 -0
  172. package/src/ReputationClient.ts +821 -0
  173. package/src/SandboxClient.ts +227 -0
  174. package/src/ServeProof.ts +290 -0
  175. package/src/ServeSession.ts +421 -0
  176. package/src/Settings.ts +296 -0
  177. package/src/abi.ts +1282 -0
  178. package/src/cli/commands/cells.ts +61 -0
  179. package/src/cli/commands/doctor.ts +235 -0
  180. package/src/cli/commands/interactive.ts +2715 -0
  181. package/src/cli/commands/list.ts +117 -0
  182. package/src/cli/commands/providers.ts +16 -0
  183. package/src/cli/commands/settings.ts +197 -0
  184. package/src/cli/commands/status.ts +170 -0
  185. package/src/cli/commands/update.ts +86 -0
  186. package/src/cli/config.ts +225 -0
  187. package/src/cli/env.ts +90 -0
  188. package/src/cli/envelope.ts +57 -0
  189. package/src/cli/errors.ts +114 -0
  190. package/src/cli/inference.ts +57 -0
  191. package/src/cli/logo.ts +125 -0
  192. package/src/cli/main.ts +235 -0
  193. package/src/cli/proofs.ts +160 -0
  194. package/src/cli/ref.ts +58 -0
  195. package/src/cli/sdk.ts +65 -0
  196. package/src/cli/settings.ts +153 -0
  197. package/src/cli/tokenize.ts +131 -0
  198. package/src/cli/types.ts +27 -0
  199. package/src/constants.ts +106 -0
  200. package/src/context.ts +161 -0
  201. package/src/index.ts +129 -0
  202. package/src/provider-catalog.json +23 -0
  203. package/src/seal.ts +163 -0
  204. package/src/secretEnv.ts +250 -0
  205. package/src/taskHash.ts +100 -0
  206. package/src/types.ts +357 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 0G Foundation
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/MIGRATION.md ADDED
@@ -0,0 +1,84 @@
1
+ # Upgrading to 0G AgentDNA
2
+
3
+ The npm package is now `@0gfoundation/0g-agentdna`, published under the
4
+ 0gfoundation organization, and the CLI command is `0g-agentdna`. The SDK
5
+ exposes `AgentDNA` and `AgentDNAConfig`; the existing `AgenticID` and
6
+ `AgenticIDConfig` exports remain compatible. Contract names and signed-message
7
+ domains retain their protocol identifiers.
8
+
9
+ ## Existing CLI users
10
+
11
+ After the matching canonical and compatibility releases are published, quit
12
+ the interactive CLI and run these commands in your system terminal:
13
+
14
+ ```bash
15
+ 0g-agenticid update
16
+ 0g-agentdna --version
17
+ 0g-agentdna
18
+ ```
19
+
20
+ The old updater reads the old npm package's `latest` tag. Its compatibility
21
+ release installs the matching canonical SDK and provides both command names.
22
+ Subsequent updates use `0g-agentdna update`. When launched through the bridge,
23
+ the updater updates that bridge package so npm retains ownership of its
24
+ global command links.
25
+
26
+ Fresh installations use `npm install -g @0gfoundation/0g-agentdna`. A
27
+ development checkout uses the repository build workflow instead of the npm
28
+ self-updater.
29
+
30
+ A `0g-agentdna` package without the scope was published briefly and is deprecated.
31
+ If you installed it, replace it; both own the `0g-agentdna` command:
32
+
33
+ ```bash
34
+ npm uninstall -g 0g-agentdna
35
+ npm install -g @0gfoundation/0g-agentdna
36
+ ```
37
+
38
+ ## Local configuration
39
+
40
+ On first access, the CLI moves `~/.config/0g-agenticid/` to
41
+ `~/.config/0g-agentdna/` if the destination does not already exist.
42
+ `XDG_CONFIG_HOME` replaces `~/.config` when set. The move preserves all files
43
+ and permissions, including credentials, proof tickets, secret-env downgrade
44
+ pins, and update-hint state. No new login is required.
45
+
46
+ If both directories exist, the AgentDNA directory wins and the legacy
47
+ directory is left intact. A failed move stops with a migration error instead
48
+ of creating an empty replacement. Existing `AGENTIC_*` environment variables
49
+ remain supported.
50
+
51
+
52
+ The old credential field `apiKey` is atomically converted to
53
+ `inferenceKeys["0g-compute"]`, preserving wallet and other provider keys.
54
+ Legacy `AGENTIC_API_KEY` / `API_KEY` overrides remain compute-only. Register
55
+ additional keys with `login <provider>` inside the manager; use `settings`
56
+ then `reset` to switch an existing agent. See [providers](./PROVIDERS.md).
57
+
58
+ ## SDK applications
59
+
60
+ ```typescript
61
+ import { AgentDNA, type AgentDNAConfig } from '@0gfoundation/0g-agentdna';
62
+ import { sealAccount } from '@0gfoundation/0g-agentdna/seal';
63
+ ```
64
+
65
+ Existing imports from `@0gfoundation/0g-agenticid-sdk` and its `/seal` subpath
66
+ continue through the compatibility package. They can be changed when updating
67
+ the application's dependencies.
68
+
69
+ ## Release order
70
+
71
+ 1. Align the canonical package version, lockfile, `SDK_VERSION`, and the
72
+ compatibility manifest's version and exact dependency.
73
+ 2. Run SDK typecheck and tests, and inspect both npm package contents.
74
+ 3. Publish `@0gfoundation/0g-agentdna` from `sdk/typescript`.
75
+ 4. Publish `@0gfoundation/0g-agenticid-sdk` from `sdk/typescript/compat/legacy`
76
+ at the same version after its canonical dependency is available. Repeat
77
+ this step for each release while supporting the old update path.
78
+ 5. Set the attestor's `ATTESTOR_CLI_LATEST` and `ATTESTOR_CLI_NOTES` after both
79
+ packages are available. Mention the rename in the notes for old clients.
80
+
81
+ Publishing only the new package does not upgrade clients that query the old
82
+ package. Repository changes alone do not publish either package.
83
+
84
+ 中文:[MIGRATION.zh.md](MIGRATION.zh.md)。
@@ -0,0 +1,70 @@
1
+ # 升级到 0G AgentDNA
2
+
3
+ npm 包名现为 `@0gfoundation/0g-agentdna`,发布在 0gfoundation 组织下;
4
+ CLI 命令为 `0g-agentdna`。SDK 提供 `AgentDNA` 和 `AgentDNAConfig`,原有
5
+ `AgenticID` 和 `AgenticIDConfig` 导出继续兼容。合约名称和签名消息域沿用协议标识符。
6
+
7
+ ## 已有 CLI 用户
8
+
9
+ 在主包和对应兼容包发布后,退出交互 CLI,在系统终端执行:
10
+
11
+ ```bash
12
+ 0g-agenticid update
13
+ 0g-agentdna --version
14
+ 0g-agentdna
15
+ ```
16
+
17
+ 旧 updater 查询旧 npm 包的 `latest` 标签;兼容版本会安装对应版本的主 SDK,
18
+ 并提供新旧两个命令。此后使用 `0g-agentdna update` 更新。通过兼容入口启动时,
19
+ updater 会更新该兼容包,保证全局命令链接仍由原包管理。
20
+
21
+ 新安装使用 `npm install -g @0gfoundation/0g-agentdna`。开发检出使用仓库的
22
+ 构建流程,不通过 npm 自更新命令覆盖。
23
+
24
+ 不带组织前缀的 `0g-agentdna` 包曾短暂发布,现已弃用。装过它的用户需要替换,
25
+ 因为两个包都提供 `0g-agentdna` 命令:
26
+
27
+ ```bash
28
+ npm uninstall -g 0g-agentdna
29
+ npm install -g @0gfoundation/0g-agentdna
30
+ ```
31
+
32
+ ## 本地配置
33
+
34
+ 首次访问时,如果新目录尚不存在,CLI 会将 `~/.config/0g-agenticid/` 移动到
35
+ `~/.config/0g-agentdna/`;设置 `XDG_CONFIG_HOME` 时以该目录替代 `~/.config`。
36
+ 迁移保留所有文件及权限,包括凭据、proof tickets、secret-env 降级保护记录和
37
+ 更新提示记录,无需重新登录。
38
+
39
+ 如果新旧目录同时存在,使用 AgentDNA 目录,保留旧目录。如果移动失败,明确报告
40
+ 迁移错误,不创建空配置替代。已有的 `AGENTIC_*` 环境变量继续支持。
41
+
42
+
43
+ 旧凭据字段 `apiKey` 会原子转换为 `inferenceKeys["0g-compute"]`,保留钱包及
44
+ 其他 provider 的 key。旧 `AGENTIC_API_KEY` / `API_KEY` 覆盖仅属于 compute。
45
+ 在 manager 内通过 `login <provider>` 登记新 key,再用 `settings`、`reset`
46
+ 切换已有 agent,见 [provider 说明](./PROVIDERS.zh.md)。
47
+
48
+ ## SDK 应用
49
+
50
+ ```typescript
51
+ import { AgentDNA, type AgentDNAConfig } from '@0gfoundation/0g-agentdna';
52
+ import { sealAccount } from '@0gfoundation/0g-agentdna/seal';
53
+ ```
54
+
55
+ 原有 `@0gfoundation/0g-agenticid-sdk` 及其 `/seal` 导入路径通过兼容包继续可用;
56
+ 应用可以在更新依赖时改用新包名。
57
+
58
+ ## 发布顺序
59
+
60
+ 1. 同步主包版本、lockfile、`SDK_VERSION`,以及兼容包版本和精确依赖版本。
61
+ 2. 执行 SDK 类型检查和测试,检查两个 npm 包的打包内容。
62
+ 3. 从 `sdk/typescript` 发布 `@0gfoundation/0g-agentdna`。
63
+ 4. 主包对应版本可用后,从 `sdk/typescript/compat/legacy` 发布同版本的
64
+ `@0gfoundation/0g-agenticid-sdk`;在支持旧更新入口期间,每次发版均发布兼容包。
65
+ 5. 两个包均可用后再更新 attestor 的 `ATTESTOR_CLI_LATEST` 和
66
+ `ATTESTOR_CLI_NOTES`,在说明中告知旧客户端改名事项。
67
+
68
+ 只发布新包,无法升级仍查询旧包的客户端。修改仓库本身不会发布任何 npm 包。
69
+
70
+ English: [MIGRATION.md](MIGRATION.md).
package/PROVIDERS.md ADDED
@@ -0,0 +1,273 @@
1
+ # Inference providers
2
+
3
+ The attestor serves the platform registry at `GET /inference/providers`.
4
+ Operators publish revisions through `PUT /admin/inference/providers`. Updates
5
+ are stored in Postgres, shared by API replicas, and survive restarts. No SSH,
6
+ server-side file replacement, OSS, or process restart is needed for publication.
7
+ The public registry contains routing/model metadata, never inference keys.
8
+
9
+ ## First rollout
10
+
11
+ Upgrade the SDK/CLI, attestor, and all configured sealed images together.
12
+ Update the existing `ATTESTOR_SANDBOX_SNAPSHOT` / `ATTESTOR_FRAMEWORKS` values
13
+ for that release and enable the existing encrypted credential switch:
14
+
15
+ ```bash
16
+ ATTESTOR_SECRET_ENV_ENABLED=true
17
+ ```
18
+
19
+ Build and upload all sealed images first, then upgrade attestor API, worker,
20
+ indexer and activate the matching images together. Existing agents enter the
21
+ new image through reset. The worker injects `SEAL_BOOT_TICKET` internally;
22
+ operators do not configure it, and the new image refuses to boot without it.
23
+ Stop/start preserves the ticket and authorized provider route while rotating
24
+ the boot generation. Reset replaces the ticket and can authorize a provider.
25
+ Rejected provision requests do not mutate or delete containers.
26
+
27
+ No administrator or image-capability ENV is added. Administrative writes use
28
+ the **current owner of the attestor's Tapp**, read from `getAppInfo` using the
29
+ existing `ATTESTOR_APP_ID` and `ATTESTOR_TAPP_REGISTRY_ADDR`. They do not use
30
+ the attestor TEE signing key, the owner of an agent, or the sandbox's admin list.
31
+ Missing/unregistered Tapp configuration or RPC failure refuses publication.
32
+
33
+ `GET /config` derives image capabilities from this release and its configured
34
+ framework/snapshot names. Hermes advertises managed OpenAI only; the other
35
+ bundled adapters advertise managed OpenAI and Anthropic. Native wiring and
36
+ credential versions are also declared automatically. Explicit unknown images
37
+ are not advertised. The deployment contract is one uniform release, not a mix
38
+ of old and new configured runtime images.
39
+
40
+ Existing CLI users can run `0g-agenticid update` after the canonical and legacy
41
+ compatibility packages are published. Their old key migrates atomically to
42
+ `inferenceKeys["0g-compute"]`; wallet keys, other provider keys, proof tickets,
43
+ and secret-env downgrade pins are preserved. See [migration](./MIGRATION.md).
44
+
45
+ ## Publish a provider
46
+
47
+ Provider updates are attestor operations, exposed through the HTTP API and SDK
48
+ for use in an operations script or backend. The CLI only reads the registry;
49
+ it has no provider publication command.
50
+
51
+ Read the current version and definitions:
52
+
53
+ ```bash
54
+ curl -fsS "$ATTESTOR_URL/inference/providers" > providers.json
55
+ # Edit providers; keep version unchanged.
56
+ ```
57
+
58
+ In an operations script, use an SDK client configured with the attestor Tapp
59
+ owner's wallet to sign and submit the edited definitions:
60
+
61
+ ```typescript
62
+ import { readFileSync } from 'node:fs';
63
+ import { AgentDNA } from '@0gfoundation/0g-agentdna';
64
+
65
+ const ag = await AgentDNA.fromAttestor(attestorUrl, { account });
66
+ const edited = JSON.parse(readFileSync('providers.json', 'utf8'));
67
+ await ag.admin.updateProviders(edited.providers, { baseVersion: edited.version });
68
+ ```
69
+
70
+ Only the signed document is uploaded; the private key stays with the signing
71
+ wallet. The file's original version protects the read/edit/publish interval.
72
+ Publication replaces the full list, so retain the existing entries. External
73
+ signers can prepare and submit the signed HTTP request as described below.
74
+
75
+ For example, append a managed provider to the exported list:
76
+
77
+ ```json
78
+ {
79
+ "id": "partner",
80
+ "name": "Partner",
81
+ "formats": ["openai"],
82
+ "defaultFormat": "openai",
83
+ "endpoints": {"openai": "https://partner.example/v1"},
84
+ "models": [{
85
+ "id": "model-id",
86
+ "supported_formats": ["openai"],
87
+ "supported_parameters": ["tools"],
88
+ "context_length": 128000,
89
+ "max_completion_tokens": 16000
90
+ }]
91
+ }
92
+ ```
93
+
94
+ The host is a placeholder. Use a static list or a public `modelCatalog` URL
95
+ returning `{ "data": [...] }`. ID-only catalogs leave model capabilities
96
+ unknown. Protocols are restricted to the implemented OpenAI/Anthropic paths;
97
+ a provider requiring another protocol or authentication scheme still needs a
98
+ code release. Endpoints/catalogs must be HTTPS without embedded credentials,
99
+ query strings, or fragments. Compatibility flags belong to their provider;
100
+ additional managed providers do not inherit compute metadata or routing guesses.
101
+ `0g-compute` must remain in the registry. The only native IDs are `openai` and
102
+ `anthropic`; they have no custom endpoints and use framework-native wiring.
103
+
104
+ ## Publication API
105
+
106
+ `PUT /admin/inference/providers` accepts:
107
+
108
+ ```json
109
+ {"document":"<exact JSON string>","signature":"0x<EIP-191 signature>"}
110
+ ```
111
+
112
+ The document contains `schema:1`, `chain_id`, `agentic_id_addr`, `base_version`,
113
+ `tapp_registry_addr`, `attestor_app_id`, `expires_at` (Unix seconds), and `providers`. Sign the message
114
+ `AgentDNA.ProviderRegistry.v1:<sha256(document UTF-8 bytes), lowercase hex without 0x>`.
115
+ The signature covers the exact supplied bytes, not a separate serialization.
116
+ The publication request must expire within the next 300 seconds; the SDK uses
117
+ 180. This is the request validity window, not an expiry of accepted settings.
118
+
119
+ The server checks the exact chain/contract/Tapp scope, live Tapp-owner
120
+ authorization, structure, and version before committing. EOA signatures use
121
+ EIP-191; contract-wallet owners are verified through
122
+ [EIP-1271](https://eips.ethereum.org/EIPS/eip-1271). Success returns `{ok:true,version}`. Concurrent/stale/replayed
123
+ updates return HTTP 409 with the current `version`; the SDK surfaces that
124
+ failure without retrying. Read again and reapply the edit. To roll
125
+ back content, publish it as a new revision; old revisions remain in history.
126
+
127
+ `GET /inference/providers` returns `version`, `providers`, and, for published
128
+ revisions, the exact signed `document` and `signature`. When `/config` advertises
129
+ the registry, read failures including 404 stop credential sealing/signing;
130
+ they never substitute the built-in seed. Version 0 is the
131
+ built-in seed from `sealed/internal/inference/providers.json`; SDK builds also
132
+ bundle that seed for old attestors/offline discovery. Published data is not
133
+ compiled into the SDK or image. The API stores a KMS-derived acceptance MAC over
134
+ the environment, Tapp, version, publisher, and exact signed envelope. Database
135
+ edits cannot forge that receipt. Accepted revisions remain readable after a
136
+ Tapp ownership transfer or wallet-policy change; every new write checks the
137
+ current owner again, so an old owner cannot continue publishing.
138
+
139
+ The trusted attestor's `/config` publishes `provider_registry_version` and
140
+ `provider_registry_digest`, computed only from a verified acceptance record.
141
+ SDK and sealed check that fingerprint, the exact document contents, and scope
142
+ before using the registry. This uses the same trusted-attestor discovery
143
+ boundary as contract addresses and snapshots; it is not an independent trust
144
+ anchor. SDK instances reject lower/conflicting seen revisions.
145
+
146
+ An unreadable `/config` also stops the operation instead of being treated as
147
+ an old attestor. Initial discovery pins advertised capabilities, so later reads
148
+ cannot withdraw registry support. Concurrent refreshes share a request only
149
+ when all version, digest and environment constraints match; other callers
150
+ validate their own discovery result.
151
+
152
+ ## Use the provider
153
+
154
+ Inside the interactive `0g-agentdna` manager:
155
+
156
+ ```text
157
+ login partner
158
+ settings 42 provider=partner model=model-id
159
+ reset 42
160
+ ```
161
+
162
+ The CLI refreshes the registry before provider selection. `login` preserves
163
+ other keys and sets the default for future deploy/login operations. Existing
164
+ agents read their provider from owner settings on reset, not the global
165
+ default. An unreadable settings row stops the operation. `whoami` shows key
166
+ presence, never values. Completion uses each provider's model list.
167
+
168
+ Provider changes are saved as pending reset and do not push the old credential
169
+ to a new service. Same-provider model/thinking edits retain hot apply. A
170
+ credential/provider/route mismatch reports reset required. Reset recreates the
171
+ container using the existing compatible image and interrupts running work;
172
+ it does not require rebuilding that image. An owner-authorized fresh sandbox
173
+ resets the current unconfirmed settings attempt counter before creation, so
174
+ reset retries that document with its matching key after a failed startup.
175
+ Content, versions, and last-known-good are preserved. Automatic reboots still
176
+ use the existing fallback policy and credential checks. Publishing a provider
177
+ does not restart any existing agent.
178
+
179
+ Legacy `AGENTIC_API_KEY` / `API_KEY` overrides are compute-only. Provider-scoped
180
+ overrides use both `AGENTDNA_API_KEY_PROVIDER` and `AGENTDNA_API_KEY`. An unbound
181
+ new override is rejected. Keys are collected through masked input/environment,
182
+ never argv, and kept locally in `inferenceKeys[provider]` at mode 0600.
183
+
184
+ ## Reading an agent's current configuration
185
+
186
+ The owner's `0g-agentdna settings <agent>` / `ag.agent.getSettings(sealId)` reads
187
+ attestor's document stored in Postgres, which can include changes awaiting reset.
188
+ An agent reads the configuration adopted by its runtime through its internal socket:
189
+
190
+ ```bash
191
+ curl --unix-socket "$SEAL_SIGN_SOCK" http://localhost/settings
192
+ ```
193
+
194
+ The response comes from sealed's successfully rendered runtime state. It includes
195
+ `source: "runtime"`, provider, model, thinking, and the managed route's `base_url`,
196
+ `format`, `registry_version` and `route_hash`. Native framework routes omit
197
+ `base_url`. It returns neither API keys nor arbitrary framework configuration,
198
+ and does not query the attestor's latest settings. Before readiness it returns
199
+ 503. Unsigned reads exist only on the 0600 internal socket; public HTTP
200
+ `/_seal/settings` remains owner-signed.
201
+
202
+ ## SDK
203
+
204
+ ```typescript
205
+ const ag = await AgentDNA.fromAttestor(attestorUrl, { account });
206
+ ag.agent.listProviders(); // cached; fromAttestor loads modern registries
207
+ await ag.agent.refreshProviders(); // get a new verified snapshot
208
+ await ag.agent.listModels({ provider: 'partner' });
209
+
210
+ const { settings, version } = await ag.agent.getSettings(sealId);
211
+ await ag.agent.setSettings(sealId, {
212
+ ...(settings ?? {}), provider: 'partner', model: 'model-id',
213
+ }, { baseVersion: version });
214
+ await ag.agent.reset(sealId, { provider: 'partner', apiKey: partnerKey });
215
+
216
+ // Attestor Tapp owner's wallet only:
217
+ const current = await ag.agent.getProviderRegistry();
218
+ await ag.admin.updateProviders(updatedProviders, { baseVersion: current.version });
219
+ ```
220
+
221
+ For a contract-wallet owner, a read-only client can prepare the exact message,
222
+ obtain the wallet's EIP-1271 signature externally, then relay it without holding
223
+ an owner private key:
224
+
225
+ ```typescript
226
+ const request = await ag.admin.prepareProviderUpdate(updatedProviders, {
227
+ baseVersion: current.version,
228
+ });
229
+ // Obtain signature for request.message from the owner wallet within its expiry.
230
+ await ag.admin.publishSignedProviders({ document: request.document, signature });
231
+ ```
232
+
233
+
234
+ No-argument model listing remains compute. Native providers without a configured
235
+ catalog accept manual model IDs. For fresh non-compute agents or changed compute
236
+ routes, deploy without `sandbox`, wait for mint, store provider/model settings,
237
+ then `start` with its provider/key/framework. The CLI wizard rechecks the current
238
+ registry after its prompts and performs this sequence. Only the unchanged
239
+ built-in compute route supports one-shot deployment. Other one-shot attempts
240
+ are refused before signing.
241
+
242
+ ## Credential and runtime binding
243
+
244
+ Dynamic routes use the existing ECIES encryption with v3 plaintext:
245
+
246
+ ```json
247
+ {"v":3,"owner":"0x...","provider":"partner","route_hash":"0x...","registry":{"version":1,"digest":"0x..."},"env":{"API_KEY":"..."}}
248
+ ```
249
+
250
+ The route hash covers provider ID, native/managed mode, formats, default format,
251
+ and fixed endpoints. SDK/Go share a fixed field-order encoding and cross-language
252
+ fixtures. Model metadata is excluded. V3 requires a matching image capability;
253
+ there is no plaintext downgrade. `sealApiKey` supports the same binding for
254
+ server-side sealing; submit its opaque result with the same provider.
255
+
256
+ V3 also binds the accepted registry's `registry.version` and `registry.digest`.
257
+ Sealed opens the credential against the live owner, retrieves that historical
258
+ version through `GET /inference/providers?version=N`, and verifies the document
259
+ digest and route hash before catalog access/configuration writes. Postgres
260
+ retains accepted history. Stop/start uses the original credential and version,
261
+ even after an endpoint changes or its provider is removed from the latest list.
262
+ Publication between signing and first boot also preserves the authorized route.
263
+ Reset binds a fresh credential to the new version and route. Missing, tampered
264
+ or unavailable history fails closed; it never substitutes the latest endpoint.
265
+ If the owner has saved settings for another provider, reset is still required:
266
+ stop/start cannot supply credentials for that new provider.
267
+ Legacy plaintext/v1 keys remain compute-only; v2 remains compatible with the
268
+ built-in native definitions. Invalid ciphertext never falls back to a separate
269
+ plaintext key. Registry fetch/acceptance verification failure does not substitute compute.
270
+ These controls govern platform-rendered routing and credentials, not all
271
+ network activity of the framework.
272
+
273
+ 中文:[PROVIDERS.zh.md](PROVIDERS.zh.md)。