docs: add public JSDoc to tools, skills, mcp and cross-platform (DOC-03)

.changeset/doc03-cross-platform.md

@@ -0,0 +1,5 @@
+---
+'@agentskit/cross-platform': patch
+---
+
+Document the public API.

.changeset/doc03-mcp.md

@@ -0,0 +1,5 @@
+---
+'@agentskit/mcp': patch
+---
+
+Document the public API.

.changeset/doc03-skills.md

@@ -0,0 +1,5 @@
+---
+'@agentskit/skills': patch
+---
+
+Document the public API.

.changeset/doc03-tools.md

@@ -0,0 +1,5 @@
+---
+'@agentskit/tools': patch
+---
+
+Document the public API.

docs/stability/jsdoc-coverage-v1.json

@@ -7,42 +7,11 @@
     "@agentskit/core": [],
     "@agentskit/cross-platform": [
       ".::basename",
-      ".::CliIo",
-      ".::compareToBaseline",
-      ".::Comparison",
-      ".::countFindings",
-      ".::CrossPlatformError",
-      ".::CrossPlatformErrorCode",
-      ".::CrossPlatformErrorCodes",
       ".::dirname",
-      ".::Env",
-      ".::ExitStatus",
       ".::extname",
-      ".::Finding",
-      ".::Frontmatter",
-      ".::LinkKind",
-      ".::PathCompareOptions",
-      ".::PORTABILITY_RULES",
-      ".::RemoveOptions",
-      ".::ResolvedCommand",
-      ".::RunOptions",
-      ".::RunResult",
-      ".::RuntimeInfo",
-      ".::SafeEnvOptions",
-      ".::ScanOptions",
-      ".::SpawnOptions",
-      ".::SplitLinesOptions",
-      ".::StdioMode",
-      ".::TerminationReason",
-      ".::WhichOptions",
-      ".::WriteAtomicOptions",
       "./pure::basename",
       "./pure::dirname",
-      "./pure::extname",
-      "./pure::Frontmatter",
-      "./pure::PathCompareOptions",
-      "./pure::RuntimeInfo",
-      "./pure::SplitLinesOptions"
+      "./pure::extname"
     ],
     "@agentskit/eval": [],
     "@agentskit/ink": [],
@@ -134,12 +103,7 @@
       "./testing::validateAction",
       "./testing::validateTrigger"
     ],
