# BRB Host Contract（M1，verdict #22 — 规划文档，非当前实现）

> 状态：**规划/原型**。不搬现有代码；目标是证明现有 pi 适配（index.ts + driver.ts + control.ts）
> 可以完整映射到这组接口，之后才允许跨平台演化（M3 Decision Gate 后 monorepo）。
> 现有 27 个纯核心模块（protocol/handshake/cycle/sideEffects/recovery/run/onboarding/identity/
> cdp/chatgpt/…）均不依赖 pi，构成这套契约的 Core 侧。

## 分层

```
BRB Core（ChatGPT 网页会话侧）
  browser / binding / identity / capability / delivery / recovery / protocol / state / diagnostics

Pi integration（Pi Agent 侧）
  session / workspace / lifecycle / execution / ui / commands / persistence

中间只有一份：BRB Host Contract（本文档的接口）
```

规则：Pi integration 必须保持薄。它不能重实现 delivery、recovery 或 binding。
Core 不得 import Pi integration（由 CI canonical negative 强制约束）。

## 六个 Port（TypeScript 原型）

```ts
// HostIdentity — 平台无关的稳定会话身份（不解释内容，只要求 opaque）
export interface HostIdentity {
	getSessionId(): string;          // pi: ctx.sessionManager.getSessionId()
	getWorkspace(): { cwd: string; workspaceRoot?: string; repoRoot?: string }; // pi: ctx.cwd
}

// HostUI — 全部能力可选（CLI 无 select 也必须能跑）
export interface HostUI {
	notify?(text: string, level?: "info" | "warning" | "error"): void;
	confirm?(title: string, body: string): Promise<boolean>;
	select?(title: string, options: string[]): Promise<string | undefined>;
	input?(title: string, placeholder?: string): Promise<string | undefined>;
	setStatus?(key: string, text: string | undefined): void;
	hasUI(): boolean;
}

// HostLifecycle — Core 需要知道"本轮执行已稳定结束"
export interface HostLifecycle {
	onSessionStart?(cb: () => void): void;
	onSessionEnd?(cb: () => void): void;
	onTurnCompleted?(cb: (info: { lastLeafId?: string }) => void): void; // pi: agent_settled
}

// HostCommandSurface — 暴露方式平台定（slash/MCP tool/plugin command/button）
export interface HostCommandSurface {
	registerAction(name: string, opts: { description: string; handler: (args: string, ctx: HostActionContext) => Promise<void> }): void;
}
export interface HostActionContext { identity: HostIdentity; ui: HostUI; }

// HostExecution — 跨平台差异最大的一层抽象
export interface HostExecution {
	dispatchTask(task: string, opts?: { deliverAs?: "user" | "followUp" }): Promise<void>; // pi: pi.sendUserMessage
	waitForCompletion(timeoutMs?: number): Promise<{ leafId?: string; text?: string }>;
	getResult(): Promise<string | null>;
}

// HostPersistence — Pi 侧配置根目录/会话元数据；BRB durable schema 仍属 Core
export interface HostPersistence {
	configRoot(): string;
	loadConfig<T>(key: string): T | undefined;
	saveConfig<T>(key: string, value: T): void;
}
```

## 现有映射（证明可映射，验收 M1）

| Port | pi 实现（现状） |
|---|---|
| HostIdentity | `localSessionId(ctx)` / `ctx.cwd` |
| HostUI | `ctx.ui.notify/confirm/select/input/setStatus` |
| HostLifecycle | `pi.on("agent_settled" / "session_start" / "session_shutdown")` |
| HostCommandSurface | `pi.registerCommand("brb", …)` + `getArgumentCompletions` |
| HostExecution | `pi.sendUserMessage` / `deliver(ctx, text)` |
| HostPersistence | `paths.ts`（config root / state root） |

## 明确不泛化（留在 Pi integration）

/brb 补全、qbtn 风格 completion、ctx.ui.select 具体表现、Pi shortcut/status line、
agent_settled 原始事件、Pi session branch/leaf UI、Pi Package 打包、Pi onboarding 文案、
Pi registerTool schema。同理，未来任何其它宿主的 hook 也不能反向污染 Core。