bashkit 0.3.2 → 0.4.0

package/AGENTS.md

@@ -98,12 +98,14 @@ This is useful for:
 
 | Tool | Purpose | Key Inputs |
 |------|---------|------------|
-| `Bash` | Execute shell commands | `command`, `timeout?`, `description?` |
-| `Read` | Read files or list directories | `file_path`, `offset?`, `limit?` |
+| `Bash` | Execute shell commands | `command`, `timeout`, `description` |
+| `Read` | Read files or list directories | `file_path`, `offset`, `limit` |
 | `Write` | Create/overwrite files | `file_path`, `content` |
-| `Edit` | Replace strings in files | `file_path`, `old_string`, `new_string`, `replace_all?` |
-| `Glob` | Find files by pattern | `pattern`, `path?` |
-| `Grep` | Search file contents | `pattern`, `path?`, `output_mode?`, `-i?`, `-C?` |
+| `Edit` | Replace strings in files | `file_path`, `old_string`, `new_string`, `replace_all` |
+| `Glob` | Find files by pattern | `pattern`, `path` |
+| `Grep` | Search file contents | `pattern`, `path`, `output_mode`, `-i`, `-C` |
+
+> **Note on nullable types:** Optional parameters use `T | null` (not `T | undefined`) for OpenAI structured outputs compatibility. AI models should send explicit `null` for parameters they don't want to set. This works with both OpenAI and Anthropic models.
 
 ### Optional Tools (via config)
 

package/README.md

