jeo-code 0.7.31 → 0.7.33

package/CHANGELOG.md

@@ -6,6 +6,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 The README mirrors the latest 5 entries — regenerate with `bun run changelog:sync`.
 
+## [0.7.33] - 2026-07-04
+_Adds `browser` — headless Chromium automation (gjc `browser` parity) — completing the gjc tool-surface parity pass started in 0.7.32._
+
+### Added
+- **`browser` — headless Chromium automation via Playwright (gjc `browser` parity, headless-only for v1 — no existing-profile/CDP-endpoint/Electron attach, no stealth patches).** `browser-session.ts` keeps one shared browser instance alive across calls with named tabs reused ("open once, act many times"); `browser-tab.ts` provides `observe()`-first helpers (tags interactive elements with stable numeric ids instead of a raw DOM dump or a screenshot) plus `click`/`type`/`fill`/`select`/`press`/`scroll`/`goto`/`back`/`extract`/`screenshot`/`evaluate`. The `browser` tool exposes `open`/`close`/`run`/`act`: `act` runs structured steps (navigate/click/type/fill/select/press/scroll/back/wait/observe/extract/screenshot) addressed by numeric `id` (from a prior `observe`) or CSS selector; `run` executes an async-function body with `page`/`browser`/`tab`/`display`/`assert`/`wait` in scope for anything the structured verbs don't cover. Mutating (drives a real browser, `run` executes arbitrary host JS) — excluded from read-only subagent roles. `playwright` moves from `devDependencies` to `dependencies` (it was already bundled for jeo-code's own test suite, so this reuses it rather than adding a second browser-automation engine).
+
+### Verified
+- `bun run typecheck` clean; full suite green.
+- New coverage: `test/browser-tool.test.ts` (open/act round-trip against real headless Chromium — observe → type → click → extract, `run` with display/assert, screenshot-to-file, close/close-all, and error-path guards) with `test.skipIf` fallbacks for environments without the Chromium binary downloaded; `test/subagent-toolset-gating.test.ts` extended to assert `browser` is excluded from every read-only role.
+
+## [0.7.32] - 2026-07-03
+_gjc tool-surface parity — ast_grep/ast_edit, lsp/lsp_rename, debug, irc, job, and goal tools — plus a `launch.ts` slash-command refactor and four agent-loop guardrail hardenings (destructive-bash denylist, spawn-gate justification quality check, done-verification abuse guard, and a blind unanchored line-range-edit guard)._
+
+### Added
+- **`ast_grep`/`ast_edit` — structural TypeScript/JavaScript search and codemods (gjc parity, pure-TS, not the native binary, not multi-language).** `ast-match.ts` implements the `$NAME`/`$_`/`$$$NAME`/`$$$` metavariable matcher over the `typescript` compiler API's AST; `ast-file-scan.ts` shares gitignore/ignored-dir-aware file targeting between them. `ast_grep` is read-only (safe for every subagent role); `ast_edit` is mutating (writes via `writeTool`, excluded from read-only roles).
+- **`lsp`/`lsp_rename` — TypeScript/JavaScript language-service queries (gjc `lsp` parity, in-process `ts.LanguageService`, not a real LSP server).** `ts-language-service.ts` caches one language service per project root with tsconfig-aware root-file discovery, a whole-tree fallback, and stat-based live file-version tracking. `lsp` covers definition/references/hover/symbols/diagnostics and is read-only; cross-file rename is the separate mutating `lsp_rename` tool so the read-only-role toolset filter (which gates by tool name) can't be bypassed by a rename action hidden inside a nominally read-only call.
+- **`debug` — Node.js debugging via an in-process CDP (V8 Inspector Protocol) client (gjc `debug` parity, Node.js only — not Bun, whose inspector speaks a different WebKit dialect).** `debug-session.ts` drives a spawned `node --inspect-brk` process (one active session, singleton); the tool exposes launch/set_breakpoint/remove_breakpoint/continue/step_over/step_in/step_out/pause/evaluate/stack_trace/scopes/variables/threads/output/terminate. Mutating (runs arbitrary code as a real process) — excluded from read-only subagent roles the same way `bash`/`computer` are.
+- **`irc` — parent-to-subagent live peer messaging for DETACHED subagents (gjc `irc` parity).** Built entirely on the existing `SubagentRegistry.steer()` delivery path (no new state store): `list` shows currently running detached subagents as peers, `send` delivers a message to one peer id or to every running peer (`to:"all"`), picked up before that subagent's next step.
+- **`job` — background shell-process control (gjc `job`/async-bash parity).** `job-registry.ts` tracks real parallel OS processes (not just concurrent JS) with a bounded output buffer; the tool exposes start/list/tail/await (optionally time-bounded)/cancel.
+- **`goal` — lets the model itself set/read/clear the session's natural-language stop condition**, wrapping the existing file-persisted `GoalState` that `/goal` and the per-`done` `verifyGoal` check already use — the model gets the same lever a human typing `/goal` has, not a new state store.
+- **`launch.ts` slash-command handlers extracted into `src/commands/launch/{agents,model,session,system}-slash.ts`**, shrinking the monolithic `launch.ts` by roughly 600 net lines without changing observable `/agents`, `/model`, `/fast`, and session-management command behavior.
+
+### Hardened
+_A guardrail audit of the agent loop, subagent spawn gate, and file-edit tools turned up four places where an existing safety mechanism was either inert or had a bypassable escape hatch. All four are now closed:_
+- **Every `bash` call (main agent and every subagent role, including the otherwise-unconstrained `executor`) now runs through a narrow, hard-coded destructive-command denylist** (`bashDestructiveReason` in `src/agent/tools.ts`): a recursive force-delete whose target normalizes to the filesystem root or home directory (`rm -rf /`, `rm -rf ~`, `sudo rm -Rf /`, chained/env-prefixed variants), fork-bomb patterns, raw disk-device overwrites (`dd ... of=/dev/...`), and raw-device filesystem formats (`mkfs ... /dev/...`) are rejected before the shell ever spawns. Everyday destructive-but-scoped commands (`rm -rf node_modules`, `git reset --hard`, force-push) are untouched — this is a narrow safety net, not a policy filter. The role-scoped `bashAllowedPrefixes` allowlist mechanism (`subagents.ts`) remains available for custom config-declared roles but was never wired to any bundled role; this denylist is the actual protection the bundled `executor` role gets today.
+- **The subagent fan-out spawn-gate's justification check accepted any 20-character string.** `task-tool.ts`'s `MAX_FANOUT` bypass required a `justification` string of length ≥20 with no content check, so `"xxxxxxxxxxxxxxxxxxxx"` or `"asdf asdf asdf asdf"` cleared the gate as easily as a real justification. `isMeaningfulJustification` now additionally rejects single-character/repeated-token padding and requires at least 4 distinct words.
+- **The done-verification pushback's "second `done` always passes" escape hatch could be triggered by resending `done` unchanged with zero intervening work.** `engine.ts` now tracks `sawActionSincePushback`: after the one-time pushback (`done_unverified`/`done_stale_verification`/`done_hook_failing`), a `done` retried with no tool call executed in between is bounced again instead of silently accepted. The escape hatch (intended for docs/config-only changes where verification is genuinely not applicable) still works — it now requires at least one real attempt (even a `read`) before honoring it.
+- **A `≔A..B` line-range replace with no hashline anchors and no prior `read` this session applied completely unverified.** `editTool`'s `staleReadError` only guarded a file the agent had already read; a plain, unanchored range-replace against a file never read this session bypassed both the freshness check and the (optional) anchor check. `editTool` now rejects that specific case — anchored edits, `<<<<<<< SEARCH` blocks (self-verifying via the search text), and insert/append directives (non-destructive) are all unaffected, and the check runs after the existing out-of-bounds validation so an invalid range still reports as invalid rather than being masked by this guard.
+
+### Verified
+- `bun run typecheck` clean; full suite green.
+- New/updated coverage: `test/ast-grep-tool.test.ts`, `test/ast-edit-tool.test.ts`, `test/ast-match.test.ts`, `test/lsp-tool.test.ts`, `test/lsp-rename-tool.test.ts`, `test/ts-language-service.test.ts`, `test/debug-tool.test.ts`, `test/irc-tool.test.ts`, `test/job-tool.test.ts`, `test/goal-tool.test.ts`, `test/subagent-toolset-gating.test.ts`, `test/engine-computer-wiring.test.ts`, `test/launch-oneshot-slash.test.ts` for the new tools/refactor; `test/done-verification-guard.test.ts`, `test/post-turn-feedback.test.ts`, `test/repeat-bounce-and-trim.test.ts`, `test/spawn-gate-lite.test.ts`, `test/edit-freshness.test.ts`, `test/tools-fs.test.ts`, `test/engine-multitool.test.ts` updated/extended for the four guardrail hardenings above.
+
 ## [0.7.31] - 2026-07-03
 _Three-round speed & memory pass across streaming, memory retrieval, and the TUI render loop (O(n²) → O(n) in several hot paths), a deep-interview repeat-question loop guard, and gajae-code managed-tmux launch sizing parity._
 

