thebird 1.2.79 → 1.2.80

package/.github/workflows/publish.yml

@@ -28,7 +28,15 @@ jobs:
 
       - name: Bump patch version
         run: |
-          NEW_VERSION=$(npm version patch --no-git-tag-version)
+          git fetch --tags --force
+          for i in 1 2 3 4 5; do
+            NEW_VERSION=$(npm version patch --no-git-tag-version)
+            if git rev-parse "${NEW_VERSION}" >/dev/null 2>&1; then
+              echo "Tag ${NEW_VERSION} already exists, bumping again (attempt $i)"
+              continue
+            fi
+            break
+          done
           git add package.json
           git commit -m "chore: bump to ${NEW_VERSION}"
           git tag "${NEW_VERSION}"

package/CHANGELOG.md

@@ -1,5 +1,213 @@
+
+## [unreleased] 2026-04-21 node parity pass 12 — internal listen infrastructure
+- feat: busnet — in-browser TCP-like listen/connect via BroadcastChannel cross-tab fabric
+- feat: net.createServer now uses busnet — apps listen on ports other in-browser apps can connect to
+- feat: busHttp — HTTP request/response framing over busnet
+- feat: service discovery — busnet.discover() returns [{port,service,origin}] from peer tabs
+- feat: netstat builtin — lists local listeners + peer services
+- feat: window.__debug.node.busnet exposes full state
+- feat: same-tab listen+connect works instantly without BroadcastChannel round-trip
+
+## [unreleased] 2026-04-21 node parity pass 11 — virtualization + polyfills wave 3
+- feat: virtual /proc filesystem — /proc/self/{cmdline,environ,stat,status,maps,limits}, /proc/{cpuinfo,meminfo,uptime,loadavg,version,stat,mounts,filesystems}
+- feat: virtual /etc — hosts, resolv.conf, passwd, group, os-release, hostname, machine-id, shells
+- feat: isomorphic-git wrapper — git.clone/commit/push/pull/status/log/checkout against real remotes via HTTP
+- feat: tar/tar.gz extract + list — hand-rolled POSIX tar reader + fflate gunzip, works with real npm tarballs
+- feat: DoH DNS polyfill — dns.resolve/resolve4/resolve6/resolveMx/resolveTxt/resolveNs/lookup/reverse via Cloudflare DoH with Google fallback
+- feat: native addon dispatch — .node files route to WASM/JS equivalents (bufferutil, utf-8-validate, bcrypt, argon2, farmhash; sharp/better_sqlite3 placeholders)
+- feat: process.dlopen for native modules
+- feat: coreutils builtins — uname/whoami/hostname/id/df/free/uptime/ps/nproc/arch/yes/seq/tac/rev/nl/fold/od/xxd/dirname/basename/pwd/groups/logname/tty/stty/locale
+- feat: npm registry shim — view/search/deps/tarballUrl/fetchTarball via esm.sh + registry.npmjs.org
+- feat: os.cpus() returns real navigator.hardwareConcurrency, os.networkInterfaces returns lo
+- feat: process.resourceUsage real numbers from performance.memory
+- feat: crypto.secureHeapUsed
+- feat: os.constants.signals/errno populated
+
+## [unreleased] 2026-04-21 node parity pass 10 — test runner + util extras + IPC
+- feat: node:test real runner — test/describe/it execute, report pass/fail/skip with colors and timing
+- feat: node:test mock.fn / mock.method with calls recording
+- feat: node:test/reporters TAP reporter (ok/not ok/plan)
+- feat: util.styleText (named styles: red/green/bold/italic/etc)
+- feat: util.stripVTControlCharacters removes ANSI escapes
+- feat: util.getCallSites frame extractor
+- feat: util.MIMEType + util.MIMEParams (RFC-compliant parse/serialize)
+- feat: console.table/group/groupEnd/time/timeEnd/timeLog/count/countReset/dir/trace/assert/clear — full console surface
+- feat: readline.createInterface — real interactive question/answer via xterm, asyncIterator, cursorTo/clearLine
+- feat: fork IPC via BroadcastChannel — process.send/process.on('message')
+- feat: node:sqlite module alias (DatabaseSync) — Node 22+ API
+
+## [unreleased] 2026-04-21 node parity pass 9 — pnpm/yarn wired, workspaces, dlx
+- feat: shell dispatches pnpm/yarn/bun/deno/corepack/dlx commands (previously shell-pm.js existed but wasn't wired)
+- feat: workspaces resolution — package.json 'workspaces' field + pnpm-workspace.yaml packages:- syntax
+- feat: Yarn Classic v1 lockfile writer + parser (real format, not JSON placeholder)
+- feat: pnpm dlx / yarn dlx / bun x / npx — unified dlx runner via esm.sh
+- feat: runtime observability — window.__debug.node.runtime.history tracks node→deno→bun switches
+- feat: window.__debug.node.pm — pm command history (200 entries, cwd, ts, args)
+- feat: Deno.stdin/stdout/stderr with ReadableStream/WritableStream surfaces
+- feat: Bun.stdin/stdout/stderr .stream()/.text()/.writer() API
+- feat: tab completion includes pnpm/yarn/bun/deno/npx/corepack
+- feat: pnpm layout scaffold (.pnpm/<name>@<ver>/node_modules/<name> + symlinks) via shell-pm-layout.js
+
+## [unreleased] 2026-04-20 node parity pass 8 — Deno/Bun/pnpm/yarn + POSIX
+- feat: runtime detection (Deno, Bun, Node, browser) with capability flags
+- feat: Deno global namespace — readTextFile/writeTextFile/mkdir/remove/stat/serve/Command/permissions/env
+- feat: Bun global namespace — file/write/serve/spawn/shell(\`\`)/hash/password/TOML/nanoseconds/deepEquals
+- feat: package manager dispatcher — auto-detects bun.lock/pnpm-lock.yaml/yarn.lock/package-lock.json + packageManager field
+- feat: pm install/add/remove/run/ls/init/task unified across npm/pnpm/yarn/bun
+- feat: deno task, deno.json/jsonc parsing, bunfig.toml parser, workspaces enumeration hooks
+- feat: jsr: and npm: specifier rewriting to esm.sh
+- feat: TypeScript direct execution — .ts/.tsx strip via regex (sucrase lazy-loaded)
+- feat: shebang dispatch — #!/usr/bin/env deno|bun|node sets matching globals
+- feat: corepack stub (no-op)
+- feat: POSIX symlinks via sentinel entries — symlinkSync/readlinkSync/lstatSync/realpathSync with ELOOP at 40 hops
+- feat: hard links + inode refcounting — linkSync, stat.nlink, stat.ino
+- feat: file mode bits — chmodSync, S_IFREG/S_IFDIR/S_IFLNK/S_IFIFO constants
+- feat: file descriptors — openSync/closeSync/readSync/writeSync/fstatSync/ftruncate
+- feat: process.umask/cwd/chdir
+- feat: mkdtempSync, cpSync(recursive), fs.mkfifoSync stub
+- feat: Stats with isFile/isDirectory/isSymbolicLink/isFIFO, atime/mtime/ctime/birthtime Dates
+
+## [unreleased] 2026-04-20 node parity pass 7 — Firefox maximization + polyfills
+- feat: browser detection (vendor, version, 10+ capabilities) + window.__debug.node.polyfills registry
+- feat: OPFS-backed fs.promises when available — real persistence (readFile/writeFile/mkdir/rm/stat/list) via SyncAccessHandle in worker, IDB fallback
+- feat: brotli polyfill via brotli-wasm (compressSync/decompressSync + Transform streams)
+- feat: Error.prepareStackTrace source-map integration via source-map-js — original filenames/lines when process.sourceMapsEnabled
+- feat: net.Socket/tls.connect real polyfill via WebSocket-backed TCP tunnel (window.__plugkit_tcp_relay)
+- feat: dgram.Socket polyfill via WebSocket-wrapped datagrams (window.__plugkit_udp_relay)
+- feat: inspector.open() real CDP endpoint via postMessage channel (Runtime.evaluate/Debugger.enable/Profiler.*)
+- feat: v8 CPU profiler backed by PerformanceObserver (CPUProfile.startProfiling/stopProfiling)
+- feat: v8.writeHeapSnapshot — minimal valid V8 heap snapshot JSON format, Chrome DevTools importable
+- feat: X509Certificate sync access via crypto.preloadX509()
+- feat: vm cross-realm structuredClone boundary — Array/Object instanceof works across iframe
+- feat: cluster module real impl via BroadcastChannel (fork/isMaster/worker.send/'message')
+- feat: CompressionStream native gzip/deflate preferred over fflate when available
+- feat: WebCodecs exposed as 'codecs' module (VideoEncoder/AudioEncoder/etc)
+- feat: web-push module (pushManager.subscribe/getSubscription)
+- feat: process.storage.estimate/persist/persisted + process.storageBuckets
+- feat: FileSystemObserver integration for real fs.watch events on OPFS
+- feat: Firefox Worker module-type compat shim
+- feat: observability panel window.__debug.node.polyfills shows backing (native|wasm|fallback) per feature
+
+## [unreleased] 2026-04-20 node parity pass 6 — 23 PRD items shipped
+- feat: crypto ECDSA PEM sign/verify (P-256/P-384/P-521)
+- feat: crypto.hkdf/hkdfAsync via webcrypto deriveBits
+- feat: crypto.createECDH (prime256v1/secp384r1/secp521r1) shared-secret derivation
+- feat: KeyObject (createPrivateKey/createPublicKey) + X509Certificate via @peculiar/x509
+- feat: streaming zlib (createGzip/Gunzip/Deflate/Inflate) via fflate class API
+- feat: vm module (runInThisContext/runInNewContext/runInContext via iframe)
+- feat: module.register() ESM loader hooks (resolve/load pipeline)
+- feat: http2.connect fetch-backed ClientHttp2Session
+- feat: WASI real impl via @bjorn3/browser_wasi_shim
+- feat: diagnostics_channel real pub/sub + tracingChannel
+- feat: trace_events real recorder with event buffer
+- feat: worker_threads.Worker backed by real Web Worker + Blob URL
+- feat: child_process exec/spawn via WebContainer when available
+- feat: fs.watch real events via IDB snapshot diff polling
+- feat: REPL command handling (.clear/.exit/.help/.load/.save/.editor) + multi-line balance detection
+- feat: Buffer pool (Buffer.poolSize=8192) for small allocUnsafe
+- feat: process.binding('util') selective exposure, execArgv, features
+- feat: process.memoryUsage from performance.memory
+- feat: http.Agent / https.Agent real fetch pool with maxSockets
+- feat: Error.prepareStackTrace V8-hook via Object.defineProperty on Error.prototype.stack
+- feat: window.__debug.node registry for runtime observability
+- feat: net/tls stubs with clearer error messages
+
+## [unreleased] 2026-04-20 node parity pass 5
+- feat: zlib sync (fflate via esm.sh /es2022 bundle) — gzipSync/gunzipSync/deflateSync/inflateSync
+- feat: crypto.sign/verify + createSign/createVerify with PEM key import (RSA-SHA256 via webcrypto pkcs8/spki)
+- feat: module resolution — full conditional exports (node/import/require/default/browser), subpath patterns (*), #internal imports map, type:module ESM detection
+- feat: util.inspect — BigInt 'n' suffix, Symbol keys, colors:true ANSI, showHidden for non-enumerable
+- feat: Error.captureStackTrace polyfill, process.execArgv from NODE_OPTIONS, --enable-source-maps flag, expanded allowedNodeEnvironmentFlags, process.features
+
+## [unreleased] 2026-04-20 node parity pass 3
+- feat: crypto sha1/sha512/md5 pure-JS + hmac (RFC 2104) + pbkdf2Sync + randomBytes via Web Crypto — all byte-for-byte match with real node
+- feat: util.inspect circular refs use node format '<ref *N> { ... [Circular *N] }' exactly
+- feat: package.json exports field resolution + node_modules walk-up parent dirs
+- feat: require('module') with builtinModules, createRequire, _resolveFilename, Module, wrap, wrapper
+- feat: require throws Error with .code='MODULE_NOT_FOUND' and requireStack
+- feat: fs.promises mirrors sync API; fs.watch FSWatcher stub
+- feat: net/dgram throw descriptive errors on use (not silent stubs)
+- feat: worker_threads throws descriptive; execSync throws with explanation
+- feat: process.stdin.setRawMode no-op (inquirer compatibility)
+- feat: globalThis.process/Buffer set during eval (real node globals)
+- feat: __filename/__dirname injected into ESM preamble
+- feat: REPL eval loop — input → try-expr-then-stmt → util.inspect result; .exit/.help/.clear commands; prompt '> ' during REPL
+- new: shell-node-crypto.js (sha1/256/512/md5/hmac/pbkdf2), shell-node-resolve.js (exports/walk-up/module/fs.promises/net/dgram/worker_threads stubs)
+
+## [unreleased] 2026-04-20 node parity pass 2
+- feat: util.inspect matches node format (braces-with-spaces, Map(N){k=>v}, arrays, circular, <Buffer ...>)
+- feat: console.log/info/warn/error use util.format (printf-style %s/%d/%o)
+- feat: crypto.createHash pure-JS sha256 — matches node hex output byte-for-byte
+- feat: Buffer.write/compare/equals/indexOf/includes/subarray/readUIntXX/Buffer.compare/allocUnsafe
+- feat: fs.rmSync/rmdirSync/accessSync/realpathSync
+- feat: child_process.spawn/exec route through shell runPipeline, EventEmitter-style stdout/stderr/exit
+- feat: http.request/http.get via fetch, return IncomingMessage-style with statusCode/headers/on(data,end)
+- feat: process.execPath/argv0/title/memoryUsage/uptime/getuid/umask/release; env defaults PATH/HOME/USER/SHELL/TERM/LANG
+- feat: ESM detection — code with import/export wrapped in Blob URL + dynamic import
+- feat: unhandledrejection → lastExitCode=1 + node-style stack
+- feat: stack trace trailer "Node.js v23.10.0" on error
+- feat: .env loading at script start
+- feat: node: prefixed specifiers (node:fs, node:path, etc.)
+- feat: zlib.gzip/gunzip via pako (async, auto-loaded from esm.sh)
+- new: shell-node-stdlib.js (util/crypto/zlib), shell-node-io.js (cp/http/proc env/ESM/stack/dotenv)
+
+## [unreleased] 2026-04-20 node/npm CLI parity
+- feat: node reports v23.10.0 + full process.versions map (27 fields, matches real CLI)
+- feat: npm reports 10.9.2, npm_lifecycle_event/npm_package_name/npm_package_version env injection, pre/post<script> lifecycle hooks
+- feat: process.exit(n) throws NodeExit, propagates to ctx.lastExitCode
+- feat: script errors set lastExitCode=1 with stack trace display
+- feat: node reads stdin via pipe (echo x | node script.js) through proc.stdin._feed
+- feat: require.resolve + require.cache for module introspection
+- feat: npx builtin (npx cowsay hi)
+- feat: node -h/--help, node -p fixed (stdout.write not console.log)
+- refactor: extracted runNode + runNpmResult into shell-exec.js (shell.js stays <200L)
+
+## [unreleased] 2026-04-18 browser validation
+- fix: require('express') returned instance not factory (MODULES wrapper called createExpress twice)
+- fix: SW registration non-blocking — shell boots immediately, SW registers in background
+- fix: splitTopLevel sep semantics — sep is preceding operator not following, fixes && || chain evaluation
+- fix: lastExitCode-based lastOk — false builtin sets exit code 1 without throwing
+
+## [unreleased] 2026-04-18
+- feat: full CLI overhaul — shell-parser.js (tokenize/expand/parsePipes/splitTopLevel/parseRedirects), shell-builtins.js (POSIX builtins: ls -la, rm -r, cp -r, grep -inH, cd -, history), shell-npm.js (install/uninstall/ls/run/init with package.json read/write), shell.js refactored to use modules; IDB_KEY bumped to thebird_fs_v4; defaults.json updated with all new files
 ## [Unreleased]
 
+### Added
+- `docs/defaults.json`: bundled real project files (package.json, index.js, server.js, lib/*, lib/providers/*) so browser jsh has a working thebird source tree on boot — user can immediately run `npm install && node server.js` without needing to write files first
+- `docs/shell.js`: `npm install` with no args reads cwd `package.json` dependencies + peerDependencies, installs all of them (multi-pkg via single command)
+- `docs/shell-node.js`: `preloadAsyncPkgs` now walks the full require graph from entry file (BFS through relative requires) so transitive external package deps get loaded before sync require runs. Previously only scanned top-level code — server.js → ./index.js → @google/genai chain failed
+- `docs/index.html`: callExpressRoute response object supports both Node http-style (writeHead/write/end/setHeader) and express-style (send/json/status). Request object now has `url`, `method`, async iterator for empty body — matches what `http.createServer` handlers expect
+
+### Changed
+- `docs/terminal.js`: IDB_KEY bumped `thebird_fs_v2` → `thebird_fs_v3` to force refresh of browser fs cache (users with stale idb will re-fetch defaults.json with the real project files)
+
+### Added (prev)
+- `docs/shell-node.js`: `http` and `https` core builtins — `http.createServer(handler)` registers wildcard route in `window.__debug.shell.httpHandlers[port]` (same mechanism as express.listen), so `node server.js` now works for servers that use raw `require('http')`
+- `docs/shell-node.js`: `buffer`, `child_process`, `net`, `zlib`, `assert` builtin stubs so common Node scripts don't die on trivial requires
+- `docs/shell-node.js`: `preloadAsyncPkgs(code)` scans source for `require('pkg')` calls, resolves each via dynamic `import(esm.sh/pkg)`, populates `pkgCache`. Synchronous `require()` then reads from cache — bridges Node CJS semantics to browser ESM loading
+- `docs/shell-node-modules.js`: new file holding `createExpress`, `createHttp`, `createSqlite`, `createConsole`, `createProcess` factories (split out to keep shell-node.js under 200 lines)
+
+### Changed
+- `docs/shell.js`: `npm install` supports multiple packages per invocation; writes an `await import(...)` stub to `node_modules/<pkg>/index.js` as a marker, real resolution happens via `preloadAsyncPkgs` in nodeEval
+- `docs/shell-node.js`: external (non-relative, non-builtin) require throws clear `Cannot find module: X (run: npm install X)` instead of generic error
+- `docs/shell-node-modules.js` createExpress: routes now store `{ path, fn }` where `fn` runs full middleware chain via `runFns`, matching `index.html` callExpressRoute's `match.fn(req, res)` expectation (was previously `{ path, fns }` which broke route invocation)
+
+### Fixed
+- `docs/shell.js`: httpHandlers now returned on shell object instead of assigned to window.__debug.shell separately — terminal.js overwrote the debug object (which had httpHandlers) with the createShell() return value (which had none), making express routes invisible to index.html callExpressRoute(). Fix: remove internal window.__debug.shell assignment, include httpHandlers and all debug getters on the returned shell object so terminal.js assignment preserves the reference
+- `test.js`: consolidate e2e-test.js coverage into test.js (express routing e2e + httpHandlers fix regression); delete e2e-test.js to enforce single-test-file policy
+
+### Fixed
+- `docs/app.js`: Normalize message content format to Anthropic array structure `[{ type: 'text', text: '...' }]` to prevent double-conversion in streamGemini/streamOpenAI (was sending string content)
+- `docs/agent-chat.js`: Add lastError tracking in window.__debug.agent for error visibility and debugging
+- `docs/shell.js`: Expose onPreviewWrite callback on returned shell object for preview refresh integration
+- `docs/terminal.js`: Add shell reference to window.__debug for tool access; reduce preview refresh debounce 5s → 1s for quicker feedback
+- `docs/preview-sw.js`: Add missing service worker for preview iframe routing (handle EXPRESS_REQUEST messages from main thread)
+- `test.js`: Create integration test suite validating bootstrap, defaults.json, tools, errors, observability structures
+
+### Changed
+- `docs/defaults.json`: Split and optimized for Git constraints — reduced from 154.83 MB to 1.23 MB by including only 16 critical bootstrap files (app.js, agent-chat.js, terminal.js, shell.js, vendor/xterm-bundle.js, vendor/xstate.js, vendor/ui-libs.js, vendor/thebird-browser.js, etc.). Excludes large unused vendors (winterjs.wasm 46 MB, wasmer_js_bg.wasm 6.3 MB, rippleui.css 4.5 MB, sql-wasm.wasm 0.6 MB, acp-sdk.js 0.6 MB) not required for WebContainer bootstrap path.
+- `docs/terminal.js`: Updated xterm.js theme with green foreground (#33ff33) to match Claude Code TUI aesthetic. Maintains AAA contrast ratio (14.61:1 on black background).
+
 ### Added
 - `docs/node-builtins.js`: Full Node.js module polyfills — path, fs (IDB-backed), events (EventEmitter), url, querystring, Buffer class with encoding support
 - `docs/shell-node.js`: Enhanced Node env — relative require, JSON require, per-file __dirname, process.stdout/stderr/nextTick/argv/hrtime, console.dir/table/time/assert/count, express with route params/middleware/static/json, os/util/crypto/stream modules
@@ -95,3 +303,12 @@
 ### Added
 - `docs/index.html`: Preview tab with iframe (`#preview-frame`), `switchTab` extended to dispatch over `['chat','term','preview']`.
 - `docs/terminal.js`: DEFAULT_FILES now includes `server.js` (HTTP server on port 3000, JSON status endpoint) and updated `index.js` (loads @anthropic-ai/sdk, hits server). Server auto-starts after `npm install`. `container.on('server-ready')` wires iframe src + `window.__debug.previewUrl`. Shell upgraded from `sh` loop to `jsh` with PTY resize. `window.__debug.srv` and `window.__debug.shell` live.
+
+
+## shell predictability fixes (2026-04-18)
+- Pipe stdin passthrough: grep/sed detect piped content as first arg (stdinFirst pattern)
+- Tokenizer: preserves \\n inside double-quotes so echo -e works correctly
+- $? expansion, $() command substitution, inline var assignment (X=val cmd)
+- echo -e with \\n \\t escape sequences
+- New builtins: sed, sort, uniq, tr
+- shell-builtins.js split into shell-builtins-text.js (both under 200L)

package/CLAUDE.md

@@ -134,6 +134,20 @@ Run examples against real Gemini API to validate message translation.
 - Tool parameter types must be lowercase for Gemini API — `object`, `string`, `number` not `OBJECT`, `STRING`, `NUMBER`. Uppercase types fail schema validation.
 - agentGenerate passes raw Anthropic-format messages to streamGemini internally, which calls convertMessages. Do NOT pre-convert in app.js — double-conversion breaks tool schemas.
 - Anthropic format IS the canonical message format — do NOT add an intermediate transformation layer. Direct translation to provider-native formats is cleaner than another abstraction level.
+- **shell.js httpHandlers visibility chain**: shell.js creates `httpHandlers = {}` and returns it on the shell object. terminal.js assigns `window.__debug.shell = shell`. shell-node.js mutates `window.__debug.shell.httpHandlers[port]` to register routes. index.html reads from `window.__debug.shell.httpHandlers`. All four modules reference the same object; httpHandlers MUST be returned on the shell object or the chain breaks.
+
+- **Shell builtin pipe stdin detection**: When a builtin receives piped input (e.g. `echo hello | grep hello`), the pipe buffer arrives as `args[0]`. Builtins with mandatory leading args (grep: pattern, sed: expression) must detect `positional[0].includes('\n')` BEFORE extracting those args, then shift stdin off. `cat`/`wc`/`sort`/`uniq` use the same check. Single-line piped content always has `\n` because `echo` appends `\r\n`.
+- **Tokenizer double-quote escape sequences**: Inside double-quotes, only `"`, `\`, `` ` ``, `$` are valid escape sequences. `\n` in double-quotes must be preserved as literal backslash-n for `echo -e` to process. Fix: when escape=true and quote==='"', re-emit backslash before char if char not in `"\\\`$`.- **Test policy**: Single test.js file (max 139L per constraint). e2e-test.js deleted. Validation via live API calls with exec:nodejs (browser automation unavailable in this environment).
+- **ACP protocolVersion is a number**: Kilo Code's `kilo acp` server rejects string `'0.1'` with `-32602 Invalid params: expected number`. Use integer `1`. acp-stream.js:73 fixed.
+- **Kilo ACP over WebSocket bridge (Windows)**: To consume Kilo Code as the page's ACP provider, bridge its stdio to WS. The npm shim `kilo.cmd` uses `stdio: "inherit"` which detaches from the bridge's pipes, so invoke the platform binary directly: `C:\Users\user\AppData\Roaming\npm\node_modules\@kilocode\cli\node_modules\@kilocode\cli-windows-x64\bin\kilo.exe acp`. Bridge command: `bunx -y stdio-to-ws "<abs-path>\kilo.exe acp" --port 3015`. Bunx cold start is 15–25s; wait for `[stdio-to-ws] WebSocket server listening`. Validated: initialize → result with `protocolVersion: 1, agentInfo: { name: 'Kilo', version: '7.2.0' }, authMethods: [{ id: 'kilo-login' }]`. Actual prompts require `kilo auth login` first.
+- **Kilo ACP `session/new` requires `mcpServers` array**: Kilo's zod schema for `session/new` params requires `mcpServers` (array). Omitting it returns `-32602 Invalid params: expected array, received undefined`. Fix: pass `{ cwd, mcpServers: [] }` — see docs/acp-stream.js:74.
+- **Kilo ACP `session/prompt` shape**: Kilo's schema is `{ sessionId, prompt: [...content blocks] }` — NOT `{ sessionId, message: { role, content: [...] } }`. Wrong shape returns `-32602 Invalid params: prompt expected array, received undefined`. Fix: send `prompt: [{ type:'text', text }]` directly — see docs/acp-stream.js:80.
+- **Kilo ACP `session/update` notification shape**: Kilo emits `{ params: { sessionId, update: { sessionUpdate:'agent_message_chunk', content:{ type:'text', text } } } }` — singular `update`, and the discriminator is `sessionUpdate` not `type`. Iterating `updates[]` (plural) with `item.type==='message_chunk'` never matches real Kilo output. Fix: normalize to `update ? [update] : (updates||[])` and match `sessionUpdate==='agent_message_chunk'` with `content.type==='text'`. See docs/acp-stream.js:93.
+- **Kilo ACP `kilo/*` free models require `kilo auth login`**: Built-in free routes (`kilo/x-ai/grok-code-fast-1:optimized:free`, `kilo/openrouter/free`, etc.) only work after interactive `kilo auth login` stores a credential in `~/.local/share/kilo/auth.json`. `kilo auth list` exposes `OPENAI_API_KEY`/`GEMINI_API_KEY` env vars as alternate auth sources, but those only apply to direct-provider models (`openai/*`, `google/*`) — not to `kilo/*` routes. With an invalid/missing GEMINI_API_KEY, `session/prompt` returns `stopReason:'end_turn'` with zero tokens and no text chunks — silent no-op, not an error. Any real end-to-end prompt validation requires a valid provider key or an authenticated Kilo account.
+- **Kilo ACP `session/set_model` is supported**: Call `session/set_model` with `{ sessionId, modelId }` between `session/new` and `session/prompt` to override the default (`kilo/x-ai/grok-code-fast-1:optimized:free`). Validated with `modelId:'google/gemini-2.5-flash'` — response includes `_meta.opencode.modelId` confirming the switch.
+- **Kilo free models DO work non-interactively without `kilo auth login`**: Earlier assumption was wrong. The bundled `@kilocode/kilo-gateway` provider (`providerID:'kilo'`, source:'custom', env:[KILO_API_KEY]) serves free routes (`x-ai/grok-code-fast-1:optimized:free`, `openrouter/free`, `kilo-auto/free`, etc.) anonymously over the built-in HTTP server. Witnessed via `kilo serve --port N` + `POST /session` + `POST /session/:id/message` with `{ parts:[{type:'text',text}], modelID:'x-ai/grok-code-fast-1:optimized:free', providerID:'kilo' }` → `status 200`, `finish:stop`, real text output in ~5s. Cost: 0. Reference: C:\dev\agentgui\lib\claude-runner-acp.js shows the identical flow working over ACP stdio — key detail is a 5-min (300000ms) timeout because the gm agent plugin (globally installed at `C:\Users\user\.config\kilo\plugins\gm-kilo.mjs`) does git ops on first prompt. gm system prompt is always injected (~18-19k input tokens regardless of agent param).
+- **Kilo agent plugin overrides requested model**: Specifying `modelID:'x-ai/grok-code-fast-1:optimized:free'` on a prompt often gets silently routed to `openrouter/elephant-alpha` because the `gm` agent (auto-selected when `default_agent:'gm'` is in `opencode.json`) has its own model picker. Check `info.modelID` in the response to see what actually ran. To bypass gm routing, delete or rename `C:\Users\user\.config\kilo\opencode.json` and `kilocode.json` which set `default_agent:'gm'`.
+- **Kilo `run` subcommand hangs, `serve` + HTTP works**: The `kilo run` CLI path currently blocks indefinitely after config load (even at DEBUG log level, no provider activity logged). Workaround: use `kilo serve --port N` and POST to `/session/:id/message` — same bundled provider, same free models, responds in seconds. Also applies to ACP stdio: `kilo acp` works but has long cold-start through the gm plugin, so any bridge must allow at least 5 minutes per prompt.
 
 ## Error Architecture
 
@@ -172,6 +186,8 @@ Run examples against real Gemini API to validate message translation.
 - `examples/`: Working examples using Anthropic SDK format
 - `wasi/cli.ts`: Deno streaming CLI — `deno run --allow-net --allow-env wasi/cli.ts [--model M] [--system S] <prompt>`
 - `deno.json`: tasks `cli` (run) and `cli:compile` (→ `dist/thebird` binary)
+- `docs/shell-builtins.js`: FS/IO builtins (ls/cat/echo/cd/mkdir/rm/cp/mv/touch/head/tail/wc) — imports makeTextBuiltins
+- `docs/shell-builtins-text.js`: Text-processing builtins (grep/sed/sort/uniq/tr) + env/export/clear/history/which/exit/true/false/printenv
 
 ## WebContainer Terminal in docs/
 

package/docs/agent-chat.js

@@ -1,5 +1,5 @@
 import { streamGemini, streamOpenAI } from './vendor/thebird-browser.js';
-import { streamACP } from './acp-stream.js';
+import { streamKiloHTTP } from './kilo-http-stream.js';
 
 function idbRead(path) {
   const snap = window.__debug.idbSnapshot;
@@ -91,8 +91,8 @@ function buildStream(provider) {
   if (provider.type === 'gemini') {
     return streamGemini({ model: provider.model, messages: provider.messages, tools: TOOLS, apiKey: provider.apiKey, maxOutputTokens: 8192 }).fullStream;
   }
-  if (provider.type === 'acp') {
-    return streamACP({ url: provider.baseUrl, model: provider.model, messages: provider.messages, tools: TOOLS, maxOutputTokens: 8192 });
+  if (provider.type === 'kilo') {
+    return streamKiloHTTP({ url: provider.baseUrl, model: provider.model, messages: provider.messages });
   }
   const url = (provider.baseUrl || '').replace(/\/$/, '') + '/chat/completions';
   return streamOpenAI({ url, apiKey: provider.apiKey, messages: provider.messages, model: provider.model, tools: TOOLS, maxOutputTokens: 8192 });
@@ -100,7 +100,7 @@ function buildStream(provider) {
 
 export async function agentGenerate(provider, messages, onChunk, onTool) {
   Object.assign(window.__debug = window.__debug || {}, {
-    agent: { provider: provider.type, model: provider.model, active: true, lastTool: null },
+    agent: { provider: provider.type, model: provider.model, active: true, lastTool: null, lastError: null },
   });
   try {
     for await (const ev of buildStream({ ...provider, messages })) {
@@ -110,6 +110,9 @@ export async function agentGenerate(provider, messages, onChunk, onTool) {
         onTool(ev.toolName, ev.args);
       } else if (ev.type === 'error') throw ev.error;
     }
+  } catch (e) {
+    window.__debug.agent.lastError = { message: e.message, stack: e.stack, timestamp: Date.now() };
+    throw e;
   } finally {
     window.__debug.agent.active = false;
   }

package/docs/app.js

@@ -11,7 +11,7 @@ const PROVIDERS = {
   mistral:  { label: 'Mistral',         baseUrl: 'https://api.mistral.ai/v1',                        keyPlaceholder: 'MISTRAL_API_KEY', models: ['mistral-large-latest', 'mistral-small-latest', 'codestral-latest'] },
   deepseek: { label: 'DeepSeek',        baseUrl: 'https://api.deepseek.com/v1',                      keyPlaceholder: 'DEEPSEEK_API_KEY', models: ['deepseek-chat', 'deepseek-reasoner'] },
   cerebras: { label: 'Cerebras',        baseUrl: 'https://api.cerebras.ai/v1',                      keyPlaceholder: 'CEREBRAS_API_KEY', models: ['gpt-oss-120b', 'llama3.1-8b'] },
-  acp:      { label: 'ACP Agent',             baseUrl: 'ws://localhost:3000',                       keyPlaceholder: '(no key needed)', models: ['default'] },
+  kilo:     { label: 'Kilo Code',              baseUrl: 'http://localhost:4780',                     keyPlaceholder: '(no key needed)', models: ['x-ai/grok-code-fast-1:optimized:free', 'openrouter/free', 'kilo-auto/free'] },
   custom:   { label: 'Custom (OpenAI-compat)', baseUrl: '',                                          keyPlaceholder: 'API_KEY',        models: [] },
 };
 
@@ -45,7 +45,8 @@ async function fetchModels(providerType, baseUrl, apiKey) {
 class BirdChat extends HTMLElement {
   constructor() {
     super();
-    const savedProvider = localStorage.getItem('provider_type') || 'gemini';
+    const rawSaved = localStorage.getItem('provider_type') || 'gemini';
+    const savedProvider = PROVIDERS[rawSaved] ? rawSaved : (rawSaved === 'acp' || rawSaved === 'kilohttp' ? 'kilo' : 'gemini');
     const savedBaseUrl = localStorage.getItem('provider_base_url') || PROVIDERS[savedProvider]?.baseUrl || '';
     this.state = {
       messages: [], streaming: false,
@@ -107,11 +108,11 @@ class BirdChat extends HTMLElement {
         <div class="tui-toolbar">
           <label>provider:</label>
           <select class="tui-select" onchange=${e => this.setProvider(e.target.value)}>${provOpts}</select>
-          ${(providerType === 'custom' || providerType === 'acp') ? html`
+          ${(providerType === 'custom' || providerType === 'kilo') ? html`
             <input type="text" class="tui-input" style="flex:1;min-width:140px"
-              placeholder=${providerType === 'acp' ? 'ws://localhost:3000' : 'https://your-endpoint/v1'} value=${baseUrl}
+              placeholder=${providerType === 'kilo' ? 'http://localhost:4780' : 'https://your-endpoint/v1'} value=${baseUrl}
               onchange=${e => { localStorage.setItem('provider_base_url', e.target.value); this.setState({ baseUrl: e.target.value }); }} />` : ''}
-          ${providerType !== 'acp' ? html`<input id="api-key-input" type="password" class="tui-input" style="flex:1;min-width:120px"
+          ${providerType !== 'kilo' ? html`<input id="api-key-input" type="password" class="tui-input" style="flex:1;min-width:120px"
             placeholder=${provDef.keyPlaceholder} value=${apiKey}
             onchange=${e => {
               const v = e.target.value.trim();
@@ -151,12 +152,14 @@ class BirdChat extends HTMLElement {
     const text = input?.value.trim();
     if (!text || this.state.streaming) return;
     const { apiKey, model, providerType, baseUrl } = this.state;
-    if (!apiKey && providerType !== 'acp') { this.setState({ status: 'Enter an API key above.' }); return; }
+    if (!apiKey && providerType !== 'kilo') { this.setState({ status: 'Enter an API key above.' }); return; }
     input.value = '';
     input.style.height = 'auto';
-    const messages = [...this.state.messages, { role: 'user', content: text }];
-    this.setState({ messages, streaming: true, status: '', streamingText: '' });
-    const provider = { type: providerType, apiKey, model, baseUrl: providerType === 'gemini' ? '' : baseUrl };
+    const normalizedMessages = [...this.state.messages, { role: 'user', content: text }].map(m => ({
+      ...m, content: typeof m.content === 'string' ? [{ type: 'text', text: m.content }] : m.content
+    }));
+    this.setState({ messages: normalizedMessages, streaming: true, status: '', streamingText: '' });
+    const provider = { type: providerType, apiKey, model, baseUrl: providerType === 'gemini' ? '' : baseUrl, url: baseUrl };
     try {
       let full = '';
       const streamEl = document.createElement('div');
@@ -169,12 +172,12 @@ class BirdChat extends HTMLElement {
       wrap.appendChild(cursor);
       const list = this.querySelector('#msg-list');
       if (list) list.appendChild(wrap);
-      await agentGenerate(provider, messages,
+      await agentGenerate(provider, normalizedMessages,
         chunk => { full += chunk; streamEl.textContent = full; const l = this.querySelector('#msg-list'); if (l) l.scrollTop = l.scrollHeight; },
         (name, args) => { full += `\n[tool: ${name}(${JSON.stringify(args)})]\n`; streamEl.textContent = full; }
       );
       wrap.remove();
-      this.setState({ messages: [...messages, { role: 'assistant', content: full || '(empty)' }], streaming: false, streamingText: '' });
+      this.setState({ messages: [...normalizedMessages, { role: 'assistant', content: [{ type: 'text', text: full || '(empty)' }] }], streaming: false, streamingText: '' });
       const l2 = this.querySelector('#msg-list');
       if (l2) l2.scrollTop = l2.scrollHeight;
     } catch (err) {