@linnlabs/linnkit 0.8.0

package/docs/integration/tool-history.md

@@ -0,0 +1,202 @@
+# Tool History · 工具历史压缩策略
+
+> **What** · 工具历史压缩策略配置 —— `per-pair` / `per-run` / `none` 三种策略 + `overflowStrategy` 溢出兜底。
+> **When to read** · 上下文里工具调用反复占满 token；想配置工具调用历史的压缩窗口；做长 run 任务的成本控制。
+> **Prerequisites** · [`tools.md`](./tools.md) · [`context-engineering.md` §5](./context-engineering.md)。
+> **Key exports** · `toolHistory` field in `AgentSpec.contextPolicy` from `@linnlabs/linnkit` · `ToolHistoryCompressor` preprocessor 由 framework 内置自动注入。
+> **Related** · [`context-engineering.md`](./context-engineering.md) ⭐ · [`tools.md`](./tools.md) · [`agent-registration-guide.md`](./agent-registration-guide.md) ⭐
+
+linnkit 的 agent preprocessor 支持三种工具历史压缩策略，host 可在 `AgentDefinition.config.contextPolicy.toolHistory` 中显式声明。
+
+## 1. 三种策略对比
+
+| 策略 | 适用场景 | 行为 | 风险 |
+|------|----------|------|------|
+| `per-pair` | 4K/8K 小上下文模型；需要强力控 token | 全局保留最近 N 组完整工具交互，其余压成自然语言摘要 | 可能跨 run 腰斩同一轮工具链，prompt cache prefix 不稳定 |
+| **`per-run`**（默认推荐）| 多步 agent、review、workspace 操作 | 按 `user_input` 划 run，完整保留最近 K 个历史 run 的工具序列 | token 使用量可能高于 per-pair |
+| `none` | 200K+ 长上下文模型；调试回放；审计敏感链路 | 不做常规压缩，只保留安全阀 | 长历史会明显涨 token |
+
+**未传配置时默认走 `per-run` + `keepLatestRuns: 1`**。host 仍应在各自的 `AgentDefinition.config.contextPolicy.toolHistory` 中显式声明策略，避免依赖全局默认。
+
+## 2. 默认值汇总
+
+| 字段 | 默认 |
+|------|------|
+| `toolHistory.strategy` | `'per-run'` |
+| `toolHistory.keepLatestRuns` | `1`（保留上一个 run 完整工具序列）|
+| `toolHistory.keepLatestToolPairs` | `2`（仅 `strategy='per-pair'` 时生效）|
+| `toolHistory.maxInteractionGroups` | `12` |
+| `toolHistory.overflowStrategy` | `'keep-latest'` |
+| `toolHistory.maxPairTokens` | `6000` |
+| `toolHistory.maxOutputSummaryTokens` | `1000` |
+
+## 3. 安全阀
+
+所有策略共用：
+
+- `maxInteractionGroups`：硬上限，默认 12
+- `overflowStrategy: 'keep-latest'`：超过上限时保留最近工具组，压缩更旧组
+- `overflowStrategy: 'fail-fast'`：超过上限时抛 `ContextProviderError`，`code = 'TOOL_HISTORY_OVERFLOW'`，适合 CI 或生产 invariant
+
+## 4. `AgentSpecContextPolicy.toolHistory` 字段
+
+```ts
+interface AgentSpecContextPolicy {
+  profileId: string;
+
+  budget?: {
+    maxTokens?: number;
+    reservedForResponse?: number;
+    workingMemoryBudgetPercentage?: number;
+  };
+
+  toolHistory?: {
+    /**
+     * 压缩策略类型（默认 'per-run'）
+     * - 'per-pair'：按工具对个数裁（旧默认；适合 4K/8K 等超紧上下文模型）
+     * - 'per-run'：按 user_input 划 run 边界，保留最近 K 个 run 完整工具序列（prompt cache 友好；通用默认）
+     * - 'none'：不压缩（适合 200K+ 长 context 模型；仅靠单 tool_output token cap 兜底）
+     *
+     * 注：当前 run（最后一条 user_input 之后）所有工具对永不压缩，不受 strategy 影响。
+     */
+    strategy?: 'per-pair' | 'per-run' | 'none';
+
+    /** strategy='per-pair' 时：保留最近 N 组完整工具对（默认 2）*/
+    keepLatestToolPairs?: number;
+
+    /** strategy='per-run' 时：保留最近 K 个 run 完整工具序列（默认 1）*/
+    keepLatestRuns?: number;
+
+    /** 工作记忆层最多保留的工具交互组总数硬上限（所有 strategy 共用，默认 12）*/
+    maxInteractionGroups?: number;
+
+    /**
+     * 溢出 maxInteractionGroups 时的处置（默认 'keep-latest'）
+     * - 'keep-latest'：按 originalIndex 倒序截，留尾不留头（保证最近行动可见）
+     * - 'fail-fast'：抛 ContextProviderError，让 host 显式处理
+     */
+    overflowStrategy?: 'keep-latest' | 'fail-fast';
+
+    /** 单组 tool pair token 上限（所有 strategy 共用，超过触发截断，默认 6000）*/
+    maxPairTokens?: number;
+
+    /** tool_output 摘要后的 token 上限（所有 strategy 共用，默认 1000）*/
+    maxOutputSummaryTokens?: number;
+  };
+
+  summarization?: {
+    triggerThreshold?: number;
+    budgetPercentage?: number;
+    oldestMessagesPercentage?: number;
+    agentId?: string;
+    failureBehavior?: 'fail-fast' | 'continue-if-within-budget';
+  };
+}
+```
+
+## 5. AgentSpec 装配
+
+AgentSpec schema 已落到 `@linnlabs/linnkit/contracts`，host 装配时可用 `contextPolicy.toolHistory` 控制策略：
+
+```ts
+import type { AgentSpec } from '@linnlabs/linnkit/contracts';
+
+const myAgentSpec: AgentSpec = {
+  id: 'my-research-agent',
+  version: '1.0.0',
+  capabilities: ['llm', 'tools'],
+  tools: [],
+  contextPolicy: {
+    profileId: 'agent',
+    toolHistory: {
+      strategy: 'per-run',
+      keepLatestRuns: 2,            // 高密度子调度 agent 建议 K=2-3
+      maxInteractionGroups: 12,
+      overflowStrategy: 'keep-latest',
+    },
+  },
+};
+```
+
+## 6. 低层 preprocessor 注入
+
+测试或自定义 registry 也可以直接从默认 preprocessor registry 注入：
+
+```ts
+import { createDefaultAgentPreprocessorRegistry } from '@linnlabs/linnkit/context-manager';
+
+const registry = createDefaultAgentPreprocessorRegistry({
+  toolHistory: {
+    strategy: 'per-run',
+    keepLatestRuns: 1,
+    maxInteractionGroups: 12,
+    overflowStrategy: 'keep-latest',
+  },
+});
+```
+
+## 7. 默认值变更的兼容声明
+
+`strategy` 默认从历史隐式的 `per-pair`（N=2）→ `'per-run'`（K=1）。对所有 host 来说：
+
+- 不会引入新 bug（per-run 是 per-pair 的超集——保留更多消息，不会少留）
+- 平均 history token 数 +20-40%（具体看 history 中工具调用密度）
+- prompt cache 命中率上升
+- host 想保持旧行为：在 AgentSpec 显式设 `toolHistory.strategy: 'per-pair'`
+
+## 8. 每个 agent 显式声明（推荐做法）
+
+每个 agent 在自己的 `index.ts` 显式声明 `contextPolicy`，**不走预设模板、不依赖全局默认**：
+
+```ts
+// app-hosts/your-app/agent-registry/agents/research-agent/index.ts
+import type { AgentDefinition } from '../../types';
+import type { AgentSpecContextPolicy } from '@linnlabs/linnkit/contracts';
+
+const RESEARCH_AGENT_CONTEXT_POLICY: AgentSpecContextPolicy = {
+  profileId: 'agent',
+  toolHistory: {
+    strategy: 'per-run',
+    keepLatestRuns: 3,            // 深度子调度，保留更多上下文
+  },
+};
+
+export const researchAgent: AgentDefinition = {
+  // ...
+  config: {
+    contextPolicy: RESEARCH_AGENT_CONTEXT_POLICY,
+  },
+};
+```
+
+**理由**：
+
+- agent 作者最了解自己的预期工具密度 + 配置的模型 ctx + 工具结果体量
+- 全局默认 per-run K=1 是合理兜底，但高密度子调度 agent 应该显式 K=2-3；translation / autocomplete / 内部子 agent 应该显式 N=0 极致省 token
+- 预设模板会增加间接耦合——换模型时不知道哪些预设需要联动改
+
+## 9. 用 ContextTrace 验证策略真的生效
+
+`toolHistory` 最终会影响 preprocessor 与 working-memory provider 的消息选择。调试时建议临时打开：
+
+```ts
+contextPolicy: {
+  profileId: 'agent',
+  toolHistory: {
+    strategy: 'per-run',
+    keepLatestRuns: 2,
+  },
+  contextTrace: {
+    enabled: true,
+    includeMessageIds: true,
+    includeTokenBreakdown: true,
+    maxTraceEvents: 200,
+  },
+}
+```
+
+然后检查 `ContextBuildResult.contextTrace.events`：
+
+- `provider` 事件能看到 working-memory 阶段保留消息数与 token delta。
+- `message-decision` 事件能看到每条 `tool_calls` / `tool_output` 的 keep/drop 决策。
+- 如果 trace `overflowed=true`，说明这次上下文太大，先提高 `maxTraceEvents` 做一次诊断；不要长期把它开太大。

