genaicode 2.33.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.
- package/README.md +1 -0
- package/dist/agents/drivers/anthropic-managed.d.ts +141 -0
- package/dist/agents/drivers/anthropic-managed.js +753 -0
- package/dist/agents/drivers/anthropic-managed.js.map +1 -0
- package/dist/agents/drivers/cursor-cloud.d.ts +78 -0
- package/dist/agents/drivers/cursor-cloud.js +478 -0
- package/dist/agents/drivers/cursor-cloud.js.map +1 -0
- package/dist/agents/drivers/gemini-managed.d.ts +78 -0
- package/dist/agents/drivers/gemini-managed.js +526 -0
- package/dist/agents/drivers/gemini-managed.js.map +1 -0
- package/dist/agents/drivers/managed-http.d.ts +28 -0
- package/dist/agents/drivers/managed-http.js +142 -0
- package/dist/agents/drivers/managed-http.js.map +1 -0
- package/dist/agents/drivers/openai-managed.d.ts +79 -0
- package/dist/agents/drivers/openai-managed.js +402 -0
- package/dist/agents/drivers/openai-managed.js.map +1 -0
- package/dist/agents/failover.d.ts +19 -1
- package/dist/agents/failover.js +63 -2
- package/dist/agents/failover.js.map +1 -1
- package/dist/agents/hosted.d.ts +5 -1
- package/dist/agents/hosted.js +45 -132
- package/dist/agents/hosted.js.map +1 -1
- package/dist/agents/managed.d.ts +154 -0
- package/dist/agents/managed.js +561 -0
- package/dist/agents/managed.js.map +1 -0
- package/dist/agents/runtime.d.ts +5 -1
- package/dist/agents/runtime.js +9 -0
- package/dist/agents/runtime.js.map +1 -1
- package/dist/agents.d.ts +11 -1
- package/dist/agents.js +6 -1
- package/dist/agents.js.map +1 -1
- package/dist/backend/backend.d.ts +131 -0
- package/dist/backend/backend.js +773 -0
- package/dist/backend/backend.js.map +1 -0
- package/dist/backend/limiter.d.ts +34 -0
- package/dist/backend/limiter.js +76 -0
- package/dist/backend/limiter.js.map +1 -0
- package/dist/backend/node.d.ts +10 -0
- package/dist/backend/node.js +124 -0
- package/dist/backend/node.js.map +1 -0
- package/dist/backend/protocol.d.ts +98 -0
- package/dist/backend/protocol.js +2 -0
- package/dist/backend/protocol.js.map +1 -0
- package/dist/backend/seal.d.ts +7 -0
- package/dist/backend/seal.js +60 -0
- package/dist/backend/seal.js.map +1 -0
- package/dist/backend.d.ts +27 -0
- package/dist/backend.js +25 -0
- package/dist/backend.js.map +1 -0
- package/dist/browser/invoke.d.ts +17 -0
- package/dist/browser/invoke.js +69 -0
- package/dist/browser/invoke.js.map +1 -0
- package/dist/browser/nano.d.ts +10 -0
- package/dist/browser/nano.js +10 -56
- package/dist/browser/nano.js.map +1 -1
- package/dist/browser/page-agent.d.ts +7 -0
- package/dist/browser/page-agent.js +26 -5
- package/dist/browser/page-agent.js.map +1 -1
- package/dist/browser/remote.d.ts +44 -0
- package/dist/browser/remote.js +372 -0
- package/dist/browser/remote.js.map +1 -0
- package/dist/browser.d.ts +9 -2
- package/dist/browser.js +8 -2
- package/dist/browser.js.map +1 -1
- package/dist/core/types.d.ts +5 -0
- package/dist/core/types.js.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/providers/google-converter.js +3 -0
- package/dist/providers/google-converter.js.map +1 -1
- package/dist/providers/google.js +7 -10
- package/dist/providers/google.js.map +1 -1
- package/dist/react/page-agent-chat.js +6 -2
- package/dist/react/page-agent-chat.js.map +1 -1
- package/docs/CHANGELOG.md +38 -395
- package/docs/agents.md +207 -1
- package/docs/backend.md +125 -0
- package/docs/browser.md +6 -1
- package/docs/changelog-2.26-and-older.md +441 -0
- package/docs/pivot.md +1 -1
- package/package.json +5 -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.
|
package/docs/backend.md
ADDED
|
@@ -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
|
|