@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.
Files changed (255) hide show
  1. package/GUIDE.md +190 -40
  2. package/OPERATORS.md +164 -0
  3. package/OPERATORS.zh.md +141 -0
  4. package/PROVIDERS.md +6 -0
  5. package/PROVIDERS.zh.md +3 -1
  6. package/README.md +84 -11
  7. package/dist/AgentClient.d.ts +374 -26
  8. package/dist/AgentClient.d.ts.map +1 -1
  9. package/dist/AgentClient.js +323 -40
  10. package/dist/AgentClient.js.map +1 -1
  11. package/dist/AgenticID.d.ts +170 -80
  12. package/dist/AgenticID.d.ts.map +1 -1
  13. package/dist/AgenticID.js +300 -42
  14. package/dist/AgenticID.js.map +1 -1
  15. package/dist/AttestorClient.d.ts +115 -31
  16. package/dist/AttestorClient.d.ts.map +1 -1
  17. package/dist/AttestorClient.js +276 -56
  18. package/dist/AttestorClient.js.map +1 -1
  19. package/dist/Credentials.d.ts +574 -0
  20. package/dist/Credentials.d.ts.map +1 -0
  21. package/dist/Credentials.js +838 -0
  22. package/dist/Credentials.js.map +1 -0
  23. package/dist/Operators.d.ts +60 -0
  24. package/dist/Operators.d.ts.map +1 -0
  25. package/dist/Operators.js +38 -0
  26. package/dist/Operators.js.map +1 -0
  27. package/dist/Providers.d.ts +13 -0
  28. package/dist/Providers.d.ts.map +1 -1
  29. package/dist/Providers.js +20 -1
  30. package/dist/Providers.js.map +1 -1
  31. package/dist/Releases.d.ts +51 -0
  32. package/dist/Releases.d.ts.map +1 -0
  33. package/dist/Releases.js +72 -0
  34. package/dist/Releases.js.map +1 -0
  35. package/dist/ReputationClient.d.ts +47 -3
  36. package/dist/ReputationClient.d.ts.map +1 -1
  37. package/dist/ReputationClient.js +204 -78
  38. package/dist/ReputationClient.js.map +1 -1
  39. package/dist/ServeProof.d.ts +70 -23
  40. package/dist/ServeProof.d.ts.map +1 -1
  41. package/dist/ServeProof.js +94 -35
  42. package/dist/ServeProof.js.map +1 -1
  43. package/dist/ServeSession.d.ts +17 -2
  44. package/dist/ServeSession.d.ts.map +1 -1
  45. package/dist/ServeSession.js +77 -9
  46. package/dist/ServeSession.js.map +1 -1
  47. package/dist/Settings.d.ts +25 -1
  48. package/dist/Settings.d.ts.map +1 -1
  49. package/dist/Settings.js +53 -1
  50. package/dist/Settings.js.map +1 -1
  51. package/dist/TrustRegistry.d.ts +28 -0
  52. package/dist/TrustRegistry.d.ts.map +1 -0
  53. package/dist/TrustRegistry.js +67 -0
  54. package/dist/TrustRegistry.js.map +1 -0
  55. package/dist/abi.d.ts +346 -34
  56. package/dist/abi.d.ts.map +1 -1
  57. package/dist/abi.js +150 -30
  58. package/dist/abi.js.map +1 -1
  59. package/dist/cli/attach.d.ts +79 -0
  60. package/dist/cli/attach.d.ts.map +1 -0
  61. package/dist/cli/attach.js +253 -0
  62. package/dist/cli/attach.js.map +1 -0
  63. package/dist/cli/commands/cells.d.ts +45 -0
  64. package/dist/cli/commands/cells.d.ts.map +1 -1
  65. package/dist/cli/commands/cells.js +77 -0
  66. package/dist/cli/commands/cells.js.map +1 -1
  67. package/dist/cli/commands/cred.d.ts +12 -0
  68. package/dist/cli/commands/cred.d.ts.map +1 -0
  69. package/dist/cli/commands/cred.js +43 -0
  70. package/dist/cli/commands/cred.js.map +1 -0
  71. package/dist/cli/commands/doctor.d.ts.map +1 -1
  72. package/dist/cli/commands/doctor.js +44 -35
  73. package/dist/cli/commands/doctor.js.map +1 -1
  74. package/dist/cli/commands/interactive.d.ts +597 -21
  75. package/dist/cli/commands/interactive.d.ts.map +1 -1
  76. package/dist/cli/commands/interactive.js +5082 -1323
  77. package/dist/cli/commands/interactive.js.map +1 -1
  78. package/dist/cli/commands/list.d.ts +5 -5
  79. package/dist/cli/commands/list.d.ts.map +1 -1
  80. package/dist/cli/commands/list.js +21 -26
  81. package/dist/cli/commands/list.js.map +1 -1
  82. package/dist/cli/commands/providers.d.ts +4 -0
  83. package/dist/cli/commands/providers.d.ts.map +1 -1
  84. package/dist/cli/commands/providers.js +19 -5
  85. package/dist/cli/commands/providers.js.map +1 -1
  86. package/dist/cli/commands/releases.d.ts +13 -0
  87. package/dist/cli/commands/releases.d.ts.map +1 -0
  88. package/dist/cli/commands/releases.js +65 -0
  89. package/dist/cli/commands/releases.js.map +1 -0
  90. package/dist/cli/commands/settings.d.ts +5 -0
  91. package/dist/cli/commands/settings.d.ts.map +1 -1
  92. package/dist/cli/commands/settings.js +70 -24
  93. package/dist/cli/commands/settings.js.map +1 -1
  94. package/dist/cli/commands/status.d.ts +2 -1
  95. package/dist/cli/commands/status.d.ts.map +1 -1
  96. package/dist/cli/commands/status.js +22 -19
  97. package/dist/cli/commands/status.js.map +1 -1
  98. package/dist/cli/config.d.ts +48 -1
  99. package/dist/cli/config.d.ts.map +1 -1
  100. package/dist/cli/config.js +114 -5
  101. package/dist/cli/config.js.map +1 -1
  102. package/dist/cli/credentials.d.ts +179 -0
  103. package/dist/cli/credentials.d.ts.map +1 -0
  104. package/dist/cli/credentials.js +1443 -0
  105. package/dist/cli/credentials.js.map +1 -0
  106. package/dist/cli/download.d.ts +21 -0
  107. package/dist/cli/download.d.ts.map +1 -0
  108. package/dist/cli/download.js +89 -0
  109. package/dist/cli/download.js.map +1 -0
  110. package/dist/cli/env.d.ts +6 -0
  111. package/dist/cli/env.d.ts.map +1 -1
  112. package/dist/cli/env.js +18 -6
  113. package/dist/cli/env.js.map +1 -1
  114. package/dist/cli/envelope.d.ts +4 -2
  115. package/dist/cli/envelope.d.ts.map +1 -1
  116. package/dist/cli/envelope.js +10 -6
  117. package/dist/cli/envelope.js.map +1 -1
  118. package/dist/cli/errors.d.ts +45 -1
  119. package/dist/cli/errors.d.ts.map +1 -1
  120. package/dist/cli/errors.js +77 -0
  121. package/dist/cli/errors.js.map +1 -1
  122. package/dist/cli/inference.d.ts.map +1 -1
  123. package/dist/cli/inference.js +7 -0
  124. package/dist/cli/inference.js.map +1 -1
  125. package/dist/cli/inkView.d.ts +341 -0
  126. package/dist/cli/inkView.d.ts.map +1 -0
  127. package/dist/cli/inkView.js +1019 -0
  128. package/dist/cli/inkView.js.map +1 -0
  129. package/dist/cli/legacy/modelKey.d.ts +24 -0
  130. package/dist/cli/legacy/modelKey.d.ts.map +1 -0
  131. package/dist/cli/legacy/modelKey.js +32 -0
  132. package/dist/cli/legacy/modelKey.js.map +1 -0
  133. package/dist/cli/livePrompt.d.ts +212 -0
  134. package/dist/cli/livePrompt.d.ts.map +1 -0
  135. package/dist/cli/livePrompt.js +576 -0
  136. package/dist/cli/livePrompt.js.map +1 -0
  137. package/dist/cli/main.js +206 -72
  138. package/dist/cli/main.js.map +1 -1
  139. package/dist/cli/modelkey.d.ts +64 -0
  140. package/dist/cli/modelkey.d.ts.map +1 -0
  141. package/dist/cli/modelkey.js +113 -0
  142. package/dist/cli/modelkey.js.map +1 -0
  143. package/dist/cli/outboxSync.d.ts +51 -0
  144. package/dist/cli/outboxSync.d.ts.map +1 -0
  145. package/dist/cli/outboxSync.js +210 -0
  146. package/dist/cli/outboxSync.js.map +1 -0
  147. package/dist/cli/plain.d.ts +46 -0
  148. package/dist/cli/plain.d.ts.map +1 -0
  149. package/dist/cli/plain.js +260 -0
  150. package/dist/cli/plain.js.map +1 -0
  151. package/dist/cli/proofs.d.ts +5 -0
  152. package/dist/cli/proofs.d.ts.map +1 -1
  153. package/dist/cli/proofs.js +20 -0
  154. package/dist/cli/proofs.js.map +1 -1
  155. package/dist/cli/ref.d.ts.map +1 -1
  156. package/dist/cli/ref.js +3 -2
  157. package/dist/cli/ref.js.map +1 -1
  158. package/dist/cli/releaseNotice.d.ts +64 -0
  159. package/dist/cli/releaseNotice.d.ts.map +1 -0
  160. package/dist/cli/releaseNotice.js +194 -0
  161. package/dist/cli/releaseNotice.js.map +1 -0
  162. package/dist/cli/sdk.d.ts +18 -0
  163. package/dist/cli/sdk.d.ts.map +1 -1
  164. package/dist/cli/sdk.js +99 -1
  165. package/dist/cli/sdk.js.map +1 -1
  166. package/dist/cli/settings.d.ts +87 -6
  167. package/dist/cli/settings.d.ts.map +1 -1
  168. package/dist/cli/settings.js +270 -18
  169. package/dist/cli/settings.js.map +1 -1
  170. package/dist/cli/textfit.d.ts +28 -0
  171. package/dist/cli/textfit.d.ts.map +1 -0
  172. package/dist/cli/textfit.js +111 -0
  173. package/dist/cli/textfit.js.map +1 -0
  174. package/dist/constants.d.ts +1 -1
  175. package/dist/constants.js +1 -1
  176. package/dist/context.d.ts +26 -0
  177. package/dist/context.d.ts.map +1 -1
  178. package/dist/context.js +1 -0
  179. package/dist/context.js.map +1 -1
  180. package/dist/index.d.ts +19 -11
  181. package/dist/index.d.ts.map +1 -1
  182. package/dist/index.js +35 -2
  183. package/dist/index.js.map +1 -1
  184. package/dist/legacy/modelKey.d.ts +67 -0
  185. package/dist/legacy/modelKey.d.ts.map +1 -0
  186. package/dist/legacy/modelKey.js +80 -0
  187. package/dist/legacy/modelKey.js.map +1 -0
  188. package/dist/legacy/serveProofV1.d.ts +56 -0
  189. package/dist/legacy/serveProofV1.d.ts.map +1 -0
  190. package/dist/legacy/serveProofV1.js +91 -0
  191. package/dist/legacy/serveProofV1.js.map +1 -0
  192. package/dist/provider-catalog.json +3 -2
  193. package/dist/secretEnv.d.ts +18 -3
  194. package/dist/secretEnv.d.ts.map +1 -1
  195. package/dist/secretEnv.js +16 -2
  196. package/dist/secretEnv.js.map +1 -1
  197. package/dist/types.d.ts +63 -1
  198. package/dist/types.d.ts.map +1 -1
  199. package/dist/viemErrors.d.ts +30 -0
  200. package/dist/viemErrors.d.ts.map +1 -0
  201. package/dist/viemErrors.js +36 -0
  202. package/dist/viemErrors.js.map +1 -0
  203. package/package.json +5 -1
  204. package/src/AgentClient.ts +622 -68
  205. package/src/AgenticID.ts +345 -56
  206. package/src/AttestorClient.ts +330 -83
  207. package/src/Credentials.ts +1027 -0
  208. package/src/Operators.ts +71 -0
  209. package/src/Providers.ts +20 -0
  210. package/src/Releases.ts +95 -0
  211. package/src/ReputationClient.ts +231 -79
  212. package/src/ServeProof.ts +123 -39
  213. package/src/ServeSession.ts +91 -9
  214. package/src/Settings.ts +61 -1
  215. package/src/TrustRegistry.ts +75 -0
  216. package/src/abi.ts +153 -30
  217. package/src/cli/attach.ts +257 -0
  218. package/src/cli/commands/cells.ts +104 -0
  219. package/src/cli/commands/cred.ts +44 -0
  220. package/src/cli/commands/doctor.ts +45 -37
  221. package/src/cli/commands/interactive.ts +4120 -664
  222. package/src/cli/commands/list.ts +21 -30
  223. package/src/cli/commands/providers.ts +17 -4
  224. package/src/cli/commands/releases.ts +60 -0
  225. package/src/cli/commands/settings.ts +75 -28
  226. package/src/cli/commands/status.ts +24 -21
  227. package/src/cli/config.ts +119 -4
  228. package/src/cli/credentials.ts +1379 -0
  229. package/src/cli/download.ts +80 -0
  230. package/src/cli/env.ts +22 -7
  231. package/src/cli/envelope.ts +10 -6
  232. package/src/cli/errors.ts +92 -0
  233. package/src/cli/inference.ts +8 -1
  234. package/src/cli/inkView.ts +969 -0
  235. package/src/cli/legacy/modelKey.ts +35 -0
  236. package/src/cli/livePrompt.ts +615 -0
  237. package/src/cli/main.ts +206 -76
  238. package/src/cli/modelkey.ts +124 -0
  239. package/src/cli/outboxSync.ts +231 -0
  240. package/src/cli/plain.ts +260 -0
  241. package/src/cli/proofs.ts +27 -0
  242. package/src/cli/ref.ts +5 -4
  243. package/src/cli/releaseNotice.ts +200 -0
  244. package/src/cli/sdk.ts +87 -7
  245. package/src/cli/settings.ts +272 -22
  246. package/src/cli/textfit.ts +95 -0
  247. package/src/constants.ts +1 -1
  248. package/src/context.ts +28 -0
  249. package/src/index.ts +50 -7
  250. package/src/legacy/modelKey.ts +80 -0
  251. package/src/legacy/serveProofV1.ts +124 -0
  252. package/src/provider-catalog.json +3 -2
  253. package/src/secretEnv.ts +18 -3
  254. package/src/types.ts +60 -1
  255. package/src/viemErrors.ts +39 -0
