genaicode 2.33.0 → 2.35.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 (194) hide show
  1. package/README.md +1 -0
  2. package/dist/agents/artifacts.d.ts +1 -1
  3. package/dist/agents/artifacts.js +4 -65
  4. package/dist/agents/artifacts.js.map +1 -1
  5. package/dist/agents/cli-agent.d.ts +3 -0
  6. package/dist/agents/cli-agent.js +1 -0
  7. package/dist/agents/cli-agent.js.map +1 -1
  8. package/dist/agents/drivers/anthropic-managed.d.ts +145 -0
  9. package/dist/agents/drivers/anthropic-managed.js +799 -0
  10. package/dist/agents/drivers/anthropic-managed.js.map +1 -0
  11. package/dist/agents/drivers/antigravity.js +2 -0
  12. package/dist/agents/drivers/antigravity.js.map +1 -1
  13. package/dist/agents/drivers/claude.js +2 -0
  14. package/dist/agents/drivers/claude.js.map +1 -1
  15. package/dist/agents/drivers/codex-live.js +2 -0
  16. package/dist/agents/drivers/codex-live.js.map +1 -1
  17. package/dist/agents/drivers/codex.js +2 -0
  18. package/dist/agents/drivers/codex.js.map +1 -1
  19. package/dist/agents/drivers/copilot.js +2 -0
  20. package/dist/agents/drivers/copilot.js.map +1 -1
  21. package/dist/agents/drivers/cursor-cloud.d.ts +78 -0
  22. package/dist/agents/drivers/cursor-cloud.js +523 -0
  23. package/dist/agents/drivers/cursor-cloud.js.map +1 -0
  24. package/dist/agents/drivers/cursor.js +2 -0
  25. package/dist/agents/drivers/cursor.js.map +1 -1
  26. package/dist/agents/drivers/gemini-managed.d.ts +78 -0
  27. package/dist/agents/drivers/gemini-managed.js +528 -0
  28. package/dist/agents/drivers/gemini-managed.js.map +1 -0
  29. package/dist/agents/drivers/gemini.js +2 -0
  30. package/dist/agents/drivers/gemini.js.map +1 -1
  31. package/dist/agents/drivers/managed-http.d.ts +28 -0
  32. package/dist/agents/drivers/managed-http.js +142 -0
  33. package/dist/agents/drivers/managed-http.js.map +1 -0
  34. package/dist/agents/drivers/muse-live.js +2 -0
  35. package/dist/agents/drivers/muse-live.js.map +1 -1
  36. package/dist/agents/drivers/muse.js +2 -0
  37. package/dist/agents/drivers/muse.js.map +1 -1
  38. package/dist/agents/drivers/openai-managed.d.ts +79 -0
  39. package/dist/agents/drivers/openai-managed.js +404 -0
  40. package/dist/agents/drivers/openai-managed.js.map +1 -0
  41. package/dist/agents/drivers/opencode.js +2 -0
  42. package/dist/agents/drivers/opencode.js.map +1 -1
  43. package/dist/agents/drivers/vibe.js +2 -0
  44. package/dist/agents/drivers/vibe.js.map +1 -1
  45. package/dist/agents/failover.d.ts +19 -1
  46. package/dist/agents/failover.js +63 -2
  47. package/dist/agents/failover.js.map +1 -1
  48. package/dist/agents/hosted.d.ts +5 -1
  49. package/dist/agents/hosted.js +47 -132
  50. package/dist/agents/hosted.js.map +1 -1
  51. package/dist/agents/live-agent.d.ts +3 -0
  52. package/dist/agents/live-agent.js +1 -0
  53. package/dist/agents/live-agent.js.map +1 -1
  54. package/dist/agents/managed.d.ts +157 -0
  55. package/dist/agents/managed.js +562 -0
  56. package/dist/agents/managed.js.map +1 -0
  57. package/dist/agents/mcp-server.d.ts +19 -0
  58. package/dist/agents/mcp-server.js +74 -0
  59. package/dist/agents/mcp-server.js.map +1 -0
  60. package/dist/agents/pack-git.d.ts +23 -0
  61. package/dist/agents/pack-git.js +112 -0
  62. package/dist/agents/pack-git.js.map +1 -0
  63. package/dist/agents/pack.d.ts +68 -0
  64. package/dist/agents/pack.js +611 -0
  65. package/dist/agents/pack.js.map +1 -0
  66. package/dist/agents/runtime.d.ts +5 -1
  67. package/dist/agents/runtime.js +9 -0
  68. package/dist/agents/runtime.js.map +1 -1
  69. package/dist/agents/session.d.ts +10 -0
  70. package/dist/agents/session.js +26 -0
  71. package/dist/agents/session.js.map +1 -1
  72. package/dist/agents/sessions/claude.d.ts +14 -0
  73. package/dist/agents/sessions/claude.js +233 -0
  74. package/dist/agents/sessions/claude.js.map +1 -0
  75. package/dist/agents/sessions/codex-api.d.ts +32 -0
  76. package/dist/agents/sessions/codex-api.js +233 -0
  77. package/dist/agents/sessions/codex-api.js.map +1 -0
  78. package/dist/agents/sessions/codex.d.ts +28 -0
  79. package/dist/agents/sessions/codex.js +430 -0
  80. package/dist/agents/sessions/codex.js.map +1 -0
  81. package/dist/agents/sessions/doctor.d.ts +67 -0
  82. package/dist/agents/sessions/doctor.js +182 -0
  83. package/dist/agents/sessions/doctor.js.map +1 -0
  84. package/dist/agents/sessions/files.d.ts +44 -0
  85. package/dist/agents/sessions/files.js +150 -0
  86. package/dist/agents/sessions/files.js.map +1 -0
  87. package/dist/agents/sessions/group.d.ts +24 -0
  88. package/dist/agents/sessions/group.js +27 -0
  89. package/dist/agents/sessions/group.js.map +1 -0
  90. package/dist/agents/sessions/hooks.d.ts +32 -0
  91. package/dist/agents/sessions/hooks.js +155 -0
  92. package/dist/agents/sessions/hooks.js.map +1 -0
  93. package/dist/agents/sessions/index.d.ts +42 -0
  94. package/dist/agents/sessions/index.js +97 -0
  95. package/dist/agents/sessions/index.js.map +1 -0
  96. package/dist/agents/sessions/live.d.ts +67 -0
  97. package/dist/agents/sessions/live.js +308 -0
  98. package/dist/agents/sessions/live.js.map +1 -0
  99. package/dist/agents/sessions/sqlite.d.ts +12 -0
  100. package/dist/agents/sessions/sqlite.js +61 -0
  101. package/dist/agents/sessions/sqlite.js.map +1 -0
  102. package/dist/agents/sessions/stores.d.ts +38 -0
  103. package/dist/agents/sessions/stores.js +616 -0
  104. package/dist/agents/sessions/stores.js.map +1 -0
  105. package/dist/agents/sessions/transcript.d.ts +20 -0
  106. package/dist/agents/sessions/transcript.js +134 -0
  107. package/dist/agents/sessions/transcript.js.map +1 -0
  108. package/dist/agents/sessions/types.d.ts +95 -0
  109. package/dist/agents/sessions/types.js +2 -0
  110. package/dist/agents/sessions/types.js.map +1 -0
  111. package/dist/agents/types.d.ts +31 -0
  112. package/dist/agents.d.ts +17 -1
  113. package/dist/agents.js +9 -1
  114. package/dist/agents.js.map +1 -1
  115. package/dist/backend/backend.d.ts +131 -0
  116. package/dist/backend/backend.js +773 -0
  117. package/dist/backend/backend.js.map +1 -0
  118. package/dist/backend/limiter.d.ts +34 -0
  119. package/dist/backend/limiter.js +76 -0
  120. package/dist/backend/limiter.js.map +1 -0
  121. package/dist/backend/node.d.ts +10 -0
  122. package/dist/backend/node.js +124 -0
  123. package/dist/backend/node.js.map +1 -0
  124. package/dist/backend/protocol.d.ts +98 -0
  125. package/dist/backend/protocol.js +2 -0
  126. package/dist/backend/protocol.js.map +1 -0
  127. package/dist/backend/seal.d.ts +7 -0
  128. package/dist/backend/seal.js +60 -0
  129. package/dist/backend/seal.js.map +1 -0
  130. package/dist/backend.d.ts +27 -0
  131. package/dist/backend.js +25 -0
  132. package/dist/backend.js.map +1 -0
  133. package/dist/browser/invoke.d.ts +17 -0
  134. package/dist/browser/invoke.js +69 -0
  135. package/dist/browser/invoke.js.map +1 -0
  136. package/dist/browser/nano.d.ts +10 -0
  137. package/dist/browser/nano.js +10 -56
  138. package/dist/browser/nano.js.map +1 -1
  139. package/dist/browser/page-agent.d.ts +7 -0
  140. package/dist/browser/page-agent.js +26 -5
  141. package/dist/browser/page-agent.js.map +1 -1
  142. package/dist/browser/remote.d.ts +44 -0
  143. package/dist/browser/remote.js +372 -0
  144. package/dist/browser/remote.js.map +1 -0
  145. package/dist/browser.d.ts +9 -2
  146. package/dist/browser.js +8 -2
  147. package/dist/browser.js.map +1 -1
  148. package/dist/cli/args.d.ts +26 -0
  149. package/dist/cli/args.js +66 -0
  150. package/dist/cli/args.js.map +1 -1
  151. package/dist/cli/hook.d.ts +7 -0
  152. package/dist/cli/hook.js +21 -0
  153. package/dist/cli/hook.js.map +1 -0
  154. package/dist/cli/main.d.ts +3 -1
  155. package/dist/cli/main.js +237 -2
  156. package/dist/cli/main.js.map +1 -1
  157. package/dist/cli.js +31 -21
  158. package/dist/cli.js.map +1 -1
  159. package/dist/core/types.d.ts +5 -0
  160. package/dist/core/types.js.map +1 -1
  161. package/dist/index.d.ts +1 -1
  162. package/dist/index.js +1 -1
  163. package/dist/index.js.map +1 -1
  164. package/dist/providers/google-converter.js +21 -8
  165. package/dist/providers/google-converter.js.map +1 -1
  166. package/dist/providers/google.js +7 -10
  167. package/dist/providers/google.js.map +1 -1
  168. package/dist/providers/openai-converter.js +3 -2
  169. package/dist/providers/openai-converter.js.map +1 -1
  170. package/dist/providers/openai-responses-converter.d.ts +35 -0
  171. package/dist/providers/openai-responses-converter.js +188 -0
  172. package/dist/providers/openai-responses-converter.js.map +1 -0
  173. package/dist/providers/openai.d.ts +6 -1
  174. package/dist/providers/openai.js +16 -1
  175. package/dist/providers/openai.js.map +1 -1
  176. package/dist/providers.d.ts +1 -0
  177. package/dist/providers.js +1 -0
  178. package/dist/providers.js.map +1 -1
  179. package/dist/react/page-agent-chat.js +6 -2
  180. package/dist/react/page-agent-chat.js.map +1 -1
  181. package/dist/ui/index.js +109 -82
  182. package/dist/ui/sessions.d.ts +19 -0
  183. package/dist/ui/sessions.js +59 -0
  184. package/dist/ui/sessions.js.map +1 -0
  185. package/dist/ui/web-client.js +15 -14
  186. package/docs/CHANGELOG.md +51 -388
  187. package/docs/agents.md +417 -2
  188. package/docs/backend.md +125 -0
  189. package/docs/browser.md +6 -1
  190. package/docs/changelog-2.26-and-older.md +441 -0
  191. package/docs/cli.md +39 -0
  192. package/docs/llm.md +6 -1
  193. package/docs/pivot.md +1 -1
  194. package/package.json +5 -1
