qlogicagent 0.5.2 → 0.6.0

package/dist/types/llm/provider-registry.d.ts

@@ -0,0 +1,54 @@
+/**
+ * ProviderRegistry — three-layer merge registry for LLM providers.
+ *
+ * Layer 1: builtin-providers.ts hardcoded (lowest priority, ~20 providers)
+ * Layer 2: model-catalog.ts remote (models.dev — enriches model metadata)
+ * Layer 3: user config override (from agent.turn.config — highest priority)
+ *
+ * Merge strategy: Layer 3 > Layer 2 > Layer 1 (later layers override same-id fields)
+ *
+ * Aligned with Hermes provider_registry.py.
+ */
+import type { ModelInfo, ProviderDef } from "./provider-def.js";
+import { ModelCatalog } from "./model-catalog.js";
+export declare class ProviderRegistry {
+    /** Layer 1: builtin hardcoded providers */
+    private builtins;
+    /** Layer 2: remote model catalog (models.dev) */
+    private catalog;
+    /** Layer 3: user overrides (from agent.turn.config) */
+    private overrides;
+    constructor(opts?: {
+        catalog?: ModelCatalog;
+    });
+    /**
+     * Apply user config override for a provider.
+     * Typically called when agent.turn.config has baseUrl/apiKey overrides.
+     */
+    applyOverride(providerId: string, override: Partial<ProviderDef>): void;
+    /**
+     * Get merged ProviderDef by id (Layer 3 > Layer 1).
+     * Returns undefined if provider not found.
+     * Supports common aliases (e.g., "claude" → "anthropic").
+     */
+    getProvider(id: string): ProviderDef | undefined;
+    /**
+     * List all known provider ids.
+     */
+    listProviders(): ProviderDef[];
+    /**
+     * List models for a specific provider.
+     * Merges: Layer 3 override > Layer 1 builtin > Layer 2 catalog enrichment.
+     */
+    listModels(providerId: string): ModelInfo[];
+    /**
+     * Trigger background refresh of the remote model catalog.
+     */
+    refreshCatalog(): Promise<boolean>;
+    /**
+     * Resolve API key for a provider:
+     *   1. Explicit key (from agent.turn.config)
+     *   2. Environment variables (ProviderDef.apiKeyEnvVars)
+     */
+    resolveApiKey(providerId: string, explicitKey?: string): string | undefined;
+}

package/dist/types/llm/transport.d.ts

