Add generic harness observe and CodeBuddy support (#18)

* feat(cli): add generic protocol observe bridge

* feat(cli): add exact CodeBuddy capture adapter

* fix(codebuddy): preserve file-configured providers through capture

* fix(translation): reuse CodeBuddy capture model

* docs(governance): require scoped validation declarations

* chore(release): prepare 0.1.0-alpha.4

Author: fengjikui

AGENTS.md

@@ -119,6 +119,8 @@ Viewer-only JavaScript, CSS, copy, or documentation changes still use hosted CI,
 
 Validation effort follows the risk and accumulated blast radius. The detailed policy lives in [the tiered validation strategy](docs/validation-strategy.md).
 
+Before running tests, the contributor MUST state the selected validation level, the changed boundary, and the planned focused commands. Level 2 MUST NOT be used as a generic confidence ritual: run it only when a trigger below applies, and name that trigger in the progress or handoff report. When Level 1 evidence is green and no escalation trigger applies, stop testing and continue development.
+
 ### Level 0: documentation and non-runtime metadata
 
 Use Level 0 only when runtime code, package contents, workflows, schemas, and user-facing behavior are unchanged.
@@ -134,6 +136,7 @@ Examples include a pure helper extraction, a narrow Viewer renderer change, or a
 
 - Run syntax/type checks and the smallest deterministic contract or integration smokes that cover the changed path.
 - Viewer interaction changes SHOULD include the narrowest representative browser scenario.
+- Prefer one direct contract plus the nearest integration boundary; do not expand to unrelated subsystem or full-profile tests without an explicit escalation trigger.
 - Commit the change when focused evidence is green; do not defer focused tests until the batch ends.
 - After three consecutive Level 1 code commits since the last successful full host-platform profile, run Level 2 before starting a fourth code commit or pushing the batch.
 

CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to peekMyAgent are documented in this file. The project foll
 
 ## [Unreleased]
 
+## [0.1.0-alpha.4] - 2026-07-31
+
+### Added
+
+- `pma observe` adds a process-local OpenAI/Anthropic capture bridge for custom Harnesses.
+- `pma codebuddy` adds exact capture and native session reuse for CodeBuddy Code 2.130.0.
+
+### Fixed
+
+- CodeBuddy keeps provider credentials in `models.json`; translation reuses the captured model instead of Viewer credentials.
+
+### Changed
+
+- Validation now declares risk and focused scope before escalating to a full host profile.
+
 ## [0.1.0-alpha.3] - 2026-07-30
 
 ### Fixed
@@ -18,6 +33,7 @@ All notable changes to peekMyAgent are documented in this file. The project foll
 - `pma codex` now opens Codex Desktop for the current project, exposes a waiting Source immediately, and binds that stable Source to the next new workspace thread without copying rollout history into peekMyAgent SQLite.
 - Codex XML-like Harness blocks now use a conservative tag registry for runtime, capability, policy, lifecycle, internal, and subagent presentation, with multilingual block translation through the shared cache pipeline.
 - `pma opencode` now starts one OpenCode CLI/TUI process behind an exact, reversible proxy overlay, preserves native session attribution, and reuses the shared Trace, tool-loop, subagent, command-injection, compaction, and same-Harness translation pipeline.
+- `pma observe` now gives custom Harness authors a child-process-only OpenAI/Anthropic base-URL bridge with exact request/response capture, protocol auto-detection, redacted authentication evidence, direct Trace links, and deterministic cleanup without a Harness-specific adapter.
 
 ### Changed
 
@@ -50,7 +66,8 @@ All notable changes to peekMyAgent are documented in this file. The project foll
 - Node.js 24 or newer is required.
 - Claude Code and OpenClaw are the primary integrated Agents. Provider-specific model and reasoning options may still affect Agent behavior independently of capture fidelity.
 
-[Unreleased]: https://github.com/fengjikui/peekMyAgent/compare/v0.1.0-alpha.3...HEAD
+[Unreleased]: https://github.com/fengjikui/peekMyAgent/compare/v0.1.0-alpha.4...HEAD
+[0.1.0-alpha.4]: https://github.com/fengjikui/peekMyAgent/compare/v0.1.0-alpha.3...v0.1.0-alpha.4
 [0.1.0-alpha.3]: https://github.com/fengjikui/peekMyAgent/compare/v0.1.0-alpha.2...v0.1.0-alpha.3
 [0.1.0-alpha.2]: https://github.com/fengjikui/peekMyAgent/compare/v0.1.0-alpha.1...v0.1.0-alpha.2
 [0.1.0-alpha.1]: https://github.com/fengjikui/peekMyAgent/releases/tag/v0.1.0-alpha.1

README.md

@@ -117,6 +117,24 @@ node bin/peekmyagent.mjs --help
 
 All examples below use `pma`. The full `peekmyagent` command remains available and behaves the same.
 
+## Observe Your Own Harness
+
+If a custom Harness already reads an OpenAI- or Anthropic-compatible base URL from an environment variable, PMA can capture it without a Harness-specific adapter:
+
+```bash
+# OPENAI_BASE_URL should contain the real upstream URL, commonly ending in /v1.
+pma observe --name my-agent --base-url-env OPENAI_BASE_URL -- my-agent run
+
+# Anthropic-compatible example.
+pma observe --name my-agent --base-url-env ANTHROPIC_BASE_URL -- python agent.py
+```
+
+`pma observe` reads the original URL before launch, creates a fresh exact-capture watch, and overrides only the named variable in the child process. API-key variables, authentication headers, stdin/stdout, signals, and the child exit code are preserved. The original base path is retained, so an OpenAI `/v1` URL still forwards `/responses` to `/v1/responses`. PMA prints a direct Trace link but omits all child arguments from its own startup output.
+
+Use `--conversation-id <id>` to attach a stable non-secret test identity, or `--target-base-url <url>` when the named environment variable is intentionally unset. Upstream URLs containing credentials, query parameters, or fragments are rejected.
+
+This generic bridge auto-detects and organizes OpenAI Responses/Chat and Anthropic Messages fields. It does not infer private Harness behavior such as permission policy, commands, compaction, or parent/child Agent relationships; those require a fixture-backed adapter. If the Harness cannot override its base URL per process, follow the [new Harness adaptation playbook](docs/new-harness-adaptation-playbook.md) instead.
+
 ## Quick Start With Claude Code
 
 Open the dashboard:
@@ -241,6 +259,27 @@ PMA only overrides the wrapped process's `baseURL`; it does not change config, r
 
 For `-c/--continue` and `-s/--session`, PMA resolves OpenCode's public session identity and offers to append to the matching existing recording. Press Enter to reuse it, choose option 2 for a separate recording, or use `pma --reuse opencode -c` to skip the prompt. `--fork` always starts a new recording because OpenCode creates a new session identity.
 
+## Quick Start With CodeBuddy Code
+
+Install CodeBuddy and provide its upstream credential in the shell. PMA deliberately does not read or copy OpenCode authentication:
+
+```bash
+npm install -g @tencent-ai/codebuddy-code
+export CODEBUDDY_API_KEY='<your-provider-key>'
+cd <your-project>
+pma codebuddy
+```
+
+By default PMA maps CodeBuddy's main, lite, reasoning, and subagent model slots to the current OpenCode model and OpenAI-compatible endpoint. Only the wrapped CodeBuddy process receives the proxy and model environment overrides; user configuration files remain unchanged.
+
+```bash
+pma codebuddy --continue
+pma --reuse codebuddy --continue
+pma codebuddy --resume <session-id>
+```
+
+The current adapter is verified against CodeBuddy 2.130.0 and OpenAI Chat Completions. See the [CodeBuddy adaptation evidence](docs/codebuddy-code-adaptation-plan.md) for exact scope and limitations.
+
 ## Full-Permission Modes
 
 These switches and settings belong to the underlying harness. PMA passes them through or uses the named isolated OpenClaw profile; it does not grant itself additional permissions.
@@ -257,6 +296,12 @@ Claude Code can bypass its permission checks for one captured process:
 pma claude -c --dangerously-skip-permissions
 ```
 
+CodeBuddy Code can bypass its permission checks for one captured process:
+
+```bash
+pma codebuddy --dangerously-skip-permissions
+```
+
 OpenCode can auto-approve requests that would otherwise ask:
 
 ```bash
@@ -603,4 +648,6 @@ node --check src/viewer/client.js
 - [Manual integration smoke matrix](docs/manual-integration-smoke-matrix.md)
 - [Claude Code current-session control](docs/claude-code-current-session-control.md)
 - [OpenCode CLI adaptation plan and evidence](docs/opencode-cli-adaptation-plan.md)
+- [CodeBuddy Code adaptation plan and evidence](docs/codebuddy-code-adaptation-plan.md)
+- [Agent observability product learnings](docs/agent-observability-product-notes.md)
 - [OpenClaw profile watch](docs/openclaw-profile-watch.md)

README.zh-CN.md

@@ -122,6 +122,24 @@ node scripts/install.mjs --dry-run
 node bin/peekmyagent.mjs --help
 ```
 
+## 调试你自己的 Harness
+
+如果自研 Harness 已经从环境变量读取 OpenAI-compatible 或 Anthropic-compatible 的 base URL，不需要先开发专用 adapter，也可以直接接入 PMA：
+
+```bash
+# OPENAI_BASE_URL 保存真实上游地址，通常以 /v1 结尾。
+pma observe --name my-agent --base-url-env OPENAI_BASE_URL -- my-agent run
+
+# Anthropic-compatible 示例。
+pma observe --name my-agent --base-url-env ANTHROPIC_BASE_URL -- python agent.py
+```
+
+`pma observe` 会在启动前读取真实上游，创建一条新的精确捕获 watch，然后只在被包装的子进程中覆写指定环境变量。API key 环境变量、认证 header、stdin/stdout、信号和子进程退出码都保持不变。原始 base URL 的路径前缀也会保留，例如 OpenAI 的 `/v1` 加上子进程请求的 `/responses`，仍会转发到真实上游的 `/v1/responses`。PMA 会打印可直接打开的 Trace 链接，但不会回显任何子进程参数。
+
+可以用 `--conversation-id <id>` 写入一个不敏感的稳定测试标识；如果指定环境变量原本为空，也可以显式传入 `--target-base-url <url>`。带用户名/密码、query 或 fragment 的上游 URL 会被拒绝。
+
+通用桥会自动识别并整理 OpenAI Responses/Chat 和 Anthropic Messages 的协议字段，但不会猜测自研 Harness 的权限策略、命令、压缩或父子 Agent 关系；这些私有机制需要有真实 fixture 证据的专用 adapter。如果 Harness 不支持进程级 base URL 覆写，请按[新 Harness 适配工作手册](docs/new-harness-adaptation-playbook.md)继续接入。
+
 ## 快速开始：Claude Code
 
 先打开 dashboard：
@@ -221,6 +239,28 @@ PMA 只覆盖当前子进程的 `baseURL`，不改配置、不读 `auth.json`、
 
 使用 `-c/--continue` 或 `-s/--session` 时，PMA 会通过 OpenCode 的公开 session 身份定位已有记录，并询问是否继续写入。直接回车默认复用，选择 2 会创建独立记录；也可用 `pma --reuse opencode -c` 跳过询问。`--fork` 会产生新的 OpenCode session，因此始终创建新记录。
 
+## 快速开始：CodeBuddy Code
+
+先安装 CodeBuddy，并在当前 shell 中提供上游凭据。PMA 不读取或复制 OpenCode 的认证：
+
+```bash
+npm install -g @tencent-ai/codebuddy-code
+export CODEBUDDY_API_KEY='<你的 provider key>'
+cd <your-project>
+pma codebuddy
+```
+
+默认情况下，PMA 会把 CodeBuddy 的主模型、轻量模型、推理模型和子 Agent 模型映射到当前 OpenCode 的 model 与 OpenAI-compatible endpoint。代理和模型环境变量只影响当前 CodeBuddy 子进程，不修改用户配置文件。
+
+```bash
+pma codebuddy --continue
+pma --reuse codebuddy --continue
+pma codebuddy --resume <session-id>
+pma codebuddy --dangerously-skip-permissions
+```
+
+当前适配由 CodeBuddy 2.130.0 和 OpenAI Chat Completions 验证。精确边界见 [CodeBuddy 适配计划与证据](docs/codebuddy-code-adaptation-plan.md)。
+
 ## 快速开始：OpenClaw
 
 ```bash
@@ -321,4 +361,6 @@ npm run release:check
 - [手动集成 smoke 矩阵](docs/manual-integration-smoke-matrix.md)
 - [Claude Code 当前会话控制](docs/claude-code-current-session-control.md)
 - [OpenCode CLI 适配计划与证据](docs/opencode-cli-adaptation-plan.md)
+- [CodeBuddy Code 适配计划与证据](docs/codebuddy-code-adaptation-plan.md)
+- [Agent 可观测与调试产品借鉴点](docs/agent-observability-product-notes.md)
 - [OpenClaw profile watch](docs/openclaw-profile-watch.md)