@thoughtflow/core 0.1.2

package/dist/libs/smart-tool-prompt.class.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SmartToolPrompt = void 0;
+const tool_discovery_class_1 = require("./tool-discovery.class");
+const tool_router_class_1 = require("./tool-router.class");
+class SmartToolPrompt {
+    discovery;
+    constructor(registry) {
+        this.discovery = new tool_discovery_class_1.ToolDiscoveryService(new tool_router_class_1.ToolCapabilityRouter(registry));
+    }
+    buildToolSection(taskDescription, style = "minimal") {
+        if (!taskDescription) {
+            return this.buildDomainSummary();
+        }
+        return this.discovery.buildSystemPromptContext(taskDescription);
+    }
+    getRelevantTools(taskDescription, maxTools = 15) {
+        const router = new tool_router_class_1.ToolCapabilityRouter();
+        const tools = router.resolveForPrompt(taskDescription, maxTools);
+        if (tools.length === 0)
+            return this.buildDomainSummary();
+        return router.getToolPrompt(tools.map(t => t.toolName), "minimal");
+    }
+    suggestTools(taskDescription) {
+        let output = "## Suggested Tools\n";
+        const suggestions = this.discovery.suggestForTask(taskDescription);
+        if (suggestions.startsWith("No tool"))
+            return output + "No specific tools matched. Use the domain summary to explore available capabilities.\n";
+        output += suggestions + "\n";
+        return output;
+    }
+    buildDomainSummary() {
+        return [
+            "## Tool Capabilities",
+            "Instead of a flat tool list, describe what you want to do and the system will route to the right tool.",
+            "",
+            "Available Domains:",
+            "- **codebase**: Repository intelligence (search, graph, impact analysis)",
+            "- **neural**: LLM-powered analysis (review, explain, debug, security scan)",
+            "- **quality**: Code metrics (complexity, coupling, coverage)",
+            "- **refactor**: Code transformation (rename, extract, organize imports)",
+            "- **testing**: Test automation (generate, fix, find gaps)",
+            "- **docs**: Documentation (generate README, API docs, diagrams)",
+            "- **devops**: CI/CD (workflows, Docker, deploy checks)",
+            "- **workspace**: File I/O, git, terminal, search",
+            "",
+            "Key Principle: Search before reading. Use codebase_search to find code, then read only relevant files.",
+        ].join("\n");
+    }
+    injectIntoSystemPrompt(basePrompt, taskDescription) {
+        const toolSection = this.buildToolSection(taskDescription, "minimal");
+        return `${basePrompt}\n\n${toolSection}`;
+    }
+}
+exports.SmartToolPrompt = SmartToolPrompt;
+//# sourceMappingURL=smart-tool-prompt.class.js.map

package/dist/libs/smart-tool-prompt.class.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"smart-tool-prompt.class.js","sourceRoot":"","sources":["../../src/libs/smart-tool-prompt.class.ts"],"names":[],"mappings":";;;AAAA,iEAA8D;AAC9D,2DAA2D;AAG3D,MAAa,eAAe;IAClB,SAAS,CAAuB;IAExC,YAAY,QAAgC;QAC1C,IAAI,CAAC,SAAS,GAAG,IAAI,2CAAoB,CAAC,IAAI,wCAAoB,CAAC,QAAe,CAAC,CAAC,CAAC;IACvF,CAAC;IAED,gBAAgB,CAAC,eAAwB,EAAE,QAA4B,SAAS;QAC9E,IAAI,CAAC,eAAe,EAAE,CAAC;YACrB,OAAO,IAAI,CAAC,kBAAkB,EAAE,CAAC;QACnC,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC,wBAAwB,CAAC,eAAe,CAAC,CAAC;IAClE,CAAC;IAED,gBAAgB,CAAC,eAAuB,EAAE,WAAmB,EAAE;QAC7D,MAAM,MAAM,GAAG,IAAI,wCAAoB,EAAE,CAAC;QAC1C,MAAM,KAAK,GAAG,MAAM,CAAC,gBAAgB,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC;QACjE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC,kBAAkB,EAAE,CAAC;QACzD,OAAO,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,CAAC;IACrE,CAAC;IAED,YAAY,CAAC,eAAuB;QAClC,IAAI,MAAM,GAAG,sBAAsB,CAAC;QACpC,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,eAAe,CAAC,CAAC;QACnE,IAAI,WAAW,CAAC,UAAU,CAAC,SAAS,CAAC;YAAE,OAAO,MAAM,GAAG,wFAAwF,CAAC;QAChJ,MAAM,IAAI,WAAW,GAAG,IAAI,CAAC;QAC7B,OAAO,MAAM,CAAC;IAChB,CAAC;IAEO,kBAAkB;QACxB,OAAO;YACL,sBAAsB;YACtB,wGAAwG;YACxG,EAAE;YACF,oBAAoB;YACpB,0EAA0E;YAC1E,4EAA4E;YAC5E,8DAA8D;YAC9D,yEAAyE;YACzE,2DAA2D;YAC3D,iEAAiE;YACjE,wDAAwD;YACxD,kDAAkD;YAClD,EAAE;YACF,wGAAwG;SACzG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IAED,sBAAsB,CAAC,UAAkB,EAAE,eAAwB;QACjE,MAAM,WAAW,GAAG,IAAI,CAAC,gBAAgB,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC;QACtE,OAAO,GAAG,UAAU,OAAO,WAAW,EAAE,CAAC;IAC3C,CAAC;CACF;AApDD,0CAoDC"}

