neoctl 0.1.0

package/dist/tools/builtins/search-providers.js

@@ -0,0 +1,240 @@
+export const DEFAULT_SEARCH_PROVIDER = "exa";
+export const DEFAULT_EXA_MCP_URL = "https://mcp.exa.ai/mcp";
+export const DEFAULT_EXA_MCP_TOOL_NAME = "web_search_exa";
+export const DEFAULT_SEARCH_TIMEOUT_MS = 30_000;
+export class SearchProviderError extends Error {
+    provider;
+    cause;
+    constructor(message, provider, cause) {
+        super(message);
+        this.provider = provider;
+        this.cause = cause;
+        this.name = "SearchProviderError";
+    }
+}
+export function createSearchProvider(config = {}, env = process.env) {
+    const provider = (config.provider ?? env.SEARCH_PROVIDER ?? env.WEB_SEARCH_PROVIDER ?? DEFAULT_SEARCH_PROVIDER).trim().toLowerCase();
+    switch (provider) {
+        case "exa":
+            return createExaSearchProvider({
+                mcpUrl: config.exa?.mcpUrl ?? env.EXA_MCP_URL ?? env.WEB_SEARCH_EXA_MCP_URL,
+                toolName: config.exa?.toolName ?? env.EXA_MCP_TOOL_NAME ?? env.WEB_SEARCH_EXA_TOOL_NAME,
+                timeoutMs: config.exa?.timeoutMs ?? parseOptionalInteger(env.SEARCH_TIMEOUT_MS ?? env.WEB_SEARCH_TIMEOUT_MS),
+            });
+        default:
+            throw new SearchProviderError(`Unsupported search provider: ${provider}. Add a provider implementation and register it in createSearchProvider().`, provider);
+    }
+}
+export function createExaSearchProvider(config = {}) {
+    const mcpUrl = config.mcpUrl?.trim() || DEFAULT_EXA_MCP_URL;
+    const toolName = config.toolName?.trim() || DEFAULT_EXA_MCP_TOOL_NAME;
+    const timeoutMs = config.timeoutMs ?? DEFAULT_SEARCH_TIMEOUT_MS;
+    return {
+        name: "exa",
+        async search(input, signal) {
+            const response = await callExaMcpTool(mcpUrl, toolName, input, timeoutMs, signal);
+            return {
+                provider: "exa",
+                query: input.query,
+                results: extractExaResults(response),
+                raw: response,
+            };
+        },
+    };
+}
+async function callExaMcpTool(mcpUrl, toolName, input, timeoutMs, signal) {
+    const controller = new AbortController();
+    const abort = () => controller.abort(signal?.reason);
+    const timeout = setTimeout(() => controller.abort(new Error(`Search request timed out after ${timeoutMs}ms`)), timeoutMs);
+    signal?.addEventListener("abort", abort, { once: true });
+    try {
+        const response = await fetch(mcpUrl, {
+            method: "POST",
+            headers: {
+                Accept: "application/json, text/event-stream",
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: 1,
+                method: "tools/call",
+                params: {
+                    name: toolName,
+                    arguments: buildExaArguments(input),
+                },
+            }),
+            signal: controller.signal,
+        });
+        const text = await response.text();
+        if (!response.ok) {
+            throw new SearchProviderError(`Exa MCP HTTP ${response.status}: ${text.slice(0, 1000)}`, "exa");
+        }
+        return parseJsonRpcOrSseResponse(text);
+    }
+    catch (error) {
+        if (error instanceof SearchProviderError)
+            throw error;
+        throw new SearchProviderError(error instanceof Error ? error.message : String(error), "exa", error);
+    }
+    finally {
+        clearTimeout(timeout);
+        signal?.removeEventListener("abort", abort);
+    }
+}
+function buildExaArguments(input) {
+    const args = {
+        query: input.query,
+        numResults: input.numResults,
+    };
+    if (input.includeDomains?.length)
+        args.includeDomains = input.includeDomains;
+    if (input.excludeDomains?.length)
+        args.excludeDomains = input.excludeDomains;
+    if (input.startPublishedDate)
+        args.startPublishedDate = input.startPublishedDate;
+    if (input.endPublishedDate)
+        args.endPublishedDate = input.endPublishedDate;
+    return args;
+}
+function parseJsonRpcOrSseResponse(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        throw new SearchProviderError("Exa MCP returned an empty response", "exa");
+    const dataMessages = trimmed
+        .split(/\r?\n/u)
+        .map((rawLine) => rawLine.trim())
+        .filter((line) => line.startsWith("data:"))
+        .map((line) => line.slice("data:".length).trim())
+        .filter((data) => data && data !== "[DONE]");
+    if (dataMessages.length === 0)
+        return parseJsonRpcMessage(trimmed);
+    return parseJsonRpcMessage(dataMessages[0] ?? "{}");
+}
+function parseJsonRpcMessage(jsonText) {
+    const message = JSON.parse(jsonText);
+    if (isRecord(message.error)) {
+        const errorMessage = typeof message.error.message === "string" ? message.error.message : JSON.stringify(message.error);
+        throw new SearchProviderError(`Exa MCP error: ${errorMessage}`, "exa");
+    }
+    if (isRecord(message.result))
+        return message.result;
+    return message;
+}
+function extractExaResults(response) {
+    const structured = extractStructuredExaResults(response);
+    if (structured.length > 0)
+        return structured;
+    const text = extractMcpText(response);
+    if (!text)
+        return [];
+    return parseExaTextResults(text);
+}
+function extractStructuredExaResults(response) {
+    const structuredContent = isRecord(response.structuredContent) ? response.structuredContent : undefined;
+    const candidates = [
+        response.results,
+        response.documents,
+        structuredContent?.results,
+        structuredContent?.documents,
+    ];
+    for (const candidate of candidates) {
+        if (!Array.isArray(candidate))
+            continue;
+        const results = candidate.map(mapStructuredResult).filter((result) => result !== undefined);
+        if (results.length > 0)
+            return results;
+    }
+    return [];
+}
+function mapStructuredResult(value) {
+    if (!isRecord(value))
+        return undefined;
+    const url = stringFrom(value.url) ?? stringFrom(value.id);
+    if (!url)
+        return undefined;
+    const title = stringFrom(value.title) ?? url;
+    const highlights = arrayOfStrings(value.highlights ?? value.snippets ?? value.texts);
+    return {
+        title,
+        url,
+        published: stringFrom(value.publishedDate ?? value.published ?? value.date),
+        author: stringFrom(value.author),
+        highlights: highlights.length ? highlights : undefined,
+        text: stringFrom(value.text ?? value.summary),
+        score: typeof value.score === "number" ? value.score : undefined,
+        raw: value,
+    };
+}
+function extractMcpText(response) {
+    const content = response.content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((item) => (isRecord(item) && item.type === "text" && typeof item.text === "string" ? item.text.trim() : ""))
+        .filter(Boolean)
+        .join("\n\n")
+        .trim();
+}
+function parseExaTextResults(text) {
+    return text
+        .split(/\n---\n/u)
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+        .map(parseExaTextEntry)
+        .filter((result) => result !== undefined);
+}
+function parseExaTextEntry(entry) {
+    const lines = entry.split(/\r?\n/u);
+    const title = readLabel(lines, "Title") ?? "Untitled";
+    const url = readLabel(lines, "URL");
+    if (!url)
+        return undefined;
+    const published = normalizeOptionalLabel(readLabel(lines, "Published"));
+    const author = normalizeOptionalLabel(readLabel(lines, "Author"));
+    const highlights = readHighlights(lines);
+    return {
+        title,
+        url,
+        published,
+        author,
+        highlights: highlights.length ? highlights : undefined,
+        text: highlights.join("\n"),
+    };
+}
+function readLabel(lines, label) {
+    const prefix = `${label}:`;
+    const line = lines.find((value) => value.startsWith(prefix));
+    return line?.slice(prefix.length).trim();
+}
+function normalizeOptionalLabel(value) {
+    if (!value || value === "N/A")
+        return undefined;
+    return value;
+}
+function readHighlights(lines) {
+    const start = lines.findIndex((line) => line.trim() === "Highlights:");
+    if (start < 0)
+        return [];
+    return lines
+        .slice(start + 1)
+        .map((line) => line.trim())
+        .filter((line) => line && line !== "[...]" && !line.startsWith("Title:") && !line.startsWith("URL:"));
+}
+function stringFrom(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function arrayOfStrings(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string" && item.trim().length > 0);
+}
+function parseOptionalInteger(value) {
+    if (!value?.trim())
+        return undefined;
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+//# sourceMappingURL=search-providers.js.map

package/dist/tools/builtins/search-providers.js.map

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

package/dist/tools/builtins/search-tool.d.ts

@@ -0,0 +1,18 @@
+import type { Tool } from "../tool.js";
+import { type SearchProvider, type SearchToolInput, type WebSearchResult } from "./search-providers.js";
+export interface WebSearchToolInput extends SearchToolInput {
+    provider?: string;
+}
+export interface WebSearchToolOutput {
+    query: string;
+    provider: string;
+    returnedResults: number;
+    results: WebSearchResult[];
+    truncated?: boolean;
+    error?: string;
+}
+export interface CreateSearchToolOptions {
+    provider?: SearchProvider;
+}
+export declare function createSearchTool(options?: CreateSearchToolOptions): Tool<WebSearchToolInput>;
+export declare const searchTool: Tool<WebSearchToolInput>;

package/dist/tools/builtins/search-tool.js

@@ -0,0 +1,171 @@
+import { createSearchProvider } from "./search-providers.js";
+const DEFAULT_NUM_RESULTS = 5;
+const MAX_NUM_RESULTS = 10;
+const MAX_HIGHLIGHTS_PER_RESULT = 6;
+const MAX_HIGHLIGHT_CHARS = 800;
+const MAX_TEXT_CHARS = 1600;
+export function createSearchTool(options = {}) {
+    return {
+        name: "search",
+        description: "Search the web for current information. Uses a pluggable provider backend; the default provider is Exa MCP. Use grep for local workspace text lookup.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Web search query." },
+                provider: { type: "string", description: "Optional backend provider name. Defaults to SEARCH_PROVIDER/WEB_SEARCH_PROVIDER or exa." },
+                numResults: { type: "integer", description: `Maximum number of results to return, 1-${MAX_NUM_RESULTS}. Defaults to ${DEFAULT_NUM_RESULTS}.` },
+                includeDomains: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional list of domains to include, such as openai.com.",
+                },
+                excludeDomains: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional list of domains to exclude.",
+                },
+                startPublishedDate: { type: "string", description: "Optional earliest published date filter, YYYY-MM-DD when supported by the provider." },
+                endPublishedDate: { type: "string", description: "Optional latest published date filter, YYYY-MM-DD when supported by the provider." },
+            },
+            required: ["query"],
+            additionalProperties: false,
+        },
+        metadata: {
+            readOnly: true,
+            concurrent: true,
+            visible: true,
+            maxResultSizeChars: 24000,
+            searchHint: "web search via provider backend",
+        },
+        validate(input) {
+            const record = input;
+            return {
+                query: record.query ?? "",
+                provider: record.provider,
+                numResults: record.numResults ?? DEFAULT_NUM_RESULTS,
+                includeDomains: record.includeDomains,
+                excludeDomains: record.excludeDomains,
+                startPublishedDate: record.startPublishedDate,
+                endPublishedDate: record.endPublishedDate,
+            };
+        },
+        validateInput(input) {
+            if (!input.query.trim())
+                return { ok: false, message: "search.query cannot be empty" };
+            if (input.provider !== undefined && !input.provider.trim())
+                return { ok: false, message: "search.provider cannot be empty" };
+            if (!Number.isInteger(input.numResults) || input.numResults < 1 || input.numResults > MAX_NUM_RESULTS) {
+                return { ok: false, message: `search.numResults must be between 1 and ${MAX_NUM_RESULTS}` };
+            }
+            if (input.includeDomains?.some((domain) => !domain.trim()))
+                return { ok: false, message: "search.includeDomains entries cannot be empty" };
+            if (input.excludeDomains?.some((domain) => !domain.trim()))
+                return { ok: false, message: "search.excludeDomains entries cannot be empty" };
+            if (input.startPublishedDate !== undefined && !input.startPublishedDate.trim())
+                return { ok: false, message: "search.startPublishedDate cannot be empty" };
+            if (input.endPublishedDate !== undefined && !input.endPublishedDate.trim())
+                return { ok: false, message: "search.endPublishedDate cannot be empty" };
+            return { ok: true, value: input };
+        },
+        isConcurrencySafe() {
+            return true;
+        },
+        async call(input, context, callOptions) {
+            let provider;
+            try {
+                provider = options.provider ?? createSearchProvider({ provider: input.provider }, process.env);
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    output: {
+                        query: input.query,
+                        provider: input.provider?.trim() || "unknown",
+                        returnedResults: 0,
+                        results: [],
+                        error: error instanceof Error ? error.message : String(error),
+                    },
+                };
+            }
+            callOptions.onProgress?.({ toolName: "search", message: `Searching the web with ${provider.name}` });
+            try {
+                const providerResult = await provider.search(input, context.abortSignal);
+                const output = {
+                    query: input.query,
+                    provider: providerResult.provider,
+                    returnedResults: providerResult.results.length,
+                    results: normalizeResults(providerResult.results),
+                };
+                return { ok: true, output, summary: `${output.returnedResults} web result(s)` };
+            }
+            catch (error) {
+                const providerName = provider.name;
+                return {
+                    ok: false,
+                    output: {
+                        query: input.query,
+                        provider: providerName,
+                        returnedResults: 0,
+                        results: [],
+                        error: error instanceof Error ? error.message : String(error),
+                    },
+                };
+            }
+        },
+        mapResult(result) {
+            return shrinkSearchOutputForTransport(result.output, 21_000);
+        },
+    };
+}
+export const searchTool = createSearchTool();
+function normalizeResults(results) {
+    return results.map((result) => ({
+        title: trimText(result.title, 400),
+        url: result.url,
+        published: result.published,
+        author: result.author,
+        score: result.score,
+        highlights: result.highlights
+            ?.map((highlight) => trimText(highlight, MAX_HIGHLIGHT_CHARS))
+            .filter(Boolean)
+            .slice(0, MAX_HIGHLIGHTS_PER_RESULT),
+        text: result.text ? trimText(result.text, MAX_TEXT_CHARS) : undefined,
+    }));
+}
+function shrinkSearchOutputForTransport(output, maxChars) {
+    if (!isSearchOutput(output))
+        return output;
+    const serialized = JSON.stringify(output);
+    if (serialized.length <= maxChars)
+        return output;
+    const shrunk = {
+        ...output,
+        truncated: true,
+        results: output.results.map((result) => ({
+            title: trimText(result.title, 240),
+            url: result.url,
+            published: result.published,
+            author: result.author,
+            highlights: result.highlights?.slice(0, 3).map((highlight) => trimText(highlight, 300)),
+            text: result.text ? trimText(result.text, 600) : undefined,
+            score: result.score,
+        })),
+    };
+    return JSON.stringify(shrunk).length <= maxChars
+        ? shrunk
+        : {
+            ...shrunk,
+            results: shrunk.results.slice(0, Math.max(1, Math.floor(shrunk.results.length / 2))),
+        };
+}
+function isSearchOutput(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    return typeof record.query === "string" && typeof record.provider === "string" && Array.isArray(record.results);
+}
+function trimText(value, maxChars) {
+    const trimmed = value.trim();
+    return trimmed.length <= maxChars ? trimmed : `${trimmed.slice(0, maxChars)}…`;
+}
+//# sourceMappingURL=search-tool.js.map

