Add pikachatd / OpenClaw / Pi ACP refactor plan

[justinmoon]

Summary

• Adds todos/pikachatd-openclaw-pi-acp-plan.md documenting the plan to refactor pikachat into a transport-first runtime (pikachatd) with clear crate boundaries (pikachat-core, pikachat-protocol), an ACP bridge for serious agents like Pi, and preserved OpenClaw native protocol integration.

Test plan

• CI passes (docs-only change)

🤖 Generated with Claude Code

---

Summary by CodeRabbit

• Documentation
  • Added comprehensive architecture and migration planning documentation outlining the system's structural evolution and transition approach while maintaining backward compatibility with existing features.

[coderabbitai]

📝 Walkthrough

Walkthrough

A new comprehensive specification document detailing the refactor of pikachat into a transport-first runtime architecture. The plan outlines target crate structure, migration phases, service-oriented extraction, acceptance criteria, governance boundaries, and deprecation strategy while maintaining backward compatibility during transition.

Changes

Cohort / File(s)	Summary
Pikachat Refactor Planning todos/pikachatd-openclaw-pi-acp-plan.md	Adds detailed specification for transport-first runtime refactor including architecture design (core, protocol, daemon, CLI, OpenClaw plugin, ACP bridge), phased migration plan with acceptance criteria, service extraction strategy (groups, media, calls), governance rules for CLI routing and session mappings, and guardrails for transport vs. agent policy boundaries.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• Agent refactor followups #304: Addresses overlapping runtime boundary modifications including protocol/bridge extraction from daemon, ACP introduction as primary frontend boundary, and OpenClaw plugin/adapter updates aligned with this transport-first refactor vision.

Poem

🐰 A blueprint drafted with careful thought,
Transport-first architecture is sought,
Boundaries drawn and pathways new,
ACP shines as the forward view,
Hop along to a brighter pike! 🎯

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding a refactor plan document for pikachatd, OpenClaw, and Pi ACP integration.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch pikachatd-plan

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[coderabbitai]

🧹 Nitpick comments (2)

todos/pikachatd-openclaw-pi-acp-plan.md (2)

303-307: Optional: Consider varying sentence structure for readability.

All five non-goal items begin with "Do not," which creates some repetition. While the content is clear, you could optionally rephrase for variety—for example, "Avoid embedding Pi-specific..." or "OpenClaw should not depend on ACP..."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@todos/pikachatd-openclaw-pi-acp-plan.md` around lines 303 - 307, The four
repeated "Do not" lines in the goals section are stylistically repetitive;
reword them to vary sentence structure while preserving meaning—e.g., change "Do
not make OpenClaw depend on ACP for its primary happy path" to "Avoid making
OpenClaw depend on ACP for its primary happy path," change "Do not embed
Pi-specific prompt logic into `pikachatd`" to "Avoid embedding Pi-specific
prompt logic into `pikachatd`," and similarly vary the others referencing
`OpenClaw`, `ACP`, `pikachatd`, `Pi`, and `pi-acp` so each line reads
differently (use "Avoid," "Do not," or active phrasing) for improved
readability.

---

226-229: Consider clarifying the "microVM agent path" concept.

Item 16 references "the microVM agent path" without prior introduction in this document. While this may be well-understood in the project context, adding a brief note in the Target Architecture section or an earlier plan item would make this document more self-contained for future readers.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@todos/pikachatd-openclaw-pi-acp-plan.md` around lines 226 - 229, Clarify the
undefined term "microVM agent path" referenced in Item 16 by adding a short
explanatory sentence in the Target Architecture section (or an earlier plan
item) that defines what the microVM agent path means in this project: e.g., that
it refers to the execution flow where a microVM-launched agent binary (the
ACP-capable agent such as "pi-acp") is started and communicated with via ACP
rather than running Pi logic locally in pikachatd; update Item 16 to reference
this definition so readers can understand that the acceptance criteria require
pikachatd to invoke the microVM agent path and to drop any remaining Pika-owned
local prompt execution, adapter fallback, or direct model HTTP fallback logic.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@todos/pikachatd-openclaw-pi-acp-plan.md`:
- Around line 303-307: The four repeated "Do not" lines in the goals section are
stylistically repetitive; reword them to vary sentence structure while
preserving meaning—e.g., change "Do not make OpenClaw depend on ACP for its
primary happy path" to "Avoid making OpenClaw depend on ACP for its primary
happy path," change "Do not embed Pi-specific prompt logic into `pikachatd`" to
"Avoid embedding Pi-specific prompt logic into `pikachatd`," and similarly vary
the others referencing `OpenClaw`, `ACP`, `pikachatd`, `Pi`, and `pi-acp` so
each line reads differently (use "Avoid," "Do not," or active phrasing) for
improved readability.
- Around line 226-229: Clarify the undefined term "microVM agent path"
referenced in Item 16 by adding a short explanatory sentence in the Target
Architecture section (or an earlier plan item) that defines what the microVM
agent path means in this project: e.g., that it refers to the execution flow
where a microVM-launched agent binary (the ACP-capable agent such as "pi-acp")
is started and communicated with via ACP rather than running Pi logic locally in
pikachatd; update Item 16 to reference this definition so readers can understand
that the acceptance criteria require pikachatd to invoke the microVM agent path
and to drop any remaining Pika-owned local prompt execution, adapter fallback,
or direct model HTTP fallback logic.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b374adb5-d04f-4b32-a453-97f40631c003

📥 Commits

Reviewing files that changed from the base of the PR and between a5dfe40 and d60b699.

📒 Files selected for processing (1)

• todos/pikachatd-openclaw-pi-acp-plan.md