feat: add Pi Coding Agent support

[zhushanwen321]

Summary

Closes #840

Add Pi Coding Agent as a first-class agent flavor. Pi has a built-in --mode rpc that speaks JSONL over stdin/stdout. The integration follows the same subprocess pattern as Codex — spawn agent process, communicate via stdio pipes, receive real-time event stream. No ACP dependency.

Feature Coverage

Core features

Feature	Status	Key files
Register as agent flavor	✅	shared/modes.ts flavors.ts schemas.ts
CLI command (hapi pi)	✅	cli/commands/pi.ts registry.ts
Session create / resume / kill	✅	cli/pi/session.ts loop.ts runPi.ts
Text messaging + streaming output	✅	piTransport.ts piMessageAccumulator.ts piEventConverter.ts
Abort generation	✅	loop.ts
Model switching	✅	runPi.ts — provider learned from get_state
Tool call display	✅	piEventConverter.ts
Dynamic model discovery	✅	CLI auto-discovery → hub callPiRpc → web usePiModels.ts → model dropdown grouped by provider
Thinking Level (6 levels)	✅	PiThinkingLevelPanel.tsx — auto-filters levels per model's capability
Permission mode (default / yolo)	✅	PiPermissionPanel.tsx
Dedicated Pi composer toolbar	✅	Two Pi-specific pill buttons in composer toolbar (model selector + thinking level) with dropdown panels (PiModelPanel.tsx + PiThinkingLevelPanel.tsx). PiPermissionPanel.tsx in settings popover
Web UI agent icon	✅	AgentFlavorIcon.tsx
Context budget bar	✅	modelConfig.ts — 200K window

Extended features

Feature	Status	Notes
Skills / slash commands	✅ Full stack	CLI: get_commands → generic listSlashCommands → web autocomplete
Steer (mid-stream steering)	✅ Transparent	User messages auto-routed as steer when Pi is streaming

Not implemented (out of scope)

Follow-up, Queue modes, History replay, Compact, Fork, Clone, Switch session, Session stats, HTML export. Wireable via callPiRpc / callPiEndpoint generics when needed.

New vs Modified Files

21 new files:

• cli/src/pi/ — 8 source files + 5 test files
• web/ — 6 Pi UI components + usePiModels.ts hook

28 modified existing files across all 4 packages. All changes follow one of three zero-impact patterns:

1. Enum / Record extension — add 'pi' key, no existing entries changed
2. If-else branch addition — === 'pi' appended at chain tail
3. New method addition — callPiRpc<T> / callPiEndpoint<T>, no existing methods modified

Notable hub-side changes (affect all agents)

• sessions.ts effort endpoint uses supportsEffort() from shared flavors instead of hardcoded flavor !== 'claude'
• syncEngine.applySessionConfig surfaces actual CLI error messages instead of generic "Missing applied session config"
• sessionCache normalizes { provider, modelId } model object to plain string for DB storage (prevents [object Object])

Notable shared changes

• SessionModelRequestSchema accepts { provider, modelId } object form in addition to plain string
• MetadataSchema adds optional piAvailableModels for offline model list fallback
• PiModelSummary includes reasoning and thinkingLevelMap fields for per-model thinking level filtering

Known Limitation

Pi's RPC mode has no tool permission approval mechanism — tools execute automatically. HAPI's "approve tool calls from phone" won't work for Pi. The permission selector offers default and yolo only.

Test Coverage

• Unit tests: 29 cases in cli/src/pi/, all pass
• E2E protocol tests: 15 cases against live Pi RPC, 12 pass
• Automated: bun run typecheck all 3 packages pass, bun run build:web succeeds

[github-actions]

Findings

