harbor-pi-sdk-agent 0.1.5

Reusable Harbor custom agent that runs Pi SDK sessions and writes trajectory artifacts.

harbor-pi-sdk-agent

Run the Pi coding agent from Harbor.

Use this package when you want Harbor to launch a Pi SDK agent and collect Harbor-compatible trajectory artifacts.

Mental Model

harbor-pi-sdk-agent is a thin Harbor wrapper around the official Pi coding agent package, @mariozechner/pi-coding-agent.

It is not a provider compatibility layer. Pass Pi's provider/model-id through to this package, and let the Pi SDK registry decide the built-in model API, base URL, and request headers. Only pass base_url, model_api, or provider_headers_json when you intentionally want to override Pi's built-in provider metadata or connect to a compatible custom endpoint.

Install

Install this package into the same Python environment or image that runs Harbor.

From a private package index:

pip install harbor-pi-sdk-agent

From this private GitHub repo:

pip install git+ssh://[e-mail]/Kingwl/harbor-pi-sdk-agent.git

With uv:

uv pip install git+ssh://[e-mail]/Kingwl/harbor-pi-sdk-agent.git

Harbor should already be available in that environment. This package is loaded by import path.

Run

Set the API key for the provider you want to use:

export OPENAI_API_KEY=...

Then pass the agent import path to Harbor:

harbor run \
  --agent-import-path harbor_pi_sdk_agent.agent:PiSdkAgent \
  --agent-kwarg 'model_name=openai/gpt-4.1' \
  --agent-kwarg 'api_key_env=OPENAI_API_KEY'

For another Pi built-in provider:

export DEEPSEEK_API_KEY=...

harbor run \
  --agent-import-path harbor_pi_sdk_agent.agent:PiSdkAgent \
  --agent-kwarg 'model_name=deepseek/deepseek-v4-pro' \
  --agent-kwarg 'api_key_env=DEEPSEEK_API_KEY'

For the Pi built-in Kimi Coding provider:

export KIMI_API_KEY=...

harbor run \
  --agent-import-path harbor_pi_sdk_agent.agent:PiSdkAgent \
  --agent-kwarg 'model_name=kimi-coding/kimi-for-coding' \
  --agent-kwarg 'api_key_env=KIMI_API_KEY'

For a compatible endpoint that is not already described by Pi's provider registry:

export ANTHROPIC_API_KEY=...

harbor run \
  --agent-import-path harbor_pi_sdk_agent.agent:PiSdkAgent \
  --agent-kwarg 'model_name=anthropic/model-id' \
  --agent-kwarg 'api_key_env=ANTHROPIC_API_KEY' \
  --agent-kwarg 'base_url=https://your-anthropic-compatible-endpoint' \
  --agent-kwarg 'model_api=anthropic-messages'

Launcher Setup

In your Harbor launcher or task wrapper, use:

harbor_pi_sdk_agent.agent:PiSdkAgent

Recommended kwargs:

model_name=provider/model-id
api_key_env=PROVIDER_API_KEY
agent_label=pi-sdk
thinking=xhigh

Optional kwargs:

base_url=https://...
model_api=anthropic-messages
provider_headers_json={"User-Agent":"..."}
compaction_enabled=0
compaction_reserve_tokens=16384
compaction_keep_recent_tokens=20000
continue_after_compaction=0
compaction_continuation_prompt=Continue from the compaction summary and complete the original task.
compaction_continuation_max_prompts=1
compaction_settle_ms=15000
compaction_trigger_reserve_tokens=16384
compaction_trigger_min_tokens=3000
extension_paths=/tmp/pi-agent/extensions/my-extension.ts
local_extension_paths=/path/on/host/my-extension.ts
filtered_events=1
progress_events=1
heartbeat_interval_sec=30
provider_timeout_ms=600000
raw_events=0
max_field_chars=200000

Recommended artifacts:

/logs/agent/trajectory.json
/logs/agent/trajectory.steps.jsonl
/logs/agent/pi-filtered.jsonl
/logs/agent/pi-progress.jsonl
/logs/agent/pi-sdk-runner.txt

Add this only when you explicitly want raw SDK events:

/logs/agent/pi-raw.jsonl

Outputs

• trajectory.json: the main Harbor trajectory.
• trajectory.steps.jsonl: step-by-step trajectory stream for long or interrupted runs.
• pi-filtered.jsonl: compact Pi SDK event log.
• pi-progress.jsonl: runner progress events and idle heartbeats.
• pi-raw.jsonl: raw Pi SDK event log when raw_events=1.
• pi-sdk-runner.txt: concise agent stdout, including idle heartbeats during long model calls.

Progress Feedback

Some providers can spend a long time thinking without streaming any Pi SDK event. During those idle periods, this wrapper prints a heartbeat line to pi-sdk-runner.txt and appends a runner_heartbeat event to pi-progress.jsonl.

The default heartbeat interval is 30 seconds. Set heartbeat_interval_sec=0 to disable stdout heartbeats. Set progress_events=0 to disable pi-progress.jsonl.

Heartbeat events are runner telemetry only. They are not written to trajectory.steps.jsonl, so the Harbor trajectory stays focused on real user, agent, and tool steps.

Pi Extensions

This wrapper runs Pi through the SDK, not the pi CLI, so CLI flags such as pi --extension ... do not apply directly. Use one of these Harbor kwargs instead:

• extension_paths: comma- or newline-separated paths that already exist inside the Harbor task environment.
• local_extension_paths: comma- or newline-separated files on the Harbor launcher side. The wrapper copies each file into /tmp/pi-agent/extensions/ before running Pi, then loads the copied container paths.

Compaction events emitted by Pi are written to pi-filtered.jsonl and trajectory.steps.jsonl. Heartbeats remain only in pi-progress.jsonl.

If an extension triggers manual compaction during a Harbor run, set continue_after_compaction=1 to send a follow-up continuation prompt after compaction starts. This keeps Terminal-Bench style single-instruction runs moving after the compacted checkpoint.

Python Usage

Harbor usually creates the agent from the import path. If you need to construct it in Python:

from harbor_pi_sdk_agent import PiSdkAgent

agent = PiSdkAgent(
    logs_dir=logs_dir,
    model_name="openai/gpt-4.1",
    api_key_env="OPENAI_API_KEY",
)

Use this package as a Harbor agent plugin, not as a standalone command-line tool.