package/dist/tools/builtins/search-tool.js.map

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

package/dist/tools/registry.d.ts

@@ -0,0 +1,18 @@
+import type { Tool, ToolDefinition, ToolUseContext } from "./tool.js";
+export interface ToolPoolOptions {
+    mode?: "default" | "simple" | "repl";
+    denyTools?: readonly string[];
+    includeDeferred?: boolean;
+}
+export declare class ToolRegistry {
+    private readonly tools;
+    private readonly aliases;
+    register(tool: Tool<any>): void;
+    get(name: string): Tool<any> | undefined;
+    getByAlias(name: string): Tool<any> | undefined;
+    definitions(context?: ToolUseContext, options?: ToolPoolOptions): ToolDefinition[];
+    names(): string[];
+    list(context?: ToolUseContext, options?: ToolPoolOptions): Tool<any>[];
+    private visibleTools;
+}
+export declare function assembleToolPool(builtInTools: readonly Tool<any>[], externalTools?: readonly Tool<any>[], options?: ToolPoolOptions): ToolRegistry;

package/dist/tools/registry.js

@@ -0,0 +1,69 @@
+import { resolveToolDescription } from "./tool.js";
+export class ToolRegistry {
+    tools = new Map();
+    aliases = new Map();
+    register(tool) {
+        if (this.tools.has(tool.name)) {
+            throw new Error(`Tool already registered: ${tool.name}`);
+        }
+        this.tools.set(tool.name, tool);
+        for (const alias of tool.aliases ?? []) {
+            if (!this.aliases.has(alias))
+                this.aliases.set(alias, tool.name);
+        }
+    }
+    get(name) {
+        return this.tools.get(name) ?? this.getByAlias(name);
+    }
+    getByAlias(name) {
+        const canonical = this.aliases.get(name);
+        return canonical ? this.tools.get(canonical) : undefined;
+    }
+    definitions(context, options = {}) {
+        return this.visibleTools(context, options).map((tool) => ({
+            name: tool.name,
+            description: resolveToolDescription(tool, context),
+            inputSchema: tool.inputSchema,
+            strict: false,
+        }));
+    }
+    names() {
+        return [...this.tools.keys()].sort();
+    }
+    list(context, options = {}) {
+        return this.visibleTools(context, options);
+    }
+    visibleTools(context, options) {
+        const deny = new Set(options.denyTools ?? []);
+        return [...this.tools.values()]
+            .filter((tool) => tool.metadata.visible)
+            .filter((tool) => !deny.has(tool.name))
+            .filter((tool) => options.includeDeferred || !tool.metadata.shouldDefer || tool.metadata.alwaysLoad)
+            .filter((tool) => tool.isEnabled?.(context) ?? true)
+            .sort(compareToolForPromptCache);
+    }
+}
+export function assembleToolPool(builtInTools, externalTools = [], options = {}) {
+    const registry = new ToolRegistry();
+    const deny = new Set(options.denyTools ?? []);
+    const ordered = [
+        ...builtInTools.filter((tool) => !deny.has(tool.name)).sort(compareToolForPromptCache),
+        ...externalTools.filter((tool) => !deny.has(tool.name)).sort(compareToolForPromptCache),
+    ];
+    const seen = new Set();
+    for (const tool of ordered) {
+        if (seen.has(tool.name))
+            continue;
+        seen.add(tool.name);
+        registry.register(tool);
+    }
+    return registry;
+}
+function compareToolForPromptCache(left, right) {
+    const leftMcp = left.metadata.isMcp ? 1 : 0;
+    const rightMcp = right.metadata.isMcp ? 1 : 0;
+    if (leftMcp !== rightMcp)
+        return leftMcp - rightMcp;
+    return left.name.localeCompare(right.name);
+}
+//# sourceMappingURL=registry.js.map

package/dist/tools/registry.js.map

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

package/dist/tools/run-tool-use.d.ts

@@ -0,0 +1,13 @@
+import { type Message, type ToolUseRequest } from "../types/messages.js";
+import type { CanUseTool, ToolProgressEvent, ToolUseContext } from "./tool.js";
+export interface ToolMessageUpdate {
+    message: Message;
+    context?: ToolUseContext;
+    progress?: ToolProgressEvent;
+}
+export interface RunToolUseOptions {
+    canUseTool?: CanUseTool;
+    parentMessage?: Message;
+}
+export declare function runToolUse(request: ToolUseRequest, context: ToolUseContext, options?: RunToolUseOptions): Promise<ToolMessageUpdate[]>;
+export declare function runToolUseToMessages(request: ToolUseRequest, context: ToolUseContext, options?: RunToolUseOptions): Promise<Message[]>;