package/README.ja.md

@@ -55,6 +55,8 @@ bun install -g jeo-code
 jeo --version
 ```
 
+> リネーム前のバージョンからアップグレードしますか? 旧 CLI 名だった `joc` バイナリは `scripts/install.sh` / `scripts/uninstall.sh` が自動的に削除します。手動で削除する場合: `rm -f ~/.local/bin/joc ~/.bun/bin/joc`。
+
 ## クイックスタート
 
 ```bash
@@ -205,11 +207,11 @@ CI は `.github/workflows/npm-publish.yml` で公開します — GitHub リリ
 ## 変更履歴 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.7.33]** (2026-07-04) — Adds `browser` — headless Chromium automation (gjc `browser` parity) — completing the gjc tool-surface parity pass started in 0.7.32.
+- **[0.7.32]** (2026-07-03) — gjc tool-surface parity — ast_grep/ast_edit, lsp/lsp_rename, debug, irc, job, and goal tools — plus a `launch.ts` slash-command refactor and four agent-loop guardrail hardenings (destructive-bash denylist, spawn-gate justification quality check, done-verification abuse guard, and a blind unanchored line-range-edit guard).
 - **[0.7.31]** (2026-07-03) — Three-round speed & memory pass across streaming, memory retrieval, and the TUI render loop (O(n²) → O(n) in several hot paths), a deep-interview repeat-question loop guard, and gajae-code managed-tmux launch sizing parity.
 - **[0.7.30]** (2026-07-02) — GPT/Codex OAuth calls work again, and the 30-minute turn budget now limits no-progress stalls instead of killing genuinely progressing autonomous runs.
 - **[0.7.29]** (2026-07-02) — gajae-code safety-refusal retry parity: Anthropic/OAuth content-classifier refusals no longer end the turn with a fatal "declined to answer" message after the context-reset ladder.
