@linnlabs/linnkit 0.8.0

package/dist/context-trace-DRi5M4lX.d.ts

@@ -0,0 +1,239 @@
+import { A as AiMessage } from './messages-XthmnHZ3.js';
+import { g as AgentSpecContextTracePolicy, e as AgentSpecContextPolicy } from './agentSpec-EkmviZjy.js';
+import { e as RuntimeEvent } from './todo-B1PmDlp3.js';
+
+type MessageType = AiMessage['type'];
+type MessageRole = AiMessage['role'];
+interface ChatMessage {
+    id?: string;
+    timestamp?: number;
+    role: MessageRole;
+    content: string;
+    type?: MessageType;
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+interface ChatProjectMetadata {
+    id?: string;
+    name?: string;
+    description?: string;
+}
+interface ChatDocumentMetadata {
+    id?: string;
+    title?: string;
+}
+interface ChatUserQuote {
+    text: string;
+    source?: Record<string, unknown>;
+    displayLabel?: string;
+}
+interface RecentRejection {
+    suggestionText: string;
+    userContinuedWith?: string;
+}
+interface GenerateRequest {
+    prompt: string;
+    promptKey: string;
+    conversationHistory?: ChatMessage[];
+    contextBefore?: string;
+    contextAfter?: string;
+    currentBlockContent?: string;
+    current_paragraph?: string;
+    documentFragment?: string;
+    modelId?: string;
+    conversationId?: string;
+    projectMetadata?: ChatProjectMetadata;
+    documentMetadata?: ChatDocumentMetadata;
+    userQuote?: ChatUserQuote;
+    completionLengthHint?: string;
+    recentRejections?: RecentRejection[];
+    intentKey?: 'continue_paragraph' | 'list_next_item' | 'bridge_to_suffix_delimiter' | 'rewrite_after_large_delete' | 'structure_editing';
+    intentConfidence?: number;
+    intentConstraints?: string[];
+    behaviorSummary?: {
+        totalEvents: number;
+        totalInsertedChars: number;
+        totalDeletedChars: number;
+        recentDeletedChars?: number;
+        hasLargeRecentDelete?: boolean;
+        typingSpeedCps?: number;
+    };
+}
+interface GenerateResponse {
+    generatedText: string;
+}
+
+interface MessageProcessingState {
+    message: AiMessage;
+    originalIndex: number;
+    action: 'keep_core' | 'keep_working_memory' | 'summarize' | 'skip';
+    tokens: number;
+    processedContent?: string;
+    contentType?: 'full' | 'final_answer_only' | 'thinking_only';
+    phase?: string;
+    replacementSourceIds?: string[];
+}
+interface SummarizationCallbacks {
+    onSummarizationStart?: () => void;
+    onSummarizationEnd?: (info: {
+        originalMessageCount: number;
+        summaryTokenCount?: number;
+        newSummaryId?: string;
+        summaryEvent?: RuntimeEvent;
+    }) => void;
+    onSummarizationError?: (error: Error) => void;
+}
+interface ProviderContext<TConfig = unknown> {
+    totalBudget: number;
+    config: TConfig;
+    debugMode: boolean;
+    estimateTokens: (message: AiMessage) => number;
+    summarizationCallbacks?: SummarizationCallbacks;
+    /**
+     * Host 注入的注册式 AI 调用入口。
+     *
+     * 中文备注：调用方必须通过 request.promptKey / agentId 解析已注册 agent/chat；
+     * framework 不应在 Provider 内直接发起裸 LLM call。
+     */
+    generate?: (request: GenerateRequest) => Promise<GenerateResponse>;
+}
+interface ProviderResult {
+    states: MessageProcessingState[];
+    tokensUsed: number;
+    strategiesApplied: string[];
+    stats: {
+        processedCount: number;
+        skippedCount: number;
+        addedCount: number;
+    };
+    events?: RuntimeEvent[];
+}
+declare const TOOL_HISTORY_OVERFLOW_ERROR_CODE: "TOOL_HISTORY_OVERFLOW";
+declare const SUMMARIZATION_FAILED_ERROR_CODE: "SUMMARIZATION_FAILED";
+type ContextProviderErrorCode = 'context_provider_failed' | typeof SUMMARIZATION_FAILED_ERROR_CODE | typeof TOOL_HISTORY_OVERFLOW_ERROR_CODE;
+interface ContextProviderErrorOptions {
+    code: ContextProviderErrorCode;
+    fatal?: boolean;
+    providerName: string;
+    message: string;
+    cause?: unknown;
+}
+/**
+ * Provider 内部向 pipeline 传递的结构化错误。
+ *
+ * 中文备注：
+ * - pipeline 只能依赖 code/fatal 这类稳定字段做控制流判断；
+ * - message 只用于日志和用户可见错误，不再承担协议语义。
+ */
+declare class ContextProviderError extends Error {
+    readonly code: ContextProviderErrorCode;
+    readonly fatal: boolean;
+    readonly providerName: string;
+    readonly cause?: unknown;
+    constructor(options: ContextProviderErrorOptions);
+}
+declare function isContextProviderError(error: unknown): error is ContextProviderError;
+interface IContextProvider<TConfig = unknown> {
+    readonly name: string;
+    readonly description: string;
+    readonly priority: number;
+    provide(states: MessageProcessingState[], availableBudget: number, context: ProviderContext<TConfig>): Promise<ProviderResult>;
+    shouldSkip?(states: MessageProcessingState[], availableBudget: number, context: ProviderContext<TConfig>): boolean;
+}
+declare abstract class BaseContextProvider<TConfig = unknown> implements IContextProvider<TConfig> {
+    abstract readonly name: string;
+    abstract readonly description: string;
+    abstract readonly priority: number;
+    abstract provide(states: MessageProcessingState[], availableBudget: number, context: ProviderContext<TConfig>): Promise<ProviderResult>;
+    shouldSkip(_states: MessageProcessingState[], availableBudget: number, _context: ProviderContext<TConfig>): boolean;
+    protected debug(message: string, data?: Record<string, unknown>, context?: ProviderContext<TConfig>): void;
+    protected createResult(states: MessageProcessingState[], tokensUsed?: number, strategiesApplied?: string[], stats?: {
+        processedCount: number;
+        skippedCount: number;
+        addedCount: number;
+    }, events?: RuntimeEvent[]): ProviderResult;
+}
+
+type ContextTraceEvent = ContextTraceProviderEvent | ContextTraceMessageDecisionEvent;
+interface ContextTraceProviderEvent {
+    kind: 'provider';
+    providerName: string;
+    skipped: boolean;
+    durationMs: number;
+    beforeTokens: number;
+    afterTokens: number;
+    tokenDelta: number;
+    tokensUsed: number;
+    beforeKeptCount: number;
+    afterKeptCount: number;
+    strategiesApplied: string[];
+    remainingBudget: number;
+}
+interface ContextTraceMessageDecisionEvent {
+    kind: 'message-decision';
+    originalIndex: number;
+    messageId?: string;
+    role: AiMessage['role'];
+    type: AiMessage['type'];
+    action: MessageProcessingState['action'];
+    phase?: string;
+    tokens: number;
+    kept: boolean;
+    reason: string;
+    replacementSourceIds?: string[];
+}
+interface ContextTrace {
+    enabled: true;
+    includeMessageIds: boolean;
+    includeTokenBreakdown: boolean;
+    maxTraceEvents: number;
+    overflowed: boolean;
+    effectivePolicy?: AgentSpecContextPolicy;
+    totalBudget: number;
+    originalCount: number;
+    finalCount: number;
+    finalTokens: number;
+    truncated: boolean;
+    events: ContextTraceEvent[];
+}
+interface ContextTraceCollectorOptions {
+    policy?: AgentSpecContextTracePolicy;
+    effectivePolicy?: AgentSpecContextPolicy;
+    totalBudget: number;
+    originalCount: number;
+}
+interface ProviderTraceInput {
+    providerName: string;
+    skipped: boolean;
+    durationMs: number;
+    beforeStates: ReadonlyArray<MessageProcessingState>;
+    afterStates: ReadonlyArray<MessageProcessingState>;
+    tokensUsed: number;
+    strategiesApplied: readonly string[];
+    remainingBudget: number;
+}
+/**
+ * ContextTrace 的最小采集器。
+ *
+ * 中文备注：
+ * - trace 只描述“本次上下文构建如何选择消息”，不进入 LLM 输入；
+ * - 采集器内部做 maxTraceEvents 限流，避免观测数据反过来膨胀。
+ */
+declare class ContextTraceCollector {
+    private readonly includeMessageIds;
+    private readonly includeTokenBreakdown;
+    private readonly maxTraceEvents;
+    private readonly effectivePolicy?;
+    private readonly totalBudget;
+    private readonly originalCount;
+    private readonly events;
+    private overflowed;
+    private constructor();
+    static create(options: ContextTraceCollectorOptions): ContextTraceCollector | undefined;
+    recordProvider(input: ProviderTraceInput): void;
+    recordMessageDecisions(states: ReadonlyArray<MessageProcessingState>): void;
+    build(finalMessages: ReadonlyArray<AiMessage>, finalTokens: number): ContextTrace;
+    private push;
+}
+
+export { BaseContextProvider as B, type ChatMessage as C, type GenerateRequest as G, type IContextProvider as I, type MessageProcessingState as M, type ProviderContext as P, type RecentRejection as R, type SummarizationCallbacks as S, TOOL_HISTORY_OVERFLOW_ERROR_CODE as T, type ProviderResult as a, ContextTraceCollector as b, type GenerateResponse as c, type ContextTrace as d, type ChatDocumentMetadata as e, type ChatProjectMetadata as f, type ChatUserQuote as g, ContextProviderError as h, type ContextProviderErrorCode as i, type ContextProviderErrorOptions as j, type ContextTraceEvent as k, type ContextTraceMessageDecisionEvent as l, type ContextTraceProviderEvent as m, type MessageRole as n, type MessageType as o, SUMMARIZATION_FAILED_ERROR_CODE as p, isContextProviderError as q };

package/dist/context-trace-HE2qY5Q-.d.cts

@@ -0,0 +1,239 @@
+import { A as AiMessage } from './messages-XthmnHZ3.cjs';
+import { g as AgentSpecContextTracePolicy, e as AgentSpecContextPolicy } from './agentSpec-EkmviZjy.cjs';
+import { e as RuntimeEvent } from './todo-B1PmDlp3.cjs';
+
+type MessageType = AiMessage['type'];
+type MessageRole = AiMessage['role'];
+interface ChatMessage {
+    id?: string;
+    timestamp?: number;
+    role: MessageRole;
+    content: string;
+    type?: MessageType;
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+interface ChatProjectMetadata {
+    id?: string;
+    name?: string;
+    description?: string;
+}
+interface ChatDocumentMetadata {
+    id?: string;
+    title?: string;
+}
+interface ChatUserQuote {
+    text: string;
+    source?: Record<string, unknown>;
+    displayLabel?: string;
+}
+interface RecentRejection {
+    suggestionText: string;
+    userContinuedWith?: string;
+}
+interface GenerateRequest {
+    prompt: string;
+    promptKey: string;
+    conversationHistory?: ChatMessage[];
+    contextBefore?: string;
+    contextAfter?: string;
+    currentBlockContent?: string;
+    current_paragraph?: string;
+    documentFragment?: string;
+    modelId?: string;
+    conversationId?: string;
+    projectMetadata?: ChatProjectMetadata;
+    documentMetadata?: ChatDocumentMetadata;
+    userQuote?: ChatUserQuote;
+    completionLengthHint?: string;
+    recentRejections?: RecentRejection[];
+    intentKey?: 'continue_paragraph' | 'list_next_item' | 'bridge_to_suffix_delimiter' | 'rewrite_after_large_delete' | 'structure_editing';
+    intentConfidence?: number;
+    intentConstraints?: string[];
+    behaviorSummary?: {
+        totalEvents: number;
+        totalInsertedChars: number;
+        totalDeletedChars: number;
+        recentDeletedChars?: number;
+        hasLargeRecentDelete?: boolean;
+        typingSpeedCps?: number;
+    };
+}
+interface GenerateResponse {
+    generatedText: string;
+}
+
+interface MessageProcessingState {
+    message: AiMessage;
+    originalIndex: number;
+    action: 'keep_core' | 'keep_working_memory' | 'summarize' | 'skip';
+    tokens: number;
+    processedContent?: string;
+    contentType?: 'full' | 'final_answer_only' | 'thinking_only';
+    phase?: string;
+    replacementSourceIds?: string[];
+}
+interface SummarizationCallbacks {
+    onSummarizationStart?: () => void;
+    onSummarizationEnd?: (info: {
+        originalMessageCount: number;
+        summaryTokenCount?: number;
+        newSummaryId?: string;
+        summaryEvent?: RuntimeEvent;
+    }) => void;
+    onSummarizationError?: (error: Error) => void;
+}
+interface ProviderContext<TConfig = unknown> {
+    totalBudget: number;
+    config: TConfig;
+    debugMode: boolean;
+    estimateTokens: (message: AiMessage) => number;
+    summarizationCallbacks?: SummarizationCallbacks;
+    /**
+     * Host 注入的注册式 AI 调用入口。
+     *
+     * 中文备注：调用方必须通过 request.promptKey / agentId 解析已注册 agent/chat；
+     * framework 不应在 Provider 内直接发起裸 LLM call。
+     */
+    generate?: (request: GenerateRequest) => Promise<GenerateResponse>;
+}
+interface ProviderResult {
+    states: MessageProcessingState[];
+    tokensUsed: number;
+    strategiesApplied: string[];
+    stats: {
+        processedCount: number;
+        skippedCount: number;
+        addedCount: number;
+    };
+    events?: RuntimeEvent[];
+}
+declare const TOOL_HISTORY_OVERFLOW_ERROR_CODE: "TOOL_HISTORY_OVERFLOW";
+declare const SUMMARIZATION_FAILED_ERROR_CODE: "SUMMARIZATION_FAILED";
+type ContextProviderErrorCode = 'context_provider_failed' | typeof SUMMARIZATION_FAILED_ERROR_CODE | typeof TOOL_HISTORY_OVERFLOW_ERROR_CODE;
+interface ContextProviderErrorOptions {
+    code: ContextProviderErrorCode;
+    fatal?: boolean;
+    providerName: string;
+    message: string;
+    cause?: unknown;
+}
+/**
+ * Provider 内部向 pipeline 传递的结构化错误。
+ *
+ * 中文备注：
+ * - pipeline 只能依赖 code/fatal 这类稳定字段做控制流判断；
+ * - message 只用于日志和用户可见错误，不再承担协议语义。
+ */
+declare class ContextProviderError extends Error {
+    readonly code: ContextProviderErrorCode;
+    readonly fatal: boolean;
+    readonly providerName: string;
+    readonly cause?: unknown;
+    constructor(options: ContextProviderErrorOptions);
+}
+declare function isContextProviderError(error: unknown): error is ContextProviderError;
+interface IContextProvider<TConfig = unknown> {
+    readonly name: string;
+    readonly description: string;
+    readonly priority: number;
+    provide(states: MessageProcessingState[], availableBudget: number, context: ProviderContext<TConfig>): Promise<ProviderResult>;
+    shouldSkip?(states: MessageProcessingState[], availableBudget: number, context: ProviderContext<TConfig>): boolean;
+}
+declare abstract class BaseContextProvider<TConfig = unknown> implements IContextProvider<TConfig> {
+    abstract readonly name: string;
+    abstract readonly description: string;
+    abstract readonly priority: number;
+    abstract provide(states: MessageProcessingState[], availableBudget: number, context: ProviderContext<TConfig>): Promise<ProviderResult>;
+    shouldSkip(_states: MessageProcessingState[], availableBudget: number, _context: ProviderContext<TConfig>): boolean;
+    protected debug(message: string, data?: Record<string, unknown>, context?: ProviderContext<TConfig>): void;
+    protected createResult(states: MessageProcessingState[], tokensUsed?: number, strategiesApplied?: string[], stats?: {
+        processedCount: number;
+        skippedCount: number;
+        addedCount: number;
+    }, events?: RuntimeEvent[]): ProviderResult;
+}
+
+type ContextTraceEvent = ContextTraceProviderEvent | ContextTraceMessageDecisionEvent;
+interface ContextTraceProviderEvent {
+    kind: 'provider';
+    providerName: string;
+    skipped: boolean;
+    durationMs: number;
+    beforeTokens: number;
+    afterTokens: number;
+    tokenDelta: number;
+    tokensUsed: number;
+    beforeKeptCount: number;
+    afterKeptCount: number;
+    strategiesApplied: string[];
+    remainingBudget: number;
+}
+interface ContextTraceMessageDecisionEvent {
+    kind: 'message-decision';
+    originalIndex: number;
+    messageId?: string;
+    role: AiMessage['role'];
+    type: AiMessage['type'];
+    action: MessageProcessingState['action'];
+    phase?: string;
+    tokens: number;
+    kept: boolean;
+    reason: string;
+    replacementSourceIds?: string[];
+}
+interface ContextTrace {
+    enabled: true;
+    includeMessageIds: boolean;
+    includeTokenBreakdown: boolean;
+    maxTraceEvents: number;
+    overflowed: boolean;
+    effectivePolicy?: AgentSpecContextPolicy;
+    totalBudget: number;
+    originalCount: number;
+    finalCount: number;
+    finalTokens: number;
+    truncated: boolean;
+    events: ContextTraceEvent[];
+}
+interface ContextTraceCollectorOptions {
+    policy?: AgentSpecContextTracePolicy;
+    effectivePolicy?: AgentSpecContextPolicy;
+    totalBudget: number;
+    originalCount: number;
+}
+interface ProviderTraceInput {
+    providerName: string;
+    skipped: boolean;
+    durationMs: number;
+    beforeStates: ReadonlyArray<MessageProcessingState>;
+    afterStates: ReadonlyArray<MessageProcessingState>;
+    tokensUsed: number;
+    strategiesApplied: readonly string[];
+    remainingBudget: number;
+}
+/**
+ * ContextTrace 的最小采集器。
+ *
+ * 中文备注：
+ * - trace 只描述“本次上下文构建如何选择消息”，不进入 LLM 输入；
+ * - 采集器内部做 maxTraceEvents 限流，避免观测数据反过来膨胀。
+ */
+declare class ContextTraceCollector {
+    private readonly includeMessageIds;
+    private readonly includeTokenBreakdown;
+    private readonly maxTraceEvents;
+    private readonly effectivePolicy?;
+    private readonly totalBudget;
+    private readonly originalCount;
+    private readonly events;
+    private overflowed;
+    private constructor();
+    static create(options: ContextTraceCollectorOptions): ContextTraceCollector | undefined;
+    recordProvider(input: ProviderTraceInput): void;
+    recordMessageDecisions(states: ReadonlyArray<MessageProcessingState>): void;
+    build(finalMessages: ReadonlyArray<AiMessage>, finalTokens: number): ContextTrace;
+    private push;
+}
+
+export { BaseContextProvider as B, type ChatMessage as C, type GenerateRequest as G, type IContextProvider as I, type MessageProcessingState as M, type ProviderContext as P, type RecentRejection as R, type SummarizationCallbacks as S, TOOL_HISTORY_OVERFLOW_ERROR_CODE as T, type ProviderResult as a, ContextTraceCollector as b, type GenerateResponse as c, type ContextTrace as d, type ChatDocumentMetadata as e, type ChatProjectMetadata as f, type ChatUserQuote as g, ContextProviderError as h, type ContextProviderErrorCode as i, type ContextProviderErrorOptions as j, type ContextTraceEvent as k, type ContextTraceMessageDecisionEvent as l, type ContextTraceProviderEvent as m, type MessageRole as n, type MessageType as o, SUMMARIZATION_FAILED_ERROR_CODE as p, isContextProviderError as q };