hosts.md

# Harness integrations

Official documentation checked **2026-10-02**. The documented capabilities below concern the public configuration interface. An installed host's version, MCP connection, agent tool use, and image interpretation are separate observations.

| Host | Native Skill | stdio MCP | Automated target | Remaining work |
| --- | --- | --- | --- | --- |
| Codex | Documented | Documented | User `.agents/skills`, user `.codex/config.toml`; explicit project scope supported by API | Restart/refresh if necessary and perform actual agent checks |
| TRAE / TraeCode CN | Documented | Documented | User `.trae-cn/skills` or project `.trae/skills`; project `.trae/mcp.json` | Enable project MCP; global MCP uses documented manual UI; bind intended agent |
| Tencent WorkBuddy | Documented ZIP format | Documented | User/project `.workbuddy/mcp.json` | Import generated Skill ZIPs through the UI |
| Cherry Studio | Modern Skills documented; automatic discovery unverified | Transport-specific capability unverified | stdio configuration generated for UI review/import | Add/start server in Settings > MCP, then bind to Work agent; read original Book Skill through MCP |

No row asserts an installed application version. `HostAdapter.detect()` reports executable/home markers without launching an application and reports its operational state/version as `unknown`. Image support remains `unknown` until an actual host/model interaction has been recorded.

The current Codex official Skill documentation specifies `$HOME/.agents/skills`. Some preexisting local installations use legacy `.codex/skills` paths; this adapter uses the documented `.agents` default and does not rewrite a legacy catalog. A supplied `home` isolates both Skill/config targets for tests. Codex uses TOML `[mcp_servers.<name>]`, `command`, and a separate `args` array; no protocol `type` field is needed for that table. [Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli), [Codex Skills](https://learn.chatgpt.com/docs/build-skills).

TRAE CN documents both Skill directories, project `.trae/mcp.json`, and manual MCP JSON configuration through Settings > MCP > Add > Manual Add. Its current command parser documentation rejects spaces in the command field; the adapter refuses application of such a command and preserves argument arrays containing Unicode/spaces/special characters. A verified executable location without spaces is required for that parser. Only the CN IDE edition's public paths are automatically chosen; other editions need selected paths/UI. [TRAE Skills](https://docs.trae.cn/ide_skills), [TRAE MCP configuration](https://docs.trae.cn/ide_add-mcp-servers).

WorkBuddy documents `.workbuddy/mcp.json` at user/project scope and `mcpServers` JSON with `command`, `args`, and optional `env`. The adapter writes no credential literals. Its generated Skill ZIP includes required bilingual descriptions, author and version fields. Import remains a UI action, and generated ZIPs are not recorded as an installed native Skill. [WorkBuddy MCP](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/MCP-Guide), [WorkBuddy Skill format](https://open.workbuddy.cn/docs/skill).

Cherry Studio's public UI connects servers under Settings > MCP and then binds them in the Work agent editor. The adapter emits a standard local stdio `mcpServers` JSON artifact for review/import and human instructions, and does not modify its private database or claim native Skill automatic discovery. Its original Book Skill is accessed with `book_get_skill`. The current fetched public page confirms the MCP UI but does not establish its transport-specific parser; `mcp_stdio` therefore remains `unknown` until that documented detail or an actual application check is available. [Cherry Studio tools, Skills and MCP](https://cherryai.com/docs/en/advanced-basic/agent-workspace/tools-knowledge-skills-mcp/).

## Runtime API

```python
adapter = HostAdapter("codex", home=isolated_home, data_dir=book_agent_data)
plan = adapter.install(package, [python_executable, "-m", "book_agent",
                                "--data-dir", str(book_agent_data), "mcp", package.book_id])
result = adapter.install(package, argv, apply=True)
verification = adapter.verify(package.book_id)
removal_plan = adapter.uninstall(package.book_id)
removal_result = adapter.uninstall(package.book_id, apply=True)
```

`detect`, `inspect`, `plan_install`, `install_skill`, `configure_mcp`, `verify`, `uninstall`, and `render_manual_instructions` provide lower-level access. High-level `install` defaults to a read-only plan; CLI `install-host` applies the announced host targets unless `--dry-run` is set. Optional `project_dir` selects documented project targets. An explicit MCP `config_path` permits an edition-specific public configuration file; Cherry remains UI-only. Skill destinations must stay within selected home/project roots.

Every stdio launch uses argv strings. No shell command assembly, shell quoting, secret interpolation, or unreviewed package installer is involved. Required query/rerank secrets should be supplied through the protected environment used when starting the host. An inherited variable is not assumed to exist merely because its name is known.

## Ownership and reversibility

Per-book deployment files live under `BookAgentData/books/<book-id>/deployment/<host>/`:

```text
install-manifest.json
mcp-config.json
manual-instructions.md
backups/
skills/                 # UI import hosts only
book-assistant.zip      # UI import hosts only
<book-wrapper>.zip      # UI import hosts only
```

The original Book Skill is preserved byte for byte in wrapper references. The wrapper provides legal names/frontmatter and directs retrieval/citations through MCP. A valid original name is reused if free. A same-name differing Skill causes a namespaced wrapper; an existing conflicting wrapper is not overwritten. The generic Skill similarly receives a named compatibility copy if `book-assistant` already has different content. Identical contents are skipped.

JSON merges preserve unrelated values. TOML merges preserve comments and unrelated values with `tomlkit`. Existing configs are backed up before changed writes; writes use temporary files and atomic replace. Cooperating Book Agent writers use file locks. The manifest tracks exact generated file hashes, configuration-entry hashes, and ownership. Identical preexisting files/entries do not become owned. Multiple installed books share the managed generic Skill until the last referencing book is uninstalled.

Uninstall removes only owned unchanged files and an unchanged owned MCP entry. Modified files/entries are reported and preserved. Unrelated files in an installed directory survive. Unrelated config edits are retained during entry removal. Backup files are retained; the program does not automatically restore an entire old config over newer unrelated edits.

## Verification levels

Report these independently:

1. Configuration generated: reviewed artifact exists, or a read-only plan contains the configuration.
2. Configuration written: the target public config contains the expected entry.
3. MCP handshake: a real client completed initialize with the running server.
4. Tool call: a real client called the server tool successfully.
5. Agent answer: an actual agent used retrieval evidence to answer a question.
6. Agent visual evidence: an actual agent inspected delivered image content.

`HostAdapter.verify()` checks only artifacts/file hashes and written entries. It returns later stages as `unknown`. Host unit tests exercise isolated directories and never imply a live application test. See the overall evaluation/acceptance record for separately executed integrations.