@lloyal-labs/rig 1.2.0

package/dist/tools/read-file.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReadFileTool = void 0;
+exports.subtractRanges = subtractRanges;
+exports.mergeRanges = mergeRanges;
+const lloyal_agents_1 = require("@lloyal-labs/lloyal-agents");
+/**
+ * Subtract previously-covered ranges from a target range
+ *
+ * Given a target half-open interval `[s, e)` and an array of
+ * already-covered intervals, returns the sub-ranges of `[s, e)`
+ * that have not yet been covered. Used by {@link ReadFileTool}
+ * to avoid re-reading lines the agent has already seen.
+ *
+ * @param range - Target range `[start, end)` (0-indexed)
+ * @param covered - Array of previously-covered `[start, end)` ranges
+ * @returns Uncovered sub-ranges of the target
+ *
+ * @category Rig
+ */
+function subtractRanges([s, e], covered) {
+    let ranges = [[s, e]];
+    for (const [cs, ce] of covered) {
+        ranges = ranges.flatMap(([a, b]) => {
+            if (ce <= a || cs >= b)
+                return [[a, b]];
+            const result = [];
+            if (a < cs)
+                result.push([a, cs]);
+            if (ce < b)
+                result.push([ce, b]);
+            return result;
+        });
+    }
+    return ranges;
+}
+/**
+ * Merge overlapping or adjacent half-open ranges into a minimal set
+ *
+ * Sorts the input ranges by start position, then collapses any
+ * overlapping or touching intervals. Used by {@link ReadFileTool}
+ * to maintain a compact record of lines already read per agent.
+ *
+ * @param ranges - Array of `[start, end)` ranges to merge
+ * @returns Merged non-overlapping ranges sorted by start
+ *
+ * @category Rig
+ */
+function mergeRanges(ranges) {
+    if (ranges.length === 0)
+        return [];
+    const sorted = [...ranges].sort((a, b) => a[0] - b[0]);
+    const merged = [sorted[0]];
+    for (let i = 1; i < sorted.length; i++) {
+        const last = merged[merged.length - 1];
+        if (sorted[i][0] <= last[1]) {
+            last[1] = Math.max(last[1], sorted[i][1]);
+        }
+        else {
+            merged.push(sorted[i]);
+        }
+    }
+    return merged;
+}
+/**
+ * Read content from corpus files by line range
+ *
+ * Tracks which lines each agent has already read and returns only
+ * the unread portions, preventing redundant context inflation.
+ * Line ranges typically come from {@link SearchTool} results.
+ *
+ * Uses {@link subtractRanges} and {@link mergeRanges} internally
+ * to maintain per-agent read tracking keyed by `agentId:filename`.
+ *
+ * @category Rig
+ */
+class ReadFileTool extends lloyal_agents_1.Tool {
+    name = 'read_file';
+    description = 'Read content from a file at specific line ranges. Use startLine/endLine from search results.';
+    parameters;
+    _resources;
+    _readRanges = new Map();
+    constructor(resources) {
+        super();
+        this._resources = resources;
+        this.parameters = {
+            type: 'object',
+            properties: {
+                filename: {
+                    type: 'string',
+                    description: 'Filename from search results',
+                    enum: resources.map(r => r.name),
+                },
+                startLine: { type: 'number', description: 'Start line (1-indexed, from search results)' },
+                endLine: { type: 'number', description: 'End line (1-indexed, from search results)' },
+            },
+            required: ['filename'],
+        };
+    }
+    *execute(args, context) {
+        const filename = args.filename || args.path || '';
+        const file = this._resources.find(r => r.name === filename);
+        if (!file) {
+            return { error: `File not found: ${filename}. Available: ${this._resources.map(r => r.name).join(', ')}` };
+        }
+        const lines = file.content.split('\n');
+        const s = Math.max(0, (args.startLine ?? 1) - 1);
+        const e = Math.min(lines.length, args.endLine ?? Math.min(100, lines.length));
+        const key = context ? `${context.agentId}:${filename}` : filename;
+        const prev = this._readRanges.get(key) ?? [];
+        const unread = subtractRanges([s, e], prev);
+        if (unread.length === 0) {
+            return { file: file.name, note: `Lines ${s + 1}-${e} already read` };
+        }
+        this._readRanges.set(key, mergeRanges([...prev, [s, e]]));
+        const content = unread
+            .map(([a, b]) => lines.slice(a, b).join('\n'))
+            .join('\n...\n');
+        return { file: file.name, content, lines: unread.map(([a, b]) => `${a + 1}-${b}`) };
+    }
+}
+exports.ReadFileTool = ReadFileTool;
+//# sourceMappingURL=read-file.js.map

