@linnlabs/linnkit 0.8.0

package/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> **Note**: linnkit is in `0.x` — minor versions may introduce new public exports
+> but patch versions should remain compatible.
+>
+> Versions before 0.5.0 were internal alpha and are summarized only at a high level here.
+
+---
+
+## [Unreleased]
+
+---
+
+## [0.8.0] - 2026-05-13
+
+### Added
+
+- `TokenizerPort` interface in `@linnlabs/linnkit/ports` — host-injectable token estimation contract
+- `DefaultTokenizerPort` + `createDefaultTokenizerPort(config)` in `@linnlabs/linnkit/runtime-kernel` — wraps the existing `TokenCalculator` (tiktoken + char-ratio fallback) behind the new interface
+- `ContextManagerBaseOptions.tokenizer` / `tokenizerModelId` on `AgentContextManager`, `ChatContextManager`, `AgentMessageOrchestrator`, `ChatMessageOrchestrator` — inject once at assembly time, drives all budget decisions
+- `updateTokenizerModelId(modelId)` on `ContextManagerBase` — required when reusing one context manager across multiple models
+- `createMockTokenizerPort()` in `@linnlabs/linnkit/testkit` — fixed-token-per-message mock for deterministic budget / trimming tests
+- `C12_HOST_TOKENIZER_DRIVES_BUDGET` strict invariant in testkit `context-harness` — proves injected tokenizer actually drives `message-decision.tokens` and `trace.finalTokens`
+
+### Compatibility
+
+- Non-breaking. Hosts not injecting `tokenizer` continue using `TokenCalculator` with 0.7.x behavior unchanged.
+- `contextPolicy.tokenEstimation` (encoding / avgCharsPerToken / toolCallOverhead) continues to configure the default tokenizer when no custom tokenizer is injected.
+
+---
+
+## [0.7.0] - 2026-05-12
+
+### Added
+
+- `defineAgent` / `runAgent` / `defineConfig` quickstart helpers
+- `@linnlabs/linnkit/quickstart` public sub-entrypoint
+- CLI v0: `linnkit init` / `linnkit run` / `linnkit doctor`
+- `README.zh-CN.md` Chinese documentation
+
+### Compatibility
+
+- Non-breaking. All 0.6.x public APIs remain unchanged.
+
+---
+
+## [0.6.0] - 2026-05-11
+
+### Added
+
+- 12-group `AgentSpec.contextPolicy`: `budget` / `toolHistory` / `toolOutput` / `providerReplay` / `summarization` / `mustKeep` / `workingMemory` / `checkpoint` / `reasoningRetention` / `tokenEstimation` / `systemReminder` / `contextTrace`
+- `defineContextPolicy()` helper — merges defaults and validates group combination constraints
+- `ContextTrace` machine-readable sidecar of every context build decision
+- `SystemReminder` registry + trigger/template extension points
+- `ContextCheckpointTool` / `createContextCheckpointTool()` — host-neutral active checkpoint tool
+- 11 additional strict invariants in testkit `context-harness` (total: 26 — 15 run + 11 contextPolicy + C12 tokenizer added in 0.8.0)
+- `docs/integration/` restructured: 18 topic-specific guides each with Front Matter
+
+### Compatibility
+
+- Non-breaking. Hosts using the pre-0.6.0 flat `contextPolicy` shape are auto-migrated via `defineContextPolicy()`.
+
+---
+
+## [0.5.0] - 2026-05-10
+
+### Added
+
+- `AgentSpec` — first-class serializable agent blueprint (id / version / capabilities / tools / contextPolicy / modelHints / audit / metadata)
+- `RunSupervisor` + `RunHandle` v2: `cancel` / `observe` / `cost` / `spawnDetached` / `waitForTerminal` / `drain` / `recoverOnBoot`
+- `invokeChildRun` — synchronous child run with cost roll-up to parent
+- `AuditEnvelope` + `AuditPort` — structured logging for non-deterministic decisions
+- Tool history compression: `per-pair` / `per-run` / `none` strategies + `overflowStrategy`
+- testkit with 15 strict run invariants
+- Documentation reorganized: 17 topic-specific guides under `docs/integration/`
+
+### Compatibility
+
+- First stable public API surface. Sub-entrypoints locked.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Linnlabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# linnkit
+
+**A fine-grained context engineering framework for Agent applications — control every token sent to the model, with clear run lifecycle, audit records, and testable protocol boundaries.**
+
+[中文文档](./README.zh-CN.md) · [Integration Guide](./docs/integration/README.md) · [Changelog](./CHANGELOG.md)
+
+---
+
+## What is linnkit?
+
+linnkit is a foundational skeleton for Agent applications:
+
+| Layer | Responsibility |
+|-------|---------------|
+| `runtime-kernel` | Run agents, run tools, manage run lifecycle, record events, handle cancellation and cost |
+| `context-manager` | Build the context sent to the model, trim to budget, inject host context |
+| `ports` | Interfaces the host must implement: LLM, tools, storage, tokenizer |
+| `testkit` | Guard the protocol with tests, not oral agreements |
+
+linnkit has no built-in LLM provider, no database binding, no UI, and no opinions on RAG, memory, permissions, or IM integrations. Those belong to your product.
+
+---
+
+## Why use linnkit?
+
+**Fine-grained context control** — Describe your entire context strategy declaratively with `AgentSpec.contextPolicy`. Configure token budget, tool history retention, summarization triggers, must-keep rules, checkpoint compression, reasoning retention, system reminder injection, observation truncation with full-copy archiving, provider sidecar replay, and custom tokenizer. The context sent to the model is not a hand-assembled `messages[]` array — it's a rule-driven, recorded build process.
+
+**ContextTrace observability** — Every context build produces a machine-readable trace: which messages were kept, which were trimmed, why, how many tokens each step consumed, and whether the final result exceeded the budget. When the model answers incorrectly, you don't need to guess whether context was lost — you can read the trace directly.
+
+**Managed run lifecycle** — `RunSupervisor` and `RunHandle` turn each agent invocation into a stateful run with its own `runId`, cancellation, observable event stream, state queries, cost accounting, synchronous child runs, and spawnable detached background runs. Agents behave like real services, not temporary function calls.
+
+**Audit-first design** — `AuditEnvelope` and `AuditPort` capture important decisions — model selection, tool rejection, fallback, awaiting user input, sandbox decisions — into a unified audit stream. Not for appearances, but so you can answer: *why did the system do that?*
+
+**Clean host boundaries via fence injection** — linnkit doesn't know what "document chunk", "knowledge base", or "project memory" means in your product. Hosts register their own context types as fence families. linnkit handles the rules: when to keep them, when to trim them, how to observe them — without hardcoding business vocabulary.
+
+**Protocol invariants, not conventions** — linnkit's testkit enforces 26 strict invariants: final tokens must not exceed budget, tool calls and outputs must not be separated, must-keep messages must never be trimmed, run state must not stay `running` after termination, budget decisions must actually use the injected custom tokenizer... The more complex an Agent system becomes, the more these invariants protect you from small changes silently breaking the protocol.
+
+---
+
+## What problems does it solve?
+
+If you've built Agent products before, you've likely run into these:
+
+- Context is hard to manage — it's difficult to observe exactly what gets sent to the LLM each time.
+- Long conversations make it unclear what the model actually sees.
+- As tool calls accumulate, deciding what to keep vs. compress becomes guesswork.
+- After a user cancels, run state, event stream, tool execution, and frontend UI can fall out of sync.
+- When multiple agents call each other, cost, events, and errors across parent/child runs are hard to trace.
+- A bug can't be reproduced because nobody recorded how context was trimmed at the time.
+- Tests only check "did the final answer look right" but can't catch a broken protocol.
+
+linnkit's goal is to turn these into configurable, observable, and testable engineering problems.
+
+---
+
+## What linnkit does NOT do
+
+These capabilities matter, but they are not linnkit's responsibility:
+
+- No built-in OpenAI / Claude / Gemini provider.
+- No built-in RAG, vector store, knowledge base, or memory system.
+- No built-in tools (search, file read/write, browser, IM).
+- No built-in UI, console, or DevTools platform.
+- No opinions on permissions, security policy, or billing strategy.
+
+linnkit provides boundaries and protocols to make these easier to integrate. The implementations belong to your product.
+
+This is what allows linnkit to serve multiple different host applications rather than becoming an internal framework for one specific product.
+
+---
+
+## Quick start
+
+Install:
+
+```bash
+npm install @linnlabs/linnkit
+```
+
+Create a demo host:
+
+```bash
+npx linnkit init demo-agent
+cd demo-agent
+npm install
+```
+
+After configuring environment variables, check your setup:
+
+```bash
+npx linnkit doctor
+```
+
+Run a hello agent:
+
+```bash
+npx linnkit run hello --input "Describe linnkit in one sentence"
+```
+
+This quickstart is for getting up and running quickly — it's not a production setup. Production hosts should assemble their own LLM, tools, storage, audit, and context policy by following the [integration guide](./docs/integration/README.md).
+
+### One-line prompt for coding agents
+
+If you use Claude Code, Codex, Cursor, Windsurf, or another coding agent, you can paste this directly:
+
+> If linnkit is not cloned yet, clone https://github.com/linnlabs/linnkit first; then follow the README and `docs/integration/02-quickstart.md` to initialize a local demo host, prefer npm, run `linnkit doctor`, do not wire production storage or real business tools, and finish by telling me the next command to run plus which `OPENAI_API_KEY` / `OPENAI_BASE_URL` / `OPENAI_MODEL` settings are still missing.
+
+---
+
+## Minimal code example
+
+```ts
+import { defineAgent, runAgent } from '@linnlabs/linnkit/quickstart';
+
+const agent = defineAgent({
+  id: 'hello',
+  version: '0.1.0',
+  role: 'Assistant',
+  systemPrompt: 'You are a concise, reliable assistant.',
+  modelId: 'gpt-4o-mini',
+  capabilities: ['agent'],
+  tools: [],
+  contextPolicy: {
+    budget: { maxTokens: 16_000, reservedForResponse: 2_000 },
+  },
+});
+
+const result = await runAgent(agent, { input: 'What is linnkit?', llm });
+console.log(result.finalAnswer);
+```
+
+---
+
+## Public sub-entrypoints
+
+| Sub-entrypoint | Purpose |
+|---------------|---------|
+| `@linnlabs/linnkit` | Root entry — exports main namespaces |
+| `@linnlabs/linnkit/ports` | Interfaces the host must implement |
+| `@linnlabs/linnkit/contracts` | Stable data structures: `AgentSpec`, `AiMessage`, `RuntimeEvent` |
+| `@linnlabs/linnkit/runtime-kernel` | Graph engine, tool runtime, run supervisor |
+| `@linnlabs/linnkit/runtime-kernel/events` | Browser-safe event governance pure functions |
+| `@linnlabs/linnkit/context-manager` | Context build, fence registry, message formatter, context policy |
+| `@linnlabs/linnkit/testkit` | Test harnesses and 26 protocol invariants |
+| `@linnlabs/linnkit/quickstart` | Demo / development helpers |
+
+> **Browser rule**: do not import `@linnlabs/linnkit/runtime-kernel` in a frontend bundle — it pulls in Node-only sub-trees. For frontend event display logic only, use `@linnlabs/linnkit/runtime-kernel/events`.
+
+---
+
+## Documentation
+
+| Document | Content |
+|----------|---------|
+| [docs/integration/README.md](./docs/integration/README.md) | Integration hub — start here |
+| [docs/integration/01-installation.md](./docs/integration/01-installation.md) | Install and registry auth |
+| [docs/integration/02-quickstart.md](./docs/integration/02-quickstart.md) | Quickstart demo |
+| [docs/integration/agent-registration-guide.md](./docs/integration/agent-registration-guide.md) | Agent registration and `AgentSpec` |
+| [docs/integration/context-engineering.md](./docs/integration/context-engineering.md) | Context policy, ContextTrace, TokenizerPort |
+| [docs/integration/context-fences.md](./docs/integration/context-fences.md) | Host context injection |
+| [docs/integration/tools.md](./docs/integration/tools.md) | Tool integration overview |
+| [docs/integration/tool-development-guide.md](./docs/integration/tool-development-guide.md) | Tool design internals |
+| [docs/integration/run-supervisor.md](./docs/integration/run-supervisor.md) | Run lifecycle management |
+| [docs/integration/testing.md](./docs/integration/testing.md) | Testkit and invariants |
+| [CHANGELOG.md](./CHANGELOG.md) | Public release history |
+
+---
+
+## Status
+
+- **Version**: see [`package.json`](./package.json)
+- **Distribution**: npmjs.com public registry
+- **Stability**: `0.x` — public sub-entrypoints are locked; Context Engineering API stable since 0.6.0
+- **Open source**: MIT-licensed source is available at <https://github.com/linnlabs/linnkit>
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,182 @@
+# linnkit
+
+**linnkit 是一个可以方便地精细化管理上下文的 Agent 框架，追求控制发给LLM的每一个 token，同时保留清晰的运行生命周期、审计记录和测试边界。**
+
+[English](./README.md) · [接入文档](./docs/integration/README.md) · [更新日志](./CHANGELOG.md)
+
+---
+
+## linnkit 是什么？
+
+linnkit是一套 Agent 应用的底层骨架：
+
+| 层 | 负责什么 |
+|---|---|
+| `runtime-kernel` | 跑 agent、跑工具、管理 run、记录事件、处理取消和 cost |
+| `context-manager` | 构建发给模型的上下文，按预算裁剪，注入 host 上下文 |
+| `ports` | 接入方需要实现的接口，例如 LLM、工具、存储、tokenizer |
+| `testkit` | 用测试守住协议，不靠口头约定 |
+
+linnkit 不内置 LLM provider，不绑定数据库，不提供 UI，也不替你做 RAG、记忆、权限、IM 接入这些产品层能力。
+
+---
+
+## 为什么选 linnkit？
+
+**精细化上下文控制** — 用 `AgentSpec.contextPolicy` 声明式地描述完整上下文策略：token 预算与预留回答空间、工具历史保留方式、摘要触发时机、必须保留的消息类型、checkpoint 压缩、推理内容保留、system reminder 注入、observation 截断与完整副本落盘、provider sidecar replay、自定义 tokenizer。发给模型的上下文不是手拼出来的 `messages[]`，而是一套有规则、有记录的构建过程。
+
+**ContextTrace 可观测性** — 每次上下文构建都会产出一份机器可读的 trace：哪些消息被保留、哪些被裁、为什么裁、每一步消耗多少 token、最终是否超过预算。模型答错时，不用猜"是不是上下文丢了"，直接看 trace。
+
+**run 生命周期管理** — `RunSupervisor` 和 `RunHandle` 让每次 agent 调用变成一个有状态的 run：独立 `runId`、可取消、可观察事件流、可查询状态、可统计 cost、可跑同步子 run、可 spawn 后台 detached run。Agent 更接近真实服务，而不是临时函数调用。
+
+**审计设计** — `AuditEnvelope` / `AuditPort` 把模型选择、工具拒绝、fallback、等待用户、sandbox 决策等重要行为纳入统一审计流。不是为了"看起来企业级"，而是为了在出问题时能回答：当时系统为什么这么做？
+
+**干净的 host 边界** — linnkit 不知道你的业务里什么叫"文档片段""知识库""项目记忆"。host 用 fence 机制注册自己的上下文类型，linnkit 负责按规则保留、裁剪、观测——不硬编码任何业务词汇。
+
+**协议不变量测试** — testkit 强制校验 26 条严格不变量：final tokens 不能超预算、tool call 与 tool output 不能拆散、must-keep 消息不能被裁、run 结束后不能停在 running、注入自定义 tokenizer 后预算决策必须真的使用它……Agent 系统越复杂，越需要这些不变量防止小改动悄悄弄坏协议。
+
+---
+
+## 它适合解决什么问题？
+
+如果你已经做过 Agent 产品，通常会遇到这些问题：
+
+- 上下文不好管理，难以观测每次发给LLM的全部上下文。
+- 对话越长，模型到底看到了什么说不清。
+- 工具调用一多，哪些结果该保留、哪些该压缩，只能靠经验调。
+- 用户点取消后，run 状态、事件流、工具执行和前端展示容易不同步。
+- 多个 agent 互相调用后，父子 run 的 cost、事件和错误不好追。
+- 一个 bug 复现不了，因为当时上下文是怎么裁剪的没人记录。
+- 测试只测"最后回答像不像"，但测不到协议是否坏了。
+
+linnkit 的目标就是把这些事变成可配置、可观测、可测试的工程问题。
+
+---
+
+## linnkit 不做什么？
+
+这些能力很重要，但不属于 linnkit 的核心职责：
+
+- 不内置 OpenAI / Claude / Gemini provider。
+- 不内置 RAG、向量库、知识库、记忆系统。
+- 不内置业务工具，例如搜索、读文件、写文件、浏览器、IM。
+- 不内置 UI、控制台、DevTools 平台。
+- 不替 host 决定权限、安全策略、计费策略。
+
+linnkit 会提供边界和协议，让这些能力更容易接入；但具体实现应该属于你的产品。
+
+它让 linnkit 可以被不同 host 使用，而不是变成某一个产品的内部框架。
+
+---
+
+## 5 分钟快速试用
+
+安装：
+
+```bash
+npm install @linnlabs/linnkit
+```
+
+创建 demo host：
+
+```bash
+npx linnkit init demo-agent
+cd demo-agent
+npm install
+```
+
+配置环境变量后检查：
+
+```bash
+npx linnkit doctor
+```
+
+运行 hello agent：
+
+```bash
+npx linnkit run hello --input "用一句话介绍 linnkit"
+```
+
+这个 quickstart 是为了让你快速跑起来，不代表生产接入方式。生产 host 应该按 [接入文档](./docs/integration/README.md) 装配自己的 LLM、工具、存储、审计和上下文策略。
+
+### 一句话交给 Coding Agent 安装
+
+如果你在用 Claude Code、Codex、Cursor、Windsurf 或其他 coding agent，可以直接把下面这句话发给它：
+
+> 如果还没 clone linnkit，就先 clone https://github.com/linnlabs/linnkit；然后按 README 和 `docs/integration/02-quickstart.md` 初始化一个本地 demo host，优先使用 npm，运行 `linnkit doctor`，不要接入生产存储或真实业务工具，结束时告诉我下一条运行命令，以及还缺哪些 `OPENAI_API_KEY` / `OPENAI_BASE_URL` / `OPENAI_MODEL` 配置需要补充。
+
+---
+
+## 最小代码示例
+
+```ts
+import { defineAgent, runAgent } from '@linnlabs/linnkit/quickstart';
+
+const agent = defineAgent({
+  id: 'hello',
+  version: '0.1.0',
+  role: '助手',
+  systemPrompt: '你是一个简洁、可靠的助手。',
+  modelId: 'gpt-4o-mini',
+  capabilities: ['agent'],
+  tools: [],
+  contextPolicy: {
+    budget: { maxTokens: 16_000, reservedForResponse: 2_000 },
+  },
+});
+
+const result = await runAgent(agent, {
+  input: 'linnkit 是什么？',
+  llm,
+});
+
+console.log(result.finalAnswer);
+```
+
+---
+
+## 公开入口
+
+| 子入口 | 用途 |
+|---|---|
+| `@linnlabs/linnkit` | 根入口，导出主要 namespace |
+| `@linnlabs/linnkit/ports` | host 需要实现的接口 |
+| `@linnlabs/linnkit/contracts` | 稳定数据结构，例如 `AgentSpec`、`AiMessage`、`RuntimeEvent` |
+| `@linnlabs/linnkit/runtime-kernel` | graph、tool runtime、run supervisor 等运行时能力 |
+| `@linnlabs/linnkit/runtime-kernel/events` | 浏览器安全的事件治理函数 |
+| `@linnlabs/linnkit/context-manager` | 上下文构建、fence、message formatter、context policy |
+| `@linnlabs/linnkit/testkit` | 测试 harness 和协议不变量 |
+| `@linnlabs/linnkit/quickstart` | demo / 试用辅助函数 |
+
+注意：前端页面不要 import `@linnlabs/linnkit/runtime-kernel`，它包含 Node-only 子树。前端只需要事件展示规则时，用 `@linnlabs/linnkit/runtime-kernel/events`。
+
+---
+
+## 文档入口
+
+| 文档 | 内容 |
+|---|---|
+| [docs/integration/README.md](./docs/integration/README.md) | 接入总入口 |
+| [docs/integration/01-installation.md](./docs/integration/01-installation.md) | 安装和包源配置 |
+| [docs/integration/02-quickstart.md](./docs/integration/02-quickstart.md) | quickstart demo |
+| [docs/integration/agent-registration-guide.md](./docs/integration/agent-registration-guide.md) | agent 注册与 `AgentSpec` |
+| [docs/integration/context-engineering.md](./docs/integration/context-engineering.md) | 上下文策略、trace、tokenizer |
+| [docs/integration/context-fences.md](./docs/integration/context-fences.md) | host 上下文注入 |
+| [docs/integration/tools.md](./docs/integration/tools.md) | 工具接入总览 |
+| [docs/integration/tool-development-guide.md](./docs/integration/tool-development-guide.md) | 工具开发细节 |
+| [docs/integration/run-supervisor.md](./docs/integration/run-supervisor.md) | run 生命周期管理 |
+| [docs/integration/testing.md](./docs/integration/testing.md) | testkit 和不变量 |
+| [CHANGELOG.md](./CHANGELOG.md) | 公开版本更新记录 |
+
+---
+
+## 当前状态
+
+- 当前版本：以 [package.json](./package.json) 为准。
+- 当前发布：npmjs.com 公开发布。
+- 稳定性：仍是 `0.x`，但公开子入口已经锁定；Context Engineering API 自 0.6.0 起基本稳定。
+- 开源状态：已按 MIT 协议开源，源码仓为 <https://github.com/linnlabs/linnkit>。
+
+## License
+
+MIT — 见 [LICENSE](./LICENSE)。

