genaicode 2.18.4 → 2.20.0

package/docs/CHANGELOG.md

@@ -20,6 +20,8 @@
   (e.g. `!npm run dev` after `genaicode embed`), its output in the transcript; `/stop`, Esc
   or the Stop button end it and what it started, `!!` sends a leading `!` to the agent.
   `<AgentChat canStop>` offers Stop while the agent is idle.
+- `Markdown` renders GFM tables (alignment, `\|` escapes, horizontal scroll when wide),
+  `~~strikethrough~~` and task lists (`- [x]`). A table may follow a paragraph line directly.
 
 ### Changed
 

package/docs/agents.md

@@ -7,6 +7,57 @@
 behind one interface. It is the agent-side counterpart of `ModelProvider`. A driver
 translates at the edge and does not own application policy.
 
+## Quick look
+
+`genaicode/agents` turns the coding-agent CLIs installed on a machine into one API. Give
+any of them a task (a prompt and a working directory) and get back the same event stream
+and result, whichever agent does the work. It is how you script, compare, or chain coding
+agents from a job, a bot, or a CI step without writing a parser per vendor.
+
+```ts
+import { claude, codex, copilot, cursor, detectAgents } from 'genaicode/agents';
+
+const [found] = detectAgents([claude(), codex(), copilot(), cursor()]).filter(({ path }) => path);
+if (!found) throw new Error('No coding agent installed.');
+
+const run = found.agent.run({ prompt: 'Add a unit test for parseDate', cwd: '/path/to/repo', timeoutMs: 20 * 60_000 });
+for await (const event of run) {
+  if (event.type === 'tool-start') console.log('⚙', event.name);
+  if (event.type === 'file-change') console.log('edited', event.paths.join(', '));
+}
+const result = await run.result; // { status, ok, text, sessionId, usage, error, ... }
+```
+
+| Agent            | Driver                        | Extras                                          |
+| ---------------- | ----------------------------- | ----------------------------------------------- |
+| Claude Code      | `claude()`                    | MCP servers, approvals, max turns, effort, cost |
+| Codex            | `codex()`, `codexLive()`      | MCP servers; live: `steer()`, approvals         |
+| GitHub Copilot   | `copilot()`                   | MCP servers, allow/deny tool patterns           |
+| Cursor           | `cursor()`                    | streamed text deltas                            |
+| Gemini CLI       | `gemini()`                    | approval mode                                   |
+| opencode         | `opencode()`                  | `provider/model` ids, variants                  |
+| Mistral Vibe     | `vibe()`                      | agent profile, max turns, max price             |
+| Antigravity CLI  | `antigravity()`               | sandbox, effort, usage                          |
+| Muse             | `muse()`, `museLive()`        | max turns; live: `steer()`, approvals           |
+| Your own CLI/API | `cliAgent()`, `hostedAgent()` | plug in any JSON-lines CLI or hosted agent      |
+
+On top of the drivers:
+
+- **Steer a running task** with `run.steer(text)` (live drivers), and answer permission
+  prompts with `onApproval` (Claude, live Codex and Muse).
+- **Pick approval and sandbox policy** with `permissions: { approval, sandbox }` (or
+  `'yolo'`); each driver maps it to the agent's own flags and refuses what it cannot honor.
+- **Attach MCP servers per task** with `mcpServers`. Header secrets stay out of argv.
+- **Verify and repair**: `runWithVerify` runs your check (tests, lint) after the agent and
+  sends failures back for another attempt.
+- **Keep credentials apart**: `withoutProviderCredentials()` strips your app's LLM API keys
+  from the agent's environment, so it bills its own login.
+
+Importing `genaicode` never spawns anything; only `genaicode/agents` does. The agent uses
+its own credentials and billing, and its own permission settings unless `permissions` sets
+them; any sandbox is the agent's own. GenAIcode does not choose a model or retry it. See the sections below for events, options per
+driver, and writing your own driver.
+
 ## Scope
 
 In scope:

package/docs/app-agent.md