package/docs/agents.md CHANGED
@@ -71,7 +71,7 @@ In scope:
71
71
  Out of scope, and left to application code:
72
72
 
73
73
  - sandboxing, credentials, and billing, which belong to the agent itself,
74
- - choosing an agent or model, retries, and verify-and-repair loops,
74
+ - choosing an agent or model (`pack()` leaves that to its lead agent), retries, and verify-and-repair loops,
75
75
  - prompts and repository tools. GenAIcode adds no agent loop of its own.
76
76
 
77
77
  ## Running a task
@@ -209,6 +209,214 @@ to brief it again (app agents do: the briefing plus the conversation so far). `c
209
209
  `/fallback` in the chat do it from the command line, and `<AgentChat>`, `chat` and `ui` show the
210
210
  switch in the transcript.
211
211
 
212
+ ## Packs: one agent over the others
213
+
214
+ `pack()` turns the agents on a machine into one `CodingAgent`. The lead takes the prompt and gets
215
+ MCP tools to hand parts of it to the other members, in parallel, and to merge what they did:
216
+
217
+ ```ts
218
+ import { claude, codex, gemini, pack } from 'genaicode/agents';
219
+
220
+ const agent = pack({ lead: claude(), members: [codex(), gemini(), claude()] });
221
+ const run = agent.run({ prompt: 'Add CSV export, with tests, and have it reviewed', cwd });
222
+ for await (const event of run) {
223
+ if (event.type === 'subtask-start') console.log(`→ ${event.agent} ${event.id}: ${event.prompt}`);
224
+ }
225
+ ```
226
+
227
+ The lead decides what to delegate and to whom; genaicode adds the tools, not a loop or a router of
228
+ its own. The lead needs `capabilities.mcp` and sees these tools on an MCP server named `pack`:
229
+
230
+ | Tool | What it does |
231
+ | ---------- | ----------------------------------------------------------------------------------------------- |
232
+ | `agents` | Members: installed or not, tasks running, the plan limits each reported, its last failure kind |
233
+ | `delegate` | Starts `prompt` on a member and returns a task id at once |
234
+ | `wait` | Blocks until tasks end (or `timeoutSeconds`), then reports status, final message, changed files |
235
+ | `steer` | More input for a running task, where the member has `steer()` |
236
+ | `stop` | Stops a running task |
237
+ | `diff` | A worktree task's changes as a unified diff |
238
+ | `merge` | Applies a finished task's changes to the lead's directory (`threeWay` for conflict markers) |
239
+ | `discard` | Drops a finished task's changes |
240
+
241
+ - A delegated task runs in its own git worktree under `.genaicode/worktrees/` (git-ignored): a
242
+ copy of the files as they are, uncommitted and untracked ones included. Nothing reaches the
243
+ working directory until the lead merges it, and a merge stages and commits nothing. Files git
244
+ ignores (`node_modules`, build output) are not in a worktree; `prepareWorktree(dir, repo)` can
245
+ link or install them. Mode `shared` runs a task in the lead's directory instead, for reviews and
246
+ for directories that are not git repositories.
247
+ - Events are the lead's, plus `subtask-start`, `subtask` (a delegated task's own event; its `done`
248
+ ends the task) and `subtask-update` (`merged` or `discarded`). A merge also emits `file-change`.
249
+ - `usage` events and `result.usage` add up the lead and every delegated task, and `task.budget`
250
+ caps the sum. `maxParallel` (default 4) caps how many tasks run at once.
251
+ - Delegated tasks get the run's `env`, `permissions` and `onApproval`; their request ids are
252
+ prefixed with the task id and the summary names the agent.
253
+ - `resume`, `steer()` and `result.sessionId` are the lead's. Tasks still running when the lead
254
+ finishes are stopped. Unmerged worktrees stay for the next turn; `agent.close()` removes them.
255
+
256
+ ## Sessions across agents
257
+
258
+ Every agent keeps its conversations somewhere of its own. `listSessions()` reads those stores and
259
+ returns one list, so an app can show what is going on in every project, whichever agent did it:
260
+
261
+ ```ts
262
+ import { claudeSessions, codexSessions, groupSessions, listSessions } from 'genaicode/agents';
263
+
264
+ const sources = [claudeSessions(), codexSessions()];
265
+ const { sessions, errors } = await listSessions(sources, { since: Date.now() - 7 * 86_400_000 });
266
+ for (const project of groupSessions(sessions)) {
267
+ console.log(project.name, project.agents); // app { claude: 12, codex: 3 }
268
+ for (const s of project.sessions) console.log(' ', s.agent, s.state, s.title ?? s.lastPrompt, s.id);
269
+ }
270
+ ```
271
+
272
+ A `SessionInfo` has the agent, its session `id` (what `AgentTask.resume` takes), the directory it
273
+ started in, branch, title, first and latest prompt, the end of the latest reply, model, usage or
274
+ cost where the store has them, and a `state`: `active` (written to in the last two minutes),
275
+ `waiting` (the agent had the last word) or `unfinished` (it stops at the user's message or in the
276
+ middle of the agent's work).
277
+
278
+ Every driver says where its sessions are in `agent.sessions`: a `SessionSource`, or `null` when
279
+ it keeps none genaicode reads. `agentSessionSources(agents)` collects them (one per store, so
280
+ `codex()` and `codexLive()` count once):
281
+
282
+ ```ts
283
+ const agents = [claude(), codex(), codexLive(), gemini()];
284
+ const { sessions } = await listSessions(agentSessionSources(agents), { limit: 50 });
285
+ ```
286
+
287
+ ### Which sessions need you: hooks
288
+
289
+ The stores say what was written, not what the agent is doing right now: a session that asks
290
+ "may I run this command?" looks the same as one that is thinking. Claude Code and Codex can say
291
+ it themselves through their hooks:
292
+
293
+ ```bash
294
+ npx genaicode hooks install # for the agents installed here; -a claude or -a codex for one
295
+ npx genaicode hooks # what is installed
296
+ npx genaicode hooks uninstall
297
+ ```
298
+
299
+ `install` adds one command hook to the agent's own user settings (`~/.claude/settings.json`,
300
+ `~/.codex/hooks.json`), beside whatever is declared there; Codex runs it once you trust it under
301
+ `/hooks`. The hook runs `genaicode hook <agent>` in the background when a session starts, takes a
302
+ prompt, asks for approval, gets its answer, finishes a turn and ends. It keeps one small file
303
+ per session in `~/.genaicode/live` with the state, the time, the directory and the name of the
304
+ tool asked for: nothing of what was said, and nothing leaves the machine.
305
+
306
+ `listSessions()` puts that over what the stores suggest: `state` is exact, and a `waiting`
307
+ session has `waitingFor`: `'approval'` (with `waitingTool`, such as `Bash`) or `'reply'`.
308
+ `genaicode sessions` marks the first with `◆`, and the browser's Sessions view has a filter for
309
+ them. A record the session's file has since moved past is ignored, so sessions driven without
310
+ the hook fall back to the stores. `{ live: false }` in the query leaves the reports out.
311
+
312
+ In code: `installHooks('claude')`, `hooksStatus()`, `uninstallHooks()`, and `recordHook(agent,
313
+ input)` with `readLive()` and `withLive(sessions, records)` to do the same for an agent of your
314
+ own whose hooks give the same JSON (`session_id`, `hook_event_name`, `cwd`).
315
+
316
+ The command in the settings is the `genaicode` that installed it (`node` and the path of its
317
+ `cli.js`): install it from a `genaicode` that stays where it is (a project's dependency or a
318
+ global install), and run `hooks install` again after moving it.
319
+
320
+ ### When an agent changes its store: `sessions doctor`
321
+
322
+ No agent promises how it keeps its sessions, so an update of its CLI can change the store, and a
323
+ reader that no longer understands it goes quiet instead of failing. `sessions doctor` shows it:
324
+
325
+ ```bash
326
+ npx genaicode sessions doctor # every store; exits 1 when one looks broken
327
+ npx genaicode sessions doctor -a codex --since 7d --json
328
+ ```
329
+
330
+ ```
331
+ claude 2.1.340 (checked with 2.1.327) ok
332
+ 412 sessions: 398 with a prompt or title, 412 with a directory, 412 with a state
333
+ read 5 of the 5 newest: agent messages in 5, tool calls in 4
334
+ hooks: installed, 3 sessions reported
335
+ ```
336
+
337
+ Per store it counts the sessions of the last 30 days and how many have a prompt, a directory and
338
+ a state, opens the five newest conversations, and compares the installed CLI with the version the
339
+ reader was last checked against (`SessionSource.verified`). A store where most sessions lost their
340
+ prompt or directory, or whose conversations no longer open, is a problem; a newer CLI alone is
341
+ not. It prints counts only, never what was said, so the output is safe to paste into an issue.
342
+ From code: `checkSessions(sources, { version })` returns the same as `SessionCheck[]`.
343
+
344
+ Codex can also be asked instead of read. Its app server (`codex app-server`) lists threads and
345
+ their turns in a documented protocol (`thread/list`, `thread/turns/list`), which holds across
346
+ Codex versions where the files may not:
347
+
348
+ ```bash
349
+ npx genaicode sessions doctor --api # compare what was read with what Codex lists
350
+ GENAICODE_CODEX_SESSIONS=app-server npx genaicode sessions # list and read through Codex itself
351
+ ```
352
+
353
+ ```ts
354
+ codexSessions({ via: 'app-server' }); // or 'auto': the app server when `codex` is installed
355
+ ```
356
+
357
+ The files stay the default: reading them changes nothing and starts nothing, while every question
358
+ to the app server starts a Codex process (about half a second) that keeps its own state and logs
359
+ in Codex's home. When the app server cannot be asked, the files are read. `doctor --api` is the
360
+ cheap middle: the files day to day, and Codex's own answer as the reference when you check.
361
+
362
+ The repository also checks every Monday, with no keys, whether the agents' latest releases still
363
+ match the readers (`.github/workflows/drift-canary.yaml`, `node scripts/drift-canary.mjs` after a
364
+ build): it lists each published CLI version beside `verified`, and fails when the latest Codex
365
+ app-server protocol (`codex app-server generate-ts`) no longer has a field that genaicode reads.
366
+
367
+ ### Continuing a session in another agent
368
+
369
+ Sources whose conversations can be read have `read(session)`: the turns of a session (prompts, the
370
+ agent's messages, tool calls with their output), as `createAgentSession` keeps them. Every local store genaicode
371
+ lists has it except Cursor's (Gemini CLI and newer Copilot CLI keep what was said, without tool calls). `session.adopt(turns)` takes them over: they join the transcript, and the
372
+ next prompt hands them to the current agent like `/agent` does, a recap in the prompt and the
373
+ whole transcript in `.genaicode/handoff/`.
374
+
375
+ ```ts
376
+ const sources = agentSessionSources([claude(), codex()]);
377
+ const found = await findSession(sources, 'a1b2c3d4'); // an id, or the start of one
378
+ if (found) {
379
+ const session = createAgentSession({ agent: codex(), cwd: found.session.cwd! });
380
+ session.adopt(await readSession(sources, found.session));
381
+ session.send('Finish what Claude started.');
382
+ }
383
+ ```
384
+
385
+ `adopt(turns, { sessionId })` is for the agent's own session: the next prompt resumes it, and the
386
+ turns are there to show. Only the end of a very long transcript is read (the last 8 MB, 100 turns).
387
+
388
+ | Driver | Source | Reads |
389
+ | -------------------- | ----------------------- | ------------------------------------------------------------------------------- |
390
+ | `claude` | `claudeSessions()` | `~/.claude/projects/*/*.jsonl` (`CLAUDE_CONFIG_DIR`), without subagents |
391
+ | `codex`, `codexLive` | `codexSessions()` | the thread index `~/.codex/state_<n>.sqlite` (`CODEX_HOME`), else rollout files |
392
+ | `copilot` | `copilotSessions()` | `~/.copilot/session-state/<id>/workspace.yaml` and `events.jsonl` |
393
+ | `cursor` | `cursorSessions()` | `~/.cursor/chats/<hash>/<id>/meta.json`, the model from the chat's `store.db` |
394
+ | `gemini` | `geminiSessions()` | `~/.gemini/tmp/<project>/chats/session-*.jsonl` |
395
+ | `antigravity` | `antigravitySessions()` | `conversation_summaries.db` in `~/.gemini/antigravity` and `antigravity-cli` |
396
+ | `muse`, `museLive` | `museSessions()` | `~/.local/share/muse/session-index.db` |
397
+ | `vibe` | `vibeSessions()` | `~/.vibe/logs/session/*/meta.json` (`VIBE_HOME`), with token and cost totals |
398
+ | `opencode` | `null` | not read yet |
399
+ | `anthropicManaged` | cloud | `GET /v1/sessions` of the driver's agent: title, status, model, usage, cost |
400
+ | `cursorCloud` | cloud | `GET /v1/agents`: the account's agents that are not archived, with their links |
401
+ | `geminiManaged` | `null` | the Interactions API lists nothing |
402
+ | `openaiManaged` | `null` | the Responses API lists nothing |
403
+
404
+ What a store does not keep stays undefined: Cursor has no usage, Antigravity and Vibe no model,
405
+ and an index without transcripts (Muse, Antigravity) gives no latest reply. Codex, Muse,
406
+ Antigravity and Cursor keep SQLite files, read with `node:sqlite` (Node 22.5 or newer; on an
407
+ older Node those sources land in `errors`). Subagent sessions and archived threads are left out.
408
+
409
+ A hosted driver lists what its platform lists, with `where: 'cloud'` and, where there is one, a
410
+ `url` to open the session: pass `anthropicManaged(...)` or `cursorCloud()` to
411
+ `agentSessionSources` next to the local agents. A cloud session has no local directory, so a
412
+ query with `cwd` leaves the clouds out.
413
+
414
+ Reading is read-only. Transcripts are read at their start and end only, so a store with hundreds
415
+ of long sessions lists quickly. `query` takes `since`, `cwd` and `limit`. A source that cannot be
416
+ read lands in `errors` and the others are still listed. A `SessionSource` is `{ name, where,
417
+ list(query) }`: implement one for another agent or for a vendor's cloud and pass it in the list.
418
+ `genaicode sessions` prints the same from the command line (see [cli.md](./cli.md)).
419
+
212
420
  ## Follow-up turns
213
421
 
214
422
  `result.sessionId` names the agent's own session. Pass it as `resume` to continue that
@@ -619,6 +827,212 @@ const run = hostedAgent(provider, { pollIntervalMs: 10_000 }).run({ prompt, cwd:
619
827
  `env`, `signal`, `timeoutMs` and `onApproval` stay local. Abort and timeout call `cancel`.
620
828
  `send` backs `steer()`.
621
829
 
830
+ ### Managed agent platforms
831
+
832
+ Platforms such as Anthropic Managed Agents, Gemini Managed Agents, OpenAI and Cursor Cloud
833
+ Agents keep sessions that outlive the process that started them, report usage, enforce their
834
+ own budgets and some ask for approvals. Implement `ManagedProvider` for those. Every method
835
+ takes a session id, so a server can start a session, store `snapshot.id`, and read it with
836
+ `get()` after a restart:
837
+
838
+ ```ts
839
+ import { managedAgent, type ManagedProvider } from 'genaicode/agents';
840
+
841
+ const provider: ManagedProvider = {
842
+ name: 'my-platform',
843
+ capabilities: { mcp: true, resume: true, usage: true, budget: ['usd'] },
844
+ start: (request, signal) => api.createSession(request, { signal }), // -> ManagedSnapshot
845
+ get: (id, signal) => api.getSession(id, { signal }), // { id, state, stopReason?, usage?, costUsd?, ... }
846
+ watch: (id, signal) => api.streamSession(id, { signal }), // optional: AsyncIterable<{ events?, snapshot? }>
847
+ send: (id, text) => api.message(id, text),
848
+ answer: (id, approvalId, decision) => api.confirm(id, approvalId, decision),
849
+ interrupt: (id) => api.interrupt(id),
850
+ release: (snapshot) => api.archiveVaults(snapshot.release), // per-session credentials, uploads
851
+ };
852
+
853
+ const run = managedAgent(provider).run({ prompt, cwd: 'env_123', budget: { maxCostUsd: 2 } });
854
+ ```
855
+
856
+ `managedAgent()` turns it into a `CodingAgent`: it follows `watch()` when the provider has one
857
+ and polls `get()` (and `events()`) otherwise. A turn ends when the session is `idle` with any
858
+ stop reason other than `requires-action`, or when it ends. `approval-request` events are
859
+ answered through `task.onApproval` and `answer()`, under `task.permissions.approval`.
860
+ `task.budget` goes to the platform as well as to the usual budget check, and a session the
861
+ platform stopped at its cap (`stopReason: 'budget'`) fails with `failure.kind: 'budget'`.
862
+ `timeoutMs` becomes `maxDurationSeconds`. Only remote MCP servers are accepted, and their
863
+ `headers` must never appear in snapshots or events. `release()` runs after every run; the
864
+ session itself stays for `task.resume` unless `managedAgent(provider, { deleteSession: true })`.
865
+ A resumed run reports its own share: usage and cost are the change since it began, and the
866
+ budget sent to the platform adds what the session had already spent. Provider exceptions are
867
+ classified for `withFallback()`: an explicit `error.failure`, HTTP 401/403 (`auth`), 429
868
+ (`quota`), 5xx or a network error (`unavailable`). Paged `events()` set `hasMore` to be read
869
+ before the next interval, and `watch()` gets the last update's `cursor` when it reconnects.
870
+ The snapshot `start()` returns may carry a `cursor` just before the new turn's first event;
871
+ reading starts there, so a resumed session's history (and its approvals) is not replayed.
872
+
873
+ `hostedAgent()` is `managedAgent(fromHosted(provider))`.
874
+
875
+ #### Claude Managed Agents
876
+
877
+ `anthropicManaged()` runs tasks as sessions of an agent you created once on
878
+ [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview), in one of
879
+ your environments. It calls `@anthropic-ai/sdk`'s `beta.sessions`; pass a client from a version
880
+ that has them (genaicode's own SDK dependency may be older):
881
+
882
+ ```ts
883
+ import Anthropic from '@anthropic-ai/sdk';
884
+ import { anthropicManaged } from 'genaicode/agents';
885
+
886
+ const agent = anthropicManaged({
887
+ client: new Anthropic(),
888
+ agent: 'agent_011...', // or { id, version } to pin one
889
+ environment: 'env_011...',
890
+ githubToken: () => process.env.GITHUB_TOKEN!, // for https://github.com/... workspaces
891
+ tools: { run_tests: async ({ path }) => runTests(String(path)) }, // the agent's custom tools
892
+ });
893
+
894
+ const run = agent.run({
895
+ prompt: 'Fix the failing test',
896
+ cwd: 'https://github.com/acme/game#main', // cloned into the session; other cwd values are ignored
897
+ budget: { maxCostUsd: 5 }, // the session's own list-cost cap
898
+ mcpServers: [{ name: 'game', url: 'https://example.com/mcp', headers: { Authorization: `Bearer ${token}` } }],
899
+ });
900
+ ```
901
+
902
+ - The prompt starts the session; `steer()` adds a `user.message`, `abort()` sends `user.interrupt`.
903
+ `task.resume` (a session id) sends the next message to the same session.
904
+ - Tool calls the agent's permission policy pauses (`always_ask`, or `auto` without a verdict) come
905
+ back as `approval-request` and are answered with `user.tool_confirmation`.
906
+ - `model`, `effort` and `system` (added to the agent's prompt) override the agent for that
907
+ session only. MCP servers the agent does not have are added for the session; a bearer token
908
+ goes into a vault made for the session, which `release()` deletes after the run, so a resumed
909
+ session cannot take new MCP credentials. Only `Authorization: Bearer` headers can be vaulted.
910
+ - `ManagedStart.files` are uploaded and mounted under `filesRoot` (default `/workspace`).
911
+ - Usage and list cost come from the session; an `idle` at `budget_reached` fails with
912
+ `failure.kind: 'budget'`, rate-limit and billing errors with `quota`, overload with `unavailable`.
913
+ - `maxTurns` and `extraArgs` are refused; `permissions.sandbox` is the environment's business.
914
+
915
+ #### Gemini Managed Agents
916
+
917
+ `geminiManaged()` runs tasks on
918
+ [Gemini Managed Agents](https://ai.google.dev/gemini-api/docs/agents) (the Antigravity agent) through
919
+ the Interactions API, with plain `fetch`. It reads `GEMINI_API_KEY` by default; `agentPlatform`
920
+ switches to Gemini Enterprise Agent Platform on Google Cloud with an OAuth access token:
921
+
922
+ ```ts
923
+ import { geminiManaged } from 'genaicode/agents';
924
+
925
+ const agent = geminiManaged({
926
+ // agent: 'agents/my-agent', // a saved agent; default antigravity-preview-09-2026
927
+ // agentPlatform: { project: 'my-project', accessToken: () => getAccessToken() },
928
+ network: ['pypi.org', 'registry.npmjs.org'], // a fresh sandbox's allowlist (MCP hosts are added)
929
+ });
930
+
931
+ const run = agent.run({
932
+ prompt: 'Fix the failing test',
933
+ cwd: 'https://github.com/acme/game', // cloned into /workspace/game; env_... reuses an environment
934
+ model: 'gemini-4-carbon',
935
+ budget: { maxTokens: 200_000 }, // the interaction's own max_total_tokens
936
+ mcpServers: [{ name: 'game', url: 'https://example.com/mcp', headers: { Authorization: `Bearer ${token}` } }],
937
+ });
938
+ ```
939
+
940
+ - Each turn is a background interaction; `abort()` cancels it. `task.resume` (the last run's
941
+ `sessionId`) chains a new interaction to it in the same environment, so the next run's
942
+ `sessionId` is a new id. Usage adds up the whole chain, and a resumed run reports its own share.
943
+ - Steps stream live (text, MCP, code execution and search calls with their results) and the
944
+ stream picks up from the last event after a drop.
945
+ - MCP servers replace the agent's default tools for that turn, so `tools` (default code execution,
946
+ Google Search, URL context) is sent beside them. Server names must match `^[a-z0-9_-]+$`.
947
+ - `ManagedStart.files` (text only) and the repository go into a fresh sandbox under `filesRoot`
948
+ (default `/workspace`); they cannot be added to an existing environment or on resume.
949
+ - `incomplete` (the token cap) fails with `failure.kind: 'budget'`; a failed interaction's error
950
+ code maps `RESOURCE_EXHAUSTED` to `quota`. The agent asks no approvals (`permissions.approval`
951
+ is `auto-approve` only); `effort`, `maxTurns` and `extraArgs` are refused, and so is `model` for
952
+ a saved agent, whose `agent_config` is fixed: its runs have no platform token cap
953
+ (`capabilities.budget` is empty), so `task.budget` is checked against reported usage only.
954
+
955
+ #### OpenAI background responses
956
+
957
+ `openaiManaged()` runs tasks as background responses of the
958
+ [Responses API](https://developers.openai.com/api/docs/guides/background), with OpenAI's hosted
959
+ tools doing the work: by default a hosted shell and web search. It
960
+ reads `OPENAI_API_KEY` by default:
961
+
962
+ ```ts
963
+ import { openaiManaged } from 'genaicode/agents';
964
+
965
+ const agent = openaiManaged({
966
+ model: 'gpt-6.2-astra',
967
+ network: ['pypi.org', 'github.com'], // the session container's allowlist (none by default)
968
+ // tools: [{ type: 'code_interpreter', container: { type: 'auto' } }], // instead of the defaults
969
+ });
970
+
971
+ const run = agent.run({
972
+ prompt: 'Clone the repo, run its tests and summarize the failures',
973
+ cwd: '.', // or cntr_... to reuse a container you created
974
+ effort: 'high', // reasoning.effort
975
+ maxTurns: 40, // max_tool_calls
976
+ mcpServers: [{ name: 'game', url: 'https://example.com/mcp', headers: { Authorization: `Bearer ${token}` } }],
977
+ });
978
+ ```
979
+
980
+ - The response is polled (`pollIntervalMs`, default 3 s): each output item arrives as a whole
981
+ event once it is finished (messages, MCP, shell, code interpreter and web search calls), so
982
+ there are no `text-delta` events. `abort()` cancels the response.
983
+ - `task.resume` (the last run's `sessionId`) chains a new response with `previous_response_id`,
984
+ so the next run's `sessionId` is a new id. Usage adds up the whole chain, and a resumed run
985
+ reports its own share.
986
+ - The default shell runs in a container made for the session (or the `cntr_...` workspace), and
987
+ a resumed run goes on in the same one, files included. It expires `containerMinutes` (default 20) after its last use; resuming after that fails rather than starting from an empty disk.
988
+ - MCP servers run without approvals (`require_approval: 'never'`; `permissions.approval` is
989
+ `auto-approve` only). Their only header can be `Authorization: Bearer`, which the platform takes
990
+ as `authorization`: it drops other headers on tool calls.
991
+ - The platform has no session-wide cap, so `task.budget` is checked against reported usage.
992
+ A response cut at `max_output_tokens` fails with `failure.kind: 'budget'`, one cut by a content
993
+ filter fails with its reason, and a failed response's error code maps rate limits to `quota`.
994
+ - `files` and `extraArgs` are refused; a model is required (`model` option or `task.model`).
995
+
996
+ #### Cursor Cloud Agents
997
+
998
+ `cursorCloud()` runs tasks as [Cursor Cloud Agents](https://cursor.com/docs/cloud-agent/api/endpoints)
999
+ in Cursor's VMs, working on a repository and pushing a branch (or opening a pull request). It
1000
+ reads `CURSOR_API_KEY` by default:
1001
+
1002
+ ```ts
1003
+ import { cursorCloud } from 'genaicode/agents';
1004
+
1005
+ const agent = cursorCloud({
1006
+ model: 'composer-2', // an id from GET /v1/models; default: the account's default model
1007
+ autoCreatePR: true,
1008
+ // env: { type: 'pool', name: 'sandbox' }, // your own workers instead of Cursor's VMs
1009
+ });
1010
+
1011
+ const run = agent.run({
1012
+ prompt: 'Add a health check endpoint with a test',
1013
+ cwd: 'https://github.com/acme/api#main', // a repo (#branch or #sha to start from) or a PR URL
1014
+ mcpServers: [{ name: 'docs', url: 'https://example.com/mcp', headers: { Authorization: `Bearer ${token}` } }],
1015
+ });
1016
+ ```
1017
+
1018
+ - A session is the agent (`bc-...`), and its `sessionId` stays the same across turns: every turn
1019
+ is a run on it. `task.resume` sends a follow-up run, which keeps the agent's model and
1020
+ repository (a different `model` or repository URL is refused). Usage is the agent's total, and
1021
+ a resumed run reports its own share.
1022
+ - The run's events stream live (`text-delta`, messages, tool calls) and the stream resumes from
1023
+ the last event after a drop. Past the stream's retention the final state is read instead.
1024
+ - `steer()` reaches the running turn (`delivery: 'steer'`), `abort()` cancels the run. A steer
1025
+ the platform queues as the next follow-up keeps the turn going into the run it starts.
1026
+ - On resume, `mcpServers` replaces the agent's servers (an empty list drops them); left out, the
1027
+ agent keeps its current ones.
1028
+ - MCP servers go along with their headers. Tools run without approvals (`permissions.approval`
1029
+ is `auto-approve` only), and there is no platform budget: `task.budget` is checked against
1030
+ usage, which is read every `pollIntervalMs` while the stream runs, and a run over it is
1031
+ cancelled.
1032
+ - A local `cwd` is ignored (the agent works in its own VM). `effort`, `maxTurns`, `files` and
1033
+ `extraArgs` are refused; a system prompt goes before the task text. `vendor` fields go into
1034
+ the create (or follow-up) request as they are.
1035
+
622
1036
  ## Writing a driver
623
1037
 
624
1038
  ```ts
