# Release Notes - v0.9.19

**Release Date:** 2026-02-01

## 🎉 Features

### AI Toolkit Package (`@portos/ai-toolkit`)
- **Created shared library for AI provider patterns**: New npm workspace package at `packages/ai-toolkit/`
  - Server services: Provider management, run execution, prompt templating
  - Express routes: REST API for providers, runs, and prompts
  - React components: `ProviderDropdown` with theming support
  - React hooks: `useProviders` and `useRuns` for state management
  - API client: Configurable fetch-based client with error handling
  - Zod validation schemas for type safety
  - Comprehensive test suite with 6 passing tests
  - Full documentation: README, INTEGRATION guide, and inline JSDoc
  - Ready for extraction to standalone package or use in other PortOS-style apps

- **Integrated toolkit into PortOS server**: Replaced local AI services with toolkit
  - Created compatibility shims for existing service imports
  - Extended toolkit routes with PortOS-specific vision testing endpoints
  - Added prompts route wrapper to maintain PortOS API contract
  - Added hooks for usage tracking and error event emission
  - Backed up original files (`.old.js` suffix) for reference
  - Server successfully restarted with toolkit integration
  - All existing functionality maintained

- **Integrated toolkit into FableLoom**: Used npm link to test cross-project compatibility
  - Created TypeScript declarations for toolkit services
  - TypeScript wrapper maintains type safety
  - Both JavaScript (PortOS) and TypeScript (FableLoom) projects now using shared library

- **Full CRUD for prompt stages**: Added create and delete operations to toolkit
  - New `createStage()` and `deleteStage()` methods in prompts service
  - `POST /api/prompts` endpoint for creating stages with config and template
  - `DELETE /api/prompts/:stage` endpoint for removing stages
  - Automatic cleanup of template files on deletion
  - Updated TypeScript declarations

### Prompt Management UI
- **Create/Delete Prompt Stages**: Added stage management UI to `/prompts` page
  - "+" button to create new stages with modal form
  - Delete button (trash icon) on each stage in the list
  - Modal form includes: stage key, display name, description, model selection, returns JSON toggle, template editor
  - Real-time validation and error handling
  - Removed unused placeholder stages (code-analysis, command-suggestion)

- **System Stage Protection**: Protect critical prompt stages from accidental deletion
  - Visual "System" badge on 9 protected stages in the list
  - `GET /api/prompts/:stage/usage` endpoint returns usage information
  - Enhanced confirmation dialogs showing what features use each stage
  - Backend protection requires `?force=true` query param to delete system stages
  - Clear warning messages: "This is a SYSTEM stage used by [features]"
  - Protected stages: CoS (4), Brain (3), Memory (1), App Detection (1)

### Template Creation Enhancement
- **Directory Picker for Template Target Path**: Replaced freeform text input with interactive directory browser on `/templates` page
  - Default directory now set to parent of PortOS project (`/Users/antic/github.com/atomantic`)
  - Visual folder navigation with breadcrumb-style current path display
  - Double-click folders to select or use "Select Current" button
  - "Parent" and "Default" navigation buttons for easy directory traversal

### Dashboard Activity Visualization
- **Hourly Activity Heatmap**: New visualization showing session distribution across all 24 hours
  - GitHub-style contribution graph with 5-level intensity colors
  - Identifies peak productivity hours with session counts
  - Responsive design with condensed hour labels on mobile
  - Fully accessible with ARIA labels and hover tooltips
  - Displays total sessions tracked for context

### Chief of Staff Enhancement (M35)
- **BM25 Hybrid Memory Search**: Added BM25 text search algorithm for hybrid memory retrieval
  - `server/lib/bm25.js` - BM25 with IDF weighting, inverted index, stemming
  - `server/services/memoryBM25.js` - Index management, persistence to `data/cos/memory/bm25-index.json`
  - Hybrid search combines BM25 + vector with reciprocal rank fusion for better context retrieval

- **Event-Driven Scheduling**: Replaced interval-based loops with cron-compatible event scheduler
  - `server/services/eventScheduler.js` - Timeout-safe timers (clamps to 2^31-1 ms), cron expressions
  - Converted `cos.js` from setInterval to scheduleEvent() calls
  - Supports interval, cron, and one-shot event types

