bernard-agent 0.8.1 → 0.9.0

package/dist/tools/tool-wrapper-run.js

@@ -0,0 +1,382 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatExamples = formatExamples;
+exports.buildChildTools = buildChildTools;
+exports.captureLastToolCall = captureLastToolCall;
+exports.captureToolCalls = captureToolCalls;
+exports.dispatchToolWrapper = dispatchToolWrapper;
+exports.renderWrapperParentView = renderWrapperParentView;
+exports.createToolWrapperRunTool = createToolWrapperRunTool;
+const ai_1 = require("ai");
+const zod_1 = require("zod");
+const index_js_1 = require("../providers/index.js");
+const index_js_2 = require("./index.js");
+const subagent_js_1 = require("./subagent.js");
+const task_js_1 = require("./task.js");
+const specialist_run_js_1 = require("./specialist-run.js");
+const task_js_2 = require("./task.js");
+const output_js_1 = require("../output.js");
+const logger_js_1 = require("../logger.js");
+const memory_context_js_1 = require("../memory-context.js");
+const agent_pool_js_1 = require("./agent-pool.js");
+const config_js_1 = require("../config.js");
+const os_info_js_1 = require("../os-info.js");
+const structured_output_js_1 = require("../structured-output.js");
+const reasoning_log_js_1 = require("../reasoning-log.js");
+const result_cap_js_1 = require("./result-cap.js");
+/** Fraction of config.maxSteps allocated to a tool-wrapper run. Mirrors task/specialist ratios. */
+const TOOL_WRAPPER_STEP_RATIO = 0.5;
+/** Formats good/bad examples as a markdown block appended to the child's system prompt. */
+function formatExamples(specialist) {
+    const parts = [];
+    const good = specialist.goodExamples ?? [];
+    const bad = specialist.badExamples ?? [];
+    if (good.length > 0) {
+        parts.push('\n\n## Good Examples (follow these patterns)');
+        for (const ex of good) {
+            parts.push(`\n- Input: ${ex.input}\n  Call: ${ex.call}`);
+            if (ex.note)
+                parts.push(`\n  Note: ${ex.note}`);
+        }
+    }
+    if (bad.length > 0) {
+        parts.push('\n\n## Bad Examples (AVOID these patterns)');
+        for (const ex of bad) {
+            parts.push(`\n- Input: ${ex.input}\n  Bad call: ${ex.call}\n  Error observed: ${ex.error}\n  Correct approach: ${ex.fix}`);
+            if (ex.note)
+                parts.push(`\n  Note: ${ex.note}`);
+        }
+    }
+    return parts.join('');
+}
+/**
+ * Builds the full tool registry a tool-wrapper specialist could possibly
+ * reach, then intersects with `targetTools` when set. Persona/tool-wrapper
+ * specialists get strict isolation; meta specialists typically pass
+ * `targetTools` that include dispatch tools (specialist, tool_wrapper_run)
+ * for recursive orchestration.
+ */
+function buildChildTools(specialist, fullRegistry) {
+    const targets = specialist.targetTools;
+    if (!targets || targets.length === 0) {
+        // No filter specified — expose everything. Common for meta specialists.
+        return fullRegistry;
+    }
+    const filtered = {};
+    for (const name of targets) {
+        if (fullRegistry[name])
+            filtered[name] = fullRegistry[name];
+    }
+    return filtered;
+}
+/**
+ * Captures the last tool call observed in a `generateText` result.
+ * Used to populate `attemptedCall` on correction candidates.
+ */
+function captureLastToolCall(steps) {
+    if (!steps || steps.length === 0)
+        return '(no tool call)';
+    for (let i = steps.length - 1; i >= 0; i--) {
+        const step = steps[i];
+        const calls = step?.toolCalls ?? [];
+        if (calls.length > 0) {
+            const tc = calls[calls.length - 1];
+            try {
+                return `${tc.toolName} ${JSON.stringify(tc.args).slice(0, 600)}`;
+            }
+            catch {
+                return `${tc.toolName} (unserializable args)`;
+            }
+        }
+    }
+    return '(no tool call)';
+}
+/**
+ * Builds a compact record of tool calls for the reasoning log.
+ */
+function captureToolCalls(steps) {
+    if (!steps)
+        return [];
+    const out = [];
+    for (const step of steps) {
+        const calls = step?.toolCalls ?? [];
+        const results = step?.toolResults ?? [];
+        for (let i = 0; i < calls.length; i++) {
+            const tc = calls[i];
+            const tr = results[i];
+            const resultText = tr?.result === undefined ? '' : String(tr.result);
+            out.push({
+                tool: tc.toolName,
+                args: tc.args,
+                resultPreview: resultText.slice(0, 300),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Core dispatch for tool-wrapper specialists. Used by both the explicit
+ * `tool_wrapper_run` tool and the shim layer that routes raw tool calls
+ * (e.g. `shell`) through their corresponding wrapper specialist.
+ *
+ * Returns a {@link WrapperResult} so callers can shape the parent-facing
+ * response however they like (JSON envelope, raw result, error string).
+ * Pool acquisition, reasoning logging, and correction-candidate enqueue
+ * happen inside.
+ */
+async function dispatchToolWrapper(args, deps) {
+    const { specialistId, input, context, provider, model, abortSignal, runLabel } = args;
+    const { config, options, memoryStore, specialistStore, correctionStore, mcpTools, ragStore, routineStore, candidateStore, } = deps;
+    const specialist = specialistStore.get(specialistId);
+    if (!specialist) {
+        return {
+            status: 'error',
+            result: `No specialist found with id "${specialistId}".`,
+            error: 'not_found',
+        };
+    }
+    const kind = specialist.kind ?? 'persona';
+    if (kind === 'persona') {
+        return {
+            status: 'error',
+            result: `Specialist "${specialistId}" is a persona specialist. Use specialist_run instead, or update its kind to "tool-wrapper".`,
+            error: 'wrong_kind',
+        };
+    }
+    const resolution = (0, config_js_1.resolveProviderAndModel)({
+        provider,
+        model,
+        specialistProvider: specialist.provider,
+        specialistModel: specialist.model,
+        config,
+    });
+    if (!resolution.ok) {
+        const hint = resolution.isCustom
+            ? `Run: bernard add-key ${resolution.provider} <key>`
+            : `Set ${resolution.envVar} or run: bernard add-key ${resolution.provider} <key>`;
+        return {
+            status: 'error',
+            result: `No API key for provider "${resolution.provider}". ${hint}.`,
+            error: 'no_api_key',
+        };
+    }
+    const { provider: resolvedProvider, model: resolvedModel } = resolution;
+    const slot = (0, agent_pool_js_1.acquireSlot)();
+    if (!slot) {
+        return {
+            status: 'error',
+            result: `Maximum concurrent agents (${agent_pool_js_1.MAX_CONCURRENT_AGENTS}) reached.`,
+            error: 'pool_exhausted',
+        };
+    }
+    const id = slot.id;
+    const prefix = `wrap:${id}`;
+    const label = runLabel ?? `[${kind}] ${specialist.name}`;
+    (0, output_js_1.printSpecialistStart)(id, label, input);
+    try {
+        const baseTools = (0, index_js_2.createTools)(options, memoryStore, mcpTools, routineStore, specialistStore, candidateStore, config);
+        const fullRegistry = {
+            ...baseTools,
+            agent: (0, subagent_js_1.createSubAgentTool)(config, options, memoryStore, mcpTools, ragStore),
+            task: (0, task_js_1.createTaskTool)(config, options, memoryStore, mcpTools, ragStore, routineStore),
+            specialist_run: (0, specialist_run_js_1.createSpecialistRunTool)(config, options, memoryStore, specialistStore, mcpTools, ragStore),
+            tool_wrapper_run: createToolWrapperRunTool(config, options, memoryStore, specialistStore, correctionStore, mcpTools, ragStore, routineStore, candidateStore),
+        };
+        const childTools = buildChildTools(specialist, fullRegistry);
+        let systemPrompt = specialist.systemPrompt;
+        if (specialist.guidelines.length > 0) {
+            systemPrompt += '\n\nGuidelines:\n' + specialist.guidelines.map((g) => `- ${g}`).join('\n');
+        }
+        systemPrompt += '\n\n' + (0, os_info_js_1.osPromptBlock)();
+        systemPrompt += formatExamples(specialist);
+        // Default to structured output for tool-wrapper specialists unless explicitly disabled.
+        const wantStructured = specialist.structuredOutput ?? kind === 'tool-wrapper';
+        if (wantStructured) {
+            systemPrompt += structured_output_js_1.STRUCTURED_OUTPUT_RULES;
+        }
+        systemPrompt += (0, memory_context_js_1.buildMemoryContext)({
+            memoryStore,
+            ragResults: undefined,
+            includeScratch: true,
+        });
+        if (Object.keys(childTools).length > 0) {
+            systemPrompt += `\n\nAvailable tools for this run: ${Object.keys(childTools).join(', ')}`;
+        }
+        else {
+            systemPrompt +=
+                '\n\nNo tools are available for this run. Produce the structured output based on reasoning alone.';
+        }
+        let userMessage = `Request: ${input}`;
+        if (context)
+            userMessage += `\n\nContext: ${context}`;
+        const maxSteps = Math.max(2, Math.ceil(config.maxSteps * TOOL_WRAPPER_STEP_RATIO));
+        const onStepFinish = ({ text, toolCalls, toolResults }) => {
+            for (const tc of toolCalls ?? []) {
+                (0, output_js_1.printToolCall)(tc.toolName, tc.args, prefix);
+            }
+            for (const tr of toolResults ?? []) {
+                (0, output_js_1.printToolResult)(tr.toolName, tr.result, prefix);
+            }
+            if (text)
+                (0, output_js_1.printAssistantText)(text, prefix);
+        };
+        // Lazy import to avoid a top-level cycle (tool-call-repair → providers).
+        const { makeRepairHook } = await import('../tool-call-repair.js');
+        const repairHook = makeRepairHook({
+            config,
+            provider: resolvedProvider,
+            model: resolvedModel,
+            label: 'tool-wrapper',
+            abortSignal,
+        });
+        const result = await (0, ai_1.generateText)({
+            model: (0, index_js_1.getModelForConfig)(config, resolvedProvider, resolvedModel),
+            providerOptions: (0, index_js_1.getProviderOptionsForConfig)(config, resolvedProvider),
+            tools: childTools,
+            maxSteps,
+            maxTokens: config.maxTokens,
+            system: systemPrompt,
+            messages: [{ role: 'user', content: userMessage }],
+            abortSignal,
+            experimental_prepareStep: wantStructured ? (0, task_js_2.makeLastStepTextOnly)(maxSteps) : undefined,
+            experimental_repairToolCall: repairHook,
+            onStepFinish,
+        });
+        (0, output_js_1.printSpecialistEnd)(id);
+        const wrapped = wantStructured
+            ? (0, structured_output_js_1.wrapWrapperResult)(result.text)
+            : { status: 'ok', result: result.text };
+        (0, reasoning_log_js_1.appendReasoningLog)({
+            ts: new Date().toISOString(),
+            specialistId,
+            input,
+            toolCalls: captureToolCalls(result.steps),
+            finalOutput: wrapped.result,
+            status: wrapped.status === 'ok'
+                ? 'ok'
+                : wrapped.error === 'parse_failed'
+                    ? 'parse_failed'
+                    : 'error',
+            ...(wrapped.error !== undefined ? { error: wrapped.error } : {}),
+            ...(wrapped.reasoning !== undefined ? { reasoning: wrapped.reasoning } : {}),
+        });
+        if (wrapped.status === 'error' && kind === 'tool-wrapper') {
+            try {
+                correctionStore.enqueue({
+                    specialistId,
+                    input,
+                    attemptedCall: captureLastToolCall(result.steps),
+                    error: wrapped.error ?? String(wrapped.result),
+                });
+            }
+            catch (err) {
+                (0, logger_js_1.debugLog)('tool-wrapper:correction-enqueue:error', err instanceof Error ? err.message : String(err));
+            }
+        }
+        return wrapped;
+    }
+    catch (err) {
+        (0, output_js_1.printSpecialistEnd)(id);
+        const message = err instanceof Error ? err.message : String(err);
+        (0, reasoning_log_js_1.appendReasoningLog)({
+            ts: new Date().toISOString(),
+            specialistId,
+            input,
+            toolCalls: [],
+            finalOutput: message,
+            status: 'error',
+            error: 'runtime_error',
+        });
+        return { status: 'error', result: message, error: 'runtime_error' };
+    }
+    finally {
+        (0, agent_pool_js_1.releaseSlot)();
+    }
+}
+/**
+ * Strips internal fields (`reasoning`) from a wrapper result before it crosses
+ * back into the parent agent's context, and caps the `result` field so the
+ * outer JSON envelope stays parseable when the wrapper output is large. The
+ * reasoning array is already persisted to the JSONL trace via
+ * {@link appendReasoningLog}; the parent doesn't need it.
+ *
+ * The cap is applied to the `result` field *before* serialization rather than
+ * to the serialized envelope, so a truncated payload never produces invalid
+ * JSON.
+ */
+function renderWrapperParentView(wrapped, maxChars = result_cap_js_1.SUBAGENT_RESULT_MAX_CHARS) {
+    const errorLen = wrapped.error?.length ?? 0;
+    const resultBudget = Math.max(256, maxChars - errorLen - 80);
+    const cappedResult = typeof wrapped.result === 'string'
+        ? (0, result_cap_js_1.capSubagentResult)(wrapped.result, resultBudget)
+        : (() => {
+            const asJson = JSON.stringify(wrapped.result);
+            if (asJson === undefined || asJson.length <= resultBudget)
+                return wrapped.result;
+            return (0, result_cap_js_1.capSubagentResult)(asJson, resultBudget);
+        })();
+    const parentView = wrapped.status === 'ok'
+        ? { status: 'ok', result: cappedResult }
+        : {
+            status: 'error',
+            result: cappedResult,
+            ...(wrapped.error !== undefined ? { error: wrapped.error } : {}),
+        };
+    return JSON.stringify(parentView);
+}
+/**
+ * Creates the `tool_wrapper_run` tool for structured, isolated tool-wrapper
+ * specialist execution with validated JSON output and failure-learning.
+ *
+ * Unlike `specialist_run` (plain-text persona execution), this dispatch:
+ *   - only runs specialists with `kind` in `'tool-wrapper' | 'meta'`
+ *   - restricts the child's tool set to the specialist's `targetTools`
+ *   - injects OS context + good/bad examples + structured-output rules
+ *   - forces a JSON final message via `experimental_prepareStep`
+ *   - parses through a Zod schema and logs runs that reach `generateText`
+ *     to the reasoning log (guard failures return early without logging)
+ *   - enqueues a correction candidate on error for end-of-session learning
+ *   - strips `reasoning` and caps the JSON envelope before returning to the
+ *     parent agent — the full reasoning lives in the JSONL trace only
+ */
+function createToolWrapperRunTool(config, options, memoryStore, specialistStore, correctionStore, mcpTools, ragStore, routineStore, candidateStore) {
+    return (0, ai_1.tool)({
+        description: 'Dispatch to a saved tool-wrapper specialist that handles a concrete tool or CLI (e.g. shell-wrapper, file-wrapper). Returns JSON {status, result, error?}. Use this for tool-heavy operations where domain-specific examples and error handling reduce misuse. Also used to invoke meta specialists (specialist-creator, correction-agent).',
+        parameters: zod_1.z.object({
+            specialistId: zod_1.z
+                .string()
+                .describe('The ID of the tool-wrapper or meta specialist to invoke (e.g. "shell-wrapper").'),
+            input: zod_1.z
+                .string()
+                .describe('The natural-language request to hand to the specialist. Be specific — the specialist has no prior context.'),
+            context: zod_1.z
+                .string()
+                .optional()
+                .describe('Optional additional context (file paths, prior findings, constraints).'),
+            provider: zod_1.z.string().optional().describe('Optional provider override for this invocation.'),
+            model: zod_1.z.string().optional().describe('Optional model override for this invocation.'),
+        }),
+        execute: async ({ specialistId, input, context, provider, model }, execOptions) => {
+            const wrapped = await dispatchToolWrapper({
+                specialistId,
+                input,
+                context,
+                provider,
+                model,
+                abortSignal: execOptions.abortSignal,
+            }, {
+                config,
+                options,
+                memoryStore,
+                specialistStore,
+                correctionStore,
+                mcpTools,
+                ragStore,
+                routineStore,
+                candidateStore,
+            });
+            return renderWrapperParentView(wrapped);
+        },
+    });
+}
+//# sourceMappingURL=tool-wrapper-run.js.map

package/dist/tools/tool-wrapper-run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-wrapper-run.js","sourceRoot":"","sources":["../../src/tools/tool-wrapper-run.ts"],"names":[],"mappings":";;AAsCA,wCAqBC;AASD,0CAcC;AAMD,kDAeC;AAKD,4CAsBC;AAqCD,kDA4NC;AAaD,0DAyBC;AAiBD,4DAyDC;AAnfD,2BAAwC;AACxC,6BAAwB;AACxB,oDAAuF;AACvF,yCAA2D;AAC3D,+CAAmD;AACnD,uCAA2C;AAC3C,2DAA8D;AAC9D,uCAAiD;AACjD,4CAMsB;AACtB,4CAAwC;AACxC,4DAA0D;AAC1D,mDAAkF;AAClF,4CAA2E;AAO3E,8CAA8C;AAC9C,kEAIiC;AACjC,0DAAyD;AACzD,mDAA+E;AAE/E,mGAAmG;AACnG,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAEpC,2FAA2F;AAC3F,SAAgB,cAAc,CAAC,UAAsB;IACnD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,IAAI,GAAG,UAAU,CAAC,YAAY,IAAI,EAAE,CAAC;IAC3C,MAAM,GAAG,GAAG,UAAU,CAAC,WAAW,IAAI,EAAE,CAAC;IACzC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpB,KAAK,CAAC,IAAI,CAAC,8CAA8C,CAAC,CAAC;QAC3D,KAAK,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC;YACtB,KAAK,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC,KAAK,aAAa,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;YACzD,IAAI,EAAE,CAAC,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnB,KAAK,CAAC,IAAI,CAAC,4CAA4C,CAAC,CAAC;QACzD,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;YACrB,KAAK,CAAC,IAAI,CACR,cAAc,EAAE,CAAC,KAAK,iBAAiB,EAAE,CAAC,IAAI,uBAAuB,EAAE,CAAC,KAAK,yBAAyB,EAAE,CAAC,GAAG,EAAE,CAC/G,CAAC;YACF,IAAI,EAAE,CAAC,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACxB,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,eAAe,CAC7B,UAAsB,EACtB,YAAiC;IAEjC,MAAM,OAAO,GAAG,UAAU,CAAC,WAAW,CAAC;IACvC,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrC,wEAAwE;QACxE,OAAO,YAAY,CAAC;IACtB,CAAC;IACD,MAAM,QAAQ,GAAwB,EAAE,CAAC;IACzC,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,IAAI,YAAY,CAAC,IAAI,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,SAAgB,mBAAmB,CAAC,KAAwB;IAC1D,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,gBAAgB,CAAC;IAC1D,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3C,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,MAAM,KAAK,GAAG,IAAI,EAAE,SAAS,IAAI,EAAE,CAAC;QACpC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YACnC,IAAI,CAAC;gBACH,OAAO,GAAG,EAAE,CAAC,QAAQ,IAAI,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;YACnE,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,GAAG,EAAE,CAAC,QAAQ,wBAAwB,CAAC;YAChD,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED;;GAEG;AACH,SAAgB,gBAAgB,CAAC,KAAwB;IAKvD,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IACtB,MAAM,GAAG,GAAkE,EAAE,CAAC;IAC9E,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,IAAI,EAAE,SAAS,IAAI,EAAE,CAAC;QACpC,MAAM,OAAO,GAAG,IAAI,EAAE,WAAW,IAAI,EAAE,CAAC;QACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YACpB,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;YACtB,MAAM,UAAU,GAAG,EAAE,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;YACrE,GAAG,CAAC,IAAI,CAAC;gBACP,IAAI,EAAE,EAAE,CAAC,QAAQ;gBACjB,IAAI,EAAE,EAAE,CAAC,IAAI;gBACb,aAAa,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;aACxC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AA2BD;;;;;;;;;GASG;AACI,KAAK,UAAU,mBAAmB,CACvC,IAA6B,EAC7B,IAAqB;IAErB,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IACtF,MAAM,EACJ,MAAM,EACN,OAAO,EACP,WAAW,EACX,eAAe,EACf,eAAe,EACf,QAAQ,EACR,QAAQ,EACR,YAAY,EACZ,cAAc,GACf,GAAG,IAAI,CAAC;IAET,MAAM,UAAU,GAAG,eAAe,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACrD,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO;YACL,MAAM,EAAE,OAAO;YACf,MAAM,EAAE,gCAAgC,YAAY,IAAI;YACxD,KAAK,EAAE,WAAW;SACnB,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,IAAI,SAAS,CAAC;IAC1C,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO;YACL,MAAM,EAAE,OAAO;YACf,MAAM,EAAE,eAAe,YAAY,8FAA8F;YACjI,KAAK,EAAE,YAAY;SACpB,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,IAAA,mCAAuB,EAAC;QACzC,QAAQ;QACR,KAAK;QACL,kBAAkB,EAAE,UAAU,CAAC,QAAQ;QACvC,eAAe,EAAE,UAAU,CAAC,KAAK;QACjC,MAAM;KACP,CAAC,CAAC;IACH,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC;QACnB,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ;YAC9B,CAAC,CAAC,wBAAwB,UAAU,CAAC,QAAQ,QAAQ;YACrD,CAAC,CAAC,OAAO,UAAU,CAAC,MAAM,4BAA4B,UAAU,CAAC,QAAQ,QAAQ,CAAC;QACpF,OAAO;YACL,MAAM,EAAE,OAAO;YACf,MAAM,EAAE,4BAA4B,UAAU,CAAC,QAAQ,MAAM,IAAI,GAAG;YACpE,KAAK,EAAE,YAAY;SACpB,CAAC;IACJ,CAAC;IACD,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,UAAU,CAAC;IAExE,MAAM,IAAI,GAAG,IAAA,2BAAW,GAAE,CAAC;IAC3B,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO;YACL,MAAM,EAAE,OAAO;YACf,MAAM,EAAE,8BAA8B,qCAAqB,YAAY;YACvE,KAAK,EAAE,gBAAgB;SACxB,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;IACnB,MAAM,MAAM,GAAG,QAAQ,EAAE,EAAE,CAAC;IAC5B,MAAM,KAAK,GAAG,QAAQ,IAAI,IAAI,IAAI,KAAK,UAAU,CAAC,IAAI,EAAE,CAAC;IACzD,IAAA,gCAAoB,EAAC,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IAEvC,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,IAAA,sBAAW,EAC3B,OAAO,EACP,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,eAAe,EACf,cAAc,EACd,MAAM,CACP,CAAC;QACF,MAAM,YAAY,GAAwB;YACxC,GAAG,SAAS;YACZ,KAAK,EAAE,IAAA,gCAAkB,EAAC,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,CAAC;YAC3E,IAAI,EAAE,IAAA,wBAAc,EAAC,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,CAAC;YACpF,cAAc,EAAE,IAAA,2CAAuB,EACrC,MAAM,EACN,OAAO,EACP,WAAW,EACX,eAAe,EACf,QAAQ,EACR,QAAQ,CACT;YACD,gBAAgB,EAAE,wBAAwB,CACxC,MAAM,EACN,OAAO,EACP,WAAW,EACX,eAAe,EACf,eAAe,EACf,QAAQ,EACR,QAAQ,EACR,YAAY,EACZ,cAAc,CACf;SACF,CAAC;QACF,MAAM,UAAU,GAAG,eAAe,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;QAE7D,IAAI,YAAY,GAAG,UAAU,CAAC,YAAY,CAAC;QAC3C,IAAI,UAAU,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrC,YAAY,IAAI,mBAAmB,GAAG,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9F,CAAC;QACD,YAAY,IAAI,MAAM,GAAG,IAAA,0BAAa,GAAE,CAAC;QACzC,YAAY,IAAI,cAAc,CAAC,UAAU,CAAC,CAAC;QAC3C,wFAAwF;QACxF,MAAM,cAAc,GAAG,UAAU,CAAC,gBAAgB,IAAI,IAAI,KAAK,cAAc,CAAC;QAC9E,IAAI,cAAc,EAAE,CAAC;YACnB,YAAY,IAAI,8CAAuB,CAAC;QAC1C,CAAC;QACD,YAAY,IAAI,IAAA,sCAAkB,EAAC;YACjC,WAAW;YACX,UAAU,EAAE,SAAS;YACrB,cAAc,EAAE,IAAI;SACrB,CAAC,CAAC;QACH,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvC,YAAY,IAAI,qCAAqC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5F,CAAC;aAAM,CAAC;YACN,YAAY;gBACV,kGAAkG,CAAC;QACvG,CAAC;QAED,IAAI,WAAW,GAAG,YAAY,KAAK,EAAE,CAAC;QACtC,IAAI,OAAO;YAAE,WAAW,IAAI,gBAAgB,OAAO,EAAE,CAAC;QAEtD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,GAAG,uBAAuB,CAAC,CAAC,CAAC;QAEnF,MAAM,YAAY,GAAG,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAO,EAAE,EAAE;YAC7D,KAAK,MAAM,EAAE,IAAI,SAAS,IAAI,EAAE,EAAE,CAAC;gBACjC,IAAA,yBAAa,EAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,IAA+B,EAAE,MAAM,CAAC,CAAC;YACzE,CAAC;YACD,KAAK,MAAM,EAAE,IAAI,WAAW,IAAI,EAAE,EAAE,CAAC;gBACnC,IAAA,2BAAe,EAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YAClD,CAAC;YACD,IAAI,IAAI;gBAAE,IAAA,8BAAkB,EAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC7C,CAAC,CAAC;QAEF,yEAAyE;QACzE,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,wBAAwB,CAAC,CAAC;QAClE,MAAM,UAAU,GAAG,cAAc,CAAC;YAChC,MAAM;YACN,QAAQ,EAAE,gBAAgB;YAC1B,KAAK,EAAE,aAAa;YACpB,KAAK,EAAE,cAAc;YACrB,WAAW;SACZ,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,MAAM,IAAA,iBAAY,EAAC;YAChC,KAAK,EAAE,IAAA,4BAAiB,EAAC,MAAM,EAAE,gBAAgB,EAAE,aAAa,CAAC;YACjE,eAAe,EAAE,IAAA,sCAA2B,EAAC,MAAM,EAAE,gBAAgB,CAAC;YACtE,KAAK,EAAE,UAAU;YACjB,QAAQ;YACR,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,MAAM,EAAE,YAAY;YACpB,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;YAClD,WAAW;YACX,wBAAwB,EAAE,cAAc,CAAC,CAAC,CAAC,IAAA,8BAAoB,EAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS;YACrF,2BAA2B,EAAE,UAAU;YACvC,YAAY;SACb,CAAC,CAAC;QAEH,IAAA,8BAAkB,EAAC,EAAE,CAAC,CAAC;QAEvB,MAAM,OAAO,GAAG,cAAc;YAC5B,CAAC,CAAC,IAAA,wCAAiB,EAAC,MAAM,CAAC,IAAI,CAAC;YAChC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAa,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;QAEnD,IAAA,qCAAkB,EAAC;YACjB,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YAC5B,YAAY;YACZ,KAAK;YACL,SAAS,EAAE,gBAAgB,CAAC,MAAM,CAAC,KAAc,CAAC;YAClD,WAAW,EAAE,OAAO,CAAC,MAAM;YAC3B,MAAM,EACJ,OAAO,CAAC,MAAM,KAAK,IAAI;gBACrB,CAAC,CAAC,IAAI;gBACN,CAAC,CAAC,OAAO,CAAC,KAAK,KAAK,cAAc;oBAChC,CAAC,CAAC,cAAc;oBAChB,CAAC,CAAC,OAAO;YACf,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAChE,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC7E,CAAC,CAAC;QAEH,IAAI,OAAO,CAAC,MAAM,KAAK,OAAO,IAAI,IAAI,KAAK,cAAc,EAAE,CAAC;YAC1D,IAAI,CAAC;gBACH,eAAe,CAAC,OAAO,CAAC;oBACtB,YAAY;oBACZ,KAAK;oBACL,aAAa,EAAE,mBAAmB,CAAC,MAAM,CAAC,KAAc,CAAC;oBACzD,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;iBAC/C,CAAC,CAAC;YACL,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAA,oBAAQ,EACN,uCAAuC,EACvC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CACjD,CAAC;YACJ,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,IAAA,8BAAkB,EAAC,EAAE,CAAC,CAAC;QACvB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,IAAA,qCAAkB,EAAC;YACjB,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YAC5B,YAAY;YACZ,KAAK;YACL,SAAS,EAAE,EAAE;YACb,WAAW,EAAE,OAAO;YACpB,MAAM,EAAE,OAAO;YACf,KAAK,EAAE,eAAe;SACvB,CAAC,CAAC;QACH,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC;IACtE,CAAC;YAAS,CAAC;QACT,IAAA,2BAAW,GAAE,CAAC;IAChB,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,uBAAuB,CACrC,OAAsB,EACtB,WAAmB,yCAAyB;IAE5C,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC,CAAC;IAC5C,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,GAAG,QAAQ,GAAG,EAAE,CAAC,CAAC;IAE7D,MAAM,YAAY,GAChB,OAAO,OAAO,CAAC,MAAM,KAAK,QAAQ;QAChC,CAAC,CAAC,IAAA,iCAAiB,EAAC,OAAO,CAAC,MAAM,EAAE,YAAY,CAAC;QACjD,CAAC,CAAC,CAAC,GAAG,EAAE;YACJ,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAC9C,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,IAAI,YAAY;gBAAE,OAAO,OAAO,CAAC,MAAM,CAAC;YACjF,OAAO,IAAA,iCAAiB,EAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QACjD,CAAC,CAAC,EAAE,CAAC;IAEX,MAAM,UAAU,GACd,OAAO,CAAC,MAAM,KAAK,IAAI;QACrB,CAAC,CAAC,EAAE,MAAM,EAAE,IAAa,EAAE,MAAM,EAAE,YAAY,EAAE;QACjD,CAAC,CAAC;YACE,MAAM,EAAE,OAAgB;YACxB,MAAM,EAAE,YAAY;YACpB,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACjE,CAAC;IACR,OAAO,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,wBAAwB,CACtC,MAAqB,EACrB,OAAoB,EACpB,WAAwB,EACxB,eAAgC,EAChC,eAAyC,EACzC,QAA8B,EAC9B,QAAmB,EACnB,YAA2B,EAC3B,cAAqC;IAErC,OAAO,IAAA,SAAI,EAAC;QACV,WAAW,EACT,6UAA6U;QAC/U,UAAU,EAAE,OAAC,CAAC,MAAM,CAAC;YACnB,YAAY,EAAE,OAAC;iBACZ,MAAM,EAAE;iBACR,QAAQ,CACP,iFAAiF,CAClF;YACH,KAAK,EAAE,OAAC;iBACL,MAAM,EAAE;iBACR,QAAQ,CACP,4GAA4G,CAC7G;YACH,OAAO,EAAE,OAAC;iBACP,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,wEAAwE,CAAC;YACrF,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iDAAiD,CAAC;YAC3F,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,8CAA8C,CAAC;SACtF,CAAC;QACF,OAAO,EAAE,KAAK,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,EAAE;YAChF,MAAM,OAAO,GAAG,MAAM,mBAAmB,CACvC;gBACE,YAAY;gBACZ,KAAK;gBACL,OAAO;gBACP,QAAQ;gBACR,KAAK;gBACL,WAAW,EAAE,WAAW,CAAC,WAAW;aACrC,EACD;gBACE,MAAM;gBACN,OAAO;gBACP,WAAW;gBACX,eAAe;gBACf,eAAe;gBACf,QAAQ;gBACR,QAAQ;gBACR,YAAY;gBACZ,cAAc;aACf,CACF,CAAC;YACF,OAAO,uBAAuB,CAAC,OAAO,CAAC,CAAC;QAC1C,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/tools/types.d.ts

@@ -1,9 +1,35 @@
+/** A single question for the `askUser` callback. */
+export interface AskUserQuestion {
+    question: string;
+    choices?: string[];
+    /** When true and `choices` is present, the implementation appends an escape-hatch row that falls back to free-form input. */
+    allowOther: boolean;
+    /** Optional label for the escape-hatch row; defaults to a generic "Other" wording. */
+    otherLabel?: string;
+}
+/** Result of an `askUser` batch interaction. `answered` is aligned by index with the input questions. */
+export type AskUserBatchResult = {
+    answers: string[];
+} | {
+    cancelled: true;
+    answered: string[];
+};
 /** Options shared by all tool implementations. */
 export interface ToolOptions {
     /** Maximum time in milliseconds a shell command may run before being killed. */
     shellTimeout: number;
-    /** Callback that prompts the user for confirmation before executing a dangerous command. */
-    confirmDangerous: (command: string) => Promise<boolean>;
+    /**
+     * Callback that prompts the user for confirmation before executing a dangerous command.
+     * The optional `signal` lets callers abort the prompt (e.g. when the user presses Esc).
+     */
+    confirmDangerous: (command: string, signal?: AbortSignal) => Promise<boolean>;
+    /**
+     * Callback that asks the user one or more questions in sequence. The
+     * implementation owns any progress UI (e.g. a tab strip for batches of
+     * 2+). On mid-batch cancellation, returns whatever was answered so far.
+     * Omitted in non-interactive environments (cron daemon).
+     */
+    askUser?: (questions: AskUserQuestion[], signal?: AbortSignal) => Promise<AskUserBatchResult>;
 }
 /** Outcome of a shell tool invocation. */
 export interface ShellResult {

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

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+/** One search result. Kept minimal so the LLM can cheaply decide which URLs to `web_read`. */
+export interface SearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+}
+/**
+ * Creates the `web_search` tool.
+ *
+ * Provider chain: Brave (`BRAVE_API_KEY`) → Tavily (`TAVILY_API_KEY`) →
+ * DuckDuckGo HTML scrape (no key). When every provider fails, the tool
+ * returns a diagnostic message and suggests calling `web_read` with a known
+ * URL instead — this keeps the specialist-creator meta-agent productive even
+ * without API keys.
+ */
+export declare function createWebSearchTool(): import("ai").Tool<z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    limit?: number | undefined;
+}, {
+    query: string;
+    limit?: number | undefined;
+}>, string> & {
+    execute: (args: {
+        query: string;
+        limit?: number | undefined;
+    }, options: import("ai").ToolExecutionOptions) => PromiseLike<string>;
+};

package/dist/tools/web-search.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWebSearchTool = createWebSearchTool;
+const ai_1 = require("ai");
+const zod_1 = require("zod");
+const node_html_parser_1 = require("node-html-parser");
+const DEFAULT_LIMIT = 5;
+const MAX_LIMIT = 10;
+const FETCH_TIMEOUT_MS = 12_000;
+const USER_AGENT = 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
+/** Try Brave Search API. Returns `undefined` when the provider is unavailable or errors. */
+async function searchBrave(query, limit) {
+    const apiKey = process.env.BRAVE_API_KEY;
+    if (!apiKey)
+        return undefined;
+    try {
+        const url = new URL('https://api.search.brave.com/res/v1/web/search');
+        url.searchParams.set('q', query);
+        url.searchParams.set('count', String(limit));
+        const res = await fetch(url.toString(), {
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+            headers: {
+                Accept: 'application/json',
+                'X-Subscription-Token': apiKey,
+            },
+        });
+        if (!res.ok)
+            return undefined;
+        const data = (await res.json());
+        const results = data.web?.results ?? [];
+        return results.slice(0, limit).map((r) => ({
+            title: String(r.title ?? ''),
+            url: String(r.url ?? ''),
+            snippet: String(r.description ?? ''),
+        }));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Try Tavily search API. Returns `undefined` when the provider is unavailable or errors. */
+async function searchTavily(query, limit) {
+    const apiKey = process.env.TAVILY_API_KEY;
+    if (!apiKey)
+        return undefined;
+    try {
+        const res = await fetch('https://api.tavily.com/search', {
+            method: 'POST',
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                api_key: apiKey,
+                query,
+                max_results: limit,
+                search_depth: 'basic',
+            }),
+        });
+        if (!res.ok)
+            return undefined;
+        const data = (await res.json());
+        const results = data.results ?? [];
+        return results.slice(0, limit).map((r) => ({
+            title: String(r.title ?? ''),
+            url: String(r.url ?? ''),
+            snippet: String(r.content ?? r.snippet ?? ''),
+        }));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * DuckDuckGo HTML scrape. No API key required but output is fragile to layout
+ * changes. Used as a last-resort fallback so specialist-creator can still do
+ * rough research without any paid API.
+ */
+async function searchDuckDuckGo(query, limit) {
+    try {
+        const url = new URL('https://html.duckduckgo.com/html/');
+        url.searchParams.set('q', query);
+        const res = await fetch(url.toString(), {
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+            headers: { 'User-Agent': USER_AGENT, Accept: 'text/html' },
+        });
+        if (!res.ok)
+            return undefined;
+        const html = await res.text();
+        const root = (0, node_html_parser_1.parse)(html);
+        const results = [];
+        const nodes = root.querySelectorAll('.result');
+        for (const node of nodes) {
+            if (results.length >= limit)
+                break;
+            const anchor = node.querySelector('a.result__a');
+            const snippetEl = node.querySelector('.result__snippet');
+            const title = anchor?.text.trim() ?? '';
+            let href = anchor?.getAttribute('href') ?? '';
+            // DuckDuckGo wraps results in a redirect like //duckduckgo.com/l/?uddg=<encoded>
+            if (href.startsWith('//duckduckgo.com/l/') || href.includes('duckduckgo.com/l/')) {
+                try {
+                    const parsed = new URL(href.startsWith('//') ? `https:${href}` : href);
+                    const uddg = parsed.searchParams.get('uddg');
+                    if (uddg)
+                        href = decodeURIComponent(uddg);
+                }
+                catch {
+                    /* leave as-is */
+                }
+            }
+            const snippet = snippetEl?.text.trim() ?? '';
+            if (title && href)
+                results.push({ title, url: href, snippet });
+        }
+        return results;
+    }
+    catch {
+        return undefined;
+    }
+}
+function formatResults(results) {
+    if (results.length === 0)
+        return 'No results found.';
+    return results
+        .map((r, i) => `${i + 1}. ${r.title}\n   ${r.url}${r.snippet ? `\n   ${r.snippet.slice(0, 300)}` : ''}`)
+        .join('\n\n');
+}
+/**
+ * Creates the `web_search` tool.
+ *
+ * Provider chain: Brave (`BRAVE_API_KEY`) → Tavily (`TAVILY_API_KEY`) →
+ * DuckDuckGo HTML scrape (no key). When every provider fails, the tool
+ * returns a diagnostic message and suggests calling `web_read` with a known
+ * URL instead — this keeps the specialist-creator meta-agent productive even
+ * without API keys.
+ */
+function createWebSearchTool() {
+    return (0, ai_1.tool)({
+        description: 'Search the web and return a ranked list of {title, url, snippet} results. Use before web_read when you do not yet know the right URL. Provider chain: Brave → Tavily → DuckDuckGo (no API key required for the fallback).',
+        parameters: zod_1.z.object({
+            query: zod_1.z
+                .string()
+                .describe('The search query. Prefer specific phrasing over generic keywords.'),
+            limit: zod_1.z
+                .number()
+                .int()
+                .min(1)
+                .max(MAX_LIMIT)
+                .optional()
+                .describe(`Maximum results to return (default ${DEFAULT_LIMIT}, max ${MAX_LIMIT}).`),
+        }),
+        execute: async ({ query, limit }) => {
+            const cappedLimit = Math.min(Math.max(1, limit ?? DEFAULT_LIMIT), MAX_LIMIT);
+            const attempts = [
+                ['brave', () => searchBrave(query, cappedLimit)],
+                ['tavily', () => searchTavily(query, cappedLimit)],
+                ['duckduckgo', () => searchDuckDuckGo(query, cappedLimit)],
+            ];
+            const failures = [];
+            for (const [name, fn] of attempts) {
+                const results = await fn();
+                if (results && results.length > 0) {
+                    return `Provider: ${name}\n\n${formatResults(results)}`;
+                }
+                failures.push(name);
+            }
+            return (`web_search returned no results (tried: ${failures.join(', ')}). ` +
+                'If you know a likely documentation URL, call web_read directly. ' +
+                'To enable higher-quality search, set BRAVE_API_KEY or TAVILY_API_KEY.');
+        },
+    });
+}
+//# sourceMappingURL=web-search.js.map

package/dist/tools/web-search.js.map

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