@thoughtflow/core 0.1.2

package/dist/libs/context-window.class.js

@@ -0,0 +1,187 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextWindowManager = void 0;
+exports.estimateTokens = estimateTokens;
+exports.pruneToolOutputs = pruneToolOutputs;
+/**
+ * Rough token estimator: 1 token ≈ 4 characters (same heuristic as opencode Token.estimate).
+ * Good enough for trimming decisions without a real tokenizer.
+ */
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/**
+ * ContextWindowManager
+ *
+ * Receives the raw message history snapshot and returns a trimmed
+ * subset safe to send to the LLM. The system message is ALWAYS
+ * preserved (it is never counted against `maxMessages`).
+ *
+ * Only deterministic trimming — no LLM calls inside.
+ */
+class ContextWindowManager {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Apply the configured strategy and return a trimmed message array.
+     * When `config.maxTokens` is set, trims by estimated token count instead of message count.
+     * @param messages Full snapshot from MessageHistory.
+     */
+    trim(messages) {
+        // Always separate system messages from the rest
+        const systemMessages = messages.filter((m) => m.role === "system");
+        const nonSystem = messages.filter((m) => m.role !== "system");
+        // Token-based trimming takes priority over message-count trimming
+        if (this.config.maxTokens !== undefined) {
+            return this.trimByTokens(systemMessages, nonSystem, this.config.maxTokens);
+        }
+        const maxMessages = this.normalizeNonNegativeInt(this.config.maxMessages);
+        if (nonSystem.length <= maxMessages) {
+            // Within budget — return unchanged
+            return messages;
+        }
+        if (this.config.strategy === "summarize") {
+            return this.trimWithSummary(systemMessages, nonSystem, maxMessages);
+        }
+        // Keep last `maxMessages` non-system messages
+        const kept = nonSystem.slice(-maxMessages);
+        const result = [...systemMessages, ...kept];
+        // DEBUG: log message order
+        if (process.env.DEBUG_CONTEXT_WINDOW) {
+            console.log(`[ContextWindow] trim: ${systemMessages.length} system + ${kept.length} kept (of ${nonSystem.length} non-system)`);
+            console.log(`[ContextWindow] roles: ${result.map(m => m.role).join(", ")}`);
+        }
+        return result;
+    }
+    /**
+     * Return true if the message list exceeds the configured window.
+     * Useful for triggering proactive compression before sending.
+     */
+    needsTrimming(messages) {
+        const nonSystem = messages.filter((m) => m.role !== "system");
+        if (this.config.maxTokens !== undefined) {
+            const total = nonSystem.reduce((sum, m) => sum + estimateTokens(m.content), 0);
+            return total > this.config.maxTokens;
+        }
+        const maxMessages = this.normalizeNonNegativeInt(this.config.maxMessages);
+        return nonSystem.length > maxMessages;
+    }
+    // ── Token-based trimming ──────────────────────────────────────────────────
+    trimByTokens(systemMessages, nonSystem, maxTokens) {
+        // Walk from newest to oldest, accumulate token estimates, stop when over budget.
+        let budget = maxTokens;
+        const kept = [];
+        for (let i = nonSystem.length - 1; i >= 0; i--) {
+            const msg = nonSystem[i];
+            const cost = estimateTokens(msg.content);
+            if (budget - cost < 0 && kept.length > 0)
+                break; // always keep at least 1 message
+            budget -= cost;
+            kept.unshift(msg);
+        }
+        return [...systemMessages, ...kept];
+    }
+    trimWithSummary(systemMessages, nonSystem, maxMessages) {
+        // Degenerate budget: keep only system messages.
+        if (maxMessages <= 0) {
+            return [...systemMessages];
+        }
+        // Reserve one slot for the synthetic summary.
+        const maxRecentAllowed = Math.max(0, maxMessages - 1);
+        const keepRecent = this.resolveKeepRecentMessages(maxRecentAllowed);
+        const splitIndex = Math.max(0, nonSystem.length - keepRecent);
+        const summarized = nonSystem.slice(0, splitIndex);
+        const recent = nonSystem.slice(splitIndex);
+        // If nothing to summarize, fall back to plain keep-last behavior.
+        if (summarized.length === 0) {
+            return [...systemMessages, ...recent.slice(-maxMessages)];
+        }
+        const summaryMessage = {
+            id: `summary_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`,
+            role: "assistant",
+            content: this.buildSummaryContent(summarized),
+            createdAt: new Date().toISOString(),
+            metadata: {
+                contextWindowSummary: true,
+                summarizedCount: summarized.length,
+                summarizedMessageIds: summarized.map((message) => message.id),
+            },
+        };
+        return [...systemMessages, summaryMessage, ...recent];
+    }
+    resolveKeepRecentMessages(maxRecentAllowed) {
+        const configured = this.config.keepRecentMessages;
+        const fallback = maxRecentAllowed;
+        const normalized = this.normalizeNonNegativeInt(configured ?? fallback);
+        return Math.min(normalized, maxRecentAllowed);
+    }
+    buildSummaryContent(messages) {
+        const prefix = this.config.summaryPrefix ?? "Summary of earlier conversation:";
+        const lines = messages.map((message) => {
+            const compact = this.normalizeWhitespace(message.content);
+            const clipped = compact.length > 160 ? `${compact.slice(0, 160).trimEnd()}...` : compact;
+            return `- ${message.role}: ${clipped || "(empty)"}`;
+        });
+        const maxSummaryChars = this.normalizeNonNegativeInt(this.config.maxSummaryChars ?? 1200);
+        const body = lines.join("\n");
+        const clippedBody = body.length > maxSummaryChars ? `${body.slice(0, maxSummaryChars).trimEnd()}...` : body;
+        return `${prefix}\n${clippedBody}`;
+    }
+    normalizeWhitespace(value) {
+        return value.replace(/\s+/g, " ").trim();
+    }
+    normalizeNonNegativeInt(value) {
+        if (!Number.isFinite(value)) {
+            return 0;
+        }
+        return Math.max(0, Math.floor(value));
+    }
+}
+exports.ContextWindowManager = ContextWindowManager;
+// ── Standalone surgical pruning ──────────────────────────────────────────────
+const TOOL_OUTPUT_PRUNED_STUB = "[output pruned to save context]";
+/**
+ * Surgical tool-output pruning (opencode-inspired).
+ *
+ * Instead of removing whole messages, this function zero-fills the `content`
+ * of old `role:"tool"` messages that fall outside the recent token budget.
+ * Message structure is preserved so the LLM still sees that a tool was called
+ * and returned something.
+ *
+ * Already-pruned messages (`metadata.pruned === true`) are skipped.
+ *
+ * @param messages          Full message array (in conversation order).
+ * @param keepRecentTokens  Token budget for the "protected recent" window.
+ *                          Tool outputs inside this window are NOT pruned.
+ * @returns A new message array with old tool outputs replaced by a stub.
+ */
+function pruneToolOutputs(messages, keepRecentTokens) {
+    // Walk from newest to oldest to determine the protected window.
+    let remainingBudget = keepRecentTokens;
+    const protectedIds = new Set();
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        const cost = estimateTokens(msg.content);
+        if (remainingBudget < cost)
+            break; // message doesn't fit — stop protecting
+        remainingBudget -= cost;
+        protectedIds.add(msg.id);
+    }
+    return messages.map((msg) => {
+        // Only prune tool result messages outside the protected window
+        if (msg.role !== "tool" ||
+            protectedIds.has(msg.id) ||
+            msg.metadata?.["pruned"] === true ||
+            msg.content === TOOL_OUTPUT_PRUNED_STUB) {
+            return msg;
+        }
+        return {
+            ...msg,
+            content: TOOL_OUTPUT_PRUNED_STUB,
+            metadata: { ...msg.metadata, pruned: true },
+        };
+    });
+}
+//# sourceMappingURL=context-window.class.js.map

