@linnlabs/linnkit 0.8.0

package/dist/tokenizer-DFL4I7-I.d.ts

@@ -0,0 +1,28 @@
+import { a as LlmRequestMessage } from './ai-engine.types-vZRnQcJa.js';
+
+/**
+ * TokenizerPort · host 可替换的 token 估算协议。
+ *
+ * 中文备注：
+ * - tokenizer 是“计算 token 的方法”的总称；
+ * - linnkit 默认实现和 host 自定义实现都实现这个接口；
+ * - 该 port 只服务上下文预算决策，不用于计费；
+ * - 计费 token 应以 provider 返回的 usage 为准，由 host 自己消费。
+ */
+interface TokenizerPort {
+    /**
+     * 估算纯文本 token 数。
+     *
+     * modelId 可用于 host 在多模型场景下选择不同 tokenizer。
+     */
+    estimateText(text: string, modelId?: string): number;
+    /**
+     * 估算一条 LLM message 的 token 数。
+     *
+     * 自定义实现应包含 message overhead、tool_call overhead 和 tool_call_id 开销；
+     * 否则上下文预算会系统性低估。
+     */
+    estimateMessage(message: LlmRequestMessage, modelId?: string): number;
+}
+
+export type { TokenizerPort as T };

package/dist/tokenizer-DH_JXv-H.d.cts

@@ -0,0 +1,28 @@
+import { a as LlmRequestMessage } from './ai-engine.types-BpeU_XQG.cjs';
+
+/**
+ * TokenizerPort · host 可替换的 token 估算协议。
+ *
+ * 中文备注：
+ * - tokenizer 是“计算 token 的方法”的总称；
+ * - linnkit 默认实现和 host 自定义实现都实现这个接口；
+ * - 该 port 只服务上下文预算决策，不用于计费；
+ * - 计费 token 应以 provider 返回的 usage 为准，由 host 自己消费。
+ */
+interface TokenizerPort {
+    /**
+     * 估算纯文本 token 数。
+     *
+     * modelId 可用于 host 在多模型场景下选择不同 tokenizer。
+     */
+    estimateText(text: string, modelId?: string): number;
+    /**
+     * 估算一条 LLM message 的 token 数。
+     *
+     * 自定义实现应包含 message overhead、tool_call overhead 和 tool_call_id 开销；
+     * 否则上下文预算会系统性低估。
+     */
+    estimateMessage(message: LlmRequestMessage, modelId?: string): number;
+}
+
+export type { TokenizerPort as T };

package/dist/toolContracts-Blll0241.d.ts

