jivamai 0.1.4-dev.edce8f4 → 0.2.0-dev.03f9681

package/docs/README.md

@@ -1,55 +0,0 @@
-# Jivam Documentation
-
-Jivam is a cross-platform desktop application that provides a polished graphical interface for [jiva-core](https://www.npmjs.com/package/jiva-core) AI agents. It handles chat sessions, conversation history, persona switching, MCP server management, and workspace file browsing — all without exposing a terminal.
-
----
-
-## Tech Stack
-
-| Layer | Technology | Version |
-|-------|-----------|---------|
-| Desktop shell | Electron | 33 |
-| UI framework | React | 18 |
-| Language | TypeScript | 5.9 |
-| Build tool | Vite + vite-plugin-electron | 5 |
-| Styling | Tailwind CSS | 3 |
-| State management | Zustand | 4.5 |
-| Animations | Framer Motion | 11 |
-| AI engine | jiva-core (global npm) | latest |
-
----
-
-## Prerequisites (development)
-
-- Node.js 20+
-- `jiva-core` installed globally: `npm install -g jiva-core`
-- jiva-core configured with an API key (run `jiva setup` or configure via the in-app Settings)
-
----
-
-## Quick Start
-
-```bash
-npm install
-npm run dev          # Electron + Vite hot-reload
-npm run build        # Production build
-npm run dist:mac     # Package for macOS (DMG + ZIP)
-npm run dist:win     # Package for Windows (NSIS installer + portable)
-npm run dist:linux   # Package for Linux (AppImage + deb)
-```
-
----
-
-## Documentation Index
-
-| Section | Description |
-|---------|-------------|
-| [architecture/overview.md](architecture/overview.md) | System diagram, process model, key directories |
-| [architecture/startup-flow.md](architecture/startup-flow.md) | Boot sequence from cold start to ready UI |
-| [architecture/ipc-contract.md](architecture/ipc-contract.md) | All IPC channels with payloads and return types |
-| [architecture/state-management.md](architecture/state-management.md) | Zustand stores, data flow patterns |
-| [architecture/jiva-core-integration.md](architecture/jiva-core-integration.md) | How jiva-core is loaded, called, and configured |
-| [architecture/code-agent-integration.md](architecture/code-agent-integration.md) | Code mode agent architecture and components |
-| [guides/design-guide.md](guides/design-guide.md) | Colors, typography, spacing, components, animations |
-| [guides/adding-features.md](guides/adding-features.md) | Step-by-step guide for adding new IPC-backed features |
-| [release_notes/](release_notes/) | Release notes (see individual version files) |

package/docs/architecture/cloud-mode.md

@@ -1,204 +0,0 @@
-# Cloud Mode Architecture
-
-## Overview
-
-Cloud mode lets users run Jivam without a local `jiva-core` install. Auth is
-handled by Supabase; chat inference runs on a Google Cloud Run deployment
-(`https://jiva-hdjcuspt2a-uc.a.run.app`).
-
-Cloud mode is architected to support two hosts:
-- **Electron desktop** — a separate `BrowserWindow` loaded with `?mode=cloud`
-- **Web (jivamai.com)** — the same React app served statically, no Electron layer
-
-The abstraction that makes this work is `src/lib/cloud-api.ts`.
-
----
-
-## Implementation Status
-
-### Done ✓
-
-| Area | File(s) | What was done |
-|------|---------|---------------|
-| Separate cloud window | `electron/main.ts` | `createCloudWindow()` opens a new `BrowserWindow` at `?mode=cloud`; clicking the cloud icon in TopBar fires `cloud:open-window` IPC |
-| Cloud window detection | `src/store/auth.store.ts` | `isCloudWindow` reads URL param at module load; `isCloudMode` is permanently `true` in the cloud window |
-| Auth store | `src/store/auth.store.ts` | Zustand store: `signIn`, `signUp`, `signOut`, `restoreSession`; session persisted to `localStorage` under key `jivam-cloud-session` |
-| Sign-in UI | `src/components/setup/CloudSignIn.tsx` | Email/password form, sign-in / create account toggle, loading spinner, error display |
-| Supabase auth (Electron) | `electron/cloud-auth.ts` | Fetch-based, no SDK: `cloudSignIn`, `cloudSignUp`, `cloudSignOut`, `initCloudSession` |
-| API shim | `src/lib/cloud-api.ts` | `cloudApiSignIn/Up/Out/Init` — Electron delegates to IPC; web calls Supabase/Cloud Run directly |
-| Cloud runner | `electron/cloud-runner.ts` | `CloudRunner` class: SSE streaming (`/api/chat/stream`) with non-streaming fallback (`/api/chat`). Configures via `configure(userId, sessionId)` |
-| IPC routing | `electron/ipc-handlers.ts` | `jiva:send-message` checks `cloudRunner.isActive()` and routes accordingly; phase/log events sent to `event.sender` (not hardcoded main window) |
-| IPC surface | `electron/preload.ts` + `src/types/electron.d.ts` | `window.electron.cloud.{openWindow, signIn, signUp, signOut, init}` |
-| App.tsx routing | `src/App.tsx` | Cloud window without `cloudUser` shows `<CloudSignIn>`; skips local preflight and `startServer()` |
-| TopBar | `src/components/layout/TopBar.tsx` | Cloud icon directly calls `openWindow()` (no dropdown in local mode); cloud mode shows badge with email + sign-out dropdown |
-| Code tab guard | `src/components/code/CodeChatView.tsx` | "Local install required" overlay when `isCloudMode` |
-
-### Known Broken / Untested ✗
-
-| Issue | File | Notes |
-|-------|------|-------|
-| **Chat does not work end-to-end** | `electron/cloud-runner.ts` | ~~FIXED~~ `cloudRunner.startInit()` is called in `cloud:init` handler before the async HTTP call. `jiva:send-message` detects cloud senders via `event.sender.getURL().includes('mode=cloud')` and calls `cloudRunner.waitUntilReady(30_000)` if not yet active. Cloud Run cold starts up to 30s are handled. |
-| **Supabase email confirmation** | `electron/cloud-auth.ts` + `src/lib/cloud-api.ts` | If the Supabase project has email confirmation enabled, `cloudSignUp` returns the user object at top-level with no `access_token`. This is handled defensively now (`data.user ?? data`), but the UX shows no "check your email" message — user just sees the app with an unconfigured session |
-| **Session restoration** | `src/store/auth.store.ts` | `restoreSession()` fires and forgets `cloudApiInit`. If the cloud runner is never actually configured before a chat message, the message silently routes to the local runner |
-| **Sign-out in cloud window** | `src/store/auth.store.ts` | `signOut` clears `localStorage` and calls `cloudApiSignOut`. But `cloudRunner.deactivate()` is called from `ipc-handlers.ts cloud:sign-out` — this path works. What doesn't work: the `cloudSignOut` IPC handler in `ipc-handlers.ts` passes no `accessToken` (it just calls `cloudRunner.deactivate()`), so Supabase session is not actually revoked server-side |
-| **Activity log in cloud window** | `electron/cloud-runner.ts` | `onLog` is called with `Tool: ${msg}` for every SSE `status` event. Whether the Cloud Run backend actually emits these is untested |
-| **Splash screen timing** | `src/App.tsx` | `showSplash` is set to `false` by the init effect before the user signs in. After sign-in, `showSplash` is already `false` — AppShell should render. This was still causing "Connecting to Jivam..." in testing; root cause not fully confirmed |
-
----
-
-## Architecture Diagram
-
-```
-USER CLICKS CLOUD ICON (TopBar, local window)
-         │
-         ▼
-window.electron.cloud.openWindow()
-         │
-         ▼ IPC: cloud:open-window
-electron/main.ts createCloudWindow()
-         │
-         ▼
-New BrowserWindow loads index.html?mode=cloud
-         │
-         ▼
-auth.store.ts  →  isCloudWindow = true  →  isCloudMode = true
-         │
-         ▼ No existing session in localStorage
-App.tsx  →  isCloudMode && !cloudUser  →  render <CloudSignIn>
-         │
-         ▼ User submits credentials
-auth.store.signIn/signUp()
-  1. cloudApiSignIn/Up()  →  window.electron.cloud.signIn/Up()
-                          →  IPC: cloud:sign-in / cloud:sign-up
-                          →  electron/cloud-auth.ts cloudSignIn/Up()
-                          →  POST Supabase /auth/v1/token or /signup
-  2. set({ cloudUser })   ← immediately (non-blocking)
-  3. cloudApiInit()       → fire-and-forget
-                          → window.electron.cloud.init()
-                          → IPC: cloud:init
-                          → electron/ipc-handlers.ts
-                          → initCloudSession() POST /api/session on Cloud Run
-                          → cloudRunner.configure(userId, sessionId)
-         │
-         ▼ cloudUser is set
-App.tsx  →  isCloudMode && cloudUser  →  render <AppShell>
-         │
-         ▼ User sends a chat message
-jiva.store.sendMessage()
-  →  window.electron.jiva.sendMessage()
-  →  IPC: jiva:send-message
-  →  ipc-handlers.ts
-  →  cloudRunner.isActive() ? cloudRunner.chat() : jivaRunner.chat()
-  →  POST https://jiva-hdjcuspt2a-uc.a.run.app/api/chat/stream (SSE)
-  →  SSE events → jiva:phase-update + jiva:jiva-log → sender window
-```
-
----
-
-## Key Files
-
-```
-src/
-  lib/cloud-api.ts          Environment shim (Electron IPC vs. direct fetch)
-  store/auth.store.ts       Cloud auth state (Zustand)
-  components/
-    setup/CloudSignIn.tsx   Sign-in / create account form
-    layout/TopBar.tsx       Cloud icon → openWindow(); cloud badge when signed in
-    code/CodeChatView.tsx   "Local only" overlay in cloud mode
-  App.tsx                   Cloud window routing: sign-in guard, skip local setup
-
-electron/
-  main.ts                   createCloudWindow(), ipcMain.handle('cloud:open-window')
-  cloud-auth.ts             Supabase fetch wrapper (Electron-side)
-  cloud-runner.ts           HTTP/SSE client to Cloud Run
-  ipc-handlers.ts           cloud:sign-in/up/out/init handlers; jiva:send-message routing
-  preload.ts                window.electron.cloud.* IPC bridge
-```
-
----
-
-## Service Credentials
-
-| Service | Value |
-|---------|-------|
-| Supabase project | `hcomegrnonxmjupvvyus` |
-| Supabase URL | `https://hcomegrnonxmjupvvyus.supabase.co` |
-| Supabase anon key | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` (in `cloud-auth.ts` and `cloud-api.ts`) |
-| Cloud Run URL | `https://jiva-hdjcuspt2a-uc.a.run.app` |
-
----
-
-## What Needs to Be Fixed Next
-
-### Priority 1 — Chat must actually work ✓ FIXED
-
-`cloudRunner.startInit()` is now called at the top of `cloud:init` before the async
-`initCloudSession` HTTP call. `jiva:send-message` detects cloud senders via
-`event.sender.getURL().includes('mode=cloud')` and awaits `cloudRunner.waitUntilReady(30_000)`
-before routing. Cloud Run cold starts up to 30 s are handled.
-
-### Priority 2 — Confirm Cloud Run API contract ✓ VERIFIED
-
-The Cloud Run endpoints are confirmed via `~/dev/Jiva/docs/deployment/HTTP_API.md`:
-
-| Endpoint | Method | Purpose |
-|----------|--------|---------|
-| `/api/session` | POST | Create/restore tenant session |
-| `/api/chat/stream` | POST | SSE streaming chat |
-| `/api/chat` | POST | Non-streaming chat fallback |
-| `/api/chat/history` | DELETE | Reset conversation |
-| `/api/chat/stop` | POST | Abort active generation |
-
-Request headers: `x-tenant-id: userId`, `x-session-id: sessionId`
-
-**These endpoints and their request/response shapes have not been verified.**
-The Cloud Run service may have a different API. Check the backend source or
-deploy logs before debugging further.
-
-SSE event format (per `docs/deployment/HTTP_API.md` in the jiva-core repo):
-```
-event: status
-data: {"message":"Processing request..."}
-
-event: response
-data: {"content":"...","iterations":3,"toolsUsed":[...]}
-
-event: done
-data: {"success":true}
-
-event: error
-data: {"message":"error text"}
-```
-The event type is carried in the SSE `event:` line, **not** as a `type` field inside the JSON body.
-Non-streaming `/api/chat` response field is `response` (not `content`).
-
-### Priority 3 — Supabase email confirmation
-
-Check the Supabase dashboard for project `hcomegrnonxmjupvvyus`:
-- If **email confirmation is ON**: sign-up returns no session. Need a "check
-  your email" screen instead of immediately transitioning to AppShell.
-- If **email confirmation is OFF** (auto-confirm): the current flow should work.
-
-### Priority 4 — Session token refresh
-
-The `cloudUser` in `localStorage` stores `userId`, `email`, and `sessionId`
-but **not** the Supabase `access_token` or `refresh_token`. These are needed
-to make authenticated calls to Supabase APIs and to revoke sessions on sign-out.
-Add `accessToken` and `refreshToken` to `CloudSession` in `auth.store.ts` and
-pass them through from `cloud-auth.ts`.
-
----
-
-## Web Export Notes (jivamai.com)
-
-When `window.electron` is absent (web browser), `isCloudWindow` is `true` and
-`cloud-api.ts` calls Supabase / Cloud Run directly via `fetch`. No IPC layer.
-
-This is partially implemented. What still needs wiring for pure-web mode:
-- Chat routing: `jiva.store.ts sendMessage` currently calls
-  `window.electron.jiva.sendMessage()` unconditionally. In cloud web mode,
-  this is `undefined`. Need to call `cloudApiChat()` from `cloud-api.ts`
-  instead (not yet implemented in the shim).
-- The `cloudApiChat` function needs to be added to `src/lib/cloud-api.ts`,
-  replicating the SSE streaming logic from `cloud-runner.ts` but callable
-  from the renderer without an Electron IPC hop.

package/docs/architecture/code-agent-integration.md

@@ -1,276 +0,0 @@
-# Code Agent Integration
-
-Jivam includes a specialized code agent mode that allows AI agents to directly manipulate files, run commands, and manage code within a user's workspace. This mode operates as a separate agent instance from the main chat interface but uses the same underlying jiva-core technology.
-
----
-
-## Architecture Overview
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  Renderer Process (React)                                   │
-│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐ │
-│  │  Chat Interface │  │  Code Agent UI  │  │   Git Panel │ │
-│  │                 │  │                 │  │             │ │
-│  │ • Message input │  │ • Code prompt   │  │ • File list │ │
-│  │ • Persona chip  │  │ • Event cards   │  │ • Diff view │ │
-│  │ • History       │  │ • Session mgmt  │  │ • Branch    │ │
-│  └─────────────────┘  └─────────────────┘  └─────────────┘ │
-│           │                       │                       │
-│           └───────────────────────┼───────────────────────┘
-│                                   │
-│                    ┌──────────────▼──────────────┐
-│                    │   window.electron.code API   │
-│                    │  (Preload Bridge)           │
-│                    └──────────────┬──────────────┘
-│                                   │
-│                    ┌──────────────▼──────────────┐
-│                    │   Main Process              │
-│                    │  ┌──────────────────────┐  │
-│                    │  │   CodeRunner         │  │
-│                    │  │  ┌─────────────────┐ │  │
-│                    │  │  │ Log Parser      │ │  │
-│                    │  │  │ Event Manager   │ │  │
-│                    │  │  │ Agent Instance  │ │  │
-│                    │  │  └─────────────────┘ │  │
-│                    │  └──────────────────────┘  │
-│                    └───────────────────────────┘
-│                                   │
-│                    ┌──────────────▼──────────────┐
-│                    │   jiva-core SDK             │
-│                    │  ┌──────────────────────┐  │
-│                    │  │   CodeAgent          │  │
-│                    │  │   • File operations  │  │
-│                    │  │   • Command execution│  │
-│                    │  │   • Tool usage       │  │
-│                    │  └──────────────────────┘  │
-│                    └───────────────────────────┘
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Key Components
-
-### CodeRunner (`electron/code-runner.ts`)
-
-The `CodeRunner` class manages a dedicated code agent instance with the following responsibilities:
-
-- **Log Event Parsing**: Intercepts stdout/stderr from jiva-core and converts structured log lines into `CodeLogEvent` objects
-- **Event Management**: Accumulates important events (file edits, warnings, errors) during code execution
-- **Resource Management**: Proper cleanup of agent instances and temporary resources
-- **Real-time Communication**: Streams progress events to the renderer via IPC
-
-#### Log Event Format
-
-jiva-core logs follow this format:
-```
-2026-03-13T10:28:32.695Z [INFO] [CodeAgent] Tool: glob
-2026-03-13T10:28:33.123Z [WARN] [CodeAgent] Doom loop: tool: write_file
-2026-03-13T10:28:33.456Z [ERROR] [CodeAgent] Model error: Invalid file path
-```
-
-#### CodeLogEvent Interface
-
-```typescript
-interface CodeLogEvent {
-  timestamp: string        // ISO timestamp
-  level: 'info' | 'warn' | 'error'
-  tag: string              // Usually 'CodeAgent'
-  message: string          // Raw log message
-}
-```
-
----
-
-### CodeStore (`src/store/code.store.ts`)
-
-The Zustand store that manages code agent state in the renderer:
-
-#### State Management
-
-| State | Type | Description |
-|-------|------|-------------|
-| `messages` | `CodeMessage[]` | Conversation history with code content |
-| `isThinking` | `boolean` | Agent is processing a request |
-| `currentAction` | `string \| null` | Current tool action (e.g., "Writing file...") |
-| `pendingEvents` | `CodeEvent[]` | Events accumulated for current turn |
-
-#### CodeMessage Interface
-
-```typescript
-interface CodeMessage {
-  id: string
-  role: 'user' | 'agent'
-  content: string
-  timestamp: Date
-  events?: CodeEvent[]  // Tool events, warnings, errors
-}
-```
-
-#### CodeEvent Interface
-
-```typescript
-interface CodeEvent {
-  id: string
-  type: 'tool' | 'warn' | 'error'
-  detail: string
-  timestamp: string
-}
-```
-
----
-
-### Event Processing
-
-#### Log to Action Mapping
-
-The system maps log messages to user-friendly action descriptions:
-
-| Log Pattern | Action Display |
-|-------------|----------------|
-| `Tool: read_file` | "Reading files..." |
-| `Tool: write_file` | "Writing file..." |
-| `Tool: edit_file` | "Editing file..." |
-| `Tool: glob` | "Searching files..." |
-| `Tool: grep` | "Searching content..." |
-| `Tool: bash` | "Running command..." |
-| `Nearing iteration limit` | "Wrapping up..." |
-| `Final phase` | "Finalizing..." |
-| `Repaired tool call` | "Retrying..." |
-
-#### Important Event Detection
-
-Events are marked as important and displayed if they:
-
-- Have level `'warn'` or `'error'`
-- Start with `Tool: edit_file`
-- Start with `Tool: write_file`
-- Start with `Tool: bash`
-
----
-
-## IPC Contract
-
-### Code Mode Channels
-
-| Channel | Direction | Description |
-|---------|-----------|-------------|
-| `code:send-message` | invoke | Send code prompt to agent |
-| `code:stop-message` | invoke | Stop active code agent |
-| `code:reset-session` | invoke | Tear down CodeRunner for fresh start |
-| `code:init` | invoke | Initialize CodeRunner |
-
----
-
-## UI Components
-
-### CodeChatView (`src/components/code/CodeChatView.tsx`)
-
-The main code agent interface featuring:
-
-- **Message Display**: User prompts and agent responses with Markdown rendering
-- **Event Cards**: Shows tool execution events above agent responses
-- **Example Prompts**: Quick-start suggestions for common code tasks
-- **Session Management**: New session button to start fresh code work
-
-#### Example Prompts
-
-The interface provides suggested prompts for common code tasks:
-- "Find and fix the bug causing tests to fail"
-- "Refactor this module for better readability"
-- "Add error handling to the API endpoints"
-- "Write a script to automate this task"
-
-### GitPanel (`src/components/code/GitPanel.tsx`)
-
-Integrated Git functionality with:
-
-- **Repository Status**: Shows current branch and sync status (↑ahead, ↓behind)
-- **File List**: Displays changed files with status badges (M, A, D, ??)
-- **Diff Viewer**: Syntax-highlighted diff display with file headers
-- **Branch Information**: Current branch name and upstream tracking
-
-#### Status Badges
-
-| Status | Display | Meaning |
-|--------|---------|---------|
-| `M` / `MM` | ⚠️ M | Modified files |
-| `A` | ✅ A | Added files |
-| `D` | 🗑️ D | Deleted files |
-| `??` | ❓ ? | Untracked files |
-| `R` | 🔄 R | Renamed files |
-
----
-
-## Data Flow
-
-### Code Execution Flow
-
-1. **User Input**: User types code prompt in CodeChatView
-2. **IPC Call**: `window.electron.code.sendMessage(prompt)`
-3. **Agent Initialization**: CodeRunner creates/configures CodeAgent instance
-4. **Log Interception**: stdout/stderr captured and parsed into structured events
-5. **Event Processing**: Important events accumulated and sent to renderer
-6. **Response Delivery**: Final code response returned with event history
-7. **UI Update**: CodeChatView displays response with event cards
-
-### Event Flow
-
-```
-jiva-core stdout/stderr
-        ↓
-Log Parser (parseLogLine)
-        ↓
-CodeLogEvent objects
-        ↓
-isImportantEvent() filter
-        ↓
-CodeEvent objects
-        ↓
-window.electron.code.onCodeLog callback
-        ↓
-useCodeStore.pendingEvents update
-        ↓
-Event cards displayed in UI
-```
-
----
-
-## Configuration
-
-### Code Mode Settings
-
-The code agent respects the same configuration as the main jiva-core system:
-
-- **Model Configuration**: Reasoning model settings from `config.json`
-- **Workspace Directory**: Current working directory for file operations
-- **Persona System**: Can use different personas for code vs chat modes
-- **MCP Servers**: Same tool servers available to both chat and code modes
-
-### Workspace Security
-
-Code operations are restricted to the user's home directory for security:
-
-- File operations limited to `$HOME` (Windows: `%APPDATA%`)
-- Path validation prevents directory traversal attacks
-- Large files (>500KB) blocked from preview, require external editor
-
----
-
-## Error Handling
-
-### Common Error Scenarios
-
-- **Agent Not Initialized**: CodeRunner not ready, requires `code:init` first
-- **Workspace Not Set**: No workspace directory configured
-- **Permission Denied**: File operations blocked by system permissions
-- **Large Files**: Files >500KB rejected for preview
-- **Invalid Paths**: Non-existent or inaccessible directories
-
-### Error Recovery
-
-- **Session Reset**: `code:reset-session` clears corrupted state
-- **Agent Restart**: Automatic re-initialization on errors
-- **Graceful Degradation**: UI continues working even if agent fails
-- **User Notifications**: Clear error messages with actionable guidance