package/dist/libs/status-machine.class.d.ts

@@ -0,0 +1,8 @@
+import { ConversationStatus } from "../contracts";
+export declare class StatusMachine {
+    private status;
+    get current(): ConversationStatus;
+    isTerminal(): boolean;
+    transitionTo(next: ConversationStatus): ConversationStatus;
+}
+//# sourceMappingURL=status-machine.class.d.ts.map

package/dist/libs/status-machine.class.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-machine.class.d.ts","sourceRoot":"","sources":["../../src/libs/status-machine.class.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAkC,MAAM,cAAc,CAAC;AAgClF,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAA+C;IAE7D,IAAI,OAAO,IAAI,kBAAkB,CAEhC;IAED,UAAU,IAAI,OAAO;IAIrB,YAAY,CAAC,IAAI,EAAE,kBAAkB,GAAG,kBAAkB;CAa3D"}

package/dist/libs/status-machine.class.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StatusMachine = void 0;
+const contracts_1 = require("../contracts");
+const ALLOWED_TRANSITIONS = {
+    [contracts_1.ConversationStatus.IDLE]: [
+        contracts_1.ConversationStatus.RUNNING,
+        contracts_1.ConversationStatus.INTERRUPTED,
+        contracts_1.ConversationStatus.CANCELLED
+    ],
+    [contracts_1.ConversationStatus.RUNNING]: [
+        contracts_1.ConversationStatus.WAITING_TOOL,
+        contracts_1.ConversationStatus.INTERRUPTED,
+        contracts_1.ConversationStatus.COMPLETED,
+        contracts_1.ConversationStatus.FAILED,
+        contracts_1.ConversationStatus.CANCELLED
+    ],
+    [contracts_1.ConversationStatus.WAITING_TOOL]: [
+        contracts_1.ConversationStatus.RUNNING,
+        contracts_1.ConversationStatus.INTERRUPTED,
+        contracts_1.ConversationStatus.COMPLETED,
+        contracts_1.ConversationStatus.FAILED,
+        contracts_1.ConversationStatus.CANCELLED
+    ],
+    [contracts_1.ConversationStatus.INTERRUPTED]: [
+        contracts_1.ConversationStatus.RUNNING,
+        contracts_1.ConversationStatus.FAILED,
+        contracts_1.ConversationStatus.CANCELLED
+    ],
+    [contracts_1.ConversationStatus.COMPLETED]: [contracts_1.ConversationStatus.RUNNING, contracts_1.ConversationStatus.WAITING_TOOL, contracts_1.ConversationStatus.FAILED, contracts_1.ConversationStatus.CANCELLED],
+    [contracts_1.ConversationStatus.FAILED]: [contracts_1.ConversationStatus.RUNNING, contracts_1.ConversationStatus.WAITING_TOOL, contracts_1.ConversationStatus.CANCELLED],
+    [contracts_1.ConversationStatus.CANCELLED]: [contracts_1.ConversationStatus.RUNNING]
+};
+class StatusMachine {
+    status = contracts_1.ConversationStatus.IDLE;
+    get current() {
+        return this.status;
+    }
+    isTerminal() {
+        return contracts_1.TERMINAL_CONVERSATION_STATUSES.has(this.status);
+    }
+    transitionTo(next) {
+        if (this.status === next) {
+            return this.status;
+        }
+        const allowed = ALLOWED_TRANSITIONS[this.status];
+        if (!allowed.includes(next)) {
+            throw new Error(`Invalid conversation status transition: ${this.status} -> ${next}`);
+        }
+        this.status = next;
+        return this.status;
+    }
+}
+exports.StatusMachine = StatusMachine;
+//# sourceMappingURL=status-machine.class.js.map

