jiva-core 0.2.3 → 0.3.1

package/.dockerignore

@@ -0,0 +1,53 @@
+# Node modules (will be reinstalled)
+node_modules/
+
+# Build outputs (will be rebuilt)
+dist/
+
+# Development files
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.npm
+.eslintcache
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Git
+.git/
+.gitignore
+.gitattributes
+
+# Documentation
+*.md
+!README.md
+docs/
+examples/
+
+# Tests
+test/
+tests/
+*.test.ts
+*.spec.ts
+
+# CI/CD
+.github/
+.gitlab-ci.yml
+.travis.yml
+
+# Local development
+.env
+.env.local
+.env.*.local
+
+# Temporary files
+tmp/
+temp/
+*.tmp

package/.gcloudignore

@@ -0,0 +1,49 @@
+# Google Cloud Build ignore patterns
+# Files not needed in Cloud Build/Container Registry
+
+# Node modules (will be installed in container)
+node_modules/
+
+# Development and docs
+docs/
+examples/
+*.md
+!README.md
+
+# Git
+.git/
+.gitignore
+.gitattributes
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+
+# Build artifacts (will be rebuilt)
+dist/
+*.tsbuildinfo
+
+# Test files
+test/
+tests/
+*.test.ts
+*.test.js
+*.spec.ts
+*.spec.js
+
+# npm package files
+.npmignore
+.npmrc
+
+# Scripts (except deploy.sh which is needed)
+setup.sh
+fix-filesystem-config.js