• [Major] Startup --model is never applied to Pi — runPi stores opts.model in HAPI state, but the subprocess is launched only with --mode rpc / --session-id and the startup sequence sends only new_session, get_state, get_available_models, and get_commands. get_state can then overwrite piSession.currentModel with Pi's default before any set_model is sent, so hapi pi --model ... or a runner-spawned Pi session with a model starts on the wrong model. Evidence: cli/src/pi/runPi.ts:63, cli/src/pi/runPi.ts:286.
  Suggested fix:

  const startupModel = opts.model?.trim() || null
  
  transport.start()
  transport.send({ type: 'new_session' })
  transport.send({ type: 'get_state' })
  
  if (startupModel) {
      const data = await sendPiRpcAndWait(piSession, transport, { type: 'get_available_models' }, 120_000)
      const models = parsePiModels(data)
      piSession.cachedPiModels = models
      const selected = models.find((model) => model.modelId === startupModel)
      if (!selected) throw new Error(`Pi model not found: ${startupModel}`)
      piSession.currentModel = selected.modelId
      piSession.currentProvider = selected.provider
      transport.send({ type: 'set_model', provider: selected.provider, modelId: selected.modelId })
  } else {
      transport.send({ type: 'get_available_models' })
  }

• [Major] Lockfile keeps two versions for the same Windows artifact — the added @twsxtd/hapi-win32-x64@0.20.0 entry reuses the same package key immediately after the existing 0.20.1 entry, so parsers that take the last key can resolve the Windows optional package back to the older artifact. This makes installs non-reproducible and can ship the wrong binary on Windows. Evidence: bun.lock:1079.
  Suggested fix:

  -    "@twsxtd/hapi-win32-x64": ["@twsxtd/hapi-win32-x64@0.20.0", "", { "os": "win32", "cpu": "x64", "bin": { "hapi": "bin/hapi.exe" } }, "sha512-1GWfncMeaZvBIfSB0RY4UI4ywiKUtOAi41nRHxqUI/VdWS9Rw3syCRa4bH2gFJzrdRtDdi0kfSib9YRHs1uQgg=="],

Summary

• Review mode: initial
• Found two major issues introduced by the diff: Pi startup model selection is ignored, and the lockfile has a duplicate Windows package entry.

Testing

• Not run: bun is not installed in this Actions environment (/bin/bash: bun: command not found).

HAPI Bot

[github-actions]

[MAJOR] Startup --model is never applied to Pi. opts.model initializes HAPI's session state, but the Pi subprocess receives only --mode rpc / --session-id; the later startup sends do not send set_model, and get_state can overwrite piSession.currentModel with Pi's default before any model switch happens. This means hapi pi --model ... and runner-spawned Pi sessions with a model can silently start on the wrong model.

Suggested fix:

const startupModel = opts.model?.trim() || null

transport.start()
transport.send({ type: 'new_session' })
transport.send({ type: 'get_state' })

if (startupModel) {
    const data = await sendPiRpcAndWait(piSession, transport, { type: 'get_available_models' }, 120_000)
    const models = parsePiModels(data)
    piSession.cachedPiModels = models
    const selected = models.find((model) => model.modelId === startupModel)
    if (!selected) throw new Error(`Pi model not found: ${startupModel}`)
    piSession.currentModel = selected.modelId
    piSession.currentProvider = selected.provider
    transport.send({ type: 'set_model', provider: selected.provider, modelId: selected.modelId })
} else {
    transport.send({ type: 'get_available_models' })
}

[github-actions]

[MAJOR] This adds a second @twsxtd/hapi-win32-x64 package entry with version 0.20.0 right after the existing 0.20.1 entry. Because the key is identical, parsers that keep the last value can resolve the Windows optional package back to the older artifact, making installs non-reproducible and shipping the wrong Windows binary.

Suggested fix:

-    "@twsxtd/hapi-win32-x64": ["@twsxtd/hapi-win32-x64@0.20.0", "", { "os": "win32", "cpu": "x64", "bin": { "hapi": "bin/hapi.exe" } }, "sha512-1GWfncMeaZvBIfSB0RY4UI4ywiKUtOAi41nRHxqUI/VdWS9Rw3syCRa4bH2gFJzrdRtDdi0kfSib9YRHs1uQgg=="],

