bashkit 0.1.0

package/dist/middleware/anthropic-cache.d.ts

@@ -0,0 +1,17 @@
+import type { LanguageModelV2Middleware } from "@ai-sdk/provider";
+/**
+ * Middleware that enables Anthropic's prompt caching feature.
+ *
+ * @example
+ * ```typescript
+ * import { wrapLanguageModel } from 'ai';
+ * import { anthropic } from '@ai-sdk/anthropic';
+ * import { anthropicPromptCacheMiddleware } from 'bashkit';
+ *
+ * const model = wrapLanguageModel({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   middleware: anthropicPromptCacheMiddleware,
+ * });
+ * ```
+ */
+export declare const anthropicPromptCacheMiddleware: LanguageModelV2Middleware;

package/dist/middleware/index.d.ts

@@ -0,0 +1 @@
+export { anthropicPromptCacheMiddleware } from "./anthropic-cache";

package/dist/sandbox/e2b.d.ts

@@ -0,0 +1,9 @@
+import type { Sandbox } from "./interface";
+export interface E2BSandboxConfig {
+    apiKey?: string;
+    template?: string;
+    timeout?: number;
+    cwd?: string;
+    metadata?: Record<string, string>;
+}
+export declare function createE2BSandbox(config?: E2BSandboxConfig): Sandbox;

package/dist/sandbox/index.d.ts

@@ -0,0 +1,4 @@
+export { createE2BSandbox, type E2BSandboxConfig } from "./e2b";
+export type { ExecOptions, ExecResult, Sandbox } from "./interface";
+export { createLocalSandbox, type LocalSandboxConfig } from "./local";
+export { createVercelSandbox, type VercelSandboxConfig } from "./vercel";

package/dist/sandbox/interface.d.ts

@@ -0,0 +1,21 @@
+export interface ExecOptions {
+    timeout?: number;
+    cwd?: string;
+    restart?: boolean;
+}
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    durationMs: number;
+    interrupted: boolean;
+}
+export interface Sandbox {
+    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    readDir(path: string): Promise<string[]>;
+    fileExists(path: string): Promise<boolean>;
+    isDirectory(path: string): Promise<boolean>;
+    destroy(): Promise<void>;
+}

package/dist/sandbox/local.d.ts

@@ -0,0 +1,5 @@
+import type { Sandbox } from "./interface";
+export interface LocalSandboxConfig {
+    cwd?: string;
+}
+export declare function createLocalSandbox(config?: LocalSandboxConfig): Sandbox;

package/dist/sandbox/vercel.d.ts

@@ -0,0 +1,13 @@
+import type { Sandbox } from "./interface";
+export interface VercelSandboxConfig {
+    runtime?: "node22" | "python3.13";
+    resources?: {
+        vcpus: number;
+    };
+    timeout?: number;
+    cwd?: string;
+    teamId?: string;
+    projectId?: string;
+    token?: string;
+}
+export declare function createVercelSandbox(config?: VercelSandboxConfig): Sandbox;

package/dist/setup/index.d.ts

@@ -0,0 +1,2 @@
+export type { AgentEnvironmentConfig, SetupResult, SkillContent, } from "./types";
+export { setupAgentEnvironment } from "./setup-environment";

package/dist/setup/setup-environment.d.ts

@@ -0,0 +1,36 @@
+import type { Sandbox } from "../sandbox/interface";
+import type { AgentEnvironmentConfig, SetupResult } from "./types";
+/**
+ * Sets up an agent environment in a sandbox.
+ *
+ * Creates workspace directories and seeds skills into the sandbox filesystem.
+ * Returns parsed skill metadata for use with skillsToXml().
+ *
+ * @param sandbox - The sandbox to set up
+ * @param config - Environment configuration
+ * @returns Setup result with skills metadata
+ *
+ * @example
+ * ```typescript
+ * const pdfSkill = await fetchSkill('anthropics/skills/pdf');
+ *
+ * const config = {
+ *   workspace: {
+ *     notes: 'files/notes/',
+ *     outputs: 'files/outputs/',
+ *   },
+ *   skills: {
+ *     'pdf': pdfSkill,  // SkillBundle with all files
+ *     'my-custom': mySkillContent,  // inline string
+ *   },
+ * };
+ *
+ * const { skills } = await setupAgentEnvironment(sandbox, config);
+ *
+ * const systemPrompt = `You are an assistant.
+ * Save notes to: ${config.workspace.notes}
+ * ${skillsToXml(skills)}
+ * `;
+ * ```
+ */
+export declare function setupAgentEnvironment(sandbox: Sandbox, config: AgentEnvironmentConfig): Promise<SetupResult>;

