codebase-onboarder 0.7.0 → 1.0.0

package/README.md

@@ -12,7 +12,7 @@
 
 Onboarder reads a software repository the way a senior engineer would: starting at the front door, tracing import graphs, mapping architectural layers, computing risk/health metrics, discovering dead exports and dependency drift, and charting Git hotspots — rendering everything as interactive, zoomable diagrams.
 
-**100% Local & Private**: Your code never leaves your computer. No external services or accounts are required.
+**Local analysis**: Repository maps and the offline explorer run on your machine without an account. Optional AI chat sends task context and requested source to your configured model provider.
 
 ---
 
@@ -22,9 +22,12 @@ Onboarder reads a software repository the way a senior engineer would: starting
 # Install from npm (Node 20+, zero runtime dependencies)
 npm install -g codebase-onboarder
 
-# Choose a folder or Git URL to explore in your terminal
+# Open the repository chat harness in your terminal
 onboarder
 
+# Browse offline, including folders and Git URLs
+onboarder explore
+
 # …or start the web UI instead
 onboarder start
 ```
@@ -40,7 +43,7 @@ npm start
 
 Open **http://localhost:4310** in your browser (the CLI opens it for you).
 
-- **Two front doors, one engine.** `onboarder` opens an interactive terminal session; `onboarder start` opens the web UI. Both run the *same* analyzer, so they can never disagree about a repository.
+- **Chat, explorer, and web UI.** `onboarder` opens the Hermes chat harness; `onboarder explore` opens offline browsing; `onboarder start` opens the web UI. Repository analysis uses the same engine in all three.
 - **Ready to run from npm**: Compiled JavaScript is included in the package. Application source lives in `src/` as TypeScript. Run `npm run build` after editing it, or use `npm run dev` for automatic rebuilds and server restarts.
 - **Zero runtime dependencies**: Powered by Node.js built-ins (`node:http`, `node:fs`, `node:crypto`).
 - **Offline ready**: Vendored Mermaid.js and Monaco Editor builds are included in `public/vendor/`.
@@ -49,18 +52,71 @@ Open **http://localhost:4310** in your browser (the CLI opens it for you).
 
 ## 🖥️ The terminal app
 
-Type `onboarder` to choose the current folder, browse directories, or paste a Git URL. Local folders are read directly, with no server or browser.
+Type `onboarder` to open the Hermes-powered chat interface for the current repository, or `onboarder chat ~/work/some-repo` to open another local checkout. An amber welcome screen shows the actual configured model, repository, permissions, six workflow skills, and 37 registered tools. The composer has a session status bar with recorded token usage, elapsed run time, and live tool activity. It keeps terminal scrollback and loads the browsing engine only when requested.
+
+```sh
+onboarder chat
+onboarder chat ~/work/some-repo --mode review
+onboarder chat https://github.com/owner/repo
+onboarder chat --resume <conversation-id>
+```
+
+Inside the chat:
+
+```text
+codebase ask › /model configure
+codebase ask › /repo https://github.com/owner/repo
+codebase ask › Explain how authentication works
+codebase ask › Where are those permissions checked?
+codebase ask › /review 42 Focus on correctness and security
+codebase review › /triage 12
+codebase triage › /permissions checks on
+codebase triage › /implement Fix the bug described in issue 12
+codebase implement › /diff
+codebase implement › Add a regression test for that fix
+codebase implement › /history
+```
+
+| Commands | Purpose |
+| --- | --- |
+| `/ask`, `/review`, `/triage`, `/implement`, `/pr`, `/github` | Start a workflow; following messages continue it |
+| `/mode`, `/model`, `/permissions`, `/limits` | Control the workflow, provider, allowed actions, timeout, and turn budget |
+| `/map`, `/tree`, `/find`, `/show`, `/diff`, `/health`, `/rescan` | Browse and analyze offline; inspect the active implementation workspace |
+| `/tour`, `/explain`, `/deps`, `/inspect`, `/graph`, `/blast`, `/symbols` | Follow the reading order, inspect modules, and trace dependencies |
+| `/hubs`, `/layers`, `/patterns`, `/stats`, `/security`, `/stack`, `/entry`, `/externals`, `/coupling`, `/clusters`, `/risks` | Explore repository structure, health, and risks |
+| `/log`, `/hotspots`, `/blame`, `/diagram`, `/layers-diagram`, `/atlas`, `/docs`, `/workflows`, `/sbom` | Inspect Git history, diagrams, documentation, CI, and licenses |
+| `/engines`, `/deep`, `/web`, `/about` | Discover and run optional analyzers, start the web interface, and inspect repository details |
+| `/new`, `/history`, `/resume`, `/repo`, `/status` | Manage saved conversations, repository context, and workspaces |
+| `/clone <GitHub URL>`, `/pull` | Clone a GitHub repository and refresh a clean saved checkout |
+| `/paste`, `/send`, `/discard` | Compose or discard multiline prompts and code |
+| `/setup`, `/doctor`, `/help`, `/clear`, `/cancel`, `/exit` | Set up Hermes, check readiness, and control the terminal session |
+| `/tools`, `/skills`, `/runs`, `/run`, `/export` | Inspect actual capabilities, saved runs, and export this chat as Markdown |
+
+Typing `/` immediately opens a searchable command menu with descriptions. Keep typing to filter, use ↑/↓ to choose, and press Tab or Enter to fill the command without starting a task. A fully typed command executes on Enter. Esc dismisses the menu and restores normal history navigation. Tab also completes settings and indexed file paths. Alt-Enter adds a newline; bracketed paste keeps multiline code together and waits for Enter before sending. Ctrl-A/E move to the start/end, Ctrl-U clears the draft, and Ctrl-C cancels an active task. Ctrl-D cancels, saves, and exits when the draft is empty.
+
+Chat opens in a **full-screen terminal interface** with the composer pinned to the bottom. The welcome, conversation and menus automatically reflow when the terminal window changes size. **Page Up / Page Down** scroll the conversation without editing your draft; new output preserves your reading position until you return to the latest messages. Narrow or short windows use compact layouts, and the original Onboarder **code-compass** logo appears in full or compact terminal art. Its reusable vector image is [public/assets/onboarder-mark.svg](public/assets/onboarder-mark.svg).
+
+The screen paints only changed rows and batches streamed output. Drafts survive resizes and model-wizard handoffs, and leaving chat restores the original shell screen. The in-memory viewport retains up to 4,000 logical lines or 2 MiB; conversation storage and `/export` remain available separately. Follow-ups reuse the saved Hermes session and its isolated implementation workspace. Changing the workflow, PR/issue target, model, or permissions starts a new session. `/clear` clears the screen while keeping context; `/new` resets the conversation. Checks and GitHub writes default to off. `/deep` requires checks permission. `/pr` prepares changes locally unless GitHub writes are enabled; publishing must also be requested in the task. `/export` saves a private Markdown transcript under the agent home's `exports` folder.
+
+`/model` opens a Hermes-style provider/model picker below the input. Type to filter, use ↑/↓ to select, and press Enter to choose. Available providers and models come from the installed Hermes catalog; selection uses Hermes' own credential resolution and saves the model to the dedicated Onboarder profile. Escape keeps your current model and conversation. Choose **Configure provider / authentication**, or run `/model configure`, for the full official Hermes configuration, including custom endpoints and provider login. Older Hermes installations can use this full wizard when the quick picker is unavailable. No model names or provider credentials are hardcoded into the picker.
+
+At startup, an unconfigured profile offers **Choose a provider and model** or **Continue offline**. Configured profiles start directly in chat. Hermes must be installed separately for AI tasks; offline commands work without it. Conversation summaries are stored privately in `~/.config/onboarder/agent/chats`, alongside agent runs, and known environment credentials are redacted. `/resume` requires a conversation for the current repository and preserves your current permission choices. `onboarder chat --resume` takes a **conversation ID**; `onboarder agent … --resume` takes an **agent run ID**.
+
+To ask about a GitHub repository, launch `onboarder chat https://github.com/owner/repo`, use `/repo <URL>` or `/clone <URL>`, or simply paste the URL into chat. You can also paste `<URL> Explain this repository` to clone and ask in one message. HTTPS and GitHub SSH URLs work; private repositories use your existing Git credentials. Cloning shows progress and can be cancelled with Ctrl-C.
+
+Chat checkouts are saved under `~/.config/onboarder/agent/repositories` and remain after exit, so conversations and isolated implementation workspaces can resume. Reopening the same URL reuses its checkout. `/pull` fetches current changes with a fast-forward-only pull and refuses local changes; use `/new` first if an implementation workspace is active. A successful pull resets AI context so the next question reads the updated source. To resume later, reopen the same URL and use `/history`, then `/resume <conversation-id>`.
+
+The original explorer remains available for its full browsing, source picker, diagrams, and optional analyzer commands:
 
 ```bash
-onboarder                 # choose a source; Enter uses the current directory
+onboarder explore         # choose a source; Enter uses the current directory
 onboarder explore ~/work/some-repo
 onboarder report .        # one-shot summary, no interactive terminal needed
 onboarder report . --json # stable JSON for scripts and CI
-onboarder explore         # same source chooser
-onboarder --server        # force the web UI (what bare `onboarder` used to do)
+onboarder --server        # force the web UI
 ```
 