- **Execution Lanes**: Lane-based concurrency control for agent spawning
  - `server/services/executionLanes.js` - Critical (1 slot), Standard (2 slots), Background (3 slots)
  - Lane acquisition with waitForLane() timeout and queue management
  - Integrated into subAgentSpawner.js for controlled parallel execution

- **Tool State Machine**: Comprehensive lifecycle tracking for tool executions
  - `server/services/toolStateMachine.js` - IDLE → START → RUNNING → UPDATE → END → ERROR states
  - Tracks timing, state history, and metadata per execution
  - Enables better error recovery and execution analytics

- **Thinking Levels**: Dynamic model selection based on task complexity
  - `server/services/thinkingLevels.js` - off, minimal, low, medium, high, xhigh levels
  - Hierarchy resolution: task → agent → provider for thinking level
  - Integrated into selectModelForTask() for automatic model upgrades

- **Error Recovery Strategies**: Structured error analysis and recovery
  - `server/services/errorRecovery.js` - retry, escalate, fallback, decompose, defer, investigate strategies
  - Analyzes error types (network, rate-limit, auth, validation, etc.)
  - Returns actionable recovery recommendations

- **Agent Run Cache**: TTL-based caching for agent outputs
  - `server/services/agentRunCache.js` - 10-minute default TTL, key-based storage
  - Memory-efficient with periodic cleanup
  - Prevents redundant re-execution of recent tasks

- **Missions Service**: Long-term goal tracking for proactive task generation
  - `server/services/missions.js` - Mission CRUD, sub-tasks, progress tracking
  - Generates proactive tasks when user queue is empty
  - App-owned missions for autonomous improvement of managed apps

- **Comprehensive Test Suite**: 18 new test files with 722 total tests
  - Unit tests for all new services
  - Integration tests for state machine and lane management
  - Missions service test coverage for CRUD and task generation

## 🔧 Improvements

### Chief of Staff Task Management
- **Separate Active Tasks from Pending**: Task list now clearly distinguishes between pending, active (in_progress), blocked, and completed tasks
  - Pending tasks shown in yellow section (waiting to be started)
  - Active tasks shown in blue section with animated pulse indicator (currently running)
  - Blocked tasks shown in red section (waiting for external factors)
  - Completed tasks remain collapsible in green section
  - Applies to both User Tasks (TASKS.md) and System Tasks (COS-TASKS.md)
  - Makes it immediately clear which tasks are actively being worked on vs queued

### Architecture
- **Monorepo with npm workspaces**: Converted root package.json to support workspaces
  - Workspace packages: `packages/*`, `server`, `client`
  - Enables sharing code between main app and reusable packages
  - Foundation for extracting more shared libraries

### API
- Added `GET /api/directories` endpoint for browsing file system directories
  - Returns current path, parent path (if available), and list of subdirectories
  - Filters out hidden directories (starting with `.`)
  - Defaults to parent of PortOS project directory when no path specified

### UI Components
- New `DirectoryPicker` component in `client/src/components/DirectoryPicker.jsx`
  - Dropdown interface with folder icons and navigation
  - Real-time directory browsing without typing paths
  - Keyboard and mouse navigation support

## 🐛 Bug Fixes

### Chief of Staff - Model Selection
- **Fixed default model selection to respect provider's defaultModel**: Standard tasks now use the provider's configured default model instead of always using the medium tier model
  - Changed `selectModelForTask()` to return `provider.defaultModel` for standard tasks instead of `provider.mediumModel`
  - Updated fallback logic to handle 'default' tier in addition to 'heavy', 'medium', and 'light'
  - This ensures that when a provider (like claude-code) has Opus set as the defaultModel, tasks without explicit model specifications will use Opus instead of Sonnet
  - Task-specific model selection (heavy for complex tasks, light for documentation) continues to work as before

### Chief of Staff - Multi-Provider CLI Support
- **Fixed Codex CLI provider support**: Agent spawner was hardcoded to use Claude CLI arguments regardless of selected provider
  - Added `buildCliSpawnConfig()` function for provider-specific CLI invocation
  - Codex CLI now correctly uses: `codex exec --model <model>`
  - Claude CLI continues using: `claude --dangerously-skip-permissions --print --model <model>`
  - Updated cos-runner to accept `cliCommand` and `cliArgs` parameters
  - Maintains backwards compatibility with legacy `claudePath` parameter