package/dist/tools/read-file.js.map

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

package/dist/tools/report.d.ts

@@ -0,0 +1,22 @@
+import type { Operation } from 'effection';
+import { Tool } from '@lloyal-labs/lloyal-agents';
+import type { JsonSchema } from '@lloyal-labs/lloyal-agents';
+/**
+ * Terminal tool for submitting research findings
+ *
+ * Used as the `terminalTool` in agent pools -- when an agent calls
+ * this tool, the pool records the findings string and marks the
+ * agent as finished. The tool itself is a no-op; the agent pool
+ * intercepts the call and extracts the `findings` argument.
+ *
+ * @category Rig
+ */
+export declare class ReportTool extends Tool<{
+    findings: string;
+}> {
+    readonly name = "report";
+    readonly description = "Submit your final research findings. Call this when you have gathered enough information to answer the question.";
+    readonly parameters: JsonSchema;
+    execute(): Operation<unknown>;
+}
+//# sourceMappingURL=report.d.ts.map

package/dist/tools/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/tools/report.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,4BAA4B,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAE7D;;;;;;;;;GASG;AACH,qBAAa,UAAW,SAAQ,IAAI,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;IACxD,QAAQ,CAAC,IAAI,YAAY;IACzB,QAAQ,CAAC,WAAW,sHAAsH;IAC1I,QAAQ,CAAC,UAAU,EAAE,UAAU,CAI7B;IAED,OAAO,IAAI,SAAS,CAAC,OAAO,CAAC;CAC/B"}

package/dist/tools/report.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReportTool = void 0;
+const lloyal_agents_1 = require("@lloyal-labs/lloyal-agents");
+/**
+ * Terminal tool for submitting research findings
+ *
+ * Used as the `terminalTool` in agent pools -- when an agent calls
+ * this tool, the pool records the findings string and marks the
+ * agent as finished. The tool itself is a no-op; the agent pool
+ * intercepts the call and extracts the `findings` argument.
+ *
+ * @category Rig
+ */
+class ReportTool extends lloyal_agents_1.Tool {
+    name = 'report';
+    description = 'Submit your final research findings. Call this when you have gathered enough information to answer the question.';
+    parameters = {
+        type: 'object',
+        properties: { findings: { type: 'string', description: 'Your research findings and answer' } },
+        required: ['findings'],
+    };
+    *execute() { return {}; }
+}
+exports.ReportTool = ReportTool;
+//# sourceMappingURL=report.js.map

package/dist/tools/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../src/tools/report.ts"],"names":[],"mappings":";;;AACA,8DAAkD;AAGlD;;;;;;;;;GASG;AACH,MAAa,UAAW,SAAQ,oBAA0B;IAC/C,IAAI,GAAG,QAAQ,CAAC;IAChB,WAAW,GAAG,kHAAkH,CAAC;IACjI,UAAU,GAAe;QAChC,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,mCAAmC,EAAE,EAAE;QAC9F,QAAQ,EAAE,CAAC,UAAU,CAAC;KACvB,CAAC;IAEF,CAAC,OAAO,KAAyB,OAAO,EAAE,CAAC,CAAC,CAAC;CAC9C;AAVD,gCAUC"}

package/dist/tools/research.d.ts

