@thoughtflow/core 0.1.2

package/dist/libs/knowledge-graph.class.js

@@ -0,0 +1,406 @@
+"use strict";
+/**
+ * KnowledgeGraph — Phase 1
+ *
+ * Persistent, queryable graph of entities spanning 3 knowledge sources:
+ *   Source 1: Business documents (.md files, plans, notes)
+ *   Source 2: Code structure (AST symbols, dependency tree)
+ *   Source 3: Behavioral understanding (LLM-inferred relationships)
+ *
+ * Features:
+ *   - Node CRUD with typed properties
+ *   - Edge CRUD with relation types + confidence scores
+ *   - Bidirectional traversal (outgoing, incoming, both)
+ *   - Neighborhood extraction (N-hop subgraph)
+ *   - Path finding between nodes
+ *   - Snapshot for divergence detection
+ *   - Statistics
+ *
+ * Backed by two IStorageAdapter instances (nodes, edges).
+ * Default: InMemoryAdapter. Users provide SQLite/Postgres for persistence.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KnowledgeGraph = void 0;
+const crypto_1 = require("crypto");
+const in_memory_adapter_1 = require("../storage/in-memory.adapter");
+// ── KnowledgeGraph ──────────────────────────────────────────────────────────
+class KnowledgeGraph {
+    nodes;
+    edges;
+    constructor(nodeAdapter, edgeAdapter) {
+        this.nodes = nodeAdapter ?? new in_memory_adapter_1.InMemoryAdapter();
+        this.edges = edgeAdapter ?? new in_memory_adapter_1.InMemoryAdapter();
+    }
+    // ── Node CRUD ───────────────────────────────────────────────────────────
+    async addNode(input) {
+        const now = new Date().toISOString();
+        return this.nodes.create({
+            ...input,
+            createdAt: now,
+            updatedAt: now,
+        });
+    }
+    async getNode(id) {
+        return this.nodes.read(id);
+    }
+    async updateNode(id, patch) {
+        return this.nodes.update(id, {
+            ...patch,
+            updatedAt: new Date().toISOString(),
+        });
+    }
+    async removeNode(id) {
+        // Remove all edges connected to this node
+        const connected = await this.getEdgesForNode(id);
+        for (const edge of connected) {
+            await this.edges.delete(edge.id);
+        }
+        await this.nodes.delete(id);
+    }
+    // ── Edge CRUD ───────────────────────────────────────────────────────────
+    async addEdge(input) {
+        // Validate that both nodes exist
+        const [fromNode, toNode] = await Promise.all([
+            this.nodes.read(input.fromId),
+            this.nodes.read(input.toId),
+        ]);
+        if (!fromNode)
+            throw new Error(`KnowledgeGraph: source node '${input.fromId}' not found`);
+        if (!toNode)
+            throw new Error(`KnowledgeGraph: target node '${input.toId}' not found`);
+        const now = new Date().toISOString();
+        return this.edges.create({
+            ...input,
+            createdAt: now,
+            updatedAt: now,
+        });
+    }
+    async getEdge(id) {
+        return this.edges.read(id);
+    }
+    async updateEdge(id, patch) {
+        return this.edges.update(id, {
+            ...patch,
+            updatedAt: new Date().toISOString(),
+        });
+    }
+    async removeEdge(id) {
+        await this.edges.delete(id);
+    }
+    // ── Queries ─────────────────────────────────────────────────────────────
+    async queryNodes(options = {}) {
+        let results = await this.nodes.list();
+        if (options.types?.length) {
+            const types = new Set(options.types);
+            results = results.filter((n) => types.has(n.type));
+        }
+        if (options.source) {
+            results = results.filter((n) => n.source === options.source);
+        }
+        if (options.tags?.length) {
+            const required = options.tags;
+            results = results.filter((n) => required.every((tag) => n.tags?.includes(tag)));
+        }
+        if (options.search) {
+            const q = options.search.toLowerCase();
+            results = results.filter((n) => n.name.toLowerCase().includes(q) ||
+                n.description.toLowerCase().includes(q));
+        }
+        if (options.sourceFile) {
+            results = results.filter((n) => n.sourceFile === options.sourceFile);
+        }
+        if (options.minConfidence !== undefined) {
+            const min = options.minConfidence;
+            results = results.filter((n) => (n.confidence ?? 1) >= min);
+        }
+        if (options.offset) {
+            results = results.slice(options.offset);
+        }
+        if (options.limit !== undefined) {
+            results = results.slice(0, options.limit);
+        }
+        return results;
+    }
+    async queryEdges(options = {}) {
+        let results = await this.edges.list();
+        if (options.types?.length) {
+            const types = new Set(options.types);
+            results = results.filter((e) => types.has(e.type));
+        }
+        if (options.fromId) {
+            results = results.filter((e) => e.fromId === options.fromId);
+        }
+        if (options.toId) {
+            results = results.filter((e) => e.toId === options.toId);
+        }
+        if (options.minConfidence !== undefined) {
+            const min = options.minConfidence;
+            results = results.filter((e) => e.confidence >= min);
+        }
+        if (options.offset) {
+            results = results.slice(options.offset);
+        }
+        if (options.limit !== undefined) {
+            results = results.slice(0, options.limit);
+        }
+        return results;
+    }
+    // ── Traversal ─────────────────────────────────────────────────────────
+    /**
+     * Get all edges connected to a node (outgoing, incoming, or both).
+     */
+    async getEdgesForNode(nodeId, direction = "both") {
+        const allEdges = await this.edges.list();
+        return allEdges.filter((e) => {
+            if (direction === "outgoing")
+                return e.fromId === nodeId;
+            if (direction === "incoming")
+                return e.toId === nodeId;
+            return e.fromId === nodeId || e.toId === nodeId;
+        });
+    }
+    /**
+     * Get direct neighbors of a node.
+     */
+    async getNeighbors(nodeId, direction = "both") {
+        const edges = await this.getEdgesForNode(nodeId, direction);
+        const neighborIds = new Set();
+        for (const e of edges) {
+            if (e.fromId === nodeId)
+                neighborIds.add(e.toId);
+            if (e.toId === nodeId)
+                neighborIds.add(e.fromId);
+        }
+        const neighbors = [];
+        for (const id of neighborIds) {
+            const node = await this.nodes.read(id);
+            if (node)
+                neighbors.push(node);
+        }
+        return neighbors;
+    }
+    /**
+     * Extract a subgraph around a center node within N hops.
+     */
+    async getNeighborhood(centerId, options = {}) {
+        const maxDepth = options.depth ?? 1;
+        const direction = options.direction ?? "both";
+        const visitedNodes = new Set();
+        const collectedEdges = new Set();
+        const frontier = [centerId];
+        visitedNodes.add(centerId);
+        for (let depth = 0; depth < maxDepth && frontier.length > 0; depth++) {
+            const nextFrontier = [];
+            for (const nodeId of frontier) {
+                const edges = await this.getEdgesForNode(nodeId, direction);
+                for (const edge of edges) {
+                    // Filter by edge types
+                    if (options.edgeTypes?.length && !options.edgeTypes.includes(edge.type)) {
+                        continue;
+                    }
+                    collectedEdges.add(edge.id);
+                    const neighborId = edge.fromId === nodeId ? edge.toId : edge.fromId;
+                    if (!visitedNodes.has(neighborId)) {
+                        visitedNodes.add(neighborId);
+                        nextFrontier.push(neighborId);
+                    }
+                }
+            }
+            frontier.length = 0;
+            frontier.push(...nextFrontier);
+        }
+        // Collect nodes
+        const nodesList = [];
+        for (const id of visitedNodes) {
+            const node = await this.nodes.read(id);
+            if (node) {
+                // Filter by node types
+                if (options.nodeTypes?.length && !options.nodeTypes.includes(node.type)) {
+                    continue;
+                }
+                nodesList.push(node);
+            }
+        }
+        // Collect edges (only those connecting collected nodes)
+        const nodeIdSet = new Set(nodesList.map((n) => n.id));
+        const edgesList = [];
+        for (const edgeId of collectedEdges) {
+            const edge = await this.edges.read(edgeId);
+            if (edge && nodeIdSet.has(edge.fromId) && nodeIdSet.has(edge.toId)) {
+                edgesList.push(edge);
+            }
+        }
+        return { nodes: nodesList, edges: edgesList };
+    }
+    /**
+     * Find shortest path between two nodes using BFS.
+     * Returns null if no path exists.
+     */
+    async findPath(startId, endId, edgeTypes) {
+        if (startId === endId) {
+            return { nodes: [startId], edges: [], confidence: 1 };
+        }
+        const allEdges = await this.edges.list();
+        // Build adjacency list
+        const adjacency = new Map();
+        for (const edge of allEdges) {
+            if (edgeTypes?.length && !edgeTypes.includes(edge.type))
+                continue;
+            if (!adjacency.has(edge.fromId))
+                adjacency.set(edge.fromId, []);
+            if (!adjacency.has(edge.toId))
+                adjacency.set(edge.toId, []);
+            adjacency.get(edge.fromId).push({
+                neighborId: edge.toId,
+                edgeId: edge.id,
+                confidence: edge.confidence,
+            });
+            adjacency.get(edge.toId).push({
+                neighborId: edge.fromId,
+                edgeId: edge.id,
+                confidence: edge.confidence,
+            });
+        }
+        // BFS
+        const visited = new Set([startId]);
+        const queue = [
+            { nodeId: startId, path: [startId], edgePath: [], confidence: 1 },
+        ];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            const neighbors = adjacency.get(current.nodeId) ?? [];
+            for (const { neighborId, edgeId, confidence } of neighbors) {
+                if (visited.has(neighborId))
+                    continue;
+                visited.add(neighborId);
+                const newPath = [...current.path, neighborId];
+                const newEdgePath = [...current.edgePath, edgeId];
+                const newConfidence = current.confidence * confidence;
+                if (neighborId === endId) {
+                    return {
+                        nodes: newPath,
+                        edges: newEdgePath,
+                        confidence: newConfidence,
+                    };
+                }
+                queue.push({
+                    nodeId: neighborId,
+                    path: newPath,
+                    edgePath: newEdgePath,
+                    confidence: newConfidence,
+                });
+            }
+        }
+        return null;
+    }
+    // ── Bulk operations ───────────────────────────────────────────────────
+    /**
+     * Find nodes that have no edges connected to them.
+     */
+    async getDisconnectedNodes() {
+        const allNodes = await this.nodes.list();
+        const allEdges = await this.edges.list();
+        const connectedIds = new Set();
+        for (const edge of allEdges) {
+            connectedIds.add(edge.fromId);
+            connectedIds.add(edge.toId);
+        }
+        return allNodes.filter((n) => !connectedIds.has(n.id));
+    }
+    /**
+     * Get all nodes that a given node can reach via a specific edge type.
+     * Useful for: "find all code that implements business concept X"
+     */
+    async getTransitiveClosure(startId, edgeType, direction = "outgoing") {
+        const visited = new Set();
+        const frontier = [startId];
+        visited.add(startId);
+        while (frontier.length > 0) {
+            const current = frontier.shift();
+            const edges = await this.getEdgesForNode(current, direction);
+            for (const edge of edges) {
+                if (edge.type !== edgeType)
+                    continue;
+                const nextId = direction === "outgoing" ? edge.toId : edge.fromId;
+                if (!visited.has(nextId)) {
+                    visited.add(nextId);
+                    frontier.push(nextId);
+                }
+            }
+        }
+        // Remove start node, collect results
+        visited.delete(startId);
+        const result = [];
+        for (const id of visited) {
+            const node = await this.nodes.read(id);
+            if (node)
+                result.push(node);
+        }
+        return result;
+    }
+    // ── Snapshot ──────────────────────────────────────────────────────────
+    /**
+     * Create a snapshot of the current graph state for divergence detection.
+     */
+    async takeSnapshot(metadata) {
+        const allNodes = await this.nodes.list();
+        const allEdges = await this.edges.list();
+        const nodeIds = allNodes.map((n) => n.id).sort();
+        const edgeIds = allEdges.map((e) => e.id).sort();
+        const hash = (0, crypto_1.createHash)("sha256");
+        hash.update(JSON.stringify({ nodeIds, edgeIds }));
+        const contentHash = hash.digest("hex");
+        return {
+            id: (0, crypto_1.randomUUID)(),
+            takenAt: new Date().toISOString(),
+            nodeCount: allNodes.length,
+            edgeCount: allEdges.length,
+            contentHash,
+            nodeIds,
+            edgeIds,
+            metadata,
+        };
+    }
+    // ── Statistics ────────────────────────────────────────────────────────
+    async getStatistics() {
+        const allNodes = await this.nodes.list();
+        const allEdges = await this.edges.list();
+        const nodesByType = {};
+        const edgesByType = {};
+        const nodesBySource = {};
+        for (const node of allNodes) {
+            nodesByType[node.type] = (nodesByType[node.type] ?? 0) + 1;
+            nodesBySource[node.source] = (nodesBySource[node.source] ?? 0) + 1;
+        }
+        for (const edge of allEdges) {
+            edgesByType[edge.type] = (edgesByType[edge.type] ?? 0) + 1;
+        }
+        const confidenceSum = allEdges.reduce((sum, e) => sum + e.confidence, 0);
+        const connectedIds = new Set();
+        for (const edge of allEdges) {
+            connectedIds.add(edge.fromId);
+            connectedIds.add(edge.toId);
+        }
+        const disconnectedNodes = allNodes.filter((n) => !connectedIds.has(n.id)).length;
+        return {
+            totalNodes: allNodes.length,
+            totalEdges: allEdges.length,
+            nodesByType,
+            edgesByType,
+            nodesBySource,
+            avgConfidence: allEdges.length > 0 ? confidenceSum / allEdges.length : 0,
+            disconnectedNodes,
+        };
+    }
+    // ── Clear ─────────────────────────────────────────────────────────────
+    async clear() {
+        const allNodes = await this.nodes.list();
+        const allEdges = await this.edges.list();
+        for (const edge of allEdges)
+            await this.edges.delete(edge.id);
+        for (const node of allNodes)
+            await this.nodes.delete(node.id);
+    }
+}
+exports.KnowledgeGraph = KnowledgeGraph;
+//# sourceMappingURL=knowledge-graph.class.js.map