package/docs/integration/tools.md

@@ -0,0 +1,188 @@
+# Tools · 注册工具集
+
+> **What** · 把工具注册进 linnkit —— `ToolRuntimePort` 接入面 + `ObservationPreviewPort` 治理超长 observation。
+> **When to read** · 要给 agent 加工具；要治理超长 observation；接 MCP / 远程工具；review 既有工具实现。
+> **Prerequisites** · [`02-quickstart.md`](./02-quickstart.md)；写自定义工具前推荐先读 [`tool-development-guide.md`](./tool-development-guide.md) ⭐。
+> **Key exports** · `BaseTool` / `ToolRuntimePort` / `ObservationPreviewPort` / `ToolExecutionContext` from `@linnlabs/linnkit/runtime-kernel`。
+> **Related** · [`tool-development-guide.md`](./tool-development-guide.md) ⭐ · [`tool-history.md`](./tool-history.md) · [`context-engineering.md` §6](./context-engineering.md)
+
+## 1. linnkit 给你的合同
+
+- `BaseTool` + `CommonParameterTypes`（来自 `@linnlabs/linnkit/runtime-kernel`）：抽象类，要求实现 `name` / `description` / `parameters` / `run(args, context)`。`run` 必须返回 `Promise<string>`（强烈推荐 `JSON.stringify({ data, observation })` 格式）。
+- `ToolExecutionContext` / `ToolSchemaContext`（同上）：执行时 / schema 构建时收到的 context 形状。
+- `ToolRuntimePort` / `ToolCatalogPort` / `ToolExecutionPort` / `ToolPresentationPort`（同上）：把工具集合装成"runtime 可调用"的合同；host 默认 `ToolManager` 实现要满足这些 port。
+- `ObservationPreviewPort`（同上）：工具产出 observation 在 UI 展示前的预览决策点。
+- `TokenizerPort`（来自 `@linnlabs/linnkit/ports`，0.8.0+）：host 可选注入的上下文预算 token 估算合同；它不属于工具执行，但会影响工具 observation / tool_calls 在上下文窗口里能保留多少。
+- `ensureToolContextRuntimeCapability`（同上）：把 runtime 必需的保留字段补进 host 的 patch，避免手抖漏字段。
+
+## 2. linnkit 自带的 mock primitive
+
+- `createToolContextFixture`（来自 `@linnlabs/linnkit/testkit`）：最小 `ToolExecutionContext`，已自动通过 `ensureToolContextRuntimeCapability` 补全 runtime 字段。
+
+## 3. 你必须做的
+
+1. 把每个工具定义为 `BaseTool` 的子类（或满足 `AgentTool` 接口的对象）；详细规范见 [`tool-development-guide.md`](./tool-development-guide.md)。
+2. 决定哪些字段走通用 `ToolExecutionContext`，哪些走 host patch；patch 必须经 `ensureToolContextRuntimeCapability` 补齐保留字段。
+3. 把工具集合装进 host 的 `ToolManager` / `ToolRuntimePort` 实现，让 runtime 在 LLM 决策返回 tool calls 时能 dispatch。
+4. 实现 `ObservationPreviewPort`，决定超长 observation 的完整副本写到哪里；再在 runtime assembly 里传给 `createDefaultGraphExecutor({ observationPreview })` 或你的自定义 `ToolNode` 装配。
+5. 把 AgentSpec 与工具集合装配在一起；详细规范见 [`agent-registration-guide.md`](./agent-registration-guide.md)。
+
+## 4. 你不要做的
+
+- 不要让工具直接吃 host 的全局单例（数据库、配置中心等都按 patch / context 注入）。
+- 不要把 runtime 保留字段（`__runtime` / `__capabilities`）手工拼进 patch；统一过 `ensureToolContextRuntimeCapability`。
+- 不要从 deep path 抓 helper（凡是没出现在 `@linnlabs/linnkit/runtime-kernel` 公开符号里的，下个 minor 可能就消失）。
+
+## 5. 最小验证
+
+- 单测：用 `createToolContextFixture()` 直接测 `tool.execute(args, fixtureContext)`。
+- 集成测：在 host-bound `ToolRuntimeHarness` 上覆盖"失败恢复 / 并行调用 / observation 预览"路径。
+
+## 6. ObservationPreviewPort：配置超长 observation 存储路径
+
+`contextPolicy.toolOutput.observationGovernance` 只控制**什么时候治理**：
+
+```ts
+contextPolicy: {
+  profileId: 'agent',
+  toolOutput: {
+    observationGovernance: {
+      enabled: true,
+      maxChars: 20_000,
+      maxLines: 1_200,
+    },
+  },
+}
+```
+
+完整内容**存到哪里**由 host 的 `ObservationPreviewPort` 决定。最小形态：
+
+```ts
+import path from 'node:path';
+import { promises as fsp } from 'node:fs';
+import { createHash } from 'node:crypto';
+import type { ObservationPreviewPort } from '@linnlabs/linnkit/runtime-kernel';
+
+export function createFsObservationPreviewPort(params: {
+  rootDir: string;
+}): ObservationPreviewPort {
+  return {
+    async truncateObservation({ context, toolName, text, maxChars, maxLines }) {
+      const raw = String(text ?? '');
+      const lines = raw.split('\n');
+      if (raw.length <= maxChars && lines.length <= maxLines) {
+        return { truncated: false, preview: raw };
+      }
+
+      const blobId = createHash('sha256')
+        .update(JSON.stringify({
+          conversationId: context.conversationId,
+          turnId: context.turnId,
+          toolName,
+          textHash: createHash('sha256').update(raw).digest('hex'),
+        }))
+        .digest('hex')
+        .slice(0, 16);
+
+      const filePath = path.join(params.rootDir, 'tool_output', 'blobs', `${blobId}.json`);
+      await fsp.mkdir(path.dirname(filePath), { recursive: true });
+      await fsp.writeFile(
+        filePath,
+        JSON.stringify({
+          version: 1,
+          kind: 'tool_output_text',
+          conversation_id: context.conversationId,
+          turn_id: context.turnId,
+          tool_name: toolName,
+          text: raw,
+        }, null, 2),
+        'utf-8',
+      );
+
+      return {
+        truncated: true,
+        blob_id: blobId,
+        preview: [
+          raw.slice(0, Math.floor(maxChars * 0.7)),
+          '',
+          `...（内容已截断，完整内容已写入 blob_id=${blobId}）...`,
+        ].join('\n'),
+      };
+    },
+  };
+}
+```
+
+然后在 executor 装配处传入：
+
+```ts
+import { createDefaultGraphExecutor } from '@linnlabs/linnkit/runtime-kernel';
+
+const observationPreview = createFsObservationPreviewPort({
+  rootDir: process.env.MY_AGENT_TOOL_OUTPUT_DIR ?? '/var/lib/my-agent',
+});
+
+const executor = createDefaultGraphExecutor({
+  llmNode,
+  toolRuntime,
+  observationPreview,
+});
+```
+
+**重要边界**：
+
+- `blob_id` 只是指针。你如果提供读取工具（例如 `resource_read("tool_output://blobs/<blob_id>")`），读取工具必须和 `ObservationPreviewPort` 使用同一个 store / rootDir。
+- AgentSpec 不应该包含本地路径、S3 bucket、数据库 DSN 这类基础设施字段；这些属于 host 部署配置。
+- 示例 host 可以使用 workspace root 下的 conversation artifact 路径：
+  `<workspaceRoot>/Artifacts/v1/conversations/<conversationId>/instances/<instanceId>/tool_output/blobs/<blobId>.json`。
+  其中 `workspaceRoot` 应来自 host 自己的部署配置、环境变量或工作区配置。读取 `tool_output://blobs/<blob_id>` 的工具也必须使用同一个 store，否则模型拿到 `blob_id` 后无法续读。
+
+## 7. 工具最小示例
+
+> 完整规范见 [`tool-development-guide.md`](./tool-development-guide.md)。本节只给最小可运行示例。
+
+```ts
+import {
+  BaseTool,
+  type ToolArgs,
+  type ToolExecutionContext,
+  type ToolParameterSchema,
+} from '@linnlabs/linnkit/runtime-kernel';
+
+interface EchoArgs extends ToolArgs {
+  text: string;
+}
+
+export class EchoTool extends BaseTool<EchoArgs> {
+  readonly name = 'echo';
+  readonly description = '回声测试，用于验证工具调用链路';
+
+  readonly parameters: ToolParameterSchema = {
+    type: 'object',
+    properties: {
+      text: { type: 'string', description: '要回声的文本' },
+    },
+    required: ['text'],
+  };
+
+  async run(args: EchoArgs, _context: ToolExecutionContext): Promise<string> {
+    const result = {
+      data: { echoed: args.text },
+      observation: `Echoed: ${args.text}`,
+    };
+    return JSON.stringify(result);
+  }
+}
+```
+
+**协议层强制约束**（违反会被运行时拒绝或导致下游解析失败）：
+
+| 约束 | 协议层守门 |
+|------|-----------|
+| `name` / `description` / `parameters` 必填 | `BaseTool` 抽象类强制 |
+| `run` 返回 `Promise<string>`（不是对象，是字符串）| `BaseTool.run` 签名 |
+| 强烈推荐 `run` 返回 `JSON.stringify({ data, observation })` 格式 | 上下游工具卡片解析依赖 |
+| 必填参数走 `parameters.required[]`，**不要**在 `run` 里手写 if-check | `BaseTool.validateArguments` 自动校验 |
+| 失败必须 `throw`，**不能**返回伪装成功的 JSON | tool 配对不变量 C10 + AuditEnvelope |
+
+详细的设计思想、错误处理规范、超长 observation 治理、交互工具协议等见 [`tool-development-guide.md`](./tool-development-guide.md)。

