用途：把最新发布的 Pi Agent API 接入消费方应用、库、运行时或 agent harness，实现稳定的流式输出、正确的队列语义，并尽量缩小包装层。
主要能力与用法：先按请求分类再动手——涉及 Agent、循环、provider、stream 或工具 API 时读 references/api-surface.md；在消费方加入 Pi 行为读 references/common-use-cases.md；使用内置 harness、会话、技能、资源或压缩读 references/harness.md；排查流式、工具、队列、续跑、代理或中止问题读 references/troubleshooting-workarounds.md。跨类时只加载相关参考。
集成约束：以 npm 上 @earendil-works/pi-agent-core 的 latest 为准；需要等待事件参与运行结算时用 Agent，仅需观察事件流时用底层 agentLoop；用户可见文本只从 message_update 中 assistantMessageEvent.type === "text_delta" 输出；转发多消息时保留助手消息边界；agent 活跃时不要调用 prompt() 或 continue()，中途输入用 steer() 或 followUp() 排队；continue() 从非空 user 或 toolResult 尾部恢复，assistant 尾部只能排空已排队的 steering/follow-up，否则抛错；streamFn、convertToLlm、transformContext、getApiKey、队列 provider 与循环钩子对预期失败不应抛出，应返回安全值或在协议事件中编码失败；工具调用、进度、结果、思考增量与 provider 载荷默认保持内部。需要会话、技能、提示模板、资源、文件系统/Shell 环境、压缩或树导航时优先用内置 harness。
实现建议：优先使用 Pi 选项而非自建状态机，如 streamFn、getApiKey、sessionId、thinkingBudgets、transport、maxRetryDelayMs、onPayload、onResponse、beforeToolCall、afterToolCall、prepareNextTurn、toolExecution、steeringMode、followUpMode；通过 agent.state 属性与 reset() 修改状态；用 transformContext 做消息级裁剪/注入，用 convertToLlm 做 provider 兼容的角色转换/过滤；队列模式显式指定 "one-at-a-time" 或 "all"；服务端代理访问用 streamFn 的 streamProxy 风格；工具策略用 toolExecution、每工具 executionMode、beforeToolCall、afterToolCall、工具抛错与 terminate。
验证与版本：检查事件到流的桥接只发文本增量、边界正确、成功/错误/中止均关闭；检查 prompt()/continue() 竞态与排队行为；检查 continue() 在空历史、user 尾、toolResult 尾、assistant 尾（含/不含排队消息）下的前置条件；检查自定义消息类型保留在状态中而 convertToLlm 只发兼容消息；检查 streamFn 编码失败而非抛出；检查工具并行/顺序、钩子阻断、进度与 terminate；检查 Agent.subscribe() 与 waitForIdle() 的异步结算；使用 harness 时检查会话、资源、钩子、压缩与中止。只面向最新发布包，重大更新前重新核对包元数据与声明，不添加向后兼容垫片或旧包名指引，除非用户明确要求迁移。
限制：资料未提供具体版本号、安装命令、代码示例与平台支持范围，暂未提供。