@@ -654,5 +1068,6 @@ way the built-in drivers are tested.
654
1068
  1. Headless drivers for claude, codex, and muse, the event IR, and discovery. Done.
655
1069
  2. Live sessions (`codex app-server`, `muse serve`): `steer()` mid-task, approval replies. Done.
656
1070
  3. MCP server injection per driver, an env scrub helper, and an opt-in verify/repair helper. Done.
657
- 4. More CLIs (gemini, cursor, opencode) and a hosted coding-agent seam (`hostedAgent`). Done.
1071
+ 4. More CLIs (gemini, cursor, opencode) and a hosted coding-agent seam (`hostedAgent`, `managedAgent`). Done.
658
1072
  5. A Copilot CLI driver (`copilot`). Done.
1073
+ 6. `pack()`: a lead agent that delegates to the other installed agents. Done; CLI and chat front ends next.
@@ -0,0 +1,125 @@
1
+ # A model behind your server for the page (`genaicode/backend`)
2
+
3
+ [← README](../README.md) · [genaicode/browser](browser.md)
4
+
5
+ `genaicode/backend` puts a model behind your server for the assistant in your web page. The
6
+ model and its key stay on the server; the page's tools still run in the page, and the user still
7
+ approves every `write` call there; server tools run on the server for the signed-in user. In
8
+ the page, `remote()` from [`genaicode/browser`](browser.md) is the driver, so `createPageAgent`,
9
+ `<PageAgentChat>`, approvals and WebMCP work as they do with Gemini Nano.
10
+
11
+ Use it where the built-in model is missing (most phones, Safari, Firefox, weaker hardware),
12
+ too small for the job, or where the assistant needs your data and your actions.
13
+
14
+ It runs one model with tools, for many visitors at once, and keeps nothing running between
15
+ requests. To let a coding agent (Claude Code, Codex) work on your app from a page, use
16
+ [`genaicode/app-agent`](app-agent.md) instead: that one runs a live agent process for you.
17
+
18
+ ```ts
19
+ // server
20
+ import { genaicode } from 'genaicode';
21
+ import { anthropic } from 'genaicode/providers';
22
+ import { createAgentBackend, toNodeListener } from 'genaicode/backend';
23
+
24
+ const backend = createAgentBackend({
25
+ client: genaicode(anthropic({ model: 'claude-haiku-4-5' })),
26
+ instructions: 'You help shoppers on Example Shop. Prices are in euro.',
27
+ secret: process.env.ASSISTANT_SECRET!, // 32+ characters, encrypts the conversation token
28
+ authorize: (request) => userFromCookie(request), // { id } or null (401)
29
+ pageTools: [
30
+ { name: 'list_products', description: 'The products in the shop.' },
31
+ {
32
+ name: 'add_to_cart',
33
+ description: 'Put a product in the cart.',
34
+ inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
35
+ write: true,
36
+ },
37
+ ],
38
+ tools: [
39
+ {
40
+ name: 'order_status',
41
+ description: "The status of the user's last order.",
42
+ run: (_args, { user }) => orders.lastOf(user!.id), // the user from authorize, never from the model
43
+ },
44
+ ],
45
+ });
46
+
47
+ app.use(toNodeListener(backend)); // Express, Connect, node:http
48
+ // Workers, Deno, Bun, Vercel: export default { fetch: (request) => backend.handle(request) };
49
+ ```
50
+
51
+ ```ts
52
+ // page
53
+ import { createPageAgent, nano, remote, withFallback } from 'genaicode/browser';
54
+
55
+ const assistant = createPageAgent({
56
+ name: 'helper',
57
+ tools, // PageTool[]: the same list as for nano()
58
+ agent: withFallback([remote({ url: '/api/assistant', tools }), nano({ tools })]),
59
+ });
60
+ ```
61
+
62
+ `withFallback` goes on with the built-in model when the backend is out: signed out (`auth`),
63
+ over its allowance (`quota`), unreachable or failing (`unavailable`). Put `nano()` first to use
64
+ the free, private model where the browser has it and the server everywhere else. A prompt that
65
+ already ran a `write` tool is not handed on: the run fails, so the action does not happen twice.
66
+ The chat asks the fallback's `info()`: it is open when any agent is, takes what the agent that
67
+ runs first takes (images only where that model does), and says when it is back when none is.
68
+
69
+ ## How a turn runs
70
+
71
+ `POST <base>/turn` streams NDJSON: text as it comes, server tool steps, and a last `turn-end`
72
+ line. When the model calls a page tool, or a server tool that needs approval, the stream ends
73
+ with `status: 'waiting'` and the calls; the page runs them (asking the user before a `write`
74
+ one) and posts the results with the `state` it got. Nothing waits on the server between
75
+ requests, so it runs on serverless hosts.
76
+
77
+ | Route | What it does |
78
+ | ------------------ | ------------------------------------------------------------------------------------ |
79
+ | `POST <base>/turn` | `{ state?, prompt, images?, tools? }`, or `{ state, results?, approvals? }` to go on |
80
+ | `GET <base>/info` | `{ name, model, inputs, available, resetsAt? }`: `remote().info()` |
81
+
82
+ `basePath` is `/api/assistant` by default.
83
+
84
+ ## Security
85
+
86
+ The page belongs to the user, so the server trusts nothing it sends: not the conversation, not
87
+ tool results, not approvals.
88
+
89
+ - **Costs.** Anyone who can reach the URL can ask the model anything, so costs are held by
90
+ limits that are on by default: `limits.maxOutputTokens` (1,024), `maxSteps` model calls per
91
+ prompt (8), `conversationTokens` (100,000), body, prompt and image sizes, and a `limiter`
92
+ with daily allowances per user and in all (`memoryLimiter()`: 200,000 and 2,000,000 tokens;
93
+ back it with your store when you run more than one instance). Each model call first reserves
94
+ its input and a full answer, so calls running at once cannot spend the same rest of an
95
+ allowance; a custom `limiter` must `reserve` in one step (a transaction). A provider that reports no
96
+ usage is counted at about four characters a token, also when its stream breaks after it
97
+ answered something. `createAgentBackend` refuses to start
98
+ without `authorize`, unless you set `public: true`.
99
+ - **The conversation** travels in a token encrypted and authenticated with `secret`
100
+ (AES-256-GCM), with the user's id and an expiry (`stateTtlMs`, 24 hours) inside; a changed,
101
+ expired or someone else's token gets 409 and the page starts over. With `store` the token
102
+ only names a conversation kept on the server. Images stay in the token only while their turn
103
+ waits on the page.
104
+ - **Page tools** run in the page, so they cannot touch the server. Listing them in `pageTools`
105
+ keeps the model's tool list in your hands; `'from-client'` lets the page choose it with each
106
+ request (checked: at most 32, names, sizes, no clash with server tools).
107
+ - **Server tools** act for `context.user`. Check what that user may do there, never from the
108
+ arguments: the model wrote them, and the model reads text other people wrote. A `write`
109
+ server tool waits for the user's approval in the page. A tool that throws shows the model
110
+ and the page `The tool failed.` (the error goes to `onError`); throw a `ToolError` for words
111
+ they should see. A step that fails after a tool ran keeps
112
+ its result, so a retry does not run it again, and with `store` one instance takes one request
113
+ per conversation at a time. An old token can still be posted again, and instances sharing a
114
+ store do not see each other's requests, so make `write` tools safe to repeat (an order id, a
115
+ check of what is done).
116
+ - **Prompt injection.** Tool results are marked as data in the system prompt, `write` tools on
117
+ both sides need a click, and the model's provider error text never reaches the page.
118
+ - **Cross-site requests** are refused (`Sec-Fetch-Site`, `Origin`) unless their origin is in
119
+ `allowedOrigins` (CORS, no cookies). Posts must be `application/json`.
120
+ - **Privacy.** Unlike Gemini Nano, what the user types leaves the device. Nothing here logs
121
+ conversation text; `onTurn` gets counts only.
122
+
123
+ ## Stability
124
+
125
+ Experimental: names here may change in a minor release.
package/docs/browser.md CHANGED
@@ -10,7 +10,9 @@ Nothing in it imports Node.
10
10
 