package/dist/setup/types.d.ts

@@ -0,0 +1,47 @@
+import type { SkillMetadata } from "../skills";
+import type { SkillBundle } from "../skills/fetch";
+/**
+ * A skill can be either:
+ * - A string (just SKILL.md content for inline skills)
+ * - A SkillBundle (complete folder with all files, from fetchSkill)
+ */
+export type SkillContent = string | SkillBundle;
+/**
+ * Configuration for setting up an agent environment in a sandbox.
+ */
+export interface AgentEnvironmentConfig {
+    /**
+     * Workspace directories to create in the sandbox.
+     * Keys are logical names, values are paths.
+     *
+     * @example
+     * workspace: {
+     *   notes: 'files/notes/',
+     *   outputs: 'files/outputs/',
+     * }
+     */
+    workspace?: Record<string, string>;
+    /**
+     * Skills to seed into the sandbox.
+     * Keys are skill names (folder names).
+     * Values can be:
+     * - A string: just the SKILL.md content (for inline skills)
+     * - A SkillBundle: complete folder from fetchSkill() (for remote skills)
+     *
+     * @example
+     * skills: {
+     *   'web-research': webResearchSkillContent,  // inline string
+     *   'pdf': await fetchSkill('anthropics/skills/pdf'),  // SkillBundle
+     * }
+     */
+    skills?: Record<string, SkillContent>;
+}
+/**
+ * Result from setting up an agent environment.
+ */
+export interface SetupResult {
+    /**
+     * Parsed skill metadata for use with skillsToXml().
+     */
+    skills: SkillMetadata[];
+}

package/dist/skills/discovery.d.ts

@@ -0,0 +1,9 @@
+import type { DiscoverSkillsOptions, SkillMetadata } from "./types";
+/**
+ * Discovers skills from configured directories.
+ * Parses only frontmatter metadata for progressive disclosure.
+ *
+ * @param options - Discovery options
+ * @returns Array of skill metadata (empty if no skills found)
+ */
+export declare function discoverSkills(options?: DiscoverSkillsOptions): Promise<SkillMetadata[]>;

package/dist/skills/fetch.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Fetches skills from GitHub repositories.
+ *
+ * Reference format: `owner/repo/skillName`
+ * Example: `anthropics/skills/pdf` fetches the entire skill folder from
+ * https://github.com/anthropics/skills/tree/main/skills/pdf
+ */
+/**
+ * A complete skill bundle with all files from the skill folder.
+ */
+export interface SkillBundle {
+    /** The skill name (folder name) */
+    name: string;
+    /** All files in the skill folder. Keys are relative paths, values are file contents. */
+    files: Record<string, string>;
+}
+/**
+ * Fetches a complete skill folder from GitHub.
+ *
+ * @param ref - GitHub reference in format `owner/repo/skillName`
+ *              Example: `anthropics/skills/pdf`
+ * @returns A SkillBundle containing all files in the skill folder
+ * @throws Error if the skill cannot be fetched
+ *
+ * @example
+ * ```typescript
+ * const pdfSkill = await fetchSkill('anthropics/skills/pdf');
+ * // Returns:
+ * // {
+ * //   name: 'pdf',
+ * //   files: {
+ * //     'SKILL.md': '---\nname: pdf\n...',
+ * //     'scripts/extract.py': '...',
+ * //     'reference.md': '...',
+ * //   }
+ * // }
+ * ```
+ */
+export declare function fetchSkill(ref: string): Promise<SkillBundle>;
+/**
+ * Fetches multiple skill folders from GitHub in parallel.
+ *
+ * @param refs - Array of GitHub references in format `owner/repo/skillName`
+ * @returns Object mapping skill names to their SkillBundle
+ * @throws Error if any skill fails to fetch
+ *
+ * @example
+ * ```typescript
+ * const skills = await fetchSkills([
+ *   'anthropics/skills/pdf',
+ *   'anthropics/skills/web-research',
+ * ]);
+ * // Returns: { 'pdf': SkillBundle, 'web-research': SkillBundle }
+ * ```
+ */
+export declare function fetchSkills(refs: string[]): Promise<Record<string, SkillBundle>>;