-- **[0.7.28]** (2026-07-02) — gajae-code 0.7.9–0.7.10 OAuth + model-execution parity: generic long rate-limit windows are retried (never fatal), retry waits are abort-cancellable, Codex prompt caching via session correlation, and the Kimi Code device-flow OAuth is completed end-to-end (catalog, gating, discovery, tests).
-- **[0.7.27]** (2026-07-02) — Extended-keyboard decode layer: Esc/Ctrl+C work again on kitty-protocol terminals, Shift+Enter breaks lines on every terminal incl. Windows, row/draft-aware Cmd+←→/↑↓ + Home/End/Ctrl+Home/End, Ctrl+V text-paste fallback. Plus Anthropic 5th-gen omp-parity: catalog-derived output budgets end thinking-vs-reply starvation; refusals fail fast at the transport and the recovery ladder strips replayed thinking blocks.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.ko.md

@@ -55,6 +55,8 @@ bun install -g jeo-code
 jeo --version
 ```
 
+> 이름 변경 이전 버전에서 업그레이드하시나요? 이전 CLI 이름이었던 `joc` 바이너리는 이제 `scripts/install.sh` / `scripts/uninstall.sh`가 자동으로 제거합니다. 수동 제거: `rm -f ~/.local/bin/joc ~/.bun/bin/joc`.
+
 ## 빠른 시작
 
 ```bash
@@ -205,11 +207,11 @@ CI는 `.github/workflows/npm-publish.yml`로 배포합니다 — GitHub 릴리
 ## 변경 이력 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.7.33]** (2026-07-04) — Adds `browser` — headless Chromium automation (gjc `browser` parity) — completing the gjc tool-surface parity pass started in 0.7.32.
+- **[0.7.32]** (2026-07-03) — gjc tool-surface parity — ast_grep/ast_edit, lsp/lsp_rename, debug, irc, job, and goal tools — plus a `launch.ts` slash-command refactor and four agent-loop guardrail hardenings (destructive-bash denylist, spawn-gate justification quality check, done-verification abuse guard, and a blind unanchored line-range-edit guard).
 - **[0.7.31]** (2026-07-03) — Three-round speed & memory pass across streaming, memory retrieval, and the TUI render loop (O(n²) → O(n) in several hot paths), a deep-interview repeat-question loop guard, and gajae-code managed-tmux launch sizing parity.
 - **[0.7.30]** (2026-07-02) — GPT/Codex OAuth calls work again, and the 30-minute turn budget now limits no-progress stalls instead of killing genuinely progressing autonomous runs.
 - **[0.7.29]** (2026-07-02) — gajae-code safety-refusal retry parity: Anthropic/OAuth content-classifier refusals no longer end the turn with a fatal "declined to answer" message after the context-reset ladder.
-- **[0.7.28]** (2026-07-02) — gajae-code 0.7.9–0.7.10 OAuth + model-execution parity: generic long rate-limit windows are retried (never fatal), retry waits are abort-cancellable, Codex prompt caching via session correlation, and the Kimi Code device-flow OAuth is completed end-to-end (catalog, gating, discovery, tests).
-- **[0.7.27]** (2026-07-02) — Extended-keyboard decode layer: Esc/Ctrl+C work again on kitty-protocol terminals, Shift+Enter breaks lines on every terminal incl. Windows, row/draft-aware Cmd+←→/↑↓ + Home/End/Ctrl+Home/End, Ctrl+V text-paste fallback. Plus Anthropic 5th-gen omp-parity: catalog-derived output budgets end thinking-vs-reply starvation; refusals fail fast at the transport and the recovery ladder strips replayed thinking blocks.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.md

@@ -55,6 +55,8 @@ bun install -g jeo-code
 jeo --version
 ```
 
+> Upgrading from a pre-rename install? A stale `joc` binary (this project's old CLI name) is now auto-removed by `scripts/install.sh` / `scripts/uninstall.sh`; to remove it manually: `rm -f ~/.local/bin/joc ~/.bun/bin/joc`.
+
 ## Quick start
 
 ```bash