package/dist/libs/knowledge-graph.class.js.map

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

package/dist/libs/llm-retry.d.ts

@@ -0,0 +1,47 @@
+/**
+ * LLM retry infrastructure: Retry-After header parsing, error taxonomy,
+ * and exponential backoff for transient provider failures.
+ *
+ * Modelled after opencode's session/retry.ts and session/overflow.ts patterns.
+ */
+/** High-level classification of LLM API errors. */
+export type LlmErrorKind = "rate_limited" | "overloaded" | "context_overflow" | "auth" | "unknown";
+/**
+ * Classify an HTTP error by status code and response body snippet.
+ * Returns `LlmErrorKind` to drive retry decisions.
+ */
+export declare function classifyLlmError(status: number, body: string): LlmErrorKind;
+/** True when `classifyLlmError` returned a retriable kind. */
+export declare function isLlmErrorRetryable(kind: LlmErrorKind): boolean;
+/**
+ * Parse `Retry-After` / `retry-after-ms` headers from a failed response
+ * and return the number of milliseconds to wait.
+ *
+ * Falls back to exponential backoff when no header is found.
+ */
+export declare function extractRetryDelayMs(headers: Headers, attempt: number): number;
+export interface LlmRetryConfig {
+    /** Maximum number of retry attempts (not counting the initial request). Default: 3 */
+    maxRetries?: number;
+}
+/** Error thrown when a non-retryable LLM error is detected. */
+export declare class LlmApiError extends Error {
+    readonly kind: LlmErrorKind;
+    readonly status: number;
+    readonly body: string;
+    constructor(kind: LlmErrorKind, status: number, body: string);
+}
+/**
+ * Wraps a `fetch`-compatible call with LLM-aware retry logic.
+ *
+ * - Reads `Retry-After` / `retry-after-ms` headers for 429 responses.
+ * - Classifies 400/401/403/503/529 and retries or throws immediately.
+ * - Respects `signal` for cancellation between retries.
+ *
+ * @param makeRequest - Factory that returns a `fetch` call (called on each attempt).
+ * @param config      - Optional retry configuration.
+ * @param signal      - Optional AbortSignal forwarded from the caller.
+ * @returns The successful `Response` object.
+ */
+export declare function fetchWithLlmRetry(makeRequest: () => Promise<Response>, config?: LlmRetryConfig, signal?: AbortSignal): Promise<Response>;
+//# sourceMappingURL=llm-retry.d.ts.map