@@ -0,0 +1,57 @@
+import type { Operation } from 'effection';
+import { Tool } from '@lloyal-labs/lloyal-agents';
+import type { JsonSchema, Toolkit, PressureThresholds } from '@lloyal-labs/lloyal-agents';
+/**
+ * Configuration for {@link ResearchTool}
+ *
+ * @category Rig
+ */
+export interface ResearchToolOpts {
+    /** System prompt for each spawned research agent */
+    systemPrompt: string;
+    /** Prompt pair used to extract findings from hard-cut agents */
+    reporterPrompt: {
+        system: string;
+        user: string;
+    };
+    /** Maximum tool-use turns per research agent (default: 20) */
+    maxTurns?: number;
+    /** Enable trace logging for sub-agent pools */
+    trace?: boolean;
+    /** Context pressure thresholds for sub-agent pools */
+    pressure?: PressureThresholds;
+}
+/**
+ * Spawn parallel research agents for sub-questions (corpus source)
+ *
+ * Creates a {@link withSharedRoot | shared root} and runs a
+ * {@link useAgentPool | pool} of research agents, one per question.
+ * Each agent has access to the full toolkit (search, read_file,
+ * grep, report). Agents that hit the turn limit without reporting
+ * are forced through a reporter pass that extracts partial findings.
+ *
+ * Call {@link ResearchTool.setToolkit | setToolkit()} before first
+ * execution to wire the toolkit into the sub-agent pool.
+ *
+ * @category Rig
+ */
+export declare class ResearchTool extends Tool<{
+    questions: string[];
+}> {
+    readonly name = "research";
+    readonly description = "Spawn parallel research agents to investigate sub-questions. Each question gets its own agent.";
+    readonly parameters: JsonSchema;
+    private _systemPrompt;
+    private _reporterPrompt;
+    private _maxTurns;
+    private _trace;
+    private _pressure?;
+    private _toolkit;
+    constructor(opts: ResearchToolOpts);
+    /** Inject the toolkit that sub-agents will use. Must be called before execute. */
+    setToolkit(toolkit: Toolkit): void;
+    execute(args: {
+        questions: string[];
+    }): Operation<unknown>;
+}
+//# sourceMappingURL=research.d.ts.map

package/dist/tools/research.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"research.d.ts","sourceRoot":"","sources":["../../src/tools/research.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,IAAI,EAA8D,MAAM,4BAA4B,CAAC;AAC9G,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAE1F;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,cAAc,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,YAAa,SAAQ,IAAI,CAAC;IAAE,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;IAC7D,QAAQ,CAAC,IAAI,cAAc;IAC3B,QAAQ,CAAC,WAAW,oGAAoG;IACxH,QAAQ,CAAC,UAAU,EAAE,UAAU,CAU7B;IAEF,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,eAAe,CAAmC;IAC1D,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,SAAS,CAAC,CAAqB;IACvC,OAAO,CAAC,QAAQ,CAAwB;gBAE5B,IAAI,EAAE,gBAAgB;IASlC,kFAAkF;IAClF,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAIjC,OAAO,CAAC,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,SAAS,CAAC,OAAO,CAAC;CAoE5D"}