@@ -0,0 +1,71 @@
+# Agent inside your app (`genaicode/app-agent`)
+
+[← README](../README.md)
+
+`genaicode/app-agent` puts an agent in a local app you run on your machine (an admin
+console, an internal tool, a game editor). The user chats with an agent CLI they already
+have; the agent works the app through tools the app serves over MCP, changes wait for the
+user's approval, and in `dev` mode the agent also edits the app's code and proposes a commit.
+
+```ts
+import { createServer } from 'node:http';
+import { createAppAgent, createAppAgentHandler } from 'genaicode/app-agent';
+
+const agent = createAppAgent({
+  name: 'the shop admin',
+  mcpUrl: 'http://127.0.0.1:3000/api/agent/mcp',
+  tools: [
+    { name: 'orders', description: 'List open orders.', run: () => JSON.stringify(listOrders()) },
+    {
+      name: 'refund',
+      description: 'Refund an order.',
+      write: true, // a card with Approve and Reject; runs only after Approve
+      inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+      run: ({ id }) => refund(String(id)),
+    },
+  ],
+  pages: () => ['/orders', '/customers'], // page context, link chips, "take me there"
+  dev: { cwd: process.cwd(), commands: ['npm test'] }, // optional: the agent edits the app
+});
+const handle = createAppAgentHandler(agent, { authorize: (req) => isSignedIn(req) });
+
+createServer(async (req, res) => {
+  if (await handle(req, res)) return;
+  // ...the rest of the app
+}).listen(3000, '127.0.0.1');
+```
+
+On the page, `AppAgentChat` from `genaicode/react` is the whole drawer: the chat, the agent's
+page chips under its replies, Approve and Reject cards (with the diff of a proposed commit),
+and the agent and mode pickers. It reports `currentPath` to the agent and calls `onNavigate`
+when a chip is clicked or the agent is asked to go somewhere.
+
+```tsx
+import { AppAgentChat } from 'genaicode/react';
+import 'genaicode/react/styles.css';
+
+<AppAgentChat currentPath={location.pathname} onNavigate={(path) => router.push(path)} />;
+```
+
+<p align="center">
+  <img alt="A shop admin with the agent drawer: the agent proposed a refund, waiting for Approve." src="media/screenshots/app-agent.png" width="80%">
+</p>
+
+Under it, `/api/agent` serves `GET /events` (a stream of `AppAgentState`: the session, earlier
+turns, pending actions, link chips, navigation requests) and `POST /send`, `/stop`, `/reset`,
+`/config`, `/view`, `/actions/:id` and `/approvals/:id` (the agent CLI's own permission
+prompts); `useAppAgent` wraps them for a page of your own. Switching agent or mode keeps the
+conversation: the next agent gets a short transcript. `trace` receives every prompt, MCP call,
+decision and finished turn, for a log. Default agents are Claude Code, Codex and
+Copilot CLI, locked down per mode: in `use` mode they get only the app's tools (no shell, no
+file edits); in `dev` mode they edit files and run the listed commands, never commit or push (Claude and
+Copilot enforce the command list; Codex has no per-command allowlist, so it runs in its
+`workspace-write` sandbox: writes only inside `cwd`, no network).
+`propose_commit` snapshots the worktree, the user reviews that diff, and Approve commits
+exactly that tree on the reviewed HEAD, or refuses if the files or HEAD changed since, a hook
+changed the files, or a merge or rebase is in progress. The repository's commit hooks run.
+The agent sees no MCP server but the app's: Claude runs with `--strict-mcp-config`, and Codex
+and Copilot get the user's own configured servers switched off. The MCP endpoint takes a per-run
+bearer and refuses browser requests; every other route asks `authorize` and refuses
+cross-site requests. Without `authorize` only a loopback `Host` is accepted (add names with
+`allowedHosts`), so a DNS-rebinding page cannot reach the agent.

package/docs/cli.md

