@linnlabs/linnkit 0.8.0

package/dist/runAgent-CPj_9e58.d.ts

@@ -0,0 +1,88 @@
+import { A as AgentAiEngine } from './audit-CtcfART1.js';
+import { f as AgentSpecContextPolicyInput, a as AgentSpec } from './agentSpec-EkmviZjy.js';
+import { e as RuntimeEvent } from './todo-B1PmDlp3.js';
+import { B as BaseTool, a as ToolArgs, O as OpenAIToolSchema, T as ToolExecutionContext } from './toolContracts-Blll0241.js';
+import { g as ToolRuntimeDefinition, f as ToolExecutionResult } from './ports-DnLuKfpE.js';
+import { e as RunCost$1 } from './runHandle-CyXvzgzk.js';
+
+interface DefinedAgent {
+    readonly spec: AgentSpec;
+    readonly systemPrompt: string;
+    readonly modelId?: string;
+    readonly tools: readonly BaseTool<ToolArgs, string>[];
+}
+interface DefineAgentInput {
+    id: string;
+    version?: string;
+    description?: string;
+    role?: string;
+    systemPrompt: string;
+    modelId?: string;
+    capabilities?: string[];
+    tools?: readonly BaseTool<ToolArgs, string>[];
+    contextPolicy?: AgentSpecContextPolicyInput;
+    metadata?: Record<string, unknown>;
+}
+interface LinnkitQuickstartConfig {
+    agents: readonly DefinedAgent[];
+    llm: AgentAiEngine | (() => AgentAiEngine | Promise<AgentAiEngine>);
+    defaultModelId?: string;
+}
+interface RunAgentOptions {
+    input: string;
+    llm: AgentAiEngine;
+    modelId?: string;
+    conversationId?: string;
+    runId?: string;
+    signal?: AbortSignal;
+    /**
+     * Quickstart 事件回调。
+     *
+     * 中文备注：CLI 用它打印实时输出；生产 host 应直接接入 EventBus / EventStore。
+     */
+    onEvent?: (event: RuntimeEvent) => void | Promise<void>;
+}
+interface RunAgentResult {
+    runId: string;
+    finalAnswer: string;
+    events: RuntimeEvent[];
+    cost: RunCost;
+    contextTrace?: unknown;
+}
+type RunCost = RunCost$1;
+interface QuickstartToolRuntime {
+    getToolSchemas(toolNames?: string[]): OpenAIToolSchema[];
+    getToolDefinition(toolName: string): ToolRuntimeDefinition | undefined;
+    getDisplayOptions(toolName: string): BaseTool<ToolArgs, string>['displayOptions'] | undefined;
+    executeTool(toolName: string, args: ToolArgs, context: ToolExecutionContext): Promise<ToolExecutionResult>;
+}
+
+/**
+ * Quickstart 级 Agent 构造器。
+ *
+ * 中文备注：
+ * - 这里不是新的业务 registry，只是把 AgentSpec 的必填项压成低门槛入口；
+ * - 生产 host 仍可直接维护自己的 AgentDefinition -> AgentSpec 映射。
+ */
+declare function defineAgent(input: DefineAgentInput): DefinedAgent;
+
+/**
+ * Quickstart 配置构造器。
+ *
+ * 中文备注：
+ * - 只做轻量运行时校验，避免 CLI 加载坏 config 后给出晦涩堆栈；
+ * - 不接管生产 host 的完整配置系统。
+ */
+declare function defineConfig(config: LinnkitQuickstartConfig): LinnkitQuickstartConfig;
+declare function resolveConfiguredLlm(config: LinnkitQuickstartConfig): Promise<AgentAiEngine>;
+
+/**
+ * 运行一个 quickstart agent。
+ *
+ * 中文备注：
+ * - 这个 helper 用于“npm install 后立即跑通”的最小体验；
+ * - 生产 host 仍应自行装配 EventStore / ToolRuntime / ContextManager / RunSupervisor。
+ */
+declare function runAgent(agent: DefinedAgent, options: RunAgentOptions): Promise<RunAgentResult>;
+
+export { type DefineAgentInput as D, type LinnkitQuickstartConfig as L, type QuickstartToolRuntime as Q, type RunAgentOptions as R, type DefinedAgent as a, type RunAgentResult as b, defineConfig as c, defineAgent as d, runAgent as e, resolveConfiguredLlm as r };