-    "@agentskit/mcp": [
-      ".::AgentsKitMcpServerOptions",
-      ".::AgentToolConfig",
-      ".::McpServer",
-      ".::TypedAgentToolConfig"
-    ],
+    "@agentskit/mcp": [],
     "@agentskit/memory": [
       ".::ChatMemoryRedactionOptions",
       ".::chroma",
@@ -322,76 +286,12 @@
     "@agentskit/react-native": [],
     "@agentskit/runtime": [],
     "@agentskit/sandbox": [],
-    "@agentskit/skills": [
-      ".::clinicalNoteSummarizer",
-      ".::coder",
-      ".::codeReviewer",
-      ".::compareSemver",
-      ".::composeSkills",
-      ".::contractReviewer",
-      ".::critic",
-      ".::curriculumDesigner",
-      ".::customerSupport",
-      ".::dataAnalyst",
-      ".::financialAdvisor",
-      ".::GlossaryEntry",
-      ".::healthcareAssistant",
-      ".::marketAnalyst",
-      ".::merchandisingAnalyst",
-      ".::planner",
-      ".::prReviewer",
-      ".::researcher",
-      ".::securityAuditor",
-      ".::SkillMetadata",
-      ".::SkillRegistry",
-      ".::SkillRegistryQuery",
-      ".::sqlAnalyst",
-      ".::sqlGen",
-      ".::summarizer",
-      ".::technicalWriter",
-      ".::transactionTriage"
-    ],
+    "@agentskit/skills": [],
     "@agentskit/solid": [],
     "@agentskit/statechart": [],
     "@agentskit/svelte": [],
     "@agentskit/templates": [],
     "@agentskit/tools": [
-      ".::DefineZodToolConfig",
-      ".::FetchUrlConfig",
-      ".::filesystem",
-      ".::FilesystemConfig",
-      ".::listTools",
-      ".::shell",
-      ".::ShellConfig",
-      ".::slackTool",
-      ".::SlackToolConfig",
-      ".::SqliteQueryConfig",
-      ".::sqliteQueryTool",
-      ".::WebSearchConfig",
-      ".::WebSearchProvider",
-      ".::WebSearchResult",
-      "./integrations::browserAgent",
-      "./integrations::BrowserAgentConfig",
-      "./integrations::browserClick",
-      "./integrations::browserFill",
-      "./integrations::browserGoto",
-      "./integrations::browserRead",
-      "./integrations::browserScreenshot",
-      "./integrations::browserWait",
-      "./integrations::CdcAdminClient",
-      "./integrations::CdcChangeEvent",
-      "./integrations::CdcSlotStatus",
-      "./integrations::CdcStreamClient",
-      "./integrations::CdcStreamOptions",
-      "./integrations::cloudflareR2",
-      "./integrations::CloudflareR2Config",
-      "./integrations::cloudflareR2Delete",
-      "./integrations::cloudflareR2Get",
-      "./integrations::cloudflareR2List",
-      "./integrations::cloudflareR2Put",
-      "./integrations::cloudflareR2SignedUrl",
-      "./integrations::documentParsers",
-      "./integrations::DocumentParsersConfig",
       "./integrations::EmailAttachment",
       "./integrations::EmailConfig",
       "./integrations::EmailMessage",
@@ -402,56 +302,13 @@
       "./integrations::HttpToolOptions",
       "./integrations::ImapClient",
       "./integrations::ImapFetchOptions",
-      "./integrations::parseDocx",
-      "./integrations::parsePdf",
-      "./integrations::parseXlsx",
-      "./integrations::postgres",
-      "./integrations::postgresCdc",
-      "./integrations::postgresCdcAdvance",
-      "./integrations::PostgresCdcConfig",
-      "./integrations::postgresCdcCreateSlot",
-      "./integrations::postgresCdcDropSlot",
-      "./integrations::postgresCdcPeek",
-      "./integrations::postgresCdcStatus",
-      "./integrations::PostgresConfig",
-      "./integrations::postgresQuery",
-      "./integrations::PostgresRolesConfig",
-      "./integrations::R2ClientLike",
       "./integrations::RetryPolicy",
-      "./integrations::s3",
-      "./integrations::S3Config",
-      "./integrations::s3GetObject",
-      "./integrations::s3ListObjects",
-      "./integrations::s3PutObject",
       "./integrations::TeamsAdaptiveCard",
       "./integrations::TeamsAdaptiveCardAction",
       "./integrations::TeamsBotClient",
       "./integrations::TeamsBotMessage",
       "./integrations::TeamsBotSendResult",
-      "./integrations::TeamsMessageCard",
-      "./mcp-devtools::devtoolsTools",
-      "./mcp-devtools::EvalResult",
-      "./mcp-devtools::EvalSummary",
-      "./mcp-devtools::MemorySummary",
-      "./mcp-devtools::ReplayHandle",
-      "./mcp-devtools::SessionDetail",
-      "./mcp-devtools::SessionMessage",
-      "./mcp-devtools::SessionSummary",
-      "./mcp-devtools::SkillSummary",
-      "./mcp-devtools::StepResult",
-      "./mcp-devtools::ToolSummary",
-      "./mcp::createStdioTransport",
-      "./mcp::JsonRpcError",
-      "./mcp::JsonRpcMessage",
-      "./mcp::JsonRpcNotification",
-      "./mcp::JsonRpcSuccess",
-      "./mcp::McpCallToolResult",
-      "./mcp::McpClient",
-      "./mcp::McpContentText",
-      "./mcp::McpServer",
-      "./mcp::McpServerOptions",
-      "./mcp::McpToolDescriptor",
-      "./mcp::McpToolsListResult"
+      "./integrations::TeamsMessageCard"
     ],
     "@agentskit/vue": []
   }

