Pi Runtime

README

# openclaw-pi-runtime

OpenClaw Runtime Control Plane Plugin — 统一 Runtime 抽象层，将 Pi / tmux / Hermes 等执行后端适配为标准 AgentRuntime 接口。

## 定位

不是 OpenClaw Skill，而是 **Runtime Control Plane Plugin**。

```
OpenClaw Core (Control Plane)
       ↓
Runtime Adapter Layer (本插件)
       ↓
Pi / tmux / Hermes / Local (Execution Backends)
```

类比云原生：OpenClaw = Kubernetes，Pi = Container Runtime，Task = Pod，Artifact = Volume。

## 架构决策

- **RPC 模式**：OpenClaw 通过 RPC 与 Pi 通信，不嵌入 SDK
- **Event Sourcing**：Session JSONL 是 Event Log，Runtime State Machine 是 Authoritative State
- **Soft Steer Only**：第一阶段只允许追加 instruction，禁止强制中断状态机
- **Artifact Store**：产出物独立于 Session，用 artifact:// 协议管理
- **降级策略**：Pi 不可达 → 降级 TmuxRuntime，降级 = 从头开始

## 项目结构

```
openclaw-pi-runtime/
├── openclaw.plugin.json       # Plugin manifest
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts               # Plugin entry point
│   ├── types/
│   │   ├── runtime.ts         # AgentRuntime interface
│   │   ├── events.ts          # TaskEvent / ToolEvent / ArtifactEvent
│   │   ├── state.ts           # RuntimeState / TaskState / SessionState
│   │   └── artifact.ts        # ArtifactMetadata
│   ├── runtime/
│   │   ├── base-runtime.ts    # Abstract base class
│   │   ├── tmux-runtime.ts    # TmuxRuntime (Phase 1)
│   │   ├── pi-runtime.ts      # PiRuntime (Phase 2)
│   │   ├── hermes-runtime.ts  # HermesRuntime (Phase 6, far future)
│   │   └── local-runtime.ts   # LocalRuntime (fallback)
│   ├── event-bus.ts           # Event Bus (Phase 3)
│   ├── artifact-store.ts      # Artifact Store (Phase 4)
│   ├── scheduler/
│   │   ├── queue.ts           # Task Queue (Phase 5)
│   │   └── scheduler.ts      # Task Scheduler (Phase 5)
│   ├── tools/
│   │   ├── runtime-start.ts   # runtime_start tool
│   │   ├── runtime-abort.ts   # runtime_abort tool
│   │   ├── runtime-steer.ts   # runtime_steer tool
│   │   ├── runtime-status.ts  # runtime_status tool
│   │   └── artifact-list.ts   # artifact_list tool (Phase 4)
│   └── cli/
│       └── runtime-cli.ts     # openclaw runtime subcommand
├── plans/
│   └── development-plan.md    # 开发计划
└── tests/
    ├── runtime.test.ts
    ├── tmux-runtime.test.ts
    └── pi-runtime.test.ts
```

## 技术栈

- TypeScript / Node.js
- OpenClaw Plugin API
- Vitest for testing

## License

MIT