package/package.json

@@ -0,0 +1,115 @@
+{
+  "name": "@linnlabs/linnkit",
+  "version": "0.8.0",
+  "type": "module",
+  "description": "linnkit · vendor-neutral Agent framework. runtime-kernel + context-manager + ports + testkit + browser-safe events seam.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/linnlabs/linnkit.git"
+  },
+  "homepage": "https://github.com/linnlabs/linnkit#readme",
+  "bugs": {
+    "url": "https://github.com/linnlabs/linnkit/issues"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public",
+    "provenance": true
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "CHANGELOG.md",
+    "README.md",
+    "README.zh-CN.md",
+    "docs/README.md",
+    "docs/integration"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "linnkit": "./dist/cli.cjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./ports": {
+      "types": "./dist/ports.d.ts",
+      "import": "./dist/ports.js",
+      "require": "./dist/ports.cjs"
+    },
+    "./contracts": {
+      "types": "./dist/contracts.d.ts",
+      "import": "./dist/contracts.js",
+      "require": "./dist/contracts.cjs"
+    },
+    "./runtime-kernel": {
+      "types": "./dist/runtime-kernel.d.ts",
+      "import": "./dist/runtime-kernel.js",
+      "require": "./dist/runtime-kernel.cjs"
+    },
+    "./runtime-kernel/events": {
+      "types": "./dist/runtime-kernel/events.d.ts",
+      "import": "./dist/runtime-kernel/events.js",
+      "require": "./dist/runtime-kernel/events.cjs"
+    },
+    "./context-manager": {
+      "types": "./dist/context-manager.d.ts",
+      "import": "./dist/context-manager.js",
+      "require": "./dist/context-manager.cjs"
+    },
+    "./testkit": {
+      "types": "./dist/testkit.d.ts",
+      "import": "./dist/testkit.js",
+      "require": "./dist/testkit.cjs"
+    },
+    "./quickstart": {
+      "types": "./dist/quickstart.d.ts",
+      "import": "./dist/quickstart.js",
+      "require": "./dist/quickstart.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:clean": "rm -rf dist",
+    "prepublishOnly": "npm run build:clean && npm run build && npm run test:smoke && npm run test:smoke:dist",
+    "publish:npm": "npm publish",
+    "publish:dry-run": "npm pack --dry-run",
+    "typecheck": "npx tsc --noEmit -p tsconfig.json",
+    "test:smoke": "npx vitest run __tests__/package.shell.test.ts",
+    "test:smoke:dist": "npx vitest run __tests__/package.runtime-import.test.ts __tests__/package.events-browser-safe.test.ts"
+  },
+  "dependencies": {
+    "tiktoken": "^1.0.22"
+  },
+  "peerDependencies": {
+    "vitest": "^2.0.0 || ^3.0.0",
+    "zod": "^3.22.0"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.4",
+    "vitest": "^3.2.4"
+  },
+  "linnkit": {
+    "phase": "released (0.8.0 — TokenizerPort：host 可选注入自定义 tokenizer，默认行为保持 0.7.x)",
+    "sourceOfTruth": "CHANGELOG.md",
+    "notes": [
+      "子入口 ./runtime-kernel/events 是 browser-safe slim seam：仅暴露 events governance 纯函数，禁止扩展任何 Node-only 依赖（如 node:async_hooks / crypto / fs）",
+      "前端代码禁止从 ./runtime-kernel（namespace 全展开入口）import，否则会把 crypto / node:async_hooks 等 Node-only 子树拖进 frontend bundle",
+      "0.x 版本号策略：任何加 export / 改既有签名都 bump minor（不是 patch），保证消费者不会在 patch 升级中吃到公开 API 变化"
+    ]
+  }
+}