package/dist/tools/research.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResearchTool = void 0;
+const lloyal_agents_1 = require("@lloyal-labs/lloyal-agents");
+/**
+ * Spawn parallel research agents for sub-questions (corpus source)
+ *
+ * Creates a {@link withSharedRoot | shared root} and runs a
+ * {@link useAgentPool | pool} of research agents, one per question.
+ * Each agent has access to the full toolkit (search, read_file,
+ * grep, report). Agents that hit the turn limit without reporting
+ * are forced through a reporter pass that extracts partial findings.
+ *
+ * Call {@link ResearchTool.setToolkit | setToolkit()} before first
+ * execution to wire the toolkit into the sub-agent pool.
+ *
+ * @category Rig
+ */
+class ResearchTool extends lloyal_agents_1.Tool {
+    name = 'research';
+    description = 'Spawn parallel research agents to investigate sub-questions. Each question gets its own agent.';
+    parameters = {
+        type: 'object',
+        properties: {
+            questions: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Sub-questions to research in parallel',
+            },
+        },
+        required: ['questions'],
+    };
+    _systemPrompt;
+    _reporterPrompt;
+    _maxTurns;
+    _trace;
+    _pressure;
+    _toolkit = null;
+    constructor(opts) {
+        super();
+        this._systemPrompt = opts.systemPrompt;
+        this._reporterPrompt = opts.reporterPrompt;
+        this._maxTurns = opts.maxTurns ?? 20;
+        this._trace = opts.trace ?? false;
+        this._pressure = opts.pressure;
+    }
+    /** Inject the toolkit that sub-agents will use. Must be called before execute. */
+    setToolkit(toolkit) {
+        this._toolkit = toolkit;
+    }
+    *execute(args) {
+        const questions = args?.questions;
+        if (!Array.isArray(questions) || questions.length === 0) {
+            return { error: 'questions must be a non-empty array of strings', example: '{"questions": ["q1", "q2"]}' };
+        }
+        if (!this._toolkit)
+            throw new Error('ResearchTool: setToolkit() must be called before execute');
+        const tw = yield* lloyal_agents_1.Trace.expect();
+        const scope = (0, lloyal_agents_1.traceScope)(tw, null, 'researchTool', { questionCount: questions.length });
+        const toolkit = this._toolkit;
+        const systemPrompt = this._systemPrompt;
+        const reporterPrompt = this._reporterPrompt;
+        const maxTurns = this._maxTurns;
+        const trace = this._trace;
+        const pressure = this._pressure;
+        return yield* (0, lloyal_agents_1.withSharedRoot)({ systemPrompt, tools: toolkit.toolsJson }, function* (root) {
+            const pool = yield* (0, lloyal_agents_1.useAgentPool)({
+                tasks: questions.map(q => ({
+                    systemPrompt,
+                    content: q,
+                    tools: toolkit.toolsJson,
+                    parent: root,
+                })),
+                tools: toolkit.toolMap,
+                terminalTool: 'report',
+                maxTurns,
+                trace,
+                pressure,
+            });
+            // Force hard-cut agents to report — same pattern as prior harness reportPass
+            const hardCut = pool.agents.filter(a => !a.findings && !a.branch.disposed);
+            if (hardCut.length > 0) {
+                for (const a of pool.agents) {
+                    if (a.findings && !a.branch.disposed)
+                        a.branch.pruneSync();
+                }
+                const reportTool = toolkit.toolMap.get('report');
+                const reporters = yield* (0, lloyal_agents_1.runAgents)({
+                    tasks: hardCut.map(a => ({
+                        systemPrompt: reporterPrompt.system,
+                        content: reporterPrompt.user,
+                        tools: JSON.stringify([reportTool.schema]),
+                        parent: a.branch,
+                    })),
+                    tools: new Map([['report', reportTool]]),
+                    terminalTool: 'report',
+                    trace,
+                    pressure: { softLimit: 200, hardLimit: 64 },
+                });
+                hardCut.forEach((a, i) => {
+                    if (reporters.agents[i]?.findings)
+                        a.findings = reporters.agents[i].findings;
+                });
+            }
+            const result = {
+                findings: pool.agents.map(a => a.findings).filter(Boolean),
+                agentCount: pool.agents.length,
+                totalTokens: pool.totalTokens,
+                totalToolCalls: pool.totalToolCalls,
+            };
+            scope.close();
+            return result;
+        });
+    }
+}
+exports.ResearchTool = ResearchTool;
+//# sourceMappingURL=research.js.map

package/dist/tools/research.js.map

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

package/dist/tools/search.d.ts

@@ -0,0 +1,34 @@
+import type { Operation } from 'effection';
+import { Tool } from '@lloyal-labs/lloyal-agents';
+import type { JsonSchema, ToolContext } from '@lloyal-labs/lloyal-agents';
+import type { Chunk } from '../resources/types';
+import type { Reranker } from './types';
+/**
+ * Semantic search over corpus chunks via a {@link Reranker}
+ *
+ * Scores all chunks against the query and returns ranked results
+ * with file names, headings, scores, and line ranges. Progress is
+ * reported through the optional {@link ToolContext.onProgress}
+ * callback as the reranker streams intermediate results.
+ *
+ * @example
+ * ```typescript
+ * const search = new SearchTool(chunks, reranker);
+ * ```
+ *
+ * @category Rig
+ */
+export declare class SearchTool extends Tool<{
+    query: string;
+}> {
+    readonly name = "search";
+    readonly description = "Search the knowledge base. Returns sections ranked by relevance with line ranges for read_file.";
+    readonly parameters: JsonSchema;
+    private _chunks;
+    private _reranker;
+    constructor(chunks: Chunk[], reranker: Reranker);
+    execute(args: {
+        query: string;
+    }, context?: ToolContext): Operation<unknown>;
+}
+//# sourceMappingURL=search.d.ts.map