@@ -10,6 +10,7 @@
10
10
  * settings <agent> model=0gm-1.0-35b-a3b change one field
11
11
  * settings <agent> thinking= clear one field
12
12
  * settings <agent> others='{"a": 1}' the framework's own opaque knobs
13
+ * settings <agent> sealed=0x… harness=0x… pick the layered runtime's versions
13
14
  *
14
15
  * Assignments MERGE into the stored document — the owner is editing one
15
16
  * field, not re-authoring the whole thing. The wire write is still a whole
@@ -20,14 +21,21 @@
20
21
  * same quotes rather than breaking the JSON on its spaces.
21
22
  */
22
23
 
23
- import { CliError } from './errors';
24
- import { SETTINGS_FIELDS, THINKING_LEVELS, type SettingsDoc, type ThinkingLevel } from '../Settings';
24
+ import { CliError, agentCmd } from './errors';
25
+ import { THINKING_LEVELS, type SettingsDoc, type ThinkingLevel, type VersionPicks } from '../Settings';
26
+ import { MODEL_KEY_PREFIX } from '../Credentials';
25
27
 
26
- /** The document's named fields. `others` is opaque JSON; the rest are
28
+ /** The layered runtime's version picks, spelled as their own keys and
29
+ * written into the document's `versions` (0g-harness only). */
30
+ export const VERSION_KEYS = ['sealed', 'harness'] as const;
31
+ export type VersionKey = (typeof VERSION_KEYS)[number];
32
+
33
+ /** The keys the grammar takes: the document's named fields (SETTINGS_FIELDS),
34
+ * `versions` spelled as its two picks. `others` is opaque JSON; the rest are
27
35
  * strings. Anything else a container understands is writable through the
28
36
  * SDK, but not through this grammar — the CLI refuses keys it cannot
29
37
  * describe, so a typo can never become a stored field. */
