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/README.md +1 -0
- package/dist/acp/server.d.ts +38 -0
- package/dist/acp/server.js +475 -0
- package/dist/acp/server.js.map +1 -0
- package/dist/agents/cli-agent.d.ts +17 -0
- package/dist/agents/cli-agent.js +92 -1
- package/dist/agents/cli-agent.js.map +1 -1
- package/dist/agents/drivers/claude.d.ts +15 -1
- package/dist/agents/drivers/claude.js +29 -7
- package/dist/agents/drivers/claude.js.map +1 -1
- package/dist/agents/process.d.ts +2 -0
- package/dist/agents/process.js +3 -0
- package/dist/agents/process.js.map +1 -1
- package/dist/cli/args.d.ts +6 -0
- package/dist/cli/args.js +19 -0
- package/dist/cli/args.js.map +1 -1
- package/dist/cli/main.d.ts +3 -1
- package/dist/cli/main.js +31 -0
- package/dist/cli/main.js.map +1 -1
- package/docs/CHANGELOG.md +15 -0
- package/docs/agents.md +18 -13
- package/docs/app-agent.md +66 -0
- package/docs/cli.md +19 -3
- package/docs/embedding.md +166 -0
- package/docs/skills/genaicode-embed/SKILL.md +80 -10
- package/package.json +4 -2
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
|
|
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
|
|
94
|
-
|
|
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,
|
|
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
|
|
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. **
|
|
38
|
-
|
|
39
|
-
|
|
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
|
-
-
|
|
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
|
|
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.
|
|
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",
|