packages/cross-platform/src/env.ts

@@ -2,6 +2,7 @@ import { homedir, tmpdir } from 'node:os'
 import { mapRuntimeError } from './errors'
 import { isWindows } from './runtime'
 
+/** Environment variables where an unset key has an `undefined` value. */
 export type Env = Record<string, string | undefined>
 
 /**
@@ -60,6 +61,7 @@ export function getEnv(name: string, env: Env = readProcessEnv()): string | unde
   return key === undefined ? undefined : env[key]
 }
 
+/** Allowlist and overrides used to construct a child process environment. */
 export interface SafeEnvOptions {
   /** Extra variable names to inherit from the parent environment. */
   inherit?: readonly string[]

packages/cross-platform/src/errors.ts

@@ -2,6 +2,7 @@ import { AgentsKitError } from '@agentskit/core'
 
 const DOCS_URL = 'https://www.agentskit.io/docs/reference/packages/cross-platform'
 
+/** Stable codes used by cross-platform process and filesystem errors. */
 export const CrossPlatformErrorCodes = {
   AK_PLATFORM_PERMISSION_DENIED: 'AK_PLATFORM_PERMISSION_DENIED',
   AK_PLATFORM_COMMAND_NOT_FOUND: 'AK_PLATFORM_COMMAND_NOT_FOUND',
@@ -10,8 +11,10 @@ export const CrossPlatformErrorCodes = {
   AK_PLATFORM_UNSUPPORTED_RUNTIME: 'AK_PLATFORM_UNSUPPORTED_RUNTIME',
 } as const
 
+/** Union of the stable cross-platform error codes. */
 export type CrossPlatformErrorCode = (typeof CrossPlatformErrorCodes)[keyof typeof CrossPlatformErrorCodes]
 
+/** Error raised by a cross-platform operation with a stable code and optional cause. */
 export class CrossPlatformError extends AgentsKitError {
   constructor(options: {
     code: CrossPlatformErrorCode

packages/cross-platform/src/fs.ts

@@ -10,6 +10,7 @@ import { isWindows } from './runtime'
 // indexers or a lingering handle hold the file (EPERM/EACCES/EBUSY).
 const gracefulRename = promisify(gracefulFs.rename)
 
+/** Retry and recursive-removal settings for graceful directory removal. */
 export interface RemoveOptions {
   /** Retries for EBUSY/EPERM/ENOTEMPTY while handles close. Default 10. */
   maxRetries?: number
@@ -40,6 +41,7 @@ export async function renamePath(from: string, to: string): Promise<void> {
   }
 }
 
+/** File mode and directory creation settings for an atomic write. */
 export interface WriteAtomicOptions {
   encoding?: BufferEncoding
   mode?: number
@@ -60,6 +62,7 @@ export async function writeFileAtomic(path: string, data: string | Uint8Array, o
   }
 }
 
+/** Method used to create a link, including platform fallbacks. */
 export type LinkKind = 'symlink' | 'junction' | 'copy'
 
 /**

packages/cross-platform/src/lint/baseline.ts

@@ -4,7 +4,8 @@ import type { Finding } from './scan'
  * Ratchet baseline: existing findings are recorded per file and rule; a
  * check fails when any count grows or a new file/rule appears. Counts may
  * only go down (`--update` refuses to raise them).
- */
+
+ * Stored portability-finding counts grouped by rule and file. */
 export interface Baseline {
   version: 1
   /** Directories scanned, relative to the repository root. */
@@ -21,6 +22,10 @@ function emptyMap<T>(): Record<string, T> {
   return Object.create(null) as Record<string, T>
 }
 
+/** Count findings by rule and file for storage in a baseline.
+ *
+ * @param findings Findings to count.
+ * @returns Rule-to-file counts. */
 export function countFindings(findings: readonly Finding[]): Record<string, Record<string, number>> {
   const counts = emptyMap<Record<string, number>>()
   for (const finding of findings) {
@@ -30,13 +35,19 @@ export function countFindings(findings: readonly Finding[]): Record<string, Reco
   return counts
 }
 
+/** New and resolved findings produced by a baseline comparison. */
 export interface Comparison {
   /** Findings in files/rules whose count exceeds the baseline. */
   regressions: Finding[]
   /** file/rule pairs now below their baseline count. */
   improvements: Array<{ file: string; rule: string; allowed: number; actual: number }>
 }
 
+/** Compare current findings with a stored portability baseline.
+ *
+ * @param findings Current findings.
+ * @param baseline Stored baseline.
+ * @returns Regressions and improvements. */
 export function compareToBaseline(findings: readonly Finding[], baseline: Baseline): Comparison {
   const counts = countFindings(findings)
   const regressions: Finding[] = []

packages/cross-platform/src/lint/cli.ts

@@ -9,15 +9,18 @@ import type { PortabilityRule } from './rules'
 const DEFAULT_BASELINE = '.cross-platform-baseline.json'
 const DEFAULT_INCLUDE = ['packages', 'scripts', 'src', 'apps']
 
+/** Input/output functions injected into the portability CLI. */
 export interface CliIo {
   cwd: string
   log: (line: string) => void
   error: (line: string) => void
 }
 
 /** Options for customizing the rules and findings used by the baseline CLI.
+ *
  * @since 0.2.0
- */
+
+ * Arguments, working directory, and I/O dependencies for the portability CLI. */
 export interface RunCliOptions {
   /** Rules to scan with; defaults to `PORTABILITY_RULES`. */
   rules?: readonly PortabilityRule[]
@@ -99,10 +102,15 @@ async function saveBaseline(path: string, baseline: Baseline): Promise<void> {
 
 /**
  * Run the baseline CLI with optional custom rules and finding filtering.
+ *
  * @param argv CLI arguments after the executable name.
+ *
  * @param io Working directory and output handlers for the command.
+ *
  * @param options Custom rules and finding filter, available since 0.2.0; defaults to `PORTABILITY_RULES` with no filtering.
+ *
  * @returns The process exit code.
+ *
  * @since 0.1.1
  */
 export async function runCli(argv: readonly string[], io: CliIo, options: RunCliOptions = {}): Promise<number> {

packages/cross-platform/src/lint/rules.ts

@@ -2,14 +2,16 @@
  * Static patterns that broke Windows (or another runtime) in the AgentsKit
  * ecosystem. Each one maps to the @agentskit/cross-platform API to use.
  * Regexes run per line, so they stay simple and predictable.
- */
+
+ * Rule definition used by the portability source scanner. */
 export interface PortabilityRule {
   id: string
   pattern: RegExp
   message: string
   fix: string
 }
 
+/** Built-in rules for common cross-platform source hazards. */
 export const PORTABILITY_RULES: readonly PortabilityRule[] = [
   {
     id: 'child-process-import',

packages/cross-platform/src/lint/scan.ts

@@ -4,6 +4,7 @@ import { toPosix } from '../paths'
 import { splitLines } from '../text'
 import { IGNORE_DIRECTIVE, PORTABILITY_RULES, type PortabilityRule } from './rules'
 
+/** A portability rule violation and its source location. */
 export interface Finding {
   file: string
   line: number
@@ -12,6 +13,7 @@ export interface Finding {
   fix: string
 }
 
+/** Optional rule set and file filters for repository scanning. */
 export interface ScanOptions {
   /** Repository root; reported paths are relative to it, with `/`. */
   root: string

packages/cross-platform/src/paths.ts

@@ -44,6 +44,7 @@ export function isWindowsStylePath(path: string): boolean {
   return WINDOWS_STYLE.test(path)
 }
 
+/** Case and separator rules used when comparing paths. */
 export interface PathCompareOptions {
   /**
    * Compare case-insensitively. Defaults to true on Windows hosts or when