Kuuzuki v0.1.16: Enhanced AI Resilience and NPM Package Fixes

# Kuuzuki v0.1.16: Enhanced AI Resilience and NPM Package Fixes

Published: August 1, 2025

We're excited to announce the release of Kuuzuki v0.1.16, which brings significant improvements to AI tool resilience, fixes critical npm package distribution issues, and achieves 95%+ parity with the original OpenCode project. This release represents a major step forward in making Kuuzuki a reliable, community-driven AI terminal assistant.

## 🎯 Key Highlights

- AI Tool Resilience: Fixed crashes when AI uses invalid parameters

- NPM Package Fix: Resolved "macros cannot be run from node_modules" error

- OpenCode Parity: Achieved 95%+ compatibility with original OpenCode

- Improved Stability: Fixed temporal dead zone and TypeScript compilation errors

## 🛠️ The TodoWrite Validation Error Fix

### The Problem

One of the most frustrating issues users encountered was the AI assistant crashing when trying to use the TodoWrite tool with a "critical" priority level. The error message was cryptic:

```

Error: Invalid enum value. Expected 'high' | 'medium' | 'low', received 'critical'

```

This would cause the entire AI session to crash, losing context and progress.

### Root Cause Analysis

The issue stemmed from a mismatch between what the AI naturally wanted to use (including "critical" priority for urgent tasks) and what our validation schema allowed. The TodoWrite tool used strict Zod schema validation that only accepted three priority levels:

```typescript

// Before: Limited priority options

priority: z.enum(["high", "medium", "low"]).describe("Priority level of the task")

```

### The Solution

We implemented a two-pronged approach to fix this:

1. Extended the schema to include "critical" as a valid priority:

```typescript

// After: Including critical priority

priority: z.enum(["high", "medium", "low", "critical"]).describe("Priority level of the task")

```

2. Added validation middleware to gracefully handle invalid parameters:

```typescript

// Validation middleware in session/index.ts

try {

if (item.parameters && 'parse' in item.parameters) {

validatedArgs = item.parameters.parse(args)

}

} catch (validationError: any) {

// For TodoWrite, default invalid priorities to 'medium'

if (item.id === 'TodoWrite' && validationError.message?.includes('Invalid enum value')) {

// Gracefully handle and fix invalid priorities

validatedArgs = {

...args,

todos: args.todos.map((todo: any) => ({

...todo,

priority: ['high', 'medium', 'low', 'critical'].includes(todo.priority)

? todo.priority

: 'medium'

}))

}

}

}

```

This ensures that even if the AI uses an unexpected priority value, the tool will gracefully default to "medium" instead of crashing.

## 📦 NPM Package Distribution Fix

### The Discovery

A critical issue was discovered when testing the npm package installation. Users installing Kuuzuki via npm would encounter:

```bash

$ npm install -g kuuzuki

$ kuuzuki --version

error: For security reasons, macros cannot be run from node_modules.

```

### Understanding the Problem

The issue was that our npm package was shipping raw TypeScript source files containing Bun macros. When Bun tries to run these files from node_modules, it blocks macro execution for security reasons.

Our package.json files configuration was:

```json

"files": [

"bin/**/*",

"binaries/**/*",

"scripts/**/*",

"README.md",

"src/**/*.ts", // ❌ Raw TypeScript with Bun macros

"src/**/*.txt"

]

```

### The Fix

We updated the package to include compiled JavaScript instead of raw TypeScript:

```json

"files": [

"bin/**/*",

"dist/**/*", // ✅ Bun-bundled JavaScript

"dist-tsc/**/*", // ✅ TypeScript-compiled fallback

"binaries/**/*",

"scripts/**/*",

"README.md"

]

```

The bin/kuuzuki.js launcher intelligently selects the best available version:

1. First tries dist/index.js (Bun-bundled, preferred)

2. Falls back to dist-tsc/index.js (TypeScript-compiled)

3. Only uses src/index.ts as last resort (with warning)

## 🔄 OpenCode Parity Restoration

### The Journey

Kuuzuki started as a community fork of OpenCode with ambitious additional features. However, maintaining these extra features while keeping up with upstream changes proved challenging. In v0.1.16, we implemented a three-phase restoration to achieve 95%+ parity with OpenCode:

#### Phase 1: Remove Development Complexity

- Removed experimental features like memory graphs and telemetry collectors