package/dist/libs/status-machine.class.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-machine.class.js","sourceRoot":"","sources":["../../src/libs/status-machine.class.ts"],"names":[],"mappings":";;;AAAA,4CAAkF;AAElF,MAAM,mBAAmB,GAAqD;IAC5E,CAAC,8BAAkB,CAAC,IAAI,CAAC,EAAE;QACzB,8BAAkB,CAAC,OAAO;QAC1B,8BAAkB,CAAC,WAAW;QAC9B,8BAAkB,CAAC,SAAS;KAC7B;IACD,CAAC,8BAAkB,CAAC,OAAO,CAAC,EAAE;QAC5B,8BAAkB,CAAC,YAAY;QAC/B,8BAAkB,CAAC,WAAW;QAC9B,8BAAkB,CAAC,SAAS;QAC5B,8BAAkB,CAAC,MAAM;QACzB,8BAAkB,CAAC,SAAS;KAC7B;IACD,CAAC,8BAAkB,CAAC,YAAY,CAAC,EAAE;QACjC,8BAAkB,CAAC,OAAO;QAC1B,8BAAkB,CAAC,WAAW;QAC9B,8BAAkB,CAAC,SAAS;QAC5B,8BAAkB,CAAC,MAAM;QACzB,8BAAkB,CAAC,SAAS;KAC7B;IACD,CAAC,8BAAkB,CAAC,WAAW,CAAC,EAAE;QAChC,8BAAkB,CAAC,OAAO;QAC1B,8BAAkB,CAAC,MAAM;QACzB,8BAAkB,CAAC,SAAS;KAC7B;IACD,CAAC,8BAAkB,CAAC,SAAS,CAAC,EAAE,CAAC,8BAAkB,CAAC,OAAO,EAAE,8BAAkB,CAAC,YAAY,EAAE,8BAAkB,CAAC,MAAM,EAAE,8BAAkB,CAAC,SAAS,CAAC;IACtJ,CAAC,8BAAkB,CAAC,MAAM,CAAC,EAAE,CAAC,8BAAkB,CAAC,OAAO,EAAE,8BAAkB,CAAC,YAAY,EAAE,8BAAkB,CAAC,SAAS,CAAC;IACxH,CAAC,8BAAkB,CAAC,SAAS,CAAC,EAAE,CAAC,8BAAkB,CAAC,OAAO,CAAC;CAC7D,CAAC;AAEF,MAAa,aAAa;IAChB,MAAM,GAAuB,8BAAkB,CAAC,IAAI,CAAC;IAE7D,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,UAAU;QACR,OAAO,0CAA8B,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACzD,CAAC;IAED,YAAY,CAAC,IAAwB;QACnC,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC,MAAM,CAAC;QACrB,CAAC;QAED,MAAM,OAAO,GAAG,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACjD,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,2CAA2C,IAAI,CAAC,MAAM,OAAO,IAAI,EAAE,CAAC,CAAC;QACvF,CAAC;QAED,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;CACF;AAxBD,sCAwBC"}

package/dist/libs/stream-emitter.class.d.ts