30
- export const SETTINGS_KEYS = SETTINGS_FIELDS;
38
+ export const SETTINGS_KEYS = ['provider', 'model', 'thinking', 'others', ...VERSION_KEYS] as const;
31
39
  export type SettingsKey = (typeof SETTINGS_KEYS)[number];
32
40
 
33
41
  /** One `key=value`. `value === undefined` means "clear this field". */
@@ -36,23 +44,26 @@ export interface Assignment {
36
44
  value: string | ThinkingLevel | unknown | undefined;
37
45
  }
38
46
 
39
- const USAGE = '0g-agentdna settings <agent> [provider=… model=… thinking=low|high|max others=<json>]';
47
+ /** The command's grammar, as typed where the owner is (`settings 286 […]` in the shell). */
48
+ const usage = (): string => `${agentCmd('settings')} [provider=… model=… thinking=low|high|max others=<json> sealed=0x… harness=0x… | versions]`;
49
+
50
+ const isVersionKey = (key: string): key is VersionKey => (VERSION_KEYS as readonly string[]).includes(key);
40
51
 
41
- /** How to quote a JSON value, in either place it can be typed. */
42
- const FRAMEWORK_QUOTING =
43
- `settings <agent> others='{"key": "value"}' # quote it — inside the REPL too`;
52
+ /** How to quote a JSON value, as typed where the owner is. */
53
+ const frameworkQuoting = (): string => `${agentCmd('settings', `others='{"key": "value"}'`)} # quote it`;
44
54
 
