diff --git a/.ai/patchbay.example.toml b/.ai/patchbay.example.toml index 361fbf41..a81015b1 100644 --- a/.ai/patchbay.example.toml +++ b/.ai/patchbay.example.toml @@ -14,12 +14,19 @@ max_context_files = 30 max_patch_attempts = 3 max_repair_iterations = 2 +[profiles.economy] +provider = "reasonix_cli" +model = "deepseek-v4-pro" +command_key = "reasonix" +label = "Reasonix/DeepSeek" + [workflow] require_plan_approval = true default_branch_prefix = "patchbay" worktree_root = "../.patchbay-worktrees" fail_on_dirty_workspace = true apply_to_current_workspace_only_after_review_pass = true +allow_apply_without_tests = false # set true only for demo/mock repos that intentionally skip tests [commands_allowlist] test = [ diff --git a/.gitignore b/.gitignore index 6c64025e..721fa2d2 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,8 @@ .ai-flow-worktrees/ __pycache__/ *.pyc +web/node_modules/ +web/dist/ +web/*.tsbuildinfo +web/vite.config.d.ts +web/vite.config.js diff --git a/PLAN.md b/PLAN.md index 0261ca8d..b9d440fe 100644 --- a/PLAN.md +++ b/PLAN.md @@ -65,6 +65,7 @@ secret-like files, absolute paths, and path-traversal patterns. configuration, mock mode, and safety enforcement are implemented. **Recently shipped (v0.1.0 → current):** +- **Unified handoff context**: `patchbay context ` and `patchbay_context` synthesize status, gate state, next safe action, provider trail, artifacts, and timeline into one cross-host resume payload. - **Cross-host visibility**: `events.jsonl` per run + `patchbay events` CLI + `patchbay_events` MCP tool. Any host can inspect what every phase/agent did, including provider, model, action, and timestamps. - **Free phase-to-provider routing**: Any configured provider that advertises a role (plan/write/review/fix) can be assigned to any phase. Unsupported assignments fail with a clear error. - **Interactive configuration**: `patchbay config` wizard + `patchbay config set k v` + `patchbay doctor`. No hand-editing TOML required. @@ -74,10 +75,11 @@ configuration, mock mode, and safety enforcement are implemented. The project is actively maintained. -## Next Planned Feature: Custom Providers +## Custom Providers -User-defined provider entries (`[providers.]` TOML blocks) are planned for a -future release. The design covers: +User-defined CLI provider entries (`[providers.]` TOML blocks) are implemented +for the current runtime via `patchbay config provider add-cli`. The broader design +continues to track additional modes and stronger provider-specific controls: - Four execution modes: `cli_stdin`, `cli_stdout`, `http_api`, `acp` - Role capability mask (a single provider can be registered for planner, writer, @@ -85,13 +87,13 @@ future release. The design covers: - Output parsing contract (sentinel markers, JSON paths) - Safety constraints (path allowlists, deny patterns, execution blocking) -**This is a design document only — not yet implemented.** See -[docs/custom-providers-plan.md](docs/custom-providers-plan.md) for the full plan. +See [docs/custom-providers-plan.md](docs/custom-providers-plan.md) for the current +CLI baseline and the remaining HTTP/ACP roadmap. ## Pointers - [README.md](README.md) — English readme, quick start, config reference - [README.zh-CN.md](README.zh-CN.md) — Chinese readme - [docs/patchbay.md](docs/patchbay.md) — Full documentation (Chinese) -- [docs/custom-providers-plan.md](docs/custom-providers-plan.md) — Custom providers design (planned) +- [docs/custom-providers-plan.md](docs/custom-providers-plan.md) — Custom providers baseline and roadmap - [AGENTS.md](AGENTS.md) — Agent instruction block for MCP hosts diff --git a/README.md b/README.md index cba8739c..de85ac93 100644 --- a/README.md +++ b/README.md @@ -33,40 +33,64 @@ commands = ["python -m unittest discover -s tests -v"] timeout = 900 ``` +The default cost profile keeps expensive reasoning in plan/review and sends high-volume implementation and repair work to the lower-cost Reasonix/DeepSeek writer. If the Reasonix command is not configured yet, readiness will surface a `configure_reasonix_command` action before it offers `start_new_task`; send `patchbay agent message "configure reasonix command" --json` to set the default executable, or `patchbay agent message "configure reasonix command to " --json` for a full local path, without starting a model run. The same readiness payload also exposes `configure_deepseek_provider` so a desktop/MCP/Skill client can offer the custom DeepSeek CLI writer template as a low-cost alternative. Localized conversational prompts such as `配置 Reasonix 命令` and `把 Reasonix 命令设为 ` are accepted through the same Agent and MCP entry points. Reapply the routing profile at any time with `patchbay config profile apply economy`. + Legacy `[models]`, `[commands]`, and `[writer].provider` keys remain supported as defaults. Each CLI phase may use either `command_key` to reference `[commands]` or `command` for an inline command. `apply` has no model executor; it applies the reviewed `FINAL.diff` only after tests and review pass. ## What It Provides -- CLI workflow: `plan`, `approve`, `write`, `test`, `review`, `fix`, `status`, `diff`, `apply`, `cleanup`. -- MCP tools: `patchbay_plan`, `patchbay_approve`, `patchbay_write`, `patchbay_test`, `patchbay_review`, `patchbay_fix`, `patchbay_status`, `patchbay_events`, `patchbay_runs`, `patchbay_artifact`, `patchbay_config_show`, `patchbay_config_phase_set`, `patchbay_config_command_set`, `patchbay_config_test_add`, `patchbay_config_provider_add_cli`, `patchbay_diff`, `patchbay_apply`. +- CLI workflow: `setup`/`install`, `doctor`, `agent message`, `web`, `plan`, `approve`, `write`, `test`, `review`, `fix`, `cancel`, `status`, `context`, `metrics`, `trace`, `diff`, `apply`, `cleanup`. +- MCP tools: `patchbay_agent`, `patchbay_setup`, `patchbay_install`, `patchbay_plan`, `patchbay_approve`, `patchbay_write`, `patchbay_test`, `patchbay_review`, `patchbay_fix`, `patchbay_cancel`, `patchbay_status`, `patchbay_context`, `patchbay_metrics`, `patchbay_doctor`, `patchbay_skill_install`, `patchbay_skill_print`, `patchbay_skill_doctor`, `patchbay_events`, `patchbay_trace`, `patchbay_runs`, `patchbay_artifact`, `patchbay_config_show`, `patchbay_config_phase_set`, `patchbay_config_command_set`, `patchbay_config_test_add`, `patchbay_config_profile_apply`, `patchbay_config_profile_show`, `patchbay_config_provider_add_cli`, `patchbay_diff`, `patchbay_apply`. - Legacy MCP aliases: `ai_flow_*`. - Isolated git worktrees by default. - File-backed run artifacts under `.ai/runs//`. - Human approval gate before implementation. -- Patch safety checks and read-only reviewer verification. -- **Cross-host visibility**: `patchbay events ` and `patchbay_status` reveal what every phase/agent did, including provider, model, action, and timestamps — from any MCP host. +- Patch safety checks, read-only reviewer verification, and a default apply gate that treats skipped tests as not passed unless `workflow.allow_apply_without_tests = true`. +- **Cross-host visibility**: `patchbay context ` / `patchbay_context` is the preferred resume call. It returns the current gate state, next safe action, provider trail, artifacts, timeline, top-level `routing_evidence` / `efficiency_summary`, and `run_metrics` efficiency evidence in one handoff digest. `run_metrics.routing_evidence` shows whether write/fix are configured for the Reasonix/DeepSeek economy route, whether the Reasonix command can execute, and whether provider events have actually observed it; missing or mismatched explicit `command_key` evidence is treated as routing drift instead of verified economy evidence. `routing_evidence.economy_health` and `agent_activity.health_cards` expose the same signal as machine-readable `healthy`, `pending_evidence`, `command_not_ready`, `drift`, or `not_configured` states, plus an `economy_efficiency` card summarizing `efficiency_summary` for desktop and MCP clients. `patchbay_metrics` also returns top-level `actions[]` and `action_groups[]` mirrored from `routing_evidence.actions[]`, so clients can render safe routing follow-ups such as applying the economy profile, configuring Reasonix, or opening the Trace tab without parsing `economy_health.next_action`. Readiness and setup responses include top-level `routing`, `recommendations`, recommendation-derived `next_actions`, and the same structured action contract; `help` also exposes local-only setup plus host-specific setup/readiness shortcut actions for Codex, Claude Code, Claude Desktop, and Gemini CLI. `patchbay events ` and `patchbay_status` remain available for focused inspection. +- **Run inbox**: `patchbay runs` now prints a human-readable Agent inbox, while `patchbay runs --inbox` shows only the queue summary and `patchbay runs --focus` expands the highest-priority run with its next action. `patchbay runs --json`, `patchbay_runs`, and stateless Agent `status` / `runs` replies still return `runs.inbox` plus per-run `inbox`, `actions[]`, and `action_groups[]`. The inbox groups runs as running, needing plan approval, ready to apply, failed, ready to continue, inspect, or applied; `focus_run_id` points clients to the highest-priority run. Gated next actions such as `approve_and_run` and `apply` are marked `safe: false` and include `requires_confirmation`, while `open_run`, diagnostics, and polling remain safe local controls. +- **Agent help surface**: `patchbay agent message "help" --json` and `patchbay_agent` help prompts return `capabilities[]` summaries alongside safe `actions[]` and `action_groups[]`, so desktop/MCP/Skill clients can render what the Agent can do without parsing prose. When a concrete `run_id` is supplied, help also returns selected-run `gate_diagnosis.next_action`, `next_action`, status/context, and safe diagnostic/setup actions without advancing gates. +- **Failure recovery**: failed runs expose `failure_recovery` through `status`, `context`, and the conversational Agent, including the failed stage, suggested next action, priority artifacts, structured `actions[]`, and `action_groups[]` for safe inspection or replacement-task follow-ups. `patchbay_context` also lifts those safe recovery choices into `next_actions` / `agent_activity.next_action`, so desktop and MCP clients can show a primary diagnostic action without treating failure recovery as `continue` or `apply`. ## Quick Start ### npx-style (recommended) ```bash -uvx --from git+https://github.com/GenistarWynth/patchbay-mcp patchbay init -uvx --from git+https://github.com/GenistarWynth/patchbay-mcp patchbay-mcp --root /path/to/repo +uvx --from git+https://github.com/GenistarWynth/patchbay-mcp patchbay setup --host codex +uvx --from git+https://github.com/GenistarWynth/patchbay-mcp patchbay doctor +uvx --from git+https://github.com/GenistarWynth/patchbay-mcp patchbay web --port 8765 ``` +Then open `http://127.0.0.1:8765`. Use `patchbay-mcp --root /path/to/repo` only when a host asks for a raw stdio server command. + ### From a local checkout ```bash -python scripts/patchbay init -cp .ai/patchbay.example.toml .ai/patchbay.toml +python scripts/patchbay setup --host codex +python scripts/patchbay doctor +python scripts/patchbay web --port 8765 ``` +Then open `http://127.0.0.1:8765`. + ### Interactive configuration ```bash +patchbay setup --host codex # init + local config + Codex Skill + MCP registration attempt + doctor summary/recommendations +patchbay setup --host codex --no-mcp # local config + Codex Skill only; no MCP registration/probe follow-ups +patchbay install --host codex # alias for setup patchbay config # Interactive wizard — no hand-editing required -patchbay doctor # Validate your resolved phase configuration +patchbay config profile apply economy # keep write/fix on Reasonix + DeepSeek +patchbay agent message "apply economy profile" --json # same routing change through the conversational Agent +patchbay agent message "configure reasonix command" --json # set commands.reasonix; append `to ` or use `把 Reasonix 命令设为 ` +patchbay agent message "configure DeepSeek provider" --json # add a custom DeepSeek CLI provider template +patchbay agent message "configure DeepSeek provider to " --json # add the template and set providers..command +patchbay agent message "configure economy provider command to " --json # repair the active economy writer/fix provider command +patchbay doctor # Unified config/Skill readiness checks; skips stdio MCP probing by default +patchbay doctor --local-only # Readiness without MCP probe/register follow-up actions +patchbay doctor --probe-mcp # Add stdio MCP initialize/tools-list verification when needed +patchbay config --doctor # Validate your resolved phase configuration +patchbay config --set-key models.planner --set-value claude-opus-4-7 ``` Edit `.ai/patchbay.toml` for your local CLI commands, model names, provider, and test allowlist. Do not commit `.ai/patchbay.toml`; it is intentionally ignored. @@ -76,14 +100,68 @@ The old `scripts/ai-flow` command and `.ai/ai-flow.toml` config still work as co ## CLI Usage ```bash +python scripts/patchbay setup --host codex --json python scripts/patchbay plan --task "..." +python scripts/patchbay agent message "..." --json +python scripts/patchbay agent message "patchbay setup" --json +python scripts/patchbay agent message "patchbay setup for Claude Desktop" --json +python scripts/patchbay agent message status --json +python scripts/patchbay agent message context --json +python scripts/patchbay agent message readiness --json +python scripts/patchbay agent message "readiness for Claude Desktop" --json +python scripts/patchbay agent message "configure DeepSeek provider" --json +python scripts/patchbay agent message "configure DeepSeek provider to " --json +python scripts/patchbay agent message "configure economy provider command to " --json +python scripts/patchbay web --port 8765 +python scripts/patchbay runs +python scripts/patchbay runs --inbox +python scripts/patchbay runs --focus python scripts/patchbay approve python scripts/patchbay write python scripts/patchbay test python scripts/patchbay review -python scripts/patchbay apply +python scripts/patchbay cancel +python scripts/patchbay context +python scripts/patchbay metrics +python scripts/patchbay apply --confirmation apply_approved ``` +`metrics` includes phase duration/attempt counts, provider usage, token/cost availability, `efficiency_summary` for the verified economy token/cost/time share, and `routing_evidence` with `economy_health` for the write/fix economy route. `runs` includes an Agent inbox: the default text view shows the summary, groups, focus run, and run list; `--inbox` keeps the output to the summary/groups/focus; `--focus` prints the selected run's details and next command hints. Non-JSON `patchbay agent message runs` and `patchbay agent message status` use the same readable inbox renderer instead of dumping the structured payload. Non-JSON `patchbay status`, `patchbay context`, and their run-bound Agent equivalents render run state, gate state, background job summaries, failure recovery, Agent activity, health cards, routing/efficiency evidence, metrics, provider trail, artifacts, and grouped safe actions. Non-JSON active-background outputs expose `Background polling` and `Background control` groups for poll/cancel controls instead of requiring users to inspect `JOB.json`. Non-JSON `patchbay events`, `patchbay trace`, `patchbay artifact`, and Agent diagnostic view replies render timelines, artifact previews, requested diagnostic tabs, recovery hints, and grouped safe actions instead of raw nested payloads. Non-JSON `patchbay setup` / `install`, `patchbay doctor`, `patchbay config profile show/apply`, `patchbay metrics`, and their Agent equivalents render local summaries for setup steps, readiness checks, write/fix economy routing, efficiency evidence, recommendations, and grouped safe actions. Non-JSON Agent guidance replies such as `help`, local-only/no-MCP prompts, missing-run handoffs, `next step`, gate-status questions, and stateless background-status checks render capabilities, selected/latest run references, gate diagnostics, next actions, background job state, and grouped safe actions instead of raw structured payloads. Non-JSON selected-run background cancellation renders a concise cancellation summary, background job state, failed `cancel_result` details, and safe follow-up actions. The JSON contract remains top-level `inbox.groups`, `inbox.focus_run_id`, active/confirmation counts, and per-run `inbox.next_action`, `actions[]`, and `action_groups[]` for safe opening/diagnostics plus explicit gated follow-ups. Setup, doctor/readiness, and profile/routing responses also include `routing.workload_policy`, a machine-readable split that labels `write`/`fix` as economy work for simple high-volume implementation and repair, while `plan`/`review` stay on supervision models. Setup/install JSON also lifts doctor `recommendations` to the top level and maps actionable recommendations into short `next_actions` such as `apply economy profile`, `configure reasonix command`, or `configure economy provider command`. For desktop and MCP clients, prefer the returned `actions[]` or `routing_evidence.actions[]` over deriving UI controls from `economy_health.next_action`; those actions are already typed as safe `local_agent`, `command`, or `diagnostic_tab` follow-ups and may include a `command` field for exact CLI fallback display. Responses that include structured actions may also include `action_groups[]`, whose `action_ids` split buttons into stable categories such as `background_polling`, `background_control`, `routing`, `setup`, `diagnostics`, `gate`, `new_task`, and `commands`; clients can use these groups for UI sections without parsing action ids. When `command_not_ready` comes from a custom economy provider, render the `configure_economy_provider_command` copy command before the inspect action so users can fix `providers..command` directly. + +Use `--background` for long conversational turns so the caller can return immediately and poll status/events: + +```bash +python scripts/patchbay agent message "..." --background --json +python scripts/patchbay agent message approve --run-id --confirmation plan_approved --background --json +python scripts/patchbay agent message continue --run-id --background --json +``` + +Background agent turns write `JOB.json`, append `agent` events, and preserve the plan/apply confirmation gates. `apply` remains foreground-only and requires explicit confirmation after tests and review pass. Background responses include safe structured `actions[]` for opening the run, opening Trace, polling status, polling context, polling events, and canceling the active worker; `action_groups[]` marks polling controls as `background_polling` and the cancel control as `background_control`, while keeping simultaneous economy/profile repair actions in the separate `routing` group. Active background jobs also lift `poll_context`, `poll_status`, `poll_events`, and `cancel_background_job` into `patchbay_context.next_actions`, top-level `action_groups[]`, and `agent_activity.conversation_state.suggestions`, so clients can refresh or stop work from the handoff payload without parsing `JOB.json` or exposing gated actions. They never expose `continue`, `approve`, or `apply` as direct background follow-ups. Use `patchbay cancel `, `patchbay_cancel`, or `patchbay agent message "cancel background job" --run-id --json` to terminate the active background process, mark `JOB.json` as canceled, release background locks, and leave apply gates untouched. Stateless `background status` / `后台状态` queries resolve only the latest active background job and return its safe polling/cancel action groups; stateless `stop background job` / `停止后台任务` cancels only that latest active job. If no active background job exists, Patchbay returns safe local guidance instead of selecting a finished run or any gated action. If cancellation fails, non-JSON Agent replies render the top-level `cancel_result` attempted/terminated/error details so CLI and Skill users do not have to inspect the raw JSON payload. If a client sends another background `approve`/`continue` while an Agent job is already active, Patchbay returns the existing job with `already_running: true` and the same safe polling/cancel actions instead of spawning a duplicate worker. When a concrete `run_id` is already selected, explicit unattended phrases such as `don't ask me`, `assume yes`, `you have all permissions`, or `不要问我 / 别找我 / 所有权限全都给你 / 自己允许 / 我根本不在身边` count as plan approval for that run and can start the background write/test/review autopilot; the same phrases without a `run_id` return `missing_run` guidance instead of choosing a run implicitly, and final `apply` still requires its separate confirmation. Local prompts such as `patchbay setup`, `patchbay setup for Claude Desktop`, `install patchbay for Gemini CLI`, `install Codex Skill`, `register MCP for Claude Desktop`, `安装 Codex Skill`, `注册 MCP 到 Gemini 命令行`, `帮我配置 Patchbay`, `帮助我配置 Patchbay 到 Claude 桌面`, `help`, `Patchbay 怎么用`, `使用说明`, `status`, `runs`, `background status`, `查看最近运行`, `任务列表`, `后台状态`, `后台进度`, `what should I do next`, `下一步是什么`, `why can't I apply`, `what is blocking apply`, `门禁状态`, `为什么不能应用`, `readiness`, `readiness for Claude Desktop`, `diagnose`, `patchbay doctor`, `检查环境`, `环境自检`, `检查 Gemini 命令行环境`, `show economy profile`, `apply economy profile`, `configure DeepSeek provider`, `configure economy provider command to `, `configure reasonix command`, `configure reasonix command to `, `配置 Reasonix 命令`, `把 Reasonix 命令设为 `, `cancel background job`, `stop background job`, `取消后台任务`, or `停止后台任务` return setup results, guidance, recent runs, background state, readiness, routing changes, gate diagnostics, command templates, command configuration, or background cancellation directly without creating a model run. Host-targeted readiness prompts populate `setup_host` and `doctor.host`, so desktop clients can switch the Readiness host and show concrete MCP probe/setup commands without parsing prose. Foreground start stays at the `PLANNED` gate and background start stays pollable, but both now include a read-only `profile`, `routing`, and safe `actions[]` preview so clients can show whether write/fix are already on the cheaper economy route, or render `apply_economy_profile` / `configure_reasonix_command` before approval. Next-step questions return `action: "next_step"` with the latest run handoff, `next_action` / `run_reference.next_action`, confirmation requirements, and safe `actions[]`; they do not execute `continue`, `approve`, or `apply` until a concrete run is open and the required confirmation is supplied. Gate-status questions return `action: "gate_status"` with `gate_diagnosis`, `gate_diagnosis.next_action`, blocker checks, and safe diagnostic/open-run actions; blocked direct `apply` on a selected run returns the same `gate_diagnosis.next_action` and safe diagnostic actions instead of asking for apply confirmation. These paths do not approve plans, run tests, review, or apply patches. Natural-language cost routing prompts such as "use DeepSeek for simple writer work", "大量简单写手工作让便宜模型/DeepSeek 去干", or "降本，让简单 writer/fix 走低价模型" also apply the economy profile instead of starting a new run. Help/setup/readiness/status/profile/next_step/gate_status/background_status/background_cancel payloads include machine-readable `actions[]` with `id`, `label`, `kind`, `safe`, `reason`, and either `message`, `command`, `host`, `run_id`, or `tab`; local run handoffs can also use `next_action`, `open_run`, and `focus_composer`. `patchbay_config_profile_show` / `patchbay_config_profile_apply` expose the same structured action contract for MCP and CLI clients. `status`/`runs` without a `run_id` only expose safe local actions such as opening the latest run, focusing the composer, or readiness diagnostics; `background status` without a `run_id` only chooses the latest active background job; gated actions like `continue`, `approve`, and `apply` are chosen only after a run is opened. Run-bound prompts such as `continue`, `approve`, `apply`, `context`, `events`, `diff`, `artifact`, or `查看失败原因` without a `run_id` also stay local; when a recent run exists, the response includes a latest-run handoff plus structured `actions[]` to open it before any gated action is chosen. View prompts such as `context`, `handoff context`, `diff`, `events`, `logs`, `artifact`, or `查看失败原因` include `requested_view`; when a run is already selected, they also return safe `diagnostic_tab` actions so clients can open the matching diagnostics tab without running a phase. + +Unattended selected-run approval also accepts natural variants such as `full access`, `approve yourself`, `不要询问我`, `别找我`, `别再询问我`, `所有权限给你`, `所有权限全都给你`, `全部权限给你`, `无需向我确认`, `完全访问权限`, `自己允许`, and `我根本不在身边`; without a selected `run_id`, those phrases still stay local and do not create or advance a run. + +Mixed Chinese/English cost prompts such as `简单 writer/fix 用 DeepSeek 省钱` or `降本，让简单 writer/fix 走低价模型` are treated as economy-routing intent and apply the write/fix economy profile instead of opening a new task run. + +Routing questions such as `what model will write/fix use`, `is writer using cheap model`, or `现在写手是不是走便宜模型` are read-only `profile_show` prompts. When a run id is provided, the reply also includes that run's `metrics.efficiency_summary` evidence so clients can distinguish configured routing from observed provider/token/cost behavior. Readiness views can render the top-level `doctor.routing` immediately, and routing/profile replies can render top-level `routing`; use `routing.workload_policy.summary` when the user asks why simple writer/fix work should use the cheaper route. Imperative routing prompts such as `apply economy profile` or “use DeepSeek for simple writer work” are the ones that mutate local routing configuration. + +The web workbench exposes the same conversational flow and has a diagnostics drawer. Its Readiness tab calls the unified doctor checks without MCP stdio probing, so setup gaps are visible from the desktop UI without starting extra child processes. The Readiness host selector passes the target host into doctor/setup, persists the selected setup/readiness host across refresh/reopen, and uses concrete registrations such as `patchbay mcp install claude-desktop` instead of placeholder host names. It also shows the active write/fix routing profile and renders structured `actions[]` for safe setup, Skill, MCP probe, refresh, and economy-routing follow-ups, grouped by `action_groups[]` into stable sections such as routing and setup. When no run is selected, the composer shows a compact start context card with local/no-MCP mode, readiness state, write/fix economy routing, and safe setup/economy actions before a new plan is created. The run composer also groups `agent_activity.conversation_state.suggestions` with `patchbay_context.action_groups[]`, so background polling, background control, diagnostics, and gated actions appear as separate controls instead of a flat button list. If an installed Codex Skill is outdated, the check card shows `status: outdated`, missing/changed/extra installed files, and the safe update action. Local conversational replies render safe `command` actions as copyable command rows with a fallback copy path, and failed Clipboard/fallback copy attempts show a visible unavailable state, so MCP/Skill registration commands are usable without opening diagnostics even when Clipboard API access is unavailable. Background job cards expose open-activity, refresh, and cancel controls for long-running turns. The selected-run conversation shows a compact run snapshot with phase/status, gate progress, economy routing health, and latest provider evidence before the detailed event stream. The sidebar run inbox also renders compact per-run quick signals for phase, gates, economy routing, and latest provider evidence, so operators can triage multiple tasks before opening a run. The Overview tab surfaces economy routing and `economy_efficiency` health cards from `agent_activity.health_cards`, so drift from the intended cheaper write/fix route and actual token/cost/time evidence are visible without parsing logs. The Trace tab renders selected-message, run-timeline, and provider-trace summaries as readable cards first, while keeping raw JSON collapsed for exact debugging. The Diff tab summarizes changed files, additions, deletions, and hunks before keeping raw patch text collapsed. The Log and Artifacts tabs reuse `failure_recovery`, status errors, priority artifacts, and the loaded artifact preview to show a failure summary, suggested next step, highlighted error lines, and an artifact index before the raw preview. The Config tab summarizes phase routes, provider commands, test allowlists, custom providers, and workflow safeguards before keeping raw config JSON behind a detail affordance. The Providers tab summarizes configured phase routes, observed provider usage, event trail, economy target, coverage, and health so writer/fix economy routing can be checked without reading raw events. + +Command rows show the exact command text visible inline before the copy button, so provider repair commands remain inspectable in screenshots and when clipboard access fails. + +The workbench also persists whether it is showing the selected run or the new-task view, diagnostics drawer open state, active diagnostics tab, selected Trace message per run, sidebar search/status/inbox filters, and composer drafts for each run plus the new-task composer across refresh/reopen. Its topbar refresh reloads the selected run's status, context, provider trace, diff, and artifact preview together instead of only refreshing the sidebar run list, and failed refreshes show a named accessible error while re-enabling the control. Initial run-list loading, startup readiness loading, selected-run detail loading, and selected-run polling failures also show named accessible errors instead of raw exception strings. Selected-run polling now pauses idle incremental context refreshes while the document is hidden, resumes with one immediate refresh when it becomes visible, and keeps active background jobs polling while hidden so long-running work still completes. Phase-advance controls catch failed gated/autopilot actions, show an accessible top-level error naming the failed action, and re-enable the controls without relaxing the final apply confirmation gate. Safe diagnostic controls such as open-run, poll context/status/events, readiness actions, and local Agent reply actions such as opening the latest run use the same visible error path when their refresh calls fail, including `open-latest-run` replies that lack a run reference. Setup/readiness/economy/provider configuration failures also name the failed action or selected host and re-enable the triggering setup/profile/readiness controls. It now preserves a lightweight, bounded local conversation transcript too: recent selected-run local notes, compact local Agent replies, and the latest new-task Agent reply survive refresh/reopen, while bulky `context`, `status`, `runs`, and `diff` are deliberately omitted. Compact local Agent replies preserve `background_job` summaries when present, so canceled/failed background results remain visible after refresh without storing the full handoff payload. If the stored run is no longer present, it falls back to the current inbox focus instead of requesting a stale run. Stale inbox filters are cleared when the current run inbox no longer exposes that group. Drafts are cleared after successful submit; selected-run free-text send failures show a named accessible error and preserve the draft. + +Copyable command controls reset their copied/unavailable state whenever readiness or Agent responses replace the underlying command, so stale feedback is not carried across provider repair commands. + +When doctor returns the structured `configure_deepseek_provider` action, the Readiness tab may render a guarded economy-provider form that creates a custom DeepSeek CLI writer/fix provider and activates economy routing. Healthy readiness alone should keep that form hidden, so clients do not expose mutating provider setup when there is no setup gap. + +Setup scope is inferred from the prompt: `install Codex Skill` installs the Skill without attempting MCP registration, `register MCP for Claude Desktop` skips Skill installation, and explicit `patchbay setup without MCP` / `--skip-mcp` / `--no-mcp` / `--local-only` keeps setup local to project files and Skill installation. Standalone conversational avoidance such as `please don't use MCP`, `no MCP`, `use Chrome Skill instead of MCP`, `少用这个MCP`, or `不要用这个MCP` returns `action: "local_mode"` with safe local CLI/Skill/readiness actions instead of running setup or starting a model run. The same avoidance scope applies to `readiness` / `doctor` prompts, so `readiness without MCP` and `patchbay doctor --local-only` suppress MCP probe/register follow-up actions in both the top-level response and nested doctor payload. The web doctor endpoint accepts `skip_mcp=true`, and local-mode readiness actions force-refresh doctor with that flag so the desktop workbench does not reuse MCP-oriented follow-ups; once selected, the workbench stores local-only mode and the selected setup/readiness host in browser storage, restores them after refresh/reopen, starts doctor with that host plus `skip_mcp=true`, and rewrites ordinary host setup buttons such as `patchbay setup for claude-desktop` to `patchbay setup without MCP for claude-desktop`. The persisted preference is reversible: the start context and Readiness panel show an explicit `MCP setup` action in local-only mode, which clears the local-only preference while keeping the selected host and sends host-aware MCP-only setup such as `register MCP for Claude Desktop`. + +Chinese local-only phrases such as `不走 MCP`, `走本地模式`, and `只用本地工具` are handled the same way: the Agent returns local CLI/Skill/readiness actions and avoids MCP probe/register follow-ups. + +Implicit local browser preferences such as `use Chrome Skill`, `use browser skill`, `use your built-in browser`, or `用你自带的浏览器功能` also select `local_mode` even when the message does not explicitly mention MCP, so they do not create a model run. In the workbench, composer replies and structured local Agent actions that select `local_mode` are persisted as local-only mode and immediately refresh readiness with `skip_mcp=true`. + +After starting `patchbay web --port 8765`, open `http://127.0.0.1:8765`. + Mock mode can validate the workflow without model credentials: ```bash @@ -104,10 +182,33 @@ patchbay mcp install claude-desktop # Claude Desktop (edits config in-place) patchbay mcp install gemini # Gemini CLI # Or manually -codex mcp add patchbay -- python scripts/patchbay_mcp_server.py +codex mcp add patchbay -- patchbay-mcp --root /path/to/repo +``` + +Use the equivalent MCP server registration command for other MCP hosts, quoting `/path/to/repo` if it contains spaces. Run `patchbay doctor --host ` for lightweight readiness checks with concrete structured registration actions for that host. Add `--probe-mcp` or run `patchbay mcp doctor` only when you specifically need stdio server reachability and tool-list evidence. + +`patchbay doctor` is read-only and reports project initialization, phase config validity, CLI shim/installed command availability, bundled Skill source, whether the Codex Skill is installed and current, and MCP follow-up actions; it skips stdio MCP probing by default so routine readiness checks do not spawn the MCP server. Use `patchbay doctor --local-only` when the current host should not show MCP probe/register actions at all. It returns prose `next_actions`/`recommendations` plus structured `actions[]` for desktop/MCP clients, including `Update Codex Skill` when the installed Skill no longer matches the bundled source. `patchbay doctor --probe-mcp` and `patchbay mcp doctor` start the stdio MCP server, send `initialize` and `tools/list`, and verify required tools including `patchbay_agent`, `patchbay_plan`, `patchbay_context`, `patchbay_metrics`, `patchbay_doctor`, `patchbay_install`, `patchbay_skill_install`, and `patchbay_skill_doctor`. For Codex, Claude Code, and Gemini, `mcp install` now tries to register automatically and falls back to the command text if the host CLI is unavailable; Claude Desktop writes its JSON config in place. Host names accept English and common Chinese aliases, such as `Claude Desktop`, `Claude 桌面`, `Claude Code`, `Claude 代码`, `Gemini CLI`, and `Gemini 命令行`. + +After MCP registration, restart or reload the target host if it caches tool lists. Verify with `patchbay mcp doctor --json`, or from the host by checking that `patchbay_agent` is visible. + +## Codex Skill Install + +Patchbay also ships as a Codex Skill. The Skill teaches Codex when to invoke the gated workflow; the MCP server provides the tools. + +```bash +patchbay skill install codex +patchbay skill doctor codex +patchbay skill print codex --json ``` -Use the equivalent MCP server registration command for other MCP hosts. Run `patchbay mcp doctor` to verify the server is reachable. +The Skill host argument accepts Codex aliases such as `Codex Desktop`, `Codex CLI`, and `Codex 桌面`; responses still use the canonical `codex` host. + +`patchbay skill doctor` validates both the bundled Skill source and the installed copy. If the installed Skill is stale, missing files, or contains old extra files, it reports `status: "outdated"`, `installed_matches_source: false`, `missing_installed_files`, `changed_installed_files`, and `extra_installed_files`, then returns a safe reinstall action. + +The Skill is intentionally compact for lower context cost. `SKILL.md` keeps only the trigger, entry-choice, gate, local-only, economy, and background rules. Detailed setup guidance lives in `references/install.md`, and structured Agent/Desktop/MCP response handling lives in `references/agent-contract.md`. `patchbay skill print codex --json` returns all bundled files, while `patchbay skill doctor` treats both references as required source files and reports drift if the installed copy is missing or stale. + +By default the Skill installs to `$CODEX_HOME/skills` or `~/.codex/skills`. It triggers on phrases such as "走多模型流程", "multi-agent workflow", Patchbay setup/install, Codex Skill installation, and no-MCP/local-only Patchbay work; MCP tools still need MCP registration when the host wants tool calls. +`patchbay skill doctor` / `patchbay_skill_doctor` also return safe structured `install_skill` and `refresh_skill_doctor` actions when the Skill is missing. With the default skills root, `install_skill` is a `local_agent` action with message `install Codex Skill` and a copyable `patchbay skill install codex` command fallback, so desktop and MCP hosts can install the Skill without invoking MCP registration. When a custom `--path` is supplied, the action remains a command so the selected destination is preserved. ## Configuration @@ -134,7 +235,13 @@ python -m unittest discover -s tests -v ## Custom Provider Support -User-defined CLI providers can be configured under `[providers.]` with `roles`, `command`, `args`, `prompt_mode`, and `output_contract`. Use `patchbay config provider add-cli ...` to add them without hand-editing TOML. See [docs/custom-providers-plan.md](docs/custom-providers-plan.md) for the design notes and safety contract. +User-defined CLI providers can be configured under `[providers.]` with `roles`, `command`, `args`, `prompt_mode`, and `output_contract`. Use `patchbay config provider add-cli ...` to add them without hand-editing TOML; add `--activate-economy --economy-model --economy-label