@ixo/oracle-runtime 0.0.1

package/dist/plugins/editor/survey-helpers.js

@@ -0,0 +1,358 @@
+/* eslint-disable no-console */
+/**
+ * Survey Helper Functions
+ *
+ * Utilities for parsing, validating, and working with SurveyJS survey schemas
+ * and answers in domainCreator blocks.
+ */
+/**
+ * Parse a JSON string survey schema into a structured object
+ */
+export function parseSurveySchema(schemaString) {
+    try {
+        if (!schemaString || typeof schemaString !== 'string') {
+            return null;
+        }
+        const parsed = JSON.parse(schemaString);
+        return parsed;
+    }
+    catch (error) {
+        console.error('Error parsing survey schema:', error);
+        return null;
+    }
+}
+/**
+ * Parse a JSON string of answers into a structured object
+ */
+export function parseSurveyAnswers(answersString) {
+    try {
+        if (!answersString || typeof answersString !== 'string') {
+            return {};
+        }
+        const parsed = JSON.parse(answersString);
+        return parsed;
+    }
+    catch (error) {
+        console.error('Error parsing survey answers:', error);
+        return {};
+    }
+}
+/**
+ * Evaluate a visibility condition against current answers
+ * Simple evaluation for common patterns like {field} = value or {field} = true
+ */
+export function evaluateVisibilityCondition(condition, answers) {
+    if (!condition) {
+        return true;
+    }
+    try {
+        // Handle simple patterns like {field} = value or {field} = true
+        const match = condition.match(/\{([^}]+)\}\s*=\s*(.+)/);
+        if (match && match[1] !== undefined && match[2] !== undefined) {
+            const fieldName = match[1].trim();
+            const expectedValue = match[2].trim();
+            const actualValue = answers[fieldName];
+            // Handle boolean strings
+            if (expectedValue === 'true') {
+                return actualValue === true || actualValue === 'true';
+            }
+            if (expectedValue === 'false') {
+                return actualValue === false || actualValue === 'false';
+            }
+            // Handle quoted strings
+            if ((expectedValue.startsWith('"') && expectedValue.endsWith('"')) ||
+                (expectedValue.startsWith("'") && expectedValue.endsWith("'"))) {
+                const unquoted = expectedValue.slice(1, -1);
+                return String(actualValue) === unquoted;
+            }
+            // Direct comparison
+            return String(actualValue) === expectedValue;
+        }
+        // Default to visible if we can't parse
+        return true;
+    }
+    catch (error) {
+        console.error('Error evaluating visibility condition:', error);
+        return true;
+    }
+}
+/**
+ * Fetch choices from a URL
+ */
+async function fetchChoicesFromUrl(choicesByUrl) {
+    try {
+        const response = await fetch(choicesByUrl.url, {
+            method: 'GET',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+        });
+        if (!response.ok) {
+            console.warn(`Failed to fetch choices from ${choicesByUrl.url}: ${response.statusText}`);
+            return null;
+        }
+        const data = await response.json();
+        // Handle array response
+        if (Array.isArray(data)) {
+            return data.map((item) => ({
+                value: String(item[choicesByUrl.valueName] ?? item.value ?? ''),
+                text: String(item[choicesByUrl.titleName] ?? item.text ?? item.title ?? ''),
+            }));
+        }
+        // Handle object response
+        if (typeof data === 'object' && data !== null) {
+            // If the response has a data property that's an array
+            if (Array.isArray(data.data)) {
+                return data.data.map((item) => ({
+                    value: String(item[choicesByUrl.valueName] ?? item.value ?? ''),
+                    text: String(item[choicesByUrl.titleName] ?? item.text ?? item.title ?? ''),
+                }));
+            }
+            // If the response itself is an object with valueName and titleName properties
+            if (data[choicesByUrl.valueName] !== undefined) {
+                return [
+                    {
+                        value: String(data[choicesByUrl.valueName]),
+                        text: String(data[choicesByUrl.titleName] ?? data[choicesByUrl.valueName]),
+                    },
+                ];
+            }
+        }
+        console.warn(`Unexpected response format from ${choicesByUrl.url}`);
+        return null;
+    }
+    catch (error) {
+        console.error(`Error fetching choices from ${choicesByUrl.url}:`, error);
+        return null;
+    }
+}
+/**
+ * Extract all questions from a survey schema with metadata
+ * Fetches choices from choicesByUrl if present
+ * If answers are provided, computes visibility inline
+ */
+export async function extractSurveyQuestions(schema, answers) {
+    const questions = [];
+    if (!schema.pages || !Array.isArray(schema.pages)) {
+        return questions;
+    }
+    async function extractFromElements(elements, pageName, pageTitle) {
+        for (const element of elements) {
+            // Skip elements without a name (they're not answerable)
+            if (!element.name) {
+                continue;
+            }
+            let choices = element.choices;
+            // Fetch choices from URL if choicesByUrl is present
+            if (element.choicesByUrl && !choices) {
+                const fetchedChoices = await fetchChoicesFromUrl(element.choicesByUrl);
+                if (fetchedChoices) {
+                    choices = fetchedChoices;
+                }
+            }
+            const question = {
+                name: element.name,
+                title: element.title || element.name,
+                description: element.description,
+                type: element.type,
+                inputType: element.inputType,
+                isRequired: element.isRequired === true,
+                isVisible: answers
+                    ? evaluateVisibilityCondition(element.visibleIf, answers)
+                    : true, // Default to visible if no answers provided
+                visibleIf: element.visibleIf,
+                defaultValue: element.defaultValue,
+                choices,
+                choicesByUrl: element.choicesByUrl,
+                pageName,
+                pageTitle,
+            };
+            questions.push(question);
+            // Handle nested elements (panels, paneldynamic)
+            if (element.elements && Array.isArray(element.elements)) {
+                await extractFromElements(element.elements, pageName, pageTitle);
+            }
+            // Handle template elements (paneldynamic)
+            if (element.templateElements && Array.isArray(element.templateElements)) {
+                await extractFromElements(element.templateElements, pageName, pageTitle);
+            }
+        }
+    }
+    for (const page of schema.pages) {
+        if (page.elements && Array.isArray(page.elements)) {
+            await extractFromElements(page.elements, page.name, page.title || page.name);
+        }
+    }
+    return questions;
+}
+/**
+ * Get all visible questions based on current answers
+ */
+export async function getVisibleQuestions(answers, schema) {
+    const allQuestions = await extractSurveyQuestions(schema, answers);
+    return allQuestions.filter((q) => q.isVisible !== false);
+}
+/**
+ * Get missing required fields from answers
+ */
+export async function getMissingRequiredFields(answers, schema) {
+    const visibleQuestions = await getVisibleQuestions(answers, schema);
+    const missing = [];
+    for (const question of visibleQuestions) {
+        if (question.isRequired) {
+            const value = answers[question.name];
+            if (value === undefined ||
+                value === null ||
+                value === '' ||
+                (Array.isArray(value) && value.length === 0)) {
+                missing.push(question.name);
+            }
+        }
+    }
+    return missing;
+}
+/**
+ * Validate a single answer value against a question
+ * Returns errors for visible questions, warnings for hidden questions
+ */
+function validateAnswerValue(question, value, options = {
+    checkRequired: true,
+    returnAsWarnings: false,
+}) {
+    const issues = [];
+    // Check required (only if checkRequired is true)
+    if (options.checkRequired && question.isRequired) {
+        if (value === undefined ||
+            value === null ||
+            value === '' ||
+            (Array.isArray(value) && value.length === 0)) {
+            if (options.returnAsWarnings) {
+                issues.push({
+                    field: question.name,
+                    message: `${question.title || question.name} is required`,
+                });
+            }
+            else {
+                issues.push({
+                    field: question.name,
+                    message: `${question.title || question.name} is required`,
+                    type: 'required',
+                });
+            }
+            return issues; // Don't check other validations if required is missing
+        }
+    }
+    // Check type and format
+    if (value !== undefined && value !== null && value !== '') {
+        const addIssue = (message, type) => {
+            if (options.returnAsWarnings) {
+                issues.push({ field: question.name, message });
+            }
+            else {
+                issues.push({
+                    field: question.name,
+                    message,
+                    type: type || 'type',
+                });
+            }
+        };
+        switch (question.type) {
+            case 'boolean':
+                if (typeof value !== 'boolean' &&
+                    value !== 'true' &&
+                    value !== 'false') {
+                    addIssue(`${question.title || question.name} must be a boolean`, 'type');
+                }
+                break;
+            case 'text':
+                if (typeof value !== 'string') {
+                    addIssue(`${question.title || question.name} must be a string`, 'type');
+                }
+                break;
+            case 'dropdown':
+                if (typeof value !== 'string') {
+                    addIssue(`${question.title || question.name} must be a string`, 'type');
+                }
+                // Check choices if available
+                if (question.choices && Array.isArray(question.choices)) {
+                    const validValues = question.choices.map((c) => c.value);
+                    if (!validValues.includes(String(value))) {
+                        addIssue(`${question.title || question.name} must be one of: ${validValues.join(', ')}`, 'choice');
+                    }
+                }
+                break;
+            case 'paneldynamic':
+                if (!Array.isArray(value)) {
+                    addIssue(`${question.title || question.name} must be an array`, 'type');
+                }
+                break;
+        }
+        // Check input type formats
+        if (question.inputType === 'email' && typeof value === 'string') {
+            const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+            if (!emailRegex.test(value)) {
+                addIssue(`${question.title || question.name} must be a valid email address`, 'format');
+            }
+        }
+        if (question.inputType === 'url' && typeof value === 'string') {
+            try {
+                new URL(value);
+            }
+            catch {
+                addIssue(`${question.title || question.name} must be a valid URL`, 'format');
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * Validate answers against schema requirements
+ */
+export async function validateAnswersAgainstSchema(answers, schema) {
+    const errors = [];
+    const warnings = [];
+    const visibleQuestions = await getVisibleQuestions(answers, schema);
+    const allQuestions = await extractSurveyQuestions(schema, answers);
+    // Validate visible questions - return errors
+    for (const question of visibleQuestions) {
+        const value = answers[question.name];
+        const questionErrors = validateAnswerValue(question, value, {
+            checkRequired: true,
+            returnAsWarnings: false,
+        });
+        errors.push(...questionErrors);
+    }
+    // Validate hidden questions that have answers - return warnings (skip required check)
+    const visibleQuestionNames = new Set(visibleQuestions.map((q) => q.name));
+    for (const question of allQuestions) {
+        if (!visibleQuestionNames.has(question.name)) {
+            // This is a hidden question
+            const value = answers[question.name];
+            if (value !== undefined && value !== null && value !== '') {
+                // Only validate if agent provided a value for hidden field
+                const questionWarnings = validateAnswerValue(question, value, {
+                    checkRequired: false,
+                    returnAsWarnings: true,
+                });
+                warnings.push(...questionWarnings);
+            }
+        }
+    }
+    // Check for answers that don't correspond to ANY question (visible or hidden)
+    const allQuestionNames = new Set(allQuestions.map((q) => q.name));
+    for (const answerKey of Object.keys(answers)) {
+        if (!allQuestionNames.has(answerKey)) {
+            warnings.push({
+                field: answerKey,
+                message: `Answer for "${answerKey}" does not correspond to any question in the schema`,
+            });
+        }
+    }
+    const result = {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+    console.log('validateAnswersAgainstSchema result:', result);
+    return result;
+}

package/dist/plugins/firecrawl/firecrawl-agent.d.ts

@@ -0,0 +1,7 @@
+import type { PluginSubAgent, PluginTool } from '../../plugin-api/types.js';
+/**
+ * Build the Firecrawl sub-agent definition. Tools are supplied by the
+ * plugin and close over a `MultiServerMCPClient` keyed to `FIRECRAWL_MCP_URL`.
+ */
+export declare function createFirecrawlSubAgent(tools: PluginTool[]): PluginSubAgent;
+//# sourceMappingURL=firecrawl-agent.d.ts.map

package/dist/plugins/firecrawl/firecrawl-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"firecrawl-agent.d.ts","sourceRoot":"","sources":["../../../src/plugins/firecrawl/firecrawl-agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AA+E5E;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,cAAc,CAS3E"}

package/dist/plugins/firecrawl/firecrawl-agent.js

@@ -0,0 +1,84 @@
+const SHARED_EXPECTATIONS = `
+You are the Firecrawl Agent for this workspace. Your entire job is to perform
+web search and scraping tasks through the Firecrawl MCP tools on behalf of the
+user.
+
+🚨 **API REJECTION RULE**: You are ONLY for scraping human-readable web pages and web search. If the task asks you to fetch data from an API endpoint (any URL containing /api/, /v1/, /v2/, /v3/, returning JSON/XML data, or any REST/GraphQL endpoint), you MUST refuse and reply: "This is an API call — use the Sandbox instead (write a script with fetch/curl/requests). I only handle web pages and web search." Do NOT attempt to scrape API endpoints.
+
+Core expectations:
+- Treat published web content as potentially unreliable—cross-check when you can.
+- Never make HTTP requests directly; always operate through the exposed Firecrawl
+  tools and respect their rate limits.
+- Narrate what you're about to fetch or search, then summarize the findings with
+  citations (URLs) when possible.
+- Call out stale, conflicting, or missing information before acting on it.
+
+Efficiency rules (CRITICAL — you run under a strict time budget):
+- **Search once, search smart.** Write a single, well-crafted search query that
+  targets exactly what you need. Do NOT issue multiple redundant searches hoping
+  for better results.
+- **One source is enough when the data is clear.** For factual lookups (prices,
+  weather, scores, exchange rates), use ONE authoritative result. Do not scrape
+  multiple sites to cross-verify commodity prices or similar public data.
+- **Prefer search over scrape.** \`firecrawl_search\` returns snippets directly —
+  use it first. Only fall back to \`firecrawl_scrape\` when you need full-page
+  content that search snippets can't provide (e.g., full articles, tables).
+- **Never crawl entire sites.** If a search gives you the answer, stop. Do not
+  follow links to "learn more" or scrape additional pages for context.
+- **Fail fast.** If a search returns no useful results on the first try, report
+  what you found (or didn't) and stop. Do NOT rephrase and retry endlessly.
+- **Total tool calls budget: max 3.** You should almost always finish in 1-2 tool
+  calls. If you've made 3 calls, wrap up with whatever you have.
+
+Task discipline:
+- You are a sub-agent invoked by the main agent. You receive a single task message — that is ALL the context you have.
+- If the task is unclear, ambiguous, or missing critical details (IDs, names, scope, what to do), do NOT guess. Instead, STOP immediately and return a clear message explaining what information you need. The main agent will ask the user and re-invoke you with a complete task.
+- Never loop or retry the same failing approach. If something fails twice, return the error and stop.
+- Complete the requested task and STOP. Do not do additional unrequested work.
+`.trim();
+const WORKFLOW_GUIDELINES = `
+### Workflow
+1. Identify the single most important piece of information the task needs.
+2. Write ONE precise search query (e.g., "gold spot price USD today" — not
+   "gold price" then "gold market" then "gold value per ounce").
+3. If the search result contains the answer, extract it and STOP.
+4. Only scrape a URL if the search snippet was incomplete and you need the full page.
+5. Return findings with citations. If data is unavailable, say so — don't keep searching.
+`.trim();
+const formatToolDocs = (tools) => {
+    if (!tools.length) {
+        return '- No Firecrawl tools are currently configured.';
+    }
+    return tools
+        .map((t) => {
+        const description = t.description?.trim() ?? 'No description provided.';
+        return `Firecrawl Agent: \`${t.name}\`: ${description}`;
+    })
+        .join('\n');
+};
+const buildFirecrawlPrompt = (tools) => `
+${SHARED_EXPECTATIONS}
+
+### Available Firecrawl Tools
+${formatToolDocs(tools)}
+
+${WORKFLOW_GUIDELINES}
+`.trim();
+const buildFirecrawlDescription = (tools) => {
+    const names = tools.map((t) => t.name).join(', ') || 'no tools configured';
+    return `Firecrawl Agent for web search & scraping human-readable web pages via (${names}). NOT for API calls — use the Sandbox for APIs (fetch/curl/requests).`;
+};
+/**
+ * Build the Firecrawl sub-agent definition. Tools are supplied by the
+ * plugin and close over a `MultiServerMCPClient` keyed to `FIRECRAWL_MCP_URL`.
+ */
+export function createFirecrawlSubAgent(tools) {
+    return {
+        name: 'Firecrawl Agent',
+        description: buildFirecrawlDescription(tools),
+        systemPrompt: buildFirecrawlPrompt(tools),
+        tools,
+        model: 'subagent',
+        middlewares: [],
+    };
+}

package/dist/plugins/firecrawl/firecrawl-tools.d.ts

@@ -0,0 +1,37 @@
+import type { PluginTool } from '../../plugin-api/types.js';
+/**
+ * Minimal surface a Firecrawl MCP tool needs to expose to be proxied: an
+ * identifier and an `invoke` method. `MultiServerMCPClient.getTools()`
+ * returns `DynamicStructuredTool[]` which trivially satisfies this shape,
+ * and unit tests can satisfy it with a plain object — no SDK ceremony.
+ */
+export interface FirecrawlMcpProxyTool {
+    name: string;
+    invoke: (input: unknown) => Promise<unknown>;
+}
+/**
+ * Tool names that the upstream Firecrawl MCP server exposes (prefixed with
+ * the server name configured in {@link MultiServerMCPClient}). Filtering by
+ * these names keeps the agent's surface area tight even if the server adds
+ * extra capabilities later.
+ */
+export declare const FIRECRAWL_SCRAPE_MCP_NAME = "firecrawl__firecrawl_scrape";
+export declare const FIRECRAWL_SEARCH_MCP_NAME = "firecrawl__firecrawl_search";
+/** Public tool names shown to the agent (server prefix dropped). */
+export declare const FIRECRAWL_SCRAPE_TOOL = "firecrawl_scrape";
+export declare const FIRECRAWL_SEARCH_TOOL = "firecrawl_search";
+/**
+ * Factory for the underlying MCP-tool list. Injectable so unit tests can
+ * substitute a stub without spinning up the real MCP transport.
+ */
+export type FirecrawlMcpFactory = () => Promise<FirecrawlMcpProxyTool[]>;
+/** Build the default factory keyed to `FIRECRAWL_MCP_URL`. */
+export declare function createDefaultFirecrawlMcpFactory(firecrawlUrl: string): FirecrawlMcpFactory;
+/**
+ * Construct the two Firecrawl plugin tools. Each tool's handler proxies
+ * the validated input into the upstream MCP server using the supplied
+ * factory. Schemas are declared statically so the agent sees a stable
+ * tool surface even before the first MCP fetch.
+ */
+export declare function createFirecrawlTools(factory: FirecrawlMcpFactory): PluginTool[];
+//# sourceMappingURL=firecrawl-tools.d.ts.map

package/dist/plugins/firecrawl/firecrawl-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"firecrawl-tools.d.ts","sourceRoot":"","sources":["../../../src/plugins/firecrawl/firecrawl-tools.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9C;AAED;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,gCAAgC,CAAC;AACvE,eAAO,MAAM,yBAAyB,gCAAgC,CAAC;AAEvE,oEAAoE;AACpE,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AACxD,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AA+CxD;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAAC;AAEzE,8DAA8D;AAC9D,wBAAgB,gCAAgC,CAC9C,YAAY,EAAE,MAAM,GACnB,mBAAmB,CA8BrB;AA6BD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,mBAAmB,GAC3B,UAAU,EAAE,CAoCd"}

package/dist/plugins/firecrawl/firecrawl-tools.js

@@ -0,0 +1,129 @@
+import { MultiServerMCPClient } from '@langchain/mcp-adapters';
+import { z } from 'zod';
+import { tool } from '../../plugin-api/tool-helper.js';
+/**
+ * Tool names that the upstream Firecrawl MCP server exposes (prefixed with
+ * the server name configured in {@link MultiServerMCPClient}). Filtering by
+ * these names keeps the agent's surface area tight even if the server adds
+ * extra capabilities later.
+ */
+export const FIRECRAWL_SCRAPE_MCP_NAME = 'firecrawl__firecrawl_scrape';
+export const FIRECRAWL_SEARCH_MCP_NAME = 'firecrawl__firecrawl_search';
+/** Public tool names shown to the agent (server prefix dropped). */
+export const FIRECRAWL_SCRAPE_TOOL = 'firecrawl_scrape';
+export const FIRECRAWL_SEARCH_TOOL = 'firecrawl_search';
+const SEARCH_DESCRIPTION = `Web search via Firecrawl. Returns a ranked list of result snippets with titles and URLs.
+
+Use this BEFORE \`firecrawl_scrape\` whenever a search snippet is enough — it's faster and cheaper. Only escalate to scraping when the snippet is incomplete and you need the full page.
+
+🚨 Never use this for API endpoints (any URL with /api/, /v1/, /v2/, /v3/, or returning JSON/XML). Use the Sandbox for those.`;
+const SCRAPE_DESCRIPTION = `Scrape a single human-readable web page via Firecrawl. Returns the page as Markdown plus structured metadata.
+
+Use this only when you've already tried \`firecrawl_search\` and need the full page content (long article, table, structured data on a static page).
+
+🚨 Never use this on API endpoints (any URL with /api/, /v1/, /v2/, /v3/, or returning JSON/XML). Use the Sandbox for those.`;
+const searchSchema = z.object({
+    query: z
+        .string()
+        .min(1, 'Query is required and cannot be empty.')
+        .describe('Search query — write ONE precise, well-targeted query.'),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(10)
+        .optional()
+        .describe('Max number of results (1-10). Default upstream.'),
+});
+const scrapeSchema = z.object({
+    url: z
+        .string()
+        .url()
+        .describe('Fully-qualified URL of the page to scrape (https://...).'),
+    formats: z
+        .array(z.enum(['markdown', 'html', 'rawHtml', 'links', 'screenshot']))
+        .optional()
+        .describe("Output formats. Defaults to ['markdown']. Use 'links' to enumerate outbound URLs."),
+    onlyMainContent: z
+        .boolean()
+        .optional()
+        .describe('When true (default), strips navigation, ads, and boilerplate — returns just the main content block.'),
+});
+/** Build the default factory keyed to `FIRECRAWL_MCP_URL`. */
+export function createDefaultFirecrawlMcpFactory(firecrawlUrl) {
+    let cached = null;
+    return () => {
+        cached ??= (async () => {
+            const client = new MultiServerMCPClient({
+                useStandardContentBlocks: true,
+                defaultToolTimeout: 120_000,
+                prefixToolNameWithServerName: true,
+                mcpServers: {
+                    firecrawl: {
+                        type: 'http',
+                        transport: 'http',
+                        url: firecrawlUrl,
+                        reconnect: {
+                            enabled: true,
+                            maxAttempts: 3,
+                            delayMs: 2000,
+                        },
+                    },
+                },
+            });
+            const all = await client.getTools();
+            return all.filter((t) => t.name === FIRECRAWL_SCRAPE_MCP_NAME ||
+                t.name === FIRECRAWL_SEARCH_MCP_NAME);
+        })();
+        return cached;
+    };
+}
+/**
+ * Build a handler that proxies a validated input through the MCP client.
+ * The underlying tool is resolved lazily on the first call and cached.
+ */
+function buildProxyHandler({ factory, mcpToolName, publicToolName, }) {
+    return async (args) => {
+        const mcpTools = await factory();
+        const target = mcpTools.find((t) => t.name === mcpToolName);
+        if (!target) {
+            throw new Error(`${publicToolName}: upstream MCP tool "${mcpToolName}" is not exposed by the configured Firecrawl server.`);
+        }
+        return target.invoke(args);
+    };
+}
+/**
+ * Construct the two Firecrawl plugin tools. Each tool's handler proxies
+ * the validated input into the upstream MCP server using the supplied
+ * factory. Schemas are declared statically so the agent sees a stable
+ * tool surface even before the first MCP fetch.
+ */
+export function createFirecrawlTools(factory) {
+    const search = tool(async (rawArgs) => {
+        const parsed = searchSchema.parse(rawArgs);
+        const handler = buildProxyHandler({
+            factory,
+            mcpToolName: FIRECRAWL_SEARCH_MCP_NAME,
+            publicToolName: FIRECRAWL_SEARCH_TOOL,
+        });
+        return handler(parsed);
+    }, {
+        name: FIRECRAWL_SEARCH_TOOL,
+        description: SEARCH_DESCRIPTION,
+        schema: searchSchema,
+    });
+    const scrape = tool(async (rawArgs) => {
+        const parsed = scrapeSchema.parse(rawArgs);
+        const handler = buildProxyHandler({
+            factory,
+            mcpToolName: FIRECRAWL_SCRAPE_MCP_NAME,
+            publicToolName: FIRECRAWL_SCRAPE_TOOL,
+        });
+        return handler(parsed);
+    }, {
+        name: FIRECRAWL_SCRAPE_TOOL,
+        description: SCRAPE_DESCRIPTION,
+        schema: scrapeSchema,
+    });
+    return [search, scrape];
+}

package/dist/plugins/firecrawl/firecrawl.plugin.d.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin.js';
+import type { PluginContext, PluginManifest, PluginSubAgent } from '../../plugin-api/types.js';
+import { type FirecrawlMcpFactory } from './firecrawl-tools.js';
+/** Optional dependency injection — primarily for tests. */
+export interface FirecrawlPluginOptions {
+    /**
+     * Override the MCP-tools factory. Defaults to a Firecrawl-MCP HTTP client
+     * built from `FIRECRAWL_MCP_URL`. Tests pass a stub so the plugin never
+     * touches the network.
+     */
+    mcpFactory?: (firecrawlUrl: string) => FirecrawlMcpFactory;
+}
+/**
+ * Firecrawl plugin. Exposes a sub-agent (`call_firecrawl_agent`) that wraps
+ * the upstream Firecrawl MCP server's `firecrawl_search` and
+ * `firecrawl_scrape` tools.
+ */
+export declare class FirecrawlPlugin extends OraclePlugin {
+    readonly name = "firecrawl";
+    readonly version = "1.0.0";
+    readonly manifest: PluginManifest;
+    readonly configSchema: z.ZodObject<{
+        FIRECRAWL_MCP_URL: z.ZodString;
+    }, z.core.$strip>;
+    readonly autoDetectHint = "FIRECRAWL_MCP_URL";
+    private readonly mcpFactory;
+    constructor(options?: FirecrawlPluginOptions);
+    autoDetect(env: NodeJS.ProcessEnv): boolean;
+    getSubAgents(ctx: PluginContext): PluginSubAgent[];
+}
+//# sourceMappingURL=firecrawl.plugin.d.ts.map

package/dist/plugins/firecrawl/firecrawl.plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"firecrawl.plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/firecrawl/firecrawl.plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,KAAK,EAEV,aAAa,EACb,cAAc,EACd,cAAc,EACf,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,sBAAsB,CAAC;AA6C9B,2DAA2D;AAC3D,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,mBAAmB,CAAC;CAC5D;AAED;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,YAAY;IAC/C,QAAQ,CAAC,IAAI,eAAe;IAE5B,QAAQ,CAAC,OAAO,WAAW;IAE3B,QAAQ,CAAC,QAAQ,iBAAY;IAE7B,SAAkB,YAAY;;sBAAgB;IAE9C,SAAkB,cAAc,uBAAuB;IAEvD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgD;gBAE/D,OAAO,GAAE,sBAA2B;IAKvC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO;IAI3C,YAAY,CAAC,GAAG,EAAE,aAAa,GAAG,cAAc,EAAE;CAM5D"}