package/dist/agent-invocation-BHcNfrBV.d.cts

@@ -0,0 +1,30 @@
+import { A as AiMessage } from './messages-XthmnHZ3.cjs';
+
+/**
+ * Agent runtime 最小调用协议。
+ *
+ * 中文备注：
+ * - 这里只声明 runtime-kernel / context-core 真正读取的字段；
+ * - 产品层的 AgentInvokeRequest 可以通过结构类型自然满足该接口；
+ * - agent package 不再从 app core 反向导入调用协议；
+ * - 公共合同面不依赖产品 enum：promptKey 在 ports 层是 opaque string。
+ */
+interface AgentInvocationRequest {
+    query: string;
+    promptKey: string;
+    model_id?: string;
+    imageGenerationModelId?: string;
+    /**
+     * 兼容字段。
+     *
+     * 当前仍允许 host 显式传入 `chat`，但长期目标不是维护两套并列核心模式；
+     * 纯聊天会逐步收敛为“不给工具的 agent 形态”。
+     */
+    mode?: 'agent' | 'chat';
+    maxSteps?: number;
+    enableTools?: boolean;
+    availableTools?: string[];
+    conversationHistory?: AiMessage[];
+}
+
+export type { AgentInvocationRequest as A };

package/dist/agent-invocation-BznDaXDs.d.ts