package/dist/tools/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/tools/search.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAS,MAAM,4BAA4B,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC1E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAe,MAAM,SAAS,CAAC;AAErD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,UAAW,SAAQ,IAAI,CAAC;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;IACrD,QAAQ,CAAC,IAAI,YAAY;IACzB,QAAQ,CAAC,WAAW,qGAAqG;IACzH,QAAQ,CAAC,UAAU,EAAE,UAAU,CAI7B;IAEF,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,SAAS,CAAW;gBAEhB,MAAM,EAAE,KAAK,EAAE,EAAE,QAAQ,EAAE,QAAQ;IAM9C,OAAO,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC,OAAO,CAAC;CAiC7E"}

package/dist/tools/search.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SearchTool = void 0;
+const effection_1 = require("effection");
+const lloyal_agents_1 = require("@lloyal-labs/lloyal-agents");
+/**
+ * Semantic search over corpus chunks via a {@link Reranker}
+ *
+ * Scores all chunks against the query and returns ranked results
+ * with file names, headings, scores, and line ranges. Progress is
+ * reported through the optional {@link ToolContext.onProgress}
+ * callback as the reranker streams intermediate results.
+ *
+ * @example
+ * ```typescript
+ * const search = new SearchTool(chunks, reranker);
+ * ```
+ *
+ * @category Rig
+ */
+class SearchTool extends lloyal_agents_1.Tool {
+    name = 'search';
+    description = 'Search the knowledge base. Returns sections ranked by relevance with line ranges for read_file.';
+    parameters = {
+        type: 'object',
+        properties: { query: { type: 'string', description: 'Search query' } },
+        required: ['query'],
+    };
+    _chunks;
+    _reranker;
+    constructor(chunks, reranker) {
+        super();
+        this._chunks = chunks;
+        this._reranker = reranker;
+    }
+    *execute(args, context) {
+        const query = args.query?.trim();
+        if (!query)
+            return { error: 'query must not be empty' };
+        const tw = yield* lloyal_agents_1.Trace.expect();
+        const reranker = this._reranker;
+        const chunks = this._chunks;
+        const t0 = performance.now();
+        tw.write({
+            traceId: tw.nextId(), parentTraceId: null, ts: t0,
+            type: 'rerank:start', query, chunkCount: chunks.length,
+        });
+        const results = yield* (0, effection_1.call)(async () => {
+            let last = [];
+            for await (const { results, filled, total } of reranker.score(query, chunks)) {
+                if (context?.onProgress)
+                    context.onProgress({ filled, total });
+                last = results;
+            }
+            return last;
+        });
+        tw.write({
+            traceId: tw.nextId(), parentTraceId: null, ts: performance.now(),
+            type: 'rerank:end',
+            topResults: results.slice(0, 5).map(r => ({ file: r.file, heading: r.heading, score: r.score })),
+            selectedPassageCount: results.length,
+            totalChars: 0,
+            durationMs: performance.now() - t0,
+        });
+        return results;
+    }
+}
+exports.SearchTool = SearchTool;
+//# sourceMappingURL=search.js.map