package/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing to Jiva
+
+Thank you for your interest in contributing to Jiva! This document provides guidelines for contributing to the project.
+
+## Code of Conduct
+
+Be respectful and constructive in your interactions with other contributors.
+
+## Getting Started
+
+1. **Fork the repository** on GitHub
+2. **Clone your fork:**
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/Jiva.git
+   cd Jiva
+   ```
+3. **Install dependencies:**
+   ```bash
+   npm install
+   ```
+4. **Build the project:**
+   ```bash
+   npm run build
+   ```
+
+## Development Workflow
+
+See [docs/guides/DEV_WORKFLOW.md](docs/guides/DEV_WORKFLOW.md) for detailed development instructions.
+
+### Quick Commands
+
+```bash
+npm run build              # Compile TypeScript
+npm run dev               # Watch mode for development
+npm run type-check        # Check TypeScript types
+npm test                  # Run tests (when available)
+```
+
+## Making Changes
+
+1. **Create a feature branch:**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes** following the coding standards
+
+3. **Test your changes:**
+   ```bash
+   npm run build
+   npm link  # Test CLI globally
+   jiva chat  # Verify functionality
+   ```
+
+4. **Commit with clear messages:**
+   ```bash
+   git commit -m "feat: add new feature X"
+   ```
+
+## Coding Standards
+
+- **TypeScript**: All code must be in TypeScript
+- **Formatting**: Follow existing code style
+- **Error Handling**: All functions should handle errors gracefully
+- **Logging**: Use the logger utility for consistent logging
+- **Documentation**: Update docs for new features
+
+## Pull Request Process
+
+1. **Update documentation** for any changed functionality
+2. **Update README.md** if adding new features
+3. **Add release notes** in `docs/release_notes/` if applicable
+4. **Create pull request** with clear description of changes
+5. **Link related issues** in the PR description
+
+## Areas for Contribution
+
+- Bug fixes
+- New MCP server integrations
+- Documentation improvements
+- Performance optimizations
+- Test coverage
+- Storage provider implementations (S3, Redis, etc.)
+- UI/UX improvements for CLI interface
+
+## Questions?
+
+Open an issue on GitHub for any questions about contributing.
+
+## License
+
+By contributing to Jiva, you agree that your contributions will be licensed under the MIT License.

package/Dockerfile

@@ -0,0 +1,63 @@
+# Multi-stage build for Jiva Cloud Run deployment
+# Stage 1: Build
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+COPY tsconfig.json ./
+
+# Install dependencies (including dev dependencies for build)
+RUN npm ci
+
+# Copy source code
+COPY src ./src
+
+# Build TypeScript
+RUN npm run build
+
+# Stage 2: Production
+FROM node:20-alpine
+
+WORKDIR /app
+
+# Install dumb-init for proper signal handling
+RUN apk add --no-cache dumb-init
+
+# Copy package files
+COPY package*.json ./
+
+# Install production dependencies only
+RUN npm ci --omit=dev && npm cache clean --force
+
+# Copy built application from builder
+COPY --from=builder /app/dist ./dist
+
+# Create non-root user
+RUN addgroup -g 1001 -S nodejs && \
+    adduser -S nodejs -u 1001 && \
+    chown -R nodejs:nodejs /app
+
+USER nodejs
+
+# Environment variables (overrideable)
+ENV NODE_ENV=production \
+    PORT=8080 \
+    LOG_LEVEL=info \
+    JIVA_STORAGE_PROVIDER=gcp \
+    MAX_CONCURRENT_SESSIONS=100 \
+    SESSION_IDLE_TIMEOUT_MS=1800000
+
+# Expose port
+EXPOSE 8080
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD node -e "require('http').get('http://localhost:8080/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"
+
+# Use dumb-init to handle signals properly
+ENTRYPOINT ["dumb-init", "--"]
+
+# Start HTTP server
+CMD ["node", "dist/interfaces/http/index.js"]

package/README.md

@@ -2,15 +2,16 @@
 
 [![npm version](https://img.shields.io/npm/v/jiva-core.svg)](https://www.npmjs.com/package/jiva-core) [![License](https://img.shields.io/github/license/KarmaloopAI/Jiva.svg)](LICENSE) [![GitHub stars](https://img.shields.io/github/stars/KarmaloopAI/Jiva.svg?style=social&label=Star)](https://github.com/KarmaloopAI/Jiva)
 
-Jiva is a powerful autonomous AI agent powered by gpt-oss-120b with full MCP (Model Context Protocol) support. It's designed to be highly goal-oriented, autonomous, and extensible for various use cases.
+Jiva is a powerful autonomous AI agent with a three-agent architecture (Manager, Worker, Client) powered by gpt-oss-120b with full MCP (Model Context Protocol) support. Deploy as a CLI tool or scale to production on Google Cloud Run.
 
 ## Quick Links
 
-- **[Quick Start Guide](docs/QUICKSTART.md)** - Get up and running in 30 seconds
-- **[Configuration Guide](docs/CONFIGURATION.md)** - Detailed configuration and provider setup
-- **[New Features Guide](docs/NEW_FEATURES.md)** - Latest improvements and features
-- **[Build Instructions](docs/BUILD.md)** - Detailed setup and development workflow
-- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Common issues and solutions
+- **[Quick Start Guide](docs/guides/QUICKSTART.md)** - Get up and running in 30 seconds
+- **[Cloud Run Deployment](docs/deployment/CLOUD_RUN_DEPLOYMENT.md)** - Deploy to production
+- **[Configuration Guide](docs/guides/CONFIGURATION.md)** - Detailed configuration and provider setup
+- **[Documentation](docs/README.md)** - Complete documentation index
+- **[Build Instructions](docs/guides/BUILD.md)** - Detailed setup and development workflow
+- **[Troubleshooting](docs/guides/TROUBLESHOOTING.md)** - Common issues and solutions
 
 ## Demo
 
@@ -19,26 +20,63 @@ Jiva is a powerful autonomous AI agent powered by gpt-oss-120b with full MCP (Mo
 ## Features
 
 ### Core Capabilities
-- **Dual-Agent Architecture**: Manager + Worker pattern for reliable task execution and planning
+- **Three-Agent Architecture**: Manager for planning, Worker for execution, Client for quality validation
+- **Adaptive Quality Control**: Client agent uses tiered validation (MINIMAL→STANDARD→THOROUGH) based on task complexity
+- **Unjustified Failure Detection**: LLM-powered analysis catches agents giving up without trying
+- **Cloud-Ready Deployment**: Run on Google Cloud Run with auto-scaling, WebSocket support, and GCS storage
+- **Multi-Tenancy**: Per-tenant isolation with authenticated session management
 - **Provider Agnostic**: Works with Krutrim, Groq, OpenAI, Ollama, and any OpenAI-compatible API
-- **Three-Phase Execution**: Planning → Execution → Synthesis for structured task completion
 - **MCP Integration**: Seamless integration with Model Context Protocol servers for extensible tooling
 - **Smart Conversations**: Auto-save, restore, and AI-generated titles for all conversations
-- **Pretty Markdown**: Beautiful terminal output with syntax highlighting
 - **Directive-Based**: Orient agent behavior with custom `jiva-directive.md` files
-- **Multi-Modal Support**: Optional image understanding via Llama-4-Maverick-17B
-- **Auto-Condensing**: Intelligent conversation history management to prevent token overload
+- **Storage Abstraction**: Local filesystem or cloud storage (GCS, future: S3, Redis)
 
-### Advanced Features (v0.2.1)
+### v0.3.1 Features
+- **Production Deployment**: One-command Cloud Run deployment with GCS persistence
+- **Client Agent**: Intelligent validation that ensures work quality and catches false failures
+- **HTTP/WebSocket API**: RESTful endpoints and real-time bidirectional communication
+- **Authentication**: Firebase Auth, custom JWT, or development mode
+- **Session Management**: Auto-scaling agent instances with idle timeout and cleanup
+- **Container Orchestration**: Multi-stage Docker builds, health probes, graceful shutdown
+- **Personas & Skills**: 100% compatible with Claude's Skills/Plugins system - extend Jiva with domain-specific capabilities
+
+### Personas (Skills & Plugins)
+
+Jiva supports persona-based skill management, fully compatible with Claude's Skills/Plugins system:
+
+```bash
+# List available personas
+jiva persona list
+
+# Activate a persona
+jiva persona activate data-analyst
+
+# Create your own skill
+jiva persona create-skill my-skill \
+  --description "Custom functionality" \
+  --author "Your Name"
+
+# Package and distribute
+jiva persona package-skill my-skill
+```
+
+**Key Features:**
+- **Progressive Disclosure**: Skills load only what's needed (L1→L2→L3)
+- **Automatic Routing**: Agent selects skills based on user request
+- **Composable**: Bundle skills, commands, agents, and MCP servers
+- **Portable**: Same .skill files work on Claude and Jiva
+
+See **[Personas Guide](docs/guides/PERSONAS.md)** for complete documentation.
+
+### v0.2.1 Features
 - **Dual-Agent System**: Separate Manager and Worker agents for better task focus and reliability
 - **Chain-of-Thought Logging**: Transparent reasoning at INFO level with clean ASCII formatting
 - **Robust Error Recovery**: Automatic retry with error feedback for API and tool failures
 - **Workspace-Aware Operations**: Smart path resolution for file operations
 - **Slash Commands**: Use `/help`, `/load`, `/save`, `/list` for easy conversation management
 - **Smart Tool Format Detection**: Auto-detects Harmony vs Standard OpenAI tool calling format
-- **Extensible Architecture**: Designed to expand from CLI to desktop or web applications
 
-See [NEW_FEATURES.md](docs/NEW_FEATURES.md) for detailed information.
+See [release notes](docs/release_notes/) for detailed version history.
 
 ## Installation
 
@@ -58,21 +96,15 @@ jiva setup
 
 ```bash
 git clone https://github.com/KarmaloopAI/Jiva.git
