@dexto/tools-builtins 1.6.0

package/dist/implementations/http-request-tool.js

@@ -0,0 +1,303 @@
+import { z } from "zod";
+import { DextoRuntimeError, ErrorScope, ErrorType, defineTool } from "@dexto/core";
+import { promises as dns } from "node:dns";
+import { isIP } from "node:net";
+import { TextDecoder } from "node:util";
+import { Agent } from "undici";
+const HttpRequestInputSchema = z.object({
+  url: z.string().url().describe("Absolute URL to request"),
+  method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).default("GET").describe("HTTP method to use"),
+  headers: z.record(z.string()).optional().describe("Optional request headers (string values only)"),
+  query: z.record(z.string()).optional().describe("Optional query parameters to append to the URL"),
+  body: z.union([z.string(), z.record(z.unknown()), z.array(z.unknown())]).optional().describe("Optional request body (string or JSON-serializable value)"),
+  timeoutMs: z.number().int().positive().optional().default(3e4).describe("Request timeout in milliseconds (default: 30000)")
+}).strict();
+function isJsonContentType(contentType) {
+  return Boolean(contentType && contentType.toLowerCase().includes("application/json"));
+}
+function safeJsonParse(text) {
+  if (!text.trim()) {
+    return void 0;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+const BLOCKED_HOSTNAMES = /* @__PURE__ */ new Set(["localhost"]);
+const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
+const SAFE_DISPATCHER = createSafeDispatcher();
+function isPrivateIpv4(ip) {
+  const parts = ip.split(".").map((part) => Number(part));
+  if (parts.length !== 4 || parts.some((part) => Number.isNaN(part))) {
+    return false;
+  }
+  const a = parts[0];
+  const b = parts[1];
+  const c = parts[2];
+  const d = parts[3];
+  if (a === void 0 || b === void 0 || c === void 0 || d === void 0) {
+    return false;
+  }
+  if (a === 0) return true;
+  if (a === 10) return true;
+  if (a === 127) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true;
+  if (a === 192 && b === 0 && c === 0) return true;
+  if (a === 192 && b === 0 && c === 2) return true;
+  if (a === 198 && b === 51 && c === 100) return true;
+  if (a === 203 && b === 0 && c === 113) return true;
+  if (a === 198 && (b === 18 || b === 19)) return true;
+  if (a >= 224 && a <= 239) return true;
+  if (a >= 240) return true;
+  return false;
+}
+function isPrivateIpv6(ip) {
+  const normalized = ip.toLowerCase();
+  if (normalized === "::" || normalized === "::1") return true;
+  if (normalized.startsWith("fe80:")) return true;
+  if (normalized.startsWith("fc") || normalized.startsWith("fd")) return true;
+  if (normalized.startsWith("::ffff:")) {
+    const ipv4Part = normalized.slice("::ffff:".length);
+    return isPrivateIpv4(ipv4Part);
+  }
+  return false;
+}
+function isPrivateAddress(ip) {
+  const version = isIP(ip);
+  if (version === 4) return isPrivateIpv4(ip);
+  if (version === 6) return isPrivateIpv6(ip);
+  return false;
+}
+function createSafeDispatcher() {
+  const lookup = (hostname, _options, callback) => {
+    void (async () => {
+      try {
+        if (BLOCKED_HOSTNAMES.has(hostname) || hostname.endsWith(".localhost")) {
+          callback(
+            new DextoRuntimeError(
+              "HTTP_REQUEST_UNSAFE_TARGET",
+              ErrorScope.TOOLS,
+              ErrorType.FORBIDDEN,
+              `Blocked request to local hostname: ${hostname}`
+            ),
+            "",
+            0
+          );
+          return;
+        }
+        const records = await dns.lookup(hostname, {
+          all: true,
+          verbatim: true
+        });
+        if (!records.length) {
+          callback(
+            new DextoRuntimeError(
+              "HTTP_REQUEST_DNS_FAILED",
+              ErrorScope.TOOLS,
+              ErrorType.THIRD_PARTY,
+              `Failed to resolve hostname: ${hostname}`
+            ),
+            "",
+            0
+          );
+          return;
+        }
+        for (const record of records) {
+          if (isPrivateAddress(record.address)) {
+            callback(
+              new DextoRuntimeError(
+                "HTTP_REQUEST_UNSAFE_TARGET",
+                ErrorScope.TOOLS,
+                ErrorType.FORBIDDEN,
+                `Blocked request to private address: ${record.address}`
+              ),
+              "",
+              0
+            );
+            return;
+          }
+        }
+        const selected = records[0];
+        callback(
+          null,
+          selected.address,
+          selected.family ?? (isIP(selected.address) === 6 ? 6 : 4)
+        );
+      } catch (error) {
+        const err = error instanceof DextoRuntimeError ? error : new DextoRuntimeError(
+          "HTTP_REQUEST_DNS_FAILED",
+          ErrorScope.TOOLS,
+          ErrorType.THIRD_PARTY,
+          `Failed to resolve hostname: ${hostname}`
+        );
+        callback(err, "", 0);
+      }
+    })();
+  };
+  return new Agent({ connect: { lookup } });
+}
+async function assertSafeUrl(requestUrl) {
+  if (!["http:", "https:"].includes(requestUrl.protocol)) {
+    throw new DextoRuntimeError(
+      "HTTP_REQUEST_UNSUPPORTED_PROTOCOL",
+      ErrorScope.TOOLS,
+      ErrorType.USER,
+      `Unsupported URL protocol: ${requestUrl.protocol}`
+    );
+  }
+  const hostname = requestUrl.hostname.trim();
+  if (!hostname) {
+    throw new DextoRuntimeError(
+      "HTTP_REQUEST_INVALID_TARGET",
+      ErrorScope.TOOLS,
+      ErrorType.USER,
+      "Request URL hostname is required"
+    );
+  }
+  if (BLOCKED_HOSTNAMES.has(hostname) || hostname.endsWith(".localhost")) {
+    throw new DextoRuntimeError(
+      "HTTP_REQUEST_UNSAFE_TARGET",
+      ErrorScope.TOOLS,
+      ErrorType.FORBIDDEN,
+      `Blocked request to local hostname: ${hostname}`
+    );
+  }
+  if (isPrivateAddress(hostname)) {
+    throw new DextoRuntimeError(
+      "HTTP_REQUEST_UNSAFE_TARGET",
+      ErrorScope.TOOLS,
+      ErrorType.FORBIDDEN,
+      `Blocked request to private address: ${hostname}`
+    );
+  }
+}
+async function readResponseTextWithLimit(response) {
+  const contentLength = response.headers.get("content-length");
+  if (contentLength) {
+    const parsed = Number.parseInt(contentLength, 10);
+    if (!Number.isNaN(parsed) && parsed > MAX_RESPONSE_BYTES) {
+      throw new DextoRuntimeError(
+        "HTTP_REQUEST_RESPONSE_TOO_LARGE",
+        ErrorScope.TOOLS,
+        ErrorType.THIRD_PARTY,
+        `Response too large: ${parsed} bytes exceeds ${MAX_RESPONSE_BYTES} byte limit`
+      );
+    }
+  }
+  if (!response.body) {
+    return "";
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let total = 0;
+  let result = "";
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (!value) continue;
+    total += value.length;
+    if (total > MAX_RESPONSE_BYTES) {
+      await reader.cancel();
+      throw new DextoRuntimeError(
+        "HTTP_REQUEST_RESPONSE_TOO_LARGE",
+        ErrorScope.TOOLS,
+        ErrorType.THIRD_PARTY,
+        `Response too large: exceeded ${MAX_RESPONSE_BYTES} byte limit`
+      );
+    }
+    result += decoder.decode(value, { stream: true });
+  }
+  result += decoder.decode();
+  return result;
+}
+function createHttpRequestTool() {
+  return defineTool({
+    id: "http_request",
+    displayName: "Fetch",
+    description: "Make a direct HTTP request using fetch. Supports method, headers, query params, JSON bodies, and timeouts. Returns status, headers, raw body text, and parsed JSON when available.",
+    inputSchema: HttpRequestInputSchema,
+    async execute(input, _context) {
+      const { url, method, headers, query, body, timeoutMs } = input;
+      const requestUrl = new URL(url);
+      if (query) {
+        for (const [key, value] of Object.entries(query)) {
+          requestUrl.searchParams.set(key, value);
+        }
+      }
+      await assertSafeUrl(requestUrl);
+      const requestHeaders = headers ? { ...headers } : {};
+      let requestBody;
+      if (body !== void 0) {
+        if (typeof body === "string") {
+          requestBody = body;
+        } else {
+          requestBody = JSON.stringify(body);
+          const hasContentType = Object.keys(requestHeaders).some(
+            (key) => key.toLowerCase() === "content-type"
+          );
+          if (!hasContentType) {
+            requestHeaders["Content-Type"] = "application/json";
+          }
+        }
+      }
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const requestInit = {
+          method,
+          headers: requestHeaders,
+          signal: controller.signal
+        };
+        requestInit.dispatcher = SAFE_DISPATCHER;
+        if (requestBody !== void 0) {
+          requestInit.body = requestBody;
+        }
+        const response = await fetch(requestUrl.toString(), requestInit);
+        const responseText = await readResponseTextWithLimit(response);
+        const contentType = response.headers.get("content-type");
+        const json = isJsonContentType(contentType) ? safeJsonParse(responseText) : void 0;
+        const responseHeaders = {};
+        response.headers.forEach((value, key) => {
+          responseHeaders[key] = value;
+        });
+        const payload = {
+          ok: response.ok,
+          status: response.status,
+          statusText: response.statusText,
+          headers: responseHeaders,
+          body: responseText,
+          ...json !== void 0 ? { json } : {}
+        };
+        return payload;
+      } catch (error) {
+        if (error instanceof DextoRuntimeError) {
+          throw error;
+        }
+        if (error instanceof Error && error.name === "AbortError") {
+          throw new DextoRuntimeError(
+            "HTTP_REQUEST_TIMEOUT",
+            ErrorScope.TOOLS,
+            ErrorType.TIMEOUT,
+            `HTTP request timed out after ${timeoutMs}ms`
+          );
+        }
+        throw new DextoRuntimeError(
+          "HTTP_REQUEST_FAILED",
+          ErrorScope.TOOLS,
+          ErrorType.THIRD_PARTY,
+          `HTTP request failed: ${error instanceof Error ? error.message : String(error)}`
+        );
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    }
+  });
+}
+export {
+  createHttpRequestTool
+};

package/dist/implementations/invoke-skill-tool.cjs

@@ -0,0 +1,134 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var invoke_skill_tool_exports = {};
+__export(invoke_skill_tool_exports, {
+  createInvokeSkillTool: () => createInvokeSkillTool
+});
+module.exports = __toCommonJS(invoke_skill_tool_exports);
+var import_zod = require("zod");
+var import_core = require("@dexto/core");
+const InvokeSkillInputSchema = import_zod.z.object({
+  skill: import_zod.z.string().min(1, "Skill name is required").describe(
+    'The name of the skill to invoke (e.g., "plugin-name:skill-name" or "skill-name")'
+  ),
+  args: import_zod.z.record(import_zod.z.string()).optional().describe("Optional arguments to pass to the skill"),
+  taskContext: import_zod.z.string().optional().describe(
+    "Context about what task this skill should accomplish. Recommended for forked skills to provide context since they run in isolation without conversation history."
+  )
+}).strict();
+function createInvokeSkillTool() {
+  return (0, import_core.defineTool)({
+    id: "invoke_skill",
+    displayName: "Skill",
+    description: buildToolDescription(),
+    inputSchema: InvokeSkillInputSchema,
+    async execute(input, context) {
+      const { skill, args, taskContext } = input;
+      const promptManager = context.services?.prompts;
+      if (!promptManager) {
+        throw import_core.ToolError.configInvalid(
+          "invoke_skill requires ToolExecutionContext.services.prompts"
+        );
+      }
+      const autoInvocable = await promptManager.listAutoInvocablePrompts();
+      let skillKey;
+      for (const key of Object.keys(autoInvocable)) {
+        const info = autoInvocable[key];
+        if (!info) continue;
+        if (key === skill || info.displayName === skill || info.commandName === skill || info.name === skill) {
+          skillKey = key;
+          break;
+        }
+      }
+      if (!skillKey) {
+        return {
+          error: `Skill '${skill}' not found or not available for model invocation. Use a skill from the available list.`,
+          availableSkills: Object.keys(autoInvocable)
+        };
+      }
+      const promptDef = await promptManager.getPromptDefinition(skillKey);
+      const promptResult = await promptManager.getPrompt(skillKey, args);
+      const flattened = (0, import_core.flattenPromptResult)(promptResult);
+      const content = flattened.text;
+      if (promptDef?.context === "fork") {
+        const taskForker = context.services?.taskForker;
+        if (!taskForker) {
+          return {
+            error: `Skill '${skill}' requires fork execution (context: fork), but agent spawning is not available.`,
+            skill: skillKey
+          };
+        }
+        const instructions = taskContext ? `## Task Context
+${taskContext}
+
+## Skill Instructions
+${content}` : content;
+        const forkOptions = {
+          task: `Skill: ${skill}`,
+          instructions,
+          autoApprove: true
+        };
+        if (promptDef.agent) {
+          forkOptions.agentId = promptDef.agent;
+        }
+        if (context.toolCallId) {
+          forkOptions.toolCallId = context.toolCallId;
+        }
+        if (context.sessionId) {
+          forkOptions.sessionId = context.sessionId;
+        }
+        const result = await taskForker.fork(forkOptions);
+        if (result.success) {
+          return result.response ?? "Task completed successfully.";
+        }
+        return `Error: ${result.error ?? "Unknown error during forked execution"}`;
+      }
+      return {
+        skill: skillKey,
+        content,
+        instructions: "Follow the instructions in the skill content above to complete the task."
+      };
+    }
+  });
+}
+function buildToolDescription() {
+  return `Invoke a skill to load and execute specialized instructions for a task. Skills are predefined prompts that guide how to handle specific scenarios.
+
+When to use:
+- When you recognize a task that matches an available skill
+- When you need specialized guidance for a complex operation
+- When the user references a skill by name
+
+Parameters:
+- skill: The name of the skill to invoke
+- args: Optional arguments to pass to the skill (e.g., for $ARGUMENTS substitution)
+- taskContext: Context about what you're trying to accomplish (important for forked skills that run in isolation)
+
+Execution modes:
+- **Inline skills**: Return instructions for you to follow in the current conversation
+- **Fork skills**: Automatically execute in an isolated subagent and return the result (no additional tool calls needed)
+
+Fork skills run in complete isolation without access to conversation history. They're useful for tasks that should run independently.
+
+Available skills are listed in your system prompt. Use the skill name exactly as shown.`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createInvokeSkillTool
+});

package/dist/implementations/invoke-skill-tool.d.cts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import { Tool } from '@dexto/core';
+
+declare const InvokeSkillInputSchema: z.ZodObject<{
+    skill: z.ZodString;
+    args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    taskContext: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    skill: string;
+    args?: Record<string, string> | undefined;
+    taskContext?: string | undefined;
+}, {
+    skill: string;
+    args?: Record<string, string> | undefined;
+    taskContext?: string | undefined;
+}>;
+/**
+ * Create the `invoke_skill` tool.
+ *
+ * Loads an auto-invocable prompt (“skill”) via the PromptManager and returns its content, or
+ * forks the skill into a sub-agent when the skill is marked as `context: fork`.
+ * Requires `ToolExecutionContext.services.prompts` and, for forked skills, `services.taskForker`.
+ */
+declare function createInvokeSkillTool(): Tool<typeof InvokeSkillInputSchema>;
+
+export { createInvokeSkillTool };

package/dist/implementations/invoke-skill-tool.d.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import type { Tool } from '@dexto/core';
+declare const InvokeSkillInputSchema: z.ZodObject<{
+    skill: z.ZodString;
+    args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    taskContext: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    skill: string;
+    args?: Record<string, string> | undefined;
+    taskContext?: string | undefined;
+}, {
+    skill: string;
+    args?: Record<string, string> | undefined;
+    taskContext?: string | undefined;
+}>;
+/**
+ * Create the `invoke_skill` tool.
+ *
+ * Loads an auto-invocable prompt (“skill”) via the PromptManager and returns its content, or
+ * forks the skill into a sub-agent when the skill is marked as `context: fork`.
+ * Requires `ToolExecutionContext.services.prompts` and, for forked skills, `services.taskForker`.
+ */
+export declare function createInvokeSkillTool(): Tool<typeof InvokeSkillInputSchema>;
+export {};
+//# sourceMappingURL=invoke-skill-tool.d.ts.map

package/dist/implementations/invoke-skill-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke-skill-tool.d.ts","sourceRoot":"","sources":["../../src/implementations/invoke-skill-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAmB,IAAI,EAAwB,MAAM,aAAa,CAAC;AAE/E,QAAA,MAAM,sBAAsB;;;;;;;;;;;;EAgBf,CAAC;AAEd;;;;;;GAMG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAAC,OAAO,sBAAsB,CAAC,CA0F3E"}

package/dist/implementations/invoke-skill-tool.js

@@ -0,0 +1,110 @@
+import { z } from "zod";
+import { ToolError, defineTool, flattenPromptResult } from "@dexto/core";
+const InvokeSkillInputSchema = z.object({
+  skill: z.string().min(1, "Skill name is required").describe(
+    'The name of the skill to invoke (e.g., "plugin-name:skill-name" or "skill-name")'
+  ),
+  args: z.record(z.string()).optional().describe("Optional arguments to pass to the skill"),
+  taskContext: z.string().optional().describe(
+    "Context about what task this skill should accomplish. Recommended for forked skills to provide context since they run in isolation without conversation history."
+  )
+}).strict();
+function createInvokeSkillTool() {
+  return defineTool({
+    id: "invoke_skill",
+    displayName: "Skill",
+    description: buildToolDescription(),
+    inputSchema: InvokeSkillInputSchema,
+    async execute(input, context) {
+      const { skill, args, taskContext } = input;
+      const promptManager = context.services?.prompts;
+      if (!promptManager) {
+        throw ToolError.configInvalid(
+          "invoke_skill requires ToolExecutionContext.services.prompts"
+        );
+      }
+      const autoInvocable = await promptManager.listAutoInvocablePrompts();
+      let skillKey;
+      for (const key of Object.keys(autoInvocable)) {
+        const info = autoInvocable[key];
+        if (!info) continue;
+        if (key === skill || info.displayName === skill || info.commandName === skill || info.name === skill) {
+          skillKey = key;
+          break;
+        }
+      }
+      if (!skillKey) {
+        return {
+          error: `Skill '${skill}' not found or not available for model invocation. Use a skill from the available list.`,
+          availableSkills: Object.keys(autoInvocable)
+        };
+      }
+      const promptDef = await promptManager.getPromptDefinition(skillKey);
+      const promptResult = await promptManager.getPrompt(skillKey, args);
+      const flattened = flattenPromptResult(promptResult);
+      const content = flattened.text;
+      if (promptDef?.context === "fork") {
+        const taskForker = context.services?.taskForker;
+        if (!taskForker) {
+          return {
+            error: `Skill '${skill}' requires fork execution (context: fork), but agent spawning is not available.`,
+            skill: skillKey
+          };
+        }
+        const instructions = taskContext ? `## Task Context
+${taskContext}
+
+## Skill Instructions
+${content}` : content;
+        const forkOptions = {
+          task: `Skill: ${skill}`,
+          instructions,
+          autoApprove: true
+        };
+        if (promptDef.agent) {
+          forkOptions.agentId = promptDef.agent;
+        }
+        if (context.toolCallId) {
+          forkOptions.toolCallId = context.toolCallId;
+        }
+        if (context.sessionId) {
+          forkOptions.sessionId = context.sessionId;
+        }
+        const result = await taskForker.fork(forkOptions);
+        if (result.success) {
+          return result.response ?? "Task completed successfully.";
+        }
+        return `Error: ${result.error ?? "Unknown error during forked execution"}`;
+      }
+      return {
+        skill: skillKey,
+        content,
+        instructions: "Follow the instructions in the skill content above to complete the task."
+      };
+    }
+  });
+}
+function buildToolDescription() {
+  return `Invoke a skill to load and execute specialized instructions for a task. Skills are predefined prompts that guide how to handle specific scenarios.
+
+When to use:
+- When you recognize a task that matches an available skill
+- When you need specialized guidance for a complex operation
+- When the user references a skill by name
+
+Parameters:
+- skill: The name of the skill to invoke
+- args: Optional arguments to pass to the skill (e.g., for $ARGUMENTS substitution)
+- taskContext: Context about what you're trying to accomplish (important for forked skills that run in isolation)
+
+Execution modes:
+- **Inline skills**: Return instructions for you to follow in the current conversation
+- **Fork skills**: Automatically execute in an isolated subagent and return the result (no additional tool calls needed)
+
+Fork skills run in complete isolation without access to conversation history. They're useful for tasks that should run independently.
+
+Available skills are listed in your system prompt. Use the skill name exactly as shown.`;
+}
+export {
+  createInvokeSkillTool
+};