-It lands on a `map` of the repo, then waits:
+The explorer lands on a `map` of the repo, then waits:
 
 ```
   codebase > tour
@@ -136,12 +192,55 @@ The HTTP equivalent is `{ "path": "/repo", "options": { "maxFiles": 10000,
 and 32 reads. Scan cache keys include every file and its imports, exports, and
 findings, so changes beyond the first hundred files also invalidate the cache.
 
-`ask` is optional. Set `ONBOARDER_AI_BASE_URL` and `ONBOARDER_AI_MODEL`, plus
+The explorer's `ask` command is optional. Set `ONBOARDER_AI_BASE_URL` and `ONBOARDER_AI_MODEL`, plus
 `ONBOARDER_AI_API_KEY` when the endpoint requires a key. The CLI also accepts
 `OPENAI_BASE_URL`, `OPENAI_MODEL`, and `OPENAI_API_KEY`. It sends the question
 and a limited scan summary only when you run `ask`; the key stays in the
 process environment and is not saved in Onboarder's config.
 
+### Hermes repository and GitHub agent
+
+`onboarder agent` adds multi-step repository work through [Nous Research's Hermes Agent](https://github.com/NousResearch/hermes-agent). Hermes is an optional, separately installed Python runtime; Onboarder's npm package still has no runtime dependencies. The TypeScript harness supplies **37 scoped MCP tools** built around Onboarder's existing analysis and GitHub's API.
+
+```sh
+onboarder agent setup
+onboarder agent model                 # choose a provider/model in the dedicated profile
+onboarder agent doctor
+onboarder agent ask . --task "Explain the authentication flow"
+onboarder agent review . --pr 42 --task "Review correctness and security"
+onboarder agent triage . --issue 12 --task "Investigate the cause and propose labels"
+onboarder agent implement . --issue 12 --task "Fix this issue" --allow-checks
+onboarder agent pr . --task "Implement the fix and open a draft PR" --allow-checks --allow-github-writes
+onboarder agent github . --task "Explain why the latest CI run failed"
+onboarder agent runs
+onboarder agent show <run-id>
+```
+
+The same commands work inside the explorer: `agent review --pr 42` uses the loaded repository. Implementation and PR work require a persistent local checkout; the explorer's temporary URL clones are removed on exit. `agent help` lists setup and workflow options. Use `--dry-run --json` to inspect a plan without creating a workspace or calling a model. Use `--json` for one machine-readable result; progress stays on stderr.
+
+| Workflow | Result |
+| --- | --- |
+| `ask` | Repository Q&A grounded in scan, architecture, search and source tools |
+| `review` | Local-change or GitHub PR findings, patch coverage, discussion and checks at the PR head SHA |
+| `triage` | Issue investigation, duplicate candidates, priority, labels and a proposed implementation plan |
+| `implement` | Edits in a separate Git worktree, diff inspection and optional npm checks |
+| `pr` | Implementation plus a proposed PR; publishes a **draft** when GitHub writes are enabled |
+| `github` | Repository, issues, PR discussions, labels, CI runs/jobs, comments and review tasks |
+
+GitHub access uses the local checkout's **github.com `origin`** and `GITHUB_TOKEN` or `GH_TOKEN`. Public reads can work without a token; private reads and writes need a token with access to the requested resources. Git transport uses your existing Git credentials. Publishing a review requires the freshly read PR head SHA and refuses a changed head.
+
+Source editing is available only in `implement`/`pr` worktrees created at **committed HEAD** on a `codex/agent-…` branch. Uncommitted changes in your source checkout are excluded. File tools refuse symlinks, credential files, traversal and files larger than 128 KiB; edits require the hash of a fresh read. Workspaces remain available after completion or failure for inspection. Publishing commits workspace changes, pushes that task branch and creates a draft PR; it does not merge. The PR target defaults to the cached `origin/HEAD` branch, falling back to the current branch; choose another with `--base`. Repeated identical successful writes are deduplicated within one running tool server.
+
+`--allow-checks` allows lockfile dependency installation with lifecycle scripts disabled, plus `npm test`, `npm run typecheck` and `npm run build`. Test/build scripts can execute repository code and may write files. `--allow-github-writes` enables issue updates, comments, PR reviews and draft PR publishing. Both permissions are enforced by the tools and default to off. Onboarder supplies only its dedicated MCP toolset to Hermes.
+
+Runs have a default 24-turn, 300-second limit; adjust with `--max-turns` and `--timeout`. Ctrl-C cancels an active agent in both the CLI and explorer. `--resume <run-id>` continues a saved Hermes session in its original workspace; repeat any enabled permission flags. Resume cannot expand the original permissions. Timeouts, missing completion frames and nonzero process exits are recorded as failures.
+
+Run metadata, final answers and operation audits live under `~/.config/onboarder/agent` (override with `ONBOARDER_AGENT_HOME`). Hermes configuration and transcripts use a dedicated named profile under the installation's `profiles` folder; `agent setup` prints its path. Audit records contain operation names, outcome and timing; Hermes session transcripts can contain prompts and source. Repository/tool content is sent to the configured model during agent tasks. Known environment credentials are redacted from Onboarder diagnostics and final answers. API keys supplied through the environment are not written by Onboarder.
+
+For an existing compatible endpoint, set `ONBOARDER_AI_BASE_URL`, `ONBOARDER_AI_MODEL` and optionally `ONBOARDER_AI_API_KEY` **before the first `agent setup`**. Standard `OPENAI_BASE_URL`, `OPENAI_MODEL`, `OPENAI_API_KEY` aliases also work. Later, `agent model` updates the dedicated profile without changing your normal Hermes profile. Use `ONBOARDER_HERMES_BIN` to select a Hermes executable. For a nonstandard source installation, preserve its `HERMES_HOME`/`HERMES_RUNTIME_DIR` environment so the harness can locate its shared Python packages.
+
+`onboarder agent source` fetches the official MIT-licensed source at the researched revision into the agent source cache. This does not install Python dependencies or vendor Hermes into the npm package. The source review and integration decisions are documented in [Hermes research](docs/HERMES_RESEARCH.md). Developers can run `node scripts/hermes-smoke.mjs` after building to verify a real installed Hermes runtime against a local model fixture, without external inference or GitHub writes.
+
 **It also takes a GitHub URL, the way the site does.** Point it at one and it clones, scans and opens that repo:
 
 ```
@@ -305,8 +404,8 @@ Next to **Explorer** in the top nav. One page with everything:
 - **What this means** — the AI reads the report: *"Explain this analysis"* for a
   prioritised read, or ask about a specific finding (*"is the eval finding
   reachable?"*). It is told which engines did **not** run, so it will not claim
-  coverage it does not have. Needs an OpenAI-compatible endpoint; without one the
-  report is still fully readable and the button offers the API key drawer.
+  coverage it does not have. Needs a Hermes connection or an AI endpoint; without one the
+  report is still fully readable and the button offers the AI connection drawer.
 
 Rules that keep this safe to self-host:
 
@@ -340,8 +439,12 @@ Rules that keep this safe to self-host:
 
 ### 5. AI Notes & Explainers (Optional)
 - Works 100% offline out-of-the-box.
+- In **AI connection**, choose **Hermes · use my configured login** to reuse the Onboarder CLI's Hermes provider and model. No API key is needed in the browser. The drawer shows the current model/provider; use **Test connection**, then **Save**. Install Hermes on the computer running the server and run `onboarder agent model` to sign in or change models, then refresh the configuration in the drawer.
 - Connect any OpenAI-compatible LLM endpoint (OpenAI, Azure OpenAI, Groq, OpenRouter, Ollama, LM Studio) to generate streaming explanations and repository documentation.
-- API keys are stored solely in your browser's `localStorage` and never logged or written to disk.
+- Hermes powers questions, explanations, diagrams, documentation, analysis summaries and review briefs using their supplied repository context. Web explanations have no machine tools. Each request starts a fresh conversation, with a two-minute runtime budget and at most two concurrent requests; closing or cancelling an answer stops its Hermes process. Runtime startup can add a few seconds to the first response.
+- **AI sketch** draws the current map, folder, file or architecture view using that connection. Sketches are checked with Mermaid before they are cached and displayed. **Static** returns to the original map; **AI sketch ✓** restores the cached sketch. Generated diagrams support **Copy Mermaid**, **Save SVG**, pan/zoom and file links. **Cancel sketch**, changing views, or opening another repository cancels an unfinished request. Hermes diagram requests use low reasoning without changing the saved chat configuration.
+- Hermes owns its login and may save prompts/source in its session transcripts. Context is sent to the configured provider under its normal account usage limits. Existing API endpoint settings still work; API-mode keys are saved in browser `localStorage` and never logged or written to the server's disk. Hermes requests do not forward these browser keys.
+- Developers can run `node scripts/hermes-web-smoke.mjs` after building to verify the HTTP integration against a real installed Hermes runtime and a local model fixture without external inference.
 
 ### 6. MCP Server — let any AI agent onboard itself
 

package/cli/agent/command.d.ts

@@ -0,0 +1,71 @@
+export declare const AGENT_HELP = "\n  Onboarder agent \u2014 Hermes with repository and GitHub tools\n\n  onboarder agent setup                    Create a dedicated Hermes profile\n  onboarder chat [folder]                  Open the conversational harness with / commands\n  onboarder agent model                    Configure its model/provider interactively\n  onboarder agent doctor                   Check runtime and integration compatibility\n  onboarder agent source                   Fetch the researched official Hermes source\n  onboarder agent runs                     List saved runs\n  onboarder agent show <run-id>             Inspect a saved result and workspace\n  onboarder agent <workflow> [folder] --task \"...\"\n\n  Workflows: ask, review, triage, implement, pr, github\n  --pr <number>             Review/inspect a GitHub pull request\n  --issue <number>          Work from an issue\n  --base <branch>           PR target (default: origin HEAD, or current branch)\n  --allow-checks            Allow npm install/test/typecheck/build (repository code)\n  --allow-github-writes     Allow issue/review/comment updates and draft PR publishing\n  --max-turns <1\u2013100>       Agent turn limit (default: 24)\n  --timeout <seconds>       Run limit, 15\u20133600 (default: 300)\n  --model <name> --provider <name>  Override the dedicated Hermes model\n  --resume <run-id>         Continue a session; repeat allowed permission flags\n  --dry-run                Print the plan without a model call or worktree\n  --json                   One JSON result; progress goes to stderr\n\n  implement/pr use a new Git worktree at committed HEAD. Uncommitted source\n  changes are excluded. Without --allow-github-writes, pr prepares a draft locally.\n  GitHub uses the checkout's github.com origin and GITHUB_TOKEN or GH_TOKEN.\n  Hermes is an optional separate Python runtime: https://github.com/NousResearch/hermes-agent\n  Profile/history: ONBOARDER_AGENT_HOME (default: ~/.config/onboarder/agent).\n\n  onboarder agent ask . --task \"Explain the authentication flow\"\n  onboarder agent review . --pr 42 --task \"Find correctness and security issues\"\n  onboarder agent triage . --issue 12 --task \"Investigate and propose a fix\"\n  onboarder agent implement . --task \"Fix issue 12\" --issue 12 --allow-checks\n  onboarder agent pr . --task \"Fix issue 12 and open a draft PR\" --issue 12 --allow-checks --allow-github-writes\n";
+export declare const AGENT_OPTIONS: {
+    task: {
+        type: 'string';
+    };
+    pr: {
+        type: 'string';
+    };
+    issue: {
+        type: 'string';
+    };
+    'max-turns': {
+        type: 'string';
+    };
+    timeout: {
+        type: 'string';
+    };
+    resume: {
+        type: 'string';
+    };
+    'allow-checks': {
+        type: 'boolean';
+    };
+    'allow-github-writes': {
+        type: 'boolean';
+    };
+    'dry-run': {
+        type: 'boolean';
+    };
+    model: {
+        type: 'string';
+    };
+    provider: {
+        type: 'string';
+    };
+    json: {
+        type: 'boolean';
+    };
+    help: {
+        type: 'boolean';
+        short: string;
+    };
+    base: {
+        type: 'string';
+    };
+};
+export declare function agentDoctor(home?: string, env?: NodeJS.ProcessEnv): Promise<{
+    runtime: boolean;
+    compatible: boolean;
+    server: boolean;
+    profile: boolean;
+    githubToken: boolean;
+    home: string;
+    ready: boolean;
+    detail: string;
+    next: string;
+}>;
+export declare function fetchHermesSource(home?: string, signal?: AbortSignal): Promise<{
+    source: string;
+    revision: string;
+    directory: string;
+    license: string;
+    installed: boolean;
+}>;
+export declare function agentCommand(sub?: string, positionals?: string[], flags?: Record<string, any>, options?: {
+    root?: string;
+    signal?: AbortSignal;
+    out?: (text: string) => void;
+    err?: (text: string) => void;
+}): Promise<number>;
+export declare function explorerAgent(args: string[], root: string, signal: AbortSignal, out: (text: string) => void, err: (text: string) => void): Promise<string>;

package/cli/agent/command.js

@@ -0,0 +1,177 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { parseArgs } from 'node:util';
+import { AGENT_MODES } from './contracts.js';
+import { agentHome, setupAgent, prepareAgentProfile, runtimePaths, hermesBinary, hermesEnvironment, HERMES_SOURCE, HERMES_REVISION } from './config.js';
+import { runAgent, savedRun } from './runner.js';
+import { runProcess, terminalText, redact } from './process.js';
+import { githubToken } from './github.js';
+export const AGENT_HELP = `
+  Onboarder agent — Hermes with repository and GitHub tools
+
+  onboarder agent setup                    Create a dedicated Hermes profile
+  onboarder chat [folder]                  Open the conversational harness with / commands
+  onboarder agent model                    Configure its model/provider interactively
+  onboarder agent doctor                   Check runtime and integration compatibility
+  onboarder agent source                   Fetch the researched official Hermes source
+  onboarder agent runs                     List saved runs
+  onboarder agent show <run-id>             Inspect a saved result and workspace
+  onboarder agent <workflow> [folder] --task "..."
+
+  Workflows: ask, review, triage, implement, pr, github
+  --pr <number>             Review/inspect a GitHub pull request
+  --issue <number>          Work from an issue
+  --base <branch>           PR target (default: origin HEAD, or current branch)
+  --allow-checks            Allow npm install/test/typecheck/build (repository code)
+  --allow-github-writes     Allow issue/review/comment updates and draft PR publishing
+  --max-turns <1–100>       Agent turn limit (default: 24)
+  --timeout <seconds>       Run limit, 15–3600 (default: 300)
+  --model <name> --provider <name>  Override the dedicated Hermes model
+  --resume <run-id>         Continue a session; repeat allowed permission flags
+  --dry-run                Print the plan without a model call or worktree
+  --json                   One JSON result; progress goes to stderr
+
+  implement/pr use a new Git worktree at committed HEAD. Uncommitted source
+  changes are excluded. Without --allow-github-writes, pr prepares a draft locally.
+  GitHub uses the checkout's github.com origin and GITHUB_TOKEN or GH_TOKEN.
+  Hermes is an optional separate Python runtime: https://github.com/NousResearch/hermes-agent
+  Profile/history: ONBOARDER_AGENT_HOME (default: ~/.config/onboarder/agent).
+
+  onboarder agent ask . --task "Explain the authentication flow"
+  onboarder agent review . --pr 42 --task "Find correctness and security issues"
+  onboarder agent triage . --issue 12 --task "Investigate and propose a fix"
+  onboarder agent implement . --task "Fix issue 12" --issue 12 --allow-checks
+  onboarder agent pr . --task "Fix issue 12 and open a draft PR" --issue 12 --allow-checks --allow-github-writes
+`;
+export const AGENT_OPTIONS = {
+    task: { type: 'string' }, pr: { type: 'string' }, issue: { type: 'string' },
+    'max-turns': { type: 'string' }, timeout: { type: 'string' }, resume: { type: 'string' },
+    'allow-checks': { type: 'boolean' }, 'allow-github-writes': { type: 'boolean' }, 'dry-run': { type: 'boolean' },
+    model: { type: 'string' }, provider: { type: 'string' }, json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
+    base: { type: 'string' },
+};
+export async function agentDoctor(home = agentHome(), env = process.env) {
+    const paths = runtimePaths(home, env);
+    let runtime = false, compatible = false, detail = '';
+    try {
+        const result = await runProcess(hermesBinary(env), ['chat', '--help'], { env: hermesEnvironment(home, env), timeoutMs: 30_000, maxBytes: 128000 });
+        runtime = result.code === 0;
+        compatible = runtime && ['--query-file', 'stream-json', '--toolsets', '--run-budget', '--ignore-rules', '--no-restore-cwd'].every(s => result.stdout.includes(s));
+        if (!compatible)
+            detail = result.code ? result.stderr.slice(-2000) || 'Hermes could not start.' : 'Update Hermes to a runtime supporting structured one-shot chat and MCP selection.';
+    }
+    catch (e) {
+        detail = redact(e instanceof Error ? e.message : String(e), env);
+    }
+    const server = await fs.access(paths.server).then(() => true).catch(() => false);
+    const profile = await fs.access(path.join(paths.profile, 'config.yaml')).then(() => true).catch(() => false);
+    return { runtime, compatible, server, profile, githubToken: Boolean(githubToken(env)), home, ready: runtime && compatible && server && profile, detail,
+        next: !runtime ? 'Install Hermes from its official repository, then agent setup and agent model.' : !profile ? 'Run onboarder agent setup, then onboarder agent model.' : 'Model credentials are checked by Hermes when a task runs; use agent model to configure them.' };
+}
+export async function fetchHermesSource(home = agentHome(), signal) {
+    const target = path.join(home, 'upstream', 'hermes-agent');
+    await fs.mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+    const git = async (args) => {
+        const output = await runProcess('git', ['-c', 'http.version=HTTP/1.1', ...args], { signal, timeoutMs: 120_000, maxBytes: 2 * 1024 * 1024 });
+        if (output.code)
+            throw new Error(`Hermes source fetch failed: ${output.stderr.slice(-1500)}`);
+        return output.stdout.trim();
+    };
+    if (!await fs.access(target).then(() => true).catch(() => false)) {
+        const staging = target + '-' + randomUUID();
+        try {
+            await git(['clone', '--depth', '1', '--no-checkout', '--', HERMES_SOURCE, staging]);
+            await fs.rename(staging, target);
+        }
+        finally {
+            await fs.rm(staging, { recursive: true, force: true });
+        }
+    }
+    if (await git(['-C', target, 'remote', 'get-url', 'origin']) !== HERMES_SOURCE)
+        throw new Error('The source cache origin is not the official Hermes repository.');
+    if (await git(['-C', target, 'status', '--porcelain']) && await fs.access(path.join(target, 'LICENSE')).then(() => true).catch(() => false))
+        throw new Error('The source cache contains edits. Preserve them before updating it.');
+    await git(['-C', target, 'fetch', '--depth', '1', 'origin', HERMES_REVISION]);
+    await git(['-C', target, '-c', 'core.hooksPath=' + path.join(home, 'empty-hooks'), 'checkout', '--detach', HERMES_REVISION]);
+    return { source: HERMES_SOURCE, revision: HERMES_REVISION, directory: target, license: 'MIT', installed: false };
+}
+export async function agentCommand(sub = 'help', positionals = [], flags = {}, options = {}) {
+    const out = options.out || console.log, err = options.err || console.error, home = agentHome();
+    const print = (value) => out(typeof value === 'string' ? value : JSON.stringify(value, null, 2));
+    if (flags.help || sub === 'help') {
+        out(AGENT_HELP);
+        return 0;
+    }
+    if (sub === 'setup') {
+        const result = await prepareAgentProfile(home, process.env, options.signal);
+        print(flags.json ? result : `Dedicated Hermes profile: ${result.profile}\n${result.created ? 'Created.' : 'Existing model settings preserved.'} Run onboarder agent model to configure its provider.\nRun onboarder agent doctor to check the integration.`);
+        return 0;
+    }
+    if (sub === 'doctor') {
+        const report = await agentDoctor(home);
+        print(report);
+        return report.ready ? 0 : 1;
+    }
+    if (sub === 'source') {
+        print(await fetchHermesSource(home, options.signal));
+        return 0;
+    }
+    if (sub === 'model') {
+        if (!process.stdin.isTTY)
+            throw new Error('Run onboarder agent model in an interactive terminal.');
+        await setupAgent(home);
+        return new Promise((resolve, reject) => {
+            const child = spawn(hermesBinary(), ['model'], { env: hermesEnvironment(home), stdio: 'inherit', shell: false, signal: options.signal });
+            child.on('error', reject);
+            child.on('close', code => resolve(code ?? 1));
+        });
+    }
+    if (sub === 'runs') {
+        const names = await fs.readdir(runtimePaths(home).runs).catch(e => { if (e.code !== 'ENOENT')
+            throw e; return []; });
+        const runs = (await Promise.all(names.filter(n => /^[a-f\d-]{36}$/.test(n)).map(async (id) => {
+            try {
+                const { manifest, result } = await savedRun(id, home);
+                return { id, mode: manifest.mode, status: result?.status || 'unfinished', startedAt: manifest.startedAt, workspace: manifest.root, repository: manifest.repository };
+            }
+            catch {
+                return { id, status: 'unreadable' };
+            }
+        }))).sort((a, b) => (b.startedAt || '').localeCompare(a.startedAt || ''));
+        print(runs);
+        return 0;
+    }
+    if (sub === 'show') {
+        print(await savedRun(positionals[0] || '', home));
+        return 0;
+    }
+    if (!AGENT_MODES.includes(sub))
+        throw new Error('Unknown agent workflow. Run onboarder agent --help.');
+    if (positionals.length > 1)
+        throw new Error('Use one repository folder and --task "your task".');
+    const task = flags.task || (sub === 'review' ? `Review ${flags.pr ? 'pull request ' + flags.pr : 'local changes'} for actionable correctness and security issues.` : sub === 'triage' ? `Investigate ${flags.issue ? 'issue ' + flags.issue : 'open issues'} and propose a prioritized plan.` : '');
+    const result = await runAgent({ mode: sub, root: positionals[0] || options.root || '.', task,
+        pr: flags.pr === undefined ? undefined : Number(flags.pr), issue: flags.issue === undefined ? undefined : Number(flags.issue),
+        maxTurns: flags.maxTurns === undefined ? flags['max-turns'] : flags.maxTurns, timeoutSeconds: flags.timeout,
+        allowChecks: flags.allowChecks || flags['allow-checks'], allowGithubWrites: flags.allowGithubWrites || flags['allow-github-writes'], dryRun: flags.dryRun || flags['dry-run'],
+        model: flags.model, provider: flags.provider, resume: flags.resume, base: flags.base }, { signal: options.signal,
+        onEvent: event => {
+            if (event.type === 'tool_use')
+                err(`  ${terminalText(event.name || 'Tool')}…`);
+            if (event.type === 'tool_result' && event.is_error)
+                err(`  ${terminalText(event.name || 'Tool')} reported an error.`);
+        } });
+    if ('dryRun' in result || flags.json)
+        print(result);
+    else
+        out(`${terminalText(result.answer)}\n\nRun: ${result.id} (${result.status})\nWorkspace: ${result.workspace}${result.branch ? '\nBranch: ' + result.branch : ''}`);
+    return 'dryRun' in result || result.status === 'completed' ? 0 : result.status === 'cancelled' ? 130 : 1;
+}
+export async function explorerAgent(args, root, signal, out, err) {
+    const parsed = parseArgs({ args, options: AGENT_OPTIONS, allowPositionals: true });
+    await agentCommand(parsed.positionals[0], parsed.positionals.slice(1), parsed.values, { root, signal, out, err });
+    return '';
+}
+//# sourceMappingURL=command.js.map

package/cli/agent/command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../../src/cli/agent/command.ts"],"names":[],"mappings":"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","sourcesContent":["import { promises as fs } from 'node:fs';\nimport path from 'node:path';\nimport { randomUUID } from 'node:crypto';\nimport { spawn } from 'node:child_process';\nimport { parseArgs } from 'node:util';\nimport { AGENT_MODES, type AgentMode } from './contracts.js';\nimport { agentHome, setupAgent, prepareAgentProfile, runtimePaths, hermesBinary, hermesEnvironment, HERMES_SOURCE, HERMES_REVISION } from './config.js';\nimport { runAgent, savedRun } from './runner.js';\nimport { runProcess, terminalText, redact } from './process.js';\nimport { githubToken } from './github.js';\n\nexport const AGENT_HELP = `\n  Onboarder agent — Hermes with repository and GitHub tools\n\n  onboarder agent setup                    Create a dedicated Hermes profile\n  onboarder chat [folder]                  Open the conversational harness with / commands\n  onboarder agent model                    Configure its model/provider interactively\n  onboarder agent doctor                   Check runtime and integration compatibility\n  onboarder agent source                   Fetch the researched official Hermes source\n  onboarder agent runs                     List saved runs\n  onboarder agent show <run-id>             Inspect a saved result and workspace\n  onboarder agent <workflow> [folder] --task \"...\"\n\n  Workflows: ask, review, triage, implement, pr, github\n  --pr <number>             Review/inspect a GitHub pull request\n  --issue <number>          Work from an issue\n  --base <branch>           PR target (default: origin HEAD, or current branch)\n  --allow-checks            Allow npm install/test/typecheck/build (repository code)\n  --allow-github-writes     Allow issue/review/comment updates and draft PR publishing\n  --max-turns <1–100>       Agent turn limit (default: 24)\n  --timeout <seconds>       Run limit, 15–3600 (default: 300)\n  --model <name> --provider <name>  Override the dedicated Hermes model\n  --resume <run-id>         Continue a session; repeat allowed permission flags\n  --dry-run                Print the plan without a model call or worktree\n  --json                   One JSON result; progress goes to stderr\n\n  implement/pr use a new Git worktree at committed HEAD. Uncommitted source\n  changes are excluded. Without --allow-github-writes, pr prepares a draft locally.\n  GitHub uses the checkout's github.com origin and GITHUB_TOKEN or GH_TOKEN.\n  Hermes is an optional separate Python runtime: https://github.com/NousResearch/hermes-agent\n  Profile/history: ONBOARDER_AGENT_HOME (default: ~/.config/onboarder/agent).\n\n  onboarder agent ask . --task \"Explain the authentication flow\"\n  onboarder agent review . --pr 42 --task \"Find correctness and security issues\"\n  onboarder agent triage . --issue 12 --task \"Investigate and propose a fix\"\n  onboarder agent implement . --task \"Fix issue 12\" --issue 12 --allow-checks\n  onboarder agent pr . --task \"Fix issue 12 and open a draft PR\" --issue 12 --allow-checks --allow-github-writes\n`;\nexport const AGENT_OPTIONS = {\n  task: { type: 'string' as const }, pr: { type: 'string' as const }, issue: { type: 'string' as const },\n  'max-turns': { type: 'string' as const }, timeout: { type: 'string' as const }, resume: { type: 'string' as const },\n  'allow-checks': { type: 'boolean' as const }, 'allow-github-writes': { type: 'boolean' as const }, 'dry-run': { type: 'boolean' as const },\n  model: { type: 'string' as const }, provider: { type: 'string' as const }, json: { type: 'boolean' as const }, help: { type: 'boolean' as const, short: 'h' },\n  base: { type: 'string' as const },\n};\nexport async function agentDoctor(home = agentHome(), env: NodeJS.ProcessEnv = process.env) {\n  const paths = runtimePaths(home, env);\n  let runtime = false, compatible = false, detail = '';\n  try {\n    const result = await runProcess(hermesBinary(env), ['chat', '--help'], { env: hermesEnvironment(home, env), timeoutMs: 30_000, maxBytes: 128000 });\n    runtime = result.code === 0;\n    compatible = runtime && ['--query-file', 'stream-json', '--toolsets', '--run-budget', '--ignore-rules', '--no-restore-cwd'].every(s => result.stdout.includes(s));\n    if (!compatible) detail = result.code ? result.stderr.slice(-2000) || 'Hermes could not start.' : 'Update Hermes to a runtime supporting structured one-shot chat and MCP selection.';\n  } catch (e) { detail = redact(e instanceof Error ? e.message : String(e), env); }\n  const server = await fs.access(paths.server).then(() => true).catch(() => false);\n  const profile = await fs.access(path.join(paths.profile, 'config.yaml')).then(() => true).catch(() => false);\n  return { runtime, compatible, server, profile, githubToken: Boolean(githubToken(env)), home, ready: runtime && compatible && server && profile, detail,\n    next: !runtime ? 'Install Hermes from its official repository, then agent setup and agent model.' : !profile ? 'Run onboarder agent setup, then onboarder agent model.' : 'Model credentials are checked by Hermes when a task runs; use agent model to configure them.' };\n}\nexport async function fetchHermesSource(home = agentHome(), signal?: AbortSignal) {\n  const target = path.join(home, 'upstream', 'hermes-agent');\n  await fs.mkdir(path.dirname(target), { recursive: true, mode: 0o700 });\n  const git = async (args: string[]) => {\n    const output = await runProcess('git', ['-c', 'http.version=HTTP/1.1', ...args], { signal, timeoutMs: 120_000, maxBytes: 2 * 1024 * 1024 });\n    if (output.code) throw new Error(`Hermes source fetch failed: ${output.stderr.slice(-1500)}`);\n    return output.stdout.trim();\n  };\n  if (!await fs.access(target).then(() => true).catch(() => false)) {\n    const staging = target + '-' + randomUUID();\n    try { await git(['clone', '--depth', '1', '--no-checkout', '--', HERMES_SOURCE, staging]); await fs.rename(staging, target); }\n    finally { await fs.rm(staging, { recursive: true, force: true }); }\n  }\n  if (await git(['-C', target, 'remote', 'get-url', 'origin']) !== HERMES_SOURCE) throw new Error('The source cache origin is not the official Hermes repository.');\n  if (await git(['-C', target, 'status', '--porcelain']) && await fs.access(path.join(target, 'LICENSE')).then(() => true).catch(() => false)) throw new Error('The source cache contains edits. Preserve them before updating it.');\n  await git(['-C', target, 'fetch', '--depth', '1', 'origin', HERMES_REVISION]);\n  await git(['-C', target, '-c', 'core.hooksPath=' + path.join(home, 'empty-hooks'), 'checkout', '--detach', HERMES_REVISION]);\n  return { source: HERMES_SOURCE, revision: HERMES_REVISION, directory: target, license: 'MIT', installed: false };\n}\n\nexport async function agentCommand(sub = 'help', positionals: string[] = [], flags: Record<string, any> = {}, options: { root?: string; signal?: AbortSignal; out?: (text: string) => void; err?: (text: string) => void } = {}) {\n  const out = options.out || console.log, err = options.err || console.error, home = agentHome();\n  const print = (value: unknown) => out(typeof value === 'string' ? value : JSON.stringify(value, null, 2));\n  if (flags.help || sub === 'help') { out(AGENT_HELP); return 0; }\n  if (sub === 'setup') {\n    const result = await prepareAgentProfile(home, process.env, options.signal);\n    print(flags.json ? result : `Dedicated Hermes profile: ${result.profile}\\n${result.created ? 'Created.' : 'Existing model settings preserved.'} Run onboarder agent model to configure its provider.\\nRun onboarder agent doctor to check the integration.`); return 0;\n  }\n  if (sub === 'doctor') { const report = await agentDoctor(home); print(report); return report.ready ? 0 : 1; }\n  if (sub === 'source') { print(await fetchHermesSource(home, options.signal)); return 0; }\n  if (sub === 'model') {\n    if (!process.stdin.isTTY) throw new Error('Run onboarder agent model in an interactive terminal.');\n    await setupAgent(home);\n    return new Promise<number>((resolve, reject) => {\n      const child = spawn(hermesBinary(), ['model'], { env: hermesEnvironment(home), stdio: 'inherit', shell: false, signal: options.signal });\n      child.on('error', reject); child.on('close', code => resolve(code ?? 1));\n    });\n  }\n  if (sub === 'runs') {\n    const names = await fs.readdir(runtimePaths(home).runs).catch(e => { if (e.code !== 'ENOENT') throw e; return []; });\n    const runs = (await Promise.all(names.filter(n => /^[a-f\\d-]{36}$/.test(n)).map(async id => {\n      try { const { manifest, result } = await savedRun(id, home); return { id, mode: manifest.mode, status: result?.status || 'unfinished', startedAt: manifest.startedAt, workspace: manifest.root, repository: manifest.repository }; }\n      catch { return { id, status: 'unreadable' }; }\n    }))).sort((a, b) => (b.startedAt || '').localeCompare(a.startedAt || ''));\n    print(runs); return 0;\n  }\n  if (sub === 'show') { print(await savedRun(positionals[0] || '', home)); return 0; }\n  if (!AGENT_MODES.includes(sub as AgentMode)) throw new Error('Unknown agent workflow. Run onboarder agent --help.');\n  if (positionals.length > 1) throw new Error('Use one repository folder and --task \"your task\".');\n  const task = flags.task || (sub === 'review' ? `Review ${flags.pr ? 'pull request ' + flags.pr : 'local changes'} for actionable correctness and security issues.` : sub === 'triage' ? `Investigate ${flags.issue ? 'issue ' + flags.issue : 'open issues'} and propose a prioritized plan.` : '');\n  const result = await runAgent({ mode: sub as AgentMode, root: positionals[0] || options.root || '.', task,\n    pr: flags.pr === undefined ? undefined : Number(flags.pr), issue: flags.issue === undefined ? undefined : Number(flags.issue),\n    maxTurns: flags.maxTurns === undefined ? flags['max-turns'] : flags.maxTurns, timeoutSeconds: flags.timeout,\n    allowChecks: flags.allowChecks || flags['allow-checks'], allowGithubWrites: flags.allowGithubWrites || flags['allow-github-writes'], dryRun: flags.dryRun || flags['dry-run'],\n    model: flags.model, provider: flags.provider, resume: flags.resume, base: flags.base }, { signal: options.signal,\n    onEvent: event => {\n      if (event.type === 'tool_use') err(`  ${terminalText(event.name || 'Tool')}…`);\n      if (event.type === 'tool_result' && event.is_error) err(`  ${terminalText(event.name || 'Tool')} reported an error.`);\n    } });\n  if ('dryRun' in result || flags.json) print(result);\n  else out(`${terminalText(result.answer)}\\n\\nRun: ${result.id} (${result.status})\\nWorkspace: ${result.workspace}${result.branch ? '\\nBranch: ' + result.branch : ''}`);\n  return 'dryRun' in result || result.status === 'completed' ? 0 : result.status === 'cancelled' ? 130 : 1;\n}\n\nexport async function explorerAgent(args: string[], root: string, signal: AbortSignal, out: (text: string) => void, err: (text: string) => void) {\n  const parsed = parseArgs({ args, options: AGENT_OPTIONS, allowPositionals: true });\n  await agentCommand(parsed.positionals[0], parsed.positionals.slice(1), parsed.values, { root, signal, out, err });\n  return '';\n}\n"]}

package/cli/agent/config.d.ts

@@ -0,0 +1,31 @@
+export declare const HERMES_SOURCE = "https://github.com/NousResearch/hermes-agent.git";
+export declare const HERMES_REVISION = "eb7e8620324b32424c06218f6a28094df2e921f8";
+export declare function agentHome(env?: NodeJS.ProcessEnv): string;
+export declare function hermesBinary(env?: NodeJS.ProcessEnv): string;
+export declare function runtimePaths(home?: string, env?: NodeJS.ProcessEnv): {
+    home: string;
+    profile: string;
+    runs: string;
+    workspaces: string;
+    server: string;
+};
+export declare function hermesEnvironment(home?: string, env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function setupAgent(home?: string, env?: NodeJS.ProcessEnv): Promise<{
+    home: string;
+    profile: string;
+    runs: string;
+    workspaces: string;
+    server: string;
+    configFile: string;
+    created: boolean;
+}>;
+/** Refresh only harness-owned settings; retain the model wizard's provider/auth choices. */
+export declare function prepareAgentProfile(home?: string, env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<{
+    home: string;
+    profile: string;
+    runs: string;
+    workspaces: string;
+    server: string;
+    configFile: string;
+    created: boolean;
+}>;