@@ -232,11 +234,11 @@ Huge thanks to [gajae-code](https://github.com/Yeachan-Heo/gajae-code) for the i
 ## Changelog
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.7.33]** (2026-07-04) — Adds `browser` — headless Chromium automation (gjc `browser` parity) — completing the gjc tool-surface parity pass started in 0.7.32.
+- **[0.7.32]** (2026-07-03) — gjc tool-surface parity — ast_grep/ast_edit, lsp/lsp_rename, debug, irc, job, and goal tools — plus a `launch.ts` slash-command refactor and four agent-loop guardrail hardenings (destructive-bash denylist, spawn-gate justification quality check, done-verification abuse guard, and a blind unanchored line-range-edit guard).
 - **[0.7.31]** (2026-07-03) — Three-round speed & memory pass across streaming, memory retrieval, and the TUI render loop (O(n²) → O(n) in several hot paths), a deep-interview repeat-question loop guard, and gajae-code managed-tmux launch sizing parity.
 - **[0.7.30]** (2026-07-02) — GPT/Codex OAuth calls work again, and the 30-minute turn budget now limits no-progress stalls instead of killing genuinely progressing autonomous runs.
 - **[0.7.29]** (2026-07-02) — gajae-code safety-refusal retry parity: Anthropic/OAuth content-classifier refusals no longer end the turn with a fatal "declined to answer" message after the context-reset ladder.
-- **[0.7.28]** (2026-07-02) — gajae-code 0.7.9–0.7.10 OAuth + model-execution parity: generic long rate-limit windows are retried (never fatal), retry waits are abort-cancellable, Codex prompt caching via session correlation, and the Kimi Code device-flow OAuth is completed end-to-end (catalog, gating, discovery, tests).
-- **[0.7.27]** (2026-07-02) — Extended-keyboard decode layer: Esc/Ctrl+C work again on kitty-protocol terminals, Shift+Enter breaks lines on every terminal incl. Windows, row/draft-aware Cmd+←→/↑↓ + Home/End/Ctrl+Home/End, Ctrl+V text-paste fallback. Plus Anthropic 5th-gen omp-parity: catalog-derived output budgets end thinking-vs-reply starvation; refusals fail fast at the transport and the recovery ladder strips replayed thinking blocks.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.zh.md

@@ -55,6 +55,8 @@ bun install -g jeo-code
 jeo --version
 ```
 
+> 从重命名前的版本升级？旧 CLI 名称 `joc` 的二进制文件现在会被 `scripts/install.sh` / `scripts/uninstall.sh` 自动移除；手动移除: `rm -f ~/.local/bin/joc ~/.bun/bin/joc`。
+
 ## 快速开始
 
 ```bash
@@ -205,11 +207,11 @@ CI 通过 `.github/workflows/npm-publish.yml` 发布 — GitHub 发布 release
 ## 更新日志 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.7.33]** (2026-07-04) — Adds `browser` — headless Chromium automation (gjc `browser` parity) — completing the gjc tool-surface parity pass started in 0.7.32.
+- **[0.7.32]** (2026-07-03) — gjc tool-surface parity — ast_grep/ast_edit, lsp/lsp_rename, debug, irc, job, and goal tools — plus a `launch.ts` slash-command refactor and four agent-loop guardrail hardenings (destructive-bash denylist, spawn-gate justification quality check, done-verification abuse guard, and a blind unanchored line-range-edit guard).
 - **[0.7.31]** (2026-07-03) — Three-round speed & memory pass across streaming, memory retrieval, and the TUI render loop (O(n²) → O(n) in several hot paths), a deep-interview repeat-question loop guard, and gajae-code managed-tmux launch sizing parity.
 - **[0.7.30]** (2026-07-02) — GPT/Codex OAuth calls work again, and the 30-minute turn budget now limits no-progress stalls instead of killing genuinely progressing autonomous runs.
 - **[0.7.29]** (2026-07-02) — gajae-code safety-refusal retry parity: Anthropic/OAuth content-classifier refusals no longer end the turn with a fatal "declined to answer" message after the context-reset ladder.
-- **[0.7.28]** (2026-07-02) — gajae-code 0.7.9–0.7.10 OAuth + model-execution parity: generic long rate-limit windows are retried (never fatal), retry waits are abort-cancellable, Codex prompt caching via session correlation, and the Kimi Code device-flow OAuth is completed end-to-end (catalog, gating, discovery, tests).
-- **[0.7.27]** (2026-07-02) — Extended-keyboard decode layer: Esc/Ctrl+C work again on kitty-protocol terminals, Shift+Enter breaks lines on every terminal incl. Windows, row/draft-aware Cmd+←→/↑↓ + Home/End/Ctrl+Home/End, Ctrl+V text-paste fallback. Plus Anthropic 5th-gen omp-parity: catalog-derived output budgets end thinking-vs-reply starvation; refusals fail fast at the transport and the recovery ladder strips replayed thinking blocks.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jeo-code",
-  "version": "0.7.31",
+  "version": "0.7.33",
 
   "description": "Clean, highly optimized AI coding agent using spec-first loop",
   "type": "module",
@@ -60,12 +60,12 @@
   "dependencies": {
     "zod": "^3.24.1",
     "chalk": "^5.3.0",
-    "js-tiktoken": "^1.0.21"
+    "js-tiktoken": "^1.0.21",
+    "typescript": "^5.6.3",
+    "playwright": "^1.61.0"
   },
   "devDependencies": {
     "@types/bun": "^1.1.14",
-    "playwright": "^1.61.0",
-    "typescript": "^5.6.3",
     "ws": "^8.21.0"
   },
   "packageManager": "pnpm@10.33.4+sha512.1c67b3b359b2d408119ba1ed289f34b8fc3c6873412bec6fd264fbdc82489e510fcbecb9ce9d22dae7f3b76269d8441046014bdca53b9979cd7a561ad631b800"

