wotann 0.5.0 → 0.5.39

package/dist/intelligence/research-loops/strategies/langgraph-agent.d.ts

@@ -0,0 +1,68 @@
+/**
+ * LangGraph Agent strategy — ported from LDR
+ * `advanced_search_system/strategies/langgraph_agent_strategy.py`.
+ *
+ * The lead "agent" runs a bounded number of tool-call iterations. Each
+ * iteration either:
+ *   1. Calls the search provider directly, OR
+ *   2. Spawns up to MAX_SUBAGENT_WORKERS parallel subagents over a
+ *      list of focused subtopics (capped at MAX_SUBTOPICS).
+ *
+ * The 50-iteration recursion limit from LangGraph is enforced here as
+ * MAX_TOOL_CALLS_PER_RUN. Subagent runs each get the same per-subagent
+ * cap, but the lead agent's *total* tool calls are summed across
+ * itself and every subagent — so a 4-subagent fan-out spends 4 tool
+ * calls of the parent budget plus whatever its own per-subagent
+ * budget allows.
+ *
+ * Subagent timeout (LDR: 1800s) is honored via `Promise.race` with an
+ * injectable clock. Tests use a fake clock to assert timeout
+ * semantics without sleeping.
+ *
+ * The search provider is INJECTABLE: tests use a stub, production
+ * wires the real backend via deep-research.ts. The strategy itself
+ * does not import any specific engine.
+ *
+ * Source: github.com/LearningCircuit/local-deep-research
+ *
+ * Quality bars:
+ *   QB #1  immutable result
+ *   QB #2  injectable provider
+ *   QB #6  honest stub when no provider
+ *   QB #7  per-call state (collector, counters)
+ *   QB #14 verified in langgraph-agent.test.ts
+ */
+import { type BaseResearchStrategy, type ResearchContext, type ResearchResult, type SearchHit, emptyResult } from "./base-strategy.js";
+/** Planner picks subtopics OR returns null to skip subagent fan-out. */
+export type SubtopicPlanner = (query: string, hits: readonly SearchHit[]) => Promise<readonly string[] | null>;
+export interface LangGraphAgentOptions {
+    /** Hard ceiling on lead-agent + subagent tool calls. ≤ MAX_TOOL_CALLS_PER_RUN. */
+    readonly maxToolCalls?: number;
+    /** Per-subagent ceiling (still inside the global cap). */
+    readonly maxSubagentCalls?: number;
+    /** Maximum concurrent subagents. ≤ MAX_SUBAGENT_WORKERS. */
+    readonly maxConcurrency?: number;
+    /** Maximum number of subtopics planned per fan-out. ≤ MAX_SUBTOPICS. */
+    readonly maxSubtopics?: number;
+    /** Optional planner — when omitted the lead agent runs alone. */
+    readonly planner?: SubtopicPlanner;
+    /** ms after which a subagent is force-resolved with a timeout finding. */
+    readonly subagentTimeoutMs?: number;
+}
+export declare class LangGraphAgentStrategy implements BaseResearchStrategy {
+    readonly name = "langgraph-agent";
+    private readonly opts;
+    constructor(options?: LangGraphAgentOptions);
+    run(query: string, context: ResearchContext): Promise<ResearchResult>;
+    /**
+     * Run a single subagent against `topic`. Subagent issues one search,
+     * collects results into the SHARED collector, and synthesizes a
+     * scoped finding. Honors the subagent timeout via Promise.race.
+     *
+     * Returns the finding (or a timeout marker), how many tool calls
+     * were spent, and whether a timeout fired.
+     */
+    private runSubagent;
+}
+export { emptyResult };
+//# sourceMappingURL=langgraph-agent.d.ts.map