-cd jiva
-npm install
-npm run build
-npm link  # For global CLI access
-```
+cd jCLI Mode (Local Development)
 
-## Quick Start
-
-### 1. Install Jiva
+#### 1. Install Jiva
 
 ```bash
 npm install -g jiva-core
 ```
 
-### 2. First-Time Setup
+#### 2. First-Time Setup
 
 Run the interactive setup wizard:
 
@@ -86,7 +118,7 @@ You'll be prompted for:
 - Optional multimodal model (Llama-4-Maverick-17B)
 - MCP server configuration
 
-### 3. Start Chatting
+#### 3. Start Chatting
 
 Launch interactive mode:
 
@@ -104,8 +136,69 @@ You: /save                    # Save this conversation
 You: /list                    # View all saved conversations
 ```
 
+### Cloud Run Mode (Production)
+
+Deploy Jiva as an auto-scaling HTTP/WebSocket service:
+
+#### 1. Prerequisites
+
+- Google Cloud account with billing enabled
+- `gcloud` CLI installed and configured
+- Docker installed (for local testing)
+
+#### 2. One-Command Deployment
+
+```bash
+git clone https://github.com/KarmaloopAI/Jiva.git
+cd jiva
+./deploy.sh YOUR_PROJECT_ID us-central1
+```
+
+The script automatically:
+- Enables required GCP APIs
+- Creates GCS bucket for state storage
+- Configures service account and IAM roles
+- Builds and deploys container to Cloud Run
+- Outputs service URL
+
+#### 3. Test Deployment
+
+```bash
+SERVICE_URL=$(gcloud run services describe jiva --region=us-central1 --format='value(status.url)')
+
+# Health check
+curl $SERVICE_URL/health
+
+# Chat endpoint (with auth bypass for testing)
+curl -X POST $SERVICE_URL/api/chat \
+  -H "Content-Type: application/json" \
+  -H "X-Session-Id: test-session" \
+  -d '{"message": "Hello, Jiva!"}'
+```
+
+**Full deployment guide:** [Cloud Run Deployment](docs/deployment/CLOUD_RUN_DEPLOYMENT.md)ry these commands:**
+```bash
+You: /help                    # Show all available commands
+You: /servers                 # Check MCP server status
+You: /tools                   # List all available tools
+You: List files in this directory
+You: /save                    # Save this conversation
+You: /list                    # View all saved conversations
+```
+
 ### 4. Advanced Usage
 
