@agentskit/cli 0.13.46 → 0.13.47

package/dist/index.d.cts

@@ -4,8 +4,18 @@ import React from 'react';
 import { ChildProcess } from 'node:child_process';
 import { RAG } from '@agentskit/rag';
 
+/**
+ * Creates the Commander program and registers the AgentsKit CLI commands.
+ * @returns A configured Commander program.
+ * @example
+ * const program = createCli()
+ */
 declare function createCli(): Command;
 
+/**
+ * Configuration values loaded by the AgentsKit CLI, including defaults and integrations.
+
+ */
 interface AgentsKitConfig {
     tools?: {
         filesystem?: {
@@ -101,6 +111,10 @@ interface AgentsKitConfig {
         }>;
     };
 }
+/**
+ * Path and environment settings used while loading CLI configuration.
+
+ */
 interface LoadConfigOptions {
     cwd?: string;
     /**
@@ -123,18 +137,38 @@ interface LoadConfigOptions {
  */
 declare function loadConfig(options?: LoadConfigOptions): Promise<AgentsKitConfig | undefined>;
 
+/**
+ * Default policy mode used when evaluating tool permissions.
+
+ */
 type PermissionMode = 'default' | 'plan' | 'acceptEdits' | 'bypassPermissions';
+/**
+ * Action the CLI applies to a tool: allow, ask for confirmation, or deny.
+
+ */
 type PermissionAction = 'allow' | 'ask' | 'deny';
+/**
+ * Tool matcher, permission action, and optional rule scope.
+
+ */
 interface PermissionRule {
     /** Exact name, or a `RegExp` / `"re:pattern"` string matching the tool name. */
     tool: string | RegExp;
     action: PermissionAction;
     scope?: 'session' | 'project' | 'global';
 }
+/**
+ * Default permission mode and explicit tool rules for a CLI session.
+
+ */
 interface PermissionPolicy {
     mode: PermissionMode;
     rules: PermissionRule[];
 }
+/**
+ * Default permission policy with ask-on-unmatched behavior.
+
+ */
 declare const defaultPolicy: PermissionPolicy;
 /**
  * Resolve an action for a tool name. Modes override specific rules:
@@ -203,6 +237,10 @@ interface Plugin {
     init?: (ctx: PluginContext) => void | Promise<void>;
     dispose?: () => void | Promise<void>;
 }
+/**
+ * CLI services and project context passed to plugin factories.
+
+ */
 interface PluginContext {
     /** Working directory the CLI was launched from. */
     cwd: string;
@@ -211,17 +249,33 @@ interface PluginContext {
     /** Logger. */
     log: (msg: string) => void;
 }
+/**
+ * Factory that creates an adapter from provider credentials and model settings.
+
+ */
 type ProviderFactory = (config: {
     apiKey?: string;
     model: string;
     baseUrl?: string;
     extra?: Record<string, unknown>;
 }) => unknown;
+/**
+ * Lifecycle event names accepted by plugin hooks.
+
+ */
 type HookEvent = 'SessionStart' | 'SessionEnd' | 'UserPromptSubmit' | 'PreLLM' | 'PostLLM' | 'PreToolUse' | 'PostToolUse' | 'Stop' | 'Error';
+/**
+ * Lifecycle-specific data passed to plugin hooks.
+
+ */
 interface HookPayload {
     event: HookEvent;
     [key: string]: unknown;
 }
+/**
+ * Continue, modify, or block decision returned by a hook handler.
+
+ */
 type HookResult = {
     decision: 'continue';
 } | {
@@ -231,11 +285,19 @@ type HookResult = {
     decision: 'modify';
     payload: HookPayload;
 };
+/**
+ * Handler that receives a lifecycle payload and returns a hook decision.
+
+ */
 interface HookHandler {
     event: HookEvent;
     matcher?: RegExp | ((payload: HookPayload) => boolean);
     run: (payload: HookPayload) => HookResult | Promise<HookResult>;
 }
+/**
+ * Command, arguments, environment, and name for one MCP server process.
+
+ */
 interface McpServerSpec {
     name: string;
     command: string;
@@ -256,6 +318,10 @@ interface PluginBundle {
     mcpServers: McpServerSpec[];
 }
 
+/**
+ * Plugin specifiers, discovery directories, and callbacks used while loading plugins.
+
+ */
 interface LoadPluginsOptions {
     /** Plugin specifiers: absolute paths, relative paths, or package names. */
     specs?: string[];
@@ -287,6 +353,10 @@ declare function loadPlugins(options?: LoadPluginsOptions): Promise<PluginBundle
  */
 declare function mergePluginsIntoBundle(plugins: Plugin[]): PluginBundle;
 
+/**
+ * Provider, session, tool, memory, plugin, hook, and permission settings for the CLI chat app.
+
+ */
 interface ChatCommandOptions {
     provider: string;
     model?: string;
@@ -314,15 +384,33 @@ interface ChatCommandOptions {
     /** Permission policy for tool calls. */
     permissionPolicy?: PermissionPolicy;
 }
+/**
+ * Interactive Ink chat component configured with provider, session, tools, and plugins.
+
+ */
 declare function ChatApp(options: ChatCommandOptions): React.JSX.Element;
+/**
+ * Renders a compact provider, model, mode, tool, skill, and memory summary for chat.
+ * @param options Chat provider and feature settings.
+ * @returns A single-line chat header.
+ * @throws {Error} If the requested provider or its required configuration is unsupported.
+ */
 declare function renderChatHeader(options: ChatCommandOptions): string;
 
 type Provider = 'openai' | 'anthropic' | 'gemini' | 'ollama' | 'deepseek' | 'grok' | 'kimi' | 'groq' | 'openrouter' | 'demo';
 
+/**
+ * Built-in project template identifier accepted by the init command.
+
+ */
 type StarterKind = 'react' | 'nextjs' | 'ink' | 'runtime' | 'multi-agent' | 'sveltekit' | 'nuxt' | 'vite-ink' | 'cloudflare-workers' | 'bun' | 'expo' | 'deno-deploy' | 'angular';
 type ToolKind = 'web_search' | 'filesystem' | 'shell';
 type MemoryKind = 'none' | 'file' | 'sqlite';
 type PackageManager = 'pnpm' | 'npm' | 'yarn' | 'bun';
+/**
+ * Destination, starter template, and optional provider, tools, memory, and package-manager settings.
+
+ */
 interface InitCommandOptions {
     targetDir: string;
     template: StarterKind;
@@ -333,14 +421,30 @@ interface InitCommandOptions {
     /** Refuse non-empty destinations unless explicitly enabled. */
     force?: boolean;
 }
+/**
+ * Writes the selected starter template files into a destination directory.
+ * @param options Destination and starter-project settings.
+ * @returns Relative paths of existing files that were replaced.
+ * @throws {Error} If the destination is invalid or a protected path cannot be written.
+ * @example
+ * await writeStarterProject({ targetDir: './my-agent', template: 'react' })
+ */
 declare function writeStarterProject(options: InitCommandOptions): Promise<string[]>;
 
+/**
+ * Provider identifier and optional model, credentials, or endpoint used to resolve a chat adapter.
+
+ */
 interface ChatProviderOptions {
     provider: string;
     model?: string;
     apiKey?: string;
     baseUrl?: string;
 }
+/**
+ * Resolved adapter together with provider, model, mode, and display summary.
+
+ */
 interface ResolvedChatProvider {
     adapter: AdapterFactory;
     provider: string;
@@ -348,8 +452,20 @@ interface ResolvedChatProvider {
     mode: 'demo' | 'live';
     summary: string;
 }
+/**
+ * Resolves a provider name and credentials to an AgentsKit chat adapter.
+ * @param options Provider, model, credential, and endpoint settings.
+ * @returns Adapter and resolved provider details.
+ * @throws {Error} If the provider is unsupported or required credentials or model are missing.
+ * @example
+ * const resolved = resolveChatProvider({ provider: 'demo' })
+ */
 declare function resolveChatProvider(options: ChatProviderOptions): ResolvedChatProvider;
 
+/**
+ * Provider and agent runtime options accepted by the CLI run command.
+
+ */
 interface RunCommandOptions {
     provider: string;
     model?: string;
@@ -366,15 +482,36 @@ interface RunCommandOptions {
     verbose?: boolean;
     pretty?: boolean;
 }
+/**
+ * Runs one agent task with the selected provider, tools, skills, and memory.
+ * @param task User task to run.
+ * @param options Provider and runtime settings.
+ * @returns A promise that resolves when the run completes.
+ * @throws {Error} If mutually exclusive skill options are both set or provider configuration is invalid.
+ * @example
+ * await runAgent('Say hello', { provider: 'demo' })
+ */
 declare function runAgent(task: string, options: RunCommandOptions): Promise<void>;
 
+/**
+ * Outcome category returned by an AgentsKit doctor check.
+
+ */
 type CheckStatus = 'pass' | 'warn' | 'fail' | 'skip';
+/**
+ * Status, description, and optional remediation for one doctor check.
+
+ */
 interface CheckResult {
     status: CheckStatus;
     name: string;
     detail?: string;
     fix?: string;
 }
+/**
+ * Doctor check results and aggregate pass, warning, failure, and skip counts.
+
+ */
 interface DoctorReport {
     results: CheckResult[];
     pass: number;
@@ -382,6 +519,10 @@ interface DoctorReport {
     fail: number;
     skip: number;
 }
+/**
+ * Provider selection and network settings for the environment doctor.
+
+ */
 interface DoctorOptions {
     /** Provider names to check. Defaults to all known providers. */
     providers?: string[];
@@ -390,11 +531,28 @@ interface DoctorOptions {
     /** Custom fetch (for tests). */
     fetchImpl?: typeof fetch;
 }
+/**
+ * Checks the local Node environment, AgentsKit configuration, and selected providers.
+ * @param options Provider selection and network-check settings.
+ * @returns A report containing each check and aggregate status counts.
+ * @example
+ * const report = await runDoctor({ noNetwork: true })
+ */
 declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;
+/**
+ * Formats doctor check results as a terminal-friendly report.
+ * @param report Doctor results and aggregate counts.
+ * @param opts Optional rendering settings.
+ * @returns The formatted report text.
+ */
 declare function renderReport(report: DoctorReport, opts?: {
     color?: boolean;
 }): string;
 
+/**
+ * Entry file, watch patterns, and process hooks for the CLI development runner.
+
+ */
 interface DevOptions {
     /** Entry file to run (relative or absolute). */
     entry: string;
@@ -420,6 +578,10 @@ interface DevOptions {
     /** Stderr sink for tests. */
     stderr?: NodeJS.WritableStream;
 }
+/**
+ * File watcher interface consumed by the development runner.
+
+ */
 interface DevWatcher {
     on(event: 'change' | 'add' | 'unlink', listener: (path: string) => void): this;
     close(): Promise<void>;
@@ -439,8 +601,20 @@ interface DevController {
     /** Number of times the entry has been (re)started. */
     restarts: () => number;
 }
+/**
+ * Runs a project entry file and restarts it when watched files change.
+ * @param options Entry, watch patterns, and process overrides.
+ * @returns A controller for observing and stopping the development session.
+ * @throws {Error} If the entry file is missing or the TypeScript runner is unavailable.
+ * @example
+ * const dev = startDev({ entry: './src/index.ts' })
+ */
 declare function startDev(options: DevOptions): DevController;
 
+/**
+ * Local port and optional host, subdomain, callbacks, and tunnel provider override.
+
+ */
 interface TunnelOptions {
     /** Local port to expose. Required. */
     port: number;
@@ -459,11 +633,19 @@ interface TunnelOptions {
     /** Called once the tunnel URL is known. */
     onReady?: (url: string) => void;
 }
+/**
+ * Tunnel provider handle with its public URL and lifecycle methods.
+
+ */
 interface TunnelLike {
     url: string;
     on(event: 'request' | 'error' | 'close', listener: (...args: unknown[]) => void): unknown;
     close(): void;
 }
+/**
+ * Public tunnel URL, completion promise, stop action, and request count.
+
+ */
 interface TunnelController {
     /** The public URL once ready. */
     url: string;
@@ -484,6 +666,10 @@ interface TunnelController {
  */
 declare function startTunnel(options: TunnelOptions): Promise<TunnelController>;
 
+/**
+ * Session identifiers, timestamps, preview, message count, and optional provider labels.
+
+ */
 interface SessionMetadata {
     id: string;
     cwd: string;
@@ -498,21 +684,53 @@ interface SessionMetadata {
     /** Session id this one was forked from, if any. */
     forkedFrom?: string;
 }
+/**
+ * Session metadata paired with its message file path.
+
+ */
 interface SessionRecord {
     metadata: SessionMetadata;
     file: string;
 }
 /** Generate a new session id — ISO-ish timestamp + 6 random hex chars. */
 declare function generateSessionId(): string;
+/**
+ * Returns the message file path for a session and ensures its storage directory exists.
+ * @param id Session identifier.
+ * @param cwd Working directory used to namespace session storage.
+ * @returns The absolute path to the session JSON file.
+ */
 declare function sessionFilePath(id: string, cwd?: string): string;
+/**
+ * Writes session metadata to the CLI session store with private file permissions.
+ * @param meta Session metadata to persist.
+ * @param cwd Working directory used to namespace session storage.
+ * @returns Nothing.
+ */
 declare function writeSessionMeta(meta: SessionMetadata, cwd?: string): void;
 /** Derive a short preview (first user message, one line, max 80 chars). */
 declare function derivePreview(messages: Array<{
     role: string;
     content: string;
 }>): string;
+/**
+ * Lists session records for a working directory, newest first.
+ * @param cwd Working directory used to locate sessions.
+ * @returns Session records with their metadata and file paths.
+ */
 declare function listSessions(cwd?: string): SessionRecord[];
+/**
+ * Returns the most recently updated session for a working directory.
+ * @param cwd Working directory used to locate sessions.
+ * @returns The newest session record, or `null` when none exists.
+ */
 declare function findLatestSession(cwd?: string): SessionRecord | null;
+/**
+ * Finds a session by id, label, or id prefix.
+ * @param id Session identifier, label, or unique prefix.
+ * @param cwd Working directory used to locate sessions.
+ * @returns The matching session record, or `null` when none matches.
+ */
 declare function findSession(id: string, cwd?: string): SessionRecord | null;
 /** Attach or update a human-readable label on an existing session. */
 declare function renameSession(id: string, label: string, cwd?: string): SessionMetadata;
@@ -521,12 +739,20 @@ declare function renameSession(id: string, label: string, cwd?: string): Session
  * can branch a conversation without disturbing the original.
  */
 declare function forkSession(id: string, cwd?: string): ResolvedSession;
+/**
+ * Explicit file, resume, create-new, and working-directory settings for session resolution.
+
+ */
 interface ResolveSessionInput {
     explicitPath?: string;
     resumeId?: string | true;
     forceNew?: boolean;
     cwd?: string;
 }
+/**
+ * Session identifier, message file path, and whether the session was newly created.
+
+ */
 interface ResolvedSession {
     id: string;
     file: string;
@@ -543,6 +769,10 @@ interface ResolvedSession {
  */
 declare function resolveSession(input: ResolveSessionInput): ResolvedSession;
 
+/**
+ * Tool name and optional description and input schema reported by an MCP server.
+
+ */
 interface McpTool {
     name: string;
     description?: string;
@@ -573,6 +803,10 @@ declare class McpClient {
     private onStdout;
 }
 
+/**
+ * Started MCP clients and the tool definitions bridged from their servers.
+
+ */
 interface McpBridgeResult {
     clients: McpClient[];
     tools: ToolDefinition[];
@@ -584,6 +818,11 @@ interface McpBridgeResult {
  * on session end.
  */
 declare function bridgeMcpServers(specs: McpServerSpec[]): Promise<McpBridgeResult>;
+/**
+ * Disposes every MCP client opened for a CLI session.
+ * @param clients MCP clients to stop.
+ * @returns Nothing.
+ */
 declare function disposeMcpClients(clients: McpClient[]): void;
 
 /**
@@ -596,12 +835,31 @@ interface ModelPricing {
     inputPerM: number;
     outputPerM: number;
 }
+/**
+ * Registers or replaces per-million-token prices for a model in this process.
+ * @param model Model identifier to register.
+ * @param pricing Input and output prices in USD per million tokens.
+ * @returns Nothing.
+ */
 declare function registerPricing(model: string, pricing: ModelPricing): void;
+/**
+ * Looks up registered model pricing by exact id or provider-prefixed model id.
+ * @param model Model identifier to look up.
+ * @returns Pricing for the model, or `undefined` when it is unknown.
+ */
 declare function getPricing(model: string | undefined): ModelPricing | undefined;
+/**
+ * Prompt and completion token counts used for cost calculation.
+
+ */
 interface TokenUsageLike {
     promptTokens: number;
     completionTokens: number;
 }
+/**
+ * Estimated input, output, and total cost for one model response.
+
+ */
 interface ComputedCost {
     model: string;
     inputUsd: number;
@@ -611,6 +869,10 @@ interface ComputedCost {
 /** Returns computed cost, or `undefined` if no pricing is registered for the model. */
 declare function computeCost(model: string | undefined, usage: TokenUsageLike): ComputedCost | undefined;
 
+/**
+ * API key and optional model and endpoint for the OpenAI-compatible embedder.
+
+ */
 interface OpenAiEmbedderConfig {
     apiKey: string;
     model?: string;
@@ -624,6 +886,10 @@ interface OpenAiEmbedderConfig {
  */
 declare function createOpenAiEmbedder(config: OpenAiEmbedderConfig): EmbedFn;
 
+/**
+ * Sources, embedder, storage, chunking, and retrieval settings for CLI RAG.
+
+ */
 interface RagConfig {
     enabled?: boolean;
     backend?: 'memory' | 'file';
@@ -638,12 +904,20 @@ interface RagConfig {
     chunkSize?: number;
     topK?: number;
 }
+/**
+ * Configuration and optional embedder used to create a file-backed RAG instance.
+
+ */
 interface BuildRagOptions {
     config: RagConfig;
     cwd?: string;
     /** Override the embedder resolution (useful for tests). */
     embedder?: EmbedFn;
 }
+/**
+ * Count and absolute paths of the files ingested by a RAG index operation.
+
+ */
 interface IndexResult {
     /** Number of input documents ingested. */
     documentCount: number;
@@ -661,6 +935,10 @@ declare function buildRagFromConfig(options: BuildRagOptions): RAG;
  */
 declare function indexSources(rag: RAG, config: RagConfig, cwd?: string): Promise<IndexResult>;
 
+/**
+ * Final hook payload and whether dispatch was blocked.
+
+ */
 interface HookDispatchResult {
     /** Final payload after any `modify` handlers. */
     payload: HookPayload;
@@ -686,6 +964,10 @@ declare class HookDispatcher {
     private matches;
 }
 
+/**
+ * Shell command and optional matcher and timeout for a configured lifecycle hook.
+
+ */
 interface ConfigHookEntry {
     /**
      * Command to run through the platform shell (`sh -c` on POSIX, `cmd.exe /d /s /c`
@@ -697,6 +979,10 @@ interface ConfigHookEntry {
     /** Millisecond budget. Default 5000. */
     timeout?: number;
 }
+/**
+ * Configured shell hooks keyed by lifecycle event.
+
+ */
 type ConfigHooksMap = Partial<Record<HookEvent, ConfigHookEntry[]>>;
 /**
  * Normalize `config.hooks` (shell entries) into `HookHandler[]`. The shell