@phuetz/code-buddy 1.2.0 → 1.3.1

package/README.md

@@ -17,7 +17,7 @@
 <p align="center">
   <a href="https://github.com/phuetz/code-buddy/stargazers"><img src="https://img.shields.io/github/stars/phuetz/code-buddy?style=flat-square&logo=github&color=feca57&label=Star" alt="GitHub stars"/></a>
   <img src="https://img.shields.io/badge/Tests-27K%2B-00d26a?style=flat-square&logo=jest" alt="Tests"/>
-  <img src="https://img.shields.io/badge/v1.2.0-GA-blueviolet?style=flat-square" alt="Version 1.2.0 GA"/>
+  <img src="https://img.shields.io/badge/v1.3.1-GA-blueviolet?style=flat-square" alt="Version 1.3.1 GA"/>
 </p>
 
 <br/>
@@ -45,7 +45,7 @@ Watch a **local model reason on screen, then use real tools to do the work** —
 [Proof ✅](docs/proof.md) ·
 [Quick Start](#quick-start) ·
 [In action](#in-action) ·
-[Features](#features) ·
+[What it does](#what-code-buddy-does) ·
 [FAQ](docs/faq.md) ·
 [Docs](#documentation) ·
 [Contributing](#contributing)
@@ -62,6 +62,12 @@ An open-source, multi-provider AI coding agent with a terminal UI, an HTTP/WebSo
 
 ## In action
 
+**It writes the code *and* the test, then runs it — `$0`.** Hand Code Buddy a task in the terminal; here Grok (a flat-fee subscription, no API key) writes FizzBuzz + a test and runs it green — then a human re-runs the test to confirm. Unedited:
+
+<p align="center">
+  <img src="docs/assets/coding-demo.gif" alt="Code Buddy writes fizzbuzz.mjs and a test on Grok, runs it, and the test passes — $0, no API key" width="760"/>
+</p>
+
 **Free local AI, with the reasoning on screen.** A local Ollama model (`qwen3.6:35b-a3b`) thinks through a task, then *uses tools* to do it — no cloud, ~`$0.0001`. Unedited captures from the Cowork desktop app:
 
 <table>
@@ -83,6 +89,12 @@ An open-source, multi-provider AI coding agent with a terminal UI, an HTTP/WebSo
   <img src="docs/screenshots/chatgpt-oauth-login.png" alt="ChatGPT OAuth login flow" width="820"/>
 </p>
 
+**xAI / SuperGrok login** — `buddy login xai`, sign in once, then Grok answers for `$0` (flat-fee subscription, no API key):
+
+<p align="center">
+  <img src="docs/assets/login-demo.gif" alt="After buddy login xai, Grok writes a haiku with no API key, $0 marginal" width="760"/>
+</p>
+
 **Self-audit.** Asked to find a bug in its own integration code, `gpt-5.5` reads `provider-chatgpt-responses.ts`, spots a stale-variable issue (mutated `body.model` not propagated), and proposes the exact fix:
 
 <p align="center">
@@ -108,6 +120,23 @@ More desktop demos (Fleet, Autonomy, Companion, …) and captures: [`cowork/read
 
 ---
 
+## Research — a sensory "nervous system" *(experimental)*
+
+Toward the long-term companion/robot vision, [`buddy-sense/`](buddy-sense/) is a **Rust, event-driven perception layer**. Parallel **sense modules** (audio VAD — energy or Silero neural; an autonomic **heartbeat**; screen via `xcap`; UI focus via AT-SPI) feed a **thalamus** that gates + coalesces the stream and broadcasts it over a loopback WebSocket into Code Buddy's event bus — where the heartbeat **paces background memory consolidation** ("dreaming", inspired by OpenClaw). Local, `$0`, permissive deps only (clean-room — no proprietary code copied).
+
+<p align="center"><img src="buddy-sense/docs/architecture.svg" alt="buddy-sense nervous-system architecture: senses → thalamus → bridge → Code Buddy event bus" width="840"/></p>
+
+**Honestly experimental** — distinct from the GA core above: the default daemon emits the heartbeat (+ audio from a WAV file); the live camera/mic aren't wired into the daemon yet. `speech → STT → 'hearing' percept` **is** wired (faster-whisper), with a hook left for driving a full agent turn. What's real today: the pure detector cores + thalamus + bridge are unit-tested (`cargo test`, 20 tests, no hardware), and the loopback bridge → event bus → reaction path (incl. the speech transcription) is covered on the Code Buddy side.
+
+```bash
+cd buddy-sense && cargo test     # 20 tests, no hardware
+./buddy-sense/demo.sh            # headless end-to-end: heartbeat + audio VAD → Code Buddy
+```
+
+Design, the five sense modules, the opt-in features, and the diagrams: [`buddy-sense/README.md`](buddy-sense/README.md).
+
+---
+
 ## Quick Start
 
 ```bash
@@ -154,6 +183,18 @@ buddy llm ensemble "is this approach sound?" # ask ChatGPT + Grok + Ollama toget
 CODEBUDDY_LLM_FAILOVER=1 buddy -p "…"         # if the primary errors, auto-continue on the next active LLM
 ```
 
+<p align="center">
+  <img src="docs/assets/llm-demo.gif" alt="buddy llm lists your active LLMs, then auto-fails over from Grok to ChatGPT when the primary errors" width="760"/>
+  <br/>
+  <sub>Your logins at a glance — and automatic failover from one to the next when one has a problem, at <code>$0</code>. Real run, unedited.</sub>
+</p>
+
+<p align="center">
+  <img src="docs/assets/ensemble-demo.gif" alt="buddy llm ensemble asks ChatGPT, Ollama and Grok the same question, then synthesizes one answer" width="760"/>
+  <br/>
+  <sub><code>buddy llm ensemble</code> — every brain you're logged into answers, then it's synthesized into one. Real run, unedited.</sub>
+</p>
+
 See [Getting Started](docs/getting-started.md) for install options, headless mode, sessions, and typical workflows.
 
 ---
@@ -168,10 +209,22 @@ Cowork is the desktop cockpit for Code Buddy: chat, tools, traces, workflows, se
   <sub>Real <code>gpt-5.5</code> in the Cowork desktop app — the answer streams in, cost <code>$0.0000</code>. <a href="docs/qa/code-buddy-studio/showcase-2026-06-16/cowork-chat-stream.mp4">MP4 →</a></sub>
 </p>
 
+<p align="center">
+  <a href="docs/assets/cowork-chat-demo.mp4"><img src="docs/assets/cowork-chat-demo.gif" alt="A local reasoning model thinks through a haiku on screen in the Cowork desktop app, $0" width="760"/></a>
+  <br/>
+  <sub>…and fully local: a reasoning model (<code>qwen3.6:35b-a3b</code>) <b>thinks on screen</b>, then answers — no cloud, <code>$0</code>. <a href="docs/assets/cowork-chat-demo.mp4">MP4 →</a></sub>
+</p>
+
+<p align="center">
+  <a href="docs/assets/cowork-panels-demo.mp4"><img src="docs/assets/cowork-panels-demo.gif" alt="The Cowork left rail opens the Autonomy dashboard, Memory and other panels as dock tabs" width="760"/></a>
+  <br/>
+  <sub>The left rail opens every panel as a dock tab — here the <b>Autonomy dashboard</b> (24/7 daemon, free-first model ladder, live subagents) and <b>Project Memory</b>. <a href="docs/assets/cowork-panels-demo.mp4">MP4 →</a></sub>
+</p>
+
 <table>
   <tr>
-    <td width="50%" align="center"><img src="docs/qa/code-buddy-studio/showcase-2026-06-16/00-welcome.png" alt="Cowork desktop cockpit" width="430"/><br/><sub>Desktop cockpit — menus, sessions, composer</sub></td>
-    <td width="50%" align="center"><img src="docs/qa/code-buddy-studio/showcase-2026-06-16/05-onboarding-provider.png" alt="Onboarding — pick a provider" width="430"/><br/><sub>Onboarding — 15 providers, ChatGPT <code>$0</code> or local Ollama</sub></td>
+    <td width="50%" align="center"><img src="docs/assets/cowork-welcome.png" alt="Cowork desktop home with the expanded left menu and quick-action cards" width="430"/><br/><sub>Home — expanded menu, quick-action cards, gradient hero</sub></td>
+    <td width="50%" align="center"><img src="docs/assets/cowork-panel.png" alt="A launcher opens its panel as a tab — here the Autonomy dashboard" width="430"/><br/><sub>A launcher opens its panel as a tab — here the Autonomy dashboard (daemon, model ladder, subagents)</sub></td>
   </tr>
   <tr>
     <td width="50%" align="center"><img src="docs/qa/code-buddy-studio/showcase-2026-06-16/03-fleet-autonomy.png" alt="Fleet and autonomy dashboard" width="430"/><br/><sub>Fleet dispatch · tool-permission posture · Hermes toolsets</sub></td>
@@ -226,26 +279,68 @@ The CLI guards this: on Node < 22, `buddy gui` prints a clear upgrade message in
 
 ---
 
-## Features
-
-| Category | Highlights | Docs |
-|:---------|:-----------|:-----|
-| **AI Providers** | 15 providers (Grok, Claude, GPT, Gemini, Ollama, LM Studio, AWS Bedrock, Azure, Groq, Together, Fireworks, OpenRouter, vLLM, Copilot, Mistral), circuit breaker, model pairs | [providers.md](docs/providers.md) |
-| **Tools** | ~110 tools with RAG selection, multi-strategy edit matching, Codex-style `apply_patch`, streaming, BM25 tool search, code-exec sandbox | [tools-reference.md](docs/tools-reference.md) |
-| **Commands** | 190+ slash commands & CLI subcommands (`/goal`, `/dev`, `/pr`, `/lint`, `/switch`, `/think`, `/batch`, …) | [commands.md](docs/commands.md) |
-| **Cowork Desktop** | Electron cockpit, embedded engine, backend health/start controls, model settings, permission rules, visual workflows, traces, artifacts, MCP/skills/plugins | [cowork.md](docs/cowork.md), [ARCHITECTURE.md](cowork/ARCHITECTURE.md) |
-| **Agents** | Multi-agent orchestration (5-tool API), 8 specialized agents, SWE agent, planning flow, A2A protocol, batch decomposition, agent teams | [agents.md](docs/agents.md) |
-| **Goal loops** | `/goal` + `/subgoal` Ralph loop — a judge model re-checks completion every turn and auto-continues until done (turn budget, pause/resume, fail-open); headless `buddy goal`, board goal-mode, peer-session goals | [fleet-guide.md](docs/fleet-guide.md) |
-| **Reasoning** | Tree-of-Thought + MCTS (4 depth levels), extended thinking, auto-escalation, `/think` | [reasoning.md](docs/reasoning.md) |
-| **Fleet & Autonomy** | Peer-to-peer hub (`peer.chat` / `peer.tool.invoke` / `peer_delegate`), A2A + ACP + MCP interop, 24/7 autonomous service (`buddy autonomy install`), event-driven daemon, free-first local→Tailscale→paid tiering | [fleet-guide.md](docs/fleet-guide.md) |
-| **Security** | Guardian Agent (AI risk scoring), OS/Docker/OpenShell sandbox, SSRF guard, secrets vault, write/exec policy, loop & omission detection, output sanitizer | [security.md](docs/security.md) |
-| **Context Engine** | Smart compression, tool-output masking, image pruning, transcript repair, pre-compaction flush, JIT context, importance-weighted window | [context-engine.md](docs/context-engine.md) |
-| **Channels** | 20+ messaging channels (Telegram, Discord, Slack, WhatsApp, Signal, Teams, Matrix, …), DM pairing, send policy | [channels.md](docs/channels.md) |
-| **Companion & Vision** | ChatGPT-backed identity, voice/TTS, proactive check-ins, self-evaluation, mission board; opt-in webcam + MediaPipe face/hand/pose percepts, local face enrollment | [commands.md](docs/commands.md) |
-| **Memory & Knowledge** | Persistent + semantic + decision + coding-style memory, cross-session ICM, knowledge-base injection, 40 bundled skills, runtime self-authored skills | [context-engine.md](docs/context-engine.md) |
-| **Infrastructure** | HTTP server (OpenAI-compatible), WebSocket gateway, daemon, cron, device nodes, canvas/A2UI, cloud deploy configs, MCP, plugins | [infrastructure.md](docs/infrastructure.md) |
-| **Configuration** | Env vars, TOML config with profiles, model-aware limits, per-agent params, i18n (6 locales), personas | [configuration.md](docs/configuration.md) |
-| **Git & Code Intel** | Auto-commit (Aider-style), `/pr`, merge-conflict resolver, LSP rename/refactor, bug finder (25+ patterns, 6 langs), OpenAPI generator, IDE extensions | [development.md](docs/development.md) |
+## What Code Buddy does
+
+Code Buddy is one engine — terminal, desktop, and HTTP — that an LLM drives to read code, edit files, run commands, search the web, open PRs, and plan complex work. Below is the whole surface, explained. Jump to any area:
+
+| Area | In one line | Deep dive |
+|:-----|:------------|:----------|
+| [Providers & login](#providers--login) | 15 LLM providers + ChatGPT/xAI login at **$0** flat-fee, auto-failover, ensembles | [providers.md](docs/providers.md) |
+| [The agentic loop](#the-agentic-loop) | autonomous tool-calling with a middleware pipeline + confirm-before-execute | [CLAUDE.md](CLAUDE.md) |
+| [~110 tools](#110-tools) | edit/shell/web/browser/docs/media, RAG-selected, 5-strategy edit matching | [tools-reference.md](docs/tools-reference.md) |
+| [Reasoning](#reasoning) | extended thinking + Tree-of-Thought / MCTS, `/think` | [reasoning.md](docs/reasoning.md) |
+| [Goal loops & autonomy](#goal-loops--autonomy) | Ralph loop + LLM judge, YOLO, a 24/7 daemon | [fleet-guide.md](docs/fleet-guide.md) |
+| [Multi-AI Fleet](#multi-ai-fleet) | peers call each other's models + read-only tools over WebSocket | [fleet-guide.md](docs/fleet-guide.md) |
+| [Self-improvement](#self-improvement) | authors + empirically gates its own tools/skills (opt-in) | [CLAUDE.md](CLAUDE.md) |
+| [Skills](#skills) | 40 bundled (Office/research/automation) + authored + imported, firewalled | [commands.md](docs/commands.md) |
+| [Memory & context](#memory--context) | compression, importance-weighted window, JIT project context | [context-engine.md](docs/context-engine.md) |
+| [Security & sandboxing](#security--sandboxing) | Guardian risk-scorer, permission modes, sandbox tiers, SSRF guard, secrets | [security.md](docs/security.md) |
+| [Server & infrastructure](#server--infrastructure) | OpenAI-compatible HTTP, WS gateway, daemon, cron | [infrastructure.md](docs/infrastructure.md) |
+| [Channels](#channels) | 20+ messaging platforms with DM-pairing access control | [channels.md](docs/channels.md) |
+| [Git & code intelligence](#git--code-intelligence) | auto-commit, `/pr`, LSP rename, bug finder, the Code Explorer graph | [development.md](docs/development.md) |
+| [Config & modes](#config--modes) | TOML profiles, permission/agent/security modes, model-aware limits | [configuration.md](docs/configuration.md) |
+
+### Providers & login
+Code Buddy talks to **15 LLM providers** through one OpenAI-compatible dispatcher (`src/codebuddy/client.ts`), picking exactly one strategy at startup: Grok, Claude, GPT, Gemini, Ollama, LM Studio, AWS Bedrock, Azure, Groq, Together, Fireworks, OpenRouter, vLLM, Copilot, Mistral. **`buddy login`** signs into a ChatGPT Plus/Pro subscription (routed via OpenAI's Codex Responses backend) and **`buddy login xai`** into SuperGrok — both **flat-fee, no API key, cost reported `$0.0000`** (no per-token metering). Multiple logins coexist: **`buddy llm`** lists them, **`buddy llm ensemble "<q>"`** asks them all and synthesizes one answer, and `CODEBUDDY_LLM_FAILOVER=1` auto-continues on the next active LLM when one errors (per-provider circuit breakers). `[model_pairs]` in TOML splits an *architect* and *editor* model.
+
+### The agentic loop
+The core is a stateful multi-turn loop (`src/agent/execution/agent-executor.ts`, `runTurnLoop`): the LLM proposes tool calls, the executor validates + confirms + runs them, feeds results back, and loops until done or you stop. A **middleware pipeline** (`src/agent/middleware/`) adds turn/cost limits, reasoning injection, workflow guards, auto-repair, and quality gates in priority order. Before any risky action the **ConfirmationService** checks permission mode → declarative rules → session flags → the Guardian Agent, and fail-closed guards block catastrophic commands (`rm -rf /`, fork bombs, `drop database`). Run it interactively (`buddy`), one-shot (`buddy -p "<task>"`), or fully autonomous (`buddy --yolo`).
+
+### ~110 tools
+The agent has **~110 tools** — file edit, shell, web search (5-provider fallback), a real headless browser, PDF/Office, media/vision, code-exec, agent orchestration — and uses **RAG selection** to send only the relevant ones each turn (BM25 `tool_search` as fallback). Edits land even in refactored code via a **5-strategy cascade**: exact → flexible (trim/indent) → regex (tokenized) → fuzzy (Levenshtein 10%) → LCS (90%). It also speaks Codex-style **`apply_patch`**, and `code_exec` runs LLM-written JavaScript in a `vm` sandbox (no `process`/`require`, 30s). Extend it with MCP servers (auto-discovered from `.codebuddy/mcp.json`), plugins, or new tool classes.
+
+### Reasoning
+Two systems: **Extended Thinking** (provider budget tokens — off/minimal/low/medium/high/xhigh) and Code Buddy's own **Tree-of-Thought + MCTS** with four depths (shallow CoT → beam search → MCTS → exhaustive). A reasoning middleware auto-detects complex queries and injects guidance; `/think`, `/megathink`, and `/ultrathink` set the depth, and the `reason` tool streams its search. (MCTSr Q-value `Q(a) = 0.5·(min(R) + mean(R))`.)
+
+### Goal loops & autonomy
+A **goal loop** is autonomy with a referee: the agent acts, an LLM **judge** checks the goal after each turn, and it self-corrects until done or the turn budget runs out — no hand-written retry logic. Drive it with `/goal "<objective>"` + `/subgoal` (numbered criteria), or headless `buddy goal`. **`buddy --yolo`** grants 400 tool rounds under a `$100` cap with guardrails, and the **24/7 autonomous daemon** (`buddy autonomy install`) claims tasks from a shared queue and runs them free-first (local → Tailscale → paid).
+
+### Multi-AI Fleet
+Run several Code Buddy instances as **peers on a WebSocket mesh** that observe each other's events live and call each other's models + read-only tools: `peer.chat` (one-shot), `peer.chat-session.*` (multi-turn, persisted), and `peer.tool.invoke` (remote read-only tools, behind three security gates that fail closed). **`/fleet route "<prompt>"`** classifies a task, gathers peer capabilities, runs a privacy lint (SSN/IBAN/card detection), and recommends a delegation; `/fleet listen|send|status|history` manage the mesh. It interops over A2A + ACP + MCP.
+
+### Self-improvement
+An empirically-gated loop (`src/agent/self-improvement/`) that improves Code Buddy's *learned* layer — never its own `src/`. It can author its own **lessons**, **tools** (`register_tool`, sandboxed, namespaced `authored__*`), and **skills**, each passing a gate before it's kept: tools must pass **held-out** behavioral cases the proposer never sees (a tool that hardcodes the visible answers fails fresh inputs → rejected), and skills pass a prompt-injection **firewall**. It's **opt-in and off by default** (`CODEBUDDY_SELF_IMPROVE=true`); `buddy improve status|cycle|tools|skills` drive it.
+
+### Skills
+Skills are procedural guidance (Markdown + frontmatter + triggers) the agent discovers and injects by topic. **40 are bundled**, including ones that build real Office docs and run analysis in *visible* Python steps (preflight libs → write script → run → verify): `xlsx`/`docx`/`pptx`, `doc-ingest` (PDF/Office → Markdown), `data-charts` (pandas/matplotlib), `web-automate` (Playwright), `web-research` (cited briefs). The agent can also **author** its own skills and **import** external ones from Hermes / OpenClaw — every imported skill is scanned by a **firewall** that quarantines prompt-injection/exfiltration payloads (`buddy skills import|imported|list`).
+
+### Memory & context
+For long sessions, `ContextManagerV2` compresses with a sliding window + **importance-weighted scoring** (errors 0.95, decisions 0.90, code 0.70, chat 0.25 — high-value messages survive truncation), masks old tool output, prunes stale images, and repairs the transcript after compaction. **JIT context** loads nearby `CODEBUDDY.md`/`CONTEXT.md`/`AGENTS.md` files when a tool touches a path, and each turn injects `<lessons_context>` and `<todo_context>`. Durable facts persist to bounded project/user memory (`/memory recent|remember|recall`), security-scanned against injection/secret-exfiltration.
+
+### Security & sandboxing
+Layered, fail-closed safety: the **Guardian Agent** scores each operation 0–100 (auto-approve <80, prompt 80–90, deny ≥90; read-only tools skip the LLM call), **permission modes** (`plan`/`acceptEdits`/`dontAsk`/`bypassPermissions`), **sandbox tiers** (read-only / workspace-write / full-access via bubblewrap·landlock·seatbelt, with `.git`/`.ssh`/`.aws` always read-only), an **SSRF guard** (blocks private ranges + IPv4/IPv6 bypass vectors with a DNS check before every fetch), an AES-256-GCM **secrets vault** (`buddy secrets`), a **write policy** (`strict` forces `apply_patch`), and an **output sanitizer** that strips model-leakage tokens.
+
+### Server & infrastructure
+**`buddy server`** exposes an HTTP API (port 3000) including an **OpenAI-compatible `/api/chat/completions`**, plus a **WebSocket gateway** (3001) for desktop/mobile clients (device pairing, presence, Origin-hardened, JWT in production). A **daemon** runs 24/7 with auto-restart, a heartbeat checklist, daily session reset, and a cross-platform service installer (systemd/launchd/Task Scheduler). **Cron** scheduling (`buddy cron add`) supports no-LLM `--watchdog` monitors and `--pre-check` gates so an expensive LLM run only fires when something actually changed.
+
+### Channels
+Code Buddy runs on **20+ messaging platforms** — Telegram, Discord, Slack, WhatsApp, Signal, Matrix, IRC, Nostr, Mattermost, Nextcloud Talk, iMessage (real persistent transports with auto-reconnect) plus REST/webhook adapters (Teams, Google Chat, Feishu, LINE, ntfy, DingTalk, WeCom, …). **DM pairing** prevents unauthorized credit burn: an unknown user gets a 6-char code (15-min TTL) you approve via `buddy pairing approve`. (A few niche adapters — Twitch/Tlon/Gmail — are in-process stubs, and Feishu real-time *inbound* needs the Lark SDK installed.)
+
+### Git & code intelligence
+`buddy dev run` plans + implements + tests + **auto-commits** with a Conventional-Commit message; **`/pr`** opens a summarized PR; `lsp_rename`/`lsp_code_action` drive language servers for safe refactors; the **bug finder** flags 25+ patterns across 6 languages. For whole-repo understanding, the optional **Code Explorer** (the `gitnexus` MCP server) pre-indexes the repo into a knowledge graph with 31 tools for impact/blast-radius, coupling, hotspots, and execution traces. Code Buddy also runs as an **ACP** agent (`buddy acp`) so editors like Zed can drive it natively.
+
+### Config & modes
+Configure via env vars, **TOML profiles** (`[profiles.<name>]`, `buddy --profile`), and per-project `.codebuddy/settings.json`. **Permission modes** gate approvals, **agent modes** (`plan`/`code`/`ask`/`architect`) restrict the tool surface, and **security modes** (`suggest`/`auto-edit`/`full-auto`) tune the approval flow. Per-model capabilities (context window, max output, patch format) live in `src/config/model-tools.ts`. The UI ships in **English and French (complete)**; `de`/`es`/`ja`/`zh` are registered locale scaffolds that currently fall back to English.
 
 ---
 

package/dist/agent/autonomous/agentic-coding-contract.d.ts

@@ -58,15 +58,15 @@ export declare const agenticCodingApprovalDecisionSchema: z.ZodObject<{
 }, "strict", z.ZodTypeAny, {
     reason: string;
     decision: "rejected" | "approved";
-    kind: "agentic-coding-approval-decision";
     schemaVersion: 1;
+    kind: "agentic-coding-approval-decision";
     reviewer: string;
     decidedAt?: string | undefined;
 }, {
     reason: string;
     decision: "rejected" | "approved";
-    kind: "agentic-coding-approval-decision";
     schemaVersion: 1;
+    kind: "agentic-coding-approval-decision";
     reviewer: string;
     decidedAt?: string | undefined;
 }>;
@@ -108,6 +108,7 @@ export declare const agenticCodingWorkflowBuilderProposalSchema: z.ZodEffects<z.
     risks: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
     summary: string;
+    schemaVersion: 1;
     kind: "agentic-coding-workflow-builder-proposal";
     nodes: {
         type: "action" | "trigger" | "logic";
@@ -116,7 +117,6 @@ export declare const agenticCodingWorkflowBuilderProposalSchema: z.ZodEffects<z.
         description: string;
         agenticType: "edit" | "analysis" | "handoff" | "approval" | "verification" | "gate";
     }[];
-    schemaVersion: 1;
     edges: {
         source: string;
         target: string;
@@ -126,6 +126,7 @@ export declare const agenticCodingWorkflowBuilderProposalSchema: z.ZodEffects<z.
     coworkVisualizationNotes: string[];
 }, {
     summary: string;
+    schemaVersion: 1;
     kind: "agentic-coding-workflow-builder-proposal";
     nodes: {
         type: "action" | "trigger" | "logic";
@@ -134,7 +135,6 @@ export declare const agenticCodingWorkflowBuilderProposalSchema: z.ZodEffects<z.
         description: string;
         agenticType: "edit" | "analysis" | "handoff" | "approval" | "verification" | "gate";
     }[];
-    schemaVersion: 1;
     edges: {
         source: string;
         target: string;
@@ -144,6 +144,7 @@ export declare const agenticCodingWorkflowBuilderProposalSchema: z.ZodEffects<z.
     coworkVisualizationNotes?: string[] | undefined;
 }>, {
     summary: string;
+    schemaVersion: 1;
     kind: "agentic-coding-workflow-builder-proposal";
     nodes: {
         type: "action" | "trigger" | "logic";
@@ -152,7 +153,6 @@ export declare const agenticCodingWorkflowBuilderProposalSchema: z.ZodEffects<z.
         description: string;
         agenticType: "edit" | "analysis" | "handoff" | "approval" | "verification" | "gate";
     }[];
-    schemaVersion: 1;
     edges: {
         source: string;
         target: string;
@@ -162,6 +162,7 @@ export declare const agenticCodingWorkflowBuilderProposalSchema: z.ZodEffects<z.
     coworkVisualizationNotes: string[];
 }, {
     summary: string;
+    schemaVersion: 1;
     kind: "agentic-coding-workflow-builder-proposal";
     nodes: {
         type: "action" | "trigger" | "logic";
@@ -170,7 +171,6 @@ export declare const agenticCodingWorkflowBuilderProposalSchema: z.ZodEffects<z.
         description: string;
         agenticType: "edit" | "analysis" | "handoff" | "approval" | "verification" | "gate";
     }[];
-    schemaVersion: 1;
     edges: {
         source: string;
         target: string;

package/dist/agent/base-agent.d.ts

@@ -191,6 +191,10 @@ export declare abstract class BaseAgent extends EventEmitter implements Agent {
     getMCPTools(): Promise<Map<string, unknown[]>>;
     getMCPClient(): MCPClient;
     protected initializeMCP(): void;
+    /** Resolves once MCP server initialization has settled (or no-op if MCP was
+     * never started). Headless/one-shot callers await this so the gitnexus-style
+     * MCP tools are registered before the first turn instead of racing init. */
+    getMCPReady(): Promise<void>;
     getContextStats(): import("./facades/agent-context-facade.js").ContextStats;
     formatContextStats(): string;
     /**

package/dist/agent/base-agent.js

@@ -316,6 +316,12 @@ export class BaseAgent extends EventEmitter {
     initializeMCP() {
         this.infrastructureFacade.initializeMCP();
     }
+    /** Resolves once MCP server initialization has settled (or no-op if MCP was
+     * never started). Headless/one-shot callers await this so the gitnexus-style
+     * MCP tools are registered before the first turn instead of racing init. */
+    getMCPReady() {
+        return this.infrastructureFacade.getMCPReady();
+    }
     // ============================================================================
     // Context Management (delegates to contextFacade)
     // ============================================================================

package/dist/agent/facades/infrastructure-facade.d.ts

@@ -77,11 +77,18 @@ export declare class InfrastructureFacade {
      * Get the MCP client instance (for advanced operations)
      */
     getMCPClient(): MCPClient;
+    /** Resolves once initializeMCP() has finished connecting servers (or failed
+     * softly). Callers that need MCP tools available — notably headless one-shot
+     * runs — can await getMCPReady() instead of racing the fire-and-forget init. */
+    private mcpReady;
     /**
-     * Initialize MCP servers asynchronously
-     * This is a fire-and-forget operation
+     * Initialize MCP servers asynchronously. Kicks off in the background (the
+     * constructor path stays non-blocking), but the readiness promise is captured
+     * so a one-shot/headless caller can await getMCPReady() before its first turn.
      */
     initializeMCP(): void;
+    /** Promise that resolves when MCP server initialization has settled. */
+    getMCPReady(): Promise<void>;
     /**
      * Get the ICM bridge instance for memory operations
      */

package/dist/agent/facades/infrastructure-facade.js

@@ -67,12 +67,17 @@ export class InfrastructureFacade {
     getMCPClient() {
         return this.mcpClient;
     }
+    /** Resolves once initializeMCP() has finished connecting servers (or failed
+     * softly). Callers that need MCP tools available — notably headless one-shot
+     * runs — can await getMCPReady() instead of racing the fire-and-forget init. */
+    mcpReady = Promise.resolve();
     /**
-     * Initialize MCP servers asynchronously
-     * This is a fire-and-forget operation
+     * Initialize MCP servers asynchronously. Kicks off in the background (the
+     * constructor path stays non-blocking), but the readiness promise is captured
+     * so a one-shot/headless caller can await getMCPReady() before its first turn.
      */
     initializeMCP() {
-        (async () => {
+        this.mcpReady = (async () => {
             try {
                 const config = loadMCPConfig();
                 if (config.servers.length > 0) {
@@ -87,9 +92,13 @@ export class InfrastructureFacade {
             catch (error) {
                 logger.warn('MCP initialization failed', { error: getErrorMessage(error) });
             }
-        })().catch((error) => {
-            logger.warn('Uncaught error in MCP initialization', { error: getErrorMessage(error) });
-        });
+        })();
+        // Never let this become an unhandled rejection for callers that don't await.
+        void this.mcpReady.catch(() => { });
+    }
+    /** Promise that resolves when MCP server initialization has settled. */
+    getMCPReady() {
+        return this.mcpReady;
     }
     /**
      * Get the ICM bridge instance for memory operations

package/dist/agent/self-improvement/authored-artifact-gate.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Authored-artifact gate — the static (no-execution) safety scan applied to any
+ * code the agent authors for itself (tools or skill scripts) BEFORE it is run or
+ * registered. Blocking and ordered; the behavioural held-out scoring (which DOES
+ * run the code, sandboxed) lives in sandbox-scorer.ts and runs only after this.
+ *
+ * @module agent/self-improvement/authored-artifact-gate
+ */
+export interface ArtifactGateResult {
+    ok: boolean;
+    reasons: string[];
+}
+/**
+ * Statically inspect authored code. Returns ok=false with one or more reasons on
+ * any finding. `subsystem` selects the dangerous-pattern set ('code' for tools,
+ * 'skill' for skill scripts).
+ */
+export declare function inspectAuthoredCode(code: string, subsystem?: 'code' | 'skill'): ArtifactGateResult;

package/dist/agent/self-improvement/authored-artifact-gate.js

@@ -0,0 +1,42 @@
+/**
+ * Authored-artifact gate — the static (no-execution) safety scan applied to any
+ * code the agent authors for itself (tools or skill scripts) BEFORE it is run or
+ * registered. Blocking and ordered; the behavioural held-out scoring (which DOES
+ * run the code, sandboxed) lives in sandbox-scorer.ts and runs only after this.
+ *
+ * @module agent/self-improvement/authored-artifact-gate
+ */
+import { matchAllDangerousPatterns } from '../../security/dangerous-patterns.js';
+/** Omission placeholders that signal truncated / non-self-contained code. */
+const OMISSION_RE = /\/\/\s*\.\.\.\s*(rest|remaining|other|more|implementation|code)\b|#\s*\.\.\.\s*(rest|remaining)\b/i;
+/** Obvious secret shapes — never let an authored artifact embed these. */
+const SECRET_RE = /(sk-[a-z0-9]{16,}|api[_-]?key\s*[:=]\s*['"]?\S{12,}|-----BEGIN [A-Z ]*PRIVATE KEY-----|ghp_[a-zA-Z0-9]{20,}|AKIA[0-9A-Z]{16})/i;
+/** Writing under src/ is the hard self-modification invariant — refuse it. */
+const SRC_WRITE_RE = /(writeFile|writeFileSync|appendFile\w*|fs\.\w*write|open\s*\([^)]*['"]w|>>?\s*['"]?\.{0,2}\/?src\/)/i;
+const MAX_CODE_BYTES = 64 * 1024;
+/**
+ * Statically inspect authored code. Returns ok=false with one or more reasons on
+ * any finding. `subsystem` selects the dangerous-pattern set ('code' for tools,
+ * 'skill' for skill scripts).
+ */
+export function inspectAuthoredCode(code, subsystem = 'code') {
+    const reasons = [];
+    const text = String(code ?? '');
+    if (!text.trim())
+        reasons.push('code is empty');
+    if (text.length > MAX_CODE_BYTES)
+        reasons.push(`code too large (${text.length} > ${MAX_CODE_BYTES} bytes)`);
+    const dangerous = matchAllDangerousPatterns(text, subsystem);
+    if (dangerous.length > 0) {
+        reasons.push(`matched ${dangerous.length} dangerous pattern(s): ${dangerous.map((d) => d.description).slice(0, 4).join('; ')}`);
+    }
+    if (SECRET_RE.test(text))
+        reasons.push('looks like it embeds a secret');
+    if (OMISSION_RE.test(text))
+        reasons.push('contains an omission placeholder (not self-contained)');
+    if (/src\//.test(text) && SRC_WRITE_RE.test(text)) {
+        reasons.push('writes under src/ (forbidden self-modification invariant)');
+    }
+    return { ok: reasons.length === 0, reasons };
+}
+//# sourceMappingURL=authored-artifact-gate.js.map

package/dist/agent/self-improvement/authored-tool-runtime.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Authored-tool runtime — shared by `register_tool` (the live capability) and the
+ * self-improvement engine's sandbox scorer (the gate). One definition of "how an
+ * authored tool runs" so the thing we GATE is exactly the thing we REGISTER.
+ *
+ * An authored tool runs its `code` SANDBOXED: a throwaway cwd, RPC off (no
+ * callback into the tool system), and its call arguments arrive as JSON in the
+ * CODEBUDDY_TOOL_INPUT env var; the script prints its result to stdout.
+ *
+ * @module agent/self-improvement/authored-tool-runtime
+ */
+import type { ITool } from '../../tools/registry/types.js';
+import { type ExecuteCodeLanguage } from '../../tools/execute-code-runner.js';
+export declare const AUTHORED_PREFIX = "authored__";
+export declare const AUTHORED_LANGUAGES: ExecuteCodeLanguage[];
+export interface AuthoredToolSpec {
+    /** Namespaced tool name (see toAuthoredName). */
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    language: ExecuteCodeLanguage;
+    code: string;
+}
+/** Namespace + sanitize a raw tool name to `authored__<slug>` (never shadows a built-in). */
+export declare function toAuthoredName(raw: string): string;
+/** Build an ITool that runs the authored `code` sandboxed when invoked. */
+export declare function buildAuthoredTool(spec: AuthoredToolSpec): ITool;

package/dist/agent/self-improvement/authored-tool-runtime.js

@@ -0,0 +1,57 @@
+/**
+ * Authored-tool runtime — shared by `register_tool` (the live capability) and the
+ * self-improvement engine's sandbox scorer (the gate). One definition of "how an
+ * authored tool runs" so the thing we GATE is exactly the thing we REGISTER.
+ *
+ * An authored tool runs its `code` SANDBOXED: a throwaway cwd, RPC off (no
+ * callback into the tool system), and its call arguments arrive as JSON in the
+ * CODEBUDDY_TOOL_INPUT env var; the script prints its result to stdout.
+ *
+ * @module agent/self-improvement/authored-tool-runtime
+ */
+import * as os from 'os';
+import * as path from 'path';
+import { randomUUID } from 'crypto';
+import { executeCode } from '../../tools/execute-code-runner.js';
+export const AUTHORED_PREFIX = 'authored__';
+export const AUTHORED_LANGUAGES = ['javascript', 'typescript', 'python'];
+/** Namespace + sanitize a raw tool name to `authored__<slug>` (never shadows a built-in). */
+export function toAuthoredName(raw) {
+    const base = String(raw)
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+    return base.startsWith(AUTHORED_PREFIX) ? base : `${AUTHORED_PREFIX}${base || 'tool'}`;
+}
+/** Build an ITool that runs the authored `code` sandboxed when invoked. */
+export function buildAuthoredTool(spec) {
+    const { name, description, parameters, language, code } = spec;
+    return {
+        name,
+        description,
+        async execute(input) {
+            const rootDir = path.join(os.tmpdir(), `cb-authored-${randomUUID()}`);
+            try {
+                const res = await executeCode({ code, language, env: { CODEBUDDY_TOOL_INPUT: JSON.stringify(input ?? {}) } }, { rootDir, rpcEnabled: false });
+                if (!res.ok) {
+                    return {
+                        success: false,
+                        error: `authored tool "${name}" failed (exit ${res.exitCode}): ${res.stderr.slice(0, 2000) || res.error || 'no output'}`,
+                    };
+                }
+                return { success: true, output: res.stdout.slice(0, 100_000) || '(no stdout)' };
+            }
+            catch (err) {
+                return {
+                    success: false,
+                    error: `authored tool "${name}" error: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+        },
+        getSchema() {
+            return { name, description, parameters: parameters };
+        },
+    };
+}
+//# sourceMappingURL=authored-tool-runtime.js.map

package/dist/agent/self-improvement/authored-tool-store.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Authored-tool store — durable persistence for tools the agent has authored and
+ * kept (auto-apply). Without this, authored tools live only for the session; with
+ * it, they are reloaded into both registries at startup so a self-improvement
+ * survives a restart. A flat JSON file alongside the evolutionary archive.
+ *
+ * @module agent/self-improvement/authored-tool-store
+ */
+import type { AuthoredToolSpec } from './authored-tool-runtime.js';
+export declare const AUTHORED_TOOL_STORE_SCHEMA_VERSION = 1;
+export interface AuthoredToolStoreOptions {
+    workDir?: string;
+}
+export declare class AuthoredToolStore {
+    private readonly filePath;
+    constructor(options?: AuthoredToolStoreOptions);
+    get path(): string;
+    private read;
+    private write;
+    list(): AuthoredToolSpec[];
+    /** Upsert a spec by name (a re-authored tool replaces the prior version). */
+    add(spec: AuthoredToolSpec): void;
+    remove(name: string): boolean;
+}

package/dist/agent/self-improvement/authored-tool-store.js

@@ -0,0 +1,57 @@
+/**
+ * Authored-tool store — durable persistence for tools the agent has authored and
+ * kept (auto-apply). Without this, authored tools live only for the session; with
+ * it, they are reloaded into both registries at startup so a self-improvement
+ * survives a restart. A flat JSON file alongside the evolutionary archive.
+ *
+ * @module agent/self-improvement/authored-tool-store
+ */
+import fs from 'fs';
+import path from 'path';
+export const AUTHORED_TOOL_STORE_SCHEMA_VERSION = 1;
+export class AuthoredToolStore {
+    filePath;
+    constructor(options = {}) {
+        const root = options.workDir ?? process.cwd();
+        this.filePath = path.join(root, '.codebuddy', 'self-improvement', 'authored-tools.json');
+    }
+    get path() {
+        return this.filePath;
+    }
+    read() {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(this.filePath, 'utf-8'));
+            if (Array.isArray(parsed.tools)) {
+                return { schemaVersion: AUTHORED_TOOL_STORE_SCHEMA_VERSION, tools: parsed.tools };
+            }
+        }
+        catch {
+            /* no store yet */
+        }
+        return { schemaVersion: AUTHORED_TOOL_STORE_SCHEMA_VERSION, tools: [] };
+    }
+    write(file) {
+        fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+        fs.writeFileSync(this.filePath, JSON.stringify(file, null, 2), 'utf-8');
+    }
+    list() {
+        return this.read().tools;
+    }
+    /** Upsert a spec by name (a re-authored tool replaces the prior version). */
+    add(spec) {
+        const file = this.read();
+        file.tools = file.tools.filter((t) => t.name !== spec.name);
+        file.tools.push(spec);
+        this.write(file);
+    }
+    remove(name) {
+        const file = this.read();
+        const before = file.tools.length;
+        file.tools = file.tools.filter((t) => t.name !== name);
+        if (file.tools.length === before)
+            return false;
+        this.write(file);
+        return true;
+    }
+}
+//# sourceMappingURL=authored-tool-store.js.map