@@ -0,0 +1,9 @@
+import { ConversationCallbacks } from "../contracts";
+import { ConversationEventsBus } from "../events/conversation-events.bus";
+export declare class StreamEmitter {
+    private readonly subscription;
+    constructor(bus: ConversationEventsBus, callbacks: ConversationCallbacks);
+    dispose(): void;
+    private routeEvent;
+}
+//# sourceMappingURL=stream-emitter.class.d.ts.map

package/dist/libs/stream-emitter.class.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-emitter.class.d.ts","sourceRoot":"","sources":["../../src/libs/stream-emitter.class.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAqB,MAAM,cAAc,CAAC;AACxE,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;gBAG1C,GAAG,EAAE,qBAAqB,EAC1B,SAAS,EAAE,qBAAqB;IAKlC,OAAO,IAAI,IAAI;IAIf,OAAO,CAAC,UAAU;CAmDnB"}

package/dist/libs/stream-emitter.class.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamEmitter = void 0;
+class StreamEmitter {
+    subscription;
+    constructor(bus, callbacks) {
+        this.subscription = bus.events$.subscribe((event) => this.routeEvent(event, callbacks));
+    }
+    dispose() {
+        this.subscription.unsubscribe();
+    }
+    routeEvent(event, callbacks) {
+        callbacks.onEvent?.(event);
+        if (event.type === "stream_chunk") {
+            callbacks.onMessagePushStream?.({
+                contentDelta: event.contentDelta,
+                fullContent: event.fullContent,
+                thinkingDelta: event.thinkingDelta,
+                fullThinking: event.fullThinking,
+                done: event.done,
+                metadata: event.metadata,
+            });
+            return;
+        }
+        if (event.type === "stream_mode") {
+            callbacks.onStreamMode?.({
+                mode: event.mode,
+                name: event.name,
+                payload: event.payload,
+            });
+            return;
+        }
+        if (event.type === "status_changed") {
+            callbacks.onStatusChange?.(event.status);
+            return;
+        }
+        if (event.type === "tool_event") {
+            callbacks.onToolEvent?.(event.tool);
+            return;
+        }
+        if (event.type === "interrupt") {
+            callbacks.onInterrupt?.(event.interrupt);
+            return;
+        }
+        if (event.type === "interrupt_resolved") {
+            callbacks.onInterruptResolved?.({
+                interruptId: event.interruptId,
+                decisions: event.decisions,
+            });
+            return;
+        }
+        if (event.type === "error") {
+            callbacks.onError?.(new Error(event.error));
+        }
+    }
+}
+exports.StreamEmitter = StreamEmitter;
+//# sourceMappingURL=stream-emitter.class.js.map

package/dist/libs/stream-emitter.class.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-emitter.class.js","sourceRoot":"","sources":["../../src/libs/stream-emitter.class.ts"],"names":[],"mappings":";;;AAIA,MAAa,aAAa;IACP,YAAY,CAAe;IAE5C,YACE,GAA0B,EAC1B,SAAgC;QAEhC,IAAI,CAAC,YAAY,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC;IAC1F,CAAC;IAED,OAAO;QACL,IAAI,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC;IAClC,CAAC;IAEO,UAAU,CAAC,KAAwB,EAAE,SAAgC;QAC3E,SAAS,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;QAE3B,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;YAClC,SAAS,CAAC,mBAAmB,EAAE,CAAC;gBAC9B,YAAY,EAAE,KAAK,CAAC,YAAY;gBAChC,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,aAAa,EAAE,KAAK,CAAC,aAAa;gBAClC,YAAY,EAAE,KAAK,CAAC,YAAY;gBAChC,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ;aACzB,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,IAAI,KAAK,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;YACjC,SAAS,CAAC,YAAY,EAAE,CAAC;gBACvB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,OAAO,EAAE,KAAK,CAAC,OAAO;aACvB,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,IAAI,KAAK,CAAC,IAAI,KAAK,gBAAgB,EAAE,CAAC;YACpC,SAAS,CAAC,cAAc,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YACzC,OAAO;QACT,CAAC;QAED,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YAChC,SAAS,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACpC,OAAO;QACT,CAAC;QAED,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YAC/B,SAAS,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;YACzC,OAAO;QACT,CAAC;QAED,IAAI,KAAK,CAAC,IAAI,KAAK,oBAAoB,EAAE,CAAC;YACxC,SAAS,CAAC,mBAAmB,EAAE,CAAC;gBAC9B,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,SAAS,EAAE,KAAK,CAAC,SAAS;aAC3B,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC3B,SAAS,CAAC,OAAO,EAAE,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;CACF;AAjED,sCAiEC"}