@@ -0,0 +1,105 @@
+# Command line: run, chat, ui, embed
+
+[← README](../README.md)
+
+## From the command line
+
+The `genaicode` bin runs the same headless drivers without writing any code:
+
+```bash
+npx genaicode agents                                   # which agent CLIs are installed
+npx genaicode run "Add a unit test for parseDate"      # first installed agent, current dir
+npx genaicode run -a codex -C ../api --verify "npm test" "Fix the failing date tests"
+git diff | npx genaicode run --json -a claude -        # prompt from stdin, JSON-lines events
+```
+
+Assistant text goes to stdout and tool calls, edits, and the result line go to stderr.
+`--verify` runs a shell command after the agent finishes and sends its output back for up
+to `--max-repairs` more attempts (`runWithVerify`). The exit code is 0 on success, 1 when
+the agent or the check fails, 2 on a usage error, and 130 when interrupted.
+`npx genaicode --help` lists every option.
+
+## Chat with an agent: terminal and browser
+
+```bash
+npx genaicode                      # chat in this terminal (same as "genaicode chat")
+npx genaicode chat -a claude -C ../api
+npx genaicode ui                   # the same chat in your browser, served on 127.0.0.1
+npx genaicode chat --web           # both: the terminal and the browser on one session
+```
+
+The terminal and the browser can show one session. `/web` in the terminal chat opens it in
+the browser (`/web off` stops the server), and Enter in the terminal that runs
+`genaicode ui` brings it into that terminal. A prompt, an approval or a stop from either
+side shows up in both.
+
+Each prompt after the first continues the agent's own session (`AgentTask.resume`), so you
+can say "now add a test for that". Prompts sent while the agent works wait in a queue and
+run next; Esc stops the agent. When the agent asks for permission, `y` approves, `n`
+denies and `a` approves everything from then on (`/auto`, or the Auto-approve chip in the
+browser; `-y` starts that way). `!` on an empty prompt switches to shell mode, as in Claude
+Code: `!npm run dev` runs in the project with its output in the transcript, and `/stop` (or
+Esc) ends it. `/agent`, `/model` and `/new` switch agent,
+model and session; `/help` lists the rest.
+
+<p align="center">
+  <picture>
+    <source media="(prefers-reduced-motion: reduce)" srcset="media/screenshots/chat-terminal.png">
+    <img alt="genaicode chat in a terminal: the agent fixes a failing test, then takes queued follow-ups." src="media/screenshots/chat-terminal.gif" width="49%">
+  </picture>
+  <picture>
+    <source media="(prefers-reduced-motion: reduce) and (prefers-color-scheme: dark)" srcset="media/screenshots/wolf-dark.png">
+    <source media="(prefers-reduced-motion: reduce)" srcset="media/screenshots/wolf-light.png">
+    <source media="(prefers-color-scheme: dark)" srcset="media/screenshots/chat-browser-dark.gif">
+    <source media="(prefers-color-scheme: light)" srcset="media/screenshots/chat-browser-light.gif">
+    <img alt="genaicode ui in a browser: the same fix and a follow-up." src="media/screenshots/chat-browser-light.gif" width="49%">
+  </picture>
+</p>
+
+The wolf from genaicode 1.0 is back. When the agent asks for approval or finishes, the
+browser UI barks if its tab is in the background and counts those events in the tab title.
+The terminal UI rings the terminal bell instead. `/bark off` (or the Bark button) quiets it.
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="media/screenshots/wolf-dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="media/screenshots/wolf-light.png">
+    <img alt="The browser UI with the wolf behind a finished turn." src="media/screenshots/wolf-light.png" width="80%">
+  </picture>
+</p>
+
+`genaicode ui` listens on the loopback address and prints a link with a random access
+token. The page, the event stream and every command need that token; only the bundled
+script and the four mascot files (`/app.js`, `/assets/…`) are served without it, since they
+hold nothing about your session. Both front ends are bundled into the package and load
+only for these commands; importing `genaicode` or `genaicode/agents` pulls in no UI code.
+In code, the same conversation is `createAgentSession` from `genaicode/agents` (see
+[agents.md](agents.md#chat-sessions)); with a live driver (`codexLive`,
+`museLive`) it also steers the running agent and asks you about permission requests.
+
+## Let your agent embed it
+
+```bash
+npx genaicode embed                      # in your project: your agent wires genaicode in
+npx genaicode embed -a codex "only the dev panel"
+npx genaicode embed --print | pbcopy     # just the instructions, for any other agent
+```
+
+`genaicode embed` does not inspect your project itself. It starts your agent with
+instructions on how to embed genaicode, and the agent reads the project and picks the way
+in: the [Vite overlay](vite.md) for an app on Vite; for any other Node dev server (webpack,
+Next.js, Express...) the same overlay through `createDevOverlay` from `genaicode/ui`; for
+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
+`<AppAgentChat>`) when the agent should act on the app itself; and `npx genaicode ui` next
+to the dev server when there is no Node process to host it. Words after `embed` go to the
+agent as your request. You watch and answer in the same chat as `genaicode chat` (`--ui`
+for the browser); without a terminal it runs headless like `run`. The agent installs the
+package, edits the config, runs your checks and reports; it does not commit.
+
+The instructions are also a Claude Code skill. Copy
+[`skills/genaicode-embed`](skills/genaicode-embed/SKILL.md) into `.claude/skills/` (or
+`~/.claude/skills/`) and ask Claude to "embed genaicode":
+
+```bash
+mkdir -p .claude/skills && cp -r node_modules/genaicode/docs/skills/genaicode-embed .claude/skills/
+```