45
55
  /**
46
56
  * Parse `key=value` positionals. Throws `BAD_FLAG` (exit 2) on an unknown
47
- * key, a bad thinking level, or an `others=` value that is not JSON — all
48
- * usage errors worth failing on before any network work.
57
+ * key, a bad thinking level, an `others=` value that is not JSON, or a
58
+ * version pick that is not a sha256 hash — all usage errors worth failing on
59
+ * before any network work.
49
60
  */
50
61
  export function parseAssignments(args: string[]): Assignment[] {
51
62
  const out: Assignment[] = [];
52
63
  for (const arg of args) {
53
64
  const eq = arg.indexOf('=');
54
65
  if (eq < 1) {
55
- throw new CliError('BAD_FLAG', `not a setting assignment: "${arg}" (expected key=value)`, { remedy: USAGE });
66
+ throw new CliError('BAD_FLAG', `not a setting assignment: "${arg}" (expected key=value)`, { remedy: usage() });
56
67
  }
57
68
  const key = arg.slice(0, eq);
58
69
  const raw = arg.slice(eq + 1);
@@ -61,7 +72,7 @@ export function parseAssignments(args: string[]): Assignment[] {
61
72
  'BAD_FLAG',
62
73
  `unknown setting "${key}" — the platform's named fields are ${SETTINGS_KEYS.join(', ')} ` +
63
74
  '(anything framework-specific goes inside others=<json>)',
64
- { remedy: USAGE },
75
+ { remedy: usage() },
65
76
  );
66
77
  }
67
78
  if (raw === '') {
@@ -70,7 +81,12 @@ export function parseAssignments(args: string[]): Assignment[] {
70
81
  }
71
82
  if (key === 'thinking' && !(THINKING_LEVELS as readonly string[]).includes(raw)) {
72
83
  throw new CliError('BAD_FLAG', `thinking must be one of ${THINKING_LEVELS.join('|')}, got "${raw}"`, {
73
- remedy: USAGE,
84
+ remedy: usage(),
85
+ });
86
+ }
87
+ if (isVersionKey(key) && !/^0x[0-9a-fA-F]{64}$/.test(raw)) {
88
+ throw new CliError('BAD_FLAG', `${key}= takes a version's sha256 hash, "0x" + 64 hex, got "${raw}"`, {
89
+ remedy: `${agentCmd('settings')} on a 0g-harness agent lists the versions the trust registry has; ${key}= clears the pick`,
74
90
  });
75
91
  }
76
92
  if (key === 'others') {
@@ -79,9 +95,10 @@ export function parseAssignments(args: string[]): Assignment[] {
79
95
  parsed = JSON.parse(raw);
80
96
  } catch (e) {
81
97
  throw new CliError('BAD_FLAG', `others= must be JSON: ${(e as Error).message}`, {
82
- remedy: FRAMEWORK_QUOTING,
98
+ remedy: frameworkQuoting(),
83
99
  });
84
100
  }
101
+ assertHarnessKnobShapes(parsed);
85
102
  out.push({ key, value: parsed });
86
103
  continue;
87
104
  }
@@ -91,7 +108,93 @@ export function parseAssignments(args: string[]): Assignment[] {
91
108
  }
92
109
 
93
110
  /** `others` keys only the 0g-harness adapter reads (sealed `harness/settings.go`). */
94
- export const HARNESS_ONLY_KEYS = ['toolJobs', 'subagents', 'schedule', 'maxParallelToolCalls'] as const;
111
+ export const HARNESS_ONLY_KEYS = ['toolJobs', 'subagents', 'schedule', 'maxParallelToolCalls', 'modelImages', 'memoryExtract', 'memoryExtractMinMessages', 'memoryInlineBytes', 'memoryRecall', 'memoryTidy', 'webTools', 'webSearch', 'subagentModels', 'subagentDefault'] as const;
112
+
113
+ /** Search services `others.webSearch.service` may name (sealed `inference.SearchServices`), and `off`. */
114
+ export const WEB_SEARCH_SERVICES = ['0g-router', 'openai', 'anthropic', 'off'] as const;
115
+ /** At most this many `others.subagentModels` (sealed `maxSubagentModels`). */
116
+ export const MAX_SUBAGENT_MODELS = 8;
117
+ const PROVIDER_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
118
+ const MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._:/@+-]{0,127}$/;
119
+ const CREDENTIAL_NAME = /^[a-z0-9][a-z0-9._-]{0,62}$/;
120
+
121
+ function knobError(message: string): CliError {
122
+ return new CliError('BAD_FLAG', message, {
123
+ remedy:
124
+ 'others={"webSearch":{"service":"0g-router|openai|anthropic|off","credential":"<name>","model":"<id>"},' +
125
+ '"subagentModels":[{"provider":"<id>","model":"<id>","credential":"<name>"}],"subagentDefault":{"provider":"<id>","model":"<id>"}}',
126
+ });
127
+ }
128
+
129
+ /**
130
+ * A model key entry (`model.<provider>`) pays only the agent's own model:
131
+ * the credential proxy has no placeholder for it, so sealed refuses it here.
132
+ */
133
+ function assertNotModelKey(credential: unknown, field: string): void {
134
+ if (typeof credential === 'string' && credential.startsWith(MODEL_KEY_PREFIX)) {
135
+ throw knobError(`${field} "${credential}" is a model key, which pays only the agent's own model: leave "credential" out to use the model key, or store the key as an owner credential (cred <agent> set <name> preset=<provider>) and name that`);
136
+ }
137
+ }
138
+
139
+ function onlyKeys(v: unknown, keys: string[]): v is Record<string, unknown> {
140
+ return !!v && typeof v === 'object' && !Array.isArray(v) && Object.keys(v).every((k) => keys.includes(k));
141
+ }
142
+
143
+ /**
144
+ * Check the shape of the 0g-harness model knobs in `others`, before anything
145
+ * is signed, the way sealed reads them (`harness/settings.go`): sealed would
146
+ * drop a malformed one at boot and log why; here the owner hears it first.
147
+ */
148
+ export function assertHarnessKnobShapes(others: unknown): void {
149
+ if (!others || typeof others !== 'object' || Array.isArray(others)) return;
150
+ const o = others as Record<string, unknown>;
151
+ if ('webSearch' in o) {
152
+ const ws = o.webSearch;
153
+ if (!onlyKeys(ws, ['service', 'credential', 'model']) || !(WEB_SEARCH_SERVICES as readonly unknown[]).includes(ws.service)) {
154
+ throw knobError(`webSearch must be {"service": ${WEB_SEARCH_SERVICES.join('|')}, "credential"?, "model"?}`);
155
+ }
156
+ if (ws.credential !== undefined && (typeof ws.credential !== 'string' || !CREDENTIAL_NAME.test(ws.credential))) throw knobError('webSearch.credential must name a credential');
157
+ assertNotModelKey(ws.credential, 'webSearch.credential');
158
+ if (ws.model !== undefined && (typeof ws.model !== 'string' || !MODEL_ID.test(ws.model))) throw knobError('webSearch.model must be a model id');
159
+ if (ws.model !== undefined && ws.service !== 'openai' && ws.service !== 'anthropic') throw knobError('webSearch.model applies only to the openai and anthropic services');
160
+ }
161
+ if ('subagentModels' in o) {
162
+ const list = o.subagentModels;
163
+ if (!Array.isArray(list) || list.length > MAX_SUBAGENT_MODELS) throw knobError(`subagentModels must be an array of at most ${MAX_SUBAGENT_MODELS} models`);
164
+ const seen = new Set<string>();
165
+ for (const m of list) {
166
+ if (!onlyKeys(m, ['provider', 'model', 'credential']) || typeof m.provider !== 'string' || !PROVIDER_ID.test(m.provider) ||
167
+ typeof m.model !== 'string' || !MODEL_ID.test(m.model) ||
168
+ (m.credential !== undefined && (typeof m.credential !== 'string' || !CREDENTIAL_NAME.test(m.credential)))) {
169
+ throw knobError('each subagentModels entry is {"provider", "model", "credential"?}');
170
+ }
171
+ assertNotModelKey(m.credential, 'subagentModels credential');
172
+ const key = `${m.provider}\0${m.model}\0${m.credential ?? ''}`;
173
+ if (seen.has(key)) throw knobError(`subagentModels repeats ${m.provider}/${m.model}`);
174
+ seen.add(key);
175
+ }
176
+ }
177
+ if ('subagentDefault' in o) {
178
+ const d = o.subagentDefault;
179
+ if (!onlyKeys(d, ['provider', 'model']) || typeof d.provider !== 'string' || !PROVIDER_ID.test(d.provider) || typeof d.model !== 'string' || !MODEL_ID.test(d.model)) {
180
+ throw knobError('subagentDefault must be {"provider", "model"}');
181
+ }
182
+ }
183
+ }
184
+
185
+ /**
186
+ * Refuse a subagentDefault that is neither the document's model nor one of
187
+ * its subagentModels: sealed would ignore it and default to the main model.
188
+ */
189
+ export function assertSubagentDefaultOffered(next: SettingsDoc): void {
190
+ const others = next.others as Record<string, unknown> | undefined;
191
+ const d = others?.subagentDefault as { provider?: string; model?: string } | undefined;
192
+ if (!d || typeof d !== 'object') return;
193
+ const list = Array.isArray(others?.subagentModels) ? (others!.subagentModels as Array<{ provider?: string; model?: string }>) : [];
194
+ const isMain = d.model === next.model && (d.provider === next.provider || (!next.provider && d.provider === '0g-compute'));
195
+ if (isMain || list.some((m) => m.provider === d.provider && m.model === d.model)) return;
196
+ throw knobError(`subagentDefault ${d.provider}/${d.model} is neither the agent's model nor one of subagentModels`);
197
+ }
95
198
 
96
199
  /**
97
200
  * Whether `framework` names the 0g-harness adapter. `dsh` is its name before
@@ -104,6 +207,48 @@ export function isHarnessFramework(framework: string | null | undefined): boolea
104
207
  return framework === '0g-harness' || framework === 'dsh';
105
208
  }
106
209
 
210
+ /**
211
+ * Whether `framework` works through tool calls, so its model must be able to
212
+ * call tools: the tool-driven frameworks, the harness under either of its
213
+ * names (`dsh` on a network still on AgenticID 1.3, see `isHarnessFramework`).
214
+ * The deploy wizard offers such a framework only models with tool use.
215
+ */
216
+ export function frameworkNeedsToolModels(framework: string): boolean {
217
+ return framework === 'openclaw' || framework === 'prime-agent' || isHarnessFramework(framework);
218
+ }
219
+
220
+ /** Whether these assignments set the model or the provider. */
221
+ export function touchesModel(assignments: Assignment[]): boolean {
222
+ return assignments.some((a) => a.key === 'model' || a.key === 'provider');
223
+ }
224
+
225
+ /**
226
+ * Refuse, before signing, a model change to one its provider's catalog lists
227
+ * without tool use on an agent whose framework works through tools: it would
228
+ * fail every turn there (the deploy wizard does not offer such a model
229
+ * either). Only a write that sets the model or the provider is checked; a
230
+ * model the catalog does not list, an unreadable catalog or an unknown
231
+ * framework passes — the catalog advisory speaks to the first.
232
+ */
233
+ export async function assertModelFitsFramework(
234
+ assignments: Assignment[],
235
+ next: SettingsDoc,
236
+ framework: string | null | undefined,
237
+ caps: (provider: string) => Promise<Array<{ id: string; chat: boolean; tools: boolean }>>,
238
+ ): Promise<void> {
239
+ const model = next.model?.trim();
240
+ if (!model || !framework || !frameworkNeedsToolModels(framework)) return;
241
+ if (!touchesModel(assignments)) return;
242
+ const listed = await caps(next.provider ?? '0g-compute').catch(() => null);
243
+ const entry = listed?.find((m) => m.id.toLowerCase() === model.toLowerCase());
244
+ if (!listed || !entry || entry.tools) return;
245
+ const able = listed.filter((m) => m.chat && m.tools).map((m) => m.id);
246
+ const an = /^[aeiou]/i.test(framework) ? 'an' : 'a';
247
+ throw new CliError('BAD_FLAG', `${model} cannot call tools, and ${an} ${framework} agent works through tool calls — it would fail every turn`, {
248
+ remedy: able.length ? `pick a model that can: ${able.slice(0, 4).join(', ')}` : 'pick a model that can call tools',
249
+ });
250
+ }
251
+
107
252
  /**
108
253
  * Refuse 0g-harness switches in `others=` for an agent known to run another
109
254
  * framework, before anything is signed. There `others` is that framework's
@@ -131,11 +276,35 @@ export function assertOthersFitFramework(assignments: Assignment[], framework: s
131
276
  );
132
277
  }
133
278
 
279
+ /**
280
+ * Refuse version picks for an agent known to run another framework, before
281
+ * anything is signed: only the 0g-harness image's layered runtime reads
282
+ * `versions`, so elsewhere a pick would be stored and silently do nothing.
283
+ * An unknown framework (a legacy row) is not refused.
284
+ */
285
+ export function assertVersionsFitFramework(assignments: Assignment[], framework: string | null | undefined): void {
286
+ if (!framework || isHarnessFramework(framework)) return;
287
+ const picks = assignments.filter((a) => isVersionKey(a.key) && a.value !== undefined).map((a) => a.key);
288
+ if (!picks.length) return;
289
+ throw new CliError(
290
+ 'BAD_FLAG',
291
+ `${picks.join('= and ')}= pick${picks.length > 1 ? '' : 's'} the layered runtime's versions, which only 0g-harness agents have; this agent runs ${framework}`,
292
+ { remedy: 'leave them out: this agent runs on the version its image carries' },
293
+ );
294
+ }
295
+
134
296
  /** Merge assignments onto the stored document, producing the document to write. */
135
297
  export function applyAssignments(base: SettingsDoc | null, assignments: Assignment[]): SettingsDoc {
136
298
  const doc: SettingsDoc = { ...(base ?? {}) };
137
299
  for (const a of assignments) {
138
- if (a.value === undefined) delete doc[a.key];
300
+ if (isVersionKey(a.key)) {
301
+ const picks: VersionPicks = { ...(doc.versions ?? {}) };
302
+ if (a.value === undefined) delete picks[a.key];
303
+ else picks[a.key] = a.value as string;
304
+ // A pick for a layer this CLI does not know stays, as in canonicalSettings.
305
+ if (Object.values(picks).some((pick) => pick !== undefined && pick !== '')) doc.versions = picks;
306
+ else delete doc.versions;
307
+ } else if (a.value === undefined) delete doc[a.key];
139
308
  else if (a.key === 'others') doc.others = a.value;
140
309
  else doc[a.key] = a.value as string & ThinkingLevel;
141
310
  }
@@ -169,8 +338,8 @@ export function assertModelPresent(next: SettingsDoc, hadStored: boolean): void
169
338
  {
170
339
  remedy:
171
340
  'include the model in the same command, e.g. ' +
172
- '`settings <agent> model=0gm-1.0-35b-a3b thinking=high` (the agent\'s current model is whatever its ' +
173
- 'image was built or last configured with — `hello <agent>` and `/agentlog` show what it is running)',
341
+ `\`${agentCmd('settings', 'model=0gm-1.0-35b-a3b thinking=high')}\` (the agent's current model is whatever its ` +
342
+ 'image was built or last configured with)',
174
343
  },
175
344
  );
176
345
  }