package/dist/libs/streaming-iterator.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Streaming iteration control with backpressure management
+ * Handles token flow, rate limiting, and buffer overflow scenarios
+ */
+/**
+ * Backpressure strategy for handling overflow
+ */
+export type BackpressureStrategy = "drop" | "wait" | "buffer";
+/**
+ * Configuration for streaming iteration
+ */
+export interface StreamIterationConfig {
+    /** Maximum tokens per second (throughput rate limiting) */
+    maxTokensPerSecond?: number;
+    /** Maximum items in buffer before applying backpressure */
+    maxBufferSize?: number;
+    /** Strategy when buffer is full: drop, wait, or buffer */
+    backpressureStrategy?: BackpressureStrategy;
+    /** Timeout for wait strategy in milliseconds */
+    backpressureTimeoutMs?: number;
+    /** Enable adaptive rate limiting based on downstream speed */
+    adaptiveRateLimit?: boolean;
+    /** Pause iteration automatically if buffer reaches threshold */
+    autoPause?: boolean;
+    /** Resume iteration when buffer drops below this percentage */
+    resumeThreshold?: number;
+}
+/**
+ * Metrics for a streaming iteration
+ */
+export interface StreamIterationMetrics {
+    /** Total items yielded */
+    itemsYielded: number;
+    /** Total items dropped (backpressure) */
+    itemsDropped: number;
+    /** Total wait time due to backpressure */
+    backpressureWaitMs: number;
+    /** Current buffer size */
+    bufferSize: number;
+    /** Items per second throughput */
+    itemsPerSecond: number;
+    /** Current iteration state */
+    isPaused: boolean;
+    /** Average item processing time */
+    avgProcessingTimeMs: number;
+    /** Peak buffer size observed */
+    peakBufferSize: number;
+}
+/**
+ * Status change event
+ */
+export interface IterationStatusChange {
+    previousStatus: "running" | "paused" | "stopped";
+    newStatus: "running" | "paused" | "stopped";
+    reason: string;
+    timestamp: Date;
+}
+/**
+ * StreamingIterator manages iteration with backpressure control
+ * Prevents downstream bottlenecks from overloading the system
+ *
+ * Usage:
+ *   const iterator = new StreamingIterator(sourceGenerator);
+ *   iterator.setConfig({ maxTokensPerSecond: 100, maxBufferSize: 10 });
+ *   for await (const item of iterator) {
+ *     // Process item
+ *   }
+ */
+export declare class StreamingIterator<T> {
+    private readonly source;
+    private config;
+    private buffer;
+    private isPaused;
+    private isStopped;
+    private lastYieldTime;
+    private startTime;
+    private itemsYielded;
+    private itemsDropped;
+    private totalWaitTimeMs;
+    private processingTimes;
+    private peakBufferSize;
+    private statusCallbacks;
+    private tokenBucket;
+    private lastTokenRefillTime;
+    constructor(source: AsyncIterable<T>, config?: Partial<StreamIterationConfig>);
+    /**
+     * Update streaming configuration
+     */
+    setConfig(config: Partial<StreamIterationConfig>): void;
+    /**
+     * Refill token bucket based on elapsed time
+     */
+    private refillTokenBucket;
+    /**
+     * Check if we can yield an item (rate limiting)
+     */
+    private checkRateLimit;
+    /**
+     * Check and handle backpressure
+     */
+    private handleBackpressure;
+    /**
+     * Pause iteration
+     */
+    setPaused(paused: boolean, reason?: string): void;
+    /**
+     * Notify status change callbacks
+     */
+    private notifyStatusChange;
+    /**
+     * Register callback for status changes
+     */
+    onStatusChange(callback: (status: IterationStatusChange) => void): void;
+    /**
+     * Main iteration method
+     */
+    iterate(): AsyncGenerator<T, void, unknown>;
+    /**
+     * Get current metrics
+     */
+    getMetrics(): StreamIterationMetrics;
+    /**
+     * Stop iteration
+     */
+    stop(): void;
+    /**
+     * Get current state
+     */
+    getState(): {
+        isPaused: boolean;
+        isStopped: boolean;
+        bufferSize: number;
+        metrics: StreamIterationMetrics;
+    };
+}
+//# sourceMappingURL=streaming-iterator.d.ts.map

