@mrpatronz/nexusflow 1.7.0 → 1.9.0

package/README.md

@@ -10,13 +10,14 @@
 
 ---
 
-NexusFlow combines multiple Git repositories into a single feature workspace and generates the context files that your AI coding assistant needs to understand all of them at once. It uses **git worktrees** so every repo stays on a clean feature branch without disturbing your main working copy.
+NexusFlow combines multiple Git repositories into a single feature workspace and generates the context files that your AI coding assistant needs to understand all of them at once. It can create isolated **git worktrees** on clean feature branches, or work in-place directly in your source repositories when you want to manage branches yourself.
 
 > **New to NexusFlow?** Jump to the [Getting Started Guide](GETTING_STARTED.md) for a hands-on walkthrough.
 
 ## ✨ Features
 
-- **Multi-repo workspaces** — group any set of local Git repos under one feature branch using worktrees
+- **Multi-repo workspaces** — group any set of local Git repos in isolated worktrees or in-place source repositories
+- **Project registry** — save named, persistent repo groups in `~/.nexusflow/projects.json` and reuse them from the CLI or API
 - **The full feature loop** — `create` opens a workspace, `finish` closes it: commit + push every repo, open PRs (or print compare links), promote learnings, and optionally clean up
 - **Knowledge that accumulates** — capture decisions and gotchas as you work with `nexusflow knowledge add`, then `promote` the reusable ones into per-repo memory that survives across features
 - **AI context generation** — automatically writes `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`, and `.cursor/rules/nexusflow.mdc`
@@ -76,20 +77,49 @@ nexusflow init
 # 2 — Create a feature workspace
 nexusflow create
 
-# 3 — Or launch the Web Dashboard
-nexusflow ui
+# 3 — Or use the GUI: desktop app (see desktop/) or browser dashboard
+nexusflow dashboard
 ```
 
 The `create` wizard walks you through:
 
-1. **Name your feature branch** — e.g. `feature/user-auth`
-2. **Describe what you're building** — plain text or a path to a `.md` file
-3. **Pick your repos** — NexusFlow scans `~/dev` for git repositories
-4. **Choose AI assistant(s)** — auto-detects what's installed
-5. **Done!** — workspace created with git worktrees + AI context files
+1. **Choose a repo source** — start from a registered project or scan/pick ad-hoc repos
+2. **Choose a work mode** — isolated worktrees or in-place source repositories
+3. **Name the branch or workspace** — branch name for worktrees, workspace name for in-place
+4. **Describe what you're building** — plain text or a path to a `.md` file
+5. **Choose AI assistant(s)** — auto-detects what's installed
+6. **Done!** — workspace created with AI context files, plus git worktrees in isolated mode
+
+## 📚 Projects
+
+A project is a named, persistent group of source repositories stored centrally in `~/.nexusflow/projects.json`. Project ids are slugified from the name, so `Hogia Billing` becomes `hogia-billing`. Use either the `project` command group or its `proj` alias:
+
+| Command | Description |
+|:---|:---|
+| `nexusflow project add -n, --name <name> -r, --repos <paths...> [-d, --description <text>]` | Register a project; omit `--repos` to use the interactive repo picker |
+| `nexusflow project list` | List registered projects (alias: `ls`) |
+| `nexusflow project show [id]` | Show a registered project |
+| `nexusflow project remove [id] [-y, --yes]` | Remove a project from the registry (alias: `rm`) |
+
+Removing a project only edits the registry — it never deletes repositories or workspaces on disk. The HTTP API exposes the same registry through `GET /api/projects`, `POST /api/projects`, `PUT /api/projects/:id`, and `DELETE /api/projects/:id`.
+
+## 🧭 Work Modes
+
+`nexusflow create` offers registered projects first (ad-hoc repo scanning is still available), then asks how the workspace should work:
+
+| Mode | What it does |
+|:---|:---|
+| **Isolated worktrees** | The classic flow: NexusFlow creates a feature branch and git worktree per repo inside the workspace directory. |
+| **In-place** | NexusFlow works directly in the source repositories. No branches or worktrees are created; you provide a workspace name, and the workspace directory only holds `nexusflow.json` plus generated AI context files. |
+
+In in-place workspaces, `nexusflow sync` is a deliberate no-op because you manage branches yourself. `nexusflow finish` commits and pushes each repo's current branch, and only offers PR/compare links when that branch differs from the default branch. Deleting an in-place workspace never touches the source repositories, `nexusflow list` tags it with `[in-place]`, and agent sessions for single-repo in-place workspaces run in the repo root.
+
+For API callers, `POST /api/workspace` accepts optional `mode` (`worktree` default, or `in-place`), `name` (required for in-place), and `projectId`. Existing workspace manifests without a `mode` field are treated as `worktree` mode.
 
 ## 📂 What Gets Generated
 
+In isolated worktree mode:
+
 ```
 ~/dev/workspaces/feature/user-auth/
 ├── CLAUDE.md                         # Context for Claude / Antigravity
