@linnlabs/linnkit 0.8.0

package/docs/integration/agent-registration-guide.md

@@ -0,0 +1,330 @@
+# Agent Registration Guide · Agent 注册与装配规范
+
+> **What** · `AgentSpec` 静态蓝图 + `defineAgent` quickstart helper + `contextPolicy` 12 大分组 + 多 agent 协作。
+> **When to read** · 第一次注册 agent；精细化控制上下文；多 agent 串接；做 agent 注册表。
+> **Prerequisites** · [`02-quickstart.md`](./02-quickstart.md)；建议先读 [`tool-development-guide.md`](./tool-development-guide.md) ⭐。
+> **Key exports** · `AgentSpec` / `ToolBindingSpec` / `defineContextPolicy` from `@linnlabs/linnkit/contracts` · `defineAgent` / `runAgent` from `@linnlabs/linnkit/quickstart`。
+> **Related** · [`context-engineering.md`](./context-engineering.md) ⭐ · [`context-fences.md`](./context-fences.md) ⭐ · [`child-runs.md`](./child-runs.md) · [`llm-provider.md`](./llm-provider.md)
+
+linnkit 把 Agent 视为**一等对象**——一个 Agent 是**可序列化的静态蓝图**（`AgentSpec`），不是一段散落的配置 + prompt。这让它能进入 audit / replay / testkit 不变量校验路径。
+
+---
+
+## 0. 一句话分层
+
+| 层 | 是什么 | 谁持有 |
+|----|--------|--------|
+| **`AgentSpec`** | 蓝图：id / version / 工具集 / contextPolicy / model hints | host 装配期注册到 registry |
+| **`AgentInvocationRequest`** | 一次调用：query / history / fences / modelId | runtime 每次调用构造 |
+
+修改 `AgentSpec` = 版本升级（需 audit）；修改 `AgentInvocationRequest` = 运行期决策（不需 audit）。
+
+---
+
+## 1. 在哪里定义 Agent · 示例
+
+> **TL;DR**：一个 Agent 一个文件 / 子目录。**Quickstart** → `agents/<id>.ts`；**生产 host** → `agent-registry/<id>/spec.ts`。linnkit 不规定路径——下面是推荐形态。
+
+### 1.1 Quickstart 形态（demo / 试用 / 单测）
+
+```text
+my-agent-demo/
+├── tools/searchDocs.ts          # SearchDocsTool extends BaseTool
+├── agents/
+│   ├── pptAssistant.ts          # defineAgent({...})
+│   └── emailWriter.ts
+└── main.ts                       # runAgent(agent, { input, llm })
+```
+
+### 1.2 生产 host 形态（产品里长期维护）
+
+```text
+app-hosts/<your-app>/
+├── agent-registry/
+│   ├── index.ts                 # 集中导出 + 注册到 host registry
+│   ├── pptAssistant/
+│   │   ├── spec.ts              # AgentSpec.parse({...})
+│   │   ├── prompt.ts            # systemPrompt（host 自管，不进 AgentSpec）
+│   │   └── tools.ts             # toolId 字符串数组
+│   └── emailWriter/spec.ts
+├── adapters/{tools,llm}/
+└── runtime-assembly/             # GraphExecutor 装配
+```
+
+### 1.3 新加一个 Agent · 三步走
+
+| 步 | Quickstart | 生产 host |
+|----|------------|----------|
+| 1. 入口 API | `defineAgent()` from `@linnlabs/linnkit/quickstart` | `AgentSpec.parse()` from `@linnlabs/linnkit/contracts` |
+| 2. 建文件 | `agents/<id>.ts` 一个文件 | `agent-registry/<id>/spec.ts` 一个子目录 |
+| 3. 注册 | `import` 给 `runAgent()` | `agent-registry/index.ts` 集中 `AgentRegistry.register(spec)` |
+
+> `AgentRegistry` 是 host 自己实现的（最简就是 `Map<string, AgentSpec>`）——linnkit 协议层不规定形状。详见 §6.1。
+
+---
+
+## 2. `AgentSpec` 字段速查
+
+```ts
+import { AgentSpec, defineContextPolicy } from '@linnlabs/linnkit/contracts';
+
+const spec = AgentSpec.parse({
+  id: 'pptAssistant',
+  version: '1.2.3',
+  capabilities: ['agent', 'createPpt'],
+  tools: [{ toolId: 'search_docs', argsSchema: searchDocsTool.parameters }],
+  contextPolicy: defineContextPolicy({
+    profileId: 'agent',
+    budget: { maxTokens: 128_000 },
+  }),
+  role: 'PPT 制作助手',           // ⚪
+  modelHints: { preferredProviders: ['anthropic'] }, // ⚪
+  audit: { redactionLevel: 'standard', pii: false }, // ⚪
+  metadata: {},                    // ⚪ host 业务字段，不要升格为协议字段
+});
+```
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `id` | ✅ | host registry 唯一标识；audit / replay / telemetry 全部用它 |
+| `version` | ✅ | semver；任何协议级改动 bump 这里（见 §7） |
+| `capabilities` | ✅ | 能力声明字符串数组；host 路由 / 权限决策可用 |
+| `tools` | ✅ | `ToolBindingSpec[]` —— 见 §3 |
+| `contextPolicy` | ✅ | **必须**用 `defineContextPolicy()` helper —— 见 §4 |
+| `role` / `description` / `modelHints` / `audit` / `metadata` | ⚪ | 见上方示例 |
+
+---
+
+## 3. `tools` 字段：`ToolBindingSpec[]`
+
+```ts
+tools: [
+  { toolId: 'search_docs', argsSchema: searchDocsTool.parameters },
+  { toolId: 'search_docs', argsSchema: ..., bindingId: 'search_v2', config: { topK: 10 } },
+]
+```
+
+**核心约束**：
+
+1. **`argsSchema` 是可序列化 JSON Schema 副本**——直接塞 runtime `zod` 对象会被协议层拒绝（让 `AgentSpec` 不可 audit / replay）。
+2. **`toolId` ≠ `BaseTool` 实例**——`AgentSpec` 只持名字字符串，实际工具实例由 host 的 `ToolRuntimePort` 管理。
+3. **同一 `toolId` 可绑定多次**——用 `bindingId` 区分（如同一搜索工具配两套 `topK`）。
+4. **`config` / `metadata` 是 host 自由字段**——framework 不解读。
+
+---
+
+## 4. `contextPolicy` 与 `defineContextPolicy()`
+
+```ts
+import { defineContextPolicy } from '@linnlabs/linnkit/contracts';
+
+const contextPolicy = defineContextPolicy({
+  profileId: 'agent',
+  budget: { maxTokens: 128_000, reservedForResponse: 8_000 },
+  toolHistory: { strategy: 'per-run', overflowStrategy: 'keep-latest' },
+  summarization: { enabled: true, agentId: 'summarizer', triggerThreshold: 0.8 },
+});
+```
+
+12 大分组的详细说明见 [`context-engineering.md`](./context-engineering.md) ⭐。
+
+> ⚠️ **不要手写 `AgentSpecContextPolicy` 对象**——`defineContextPolicy()` 不只补默认值，还**校验组合约束**（如 `summarization.enabled = true` 必须有 `agentId`）。手写绕过 helper 会在运行时崩溃。
+
+### 4.1 `maxTokens` 谁来算？
+
+linnkit 内置默认 tokenizer（`tiktoken` + 字节比兜底），用于 `contextPolicy.budget` 决策。三种调整方式：
+
+| 你的场景 | 推荐做法 |
+|---------|---------|
+| 试用 / 默认行为够用 | 不动 |
+| GPT-4o 系 | `tokenEstimation: { encoding: 'o200k_base' }` |
+| 中文为主 | `tokenEstimation: { avgCharsPerToken: 1.7 }` |
+| 严格按真实 Claude/Gemini 计费做预算 | 注入自定义 `TokenizerPort`（见 [`context-engineering.md §9.4`](./context-engineering.md)） |
+
+linnkit **不**做：跨 provider 统一计费 token 数协议（不同模型口径不一样）。计费 token 走 provider `usage`。
+
+### 4.2 摘要 agent：`summarization.agentId`
+
+被动摘要（`contextPolicy.summarization`）会把一批旧消息交给 host 注册表里的**无工具**摘要 agent/chat；framework 不写摘要 prompt、不直接裸调 LLM。接入顺序：**先在 host 侧注册摘要项** → **再让业务 `AgentSpec` 的 `summarization.agentId` 指向该注册 id**。
+
+```ts
+// ① host：注册一个无工具的摘要 agent/chat（表单项形状随 host 而定；核心是 id 可被解析、tools 为空）
+//    例如注册 id: 'history_compression'，并自行装配 prompt / 模型。
+
+// ② 业务 AgentSpec.contextPolicy（片段）
+defineContextPolicy({
+  profileId: 'agent',
+  summarization: {
+    agentId: 'history_compression',
+    triggerThreshold: 0.72,
+    failureBehavior: 'continue-if-within-budget',
+  },
+}),
+```
+
+- `agentId` 必须在 host 注册表里存在；未知 id 应在装配期失败。
+- 摘要 agent **不要带工具**，否则摘要路径可能二次进工具循环。
+- `failureBehavior: 'continue-if-within-budget'`：仅当当前上下文仍不超预算时可继续用原文；**已超预算仍会 fail-fast**。字段语义与阈值细则见 [`context-engineering.md`](./context-engineering.md) §5.4。
+
+---
+
+## 5. 两种注册 API
+
+### 5.1 生产：`AgentSpec.parse()`
+
+```ts
+// agent-registry/pptAssistant/spec.ts
+import { AgentSpec, defineContextPolicy } from '@linnlabs/linnkit/contracts';
+
+export const pptAssistantSpec = AgentSpec.parse({
+  id: 'pptAssistant',
+  version: '1.2.3',
+  capabilities: ['agent', 'createPpt'],
+  tools: [{ toolId: 'search_docs', argsSchema: searchDocsToolSchema }],
+  contextPolicy: defineContextPolicy({ profileId: 'agent', budget: { maxTokens: 128_000 } }),
+  modelHints: { preferredProviders: ['anthropic'] },
+});
+```
+
+### 5.2 Quickstart：`defineAgent()`
+
+```ts
+import { defineAgent } from '@linnlabs/linnkit/quickstart';
+
+export const pptAssistant = defineAgent({
+  id: 'pptAssistant',
+  version: '1.2.3',
+  role: 'PPT 制作助手',
+  systemPrompt: '你是 ...',
+  modelId: 'claude-sonnet-4',
+  capabilities: ['agent', 'createPpt'],
+  tools: [new SearchDocsTool()],
+  contextPolicy: { budget: { maxTokens: 128_000 } },
+});
+```
+
+| 维度 | `defineAgent()` | `AgentSpec.parse()` |
+|------|----------------|---------------------|
+| 工具引用 | 持有 `BaseTool` 实例 | 只持 `toolId` 字符串 |
+| systemPrompt | 必填，由 helper 持有 | 不存在（host 自管 prompt 装配）|
+| modelId | helper 字段 | 走 `modelHints` |
+| 用途 | demo / 测试 / 5 分钟入门 | 生产 host 接入 |
+
+完整 quickstart demo 见 [`02-quickstart.md`](./02-quickstart.md)。
+
+---
+
+## 6. 生产 host 装配 · 三件事
+
+### 6.1 实现 `AgentRegistry`
+
+linnkit 不规定形状，host 自己实现。最小职责：`register(spec)` + `get(agentId)`。
+
+| Pattern | 适用场景 |
+|---------|----------|
+| **A · 内存 Map** | 80% 场景；agent 集合在编译期确定（典型单进程宿主）。`new Map<string, AgentSpec>()` 即可 |
+| **B · 启动时从 JSON 加载** | 让运维 / PM 改配置就能调 agent。boot 时 `AgentSpec.parse(json)` 校验 |
+| **C · 数据库 + 动态更新** | 多租户 SaaS；UI 编辑 spec；要 audit trail |
+
+> ⚠️ 无论用哪种 pattern，**`AgentSpec.parse()` 是必经入口**——保证进入 runtime 的 spec 100% 满足协议约束。绕过 = 让坏数据流到生产。
+
+### 6.2 装配 GraphExecutor（进程级共享单例）
+
+```ts
+import { createDefaultGraphExecutor, LlmNode, LlmCaller } from '@linnlabs/linnkit/runtime-kernel';
+
+const executor = createDefaultGraphExecutor({
+  llmNode: new LlmNode({ llmCaller: new LlmCaller({ aiEngine }) }),
+  toolRuntime,             // host 实现，见 tools.md
+  observationPreview,      // host 实现，见 tools.md
+});
+```
+
+所有 agent 共用一个 executor，每次调用通过 `agentSpec` 切换蓝图。
+
+### 6.3 运行期入口 · `AgentInvocationRequest`
+
+```ts
+// HTTP / IPC / CLI handler
+const spec = AgentRegistry.get(req.agentId);
+if (!spec) throw new Error(`Unknown agent: ${req.agentId}`);
+
+await executor.run({
+  agentSpec: spec,
+  runId: generateRunId(),
+  query: req.userMessage,
+  history: await loadHistory(req.conversationId),
+  fences: await buildFences(req),    // 见 context-fences.md
+  modelId: spec.modelHints?.preferredModels?.[0] ?? 'claude-sonnet-4',
+});
+```
+
+详细装配见 [`02-quickstart.md`](./02-quickstart.md) 与 [`run-supervisor.md`](./run-supervisor.md)。
+
+---
+
+## 7. AgentSpec 版本管理
+
+`AgentSpec` 是协议层蓝图——任何修改都要 bump version：
+
+| 修改 | 版本号 | 配套动作 |
+|------|--------|----------|
+| 加工具 / 加 capability | minor | audit log 记"能力扩展" |
+| 改 `contextPolicy.budget` / `toolHistory.strategy` | minor | audit log；考虑 replay 验证 |
+| 删工具 / 删 capability | **major** | audit log；既有 run 进 deprecated 路径 |
+| 改 `metadata` / `role` / `description` 文案 | patch | 一般不需要 audit |
+
+**对 replay 的影响**：未来 Replay SDK 按 `AgentSpec.version` 精确匹配——同一 runId 必须用**当时的 spec 版本**重演。这是 `version` 必填、spec 必须可序列化的原因。
+
+---
+
+## 8. 多 Agent 协作
+
+linnkit 协议层只承认两种多 agent 形态——**不做** AgentMessageBus / role / backstory 这类"自由 chat"协议。所有多 agent 行为必须能映射到下面其一，才能 100% 可审计 / 可回放。
+
+```ts
+import { runSupervisor } from '@linnlabs/linnkit/runtime-kernel';
+
+// 同步嵌入：子 run 的 cost 聚合到父 run
+const result = await runSupervisor.invokeChildRun({
+  parentRunId: context.runId,
+  agentSpec: emailWriterSpec,
+  input: { query: '写感谢信...' },
+});
+
+// 异步后台：立刻返回 handle，可 observe / cancel / waitForTerminal
+const handle = runSupervisor.spawnDetached({
+  agentSpec: backgroundAgentSpec,
+  input: { task: '生成每日报告' },
+});
+```
+
+详细对比见 [`child-runs.md`](./child-runs.md)。
+
+---
+
+## 9. 自查清单
+
+- [ ] agent 文件位置正确（Quickstart `agents/<id>.ts` / 生产 `agent-registry/<id>/spec.ts`）
+- [ ] 一个文件 / 子目录只放一个 Agent
+- [ ] 已在入口处注册（`runAgent()` 引用 或 `AgentRegistry.register(spec)`）
+- [ ] `AgentSpec.parse()` 是 registry 入口必经路径（生产 host）
+- [ ] `id` 在 registry 中唯一；`version` 是 semver；`capabilities` 明确
+- [ ] `argsSchema` 是可序列化 JSON Schema 副本（**不是** runtime `zod` 对象）
+- [ ] `contextPolicy` 用 `defineContextPolicy()` 而**不是**手写
+- [ ] 多 agent 协作走 `invokeChildRun` 或 `spawnDetached`，不自由 chat
+- [ ] 有交互工具 → 配套 `WaitUserNode` 路径（见 [`tool-development-guide.md §7`](./tool-development-guide.md)）
+- [ ] 配套写了 testkit 不变量测试（见 [`testing.md`](./testing.md)）
+
+---
+
+## 10. 与其他文档的关系
+
+- [`tool-development-guide.md`](./tool-development-guide.md) — 工具内部设计规范
+- [`tools.md`](./tools.md) — `ToolRuntimePort` / `ObservationPreviewPort` 接入面
+- [`context-engineering.md`](./context-engineering.md) — 12 大分组 `contextPolicy` + `TokenizerPort`
+- [`context-fences.md`](./context-fences.md) — fence 注册与注入（与 `mustKeep` 配合）
+- [`run-supervisor.md`](./run-supervisor.md) — `RunHandle.cost()` / `observe` / `cancel`
+- [`child-runs.md`](./child-runs.md) — `invokeChildRun` vs `spawnDetached`
+- [`audit.md`](./audit.md) — Agent 调用 / spec 升级的审计 envelope
+- [`testing.md`](./testing.md) — testkit 26 条 strict invariants