@@ -185,10 +354,91 @@ export function renderSettings(doc: SettingsDoc | null): string[] {
185
354
  if (!doc || Object.keys(doc).length === 0) return ['(not configured — the agent boots on its framework defaults)'];
186
355
  const show = (v: unknown): string =>
187
356
  v === undefined || v === null ? '—' : typeof v === 'string' ? v : JSON.stringify(v);
188
- const extra = Object.keys(doc).filter(
189
- (k) => !(SETTINGS_KEYS as readonly string[]).includes(k) && doc[k] !== undefined,
357
+ // `versions` shows as its two picks, the keys that write them, and a pick
358
+ // for a layer this CLI does not know as `versions.<layer>`; a value of
359
+ // another shape shows as itself.
360
+ const v = doc.versions as unknown;
361
+ const picks = v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : null;
362
+ const flat: Record<string, unknown> = { ...doc, versions: picks ? undefined : v };
363
+ if (picks) {
364
+ for (const k of VERSION_KEYS) flat[k] = picks[k] || undefined;
365
+ for (const [k, pick] of Object.entries(picks)) {
366
+ if (!(VERSION_KEYS as readonly string[]).includes(k)) flat[`versions.${k}`] = pick;
367
+ }
368
+ }
369
+ const extra = Object.keys(flat).filter(
370
+ (k) => !(SETTINGS_KEYS as readonly string[]).includes(k) && flat[k] !== undefined,
190
371
  );
191
- return [...SETTINGS_KEYS.filter((k) => doc[k] !== undefined), ...extra].map(
192
- (k) => `${k.padEnd(11)}${show(doc[k])}`,
372
+ return [...SETTINGS_KEYS.filter((k) => flat[k] !== undefined), ...extra].map(
373
+ (k) => `${`${k} `.padEnd(11)}${show(flat[k])}`,
193
374
  );
194
375
  }
376
+
377
+ /**
378
+ * A settings command's words after the agent: `versions` alone asks for the
379
+ * versions the trust registry lists; anything else is assignments
380
+ * ({@link parseAssignments}). `versions` is never an assignment, and goes
381
+ * alone.
382
+ */
383
+ export function settingsArgs(args: string[]): { versions: boolean; assignments: ReturnType<typeof parseAssignments> } {
384
+ if (args.length === 1 && args[0] === 'versions') return { versions: true, assignments: [] };
385
+ if (args.includes('versions')) {
386
+ throw new CliError('BAD_FLAG', '`versions` goes on its own: it shows the versions to pick from, and writes nothing', { remedy: usage() });
387
+ }
388
+ return { versions: false, assignments: parseAssignments(args) };
389
+ }
390
+
391
+ /**
392
+ * The versions a 0g-harness agent runs, on one line of the settings view:
393
+ * with no pick, the trust registry's newest (what an agent with no pick
394
+ * moves to); with picks, the picks — one no longer listed is not run — and
395
+ * the newest for a layer without one. `none listed` for an empty list.
396
+ */
397
+ export function renderVersionsLine(
398
+ listed: { sealed: readonly string[]; harness: readonly string[] },
399
+ picks?: VersionPicks,
400
+ ): string {
401
+ const short = (h: string): string => `${h.slice(0, 10)}…`;
402
+ const newest = (layer: VersionKey): string => {
403
+ const hashes = listed[layer];
404
+ return hashes.length ? short(hashes[hashes.length - 1]) : 'none listed';
405
+ };
406
+ const pick = (layer: VersionKey): string | undefined => {
407
+ const p = picks?.[layer];
408
+ return typeof p === 'string' && p ? p : undefined;
409
+ };
410
+ const head = `${'versions '.padEnd(11)}`;
411
+ if (!VERSION_KEYS.some(pick)) return `${head}newest listed (${VERSION_KEYS.map((k) => `${k} ${newest(k)}`).join(', ')})`;
412
+ return `${head}pinned: ${VERSION_KEYS.map((k) => {
413
+ const p = pick(k);
414
+ if (!p) return `${k} newest listed (${newest(k)})`;
415
+ const isListed = listed[k].some((h) => h.toLowerCase() === p.toLowerCase());
416
+ return `${k} ${short(p)}${isListed ? '' : ' (not listed: not run)'}`;
417
+ }).join(', ')}`;
418
+ }
419
+
420
+ /**
421
+ * The versions an owner can pick (0g-harness): the trust registry's sealed
422
+ * and harness lists in listing order, the last one the newest — what an
423
+ * agent with no pick moves to once its own version is delisted. The picks in
424
+ * `picks` are marked, and a pick no longer listed says that it does not run.
425
+ */
426
+ export function renderListedVersions(
427
+ listed: { sealed: readonly string[]; harness: readonly string[] },
428
+ picks?: VersionPicks,
429
+ ): string[] {
430
+ const lines = ['listed versions, oldest first (pick with sealed=<hash> harness=<hash>):'];
431
+ for (const layer of VERSION_KEYS) {
432
+ const hashes = listed[layer];
433
+ const pick = picks?.[layer]?.toLowerCase();
434
+ if (!hashes.length) lines.push(` ${layer.padEnd(8)} (none listed)`);
435
+ hashes.forEach((h, i) => {
436
+ const tags = [i === hashes.length - 1 ? 'newest' : '', pick === h.toLowerCase() ? 'picked' : ''].filter(Boolean);
437
+ lines.push(` ${layer.padEnd(8)} ${h}${tags.length ? ` (${tags.join(', ')})` : ''}`);
438
+ });
439
+ if (pick && !hashes.some((h) => h.toLowerCase() === pick)) {
440
+ lines.push(` ${layer.padEnd(8)} ${picks![layer]} (picked, not listed: not run)`);
441
+ }
442
+ }
443
+ return lines;
444
+ }
@@ -0,0 +1,95 @@
1
+ /**
2
+ * @file textfit.ts
3
+ * @description Text that fits the owner's terminal: the width to use, the
4
+ * shell's two-column help reflowed for narrow terminals, whole lines wrapped
5
+ * (with livePrompt.ts's wrapProse, the CLI's one word wrap), and the nearest
6
+ * known word for a typo.
7
+ */
8
+
9
+ import { wrapProse, wrapText } from './livePrompt';
10
+
11
+ /** The columns text may use on `stream` when it is a terminal: its width
12
+ * less the last column (a character there leaves the cursor pending a wrap
13
+ * some terminals then take); undefined when it is piped. */
14
+ export function termWidth(stream: NodeJS.WriteStream = process.stdout): number | undefined {
15
+ return stream.isTTY && stream.columns ? Math.max(20, stream.columns - 1) : undefined;
16
+ }
17
+
18
+ /**
19
+ * The shell's help text, fitted to `width`. The text is written for 80
20
+ * columns in two columns (a command, then its description from column
21
+ * `col`); on a narrower terminal each description is re-wrapped under its
22
+ * command, and below 60 columns it goes on the lines below the command.
23
+ */
24
+ export function fitHelp(text: string, width: number | undefined, col = 26): string {
25
+ const lines = text.split('\n');
26
+ if (!width || lines.every((l) => [...l].length <= width)) return text;
27
+ type Entry = { cmd?: string; desc: string };
28
+ const entries: Entry[] = [];
29
+ const pad = ' '.repeat(col);
30
+ for (const l of lines) {
31
+ if (l.startsWith(pad) && entries.length && entries[entries.length - 1].cmd !== undefined) {
32
+ entries[entries.length - 1].desc += ` ${l.trim()}`;
33
+ } else if (/^ {2}\S/.test(l)) {
34
+ const cmd = l.slice(2, col).trimEnd();
35
+ // A command wider than its column puts its description on the next line.
36
+ entries.push(l.length > col && l[col - 1] === ' ' ? { cmd, desc: l.slice(col).trim() } : { cmd: l.trim(), desc: '' });
37
+ } else if (l.trim() && entries.length && entries[entries.length - 1].cmd === undefined && entries[entries.length - 1].desc.trim()) {
38
+ entries[entries.length - 1].desc += ` ${l.trim()}`;
39
+ } else {
40
+ entries.push({ desc: l });
41
+ }
42
+ }
43
+ const out: string[] = [];
44
+ const twoCol = width >= 60;
45
+ for (const e of entries) {
46
+ if (e.cmd === undefined) { out.push(...wrapProse(e.desc, width)); continue; }
47
+ if (!e.desc) { out.push(` ${e.cmd}`); continue; }
48
+ if (twoCol && e.cmd.length <= col - 3) {
49
+ const cmd = e.cmd;
50
+ wrapProse(e.desc.trim(), width - col).forEach((r, i) => out.push(`${i ? pad : ` ${cmd.padEnd(col - 2)}`}${r}`));
51
+ } else {
52
+ out.push(` ${e.cmd}`);
53
+ const under = twoCol ? pad : ' ';
54
+ wrapProse(e.desc.trim(), width - under.length).forEach((r) => out.push(`${under}${r}`));
55
+ }
56
+ }
57
+ return out.join('\n');
58
+ }
59
+
60
+ /** Damerau–Levenshtein distance (adjacent swaps cost 1: `lsit` → `list`). */
61
+ function distance(a: string, b: string): number {
62
+ const d: number[][] = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
63
+ for (let j = 1; j <= b.length; j++) d[0][j] = j;
64
+ for (let i = 1; i <= a.length; i++) {
65
+ for (let j = 1; j <= b.length; j++) {
66
+ const cost = a[i - 1] === b[j - 1] ? 0 : 1;
67
+ d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
68
+ if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
69
+ }
70
+ }
71
+ return d[a.length][b.length];
72
+ }
73
+
74
+ /** The known word `typed` is most likely a typo of, or undefined when none is close. */
75
+ export function didYouMean(typed: string, words: readonly string[]): string | undefined {
76
+ const t = typed.toLowerCase();
77
+ let best: string | undefined;
78
+ let bestD = Infinity;
79
+ for (const w of words) {
80
+ const dist = distance(t, w);
81
+ if (dist < bestD) { best = w; bestD = dist; }
82
+ }
83
+ // Close means at most 2 edits, and fewer than half the word's letters.
84
+ return best !== undefined && bestD <= 2 && bestD * 2 < Math.max(t.length, best.length) ? best : undefined;
85
+ }
86
+
87
+ /**
88
+ * Text of whole lines fitted to `width` (undefined: as it is), between words:
89
+ * the shell's word wrap (livePrompt.ts wrapText — later rows under the text,
90
+ * a label's value or an `error:`/`fix:` text; long tokens whole; CJK between
91
+ * characters), for the one-shot commands' lines on a terminal.
92
+ */
93
+ export function fitLines(text: string, width: number | undefined): string {
94
+ return width ? wrapText(text, width) : text;
95
+ }
package/src/constants.ts CHANGED
@@ -103,4 +103,4 @@ export const RECEIPT_WAIT = {
103
103
 
104
104
  /** This SDK's own version. Kept in lockstep with package.json by a test —
105
105
  * a runtime package.json read would break browser bundles, so a constant. */
106
- export const SDK_VERSION = '0.4.0';
106
+ export const SDK_VERSION = '0.5.0';
package/src/context.ts CHANGED
@@ -16,6 +16,13 @@ import {
16
16
  import { privateKeyToAccount } from 'viem/accounts';
17
17
  import { ZERO_G_TESTNET, RPC_URL, type ContractAddresses } from './constants';
18
18
 
19
+ /** A stored credential set's place in order, and its EIP-712 digest. */
20
+ export interface CredentialMarkRecord {
21
+ epoch: number;
22
+ version: number;
23
+ digest?: string;
24
+ }
25
+
19
26
  /** Public config for `new AgentDNA(config)` (exported as `AgentDNAConfig`). */
20
27
  export interface AgenticIDConfig {
21
28
  /** RPC endpoint. Defaults to the 0G Galileo testnet RPC. */
@@ -43,6 +50,9 @@ export interface AgenticIDConfig {
43
50
  */
44
51
  componentAppIds?: string[];
45
52
  /**
53
+ * LEGACY(model-key): only the request copy of a model key is sealed with
54
+ * the secret-env scheme.
55
+ *
46
56
  * Sticky memory for the secret-env scheme (issue #166): once an attestor
47
57
  * has advertised `secret_env_scheme`, its later absence is treated as
48
58
  * tampering and refused (`scheme_withdrawn`) rather than silently falling
@@ -55,6 +65,21 @@ export interface AgenticIDConfig {
55
65
  seen(attestorUrl: string): boolean | Promise<boolean>;
56
66
  record(attestorUrl: string): void | Promise<void>;
57
67
  };
68
+ /**
69
+ * Memory of the newest credential set (ownership epoch, version) this
70
+ * client has seen for each agent, so an older one the attestor serves
71
+ * again is refused instead of signed anew. Every client remembers within
72
+ * its own lifetime; supply this store to remember across processes (the
73
+ * CLI backs it with a file). Keys are opaque strings; `record` is called
74
+ * with a newer mark than `seen` answered, and should keep the newer of it
75
+ * and what it holds. `where` names the store in the error that refuses an
76
+ * older set, for an owner whose attestor's data was reset on purpose.
77
+ */
78
+ credentialMarks?: {
79
+ seen(key: string): CredentialMarkRecord | undefined | Promise<CredentialMarkRecord | undefined>;
80
+ record(key: string, mark: CredentialMarkRecord): void | Promise<void>;
81
+ where?: string;
82
+ };
58
83
  }
59
84
 
60
85
  /** The slice of the attestor's GET /config the SDK auto-configures from. */
@@ -103,6 +128,8 @@ export interface Ctx {
103
128
  seen(attestorUrl: string): boolean | Promise<boolean>;
104
129
  record(attestorUrl: string): void | Promise<void>;
105
130
  };
131
+ /** See {@link AgenticIDConfig.credentialMarks}. */
132
+ credentialMarks?: AgenticIDConfig['credentialMarks'];
106
133
  }
107
134
 
108
135
  const DEFAULT_COMPONENT_APP_IDS = ['0g-attestor', '0g-kms', '0g-sandbox-provider'];
@@ -148,6 +175,7 @@ export function buildCtx(config: AgenticIDConfig): Ctx {
148
175
  componentAppIdsExplicit: config.componentAppIds !== undefined,
149
176
  attestorConfig,
150
177
  secretEnvPin: config.secretEnvPin,
178
+ credentialMarks: config.credentialMarks,
151
179
  publicClient: createPublicClient({ chain, transport: http(rpcUrl) }),
152
180
  };
153
181
  }