- Simplified command structure from 22 to 8 essential commands

- Maintained kuuzuki branding and .agentrc support

#### Phase 2: Remove Git Permissions System

- Removed the complex git-permissions feature

- Simplified configuration management

- Improved startup performance

#### Phase 3: Final Alignment

- Synchronized tool implementations with OpenCode

- Updated documentation

- Achieved functional parity while keeping strategic kuuzuki features

### What We Kept

- Kuuzuki branding: Community identity remains

- *.agentrc support**: Enhanced agent configuration

- NPM distribution: Easy installation via npm install -g kuuzuki

- Community focus: Open to contributions and enhancements

## 🐛 Other Important Fixes

### Temporal Dead Zone Error

Fixed a critical error where the mode variable was accessed before initialization:

```typescript

// Before: mode accessed at line 814, but defined at line 814

const mode = await Mode.get(inputMode) // ReferenceError!

// After: Moved initialization before first use

const mode = await Mode.get(inputMode) // Line 715

// ... mode can now be safely used

```

### TypeScript Compilation

- Fixed 150+ type errors across the codebase

- Updated module resolution to support @openauthjs/openauth

- Removed references to deleted components

- Ensured clean compilation with tsc --noEmit

## 🚀 Installation and Usage

With v0.1.16, installation is now reliable:

```bash

# Install globally

npm install -g kuuzuki@0.1.16

# Verify installation

kuuzuki --version

# Start the terminal UI

kuuzuki tui

```

## 🔧 Technical Implementation Details

### Build Process

The release now includes a proper build step that creates both Bun-bundled and TypeScript-compiled versions:

```bash

# Bun bundle (preferred, fastest)

bun run build:bun # Creates dist/index.js

# TypeScript compilation (fallback)

bun run build:tsc # Creates dist-tsc/index.js

```

### Testing Approach

We implemented comprehensive testing for the npm package:

```typescript

// Test priority validation

const testCases = [

{ priority: "high", shouldPass: true },

{ priority: "critical", shouldPass: true },

{ priority: "urgent", shouldPass: false } // Gracefully handled

]

```

### GitHub Actions Integration

The release workflow automatically:

- Builds binaries for all platforms

- Creates properly structured npm packages

- Publishes to npm with correct versioning

- Generates GitHub releases with binaries

## 📚 Lessons Learned

1. Test the actual npm package: Our validation script tested the source directory, not the installed package. Always test the end-user experience.

2. Graceful error handling > strict validation: Instead of crashing on invalid input, provide sensible defaults and continue operation.

3. Maintain focus: While additional features are tempting, maintaining parity with upstream projects ensures long-term sustainability.

4. Community feedback is invaluable: The TodoWrite crash was reported by users who depend on the tool for their daily workflow.

## 🎯 What's Next

### Roadmap

- v0.2.0: Enhanced MCP (Model Context Protocol) support

- v0.3.0: Improved plugin system for community tools

- v0.4.0: Performance optimizations for large codebases

### Contributing

Kuuzuki is a community-driven project, and we welcome contributions:

- Report issues: https://github.com/moikas-code/kuuzuki/issues

- Submit PRs: Fork, branch, and propose changes

- Join discussions: Share ideas for new features

- Write tools: Extend Kuuzuki with custom tools

## 🙏 Acknowledgments

Special thanks to:

- The SST team for the original OpenCode project

- Community members who reported the TodoWrite crash

- Contributors who helped test the npm package fixes

- Everyone using Kuuzuki in their daily development workflow

## 📦 Upgrading

To upgrade to v0.1.16:

```bash

# Uninstall old version (if needed)

npm uninstall -g kuuzuki

# Install new version

npm install -g kuuzuki@0.1.16

# Verify the upgrade

kuuzuki --version

```

## 🔗 Resources

- GitHub: https://github.com/moikas-code/kuuzuki

- NPM: https://www.npmjs.com/package/kuuzuki

- Issues: https://github.com/moikas-code/kuuzuki/issues

- Original OpenCode: https://github.com/sst/opencode

---

Kuuzuki v0.1.16 represents a significant milestone in our journey to provide a reliable, community-driven AI terminal assistant. With improved resilience, fixed npm distribution, and strong OpenCode compatibility, we're excited to see what you'll build with Kuuzuki!

Happy coding! 🚀