Metadata-Version: 2.4
Name: harbor-pi-sdk-agent
Version: 0.1.5
Summary: Reusable Harbor custom agent that runs Pi SDK sessions and writes trajectory artifacts.
Author: Kingwl
License-Expression: LicenseRef-Proprietary
Project-URL: Repository, https://github.com/Kingwl/harbor-pi-sdk-agent
Keywords: harbor,pi,agent,atif,trajectory
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: twine; extra == "dev"

# 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:

```bash
pip install harbor-pi-sdk-agent
```

From this private GitHub repo:

```bash
pip install git+ssh://git@github.com/Kingwl/harbor-pi-sdk-agent.git
```

With `uv`:

```bash
uv pip install git+ssh://git@github.com/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:

```bash
export OPENAI_API_KEY=...
```

Then pass the agent import path to Harbor:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```text
harbor_pi_sdk_agent.agent:PiSdkAgent
```

Recommended kwargs:

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

Optional kwargs:

```text
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:

```text
/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:

```text
/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:

```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.
