@linnlabs/linnkit 0.8.0

package/dist/defaultGraphExecutor-BIjJj7WF.d.cts

@@ -0,0 +1,624 @@
+import { a as EventStore, P as PersistedEvent, E as EventRangeOptions, m as RunRegistryStore, l as RunRecord, L as ListRunsFilter, n as RunRequestSnapshot, b as EventBus, f as RunCostCollector, h as RunHandle, k as RunObserveFilter, C as CancelOpts, R as RunAwaitingUserPatch, j as RunMeta } from './runHandle-D3gPsD7B.cjs';
+import { p as AgentSpecSystemReminderPolicy, t as AgentSpecToolObservationGovernancePolicy, a as AgentSpec } from './agentSpec-EkmviZjy.cjs';
+import { e as RuntimeEvent } from './todo-B1PmDlp3.cjs';
+import { A as AgentAiEngine, b as AuditPort } from './audit-LeOrm2hX.cjs';
+import { A as AgentInvocationRequest } from './agent-invocation-BHcNfrBV.cjs';
+import { A as AnyAgentEvent } from './agentEvents-DEB7Fy_J.cjs';
+import { T as ToolCall, c as LlmRetryConfig, a as LlmRequestMessage, L as LlmCallOptions, e as ToolCallExtraContent } from './ai-engine.types-BpeU_XQG.cjs';
+import { T as ToolExecutionContext } from './toolContracts-CLkQmhTG.cjs';
+import { h as ToolRuntimePort, O as ObservationPreviewPort } from './ports-DaatKJXp.cjs';
+
+type NormalizedLlmUsage = {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+};
+type LLMTelemetryContext = {
+    /**
+     * 预留：用于业务侧注入“聚合维度”。
+     *
+     * 中文备注：
+     * - 该字段不进入模型上下文、不落库，仅用于本地统计/审计聚合；
+     * - 建议只放稳定标识（如 conversationId/turnId/runId 等），避免塞入大对象。
+     */
+    scope?: {
+        conversationId?: string;
+        turnId?: string;
+        runId?: string;
+        stepId?: string;
+        stepIndex?: number;
+    };
+};
+type LlmCallTelemetry = {
+    modelId: string;
+    stream: boolean;
+    startedAt: number;
+    durationMs: number;
+    usage?: NormalizedLlmUsage;
+};
+declare function withLLMTelemetryContext<T>(ctx: LLMTelemetryContext, fn: () => Promise<T>): Promise<{
+    value: T;
+    calls: LlmCallTelemetry[];
+}>;
+
+declare const TELEMETRY_EVENT_KINDS: readonly ["llm_call", "tool_call", "graph_node", "run_lifecycle"];
+type TelemetryEventKind = (typeof TELEMETRY_EVENT_KINDS)[number];
+
+type TelemetryScope = {
+    conversationId?: string;
+    runId?: string;
+    parentRunId?: string;
+    turnId?: string;
+    stepId?: string;
+};
+type TelemetryEvent = {
+    kind: Extract<TelemetryEventKind, 'llm_call'>;
+    modelId: string;
+    stream: boolean;
+    durationMs: number;
+    usage?: NormalizedLlmUsage;
+    scope: TelemetryScope;
+} | {
+    kind: Extract<TelemetryEventKind, 'tool_call'>;
+    toolName: string;
+    durationMs: number;
+    ok: boolean;
+    errorCode?: string;
+    scope: TelemetryScope;
+} | {
+    kind: Extract<TelemetryEventKind, 'graph_node'>;
+    nodeId: string;
+    durationMs: number;
+    scope: TelemetryScope;
+} | {
+    kind: Extract<TelemetryEventKind, 'run_lifecycle'>;
+    runId: string;
+    phase: 'spawned' | 'completed' | 'failed' | 'cancelled';
+    scope: TelemetryScope;
+};
+interface TelemetryPort {
+    emit(event: TelemetryEvent): void;
+    flush?(): Promise<void>;
+}
+
+/**
+ * ToolContext patch 的最小合同
+ *
+ * 中文备注：
+ * - 这里表达的是“宿主/产品层希望追加到 ToolContext 上的增量字段”；
+ * - 它不是完整 ToolContext，也不承诺 runtime-owned capability；
+ * - 迁移期仍允许任意键，但调用方必须接受 runtime reserved keys 会被过滤。
+ */
+type ToolContextPatch = Record<string, unknown>;
+
+/**
+ * @file src/agent/runtime-kernel/llm/policies/types.ts
+ *
+ * @description
+ * LLM Policy 是对“供应商/模型组合差异”的封装。
+ * 主链路只调用 PolicyEngine，不再内联 provider-specific 逻辑。
+ */
+type LLMPolicyMatchContext = {
+    /** 逻辑模型 ID（如 google/gemini-3-pro-preview） */
+    modelId?: string;
+    /** 供应商/网关的 base url（如 https://openrouter.ai/api/v1） */
+    apiBase?: string;
+    /** 实际请求体中的 model 字段（如 google/gemini-3-pro-preview） */
+    requestModelName?: string;
+};
+type LLMPolicyRequestContext = LLMPolicyMatchContext & {
+    endpoint: string;
+    requestData: unknown;
+    headers?: Record<string, string>;
+};
+type LLMPolicyResponseContext = LLMPolicyMatchContext & {
+    endpoint: string;
+    responseData: unknown;
+};
+type LLMPolicyErrorDecision = {
+    action: 'none';
+} | {
+    action: 'retry';
+    delayMs?: number;
+} | {
+    action: 'switch_model';
+    reason: string;
+};
+interface LLMPolicy {
+    /** 名称仅用于日志/调试 */
+    name: string;
+    /** 是否匹配当前请求上下文 */
+    match(ctx: LLMPolicyMatchContext): boolean;
+    /** 发送前：可修改 requestData / headers（必须保持幂等） */
+    beforeRequest?(ctx: LLMPolicyRequestContext): {
+        requestData?: unknown;
+        headers?: Record<string, string>;
+    };
+    /** 收到后（非流式）：可修改 responseData（必须保持幂等） */
+    afterResponse?(ctx: LLMPolicyResponseContext): {
+        responseData?: unknown;
+    };
+    /** 错误处理：给主链路一个“是否需要切模型/重试”的建议 */
+    onError?(error: Error, ctx: LLMPolicyMatchContext): LLMPolicyErrorDecision;
+}
+
+/**
+ * @file src/agent/runtime-kernel/llm/modelCatalog.ts
+ *
+ * @description
+ * Agent runtime 对“模型目录”的最小协议定义。
+ * runtime-kernel 只依赖这些查询能力，不直接依赖 app 的 model-registry 实现。
+ */
+interface ModelCatalogEntry {
+    id: string;
+    enabled?: boolean;
+    api_key?: string;
+    api_base?: string;
+    billing_mode?: 'byok' | 'cloud';
+    /**
+     * 是否允许客户端侧重试。
+     *
+     * 说明：
+     * - runtime-kernel 会基于该字段与 billing_mode 决定重试策略；
+     * - 该字段来自上层 model-registry（对齐 `src/model-registry/contracts.ts`），避免在 runtime 侧出现类型漂移。
+     */
+    enable_client_retry?: boolean;
+    model_name?: string;
+    provider?: string;
+    capabilities?: readonly string[];
+    ui_visibility?: readonly string[];
+}
+interface ModelCatalogLike {
+    getModelById(id: string): ModelCatalogEntry | undefined;
+    getModelsByCapability(capability: string): ModelCatalogEntry[];
+    getModelsByUIVisibility(visibility: string): ModelCatalogEntry[];
+}
+
+interface ModelResolverOptions {
+    fallbackModelPreferredOrder?: readonly string[];
+    modelCatalog?: ModelCatalogLike;
+}
+interface ModelResolverLike {
+    resolveModelId(requestedModelId?: string): string;
+    pickFallbackChatModel(excludedModelIds: Set<string>): string | null;
+}
+/**
+ * 模型解析职责单独收口，避免 caller / executor stage 混入 registry 选模细节。
+ */
+declare class ModelResolver implements ModelResolverLike {
+    private readonly fallbackModelPreferredOrder;
+    private readonly modelCatalog;
+    constructor(options?: ModelResolverOptions);
+    resolveModelId(requestedModelId?: string): string;
+    /**
+     * 选模规则（严格、可解释）：
+     * - “默认聊天模型”应来自主对话下拉（ui_visibility: 'chat'），而不是“任何具备 chat capability 的模型”。
+     *
+     * 根因说明：
+     * - default_models.json 中存在 mock-chat（capabilities: ['chat']，但 ui_visibility 是 'chat1'）；
+     * - 若按 capability='chat' 取第一个，会导致内部流程（如 deep_search 子 Agent）默认落到 mock 模型，
+     *   从而无法产生 tool_calls / final_answer（只会 yield thought）。
+     */
+    private getDefaultChatModel;
+    /**
+     * 选择一个可用的“策略切模备用聊天模型”：
+     * - 必须具备 chat 能力
+     * - 必须已解析到 api_key（否则必然失败）
+     * - 尽量避开 openrouter（减少被路由到受限上游的概率）
+     */
+    pickFallbackChatModel(excludedModelIds: Set<string>): string | null;
+}
+
+interface LlmCallerOptions {
+    maxRetries?: number;
+    enableEmptyResponseRetry?: boolean;
+    retryDelayMs?: number;
+    fallbackModelPreferredOrder?: readonly string[];
+    modelResolver?: ModelResolverLike;
+    modelCatalog?: ModelCatalogLike;
+    policyEngine?: {
+        decideOnError(error: Error, ctx: LLMPolicyMatchContext): LLMPolicyErrorDecision;
+    };
+    aiEngine: AgentAiEngine;
+}
+
+type LlmCallResult = string | {
+    content: string;
+    tool_calls?: ToolCall[];
+    reasoning_details?: unknown[];
+    usage?: unknown;
+};
+
+/**
+ * @file src/agent/runtime-kernel/llm/caller.ts
+ *
+ * @brief LLM 调用器 - 统一管理 LLM 调用、流式适配与重试编排
+ *
+ * @description
+ * 这个文件只保留 orchestrator 职责：
+ * - 构造依赖；
+ * - 暴露 call / callStream / callWithRetries 公共方法；
+ * - 把具体实现委托给 request-builder / streaming-adapter / retry-fallback 等模块。
+ */
+
+/**
+ * LLM 调用器。
+ *
+ * 中文备注：
+ * - 具体策略实现拆到同目录小模块，避免 caller.ts 再次膨胀；
+ * - public method 签名保持原样，保护现有 host / testkit 调用方。
+ */
+declare class LlmCaller {
+    private readonly deps;
+    private readonly modelResolver;
+    constructor(options?: Partial<LlmRetryConfig> | LlmCallerOptions);
+    /**
+     * 非流式 LLM 调用。
+     */
+    call(modelId: string, messages: LlmRequestMessage[], options?: LlmCallOptions, signal?: AbortSignal): Promise<LlmCallResult>;
+    /**
+     * 流式 LLM 调用。
+     */
+    callStream(modelId: string, messages: LlmRequestMessage[], options: LlmCallOptions | undefined, eventHandler: (event: AnyAgentEvent) => void, signal?: AbortSignal): Promise<LlmCallResult>;
+    /**
+     * 带智能重试和模型降级的 LLM 调用。
+     */
+    callWithRetries(modelId: string, messages: LlmRequestMessage[], options?: LlmCallOptions, eventHandler?: (event: AnyAgentEvent) => void, signal?: AbortSignal, onCloudQuotaFallbackApplied?: (fallbackModelId: string) => void, onModelFallbackApplied?: (info: {
+        fromModelId: string;
+        toModelId: string;
+        reason: string;
+        policy: 'policy-switch' | 'cloud-quota';
+    }) => void): Promise<LlmCallResult>;
+    /**
+     * 获取或使用默认模型 ID。
+     */
+    resolveModelId(requestedModelId?: string): string;
+}
+
+interface ExecutorLocalState {
+    stepCount: number;
+    phase?: 'running' | 'force_final_answer' | 'force_tools' | string;
+    maxSteps?: number;
+    remainingSteps?: number;
+    finalStepPolicy?: 'final_answer' | 'force_tools';
+    finalStepForcedTools?: string[];
+    lastStepsHintThreshold?: number;
+    systemReminderPolicy?: AgentSpecSystemReminderPolicy;
+    toolObservationPolicy?: AgentSpecToolObservationGovernancePolicy;
+    contextCheckpointToolName?: string;
+    runLockedModelId?: string;
+}
+interface EngineLocalState extends Record<string, unknown> {
+    conversationId?: string;
+    turnId?: string;
+    request?: Record<string, unknown>;
+    toolContext?: ToolExecutionContext;
+    history?: RuntimeEvent[];
+    newEvents?: RuntimeEvent[];
+    executorLocal?: ExecutorLocalState;
+    pendingToolCalls?: StandardToolCall[];
+    pendingInteractionSpec?: Record<string, unknown>;
+    lastToolResult?: Record<string, unknown>;
+    finalAnswer?: string;
+    answerId?: string;
+    chunkSeq?: number;
+    signal?: AbortSignal;
+    sseSink?: (evt: unknown) => RuntimeEvent[] | void;
+    summarizationCallbacks?: {
+        onSummarizationStart?: () => void;
+        onSummarizationEnd?: (summaryInfo: unknown) => void;
+    };
+}
+declare const ENGINE_STATE_SCHEMA_VERSION = 1;
+interface EngineState {
+    nodeId: string;
+    /**
+     * 顶层 schema version，供持久化后端在不解读 local 结构时也能快速判断版本。
+     *
+     * 当前 save 路径会统一写入该字段；类型先保持向后兼容，直到旧测试/fixture 全部收敛。
+     */
+    schemaVersion?: number;
+    local?: EngineLocalState;
+}
+interface NodeResult {
+    kind: 'route' | 'yield' | 'pause';
+    nextNodeId?: string;
+    events?: RuntimeEvent[];
+}
+interface GraphNode {
+    id: string;
+    run(state: EngineState): Promise<NodeResult>;
+}
+interface StandardToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+    extra_content?: ToolCallExtraContent;
+}
+
+/**
+ * @file checkpointer/base.ts
+ * @description Engine-state Checkpointer 接口定义。
+ *
+ * ## 术语：这里说的 "Checkpointer" 是哪个 checkpoint？
+ *
+ * 在 agent 生态里，"checkpoint" 是个被严重重载的词。这个接口指的是
+ * **graph engine 的执行状态快照**——也就是 `EngineState`：
+ *
+ *   - `nodeId`: 图执行当前停在哪个节点
+ *   - `pendingToolCalls`: 已发出还未回收的 tool call
+ *   - `executorLocal.stepCount`: 循环步数计数
+ *   - `local`: 节点间共享的中间字典（含 history、checkpointCount 等）
+ *
+ * 这是 **执行控制层** 的概念：让一次 run 在被打断后能从断点恢复继续推理，
+ * 让宿主能查询"我现在停在哪个节点、还欠几个 tool call"。
+ *
+ * ### 这个 Checkpointer **不是**：
+ *
+ * - **不是** 应用层的"对话总结 / 上下文裁剪 checkpoint"。那是上下文工程
+ *   领域的概念，通常由宿主自己实现成一个 LLM tool（让模型主动写阶段总结，
+ *   下一轮上下文构建时把摘要点之前的旧消息从 LLM context window 里裁掉）。
+ *   那种产出本质上是一个 RuntimeEvent，落在宿主的 EventStore 里，跟本接口
+ *   毫无关系。
+ *
+ * - **不是** RuntimeEvent 持久化。事件流的持久化由 `EventStore` 接口负责。
+ *
+ * - **不是** Run 元数据持久化。Run 注册由 `RunRegistryStore` 负责。
+ *
+ * 名字相同语义不同，是历史遗留。如果你在文档里同时看到 "checkpoint"，
+ * 请按上下文区分：本接口语境下的 checkpoint 永远指 EngineState 快照。
+ */
+
+type CheckpointMeta = {
+    conversationId: string;
+    schemaVersion: number;
+    savedAt: number;
+    currentNode?: string;
+    iterations?: number;
+    hasPendingToolCalls: boolean;
+};
+type CheckpointListFilter = {
+    savedAfter?: number;
+    limit?: number;
+    cursor?: string;
+};
+type CheckpointSummary = CheckpointMeta;
+interface Checkpointer {
+    load(conversationId: string): Promise<EngineState | null>;
+    save(conversationId: string, state: EngineState): Promise<void>;
+    clear(conversationId: string): Promise<void>;
+    peekMeta?(conversationId: string): Promise<CheckpointMeta | null>;
+    list?(filter?: CheckpointListFilter): Promise<CheckpointSummary[]>;
+}
+declare function summarizeCheckpoint(conversationId: string, state: EngineState, savedAt: number): CheckpointSummary;
+
+interface GraphExecutorConfig {
+    maxSteps?: number;
+    maxCheckpoints?: number;
+    /**
+     * 可选：宿主提供的 TelemetryPort 实现。
+     * 不传时使用 noopTelemetry（observability 默认关闭，零业务影响）。
+     */
+    telemetryPort?: TelemetryPort;
+}
+declare class GraphExecutor {
+    private readonly checkpointer;
+    private nodes;
+    private ephemeralLocals;
+    private readonly config;
+    private readonly telemetryPort;
+    constructor(checkpointer: Checkpointer, config?: GraphExecutorConfig);
+    registerNode(node: GraphNode): void;
+    peekCheckpoint(conversationId: string): Promise<EngineState | null>;
+    private sanitize;
+    prime(conversationId: string, local: Record<string, unknown>, nodeId?: string): Promise<void>;
+    setNode(conversationId: string, nodeId: string, localPatch?: Record<string, unknown>): Promise<void>;
+    runUntilYield(conversationId: string): Promise<{
+        events: RuntimeEvent[];
+        checkpoint: EngineState;
+        stepCount: number;
+    }>;
+    private runUntilYieldInternal;
+}
+
+declare class MemoryEventStore implements EventStore {
+    private readonly store;
+    append(conversationId: string, event: PersistedEvent): Promise<void>;
+    range(conversationId: string, opts?: EventRangeOptions): Promise<PersistedEvent[]>;
+    latestEventId(conversationId: string): Promise<string | null>;
+    truncate(conversationId: string, opts: {
+        beforeEventId?: string;
+        beforeMs?: number;
+    }): Promise<void>;
+}
+
+declare class MemoryRunRegistryStore implements RunRegistryStore {
+    private readonly store;
+    save(record: RunRecord): Promise<void>;
+    load(runId: string): Promise<RunRecord | null>;
+    list(filter?: ListRunsFilter): Promise<{
+        runs: RunRecord[];
+        nextCursor?: string;
+    }>;
+    delete(runId: string): Promise<void>;
+}
+
+type RunTerminalStatus = Extract<RunRecord['status'], 'completed' | 'failed' | 'cancelled'>;
+type RunTerminalError = {
+    errorCode: string;
+    message: string;
+    recoverable: boolean;
+};
+interface RunOutcome {
+    runId: string;
+    status: RunTerminalStatus;
+    completedAt: number;
+    currentNode?: string;
+    iterationsUsed?: number;
+    error?: RunTerminalError;
+    metadata?: Record<string, unknown>;
+}
+interface RunSnapshot extends RunMeta {
+    metadata?: Record<string, unknown>;
+}
+interface RunTerminalEvent {
+    runId: string;
+    status: RunTerminalStatus;
+    outcome: RunOutcome;
+}
+interface RunWaitForTerminalOptions {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+interface FindActiveByConversationOptions {
+    includeChildren?: boolean;
+    agentSpecId?: string;
+}
+interface RunExecutionContext<TRequest extends RunRequestSnapshot = RunRequestSnapshot> {
+    runId: string;
+    parentRunId?: string;
+    conversationId: string;
+    agentSpec: AgentSpec;
+    request: TRequest;
+    signal: AbortSignal;
+    eventBus: EventBus;
+    eventStore: EventStore;
+    costCollector: RunCostCollector;
+    query?: string;
+    contextFences?: readonly unknown[];
+    wakeSource?: string;
+    ephemeral?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+interface RunExecutorPort<TRequest extends RunRequestSnapshot = RunRequestSnapshot> {
+    execute(context: RunExecutionContext<TRequest>): Promise<RunOutcome | void>;
+}
+interface RunRegistrationSpec<TRequest extends RunRequestSnapshot = RunRequestSnapshot> {
+    runId?: string;
+    parentRunId?: string;
+    parentSignal?: AbortSignal;
+    conversationId: string;
+    agentSpec: AgentSpec;
+    request: TRequest;
+    eventBus: EventBus;
+    eventStore: EventStore;
+    costCollector: RunCostCollector;
+    iterationBudget?: RunRecord['iterationBudget'];
+    query?: string;
+    contextFences?: readonly unknown[];
+    wakeSource?: string;
+    ephemeral?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+interface RunSupervisor<TRequest extends RunRequestSnapshot = RunRequestSnapshot> {
+    registerRun(spec: RunRegistrationSpec<TRequest>): Promise<RunHandle<TRequest>>;
+    spawnDetached(spec: RunRegistrationSpec<TRequest>): Promise<RunHandle<TRequest>>;
+    observeRun(runId: string, filter?: RunObserveFilter): AsyncIterable<RuntimeEvent>;
+    cancel(runId: string, opts: CancelOpts): Promise<void>;
+    markAwaitingUser(runId: string, patch?: RunAwaitingUserPatch): Promise<void>;
+    list(filter?: ListRunsFilter): Promise<{
+        runs: RunMeta[];
+        nextCursor?: string;
+    }>;
+    peek(runId: string): Promise<RunMeta | null>;
+    waitForTerminal(runId: string, opts?: RunWaitForTerminalOptions): Promise<RunOutcome>;
+    findActiveByConversation(conversationId: string, opts?: FindActiveByConversationOptions): Promise<RunSnapshot[]>;
+    drain(opts?: RunWaitForTerminalOptions): Promise<RunOutcome[]>;
+    recoverOnBoot(reason?: string): Promise<RunOutcome[]>;
+    pause(runId: string, reason?: string): Promise<never>;
+    resume(runId: string): Promise<never>;
+    runTree(rootRunId: string): Promise<never>;
+    handleFailure(runId: string, error: unknown): Promise<never>;
+}
+interface DefaultRunSupervisorOptions<TRequest extends RunRequestSnapshot = RunRequestSnapshot> {
+    registryStore: RunRegistryStore;
+    auditPort?: AuditPort;
+    executor?: RunExecutorPort<TRequest>;
+    runIdFactory?: () => string;
+    now?: () => number;
+}
+declare class DefaultRunSupervisor<TRequest extends RunRequestSnapshot = RunRequestSnapshot> implements RunSupervisor<TRequest> {
+    private readonly registryStore;
+    private readonly auditPort?;
+    private readonly executor?;
+    private readonly runIdFactory;
+    private readonly now;
+    private readonly handles;
+    private readonly controllers;
+    private readonly inFlight;
+    private readonly terminalOutcomes;
+    private readonly terminalWaiters;
+    constructor(options: DefaultRunSupervisorOptions<TRequest>);
+    registerRun(spec: RunRegistrationSpec<TRequest>): Promise<RunHandle<TRequest>>;
+    spawnDetached(spec: RunRegistrationSpec<TRequest>): Promise<RunHandle<TRequest>>;
+    observeRun(runId: string, filter?: RunObserveFilter): AsyncIterable<RuntimeEvent>;
+    cancel(runId: string, opts: CancelOpts): Promise<void>;
+    markAwaitingUser(runId: string, patch?: RunAwaitingUserPatch): Promise<void>;
+    list(filter?: ListRunsFilter): Promise<{
+        runs: RunMeta[];
+        nextCursor?: string;
+    }>;
+    peek(runId: string): Promise<RunMeta | null>;
+    waitForTerminal(runId: string, opts?: RunWaitForTerminalOptions): Promise<RunOutcome>;
+    findActiveByConversation(conversationId: string, opts?: FindActiveByConversationOptions): Promise<RunSnapshot[]>;
+    drain(opts?: RunWaitForTerminalOptions): Promise<RunOutcome[]>;
+    recoverOnBoot(reason?: string): Promise<RunOutcome[]>;
+    pause(_runId: string, _reason?: string): Promise<never>;
+    resume(_runId: string): Promise<never>;
+    runTree(_rootRunId: string): Promise<never>;
+    handleFailure(_runId: string, _error: unknown): Promise<never>;
+    private executeDetachedRun;
+    private persistExecutorOutcome;
+    private getTerminalWaiters;
+    private notifyTerminalWaiters;
+    private getHandle;
+    private watchAwaitingUserEvents;
+    private toRunMeta;
+}
+
+interface GraphLoopLlmNodeFactoryParams {
+    llmCaller: LlmCaller;
+    toolRuntime: ToolRuntimePort;
+}
+interface GraphLoopHarnessOptions {
+    conversationId: string;
+    turnId: string;
+    query: string;
+    request: AgentInvocationRequest;
+    toolContext: ToolExecutionContext;
+    llmCaller: LlmCaller;
+    toolRuntime: ToolRuntimePort;
+    observationPreview: ObservationPreviewPort;
+    createLlmNode: (params: GraphLoopLlmNodeFactoryParams) => GraphNode;
+    executorLocal?: ExecutorLocalState;
+    history?: RuntimeEvent[];
+    maxSteps?: number;
+    signal?: AbortSignal;
+    auditPort?: AuditPort;
+    telemetryPort?: TelemetryPort;
+    sseSink?: (evt: unknown) => RuntimeEvent[] | void;
+}
+interface GraphLoopHarnessRunResult {
+    checkpointNodeId: string;
+    stepCount: number;
+}
+interface GraphLoopHarness {
+    run(): Promise<GraphLoopHarnessRunResult>;
+}
+declare function createGraphLoopHarness(options: GraphLoopHarnessOptions): GraphLoopHarness;
+
+interface DefaultGraphExecutorOptions {
+    llmNode: GraphNode;
+    toolRuntime: ToolRuntimePort;
+    observationPreview: ObservationPreviewPort;
+    maxSteps?: number;
+    checkpointer?: Checkpointer;
+    auditPort?: AuditPort;
+    telemetryPort?: TelemetryPort;
+}
+declare function createDefaultGraphExecutor(options: DefaultGraphExecutorOptions): GraphExecutor;
+
+export { type RunTerminalError as A, type RunTerminalEvent as B, type Checkpointer as C, DefaultRunSupervisor as D, type ExecutorLocalState as E, type FindActiveByConversationOptions as F, type GraphNode as G, type RunTerminalStatus as H, type RunWaitForTerminalOptions as I, TELEMETRY_EVENT_KINDS as J, type TelemetryEvent as K, type LlmCallTelemetry as L, type ModelCatalogEntry as M, type NodeResult as N, type TelemetryScope as O, type DefaultGraphExecutorOptions as P, type GraphLoopHarness as Q, type RunExecutionContext as R, type StandardToolCall as S, type TelemetryPort as T, type GraphLoopHarnessOptions as U, type GraphLoopHarnessRunResult as V, type GraphLoopLlmNodeFactoryParams as W, createDefaultGraphExecutor as X, createGraphLoopHarness as Y, type LLMPolicy as a, type LLMPolicyRequestContext as b, type LLMPolicyResponseContext as c, type LLMPolicyMatchContext as d, type LLMPolicyErrorDecision as e, LlmCaller as f, type ModelCatalogLike as g, ModelResolver as h, type ModelResolverLike as i, type EngineState as j, type CheckpointMeta as k, type CheckpointListFilter as l, type CheckpointSummary as m, ENGINE_STATE_SCHEMA_VERSION as n, GraphExecutor as o, MemoryEventStore as p, type ToolContextPatch as q, type DefaultRunSupervisorOptions as r, summarizeCheckpoint as s, MemoryRunRegistryStore as t, type RunExecutorPort as u, type RunOutcome as v, withLLMTelemetryContext as w, type RunRegistrationSpec as x, type RunSnapshot as y, type RunSupervisor as z };