bashkit 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,32 @@
+import type { LanguageModel } from "ai";
+export type ToolConfig = {
+    timeout?: number;
+    maxFileSize?: number;
+    maxOutputLength?: number;
+    allowedPaths?: string[];
+    blockedCommands?: string[];
+};
+export type WebSearchConfig = {
+    apiKey: string;
+};
+export type WebFetchConfig = {
+    apiKey: string;
+    model: LanguageModel;
+};
+export type AgentConfig = {
+    tools?: {
+        Bash?: ToolConfig;
+        Read?: ToolConfig;
+        Write?: ToolConfig;
+        Edit?: ToolConfig;
+        Glob?: ToolConfig;
+        Grep?: ToolConfig;
+    };
+    /** Include WebSearch tool with this config */
+    webSearch?: WebSearchConfig;
+    /** Include WebFetch tool with this config */
+    webFetch?: WebFetchConfig;
+    defaultTimeout?: number;
+    workingDirectory?: string;
+};
+export declare const DEFAULT_CONFIG: AgentConfig;

package/dist/utils/compact-conversation.d.ts

@@ -0,0 +1,85 @@
+import { type LanguageModel, type ModelMessage } from "ai";
+export interface CompactConversationConfig {
+    /** Model's context limit (e.g., 200000 for Claude) */
+    maxTokens: number;
+    /** Trigger compaction at this % of maxTokens (default: 0.85) */
+    compactionThreshold?: number;
+    /** Keep last N messages intact (default: 10) */
+    protectRecentMessages?: number;
+    /** Model to use for summarization (use a fast/cheap model like Haiku) */
+    summarizerModel: LanguageModel;
+    /** The original task/goal the agent is working on - helps preserve context */
+    taskContext?: string;
+}
+export interface CompactConversationState {
+    /** Accumulated summary from previous compactions */
+    conversationSummary: string;
+}
+export interface CompactConversationResult {
+    /** Messages to use (unchanged if under limit, compacted if over) */
+    messages: ModelMessage[];
+    /** Updated state to pass to next call */
+    state: CompactConversationState;
+    /** Whether compaction occurred this call */
+    didCompact: boolean;
+}
+/**
+ * Compacts a conversation when it exceeds the token limit.
+ *
+ * When the conversation hits the threshold, it:
+ * 1. Summarizes older messages using the summarizer model
+ * 2. Keeps recent messages intact
+ * 3. Returns a new conversation starting with the summary
+ *
+ * Use this alongside pruneMessagesByTokens:
+ * - pruneMessagesByTokens: Fast pruning, loses context
+ * - compactConversation: Preserves context via summarization
+ *
+ * @param messages - Current conversation messages
+ * @param config - Compaction configuration
+ * @param state - State from previous compaction (or empty for first call)
+ * @returns Compacted messages, updated state, and whether compaction occurred
+ *
+ * @example
+ * ```typescript
+ * import { compactConversation } from 'bashkit';
+ *
+ * let messages: CoreMessage[] = [];
+ * let compactState = { conversationSummary: '' };
+ *
+ * async function chat(userMessage: string) {
+ *   messages.push({ role: 'user', content: userMessage });
+ *
+ *   const result = await compactConversation(messages, {
+ *     maxTokens: 200_000,
+ *     summarizerModel: anthropic('claude-haiku-4')
+ *   }, compactState);
+ *
+ *   messages = result.messages;
+ *   compactState = result.state;
+ *
+ *   // Continue with streamText using result.messages...
+ * }
+ * ```
+ */
+export declare function compactConversation(messages: ModelMessage[], config: CompactConversationConfig, state?: CompactConversationState): Promise<CompactConversationResult>;
+/**
+ * Pre-configured token limits for common models.
+ * Use these with compactConversation config.
+ */
+export declare const MODEL_CONTEXT_LIMITS: {
+    readonly "claude-opus-4-5": 200000;
+    readonly "claude-sonnet-4-5": 200000;
+    readonly "claude-haiku-4": 200000;
+    readonly "gpt-4o": 128000;
+    readonly "gpt-4-turbo": 128000;
+    readonly "gpt-4": 8192;
+    readonly "gpt-3.5-turbo": 16385;
+    readonly "gemini-2.5-pro": 1000000;
+    readonly "gemini-2.5-flash": 1000000;
+};
+export type ModelContextLimit = keyof typeof MODEL_CONTEXT_LIMITS;
+/**
+ * Helper to create config with model preset
+ */
+export declare function createCompactConfig(modelId: ModelContextLimit, summarizerModel: LanguageModel, overrides?: Partial<Omit<CompactConversationConfig, "summarizerModel">>): CompactConversationConfig;

package/dist/utils/context-status.d.ts