@@ -104,29 +134,33 @@ The `create` wizard walks you through:
 └── my-frontend/                      # ← Git worktree on feature branch
 ```
 
+In-place workspaces keep the manifest and generated AI context files in the workspace directory while the code stays in the source repositories.
+
 Open this folder in your editor → your AI assistant picks up the context → it understands *all* your repos.
 
 ## 🖥️ Commands
 
 | Command | Description |
 |:---|:---|
-| `nexusflow create` | Interactive wizard to create a new feature workspace |
-| `nexusflow list` | List all existing workspaces (alias: `ls`) |
+| `nexusflow create` | Interactive wizard to create a new worktree or in-place workspace |
+| `nexusflow list` | List all existing workspaces, tagging in-place ones with `[in-place]` (alias: `ls`) |
 | `nexusflow open` | Re-open a workspace in your editor |
 | `nexusflow init` | Configure NexusFlow settings |
+| `nexusflow project` | Manage registered repo groups: `add`, `list`/`ls`, `show`, `remove`/`rm` (alias: `proj`) |
 | `nexusflow add-repo` | Add a repository to an existing workspace (alias: `add`) |
-| `nexusflow remove` | Delete a workspace and prune its git worktrees (alias: `rm`) |
+| `nexusflow remove` | Delete a workspace and prune its git worktrees when present (alias: `rm`) |
 | `nexusflow start` | Start all services in a workspace (auto-detected) |
 | `nexusflow stop` | Stop all running services |
 | `nexusflow status` | Show running/stopped status and PIDs |
 | `nexusflow logs` | Tail aggregated logs from all services |
-| `nexusflow ui` | Launch the interactive Web Dashboard (`--port`, `--server-only`, `--strict-port`) |
-| `nexusflow dashboard` | Instantly open the Web Dashboard in your browser (alias: `dash`) |
+| `nexusflow ui` | Start the dashboard server — the backend the desktop app embeds (`--port`, `--open`, `--strict-port`) |
+| `nexusflow dashboard` | Open the dashboard in your browser (alias: `dash`) |
 | `nexusflow tui` | Open the interactive terminal (TUI) dashboard |
 | `nexusflow diff` | View changes across all sub-repositories, including unpushed commits (`--repo` to filter) |
 | `nexusflow commit` | Commit and push changes across all modified repositories (`--repo`, `--no-push`, `--dry-run`) |
-| `nexusflow sync` | Rebase all repositories in the workspace with default base branches |
+| `nexusflow sync` | Rebase worktree-mode repositories with default base branches; deliberate no-op for in-place workspaces |
 | `nexusflow finish` | Close out a feature: commit & push all repos, open PRs / print compare links, promote learnings, optionally remove the workspace (`-m`, `--no-pr`, `--no-knowledge`, `--cleanup`, `--dry-run`) |
+| `nexusflow review` | Start an iterative reviewer-implementer agent loop with automated verification harnesses |
 | `nexusflow knowledge` | Capture & manage workspace learnings: `add` (decision/gotcha/progress/…), `show`, `promote` into per-repo base knowledge |
 | `nexusflow refresh`| Regenerate maps, plan, and AI context files — only re-analyzes changed repos (`--force` for a full pass) |
 | `nexusflow handoff` | Generate a compact handoff bundle (`nexusflow-handoff.md`) for session resumption |
@@ -135,7 +169,7 @@ Open this folder in your editor → your AI assistant picks up the context → i
 | `nexusflow config` | View and update configuration: `show`, `get <key>`, `set <key> <value>` |
 | `nexusflow adapter` | Manage storage adapters: `list`, `use`, `info`, `init` |
 | `nexusflow mcp` | Manage the MCP server for AI assistants: `run`, `setup` |
-| `nexusflow desktop` | Launch the NexusFlow desktop application |
+| `nexusflow desktop` | Launch the Electron desktop app from the workspace `desktop/` project (requires a built CLI and `desktop/` deps installed) |
 
 ## 🤖 Supported AI Assistants
 
@@ -152,7 +186,7 @@ NexusFlow auto-detects which assistants are available on your machine and genera
 
 NexusFlow is built around a single loop:
 
-1. **`nexusflow create`** — open a workspace of git worktrees on a feature branch with AI context files generated. Along the way you can **scaffold a brand-new project** (a fresh local git repo in your dev directory) and, per repo, **check out an existing branch** — local or remote — instead of creating the feature branch.
+1. **`nexusflow create`** — open a worktree or in-place workspace with AI context files generated. Along the way you can **scaffold a brand-new project** (a fresh local git repo in your dev directory) and, per repo, **check out an existing branch** — local or remote — instead of creating the feature branch.
 2. **Work** — your AI assistant edits code across repos. As it goes, it records learnings:
    ```bash
    nexusflow knowledge add -t decision -m "Chose worktrees over submodules for isolation"
