simplify(agent): remove DeepSeek Harness preview and document the Harness extension contract #288

Status

READY FOR IMPLEMENTATION. SUPPORT-SURFACE SIMPLIFICATION, NOT A MIGRATION PROJECT.

Free4Chat is still internally dogfooding the resident Agent Runtime and built-in Harness set. There is no need to preserve a preview integration that is poorly defined, requires a special checkout, and is not part of a stable user workflow.

Remove the built-in DeepSeek Harness preview now, while the product is still experimental, and use the same change to document the thin contract for adding future Harness integrations.

This keeps Free4Chat aligned with its product position:

A simple temporary collaboration Swiss Army knife, not a framework that carries every experimental Harness integration forever.

Future Harnesses remain easy to add through the generic ACP boundary or the trusted custom ACP launcher.

Why remove DeepSeek Harness preview

The current built-in entry is materially different from the other launchers:

deepseek-harness
→ requires pnpm
→ requires an external checkout
→ requires FREE4CHAT_DEEPSEEK_REPO
→ runs pnpm --dir <repo> run demo:acp
→ maturity = preview

This creates special-case product and Runtime behavior without evidence that the integration is stable or useful enough to justify permanent built-in support.

Phase 0 of #286 also could not verify its permission/session behavior because no configured checkout was available.

Keeping it built in currently costs more than it provides:

• more launcher branches and environment handling;
• more bootstrap/docs surface;
• more readiness/doctor cases;
• more permission-policy ambiguity;
• a misleading impression that DeepSeek Harness is a first-class supported integration.

Removing it does not remove DeepSeek models from Free4Chat. A Harness may still use DeepSeek as its model internally.

It also does not prevent future DeepSeek Harness support. If that project later exposes a stable ACP distribution and a reproducible integration contract, it can be added back like any other Harness.

Scope A — remove the preview built-in integration

Remove deepseek-harness from the built-in launcher surface.

At minimum inspect and update all affected areas:

• agent/internal/harness/launchers.go;
• special FREE4CHAT_DEEPSEEK_REPO handling and errors;
• launcher tests / doctor / readiness / CLI validation;
• help text and machine-readable launcher lists;
• README.md;
• public product docs under docs/en/**;
• app/public/agent.md bootstrap contract;
• generated/aggregated docs such as app/public/llms-full.txt if applicable;
• tests/snapshots that enumerate built-in Harnesses.

After this change the intended built-in set is:

hermes
opencode
codex
claude
pi

plus:

--agent-command <trusted ACP-compatible process>

as the explicit extension/escape hatch.

Do not remove or weaken the custom ACP path.

No migration compatibility required

There is no established public migration obligation for this preview integration.

Do not add:

• deprecated aliases;
• compatibility shims;
• hidden environment fallbacks;
• warning-only legacy support;
• automatic conversion from deepseek-harness to a custom command.

A user who deliberately wants the old preview can use the documented custom ACP launcher path.

Prefer a smaller truthful support surface over preserving an unproven preview forever.

Scope B — define the Harness extension contract

Add concise documentation explaining how a Harness becomes a Free4Chat participant.

The architecture should remain:

Free4Chat Room
      ↓
Go Runtime
      ↓
ACP
      ↓
Harness

Free4Chat should not require a vendor-specific SDK or a new Room primitive for each Harness.

Document two integration levels

1. Custom ACP Harness

This is the generic extension path.

Document how an operator/developer can run any trusted local ACP-compatible process using:

--agent-command
--agent-arg
--agent-env

Explain the key boundary:

• the process must speak the ACP version supported by the Runtime;
• it owns its intelligence, native tools, credentials, private memory, and local permission semantics;
• Free4Chat owns resident lifecycle and Room collaboration;
• ACP is not a sandbox;
• custom launchers are trusted-local integrations and do not receive invented Free4Chat security guarantees.

This should be enough for experimentation without adding a built-in launcher.

2. Built-in Harness

Document the bar for promoting a Harness into the built-in registry.

A built-in integration should be boring and reproducible, not merely technically possible.

Recommended admission criteria:

• stable ACP subprocess entrypoint;
• no required source checkout;
• no vendor-specific repository path environment variable;
• install/launch path that can be explained in one small recipe;
• verified initialize + session/new against the Runtime;
• one retained-session prompt works;
• local environment requirements are explicit and secret-safe;
• permission behavior is understood well enough to document truthfully;
• failure is diagnosable through doctor / readiness;
• no global config mutation required merely to join Free4Chat;
• tests cover the exact launcher command/args;
• public product docs list it only after the integration is actually supported.

Do not require every Harness to expose identical permission modes. The generic ACP permission relay in #286 should preserve native semantics.

Suggested contributor workflow

Document a small repeatable workflow such as:

1. prove the Harness through --agent-command first
2. capture exact ACP handshake and retained-turn behavior
3. verify permission behavior / limitations
4. add one thin launcher registry entry
5. add launcher/doctor tests
6. update public docs
7. dogfood cross-machine
8. only then call it built-in support

This should be guidance, not a plugin framework.

Public documentation

This issue should improve the public product docs, not only internal contributor notes.

Users should be able to understand:

• which Harnesses are built in;
• that any ACP-compatible Harness can still be connected through the custom path;
• what “built-in” actually guarantees;
• where local tool permissions and credentials remain;
• that a model provider and a Harness are different concepts.

Keep the public wording short. Do not turn the docs into an integration certification manual.

If more detailed contributor instructions are useful, place those in an appropriate repository developer/contributor doc and link from the public Harness page only where helpful.

Non-goals

• plugin marketplace;
• dynamic remote launcher registry;
• auto-discovery of every installed coding Agent;
• universal Harness installer;
• vendor certification program;
• universal permission DSL;
• central model routing;
• removing DeepSeek model support from other Harnesses;
• redesigning ACP;
• blocking users from experimenting with unsupported Harnesses through --agent-command.

Acceptance

Removal

• deepseek-harness is no longer a built-in launcher.
• FREE4CHAT_DEEPSEEK_REPO and DeepSeek-specific launcher branching are removed.
• CLI/help/doctor/readiness no longer advertise the preview.
• public product docs no longer advertise it.
• app/public/agent.md no longer tells setup Agents to select it.
• generated docs/snapshots are consistent.
• no compatibility shim or deprecated alias is added.
• custom ACP launcher remains available.

Extension contract

• public Runtime/Harness docs explain built-in vs custom ACP Harnesses.
• a concise “add/integrate a Harness” path is documented.
• built-in admission criteria emphasize stable/reproducible ACP behavior.
• docs explicitly separate Harness choice from model-provider choice.
• docs explain that new/experimental Harnesses should prove themselves through the custom ACP path before entering the built-in registry.
• no plugin framework or new central abstraction is introduced.

Regression

• Hermes, OpenCode, Codex, Claude, and Pi launcher enumeration still works.
• custom --agent-command flow still works.
• launcher tests remain deterministic.
• no Room protocol or MCP behavior changes merely because one launcher was removed.

Relationship to current work

• ux/security(agent): Room-native ACP approval for resident Harnesses #286 — Room-native ACP permission work should target the smaller stable built-in set; DeepSeek preview does not need a policy mapping.
• bug(agent): verify and fix built-in OpenCode ACP launcher compatibility #287 — OpenCode launcher correctness remains independent and should be fixed rather than removed because OpenCode is intended to remain a supported built-in Harness.
• ux(agent): minimize time-to-collaboration for a temporary Agent LAN #246 — reducing fragile setup paths directly supports time-to-collaboration.
• Core direction — temporary capability access and collaboration fabric #51 — reinforces the boundary: Free4Chat is the collaboration fabric; independently evolving Harnesses attach through ACP rather than becoming Free4Chat subsystems.

Design principle

Built-in support should be earned by a small, reproducible integration. Everything else can remain extensible through generic ACP.

This keeps the core simple today without closing the door to future Harnesses.