package/docs/integration/audit.md

@@ -0,0 +1,64 @@
+# AuditPort · 决策账本
+
+> **What** · `AuditPort` 接入 —— 把 5 类非确定性决策（policy / tool retry / overflow / fence drop / tokenizer fallback）写入审计账本。Telemetry 记录事实，Audit 记录**为什么**。
+> **When to read** · 要追溯"agent 为什么这么做"；做合规 / 多租户审计；调试上下文裁剪 / overflow 决策；企业接入强烈建议。
+> **Prerequisites** · [`02-quickstart.md`](./02-quickstart.md)。
+> **Key exports** · `AuditPort` / `AuditEnvelope` from `@linnlabs/linnkit/ports` · `createFileAudit` / `createCompositeAudit` from `@linnlabs/linnkit/runtime-kernel`。
+> **Related** · [`telemetry.md`](./telemetry.md) · [`persistence.md`](./persistence.md) · [`testing.md`](./testing.md)（`createCollectingAuditPort` for tests）
+
+> 可选，但企业接入强烈建议。
+
+AuditPort 是"决策账本"。Telemetry 记录事实（比如一次 LLM 调用了多久、用了多少 token），Audit 记录**为什么做了这个决定**（比如为什么取消、为什么拒绝工具、为什么 fallback 到另一个模型）。
+
+这套接入方式是 host-neutral 的：桌面应用、在线秘书 agent、知识库 agent 或任意自研 agent host 都只需要实现自己的 EventStore / file / SIEM sink，不需要把产品语义写回 linnkit。
+
+## 1. 最小接入骨架
+
+默认进 EventStore，再按需分发到文件 / SIEM：
+
+```ts
+import { runtimeKernel } from '@linnlabs/linnkit';
+
+const eventStoreAudit = runtimeKernel.audit.createEventStoreAudit({ eventStore });
+const fileAudit = runtimeKernel.audit.createFileAudit({ filePath: '/var/log/linnkit/audit.jsonl' });
+const auditPort = runtimeKernel.audit.createCompositeAudit({
+  ports: [eventStoreAudit, fileAudit],
+});
+
+const supervisor = new runtimeKernel.runSupervisor.DefaultRunSupervisor({
+  registryStore,
+  auditPort,
+});
+```
+
+## 2. 当前已自动发出的 envelope
+
+- `RunHandle.cancel({ reason })` 会发 `action: 'run.cancel'`，并把 `reason`、`forceCleanup`、`runId`、`conversationId`、`agentSpecId` 写进 envelope。
+- `GraphAgentExecutor` 会发 `model.select`；发生模型切换时发 `model.fallback`。
+- `ToolNode` 会发 `tool.allow` / `tool.deny`。
+- `WaitUserNode` 会发 `wait_user.request`。
+- `runtimeKernel.audit.emitSandboxDecisionAudit()` 是 sandbox 决策标准入口；当前 linnkit 还没有内置 SandboxPort，所以不会伪造 sandbox 执行链。
+
+## 3. 你现在可以选的 sink
+
+| sink | 用途 |
+|---|---|
+| `runtimeKernel.audit.noopAudit` | 测试或本地开发占位 |
+| `runtimeKernel.audit.consoleAudit` / `createConsoleAudit()` | 开发期看结构 |
+| `runtimeKernel.audit.createFileAudit({ filePath })` | 追加写 JSONL，适合最小生产审计或回归测试 |
+| `runtimeKernel.audit.createEventStoreAudit({ eventStore })` | 默认推荐落点，写入 `type: 'audit_envelope'` 的隐藏 RuntimeEvent |
+| `runtimeKernel.audit.createCompositeAudit({ ports })` | 组合多个 sink |
+
+## 4. 接入规则
+
+- Audit envelope 是追加只读记录；不要在 sink 里回写或修改 run 状态。
+- `AuditPort.emit()` 可以是同步或异步；如果你的 sink 有缓冲，暴露 `flush()`，在进程退出或测试结束时显式调用。
+- 不要把 AuditPort 当普通日志散用。只有"决策"进 audit，普通耗时 / token / 节点状态继续走 telemetry。
+- `audit_envelope` 会持久化，但不会进 UI、不会进 agent context、不会走 SSE。
+- `createEventStoreAudit()` 要求 envelope 带 `scope.conversationId`，这是为了避免跨会话审计混流。
+
+## 5. 最小验证
+
+- 单测：注入一个数组 sink，调用 `handle.cancel({ reason: 'user_request' })` 后能收到 `action === 'run.cancel'` 的 envelope。
+- 单测：`createFileAudit()` 连续 emit 两条 envelope 后，JSONL 文件应有两行且可逐行 `JSON.parse`。
+- 单测：`createEventStoreAudit()` emit 后，EventStore 中应出现 `type === 'audit_envelope'` 且 `shouldEnterAgentContext(event) === false`。

