Harness boundary

The Agent Harness owns the model/tool turn loop inside the resident System Guest. PocketPi owns the device experience around it. Making the Harness replaceable means keeping that experience and host contract stable while swapping the guest-side loop.

Current status

Implemented The firmware-embedded resident Harness ispi-agent-core. It is built into apps/pi-agent/dist/agent.js and shares the Pi Agent System Guest with the Root View. There is no runtime Harness selector onupstream/main today.

Choosing --backend deepseek selects a model provider for the current Pi Harness. It does not run DeepSeek Harness. Model backend and Agent Harness are separate axes.

Stable PocketPi contract

Native host → resident guest
  host.startModel(request)
  host.startTool(callId, name, args)
  host.poll()

Resident guest → PocketPi
  boot(config)
  prompt(text)
  tick()
  drain()
  replaceTools(definitions)

Model requests/results, Tool definitions/results and Agent events cross this narrow boundary. AppSupervisor, native Tool/App routing, provider codecs, workspace, schedules, Root View and SystemFacts should not need to know which Harness implements the turn loop.

Target: build-time Harness replacement

Research target The next step is to build either Pi Agent or DeepSeek Harness into the same resident System App. Adaptation belongs in guest JavaScript, its prelude and the build task, not in a fork of DeepSeek Harness and not in parallel Rust runtime logic.

PocketPi
└── resident System Guest
    ├── Pi adapter  → pi-agent-core
    └── DSH adapter → DeepSeek Harness core

Both expose the same PocketPiEmbedded contract
Both consume the same host model/tool contract
Both drive the same Root View and App ecosystem

Parity comes before new features

A first DeepSeek Harness integration is accepted only when the observable product remains aligned:

• boot reaches ready and the Root View follows the same status transitions;
• prompt text streams incrementally while hidden reasoning stays out of chat text;
• busy prompts and mid-turn Tool replacement follow the current admission behavior;
• native and App Tools remain sequential and App install/uninstall updates the next turn's catalog;
• provider errors surface through the same fault state;
• workspace, schedules, UI and native credentials remain owned by PocketPi;
• reboot conversation behavior remains identical until persistence is deliberately added;
• heap and firmware-size growth are measured on QuickJS-ng and physical firmware.

Explicitly deferred from first parity

• third-party DeepSeek Harness plugin installation or on-device profile scanning;
• DeepSeek Harness web/client UI, because the PocketJS Root View remains the product UI;
• subagents, skills, plan/todo, compaction and session persistence plugins;
• mid-turn steering semantics and a separate schedule plugin;
• multiple in-process Agents before async-context propagation is proven.

Why this boundary matters

PocketPi should support more than one Agent loop without becoming a generic collection of harness ports. The device runtime remains the product: local ownership, native capabilities, App lifecycle and fixed Views. Harness-specific ecosystem ports can later become separate Pi Agent and DeepSeek Harness compatibility layers when there are additional hardware/platform reasons to distribute them independently.

Replaceable Harness is a target architecture backed by a QuickJS feasibility handoff. It is not an implemented feature of the current public branch and must not be described as shipped.