@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
@@ -17,9 +17,28 @@
17
17
  * services via `fetch`/`fetchWithProof` and captures the proof.
18
18
  */
19
19
  Object.defineProperty(exports, "__esModule", { value: true });
20
+ exports.plainText = plainText;
20
21
  exports.mcpServices = mcpServices;
22
+ exports.withImages = withImages;
21
23
  exports.makeAgentClient = makeAgentClient;
22
24
  const ServeSession_1 = require("./ServeSession");
25
+ /** What a task id the agent returns must look like to be handed out. */
26
+ const TASK_ID = /^[A-Za-z0-9_.:-]{1,128}$/;
27
+ /**
28
+ * Text from the agent (an activity label, an error it sent) made one plain
29
+ * line for display: escape sequences, control characters and bidi controls
30
+ * removed, so a program that prints it cannot have its terminal restyled.
31
+ */
32
+ function plainText(s) {
33
+ return s
34
+ .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, '')
35
+ .replace(/\u009b[0-?]*[ -/]*[@-~]/g, '')
36
+ .replace(/\u001b\][^\u0007\u001b\u009c]*(?:\u0007|\u001b\\|\u009c)?/g, '')
37
+ .replace(/\u001b[PX^_][^\u001b\u009c]*(?:\u001b\\|\u009c)?/g, '')
38
+ // eslint-disable-next-line no-control-regex
39
+ .replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, ' ')
40
+ .replace(/[\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, '');
41
+ }
23
42
  /**
24
43
  * The agent's MCP-mountable service endpoints — the `/hello` entries marked
25
44
  * `transport: "mcp"`. This is the consumption half of trusted-MCP serving:
@@ -175,11 +194,11 @@ function chunkDelta(chunk) {
175
194
  return { role: delta?.role, content };
176
195
  }
177
196
  /** Fold an SSE chat stream into a single reassembled {@link ChatCompletion}. */
