@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
@@ -0,0 +1,296 @@
1
+ import { inferenceModels, inferenceProvider, modelsForProvider, type InferenceProvider } from './Providers';
2
+ /**
3
+ * @file Settings.ts
4
+ * @description The owner's configuration document — the one blob that says
5
+ * which model an agent thinks with, and how hard.
6
+ *
7
+ * Where it lives and who understands it:
8
+ * - the OWNER authors it (this file's {@link SettingsDoc});
9
+ * - the ATTESTOR stores it opaquely: it never parses the contents, never
10
+ * validates them, and gains no knowledge of what a setting means. Its
11
+ * only jobs are store / serve to the container / refuse a write that is
12
+ * not signed by the agent's current on-chain owner;
13
+ * - the CONTAINER (`sealed/internal/settings`) is where all meaning lives
14
+ * and is the real gate.
15
+ *
16
+ * That layering is the point: widening the vocabulary — a new field, a new
17
+ * framework knob — is a container change only. Nothing here or in the
18
+ * attestor has to learn about it. {@link SettingsDoc} therefore mirrors the
19
+ * Go `settings.Doc` exactly, and `others` stays deliberately opaque.
20
+ *
21
+ * It is NOT on chain. Configuration is re-suppliable (an owner re-picks a
22
+ * model in ten seconds); memory is not, and only memory earns chain storage.
23
+ *
24
+ * THE SIGNATURE COVERS A DIGEST, NOT THE DOCUMENT. `POST /settings` carries
25
+ * the signed statement in an HTTP header, which must stay short and ASCII,
26
+ * while the document is large and may be non-ASCII. So the owner signs
27
+ * `AgenticID.Settings.v1:<sealId>:<ts>:<base_version>:<sha256 of the bytes sent>`
28
+ * and the bytes themselves ride the body. For that to mean anything, the
29
+ * digest and the body must come from ONE serialization — see
30
+ * {@link canonicalSettings}, whose output is BOTH hashed and spliced
31
+ * verbatim into the request body.
32
+ *
33
+ * EVERY WRITE IS A COMPARE-AND-SWAP. `base_version` is the version the writer
34
+ * read before editing (0 = "I believe there is no document yet"); the attestor
35
+ * refuses with HTTP 409 when it no longer matches the stored one. Three holes
36
+ * close at once: a captured request cannot be replayed to roll the document
37
+ * back to a superseded one, two clients editing the same agent cannot silently
38
+ * overwrite each other, and a client that never read cannot blind-write over a
39
+ * document it has not seen. {@link SettingsConflictError} is what the SDK
40
+ * raises for that 409 — re-read, re-apply the edit, write again. Never retry
41
+ * the same bytes in a loop: the point of the refusal is that a human decides
42
+ * what survives.
43
+ *
44
+ * READS ARE OWNER-GATED TOO. The document is the owner's, so `GET /settings`
45
+ * carries the same owner signature, minus the digest (there is no body): the
46
+ * message ends at `base_version`, which a reader sends as 0. It is NOT on the
47
+ * public deployment row or in any listing.
48
+ */
49
+
50
+ /** The reasoning-depth vocabulary (Go: `settings.Levels`). */
51
+ export const THINKING_LEVELS = ['low', 'high', 'max'] as const;
52
+ export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
53
+
54
+ /** Signed-message domain for `POST /settings`. */
55
+ export const SETTINGS_DOMAIN = 'AgenticID.Settings.v1';
56
+
57
+ /** The 0G router's public model catalog — no auth. */
58
+ export const ROUTER_MODELS_URL = inferenceProvider('0g-compute').modelCatalog!;
59
+
60
+ /**
61
+ * The owner's settings document — the exact shape of Go's `settings.Doc`
62
+ * (`sealed/internal/settings/settings.go`). Field names, field order and
63
+ * omit-when-empty semantics all match, so what this SDK stores is what Go
64
+ * parses back, field for field. (The encoded BYTES can differ — see
65
+ * {@link canonicalSettings} — and nothing depends on them not doing so.)
66
+ */
67
+ export interface SettingsDoc {
68
+ /**
69
+ * Who serves the model. `'0g-compute'` means the PLATFORM supplies the
70
+ * endpoint. Other registered managed providers supply their own endpoint;
71
+ * registered native providers use the framework's built-in wiring.
72
+ */
73
+ provider?: string;
74
+ /** The model id, spelled the way the provider spells it. */
75
+ model?: string;
76
+ /** Reasoning-depth preference — one of {@link THINKING_LEVELS}. */
77
+ thinking?: ThinkingLevel;
78
+ /**
79
+ * Everything beyond the three named settings: the running framework's OWN
80
+ * knobs, passed through opaquely. Named `others` and not `framework`
81
+ * because a live drill showed the obvious reading of that word — choosing
82
+ * WHICH framework runs — is exactly what this field cannot do (the
83
+ * framework binding is minted identity). The platform neither parses nor
84
+ * validates the contents, nor promises they survive a framework upgrade. Any
85
+ * JSON value. `undefined`/`null` omits the section entirely.
86
+ */
87
+ others?: unknown;
88
+ /**
89
+ * The document is EXTENSIBLE by design: the container defines the
90
+ * vocabulary, so a field newer than this SDK is legitimate. It is carried
91
+ * through {@link canonicalSettings} untouched, which is what keeps an
92
+ * older client from erasing a newer setting on a read-modify-write.
93
+ */
94
+ [key: string]: unknown;
95
+ }
96
+
97
+ /** `'0g-compute'` — the provider for which the platform routes the model. */
98
+ export const ZG_COMPUTE_PROVIDER = '0g-compute';
99
+
100
+ /** The fields the PLATFORM names and guarantees, in Go declaration order.
101
+ * Everything else in a document belongs to the container. */
102
+ export const SETTINGS_FIELDS = ['provider', 'model', 'thinking', 'others'] as const;
103
+
104
+ /**
105
+ * THE serialization. Its output is what gets hashed into the signed header
106
+ * AND what is spliced verbatim into the request body, so the two can never
107
+ * disagree — two independent `JSON.stringify` calls would be one refactor
108
+ * away from a bogus "signer mismatch".
109
+ *
110
+ * Field order follows the Go struct's declaration order and empty fields are
111
+ * dropped, matching `encoding/json` + `omitempty`. `others` is passed
112
+ * through as raw JSON — the platform does not interpret it.
113
+ *
114
+ * It is NOT byte-identical to Go's `settings.Doc.Marshal`, and does not have
115
+ * to be: Go's encoder escapes `<`, `>`, `&` (and U+2028/U+2029) by default,
116
+ * where `JSON.stringify` emits them literally — so any document containing
117
+ * one of those serializes differently on the two sides. Nothing rests on the
118
+ * two agreeing byte-for-byte. The digest covers the bytes ACTUALLY SENT, the
119
+ * attestor stores those bytes, and the container parses the document rather
120
+ * than re-hashing it. What must match across the two is the VALUE: same
121
+ * fields, same types, same omissions.
122
+ */
123
+ export function canonicalSettings(doc: SettingsDoc): string {
124
+ const parts: string[] = [];
125
+ const put = (key: string, value: string | undefined): void => {
126
+ if (value !== undefined && value !== '') parts.push(`"${key}":${JSON.stringify(value)}`);
127
+ };
128
+ put('provider', doc.provider);
129
+ put('model', doc.model);
130
+ put('thinking', doc.thinking);
131
+ // Go's `omitempty` on a json.RawMessage drops only a nil/empty member — an
132
+ // explicit `{}` is content and stays. null/undefined here mean "no section".
133
+ if (doc.others !== undefined && doc.others !== null) {
134
+ const raw = JSON.stringify(doc.others);
135
+ if (raw !== undefined) parts.push(`"others":${raw}`);
136
+ }
137
+ // Anything this SDK version has never heard of goes through untouched, in
138
+ // its own order. The container owns the vocabulary, so a field newer than
139
+ // this build is legitimate — and a read-modify-write that dropped it would
140
+ // let an old client silently erase a new setting, which is exactly the loss
141
+ // the "widening the vocabulary never touches the platform" design forbids.
142
+ for (const [key, value] of Object.entries(doc)) {
143
+ if ((SETTINGS_FIELDS as readonly string[]).includes(key) || value === undefined) continue;
144
+ const raw = JSON.stringify(value);
145
+ if (raw !== undefined) parts.push(`${JSON.stringify(key)}:${raw}`);
146
+ }
147
+ return `{${parts.join(',')}}`;
148
+ }
149
+
150
+ /** The one WebCrypto member we need — structural, so the SDK keeps compiling
151
+ * without the DOM lib. */
152
+ type Digester = { digest(algorithm: string, data: Uint8Array): Promise<ArrayBuffer> };
153
+
154
+ /** WebCrypto, wherever we are: browsers and Node >= 19 expose it globally;
155
+ * Node 18 (the `engines` floor) needs the node:crypto fallback. */
156
+ function subtleCrypto(): Digester {
157
+ type WebCrypto = { subtle?: Digester };
158
+ let c = (globalThis as { crypto?: WebCrypto }).crypto;
159
+ if (!c?.subtle && typeof require === 'function') {
160
+ // eslint-disable-next-line @typescript-eslint/no-var-requires
161
+ c = (require('crypto') as { webcrypto?: WebCrypto }).webcrypto;
162
+ }
163
+ if (!c?.subtle) {
164
+ throw new Error('Settings: no WebCrypto SubtleCrypto available (need a browser or Node >= 18)');
165
+ }
166
+ return c.subtle;
167
+ }
168
+
169
+ /** sha256 of a string's UTF-8 bytes, lowercase hex, no `0x`. */
170
+ export async function sha256Hex(s: string): Promise<string> {
171
+ const digest = await subtleCrypto().digest('SHA-256', new TextEncoder().encode(s));
172
+ return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('');
173
+ }
174
+
175
+ /**
176
+ * The exact statement the owner signs. ASCII and short by construction — it
177
+ * travels in `X-Auth-Message`. Two forms, one grammar:
178
+ *
179
+ * write `AgenticID.Settings.v1:0x<sealId>:<unix seconds>:<base_version>:<sha256-hex>`
180
+ * read `AgenticID.Settings.v1:0x<sealId>:<unix seconds>:<base_version>`
181
+ *
182
+ * `baseVersion` is the version the writer read before editing — the
183
+ * compare-and-swap term. A read has no body and therefore no digest, and
184
+ * nothing to swap against, so it ends at `baseVersion` and sends 0.
185
+ */
186
+ export function settingsAuthMessage(
187
+ sealId: string,
188
+ unixSeconds: number,
189
+ baseVersion: number,
190
+ digestHex?: string,
191
+ ): string {
192
+ const head = `${SETTINGS_DOMAIN}:${sealId.toLowerCase()}:${unixSeconds}:${baseVersion}`;
193
+ return digestHex === undefined ? head : `${head}:${digestHex}`;
194
+ }
195
+
196
+ /**
197
+ * A write whose `base_version` no longer matches what the attestor holds
198
+ * (HTTP 409): somebody else changed the document between the read and the
199
+ * write, or the request is a replay of a superseded one.
200
+ *
201
+ * The SDK re-reads before throwing, so {@link current} / {@link currentVersion}
202
+ * are the live document — enough for a caller to show what it would have
203
+ * overwritten. It deliberately does NOT retry: re-applying the same edit
204
+ * blindly is how the other writer's change disappears, which is the whole
205
+ * thing the version guard exists to prevent. Re-apply the edit onto
206
+ * {@link current} and write again against {@link currentVersion} — as a human
207
+ * decision, not a loop.
208
+ */
209
+ export class SettingsConflictError extends Error {
210
+ readonly name = 'SettingsConflictError';
211
+ /** The agent whose document was contested. */
212
+ readonly sealId: string;
213
+ /** The version this write was made against. */
214
+ readonly baseVersion: number;
215
+ /** The version the attestor holds now (0 when it could not be re-read). */
216
+ readonly currentVersion: number;
217
+ /** The document the attestor holds now; null when unset or unreadable. */
218
+ readonly current: SettingsDoc | null;
219
+
220
+ constructor(args: {
221
+ sealId: string;
222
+ baseVersion: number;
223
+ currentVersion: number;
224
+ current: SettingsDoc | null;
225
+ detail?: string;
226
+ }) {
227
+ super(
228
+ `settings: version conflict on ${args.sealId} — you edited version ${args.baseVersion}, ` +
229
+ `the attestor now holds version ${args.currentVersion}. ` +
230
+ 'Someone else changed this agent\'s configuration; re-read it, re-apply your change, and write again.' +
231
+ (args.detail ? ` (${args.detail})` : ''),
232
+ );
233
+ this.sealId = args.sealId;
234
+ this.baseVersion = args.baseVersion;
235
+ this.currentVersion = args.currentVersion;
236
+ this.current = args.current;
237
+ }
238
+ }
239
+
240
+ /**
241
+ * The advisory model check: is `model` in the 0G router's public catalog?
242
+ *
243
+ * ADVISORY ONLY, in both directions. A framework built-in
244
+ * (`anthropic/claude-…`) is legitimately absent from a catalog that covers
245
+ * the 0G router alone, and the container is the real gate — so an absence is
246
+ * a warning, never a refusal. An unreachable catalog produces no warning at
247
+ * all rather than a false one.
248
+ *
249
+ * Never throws.
250
+ *
251
+ * @returns human-readable warnings; empty when everything looked fine, the
252
+ * catalog was unreachable, or there was nothing to check.
253
+ */
254
+ export async function modelAdvisory(doc: SettingsDoc, resolvedProvider?: InferenceProvider): Promise<string[]> {
255
+ const model = doc.model?.trim();
256
+ if (!model) return [];
257
+ const provider = doc.provider?.trim() || ZG_COMPUTE_PROVIDER;
258
+ const definition = resolvedProvider ?? inferenceProvider(provider);
259
+ if (!definition.modelCatalog && !definition.models?.length) return [];
260
+ let ids: string[] | null;
261
+ try { ids = (await modelsForProvider(definition)).map((model) => model.id); } catch { ids = null; }
262
+ if (!ids) return []; // catalog unreachable — say nothing rather than something wrong
263
+ if (ids.some((id) => id.toLowerCase() === model.toLowerCase())) return [];
264
+ // Typo help, cheap and predictable: a substring either way, or a shared
265
+ // prefix long enough to be a family rather than a coincidence
266
+ // ("glm-4.7" → "glm-4.6"; "claude-opus-4" → nothing).
267
+ const needle = model.toLowerCase().split('/').pop() ?? model.toLowerCase();
268
+ const shared = (a: string, b: string): number => {
269
+ let i = 0;
270
+ while (i < a.length && i < b.length && a[i] === b[i]) i++;
271
+ return i;
272
+ };
273
+ const near = ids
274
+ .filter((id) => {
275
+ const lid = id.toLowerCase();
276
+ return lid.includes(needle) || needle.includes(lid) || shared(lid, needle) >= 4;
277
+ })
278
+ .slice(0, 3);
279
+ // provider '0g-compute' = the platform routes this model, so the router
280
+ // catalog IS authoritative there; any other provider is a framework
281
+ // built-in whose models the catalog never lists.
282
+ const routed = !!doc.provider?.trim() && !definition.native;
283
+ return [
284
+ `model "${model}" is not in the ${provider === ZG_COMPUTE_PROVIDER ? '0G router' : provider} catalog` +
285
+ (routed
286
+ ? ` — and provider "${provider}" means the platform routes it there, so this one probably will not resolve.`
287
+ : ' — expected for a framework built-in; the container decides.') +
288
+ (near.length ? ` Close matches: ${near.join(', ')}.` : ''),
289
+ ];
290
+ }
291
+
292
+ /** The router catalog's model ids, or null when it could not be read. */
293
+ export async function fetchRouterModelIds(provider = ZG_COMPUTE_PROVIDER): Promise<string[] | null> {
294
+ try { return (await inferenceModels(provider)).map((model) => model.id); }
295
+ catch { return null; }
296
+ }