@@ -162,10 +196,10 @@ NexusFlow is built around a single loop:
    Entries land under the right heading in `nexusflow-knowledge.md` (routed through your storage adapter — local or central vault — so the GUI and the generators all see the same file). No hand-editing, no accidental overwrites.
 3. **`nexusflow finish`** — close it out:
    - Shows a preflight status table (branch, dirty files, unpushed commits) per repo.
-   - Commits any remaining changes (repos on the wrong branch or in a detached HEAD are skipped, never committed) and pushes every branch.
+   - Commits any remaining changes and pushes every branch; worktree-mode repos on the wrong branch or in a detached HEAD are skipped, while in-place workspaces use each repo's current branch.
    - Opens a PR per repo with the GitHub CLI when it's installed and authenticated; otherwise prints a ready-to-click **compare URL** for GitHub, GitLab, Azure DevOps, or Bitbucket.
    - Offers to **promote** reusable learnings into each repo's persistent base knowledge (so they survive into the next feature).
-   - With `--cleanup`, removes the workspace once everything is confirmed pushed (never while you're `cd`'d inside it).
+   - With `--cleanup`, removes the workspace once everything is confirmed pushed (never while you're `cd`'d inside it, and never touching source repositories for in-place workspaces).
 
    ```bash
    nexusflow finish --dry-run        # preview what would happen
@@ -189,7 +223,7 @@ NexusFlow is built around a single loop:
 | `promote_knowledge` | Copy a learning into a repo's persistent base knowledge |
 | `finish_workspace` | Commit, push, and return PR/compare links (never deletes anything) |
 | `get_service_logs` | Tail a running service's logs |
-| `delegate_to_local_agent` | Offload cheap/high-volume subtasks to a local SLM (when enabled) |
+
 
 Read-only tools are annotated as such; `finish_workspace` deliberately cannot delete worktrees (cleanup stays a human-confirmed CLI action). Pass `--debug` (or set `NEXUSFLOW_DEBUG=1`) on any CLI command to surface diagnostic logging on stderr.
 
@@ -260,7 +294,7 @@ nexusflow schedule disable <id>
 nexusflow schedule run <id>
 ```
 
-Jobs are stored in `~/.nexusflow/schedules.json` and executed while a NexusFlow server is running — start one with `nexusflow ui` (use `--daemon --server-only` for a background host). A job whose interval elapsed while no server was running simply runs on the next scheduler tick.
+Jobs are stored in `~/.nexusflow/schedules.json` and executed while a NexusFlow server is running — start one with `nexusflow ui` (use `--daemon` for a background host). A job whose interval elapsed while no server was running simply runs on the next scheduler tick.
 
 Scheduled runs are **token-efficient by design**: they use the same analysis cache as `nexusflow refresh`, so only repos whose content changed are re-analyzed, and unchanged context files are left byte-identical (no git churn, no invalidated AI prompt caches). The dashboard API exposes the same functionality under `/api/schedules`.
 
@@ -283,9 +317,9 @@ The dashboard integrates an **AI Strategy Analysis** inspector:
 2. (Optional) Provide a comment or specific evaluation focus (e.g. *"Ensure subagent roles are distinct"*).
 3. Click **Inspect Strategy** to have the AI analyze the strategy rules, identify ambiguities/contradictions, rate its orchestration effectiveness, and generate an optimized rewritten guideline.
 
-## 🌐 Web Dashboard
+## 🖥️ Dashboard (Desktop App & Browser)
 
-Launch with `nexusflow ui` to get a full-featured dark-themed GUI:
+The primary GUI is the Electron desktop app in `desktop/` (`npm install && npm start` there). It embeds the same dashboard the browser sees. For browser access, run `nexusflow dashboard`; `nexusflow ui` starts the underlying server without opening anything (add `--open` to launch a browser). For the platform rationale (Electron vs Tauri and friends), see [docs/desktop-platform.md](docs/desktop-platform.md). The dashboard is a full-featured dark-themed GUI:
 
 - **Workspaces tab** — create, browse, and manage feature workspaces
 - **Sessions tab** — view past AI conversation transcripts and resume sessions

package/dist/agent/AntigravityCliAdapter.d.ts

