@linnlabs/linnkit 0.8.0

package/dist/testkit.d.cts

@@ -0,0 +1,284 @@
+import { L as LlmCallOptions$1, a as LlmRequestMessage } from './ai-engine.types-BpeU_XQG.cjs';
+import { f as LlmCaller$1, K as TelemetryEvent$2, D as DefaultRunSupervisor, t as MemoryRunRegistryStore, p as MemoryEventStore, u as RunExecutorPort$1, v as RunOutcome$1, q as ToolContextPatch$1 } from './defaultGraphExecutor-BIjJj7WF.cjs';
+export { P as DefaultGraphExecutorOptions, Q as GraphLoopHarness, U as GraphLoopHarnessOptions, V as GraphLoopHarnessRunResult, W as GraphLoopLlmNodeFactoryParams, X as createDefaultGraphExecutor, Y as createGraphLoopHarness } from './defaultGraphExecutor-BIjJj7WF.cjs';
+import { e as RuntimeEvent } from './todo-B1PmDlp3.cjs';
+import { A as AiMessage } from './messages-XthmnHZ3.cjs';
+import { e as AgentSpecContextPolicy, a as AgentSpec } from './agentSpec-EkmviZjy.cjs';
+import { d as ContextTrace } from './context-trace-HE2qY5Q-.cjs';
+import { T as TokenizerPort } from './tokenizer-DH_JXv-H.cjs';
+import { e as AuditEnvelope } from './audit-BaRUGaqv.cjs';
+import { b as AuditPort } from './audit-LeOrm2hX.cjs';
+import { f as RunCostCollector$1, n as RunRequestSnapshot$1, b as EventBus, h as RunHandle$1, l as RunRecord$2, P as PersistedEvent$1, e as RunCost$1 } from './runHandle-D3gPsD7B.cjs';
+import { T as ToolExecutionContext$1, f as ToolContextCompatibilityFields$1 } from './toolContracts-CLkQmhTG.cjs';
+import './agent-invocation-BHcNfrBV.cjs';
+import './agentEvents-DEB7Fy_J.cjs';
+import './ports-DaatKJXp.cjs';
+import 'zod';
+import './execution-CAIypb41.cjs';
+
+type LlmCaller = LlmCaller$1;
+type LlmCallOptions = LlmCallOptions$1;
+interface ScriptedLlmCall {
+    modelId: string;
+    messages: unknown[];
+    options: LlmCallOptions & {
+        signal?: AbortSignal;
+        stream_options?: {
+            include_usage?: boolean;
+        };
+    };
+}
+interface ScriptedToolCall {
+    id: string;
+    name: string;
+    argumentsJson: string;
+    index?: number;
+}
+interface ScriptedLlmTurn {
+    thoughtDeltas?: string[];
+    contentChunks?: string[];
+    toolCalls?: ScriptedToolCall[];
+    reasoningDetails?: unknown[];
+    usage?: unknown;
+    finishReason?: string;
+    error?: string | Error;
+    throwAfterCallbacks?: string | Error;
+    assertCall?: (call: ScriptedLlmCall) => void;
+}
+interface ScriptedAiEngineHarness {
+    getCalls(): ScriptedLlmCall[];
+    getConsumedTurnCount(): number;
+    getLlmCaller(): LlmCaller;
+    assertAllTurnsConsumed(): void;
+    restore(): void;
+}
+interface ScriptedAiEngineHarnessOptions {
+    /**
+     * 迁移期兼容开关：历史上可把 scripted engine patch 到模块级 `aiEngine`。
+     *
+     * 中文备注：
+     * - `src/agent/testkit/*` 现在不再依赖 `src/core/aiEngine`；
+     * - 新旧测试都应显式注入 `getLlmCaller()`；
+     * - 若仍传入 `true`，直接抛错，避免 package boundary 悄悄回退。
+     */
+    patchModuleAiEngine?: boolean;
+}
+declare function createScriptedAiEngineHarness(turns: ScriptedLlmTurn[], options?: ScriptedAiEngineHarnessOptions): ScriptedAiEngineHarness;
+
+declare function expectMessagesContainToolResult(call: ScriptedLlmCall, expectedText: string): void;
+declare function expectToolOutputFedBackToHistory(call: ScriptedLlmCall, expectedText: string): void;
+declare function expectFinalStepForcedTools(call: ScriptedLlmCall, forcedToolName: string): void;
+declare function expectRunEndedWithFinalAnswer(events: RuntimeEvent[], expectedText: string): void;
+declare function expectMessagesContainText(call: ScriptedLlmCall, expectedText: string): void;
+
+declare const assertions_expectFinalStepForcedTools: typeof expectFinalStepForcedTools;
+declare const assertions_expectMessagesContainText: typeof expectMessagesContainText;
+declare const assertions_expectMessagesContainToolResult: typeof expectMessagesContainToolResult;
+declare const assertions_expectRunEndedWithFinalAnswer: typeof expectRunEndedWithFinalAnswer;
+declare const assertions_expectToolOutputFedBackToHistory: typeof expectToolOutputFedBackToHistory;
+declare namespace assertions {
+  export { assertions_expectFinalStepForcedTools as expectFinalStepForcedTools, assertions_expectMessagesContainText as expectMessagesContainText, assertions_expectMessagesContainToolResult as expectMessagesContainToolResult, assertions_expectRunEndedWithFinalAnswer as expectRunEndedWithFinalAnswer, assertions_expectToolOutputFedBackToHistory as expectToolOutputFedBackToHistory };
+}
+
+/**
+ * 中文备注：
+ * - ReplayHarness 负责把“持久化事实事件 -> LLM 回放消息”这个协议边界显式化；
+ * - 测试不再直接散落调用 eventConverter，而是通过统一夹具观察回放结果；
+ * - 这样后续如果回放语义升级，测试入口可以保持稳定。
+ */
+interface ReplayHarness {
+    replay(): AiMessage[];
+    getAssistantToolCallMessages(): AiMessage[];
+    getToolOutputMessages(): AiMessage[];
+}
+declare function createReplayHarness(events: RuntimeEvent[]): ReplayHarness;
+
+type ContextPolicyInvariantId = 'C1_TRACE_ENABLED_MATCHES_POLICY' | 'C2_EFFECTIVE_POLICY_MATCHES_EXPECTED' | 'C3_TRACE_OPTIONS_MATCH_POLICY' | 'C4_TRACE_EVENT_LIMIT' | 'C5_FINAL_COUNTS_MATCH_MESSAGES' | 'C6_FINAL_TOKENS_WITHIN_BUDGET' | 'C7_PROVIDER_TOKEN_DELTA' | 'C8_TRACE_DETAIL_OPTIONS' | 'C9_MESSAGE_DECISION_REASON' | 'C10_TOOL_PAIR_DECISIONS_STAY_TOGETHER' | 'C11_MUST_KEEP_TYPES_KEPT' | 'C12_HOST_TOKENIZER_DRIVES_BUDGET';
+interface ContextPolicyInvariantFailure {
+    id: ContextPolicyInvariantId;
+    title: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+interface ContextPolicyInvariantReport {
+    ok: boolean;
+    failures: ContextPolicyInvariantFailure[];
+}
+interface ContextPolicyInvariantContext {
+    expectedPolicy?: AgentSpecContextPolicy;
+    trace?: ContextTrace;
+    originalMessages?: readonly AiMessage[];
+    finalMessages?: readonly AiMessage[];
+    tokenizer?: TokenizerPort;
+    tokenizerModelId?: string;
+}
+type ContextPolicyInvariantValidator = (context: ContextPolicyInvariantContext) => ContextPolicyInvariantFailure[];
+interface ValidateContextPolicyInvariantsOptions {
+    enabled?: readonly ContextPolicyInvariantId[];
+    disabled?: readonly ContextPolicyInvariantId[];
+}
+
+declare function validateContextPolicyInvariants(context: ContextPolicyInvariantContext, options?: ValidateContextPolicyInvariantsOptions): ContextPolicyInvariantReport;
+declare function assertContextPolicyInvariants(report: ContextPolicyInvariantReport): void;
+
+interface CollectingAuditPortHarness {
+    port: AuditPort;
+    getEnvelopes(action?: string): AuditEnvelope[];
+    assertEmitted(action: string): AuditEnvelope;
+    assertEmittedInOrder(actions: readonly string[]): AuditEnvelope[];
+    reset(): void;
+}
+/**
+ * 收集型 AuditPort。
+ *
+ * 中文备注：
+ * - 用于测试“某次 run 做过哪些决策”，不写文件、不进 EventStore；
+ * - 断言方法故意抛普通 Error，让 Vitest/Jest 能直接显示友好的失败原因。
+ */
+declare function createCollectingAuditPort(): CollectingAuditPortHarness;
+
+type TelemetryEvent$1 = TelemetryEvent$2;
+type RunCostCollector = RunCostCollector$1;
+interface TelemetryUsageTotal {
+    tokensInput: number;
+    tokensOutput: number;
+    latencyMs: number;
+    llmCallCount: number;
+    toolCallCount: number;
+}
+interface MockTelemetryPortHarness {
+    port: {
+        emit(event: TelemetryEvent$1): void;
+        flush(): Promise<void>;
+    };
+    costCollector: RunCostCollector;
+    emit(event: TelemetryEvent$1): void;
+    getEvents(runId?: string): TelemetryEvent$1[];
+    getTotalUsageByRun(runId: string): TelemetryUsageTotal;
+    getKnownRunIds(): string[];
+    reset(): void;
+}
+/**
+ * TelemetryPort 测试夹具。
+ *
+ * 中文备注：
+ * - 它同时保留 ground truth 事件列表和一个 RunCostCollector；
+ * - 父子 run 通过 scope.parentRunId 关联，方便验证 B.3 的 childrenTotal。
+ */
+declare function createMockTelemetryPort(): MockTelemetryPortHarness;
+
+type RunHandle<TRequest extends RunRequestSnapshot$1> = RunHandle$1<TRequest>;
+type RunRecord$1 = RunRecord$2;
+type RunRequestSnapshot = RunRequestSnapshot$1;
+type RunExecutorPort<TRequest extends RunRequestSnapshot> = RunExecutorPort$1<TRequest>;
+interface RunSupervisorHarness<TRequest extends RunRequestSnapshot = RunRequestSnapshot> {
+    supervisor: DefaultRunSupervisor<TRequest>;
+    registry: MemoryRunRegistryStore;
+    eventStore: MemoryEventStore;
+    eventBus: EventBus;
+    audit: CollectingAuditPortHarness;
+    telemetry: MockTelemetryPortHarness;
+    registerRun(params?: Partial<{
+        runId: string;
+        parentRunId: string;
+        conversationId: string;
+        agentSpec: AgentSpec;
+        request: TRequest;
+        metadata: Record<string, unknown>;
+    }>): Promise<RunHandle<TRequest>>;
+    spawnDetached(params?: Partial<{
+        runId: string;
+        parentRunId: string;
+        conversationId: string;
+        agentSpec: AgentSpec;
+        request: TRequest;
+        metadata: Record<string, unknown>;
+    }>): Promise<RunHandle<TRequest>>;
+    publish(event: RuntimeEvent, seq?: number): void;
+    persist(event: RuntimeEvent, eventId?: string): Promise<void>;
+    getRegisteredRuns(): Promise<RunRecord$1[]>;
+    restore(): void;
+}
+/**
+ * RunSupervisor 一站式测试夹具。
+ *
+ * 中文备注：
+ * - 只使用 linnkit package 内部 port，不依赖具体 host；
+ * - 适合协议测试、外部接入方测试、Quickstart/CLI 的最小 run 验证。
+ */
+declare function createRunSupervisorHarness<TRequest extends RunRequestSnapshot = RunRequestSnapshot>(options?: Partial<{
+    executionId: string;
+    now: () => number;
+    runIdFactory: () => string;
+    executor: RunExecutorPort<TRequest>;
+}>): RunSupervisorHarness<TRequest>;
+
+type PersistedEvent = PersistedEvent$1;
+type RunCost = RunCost$1;
+type RunRecord = RunRecord$2;
+type RunOutcome = RunOutcome$1;
+type TelemetryEvent = TelemetryEvent$2;
+type RunInvariantId = 'I1_FINAL_STATUS' | 'I2_CHILDREN_COST_TOTAL' | 'I3_TOOL_CALL_OUTPUT_PAIR' | 'I4_LLM_MODEL_SELECT_AUDIT' | 'I5_CANCEL_AUDIT' | 'I6_EVENT_RUN_CONTEXT' | 'I7_PERSISTED_EVENT_ORDER' | 'I8_NO_ACTION_EVENT' | 'I9_CANCEL_SIGNAL_STATUS' | 'I10_TELEMETRY_RUN_REGISTERED' | 'I11_COST_NON_NEGATIVE' | 'I12_AUDIT_RUN_REGISTERED' | 'I13_WAIT_USER_STATUS' | 'I14_DETACHED_TERMINAL_OUTCOME' | 'I15_DRAIN_NO_INFLIGHT';
+interface RunInvariantFailure {
+    id: RunInvariantId;
+    title: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+interface RunInvariantReport {
+    ok: boolean;
+    failures: RunInvariantFailure[];
+}
+interface RunInvariantContext {
+    rootRunId: string;
+    runRecords: readonly RunRecord[];
+    events?: readonly RuntimeEvent[];
+    persistedEvents?: readonly PersistedEvent[];
+    telemetryEvents?: readonly TelemetryEvent[];
+    auditEnvelopes?: readonly AuditEnvelope[];
+    terminalOutcomes?: readonly RunOutcome[];
+    inFlightRunIds?: readonly string[];
+    signal?: AbortSignal;
+    getCost?: (runId: string) => RunCost | Promise<RunCost>;
+}
+interface ValidateRunInvariantsOptions {
+    enabled?: readonly RunInvariantId[];
+    disabled?: readonly RunInvariantId[];
+    /**
+     * 中文备注：
+     * N-3.B.0 只给同步 child-run 透传 runId，并未正式注册 child RunRecord。
+     * 默认严格校验会暴露这个缺口；过渡测试可显式允许 parentRunId 场景下的未注册 child telemetry。
+     */
+    allowUnregisteredChildTelemetry?: boolean;
+}
+
+declare function validateRunInvariants(context: RunInvariantContext, options?: ValidateRunInvariantsOptions): Promise<RunInvariantReport>;
+declare function assertRunInvariants(report: RunInvariantReport): void;
+
+interface MockTokenizerPortOptions {
+    /** 每段 text 固定返回的 token 数，默认 10。 */
+    tokensPerText?: number;
+    /** 每条 message 固定返回的 token 数，默认 50。 */
+    tokensPerMessage?: number;
+    /** 自定义 text 估算逻辑，优先级高于 tokensPerText。 */
+    estimateText?: (text: string, modelId?: string) => number;
+    /** 自定义 message 估算逻辑，优先级高于 tokensPerMessage。 */
+    estimateMessage?: (message: LlmRequestMessage, modelId?: string) => number;
+}
+declare function createMockTokenizerPort(options?: MockTokenizerPortOptions): TokenizerPort;
+
+type ToolContextCompatibilityFields = ToolContextCompatibilityFields$1;
+type ToolExecutionContext = ToolExecutionContext$1;
+type ToolContextPatch = ToolContextPatch$1;
+type ToolContextFixture = ToolExecutionContext & ToolContextCompatibilityFields & Record<string, unknown>;
+interface ToolContextFixtureOptions {
+    conversationId?: string;
+    turnId?: string;
+    historyEvents?: RuntimeEvent[];
+    workingHistoryEvents?: RuntimeEvent[];
+    persistedHistoryEvents?: RuntimeEvent[];
+    patch?: ToolContextPatch;
+}
+declare function createToolContextFixture(options?: ToolContextFixtureOptions): ToolContextFixture;
+
+export { type CollectingAuditPortHarness, type ContextPolicyInvariantContext, type ContextPolicyInvariantFailure, type ContextPolicyInvariantId, type ContextPolicyInvariantReport, type ContextPolicyInvariantValidator, type MockTelemetryPortHarness, type MockTokenizerPortOptions, type ReplayHarness, type RunInvariantContext, type RunInvariantFailure, type RunInvariantId, type RunInvariantReport, type RunSupervisorHarness, type ScriptedAiEngineHarness, type ScriptedAiEngineHarnessOptions, type ScriptedLlmCall, type ScriptedLlmTurn, type ScriptedToolCall, type TelemetryUsageTotal, type ToolContextFixture, type ToolContextFixtureOptions, type ValidateContextPolicyInvariantsOptions, type ValidateRunInvariantsOptions, assertContextPolicyInvariants, assertRunInvariants, assertions, createCollectingAuditPort, createMockTelemetryPort, createMockTokenizerPort, createReplayHarness, createRunSupervisorHarness, createScriptedAiEngineHarness, createToolContextFixture, expectFinalStepForcedTools, expectMessagesContainText, expectMessagesContainToolResult, expectRunEndedWithFinalAnswer, expectToolOutputFedBackToHistory, validateContextPolicyInvariants, validateRunInvariants };

package/dist/testkit.d.ts

@@ -0,0 +1,284 @@
+import { L as LlmCallOptions$1, a as LlmRequestMessage } from './ai-engine.types-vZRnQcJa.js';
+import { f as LlmCaller$1, K as TelemetryEvent$2, D as DefaultRunSupervisor, t as MemoryRunRegistryStore, p as MemoryEventStore, u as RunExecutorPort$1, v as RunOutcome$1, q as ToolContextPatch$1 } from './defaultGraphExecutor-BBswR8wn.js';
+export { P as DefaultGraphExecutorOptions, Q as GraphLoopHarness, U as GraphLoopHarnessOptions, V as GraphLoopHarnessRunResult, W as GraphLoopLlmNodeFactoryParams, X as createDefaultGraphExecutor, Y as createGraphLoopHarness } from './defaultGraphExecutor-BBswR8wn.js';
+import { e as RuntimeEvent } from './todo-B1PmDlp3.js';
+import { A as AiMessage } from './messages-XthmnHZ3.js';
+import { e as AgentSpecContextPolicy, a as AgentSpec } from './agentSpec-EkmviZjy.js';
+import { d as ContextTrace } from './context-trace-DRi5M4lX.js';
+import { T as TokenizerPort } from './tokenizer-DFL4I7-I.js';
+import { e as AuditEnvelope } from './audit-BaRUGaqv.js';
+import { b as AuditPort } from './audit-CtcfART1.js';
+import { f as RunCostCollector$1, n as RunRequestSnapshot$1, b as EventBus, h as RunHandle$1, l as RunRecord$2, P as PersistedEvent$1, e as RunCost$1 } from './runHandle-CyXvzgzk.js';
+import { T as ToolExecutionContext$1, f as ToolContextCompatibilityFields$1 } from './toolContracts-Blll0241.js';
+import './agent-invocation-BznDaXDs.js';
+import './agentEvents-DEB7Fy_J.js';
+import './ports-DnLuKfpE.js';
+import 'zod';
+import './execution-CAIypb41.js';
+
+type LlmCaller = LlmCaller$1;
+type LlmCallOptions = LlmCallOptions$1;
+interface ScriptedLlmCall {
+    modelId: string;
+    messages: unknown[];
+    options: LlmCallOptions & {
+        signal?: AbortSignal;
+        stream_options?: {
+            include_usage?: boolean;
+        };
+    };
+}
+interface ScriptedToolCall {
+    id: string;
+    name: string;
+    argumentsJson: string;
+    index?: number;
+}
+interface ScriptedLlmTurn {
+    thoughtDeltas?: string[];
+    contentChunks?: string[];
+    toolCalls?: ScriptedToolCall[];
+    reasoningDetails?: unknown[];
+    usage?: unknown;
+    finishReason?: string;
+    error?: string | Error;
+    throwAfterCallbacks?: string | Error;
+    assertCall?: (call: ScriptedLlmCall) => void;
+}
+interface ScriptedAiEngineHarness {
+    getCalls(): ScriptedLlmCall[];
+    getConsumedTurnCount(): number;
+    getLlmCaller(): LlmCaller;
+    assertAllTurnsConsumed(): void;
+    restore(): void;
+}
+interface ScriptedAiEngineHarnessOptions {
+    /**
+     * 迁移期兼容开关：历史上可把 scripted engine patch 到模块级 `aiEngine`。
+     *
+     * 中文备注：
+     * - `src/agent/testkit/*` 现在不再依赖 `src/core/aiEngine`；
+     * - 新旧测试都应显式注入 `getLlmCaller()`；
+     * - 若仍传入 `true`，直接抛错，避免 package boundary 悄悄回退。
+     */
+    patchModuleAiEngine?: boolean;
+}
+declare function createScriptedAiEngineHarness(turns: ScriptedLlmTurn[], options?: ScriptedAiEngineHarnessOptions): ScriptedAiEngineHarness;
+
+declare function expectMessagesContainToolResult(call: ScriptedLlmCall, expectedText: string): void;
+declare function expectToolOutputFedBackToHistory(call: ScriptedLlmCall, expectedText: string): void;
+declare function expectFinalStepForcedTools(call: ScriptedLlmCall, forcedToolName: string): void;
+declare function expectRunEndedWithFinalAnswer(events: RuntimeEvent[], expectedText: string): void;
+declare function expectMessagesContainText(call: ScriptedLlmCall, expectedText: string): void;
+
+declare const assertions_expectFinalStepForcedTools: typeof expectFinalStepForcedTools;
+declare const assertions_expectMessagesContainText: typeof expectMessagesContainText;
+declare const assertions_expectMessagesContainToolResult: typeof expectMessagesContainToolResult;
+declare const assertions_expectRunEndedWithFinalAnswer: typeof expectRunEndedWithFinalAnswer;
+declare const assertions_expectToolOutputFedBackToHistory: typeof expectToolOutputFedBackToHistory;
+declare namespace assertions {
+  export { assertions_expectFinalStepForcedTools as expectFinalStepForcedTools, assertions_expectMessagesContainText as expectMessagesContainText, assertions_expectMessagesContainToolResult as expectMessagesContainToolResult, assertions_expectRunEndedWithFinalAnswer as expectRunEndedWithFinalAnswer, assertions_expectToolOutputFedBackToHistory as expectToolOutputFedBackToHistory };
+}
+
+/**
+ * 中文备注：
+ * - ReplayHarness 负责把“持久化事实事件 -> LLM 回放消息”这个协议边界显式化；
+ * - 测试不再直接散落调用 eventConverter，而是通过统一夹具观察回放结果；
+ * - 这样后续如果回放语义升级，测试入口可以保持稳定。
+ */
+interface ReplayHarness {
+    replay(): AiMessage[];
+    getAssistantToolCallMessages(): AiMessage[];
+    getToolOutputMessages(): AiMessage[];
+}
+declare function createReplayHarness(events: RuntimeEvent[]): ReplayHarness;
+
+type ContextPolicyInvariantId = 'C1_TRACE_ENABLED_MATCHES_POLICY' | 'C2_EFFECTIVE_POLICY_MATCHES_EXPECTED' | 'C3_TRACE_OPTIONS_MATCH_POLICY' | 'C4_TRACE_EVENT_LIMIT' | 'C5_FINAL_COUNTS_MATCH_MESSAGES' | 'C6_FINAL_TOKENS_WITHIN_BUDGET' | 'C7_PROVIDER_TOKEN_DELTA' | 'C8_TRACE_DETAIL_OPTIONS' | 'C9_MESSAGE_DECISION_REASON' | 'C10_TOOL_PAIR_DECISIONS_STAY_TOGETHER' | 'C11_MUST_KEEP_TYPES_KEPT' | 'C12_HOST_TOKENIZER_DRIVES_BUDGET';
+interface ContextPolicyInvariantFailure {
+    id: ContextPolicyInvariantId;
+    title: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+interface ContextPolicyInvariantReport {
+    ok: boolean;
+    failures: ContextPolicyInvariantFailure[];
+}
+interface ContextPolicyInvariantContext {
+    expectedPolicy?: AgentSpecContextPolicy;
+    trace?: ContextTrace;
+    originalMessages?: readonly AiMessage[];
+    finalMessages?: readonly AiMessage[];
+    tokenizer?: TokenizerPort;
+    tokenizerModelId?: string;
+}
+type ContextPolicyInvariantValidator = (context: ContextPolicyInvariantContext) => ContextPolicyInvariantFailure[];
+interface ValidateContextPolicyInvariantsOptions {
+    enabled?: readonly ContextPolicyInvariantId[];
+    disabled?: readonly ContextPolicyInvariantId[];
+}
+
+declare function validateContextPolicyInvariants(context: ContextPolicyInvariantContext, options?: ValidateContextPolicyInvariantsOptions): ContextPolicyInvariantReport;
+declare function assertContextPolicyInvariants(report: ContextPolicyInvariantReport): void;
+
+interface CollectingAuditPortHarness {
+    port: AuditPort;
+    getEnvelopes(action?: string): AuditEnvelope[];
+    assertEmitted(action: string): AuditEnvelope;
+    assertEmittedInOrder(actions: readonly string[]): AuditEnvelope[];
+    reset(): void;
+}
+/**
+ * 收集型 AuditPort。
+ *
+ * 中文备注：
+ * - 用于测试“某次 run 做过哪些决策”，不写文件、不进 EventStore；
+ * - 断言方法故意抛普通 Error，让 Vitest/Jest 能直接显示友好的失败原因。
+ */
+declare function createCollectingAuditPort(): CollectingAuditPortHarness;
+
+type TelemetryEvent$1 = TelemetryEvent$2;
+type RunCostCollector = RunCostCollector$1;
+interface TelemetryUsageTotal {
+    tokensInput: number;
+    tokensOutput: number;
+    latencyMs: number;
+    llmCallCount: number;
+    toolCallCount: number;
+}
+interface MockTelemetryPortHarness {
+    port: {
+        emit(event: TelemetryEvent$1): void;
+        flush(): Promise<void>;
+    };
+    costCollector: RunCostCollector;
+    emit(event: TelemetryEvent$1): void;
+    getEvents(runId?: string): TelemetryEvent$1[];
+    getTotalUsageByRun(runId: string): TelemetryUsageTotal;
+    getKnownRunIds(): string[];
+    reset(): void;
+}
+/**
+ * TelemetryPort 测试夹具。
+ *
+ * 中文备注：
+ * - 它同时保留 ground truth 事件列表和一个 RunCostCollector；
+ * - 父子 run 通过 scope.parentRunId 关联，方便验证 B.3 的 childrenTotal。
+ */
+declare function createMockTelemetryPort(): MockTelemetryPortHarness;
+
+type RunHandle<TRequest extends RunRequestSnapshot$1> = RunHandle$1<TRequest>;
+type RunRecord$1 = RunRecord$2;
+type RunRequestSnapshot = RunRequestSnapshot$1;
+type RunExecutorPort<TRequest extends RunRequestSnapshot> = RunExecutorPort$1<TRequest>;
+interface RunSupervisorHarness<TRequest extends RunRequestSnapshot = RunRequestSnapshot> {
+    supervisor: DefaultRunSupervisor<TRequest>;
+    registry: MemoryRunRegistryStore;
+    eventStore: MemoryEventStore;
+    eventBus: EventBus;
+    audit: CollectingAuditPortHarness;
+    telemetry: MockTelemetryPortHarness;
+    registerRun(params?: Partial<{
+        runId: string;
+        parentRunId: string;
+        conversationId: string;
+        agentSpec: AgentSpec;
+        request: TRequest;
+        metadata: Record<string, unknown>;
+    }>): Promise<RunHandle<TRequest>>;
+    spawnDetached(params?: Partial<{
+        runId: string;
+        parentRunId: string;
+        conversationId: string;
+        agentSpec: AgentSpec;
+        request: TRequest;
+        metadata: Record<string, unknown>;
+    }>): Promise<RunHandle<TRequest>>;
+    publish(event: RuntimeEvent, seq?: number): void;
+    persist(event: RuntimeEvent, eventId?: string): Promise<void>;
+    getRegisteredRuns(): Promise<RunRecord$1[]>;
+    restore(): void;
+}
+/**
+ * RunSupervisor 一站式测试夹具。
+ *
+ * 中文备注：
+ * - 只使用 linnkit package 内部 port，不依赖具体 host；
+ * - 适合协议测试、外部接入方测试、Quickstart/CLI 的最小 run 验证。
+ */
+declare function createRunSupervisorHarness<TRequest extends RunRequestSnapshot = RunRequestSnapshot>(options?: Partial<{
+    executionId: string;
+    now: () => number;
+    runIdFactory: () => string;
+    executor: RunExecutorPort<TRequest>;
+}>): RunSupervisorHarness<TRequest>;
+
+type PersistedEvent = PersistedEvent$1;
+type RunCost = RunCost$1;
+type RunRecord = RunRecord$2;
+type RunOutcome = RunOutcome$1;
+type TelemetryEvent = TelemetryEvent$2;
+type RunInvariantId = 'I1_FINAL_STATUS' | 'I2_CHILDREN_COST_TOTAL' | 'I3_TOOL_CALL_OUTPUT_PAIR' | 'I4_LLM_MODEL_SELECT_AUDIT' | 'I5_CANCEL_AUDIT' | 'I6_EVENT_RUN_CONTEXT' | 'I7_PERSISTED_EVENT_ORDER' | 'I8_NO_ACTION_EVENT' | 'I9_CANCEL_SIGNAL_STATUS' | 'I10_TELEMETRY_RUN_REGISTERED' | 'I11_COST_NON_NEGATIVE' | 'I12_AUDIT_RUN_REGISTERED' | 'I13_WAIT_USER_STATUS' | 'I14_DETACHED_TERMINAL_OUTCOME' | 'I15_DRAIN_NO_INFLIGHT';
+interface RunInvariantFailure {
+    id: RunInvariantId;
+    title: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+interface RunInvariantReport {
+    ok: boolean;
+    failures: RunInvariantFailure[];
+}
+interface RunInvariantContext {
+    rootRunId: string;
+    runRecords: readonly RunRecord[];
+    events?: readonly RuntimeEvent[];
+    persistedEvents?: readonly PersistedEvent[];
+    telemetryEvents?: readonly TelemetryEvent[];
+    auditEnvelopes?: readonly AuditEnvelope[];
+    terminalOutcomes?: readonly RunOutcome[];
+    inFlightRunIds?: readonly string[];
+    signal?: AbortSignal;
+    getCost?: (runId: string) => RunCost | Promise<RunCost>;
+}
+interface ValidateRunInvariantsOptions {
+    enabled?: readonly RunInvariantId[];
+    disabled?: readonly RunInvariantId[];
+    /**
+     * 中文备注：
+     * N-3.B.0 只给同步 child-run 透传 runId，并未正式注册 child RunRecord。
+     * 默认严格校验会暴露这个缺口；过渡测试可显式允许 parentRunId 场景下的未注册 child telemetry。
+     */
+    allowUnregisteredChildTelemetry?: boolean;
+}
+
+declare function validateRunInvariants(context: RunInvariantContext, options?: ValidateRunInvariantsOptions): Promise<RunInvariantReport>;
+declare function assertRunInvariants(report: RunInvariantReport): void;
+
+interface MockTokenizerPortOptions {
+    /** 每段 text 固定返回的 token 数，默认 10。 */
+    tokensPerText?: number;
+    /** 每条 message 固定返回的 token 数，默认 50。 */
+    tokensPerMessage?: number;
+    /** 自定义 text 估算逻辑，优先级高于 tokensPerText。 */
+    estimateText?: (text: string, modelId?: string) => number;
+    /** 自定义 message 估算逻辑，优先级高于 tokensPerMessage。 */
+    estimateMessage?: (message: LlmRequestMessage, modelId?: string) => number;
+}
+declare function createMockTokenizerPort(options?: MockTokenizerPortOptions): TokenizerPort;
+
+type ToolContextCompatibilityFields = ToolContextCompatibilityFields$1;
+type ToolExecutionContext = ToolExecutionContext$1;
+type ToolContextPatch = ToolContextPatch$1;
+type ToolContextFixture = ToolExecutionContext & ToolContextCompatibilityFields & Record<string, unknown>;
+interface ToolContextFixtureOptions {
+    conversationId?: string;
+    turnId?: string;
+    historyEvents?: RuntimeEvent[];
+    workingHistoryEvents?: RuntimeEvent[];
+    persistedHistoryEvents?: RuntimeEvent[];
+    patch?: ToolContextPatch;
+}
+declare function createToolContextFixture(options?: ToolContextFixtureOptions): ToolContextFixture;
+
+export { type CollectingAuditPortHarness, type ContextPolicyInvariantContext, type ContextPolicyInvariantFailure, type ContextPolicyInvariantId, type ContextPolicyInvariantReport, type ContextPolicyInvariantValidator, type MockTelemetryPortHarness, type MockTokenizerPortOptions, type ReplayHarness, type RunInvariantContext, type RunInvariantFailure, type RunInvariantId, type RunInvariantReport, type RunSupervisorHarness, type ScriptedAiEngineHarness, type ScriptedAiEngineHarnessOptions, type ScriptedLlmCall, type ScriptedLlmTurn, type ScriptedToolCall, type TelemetryUsageTotal, type ToolContextFixture, type ToolContextFixtureOptions, type ValidateContextPolicyInvariantsOptions, type ValidateRunInvariantsOptions, assertContextPolicyInvariants, assertRunInvariants, assertions, createCollectingAuditPort, createMockTelemetryPort, createMockTokenizerPort, createReplayHarness, createRunSupervisorHarness, createScriptedAiEngineHarness, createToolContextFixture, expectFinalStepForcedTools, expectMessagesContainText, expectMessagesContainToolResult, expectRunEndedWithFinalAnswer, expectToolOutputFedBackToHistory, validateContextPolicyInvariants, validateRunInvariants };