package/docs/integration/child-runs.md

@@ -0,0 +1,87 @@
+# Child Runs · 同步嵌入 vs 异步后台子 agent
+
+> **What** · 两种子 agent 调用形态 —— `invokeChildRun`（同步嵌入，父 agent 等结果）vs `spawnDetached`（异步后台，立刻返回 `RunHandle`）。
+> **When to read** · 多 agent 协作；要在一个 agent 里调另一个 agent；想做后台调度 / 长任务 / 通知触发。
+> **Prerequisites** · [`run-supervisor.md`](./run-supervisor.md)。
+> **Key exports** · `invokeChildRun` / `spawnDetached` from `@linnlabs/linnkit/runtime-kernel`。
+> **Related** · [`run-supervisor.md`](./run-supervisor.md) · [`agent-registration-guide.md` §6](./agent-registration-guide.md) ⭐
+
+linnkit 提供**两条 API**承载"子 agent"概念。它们不是配置开关，是两种本质不同的调用形态——按需选用。
+
+## 1. 概念对照
+
+| API | 场景 | 语义 |
+|---|---|---|
+| `toolContext.invokeChildRun(...)` | 父 agent 工具内**同步调用**子 agent | 父等待子完成；用于 deep search / task subagent 这类嵌入式执行 |
+| `runSupervisor.spawnDetached(...)` | 顶层后台任务、定时任务、wake hook、在线秘书 | 立刻返回 handle；调用方后续 `peek / waitForTerminal / cancel / drain` |
+
+## 2. 何时用同步 `invokeChildRun`
+
+适合场景：
+
+- 子 agent 是**父 agent 工具的实现细节**（"调用搜索 agent → 取结果作为本工具的 observation"）
+- 调用方需要立刻拿到子 agent 的结构化输出来决定下一步
+- 子 agent 的成本/取消语义跟父 agent 绑死（取消父则子必停）
+
+调用形态：在父 agent 的某个工具实现里调 `toolContext.invokeChildRun(spec)`。返回值是 child run 的最终输出，且 child run 内的 LLM cost / tool cost 会自动归到父 run 的 `childrenTotal`。
+
+## 3. 何时用异步 `spawnDetached`
+
+适合场景：
+
+- 任务由**外部触发器**（HTTP / cron / wake hook / 用户在前端点了"启动一个后台代办"）触发
+- 调用方**不阻塞**等待结果——立刻拿 handle 用于 cancel / observe / cost
+- 子 agent 与父 agent 的生命周期解耦（子 agent 失败不直接导致父 agent 失败）
+
+骨架：
+
+```ts
+const supervisor = new runtimeKernel.runSupervisor.DefaultRunSupervisor({
+  registryStore,
+  executor: {
+    async execute(ctx) {
+      // 这里接你自己的 GraphExecutor / daemon runner。
+      // ctx.signal、ctx.eventBus、ctx.eventStore、ctx.costCollector 都来自 register spec。
+      await runYourAgent(ctx);
+      return {
+        runId: ctx.runId,
+        status: 'completed',
+        completedAt: Date.now(),
+      };
+    },
+  },
+});
+
+const handle = await supervisor.spawnDetached({
+  conversationId,
+  agentSpec,
+  request,
+  eventBus,
+  eventStore,
+  costCollector,
+  wakeSource: 'cron',
+  iterationBudget: { max: 20, refundable: true },
+});
+
+const outcome = await supervisor.waitForTerminal(handle.runId);
+```
+
+`spawnDetached` 与 `registerRun + 自己跑` 等价，但显式告诉 supervisor"这不是同步等结果的 run"——`RunRegistrationSpec.wakeSource` / `iterationBudget` / `ephemeral` 等字段都在这里生效。
+
+## 4. 命名注意
+
+- 公开 namespace：`runtimeKernel.childRunTrace`（含 `subrun_trace` 观测协议 publisher 与合同）。
+- 事件 type 仍叫 `subrun_trace`（前端可继续按这个名字处理）。
+- 内部目录是 `child-run-trace/`；外部消费者一律走公开 namespace。
+
+## 5. 关键边界
+
+- **不要**把 `invokeChildRun` 当成"小一号的 run"——它本质上是父 run 内部的一个嵌入式调用，与父 run 共享 abort signal、cost 聚合、enrichment registry。
+- **不要**把 `spawnDetached` 用于工具调用流（HTTP 端到端响应里不应该等 spawnDetached 完成）——那是 invokeChildRun 的场景。
+- 父子 run 的 cost 通过 `scope.parentRunId` 关联；如果你的 telemetry adapter 没把 `parentRunId` 透传到 sink，那 `childrenTotal` 字段就是 0。
+
+## 6. 最小验证
+
+- 单测：父 agent 工具内 `invokeChildRun` → 父 run 的 `cost().childrenTotal.llmCost > 0`
+- 单测：`spawnDetached` 立刻返回；`waitForTerminal` 在执行结束后 resolve 出最终 status
+- 单测：`spawnDetached` 中的 run 被 `cancel()` 后，executor 收到的 `ctx.signal.aborted === true`