@@ -0,0 +1,71 @@
+import type { ModelMessage } from "ai";
+export type ContextStatusLevel = "comfortable" | "elevated" | "high" | "critical";
+export interface ContextStatus {
+    /** Estimated tokens used by current messages */
+    usedTokens: number;
+    /** Maximum tokens for the model */
+    maxTokens: number;
+    /** Usage as a decimal (0-1) */
+    usagePercent: number;
+    /** Usage level category */
+    status: ContextStatusLevel;
+    /** Optional guidance message to inject into the conversation */
+    guidance?: string;
+}
+/** Base context metrics passed to custom guidance functions */
+export interface ContextMetrics {
+    usedTokens: number;
+    maxTokens: number;
+    usagePercent: number;
+}
+export interface ContextStatusConfig {
+    /** Threshold for 'elevated' status (default: 0.5) */
+    elevatedThreshold?: number;
+    /** Threshold for 'high' status (default: 0.7) */
+    highThreshold?: number;
+    /** Threshold for 'critical' status (default: 0.85) */
+    criticalThreshold?: number;
+    /** Custom guidance message for 'high' status */
+    highGuidance?: string | ((metrics: ContextMetrics) => string);
+    /** Custom guidance message for 'critical' status */
+    criticalGuidance?: string | ((metrics: ContextMetrics) => string);
+}
+/**
+ * Get the current context window status for a conversation.
+ *
+ * Use this to monitor context usage and optionally inject guidance
+ * to prevent agents from rushing when context is filling up.
+ *
+ * @param messages - Current conversation messages
+ * @param maxTokens - Maximum tokens for the model (use MODEL_CONTEXT_LIMITS)
+ * @param config - Optional thresholds and custom guidance
+ * @returns Context status with usage info and optional guidance message
+ *
+ * @example
+ * ```typescript
+ * import { getContextStatus, MODEL_CONTEXT_LIMITS } from '@jbreite/bashkit';
+ *
+ * const status = getContextStatus(messages, MODEL_CONTEXT_LIMITS['claude-sonnet-4-5']);
+ *
+ * if (status.guidance) {
+ *   // Inject into system prompt or conversation
+ *   system = `${system}\n\n<context_status>${status.guidance}</context_status>`;
+ * }
+ *
+ * if (status.status === 'critical') {
+ *   // Trigger compaction
+ *   const compacted = await compactConversation(messages, config, state);
+ * }
+ * ```
+ */
+export declare function getContextStatus(messages: ModelMessage[], maxTokens: number, config?: ContextStatusConfig): ContextStatus;
+/**
+ * Check if context status requires action (high or critical).
+ * Convenience helper for conditional logic.
+ */
+export declare function contextNeedsAttention(status: ContextStatus): boolean;
+/**
+ * Check if context should be compacted (critical status).
+ * Convenience helper for triggering compaction.
+ */
+export declare function contextNeedsCompaction(status: ContextStatus): boolean;

package/dist/utils/index.d.ts

@@ -0,0 +1,3 @@
+export { type CompactConversationConfig, type CompactConversationResult, type CompactConversationState, compactConversation, createCompactConfig, MODEL_CONTEXT_LIMITS, type ModelContextLimit, } from "./compact-conversation";
+export { type ContextMetrics, type ContextStatus, type ContextStatusConfig, type ContextStatusLevel, contextNeedsAttention, contextNeedsCompaction, getContextStatus, } from "./context-status";
+export { estimateMessagesTokens, estimateMessageTokens, estimateTokens, type PruneMessagesConfig, pruneMessagesByTokens, } from "./prune-messages";

package/dist/utils/prune-messages.d.ts

@@ -0,0 +1,32 @@
+import type { ModelMessage } from "ai";
+export interface PruneMessagesConfig {
+    /** Keep approximately this many tokens (default: 40000) */
+    targetTokens?: number;
+    /** Only prune if we'd save more than this many tokens (default: 20000) */
+    minSavingsThreshold?: number;
+    /** Always keep the last N user messages and their responses (default: 3) */
+    protectLastNUserMessages?: number;
+}
+/**
+ * Estimate token count for a string (~4 chars per token for English)
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Estimate token count for a single message
+ */
+export declare function estimateMessageTokens(message: ModelMessage): number;
+/**
+ * Estimate total token count for an array of messages
+ */
+export declare function estimateMessagesTokens(messages: ModelMessage[]): number;
+/**
+ * Prune messages to fit within target token budget.
+ *
+ * Strategy: Remove tool call details and tool results from older messages,
+ * keeping the conversation structure intact. Recent messages are protected.
+ *
+ * @param messages - Array of ModelMessage from the AI SDK
+ * @param config - Pruning configuration
+ * @returns Pruned messages array
+ */
+export declare function pruneMessagesByTokens(messages: ModelMessage[], config?: PruneMessagesConfig): ModelMessage[];

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "bashkit",
+  "version": "0.1.0",
+  "description": "Agentic coding tools for the Vercel AI SDK",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "bashkit": "./dist/cli/init.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "AGENTS.md"
+  ],
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "build": "bun run build:js && bun run build:cli && bun run build:types",
+    "build:js": "bun build src/index.ts --outdir dist --target node --format esm --external ai --external zod --external @ai-sdk/* --external @vercel/sandbox --external @e2b/code-interpreter --external parallel-web",
+    "build:cli": "bun build src/cli/init.ts --outdir dist/cli --target node --format esm --external @clack/prompts && chmod +x dist/cli/init.js",
+    "build:types": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
+    "lint": "biome lint --write .",
+    "lint:check": "biome lint .",
+    "check": "biome check --write .",
+    "check:ci": "biome check .",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "vercel",
+    "ai-sdk",
+    "sandbox",
+    "tools",
+    "bash",
+    "code-execution"
+  ],
+  "author": "jbreite",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jbreite/bashkit"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0"
+  },
+  "devDependencies": {
+    "@ai-sdk/anthropic": "^2.0.50",
+    "@biomejs/biome": "^2.3.9",
+    "@e2b/code-interpreter": "^1.5.1",
+    "@types/bun": "latest",
+    "@types/node": "^24.10.0",
+    "@vercel/sandbox": "^1.0.4",
+    "parallel-web": "^0.2.4",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "ai": "^5.0.0",
+    "zod": "^4.1.8",
+    "@vercel/sandbox": "^1.0.0",
+    "@e2b/code-interpreter": "^1.0.0",
+    "parallel-web": "^0.2.4"
+  },
+  "peerDependenciesMeta": {
+    "@vercel/sandbox": {
+      "optional": true
+    },
+    "@e2b/code-interpreter": {
+      "optional": true
+    },
+    "parallel-web": {
+      "optional": true
+    }
+  }
+}