Open workflow-agent sessions in Herdr

Overview

The extension complements pi-extensible-workflows. It registers trusted workflow attempt actions and a transport setup hook. It does not register model-facing tools.

The integration activates only when Pi is running in a valid Herdr-managed pane. Outside Herdr, package loading is inert.

Installation and requirements

Use Node.js 22.19 or newer. Both packages are trusted Pi host code and run with the same filesystem and process access as Pi.

pi install npm:pi-extensible-workflows
pi install npm:@piewf/herdr

Requirements:

• The core workflow extension is loaded.
• Pi is running inside a Herdr-managed pane with Herdr available.
• The project and package code are trusted.
• A live handoff has a transferable session file and an available originating Pi runtime.

Set PI_CODING_AGENT_DIR when the Pi agent directory is not ~/.pi/agent. Herdr reads workflow settings from that directory.

Available `/workflow` actions

Open /workflow, select a run, and select the agent attempt. Only actions valid for the latest attempt are shown.

Fully inspectable mode

Enable fully inspectable mode in the global workflow settings file, normally ~/.pi/agent/pi-extensible-workflows/settings.json:

{
  "extensions": {
    "herdr": {
      "enableFullyInspectableMode": true
    }
  }
}

The setting is global-only. When enabled, every workflow agent launches in a dedicated labeled Herdr workspace and uses the Herdr transport. The manual live-session action is hidden because the session is already in Herdr. Completed-session inspection remains available.

Live handoff and ownership

Live handoff pauses the local SDK at a turn boundary while the Herdr pane owns the task. The originating Pi TUI reports the handed-off agent as working, then idle or completed before handback.

Ownership returns when the pane exits, the user runs /quit, or Herdr observes a pane return to idle after it has been working. The local SDK then resumes the same session. If the last assistant message was aborted or ended on a tool call without the expected result, the workflow asks the local session to continue.

Stopping or disposing the workflow closes active Herdr panes, bridges, and owned workspaces before the underlying local session is disposed.

What the handoff preserves

• The originating Pi executable and entrypoint.
• The native session file and selected model and thinking level.
• Allowed built-in tools, custom tools, and structured-result tools.
• System prompt, appended prompt, selected context files, skills, extensions, and project trust policy.
• Workflow identity, labels, worktree cwd, and lifecycle reporting.

Custom tools are bridged back to the owning process. Transferable inline extension factories are materialized as temporary explicit extensions. Temporary bridge files use private permissions; command, prompt, extension, and socket artifacts are cleaned after the pane closes.

Interruption behavior and limitations

• Herdr's Pi screen detection cannot distinguish an aborted turn from a completed turn.
• In Pi's default keybindings, use double-Escape to abort a turn.
• A single Ctrl-C clears the editor and double-Ctrl-C exits Pi, so Ctrl-C is not a handback signal.
• Lifecycle reports from this extension are advisory when Herdr's built-in Pi integration has authority.
• Completed-session opening is inspection only and uses a restricted tool set.