11
11
  It is a small model. It is good at "show me X", "what does this page say about Y", "switch
12
12
  that on": one or two tool calls and a short answer. It does not write code; for that, put a
13
- coding agent behind your app with [`genaicode/app-agent`](app-agent.md).
13
+ coding agent behind your app with [`genaicode/app-agent`](app-agent.md). For a bigger model,
14
+ or for browsers without one, the same page agent runs on a model behind your server:
15
+ `remote()` and [`genaicode/backend`](backend.md).
14
16
 
15
17
  ```ts
16
18
  import { createPageAgent, exposeWebMcp, type PageTool } from 'genaicode/browser';
@@ -179,6 +181,9 @@ empty list where the browser cannot list tools.
179
181
  | WebMCP | A draft: Chrome origin trial (149 to 156), Edge behind a flag. Register a trial token. |
180
182
  | Everything else | `availability()` is `unavailable`: show the page without the assistant, or use a fallback. |
181
183
 
184
+ The fallback can be a model behind your server: `withFallback([nano({ tools }), remote({ url, tools })])`
185
+ ([backend.md](backend.md)).
186
+
182
187
  Check `availability()` (or `<PageAgentChat>`'s `unavailable` slot) and treat the assistant as
183
188
  an extra. A common setup loads it only where `'LanguageModel' in self`.
184
189