package/dist/libs/streaming-iterator.d.ts.map

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

package/dist/libs/streaming-iterator.js

@@ -0,0 +1,248 @@
+"use strict";
+/**
+ * Streaming iteration control with backpressure management
+ * Handles token flow, rate limiting, and buffer overflow scenarios
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamingIterator = void 0;
+/**
+ * StreamingIterator manages iteration with backpressure control
+ * Prevents downstream bottlenecks from overloading the system
+ *
+ * Usage:
+ *   const iterator = new StreamingIterator(sourceGenerator);
+ *   iterator.setConfig({ maxTokensPerSecond: 100, maxBufferSize: 10 });
+ *   for await (const item of iterator) {
+ *     // Process item
+ *   }
+ */
+class StreamingIterator {
+    source;
+    config;
+    buffer = [];
+    isPaused = false;
+    isStopped = false;
+    lastYieldTime = Date.now();
+    startTime = Date.now();
+    itemsYielded = 0;
+    itemsDropped = 0;
+    totalWaitTimeMs = 0;
+    processingTimes = [];
+    peakBufferSize = 0;
+    statusCallbacks = [];
+    tokenBucket = 0;
+    lastTokenRefillTime = Date.now();
+    constructor(source, config = {}) {
+        this.source = source;
+        this.config = {
+            maxTokensPerSecond: config.maxTokensPerSecond ?? 1000,
+            maxBufferSize: config.maxBufferSize ?? 100,
+            backpressureStrategy: config.backpressureStrategy ?? "wait",
+            backpressureTimeoutMs: config.backpressureTimeoutMs ?? 5000,
+            adaptiveRateLimit: config.adaptiveRateLimit ?? false,
+            autoPause: config.autoPause ?? false,
+            resumeThreshold: config.resumeThreshold ?? 0.5,
+        };
+        this.tokenBucket = this.config.maxTokensPerSecond;
+    }
+    /**
+     * Update streaming configuration
+     */
+    setConfig(config) {
+        this.config = {
+            ...this.config,
+            ...config,
+            maxTokensPerSecond: config.maxTokensPerSecond ?? this.config.maxTokensPerSecond,
+            maxBufferSize: config.maxBufferSize ?? this.config.maxBufferSize,
+            backpressureStrategy: config.backpressureStrategy ?? this.config.backpressureStrategy,
+            backpressureTimeoutMs: config.backpressureTimeoutMs ?? this.config.backpressureTimeoutMs,
+            adaptiveRateLimit: config.adaptiveRateLimit ?? this.config.adaptiveRateLimit,
+            autoPause: config.autoPause ?? this.config.autoPause,
+            resumeThreshold: config.resumeThreshold ?? this.config.resumeThreshold,
+        };
+    }
+    /**
+     * Refill token bucket based on elapsed time
+     */
+    refillTokenBucket() {
+        const now = Date.now();
+        const elapsedSeconds = (now - this.lastTokenRefillTime) / 1000;
+        const tokensToAdd = elapsedSeconds * this.config.maxTokensPerSecond;
+        this.tokenBucket = Math.min(this.config.maxTokensPerSecond, this.tokenBucket + tokensToAdd);
+        this.lastTokenRefillTime = now;
+    }
+    /**
+     * Check if we can yield an item (rate limiting)
+     */
+    async checkRateLimit() {
+        this.refillTokenBucket();
+        // If we don't have tokens, wait for them
+        if (this.tokenBucket < 1) {
+            const waitMs = (1 - this.tokenBucket) / (this.config.maxTokensPerSecond / 1000);
+            this.totalWaitTimeMs += waitMs;
+            await new Promise((resolve) => setTimeout(resolve, waitMs));
+            this.refillTokenBucket();
+        }
+        // Consume a token
+        this.tokenBucket--;
+    }
+    /**
+     * Check and handle backpressure
+     */
+    async handleBackpressure() {
+        if (this.buffer.length < this.config.maxBufferSize) {
+            return; // No backpressure
+        }
+        // Auto-pause if enabled
+        if (this.config.autoPause && !this.isPaused) {
+            this.setPaused(true, "Auto-paused due to buffer overflow");
+        }
+        const strategy = this.config.backpressureStrategy;
+        if (strategy === "drop") {
+            // Drop oldest item
+            this.buffer.shift();
+            this.itemsDropped++;
+        }
+        else if (strategy === "wait") {
+            // Wait for consumer to drain buffer
+            const waitStartTime = Date.now();
+            let waited = 0;
+            while (this.buffer.length >= this.config.maxBufferSize &&
+                waited < this.config.backpressureTimeoutMs) {
+                await new Promise((resolve) => setTimeout(resolve, 10));
+                waited = Date.now() - waitStartTime;
+            }
+            this.totalWaitTimeMs += waited;
+            if (waited >= this.config.backpressureTimeoutMs) {
+                throw new Error("Backpressure timeout: consumer not draining buffer");
+            }
+        }
+        else if (strategy === "buffer") {
+            // Allow unlimited buffering (risky, use with caution)
+            // Just continue without waiting
+        }
+    }
+    /**
+     * Pause iteration
+     */
+    setPaused(paused, reason = "") {
+        if (paused === this.isPaused) {
+            return; // Already in this state
+        }
+        const previousStatus = this.isPaused ? "paused" : "running";
+        this.isPaused = paused;
+        const newStatus = paused ? "paused" : "running";
+        this.notifyStatusChange(previousStatus, newStatus, reason);
+        // Check resume threshold
+        if (!paused && this.config.autoPause) {
+            const resumeThreshold = this.config.maxBufferSize * this.config.resumeThreshold;
+            if (this.buffer.length > resumeThreshold) {
+                this.isPaused = true;
+                this.notifyStatusChange("running", "paused", "Buffer still above resume threshold");
+            }
+        }
+    }
+    /**
+     * Notify status change callbacks
+     */
+    notifyStatusChange(previousStatus, newStatus, reason) {
+        const status = {
+            previousStatus,
+            newStatus,
+            reason,
+            timestamp: new Date(),
+        };
+        this.statusCallbacks.forEach((cb) => cb(status));
+    }
+    /**
+     * Register callback for status changes
+     */
+    onStatusChange(callback) {
+        this.statusCallbacks.push(callback);
+    }
+    /**
+     * Main iteration method
+     */
+    async *iterate() {
+        try {
+            for await (const item of this.source) {
+                if (this.isStopped) {
+                    break;
+                }
+                // Wait if paused
+                while (this.isPaused && !this.isStopped) {
+                    await new Promise((resolve) => setTimeout(resolve, 10));
+                }
+                if (this.isStopped) {
+                    break;
+                }
+                // Check rate limiting BEFORE buffering
+                await this.checkRateLimit();
+                // Handle backpressure before adding to buffer
+                await this.handleBackpressure();
+                // Track metrics
+                const processingStartTime = Date.now();
+                this.itemsYielded++;
+                this.lastYieldTime = Date.now();
+                const processingTime = Date.now() - processingStartTime;
+                this.processingTimes.push(processingTime);
+                // Keep only last 100 entries
+                if (this.processingTimes.length > 100) {
+                    this.processingTimes.shift();
+                }
+                // Auto-resume if buffer is below threshold
+                if (this.isPaused && this.config.autoPause) {
+                    const resumeThreshold = this.config.maxBufferSize * this.config.resumeThreshold;
+                    if (this.buffer.length < resumeThreshold) {
+                        this.setPaused(false, "Buffer below resume threshold");
+                    }
+                }
+                yield item;
+            }
+        }
+        finally {
+            this.isStopped = true;
+            this.notifyStatusChange("running", "stopped", "Iteration completed");
+        }
+    }
+    /**
+     * Get current metrics
+     */
+    getMetrics() {
+        const elapsedSeconds = (Date.now() - this.startTime) / 1000;
+        const itemsPerSecond = elapsedSeconds > 0 ? this.itemsYielded / elapsedSeconds : 0;
+        const avgProcessingTimeMs = this.processingTimes.length > 0
+            ? this.processingTimes.reduce((a, b) => a + b, 0) /
+                this.processingTimes.length
+            : 0;
+        return {
+            itemsYielded: this.itemsYielded,
+            itemsDropped: this.itemsDropped,
+            backpressureWaitMs: this.totalWaitTimeMs,
+            bufferSize: this.buffer.length,
+            itemsPerSecond,
+            isPaused: this.isPaused,
+            avgProcessingTimeMs,
+            peakBufferSize: this.peakBufferSize,
+        };
+    }
+    /**
+     * Stop iteration
+     */
+    stop() {
+        this.isStopped = true;
+    }
+    /**
+     * Get current state
+     */
+    getState() {
+        return {
+            isPaused: this.isPaused,
+            isStopped: this.isStopped,
+            bufferSize: this.buffer.length,
+            metrics: this.getMetrics(),
+        };
+    }
+}
+exports.StreamingIterator = StreamingIterator;
+//# sourceMappingURL=streaming-iterator.js.map