package/dist/libs/context-window.class.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-window.class.js","sourceRoot":"","sources":["../../src/libs/context-window.class.ts"],"names":[],"mappings":"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"}

package/dist/libs/conversation-runner.class.d.ts

@@ -0,0 +1,172 @@
+import { ConversationInterrupt, ConversationInterruptOnMap, ConversationPendingInterrupt, ConversationResumeResponse, ConversationMessage, LlmToolSpec, ConversationTool, ConversationTurnResult, PromptBuildOutput, SendPromptOptions, StallDetectionMode, BeforeModelHook, AfterModelHook, ToolRetryPolicy } from "../contracts";
+import { ConversationEventsBus } from "../events/conversation-events.bus";
+import { ToolRegistry } from "../tools/tool-registry.class";
+import { MessageHistory } from "./message-history.class";
+import { StatusMachine } from "./status-machine.class";
+import { ContextWindowManager } from "./context-window.class";
+import { DebugLogger } from "./debug-logger.class";
+interface RunnerDependencies {
+    conversationId: string;
+    sessionId: string;
+    getModel: () => string;
+    selectModel?: (context: {
+        phase: "turn" | "resume";
+        iteration: number;
+        defaultModel: string;
+        messages: ConversationMessage[];
+    }) => string | undefined;
+    thinking?: boolean;
+    temperature?: number;
+    numCtx?: number;
+    seed?: number;
+    stallDetection?: StallDetectionMode;
+    onTurnComplete?: (messages: ConversationMessage[]) => Promise<void>;
+    llmAdapter: {
+        streamChat: (request: {
+            model: string;
+            messages: ReturnType<MessageHistory["snapshot"]>;
+            tools: ReturnType<ToolRegistry["getLlmToolSpecs"]>;
+            signal?: AbortSignal;
+            thinking?: boolean;
+            temperature?: number;
+            numCtx?: number;
+            seed?: number;
+        }, onChunk: (chunk: {
+            contentDelta?: string;
+            fullContent: string;
+            thinkingDelta?: string;
+            fullThinking?: string;
+            done: boolean;
+            metadata?: Record<string, unknown>;
+        }) => void) => Promise<{
+            message: {
+                content: string;
+                toolCalls?: Array<{
+                    name: string;
+                    arguments: Record<string, unknown>;
+                }>;
+                thinking?: string;
+            };
+            tokensInput?: number;
+            tokensOutput?: number;
+        }>;
+        chat: (request: {
+            model: string;
+            messages: ReturnType<MessageHistory["snapshot"]>;
+            tools: ReturnType<ToolRegistry["getLlmToolSpecs"]>;
+            signal?: AbortSignal;
+            thinking?: boolean;
+            temperature?: number;
+            numCtx?: number;
+            seed?: number;
+        }) => Promise<{
+            message: {
+                content: string;
+                toolCalls?: Array<{
+                    name: string;
+                    arguments: Record<string, unknown>;
+                }>;
+                thinking?: string;
+            };
+            tokensInput?: number;
+            tokensOutput?: number;
+        }>;
+    };
+    history: MessageHistory;
+    statusMachine: StatusMachine;
+    eventsBus: ConversationEventsBus;
+    toolRegistry: ToolRegistry;
+    /** Optional context window manager — applied before every LLM request. */
+    contextWindowManager?: ContextWindowManager;
+    /** Debug logger instance — use DebugLogger.NOOP if not provided. */
+    logger?: DebugLogger;
+    /** Optional dynamic tool filter by phase/iteration/permissions. */
+    toolFilter?: (context: {
+        phase: "turn" | "resume";
+        iteration: number;
+        toolName: string;
+        metadata: Record<string, unknown>;
+        permissions: string[];
+    }) => boolean;
+    /** Optional tool router for intelligent tool selection (reduces prompt size). */
+    toolRouter?: {
+        selectTools: (userMessage: string, availableTools: ConversationTool[], context?: {
+            phase?: "turn" | "resume";
+            iteration?: number;
+            conversationHistory?: string;
+        }) => Promise<{
+            toolSpecs: LlmToolSpec[];
+        }>;
+    };
+    /** Optional runtime-context normalizer/validator applied to metadata lifecycle. */
+    normalizeRuntimeMetadata?: (metadata: Record<string, unknown>) => Record<string, unknown>;
+    /** Retry policy for selected transient-failure I/O tools. */
+    toolRetryPolicy?: ToolRetryPolicy;
+    /** Optional policy hook called before model invocation. */
+    beforeModelHook?: BeforeModelHook;
+    /** Optional policy hook called after model invocation. */
+    afterModelHook?: AfterModelHook;
+    /** Per-tool HITL policy. Tools configured here can pause run for human decisions. */
+    interruptOn?: ConversationInterruptOnMap;
+    /** Fallback description prefix for interrupt requests without explicit description. */
+    interruptDescriptionPrefix?: string;
+    /** Optional LLM caller for tools that need structured output analysis. */
+    caller?: import("../contracts").ToolLlmCaller;
+}
+export declare class ConversationRunner {
+    private readonly deps;
+    private readonly log;
+    private pendingInterrupt;
+    constructor(deps: RunnerDependencies);
+    hasPendingInterrupt(): boolean;
+    getPendingInterruptSnapshot(): ConversationPendingInterrupt | null;
+    restorePendingInterrupt(snapshot: ConversationPendingInterrupt | null): void;
+    getPendingInterrupt(): ConversationInterrupt | null;
+    runTurn(builtPrompt: PromptBuildOutput, options?: SendPromptOptions & {
+        signal?: AbortSignal;
+        metadata?: Record<string, unknown>;
+        maxIterations?: number;
+        maxToolCalls?: number;
+        maxToolCallsPerTool?: Record<string, number>;
+    }): Promise<ConversationTurnResult>;
+    resumeTurn(response: ConversationResumeResponse, options?: SendPromptOptions & {
+        signal?: AbortSignal;
+        metadata?: Record<string, unknown>;
+        maxIterations?: number;
+        maxToolCalls?: number;
+        maxToolCallsPerTool?: Record<string, number>;
+    }): Promise<ConversationTurnResult>;
+    private buildPendingInterrupt;
+    private resolveInterruptConfig;
+    private applyInterruptDecisions;
+    private resolveResumeResponse;
+    private processDecision;
+    private cloneInterrupt;
+    private toPendingInterruptSnapshot;
+    private applyToolCommand;
+    private trackStallSignals;
+    private checkStall;
+    private ensureToolResultsForBatch;
+    private injectTerminationHint;
+    private resolveModelForIteration;
+    private normalizeMaxIterations;
+    private createToolCallBudget;
+    private consumeToolCallBudget;
+    private normalizePositiveInt;
+    private resolveStreamNamespace;
+    private resolveAllowedToolSpecs;
+    private isToolAllowed;
+    private extractPermissions;
+    private filterBlockedToolCalls;
+    private createSkippedToolTrace;
+    private executeToolWithRetry;
+    private resolveToolRetryConfig;
+    private waitForRetryDelay;
+    private executeTool;
+    private transition;
+    private normalizeRuntimeMetadata;
+    private throwIfAborted;
+    private isAbortError;
+}
+export {};
+//# sourceMappingURL=conversation-runner.class.d.ts.map

package/dist/libs/conversation-runner.class.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-runner.class.d.ts","sourceRoot":"","sources":["../../src/libs/conversation-runner.class.ts"],"names":[],"mappings":"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"}