package/dist/runAgent-HYKlXbVr.d.cts

@@ -0,0 +1,88 @@
+import { A as AgentAiEngine } from './audit-LeOrm2hX.cjs';
+import { f as AgentSpecContextPolicyInput, a as AgentSpec } from './agentSpec-EkmviZjy.cjs';
+import { e as RuntimeEvent } from './todo-B1PmDlp3.cjs';
+import { B as BaseTool, a as ToolArgs, O as OpenAIToolSchema, T as ToolExecutionContext } from './toolContracts-CLkQmhTG.cjs';
+import { g as ToolRuntimeDefinition, f as ToolExecutionResult } from './ports-DaatKJXp.cjs';
+import { e as RunCost$1 } from './runHandle-D3gPsD7B.cjs';
+
+interface DefinedAgent {
+    readonly spec: AgentSpec;
+    readonly systemPrompt: string;
+    readonly modelId?: string;
+    readonly tools: readonly BaseTool<ToolArgs, string>[];
+}
+interface DefineAgentInput {
+    id: string;
+    version?: string;
+    description?: string;
+    role?: string;
+    systemPrompt: string;
+    modelId?: string;
+    capabilities?: string[];
+    tools?: readonly BaseTool<ToolArgs, string>[];
+    contextPolicy?: AgentSpecContextPolicyInput;
+    metadata?: Record<string, unknown>;
+}
+interface LinnkitQuickstartConfig {
+    agents: readonly DefinedAgent[];
+    llm: AgentAiEngine | (() => AgentAiEngine | Promise<AgentAiEngine>);
+    defaultModelId?: string;
+}
+interface RunAgentOptions {
+    input: string;
+    llm: AgentAiEngine;
+    modelId?: string;
+    conversationId?: string;
+    runId?: string;
+    signal?: AbortSignal;
+    /**
+     * Quickstart 事件回调。
+     *
+     * 中文备注：CLI 用它打印实时输出；生产 host 应直接接入 EventBus / EventStore。
+     */
+    onEvent?: (event: RuntimeEvent) => void | Promise<void>;
+}
+interface RunAgentResult {
+    runId: string;
+    finalAnswer: string;
+    events: RuntimeEvent[];
+    cost: RunCost;
+    contextTrace?: unknown;
+}
+type RunCost = RunCost$1;
+interface QuickstartToolRuntime {
+    getToolSchemas(toolNames?: string[]): OpenAIToolSchema[];
+    getToolDefinition(toolName: string): ToolRuntimeDefinition | undefined;
+    getDisplayOptions(toolName: string): BaseTool<ToolArgs, string>['displayOptions'] | undefined;
+    executeTool(toolName: string, args: ToolArgs, context: ToolExecutionContext): Promise<ToolExecutionResult>;
+}
+
+/**
+ * Quickstart 级 Agent 构造器。
+ *
+ * 中文备注：
+ * - 这里不是新的业务 registry，只是把 AgentSpec 的必填项压成低门槛入口；
+ * - 生产 host 仍可直接维护自己的 AgentDefinition -> AgentSpec 映射。
+ */
+declare function defineAgent(input: DefineAgentInput): DefinedAgent;
+
+/**
+ * Quickstart 配置构造器。
+ *
+ * 中文备注：
+ * - 只做轻量运行时校验，避免 CLI 加载坏 config 后给出晦涩堆栈；
+ * - 不接管生产 host 的完整配置系统。
+ */
+declare function defineConfig(config: LinnkitQuickstartConfig): LinnkitQuickstartConfig;
+declare function resolveConfiguredLlm(config: LinnkitQuickstartConfig): Promise<AgentAiEngine>;
+
+/**
+ * 运行一个 quickstart agent。
+ *
+ * 中文备注：
+ * - 这个 helper 用于“npm install 后立即跑通”的最小体验；
+ * - 生产 host 仍应自行装配 EventStore / ToolRuntime / ContextManager / RunSupervisor。
+ */
+declare function runAgent(agent: DefinedAgent, options: RunAgentOptions): Promise<RunAgentResult>;
+
+export { type DefineAgentInput as D, type LinnkitQuickstartConfig as L, type QuickstartToolRuntime as Q, type RunAgentOptions as R, type DefinedAgent as a, type RunAgentResult as b, defineConfig as c, defineAgent as d, runAgent as e, resolveConfiguredLlm as r };

