genaicode 2.32.0 → 2.34.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 (109) hide show
  1. package/README.md +2 -0
  2. package/dist/agents/drivers/anthropic-managed.d.ts +141 -0
  3. package/dist/agents/drivers/anthropic-managed.js +753 -0
  4. package/dist/agents/drivers/anthropic-managed.js.map +1 -0
  5. package/dist/agents/drivers/cursor-cloud.d.ts +78 -0
  6. package/dist/agents/drivers/cursor-cloud.js +478 -0
  7. package/dist/agents/drivers/cursor-cloud.js.map +1 -0
  8. package/dist/agents/drivers/gemini-managed.d.ts +78 -0
  9. package/dist/agents/drivers/gemini-managed.js +526 -0
  10. package/dist/agents/drivers/gemini-managed.js.map +1 -0
  11. package/dist/agents/drivers/managed-http.d.ts +28 -0
  12. package/dist/agents/drivers/managed-http.js +142 -0
  13. package/dist/agents/drivers/managed-http.js.map +1 -0
  14. package/dist/agents/drivers/openai-managed.d.ts +79 -0
  15. package/dist/agents/drivers/openai-managed.js +402 -0
  16. package/dist/agents/drivers/openai-managed.js.map +1 -0
  17. package/dist/agents/failover.d.ts +19 -1
  18. package/dist/agents/failover.js +63 -2
  19. package/dist/agents/failover.js.map +1 -1
  20. package/dist/agents/hosted.d.ts +5 -1
  21. package/dist/agents/hosted.js +45 -132
  22. package/dist/agents/hosted.js.map +1 -1
  23. package/dist/agents/managed.d.ts +154 -0
  24. package/dist/agents/managed.js +561 -0
  25. package/dist/agents/managed.js.map +1 -0
  26. package/dist/agents/runtime.d.ts +5 -1
  27. package/dist/agents/runtime.js +9 -0
  28. package/dist/agents/runtime.js.map +1 -1
  29. package/dist/agents/session.d.ts +11 -0
  30. package/dist/agents/session.js.map +1 -1
  31. package/dist/agents.d.ts +11 -1
  32. package/dist/agents.js +6 -1
  33. package/dist/agents.js.map +1 -1
  34. package/dist/backend/backend.d.ts +131 -0
  35. package/dist/backend/backend.js +773 -0
  36. package/dist/backend/backend.js.map +1 -0
  37. package/dist/backend/limiter.d.ts +34 -0
  38. package/dist/backend/limiter.js +76 -0
  39. package/dist/backend/limiter.js.map +1 -0
  40. package/dist/backend/node.d.ts +10 -0
  41. package/dist/backend/node.js +124 -0
  42. package/dist/backend/node.js.map +1 -0
  43. package/dist/backend/protocol.d.ts +98 -0
  44. package/dist/backend/protocol.js +2 -0
  45. package/dist/backend/protocol.js.map +1 -0
  46. package/dist/backend/seal.d.ts +7 -0
  47. package/dist/backend/seal.js +60 -0
  48. package/dist/backend/seal.js.map +1 -0
  49. package/dist/backend.d.ts +27 -0
  50. package/dist/backend.js +25 -0
  51. package/dist/backend.js.map +1 -0
  52. package/dist/browser/fake-model.d.ts +43 -0
  53. package/dist/browser/fake-model.js +133 -0
  54. package/dist/browser/fake-model.js.map +1 -0
  55. package/dist/browser/invoke.d.ts +17 -0
  56. package/dist/browser/invoke.js +69 -0
  57. package/dist/browser/invoke.js.map +1 -0
  58. package/dist/browser/language-model.d.ts +74 -0
  59. package/dist/browser/language-model.js +83 -0
  60. package/dist/browser/language-model.js.map +1 -0
  61. package/dist/browser/nano.d.ts +93 -0
  62. package/dist/browser/nano.js +564 -0
  63. package/dist/browser/nano.js.map +1 -0
  64. package/dist/browser/page-agent.d.ts +81 -0
  65. package/dist/browser/page-agent.js +360 -0
  66. package/dist/browser/page-agent.js.map +1 -0
  67. package/dist/browser/remote.d.ts +44 -0
  68. package/dist/browser/remote.js +372 -0
  69. package/dist/browser/remote.js.map +1 -0
  70. package/dist/browser/tools.d.ts +36 -0
  71. package/dist/browser/tools.js +190 -0
  72. package/dist/browser/tools.js.map +1 -0
  73. package/dist/browser/webmcp.d.ts +32 -0
  74. package/dist/browser/webmcp.js +150 -0
  75. package/dist/browser/webmcp.js.map +1 -0
  76. package/dist/browser.d.ts +46 -0
  77. package/dist/browser.js +38 -0
  78. package/dist/browser.js.map +1 -0
  79. package/dist/core/types.d.ts +5 -0
  80. package/dist/core/types.js.map +1 -1
  81. package/dist/index.d.ts +1 -1
  82. package/dist/index.js +1 -1
  83. package/dist/index.js.map +1 -1
  84. package/dist/providers/google-converter.js +3 -0
  85. package/dist/providers/google-converter.js.map +1 -1
  86. package/dist/providers/google.js +7 -10
  87. package/dist/providers/google.js.map +1 -1
  88. package/dist/react/agent-chat.css +141 -0
  89. package/dist/react/agent-chat.d.ts +12 -2
  90. package/dist/react/agent-chat.js +32 -4
  91. package/dist/react/agent-chat.js.map +1 -1
  92. package/dist/react/attachments.d.ts +41 -0
  93. package/dist/react/attachments.js +162 -0
  94. package/dist/react/attachments.js.map +1 -0
  95. package/dist/react/page-agent-chat.d.ts +38 -0
  96. package/dist/react/page-agent-chat.js +44 -0
  97. package/dist/react/page-agent-chat.js.map +1 -0
  98. package/dist/react.d.ts +6 -1
  99. package/dist/react.js +2 -0
  100. package/dist/react.js.map +1 -1
  101. package/dist/ui/web-client.js +154 -13
  102. package/docs/CHANGELOG.md +38 -395
  103. package/docs/agents.md +207 -1
  104. package/docs/backend.md +125 -0
  105. package/docs/browser.md +205 -0
  106. package/docs/changelog-2.26-and-older.md +441 -0
  107. package/docs/pivot.md +1 -1
  108. package/docs/semver.md +2 -0
  109. package/package.json +9 -1