+**View current configuration:**
+```bash
+jiva config --show
+```
+
+**Use a custom configuration file:**
+```bash
+jiva chat --config ./my-project-config.json
+jiva run "analyze code" --config ./team-config.json
+```
+
 **Custom workspace and directive:**
 ```bash
 jiva chat --workspace /path/to/project --directive ./project-directive.md
@@ -216,7 +309,7 @@ Provides comprehensive file operations across user directories (subject to OS pe
 - **Package:** `@modelcontextprotocol/server-filesystem`
 - **Access:** `/Users` (macOS/Linux) or `C:\Users` (Windows)
 - **Tools:** read_file, write_file, list_directory, create_directory, and more
-- **Details:** See [FILESYSTEM_ACCESS.md](docs/FILESYSTEM_ACCESS.md)
+- **Details:** See [FILESYSTEM_ACCESS.md](docs/architecture/FILESYSTEM_ACCESS.md)
 
 ### Recommended Additional Servers
 
@@ -320,93 +413,140 @@ Edit your config file at `~/.config/jiva-nodejs/config.json` (Linux) or `~/Libra
 #### Programmatically
 
 ```typescript
-import { configManager } from 'jiva-core';
+### Three-Agent System (v0.3.1)
 
-configManager.addMCPServer('playwright', {
-  command: 'npx',
-  args: ['@playwright/mcp@latest'],
-  enabled: true,
-});
-```
-
-### Checking MCP Server Status
-
-```bash
-jiva chat
-# Type: /servers
-```
+Jiva uses a three-agent architecture for intelligent task execution:
 
-You'll see:
 ```
-MCP Servers:
-  ✓ filesystem: 12 tools
-  ✓ playwright: 8 tools
-  ✓ desktop-commander: 6 tools
+User Request
+     ↓
+┌────────────────┐
+│ Manager Agent  │  Plans subtasks, coordinates workflow
+└────────┬───────┘
+         ↓
+┌────────────────┐
+│ Worker Agent   │  Executes subtasks with MCP tools
+└────────┬───────┘
+         ↓
+┌────────────────┐
+│ Client Agent   │  Validates outputs, ensures quality
+└────────┬───────┘
+         ↓
+    Final Response
 ```
 