package/dist/tools/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/tools/search.ts"],"names":[],"mappings":";;;AAAA,yCAAiC;AAEjC,8DAAyD;AAKzD;;;;;;;;;;;;;;GAcG;AACH,MAAa,UAAW,SAAQ,oBAAuB;IAC5C,IAAI,GAAG,QAAQ,CAAC;IAChB,WAAW,GAAG,iGAAiG,CAAC;IAChH,UAAU,GAAe;QAChC,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE,EAAE;QACtE,QAAQ,EAAE,CAAC,OAAO,CAAC;KACpB,CAAC;IAEM,OAAO,CAAU;IACjB,SAAS,CAAW;IAE5B,YAAY,MAAe,EAAE,QAAkB;QAC7C,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;IAC5B,CAAC;IAED,CAAC,OAAO,CAAC,IAAuB,EAAE,OAAqB;QACrD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC;QACjC,IAAI,CAAC,KAAK;YAAE,OAAO,EAAE,KAAK,EAAE,yBAAyB,EAAE,CAAC;QACxD,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,qBAAK,CAAC,MAAM,EAAE,CAAC;QACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC;QAE5B,MAAM,EAAE,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAC7B,EAAE,CAAC,KAAK,CAAC;YACP,OAAO,EAAE,EAAE,CAAC,MAAM,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE;YACjD,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM;SACvD,CAAC,CAAC;QAEH,MAAM,OAAO,GAAkB,KAAK,CAAC,CAAC,IAAA,gBAAI,EAAC,KAAK,IAAI,EAAE;YACpD,IAAI,IAAI,GAAkB,EAAE,CAAC;YAC7B,IAAI,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC;gBAC7E,IAAI,OAAO,EAAE,UAAU;oBAAE,OAAO,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;gBAC/D,IAAI,GAAG,OAAO,CAAC;YACjB,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,KAAK,CAAC;YACP,OAAO,EAAE,EAAE,CAAC,MAAM,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,EAAE,EAAE,WAAW,CAAC,GAAG,EAAE;YAChE,IAAI,EAAE,YAAY;YAClB,UAAU,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;YAChG,oBAAoB,EAAE,OAAO,CAAC,MAAM;YACpC,UAAU,EAAE,CAAC;YACb,UAAU,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE;SACnC,CAAC,CAAC;QAEH,OAAO,OAAO,CAAC;IACjB,CAAC;CACF;AAnDD,gCAmDC"}

package/dist/tools/types.d.ts