package/dist/skills/index.d.ts

@@ -0,0 +1,6 @@
+export type { DiscoverSkillsOptions, SkillMetadata } from "./types";
+export type { SkillBundle } from "./fetch";
+export { discoverSkills } from "./discovery";
+export { fetchSkill, fetchSkills } from "./fetch";
+export { parseSkillMetadata } from "./loader";
+export { skillsToXml } from "./xml";

package/dist/skills/loader.d.ts

@@ -0,0 +1,11 @@
+import type { SkillMetadata } from "./types";
+/**
+ * Parses YAML frontmatter from a SKILL.md file content.
+ * Only extracts metadata - ignores the markdown body for progressive disclosure.
+ *
+ * @param content - Raw content of SKILL.md file
+ * @param skillPath - Absolute path to the SKILL.md file
+ * @returns Parsed skill metadata
+ * @throws Error if required fields (name, description) are missing
+ */
+export declare function parseSkillMetadata(content: string, skillPath: string): SkillMetadata;

package/dist/skills/types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Lightweight skill metadata loaded at startup.
+ * Does NOT include instructions - agent reads full SKILL.md via Read tool when activating.
+ */
+export interface SkillMetadata {
+    /** Skill identifier: 1-64 chars, lowercase + hyphens, matches folder name */
+    name: string;
+    /** When to use this skill: 1-1024 chars */
+    description: string;
+    /** Absolute path to SKILL.md file (agent uses Read tool to get full content) */
+    path: string;
+    /** License name or reference to bundled license file */
+    license?: string;
+    /** Environment requirements (intended product, system packages, network access, etc.) */
+    compatibility?: string;
+    /** Arbitrary key-value mapping for additional metadata */
+    metadata?: Record<string, string>;
+    /** Space-delimited list of pre-approved tools (experimental) */
+    allowedTools?: string[];
+}
+/**
+ * Options for discovering skills from the filesystem.
+ */
+export interface DiscoverSkillsOptions {
+    /** Override default discovery paths. Default: [".skills/", "~/.bashkit/skills/"] */
+    paths?: string[];
+    /** Working directory for resolving relative paths. Default: process.cwd() */
+    cwd?: string;
+}

package/dist/skills/xml.d.ts

@@ -0,0 +1,26 @@
+import type { SkillMetadata } from "./types";
+/**
+ * Generates XML representation of available skills for system prompts.
+ * This is the recommended format for Claude models per the Agent Skills spec.
+ *
+ * The output includes name, description, and location for each skill.
+ * Agents can use the location path with the Read tool to activate a skill.
+ *
+ * @param skills - Array of skill metadata
+ * @returns XML string to inject into system prompt
+ *
+ * @example
+ * ```typescript
+ * const skills = await discoverSkills();
+ * const xml = skillsToXml(skills);
+ * // Returns:
+ * // <available_skills>
+ * //   <skill>
+ * //     <name>pdf-processing</name>
+ * //     <description>Extract text from PDFs...</description>
+ * //     <location>/path/to/.skills/pdf-processing/SKILL.md</location>
+ * //   </skill>
+ * // </available_skills>
+ * ```
+ */
+export declare function skillsToXml(skills: SkillMetadata[]): string;

package/dist/tools/bash.d.ts