package/dist/libs/llm-retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-retry.d.ts","sourceRoot":"","sources":["../../src/libs/llm-retry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,mDAAmD;AACnD,MAAM,MAAM,YAAY,GACpB,cAAc,GACd,YAAY,GACZ,kBAAkB,GAClB,MAAM,GACN,SAAS,CAAC;AAed;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAS3E;AAED,8DAA8D;AAC9D,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAE/D;AAeD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAwB7E;AAID,MAAM,WAAW,cAAc;IAC7B,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAmBD,+DAA+D;AAC/D,qBAAa,WAAY,SAAQ,KAAK;aAElB,IAAI,EAAE,YAAY;aAClB,MAAM,EAAE,MAAM;aACd,IAAI,EAAE,MAAM;gBAFZ,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM;CAK/B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,EACpC,MAAM,CAAC,EAAE,cAAc,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,QAAQ,CAAC,CAyBnB"}

package/dist/libs/llm-retry.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * LLM retry infrastructure: Retry-After header parsing, error taxonomy,
+ * and exponential backoff for transient provider failures.
+ *
+ * Modelled after opencode's session/retry.ts and session/overflow.ts patterns.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LlmApiError = void 0;
+exports.classifyLlmError = classifyLlmError;
+exports.isLlmErrorRetryable = isLlmErrorRetryable;
+exports.extractRetryDelayMs = extractRetryDelayMs;
+exports.fetchWithLlmRetry = fetchWithLlmRetry;
+/** Phrases that indicate context/token overflow in a 400 response body. */
+const OVERFLOW_PHRASES = [
+    "too many tokens",
+    "context length",
+    "maximum context",
+    "reduce the length",
+    "reduce your prompt",
+    "token limit",
+    "context_length_exceeded",
+    "context window",
+    "prompt_too_long",
+];
+/**
+ * Classify an HTTP error by status code and response body snippet.
+ * Returns `LlmErrorKind` to drive retry decisions.
+ */
+function classifyLlmError(status, body) {
+    if (status === 401 || status === 403)
+        return "auth";
+    if (status === 429)
+        return "rate_limited";
+    if (status === 503 || status === 529)
+        return "overloaded";
+    if (status === 400) {
+        const lower = body.toLowerCase();
+        if (OVERFLOW_PHRASES.some((p) => lower.includes(p)))
+            return "context_overflow";
+    }
+    return "unknown";
+}
+/** True when `classifyLlmError` returned a retriable kind. */
+function isLlmErrorRetryable(kind) {
+    return kind === "rate_limited" || kind === "overloaded";
+}
+// ── Delay calculation ───────────────────────────────────────────────────────
+const RETRY_INITIAL_DELAY_MS = 2_000;
+const RETRY_BACKOFF_FACTOR = 2;
+/** Cap when NO Retry-After header is present (30 s). */
+const RETRY_MAX_NO_HEADER_MS = 30_000;
+/** Absolute cap (int32 max) to avoid setTimeout overflow. */
+const RETRY_MAX_ABSOLUTE_MS = 2_147_483_647;
+function capMs(ms, hasHeader) {
+    return Math.min(ms, hasHeader ? RETRY_MAX_ABSOLUTE_MS : RETRY_MAX_NO_HEADER_MS);
+}
+/**
+ * Parse `Retry-After` / `retry-after-ms` headers from a failed response
+ * and return the number of milliseconds to wait.
+ *
+ * Falls back to exponential backoff when no header is found.
+ */
+function extractRetryDelayMs(headers, attempt) {
+    // Anthropic-specific millisecond header (highest priority)
+    const retryAfterMs = headers.get("retry-after-ms");
+    if (retryAfterMs !== null) {
+        const parsed = parseFloat(retryAfterMs);
+        if (Number.isFinite(parsed) && parsed > 0)
+            return capMs(parsed, true);
+    }
+    // Standard Retry-After — seconds or HTTP date
+    const retryAfter = headers.get("retry-after");
+    if (retryAfter !== null) {
+        const parsedSeconds = parseFloat(retryAfter);
+        if (Number.isFinite(parsedSeconds) && parsedSeconds >= 0) {
+            return capMs(Math.ceil(parsedSeconds * 1_000), true);
+        }
+        const dateMs = Date.parse(retryAfter) - Date.now();
+        if (Number.isFinite(dateMs) && dateMs > 0)
+            return capMs(Math.ceil(dateMs), true);
+    }
+    // Exponential backoff with no-header cap
+    return capMs(RETRY_INITIAL_DELAY_MS * Math.pow(RETRY_BACKOFF_FACTOR, attempt - 1), false);
+}
+/** Sleep for `ms` milliseconds, aborting early if `signal` fires. */
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+            return;
+        }
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(timer);
+            reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+        }, { once: true });
+    });
+}
+// ── Core wrapper ─────────────────────────────────────────────────────────────
+/** Error thrown when a non-retryable LLM error is detected. */
+class LlmApiError extends Error {
+    kind;
+    status;
+    body;
+    constructor(kind, status, body) {
+        super(`LLM API error ${status} (${kind}): ${body.slice(0, 300)}`);
+        this.kind = kind;
+        this.status = status;
+        this.body = body;
+        this.name = "LlmApiError";
+    }
+}
+exports.LlmApiError = LlmApiError;
+/**
+ * Wraps a `fetch`-compatible call with LLM-aware retry logic.
+ *
+ * - Reads `Retry-After` / `retry-after-ms` headers for 429 responses.
+ * - Classifies 400/401/403/503/529 and retries or throws immediately.
+ * - Respects `signal` for cancellation between retries.
+ *
+ * @param makeRequest - Factory that returns a `fetch` call (called on each attempt).
+ * @param config      - Optional retry configuration.
+ * @param signal      - Optional AbortSignal forwarded from the caller.
+ * @returns The successful `Response` object.
+ */
+async function fetchWithLlmRetry(makeRequest, config, signal) {
+    const maxRetries = config?.maxRetries ?? 3;
+    for (let attempt = 1; attempt <= maxRetries + 1; attempt++) {
+        if (signal?.aborted) {
+            throw signal.reason ?? new DOMException("Aborted", "AbortError");
+        }
+        const res = await makeRequest();
+        if (res.ok)
+            return res;
+        // Read body once; we need it for classification and the caller won't re-read it.
+        const body = await res.text();
+        const kind = classifyLlmError(res.status, body);
+        if (!isLlmErrorRetryable(kind) || attempt > maxRetries) {
+            throw new LlmApiError(kind, res.status, body);
+        }
+        const delayMs = extractRetryDelayMs(res.headers, attempt);
+        await sleep(delayMs, signal);
+    }
+    // Unreachable — loop always returns or throws.
+    throw new LlmApiError("unknown", 0, "Retry loop exhausted");
+}
+//# sourceMappingURL=llm-retry.js.map

package/dist/libs/llm-retry.js.map

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

package/dist/libs/local-execution.runner.d.ts

@@ -0,0 +1,5 @@
+import type { ExecutionRunner, CommandResult, CommandOptions } from "../contracts/execution-runner.types";
+export declare class LocalExecutionRunner implements ExecutionRunner {
+    run(command: string, options?: CommandOptions): Promise<CommandResult>;
+}
+//# sourceMappingURL=local-execution.runner.d.ts.map

package/dist/libs/local-execution.runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-execution.runner.d.ts","sourceRoot":"","sources":["../../src/libs/local-execution.runner.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAI1G,qBAAa,oBAAqB,YAAW,eAAe;IACpD,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;CAe7E"}