Import Herdr-hosted Pi sessions as live agents

[HackXIt]

Linked issue / discussion

Product discussion: #4070

I initially opened this workflow context as issue #4045, then moved it to a Discussion and closed the issue because CONTRIBUTING.md says feature requests belong in Discussions rather than Issues.

Type of change

• Bug fix
• New feature
• Enhancement
• Refactor
• Docs

Reasoning

I built this for my own workflow: I run Pi inside Herdr, then use Paseo mobile when I am away from the keyboard and want to respond to the same running session.

Before this change, that workflow has an awkward split. The real Pi session can keep running in the Herdr terminal, but Paseo mobile cannot import it as a live agent. Starting a separate Paseo-managed Pi process works technically, but it is not the session I was trying to continue.

This PR adds the smallest integration layer I could find: Herdr-attached sessions still show up as normal provider=pi agents. Herdr is only used as the transport for the existing terminal target, and Pi's own JSONL session history remains the source of truth for timeline catch-up.

The implementation was written with Codex. I chose the approach, tested the result in my own workflow, and I am happy to clean up or reshape the code if the abstraction is not what you want in Paseo.

Goals

• Let the Pi provider discover eligible Herdr Pi targets for Import session when Herdr discovery is configured.
• Import a Herdr target without starting a managed pi --mode rpc process.
• Persist enough attachment identity to reconnect safely: Herdr target/session, native Pi session ID, native session file, cwd, and pane ID when available.
• Send prompts and interrupts from Paseo through Herdr to the terminal-owned Pi session.
• Reconcile terminal-side activity back into Paseo from Pi's native JSONL history.
• Keep normal Paseo-managed Pi sessions on their existing RPC path.
• Document the configuration and include a disposable smoke-test helper.

Non-goals

• Add Herdr as a first-class agent provider.
• Have Paseo manage Herdr lifecycle.
• Add token-by-token streaming for Herdr-attached sessions.
• Change import behavior for other providers.

QA

Public evidence:

• Branch: https://github.com/HackXIt/paseo/tree/feature/herdr-attached-pi-live
• Main implementation commit: HackXIt@16b2d2f
• Follow-up live test repair: HackXIt@61567e8
• Docs and smoke-helper cleanup: HackXIt@c2b2eab
• Fork CI run after the rebase: https://github.com/HackXIt/paseo/actions/runs/33305635674

Local validation I ran on the upstream-based branch:

npm run format:check:files -- docs/custom-providers.md docs/providers.md packages/server/src/server/agent/agent-manager.ts packages/server/src/server/agent/agent-sdk-types.ts packages/server/src/server/agent/providers/pi/agent.ts packages/server/src/server/agent/providers/pi/herdr-attached-session.test.ts packages/server/src/server/agent/providers/pi/herdr-attached-session.ts packages/server/src/server/agent/providers/pi/herdr-attachment.test.ts packages/server/src/server/agent/providers/pi/herdr-attachment.ts packages/server/src/server/agent/providers/pi/herdr-client.test.ts packages/server/src/server/agent/providers/pi/herdr-client.ts packages/server/src/server/agent/providers/pi/native-history.test.ts packages/server/src/server/agent/providers/pi/native-history.ts scripts/herdr-pi-live-smoke.sh
npm run lint -- docs/custom-providers.md docs/providers.md packages/server/src/server/agent/agent-manager.ts packages/server/src/server/agent/agent-sdk-types.ts packages/server/src/server/agent/providers/pi/agent.ts packages/server/src/server/agent/providers/pi/herdr-attached-session.test.ts packages/server/src/server/agent/providers/pi/herdr-attached-session.ts packages/server/src/server/agent/providers/pi/herdr-attachment.test.ts packages/server/src/server/agent/providers/pi/herdr-attachment.ts packages/server/src/server/agent/providers/pi/herdr-client.test.ts packages/server/src/server/agent/providers/pi/herdr-client.ts packages/server/src/server/agent/providers/pi/native-history.test.ts packages/server/src/server/agent/providers/pi/native-history.ts scripts/herdr-pi-live-smoke.sh
npm run typecheck
npx vitest run packages/server/src/server/agent/providers/pi/herdr-attached-session.test.ts packages/server/src/server/agent/providers/pi/herdr-attachment.test.ts packages/server/src/server/agent/providers/pi/herdr-client.test.ts packages/server/src/server/agent/providers/pi/native-history.test.ts --bail=1
# 4 files / 26 tests passed
npx vitest run packages/server/src/server/agent/agent-manager.test.ts --bail=1
# 1 file / 168 tests passed
bash -n scripts/herdr-pi-live-smoke.sh

After rebasing away the GitHub-created merge commit, I checked that the patch series is unchanged with git range-diff:

1:  86766d864 = 1:  16b2d2f06 feat(server): support Herdr-attached Pi sessions
2:  45d194a92 = 2:  61567e812 fix(server): discover live Herdr-hosted Pi sessions
3:  a22853bb7 = 3:  c2b2eab86 docs: add repeatable Herdr Pi live smoke workflow

Manual test in my own workflow on Linux:

1. Started a disposable Pi session inside Herdr.
2. Imported that Herdr Pi target into Paseo mobile.
3. Sent a prompt from mobile and confirmed it appeared in the Herdr terminal session.
4. Typed a prompt directly in the Herdr terminal and confirmed the new history synced back to mobile.

I did not test iOS, Android, browser web, macOS desktop, or Windows desktop in this pass. The exercised path is daemon/provider behavior plus the mobile-to-terminal workflow against a Linux Herdr terminal.

Checklist

• One focused change
• npm run typecheck passes
• npm run lint passes
• npm run format passes
• QA evidence included
• Tests added where they made sense

[HackXIt]

The functionality was entirely created by Codex. I personally just needed this, because I wanted to respond to firstmate and running agents inside herdr while AFK on mobile, but not be forced to resume it, but just have it be the exact same session. I chose an abstraction level, that would be least interferring and re-uses what is already there.

Fundamentally it is only an integration specifically for herdr.

I can perform cleanup, or necessary changes, or act on potential criticism of the code.
The PR and issue was created to publicly share the paseo tweak I made for myself.

[boudra]

Closing this feature PR. Please discuss the workflow and shared need in Discussions, following CONTRIBUTING.md.