@@ -0,0 +1,18 @@
+import type { Sandbox } from "../sandbox/interface";
+import type { ToolConfig } from "../types";
+export interface BashOutput {
+    stdout: string;
+    stderr: string;
+    exit_code: number;
+    interrupted: boolean;
+    duration_ms: number;
+}
+export interface BashError {
+    error: string;
+}
+export declare function createBashTool(sandbox: Sandbox, config?: ToolConfig): import("ai").Tool<{
+    command: string;
+    timeout?: number | undefined;
+    description?: string | undefined;
+    run_in_background?: boolean | undefined;
+}, BashOutput | BashError>;

package/dist/tools/edit.d.ts

@@ -0,0 +1,16 @@
+import type { Sandbox } from "../sandbox/interface";
+import type { ToolConfig } from "../types";
+export interface EditOutput {
+    message: string;
+    file_path: string;
+    replacements: number;
+}
+export interface EditError {
+    error: string;
+}
+export declare function createEditTool(sandbox: Sandbox, config?: ToolConfig): import("ai").Tool<{
+    file_path: string;
+    old_string: string;
+    new_string: string;
+    replace_all?: boolean | undefined;
+}, EditOutput | EditError>;

package/dist/tools/exit-plan-mode.d.ts

@@ -0,0 +1,11 @@
+import type { ToolConfig } from "../types";
+export interface ExitPlanModeOutput {
+    message: string;
+    approved?: boolean;
+}
+export interface ExitPlanModeError {
+    error: string;
+}
+export declare function createExitPlanModeTool(config?: ToolConfig, onPlanSubmit?: (plan: string) => Promise<boolean> | boolean): import("ai").Tool<{
+    plan: string;
+}, ExitPlanModeOutput | ExitPlanModeError>;

package/dist/tools/glob.d.ts

@@ -0,0 +1,14 @@
+import type { Sandbox } from "../sandbox/interface";
+import type { ToolConfig } from "../types";
+export interface GlobOutput {
+    matches: string[];
+    count: number;
+    search_path: string;
+}
+export interface GlobError {
+    error: string;
+}
+export declare function createGlobTool(sandbox: Sandbox, config?: ToolConfig): import("ai").Tool<{
+    pattern: string;
+    path?: string | undefined;
+}, GlobOutput | GlobError>;

package/dist/tools/grep.d.ts

@@ -0,0 +1,42 @@
+import type { Sandbox } from "../sandbox/interface";
+import type { ToolConfig } from "../types";
+export interface GrepMatch {
+    file: string;
+    line_number?: number;
+    line: string;
+    before_context?: string[];
+    after_context?: string[];
+}
+export interface GrepContentOutput {
+    matches: GrepMatch[];
+    total_matches: number;
+}
+export interface GrepFilesOutput {
+    files: string[];
+    count: number;
+}
+export interface GrepCountOutput {
+    counts: Array<{
+        file: string;
+        count: number;
+    }>;
+    total: number;
+}
+export interface GrepError {
+    error: string;
+}
+export type GrepOutput = GrepContentOutput | GrepFilesOutput | GrepCountOutput | GrepError;
+export declare function createGrepTool(sandbox: Sandbox, config?: ToolConfig): import("ai").Tool<{
+    pattern: string;
+    path?: string | undefined;
+    glob?: string | undefined;
+    type?: string | undefined;
+    output_mode?: "content" | "count" | "files_with_matches" | undefined;
+    "-i"?: boolean | undefined;
+    "-n"?: boolean | undefined;
+    "-B"?: number | undefined;
+    "-A"?: number | undefined;
+    "-C"?: number | undefined;
+    head_limit?: number | undefined;
+    multiline?: boolean | undefined;
+}, GrepOutput>;

package/dist/tools/index.d.ts