package/dist/intelligence/research-loops/strategies/langgraph-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"langgraph-agent.d.ts","sourceRoot":"","sources":["../../../../src/intelligence/research-loops/strategies/langgraph-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,eAAe,EAEpB,KAAK,cAAc,EACnB,KAAK,SAAS,EAMd,WAAW,EAEZ,MAAM,oBAAoB,CAAC;AAI5B,wEAAwE;AACxE,MAAM,MAAM,eAAe,GAAG,CAC5B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,SAAS,SAAS,EAAE,KACvB,OAAO,CAAC,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;AAEvC,MAAM,WAAW,qBAAqB;IACpC,kFAAkF;IAClF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,0DAA0D;IAC1D,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,4DAA4D;IAC5D,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,wEAAwE;IACxE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,iEAAiE;IACjE,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,qBAAa,sBAAuB,YAAW,oBAAoB;IACjE,QAAQ,CAAC,IAAI,qBAAiB;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAEnB;gBAEU,OAAO,GAAE,qBAA0B;IA2BzC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAmF3E;;;;;;;OAOG;YACW,WAAW;CAkE1B;AAwCD,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/dist/intelligence/research-loops/strategies/langgraph-agent.js

@@ -0,0 +1,221 @@
+/**
+ * LangGraph Agent strategy — ported from LDR
+ * `advanced_search_system/strategies/langgraph_agent_strategy.py`.
+ *
+ * The lead "agent" runs a bounded number of tool-call iterations. Each
+ * iteration either:
+ *   1. Calls the search provider directly, OR
+ *   2. Spawns up to MAX_SUBAGENT_WORKERS parallel subagents over a
+ *      list of focused subtopics (capped at MAX_SUBTOPICS).
+ *
+ * The 50-iteration recursion limit from LangGraph is enforced here as
+ * MAX_TOOL_CALLS_PER_RUN. Subagent runs each get the same per-subagent
+ * cap, but the lead agent's *total* tool calls are summed across
+ * itself and every subagent — so a 4-subagent fan-out spends 4 tool
+ * calls of the parent budget plus whatever its own per-subagent
+ * budget allows.
+ *
+ * Subagent timeout (LDR: 1800s) is honored via `Promise.race` with an
+ * injectable clock. Tests use a fake clock to assert timeout
+ * semantics without sleeping.
+ *
+ * The search provider is INJECTABLE: tests use a stub, production
+ * wires the real backend via deep-research.ts. The strategy itself
+ * does not import any specific engine.
+ *
+ * Source: github.com/LearningCircuit/local-deep-research
+ *
+ * Quality bars:
+ *   QB #1  immutable result
+ *   QB #2  injectable provider
+ *   QB #6  honest stub when no provider
+ *   QB #7  per-call state (collector, counters)
+ *   QB #14 verified in langgraph-agent.test.ts
+ */
+import { ResearchResultsCollector } from "../results-collector.js";
+import { MAX_SUBAGENT_WORKERS, MAX_SUBTOPICS, MAX_TOOL_CALLS_PER_RUN, clampMax, emptyResult, requireProvider, } from "./base-strategy.js";
+const STRATEGY_NAME = "langgraph-agent";
+export class LangGraphAgentStrategy {
+    name = STRATEGY_NAME;
+    opts;
+    constructor(options = {}) {
+        const maxToolCalls = clampMax(options.maxToolCalls, MAX_TOOL_CALLS_PER_RUN, MAX_TOOL_CALLS_PER_RUN);
+        const maxSubagentCalls = clampMax(options.maxSubagentCalls, maxToolCalls, Math.max(1, Math.floor(maxToolCalls / 4)));
+        const maxConcurrency = clampMax(options.maxConcurrency, MAX_SUBAGENT_WORKERS, MAX_SUBAGENT_WORKERS);
+        const maxSubtopics = clampMax(options.maxSubtopics, MAX_SUBTOPICS, MAX_SUBTOPICS);
+        this.opts = Object.freeze({
+            maxToolCalls,
+            maxSubagentCalls,
+            maxConcurrency,
+            maxSubtopics,
+            subagentTimeoutMs: options.subagentTimeoutMs ?? 1_800_000,
+            planner: options.planner,
+        });
+    }
+    async run(query, context) {
+        if (typeof query !== "string" || query.length === 0) {
+            throw new Error("langgraph-agent: query must be non-empty string");
+        }
+        const noProvider = requireProvider(context, STRATEGY_NAME);
+        if (noProvider) {
+            return Object.freeze({ ...noProvider, query });
+        }
+        const collector = new ResearchResultsCollector();
+        let toolCalls = 0;
+        let stopReason = "completed";
+        // ── Phase 1: lead agent does one search to seed context ─────────
+        const initialHits = await safeSearch(context.provider, query);
+        toolCalls += 1;
+        if (initialHits === null) {
+            return Object.freeze({
+                strategy: STRATEGY_NAME,
+                query,
+                findings: Object.freeze([]),
+                toolCalls,
+                stopReason: "provider-error",
+                ok: false,
+            });
+        }
+        collector.addResults(initialHits, "lead");
+        // ── Phase 2: optional subtopic fan-out via subagents ────────────
+        const subFindings = [];
+        if (this.opts.planner && toolCalls < this.opts.maxToolCalls) {
+            const planned = await this.opts.planner(query, initialHits);
+            const subtopics = (planned ?? []).slice(0, this.opts.maxSubtopics);
+            if (subtopics.length > 0) {
+                const remaining = this.opts.maxToolCalls - toolCalls;
+                const perSubagent = Math.max(1, Math.min(this.opts.maxSubagentCalls, Math.floor(remaining / subtopics.length)));
+                // Slice subtopics into concurrency-bounded waves.
+                let cursor = 0;
+                while (cursor < subtopics.length && toolCalls < this.opts.maxToolCalls) {
+                    const wave = subtopics.slice(cursor, cursor + this.opts.maxConcurrency);
+                    cursor += this.opts.maxConcurrency;
+                    const waveResults = await Promise.all(wave.map((topic) => this.runSubagent(topic, perSubagent, context, collector)));
+                    for (const r of waveResults) {
+                        toolCalls += r.toolCalls;
+                        if (r.finding)
+                            subFindings.push(r.finding);
+                        if (r.timedOut)
+                            stopReason = "completed"; // partial finding kept
+                        if (toolCalls >= this.opts.maxToolCalls) {
+                            stopReason = "max-tool-calls";
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+        if (toolCalls >= this.opts.maxToolCalls && stopReason === "completed") {
+            stopReason = "max-tool-calls";
+        }
+        // ── Phase 3: synthesize a single lead finding ───────────────────
+        const leadFinding = Object.freeze({
+            question: query,
+            content: synthesize(query, initialHits, subFindings),
+            citations: collector.citations(),
+        });
+        return Object.freeze({
+            strategy: STRATEGY_NAME,
+            query,
+            findings: Object.freeze([leadFinding, ...subFindings]),
+            toolCalls,
+            stopReason,
+            ok: true,
+        });
+    }
+    /**
+     * Run a single subagent against `topic`. Subagent issues one search,
+     * collects results into the SHARED collector, and synthesizes a
+     * scoped finding. Honors the subagent timeout via Promise.race.
+     *
+     * Returns the finding (or a timeout marker), how many tool calls
+     * were spent, and whether a timeout fired.
+     */
+    async runSubagent(topic, perSubagentCap, context, collector) {
+        const before = collector.size();
+        const timeoutPromise = new Promise((resolve) => {
+            setTimeout(() => resolve("timeout"), this.opts.subagentTimeoutMs).unref?.();
+        });
+        let subToolCalls = 0;
+        let timedOut = false;
+        const workPromise = (async () => {
+            const hits = await safeSearch(context.provider, topic);
+            subToolCalls += 1;
+            if (hits === null)
+                return null;
+            collector.addResults(hits, `subagent:${topic.slice(0, 24)}`);
+            // Subagents are bounded by perSubagentCap — but for the JS port
+            // we keep a single search per subagent (the LDR Python version
+            // can iterate via LangGraph recursion; here we sum tool calls
+            // and let the lead agent decide whether to fan out more).
+            // Future enhancement: per-subagent iterative refinement.
+            void perSubagentCap;
+            return hits;
+        })();
+        const raceResult = await Promise.race([workPromise, timeoutPromise]);
+        if (raceResult === "timeout") {
+            timedOut = true;
+            return {
+                finding: Object.freeze({
+                    question: topic,
+                    content: `[subagent timeout] ${topic}`,
+                    citations: Object.freeze([]),
+                }),
+                toolCalls: subToolCalls > 0 ? subToolCalls : 1,
+                timedOut,
+            };
+        }
+        if (raceResult === null) {
+            return {
+                finding: Object.freeze({
+                    question: topic,
+                    content: `[subagent provider-error] ${topic}`,
+                    citations: Object.freeze([]),
+                }),
+                toolCalls: subToolCalls,
+                timedOut,
+            };
+        }
+        // Build citation list for the new hits this subagent contributed.
+        const after = collector.citations();
+        const newOnes = after.slice(before);
+        const finding = Object.freeze({
+            question: topic,
+            content: synthesize(topic, raceResult, []),
+            citations: Object.freeze(newOnes),
+        });
+        return { finding, toolCalls: subToolCalls, timedOut };
+    }
+}
+// ── Helpers ─────────────────────────────────────────────────────────
+async function safeSearch(provider, query) {
+    try {
+        const out = await provider(query);
+        if (!Array.isArray(out))
+            return null;
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
+function synthesize(question, hits, subFindings) {
+    const lines = [];
+    lines.push(`## Research: ${question}`);
+    if (hits.length > 0) {
+        lines.push("### Direct findings");
+        for (const h of hits.slice(0, 10)) {
+            lines.push(`- ${h.title} — ${h.snippet}`);
+        }
+    }
+    if (subFindings.length > 0) {
+        lines.push("### Subagent findings");
+        for (const sf of subFindings) {
+            lines.push(`- ${sf.question}: ${sf.content.split("\n")[0] ?? sf.content}`);
+        }
+    }
+    return lines.join("\n");
+}
+// Re-export the empty-result helper so callers know it's part of the contract.
+export { emptyResult };
+//# sourceMappingURL=langgraph-agent.js.map

package/dist/intelligence/research-loops/strategies/langgraph-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"langgraph-agent.js","sourceRoot":"","sources":["../../../../src/intelligence/research-loops/strategies/langgraph-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAOL,oBAAoB,EACpB,aAAa,EACb,sBAAsB,EACtB,QAAQ,EACR,WAAW,EACX,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,aAAa,GAAG,iBAAiB,CAAC;AAuBxC,MAAM,OAAO,sBAAsB;IACxB,IAAI,GAAG,aAAa,CAAC;IACb,IAAI,CAEnB;IAEF,YAAY,UAAiC,EAAE;QAC7C,MAAM,YAAY,GAAG,QAAQ,CAC3B,OAAO,CAAC,YAAY,EACpB,sBAAsB,EACtB,sBAAsB,CACvB,CAAC;QACF,MAAM,gBAAgB,GAAG,QAAQ,CAC/B,OAAO,CAAC,gBAAgB,EACxB,YAAY,EACZ,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC,CAC1C,CAAC;QACF,MAAM,cAAc,GAAG,QAAQ,CAC7B,OAAO,CAAC,cAAc,EACtB,oBAAoB,EACpB,oBAAoB,CACrB,CAAC;QACF,MAAM,YAAY,GAAG,QAAQ,CAAC,OAAO,CAAC,YAAY,EAAE,aAAa,EAAE,aAAa,CAAC,CAAC;QAClF,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC;YACxB,YAAY;YACZ,gBAAgB;YAChB,cAAc;YACd,YAAY;YACZ,iBAAiB,EAAE,OAAO,CAAC,iBAAiB,IAAI,SAAS;YACzD,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,KAAa,EAAE,OAAwB;QAC/C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpD,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;QACrE,CAAC;QACD,MAAM,UAAU,GAAG,eAAe,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QAC3D,IAAI,UAAU,EAAE,CAAC;YACf,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC;QACjD,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,wBAAwB,EAAE,CAAC;QACjD,IAAI,SAAS,GAAG,CAAC,CAAC;QAClB,IAAI,UAAU,GAAuB,WAAW,CAAC;QAEjD,mEAAmE;QACnE,MAAM,WAAW,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC9D,SAAS,IAAI,CAAC,CAAC;QACf,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;YACzB,OAAO,MAAM,CAAC,MAAM,CAAC;gBACnB,QAAQ,EAAE,aAAa;gBACvB,KAAK;gBACL,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAoB,EAAE,CAAC;gBAC9C,SAAS;gBACT,UAAU,EAAE,gBAAgB;gBAC5B,EAAE,EAAE,KAAK;aACV,CAAC,CAAC;QACL,CAAC;QACD,SAAS,CAAC,UAAU,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QAE1C,mEAAmE;QACnE,MAAM,WAAW,GAAsB,EAAE,CAAC;QAC1C,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YAC5D,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;YAC5D,MAAM,SAAS,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAEnE,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACzB,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,GAAG,SAAS,CAAC;gBACrD,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAC1B,CAAC,EACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAC/E,CAAC;gBAEF,kDAAkD;gBAClD,IAAI,MAAM,GAAG,CAAC,CAAC;gBACf,OAAO,MAAM,GAAG,SAAS,CAAC,MAAM,IAAI,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;oBACvE,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;oBACxE,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC;oBACnC,MAAM,WAAW,GAAG,MAAM,OAAO,CAAC,GAAG,CACnC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAC9E,CAAC;oBACF,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;wBAC5B,SAAS,IAAI,CAAC,CAAC,SAAS,CAAC;wBACzB,IAAI,CAAC,CAAC,OAAO;4BAAE,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;wBAC3C,IAAI,CAAC,CAAC,QAAQ;4BAAE,UAAU,GAAG,WAAW,CAAC,CAAC,uBAAuB;wBACjE,IAAI,SAAS,IAAI,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;4BACxC,UAAU,GAAG,gBAAgB,CAAC;4BAC9B,MAAM;wBACR,CAAC;oBACH,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAED,IAAI,SAAS,IAAI,IAAI,CAAC,IAAI,CAAC,YAAY,IAAI,UAAU,KAAK,WAAW,EAAE,CAAC;YACtE,UAAU,GAAG,gBAAgB,CAAC;QAChC,CAAC;QAED,mEAAmE;QACnE,MAAM,WAAW,GAAoB,MAAM,CAAC,MAAM,CAAC;YACjD,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,UAAU,CAAC,KAAK,EAAE,WAAW,EAAE,WAAW,CAAC;YACpD,SAAS,EAAE,SAAS,CAAC,SAAS,EAAE;SACjC,CAAC,CAAC;QAEH,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,QAAQ,EAAE,aAAa;YACvB,KAAK;YACL,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAoB,CAAC,WAAW,EAAE,GAAG,WAAW,CAAC,CAAC;YACzE,SAAS;YACT,UAAU;YACV,EAAE,EAAE,IAAI;SACT,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACK,KAAK,CAAC,WAAW,CACvB,KAAa,EACb,cAAsB,EACtB,OAAwB,EACxB,SAAmC;QAMnC,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;QAChC,MAAM,cAAc,GAAG,IAAI,OAAO,CAAY,CAAC,OAAO,EAAE,EAAE;YACxD,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC;QAC9E,CAAC,CAAC,CAAC;QACH,IAAI,YAAY,GAAG,CAAC,CAAC;QACrB,IAAI,QAAQ,GAAG,KAAK,CAAC;QAErB,MAAM,WAAW,GAAG,CAAC,KAAK,IAA0C,EAAE;YACpE,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;YACvD,YAAY,IAAI,CAAC,CAAC;YAClB,IAAI,IAAI,KAAK,IAAI;gBAAE,OAAO,IAAI,CAAC;YAC/B,SAAS,CAAC,UAAU,CAAC,IAAI,EAAE,YAAY,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;YAC7D,gEAAgE;YAChE,+DAA+D;YAC/D,8DAA8D;YAC9D,0DAA0D;YAC1D,yDAAyD;YACzD,KAAK,cAAc,CAAC;YACpB,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,EAAE,CAAC;QAEL,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC,CAAC;QACrE,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,QAAQ,GAAG,IAAI,CAAC;YAChB,OAAO;gBACL,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC;oBACrB,QAAQ,EAAE,KAAK;oBACf,OAAO,EAAE,sBAAsB,KAAK,EAAE;oBACtC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;iBAC7B,CAAC;gBACF,SAAS,EAAE,YAAY,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;gBAC9C,QAAQ;aACT,CAAC;QACJ,CAAC;QACD,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;YACxB,OAAO;gBACL,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC;oBACrB,QAAQ,EAAE,KAAK;oBACf,OAAO,EAAE,6BAA6B,KAAK,EAAE;oBAC7C,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;iBAC7B,CAAC;gBACF,SAAS,EAAE,YAAY;gBACvB,QAAQ;aACT,CAAC;QACJ,CAAC;QAED,kEAAkE;QAClE,MAAM,KAAK,GAAG,SAAS,CAAC,SAAS,EAAE,CAAC;QACpC,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACpC,MAAM,OAAO,GAAoB,MAAM,CAAC,MAAM,CAAC;YAC7C,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC;YAC1C,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC;SAClC,CAAC,CAAC;QACH,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC;IACxD,CAAC;CACF;AAED,uEAAuE;AAEvE,KAAK,UAAU,UAAU,CACvB,QAAqC,EACrC,KAAa;IAEb,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QACrC,OAAO,GAAG,CAAC;IACb,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CACjB,QAAgB,EAChB,IAA0B,EAC1B,WAAuC;IAEvC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,gBAAgB,QAAQ,EAAE,CAAC,CAAC;IACvC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpB,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;QAClC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;YAClC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IACD,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;QACpC,KAAK,MAAM,EAAE,IAAI,WAAW,EAAE,CAAC;YAC7B,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,QAAQ,KAAK,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;QAC7E,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,+EAA+E;AAC/E,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/dist/intelligence/research-loops/strategies/parallel-constrained.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Parallel Constrained strategy — ported from LDR
+ * `advanced_search_system/strategies/parallel_constrained_strategy.py`.
+ *
+ * Launches up to MAX_CONCURRENCY parallel branches over a list of
+ * query "constraint slots". Each branch runs one search and reports
+ * its cost (in tool calls) back to a shared budget. As soon as the
+ * budget is exhausted, in-flight branches are allowed to finish but
+ * no new branches are started.
+ *
+ * LDR's Python version classifies constraints as hard/soft and walks
+ * three strictness phases (strict → relaxed → individual). The TS
+ * port keeps the same idea: caller provides ordered "slots", and the
+ * strategy spends its budget greedily, never exceeding the global
+ * tool-call cap.
+ *
+ * The provider is INJECTABLE. Tests use a stub that consumes a fixed
+ * cost per call and exercises budget exhaustion deterministically.
+ *
+ * Source: github.com/LearningCircuit/local-deep-research
+ *
+ * Quality bars: QB#1, QB#2, QB#6, QB#7, QB#14.
+ */
+import { type BaseResearchStrategy, type ResearchContext, type ResearchResult } from "./base-strategy.js";
+export interface ConstraintSlot {
+    readonly query: string;
+    /** Cost in tool calls. Default 1. */
+    readonly cost?: number;
+}
+export interface ParallelConstrainedOptions {
+    readonly slots: readonly ConstraintSlot[];
+    readonly maxToolCalls?: number;
+    /** Maximum concurrent branches. ≤ MAX_SUBAGENT_WORKERS. */
+    readonly maxConcurrency?: number;
+}
+export declare class ParallelConstrainedStrategy implements BaseResearchStrategy {
+    readonly name = "parallel-constrained";
+    private readonly opts;
+    constructor(options: ParallelConstrainedOptions);
+    run(query: string, context: ResearchContext): Promise<ResearchResult>;
+}
+//# sourceMappingURL=parallel-constrained.d.ts.map

package/dist/intelligence/research-loops/strategies/parallel-constrained.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel-constrained.d.ts","sourceRoot":"","sources":["../../../../src/intelligence/research-loops/strategies/parallel-constrained.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,eAAe,EAEpB,KAAK,cAAc,EAOpB,MAAM,oBAAoB,CAAC;AAI5B,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IAC1C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAQD,qBAAa,2BAA4B,YAAW,oBAAoB;IACtE,QAAQ,CAAC,IAAI,0BAAiB;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkB;gBAE3B,OAAO,EAAE,0BAA0B;IAWzC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;CA8F5E"}

package/dist/intelligence/research-loops/strategies/parallel-constrained.js

@@ -0,0 +1,132 @@
+/**
+ * Parallel Constrained strategy — ported from LDR
+ * `advanced_search_system/strategies/parallel_constrained_strategy.py`.
+ *
+ * Launches up to MAX_CONCURRENCY parallel branches over a list of
+ * query "constraint slots". Each branch runs one search and reports
+ * its cost (in tool calls) back to a shared budget. As soon as the
+ * budget is exhausted, in-flight branches are allowed to finish but
+ * no new branches are started.
+ *
+ * LDR's Python version classifies constraints as hard/soft and walks
+ * three strictness phases (strict → relaxed → individual). The TS
+ * port keeps the same idea: caller provides ordered "slots", and the
+ * strategy spends its budget greedily, never exceeding the global
+ * tool-call cap.
+ *
+ * The provider is INJECTABLE. Tests use a stub that consumes a fixed
+ * cost per call and exercises budget exhaustion deterministically.
+ *
+ * Source: github.com/LearningCircuit/local-deep-research
+ *
+ * Quality bars: QB#1, QB#2, QB#6, QB#7, QB#14.
+ */
+import { ResearchResultsCollector } from "../results-collector.js";
+import { MAX_SUBAGENT_WORKERS, MAX_TOOL_CALLS_PER_RUN, clampMax, requireProvider, } from "./base-strategy.js";
+const STRATEGY_NAME = "parallel-constrained";
+export class ParallelConstrainedStrategy {
+    name = STRATEGY_NAME;
+    opts;
+    constructor(options) {
+        if (!Array.isArray(options.slots) || options.slots.length === 0) {
+            throw new Error("parallel-constrained: at least one slot is required");
+        }
+        this.opts = Object.freeze({
+            slots: Object.freeze(options.slots.slice()),
+            maxToolCalls: clampMax(options.maxToolCalls, MAX_TOOL_CALLS_PER_RUN, MAX_TOOL_CALLS_PER_RUN),
+            maxConcurrency: clampMax(options.maxConcurrency, MAX_SUBAGENT_WORKERS, MAX_SUBAGENT_WORKERS),
+        });
+    }
+    async run(query, context) {
+        if (typeof query !== "string" || query.length === 0) {
+            throw new Error("parallel-constrained: query must be non-empty string");
+        }
+        const noProvider = requireProvider(context, STRATEGY_NAME);
+        if (noProvider)
+            return Object.freeze({ ...noProvider, query });
+        const collector = new ResearchResultsCollector();
+        let toolCalls = 0;
+        let stopReason = "completed";
+        const findings = [];
+        // Walk slots in waves of maxConcurrency. Each branch's cost is
+        // committed BEFORE the call; if the wave would exceed the budget,
+        // trim it.
+        let cursor = 0;
+        let providerErrored = false;
+        while (cursor < this.opts.slots.length && toolCalls < this.opts.maxToolCalls) {
+            const wave = [];
+            let waveCost = 0;
+            while (cursor < this.opts.slots.length &&
+                wave.length < this.opts.maxConcurrency &&
+                toolCalls + waveCost + (this.opts.slots[cursor]?.cost ?? 1) <= this.opts.maxToolCalls) {
+                const slot = this.opts.slots[cursor];
+                if (!slot)
+                    break;
+                wave.push(slot);
+                waveCost += slot.cost ?? 1;
+                cursor += 1;
+            }
+            if (wave.length === 0) {
+                // Next slot is too expensive for the remaining budget.
+                stopReason = "max-tool-calls";
+                break;
+            }
+            const results = await Promise.all(wave.map(async (slot) => {
+                try {
+                    const out = await context.provider(slot.query);
+                    const hits = Array.isArray(out) ? out : [];
+                    return { slot, hits, errored: false };
+                }
+                catch {
+                    return { slot, hits: [], errored: true };
+                }
+            }));
+            toolCalls += waveCost;
+            for (const r of results) {
+                if (r.errored) {
+                    providerErrored = true;
+                    findings.push(Object.freeze({
+                        question: r.slot.query,
+                        content: `[provider-error] ${r.slot.query}`,
+                        citations: Object.freeze([]),
+                    }));
+                    continue;
+                }
+                const before = collector.size();
+                collector.addResults(r.hits, "parallel");
+                const newCitations = collector.citations().slice(before);
+                findings.push(Object.freeze({
+                    question: r.slot.query,
+                    content: summarizeHits(r.slot.query, r.hits),
+                    citations: Object.freeze(newCitations),
+                }));
+            }
+            if (toolCalls >= this.opts.maxToolCalls && cursor < this.opts.slots.length) {
+                stopReason = "max-tool-calls";
+                break;
+            }
+        }
+        if (toolCalls >= this.opts.maxToolCalls &&
+            cursor < this.opts.slots.length &&
+            stopReason === "completed") {
+            stopReason = "max-tool-calls";
+        }
+        return Object.freeze({
+            strategy: STRATEGY_NAME,
+            query,
+            findings: Object.freeze(findings),
+            toolCalls,
+            stopReason,
+            ok: !providerErrored,
+        });
+    }
+}
+function summarizeHits(query, hits) {
+    if (hits.length === 0)
+        return `No results for: ${query}`;
+    const lines = [`### ${query}`];
+    for (const h of hits.slice(0, 8))
+        lines.push(`- ${h.title}: ${h.snippet}`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=parallel-constrained.js.map

package/dist/intelligence/research-loops/strategies/parallel-constrained.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel-constrained.js","sourceRoot":"","sources":["../../../../src/intelligence/research-loops/strategies/parallel-constrained.ts"],"names":[],"mappings":"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"}

package/dist/intelligence/research-loops/strategies/recursive-decomposition.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Recursive Decomposition strategy — ported from LDR
+ * `advanced_search_system/strategies/recursive_decomposition_strategy.py`.
+ *
+ * The lead agent decides for the input query: "DECOMPOSE" or
+ * "SEARCH_DIRECTLY". On DECOMPOSE, it produces 2–MAX_SUBTOPICS subtasks
+ * and recursively analyzes each at depth+1. On SEARCH_DIRECTLY (or
+ * when MAX_RECURSION_DEPTH is reached), the strategy calls the
+ * injected search provider once and synthesizes a leaf finding.
+ *
+ * Final synthesis aggregates per-subtask findings into a single root
+ * finding while preserving the per-subtask citations on the deeper
+ * findings.
+ *
+ * The decomposer is INJECTABLE — tests use a deterministic stub.
+ * Production wires an LLM-backed planner. Recursion is bounded by
+ * MAX_RECURSION_DEPTH AND a global tool-call cap (MAX_TOOL_CALLS_PER_RUN)
+ * so even a pathological decomposer cannot run away.
+ *
+ * Source: github.com/LearningCircuit/local-deep-research
+ *
+ * Quality bars: QB#1, QB#2, QB#6, QB#7, QB#14.
+ */
+import { type BaseResearchStrategy, type ResearchContext, type ResearchResult } from "./base-strategy.js";
+export interface DecompositionDecision {
+    readonly shouldDecompose: boolean;
+    readonly subtasks: readonly string[];
+    readonly reasoning: string;
+}
+/**
+ * Decide whether to decompose, and into which subtasks. Receives the
+ * current depth so the decomposer can be biased against decomposing
+ * near the cap. Should return at most MAX_SUBTOPICS subtasks.
+ */
+export type Decomposer = (query: string, depth: number) => Promise<DecompositionDecision>;
+export interface RecursiveDecompositionOptions {
+    readonly decomposer?: Decomposer;
+    readonly maxToolCalls?: number;
+    readonly maxDepth?: number;
+    readonly maxSubtopics?: number;
+}
+export declare class RecursiveDecompositionStrategy implements BaseResearchStrategy {
+    readonly name = "recursive-decomposition";
+    private readonly opts;
+    constructor(options?: RecursiveDecompositionOptions);
+    run(query: string, context: ResearchContext): Promise<ResearchResult>;
+    /**
+     * Analyze a (sub)query at a given depth. Returns a single finding
+     * for this node — for decomposed nodes, the finding's content is
+     * the LLM-aggregated synthesis of child findings.
+     */
+    private analyze;
+    private directSearch;
+}
+//# sourceMappingURL=recursive-decomposition.d.ts.map

package/dist/intelligence/research-loops/strategies/recursive-decomposition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recursive-decomposition.d.ts","sourceRoot":"","sources":["../../../../src/intelligence/research-loops/strategies/recursive-decomposition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,eAAe,EAEpB,KAAK,cAAc,EAQpB,MAAM,oBAAoB,CAAC;AAI5B,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;AAE1F,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAeD,qBAAa,8BAA+B,YAAW,oBAAoB;IACzE,QAAQ,CAAC,IAAI,6BAAiB;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkB;gBAE3B,OAAO,GAAE,6BAAkC;IASjD,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAwB3E;;;;OAIG;YACW,OAAO;YA4DP,YAAY;CA0C3B"}