@@ -0,0 +1,7 @@
+import { CliAdapterBase } from './CliAdapterBase.js';
+export declare class AntigravityCliAdapter extends CliAdapterBase {
+    protected readonly binary = "agy";
+    protected readonly label = "agy CLI";
+    protected buildArgs(isFirstTurn: boolean, prompt: string): string[];
+}
+//# sourceMappingURL=AntigravityCliAdapter.d.ts.map

package/dist/agent/AntigravityCliAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AntigravityCliAdapter.d.ts","sourceRoot":"","sources":["../../src/agent/AntigravityCliAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,qBAAa,qBAAsB,SAAQ,cAAc;IACvD,SAAS,CAAC,QAAQ,CAAC,MAAM,SAAS;IAClC,SAAS,CAAC,QAAQ,CAAC,KAAK,aAAa;IAMrC,SAAS,CAAC,SAAS,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;CAGpE"}

package/dist/agent/AntigravityCliAdapter.js

@@ -0,0 +1,13 @@
+import { CliAdapterBase } from './CliAdapterBase.js';
+export class AntigravityCliAdapter extends CliAdapterBase {
+    binary = 'agy';
+    label = 'agy CLI';
+    // agy is a native binary: reads the prompt from argv and needs no shell
+    // (argv is passed literally, so multi-word prompts are safe without quoting).
+    // -p runs a single prompt; -c continues the conversation for later turns.
+    // agy has no resume-by-id, so no fallback.
+    buildArgs(isFirstTurn, prompt) {
+        return isFirstTurn ? ['-p', prompt] : ['-c', '-p', prompt];
+    }
+}
+//# sourceMappingURL=AntigravityCliAdapter.js.map

package/dist/agent/AntigravityCliAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AntigravityCliAdapter.js","sourceRoot":"","sources":["../../src/agent/AntigravityCliAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,MAAM,OAAO,qBAAsB,SAAQ,cAAc;IACpC,MAAM,GAAG,KAAK,CAAC;IACf,KAAK,GAAG,SAAS,CAAC;IACrC,wEAAwE;IACxE,8EAA8E;IAE9E,0EAA0E;IAC1E,2CAA2C;IACjC,SAAS,CAAC,WAAoB,EAAE,MAAc;QACtD,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7D,CAAC;CACF"}

package/dist/agent/ClaudeCliAdapter.d.ts

@@ -0,0 +1,16 @@
+import { CliAdapterBase } from './CliAdapterBase.js';
+import { type AgentSession } from './session.js';
+export declare class ClaudeCliAdapter extends CliAdapterBase {
+    protected readonly binary = "claude";
+    protected readonly label = "claude CLI";
+    protected readonly useShell = true;
+    protected readonly promptViaStdin = true;
+    protected fallbackMessage: string;
+    private session;
+    private sessionEstablished;
+    start(cwd: string, session?: AgentSession): Promise<void>;
+    protected buildArgs(isFirstTurn: boolean): string[];
+    protected fallbackArgs(): string[] | null;
+    protected onTurnComplete(succeeded: boolean): void;
+}
+//# sourceMappingURL=ClaudeCliAdapter.d.ts.map

package/dist/agent/ClaudeCliAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClaudeCliAdapter.d.ts","sourceRoot":"","sources":["../../src/agent/ClaudeCliAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAEtE,qBAAa,gBAAiB,SAAQ,cAAc;IAClD,SAAS,CAAC,QAAQ,CAAC,MAAM,YAAY;IACrC,SAAS,CAAC,QAAQ,CAAC,KAAK,gBAAgB;IAGxC,SAAS,CAAC,QAAQ,CAAC,QAAQ,QAAQ;IACnC,SAAS,CAAC,QAAQ,CAAC,cAAc,QAAQ;IACzC,SAAS,CAAC,eAAe,SAAiE;IAE1F,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,kBAAkB,CAAkB;IAE/B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;IAMtD,SAAS,CAAC,SAAS,CAAC,WAAW,EAAE,OAAO,GAAG,MAAM,EAAE;IAMnD,SAAS,CAAC,YAAY,IAAI,MAAM,EAAE,GAAG,IAAI;IAOzC,SAAS,CAAC,cAAc,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI;CAGnD"}

package/dist/agent/ClaudeCliAdapter.js