@@ -0,0 +1,45 @@
+import type { ToolSet } from "ai";
+import type { Sandbox } from "../sandbox/interface";
+import type { AgentConfig } from "../types";
+/**
+ * Creates all sandbox-based agent tools for AI SDK's generateText/streamText.
+ * Returns an object with Bash, Read, Write, Edit, Glob, Grep tools.
+ * Optionally includes WebSearch and WebFetch if configured.
+ *
+ * @param sandbox - The sandbox to execute commands in
+ * @param config - Optional configuration for individual tools and web tools
+ *
+ * @example
+ * // Basic sandbox tools only
+ * const tools = createAgentTools(sandbox);
+ *
+ * @example
+ * // With web tools included
+ * const tools = createAgentTools(sandbox, {
+ *   webSearch: { apiKey: process.env.PARALLEL_API_KEY },
+ *   webFetch: { apiKey: process.env.PARALLEL_API_KEY, model: haiku },
+ * });
+ */
+export declare function createAgentTools(sandbox: Sandbox, config?: AgentConfig): ToolSet;
+export type { BashError, BashOutput } from "./bash";
+export { createBashTool } from "./bash";
+export type { EditError, EditOutput } from "./edit";
+export { createEditTool } from "./edit";
+export type { ExitPlanModeError, ExitPlanModeOutput } from "./exit-plan-mode";
+export { createExitPlanModeTool } from "./exit-plan-mode";
+export type { GlobError, GlobOutput } from "./glob";
+export { createGlobTool } from "./glob";
+export type { GrepContentOutput, GrepCountOutput, GrepError, GrepFilesOutput, GrepMatch, GrepOutput, } from "./grep";
+export { createGrepTool } from "./grep";
+export type { ReadDirectoryOutput, ReadError, ReadOutput, ReadTextOutput, } from "./read";
+export { createReadTool } from "./read";
+export type { SubagentStepEvent, SubagentTypeConfig, TaskError, TaskOutput, TaskToolConfig, } from "./task";
+export { createTaskTool } from "./task";
+export type { TodoItem, TodoState, TodoWriteError, TodoWriteOutput, } from "./todo-write";
+export { createTodoWriteTool } from "./todo-write";
+export type { WebFetchError, WebFetchOutput, WebFetchToolConfig, } from "./web-fetch";
+export { createWebFetchTool } from "./web-fetch";
+export type { WebSearchError, WebSearchOutput, WebSearchResult, WebSearchToolConfig, } from "./web-search";
+export { createWebSearchTool } from "./web-search";
+export type { WriteError, WriteOutput } from "./write";
+export { createWriteTool } from "./write";

package/dist/tools/read.d.ts

@@ -0,0 +1,25 @@
+import type { Sandbox } from "../sandbox/interface";
+import type { ToolConfig } from "../types";
+export interface ReadTextOutput {
+    type: "text";
+    content: string;
+    lines: Array<{
+        line_number: number;
+        content: string;
+    }>;
+    total_lines: number;
+}
+export interface ReadDirectoryOutput {
+    type: "directory";
+    entries: string[];
+    count: number;
+}
+export interface ReadError {
+    error: string;
+}
+export type ReadOutput = ReadTextOutput | ReadDirectoryOutput | ReadError;
+export declare function createReadTool(sandbox: Sandbox, config?: ToolConfig): import("ai").Tool<{
+    file_path: string;
+    offset?: number | undefined;
+    limit?: number | undefined;
+}, ReadOutput>;

package/dist/tools/task.d.ts

