genaicode 2.17.0 → 2.17.1

package/README.md

@@ -1,89 +1,47 @@
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="media/logo-dark.png">
-    <source media="(prefers-color-scheme: light)" srcset="media/logo.png">
-    <img alt="GenAIcode Logo." src="media/logo.png" width="100%" height="auto">
+    <source media="(prefers-color-scheme: dark)" srcset="docs/media/logo-dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="docs/media/logo.png">
+    <img alt="GenAIcode Logo." src="docs/media/logo.png" width="100%" height="auto">
   </picture>
 </p>
 
 # GenAIcode
 
-GenAIcode is a small TypeScript toolkit for using LLMs in backend code.
+GenAIcode drives the coding-agent CLIs you already have (Claude Code, Codex, GitHub Copilot
+CLI, Cursor, Gemini CLI, opencode, Muse, Mistral Vibe, Antigravity) behind one API and one
+CLI. Script them, swap them with one flag, and let your tests decide when the job is done.
 
-It sits between raw provider SDKs and full agent frameworks: one prompt representation,
-thin provider adapters, a convenient request API, and lightweight conversation chains.
-The core does not inspect repositories, execute shell commands, edit files, or run an agent UI.
-The opt-in [`genaicode/agents`](#coding-agents) subpath drives the coding-agent CLIs you
-already have (Claude Code, Codex, GitHub Copilot CLI, Cursor, Gemini CLI, opencode, Muse,
-Mistral Vibe, Antigravity) behind one task and event API, so you can orchestrate them from
-backend code. The same drivers are on the command line as `npx genaicode run`.
-
-**Like jQuery**, the common case starts with one small function and becomes more specific
-through chaining—configure a request, follow up across multiple prompts, and keep history
-portable without adopting a full agent framework.
-
-GenAIcode 1.x was a coding agent; see [Migration from 1.x](#migration-from-1x) if you need
-the old product or the 2.0 scope decisions.
-
-## Install
+<p align="center">
+  <a href="docs/media/showcase.mp4">
+    <img alt="genaicode in 20 seconds: the Vite overlay fixes a broken page, run --verify sends a failed test back to the agent, and an agent inside an app waits for Approve." src="docs/media/screenshots/showcase.gif" width="100%">
+  </a>
+  <br>
+  <sub>Recorded live with Claude Code and Codex. <a href="docs/media/showcase.mp4">Full video (87 s)</a>.</sub>
+</p>
 
 ```bash
-npm install genaicode
+npx genaicode run --verify "npm test" "fix the failing tests"
 ```
 
-Node.js 20 or newer is required.
+That runs the first agent CLI installed on your machine in the current directory, then runs
+`npm test`. If the check fails, its output goes back to the agent for another attempt. Add
+`-a codex` (or `claude`, `copilot`, `opencode`...) to pick the agent; the command stays the
+same. From there, the same drivers are a TypeScript API, a chat in your terminal or browser,
+a panel inside your Vite app, and an agent inside your own app.
 
-## Why this vs a raw SDK
+GenAIcode also ships [a thin LLM layer](#also-a-thin-llm-layer) for calling model providers
+from backend code. The two halves are separate subpaths: importing `genaicode` never spawns an
+agent, and `genaicode/agents` loads no provider SDK.
 
-Provider SDKs are the right tool when you call one vendor and own every request shape
-yourself. The cost shows up when the same backend needs a second provider, a test double,
-or shared policy (timeouts, JSON parsing, rate limits, fallback) without copying glue.
-
-GenAIcode is that thin shared layer:
-
-- One portable prompt/tool IR (`PromptItem`) instead of OpenAI messages vs Anthropic
-  blocks vs Gemini contents.
-- One request API (`.text()`, `.json()`, `.stream()`, chains) over those adapters.
-- A tiny `ModelProvider` seam so tests and custom gateways do not mock vendor HTTP.
-- Opt-in middleware and retry helpers—no hidden tool runners, no silent retries, no
-  agent loop.
-
-If you are happy importing one SDK and never swapping models or providers, stay on the
-SDK. If you want the call site to look the same while the edge stays replaceable, use
-GenAIcode.
-
-## A prompt in three lines
-
-```ts
-import { genaicode } from 'genaicode';
-import { openai } from 'genaicode/providers';
-
-const ai = genaicode(openai({ model: 'your-model-name' }));
-const answer = await ai('Explain why the sky is blue in two sentences.').text();
-```
-
-The client is callable on purpose. Configuration is ordinary method chaining—system
-instructions, temperature, token limits, and more—without a separate options object or
-framework setup:
+## Install
 
-```ts
-const result = await ai('Create a release note from these commits')
-  .system('You are a concise technical writer.')
-  .temperature(0.2)
-  .maxOutputTokens(500)
-  .text();
+```bash
+npm install genaicode
 ```
 
-Builders are immutable, so a configured base request can be safely reused:
-
-```ts
-const releaseNote = ai('Create a release note from these commits')
-  .system('You are a concise technical writer.')
-  .temperature(0.2);
-
-const short = await releaseNote.maxOutputTokens(200).text();
-const long = await releaseNote.maxOutputTokens(800).text();
-```
+Node.js 20 or newer is required. The agent CLIs are yours to install and log in to;
+`npx genaicode agents` lists which ones it finds.
 
 ## Coding agents
 
@@ -168,15 +126,15 @@ 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%">
+    <source media="(prefers-reduced-motion: reduce)" srcset="docs/media/screenshots/chat-terminal.png">
+    <img alt="genaicode chat in a terminal: the agent fixes a failing test, then takes queued follow-ups." src="docs/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%">
+    <source media="(prefers-reduced-motion: reduce) and (prefers-color-scheme: dark)" srcset="docs/media/screenshots/wolf-dark.png">
+    <source media="(prefers-reduced-motion: reduce)" srcset="docs/media/screenshots/wolf-light.png">
+    <source media="(prefers-color-scheme: dark)" srcset="docs/media/screenshots/chat-browser-dark.gif">
+    <source media="(prefers-color-scheme: light)" srcset="docs/media/screenshots/chat-browser-light.gif">
+    <img alt="genaicode ui in a browser: the same fix and a follow-up." src="docs/media/screenshots/chat-browser-light.gif" width="49%">
   </picture>
 </p>
 
@@ -186,9 +144,9 @@ The terminal UI rings the terminal bell instead. `/bark off` (or the Bark button
 
 <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%">
+    <source media="(prefers-color-scheme: dark)" srcset="docs/media/screenshots/wolf-dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="docs/media/screenshots/wolf-light.png">
+    <img alt="The browser UI with the wolf behind a finished turn." src="docs/media/screenshots/wolf-light.png" width="80%">
   </picture>
 </p>
 
@@ -213,9 +171,9 @@ export default defineConfig({ plugins: [genaicode()] });
 
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="media/screenshots/vite-dark.png">
-    <source media="(prefers-color-scheme: light)" srcset="media/screenshots/vite-light.png">
-    <img alt="The genaicode panel over a Vite app: the agent fixed the page's two errors." src="media/screenshots/vite-light.png" width="80%">
+    <source media="(prefers-color-scheme: dark)" srcset="docs/media/screenshots/vite-dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="docs/media/screenshots/vite-light.png">
+    <img alt="The genaicode panel over a Vite app: the agent fixed the page's two errors." src="docs/media/screenshots/vite-light.png" width="80%">
   </picture>
 </p>
 
@@ -409,7 +367,7 @@ import 'genaicode/react/styles.css';
 ```
 
 <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%">
+  <img alt="A shop admin with the agent drawer: the agent proposed a refund, waiting for Approve." src="docs/media/screenshots/app-agent.png" width="80%">
 </p>
 
 Under it, `/api/agent` serves `GET /events` (a stream of `AppAgentState`: the session, earlier
@@ -431,7 +389,70 @@ bearer and refuses browser requests; every other route asks `authorize` and refu
 cross-site requests. Without `authorize` only a loopback `Host` is accepted (add names with
 `allowedHosts`), so a DNS-rebinding page cannot reach the agent.
 
-## Chaining prompts
+## Also: a thin LLM layer
+
+Besides driving agents, GenAIcode is a small TypeScript toolkit for calling LLMs from backend
+code. It sits between raw provider SDKs and full agent frameworks: one prompt representation,
+thin provider adapters, a convenient request API, and lightweight conversation chains. This
+layer does not inspect repositories, execute shell commands, edit files, or run an agent UI.
+
+**Like jQuery**, the common case starts with one small function and becomes more specific
+through chaining—configure a request, follow up across multiple prompts, and keep history
+portable without adopting a full agent framework.
+
+### A prompt in three lines
+
+```ts
+import { genaicode } from 'genaicode';
+import { openai } from 'genaicode/providers';
+
+const ai = genaicode(openai({ model: 'your-model-name' }));
+const answer = await ai('Explain why the sky is blue in two sentences.').text();
+```
+
+The client is callable on purpose. Configuration is ordinary method chaining—system
+instructions, temperature, token limits, and more—without a separate options object or
+framework setup:
+
+```ts
+const result = await ai('Create a release note from these commits')
+  .system('You are a concise technical writer.')
+  .temperature(0.2)
+  .maxOutputTokens(500)
+  .text();
+```
+
+Builders are immutable, so a configured base request can be safely reused:
+
+```ts
+const releaseNote = ai('Create a release note from these commits')
+  .system('You are a concise technical writer.')
+  .temperature(0.2);
+
+const short = await releaseNote.maxOutputTokens(200).text();
+const long = await releaseNote.maxOutputTokens(800).text();
+```
+
+### Why this vs a raw SDK
+
+Provider SDKs are the right tool when you call one vendor and own every request shape
+yourself. The cost shows up when the same backend needs a second provider, a test double,
+or shared policy (timeouts, JSON parsing, rate limits, fallback) without copying glue.
+
+GenAIcode is that thin shared layer:
+
+- One portable prompt/tool IR (`PromptItem`) instead of OpenAI messages vs Anthropic
+  blocks vs Gemini contents.
+- One request API (`.text()`, `.json()`, `.stream()`, chains) over those adapters.
+- A tiny `ModelProvider` seam so tests and custom gateways do not mock vendor HTTP.
+- Opt-in middleware and retry helpers—no hidden tool runners, no silent retries, no
+  agent loop.
+
+If you are happy importing one SDK and never swapping models or providers, stay on the
+SDK. If you want the call site to look the same while the edge stays replaceable, use
+GenAIcode.
+
+### Chaining prompts
 
 A chain remembers successful user and assistant turns. Each new prompt sees the complete
 history, so multi-step work stays in ordinary application code:
@@ -449,7 +470,7 @@ const answer3 = await chain.text('Prompt 3: summarize the final contract.');
 This is `prompt1 → response1 → prompt2 → response2 → prompt3 → response3`. The history
 is available as portable `PromptItem[]` through `chain.history()`.
 
-## Using a chain in a loop
+### Using a chain in a loop
 
 A chain is ordinary application state, so normal control flow works:
 
@@ -492,7 +513,7 @@ for (let attempt = 1; attempt <= 3; attempt += 1) {
 
 The application owns validation, attempt limits, and failure policy.
 
-## Schema adapters
+### Schema adapters
 
 `json(...)` and `parseJsonResult(...)` accept either a parser function or a schema adapter
 with a `parse(value)` method. This keeps schema validation library-agnostic:
@@ -512,7 +533,7 @@ Calling `.json()` also sets `responseFormat: { type: 'json' }` on the request wh
 not already chosen a format, so providers that support JSON mode (OpenAI, Gemini/Vertex)
 are asked for JSON rather than free text.
 
-## Response format and thinking
+### Response format and thinking
 
 Portable request fields cover the two knobs backends usually poke through provider-specific
 config:
@@ -543,7 +564,7 @@ Providers map what they support and ignore the rest. `ProviderCapabilities.jsonR
 and `ProviderCapabilities.thinking` advertise support. Vendor-specific escapes such as
 Vertex `generationConfig` remain available for anything not covered here.
 
-## PromptItem: the portable prompt IR
+### PromptItem: the portable prompt IR
 
 `PromptItem` is GenAIcode's provider-neutral intermediate representation:
 
@@ -576,7 +597,7 @@ const supportTicket = (ticket: Ticket) =>
 await ai(supportTicket(ticket)).text();
 ```
 
-## Tools
+### Tools
 
 ```ts
 const calls = await ai('What is the weather in Warsaw?')
@@ -598,7 +619,7 @@ const calls = await ai('What is the weather in Warsaw?')
 GenAIcode normalizes tool calls but deliberately does not execute them. The application
 owns permissions, retries, and side effects.
 
-## Streaming
+### Streaming
 
 Providers that support native streaming expose a provider-neutral `StreamEvent` IR.
 Request builders and chains offer `.stream()` and `.streamText()`. If a provider has no
@@ -618,7 +639,7 @@ ai.provider.capabilities;
 // { streaming: true, tools: true, images: 'input', systemPrompt: true }
 ```
 
-## Middleware
+### Middleware
 
 Hook-style plugins remain the extension point. Built-in helpers cover common backend
 needs without restoring a global registry:
@@ -637,7 +658,7 @@ const ai = genaicode(openai({ model: 'your-model-name' }), {
 });
 ```
 
-## Retries
+### Retries
 
 Retries stay in application code. Use `classifyError`, `isRetryable`, and `withRetry`
 when you want shared classification without hidden policy:
@@ -654,7 +675,7 @@ const text = await withRetry(() => ai('Summarize the deploy notes.').text(), {
 See [retry guidance](docs/retry.md), [semver policy](docs/semver.md), and the
 [provider package evaluation](docs/provider-packages.md).
 
-## Providers
+### Providers
 
 Models are provided in the adapter, through `.model(...)`, or with environment variables:
 
@@ -718,7 +739,7 @@ const provider: ModelProvider = {
 All Anthropic, Google, and OpenAI conversion functions are public from
 `genaicode/providers`, so gateways and tests can reuse them without instantiating clients.
 
-## Provider E2E tests
+### Provider E2E tests
 
 Run real-provider E2E tests locally with:
 
@@ -739,7 +760,7 @@ Beyond the smoke call, E2E also covers portable `responseFormat: { type: 'json'
 CI/CD is configured in `.github/workflows/provider-e2e.yaml`. Each provider runs in its own
 job and only starts when both required secrets are configured in GitHub Actions.
 
-## Plugins and hooks
+### Plugins and hooks
 
 A provider plugin no longer needs registration in global configuration. It exports the
 same small `ModelProvider` contract as a built-in adapter:
@@ -787,7 +808,7 @@ Plugins run in registration order, and each plugin may call `next()` once. This
 extension mechanism compatible with npm packages and ordinary imports without restoring
 the 1.x runtime TypeScript loader or process-global plugin registry.
 
-Framework-shaped examples live under `examples/` (`http-handler`, `queue-worker`,
+Framework-shaped examples live under [`docs/examples/`](docs/examples/) (`http-handler`, `queue-worker`,
 `cron-job`).
 
 ## Design boundaries

package/{CHANGELOG.md → docs/CHANGELOG.md}

@@ -53,6 +53,9 @@
 
 ### Changed
 
+- README and the package description lead with the coding agents: a 20-second demo, the
+  `npx genaicode run --verify` one-liner, then `genaicode/agents`. The LLM layer moved below
+  them as "Also: a thin LLM layer", and the 1.x note to the end.
 - `defaultAppAgents`: Claude cannot start subagents (`Task`, `Agent`) in either mode; one can
   outlive the turn, so its answer never reaches the user.
 
@@ -265,7 +268,7 @@
 ### Notes
 
 - Releases are published from GitHub Actions when a version tag is pushed. See
-  [docs/releasing.md](docs/releasing.md).
+  [docs/releasing.md](releasing.md).
 
 ## 2.4.0 — 2026-09-24
 
@@ -275,7 +278,7 @@
   `CodingAgent` interface. Drivers `claude()`, `codex()`, `muse()`; agent-neutral
   `AgentEvent` stream and `AgentResult`; abort, timeout and process-group kill;
   `detectAgents` / `findExecutable`; `cliAgent()` for custom drivers. See
-  [docs/agents.md](docs/agents.md).
+  [docs/agents.md](agents.md).
 - Live agent sessions over JSON-RPC: `codexLive()` (`codex app-server`) and `museLive()`
   (`muse serve`) with `AgentRun.steer()` and `AgentTask.onApproval`; `liveAgent()` and
   `RpcPeer` for custom live drivers; `approval-resolved` event.
@@ -316,7 +319,7 @@
 
 Publishes the Phase 3–4 work already on `master`. npm `2.0.0` shipped the 2.0
 kernel and provider adapters only; this minor adds the remaining public surface
-documented in the README and [semver policy](docs/semver.md).
+documented in the README and [semver policy](semver.md).
 
 ### Added
 
@@ -324,12 +327,12 @@ documented in the README and [semver policy](docs/semver.md).
   native streams for OpenAI / Anthropic / Google with generate→stream fallback)
 - Built-in middleware: `timingPlugin`, `rateLimitPlugin`, `cachePlugin`,
   `fallbackPlugin`, `fallbackProvider`
-- Retry helpers: `classifyError`, `isRetryable`, `withRetry` (+ [docs/retry.md](docs/retry.md))
+- Retry helpers: `classifyError`, `isRetryable`, `withRetry` (+ [docs/retry.md](retry.md))
 - `ProviderCapabilities` on `ModelProvider`
 - Compatibility fixtures for multimodal and tool-call round trips
 - Framework examples under `examples/` (HTTP handler, queue worker, cron job)
-- Written guidance: [docs/semver.md](docs/semver.md),
-  [docs/provider-packages.md](docs/provider-packages.md)
+- Written guidance: [docs/semver.md](semver.md),
+  [docs/provider-packages.md](provider-packages.md)
 
 ### Notes
 

package/docs/pivot.md

@@ -91,7 +91,7 @@ and in the 1.x npm line.
   `fallbackProvider`).
 - First-class schema adapters without requiring a specific validation library — implemented.
 - Small framework examples for HTTP handlers, queues, and cron jobs — implemented
-  under `examples/`.
+  under `docs/examples/`.
 - Re-evaluate separate provider packages if dependency size becomes material —
   evaluated; keep bundled for 2.x (see [provider-packages.md](./provider-packages.md)).
 
@@ -113,7 +113,7 @@ and in the 1.x npm line.
   helpers, fixtures, examples, and related docs).
 - `2.2.0` adds portable `responseFormat` and `thinking` request fields (so apps
   need fewer provider-specific `generationConfig` casts). See
-  [CHANGELOG.md](../CHANGELOG.md).
+  [CHANGELOG.md](CHANGELOG.md).
 
 ## Success measures
 

package/docs/semver.md

@@ -52,7 +52,7 @@ Require a new major version:
 - Timing of stream events beyond the `StreamEvent` discriminant
 - Dependency versions of underlying provider SDKs within a major (may bump in
   minors when needed for security or API drift)
-- Example apps under `examples/` (illustrative only)
+- Example apps under `docs/examples/` (illustrative only)
 
 ## Plugin and provider authors
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "genaicode",
-  "version": "2.17.0",
-  "description": "A small, provider-neutral TypeScript toolkit for calling LLMs from backend code.",
+  "version": "2.17.1",
+  "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.",
   "author": "Grzegorz Tańczyk",
   "repository": {
     "type": "git",
@@ -33,7 +33,8 @@
   "files": [
     "dist",
     "docs",
-    "CHANGELOG.md",
+    "!docs/examples",
+    "!docs/media",
     "README.md",
     "LICENSE"
   ],
@@ -70,16 +71,17 @@
   },
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
-    "build": "npm run clean && tsc -p tsconfig.build.json && node scripts/build-ui.mjs",
+    "build": "npm run clean && tsc -p scripts/tsconfig.build.json && node scripts/build-ui.mjs",
     "lint": "eslint . --ext js,ts,tsx --report-unused-disable-directives --max-warnings 0",
-    "test": "vitest --config vitest.unit.config.ts --run",
-    "test:e2e": "vitest --config vitest.e2e.config.ts --run",
-    "test:browser": "vitest --config vitest.browser.config.ts --run",
-    "test:watch": "vitest --config vitest.unit.config.ts",
+    "test": "vitest --config scripts/vitest.config.ts --run --project unit",
+    "test:e2e": "vitest --config scripts/vitest.config.ts --run --project e2e",
+    "test:browser": "vitest --config scripts/vitest.config.ts --run --project browser",
+    "test:watch": "vitest --config scripts/vitest.config.ts --project unit",
     "type-check": "tsc --noEmit",
     "check": "npm run type-check && npm run lint && npm test && npm run build",
     "prepublishOnly": "npm run check",
-    "prepare": "npm run build"
+    "prepare": "npm run build",
+    "format": "prettier --write ."
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.74.0",
@@ -96,10 +98,8 @@
     "eslint": "^8.54.0",
     "eslint-config-prettier": "^9.0.0",
     "happy-dom": "^20.14.5",
-    "husky": "^9.1.1",
     "ink": "^6.8.0",
     "ink-testing-library": "^4.0.0",
-    "lint-staged": "^16.4.0",
     "playwright": "^1.56.1",
     "prettier": "^3.1.0",
     "react": "^19.3.0",
@@ -108,7 +108,29 @@
     "vite": "^6.4.3",
     "vitest": "^4.1.11"
   },
-  "lint-staged": {
-    "*.{js,ts,md}": "prettier --write"
+  "prettier": {
+    "trailingComma": "all",
+    "tabWidth": 2,
+    "semi": true,
+    "singleQuote": true,
+    "printWidth": 120,
+    "bracketSpacing": true,
+    "endOfLine": "lf"
+  },
+  "eslintConfig": {
+    "root": true,
+    "env": {
+      "node": true
+    },
+    "extends": [
+      "eslint:recommended",
+      "plugin:@typescript-eslint/recommended"
+    ],
+    "ignorePatterns": [
+      "docs/examples/**/*",
+      "dist",
+      "coverage"
+    ],
+    "parser": "@typescript-eslint/parser"
   }
 }