@@ -0,0 +1,30 @@
+import { A as AiMessage } from './messages-XthmnHZ3.js';
+
+/**
+ * Agent runtime 最小调用协议。
+ *
+ * 中文备注：
+ * - 这里只声明 runtime-kernel / context-core 真正读取的字段；
+ * - 产品层的 AgentInvokeRequest 可以通过结构类型自然满足该接口；
+ * - agent package 不再从 app core 反向导入调用协议；
+ * - 公共合同面不依赖产品 enum：promptKey 在 ports 层是 opaque string。
+ */
+interface AgentInvocationRequest {
+    query: string;
+    promptKey: string;
+    model_id?: string;
+    imageGenerationModelId?: string;
+    /**
+     * 兼容字段。
+     *
+     * 当前仍允许 host 显式传入 `chat`，但长期目标不是维护两套并列核心模式；
+     * 纯聊天会逐步收敛为“不给工具的 agent 形态”。
+     */
+    mode?: 'agent' | 'chat';
+    maxSteps?: number;
+    enableTools?: boolean;
+    availableTools?: string[];
+    conversationHistory?: AiMessage[];
+}
+
+export type { AgentInvocationRequest as A };

package/dist/agentEvents-DEB7Fy_J.d.cts

@@ -0,0 +1,81 @@
+/**
+ * @file runtime-kernel/events/agentEvents.ts
+ * @description graph 主执行链使用的最小 Agent 事件契约
+ *
+ * 中文备注：
+ * - 该文件只承载 runtime-kernel 主链路真正需要识别的事件子集；
+ * - 目标是让 `executor` / `llmNode` / `eventMappers` 不再反向依赖宿主或产品层事件定义；
+ * - host/product 层若有更丰富的事件，只要结构兼容，仍可在边界透传进来。
+ */
+interface AgentEvent {
+    type: string;
+    timestamp: number;
+    id?: string;
+    /**
+     * 中文备注：
+     * - 该标记只在运行期内存中使用，用于避免同一事件被 SSE 重复分发；
+     * - 不属于持久化协议字段。
+     */
+    __dispatched_via_sse__?: true;
+}
+interface BaseToolLifecycleAgentEvent extends AgentEvent {
+    tool_name: string;
+    tool_args: Record<string, unknown>;
+    tool_calls?: unknown[];
+    tool_call_id?: string;
+    phase?: 'start' | 'update' | 'complete' | 'error';
+    status?: 'loading' | 'success' | 'error';
+    payload?: Record<string, unknown>;
+    meta?: Record<string, unknown>;
+}
+interface ThoughtEvent extends AgentEvent {
+    type: 'thought';
+    content: string;
+    delta?: string;
+    is_complete?: boolean;
+    meta?: Record<string, unknown>;
+    thought_message_id?: string;
+}
+interface ToolCallDecisionEvent extends BaseToolLifecycleAgentEvent {
+    type: 'tool_call_decision';
+}
+interface ToolProcessEvent extends BaseToolLifecycleAgentEvent {
+    type: 'tool_process';
+}
+interface ObservationEvent extends AgentEvent {
+    type: 'observation';
+    tool_name: string;
+    tool_call_id?: string;
+    output: string;
+    success?: boolean;
+    payload?: Record<string, unknown>;
+    duration_ms?: number;
+}
+interface FinalAnswerEvent extends AgentEvent {
+    type: 'final_answer';
+    answer: string;
+    answer_id?: string;
+    answerId?: string;
+    reasoning_details?: unknown[];
+    meta?: Record<string, unknown>;
+}
+interface ErrorEvent extends AgentEvent {
+    type: 'error';
+    error: string;
+    details?: string;
+}
+interface StreamChunkEvent extends AgentEvent {
+    type: 'stream_chunk';
+    content: string;
+    answer_id?: string;
+    seq?: number;
+    is_last?: boolean;
+    isLast?: boolean;
+}
+interface ProviderSidecarEvent extends AgentEvent {
+    type: 'provider_sidecar';
+    reasoning_details?: unknown[];
+}
+type AnyAgentEvent = ThoughtEvent | ToolCallDecisionEvent | ToolProcessEvent | ObservationEvent | FinalAnswerEvent | ErrorEvent | StreamChunkEvent | ProviderSidecarEvent;
+
+export type { AnyAgentEvent as A };