@agentskit/cli 0.6.0 → 0.7.1

package/dist/index.d.cts

@@ -1,7 +1,8 @@
 import { Command } from 'commander';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ChatReturn, AdapterFactory } from '@agentskit/core';
+import { ToolDefinition, ChatReturn, SkillDefinition, AdapterFactory, EmbedFn } from '@agentskit/core';
 import { ChildProcess } from 'node:child_process';
+import { RAG } from '@agentskit/rag';
 
 declare function createCli(): Command;
 
@@ -45,6 +46,60 @@ interface AgentsKitConfig {
             projectName?: string;
         };
     };
+    /**
+     * Plugin specifiers. Each entry is a package name (`@org/plugin`) or
+     * a relative/absolute path to a module exporting a `Plugin`.
+     */
+    plugins?: string[];
+    /**
+     * Shell-based hooks keyed by event name. See `extensibility/hooks`.
+     */
+    hooks?: Record<string, Array<{
+        run: string;
+        matcher?: string;
+        timeout?: number;
+    }>>;
+    /**
+     * Retrieval-augmented generation config. Indexes files via
+     * `agentskit rag index`. Chat-side auto-retrieval lands in a later phase.
+     */
+    rag?: {
+        enabled?: boolean;
+        backend?: 'memory' | 'file';
+        dir?: string;
+        sources?: string[];
+        embedder?: {
+            provider?: string;
+            model?: string;
+            apiKey?: string;
+            baseUrl?: string;
+        };
+        chunkSize?: number;
+        topK?: number;
+    };
+    /**
+     * MCP servers to spawn on chat start. Tools list + call bridge
+     * them into the runtime tool set as `<serverName>__<toolName>`.
+     */
+    mcp?: {
+        servers?: Record<string, {
+            command: string;
+            args?: string[];
+            env?: Record<string, string>;
+            timeout?: number;
+        }>;
+    };
+    /**
+     * Tool permission policy. See `extensibility/permissions`.
+     */
+    permissions?: {
+        mode?: 'default' | 'plan' | 'acceptEdits' | 'bypassPermissions';
+        rules?: Array<{
+            tool: string;
+            action: 'allow' | 'ask' | 'deny';
+            scope?: 'session' | 'project' | 'global';
+        }>;
+    };
 }
 interface LoadConfigOptions {
     cwd?: string;
@@ -68,6 +123,37 @@ interface LoadConfigOptions {
  */
 declare function loadConfig(options?: LoadConfigOptions): Promise<AgentsKitConfig | undefined>;
 
+type PermissionMode = 'default' | 'plan' | 'acceptEdits' | 'bypassPermissions';
+type PermissionAction = 'allow' | 'ask' | 'deny';
+interface PermissionRule {
+    /** Exact name, or a `RegExp` / `"re:pattern"` string matching the tool name. */
+    tool: string | RegExp;
+    action: PermissionAction;
+    scope?: 'session' | 'project' | 'global';
+}
+interface PermissionPolicy {
+    mode: PermissionMode;
+    rules: PermissionRule[];
+}
+declare const defaultPolicy: PermissionPolicy;
+/**
+ * Resolve an action for a tool name. Modes override specific rules:
+ *
+ *   - `bypassPermissions`: everything → allow
+ *   - `plan`:              everything → ask (pretend the agent is planning)
+ *   - `acceptEdits`:       fs_write / edit tools → allow, others unchanged
+ *   - `default`:           rules drive it; no matching rule → ask
+ */
+declare function evaluatePolicy(policy: PermissionPolicy, toolName: string): PermissionAction;
+/**
+ * Apply the policy to a tool definition. Returns the tool with
+ * `requiresConfirmation` set per the evaluated action, or `null` when the
+ * tool is denied (the caller should skip it entirely).
+ */
+declare function applyPolicyToTool(policy: PermissionPolicy, tool: ToolDefinition): ToolDefinition | null;
+/** Filter+annotate a tool list under a policy. Denied tools dropped. */
+declare function applyPolicyToTools(policy: PermissionPolicy, tools: ToolDefinition[]): ToolDefinition[];
+
 type FeedbackKind = 'info' | 'warn' | 'error' | 'success';
 interface SlashCommandContext {
     chat: ChatReturn;
@@ -79,6 +165,7 @@ interface SlashCommandContext {
         baseUrl?: string;
         tools?: string;
         skill?: string;
+        sessionId?: string;
     };
     /** Mutators — each rebuilds the underlying adapter/tool chain. */
     setProvider: (value: string) => void;
@@ -100,6 +187,106 @@ interface SlashCommand {
     run: (ctx: SlashCommandContext, argsText: string) => void | Promise<void>;
 }
 
+/**
+ * Public plugin contract. Every capability shipped by the CLI is a record
+ * that a plugin can contribute or override — built-ins use the same shape.
+ */
+interface Plugin {
+    name: string;
+    version?: string;
+    slashCommands?: SlashCommand[];
+    tools?: ToolDefinition[];
+    skills?: SkillDefinition[];
+    providers?: Record<string, ProviderFactory>;
+    hooks?: HookHandler[];
+    mcpServers?: McpServerSpec[];
+    init?: (ctx: PluginContext) => void | Promise<void>;
+    dispose?: () => void | Promise<void>;
+}
+interface PluginContext {
+    /** Working directory the CLI was launched from. */
+    cwd: string;
+    /** Absolute path to the plugin file (for relative resolution). */
+    sourcePath?: string;
+    /** Logger. */
+    log: (msg: string) => void;
+}
+type ProviderFactory = (config: {
+    apiKey?: string;
+    model: string;
+    baseUrl?: string;
+    extra?: Record<string, unknown>;
+}) => unknown;
+type HookEvent = 'SessionStart' | 'SessionEnd' | 'UserPromptSubmit' | 'PreLLM' | 'PostLLM' | 'PreToolUse' | 'PostToolUse' | 'Stop' | 'Error';
+interface HookPayload {
+    event: HookEvent;
+    [key: string]: unknown;
+}
+type HookResult = {
+    decision: 'continue';
+} | {
+    decision: 'block';
+    reason: string;
+} | {
+    decision: 'modify';
+    payload: HookPayload;
+};
+interface HookHandler {
+    event: HookEvent;
+    matcher?: RegExp | ((payload: HookPayload) => boolean);
+    run: (payload: HookPayload) => HookResult | Promise<HookResult>;
+}
+interface McpServerSpec {
+    name: string;
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    timeout?: number;
+}
+/** Plugin factory — a plugin module may export this instead of a Plugin value. */
+type PluginFactory = (ctx: PluginContext) => Plugin | Promise<Plugin>;
+/** Shape of aggregated plugin records after loading. */
+interface PluginBundle {
+    plugins: Plugin[];
+    slashCommands: SlashCommand[];
+    tools: ToolDefinition[];
+    skills: SkillDefinition[];
+    providers: Record<string, ProviderFactory>;
+    hooks: HookHandler[];
+    mcpServers: McpServerSpec[];
+}
+
+interface LoadPluginsOptions {
+    /** Plugin specifiers: absolute paths, relative paths, or package names. */
+    specs?: string[];
+    /** Extra directories to auto-discover plugin modules from. */
+    pluginDirs?: string[];
+    /** Working directory; defaults to process.cwd(). */
+    cwd?: string;
+    /**
+     * Auto-discover from `~/.agentskit/plugins`. Defaults to true. Tests pass
+     * false so the user's real home dir can't contaminate runs.
+     */
+    autoDiscoverUserDir?: boolean;
+    /** Error logger. Defaults to stderr. */
+    onError?: (spec: string, err: unknown) => void;
+    /** Info logger. */
+    log?: (msg: string) => void;
+}
+/**
+ * Load every plugin listed in `specs` + any auto-discovered module in
+ * `pluginDirs` (and `~/.agentskit/plugins` by default). Failures on a single
+ * plugin are reported but do not abort the rest — a broken third-party
+ * plugin should never prevent the CLI from starting.
+ */
+declare function loadPlugins(options?: LoadPluginsOptions): Promise<PluginBundle>;
+/**
+ * Merge every plugin's records into a single bundle. Later plugins override
+ * earlier ones by name (last-write-wins) — users override built-ins without
+ * forking.
+ */
+declare function mergePluginsIntoBundle(plugins: Plugin[]): PluginBundle;
+
 interface ChatCommandOptions {
     provider: string;
     model?: string;
@@ -118,6 +305,14 @@ interface ChatCommandOptions {
      * built-in by re-registering its name.
      */
     slashCommands?: SlashCommand[];
+    /** Extra tools contributed by plugins — merged into the resolved tool set. */
+    extraTools?: ToolDefinition[];
+    /** Extra skills contributed by plugins — merged into the resolved skill set. */
+    extraSkills?: SkillDefinition[];
+    /** Hook handlers — from plugins + config. Fire on lifecycle events. */
+    hookHandlers?: HookHandler[];
+    /** Permission policy for tool calls. */
+    permissionPolicy?: PermissionPolicy;
 }
 declare function ChatApp(options: ChatCommandOptions): react_jsx_runtime.JSX.Element;
 declare function renderChatHeader(options: ChatCommandOptions): string;
@@ -286,4 +481,227 @@ interface TunnelController {
  */
 declare function startTunnel(options: TunnelOptions): Promise<TunnelController>;
 
-export { type AgentsKitConfig, ChatApp, type ChatCommandOptions, type ChatProviderOptions, type CheckResult, type CheckStatus, type DevController, type DevOptions, type DevWatcher, type DoctorOptions, type DoctorReport, type InitCommandOptions, type LoadConfigOptions, type ResolvedChatProvider, type RunCommandOptions, type StarterKind, type TunnelController, type TunnelLike, type TunnelOptions, createCli, loadConfig, renderChatHeader, renderReport, resolveChatProvider, runAgent, runDoctor, startDev, startTunnel, writeStarterProject };
+interface SessionMetadata {
+    id: string;
+    cwd: string;
+    createdAt: string;
+    updatedAt: string;
+    messageCount: number;
+    preview: string;
+    provider?: string;
+    model?: string;
+    /** Optional human-readable label. Set via `/rename` or `renameSession`. */
+    label?: string;
+    /** Session id this one was forked from, if any. */
+    forkedFrom?: string;
+}
+interface SessionRecord {
+    metadata: SessionMetadata;
+    file: string;
+}
+/** Generate a new session id — ISO-ish timestamp + 6 random hex chars. */
+declare function generateSessionId(): string;
+declare function sessionFilePath(id: string, cwd?: string): string;
+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;
+declare function listSessions(cwd?: string): SessionRecord[];
+declare function findLatestSession(cwd?: string): SessionRecord | null;
+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;
+/**
+ * Copy an existing session's message file into a new session so the user
+ * can branch a conversation without disturbing the original.
+ */
+declare function forkSession(id: string, cwd?: string): ResolvedSession;
+interface ResolveSessionInput {
+    explicitPath?: string;
+    resumeId?: string | true;
+    forceNew?: boolean;
+    cwd?: string;
+}
+interface ResolvedSession {
+    id: string;
+    file: string;
+    isNew: boolean;
+}
+/**
+ * Decide which session file to read/write:
+ * - `explicitPath` wins if given (legacy `--memory-path` flag).
+ * - `forceNew` creates a fresh session.
+ * - `resumeId === true` → latest in cwd.
+ * - `resumeId` string → that id (or prefix).
+ * - Otherwise: resume latest if one exists, else create new. Matches
+ *   Claude Code's "pick up where you left off" default.
+ */
+declare function resolveSession(input: ResolveSessionInput): ResolvedSession;
+
+interface McpTool {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+}
+/**
+ * Minimal JSON-RPC-over-stdio client for an MCP server. This is a
+ * pragmatic subset of the MCP protocol sufficient for `tools/list` +
+ * `tools/call` — full spec support lives in `@modelcontextprotocol/sdk`
+ * if/when we depend on it.
+ *
+ * Transport: newline-delimited JSON (per the MCP stdio transport spec).
+ */
+declare class McpClient {
+    readonly spec: McpServerSpec;
+    private readonly onError;
+    private child;
+    private buffer;
+    private nextId;
+    private readonly pending;
+    private disposed;
+    constructor(spec: McpServerSpec, onError?: (err: unknown) => void);
+    start(): Promise<void>;
+    listTools(): Promise<McpTool[]>;
+    callTool(name: string, args: unknown): Promise<unknown>;
+    dispose(): void;
+    private request;
+    private onStdout;
+}
+
+interface McpBridgeResult {
+    clients: McpClient[];
+    tools: ToolDefinition[];
+}
+/**
+ * Start every MCP server in `specs`, call `tools/list`, and produce a
+ * `ToolDefinition[]` whose `execute` forwards to the server via
+ * `tools/call`. Returns the live clients so the caller can dispose them
+ * on session end.
+ */
+declare function bridgeMcpServers(specs: McpServerSpec[]): Promise<McpBridgeResult>;
+declare function disposeMcpClients(clients: McpClient[]): void;
+
+/**
+ * Per-million-token prices in USD. Keeps only a few canonical models —
+ * hosts can override at runtime via `registerPricing`. Values are
+ * publicly listed prices as of 2026-Q1 and may drift; authoritative
+ * cost tracking should come from the provider's invoice.
+ */
+interface ModelPricing {
+    inputPerM: number;
+    outputPerM: number;
+}
+declare function registerPricing(model: string, pricing: ModelPricing): void;
+declare function getPricing(model: string | undefined): ModelPricing | undefined;
+interface TokenUsageLike {
+    promptTokens: number;
+    completionTokens: number;
+}
+interface ComputedCost {
+    model: string;
+    inputUsd: number;
+    outputUsd: number;
+    totalUsd: number;
+}
+/** Returns computed cost, or `undefined` if no pricing is registered for the model. */
+declare function computeCost(model: string | undefined, usage: TokenUsageLike): ComputedCost | undefined;
+
+interface OpenAiEmbedderConfig {
+    apiKey: string;
+    model?: string;
+    baseUrl?: string;
+}
+/**
+ * Minimal OpenAI-compatible embedder. Works with the official OpenAI API
+ * or any gateway that speaks the `/v1/embeddings` shape (OpenRouter,
+ * Azure OpenAI, local servers, etc.). One embedding per call — batching
+ * is a follow-up when demand arrives.
+ */
+declare function createOpenAiEmbedder(config: OpenAiEmbedderConfig): EmbedFn;
+
+interface RagConfig {
+    enabled?: boolean;
+    backend?: 'memory' | 'file';
+    dir?: string;
+    sources?: string[];
+    embedder?: {
+        provider?: string;
+        model?: string;
+        apiKey?: string;
+        baseUrl?: string;
+    };
+    chunkSize?: number;
+    topK?: number;
+}
+interface BuildRagOptions {
+    config: RagConfig;
+    cwd?: string;
+    /** Override the embedder resolution (useful for tests). */
+    embedder?: EmbedFn;
+}
+interface IndexResult {
+    /** Number of input documents ingested. */
+    documentCount: number;
+    /** Sources globbed + ingested (absolute paths). */
+    sources: string[];
+}
+/**
+ * Build a live `RAG` instance from a config. Wires the embedder + vector
+ * store but does not ingest anything — call `indexSources` for that.
+ */
+declare function buildRagFromConfig(options: BuildRagOptions): RAG;
+/**
+ * Glob `config.sources` from `cwd`, read each file, and ingest through the
+ * provided RAG. Returns a summary of what was indexed.
+ */
+declare function indexSources(rag: RAG, config: RagConfig, cwd?: string): Promise<IndexResult>;
+
+interface HookDispatchResult {
+    /** Final payload after any `modify` handlers. */
+    payload: HookPayload;
+    /** True when any handler returned `block`. */
+    blocked: boolean;
+    /** Block reason from the first blocking handler, if any. */
+    reason?: string;
+}
+/**
+ * Runs every handler registered for an event in order. Handlers can:
+ *   - `continue`: do nothing, pass payload through
+ *   - `modify`:   replace the payload for subsequent handlers
+ *   - `block`:    stop dispatch and surface a reason to the caller
+ *
+ * Handlers that throw are reported via `onError` and treated as `continue`.
+ */
+declare class HookDispatcher {
+    private readonly onError;
+    private readonly handlers;
+    constructor(handlers?: HookHandler[], onError?: (handler: HookHandler, err: unknown) => void);
+    register(handler: HookHandler): void;
+    dispatch(event: HookEvent, payload: HookPayload): Promise<HookDispatchResult>;
+    private matches;
+}
+
+interface ConfigHookEntry {
+    /** Command to run. Executed through `sh -c`, so shell syntax is allowed. */
+    run: string;
+    /** Optional regex string the hook's subject must match to fire. */
+    matcher?: string;
+    /** Millisecond budget. Default 5000. */
+    timeout?: number;
+}
+type ConfigHooksMap = Partial<Record<HookEvent, ConfigHookEntry[]>>;
+/**
+ * Normalize `config.hooks` (shell entries) into `HookHandler[]`. The shell
+ * command receives the JSON-serialized payload on stdin. It can print a
+ * single JSON object on stdout to `modify` the payload, or exit non-zero
+ * to `block`.
+ *
+ *   { "decision": "continue" }             — default, no output needed
+ *   { "decision": "block", "reason": "…" }  — also signalled by non-zero exit
+ *   { "decision": "modify", "payload": … }  — swaps the payload
+ */
+declare function configHooksToHandlers(config: ConfigHooksMap | undefined): HookHandler[];
+
+export { type AgentsKitConfig, type BuildRagOptions, ChatApp, type ChatCommandOptions, type ChatProviderOptions, type CheckResult, type CheckStatus, type ComputedCost, type ConfigHookEntry, type ConfigHooksMap, type DevController, type DevOptions, type DevWatcher, type DoctorOptions, type DoctorReport, type HookDispatchResult, HookDispatcher, type HookEvent, type HookHandler, type HookPayload, type HookResult, type IndexResult, type InitCommandOptions, type LoadConfigOptions, type LoadPluginsOptions, type McpBridgeResult, McpClient, type McpServerSpec, type McpTool, type ModelPricing, type OpenAiEmbedderConfig, type PermissionAction, type PermissionMode, type PermissionPolicy, type PermissionRule, type Plugin, type PluginBundle, type PluginContext, type PluginFactory, type ProviderFactory, type RagConfig, type ResolveSessionInput, type ResolvedChatProvider, type ResolvedSession, type RunCommandOptions, type SessionMetadata, type SessionRecord, type StarterKind, type TokenUsageLike, type TunnelController, type TunnelLike, type TunnelOptions, applyPolicyToTool, applyPolicyToTools, bridgeMcpServers, buildRagFromConfig, computeCost, configHooksToHandlers, createCli, createOpenAiEmbedder, defaultPolicy, derivePreview, disposeMcpClients, evaluatePolicy, findLatestSession, findSession, forkSession, generateSessionId, getPricing, indexSources, listSessions, loadConfig, loadPlugins, mergePluginsIntoBundle, registerPricing, renameSession, renderChatHeader, renderReport, resolveChatProvider, resolveSession, runAgent, runDoctor, sessionFilePath, startDev, startTunnel, writeSessionMeta, writeStarterProject };