Merge pull request #13 from jbreite/add-nullable-schemas-instead-optional

add: nullable schemas instead optional on zod

Author: jbreite

.gitignore

@@ -173,3 +173,6 @@ dist
 
 # Finder (MacOS) folder config
 .DS_Store
+
+#workflow review
+/todos

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)
 

CLAUDE.md

@@ -4,7 +4,7 @@
 
 **Tech Stack**: TypeScript • Bun • Vercel AI SDK • Zod
 **Inspired by**: Claude Code tools
-**Version**: 0.3.0
+**Version**: 0.4.0
 
 ---
 
@@ -148,12 +148,42 @@ Zod schemas define and validate all tool inputs:
 ```typescript
 const bashInputSchema = z.object({
   command: z.string(),
-  description: z.string(),
-  restart: z.boolean().optional()
+  description: z.string().nullable(),
+  timeout: z.number().nullable()
 });
 ```
 
-#### 6. Tool Result Caching
+#### 6. Nullable Types for AI Provider Compatibility
+
+All optional tool parameters use `.nullable()` instead of `.optional()` for OpenAI structured outputs compatibility.
+
+**Why `.nullable()` instead of `.optional()`:**
+- OpenAI structured outputs require all properties in the `required` array
+- `.optional()` removes properties from `required` (breaks OpenAI)
+- `.nullable()` keeps properties in `required` but allows `null` values
+- Works with both OpenAI and Anthropic models
+
+**Pattern for handling nullable values:**
+```typescript
+// Zod schema uses .nullable()
+const schema = z.object({
+  timeout: z.number().nullable(),
+  replace_all: z.boolean().nullable(),
+});
+
+// In execute function, use ?? for defaults
+// NOTE: Destructuring defaults (= value) only work with undefined, NOT null
+const { timeout, replace_all: rawReplaceAll } = input;
+const effectiveTimeout = timeout ?? 120000;
+const replaceAll = rawReplaceAll ?? false;
+```
+
+**Type conventions:**
+- Zod schemas: `.nullable()` → produces `T | null`
+- Exported interfaces: `T | null` (e.g., `description: string | null`)
+- Internal functions: `T | null` for parameters that accept nullable values
+
+#### 7. Tool Result Caching
 Optional caching for tool execution results:
 ```typescript
 // Enable with defaults (LRU, 5min TTL)
@@ -841,5 +871,5 @@ const { tools } = createAgentTools(sandbox, {
 
 ---
 
-*Last Updated*: 2026-01-02
+*Last Updated*: 2026-01-22
 *For*: Claude Code and AI coding assistants

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.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",

src/index.ts

@@ -41,6 +41,8 @@ export type {
   AskUserError,
   AskUserOutput,
   AskUserResponseHandler,
+  QuestionOption,
+  StructuredQuestion,
   // Sandbox tools
   BashError,
   BashOutput,

src/tools/ask-user.ts

@@ -10,15 +10,15 @@ import {
 // Option for structured questions
 export interface QuestionOption {
   label: string;
-  description?: string;
+  description: string | null;
 }
 
 // Structured question with options
 export interface StructuredQuestion {
-  header?: string; // Short label (max 12 chars), displayed as chip/tag
+  header: string | null; // Short label (max 12 chars), displayed as chip/tag
   question: string;
-  options?: QuestionOption[];
-  multiSelect?: boolean;
+  options: QuestionOption[] | null;
+  multiSelect: boolean | null;
 }
 
 // Simple question output (backward compatible)
@@ -54,15 +54,17 @@ const questionOptionSchema = z.object({
     ),
   description: z
     .string()
-    .optional()
+    .nullable()
+    .default(null)
     .describe("Explanation of what this option means or its implications."),
 });
 
 // Schema for structured question
 const structuredQuestionSchema = z.object({
   header: z
     .string()
-    .optional()
+    .nullable()
+    .default(null)
     .describe(
       "Very short label displayed as a chip/tag (max 12 chars). Examples: 'Auth method', 'Library', 'Approach'.",
     ),
@@ -75,13 +77,15 @@ const structuredQuestionSchema = z.object({
     .array(questionOptionSchema)
     .min(2)
     .max(4)
-    .optional()
+    .nullable()
+    .default(null)
     .describe(
       "Available choices for this question. 2-4 options. An 'Other' option is automatically available to users.",
     ),
   multiSelect: z
     .boolean()
-    .optional()
+    .nullable()
+    .default(null)
     .describe(
       "Set to true to allow the user to select multiple options instead of just one.",
     ),
@@ -91,15 +95,17 @@ const structuredQuestionSchema = z.object({
 const askUserInputSchema = z.object({
   question: z
     .string()
-    .optional()
+    .nullable()
+    .default(null)
     .describe(
       "Simple question string (for backward compatibility). Use 'questions' for structured multi-choice.",
     ),
   questions: z
     .array(structuredQuestionSchema)
     .min(1)
     .max(4)
-    .optional()
+    .nullable()
+    .default(null)
     .describe("Structured questions with options (1-4 questions)."),
 });
 

src/tools/bash.ts

@@ -25,17 +25,20 @@ const bashInputSchema = z.object({
   command: z.string().describe("The command to execute"),
   timeout: z
     .number()
-    .optional()
+    .nullable()
+    .default(null)
     .describe("Optional timeout in milliseconds (max 600000)"),
   description: z
     .string()
-    .optional()
+    .nullable()
+    .default(null)
     .describe(
       "Clear, concise description of what this command does in 5-10 words",
     ),
   run_in_background: z
     .boolean()
-    .optional()
+    .nullable()
+    .default(null)
     .describe("Set to true to run this command in the background"),
 });
 

src/tools/edit.ts

@@ -29,7 +29,8 @@ const editInputSchema = z.object({
     ),
   replace_all: z
     .boolean()
-    .optional()
+    .nullable()
+    .default(null)
     .describe("Replace all occurrences of old_string (default false)"),
 });
 
@@ -65,8 +66,9 @@ export function createEditTool(sandbox: Sandbox, config?: ToolConfig) {
       file_path,
       old_string,
       new_string,
-      replace_all = false,
+      replace_all: rawReplaceAll,
     }: EditInput): Promise<EditOutput | EditError> => {
+      const replace_all = rawReplaceAll ?? false;
       const startTime = performance.now();
       const debugId = isDebugEnabled()
         ? debugStart("edit", {

src/tools/glob.ts

@@ -27,7 +27,8 @@ const globInputSchema = z.object({
     ),
   path: z
     .string()
-    .optional()
+    .nullable()
+    .default(null)
     .describe("Directory to search in (defaults to working directory)"),
 });
 
@@ -54,7 +55,7 @@ export function createGlobTool(sandbox: Sandbox, config?: ToolConfig) {
       pattern,
       path,
     }: GlobInput): Promise<GlobOutput | GlobError> => {
-      const searchPath = path || ".";
+      const searchPath = path ?? ".";
       const startTime = performance.now();
       const debugId = isDebugEnabled()
         ? debugStart("glob", { pattern, path: searchPath })