package/docs/integration/constraints-and-pitfalls.md

@@ -0,0 +1,87 @@
+# Constraints & Pitfalls · 硬约束 + 不建议做的事 + FAQ
+
+> **What** · linnkit 接入侧的硬约束 + 不建议做的事 + 常见踩坑 FAQ（含 AST 级 guard 规则、deep import 风险、浏览器 bundle 边界）。
+> **When to read** · 上线前 review；遇到诡异 import 错误；review 别人的接入实现；接入 PR 自检。
+> **Prerequisites** · 起码读完你用到的 §7.2 单点接入篇。
+> **Key exports** · 无（本文是约束清单）。
+> **Related** · [`glossary.md`](./glossary.md) · [`README §5`](./README.md)（browser rules） · [`realtime.md`](./realtime.md)
+
+## 1. 硬约束（接入方必读）
+
+linnkit 仓库内部的 package-boundary 由 **AST 级 guard**（基于 TypeScript Compiler API）强制 10 条规则。其中**直接影响外部消费者**的：
+
+1. **只能从公开子入口 import**。`exports` 字段没声明的路径会被 Node 16+ ESM 解析直接拒绝。
+2. **不要 deep import**。`@linnlabs/linnkit/runtime-kernel/some-internal-folder/foo` 不算公开 API；下个 minor 随时可能挪。
+3. **不要依赖 internal-only 模块**：`shared/logger` / `shared/errorClassifier` / `shared/TokenCalculator` 等都是包内私有。
+4. **不要把你自己的 provider/tool/adapter 反向塞回 linnkit**——linnkit 是你装的 npm 包，物理上塞不进去；逻辑上也不要试图通过 monkey patch 修改 linnkit 内部。
+5. **`promptKey` 在 ports 层是 opaque string**——linnkit 不认识你的产品菜单，也不会替你解析。
+6. **前端代码禁止 import `@linnlabs/linnkit/runtime-kernel`**（namespace 全展开入口，含 `node:async_hooks` / `crypto` 等 Node-only 子树）。前端只能从 `@linnlabs/linnkit/runtime-kernel/events` slim seam 取 events governance 纯函数。
+7. **生产代码禁止 import `@linnlabs/linnkit/testkit`**。`testkit` 顶层 `import { vi, expect } from 'vitest'`，会把 vitest runtime 拖进生产 bundle。如果你确实在 monorepo 里有 mixed 代码，请用打包阶段的 lint 规则守门。
+
+> 第 6 / 7 条来自早期打包事故：`@linnlabs/linnkit/testkit` 一旦从根入口被静态导入，esbuild/tsup 会把整棵 testkit 子树带进 backend production bundle，导致生产启动时加载测试运行时。公开版本用独立子入口和 package smoke 测试守住这条边界。
+
+## 2. 当前不建议你做的事
+
+不要这样接：
+
+1. **直接把 linnkit 真源仓内的 host adapters 整个抄过来当模板**——那是产品决策内嵌的实现（默认 provider / 默认 task / 默认 schema），里面糊了具体产品的语义。可以参考它们的**形状**和**装配顺序**，但不要直接拷贝再硬改。
+2. **把别人的 agent registry / context / flow 当作公开 API 引用**——它们没在 `package.json#exports` 里。
+3. **试图通过自定义 build 钩子修改 `@linnlabs/linnkit` 内部行为**——所有定制点必须通过依赖注入。
+4. **为了省事继续从外部 schemas 包拿本该属于 agent 的 A 类协议**——0.1.1 已经把 schemas 收回包内（`@linnlabs/linnkit/contracts`），不要再走老路径。
+
+正确做法：
+
+- 复用 `@linnlabs/linnkit` 的 7 个公开子入口
+- 在你自己的 host layer 决定 provider、tool、persistence、flow 的真实实现
+- 通过 fence registry 把产品上下文挂进框架，而不是改框架
+
+## 3. FAQ
+
+**Q：我装的是 `@linnlabs/linnkit`，但 npm/yarn 报 401 / 404？**
+
+优先检查项目或用户级 `.npmrc` 是否还保留旧的 GitHub Packages scope override：
+
+```bash
+npm config get @linnlabs:registry
+```
+
+如果输出是 `https://npm.pkg.github.com/`，删掉这条配置，让 npm 使用默认的 `https://registry.npmjs.org/`。`@linnlabs/linnkit` 当前是 npmjs.com 公开包，不需要 GitHub token。
+
+**Q：我能不能 fork linnkit、改它内部然后用我自己的 fork？**
+
+技术上可以，但你要自己负担"和上游同步 + boundary guard 自维护"的成本。99% 你想做的事都能通过依赖注入在 host 层完成；如果你发现某个改动只能 fork 才能做，那大概率说明你应该来跟 linnkit 维护方提 issue / PR。
+
+**Q：我的产品上下文是不是只能用 fence 表达？**
+
+A 类（system / user 注入）走 fence 是最干净的路。B 类（per-tool 工具调用上下文）按 tool 自己的 schema/context/patch 表达，跟 fence 无关。C 类（运行时副作用、telemetry）走 telemetry port。三类互不替代。
+
+**Q：legacy `document_fragment` / `context_before` 字段我该不该用？**
+
+**不该**。它们在 0.2.x 仍保留是为了存量 host 渐进迁移；新接入方一律走 fence 通道。
+
+**Q：我能跳过 host-bound testkit，只用 linnkit 自带的 testkit 写测试吗？**
+
+能跑通 contract 测试是可以的。但一旦你的 host 装配里有任何"默认 LlmNode 行为 / 默认 tool registry 默认值"等产品决策，第一层 testkit 不会替你验证。所以建议第二层 testkit 至少薄薄一层包一下。
+
+**Q：父子 agent 的 cost 为什么 `childrenTotal` 是 0？**
+
+99% 是你的 telemetry adapter 没把 `scope.parentRunId` 透传到 sink。检查：
+
+- `withLLMTelemetryContext` 内是否传了 `parentRunId`
+- LLM caller / tool runtime 是否包在 `withLLMTelemetryContext` 内
+- 你的 `RunCostCollector` 是否监听了 `scope.parentRunId` 而不是只看 `scope.runId`
+
+**Q：`@linnlabs/linnkit/runtime-kernel` 导入报 "Missing tiktoken_bg.wasm"？**
+
+升级到 ≥ `0.1.3`。0.1.0~0.1.2 三个版本里 tiktoken wasm 被错误 inline 进 dist，已在 0.1.3 修复。
+
+**Q：升级到 0.5.0 后我之前的 import 报错了？**
+
+0.4.x → 0.5.0 主要变化：
+
+- `linnkitCompat` 命名空间已删除（0.3.0 起）
+- `AgentProfileRequest` 的 host 产品字段（`document_fragment` / `context_before` 等）已移除（0.4.0 起）
+- `MessageFormatter` 不再特殊处理 `document_fragment` / `<additional_context>` / `[任务完成]` 包装
+- `linnkit/context-manager` 主入口冻结 chat namespace（`chatContext` / `chatTasks` 等已不再暴露）
+
+具体兼容性看仓根 `CHANGELOG.md` 的 0.5.0 entry。