package/docs/agents.md CHANGED
@@ -619,6 +619,212 @@ const run = hostedAgent(provider, { pollIntervalMs: 10_000 }).run({ prompt, cwd:
619
619
  `env`, `signal`, `timeoutMs` and `onApproval` stay local. Abort and timeout call `cancel`.
620
620
  `send` backs `steer()`.
621
621
 
622
+ ### Managed agent platforms
623
+
624
+ Platforms such as Anthropic Managed Agents, Gemini Managed Agents, OpenAI and Cursor Cloud
625
+ Agents keep sessions that outlive the process that started them, report usage, enforce their
626
+ own budgets and some ask for approvals. Implement `ManagedProvider` for those. Every method
627
+ takes a session id, so a server can start a session, store `snapshot.id`, and read it with
628
+ `get()` after a restart:
629
+
630
+ ```ts
631
+ import { managedAgent, type ManagedProvider } from 'genaicode/agents';
632
+
633
+ const provider: ManagedProvider = {
634
+ name: 'my-platform',
635
+ capabilities: { mcp: true, resume: true, usage: true, budget: ['usd'] },
636
+ start: (request, signal) => api.createSession(request, { signal }), // -> ManagedSnapshot
637
+ get: (id, signal) => api.getSession(id, { signal }), // { id, state, stopReason?, usage?, costUsd?, ... }
638
+ watch: (id, signal) => api.streamSession(id, { signal }), // optional: AsyncIterable<{ events?, snapshot? }>
639
+ send: (id, text) => api.message(id, text),
640
+ answer: (id, approvalId, decision) => api.confirm(id, approvalId, decision),
641
+ interrupt: (id) => api.interrupt(id),
642
+ release: (snapshot) => api.archiveVaults(snapshot.release), // per-session credentials, uploads
643
+ };
644
+
645
+ const run = managedAgent(provider).run({ prompt, cwd: 'env_123', budget: { maxCostUsd: 2 } });
646
+ ```
647
+
648
+ `managedAgent()` turns it into a `CodingAgent`: it follows `watch()` when the provider has one
649
+ and polls `get()` (and `events()`) otherwise. A turn ends when the session is `idle` with any
650
+ stop reason other than `requires-action`, or when it ends. `approval-request` events are
651
+ answered through `task.onApproval` and `answer()`, under `task.permissions.approval`.
652
+ `task.budget` goes to the platform as well as to the usual budget check, and a session the
653
+ platform stopped at its cap (`stopReason: 'budget'`) fails with `failure.kind: 'budget'`.
654
+ `timeoutMs` becomes `maxDurationSeconds`. Only remote MCP servers are accepted, and their
655
+ `headers` must never appear in snapshots or events. `release()` runs after every run; the
656
+ session itself stays for `task.resume` unless `managedAgent(provider, { deleteSession: true })`.
657
+ A resumed run reports its own share: usage and cost are the change since it began, and the
658
+ budget sent to the platform adds what the session had already spent. Provider exceptions are
659
+ classified for `withFallback()`: an explicit `error.failure`, HTTP 401/403 (`auth`), 429
660
+ (`quota`), 5xx or a network error (`unavailable`). Paged `events()` set `hasMore` to be read
661
+ before the next interval, and `watch()` gets the last update's `cursor` when it reconnects.
662
+ The snapshot `start()` returns may carry a `cursor` just before the new turn's first event;
663
+ reading starts there, so a resumed session's history (and its approvals) is not replayed.
664
+
665
+ `hostedAgent()` is `managedAgent(fromHosted(provider))`.
666
+
667
+ #### Claude Managed Agents
668
+
669
+ `anthropicManaged()` runs tasks as sessions of an agent you created once on
670
+ [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview), in one of
671
+ your environments. It calls `@anthropic-ai/sdk`'s `beta.sessions`; pass a client from a version
672
+ that has them (genaicode's own SDK dependency may be older):
673
+
674
+ ```ts
675
+ import Anthropic from '@anthropic-ai/sdk';
676
+ import { anthropicManaged } from 'genaicode/agents';
677
+
678
+ const agent = anthropicManaged({
679
+ client: new Anthropic(),
680
+ agent: 'agent_011...', // or { id, version } to pin one
681
+ environment: 'env_011...',
682
+ githubToken: () => process.env.GITHUB_TOKEN!, // for https://github.com/... workspaces
683
+ tools: { run_tests: async ({ path }) => runTests(String(path)) }, // the agent's custom tools
684
+ });
685
+
686
+ const run = agent.run({
687
+ prompt: 'Fix the failing test',
688
+ cwd: 'https://github.com/acme/game#main', // cloned into the session; other cwd values are ignored
689
+ budget: { maxCostUsd: 5 }, // the session's own list-cost cap
690
+ mcpServers: [{ name: 'game', url: 'https://example.com/mcp', headers: { Authorization: `Bearer ${token}` } }],
691
+ });
692
+ ```
693
+
694
+ - The prompt starts the session; `steer()` adds a `user.message`, `abort()` sends `user.interrupt`.
695
+ `task.resume` (a session id) sends the next message to the same session.
696
+ - Tool calls the agent's permission policy pauses (`always_ask`, or `auto` without a verdict) come
697
+ back as `approval-request` and are answered with `user.tool_confirmation`.
698
+ - `model`, `effort` and `system` (added to the agent's prompt) override the agent for that
699
+ session only. MCP servers the agent does not have are added for the session; a bearer token
700
+ goes into a vault made for the session, which `release()` deletes after the run, so a resumed
701
+ session cannot take new MCP credentials. Only `Authorization: Bearer` headers can be vaulted.
702
+ - `ManagedStart.files` are uploaded and mounted under `filesRoot` (default `/workspace`).
703
+ - Usage and list cost come from the session; an `idle` at `budget_reached` fails with
704
+ `failure.kind: 'budget'`, rate-limit and billing errors with `quota`, overload with `unavailable`.
705
+ - `maxTurns` and `extraArgs` are refused; `permissions.sandbox` is the environment's business.
706
+
707
+ #### Gemini Managed Agents
708
+
709
+ `geminiManaged()` runs tasks on
710
+ [Gemini Managed Agents](https://ai.google.dev/gemini-api/docs/agents) (the Antigravity agent) through
711
+ the Interactions API, with plain `fetch`. It reads `GEMINI_API_KEY` by default; `agentPlatform`
712
+ switches to Gemini Enterprise Agent Platform on Google Cloud with an OAuth access token:
713
+
714
+ ```ts
715
+ import { geminiManaged } from 'genaicode/agents';
716
+
717
+ const agent = geminiManaged({
718
+ // agent: 'agents/my-agent', // a saved agent; default antigravity-preview-09-2026
719
+ // agentPlatform: { project: 'my-project', accessToken: () => getAccessToken() },
720
+ network: ['pypi.org', 'registry.npmjs.org'], // a fresh sandbox's allowlist (MCP hosts are added)
721
+ });
722
+
723
+ const run = agent.run({
724
+ prompt: 'Fix the failing test',
725
+ cwd: 'https://github.com/acme/game', // cloned into /workspace/game; env_... reuses an environment
726
+ model: 'gemini-4-carbon',
727
+ budget: { maxTokens: 200_000 }, // the interaction's own max_total_tokens
728
+ mcpServers: [{ name: 'game', url: 'https://example.com/mcp', headers: { Authorization: `Bearer ${token}` } }],
729
+ });
730
+ ```
731
+
732
+ - Each turn is a background interaction; `abort()` cancels it. `task.resume` (the last run's
733
+ `sessionId`) chains a new interaction to it in the same environment, so the next run's
734
+ `sessionId` is a new id. Usage adds up the whole chain, and a resumed run reports its own share.
735
+ - Steps stream live (text, MCP, code execution and search calls with their results) and the
736
+ stream picks up from the last event after a drop.
737
+ - MCP servers replace the agent's default tools for that turn, so `tools` (default code execution,
738
+ Google Search, URL context) is sent beside them. Server names must match `^[a-z0-9_-]+$`.
739
+ - `ManagedStart.files` (text only) and the repository go into a fresh sandbox under `filesRoot`
740
+ (default `/workspace`); they cannot be added to an existing environment or on resume.
741
+ - `incomplete` (the token cap) fails with `failure.kind: 'budget'`; a failed interaction's error
742
+ code maps `RESOURCE_EXHAUSTED` to `quota`. The agent asks no approvals (`permissions.approval`
743
+ is `auto-approve` only); `effort`, `maxTurns` and `extraArgs` are refused, and so is `model` for
744
+ a saved agent, whose `agent_config` is fixed: its runs have no platform token cap
745
+ (`capabilities.budget` is empty), so `task.budget` is checked against reported usage only.
746
+
747
+ #### OpenAI background responses
748
+
749
+ `openaiManaged()` runs tasks as background responses of the
750
+ [Responses API](https://developers.openai.com/api/docs/guides/background), with OpenAI's hosted
751
+ tools doing the work: by default a hosted shell and web search. It
752
+ reads `OPENAI_API_KEY` by default:
753
+
754
+ ```ts
755
+ import { openaiManaged } from 'genaicode/agents';
756
+
757
+ const agent = openaiManaged({
758
+ model: 'gpt-6.2-astra',
759
+ network: ['pypi.org', 'github.com'], // the session container's allowlist (none by default)
760
+ // tools: [{ type: 'code_interpreter', container: { type: 'auto' } }], // instead of the defaults
761
+ });
762
+
763
+ const run = agent.run({
764
+ prompt: 'Clone the repo, run its tests and summarize the failures',
765
+ cwd: '.', // or cntr_... to reuse a container you created
766
+ effort: 'high', // reasoning.effort
767
+ maxTurns: 40, // max_tool_calls
768
+ mcpServers: [{ name: 'game', url: 'https://example.com/mcp', headers: { Authorization: `Bearer ${token}` } }],
769
+ });
770
+ ```
771
+
772
+ - The response is polled (`pollIntervalMs`, default 3 s): each output item arrives as a whole
773
+ event once it is finished (messages, MCP, shell, code interpreter and web search calls), so
774
+ there are no `text-delta` events. `abort()` cancels the response.
775
+ - `task.resume` (the last run's `sessionId`) chains a new response with `previous_response_id`,
776
+ so the next run's `sessionId` is a new id. Usage adds up the whole chain, and a resumed run
777
+ reports its own share.
778
+ - The default shell runs in a container made for the session (or the `cntr_...` workspace), and
779
+ 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.
780
+ - MCP servers run without approvals (`require_approval: 'never'`; `permissions.approval` is
781
+ `auto-approve` only). Their only header can be `Authorization: Bearer`, which the platform takes
782
+ as `authorization`: it drops other headers on tool calls.
783
+ - The platform has no session-wide cap, so `task.budget` is checked against reported usage.
784
+ A response cut at `max_output_tokens` fails with `failure.kind: 'budget'`, one cut by a content
785
+ filter fails with its reason, and a failed response's error code maps rate limits to `quota`.
786
+ - `files` and `extraArgs` are refused; a model is required (`model` option or `task.model`).
787
+
788
+ #### Cursor Cloud Agents
789
+
790
+ `cursorCloud()` runs tasks as [Cursor Cloud Agents](https://cursor.com/docs/cloud-agent/api/endpoints)
791
+ in Cursor's VMs, working on a repository and pushing a branch (or opening a pull request). It
792
+ reads `CURSOR_API_KEY` by default:
793
+
794
+ ```ts
795
+ import { cursorCloud } from 'genaicode/agents';
796
+
797
+ const agent = cursorCloud({
798
+ model: 'composer-2', // an id from GET /v1/models; default: the account's default model
799
+ autoCreatePR: true,
800
+ // env: { type: 'pool', name: 'sandbox' }, // your own workers instead of Cursor's VMs
801
+ });
802
+
803
+ const run = agent.run({
804
+ prompt: 'Add a health check endpoint with a test',
805
+ cwd: 'https://github.com/acme/api#main', // a repo (#branch or #sha to start from) or a PR URL
806
+ mcpServers: [{ name: 'docs', url: 'https://example.com/mcp', headers: { Authorization: `Bearer ${token}` } }],
807
+ });
808
+ ```
809
+
810
+ - A session is the agent (`bc-...`), and its `sessionId` stays the same across turns: every turn
811
+ is a run on it. `task.resume` sends a follow-up run, which keeps the agent's model and
812
+ repository (a different `model` or repository URL is refused). Usage is the agent's total, and
813
+ a resumed run reports its own share.
814
+ - The run's events stream live (`text-delta`, messages, tool calls) and the stream resumes from
815
+ the last event after a drop. Past the stream's retention the final state is read instead.
816
+ - `steer()` reaches the running turn (`delivery: 'steer'`), `abort()` cancels the run. A steer
817
+ the platform queues as the next follow-up keeps the turn going into the run it starts.
818
+ - On resume, `mcpServers` replaces the agent's servers (an empty list drops them); left out, the
819
+ agent keeps its current ones.
820
+ - MCP servers go along with their headers. Tools run without approvals (`permissions.approval`
821
+ is `auto-approve` only), and there is no platform budget: `task.budget` is checked against
822
+ usage, which is read every `pollIntervalMs` while the stream runs, and a run over it is
823
+ cancelled.
824
+ - A local `cwd` is ignored (the agent works in its own VM). `effort`, `maxTurns`, `files` and
825
+ `extraArgs` are refused; a system prompt goes before the task text. `vendor` fields go into
826
+ the create (or follow-up) request as they are.
827
+
622
828
  ## Writing a driver
623
829
 
624
830
  ```ts
@@ -654,5 +860,5 @@ way the built-in drivers are tested.
654
860
  1. Headless drivers for claude, codex, and muse, the event IR, and discovery. Done.
655
861
  2. Live sessions (`codex app-server`, `muse serve`): `steer()` mid-task, approval replies. Done.
656
862
  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.
863
+ 4. More CLIs (gemini, cursor, opencode) and a hosted coding-agent seam (`hostedAgent`, `managedAgent`). Done.
658
864
  5. A Copilot CLI driver (`copilot`). Done.
@@ -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.
@@ -0,0 +1,205 @@
1
+ # An agent in the page (`genaicode/browser`)
2
+
3
+ [← README](../README.md)
4
+
5
+ `genaicode/browser` runs an agent **in the web page itself**, on the browser's built-in model
6
+ (Gemini Nano through Chrome's [Prompt API](https://developer.chrome.com/docs/ai/prompt-api)),
7
+ and offers the page's tools to outside agents over [WebMCP](https://webmachinelearning.github.io/webmcp/).
8
+ No server, no API key, no cost per token, and nothing the user types leaves their device.
9
+ Nothing in it imports Node.
10
+
11
+ It is a small model. It is good at "show me X", "what does this page say about Y", "switch
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). 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).
16
+
17
+ ```ts
18
+ import { createPageAgent, exposeWebMcp, type PageTool } from 'genaicode/browser';
19
+
20
+ const tools: PageTool[] = [
21
+ {
22
+ name: 'list_products',
23
+ description: 'The products in the shop, with id, name and price.',
24
+ run: () => products,
25
+ },
26
+ {
27
+ name: 'add_to_cart',
28
+ description: 'Put a product in the cart.',
29
+ inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
30
+ write: true, // the user approves it first
31
+ summary: ({ id }) => `Add ${nameOf(id)} to your cart`,
32
+ run: ({ id }) => cart.add(String(id)),
33
+ },
34
+ ];
35
+
36
+ export const assistant = createPageAgent({
37
+ name: 'helper',
38
+ instructions: 'You help shoppers on Example Shop. Prices are in euro.',
39
+ tools,
40
+ });
41
+
42
+ exposeWebMcp(tools); // the same tools for the browser's own agent and extensions
43
+ ```
44
+
45
+ ```tsx
46
+ import { PageAgentChat } from 'genaicode/react';
47
+ import 'genaicode/react/styles.css';
48
+
49
+ <PageAgentChat agent={assistant} emptyState={<p>Ask me about the shop.</p>} />;
50
+ ```
51
+
52
+ `<PageAgentChat>` is [`<AgentChat>`](react.md) wired to the page agent, with what an
53
+ on-device model needs on top: a note where the browser has no model (`unavailable`), a
54
+ "Download the model" button with progress, Approve/Deny for `write` tools, a chip that shows
55
+ how full the context window is, and "New". Without React, read `assistant.get()` and
56
+ `assistant.subscribe()` and call `send`, `stop`, `reset`, `approve` and `prepare` yourself.
57
+
58
+ ## Tools
59
+
60
+ A `PageTool` is a function with a `name`, a `description` and a JSON Schema (`inputSchema`,
61
+ an object schema). `run(args, signal)` returns text, or any value, which is sent as JSON.
62
+
63
+ - `write: true` marks a tool that changes something. It runs only after the user approved the
64
+ call; `summary(args)` is the line they read. An in-page agent asks in the chat, an outside
65
+ agent goes through `exposeWebMcp`'s `confirm`.
66
+ - `validate(args)` may throw to refuse a call before anyone is asked. Required arguments,
67
+ basic types and `enum` values are checked for you, and the problem goes back to the model.
68
+ - Keep the list short (a handful) and the outputs small: the model sees at most
69
+ `maxToolOutput` characters (default 2,000) of each result. `enum` arguments help a small
70
+ model the most.
71
+
72
+ A `PageTool` has the shape of `AppTool` from `genaicode/app-agent`, so one definition can serve
73
+ a coding agent on your server and the model in the page.
74
+
75
+ ## How the model calls tools
76
+
77
+ The Prompt API has no tool calling, so `nano()` breaks every step into choices the browser
78
+ can constrain with a JSON Schema (`responseConstraint`):
79
+
80
+ 1. Which action: one of the tool names, or `reply`.
81
+ 2. The chosen tool's arguments, constrained by its `inputSchema`.
82
+ 3. The tool runs; its result goes back and the model chooses again, up to `maxSteps` (default 6).
83
+ 4. On `reply`, the answer streams as text.
84
+
85
+ The same exact call is never run twice in a task, bad arguments come back as an error the
86
+ model can fix, and a model that never picks `reply` is made to answer when the steps run out.
87
+
88
+ ## The driver: `nano()`
89
+
90
+ `createPageAgent` is a conversation on top of `nano()`, which is a `CodingAgent` like every
91
+ driver in [`genaicode/agents`](agents.md): the same `run(task)`, events and result.
92
+
93
+ ```ts
94
+ import { nano } from 'genaicode/browser';
95
+
96
+ const agent = nano({ instructions, tools });
97
+ if ((await agent.availability()) !== 'unavailable') {
98
+ const run = agent.run({ prompt: 'Which plans include SSO?', cwd: '' });
99
+ for await (const event of run) if (event.type === 'text-delta') render(event.text);
100
+ const { text, sessionId } = await run.result; // pass sessionId as task.resume to go on
101
+ }
102
+ ```
103
+
104
+ - `availability()`: `available`, `downloadable`, `downloading` or `unavailable`.
105
+ - `prepare()` loads the model, downloading it first when needed. A download needs a user
106
+ gesture, so call it from a click; `onDownload(progress)` reports 0 to 1.
107
+ - Chrome keeps the first `responseConstraint` a session was given: a later prompt with another
108
+ schema fails with `UnknownError` or answers in the first one's shape. So `nano` asks every
109
+ constrained step on a copy of the conversation (`session.clone()`), tells it the task so far,
110
+ and lets the copy go; the conversation itself only hears the request for the reply.
111
+ - A schema-constrained call can still fail with an unexplained `UnknownError`. `nano` then asks
112
+ the model the same thing in words and checks the answer itself, and a reply that fails before
113
+ its first word is tried once more. An error that remains names the step: choosing the action,
114
+ filling in the arguments or writing the reply.
115
+ - `onModelCall({ step, ms, constrained, error })` reports every call to the model, for logs and
116
+ for finding the slow step.
117
+ - `task.onApproval` answers `write` tools (without it they are declined);
118
+ `task.permissions.approval` `'auto-approve'` and `'deny'` work as in every driver.
119
+ `permissions.sandbox: 'read-only'` refuses every `write` tool; a page has no other sandbox,
120
+ so `'workspace-write'`, `'unrestricted'` and `'yolo'` fail the task.
121
+ - `task.resume` continues a conversation in the same model session; `forget(sessionId)` frees it.
122
+ When the context window fills up, the browser drops the oldest messages and keeps the
123
+ instructions. `context(sessionId)` says how full it is.
124
+ - Usage is what the task added to the conversation (`usage.totalTokens`), and
125
+ `task.budget.maxTokens` stops a task that goes over it. There is no cost to cap.
126
+ - `task.cwd`, `env` and `mcpServers` mean nothing in a page. Pass `cwd: ''`.
127
+
128
+ `createPageAgent({ agent })` takes any other `CodingAgent` that runs in a browser instead.
129
+
130
+ ## Files, images and voice
131
+
132
+ ```ts
133
+ const assistant = createPageAgent({ tools, nano: { inputs: ['image', 'audio'] } });
134
+ assistant.send('What is on this screenshot?', [file]);
135
+ ```
136
+
137
+ ```tsx
138
+ <PageAgentChat agent={assistant} attachments />
139
+ ```
140
+
141
+ `send(text, files)` takes `File`s or `Blob`s with a prompt, and `nano().run({ prompt, attachments })`
142
+ does the same one level down.
143
+
144
+ - A text file (by MIME type or extension: Markdown, JSON, CSV, source code) is read into the
145
+ prompt, up to `maxAttachmentText` characters (default 4,000). The context window is small, so a
146
+ long file is cut and the model is told so.
147
+ - An image or audio file goes to the model as it is, if `nano: { inputs }` asked for that kind
148
+ and the browser's model takes it. `assistant.get().model.inputs` (and `nano().inputs()`) lists
149
+ what it takes; elsewhere such a file fails the turn with a message that says why. Audio needs
150
+ a GPU in Chrome.
151
+ - Anything else (a PDF, an archive) is refused.
152
+
153
+ With `attachments`, `<PageAgentChat>` adds an attach button, takes pasted and dropped files, and
154
+ shows a microphone where the model takes audio: it records a voice message that is sent as an
155
+ audio file, so speech stays on the device too. The chat offers only the kinds the model takes.
156
+ `<AgentChat attachments={{ accept, voice, max }}>` has the same composer for any host:
157
+ `onSend(text, files)` gets the files, and a turn's `attachments` are drawn under its prompt.
158
+
159
+ ## WebMCP
160
+
161
+ `exposeWebMcp(tools, { confirm, onCall })` registers the tools on `document.modelContext`
162
+ (or `navigator.modelContext` in the first implementations), so an agent outside the page,
163
+ such as the browser's own assistant, calls your functions instead of guessing at the DOM.
164
+ Read tools are marked `readOnlyHint`, `write` tools `consequentialHint`, and a `write` tool
165
+ runs only after `confirm(tool, args)` resolves true (default: the browser's `confirm()`
166
+ dialog). It returns a function that takes the tools back, and does nothing where WebMCP is
167
+ missing, so it is safe to call everywhere.
168
+
169
+ `webMcpTools()` goes the other way: it lists what the page already registered over WebMCP
170
+ (by any script, or by annotated forms) as `PageTool`s for the in-page agent. It returns an
171
+ empty list where the browser cannot list tools.
172
+
173
+ ## Where it runs
174
+
175
+ | | |
176
+ | --------------- | ------------------------------------------------------------------------------------------ |
177
+ | Prompt API | Chrome 148+ on desktop (Windows, macOS, Linux, Chromebook Plus). Not on Android or iOS. |
178
+ | Hardware | About 22 GB of free disk, and 16 GB of RAM or a GPU with more than 4 GB of VRAM. |
179
+ | Languages | English, Japanese, Spanish, German, French (`nano({ language })`, default `en`). |
180
+ | First use | The browser downloads the model once (a few GB); after that it works offline. |
181
+ | WebMCP | A draft: Chrome origin trial (149 to 156), Edge behind a flag. Register a trial token. |
182
+ | Everything else | `availability()` is `unavailable`: show the page without the assistant, or use a fallback. |
183
+
184
+ The fallback can be a model behind your server: `withFallback([nano({ tools }), remote({ url, tools })])`
185
+ ([backend.md](backend.md)).
186
+
187
+ Check `availability()` (or `<PageAgentChat>`'s `unavailable` slot) and treat the assistant as
188
+ an extra. A common setup loads it only where `'LanguageModel' in self`.
189
+
190
+ ## Tests
191
+
192
+ `fakeLanguageModel(script)` stands in for the browser's model: replies come from `script` in
193
+ order and every prompt is recorded.
194
+
195
+ ```ts
196
+ import { createPageAgent, fakeLanguageModel } from 'genaicode/browser';
197
+
198
+ const model = fakeLanguageModel(['{"action":"list_products"}', '{"action":"reply"}', 'Two products.']);
199
+ const assistant = createPageAgent({ tools, nano: { languageModel: model.factory } });
200
+ ```
201
+
202
+ ## Stability
203
+
204
+ Experimental, like the Prompt API and WebMCP themselves: names here may change in a minor
205
+ release.