[github-actions]

Findings

• [Major] Pi abort ends the whole session instead of cancelling the current turn — the abort RPC sends Pi's abort command and then immediately starts lifecycle cleanup, which archives/ends the active HAPI session. The composer abort button is wired to /sessions/:id/abort for stopping a running generation, and existing Claude/OpenCode handlers keep the session alive after abort. Evidence: cli/src/pi/runPi.ts:271.
  Suggested fix:

  apiSession.rpcHandlerManager.registerHandler(RPC_METHODS.Abort, async () => {
      transport.send({ type: 'abort' })
      piSession.piIsStreaming = false
      piSession.updateThinkingState(false)
      if (pendingLocalIds.length > 0) {
          piSession.emitMessagesConsumed([pendingLocalIds.shift()!], { clearQueuedThinkingGrace: true })
      }
      return { success: true }
  })

• [Major] Clearing Pi thinking level is acknowledged but not applied — the Pi panel sends null when the selected level is clicked again, and the CLI returns that value as applied, but the forwarding block only sends set_thinking_level when currentThinkingLevel is truthy. The hub/web will show the level as cleared while Pi keeps using the previous level. Evidence: cli/src/pi/runPi.ts:186, web/src/components/AssistantChat/PiThinkingLevelPanel.tsx:52.
  Suggested fix:

  const shouldUpdateThinkingLevel = config.effort !== undefined
  if (config.effort !== undefined) {
      if (config.effort === null) {
          piSession.currentThinkingLevel = 'off'
      } else {
          const result = PiThinkingLevelSchema.safeParse(
              typeof config.effort === 'string' ? config.effort.trim().toLowerCase() : config.effort,
          )
          if (!result.success) throw new Error('Invalid effort')
          piSession.currentThinkingLevel = result.data
      }
  }
  
  if (shouldUpdateThinkingLevel && piSession.currentThinkingLevel) {
      transport.send({ type: 'set_thinking_level', level: piSession.currentThinkingLevel })
  }

Summary

• Review mode: follow-up after new commits
• The prior lockfile duplicate was fixed. The new Pi control path still has two major state-sync problems: abort tears down the session, and clearing thinking level only updates HAPI state.

Testing

• Not run (automation review; did not execute PR code). Also note: e2e/scratchlist.spec.ts was deleted with no replacement found in the PR, so scratchlist browser coverage is reduced.

HAPI Bot

[github-actions]

[MAJOR] This makes the abort button end the Pi session instead of just cancelling the current generation. /sessions/:id/abort is the composer stop action, and the existing Claude/OpenCode handlers cancel the turn while leaving the session alive; calling cleanupAndExit() here marks the session ended immediately after sending Pi's abort command.

Suggested fix:

apiSession.rpcHandlerManager.registerHandler(RPC_METHODS.Abort, async () => {
    transport.send({ type: 'abort' })
    piSession.piIsStreaming = false
    piSession.updateThinkingState(false)
    if (pendingLocalIds.length > 0) {
        piSession.emitMessagesConsumed([pendingLocalIds.shift()!], { clearQueuedThinkingGrace: true })
    }
    return { success: true }
})

[github-actions]

[MAJOR] Clearing a Pi thinking level is acknowledged but never forwarded to Pi. The UI sends null when the selected level is clicked again, this handler stores currentThinkingLevel = null and returns it in applied, but the send block only calls set_thinking_level for truthy values. The web/hub will show the level as cleared while the Pi process keeps using the previous level.

Suggested fix:

const shouldUpdateThinkingLevel = config.effort !== undefined
if (config.effort !== undefined) {
    if (config.effort === null) {
        piSession.currentThinkingLevel = 'off'
    } else {
        const result = PiThinkingLevelSchema.safeParse(
            typeof config.effort === 'string' ? config.effort.trim().toLowerCase() : config.effort,
        )
        if (!result.success) throw new Error('Invalid effort')
        piSession.currentThinkingLevel = result.data
    }
}