@@ -0,0 +1,62 @@
+/**
+ * LLMTransport — abstract interface for LLM inference calls.
+ *
+ * Aligned with Hermes `ProviderTransport` ABC:
+ *   stream(request, apiKey, signal) → AsyncGenerator<LLMChunk>
+ *
+ * Two concrete implementations:
+ *   - OpenAI Chat Completions (covers 95% of providers)
+ *   - Anthropic Messages API
+ */
+import type { ChatMessage, ToolDefinition } from "../agent/types.js";
+export interface LLMRequest {
+    model: string;
+    messages: ChatMessage[];
+    tools?: ToolDefinition[];
+    toolChoice?: "auto" | "none" | "required";
+    temperature?: number;
+    maxTokens?: number;
+    reasoning?: {
+        effort: "low" | "medium" | "high";
+    };
+}
+export type LLMChunk = {
+    type: "delta";
+    text: string;
+} | {
+    type: "tool_call_delta";
+    index: number;
+    id?: string;
+    name?: string;
+    arguments: string;
+} | {
+    type: "reasoning_delta";
+    text: string;
+} | {
+    type: "usage";
+    promptTokens: number;
+    completionTokens: number;
+    reasoningTokens?: number;
+} | {
+    type: "done";
+    finishReason: string;
+};
+export interface AccumulatedToolCall {
+    id: string;
+    name: string;
+    arguments: string;
+}
+export interface LLMTransport {
+    /**
+     * Stream an LLM inference request.
+     * apiKey is passed explicitly (from agent.turn.config, not env).
+     */
+    stream(request: LLMRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<LLMChunk>;
+}
+/**
+ * Accumulate tool_call_delta chunks into complete ToolCall objects.
+ * Modeled after admin-infer-proxy-client's Map<index, toolCall> accumulator.
+ */
+export declare function accumulateToolCalls(accumulator: Map<number, AccumulatedToolCall>, chunk: LLMChunk & {
+    type: "tool_call_delta";
+}): void;

package/dist/types/llm/transports/anthropic-messages.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Anthropic Messages Transport — SSE streaming for Claude API.
+ *
+ * POST {baseUrl}/v1/messages with stream: true
+ * Auth: x-api-key: {apiKey} + anthropic-version header
+ *
+ * SSE event types:
+ *   message_start, content_block_start, content_block_delta,
+ *   content_block_stop, message_delta, message_stop
+ *
+ * Tool use is via content blocks with type "tool_use" + "input_json_delta".
+ *
+ * Aligned with Hermes anthropic_messages.py transport.
+ */
+import type { LLMChunk, LLMRequest, LLMTransport } from "../transport.js";
+export interface AnthropicTransportConfig {
+    baseUrl: string;
+    /** anthropic-version header (default "2023-06-01") */
+    apiVersion?: string;
+    /** Timeout in ms (default 180_000) */
+    timeoutMs?: number;
+}
+export declare class AnthropicMessagesTransport implements LLMTransport {
+    private baseUrl;
+    private apiVersion;
+    private timeoutMs;
+    constructor(config: AnthropicTransportConfig);
+    stream(request: LLMRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<LLMChunk>;
+    private parseSSEStream;
+    private mapEvent;
+}

package/dist/types/llm/transports/openai-chat.d.ts

@@ -0,0 +1,36 @@
+/**
+ * OpenAI Chat Completions Transport — SSE streaming implementation.
+ *
+ * Covers all OpenAI-compatible providers:
+ *   DeepSeek, Qwen, 硅基, Minimax, Moonshot, Groq, Together, OpenRouter, etc.
+ *
+ * POST {baseUrl}/v1/chat/completions with stream: true
+ * Auth: Authorization: Bearer {apiKey}
+ *
+ * SSE format: lines prefixed with "data: ", JSON parsing per event.
+ *
+ * Adapted from admin-infer-proxy-client.ts SSE logic + Hermes openai_chat.py transport.
+ */
+import type { LLMChunk, LLMRequest, LLMTransport } from "../transport.js";
+export interface OpenAIChatTransportConfig {
+    baseUrl: string;
+    /** Additional headers (e.g. for specific providers) */
+    extraHeaders?: Record<string, string>;
+    /** Timeout in ms (default 180_000) */
+    timeoutMs?: number;
+    /** Whether to include stream_options (default true). Set false for providers that reject it. */
+    supportsStreamOptions?: boolean;
+    /** Whether to omit temperature when it equals 0 (e.g. Moonshot rejects 0) */
+    omitZeroTemperature?: boolean;
+}
+export declare class OpenAIChatTransport implements LLMTransport {
+    private baseUrl;
+    private extraHeaders;
+    private timeoutMs;
+    private supportsStreamOptions;
+    private omitZeroTemperature;
+    constructor(config: OpenAIChatTransportConfig);
+    stream(request: LLMRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<LLMChunk>;
+    private parseSSEStream;
+    private mapChunk;
+}

package/dist/types/orchestration/context/context-collapse.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Context Collapse — staged lightweight context reduction that runs
+ * BEFORE autocompact and can drain on 413 BEFORE reactive compact.
+ *
+ * CC parity: services/contextCollapse/index.ts
+ *
+ * Architecture:
+ * 1. applyCollapsesIfNeeded() — runs every iteration, projects the
+ *    collapsed view and maybe commits more collapses (by summarizing
+ *    old tool-result groups into compact summaries).
+ * 2. recoverFromOverflow() — drain all staged collapses on a real
+ *    API 413. If it can free enough context, the retry may succeed
+ *    without reactive compact (which is heavier and destroys more
+ *    context).
+ *
+ * Collapses are ordered "stages" — oldest first. Each stage replaces
+ * a contiguous run of old messages with a single summary line.
+ */
+export interface CollapseStage {
+    /** UUID of the stage (for dedup and ordering). */
+    id: string;
+    /** Index range [start, end) in the original message array. */
+    range: [number, number];
+    /** Summary text that replaces the range. */
+    summary: string;
+    /** Whether this stage has been committed (applied to messages). */
+    committed: boolean;
+}
+export interface CollapseStore {
+    stages: CollapseStage[];
+}
+export declare function createCollapseStore(): CollapseStore;
+/**
+ * Evaluate whether new collapses should be staged.
+ *
+ * Heuristic: if the conversation has > thresholdMessages non-system messages,
+ * group old tool-result runs into collapse stages.
+ */
+export declare function applyCollapsesIfNeeded<T extends {
+    role: string;
+    content?: string | unknown;
+}>(messages: T[], store: CollapseStore, opts?: {
+    thresholdMessages?: number;
+}): {
+    messages: T[];
+    stagedCount: number;
+};
+/**
+ * Drain all staged (uncommitted) collapses — called on 413 recovery.
+ * Commits every pending stage and returns the collapsed messages.
+ */
+export declare function recoverFromOverflow<T extends {
+    role: string;
+    content?: string | unknown;
+}>(messages: T[], store: CollapseStore): {
+    messages: T[];
+    committed: number;
+};

package/dist/types/orchestration/context/context-compression.d.ts

@@ -0,0 +1,301 @@
+export interface CompressibleMessage {
+    role: string;
+    content?: string | unknown;
+    tool_call_id?: string;
+    tool_calls?: unknown;
+    name?: string;
+}
+export interface CompressionResult {
+    messages: CompressibleMessage[];
+    droppedCount: number;
+    strategy: string;
+    /** Phase 4: optional metrics from the compression pass */
+    metrics?: CompressionMetrics;
+}
+export interface CompressionMetrics {
+    tokensBefore: number;
+    tokensAfter: number;
+    compressionRatio: number;
+    /** ms elapsed for this strategy pass */
+    latencyMs: number;
+    /** Whether an LLM call was made during this pass */
+    usedLlm: boolean;
+    /** Whether prompt cache was invalidated by compression */
+    cacheInvalidated?: boolean;
+}
+export interface CompressionStrategy {
+    compress(messages: CompressibleMessage[], budget: number): CompressionResult;
+}
+/**
+ * Async compression strategy — required for LLM-based summarization.
+ * Falls back to sync `compress` when the caller doesn't support async.
+ */
+export interface AsyncCompressionStrategy extends CompressionStrategy {
+    compressAsync(messages: CompressibleMessage[], budget: number): Promise<CompressionResult>;
+}
+export declare function isAsyncCompressionStrategy(s: CompressionStrategy): s is AsyncCompressionStrategy;
+/** Caller-provided LLM summarization function (wired by Hub). */
+export type SummarizeFn = (messages: CompressibleMessage[], instruction: string) => Promise<string>;
+export declare class SlidingWindowStrategy implements CompressionStrategy {
+    private estimateTokens;
+    constructor(estimateTokens: (msg: CompressibleMessage) => number);
+    compress(messages: CompressibleMessage[], budget: number): CompressionResult;
+}
+export declare class SummarizeOldStrategy implements CompressionStrategy {
+    private recentCount;
+    private summarize;
+    constructor(recentCount: number, summarize: (messages: CompressibleMessage[]) => string);
+    compress(messages: CompressibleMessage[], _budget: number): CompressionResult;
+}
+export declare class ToolResultTrimStrategy implements CompressionStrategy {
+    private maxToolResultChars;
+    constructor(maxToolResultChars?: number);
+    compress(messages: CompressibleMessage[], _budget: number): CompressionResult;
+}
+export declare function composeStrategies(...strategies: CompressionStrategy[]): CompressionStrategy;
+/**
+ * Compose strategies with async support — if any strategy is async,
+ * the pipeline becomes async.
+ */
+export declare function composeAsyncStrategies(...strategies: CompressionStrategy[]): AsyncCompressionStrategy;
+/**
+ * Build the structured 9-section summary instruction for the LLM.
+ * Based on Claude Code's Full Compact mode, adapted for Hub.
+ */
+export declare function buildStructuredSummaryPrompt(messagesToSummarize: CompressibleMessage[], opts?: {
+    taskContext?: string;
+}): string;
+export interface HeadTailProtectionConfig {
+    /** Number of initial user-assistant exchanges to protect (default: 1) */
+    protectedHeadExchanges: number;
+    /** Number of recent messages to always keep (default: 8 = ~4 exchanges) */
+    protectedTailMessages: number;
+    /** The summarization callback */
+    summarize: SummarizeFn;
+    /** Optional token estimator */
+    estimateTokens?: (msg: CompressibleMessage) => number;
+    /** Optional extra context for the summary prompt */
+    taskContext?: string;
+}
+/**
+ * Phase 2.2: Head/Tail protected summarization.
+ *
+ * Protects: system messages + first exchange + last N messages.
+ * Compresses: middle section via LLM summarization.
+ */
+export declare class HeadTailProtectedStrategy implements AsyncCompressionStrategy {
+    private config;
+    constructor(config: HeadTailProtectionConfig);
+    compress(messages: CompressibleMessage[], _budget: number): CompressionResult;
+    compressAsync(messages: CompressibleMessage[], budget: number): Promise<CompressionResult>;
+}
+export interface IncrementalCompactConfig {
+    /** Messages newer than this count are never summarized (default: 12) */
+    preserveRecentCount: number;
+    /** Summarization callback */
+    summarize: SummarizeFn;
+    /** Token estimator */
+    estimateTokens?: (msg: CompressibleMessage) => number;
+}
+/**
+ * Phase 2.3: Incremental (partial) compaction.
+ *
+ * Only summarizes the oldest messages beyond the preserve window.
+ * Avoids repeatedly re-summarizing already-compressed content.
+ * If a previous summary marker exists, only new old messages are compressed.
+ */
+export declare class IncrementalCompactStrategy implements AsyncCompressionStrategy {
+    private config;
+    constructor(config: IncrementalCompactConfig);
+    compress(messages: CompressibleMessage[], _budget: number): CompressionResult;
+    compressAsync(messages: CompressibleMessage[], budget: number): Promise<CompressionResult>;
+}
+export interface CacheAwareCompressionConfig {
+    /** The inner strategy to delegate to */
+    inner: CompressionStrategy;
+    /** Token estimator */
+    estimateTokens?: (msg: CompressibleMessage) => number;
+    /**
+     * Callback: notify when prompt cache was invalidated by compression.
+     * Hub uses this to set pendingPostCompaction and track cache miss rate.
+     */
+    onCacheInvalidated?: (info: {
+        droppedCount: number;
+        strategy: string;
+    }) => void;
+}
+/**
+ * Phase 3: Cache-aware wrapper.
+ *
+ * Wraps any strategy and tracks whether compression invalidated the
+ * provider prompt cache. System prompt prefix stability is preserved
+ * by never modifying system[0] (the original system prompt).
+ */
+export declare class CacheAwareCompressionStrategy implements AsyncCompressionStrategy {
+    private config;
+    constructor(config: CacheAwareCompressionConfig);
+    compress(messages: CompressibleMessage[], budget: number): CompressionResult;
+    compressAsync(messages: CompressibleMessage[], budget: number): Promise<CompressionResult>;
+}
+export interface AdaptiveBudgetConfig {
+    /** Model context window size in tokens */
+    modelContextWindow: number;
+    /** Target usage ratio (0.0–1.0, default 0.75) — trigger compaction at this fraction */
+    targetUsageRatio: number;
+    /** Minimum guaranteed budget in tokens */
+    minBudget: number;
+    /** Maximum budget (usually = modelContextWindow) */
+    maxBudget: number;
+}
+export declare const DEFAULT_ADAPTIVE_BUDGET_CONFIG: AdaptiveBudgetConfig;
+/**
+ * Compute the adaptive token budget for a given model + message history.
+ *
+ * Adjusts based on model context window, and uses the target ratio
+ * so compression triggers before hitting the hard limit.
+ */
+export declare function computeAdaptiveBudget(config?: Partial<AdaptiveBudgetConfig>): number;
+/**
+ * Decide which compression tier to use based on current token count vs budget.
+ */
+export type CompressionTier = "none" | "trim-only" | "sliding-window" | "llm-summarize";
+export declare function selectCompressionTier(currentTokens: number, budget: number): CompressionTier;
+export interface CompressionEvent {
+    timestamp: number;
+    strategy: string;
+    tokensBefore: number;
+    tokensAfter: number;
+    droppedCount: number;
+    latencyMs: number;
+    usedLlm: boolean;
+    cacheInvalidated: boolean;
+    tier: CompressionTier;
+}
+export interface CompressionMetricsSnapshot {
+    totalCompressions: number;
+    totalLlmCalls: number;
+    totalCacheInvalidations: number;
+    averageCompressionRatio: number;
+    averageLatencyMs: number;
+    totalTokensSaved: number;
+    recentEvents: CompressionEvent[];
+}
+export declare class CompressionMetricsCollector {
+    private events;
+    private maxEvents;
+    constructor(maxEvents?: number);
+    record(event: CompressionEvent): void;
+    snapshot(): CompressionMetricsSnapshot;
+    reset(): void;
+}
+/**
+ * A pluggable context engine. Only one can be active at a time.
+ * The default engine uses the 4-layer compression funnel.
+ */
+export interface ContextEngine {
+    /** Unique engine identifier */
+    readonly id: string;
+    /** Human-readable label */
+    readonly label: string;
+    /** Compress messages for a turn */
+    compressAsync(messages: CompressibleMessage[], budget: number, context?: {
+        model?: string;
+        sessionId?: string;
+    }): Promise<CompressionResult>;
+}
+/**
+ * Registry for context engines. Enforces single-active constraint.
+ */
+export declare class ContextEngineRegistry {
+    private engines;
+    private activeId;
+    register(engine: ContextEngine): void;
+    activate(id: string): boolean;
+    getActive(): ContextEngine | undefined;
+    listEngines(): Array<{
+        id: string;
+        label: string;
+        active: boolean;
+    }>;
+}
+/**
+ * MicroCompact — selective clearing of old compactable tool results.
+ *
+ * CC parity: microCompact.ts
+ *
+ * For tool result messages from COMPACTABLE_TOOLS, if the message is
+ * "old enough" (not in the most recent N messages), replace its content
+ * with a compact "[result cleared]" marker. This preserves the tool call
+ * structure (so the LLM knows what was called) but reclaims token budget.
+ *
+ * This is a lighter alternative to full summarization — it runs BEFORE
+ * LLM summarization as a first-pass reduction.
+ */
+export declare class MicroCompactStrategy implements CompressionStrategy {
+    /** Number of recent messages to preserve (don't clear) */
+    private preserveRecentCount;
+    /** Token estimator */
+    private estimateTokens;
+    constructor(
+    /** Number of recent messages to preserve (don't clear) */
+    preserveRecentCount?: number, 
+    /** Token estimator */
+    estimateTokens?: (msg: CompressibleMessage) => number);
+    compress(messages: CompressibleMessage[], _budget: number): CompressionResult;
+}
+/**
+ * After compaction, the most recently read/edited files may have been
+ * dropped from the conversation. CC re-injects up to N file contents
+ * to ensure the agent doesn't lose awareness of files it was working with.
+ *
+ * CC parity: compact.ts postCompactFileStateRecovery
+ */
+export interface PostCompactRecoveryConfig {
+    /** Maximum number of files to re-inject (default 5) */
+    maxFiles: number;
+    /** Maximum total tokens for re-injected files (default 50000) */
+    maxTokenBudget: number;
+    /** Function to read a file from disk (injected by caller) */
+    readFile: (path: string) => Promise<string | null>;
+    /** Token estimator */
+    estimateTokens?: (text: string) => number;
+}
+/**
+ * Extract file paths that were recently read/edited from the conversation.
+ * Looks at tool calls and results for file path arguments.
+ */
+export declare function extractRecentFilePaths(messages: CompressibleMessage[]): string[];
+/**
+ * Re-inject recently-used file contents after compaction.
+ *
+ * Call this AFTER compression but BEFORE sending to the LLM.
+ * Appends file content as system messages at the end of the
+ * system message block.
+ */
+export declare function postCompactFileRecovery(compressedMessages: CompressibleMessage[], originalMessages: CompressibleMessage[], config: PostCompactRecoveryConfig): Promise<CompressibleMessage[]>;
+/**
+ * Snip Compact — permanently remove specific messages by identifier.
+ *
+ * CC parity: services/compact/snipCompact.ts
+ *
+ * Unlike sliding window or summarization, snip removes messages by
+ * their unique id (tool_call_id, or index-based). This is used for:
+ * - Removing old tool results that are known to be stale
+ * - Dropping large image/media messages after they've been processed
+ * - Clearing tombstoned messages from the transcript
+ *
+ * Snip runs BEFORE microcompact and autocompact — both may fire
+ * after snip if the result is still over threshold.
+ */
+export interface SnipResult {
+    messages: CompressibleMessage[];
+    tokensFreed: number;
+    removedCount: number;
+    /** Optional boundary message to yield (marks snip point in transcript). */
+    boundaryMessage?: CompressibleMessage;
+}
+/**
+ * Remove messages whose tool_call_id or name matches the removedIds set.
+ * If no removedIds are pending, this is a no-op.
+ */
+export declare function snipCompactIfNeeded(messages: CompressibleMessage[], removedIds: Set<string>, estimateTokens?: (msg: CompressibleMessage) => number): SnipResult;

package/dist/types/orchestration/context/reactive-compact.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Reactive Compact — Emergency context compression when API returns prompt-too-long.
+ *
+ * Aligned with Claude Code's reactive compact chain:
+ * 1. API 413 → withhold error → attempt reactive compact → retry
+ * 2. Only one reactive compact attempt per turn (prevent infinite loops)
+ * 3. Falls back to abort if compact fails
+ *
+ * Also handles post-compact restoration:
+ * - Todo list re-injection
+ * - Skill context re-injection
+ * - Tool delta re-injection (new/removed tools since last compact)
+ */
+export interface ReactiveCompactConfig {
+    /** Maximum consecutive auto-compact failures before giving up (CC: 3). */
+    maxConsecutiveFailures: number;
+    /** Minimum messages to keep after reactive compact. */
+    minMessagesAfterCompact: number;
+    /** Target token usage after compact (percentage of context window). */
+    targetUsagePercent: number;
+}
+export declare const DEFAULT_REACTIVE_COMPACT_CONFIG: ReactiveCompactConfig;
+export interface PostCompactRestorationPayload {
+    /** Current active todo list to re-inject after compact. */
+    todoList?: Array<{
+        id: number;
+        title: string;
+        status: string;
+    }>;
+    /** Active skill context (if LLM is executing a skill). */
+    activeSkillContext?: {
+        name: string;
+        step: number;
+        instructions: string;
+    };
+    /** Tool delta since last compact (tools added/removed from available set). */
+    toolDelta?: {
+        added: string[];
+        removed: string[];
+    };
+    /** Custom restoration blocks from memory hooks. */
+    customBlocks?: Array<{
+        label: string;
+        content: string;
+    }>;
+}
+/**
+ * Build the restoration message to inject after a compact operation.
+ * This ensures critical state survives context compression.
+ */
+export declare function buildPostCompactRestorationMessage(payload: PostCompactRestorationPayload): string | null;
+export interface ReactiveCompactState {
+    /** Number of consecutive compact failures. */
+    consecutiveFailures: number;
+    /** Whether reactive compact has been attempted in this turn. */
+    attemptedThisTurn: boolean;
+    /** Last compact timestamp. */
+    lastCompactAt: number | null;
+    /** Tool names at time of last compact (for delta calculation). */
+    toolsAtLastCompact: string[];
+}
+export declare function createReactiveCompactState(): ReactiveCompactState;
+/**
+ * Determine if reactive compact should be attempted.
+ */
+export declare function shouldAttemptReactiveCompact(state: ReactiveCompactState, config?: ReactiveCompactConfig): boolean;
+/**
+ * Calculate the tool delta since last compact.
+ */
+export declare function computeToolDelta(currentTools: string[], toolsAtLastCompact: string[]): {
+    added: string[];
+    removed: string[];
+};