package/dist/libs/streaming-iterator.js.map

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

package/dist/libs/structured-call.d.ts

@@ -0,0 +1,40 @@
+/**
+ * structured-call.ts
+ *
+ * Framework-agnostic callStructured<T> and callStructuredStreaming<T> helpers.
+ * These run a single-turn LlmAdapter request in JSON mode and validate with Zod.
+ */
+import { ZodSchema } from "zod";
+import { LlmAdapter } from "../contracts/llm.types";
+export interface StructuredCallOptions {
+    temperature?: number;
+    numCtx?: number;
+    thinking?: boolean;
+    signal?: AbortSignal;
+    seed?: number;
+}
+export interface StructuredCallResult<T> {
+    result: T;
+    thinking?: string;
+    tokensInput?: number;
+    tokensOutput?: number;
+}
+export declare function callStructured<T>(adapter: LlmAdapter, model: string, systemPrompt: string, userPrompt: string, schema: ZodSchema<T>, options?: StructuredCallOptions): Promise<StructuredCallResult<T>>;
+export declare function callStructuredStreaming<T>(adapter: LlmAdapter, model: string, systemPrompt: string, userPrompt: string, schema: ZodSchema<T>, options?: StructuredCallOptions, onToken?: (token: string, fullText: string) => void): Promise<StructuredCallResult<T>>;
+/**
+ * Recursively fill misid: "s", createdAt: NOW(), content: systemPrompt },
+        { role: "user" as const, id: "u", createdAt: NOW()ing required fields in `data` with type-appropriate
+ * defaults so that schema.parse() doesn't throw on partially-filled objects.
+ */
+export declare function fillSchemaDefaults(data: any, schema: ZodSchema): any;
+/**
+ * Generate a human-readable JSON schema description from a Zod schema.
+ * Appended to the user prompt so the LLM knows what fields to produce.
+ */
+export declare function describeZodSchema(schema: ZodSchema): string;
+/**
+ * Convert a Zod schema to a minimal JSON Schema representation
+ * for providers that support structured output via responseSchema.
+ */
+export declare function zodToJsonSchema(schema: ZodSchema): Record<string, unknown> | undefined;
+//# sourceMappingURL=structured-call.d.ts.map

package/dist/libs/structured-call.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-call.d.ts","sourceRoot":"","sources":["../../src/libs/structured-call.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAUL,SAAS,EAEV,MAAM,KAAK,CAAC;AACb,OAAO,EAAE,UAAU,EAAkB,MAAM,wBAAwB,CAAC;AAGpE,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,MAAM,EAAE,CAAC,CAAC;IACV,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAID,wBAAsB,cAAc,CAAC,CAAC,EACpC,OAAO,EAAE,UAAU,EACnB,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAqElC;AAED,wBAAsB,uBAAuB,CAAC,CAAC,EAC7C,OAAO,EAAE,UAAU,EACnB,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,EAAE,qBAAqB,EAC/B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,GAClD,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAwClC;AAwBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,GAAG,GAAG,CAqDpE;AAgDD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAQ3D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CA2BtF"}