-**Troubleshooting MCP Issues:** See [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md#mcp-server-issues)
+**Manager Agent**: High-level planning and task decomposition  
+**Worker Agent**: Tool execution and information gathering  
+**Client Agent**: Adaptive validation and quality control (new in v0.3.1)
 
-## CLI Commands
+The Client agent uses tiered involvement levels to balance quality with efficiency:
+- **MINIMAL**: Information requests → metadata validation only
+- **STANDARD**: Creation tasks → file exists + basic checks
+- **THOROUGH**: Complex tasks or after failures → full E2E validation
 
-### Interactive Mode Commands
-
-While in chat mode, you can use these commands (prefix with `/`):
-
-- `/help` - Show available commands
-- `/exit` / `/quit` - Exit the session
-- `/reset` - Reset conversation history
-- `/history` - Show conversation history
-- `/tools` - List available MCP tools
-- `/servers` - Show MCP server status
-- `/save` - Save current conversation ✨ NEW
-- `/load` - Load a saved conversation ✨ NEW
-- `/list` - List all saved conversations ✨ NEW
-
-## Architecture
-
-Jiva is designed with extensibility in mind:
+### Project Structure
 
 ```
 jiva/
 ├── src/
-│   ├── core/           # Core agent logic
-│   ├── models/         # Model integrations and Harmony format
-│   ├── mcp/            # MCP client and server management
-│   ├── interfaces/     # CLI, Electron, Web interfaces
-│   └── utils/          # Utilities and helpers
+│   ├── core/              # Three-agent system
+│   │   ├── dual-agent.ts        # Main orchestrator
+│   │   ├── manager-agent.ts     # Planning & coordination
+│   │   ├── worker-agent.ts      # Tool execution
+│   │   └── client-agent.ts      # Quality validation (v0.3.1)
+│   ├── models/            # Model integrations and Harmony format
+│   ├── mcp/               # MCP client and server management
+│   ├── storage/           # Storage abstraction (v0.3.1)
+│   │   ├── local-provider.ts    # Filesystem storage
+│   │   └── gcp-bucket-provider.ts # Cloud storage
+│   ├── interfaces/        # CLI and HTTP interfaces
+│   │   ├── cli/           # CLI interface
+│   │   └── http/          # Cloud Run HTTP/WebSocket (v0.3.1)
+│   └── utils/             # Utilities and helpers
 ```
 
 ### Key Components
 
-1. **DualAgent**: Main orchestrator coordinating Manager and Worker agents (v0.2.1+)
+1. **DualAgent**: Main orchestrator coordinating Manager, Worker, and Client agents
 2. **ManagerAgent**: High-level planning, task breakdown, and result synthesis
 3. **WorkerAgent**: Focused tool execution and information gathering
-4. **ModelOrchestrator**: Manages multi-model coordination (reasoning + multimodal)
-5. **MCPServerManager**: Handles MCP server lifecycle and tool discovery
-6. **WorkspaceManager**: Manages workspace directory and directive files
-7. **Harmony Format Handler**: Implements gpt-oss-120b's required response format
+4. **ClientAgent**: Adaptive validation with unjustified failure detection
+5. **ModelOrchestrator**: Manages multi-model coordination (reasoning + multimodal)
+6. **MCPServerManager**: Handles MCP server lifecycle and tool discovery
+7. **StorageProvider**: Unified interface for local/cloud persistence
+8. **SessionManager**: Manages DualAgent lifecycle in cloud deployments
+
+**Troubleshooting MCP Issues:** See [TROUBLESHOOTING.md](docs/guides/TROUBLESHOOTING.md#mcp-server-issues)
+
+### CLI/Library Mode
+
+```typescript
+import {
+  DualAgent,
+  createKrutrimModel,
+  ModelOrchestrator,
+  MCPServerManager,
+  WorkspaceManager,
+  ConversationManager,
+  createStorageProvider,
+} from 'jiva-core';
+
+// Create storage provider (auto-detects local/cloud)
+const storageProvider = await createStorageProvider();
+
+// Create models
+const reasoningModel = createKrutrimModel({
+  endpoint: 'https://cloud.olakrutrim.com/v1/chat/completions',
+  apiKey: 'your-api-key',
+  model: 'gpt-oss-120b',
+  type: 'reasoning',
+});
+
+// Create orchestrator
+const orchestrator = new ModelOrchestrator({ reasoningModel });
 
-**Legacy:** JivaAgent (single-agent) remains available for compatibility
+// Initialize MCP
+const mcpManager = new MCPServerManager();
+await mcpManager.initialize({
+  filesystem: {
+    command: 'npx',
+    args: ['-y', '@modelcontextprotocol/server-filesystem', process.cwd()],
+    enabled: true,
+  },
+});
 
-## Working with gpt-oss-120b
+// Initialize workspace
+const workspace = new WorkspaceManager(storageProvider);
+await workspace.initialize();
 
-The gpt-oss-120b model requires the Harmony response format. Jiva handles this automatically with:
+// Initialize conversation manager
+const conversationManager = new ConversationManager(storageProvider);
 
-### Tool Call Parsing
-- Robust parsing of `<|call|>function_name({"param": "value"})<|return|>` format
-- Automatic JSON fixing for common formatting issues
-- Validation against available tools
+// Create three-agent system
+const agent = new DualAgent({
+  orchestrator,
+  mcpManager,
+  workspace,
+  conversationManager,
+  maxSubtasks: 20,        // Manager's subtask limit
+  maxIterations: 10,      // Worker's iteration limit per subtask
+});
+
+// Use agent
+const response = await agent.chat('Hello, Jiva!');
+console.log(response.content);
+console.log(`Plan: ${response.plan?.subtasks.join(', ')}`);
+console.log(`Tools used: ${response.toolsUsed.join(', ')}`);
+
+// Cleanup
+await agent.cleanup();
+```
 
-### Multi-Channel Output
-- Analysis channel: Chain-of-thought reasoning
-- Final channel: User-facing responses
-- Tool calling: Structured function calls
+### Cloud Mode (HTTP/WebSocket)
 
-### Error Handling
-- Retry logic for malformed tool calls
-- Graceful degradation when tools fail
-- Detailed logging for debugging
+For cloud deployments, see the [HTTP interface documentation](docs/deployment/CLOUD_RUN_IMPLEMENTATION.md) and [example programs](examples/).
 
+**Key difference:** Cloud mode uses `SessionManager` to handle multiple concurrent agent instances with per-tenant isolation.
 ## Development
 
 ### Build