if (shouldUpdateThinkingLevel && piSession.currentThinkingLevel) {
    transport.send({ type: 'set_thinking_level', level: piSession.currentThinkingLevel })
}

[github-actions]

Findings

• [Major] Pi abort ends the whole HAPI session instead of cancelling the active turn — the web composer abort action routes to /sessions/:id/abort to stop an in-flight generation, but this handler sends Pi abort and then immediately runs lifecycle cleanup, which marks the session ended/archived. That makes a normal stop button terminate the remote session instead of leaving it available for the next prompt. Evidence: cli/src/pi/runPi.ts:271.
  Suggested fix:

  apiSession.rpcHandlerManager.registerHandler(RPC_METHODS.Abort, async () => {
      transport.send({ type: 'abort' })
      piSession.piIsStreaming = false
      piSession.updateThinkingState(false)
      if (pendingLocalIds.length > 0) {
          piSession.emitMessagesConsumed([pendingLocalIds.shift()!], { clearQueuedThinkingGrace: true })
      }
      return { success: true }
  })

• [Major] Clearing Pi thinking level updates HAPI but never tells Pi — the UI sends null when the selected thinking level is clicked again, and this handler returns effort: null as applied, but the outbound command is guarded by if (piSession.currentThinkingLevel). The hub/web will show thinking cleared while the Pi process keeps using the previous level. Evidence: cli/src/pi/runPi.ts:186.
  Suggested fix:

  const shouldUpdateThinkingLevel = config.effort !== undefined
  if (config.effort !== undefined) {
      if (config.effort === null) {
          piSession.currentThinkingLevel = 'off'
      } else {
          const result = PiThinkingLevelSchema.safeParse(
              typeof config.effort === 'string' ? config.effort.trim().toLowerCase() : config.effort,
          )
          if (!result.success) throw new Error('Invalid effort')
          piSession.currentThinkingLevel = result.data
      }
  }
  
  if (shouldUpdateThinkingLevel) {
      transport.send({ type: 'set_thinking_level', level: piSession.currentThinkingLevel })
  }

Summary

• Review mode: follow-up after new commits
• The latest commit only changed an effort endpoint test expectation. The two Pi control-path bugs from the prior bot review remain in the current head.

Testing

• Not run (automation review; static inspection only). Existing tests found for Pi parsing/loop behavior, but not for the abort lifecycle or null thinking-level RPC paths.

HAPI Bot

[github-actions]

[MAJOR] This makes the composer stop button archive/end the Pi session. /sessions/:id/abort is used to cancel the active generation, but calling cleanupAndExit() tears down the HAPI session after sending Pi abort.

Suggested fix:

apiSession.rpcHandlerManager.registerHandler(RPC_METHODS.Abort, async () => {
    transport.send({ type: 'abort' })
    piSession.piIsStreaming = false
    piSession.updateThinkingState(false)
    if (pendingLocalIds.length > 0) {
        piSession.emitMessagesConsumed([pendingLocalIds.shift()!], { clearQueuedThinkingGrace: true })
    }
    return { success: true }
})

[github-actions]

[MAJOR] Clearing the Pi thinking level is acknowledged locally but no command is sent to Pi. When the UI sends effort: null, line 170 stores null, then this truthy guard suppresses set_thinking_level, so the backend keeps the previous level while HAPI reports it cleared.

Suggested fix:

const shouldUpdateThinkingLevel = config.effort !== undefined
if (config.effort !== undefined) {
    if (config.effort === null) {
        piSession.currentThinkingLevel = 'off'
    } else {
        const result = PiThinkingLevelSchema.safeParse(
            typeof config.effort === 'string' ? config.effort.trim().toLowerCase() : config.effort,
        )
        if (!result.success) throw new Error('Invalid effort')
        piSession.currentThinkingLevel = result.data
    }
}

if (shouldUpdateThinkingLevel) {
    transport.send({ type: 'set_thinking_level', level: piSession.currentThinkingLevel })
}