@@ -0,0 +1,34 @@
+import { CliAdapterBase } from './CliAdapterBase.js';
+import { buildClaudeTurnArgs } from './session.js';
+export class ClaudeCliAdapter extends CliAdapterBase {
+    binary = 'claude';
+    label = 'claude CLI';
+    // claude is an npm .cmd shim: needs a shell on Windows, and under a shell an
+    // argv prompt would split on spaces, so the prompt goes over stdin.
+    useShell = true;
+    promptViaStdin = true;
+    fallbackMessage = 'Could not resume the previous session — starting a new one.';
+    session;
+    sessionEstablished = false;
+    async start(cwd, session) {
+        await super.start(cwd);
+        this.session = session;
+        this.sessionEstablished = false;
+    }
+    buildArgs(isFirstTurn) {
+        return buildClaudeTurnArgs(isFirstTurn, this.session);
+    }
+    // A --resume of a purged session fails on the very first turn; the id is
+    // then free, so one retry with --session-id recreates it under the same id.
+    fallbackArgs() {
+        if (this.session?.resume === true && !this.sessionEstablished) {
+            return ['-p', '--session-id', this.session.id];
+        }
+        return null;
+    }
+    onTurnComplete(succeeded) {
+        if (succeeded)
+            this.sessionEstablished = true;
+    }
+}
+//# sourceMappingURL=ClaudeCliAdapter.js.map

package/dist/agent/ClaudeCliAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClaudeCliAdapter.js","sourceRoot":"","sources":["../../src/agent/ClaudeCliAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAqB,MAAM,cAAc,CAAC;AAEtE,MAAM,OAAO,gBAAiB,SAAQ,cAAc;IAC/B,MAAM,GAAG,QAAQ,CAAC;IAClB,KAAK,GAAG,YAAY,CAAC;IACxC,6EAA6E;IAC7E,oEAAoE;IACjD,QAAQ,GAAG,IAAI,CAAC;IAChB,cAAc,GAAG,IAAI,CAAC;IAC/B,eAAe,GAAG,6DAA6D,CAAC;IAElF,OAAO,CAA2B;IAClC,kBAAkB,GAAY,KAAK,CAAC;IAErC,KAAK,CAAC,KAAK,CAAC,GAAW,EAAE,OAAsB;QACpD,MAAM,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,kBAAkB,GAAG,KAAK,CAAC;IAClC,CAAC;IAES,SAAS,CAAC,WAAoB;QACtC,OAAO,mBAAmB,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACxD,CAAC;IAED,yEAAyE;IACzE,4EAA4E;IAClE,YAAY;QACpB,IAAI,IAAI,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC9D,OAAO,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACjD,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAES,cAAc,CAAC,SAAkB;QACzC,IAAI,SAAS;YAAE,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAChD,CAAC;CACF"}

package/dist/agent/CliAdapterBase.d.ts

@@ -0,0 +1,48 @@
+import { EventEmitter } from 'node:events';
+import { type ChildProcess } from 'node:child_process';
+/**
+ * Shared lifecycle for CLI-backed agents (claude, agy). Each turn spawns the
+ * binary once in print mode, streams stdout as `data`, and emits `idle` when
+ * the turn ends. Subclasses supply the binary, the per-turn args, how the
+ * prompt is delivered, and (optionally) a one-shot fallback used when the
+ * first attempt of a turn fails with no output.
+ *
+ * Prompt delivery differs per CLI: `claude` is an npm `.cmd` shim that needs
+ * `shell: true` on Windows, and under a shell an argv prompt would be split on
+ * spaces, so its prompt goes over stdin. `agy` is a native binary that reads
+ * the prompt from argv and needs no shell (argv is passed literally, so no
+ * quoting hazard).
+ */
+export declare abstract class CliAdapterBase extends EventEmitter {
+    protected cwd: string;
+    protected isFirstTurn: boolean;
+    private isProcessing;
+    private stopped;
+    private child;
+    /** Executable name, e.g. 'claude' or 'agy'. */
+    protected abstract readonly binary: string;
+    /** Short label for stderr/error diagnostics. */
+    protected abstract readonly label: string;
+    /** Spawn through a shell (needed to resolve a `.cmd` shim on Windows). */
+    protected readonly useShell: boolean;
+    /** Pipe the prompt to stdin (true) vs. include it in argv via buildArgs (false). */
+    protected readonly promptViaStdin: boolean;
+    /** Args for one print-mode turn. Receives the prompt so argv-mode CLIs can
+     *  include it; stdin-mode CLIs ignore it. */
+    protected abstract buildArgs(isFirstTurn: boolean, prompt: string): string[];
+    /**
+     * Args to retry with when the first attempt of a turn exits non-zero with no
+     * output (e.g. resuming a purged session). Return null for no fallback.
+     */
+    protected fallbackArgs(): string[] | null;
+    /** Message emitted as a `system` event when the fallback kicks in. */
+    protected fallbackMessage: string;
+    /** Called once per turn after it settles; `succeeded` if it produced output or exited 0. */
+    protected onTurnComplete(_succeeded: boolean): void;
+    start(cwd: string): Promise<void>;
+    send(data: string): Promise<void>;
+    private runTurn;
+    stop(): void;
+}
+export declare function killTree(child: ChildProcess | null): void;
+//# sourceMappingURL=CliAdapterBase.d.ts.map