@@ -19,6 +19,32 @@ Agentic coding tools for Vercel AI SDK. Give AI agents the ability to execute co
 - Search the web and fetch URLs
 - Load skills on-demand via the [Agent Skills](https://agentskills.io) standard
 
+## Breaking Changes in v0.4.0
+
+### Nullable Types for OpenAI Compatibility
+
+All optional tool parameters now use `.nullable()` instead of `.optional()` in Zod schemas. This change enables compatibility with OpenAI's structured outputs, which require all properties to be in the `required` array.
+
+**What changed:**
+- Tool input types changed from `T | undefined` to `T | null`
+- Exported interfaces (`QuestionOption`, `StructuredQuestion`) use `T | null`
+- AI models will send explicit `null` values instead of omitting properties
+
+**Migration:**
+```typescript
+// Before v0.4.0
+const option: QuestionOption = { label: "test", description: undefined };
+
+// v0.4.0+
+const option: QuestionOption = { label: "test", description: null };
+```
+
+**Why this matters:**
+- Works with both OpenAI and Anthropic models
+- OpenAI structured outputs require nullable (not optional) fields
+- Anthropic/Claude handles nullable fields correctly
+- The `??` operator handles both `null` and `undefined`, so runtime behavior is unchanged
+
 ## Installation
 
 ```bash

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { anthropicPromptCacheMiddleware, anthropicPromptCacheMiddlewareV2, } fro
 export type { E2BSandboxConfig, LocalSandboxConfig, VercelSandboxConfig, } from "./sandbox";
 export { createE2BSandbox, createLocalSandbox, createVercelSandbox, ensureSandboxTools, } from "./sandbox";
 export type { ExecOptions, ExecResult, Sandbox } from "./sandbox/interface";
-export type { AgentToolsResult, AskUserError, AskUserOutput, AskUserResponseHandler, BashError, BashOutput, EditError, EditOutput, EnterPlanModeError, EnterPlanModeOutput, ExitPlanModeError, ExitPlanModeOutput, PlanModeState, GlobError, GlobOutput, GrepContentOutput, GrepCountOutput, GrepError, GrepFilesOutput, GrepMatch, GrepOutput, ReadDirectoryOutput, ReadError, ReadOutput, ReadTextOutput, SkillError, SkillOutput, SkillToolConfig, SubagentEventData, SubagentStepEvent, SubagentTypeConfig, TaskError, TaskOutput, TaskToolConfig, TodoItem, TodoState, TodoWriteError, TodoWriteOutput, WebFetchError, WebFetchOutput, WebSearchError, WebSearchOutput, WebSearchResult, WriteError, WriteOutput, } from "./tools";
+export type { AgentToolsResult, AskUserError, AskUserOutput, AskUserResponseHandler, QuestionOption, StructuredQuestion, BashError, BashOutput, EditError, EditOutput, EnterPlanModeError, EnterPlanModeOutput, ExitPlanModeError, ExitPlanModeOutput, PlanModeState, GlobError, GlobOutput, GrepContentOutput, GrepCountOutput, GrepError, GrepFilesOutput, GrepMatch, GrepOutput, ReadDirectoryOutput, ReadError, ReadOutput, ReadTextOutput, SkillError, SkillOutput, SkillToolConfig, SubagentEventData, SubagentStepEvent, SubagentTypeConfig, TaskError, TaskOutput, TaskToolConfig, TodoItem, TodoState, TodoWriteError, TodoWriteOutput, WebFetchError, WebFetchOutput, WebSearchError, WebSearchOutput, WebSearchResult, WriteError, WriteOutput, } from "./tools";
 export { createAgentTools, createAskUserTool, createBashTool, createEditTool, createEnterPlanModeTool, createExitPlanModeTool, createGlobTool, createGrepTool, createReadTool, createSkillTool, createTaskTool, createTodoWriteTool, createWebFetchTool, createWebSearchTool, createWriteTool, } from "./tools";
 export type { AgentConfig, AskUserConfig, CacheConfig, SkillConfig, ToolConfig, WebFetchConfig, WebSearchConfig, } from "./types";
 export { DEFAULT_CONFIG } from "./types";

package/dist/index.js

@@ -795,17 +795,17 @@ function reinitDebugMode() {
 // src/tools/ask-user.ts
 var questionOptionSchema = z.object({
   label: z.string().describe("The display text for this option. Should be concise (1-5 words). Add '(Recommended)' suffix for suggested options."),
-  description: z.string().optional().describe("Explanation of what this option means or its implications.")
+  description: z.string().nullable().default(null).describe("Explanation of what this option means or its implications.")
 });
 var structuredQuestionSchema = z.object({
-  header: z.string().optional().describe("Very short label displayed as a chip/tag (max 12 chars). Examples: 'Auth method', 'Library', 'Approach'."),
+  header: z.string().nullable().default(null).describe("Very short label displayed as a chip/tag (max 12 chars). Examples: 'Auth method', 'Library', 'Approach'."),
   question: z.string().describe("The complete question to ask the user. Should be clear and specific."),
-  options: z.array(questionOptionSchema).min(2).max(4).optional().describe("Available choices for this question. 2-4 options. An 'Other' option is automatically available to users."),
-  multiSelect: z.boolean().optional().describe("Set to true to allow the user to select multiple options instead of just one.")
+  options: z.array(questionOptionSchema).min(2).max(4).nullable().default(null).describe("Available choices for this question. 2-4 options. An 'Other' option is automatically available to users."),
+  multiSelect: z.boolean().nullable().default(null).describe("Set to true to allow the user to select multiple options instead of just one.")
 });
 var askUserInputSchema = z.object({
-  question: z.string().optional().describe("Simple question string (for backward compatibility). Use 'questions' for structured multi-choice."),
-  questions: z.array(structuredQuestionSchema).min(1).max(4).optional().describe("Structured questions with options (1-4 questions).")
+  question: z.string().nullable().default(null).describe("Simple question string (for backward compatibility). Use 'questions' for structured multi-choice."),
+  questions: z.array(structuredQuestionSchema).min(1).max(4).nullable().default(null).describe("Structured questions with options (1-4 questions).")
 });
 var ASK_USER_DESCRIPTION = `Use this tool when you need to ask the user questions during execution.
 
@@ -930,9 +930,9 @@ import { tool as tool2, zodSchema as zodSchema2 } from "ai";
 import { z as z2 } from "zod";
 var bashInputSchema = z2.object({
   command: z2.string().describe("The command to execute"),
-  timeout: z2.number().optional().describe("Optional timeout in milliseconds (max 600000)"),
-  description: z2.string().optional().describe("Clear, concise description of what this command does in 5-10 words"),
-  run_in_background: z2.boolean().optional().describe("Set to true to run this command in the background")
+  timeout: z2.number().nullable().default(null).describe("Optional timeout in milliseconds (max 600000)"),
+  description: z2.string().nullable().default(null).describe("Clear, concise description of what this command does in 5-10 words"),
+  run_in_background: z2.boolean().nullable().default(null).describe("Set to true to run this command in the background")
 });
 var BASH_DESCRIPTION = `Executes a bash command in a persistent shell session with optional timeout.
 
@@ -1049,7 +1049,7 @@ var editInputSchema = z3.object({
   file_path: z3.string().describe("The absolute path to the file to modify"),
   old_string: z3.string().describe("The text to replace"),
   new_string: z3.string().describe("The text to replace it with (must be different from old_string)"),
-  replace_all: z3.boolean().optional().describe("Replace all occurrences of old_string (default false)")
+  replace_all: z3.boolean().nullable().default(null).describe("Replace all occurrences of old_string (default false)")
 });
 var EDIT_DESCRIPTION = `Performs exact string replacements in files.
 
@@ -1079,8 +1079,9 @@ function createEditTool(sandbox, config) {
       file_path,
       old_string,
       new_string,
-      replace_all = false
+      replace_all: rawReplaceAll
     }) => {
+      const replace_all = rawReplaceAll ?? false;
       const startTime = performance.now();
       const debugId = isDebugEnabled() ? debugStart("edit", {
         file_path,
@@ -1330,7 +1331,7 @@ import { tool as tool6, zodSchema as zodSchema6 } from "ai";
 import { z as z6 } from "zod";
 var globInputSchema = z6.object({
   pattern: z6.string().describe('Glob pattern to match files (e.g., "**/*.ts", "src/**/*.js", "*.md")'),
-  path: z6.string().optional().describe("Directory to search in (defaults to working directory)")
+  path: z6.string().nullable().default(null).describe("Directory to search in (defaults to working directory)")
 });
 var GLOB_DESCRIPTION = `
 - Fast file pattern matching tool that works with any codebase size
@@ -1351,7 +1352,7 @@ function createGlobTool(sandbox, config) {
       pattern,
       path
     }) => {
-      const searchPath = path || ".";
+      const searchPath = path ?? ".";
       const startTime = performance.now();
       const debugId = isDebugEnabled() ? debugStart("glob", { pattern, path: searchPath }) : "";
       if (config?.allowedPaths) {
@@ -1403,18 +1404,18 @@ import { tool as tool7, zodSchema as zodSchema7 } from "ai";
 import { z as z7 } from "zod";
 var grepInputSchema = z7.object({
   pattern: z7.string().describe("The regular expression pattern to search for in file contents"),
-  path: z7.string().optional().describe("File or directory to search in (defaults to cwd)"),
-  glob: z7.string().optional().describe('Glob pattern to filter files (e.g. "*.js", "*.{ts,tsx}")'),
-  type: z7.string().optional().describe('File type to search (e.g. "js", "py", "rust")'),
-  output_mode: z7.enum(["content", "files_with_matches", "count"]).optional().describe('Output mode: "content" shows matching lines, "files_with_matches" shows file paths (default), "count" shows match counts'),
-  "-i": z7.boolean().optional().describe("Case insensitive search"),
-  "-n": z7.boolean().optional().describe("Show line numbers in output. Requires output_mode: 'content'. Defaults to true."),
-  "-B": z7.number().optional().describe("Number of lines to show before each match. Requires output_mode: 'content'."),
-  "-A": z7.number().optional().describe("Number of lines to show after each match. Requires output_mode: 'content'."),
-  "-C": z7.number().optional().describe("Number of lines to show before and after each match. Requires output_mode: 'content'."),
-  head_limit: z7.number().optional().describe("Limit output to first N lines/entries. Works across all output modes. Defaults to 0 (unlimited)."),
-  offset: z7.number().optional().describe("Skip first N lines/entries before applying head_limit. Works across all output modes. Defaults to 0."),
-  multiline: z7.boolean().optional().describe("Enable multiline mode where patterns can span lines. Default: false.")
+  path: z7.string().nullable().default(null).describe("File or directory to search in (defaults to cwd)"),
+  glob: z7.string().nullable().default(null).describe('Glob pattern to filter files (e.g. "*.js", "*.{ts,tsx}")'),
+  type: z7.string().nullable().default(null).describe('File type to search (e.g. "js", "py", "rust")'),
+  output_mode: z7.enum(["content", "files_with_matches", "count"]).nullable().default(null).describe('Output mode: "content" shows matching lines, "files_with_matches" shows file paths (default), "count" shows match counts'),
+  "-i": z7.boolean().nullable().default(null).describe("Case insensitive search"),
+  "-n": z7.boolean().nullable().default(null).describe("Show line numbers in output. Requires output_mode: 'content'. Defaults to true."),
+  "-B": z7.number().nullable().default(null).describe("Number of lines to show before each match. Requires output_mode: 'content'."),
+  "-A": z7.number().nullable().default(null).describe("Number of lines to show after each match. Requires output_mode: 'content'."),
+  "-C": z7.number().nullable().default(null).describe("Number of lines to show before and after each match. Requires output_mode: 'content'."),
+  head_limit: z7.number().nullable().default(null).describe("Limit output to first N lines/entries. Works across all output modes. Defaults to 0 (unlimited)."),
+  offset: z7.number().nullable().default(null).describe("Skip first N lines/entries before applying head_limit. Works across all output modes. Defaults to 0."),
+  multiline: z7.boolean().nullable().default(null).describe("Enable multiline mode where patterns can span lines. Default: false.")
 });
 var GREP_DESCRIPTION = `A powerful content search tool built on ripgrep with regex support.
 
@@ -1449,15 +1450,17 @@ function createGrepTool(sandbox, config) {
         path,
         glob,
         type,
-        output_mode = "files_with_matches",
+        output_mode: rawOutputMode,
         "-i": caseInsensitive,
         "-B": beforeContext,
         "-A": afterContext,
         "-C": context,
         head_limit,
-        offset = 0,
+        offset: rawOffset,
         multiline
       } = input;
+      const output_mode = rawOutputMode ?? "files_with_matches";
+      const offset = rawOffset ?? 0;
       const searchPath = path || ".";
       const startTime = performance.now();
       const debugId = isDebugEnabled() ? debugStart("grep", {
@@ -1607,7 +1610,7 @@ function parseCountOutput(stdout) {
     total
   };
 }
-function parseContentOutput(stdout, head_limit, offset = 0) {
+function parseContentOutput(stdout, head_limit, offset) {
   const fileData = new Map;
   for (const line of stdout.split(`
 `).filter(Boolean)) {
@@ -1704,8 +1707,8 @@ import { tool as tool8, zodSchema as zodSchema8 } from "ai";
 import { z as z8 } from "zod";
 var readInputSchema = z8.object({
   file_path: z8.string().describe("Absolute path to file or directory"),
-  offset: z8.number().optional().describe("Line number to start reading from (1-indexed)"),
-  limit: z8.number().optional().describe("Maximum number of lines to read")
+  offset: z8.number().nullable().default(null).describe("Line number to start reading from (1-indexed)"),
+  limit: z8.number().nullable().default(null).describe("Maximum number of lines to read")
 });
 var READ_DESCRIPTION = `Reads a file from the local filesystem. You can access any file directly by using this tool.
 Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
@@ -2118,8 +2121,8 @@ async function searchContent(apiKey, provider, options) {
 }
 var webSearchInputSchema = z11.object({
   query: z11.string().describe("The search query to use"),
-  allowed_domains: z11.array(z11.string()).optional().describe("Only include results from these domains"),
-  blocked_domains: z11.array(z11.string()).optional().describe("Never include results from these domains")
+  allowed_domains: z11.array(z11.string()).nullable().default(null).describe("Only include results from these domains"),
+  blocked_domains: z11.array(z11.string()).nullable().default(null).describe("Never include results from these domains")
 });
 var WEB_SEARCH_DESCRIPTION = `Searches the web and returns results with links. Use this for accessing up-to-date information beyond your knowledge cutoff.
 
@@ -2283,8 +2286,8 @@ var taskInputSchema = z13.object({
   description: z13.string().describe("A short (3-5 word) description of the task"),
   prompt: z13.string().describe("The task for the agent to perform"),
   subagent_type: z13.string().describe("The type of specialized agent to use for this task"),
-  system_prompt: z13.string().optional().describe("Optional custom system prompt for this agent. If provided, overrides the default system prompt for the subagent type. Use this to create dynamic, specialized agents on the fly."),
-  tools: z13.array(z13.string()).optional().describe("Optional list of tool names this agent can use (e.g., ['Read', 'Grep', 'WebSearch']). If provided, overrides the default tools for the subagent type. Use this to restrict or expand the agent's capabilities.")
+  system_prompt: z13.string().nullable().default(null).describe("Optional custom system prompt for this agent. If provided, overrides the default system prompt for the subagent type. Use this to create dynamic, specialized agents on the fly."),
+  tools: z13.array(z13.string()).nullable().default(null).describe("Optional list of tool names this agent can use (e.g., ['Read', 'Grep', 'WebSearch']). If provided, overrides the default tools for the subagent type. Use this to restrict or expand the agent's capabilities.")
 });
 var TASK_DESCRIPTION = `Launch a new agent to handle complex, multi-step tasks autonomously.
 

package/dist/tools/ask-user.d.ts

@@ -1,12 +1,12 @@
 export interface QuestionOption {
     label: string;
-    description?: string;
+    description: string | null;
 }
 export interface StructuredQuestion {
-    header?: string;
+    header: string | null;
     question: string;
-    options?: QuestionOption[];
-    multiSelect?: boolean;
+    options: QuestionOption[] | null;
+    multiSelect: boolean | null;
 }
 export interface AskUserSimpleOutput {
     question: string;
@@ -40,14 +40,14 @@ export interface AskUserToolConfig {
  * @param config - Configuration with optional handlers for questions
  */
 export declare function createAskUserTool(config?: AskUserToolConfig | AskUserResponseHandler): import("ai").Tool<{
-    question?: string | undefined;
-    questions?: {
+    question: string | null;
+    questions: {
+        header: string | null;
         question: string;
-        header?: string | undefined;
-        options?: {
+        options: {
             label: string;
-            description?: string | undefined;
-        }[] | undefined;
-        multiSelect?: boolean | undefined;
-    }[] | undefined;
+            description: string | null;
+        }[] | null;
+        multiSelect: boolean | null;
+    }[] | null;
 }, AskUserOutput | AskUserError | AskUserAnswerOutput>;

package/dist/tools/bash.d.ts

@@ -12,7 +12,7 @@ export interface BashError {
 }
 export declare function createBashTool(sandbox: Sandbox, config?: ToolConfig): import("ai").Tool<{
     command: string;
-    timeout?: number | undefined;
-    description?: string | undefined;
-    run_in_background?: boolean | undefined;
+    timeout: number | null;
+    description: string | null;
+    run_in_background: boolean | null;
 }, BashOutput | BashError>;

package/dist/tools/edit.d.ts

@@ -12,5 +12,5 @@ export declare function createEditTool(sandbox: Sandbox, config?: ToolConfig): i
     file_path: string;
     old_string: string;
     new_string: string;
-    replace_all?: boolean | undefined;
+    replace_all: boolean | null;
 }, EditOutput | EditError>;

package/dist/tools/glob.d.ts

@@ -10,5 +10,5 @@ export interface GlobError {
 }
 export declare function createGlobTool(sandbox: Sandbox, config?: ToolConfig): import("ai").Tool<{
     pattern: string;
-    path?: string | undefined;
+    path: string | null;
 }, GlobOutput | GlobError>;

package/dist/tools/grep.d.ts

@@ -28,16 +28,16 @@ export interface GrepError {
 export type GrepOutput = GrepContentOutput | GrepFilesOutput | GrepCountOutput | GrepError;
 export declare function createGrepTool(sandbox: Sandbox, config?: GrepToolConfig): 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;
-    offset?: number | undefined;
-    multiline?: boolean | undefined;
+    path: string | null;
+    glob: string | null;
+    type: string | null;
+    output_mode: "content" | "count" | "files_with_matches" | null;
+    "-i": boolean | null;
+    "-n": boolean | null;
+    "-B": number | null;
+    "-A": number | null;
+    "-C": number | null;
+    head_limit: number | null;
+    offset: number | null;
+    multiline: boolean | null;
 }, GrepOutput>;

package/dist/tools/index.d.ts

@@ -47,7 +47,7 @@ export interface AgentToolsResult {
  * });
  */
 export declare function createAgentTools(sandbox: Sandbox, config?: AgentConfig): AgentToolsResult;
-export type { AskUserError, AskUserOutput, AskUserResponseHandler, } from "./ask-user";
+export type { AskUserError, AskUserOutput, AskUserResponseHandler, QuestionOption, StructuredQuestion, } from "./ask-user";
 export { createAskUserTool } from "./ask-user";
 export type { BashError, BashOutput } from "./bash";
 export { createBashTool } from "./bash";

package/dist/tools/read.d.ts

@@ -20,6 +20,6 @@ export interface ReadError {
 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;
+    offset: number | null;
+    limit: number | null;
 }, ReadOutput>;

package/dist/tools/task.d.ts

@@ -17,8 +17,8 @@ declare const taskInputSchema: z.ZodObject<{
     description: z.ZodString;
     prompt: z.ZodString;
     subagent_type: z.ZodString;
-    system_prompt: z.ZodOptional<z.ZodString>;
-    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    system_prompt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    tools: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodString>>>;
 }, z.core.$strip>;
 type TaskInput = z.infer<typeof taskInputSchema>;
 /** Event emitted for each step a subagent takes */

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

@@ -17,6 +17,6 @@ export interface WebSearchError {
 }
 export declare function createWebSearchTool(config: WebSearchConfig): import("ai").Tool<{
     query: string;
-    allowed_domains?: string[] | undefined;
-    blocked_domains?: string[] | undefined;
+    allowed_domains: string[] | null;
+    blocked_domains: string[] | null;
 }, WebSearchOutput | WebSearchError>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bashkit",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Agentic coding tools for the Vercel AI SDK",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,6 +26,9 @@
     "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",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:coverage": "vitest run --coverage",
     "format": "biome format --write .",
     "format:check": "biome format .",
     "lint": "biome lint --write .",
@@ -61,9 +64,11 @@
     "@types/bun": "latest",
     "@types/node": "^24.10.0",
     "@vercel/sandbox": "^1.0.4",
+    "@vitest/coverage-v8": "^3.0.0",
     "ai": "^6.0.0",
     "parallel-web": "^0.2.4",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^3.0.0"
   },
   "peerDependencies": {
     "ai": ">=5.0.0",