@@ -0,0 +1,50 @@
+import { type LanguageModel, type PrepareStepFunction, type StepResult, type StopCondition, type Tool, type ToolSet } from "ai";
+export interface TaskOutput {
+    result: string;
+    usage?: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+    total_cost_usd?: number;
+    duration_ms?: number;
+}
+export interface TaskError {
+    error: string;
+}
+/** Event emitted for each step a subagent takes */
+export interface SubagentStepEvent {
+    subagentType: string;
+    description: string;
+    step: StepResult<ToolSet>;
+}
+export interface SubagentTypeConfig {
+    /** Model to use for this subagent type */
+    model?: LanguageModel;
+    /** System prompt for this subagent type */
+    systemPrompt?: string;
+    /** Tool names this subagent can use (filters from parent tools) */
+    tools?: string[];
+    /** Stop condition for this subagent (default: stepCountIs(15)) */
+    stopWhen?: StopCondition<ToolSet>;
+    /** Prepare step callback for dynamic control per step */
+    prepareStep?: PrepareStepFunction<ToolSet>;
+    /** Callback for each step this subagent takes */
+    onStepFinish?: (step: StepResult<ToolSet>) => void | Promise<void>;
+}
+export interface TaskToolConfig {
+    /** Default model for subagents */
+    model: LanguageModel;
+    /** All available tools that subagents can use */
+    tools: ToolSet;
+    /** Configuration for each subagent type */
+    subagentTypes?: Record<string, SubagentTypeConfig>;
+    /** Cost per input token for usage tracking */
+    costPerInputToken?: number;
+    /** Cost per output token for usage tracking */
+    costPerOutputToken?: number;
+    /** Default stop condition for subagents (default: stepCountIs(15)) */
+    defaultStopWhen?: StopCondition<ToolSet>;
+    /** Default callback for each step any subagent takes */
+    defaultOnStepFinish?: (event: SubagentStepEvent) => void | Promise<void>;
+}
+export declare function createTaskTool(config: TaskToolConfig): Tool;

package/dist/tools/todo-write.d.ts

@@ -0,0 +1,28 @@
+import type { ToolConfig } from "../types";
+export interface TodoItem {
+    content: string;
+    status: "pending" | "in_progress" | "completed";
+    activeForm: string;
+}
+export interface TodoWriteOutput {
+    message: string;
+    stats: {
+        total: number;
+        pending: number;
+        in_progress: number;
+        completed: number;
+    };
+}
+export interface TodoWriteError {
+    error: string;
+}
+export interface TodoState {
+    todos: TodoItem[];
+}
+export declare function createTodoWriteTool(state: TodoState, config?: ToolConfig, onUpdate?: (todos: TodoItem[]) => void): import("ai").Tool<{
+    todos: {
+        content: string;
+        status: "pending" | "in_progress" | "completed";
+        activeForm: string;
+    }[];
+}, TodoWriteOutput | TodoWriteError>;

package/dist/tools/web-fetch.d.ts

@@ -0,0 +1,20 @@
+import type { LanguageModel } from "ai";
+export interface WebFetchOutput {
+    response: string;
+    url: string;
+    final_url?: string;
+    status_code?: number;
+}
+export interface WebFetchError {
+    error: string;
+    status_code?: number;
+    retryable?: boolean;
+}
+export interface WebFetchToolConfig {
+    apiKey: string;
+    model: LanguageModel;
+}
+export declare function createWebFetchTool(config: WebFetchToolConfig): import("ai").Tool<{
+    url: string;
+    prompt: string;
+}, WebFetchOutput | WebFetchError>;

package/dist/tools/web-search.d.ts

@@ -0,0 +1,24 @@
+export interface WebSearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+    metadata?: Record<string, unknown>;
+}
+export interface WebSearchOutput {
+    results: WebSearchResult[];
+    total_results: number;
+    query: string;
+}
+export interface WebSearchError {
+    error: string;
+    status_code?: number;
+    retryable?: boolean;
+}
+export interface WebSearchToolConfig {
+    apiKey: string;
+}
+export declare function createWebSearchTool(config: WebSearchToolConfig): import("ai").Tool<{
+    query: string;
+    allowed_domains?: string[] | undefined;
+    blocked_domains?: string[] | undefined;
+}, WebSearchOutput | WebSearchError>;

package/dist/tools/write.d.ts

@@ -0,0 +1,14 @@
+import type { Sandbox } from "../sandbox/interface";
+import type { ToolConfig } from "../types";
+export interface WriteOutput {
+    message: string;
+    bytes_written: number;
+    file_path: string;
+}
+export interface WriteError {
+    error: string;
+}
+export declare function createWriteTool(sandbox: Sandbox, config?: ToolConfig): import("ai").Tool<{
+    file_path: string;
+    content: string;
+}, WriteOutput | WriteError>;