genaicode 2.21.0 → 2.23.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/docs/CHANGELOG.md CHANGED
@@ -4,6 +4,21 @@
4
4
 
5
5
  ### Added
6
6
 
7
+ - `claude()` supports `steer()`: the prompt goes to Claude Code as stream-json on stdin, and
8
+ a message sent while it works reaches the running turn between tool calls, as in Claude
9
+ Code itself. `AgentSession.send()` (and so `genaicode chat`, `genaicode ui`, `<AgentChat>`
10
+ and `createAppAgent`) now steers Claude instead of queueing. `claude({ steer: false })`
11
+ keeps the old one-shot prompt argument.
12
+
13
+ - `genaicode acp`: the Agent Client Protocol (version 1) on stdin/stdout, so editors (Zed,
14
+ JetBrains) and apps in any language (a game engine's editor, a Tauri or native app) can run
15
+ the installed agent CLIs: sessions with MCP servers, streamed text and tool calls, permission
16
+ requests, cancel, and config options for the agent, its effort and approvals. See
17
+ [embedding.md](embedding.md#any-language-the-agent-client-protocol).
18
+ - `genaicode embed` (and its skill) also covers desktop apps, game engine editors and apps in
19
+ other languages through `genaicode acp`, and can let the agent drive the running app (play
20
+ the game) through observe / take control / act / release tools. A Godot example lives in
21
+ `docs/examples/godot`.
7
22
  - `autoApprove` in `createAppAgent` answers the agent CLI's own permission prompts the app
8
23
  decides itself (e.g. its auto-approve setting); the rest still wait for the user.
9
24
  - An `AppTool` may return `{ text, images }`: the images (e.g. a screenshot of the app)
package/docs/agents.md CHANGED
@@ -28,22 +28,22 @@ for await (const event of run) {
28
28
  const result = await run.result; // { status, ok, text, sessionId, usage, error, ... }
29
29
  ```
30
30
 
31
- | Agent | Driver | Extras |
32
- | ---------------- | ----------------------------- | ----------------------------------------------- |
33
- | Claude Code | `claude()` | MCP servers, approvals, max turns, effort, cost |
34
- | Codex | `codex()`, `codexLive()` | MCP servers; live: `steer()`, approvals |
35
- | GitHub Copilot | `copilot()` | MCP servers, allow/deny tool patterns |
36
- | Cursor | `cursor()` | streamed text deltas |
37
- | Gemini CLI | `gemini()` | approval mode |
38
- | opencode | `opencode()` | `provider/model` ids, variants |
39
- | Mistral Vibe | `vibe()` | agent profile, max turns, max price |
40
- | Antigravity CLI | `antigravity()` | sandbox, effort, usage |
41
- | Muse | `muse()`, `museLive()` | max turns; live: `steer()`, approvals |
42
- | Your own CLI/API | `cliAgent()`, `hostedAgent()` | plug in any JSON-lines CLI or hosted agent |
31
+ | Agent | Driver | Extras |
32
+ | ---------------- | ----------------------------- | -------------------------------------------- |
33
+ | Claude Code | `claude()` | `steer()`, MCP, approvals, max turns, effort |
34
+ | Codex | `codex()`, `codexLive()` | MCP servers; live: `steer()`, approvals |
35
+ | GitHub Copilot | `copilot()` | MCP servers, allow/deny tool patterns |
36
+ | Cursor | `cursor()` | streamed text deltas |
37
+ | Gemini CLI | `gemini()` | approval mode |
38
+ | opencode | `opencode()` | `provider/model` ids, variants |
39
+ | Mistral Vibe | `vibe()` | agent profile, max turns, max price |
40
+ | Antigravity CLI | `antigravity()` | sandbox, effort, usage |
41
+ | Muse | `muse()`, `museLive()` | max turns; live: `steer()`, approvals |
42
+ | Your own CLI/API | `cliAgent()`, `hostedAgent()` | plug in any JSON-lines CLI or hosted agent |
43
43
 
44
44
  On top of the drivers:
45
45
 
46
- - **Steer a running task** with `run.steer(text)` (live drivers), and answer permission
46
+ - **Steer a running task** with `run.steer(text)` (Claude and the live drivers), and answer permission
47
47
  prompts with `onApproval` (Claude, live Codex and Muse).
48
48
  - **Pick approval and sandbox policy** with `permissions: { approval, sandbox }` (or
49
49
  `'yolo'`); each driver maps it to the agent's own flags and refuses what it cannot honor.
@@ -212,6 +212,11 @@ const result = await run.result;
212
212
  - `steer(text)` resolves once the agent acknowledges the input. It rejects after the task has
213
213
  ended, and when no acknowledgement arrives (the input may or may not have reached the agent).
214
214
  - `onApproval` answers permission requests; see [Approvals](#approvals).
215
+ - `claude()` steers too, without a server: it writes the prompt to Claude Code as
216
+ `--input-format stream-json`, and each steer is one more user message that Claude reads
217
+ between tool calls of the running turn. `steer(text)` resolves once Claude takes it; a steer
218
+ that arrives as the turn ends runs as one more turn of the same task. `claude({ steer: false })`
219
+ passes the prompt as an argument instead.
215
220
  - The task ends when the agent reports its turn complete. The server is then stopped. An exit
216
221
  before that point is a failure, even with exit code 0.
217
222
 
package/docs/app-agent.md CHANGED
@@ -74,3 +74,69 @@ and Copilot get the user's own configured servers switched off. The MCP endpoint
74
74
  bearer and refuses browser requests; every other route asks `authorize` and refuses
75
75
  cross-site requests. Without `authorize` only a loopback `Host` is accepted (add names with
76
76
  `allowedHosts`), so a DNS-rebinding page cannot reach the agent.
77
+
78
+ ## The agent drives the app (a game)
79
+
80
+ The same tools let the agent use the app the way a person does: play a level, click through a
81
+ flow, reproduce a bug. Give it a way to look and a way to act, and make taking control visible.
82
+
83
+ ```ts
84
+ let controlled = false; // the page shows "Agent controls this game" and a Take back control button
85
+
86
+ const agent = createAppAgent({
87
+ name: 'the game in the dev build',
88
+ instructions: 'Call game_take_control before game_act. Observe after each move.',
89
+ tools: [
90
+ {
91
+ name: 'game_observe',
92
+ description: "The game's state and a screenshot of the current frame.",
93
+ run: async () => ({ text: JSON.stringify(game.state()), images: [await game.screenshot()] }),
94
+ },
95
+ {
96
+ name: 'game_take_control',
97
+ description: 'Take the controls from the player.',
98
+ run: () => ((controlled = true), 'ok'),
99
+ },
100
+ {
101
+ name: 'game_act',
102
+ description: 'Press keys or click, then let the game run for `frames` frames.',
103
+ inputSchema: {
104
+ type: 'object',
105
+ properties: { keys: { type: 'array', items: { type: 'string' } }, frames: { type: 'integer', maximum: 120 } },
106
+ },
107
+ validate: () => {
108
+ if (!controlled) throw new Error('Call game_take_control first.');
109
+ },
110
+ // The schema is a hint to the agent; the bound is enforced here.
111
+ run: async ({ keys, frames }) =>
112
+ game.step(
113
+ Array.isArray(keys) ? keys.map(String) : [],
114
+ Math.min(Math.max(Math.trunc(Number(frames) || 10), 1), 120),
115
+ ),
116
+ },
117
+ { name: 'game_release_control', description: 'Give the controls back.', run: () => ((controlled = false), 'ok') },
118
+ ],
119
+ });
120
+
121
+ // The player can always take control back, and control never outlives the agent's turn.
122
+ agent.subscribe((state) => {
123
+ if (state.session?.status !== 'running') controlled = false;
124
+ });
125
+ ```
126
+
127
+ What makes this work:
128
+
129
+ - **No approval cards for moves.** These tools are not `write`, so each call runs at once. Keep
130
+ `write: true` for what should wait for the user (deleting a save, publishing a build).
131
+ - **Observe returns pixels.** A read tool may return `images`; the agent sees the frame, not only
132
+ the numbers. Keep screenshots small (a few hundred pixels wide) so the turn stays fast.
133
+ - **Bound every move.** `game_act` advances a limited number of frames and returns, so the agent
134
+ plays in short steps and a stuck call cannot hang the turn.
135
+ - **Control is visible and revocable.** Show who drives in the page, let a click give control back
136
+ (the next `game_act` then fails with a message the agent reads), and drop control when the turn
137
+ ends or the user presses Stop.
138
+ - **Pause when nobody acts**, if the game allows it, so the agent's thinking time does not cost
139
+ the player their run.
140
+
141
+ Outside a browser (a Godot or Unity editor, a native app) the game serves the same tools from
142
+ its own MCP server; see [embedding.md](./embedding.md).
package/docs/cli.md CHANGED
@@ -1,4 +1,4 @@
1
- # Command line: run, chat, ui, embed
1
+ # Command line: run, chat, ui, embed, acp
2
2
 
3
3
  [← README](../README.md)
4
4
 
@@ -90,8 +90,12 @@ instructions on how to embed genaicode, and the agent reads the project and pick
90
90
  in: the [Vite overlay](vite.md) for an app on Vite; for any other Node dev server (webpack,
91
91
  Next.js, Express...) the same overlay through `createDevOverlay` from `genaicode/ui`; for
92
92
  pages with no dev server at all, a small dev-only server of its own with that overlay; the in-app agent (`genaicode/app-agent` with
93
- `<AppAgentChat>`) when the agent should act on the app itself; and `npx genaicode ui` next
94
- to the dev server when there is no Node process to host it. Words after `embed` go to the
93
+ `<AppAgentChat>`) when the agent should act on the app's data; a panel over `genaicode acp`
94
+ for a desktop app, a game engine editor (Godot, Unity...) or an app in another language; and
95
+ `npx genaicode ui` next to the dev server when there is nothing to add a panel to. Any of
96
+ them can also let the agent drive the running app (play the game, click through a flow)
97
+ through observe / take control / act / release tools ([embedding.md](embedding.md#let-the-agent-act-on-the-app)).
98
+ Words after `embed` go to the
95
99
  agent as your request. You watch and answer in the same chat as `genaicode chat` (`--ui`
96
100
  for the browser); without a terminal it runs headless like `run`. The agent installs the
97
101
  package, edits the config, runs your checks and reports; it does not commit.
@@ -103,3 +107,15 @@ The instructions are also a Claude Code skill. Copy
103
107
  ```bash
104
108
  mkdir -p .claude/skills && cp -r node_modules/genaicode/docs/skills/genaicode-embed .claude/skills/
105
109
  ```
110
+
111
+ ## For editors and apps in other languages: `genaicode acp`
112
+
113
+ ```bash
114
+ npx genaicode acp -a claude
115
+ ```
116
+
117
+ `genaicode acp` serves the [Agent Client Protocol](https://agentclientprotocol.com) on stdin
118
+ and stdout, for editors that speak it (Zed, JetBrains IDEs) and for any app that starts it as a
119
+ child process: a Godot or Unity editor plugin, a Tauri or native app, a Python tool. Sessions,
120
+ streamed replies and tool calls, permission requests and cancel go over the protocol; the host
121
+ picks the agent, effort and approvals per session. See [embedding.md](embedding.md#any-language-the-agent-client-protocol).
@@ -0,0 +1,166 @@
1
+ # Embedding genaicode outside the web
2
+
3
+ [← README](../README.md)
4
+
5
+ genaicode runs coding agents on the developer's machine. Web apps get the [Vite panel](./vite.md),
6
+ [`createDevOverlay`](./vite.md) or [`<AppAgentChat>`](./app-agent.md). This page is for every other
7
+ host: desktop apps, game editors, terminal tools and programs that are not written in JavaScript.
8
+ It is about development tools: the agent CLIs, their logins and Node 20+ come from the developer's
9
+ machine, so none of this belongs in an app you ship to end users.
10
+
11
+ | Host | What to use |
12
+ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
13
+ | Electron | `genaicode/agents` in the main process, the chat in a window ([below](#electron)) |
14
+ | Any webview (Tauri, WebView2, Qt, CEF) | a small Node script with `startEmbeddedWeb`, its URL in the webview ([below](#a-webview-in-another-language)) |
15
+ | Any language, a whole conversation | `genaicode acp`: the Agent Client Protocol on stdin/stdout ([below](#any-language-the-agent-client-protocol)) |
16
+ | Any language, one prompt at a time | `genaicode run --json` as a child process ([below](#any-language-one-prompt-at-a-time)) |
17
+ | An app the agent should act on | the app's tools over MCP ([below](#let-the-agent-act-on-the-app)) |
18
+
19
+ ## Electron
20
+
21
+ The main process is Node, so the whole API is there. Either show the bundled chat in a window:
22
+
23
+ ```ts
24
+ // main.ts
25
+ import { app, BrowserWindow } from 'electron';
26
+ import { startEmbeddedWeb } from 'genaicode/ui';
27
+
28
+ app.whenReady().then(async () => {
29
+ const web = await startEmbeddedWeb({ cwd: projectDir });
30
+ const win = new BrowserWindow({ width: 480, height: 800 });
31
+ await win.loadURL(web.url); // 127.0.0.1 with its access token: keep it out of logs
32
+ app.on('before-quit', () => void web.close());
33
+ });
34
+ ```
35
+
36
+ `web.controller` lets the app drive the same session: `submit()` a prompt, `note()` a line into
37
+ the transcript, `approve()` a pending request.
38
+
39
+ Or draw the chat in your own renderer: run `createAppAgent` and `createAppAgentHandler` in the
40
+ main process on 127.0.0.1 and put `<AppAgentChat>` in the renderer ([app-agent.md](./app-agent.md)),
41
+ or build on `createAgentSession` and `<AgentChat>` ([react.md](./react.md)).
42
+
43
+ ## A webview in another language
44
+
45
+ A Tauri, .NET or Qt app can show the same chat. Start it from a short Node script next to the app
46
+ and read its URL from stdout:
47
+
48
+ ```js
49
+ // genaicode-panel.mjs, started by the app with: node genaicode-panel.mjs <project dir>
50
+ import { startEmbeddedWeb } from 'genaicode/ui';
51
+
52
+ const web = await startEmbeddedWeb({ cwd: process.argv[2] });
53
+ process.stdout.write(JSON.stringify({ url: web.url }) + '\n');
54
+ process.stdin.on('end', () => web.close().then(() => process.exit(0))); // the app went away
55
+ process.stdin.resume();
56
+ ```
57
+
58
+ The app opens `url` in its webview (top level, not in an iframe: framing needs `frameAncestors`).
59
+ Treat the URL as a secret; it carries the access token.
60
+
61
+ ## Any language: the Agent Client Protocol
62
+
63
+ `genaicode acp` speaks the [Agent Client Protocol](https://agentclientprotocol.com) (ACP,
64
+ version 1): JSON-RPC 2.0, one message per line, on stdin and stdout. Editors that support ACP
65
+ (Zed, JetBrains IDEs and others) can run it as an agent as it is, and a host in any language can
66
+ drive it with an ACP client library (TypeScript, Python, Rust, Kotlin...) or a few lines of JSON.
67
+
68
+ ```bash
69
+ npx genaicode acp # the first installed agent
70
+ npx genaicode acp -a codex -y # start with Codex, approving every permission request
71
+ ```
72
+
73
+ The host starts the process and then:
74
+
75
+ 1. `initialize` with `protocolVersion: 1`.
76
+ 2. `session/new` with `cwd` (the project) and `mcpServers` (HTTP or stdio servers the agent should
77
+ use, e.g. the app's own tools). The reply lists the session's config options.
78
+ 3. `session/prompt` with the user's text (also `resource_link` and embedded `resource` blocks).
79
+ While the agent works, the host gets `session/update` notifications: `agent_message_chunk`,
80
+ `tool_call` and `tool_call_update` (with `kind`, a title such as `Bash: npm test`, and the
81
+ file in `locations`). The reply comes when the turn ends: `stopReason: "end_turn"`, or
82
+ `"cancelled"` after a `session/cancel`; a failed run is a JSON-RPC error with the agent's
83
+ message.
84
+ 4. When the agent asks for permission, genaicode sends `session/request_permission` with the
85
+ options `approve` and `deny`; the host answers with the one the user picked.
86
+
87
+ Each prompt continues the agent's own session, so the conversation carries on. The config
88
+ options switch, between prompts, `agent` (one of the installed agent CLIs; the next agent starts
89
+ a new conversation), `effort` (when the agent has levels) and `mode` (`ask` or `auto-approve`)
90
+ through `session/set_config_option`. `session/close` stops a session.
91
+
92
+ A complete exchange, one JSON object per line (`>` sent by the host, `<` by genaicode):
93
+
94
+ ```text
95
+ > {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1}}
96
+ < {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"genaicode",...},...}}
97
+ > {"jsonrpc":"2.0","id":2,"method":"session/new","params":{"cwd":"/work/game","mcpServers":[]}}
98
+ < {"jsonrpc":"2.0","id":2,"result":{"sessionId":"5b1c...","configOptions":[...]}}
99
+ > {"jsonrpc":"2.0","id":3,"method":"session/prompt","params":{"sessionId":"5b1c...","prompt":[{"type":"text","text":"Fix the bug in math.js"}]}}
100
+ < {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"5b1c...","update":{"sessionUpdate":"tool_call","toolCallId":"toolu_01...","title":"Read: /work/game/math.js","kind":"read","status":"in_progress",...}}}
101
+ < {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"5b1c...","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"Fixed: add now adds."},...}}}
102
+ < {"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}}
103
+ ```
104
+
105
+ [examples/godot](examples/godot/README.md) is a complete host: a Godot editor dock that chats
106
+ with the agent over ACP in GDScript, and a game that serves its own MCP tools so the agent can
107
+ play it.
108
+
109
+ With an agent that cannot resume (gemini, antigravity) each prompt starts a fresh agent session.
110
+ A session with MCP servers offers only the agents that can attach them (claude, codex, copilot).
111
+ Not supported yet: `session/load` and `session/resume` (sessions live as long as the process),
112
+ images in prompts, SSE MCP servers, and the client's file system and terminal methods (the agent
113
+ CLI reads, writes and runs commands itself).
114
+
115
+ ## Any language, one prompt at a time
116
+
117
+ `genaicode run --json` reads the prompt from stdin (`-`) and prints one JSON `AgentEvent` per line:
118
+ `session`, `text-delta`, `message`, `tool-start`, `tool-end`, `file-change`, `usage`, `error`,
119
+ then `done` with the result ([agents.md](./agents.md)). Pass `--resume <sessionId>` from the
120
+ `session` event to continue the conversation on the next prompt.
121
+
122
+ ```python
123
+ import json, subprocess
124
+
125
+ proc = subprocess.Popen(
126
+ ["npx", "genaicode", "run", "--json", "-a", "claude", "-C", project_dir, "-"],
127
+ stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True,
128
+ )
129
+ proc.stdin.write("Fix the failing test in test_physics.py")
130
+ proc.stdin.close()
131
+ for line in proc.stdout:
132
+ event = json.loads(line)
133
+ if event["type"] == "text-delta":
134
+ print(event["text"], end="")
135
+ elif event["type"] == "done":
136
+ session_id = event["result"].get("sessionId")
137
+ ```
138
+
139
+ This is one-way (use `genaicode acp` for a conversation): the agent cannot ask the host for a permission, so steps that need one are
140
+ declined unless you pass `--yes` (approve everything). Stop a run by ending the process.
141
+
142
+ ## Let the agent act on the app
143
+
144
+ The agent can do more than edit code: it can use the app, for example play a level in a game and
145
+ look at the frames. The app serves tools over MCP and the agent calls them. In a Node host,
146
+ `genaicode/app-agent` does this with approval cards and a chat ([app-agent.md](./app-agent.md),
147
+ including [a game the agent plays](./app-agent.md#the-agent-drives-the-app-a-game)).
148
+
149
+ An app in another language serves the tools from its own MCP server (there is an MCP SDK for
150
+ most languages) and hands it to the agent through `AgentTask.mcpServers`, e.g. from the Node
151
+ script above:
152
+
153
+ ```js
154
+ const web = await startEmbeddedWeb({
155
+ cwd: process.argv[2],
156
+ task: { mcpServers: [{ name: 'game', url: 'http://127.0.0.1:7777/mcp' }] },
157
+ });
158
+ ```
159
+
160
+ The [Godot example](examples/godot/README.md) does this from GDScript: the running game serves
161
+ `game_observe`, `game_take_control`, `game_act` and `game_release_control` on 127.0.0.1, and the
162
+ editor dock passes that server to `genaicode acp` in `session/new`.
163
+
164
+ The agent's CLI may ask before it calls a tool of a new server; answer in the chat, or allow the
165
+ server in the agent's own settings. Keep each action short and bounded, and show in the app when
166
+ the agent has the controls.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: genaicode-embed
3
- description: Embed genaicode in a project so its developers chat with their own coding agent (Claude Code, Codex, Copilot...) from inside the running app. Use when asked to add genaicode, its Vite overlay, a dev agent panel, or an in-app agent drawer (genaicode/app-agent) to a project, with or without Vite.
3
+ description: Embed genaicode in a project so its developers chat with their own coding agent (Claude Code, Codex, Copilot...) from inside the running app, and optionally let the agent use the app itself (play a game, click through a flow). Use when asked to add genaicode, its Vite overlay, a dev agent panel, an in-app agent drawer (genaicode/app-agent), or an agent panel in a desktop app, a game engine editor (Godot, Unity...) or a non-JavaScript app (genaicode acp).
4
4
  ---
5
5
 
6
6
  # Embed genaicode in this project
@@ -10,9 +10,9 @@ already has installed (Claude Code, Codex, Copilot CLI, Cursor, Gemini, opencode
10
10
  one API. Your job is to wire it into the project in the current directory so the
11
11
  project's developers can talk to their agent from inside the running app.
12
12
 
13
- There are four ways in, plus a last resort. Pick by what the project is, not by what is
13
+ There are five ways in, plus a last resort. Pick by what the project is, not by what is
14
14
  more impressive. Always end with a working way in: "it doesn't fit" is not a result while
15
- the project has HTML pages a browser can open.
15
+ the project has HTML pages a browser can open or a UI you can add a panel to.
16
16
 
17
17
  1. **Vite dev overlay** (`genaicode/vite`): for any app built with Vite. One plugin line;
18
18
  in `vite dev` the page gets a wolf button that opens a chat with the agent working in
@@ -34,9 +34,21 @@ the project has HTML pages a browser can open.
34
34
  serves those files on localhost with the overlay from option 2 injected into the HTML
35
35
  it serves, and an npm script to start it. The files on disk and the build output stay
36
36
  untouched, so size budgets and release builds are not affected.
37
- 5. **Last resort**: no Node at all in the project and no HTML to serve (a Rails, Django or
38
- Go app whose server you cannot change safely): tell the user to run `npx genaicode ui`
39
- (browser) or `npx genaicode` (terminal) next to their dev server, and say why.
37
+ 5. **Desktop app, game engine or another language** (`genaicode acp`): Electron, Tauri,
38
+ .NET, Qt, a Godot or Unity editor plugin, a Python or Go tool. The app starts
39
+ `npx genaicode acp` as a child process and talks the Agent Client Protocol (JSON-RPC on
40
+ stdin/stdout) to it: a whole conversation with streaming, tool calls, permission questions
41
+ and agent/effort pickers, from any language. Electron can also use `genaicode/ui` in its
42
+ main process directly.
43
+ 6. **Last resort**: nothing you can add a panel to (a Rails, Django or Go web app whose
44
+ server you cannot change safely): tell the user to run `npx genaicode ui` (browser) or
45
+ `npx genaicode` (terminal) next to their dev server, and say why.
46
+
47
+ Any of these can also **let the agent drive the app**: the app serves a few MCP tools
48
+ (observe, take control, act, release control) and the agent uses the running app the way a
49
+ person does, e.g. plays the game to test a change, reproduces a bug, walks through a flow.
50
+ Offer it when the app is a game or anything interactive; add it when the user asks for it.
51
+ See "Recipe: let the agent drive the app".
40
52
 
41
53
  The agent CLI always runs on the machine that runs the server, with that machine's
42
54
  login and files. Options 1, 2 and 4 exist only in development. The in-app agent is for apps
@@ -62,7 +74,11 @@ allow, batch what must run into few commands, and do not run the dev server just
62
74
  is an internal tool with a Node server and a React UI: option 3, alone or next to
63
75
  option 1 or 2.
64
76
  - Pages but no dev server: option 4.
65
- - Otherwise: option 5. Say why.
77
+ - A desktop app, a game engine project (`project.godot`, a Unity `Assets/` folder...),
78
+ or an app in another language with its own UI: option 5.
79
+ - The user wants the agent to play the game or click through the app: add the tools from
80
+ "Recipe: let the agent drive the app" to whichever option you chose.
81
+ - Otherwise: option 6. Say why.
66
82
  - If genaicode is already wired in, extend or fix what is there instead of adding a
67
83
  second copy.
68
84
  3. **Install** `genaicode` as a dev dependency for options 1, 2 and 4, as a regular
@@ -71,12 +87,15 @@ allow, batch what must run into few commands, and do not run the dev server just
71
87
  `bun.lockb`/`bun.lock` bun). If you may not run the install, add the dependency to
72
88
  `package.json` with the version from your task and tell the user to run it. genaicode
73
89
  needs Node 20+ and declares no React peer: the app brings React 18+ for
74
- `genaicode/react`.
90
+ `genaicode/react`. Option 5 outside Node installs nothing in the project: the app runs
91
+ `npx -y genaicode@<version> acp` (the version from your task) and needs Node 20+ on the
92
+ developer's machine.
75
93
  4. **Wire it in** (recipes below), matching the project's style: TypeScript or
76
94
  JavaScript, ESM or CJS, its formatter, its folder layout.
77
95
  5. **Check it**: run the project's type check, lint and tests if it has them, and a
78
96
  production build. For options 1, 2 and 4 the production output must not contain
79
- genaicode. Fix what you broke; do not "fix" unrelated failures. Remove build output
97
+ genaicode; for option 5 and the drive-the-app tools, release builds must not start
98
+ `genaicode acp` or serve the tools. Fix what you broke; do not "fix" unrelated failures. Remove build output
80
99
  you created that the project does not track.
81
100
  6. **Report**, starting with how to see it, before anything else: one line with the exact
82
101
  command to run and what happens next, e.g. "Run `npm run agent`: the game opens in your
@@ -238,6 +257,56 @@ createServer(async (req, res) => {
238
257
  - A page that reloads itself on change (a watch build) is the developer's own; do not
239
258
  add a live-reload system for this.
240
259
 
260
+ ## Recipe: desktop, game engines, other languages (`genaicode acp`)
261
+
262
+ `genaicode acp` is a coding agent for the [Agent Client Protocol](https://agentclientprotocol.com)
263
+ (v1): newline-delimited JSON-RPC 2.0 on stdin/stdout. Zed and other ACP editors can use it as
264
+ is. In an app you write a small client:
265
+
266
+ 1. Start `npx -y genaicode@<version> acp` (flags: `-a <agent>`, `-m <model>`, `--effort`,
267
+ `-y` to skip permission prompts, only if asked) with the project as working directory.
268
+ On Windows run it through `cmd.exe /c`. Read stdout without blocking the UI thread.
269
+ 2. Send `initialize` `{protocolVersion: 1}`, then `session/new`
270
+ `{cwd, mcpServers: [...]}`. Its result has `sessionId` and `configOptions` (agent, effort,
271
+ approval mode): show them as pickers, change them with `session/set_config_option`.
272
+ 3. Send `session/prompt` `{sessionId, prompt: [{type: 'text', text}]}`. While it runs,
273
+ `session/update` notifications stream `agent_message_chunk` text, `tool_call` and
274
+ `tool_call_update`; render them in the panel. The result has `stopReason`.
275
+ 4. Answer `session/request_permission` requests (Allow / Reject in the panel) with
276
+ `{outcome: {outcome: 'selected', optionId}}`; several can be open at once. Stop sends the
277
+ `session/cancel` notification.
278
+ 5. After a prompt, refresh what the host shows from disk (the agent edited files).
279
+
280
+ Put the panel where the host's developers work: an editor dock (Godot `EditorPlugin`, Unity
281
+ `EditorWindow`), a side window, a dev-only menu entry. Keep it out of release builds.
282
+ A complete GDScript client and editor dock: https://github.com/gtanczyk/genaicode/blob/master/docs/examples/godot
283
+ Electron: `startEmbeddedWeb` from `genaicode/ui` in the main process shows the bundled chat in
284
+ a `BrowserWindow` without any protocol code.
285
+
286
+ ## Recipe: let the agent drive the app
287
+
288
+ In the running app (development builds only), serve four MCP tools on 127.0.0.1 and pass that
289
+ server to the agent: `mcpServers` in `session/new` for ACP, `tools` of `createAppAgent` for the
290
+ in-app agent, `task.mcpServers` elsewhere.
291
+
292
+ - `game_observe` (or `app_observe`): the state as JSON plus a small screenshot (a few hundred
293
+ pixels wide) as an MCP image.
294
+ - `game_take_control`: the agent takes over. The app shows "Agent controls this game" with a
295
+ Take back control button, and pauses between the agent's moves if it can.
296
+ - `game_act`: press keys or click, run a bounded number of frames (clamp, e.g. 1-120, in code,
297
+ not only in the schema), return the new state. Fails until control is taken, and when the
298
+ user took control back. One act at a time.
299
+ - `game_release_control`: give the controls back. Also release when the agent's turn ends
300
+ or its client disconnects.
301
+
302
+ Listen on 127.0.0.1 only and refuse browser requests (an `Origin` header, a `Host` that is not
303
+ localhost) so a web page cannot drive the app. These tools are not writes, so they need no
304
+ approval card. Details and a TypeScript version: "The agent drives the app (a game)" in
305
+ https://github.com/gtanczyk/genaicode/blob/master/docs/app-agent.md; a GDScript server:
306
+ https://github.com/gtanczyk/genaicode/blob/master/docs/examples/godot/addons/genaicode/game_mcp.gd.
307
+ When you add this, the report says how to try it, e.g. "run the game, then ask the agent:
308
+ Play the game: take control and collect 3 stars."
309
+
241
310
  ## Recipe: in-app agent
242
311
 
243
312
  Server side, wherever the Node server is created:
@@ -319,4 +388,5 @@ import 'genaicode/react/styles.css';
319
388
  - Do not turn on `approveAll` or the agents' "yolo" modes unless the user asks.
320
389
  - These recipes are starting points, not templates to paste: adapt them to what the
321
390
  project already does. If something does not fit, say what and why instead of forcing it.
322
- - Docs: https://github.com/gtanczyk/genaicode#readme
391
+ - Docs: https://github.com/gtanczyk/genaicode#readme, outside the web:
392
+ https://github.com/gtanczyk/genaicode/blob/master/docs/embedding.md
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "genaicode",
3
- "version": "2.21.0",
3
+ "version": "2.23.0",
4
4
  "description": "Drive the coding-agent CLIs you already have (Claude Code, Codex, Copilot, Cursor, Gemini, opencode...) behind one API and one CLI, plus a thin provider-neutral LLM layer.",
5
5
  "author": "Grzegorz Tańczyk",
6
6
  "repository": {
@@ -89,6 +89,7 @@
89
89
  "openai": "^5.16.0"
90
90
  },
91
91
  "devDependencies": {
92
+ "@agentclientprotocol/sdk": "^2.0.2",
92
93
  "@types/node": "^20.0.0",
93
94
  "@types/react": "^19.3.0",
94
95
  "@types/react-dom": "^19.3.0",
@@ -106,7 +107,8 @@
106
107
  "react-dom": "^19.3.0",
107
108
  "typescript": "^5.0.0",
108
109
  "vite": "^6.4.5",
109
- "vitest": "^4.1.12"
110
+ "vitest": "^4.1.12",
111
+ "zod": "^3.25.76"
110
112
  },
111
113
  "prettier": {
112
114
  "trailingComma": "all",