package/scripts/install.sh

@@ -124,6 +124,23 @@ require_bun() {
 
 bun_bin_dir() { echo "${BUN_INSTALL:-$HOME/.bun}/bin"; }
 
+# Remove a stale `joc` bin/symlink left by a pre-rename install (jeo-code's
+# CLI was renamed joc -> jeo). Runs on every install so it can't silently
+# reappear for machines/users who installed before the rename.
+cleanup_stale_joc() {
+  BUN_BIN="$(bun_bin_dir)"
+  for STALE in "$BUN_BIN/joc" "$INSTALL_DIR/joc"; do
+    if [ -L "$STALE" ] || [ -f "$STALE" ]; then
+      if [ "$DRY_RUN" = "1" ]; then
+        echo "+ rm -f $STALE"
+      else
+        rm -f "$STALE"
+      fi
+      echo "Removed stale pre-rename joc bin: $STALE"
+    fi
+  done
+}
+
 registry_key() {
   if [ -n "$SCOPE" ]; then
     case "$SCOPE" in
@@ -275,11 +292,13 @@ install_binary() {
     ( cd "$SRC_DIR" && bun build src/cli.ts --compile --outfile "$INSTALL_DIR/jeo" >/dev/null )
     chmod +x "$INSTALL_DIR/jeo" 2>/dev/null || true
   fi
+  cleanup_stale_joc
 }
 
 # Add a symlink in INSTALL_DIR so the documented location works even when
 # Bun's global bin dir is not on PATH.
 link_compat() {
+  cleanup_stale_joc
   [ "$DRY_RUN" = "1" ] && return 0
   BUN_BIN="$(bun_bin_dir)"
   [ -e "$BUN_BIN/jeo" ] && LINKED="$BUN_BIN/jeo"

package/scripts/uninstall.sh

@@ -8,7 +8,7 @@ INSTALL_DIR="${JEO_INSTALL_DIR:-$HOME/.local/bin}"
 PURGE=0
 [ "$1" = "--purge" ] && PURGE=1
 
-for BIN_NAME in jeo; do
+for BIN_NAME in jeo joc; do
   if [ -L "$INSTALL_DIR/$BIN_NAME" ] || [ -f "$INSTALL_DIR/$BIN_NAME" ]; then
     rm -f "$INSTALL_DIR/$BIN_NAME"
     echo "Removed $INSTALL_DIR/$BIN_NAME"
@@ -17,7 +17,7 @@ done
 
 # Remove the bun-native link (bin + global registry entry).
 BUN_BIN="${BUN_INSTALL:-$HOME/.bun}/bin"
-for BIN_NAME in jeo; do
+for BIN_NAME in jeo joc; do
   if [ -L "$BUN_BIN/$BIN_NAME" ] || [ -f "$BUN_BIN/$BIN_NAME" ]; then
     rm -f "$BUN_BIN/$BIN_NAME"
     echo "Removed $BUN_BIN/$BIN_NAME (bun link)"

package/src/agent/AGENTS.md

@@ -9,6 +9,18 @@ The core runtime loop, tool registry, session management, and state persistence
 ## Key Files
 | File | Description |
 |------|-------------|
+| `ast-match.ts` | Structural AST metavariable matcher for TypeScript/JavaScript (gjc `ast_grep`/`ast_edit` parity) — `$NAME`/`$_`/`$$$NAME`/`$$$` pattern matching over the `typescript` compiler API's AST, plus replacement-template rendering |
+| `ast-file-scan.ts` | Shared file targeting (files/dirs/globs, gitignore + ignored-dir aware) for `ast_grep`/`ast_edit` |
+| `ast-grep-tool.ts` | `ast_grep` tool — read-only structural code search using `ast-match.ts` |
+| `ts-language-service.ts` | Cached in-process `ts.LanguageService` per project root (gjc `lsp` parity, TS/JS only) — tsconfig-aware root file discovery with a whole-tree fallback, live file-version tracking via stat, and position/selector resolution helpers shared by `lsp-tool.ts`/`lsp-rename-tool.ts` |
+| `lsp-tool.ts` | `lsp` tool — read-only definition/references/hover/symbols/diagnostics via `ts-language-service.ts` |
+| `debug-session.ts` | In-process CDP (V8 Inspector Protocol) client driving a spawned `node --inspect-brk` process (gjc `debug` parity, Node.js only — not Bun, whose inspector speaks a different WebKit dialect); one active session, singleton |
+| `debug-tool.ts` | `debug` tool — launch/set_breakpoint/continue/step/evaluate/stack_trace/scopes/variables/threads/output/terminate via `debug-session.ts`; mutating (runs arbitrary code), excluded from read-only roles |
+| `lsp-rename-tool.ts` | `lsp_rename` tool — cross-file TypeScript/JavaScript rename; mutating, writes via `writeTool`, kept separate from `lsp` so read-only roles can't reach it |
+| `browser-session.ts` | Named-tab headless-Chromium session registry (gjc `browser` parity, via Playwright — already a jeo-code dependency) — one shared browser instance launched lazily, tabs reused by name across calls |
+| `browser-tab.ts` | Per-tab helpers (`observe`/`click`/`type`/`fill`/`select`/`press`/`scroll`/`goto`/`back`/`extract`/`screenshot`/`evaluate`) — `observe()` tags interactive elements with stable numeric ids instead of returning a raw DOM dump or requiring a screenshot |
+| `browser-tool.ts` | `browser` tool — open/close/run/act actions; mutating (drives a real browser, `run` executes arbitrary host JS), excluded from read-only roles |
+| `ast-edit-tool.ts` | `ast_edit` tool — structural codemod using `ast-match.ts`; mutating, writes via `writeTool` |
 | `bash-fixups.ts` | Brief description of purpose |
 | `compaction.ts` | Brief description of purpose |
 | `config-schema.ts` | Brief description of purpose |
@@ -30,6 +42,9 @@ The core runtime loop, tool registry, session management, and state persistence
 | `session.ts` | Session context building, compaction, and history management |
 | `state.ts` | File-backed state and session persistence (`.jeo/state/`) |
 | `step-budget.ts` | gjc-style flexible step budgeting: progress-scored extensions, hard cap, fail-fast |
+| `irc-tool.ts` | `irc` tool — parent/peer live messaging into running DETACHED subagents (list peers, send to one id or "all"); built entirely on `SubagentRegistry.steer()`, gjc `irc` parity |
+| `job-registry.ts` | In-process registry for BACKGROUND shell processes spawned via `job {action:"start"}` — real parallel OS processes (not just concurrent JS), bounded output buffer, list/tail/awaitIds/cancel, gjc `job`/async-bash parity |
+| `job-tool.ts` | `job` control tool — start/list/tail/await/cancel background shell processes tracked by `job-registry.ts` |
 | `subagent-registry.ts` | Brief description of purpose |
 | `subagent-tool.ts` | Brief description of purpose |
 | `subagents.ts` | Brief description of purpose |

package/src/agent/ast-edit-tool.ts

@@ -0,0 +1,123 @@
+/**
+ * `ast_edit` tool — structural (AST-based) codemod for TypeScript/JavaScript, gjc
+ * `ast_edit` parity via the same pure-TS metavariable matcher as `ast_grep`. MUTATING:
+ * excluded from read-only subagent roles (see `subagents.ts`'s `MUTATING` set).
+ *
+ * Each match is replaced by rendering the `replacement` template — `$NAME`/`$$$NAME`
+ * substituted with that match's captured text — then splicing the result into the
+ * original file text (matches within one file are applied in reverse source order so
+ * earlier replacements never shift later offsets; overlapping matches are resolved by
+ * keeping the earliest and skipping any later match that starts before it ends).
+ * Writes go through the existing `writeTool` so the deep-interview mutation lock and
+ * stale-read guard apply exactly as they do for `write`/`edit`.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as ts from "typescript";
+import type { ToolHandler } from "./engine";
+import type { ToolResult } from "./tools";
+import { writeTool } from "./tools";
+import { findMatches, parsePattern, renderReplacement, type MatchResult } from "./ast-match";
+import { resolveTargetFiles, scriptKindFor } from "./ast-file-scan";
+
+/** One-line protocol description appended to the launch system prompt. */
+export const AST_EDIT_TOOL_PROTOCOL_LINE =
+  `ast_edit {pattern, replacement, paths} — structural TypeScript/JavaScript rewrite. Same ` +
+  `pattern metavariables as ast_grep; 'replacement' is a template where $NAME/$$$NAME are ` +
+  `substituted with that match's captured text (empty replacement deletes matches). Rewrites ` +
+  `every match across the given files/dirs/globs and writes the files (mutation lock and ` +
+  `stale-read checks apply, same as write/edit).`;
+
+function pathsOf(args: Record<string, any>): string[] {
+  if (Array.isArray(args.paths)) return args.paths.map((p: unknown) => String(p));
+  if (typeof args.paths === "string" && args.paths.trim()) return [args.paths];
+  return [];
+}
+
+export function createAstEditTool(): ToolHandler {
+  return async (args: Record<string, any>, cwd: string): Promise<ToolResult> => {
+    const pattern = typeof args.pattern === "string" ? args.pattern.trim() : "";
+    if (!pattern) {
+      return { success: false, output: "", error: `ast_edit requires a non-empty "pattern".` };
+    }
+    const replacement = typeof args.replacement === "string" ? args.replacement
+      : typeof args.out === "string" ? args.out : undefined;
+    if (replacement === undefined) {
+      return { success: false, output: "", error: `ast_edit requires a "replacement" template string (use "" to delete matches).` };
+    }
+    try {
+      parsePattern(pattern);
+    } catch (err: any) {
+      return { success: false, output: "", error: `ast_edit pattern error: ${err.message}` };
+    }
+
+    const rawPaths = pathsOf(args);
+    if (rawPaths.length === 0) {
+      return { success: false, output: "", error: `ast_edit requires a non-empty "paths" array (files, directories, or globs).` };
+    }
+
+    let files: string[];
+    try {
+      files = await resolveTargetFiles(rawPaths, cwd);
+    } catch (err: any) {
+      return { success: false, output: "", error: err.message };
+    }
+    if (files.length === 0) {
+      return {
+        success: true,
+        output: "No TypeScript/JavaScript files matched the given paths (ast_edit only covers .ts/.tsx/.js/.jsx/.mjs/.cjs/.mts/.cts).",
+      };
+    }
+
+    const perFile: { file: string; replaced: number }[] = [];
+    let totalReplaced = 0;
+
+    for (const abs of files) {
+      let original: string;
+      try {
+        original = await fs.readFile(abs, "utf-8");
+      } catch {
+        continue;
+      }
+      const sf = ts.createSourceFile(abs, original, ts.ScriptTarget.Latest, true, scriptKindFor(abs));
+      const matches = findMatches(pattern, sf);
+      if (matches.length === 0) continue;
+
+      // Greedy non-overlap selection: earliest-starting match wins any overlap.
+      const sorted = [...matches].sort((a, b) => a.node.getStart(sf) - b.node.getStart(sf));
+      const selected: MatchResult[] = [];
+      let lastEnd = -1;
+      for (const m of sorted) {
+        const start = m.node.getStart(sf);
+        if (start < lastEnd) continue;
+        selected.push(m);
+        lastEnd = m.node.getEnd();
+      }
+      if (selected.length === 0) continue;
+
+      const edits = selected.map(m => ({
+        start: m.node.getStart(sf),
+        end: m.node.getEnd(),
+        text: renderReplacement(replacement, m.captures),
+      }));
+      let newText = original;
+      for (const e of [...edits].sort((a, b) => b.start - a.start)) {
+        newText = newText.slice(0, e.start) + e.text + newText.slice(e.end);
+      }
+
+      const rel = path.relative(cwd, abs) || abs;
+      const res = await writeTool(rel, newText, cwd);
+      if (!res.success) {
+        return { success: false, output: "", error: `${rel}: ${res.error ?? "write failed"}` };
+      }
+      perFile.push({ file: rel, replaced: selected.length });
+      totalReplaced += selected.length;
+    }
+
+    if (totalReplaced === 0) {
+      return { success: true, output: `0 matches for pattern across ${files.length} file(s) — nothing rewritten.` };
+    }
+    const lines = perFile.map(f => `- ${f.file}: ${f.replaced} replacement(s)`);
+    return { success: true, output: `${totalReplaced} replacement(s) across ${perFile.length} file(s):\n${lines.join("\n")}` };
+  };
+}

package/src/agent/ast-file-scan.ts

@@ -0,0 +1,62 @@
+/**
+ * Shared file-targeting helpers for `ast_grep`/`ast_edit` — resolves a loose
+ * `paths` argument (files, directories, or globs) to a deduplicated, sorted list
+ * of TypeScript/JavaScript file absolute paths, respecting `.gitignore` and the
+ * same ignored-directory list as `find`/`search` (see `tools.ts`).
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as ts from "typescript";
+import { IGNORED_DIRS, readGitignore } from "./tools";
+
+export const AST_SUPPORTED_EXT = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts"]);
+
+/** Hard cap on how many files a single ast_grep/ast_edit call will scan — a stray
+ *  `paths: ["**"]` on a huge repo must not hang the turn. */
+export const AST_MAX_FILES = 500;
+
+export function scriptKindFor(file: string): ts.ScriptKind {
+  const ext = path.extname(file);
+  if (ext === ".tsx") return ts.ScriptKind.TSX;
+  if (ext === ".jsx") return ts.ScriptKind.JSX;
+  if (ext === ".ts" || ext === ".mts" || ext === ".cts") return ts.ScriptKind.TS;
+  return ts.ScriptKind.JS;
+}
+
+export async function resolveTargetFiles(rawPaths: string[], cwd: string): Promise<string[]> {
+  const gi = await readGitignore(cwd);
+  const prunedDirs = new Set([...IGNORED_DIRS, ...gi.dirs]);
+  const fileGlobs = gi.fileGlobs.map(g => new Bun.Glob(g));
+  const out = new Set<string>();
+
+  for (const raw of rawPaths) {
+    if (out.size >= AST_MAX_FILES) break;
+    const trimmed = raw.trim();
+    if (!trimmed) continue;
+
+    let pattern = trimmed;
+    const abs = path.resolve(cwd, trimmed);
+    let isDir = false;
+    try { isDir = (await fs.stat(abs)).isDirectory(); } catch { /* not an existing path — treat as a glob/pattern */ }
+
+    if (isDir) {
+      pattern = `${trimmed.replace(/\/+$/, "")}/**/*`;
+    } else if (!/[*?[\]]/.test(trimmed)) {
+      // A plain existing (or nonexistent) file path — no glob metacharacters.
+      if (AST_SUPPORTED_EXT.has(path.extname(trimmed))) out.add(abs);
+      continue;
+    }
+
+    for await (const rel of new Bun.Glob(pattern).scan({ cwd, onlyFiles: true })) {
+      const norm = rel.replace(/\\/g, "/");
+      const segs = norm.split("/");
+      if (segs.some(s => prunedDirs.has(s))) continue;
+      const base = segs[segs.length - 1] ?? norm;
+      if (fileGlobs.some(g => g.match(base))) continue;
+      if (!AST_SUPPORTED_EXT.has(path.extname(base))) continue;
+      out.add(path.resolve(cwd, norm));
+      if (out.size >= AST_MAX_FILES) break;
+    }
+  }
+  return [...out].sort();
+}

package/src/agent/ast-grep-tool.ts

@@ -0,0 +1,107 @@
+/**
+ * `ast_grep` tool — structural (AST-based) code search for TypeScript/JavaScript,
+ * gjc `ast_grep` parity via a pure-TS metavariable matcher (see `ast-match.ts`),
+ * scoped to `.ts`/`.tsx`/`.js`/`.jsx`/`.mjs`/`.cjs`/`.mts`/`.cts` — NOT the native
+ * ast-grep binary and NOT multi-language. Read-only; safe for every subagent role.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as ts from "typescript";
+import type { ToolHandler } from "./engine";
+import type { ToolResult } from "./tools";
+import { findMatches, parsePattern, type MatchResult } from "./ast-match";
+import { resolveTargetFiles, scriptKindFor } from "./ast-file-scan";
+
+/** One-line protocol description appended to the launch system prompt. */
+export const AST_GREP_TOOL_PROTOCOL_LINE =
+  `ast_grep {pattern, paths} — structural TypeScript/JavaScript search (files/dirs/globs in ` +
+  `'paths'). Pattern metavariables: $NAME captures one node (repeats must match identical ` +
+  `code), $_ is a wildcard node, $$$NAME/$$$ capture/ignore zero-or-more sibling nodes in a ` +
+  `list (call args, statements, class members, ...). Whitespace/formatting is ignored — this ` +
+  `matches AST shape, not text.`;
+
+const MAX_MATCHES_PER_FILE = 20;
+const MAX_TOTAL_MATCHES = 200;
+
+function lineOf(sf: ts.SourceFile, pos: number): number {
+  return sf.getLineAndCharacterOfPosition(pos).line + 1;
+}
+
+function snippet(sf: ts.SourceFile, node: ts.Node): string {
+  const oneLine = node.getText(sf).replace(/\s+/g, " ").trim();
+  return oneLine.length > 140 ? oneLine.slice(0, 139) + "…" : oneLine;
+}
+
+function captureSummary(m: MatchResult): string {
+  const flat: Record<string, string> = { ...m.captures.single };
+  for (const [k, v] of Object.entries(m.captures.multi)) flat[k] = v.join(", ");
+  return Object.keys(flat).length ? ` ${JSON.stringify(flat)}` : "";
+}
+
+function pathsOf(args: Record<string, any>): string[] {
+  if (Array.isArray(args.paths)) return args.paths.map((p: unknown) => String(p));
+  if (typeof args.paths === "string" && args.paths.trim()) return [args.paths];
+  return [];
+}
+
+export function createAstGrepTool(): ToolHandler {
+  return async (args: Record<string, any>, cwd: string): Promise<ToolResult> => {
+    const pattern = typeof args.pattern === "string" ? args.pattern.trim() : "";
+    if (!pattern) {
+      return { success: false, output: "", error: `ast_grep requires a non-empty "pattern".` };
+    }
+    try {
+      parsePattern(pattern);
+    } catch (err: any) {
+      return { success: false, output: "", error: `ast_grep pattern error: ${err.message}` };
+    }
+
+    const rawPaths = pathsOf(args);
+    if (rawPaths.length === 0) {
+      return { success: false, output: "", error: `ast_grep requires a non-empty "paths" array (files, directories, or globs).` };
+    }
+
+    let files: string[];
+    try {
+      files = await resolveTargetFiles(rawPaths, cwd);
+    } catch (err: any) {
+      return { success: false, output: "", error: err.message };
+    }
+    if (files.length === 0) {
+      return {
+        success: true,
+        output: "No TypeScript/JavaScript files matched the given paths (ast_grep only covers .ts/.tsx/.js/.jsx/.mjs/.cjs/.mts/.cts).",
+      };
+    }
+
+    const lines: string[] = [];
+    let total = 0;
+    let filesWithMatches = 0;
+    for (const abs of files) {
+      if (total >= MAX_TOTAL_MATCHES) break;
+      let text: string;
+      try {
+        text = await fs.readFile(abs, "utf-8");
+      } catch {
+        continue;
+      }
+      const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true, scriptKindFor(abs));
+      const matches = findMatches(pattern, sf);
+      if (matches.length === 0) continue;
+      filesWithMatches++;
+      const rel = path.relative(cwd, abs) || abs;
+      for (const m of matches.slice(0, MAX_MATCHES_PER_FILE)) {
+        if (total >= MAX_TOTAL_MATCHES) break;
+        total++;
+        const line = lineOf(sf, m.node.getStart(sf));
+        lines.push(`${rel}:${line}: ${snippet(sf, m.node)}${captureSummary(m)}`);
+      }
+    }
+
+    if (total === 0) {
+      return { success: true, output: `0 matches for pattern across ${files.length} file(s).` };
+    }
+    const capNote = total >= MAX_TOTAL_MATCHES ? ` (truncated at ${MAX_TOTAL_MATCHES})` : "";
+    return { success: true, output: `${total} match(es) in ${filesWithMatches} file(s)${capNote}:\n${lines.join("\n")}` };
+  };
+}