@@ -0,0 +1,84 @@
+import type { Chunk } from '../resources/types';
+/**
+ * A single chunk scored by the {@link Reranker} against a query
+ *
+ * Returned as part of {@link ScoredResult} from reranker scoring.
+ * Contains the file location, heading, relevance score, and line
+ * range so downstream tools (e.g. {@link ReadFileTool}) can fetch
+ * the exact content.
+ *
+ * @category Rig
+ */
+export interface ScoredChunk {
+    /** Source filename containing the chunk */
+    file: string;
+    /** Section heading the chunk belongs to */
+    heading: string;
+    /** Relevance score (higher = more relevant) */
+    score: number;
+    /** Start line in the source file (1-indexed) */
+    startLine: number;
+    /** End line in the source file (1-indexed) */
+    endLine: number;
+}
+/**
+ * Progressive reranker output emitted during scoring
+ *
+ * Streamed from {@link Reranker.score} as an async iterable,
+ * allowing callers to report progress while scoring is in flight.
+ *
+ * @category Rig
+ */
+export interface ScoredResult {
+    /** Scored chunks accumulated so far, ordered by relevance */
+    results: ScoredChunk[];
+    /** Number of chunks scored so far */
+    filled: number;
+    /** Total number of chunks to score */
+    total: number;
+}
+/**
+ * Embedding-based reranker for scoring corpus chunks against a query
+ *
+ * Implementations tokenize chunks up front via {@link tokenizeChunks},
+ * then stream progressive results from {@link score}. Used by
+ * {@link SearchTool} to rank knowledge-base passages.
+ *
+ * @category Rig
+ */
+export interface Reranker {
+    /** Score chunks against a query, streaming progressive results */
+    score(query: string, chunks: Chunk[]): AsyncIterable<ScoredResult>;
+    /** Pre-tokenize chunks for subsequent scoring calls */
+    tokenizeChunks(chunks: Chunk[]): Promise<void>;
+    /** Release reranker resources */
+    dispose(): void;
+}
+/**
+ * A single result from a {@link SearchProvider} web search
+ *
+ * @category Rig
+ */
+export interface SearchResult {
+    /** Page title */
+    title: string;
+    /** Page URL */
+    url: string;
+    /** Excerpt or snippet from the page content */
+    snippet: string;
+}
+/**
+ * Adapter interface for web search backends
+ *
+ * Implement this to plug in a search provider (e.g. Tavily, Brave,
+ * SerpAPI). Pass the implementation to {@link WebSearchTool}.
+ *
+ * @see {@link TavilyProvider} for the default implementation
+ *
+ * @category Rig
+ */
+export interface SearchProvider {
+    /** Execute a web search and return ranked results */
+    search(query: string, maxResults: number): Promise<SearchResult[]>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/tools/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEhD;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAQ;IACvB,kEAAkE;IAClE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,aAAa,CAAC,YAAY,CAAC,CAAC;IACnE,uDAAuD;IACvD,cAAc,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,iCAAiC;IACjC,OAAO,IAAI,IAAI,CAAC;CACjB;AAID;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,eAAe;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CACpE"}

package/dist/tools/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/tools/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":""}

package/dist/tools/web-research.d.ts

@@ -0,0 +1,60 @@
+import type { Operation } from "effection";
+import { Tool } from "@lloyal-labs/lloyal-agents";
+import type { JsonSchema, Toolkit, PressureThresholds } from "@lloyal-labs/lloyal-agents";
+/**
+ * Configuration for {@link WebResearchTool}.
+ *
+ * @category Rig
+ */
+export interface WebResearchToolOpts {
+    /** Override the tool name exposed to the model. @defaultValue "research" */
+    name?: string;
+    /** Override the tool description exposed to the model. */
+    description?: string;
+    /** System prompt given to each spawned web-research sub-agent. */
+    systemPrompt: string;
+    /** Prompts used for grammar-constrained scratchpad extraction on hard-cut agents. */
+    reporterPrompt: {
+        system: string;
+        user: string;
+    };
+    /** Maximum tool-use turns per sub-agent before hard cut. @defaultValue 20 */
+    maxTurns?: number;
+    /** Enable trace output for sub-agent execution. @defaultValue false */
+    trace?: boolean;
+    /** Context pressure thresholds for the sub-agent pool. */
+    pressure?: PressureThresholds;
+}
+/**
+ * Spawn parallel web-research sub-agents for a set of questions.
+ *
+ * Similar to {@link ResearchTool} but designed for web-source pipelines.
+ * Each question gets its own agent in a shared-root pool with access
+ * to web_search, fetch_page, and report tools. Hard-cut agents that
+ * exhaust their turns without reporting get a grammar-constrained
+ * scratchpad extraction via {@link generate} to recover partial findings.
+ *
+ * Must call {@link setToolkit} before the tool is executed.
+ *
+ * @category Rig
+ */
+export declare class WebResearchTool extends Tool<{
+    questions: string[];
+}> {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: JsonSchema;
+    private _systemPrompt;
+    private _reporterPrompt;
+    private _maxTurns;
+    private _trace;
+    private _pressure?;
+    private _toolkit;
+    constructor(opts: WebResearchToolOpts);
+    /** Inject the toolkit that sub-agents will use. Must be called before execute. */
+    setToolkit(toolkit: Toolkit): void;
+    execute(args: {
+        questions: string[];
+    }): Operation<unknown>;
+}
+//# sourceMappingURL=web-research.d.ts.map

package/dist/tools/web-research.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-research.d.ts","sourceRoot":"","sources":["../../src/tools/web-research.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EACL,IAAI,EAOL,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EACV,UAAU,EACV,OAAO,EACP,kBAAkB,EACnB,MAAM,4BAA4B,CAAC;AAEpC;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,cAAc,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAgB,SAAQ,IAAI,CAAC;IAAE,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAU7B;IAEF,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,eAAe,CAAmC;IAC1D,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,SAAS,CAAC,CAAqB;IACvC,OAAO,CAAC,QAAQ,CAAwB;gBAE5B,IAAI,EAAE,mBAAmB;IAarC,kFAAkF;IAClF,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAIjC,OAAO,CAAC,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,SAAS,CAAC,OAAO,CAAC;CA2F5D"}