package/dist/agent/CliAdapterBase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CliAdapterBase.d.ts","sourceRoot":"","sources":["../../src/agent/CliAdapterBase.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE9D;;;;;;;;;;;;GAYG;AACH,8BAAsB,cAAe,SAAQ,YAAY;IACvD,SAAS,CAAC,GAAG,EAAE,MAAM,CAAM;IAC3B,SAAS,CAAC,WAAW,EAAE,OAAO,CAAQ;IACtC,OAAO,CAAC,YAAY,CAAkB;IACtC,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,KAAK,CAA6B;IAE1C,+CAA+C;IAC/C,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAC3C,gDAAgD;IAChD,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAC1C,0EAA0E;IAC1E,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAS;IAC7C,oFAAoF;IACpF,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAS;IAEnD;iDAC6C;IAC7C,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IAE5E;;;OAGG;IACH,SAAS,CAAC,YAAY,IAAI,MAAM,EAAE,GAAG,IAAI;IAIzC,sEAAsE;IACtE,SAAS,CAAC,eAAe,EAAE,MAAM,CAAe;IAEhD,4FAA4F;IAC5F,SAAS,CAAC,cAAc,CAAC,UAAU,EAAE,OAAO,GAAG,IAAI;IAEtC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU9C,OAAO,CAAC,OAAO;IA0DR,IAAI,IAAI,IAAI;CAOpB;AAID,wBAAgB,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,QAOlD"}

package/dist/agent/CliAdapterBase.js

@@ -0,0 +1,120 @@
+import { EventEmitter } from 'node:events';
+import { spawn } from 'node:child_process';
+/**
+ * Shared lifecycle for CLI-backed agents (claude, agy). Each turn spawns the
+ * binary once in print mode, streams stdout as `data`, and emits `idle` when
+ * the turn ends. Subclasses supply the binary, the per-turn args, how the
+ * prompt is delivered, and (optionally) a one-shot fallback used when the
+ * first attempt of a turn fails with no output.
+ *
+ * Prompt delivery differs per CLI: `claude` is an npm `.cmd` shim that needs
+ * `shell: true` on Windows, and under a shell an argv prompt would be split on
+ * spaces, so its prompt goes over stdin. `agy` is a native binary that reads
+ * the prompt from argv and needs no shell (argv is passed literally, so no
+ * quoting hazard).
+ */
+export class CliAdapterBase extends EventEmitter {
+    cwd = '';
+    isFirstTurn = true;
+    isProcessing = false;
+    stopped = false;
+    child = null;
+    /** Spawn through a shell (needed to resolve a `.cmd` shim on Windows). */
+    useShell = false;
+    /** Pipe the prompt to stdin (true) vs. include it in argv via buildArgs (false). */
+    promptViaStdin = false;
+    /**
+     * Args to retry with when the first attempt of a turn exits non-zero with no
+     * output (e.g. resuming a purged session). Return null for no fallback.
+     */
+    fallbackArgs() {
+        return null;
+    }
+    /** Message emitted as a `system` event when the fallback kicks in. */
+    fallbackMessage = 'Retrying…';
+    /** Called once per turn after it settles; `succeeded` if it produced output or exited 0. */
+    onTurnComplete(_succeeded) { }
+    async start(cwd) {
+        this.cwd = cwd;
+        this.isFirstTurn = true;
+    }
+    async send(data) {
+        if (this.isProcessing)
+            return;
+        this.isProcessing = true;
+        this.stopped = false;
+        const args = this.buildArgs(this.isFirstTurn, data);
+        this.isFirstTurn = false;
+        this.runTurn(args, data, true);
+    }
+    runTurn(args, data, allowFallback) {
+        const cliProcess = spawn(this.binary, args, {
+            cwd: this.cwd,
+            shell: this.useShell,
+            env: { ...process.env, FORCE_COLOR: '0' } // Strip colors for easier parsing
+        });
+        this.child = cliProcess;
+        if (this.promptViaStdin) {
+            cliProcess.stdin?.write(data);
+            cliProcess.stdin?.end();
+        }
+        let producedOutput = false;
+        let stderrTail = '';
+        cliProcess.stdout?.on('data', (chunk) => {
+            producedOutput = true;
+            this.emit('data', chunk.toString());
+        });
+        // CLIs print warnings and progress on stderr; only keep it for diagnostics.
+        cliProcess.stderr?.on('data', (chunk) => {
+            const text = chunk.toString();
+            stderrTail = (stderrTail + text).slice(-2000);
+            console.warn(`[${this.label} stderr]`, text.trimEnd());
+        });
+        cliProcess.on('error', (err) => {
+            this.isProcessing = false;
+            this.child = null;
+            this.emit('error', new Error(`Failed to start ${this.label}: ${err.message}`));
+            this.emit('idle');
+        });
+        cliProcess.on('close', (code) => {
+            this.child = null;
+            if (!this.stopped && code !== 0 && !producedOutput && allowFallback) {
+                const fb = this.fallbackArgs();
+                if (fb) {
+                    this.emit('system', this.fallbackMessage);
+                    this.runTurn(fb, data, false);
+                    return;
+                }
+            }
+            this.isProcessing = false;
+            this.onTurnComplete(code === 0 || producedOutput);
+            // A non-zero exit after an intentional stop is expected, not an error.
+            if (!this.stopped && code !== 0 && !producedOutput) {
+                this.emit('error', new Error(`${this.label} exited with code ${code}${stderrTail ? `: ${stderrTail.trim()}` : ''}`));
+            }
+            // Turn separation is the GUI's concern — do not inject stray output here,
+            // or a failed turn would spawn an empty bubble on the client.
+            this.emit('idle');
+        });
+    }
+    stop() {
+        this.stopped = true;
+        killTree(this.child);
+        this.child = null;
+        this.isProcessing = false;
+        this.emit('close', 0);
+    }
+}
+// With shell:true on Windows, child.kill() only kills the shell wrapper,
+// so take the whole tree down via taskkill.
+export function killTree(child) {
+    if (!child || child.killed || child.exitCode !== null || !child.pid)
+        return;
+    if (process.platform === 'win32') {
+        spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+    }
+    else {
+        child.kill('SIGTERM');
+    }
+}
+//# sourceMappingURL=CliAdapterBase.js.map