package/dist/runHandle-CyXvzgzk.d.ts

@@ -0,0 +1,239 @@
+import { a as AgentSpec } from './agentSpec-EkmviZjy.js';
+import { e as RuntimeEvent } from './todo-B1PmDlp3.js';
+import { b as AuditPort } from './audit-CtcfART1.js';
+import { E as EventEnvelope } from './execution-CAIypb41.js';
+
+type PersistedEvent = {
+    eventId: string;
+    timestamp: number;
+    conversationId: string;
+    runId?: string;
+    event: RuntimeEvent;
+};
+type EventRangeOptions = {
+    fromEventId?: string;
+    toEventId?: string;
+    limit?: number;
+};
+interface EventStore {
+    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 function createMonotonicEventIdFactory(nowProvider?: () => number): () => string;
+
+/**
+ * @file src/agent/runtime-kernel/execution/event-bus.ts
+ * @description 内存中的事件总线
+ *
+ * 功能 (What):
+ * - 提供一个中央事件中心，用于发布和订阅 `EventEnvelope` 事件。
+ * - 解耦事件的产生方（如 Runners）和消费方（如持久化、SSE推送）。
+ * - 保证事件处理的逻辑集中化。
+ *
+ * 这是一个简单的内存实现，为每个执行流程（execution）创建一个实例。
+ */
+
+type EventBusEvents = {
+    'event': (envelope: EventEnvelope<RuntimeEvent>) => void;
+    'error': (error: Error) => void;
+    'close': () => void;
+};
+type EventListener = (...args: never[]) => void;
+declare class TypedEventEmitter<TEvents extends Record<string, EventListener>> {
+    private readonly listeners;
+    private maxListeners;
+    on<TEvent extends keyof TEvents>(event: TEvent, listener: TEvents[TEvent]): this;
+    off<TEvent extends keyof TEvents>(event: TEvent, listener: TEvents[TEvent]): this;
+    once<TEvent extends keyof TEvents>(event: TEvent, listener: TEvents[TEvent]): this;
+    emit<TEvent extends keyof TEvents>(event: TEvent, ...args: Parameters<TEvents[TEvent]>): boolean;
+    removeAllListeners<TEvent extends keyof TEvents>(event?: TEvent): this;
+    setMaxListeners(n: number): this;
+    private getListeners;
+}
+/**
+ * 事件总线类
+ *
+ * 为每一次执行（execution）实例化一次，管理该执行生命周期内的所有事件。
+ */
+declare class EventBus extends TypedEventEmitter<EventBusEvents> {
+    readonly executionId: string;
+    constructor(executionId: string);
+    /**
+     * 发布一个事件到总线
+     * @param envelope - 经过序列器包装的事件信封
+     */
+    publish(envelope: EventEnvelope<RuntimeEvent>): void;
+    /**
+     * 关闭总线，清理所有监听器
+     */
+    close(): void;
+}
+
+type RunStatus = 'pending' | 'running' | 'awaiting_user' | 'paused' | 'completed' | 'failed' | 'cancelled';
+type ListRunsFilter = {
+    status?: RunStatus | RunStatus[];
+    parentRunId?: string;
+    agentSpecId?: string;
+    startedAfter?: number;
+    startedBefore?: number;
+    limit?: number;
+    cursor?: string;
+};
+type RunRecord = {
+    runId: string;
+    conversationId: string;
+    parentRunId?: string;
+    agentSpecId?: string;
+    status: RunStatus;
+    currentNode?: string;
+    startedAt: number;
+    updatedAt: number;
+    pausedAt?: number;
+    pauseReason?: string;
+    iterationsUsed?: number;
+    iterationBudget?: {
+        max: number;
+        refundable: boolean;
+    };
+    errorIfAny?: {
+        errorCode: string;
+        message: string;
+        recoverable: boolean;
+    };
+    metadata?: Record<string, unknown>;
+};
+interface RunRegistryStore {
+    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 RunRequestSnapshot = Readonly<object>;
+interface CancelOpts {
+    reason: string;
+    forceCleanup?: boolean;
+    timeout?: number;
+}
+interface RunCost {
+    tokensInput: number;
+    tokensOutput: number;
+    totalCostUsd?: number;
+    latencyMs?: number;
+    childrenTotal?: RunCost;
+}
+interface RunCostCollector {
+    snapshot(runId: string): RunCost | Promise<RunCost>;
+}
+interface RunLifecyclePatch {
+    currentNode?: string;
+    iterationsUsed?: number;
+}
+interface RunAwaitingUserPatch extends RunLifecyclePatch {
+    reason?: string;
+    eventId?: string;
+}
+interface RunFailureInfo {
+    errorCode: string;
+    message: string;
+    recoverable: boolean;
+}
+interface RunMeta {
+    runId: string;
+    parentRunId?: string;
+    agentSpecId?: string;
+    conversationId: string;
+    status: RunStatus;
+    currentNode?: string;
+    startedAt: number;
+    updatedAt: number;
+    pausedAt?: number;
+    pauseReason?: string;
+    iterationsUsed?: number;
+    errorIfAny?: {
+        errorCode: string;
+        message: string;
+        recoverable: boolean;
+    };
+}
+interface RunObserveFilter {
+    /** RuntimeEvent 使用 type 作为主判别字段；保留 kinds 只是为了贴近 N-3 草案措辞。 */
+    types?: RuntimeEvent['type'][];
+    kinds?: RuntimeEvent['type'][];
+    includePersisted?: boolean;
+}
+interface RunHandle<TRequest extends RunRequestSnapshot = RunRequestSnapshot> {
+    readonly runId: string;
+    readonly parentRunId?: string;
+    readonly signal: AbortSignal;
+    spec(): Promise<AgentSpec>;
+    request(): Promise<TRequest>;
+    cancel(opts: CancelOpts): Promise<void>;
+    observe(filter?: RunObserveFilter): AsyncIterable<RuntimeEvent>;
+    cost(): Promise<RunCost>;
+    meta(): Promise<RunMeta>;
+    markRunning(patch?: RunLifecyclePatch): Promise<void>;
+    markAwaitingUser(patch?: RunAwaitingUserPatch): Promise<void>;
+    markCompleted(patch?: RunLifecyclePatch): Promise<void>;
+    markFailed(error: RunFailureInfo, patch?: RunLifecyclePatch): Promise<void>;
+    pause(reason?: string): Promise<never>;
+    resume(): Promise<never>;
+}
+interface DefaultRunHandleOptions<TRequest extends RunRequestSnapshot = RunRequestSnapshot> {
+    runRecord: RunRecord;
+    abortController: AbortController;
+    agentSpec: AgentSpec;
+    request: TRequest;
+    eventBus: EventBus;
+    eventStore: EventStore;
+    costCollector: RunCostCollector;
+    registryStore: RunRegistryStore;
+    auditPort?: AuditPort;
+    onCancelled?: (runId: string, opts: CancelOpts) => void;
+}
+/**
+ * RunHandle 的默认实现只编织现有机制：
+ * - cancel 只触发 AbortController，不改 GraphExecutor；
+ * - observe 只包装 EventBus/EventStore；
+ * - cost 只读取外部注入的 CostCollector。
+ */
+declare class DefaultRunHandle<TRequest extends RunRequestSnapshot = RunRequestSnapshot> implements RunHandle<TRequest> {
+    readonly runId: string;
+    readonly parentRunId?: string;
+    readonly signal: AbortSignal;
+    private runRecord;
+    private readonly abortController;
+    private readonly agentSpecSnapshot;
+    private readonly requestSnapshot;
+    private readonly eventBus;
+    private readonly eventStore;
+    private readonly costCollector;
+    private readonly registryStore;
+    private readonly auditPort;
+    private readonly onCancelled?;
+    constructor(options: DefaultRunHandleOptions<TRequest>);
+    spec(): Promise<AgentSpec>;
+    request(): Promise<TRequest>;
+    cancel(opts: CancelOpts): Promise<void>;
+    observe(filter?: RunObserveFilter): AsyncIterable<RuntimeEvent>;
+    cost(): Promise<RunCost>;
+    meta(): Promise<RunMeta>;
+    markRunning(patch?: RunLifecyclePatch): Promise<void>;
+    markAwaitingUser(patch?: RunAwaitingUserPatch): Promise<void>;
+    markCompleted(patch?: RunLifecyclePatch): Promise<void>;
+    markFailed(error: RunFailureInfo, patch?: RunLifecyclePatch): Promise<void>;
+    pause(_reason?: string): Promise<never>;
+    resume(): Promise<never>;
+    private saveLifecycleStatus;
+}
+declare function runMetaFromRecord(record: RunRecord): RunMeta;
+
+export { type CancelOpts as C, DefaultRunHandle as D, type EventRangeOptions as E, type ListRunsFilter as L, type PersistedEvent as P, type RunAwaitingUserPatch as R, type EventStore as a, EventBus as b, createMonotonicEventIdFactory as c, type DefaultRunHandleOptions as d, type RunCost as e, type RunCostCollector as f, type RunFailureInfo as g, type RunHandle as h, type RunLifecyclePatch as i, type RunMeta as j, type RunObserveFilter as k, type RunRecord as l, type RunRegistryStore as m, type RunRequestSnapshot as n, type RunStatus as o, runMetaFromRecord as r };

package/dist/runHandle-D3gPsD7B.d.cts

@@ -0,0 +1,239 @@
+import { a as AgentSpec } from './agentSpec-EkmviZjy.cjs';
+import { e as RuntimeEvent } from './todo-B1PmDlp3.cjs';
+import { b as AuditPort } from './audit-LeOrm2hX.cjs';
+import { E as EventEnvelope } from './execution-CAIypb41.cjs';
+
+type PersistedEvent = {
+    eventId: string;
+    timestamp: number;
+    conversationId: string;
+    runId?: string;
+    event: RuntimeEvent;
+};
+type EventRangeOptions = {
+    fromEventId?: string;
+    toEventId?: string;
+    limit?: number;
+};
+interface EventStore {
+    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 function createMonotonicEventIdFactory(nowProvider?: () => number): () => string;
+
+/**
+ * @file src/agent/runtime-kernel/execution/event-bus.ts
+ * @description 内存中的事件总线
+ *
+ * 功能 (What):
+ * - 提供一个中央事件中心，用于发布和订阅 `EventEnvelope` 事件。
+ * - 解耦事件的产生方（如 Runners）和消费方（如持久化、SSE推送）。
+ * - 保证事件处理的逻辑集中化。
+ *
+ * 这是一个简单的内存实现，为每个执行流程（execution）创建一个实例。
+ */
+
+type EventBusEvents = {
+    'event': (envelope: EventEnvelope<RuntimeEvent>) => void;
+    'error': (error: Error) => void;
+    'close': () => void;
+};
+type EventListener = (...args: never[]) => void;
+declare class TypedEventEmitter<TEvents extends Record<string, EventListener>> {
+    private readonly listeners;
+    private maxListeners;
+    on<TEvent extends keyof TEvents>(event: TEvent, listener: TEvents[TEvent]): this;
+    off<TEvent extends keyof TEvents>(event: TEvent, listener: TEvents[TEvent]): this;
+    once<TEvent extends keyof TEvents>(event: TEvent, listener: TEvents[TEvent]): this;
+    emit<TEvent extends keyof TEvents>(event: TEvent, ...args: Parameters<TEvents[TEvent]>): boolean;
+    removeAllListeners<TEvent extends keyof TEvents>(event?: TEvent): this;
+    setMaxListeners(n: number): this;
+    private getListeners;
+}
+/**
+ * 事件总线类
+ *
+ * 为每一次执行（execution）实例化一次，管理该执行生命周期内的所有事件。
+ */
+declare class EventBus extends TypedEventEmitter<EventBusEvents> {
+    readonly executionId: string;
+    constructor(executionId: string);
+    /**
+     * 发布一个事件到总线
+     * @param envelope - 经过序列器包装的事件信封
+     */
+    publish(envelope: EventEnvelope<RuntimeEvent>): void;
+    /**
+     * 关闭总线，清理所有监听器
+     */
+    close(): void;
+}
+
+type RunStatus = 'pending' | 'running' | 'awaiting_user' | 'paused' | 'completed' | 'failed' | 'cancelled';
+type ListRunsFilter = {
+    status?: RunStatus | RunStatus[];
+    parentRunId?: string;
+    agentSpecId?: string;
+    startedAfter?: number;
+    startedBefore?: number;
+    limit?: number;
+    cursor?: string;
+};
+type RunRecord = {
+    runId: string;
+    conversationId: string;
+    parentRunId?: string;
+    agentSpecId?: string;
+    status: RunStatus;
+    currentNode?: string;
+    startedAt: number;
+    updatedAt: number;
+    pausedAt?: number;
+    pauseReason?: string;
+    iterationsUsed?: number;
+    iterationBudget?: {
+        max: number;
+        refundable: boolean;
+    };
+    errorIfAny?: {
+        errorCode: string;
+        message: string;
+        recoverable: boolean;
+    };
+    metadata?: Record<string, unknown>;
+};
+interface RunRegistryStore {
+    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 RunRequestSnapshot = Readonly<object>;
+interface CancelOpts {
+    reason: string;
+    forceCleanup?: boolean;
+    timeout?: number;
+}
+interface RunCost {
+    tokensInput: number;
+    tokensOutput: number;
+    totalCostUsd?: number;
+    latencyMs?: number;
+    childrenTotal?: RunCost;
+}
+interface RunCostCollector {
+    snapshot(runId: string): RunCost | Promise<RunCost>;
+}
+interface RunLifecyclePatch {
+    currentNode?: string;
+    iterationsUsed?: number;
+}
+interface RunAwaitingUserPatch extends RunLifecyclePatch {
+    reason?: string;
+    eventId?: string;
+}
+interface RunFailureInfo {
+    errorCode: string;
+    message: string;
+    recoverable: boolean;
+}
+interface RunMeta {
+    runId: string;
+    parentRunId?: string;
+    agentSpecId?: string;
+    conversationId: string;
+    status: RunStatus;
+    currentNode?: string;
+    startedAt: number;
+    updatedAt: number;
+    pausedAt?: number;
+    pauseReason?: string;
+    iterationsUsed?: number;
+    errorIfAny?: {
+        errorCode: string;
+        message: string;
+        recoverable: boolean;
+    };
+}
+interface RunObserveFilter {
+    /** RuntimeEvent 使用 type 作为主判别字段；保留 kinds 只是为了贴近 N-3 草案措辞。 */
+    types?: RuntimeEvent['type'][];
+    kinds?: RuntimeEvent['type'][];
+    includePersisted?: boolean;
+}
+interface RunHandle<TRequest extends RunRequestSnapshot = RunRequestSnapshot> {
+    readonly runId: string;
+    readonly parentRunId?: string;
+    readonly signal: AbortSignal;
+    spec(): Promise<AgentSpec>;
+    request(): Promise<TRequest>;
+    cancel(opts: CancelOpts): Promise<void>;
+    observe(filter?: RunObserveFilter): AsyncIterable<RuntimeEvent>;
+    cost(): Promise<RunCost>;
+    meta(): Promise<RunMeta>;
+    markRunning(patch?: RunLifecyclePatch): Promise<void>;
+    markAwaitingUser(patch?: RunAwaitingUserPatch): Promise<void>;
+    markCompleted(patch?: RunLifecyclePatch): Promise<void>;
+    markFailed(error: RunFailureInfo, patch?: RunLifecyclePatch): Promise<void>;
+    pause(reason?: string): Promise<never>;
+    resume(): Promise<never>;
+}
+interface DefaultRunHandleOptions<TRequest extends RunRequestSnapshot = RunRequestSnapshot> {
+    runRecord: RunRecord;
+    abortController: AbortController;
+    agentSpec: AgentSpec;
+    request: TRequest;
+    eventBus: EventBus;
+    eventStore: EventStore;
+    costCollector: RunCostCollector;
+    registryStore: RunRegistryStore;
+    auditPort?: AuditPort;
+    onCancelled?: (runId: string, opts: CancelOpts) => void;
+}
+/**
+ * RunHandle 的默认实现只编织现有机制：
+ * - cancel 只触发 AbortController，不改 GraphExecutor；
+ * - observe 只包装 EventBus/EventStore；
+ * - cost 只读取外部注入的 CostCollector。
+ */
+declare class DefaultRunHandle<TRequest extends RunRequestSnapshot = RunRequestSnapshot> implements RunHandle<TRequest> {
+    readonly runId: string;
+    readonly parentRunId?: string;
+    readonly signal: AbortSignal;
+    private runRecord;
+    private readonly abortController;
+    private readonly agentSpecSnapshot;
+    private readonly requestSnapshot;
+    private readonly eventBus;
+    private readonly eventStore;
+    private readonly costCollector;
+    private readonly registryStore;
+    private readonly auditPort;
+    private readonly onCancelled?;
+    constructor(options: DefaultRunHandleOptions<TRequest>);
+    spec(): Promise<AgentSpec>;
+    request(): Promise<TRequest>;
+    cancel(opts: CancelOpts): Promise<void>;
+    observe(filter?: RunObserveFilter): AsyncIterable<RuntimeEvent>;
+    cost(): Promise<RunCost>;
+    meta(): Promise<RunMeta>;
+    markRunning(patch?: RunLifecyclePatch): Promise<void>;
+    markAwaitingUser(patch?: RunAwaitingUserPatch): Promise<void>;
+    markCompleted(patch?: RunLifecyclePatch): Promise<void>;
+    markFailed(error: RunFailureInfo, patch?: RunLifecyclePatch): Promise<void>;
+    pause(_reason?: string): Promise<never>;
+    resume(): Promise<never>;
+    private saveLifecycleStatus;
+}
+declare function runMetaFromRecord(record: RunRecord): RunMeta;
+
+export { type CancelOpts as C, DefaultRunHandle as D, type EventRangeOptions as E, type ListRunsFilter as L, type PersistedEvent as P, type RunAwaitingUserPatch as R, type EventStore as a, EventBus as b, createMonotonicEventIdFactory as c, type DefaultRunHandleOptions as d, type RunCost as e, type RunCostCollector as f, type RunFailureInfo as g, type RunHandle as h, type RunLifecyclePatch as i, type RunMeta as j, type RunObserveFilter as k, type RunRecord as l, type RunRegistryStore as m, type RunRequestSnapshot as n, type RunStatus as o, runMetaFromRecord as r };