@@ -0,0 +1,463 @@
+import { e as RuntimeEvent, g as SubRunTraceEvent, a as AgentTodoSnapshot } from './todo-B1PmDlp3.js';
+
+interface ToolContextConversationView {
+    /**
+     * 当前工具执行可见的 working history
+     *
+     * 中文备注：
+     * - 该视图允许工具读取“本轮 run 中已产生、但可能尚未持久化”的最新事实事件；
+     * - ToolNode / graph runtime 后续只应更新这一层背后的 source，而不是覆写顶层 getter。
+     */
+    getWorkingHistoryEvents(): ReadonlyArray<RuntimeEvent>;
+    /**
+     * run 启动时的 persisted history 视图
+     *
+     * 中文备注：
+     * - 该视图对应 EventStore 回放得到的稳定历史；
+     * - 与 working history 显式区分，避免调用方误把“最新运行态”当成“已持久化事实”。
+     */
+    getPersistedHistoryEvents(): ReadonlyArray<RuntimeEvent>;
+}
+
+/**
+ * 子 run trace 的“业务无关”发布载荷。
+ *
+ * 说明：
+ * - 该结构刻意只包含 subrun_trace 的 payload 字段（不包含 conversation_id/turn_id 等基础字段）
+ * - parent_tool_call_id/subrun_id 是发布器构造时绑定的，不需要每次 publish 重复提供
+ */
+interface SubRunTraceEnvelope {
+    /** 分片类型 */
+    kind: SubRunTraceEvent['kind'];
+    /** 增量文本（kind=*_delta 时使用） */
+    delta?: string;
+    /** 完整文本（kind=*_complete/final_answer 时使用） */
+    content?: string;
+    /** 关联工具名（kind=tool_call_decision/tool_process/tool_output 时使用） */
+    tool_name?: string;
+    /** 关联工具调用 ID（子 run 内部的 tool_call_id，用于展示步骤） */
+    tool_call_id?: string;
+    /** 工具调用阶段（kind=tool_call_decision/tool_process 时使用） */
+    phase?: SubRunTraceEvent['phase'];
+    /** 工具调用状态（kind=tool_call_decision/tool_process/tool_output 时使用） */
+    status?: SubRunTraceEvent['status'];
+    /** 工具参数（结构不做强约束，避免与业务强耦合） */
+    args?: unknown;
+    /** 工具输出（结构不做强约束，避免与业务强耦合） */
+    output?: unknown;
+    /** 执行耗时（毫秒） */
+    duration_ms?: number;
+    /** 可选调试/渲染元信息 */
+    meta?: Record<string, unknown>;
+}
+/**
+ * 子 run trace 发布器接口（面向业务工具层）。
+ *
+ * 约束：
+ * - 发布器必须确保生成的 RuntimeEvent 为 `type='subrun_trace'` 且 `ephemeral=true`
+ * - 发布器应保证每条事件的 id 唯一（用于前端 processedEvents 幂等去重）
+ */
+interface SubRunTracePublisher {
+    publish(envelope: SubRunTraceEnvelope): void;
+}
+
+/**
+ * @file src/agent/runtime-kernel/run-context/types.ts
+ * @description 统一运行上下文定义
+ *
+ * 核心目标：
+ * - 统一管理跨 Run（Graph执行）的链路追踪信息
+ * - 支持父子任务（SubAgent）与审阅等长程业务的上下文贯穿
+ * - 替代散落在各处的 review_run_id 等专用字段
+ */
+interface RunContext {
+    /**
+     * 当前 Run 的唯一标识（对应一次 Graph 执行 / 一次 conversation turn）
+     * - 通常对应 `turnId` 或 `messageId`
+     */
+    runId: string;
+    /**
+     * 链路追踪 ID（贯穿业务全流程）
+     * - Review场景：对应 review_run_id（一次审阅包含多次 AI 调用）
+     * - 简单对话场景：可与 conversationId 或 runId 相同
+     */
+    traceId: string;
+    /**
+     * 父级 Run ID（用于子 Agent / 嵌套图）
+     * - 如果是顶层任务，则为 undefined
+     */
+    parentId?: string;
+    /**
+     * 根 Run ID（业务发起的原点）
+     */
+    rootRunId?: string;
+    /**
+     * 业务标签/元数据（业务特定的上下文挂载点）
+     * - 例如：{ agentId: 'logicCheck', chunkIndex: 0 }
+     * - 替代原先散落在 ToolContext 顶层的 loose fields
+     */
+    tags: Record<string, string | number | boolean | undefined>;
+}
+/**
+ * 创建默认的 RunContext
+ */
+declare function createDefaultRunContext(overrides?: Partial<RunContext>): RunContext;
+
+interface ToolContextCompatibilityFields {
+    /**
+     * 兼容字段：原始用户请求
+     *
+     * 中文备注：
+     * - 当前由 host context injection 写入；
+     * - 仍有少量 deep_search 调用方在读取；
+     * - 后续应继续收窄，不再扩散新的读取点。
+     */
+    user_query?: string;
+    /**
+     * 兼容字段：当前 run 选定模型 ID
+     *
+     * 中文备注：
+     * - 当前主要给 child-run 调用方继承父模型选择；
+     * - 后续应继续收窄到显式 child-run execution policy。
+     */
+    modelId?: string;
+    /**
+     * 兼容字段：当前 runContext
+     *
+     * 中文备注：
+     * - 当前主要由 host 注入；尚未在工具侧广泛直接读取；
+     * - 保留显式字段是为了停止继续依赖 string-index loose access。
+     */
+    run_context?: RunContext;
+}
+type CompatibilityCarrier = ToolContextCompatibilityFields | Record<string, unknown> | undefined;
+declare function readToolContextUserQuery(context: CompatibilityCarrier): string | undefined;
+declare function readToolContextModelId(context: CompatibilityCarrier): string | undefined;
+declare function readToolContextRunContext(context: CompatibilityCarrier): RunContext | undefined;
+
+/**
+ * child-run 父上下文的 runtime-owned 最小合同
+ *
+ * 中文备注：
+ * - 这里只声明 child-run 协议真正需要的 runtime capability / compatibility fields；
+ * - 不显式依赖完整 ToolContext，避免 child-run 主链编译期吃进整套 host/product 服务类型；
+ * - 仍保留 index signature，用于在创建 child ToolContext 时透传宿主/产品层 patch。
+ */
+interface ChildRunParentContext extends ToolExecutionContext, ToolContextCompatibilityFields {
+    deepSearchDepth?: number;
+    [key: string]: unknown;
+}
+interface ChildRunHistoryPolicy {
+    inheritTurns: number;
+    eventFilter?: (event: RuntimeEvent) => boolean;
+}
+interface ChildRunTracePolicy {
+    parentToolCallId?: string;
+    subrunId?: string;
+    source?: string;
+    metadata?: Record<string, unknown>;
+    persistForReplay?: boolean;
+}
+interface ChildRunExecutionPolicy {
+    /**
+     * 显式 child-run runId。默认由 host adapter 取 subrunId。
+     */
+    runId?: string;
+    /**
+     * 父 runId。默认从 parentToolContext.runId 继承。
+     */
+    parentRunId?: string;
+    maxSteps?: number;
+    modelId?: string;
+    abortSignal?: AbortSignal;
+}
+interface ChildRunRequest<TParentToolContext = ChildRunParentContext> {
+    userMessage: string;
+    parentToolContext: TParentToolContext;
+    historyPolicy?: ChildRunHistoryPolicy;
+    tracePolicy?: ChildRunTracePolicy;
+    executionPolicy?: ChildRunExecutionPolicy;
+}
+interface ChildRunResult {
+    runId?: string;
+    parentRunId?: string;
+    subrunId: string;
+    success: boolean;
+    finalAnswer: string;
+    events: RuntimeEvent[];
+    stepCount: number;
+    error?: string;
+    judgeToolOutput?: string;
+}
+interface ChildRunInvokerPort<TRequest extends ChildRunRequest = ChildRunRequest, TResult extends ChildRunResult = ChildRunResult> {
+    invoke(params: TRequest): Promise<TResult>;
+}
+
+/**
+ * runtime-owned 工具执行上下文最小合同
+ *
+ * 中文备注：
+ * - 这里只保留 graph-engine / tool runtime / child-run 真正需要解释执行的字段；
+ * - 不包含 KnowledgeBase / Workspace / DB 等宿主服务类型；
+ * - 不包含 deepSearch / research / workspaceProject 等产品语义字段。
+ */
+interface ToolExecutionContext {
+    /**
+     * 当前对话 run 的唯一标识（由 FlowOrchestrator 注入）
+     * 说明：Workspace 工具 vNext 协议已不再依赖 index 快照，但 runId 仍可用于其他链路的追踪/调试。
+     */
+    runId?: string;
+    /**
+     * 父级 run 标识。
+     *
+     * 中文备注：
+     * - 顶层 run 通常为空；
+     * - 同步 child-run 会把自己的 `runId` 设为子 run / subrun ID，同时把父 run 写到这里；
+     * - Telemetry / Audit / Cost 聚合依赖这个字段建立父子关系，但 graph-engine 不解释产品语义。
+     */
+    parentRunId?: string;
+    /**
+     * 🔥 引用编号偏移量（用于多次工具调用时的连续编号）
+     *
+     * 工作原理：
+     * - 每次调用知识库工具时,由 ToolNode 传入当前轮次已使用的引用数量
+     * - 工具在格式化 observation 和构建 citations 时使用此偏移量
+     * - 确保 AI 看到的编号和引用元数据的编号都是连续且一致的
+     *
+     * @default 0 - 表示从 1 开始编号
+     */
+    citationOffset?: number;
+    /**
+     * 🔥 取消信号（贯穿一次对话请求）
+     *
+     * 约定：
+     * - 工具实现必须在合适的边界检查 `abortSignal.aborted` 并尽快退出；
+     * - 该字段属于“执行期上下文”，不应被写入持久化事件。
+     */
+    abortSignal?: AbortSignal;
+    /**
+     * 🔥 当前这次工具调用的 tool_call_id（由 ToolNode 在执行前注入）
+     *
+     * 说明：
+     * - tool_call_id 属于“事件层/执行层”的稳定关联键；
+     * - 工具内部如果需要发布 subrun_trace（子 run 过程），必须使用该字段作为 parent_tool_call_id。
+     * - 该字段仅在工具执行期间有效，不应被工具写入持久化历史。
+     */
+    parentToolCallId?: string;
+    /**
+     * 🔥 当前对话 ID（由 GraphExecutor/ToolNode 注入，用于工具内部做链路追踪）
+     */
+    conversationId?: string;
+    /**
+     * 🔥 当前轮次 ID（由 GraphExecutor/ToolNode 注入，用于工具内部做链路追踪）
+     */
+    turnId?: string;
+    /**
+     * 🔥 Agent ToDo（working memory）快照（对话级）
+     *
+     * 设计说明：
+     * - ToDo 的权威状态应落到 RuntimeEvent（todo_updated）以便截断/回放一致；
+     * - 但工具执行期间需要“读到本轮最新状态”（尚未落库），因此把最新快照同时缓存到 ToolContext。
+     * - AgentRunnerService 会在每次 run 开始时用历史事件回放的最后一条 todo_updated 为其初始化。
+     */
+    agentTodo?: AgentTodoSnapshot;
+    /**
+     * 🔥 显式会话视图 capability
+     *
+     * 中文备注：
+     * - `conversationView` 是后续统一承载 working/persisted history 的稳定协议面；
+     * - 迁移期仍保留 `getConversationHistoryEvents()` 兼容旧工具。
+     */
+    conversationView?: ToolContextConversationView;
+    /**
+     * 🔥 获取父会话的历史事件（兼容 getter）
+     *
+     * 约束：
+     * - 返回值必须被视为只读：工具不得修改数组内容；
+     * - 迁移期该 getter 语义固定为 `conversationView.getWorkingHistoryEvents()`；
+     * - 新代码优先直接使用 `conversationView`，避免继续把 working/persisted history 混为一个概念。
+     */
+    getConversationHistoryEvents?: () => ReadonlyArray<RuntimeEvent>;
+    /**
+     * 🔥 发布 todo_updated RuntimeEvent（低耦合注入）
+     */
+    publishAgentTodoUpdated?: (snapshot: AgentTodoSnapshot) => void;
+    /**
+     * 🔥 SubRun Trace Channel：为工具提供 publisher 工厂（低耦合）
+     */
+    createSubRunTracePublisher?: (opts: {
+        parentToolCallId: string;
+        subrunId: string;
+        subrunParentId?: string;
+        source?: string;
+        metadata?: Record<string, unknown>;
+        persistForReplay?: boolean;
+    }) => SubRunTracePublisher;
+    /**
+     * 显式 child-run invoker 注入（迁移期优先入口）
+     */
+    registeredChildRunInvoker?: ChildRunInvokerPort;
+    /**
+     * 与 ConversationArtifactContext 等「可扩展宿主字段」交织时的结构兼容：
+     * - 运行期 toolContext 常为普通对象，可能携带 sharedMemory / research 等附加键；
+     * - 无此索引签名时，`ToolExecutionContext` 无法赋给 `ToolExecutionContext & ConversationArtifactContext`（strict 下报错）。
+     */
+    [key: string]: unknown;
+}
+
+/**
+ * @file src/agent/runtime-kernel/tools/ui-types.ts
+ *
+ * @brief 定义工具在前端UI展示时所需的元数据类型
+ *
+ * @description
+ * 这个文件中的类型专门用于 "后端驱动UI (Backend-Driven UI)" 架构。
+ * 当后端Agent执行一个工具时，它会附带这些UI元数据。
+ * 前端则根据这些元数据，动态地、智能地渲染出对应的UI组件，
+ * 从而实现工具展示逻辑与前端渲染逻辑的解耦。
+ */
+interface ToolLayoutOptions {
+    contentPadding?: boolean;
+    showBorder?: boolean;
+    showBackground?: boolean;
+}
+interface ToolDisplayOptions {
+    viewType: string;
+    titleTemplate?: string;
+    icon?: string;
+    layout?: ToolLayoutOptions;
+}
+interface ToolControlInfo {
+    requireUser?: boolean;
+    questionnaireId?: string;
+    resumeStrategy?: 'continue';
+    terminateRun?: boolean;
+    reason?: string;
+}
+interface StructuredToolResult<T = Record<string, unknown>> {
+    data: T;
+    observation?: string;
+    control?: ToolControlInfo;
+}
+
+type ToolIdempotencyScope = 'conversation' | 'turn';
+type ToolIdempotencyPolicy = {
+    scope: ToolIdempotencyScope;
+};
+declare function computeToolIdempotencyKey(params: {
+    policy: ToolIdempotencyPolicy;
+    toolName: string;
+    args: Record<string, unknown>;
+    context: ToolExecutionContext;
+}): string;
+declare function findCachedToolOutputByIdempotencyKey(params: {
+    history: ReadonlyArray<RuntimeEvent>;
+    toolName: string;
+    idempotencyKey: string;
+}): {
+    output: string;
+} | undefined;
+
+type ToolArgs = Record<string, unknown>;
+type JsonObjectSchema = Record<string, unknown>;
+interface ToolParameterProperty {
+    type: string;
+    description: string;
+    default?: unknown;
+    enum?: string[];
+    properties?: Record<string, ToolParameterProperty>;
+    items?: ToolParameterProperty;
+    required?: string[];
+}
+interface ToolParameterSchema {
+    type: 'object';
+    properties: Record<string, ToolParameterProperty>;
+    required?: string[];
+    additionalProperties?: boolean;
+}
+interface ToolResult {
+    success: boolean;
+    data: string;
+    metadata?: Record<string, unknown>;
+}
+type UnifiedToolResult = {
+    kind: 'ok';
+    output: unknown;
+} | {
+    kind: 'need_user';
+    spec: unknown;
+} | {
+    kind: 'async';
+    run_id: string;
+};
+declare abstract class BaseTool<TArgs extends ToolArgs = ToolArgs, TResult extends string = string> {
+    abstract readonly name: string;
+    abstract readonly description: string;
+    abstract readonly parameters: ToolParameterSchema;
+    readonly idempotency?: ToolIdempotencyPolicy;
+    readonly displayOptions?: ToolDisplayOptions;
+    getExecutionSummary?(output: string): string;
+    abstract run(args: TArgs, context: ToolExecutionContext): Promise<TResult>;
+    protected validateArguments(args: TArgs): {
+        success: boolean;
+        error?: string;
+    };
+    getMetadata(): {
+        name: string;
+        description: string;
+        parameters: ToolParameterSchema;
+    };
+}
+interface ToolRegistryEntry {
+    name: string;
+    toolClass: new () => BaseTool<ToolArgs, string>;
+    metadata: ReturnType<BaseTool['getMetadata']>;
+}
+declare const CommonParameterTypes: {
+    readonly docId: {
+        readonly type: "string";
+        readonly description: "The unique ID of the document";
+    };
+    readonly query: {
+        readonly type: "string";
+        readonly description: "The search query text";
+    };
+    readonly topK: {
+        readonly type: "integer";
+        readonly description: "The maximum number of results to return";
+        readonly default: 5;
+    };
+    readonly blockId: {
+        readonly type: "string";
+        readonly description: "The unique ID of a content block";
+    };
+    readonly pageNumber: {
+        readonly type: "integer";
+        readonly description: "Page number (1-indexed)";
+        readonly default: 1;
+    };
+};
+interface AgentTool<TArgs extends ToolArgs = ToolArgs, TResult = unknown> {
+    name: string;
+    description: string;
+    parameters: JsonObjectSchema;
+    execute(args: TArgs): Promise<TResult>;
+}
+interface OpenAIToolSchema {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: JsonObjectSchema;
+    };
+}
+interface ToolCallResult<TResult = unknown> {
+    toolName: string;
+    args: ToolArgs;
+    result: TResult;
+    success: boolean;
+    error?: string;
+    durationMs: number;
+}
+
+export { type AgentTool as A, BaseTool as B, CommonParameterTypes as C, type JsonObjectSchema as J, type OpenAIToolSchema as O, type RunContext as R, type StructuredToolResult as S, type ToolExecutionContext as T, type UnifiedToolResult as U, type ToolArgs as a, type ToolParameterSchema as b, type ToolParameterProperty as c, type ToolContextConversationView as d, type ToolCallResult as e, type ToolContextCompatibilityFields as f, type ToolControlInfo as g, type ToolDisplayOptions as h, type ToolLayoutOptions as i, type ToolRegistryEntry as j, type ToolResult as k, computeToolIdempotencyKey as l, findCachedToolOutputByIdempotencyKey as m, readToolContextRunContext as n, readToolContextUserQuery as o, createDefaultRunContext as p, type ChildRunParentContext as q, readToolContextModelId as r, type SubRunTracePublisher as s, type ChildRunHistoryPolicy as t, type ChildRunInvokerPort as u, type ChildRunRequest as v, type ChildRunResult as w, type SubRunTraceEnvelope as x, type ToolIdempotencyPolicy as y };