package/dist/agent/CliAdapterBase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CliAdapterBase.js","sourceRoot":"","sources":["../../src/agent/CliAdapterBase.ts"],"names":[],"mappings":"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"}

package/dist/agent/NativeAgent.d.ts

@@ -0,0 +1,13 @@
+import { NativeAgentBase } from './NativeAgentBase.js';
+export declare class NativeAgent extends NativeAgentBase {
+    protected readonly label = "NativeAgent";
+    private openai;
+    private messages;
+    private modelName;
+    constructor();
+    private client;
+    protected configError(): string | null;
+    protected resetHistory(): void;
+    protected runLoop(userInput: string, signal: AbortSignal): Promise<void>;
+}
+//# sourceMappingURL=NativeAgent.d.ts.map

package/dist/agent/NativeAgent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NativeAgent.d.ts","sourceRoot":"","sources":["../../src/agent/NativeAgent.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AASvD,qBAAa,WAAY,SAAQ,eAAe;IAC9C,SAAS,CAAC,QAAQ,CAAC,KAAK,iBAAiB;IACzC,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,SAAS,CAAS;;IAS1B,OAAO,CAAC,MAAM;IAId,SAAS,CAAC,WAAW,IAAI,MAAM,GAAG,IAAI;IAItC,SAAS,CAAC,YAAY;cAIN,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW;CAiF/D"}

package/dist/agent/NativeAgent.js

