From 6af47966f8e49d495abd172898f266e6a5d4c486 Mon Sep 17 00:00:00 2001 From: EmersonBraun Date: Sat, 3 Oct 2026 15:43:21 -0300 Subject: [PATCH] docs(tools): document public API root --- .changeset/doc03-tools.md | 5 +++++ docs/stability/jsdoc-coverage-v1.json | 14 -------------- packages/tools/src/discovery.ts | 5 +++++ packages/tools/src/fetch-url.ts | 10 ++++++++++ packages/tools/src/filesystem.ts | 12 ++++++++++++ packages/tools/src/shell.ts | 13 +++++++++++++ packages/tools/src/slack.ts | 14 ++++++++++++++ packages/tools/src/sqlite-query.ts | 14 ++++++++++++++ packages/tools/src/web-search.ts | 3 +++ packages/tools/src/zod.ts | 3 +++ 10 files changed, 79 insertions(+), 14 deletions(-) create mode 100644 .changeset/doc03-tools.md diff --git a/.changeset/doc03-tools.md b/.changeset/doc03-tools.md new file mode 100644 index 000000000..044e4745d --- /dev/null +++ b/.changeset/doc03-tools.md @@ -0,0 +1,5 @@ +--- +'@agentskit/tools': patch +--- + +Document the public API. diff --git a/docs/stability/jsdoc-coverage-v1.json b/docs/stability/jsdoc-coverage-v1.json index 50ca6d4df..572b847d0 100644 --- a/docs/stability/jsdoc-coverage-v1.json +++ b/docs/stability/jsdoc-coverage-v1.json @@ -1120,20 +1120,6 @@ ".::validateToolTemplate" ], "@agentskit/tools": [ - ".::DefineZodToolConfig", - ".::FetchUrlConfig", - ".::filesystem", - ".::FilesystemConfig", - ".::listTools", - ".::shell", - ".::ShellConfig", - ".::slackTool", - ".::SlackToolConfig", - ".::SqliteQueryConfig", - ".::sqliteQueryTool", - ".::WebSearchConfig", - ".::WebSearchProvider", - ".::WebSearchResult", "./integrations::browserAgent", "./integrations::BrowserAgentConfig", "./integrations::browserClick", diff --git a/packages/tools/src/discovery.ts b/packages/tools/src/discovery.ts index 07f673807..ffe81c445 100644 --- a/packages/tools/src/discovery.ts +++ b/packages/tools/src/discovery.ts @@ -5,6 +5,7 @@ import { fetchUrl } from './fetch-url' import { filesystem } from './filesystem' import { shell } from './shell' +/** Model-facing metadata for one built-in tool. */ export interface ToolMetadata { name: string description: string @@ -23,6 +24,10 @@ function extractMetadata(tool: ToolDefinition): ToolMetadata { } } +/** List metadata for the package's built-in tools using their default configurations. + * + * @returns Names, descriptions, tags, categories, and JSON Schemas for each built-in tool. + */ export function listTools(): ToolMetadata[] { // Instantiate tools with safe defaults to extract their metadata const tools: ToolDefinition[] = [ diff --git a/packages/tools/src/fetch-url.ts b/packages/tools/src/fetch-url.ts index 5d5300388..aca972e5b 100644 --- a/packages/tools/src/fetch-url.ts +++ b/packages/tools/src/fetch-url.ts @@ -1,6 +1,7 @@ import type { ToolDefinition } from '@agentskit/core' import { checkEgress } from './safe-fetch' +/** Response, redirect, and egress settings for {@link fetchUrl}. */ export interface FetchUrlConfig { /** Maximum bytes to read from the response body. Default: 200 KB. */ maxBytes?: number @@ -82,6 +83,15 @@ function stripHtml(html: string): string { * - Caps response size via `maxBytes` so a huge page can't flood the * model's context window or blow memory. * - Strips HTML tags by default; set `raw: true` to get the body verbatim. + * + * @param config Byte cap, timeout, user agent, and egress policy options. + * @returns A `fetch_url` tool definition. + * @example + * ```ts + * import { fetchUrl } from '@agentskit/tools' + * + * const tool = fetchUrl({ maxBytes: 100_000 }) + * ``` */ export function fetchUrl(config: FetchUrlConfig = {}): ToolDefinition { const { diff --git a/packages/tools/src/filesystem.ts b/packages/tools/src/filesystem.ts index a06ead98e..bf2daac10 100644 --- a/packages/tools/src/filesystem.ts +++ b/packages/tools/src/filesystem.ts @@ -2,6 +2,7 @@ import { isAbsolute, resolve, relative, sep } from 'node:path' import { ErrorCodes, ToolError } from '@agentskit/core' import type { ToolDefinition } from '@agentskit/core' +/** Workspace root and symlink policy for {@link filesystem}. */ export interface FilesystemConfig { basePath: string /** @@ -115,6 +116,17 @@ async function realJailPath( return real } +/** Create jailed file read, write, and directory-listing tools. + * + * @param config Workspace root and symlink policy. + * @returns The `read_file`, confirmation-gated `write_file`, and `list_directory` tools. + * @example + * ```ts + * import { filesystem } from '@agentskit/tools' + * + * const tools = filesystem({ basePath: './workspace' }) + * ``` + */ export function filesystem(config: FilesystemConfig): ToolDefinition[] { const basePath = resolve(config.basePath) const denySymlinks = config.denySymlinks ?? true diff --git a/packages/tools/src/shell.ts b/packages/tools/src/shell.ts index c51c48ccc..3212d833d 100644 --- a/packages/tools/src/shell.ts +++ b/packages/tools/src/shell.ts @@ -1,6 +1,7 @@ import { ConfigError, ErrorCodes, type ToolDefinition } from '@agentskit/core' import { isWindows } from '@agentskit/cross-platform/pure' +/** Executable allowlist, timeout, output cap, working directory, and environment for {@link shell}. */ export interface ShellConfig { /** Per-command timeout in ms. Default 30s. */ timeout?: number @@ -51,6 +52,18 @@ function parseCommand(input: string, windows: boolean): { argv: string[]; reason return { argv } } +/** Create a confirmation-gated tool that runs one executable without a shell. + * + * @param config Allowlist or trusted open mode, timeout, output limit, and process options. + * @returns A `shell` tool definition. + * @throws {ConfigError} With code AK_CONFIG_INVALID when neither `allowed` nor `allowAny` is set. + * @example + * ```ts + * import { shell } from '@agentskit/tools' + * + * const tool = shell({ allowed: ['git', 'node'] }) + * ``` + */ export function shell(config: ShellConfig = {}): ToolDefinition { const { timeout = 30_000, diff --git a/packages/tools/src/slack.ts b/packages/tools/src/slack.ts index e7cd0e954..a3bbf0d93 100644 --- a/packages/tools/src/slack.ts +++ b/packages/tools/src/slack.ts @@ -5,6 +5,7 @@ import type { ToolDefinition } from '@agentskit/core' const MAX_SLACK_ERROR_BYTES = 1024 +/** Incoming webhook and request cancellation settings for {@link slackTool}. */ export interface SlackToolConfig { webhookUrl: string /** Override fetch (mainly for tests). Defaults to the global `fetch`. */ @@ -13,6 +14,19 @@ export interface SlackToolConfig { signal?: AbortSignal } +/** Create a confirmation-gated tool that sends messages through a Slack webhook. + * + * @param config Slack incoming webhook URL and optional fetch, timeout, and abort signal. + * @returns A `slack_send` tool definition. + * @throws {ConfigError} With code AK_CONFIG_INVALID when `webhookUrl` is empty. + * @throws {ToolError} During execution when the message is empty or Slack returns a non-success response. + * @example + * ```ts + * import { slackTool } from '@agentskit/tools' + * + * const tool = slackTool({ webhookUrl: process.env.SLACK_WEBHOOK_URL! }) + * ``` + */ export function slackTool(config: SlackToolConfig): ToolDefinition { if (!config.webhookUrl) { throw new ConfigError({ diff --git a/packages/tools/src/sqlite-query.ts b/packages/tools/src/sqlite-query.ts index bb9d20619..913bd02fc 100644 --- a/packages/tools/src/sqlite-query.ts +++ b/packages/tools/src/sqlite-query.ts @@ -1,6 +1,7 @@ import { ConfigError, ErrorCodes, ToolError } from '@agentskit/core' import type { ToolDefinition } from '@agentskit/core' +/** Read-only database path and row limit for {@link sqliteQueryTool}. */ export interface SqliteQueryConfig { path: string /** Reserved for v2; only `true` is accepted today. */ @@ -39,6 +40,19 @@ async function openDatabase(path: string): Promise { const WRITE_KEYWORDS = /\b(?:insert|update|delete|drop|create|alter|attach|detach|replace|reindex|vacuum|pragma)\b/i +/** Create a read-only SQLite query tool backed by optional `better-sqlite3`. + * + * @param config Database file path, read-only flag, and maximum returned rows. + * @returns A `sqlite_query` tool definition. + * @throws {ConfigError} With code AK_CONFIG_INVALID for an unsupported `readOnly` value or invalid `maxRows`. + * @throws {ToolError} During execution when `better-sqlite3` is unavailable or the query is not read-only. + * @example + * ```ts + * import { sqliteQueryTool } from '@agentskit/tools' + * + * const tool = sqliteQueryTool({ path: './data.db', maxRows: 50 }) + * ``` + */ export function sqliteQueryTool(config: SqliteQueryConfig): ToolDefinition { if (config.readOnly !== undefined && config.readOnly !== true) { throw new ConfigError({ diff --git a/packages/tools/src/web-search.ts b/packages/tools/src/web-search.ts index f33df1626..5440e5818 100644 --- a/packages/tools/src/web-search.ts +++ b/packages/tools/src/web-search.ts @@ -3,14 +3,17 @@ import { NetError, NetErrorCodes, readText } from '@agentskit/net' import type { ToolDefinition } from '@agentskit/core' import { safeFetch } from './safe-fetch' +/** Title, URL, and text snippet returned by a web-search provider. */ export interface WebSearchResult { title: string url: string snippet: string } +/** Search backend selection; `auto` prefers configured Serper, then Tavily, then DuckDuckGo. */ export type WebSearchProvider = 'auto' | 'serper' | 'tavily' | 'duckduckgo' +/** Provider, credentials, result count, timeout, response cap, and custom search settings for {@link webSearch}. */ export interface WebSearchConfig { /** * Which backend to use. `'auto'` (default) picks the best available: diff --git a/packages/tools/src/zod.ts b/packages/tools/src/zod.ts index 1d404a007..e9225ed62 100644 --- a/packages/tools/src/zod.ts +++ b/packages/tools/src/zod.ts @@ -18,6 +18,7 @@ type InferZodOutput = T extends ZodLike ? O : never // defineZodTool — Zod-based tool definition with automatic type inference // --------------------------------------------------------------------------- +/** Configuration for {@link defineZodTool}, including its runtime and JSON Schema adapters. */ export interface DefineZodToolConfig { name: string description?: string @@ -46,6 +47,8 @@ export interface DefineZodToolConfig { * callback lets you convert the Zod schema to JSON Schema for the adapter * (e.g. using `zod-to-json-schema`). * + * @param config Tool metadata, Zod schema, and optional schema-conversion and execution callbacks. + * @returns A `ToolDefinition` whose execution arguments are inferred from the schema. * @example * ```ts * import { z } from 'zod'