178
- async function collectChatStream(body) {
197
+ async function collectChatStream(body, onComment) {
179
198
  let content = '';
180
199
  let role = 'assistant';
181
200
  let last = {};
182
- for await (const chunk of iterSseChunks(body)) {
201
+ for await (const chunk of iterSseChunks(body, onComment)) {
183
202
  last = chunk;
184
203
  const d = chunkDelta(chunk);
185
204
  if (d.role)
@@ -188,6 +207,67 @@ async function collectChatStream(body) {
188
207
  }
189
208
  return { ...last, choices: [{ message: { role, content } }] };
190
209
  }
210
+ // Base64 without Node's Buffer, so the module runs in browsers too.
211
+ function bytesToBase64(bytes) {
212
+ let bin = '';
213
+ for (let i = 0; i < bytes.length; i += 0x8000)
214
+ bin += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
215
+ return btoa(bin);
216
+ }
217
+ const imageUrl = (im) => `data:${im.mediaType};base64,${im.data}`;
218
+ /**
219
+ * The messages with `images` on the last user message, in the request's own
220
+ * shape: chat/completions `image_url` parts, or Responses `input_text` /
221
+ * `input_image` parts. No images: the messages as they are.
222
+ */
223
+ function withImages(messages, images, shape, names = false) {
224
+ if (!images?.length)
225
+ return messages;
226
+ let i = messages.length - 1;
227
+ while (i >= 0 && messages[i].role !== 'user')
228
+ i--;
229
+ const text = i >= 0 ? messages[i].content : '';
230
+ // `filename` only where the agent reads it (`names`): another runtime may refuse a field it does not know.
231
+ const named = (im) => (names && im.name ? { filename: im.name } : {});
232
+ const content = shape === 'chat'
233
+ ? [{ type: 'text', text }, ...images.map((im) => ({ type: 'image_url', image_url: { url: imageUrl(im) }, ...named(im) }))]
234
+ : [{ type: 'input_text', text }, ...images.map((im) => ({ type: 'input_image', image_url: imageUrl(im), ...named(im) }))];
235
+ const out = messages.slice();
236
+ if (i >= 0)
237
+ out[i] = { role: 'user', content };
238
+ else
239
+ out.push({ role: 'user', content });
240
+ return out;
241
+ }
242
+ /** The notice an SSE comment carries (`: notice images_saved_as_files [...]`, `: notice outbox_files [...]`), if any. */
243
+ function noticeOf(comment) {
244
+ const m = /^notice (images_saved_as_files|outbox_files) (\[.*\])$/.exec(comment);
245
+ if (!m)
246
+ return undefined;
247
+ try {
248
+ const items = JSON.parse(m[2]);
249
+ if (!Array.isArray(items) || !items.every((p) => typeof p === 'string'))
250
+ return undefined;
251
+ const clean = items.map((p) => plainText(p));
252
+ return m[1] === 'outbox_files' ? { outboxFiles: clean } : { imagesSavedAsFiles: clean };
253
+ }
254
+ catch { /* not a notice */ }
255
+ return undefined;
256
+ }
257
+ /** The notice a buffered reply or a Responses record carries in `harness`, if any. */
258
+ function harnessNotice(harness) {
259
+ if (!harness)
260
+ return undefined;
261
+ const n = {};
262
+ const strings = (v) => Array.isArray(v) && v.length && v.every((p) => typeof p === 'string') ? v.map((p) => plainText(p)) : undefined;
263
+ const images = strings(harness.images_saved_as_files);
264
+ const outbox = strings(harness.outbox_files);
265
+ if (images)
266
+ n.imagesSavedAsFiles = images;
267
+ if (outbox)
268
+ n.outboxFiles = outbox;
269
+ return images || outbox ? n : undefined;
270
+ }
191
271
  /**
192
272
  * Build an {@link AgentClient} from a base URL, the agent's declared surface,
193
273
  * and (optionally) a way to authenticate:
@@ -290,7 +370,32 @@ function makeAgentClient(params) {
290
370
  // deploy. There's no framework-agnostic default (/hello doesn't declare it),
291
371
  // so omit the field when the caller doesn't set one rather than sending a
292
372
  // bogus value the framework rejects.
293
- const chatBody = (messages, opts) => JSON.stringify(opts?.model ? { model: opts.model, messages, stream: true } : { messages, stream: true });
373
+ const chatBody = async (messages, opts) => {
374
+ const sent = withImages(messages, opts?.images, 'chat', await imageNames(opts?.images));
375
+ return JSON.stringify(opts?.model ? { model: opts.model, messages: sent, stream: true } : { messages: sent, stream: true });
376
+ };
377
+ // What the agent's runtime says it reads (0g-harness `GET /v1/harness`,
378
+ // `features`), asked once; null where there is no such route.
379
+ let featuresAsked = null;
380
+ const harnessFeatures = () => {
381
+ const r = routes.find((x) => x.kind === 'chat') ?? routes.find((x) => x.kind === 'responses');
382
+ if (!r || !canAuth)
383
+ return Promise.resolve(null);
384
+ const path = r.kind === 'chat' ? `${r.prefix.replace(/\/?$/, '/')}harness` : r.prefix.replace(/responses\/?$/, 'harness');
385
+ featuresAsked ?? (featuresAsked = doFetch(path, { signal: AbortSignal.timeout(5000) })
386
+ .then(async (res) => {
387
+ if (res.status === 404)
388
+ return null; // not a harness: it never will be
389
+ if (!res.ok)
390
+ throw new Error(`harness: HTTP ${res.status}`);
391
+ const f = (await res.json()).features;
392
+ return f && typeof f === 'object' ? f : null;
393
+ })
394
+ .catch(() => { featuresAsked = null; return null; })); // asked again next time
395
+ return featuresAsked;
396
+ };
397
+ /** Whether image parts carry their file name: only where the agent says it reads it. */
398
+ const imageNames = async (images) => !!images?.some((im) => im.name) && (await harnessFeatures())?.image_names === true;
294
399
  const chat = routes.find((r) => r.kind === 'chat');
295
400
  if (chat && canAuth) {
296
401
  // OpenAI-compatible convention: completions sit at `<prefix>chat/completions`.
@@ -312,7 +417,7 @@ function makeAgentClient(params) {
312
417
  }
313
418
  if (r.status === 404)
314
419
  return { aborted: false, note: 'no bridge endpoint — this framework stops its turn when the stream disconnects' };
315
- throw new Error(`interrupt: HTTP ${r.status}: ${await r.text()}`);
420
+ throw new Error(`interrupt: HTTP ${r.status}: ${plainText(await r.text())}`);
316
421
  }
317
422
  catch (e) {
318
423
  if (e.message.startsWith('interrupt:'))
@@ -324,26 +429,31 @@ function makeAgentClient(params) {
324
429
  const r = await doFetch(path, {
325
430
  method: 'POST',
326
431
  headers: { 'content-type': 'application/json' },
327
- body: chatBody(messages, opts),
432
+ body: await chatBody(messages, opts),
328
433
  signal: opts?.signal,
329
434
  });
330
435
  if (!r.ok)
331
- throw new Error(`chat: HTTP ${r.status}: ${await r.text()}`);
436
+ throw new Error(`chat: HTTP ${r.status}: ${plainText(await r.text())}`);
332
437
  const ct = r.headers.get('content-type') ?? '';
333
438
  if (!r.body || !ct.toLowerCase().includes('text/event-stream')) {
334
- return (await r.json()); // server didn't stream → plain JSON
439
+ const full = (await r.json());
440
+ const n = harnessNotice(full.harness);
441
+ if (n)
442
+ opts?.onNotice?.(n);
443
+ return full; // server didn't stream → plain JSON
335
444
  }
336
- return collectChatStream(r.body);
445
+ return collectChatStream(r.body, opts?.onNotice ? (c) => { const n = noticeOf(c); if (n)
446
+ opts.onNotice(n); } : undefined);
337
447
  };
338
448
  client.chatStream = async function* (messages, opts) {
339
449
  const r = await doFetch(path, {
340
450
  method: 'POST',
341
451
  headers: { 'content-type': 'application/json' },
342
- body: chatBody(messages, opts),
452
+ body: await chatBody(messages, opts),
343
453
  signal: opts?.signal,
344
454
  });
345
455
  if (!r.ok)
346
- throw new Error(`chat: HTTP ${r.status}: ${await r.text()}`);
456
+ throw new Error(`chat: HTTP ${r.status}: ${plainText(await r.text())}`);
347
457
  const ct = r.headers.get('content-type') ?? '';
348
458
  if (!r.body || !ct.toLowerCase().includes('text/event-stream')) {
349
459
  // Server didn't stream — yield the whole reply as one delta. An EMPTY
@@ -363,9 +473,14 @@ function makeAgentClient(params) {
363
473
  // (feedback.md F15)
364
474
  let sawContent = false;
365
475
  let streamErr = null;
366
- const onComment = opts?.onActivity
367
- ? (c) => { if (c.startsWith('activity '))
368
- opts.onActivity(c.slice(9)); }
476
+ const onComment = opts?.onActivity || opts?.onNotice
477
+ ? (c) => {
478
+ if (c.startsWith('activity '))
479
+ opts.onActivity?.(plainText(c.slice(9)));
480
+ const n = noticeOf(c);
481
+ if (n)
482
+ opts.onNotice?.(n);
483
+ }
369
484
  : undefined;
370
485
  let lastThinkingAt = 0;
371
486
  const thinking = () => {
@@ -388,10 +503,10 @@ function makeAgentClient(params) {
388
503
  thinking();
389
504
  else if (ev === 'hermes.tool.progress') {
390
505
  if (tool)
391
- opts.onActivity(`tool/call ${tool}`);
506
+ opts.onActivity(plainText(`tool/call ${tool}`));
392
507
  }
393
508
  else
394
- opts.onActivity(tool ? `${ev.replace(/^hermes\./, '')} ${tool}` : ev.replace(/^hermes\./, ''));
509
+ opts.onActivity(plainText(tool ? `${ev.replace(/^hermes\./, '')} ${tool}` : ev.replace(/^hermes\./, '')));
395
510
  }
396
511
  continue;
397
512
  }
@@ -406,7 +521,7 @@ function makeAgentClient(params) {
406
521
  for (const tc of delta?.tool_calls ?? []) {
407
522
  const fn = tc?.function?.name;
408
523
  if (fn)
409
- opts.onActivity(`tool/call ${fn}`);
524
+ opts.onActivity(plainText(`tool/call ${fn}`));
410
525
  }
411
526
  }
412
527
  const d = chunkDelta(chunk);
@@ -417,7 +532,7 @@ function makeAgentClient(params) {
417
532
  }
418
533
  if (!sawContent) {
419
534
  throw new Error(streamErr
420
- ? `chat: upstream error: ${streamErr}`
535
+ ? `chat: upstream error: ${plainText(String(streamErr))}`
421
536
  : 'chat: the stream ended without any output — the agent-side model call likely failed (see /agentlog)');
422
537
  }
423
538
  };
@@ -438,7 +553,7 @@ function makeAgentClient(params) {
438
553
  const taskSnapshot = async (id) => {
439
554
  const r = await doFetch(`${rPrefix}/${id}`);
440
555
  if (!r.ok)
441
- throw new Error(`task: HTTP ${r.status}: ${await r.text()}`);
556
+ throw new Error(`task: HTTP ${r.status}: ${plainText(await r.text())}`);
442
557
  return (await r.json());
443
558
  };
444
559
  // Normalize activity labels across serving layers: hermes narrates its
@@ -487,8 +602,8 @@ function makeAgentClient(params) {
487
602
  // the threshold is small (at stallMs=150 it made the give-up path 24s of
488
603
  // a 29s suite) and is the last constant not derived from the threshold.
489
604
  const backoffFor = (n) => Math.min(500 * 2 ** n, 8000, Math.max(50, STALL_MS * 4));
490
- const lostAgent = (id, why) => new Error(`task ${id}: lost the agent while following (${why}) — ` +
491
- `the task may still be running; re-attach with followTask("${id}")`);
605
+ const lostAgent = (id, why) => new Error(`task ${plainText(String(id))}: lost the agent while following (${plainText(why)}) — ` +
606
+ `the task may still be running; re-attach with followTask("${plainText(String(id))}")`);
492
607
  async function* followResponse(args) {
493
608
  const id = args.id;
494
609
  let seq = args.startingAfter ?? 0;
@@ -529,7 +644,7 @@ function makeAgentClient(params) {
529
644
  try {
530
645
  const r = await doFetch(`${rPrefix}/${id}?stream=true&starting_after=${seq}`, { signal: attempt.signal });
531
646
  if (!r.ok)
532
- throw new Error(`HTTP ${r.status}: ${await r.text()}`);
647
+ throw new Error(`HTTP ${r.status}: ${plainText(await r.text())}`);
533
648
  res = r;
534
649
  lastByteAt = Date.now();
535
650
  }
@@ -578,7 +693,7 @@ function makeAgentClient(params) {
578
693
  case 'response.activity': {
579
694
  const label = chunk.label;
580
695
  if (args.onActivity && typeof label === 'string')
581
- args.onActivity(label);
696
+ args.onActivity(plainText(label));
582
697
  break;
583
698
  }
584
699
  case 'response.completed':
@@ -623,8 +738,14 @@ function makeAgentClient(params) {
623
738
  args.signal.removeEventListener('abort', onOuterAbort);
624
739
  }
625
740
  }
741
+ // Notices known only when the turn ends (files it left in the outbox).
742
+ {
743
+ const n = harnessNotice(terminal.harness);
744
+ if (n?.outboxFiles)
745
+ args.onNotice?.({ outboxFiles: n.outboxFiles });
746
+ }
626
747
  if (terminal.status === 'failed') {
627
- throw new Error(`chat: ${terminal.error?.message ?? 'task failed'}`);
748
+ throw new Error(`chat: ${plainText(terminal.error?.message ?? 'task failed')}`);
628
749
  }
629
750
  if (terminal.status === 'cancelled')
630
751
  return; // owner stopped it — partial text already yielded
@@ -646,7 +767,7 @@ function makeAgentClient(params) {
646
767
  // returns the id in milliseconds, so every long-lived byte after that
647
768
  // travels on a GET we can always resume by id. One extra round trip
648
769
  // buys the guarantee that a task is never lost to a dropped connection.
649
- const payload = { input: messages };
770
+ const payload = { input: withImages(messages, opts?.images, 'responses', await imageNames(opts?.images)) };
650
771
  if (opts?.model)
651
772
  payload.model = opts.model;
652
773
  if (opts?.thinking)
@@ -658,16 +779,23 @@ function makeAgentClient(params) {
658
779
  signal: opts?.signal,
659
780
  });
660
781
  if (!r.ok)
661
- throw new Error(`chat: HTTP ${r.status}: ${await r.text()}`);
782
+ throw new Error(`chat: HTTP ${r.status}: ${plainText(await r.text())}`);
662
783
  const submitted = (await r.json());
663
784
  if (!submitted?.id)
664
785
  throw new Error('chat: the agent accepted the task but returned no id');
665
- opts?.onTask?.(submitted.id);
786
+ const saved = harnessNotice(submitted.harness)?.imagesSavedAsFiles;
787
+ if (saved)
788
+ opts?.onNotice?.({ imagesSavedAsFiles: saved });
789
+ // A task id is a name to re-attach with: one that is not a plain
790
+ // identifier is not handed out to be printed.
791
+ if (TASK_ID.test(submitted.id))
792
+ opts?.onTask?.(submitted.id);
666
793
  yield* followResponse({
667
794
  id: submitted.id,
668
795
  startingAfter: 0,
669
796
  signal: opts?.signal,
670
797
  onActivity: wrapActivity(opts?.onActivity),
798
+ onNotice: opts?.onNotice,
671
799
  });
672
800
  };
673
801
  client.chat = async (messages, opts) => {
@@ -686,11 +814,11 @@ function makeAgentClient(params) {
686
814
  client.cancelTask = async (id) => {
687
815
  const r = await doFetch(`${rPrefix}/${id}/cancel`, { method: 'POST' });
688
816
  if (!r.ok)
689
- throw new Error(`cancelTask: HTTP ${r.status}: ${await r.text()}`);
817
+ throw new Error(`cancelTask: HTTP ${r.status}: ${plainText(await r.text())}`);
690
818
  return (await r.json());
691
819
  };
692
820
  }
693
- // ── The agent's own work: inbox, live feed, tasks, reminders ─────────────
821
+ // ── The agent's own work: inbox, live feed, activities, reminders ────────
694
822
  //
695
823
  // An agent that works in the background (commands, subagents, reminders)
696
824
  // also opens turns by itself, and their words belong to no chat request.
@@ -712,7 +840,7 @@ function makeAgentClient(params) {
712
840
  const getJSON = async (what, path) => {
713
841
  const r = await doFetch(path);
714
842
  if (!r.ok)
715
- throw new Error(`${what}: HTTP ${r.status}: ${await r.text()}`);
843
+ throw new Error(`${what}: HTTP ${r.status}: ${plainText(await r.text())}`);
716
844
  return (await r.json());
717
845
  };
718
846
  const postJSON = async (what, path, body) => {
@@ -721,7 +849,7 @@ function makeAgentClient(params) {
721
849
  ...(body === undefined ? {} : { headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) }),
722
850
  });
723
851
  if (!r.ok)
724
- throw new Error(`${what}: HTTP ${r.status}: ${await r.text()}`);
852
+ throw new Error(`${what}: HTTP ${r.status}: ${plainText(await r.text())}`);
725
853
  return (await r.json());
726
854
  };
727
855
  const inboxBase = ownerBase('inbox');
@@ -729,17 +857,43 @@ function makeAgentClient(params) {
729
857
  client.inbox = (opts) => getJSON('inbox', `${inboxBase}${query({ after: opts?.after, limit: opts?.limit })}`);
730
858
  client.ackInbox = (through) => postJSON('ackInbox', `${inboxBase}/ack`, { through });
731
859
  }
732
- const tasksBase = ownerBase('tasks');
733
- if (tasksBase) {
734
- client.tasks = async (opts) => (await getJSON('tasks', `${tasksBase}${query({ status: opts?.status, limit: opts?.limit })}`)).data;
735
- client.taskInfo = (id) => getJSON('taskInfo', `${tasksBase}/${encodeURIComponent(id)}`);
736
- client.stopTask = async (id) => {
860
+ // The activity list: /v1/activities, or /v1/tasks, its old name, on a
861
+ // runtime from before the rename. A newer sealed can run an older harness
862
+ // package, which answers 404 on /v1/activities: then the old name. A
863
+ // runtime that declares `task-feed` serves zgh-style tasks on /v1/tasks
864
+ // instead (below), so there is no old name to fall back to.
865
+ const taskFeedBase = ownerBase('task-feed');
866
+ const activitiesBase = ownerBase('activities');
867
+ const legacyTasksBase = taskFeedBase ? undefined : ownerBase('tasks');
868
+ if (activitiesBase || legacyTasksBase) {
869
+ let base = (activitiesBase ?? legacyTasksBase);
870
+ const activityCall = async (what, rest, post = false) => {
871
+ const send = (b) => doFetch(`${b}${rest}`, post ? { method: 'POST' } : undefined);
872
+ let r = await send(base);
873
+ if (r.status === 404 && base === activitiesBase && legacyTasksBase) {
874
+ const old = await send(legacyTasksBase);
875
+ if (old.status !== 404) {
876
+ base = legacyTasksBase;
877
+ r = old;
878
+ }
879
+ }
880
+ if (!r.ok)
881
+ throw new Error(`${what}: HTTP ${r.status}: ${plainText(await r.text())}`);
882
+ return (await r.json());
883
+ };
884
+ client.activities = async (opts) => (await activityCall('activities', query({ status: opts?.status, limit: opts?.limit }))).data;
885
+ client.activity = (id) => activityCall('activity', `/${encodeURIComponent(id)}`);
886
+ client.stopActivity = async (id) => {
737
887
  // `all` is a different request with a different answer.
738
888
  if (id === 'all')
739
- throw new Error('stopTask: "all" is stopAllTasks()');
740
- return postJSON('stopTask', `${tasksBase}/${encodeURIComponent(id)}/cancel`);
889
+ throw new Error('stopActivity: "all" is stopAllActivities()');
890
+ return activityCall('stopActivity', `/${encodeURIComponent(id)}/cancel`, true);
741
891
  };
742
- client.stopAllTasks = async () => (await postJSON('stopAllTasks', `${tasksBase}/all/cancel`)).data;
892
+ client.stopAllActivities = async () => (await activityCall('stopAllActivities', '/all/cancel', true)).data;
893
+ client.tasks = client.activities;
894
+ client.taskInfo = client.activity;
895
+ client.stopTask = client.stopActivity;
896
+ client.stopAllTasks = client.stopAllActivities;
743
897
  }
744
898
  const schedulesBase = ownerBase('schedules');
745
899
  if (schedulesBase) {
@@ -748,6 +902,135 @@ function makeAgentClient(params) {
748
902
  return { enabled: j.enabled !== false, data: j.data ?? [] };
749
903
  };
750
904
  }
905
+ const filesBase = ownerBase('files');
906
+ if (filesBase) {
907
+ client.uploadFile = (name, data) => postJSON('uploadFile', filesBase, { name, content_base64: bytesToBase64(data) });
908
+ // Downloads share the files route; an agent whose runtime predates them
909
+ // does not list the GET endpoints, and the proxy answers 404.
910
+ const noDownloads = (what, status, text) => status === 404 && /no route|not found|404/i.test(text) && !/no file /.test(text)
911
+ ? new Error(`${what}: this agent's runtime does not serve downloads (update the agent)`)
912
+ : new Error(`${what}: HTTP ${status}: ${plainText(text)}`);
913
+ client.listFiles = async (dir = 'outbox') => {
914
+ const r = await doFetch(`${filesBase}${query({ dir })}`);
915
+ if (!r.ok)
916
+ throw noDownloads('listFiles', r.status, await r.text());
917
+ const j = (await r.json());
918
+ return (j.data ?? []).map((f) => ({ ...f, name: plainText(String(f.name)) }));
919
+ };
920
+ client.downloadFile = async (dir, name) => {
921
+ if (dir !== 'outbox' && dir !== 'inbox')
922
+ throw new Error('downloadFile: dir is outbox or inbox');
923
+ if (!name || name.includes('/') || name.includes('\\') || name.startsWith('.'))
924
+ throw new Error('downloadFile: a file name is one path segment, without a leading dot');
925
+ const r = await doFetch(`${filesBase}/${dir}/${encodeURIComponent(name)}`);
926
+ if (!r.ok)
927
+ throw noDownloads('downloadFile', r.status, await r.text());
928
+ return new Uint8Array(await r.arrayBuffer());
929
+ };
930
+ client.deleteFile = async (dir, name) => {
931
+ if (dir !== 'outbox' && dir !== 'inbox')
932
+ throw new Error('deleteFile: dir is outbox or inbox');
933
+ if (!name || name.includes('/') || name.includes('\\') || name.startsWith('.'))
934
+ throw new Error('deleteFile: a file name is one path segment, without a leading dot');
935
+ const r = await doFetch(`${filesBase}/${dir}/${encodeURIComponent(name)}`, { method: 'DELETE' });
936
+ if (r.ok)
937
+ return 'deleted';
938
+ const text = await r.text();
939
+ // The harness answers a missing file with "no file …"; anything else
940
+ // that is not found (or a method the route does not take) is a runtime
941
+ // without the delete route.
942
+ if (r.status === 404 && /no file /i.test(text))
943
+ return 'missing';
944
+ if (r.status === 404 || r.status === 405)
945
+ return 'unsupported';
946
+ throw new Error(`deleteFile: HTTP ${r.status}: ${plainText(text)}`);
947
+ };
948
+ }
949
+ const steerBase = ownerBase('steer');
950
+ if (steerBase) {
951
+ client.steer = (text) => postJSON('steer', steerBase, { text });
952
+ client.steerState = (id) => getJSON('steerState', `${steerBase}/${encodeURIComponent(id)}`);
953
+ }
954
+ const sessionsBase = ownerBase('sessions');
955
+ if (sessionsBase) {
956
+ const sid = (id) => {
957
+ // owner-chat, an owner session, a task, or a session a schedule opened (DSH's `session-…` ids).
958
+ if (!/^(owner-chat|(sess|task)-[a-z0-9][a-z0-9-]{0,62}|session-[a-z0-9][a-z0-9-]{0,90})$/.test(id))
959
+ throw new Error(`not a session id: ${plainText(id)}`);
960
+ return `${sessionsBase}/${id}`;
961
+ };
962
+ const clean = (s) => ({ ...s, title: plainText(String(s.title ?? '')) });
963
+ client.sessions = async () => ((await getJSON('sessions', sessionsBase)).data ?? []).map(clean);
964
+ client.session = async (id) => clean(await getJSON('session', sid(id)));
965
+ client.createSession = async (opts = {}) => clean(await postJSON('createSession', sessionsBase, opts));
966
+ client.promptSession = (id, text, opts = {}) => postJSON('promptSession', `${sid(id)}/prompt`, { text, ...(opts.mode ? { mode: opts.mode } : {}) });
967
+ client.cancelSession = (id) => postJSON('cancelSession', `${sid(id)}/cancel`);
968
+ }
969
+ // zgh-style tasks: /v1/tasks with the `task-feed` kind beside it (an older
970
+ // runtime's `tasks` kind alone is the activity list's old name).
971
+ const tasksBase = taskFeedBase ? ownerBase('tasks') : undefined;
972
+ if (tasksBase && taskFeedBase) {
973
+ const tid = (id) => {
974
+ // A task's id, or a scheduled task's (the session id a schedule gave it).
975
+ if (!/^(task-[a-z0-9][a-z0-9-]{0,62}|session-[a-z0-9][a-z0-9-]{0,90})$/.test(id))
976
+ throw new Error(`not a task id: ${plainText(id)}`);
977
+ return `${tasksBase}/${id}`;
978
+ };
979
+ const clean = (t) => (t && typeof t.title === 'string' ? { ...t, title: plainText(t.title) } : t);
980
+ client.createTask = async (opts) => {
981
+ const r = await doFetch(tasksBase, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(opts) });
982
+ const text = await r.text();
983
+ let body;
984
+ try {
985
+ body = JSON.parse(text);
986
+ }
987
+ catch {
988
+ body = undefined;
989
+ }
990
+ if (r.status === 201 && body)
991
+ return { task: clean(body), created: true };
992
+ const taken = body;
993
+ if (r.status === 409 && taken?.error?.code === 'id-taken' && taken.task)
994
+ return { task: clean(taken.task), created: false };
995
+ throw new Error(`createTask: HTTP ${r.status}: ${plainText(text)}`);
996
+ };
997
+ client.listTasks = async (opts = {}) => {
998
+ const q = new URLSearchParams();
999
+ for (const st of opts.state === undefined ? [] : Array.isArray(opts.state) ? opts.state : [opts.state])
1000
+ q.append('state', st);
1001
+ for (const [k, v] of Object.entries(opts.metadata ?? {}))
1002
+ q.set(`metadata.${k}`, v);
1003
+ if (opts.limit !== undefined)
1004
+ q.set('limit', String(opts.limit));
1005
+ const qs = q.toString();
1006
+ return ((await getJSON('listTasks', `${tasksBase}${qs ? `?${qs}` : ''}`)).data ?? []).map(clean);
1007
+ };
1008
+ client.getTask = async (id) => clean(await getJSON('getTask', tid(id)));
1009
+ client.taskInput = async (id, text, opts = {}) => clean(await postJSON('taskInput', `${tid(id)}/input`, { text, ...(opts.mode ? { mode: opts.mode } : {}) }));
1010
+ client.cancelTaskRun = async (id) => clean(await postJSON('cancelTaskRun', `${tid(id)}/cancel`));
1011
+ client.archiveTask = async (id) => clean(await postJSON('archiveTask', `${tid(id)}/archive`));
1012
+ client.taskFeed = async function* (opts) {
1013
+ const res = await doFetch(taskFeedBase, opts?.signal ? { signal: opts.signal } : undefined);
1014
+ if (!res.ok)
1015
+ throw new Error(`taskFeed: HTTP ${res.status}: ${plainText(await res.text())}`);
1016
+ if (!res.body)
1017
+ throw new Error('taskFeed: expected an SSE stream from the task-feed route');
1018
+ try {
1019
+ for await (const chunk of iterSseChunks(res.body)) {
1020
+ const { __sseEvent, ...data } = chunk;
1021
+ if (__sseEvent === 'ready')
1022
+ yield { type: 'ready' };
1023
+ else if (__sseEvent === 'task' && typeof data.id === 'string')
1024
+ yield { type: 'task', task: data };
1025
+ }
1026
+ }
1027
+ catch (err) {
1028
+ if (opts?.signal?.aborted)
1029
+ return;
1030
+ throw err;
1031
+ }
1032
+ };
1033
+ }
751
1034
  const eventsBase = ownerBase('events');
752
1035
  if (eventsBase) {
753
1036
  // The agent sends a keepalive every 10s, so this much silence means the
@@ -794,7 +1077,7 @@ function makeAgentClient(params) {
794
1077
  // A 4xx is an answer (the route is gone, the handle is refused),
795
1078
  // and asking again gets the same one.
796
1079
  if (res.status < 500 && res.status !== 408 && res.status !== 429) {
797
- throw new Error(`events: HTTP ${res.status}: ${text}`);
1080
+ throw new Error(`events: HTTP ${res.status}: ${plainText(text)}`);
798
1081
  }
799
1082
  res = undefined;
800
1083
  }
@@ -861,7 +1144,7 @@ function makeAgentClient(params) {
861
1144
  signal: AbortSignal.timeout(30000),
862
1145
  });
863
1146
  if (!r.ok)
864
- throw new Error(`logs: HTTP ${r.status}: ${await r.text()}`);
1147
+ throw new Error(`logs: HTTP ${r.status}: ${plainText(await r.text())}`);
865
1148
  const text = await r.text();
866
1149
  if (opts?.tail && opts.tail > 0) {
867
1150
  return text.split('\n').slice(-opts.tail).join('\n');