@@ -0,0 +1,97 @@
+import OpenAI from 'openai';
+import { NativeAgentBase } from './NativeAgentBase.js';
+import { NATIVE_TOOLS, NATIVE_STEP_LIMIT, STEP_LIMIT_NOTICE, buildSystemPrompt, executeNativeTool, } from './nativeTools.js';
+export class NativeAgent extends NativeAgentBase {
+    label = 'NativeAgent';
+    openai = null;
+    messages = [];
+    modelName;
+    constructor() {
+        super();
+        this.modelName = process.env.OPENAI_MODEL || 'gpt-4o';
+    }
+    // The OpenAI SDK throws on an empty key, so build the client lazily — after
+    // configError() has gated on the key being present.
+    client() {
+        return (this.openai ??= new OpenAI({ apiKey: process.env.OPENAI_API_KEY || '' }));
+    }
+    configError() {
+        return process.env.OPENAI_API_KEY ? null : 'OpenAI API key is not configured (set OPENAI_API_KEY).';
+    }
+    resetHistory() {
+        this.messages = [{ role: 'system', content: buildSystemPrompt(this.cwd) }];
+    }
+    async runLoop(userInput, signal) {
+        this.messages.push({ role: 'user', content: userInput });
+        const tools = NATIVE_TOOLS.map((t) => ({
+            type: 'function',
+            function: {
+                name: t.name,
+                description: t.description,
+                parameters: {
+                    type: 'object',
+                    properties: { [t.argName]: { type: 'string', description: t.argDescription } },
+                    required: [t.argName],
+                },
+            },
+        }));
+        let completed = false;
+        for (let step = 0; step < NATIVE_STEP_LIMIT; step++) {
+            if (signal.aborted)
+                break;
+            const stream = await this.client().chat.completions.create({
+                model: this.modelName,
+                messages: this.messages,
+                tools: tools,
+                stream: true,
+            }, { signal });
+            let content = '';
+            const toolCalls = [];
+            for await (const chunk of stream) {
+                const delta = chunk.choices[0]?.delta;
+                if (!delta)
+                    continue;
+                if (delta.content) {
+                    content += delta.content;
+                    this.emit('data', delta.content);
+                }
+                if (delta.tool_calls) {
+                    for (const toolCall of delta.tool_calls) {
+                        const index = toolCall.index;
+                        if (!toolCalls[index]) {
+                            toolCalls[index] = {
+                                id: toolCall.id,
+                                type: 'function',
+                                function: { name: toolCall.function?.name, arguments: '' },
+                            };
+                            this.emit('data', `\n\n*Running tool: ${toolCall.function?.name}*\n`);
+                        }
+                        if (toolCall.function?.arguments) {
+                            toolCalls[index].function.arguments += toolCall.function.arguments;
+                        }
+                    }
+                }
+            }
+            this.messages.push({ role: 'assistant', content, tool_calls: toolCalls.length > 0 ? toolCalls : undefined });
+            if (toolCalls.length === 0) {
+                completed = true;
+                break;
+            }
+            for (const tc of toolCalls) {
+                let result;
+                try {
+                    const args = JSON.parse(tc.function.arguments || '{}');
+                    result = await executeNativeTool(this.cwd, tc.function.name, args);
+                }
+                catch (err) {
+                    result = `Error: ${err.message}`;
+                }
+                this.messages.push({ role: 'tool', tool_call_id: tc.id, name: tc.function.name, content: result });
+            }
+        }
+        if (!completed && !signal.aborted) {
+            this.emit('data', STEP_LIMIT_NOTICE);
+        }
+    }
+}
+//# sourceMappingURL=NativeAgent.js.map

package/dist/agent/NativeAgent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NativeAgent.js","sourceRoot":"","sources":["../../src/agent/NativeAgent.ts"],"names":[],"mappings":"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"}

package/dist/agent/NativeAgentBase.d.ts

@@ -0,0 +1,27 @@
+import { EventEmitter } from 'node:events';
+/**
+ * Shared lifecycle for the SDK-backed native agents. Owns the processing guard,
+ * the abort controller, and the idle/error signalling so each provider only
+ * implements its SDK-specific streaming loop.
+ */
+export declare abstract class NativeAgentBase extends EventEmitter {
+    protected cwd: string;
+    protected isProcessing: boolean;
+    protected abortController: AbortController | null;
+    /** Human label used in server-side error logs. */
+    protected abstract readonly label: string;
+    /** Clear provider-specific conversation history for a new session. */
+    protected abstract resetHistory(): void;
+    /** Run one user turn's agent loop, honoring `signal` for cancellation. */
+    protected abstract runLoop(userInput: string, signal: AbortSignal): Promise<void>;
+    /**
+     * Returns a user-facing message when the provider isn't usable (e.g. missing
+     * API key), or null when it is. Checked before each turn so a misconfigured
+     * provider gives a clear error instead of a raw SDK auth exception.
+     */
+    protected configError(): string | null;
+    start(cwd: string): Promise<void>;
+    send(data: string): Promise<void>;
+    stop(): void;
+}
+//# sourceMappingURL=NativeAgentBase.d.ts.map

package/dist/agent/NativeAgentBase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NativeAgentBase.d.ts","sourceRoot":"","sources":["../../src/agent/NativeAgentBase.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;GAIG;AACH,8BAAsB,eAAgB,SAAQ,YAAY;IACxD,SAAS,CAAC,GAAG,EAAE,MAAM,CAAM;IAC3B,SAAS,CAAC,YAAY,EAAE,OAAO,CAAS;IACxC,SAAS,CAAC,eAAe,EAAE,eAAe,GAAG,IAAI,CAAQ;IAEzD,kDAAkD;IAClD,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAE1C,sEAAsE;IACtE,SAAS,CAAC,QAAQ,CAAC,YAAY,IAAI,IAAI;IAEvC,0EAA0E;IAC1E,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAEjF;;;;OAIG;IACH,SAAS,CAAC,WAAW,IAAI,MAAM,GAAG,IAAI;IAIzB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BvC,IAAI,IAAI,IAAI;CAKpB"}