jawere 1.0.13

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 jawere
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# jawere — AI Coding Agent
+
+Terminal-based AI coding assistant powered by DeepSeek. Runs as an interactive REPL — describe tasks in natural language, and the agent reads, edits, writes, and executes shell commands autonomously.
+
+## Features
+
+- **Autonomous Agent Loop** — Tool-calling loop (up to 500 turns) with seven filesystem tools
+- **Codebase Scanner** — Pre-scans the project on startup, generating `.codebase/tree.yaml` and `.codebase/meta.json` so the LLM has structural context before the first prompt
+- **Interactive REPL** — Multiline input (Shift+Enter), session resumption, and persistent conversation history backed by Convex
+- **Encrypted API Key** — AES-256-GCM encrypted key storage at `~/.jawere/key.enc`
+- **Session Persistence** — Full message history, tool calls, and token usage stored in Convex
+- **Dual Environment** — Dev/prod modes with separate Convex deployments
+
+## Quick Start
+
+```bash
+git clone git@github.com:jawere/agent.git
+cd agent
+npm install
+npx tsx src/index.ts --setup   # one-time API key setup
+npm start
+```
+
+Or set the key via environment variable:
+
+```bash
+export DEEPSEEK_API_KEY=sk-...
+npm start
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show available commands |
+| `/sessions` | List recent Convex sessions |
+| `/load <id>` | Resume a previous session |
+| `/key` | Show API key status |
+| `/setup` | Re-enter and save API key |
+| `/clear` | Clear screen and start fresh |
+| `/exit`, `/quit` | Exit |
+
+## Tools
+
+The LLM has access to seven filesystem tools:
+
+- `bash` — Execute shell commands with configurable timeout (max 300s). Output truncated at 2000 lines / 50KB.
+- `read` — Read file contents with line offset/limit for large files.
+- `edit` — Precise exact-text replacement with uniqueness validation. Supports batched edits.
+- `write` — Create or overwrite files. Auto-creates parent directories.
+- `ls` — List directory contents with sizes.
+- `find` — Find files by fuzzy name or glob pattern. Skips hidden dirs and node_modules.
+- `grep` — Search file contents with regex. Supports file glob filtering.
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DEEPSEEK_API_KEY` | — | DeepSeek API key |
+| `DEEPSEEK_MODEL` | `deepseek-v4-pro` | Model name |
+| `WORK_DIR` | `process.cwd()` | Working directory |
+| `CONVEX_URL` | auto | Convex deployment URL |
+| `NODE_ENV` | auto-detected | `development` or `production` |
+
+## Project Structure
+
+```
+├── bin/jawere.js              # CLI entry point (global install)
+├── src/
+│   ├── index.ts               # REPL main loop, command handling
+│   ├── agent.ts               # Agent loop: LLM calls + tool execution
+│   ├── config.ts              # Configuration (env, key, mode)
+│   ├── tools.ts               # Tool definitions & implementations
+│   ├── convex-client.ts       # HTTP client for Convex backend
+│   ├── crypto.ts              # Encrypted API key storage (AES-256-GCM)
+│   ├── scanner.ts             # Codebase pre-scanner (.codebase/)
+│   ├── spinner.ts             # Terminal spinner animations
+│   └── system-prompt.ts       # System prompt template
+├── convex/                    # Convex backend (schema, mutations, queries)
+├── scripts/build.js           # esbuild bundler
+├── dist/                      # Compiled output
+├── package.json
+└── tsconfig.json
+```
+
+## Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm start` | Run in dev mode |
+| `npm run start:prod` | Run in prod mode |
+| `npm run build` | Bundle with esbuild |
+| `npm run dev` | Run `convex dev` for backend |
+| `npm run deploy:dev` | Deploy Convex backend (dev) |
+| `npm run deploy:prod` | Deploy Convex backend (prod) |
+| `npm run seed:dev` | Seed dev database |
+| `npm run seed:prod` | Seed prod database |
+
+## License
+
+MIT

package/bin/jawere.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import('../dist/index.js').catch((err) => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});

package/dist/agent.d.ts

@@ -0,0 +1,15 @@
+import type { ChatCompletionMessageParam } from 'openai/resources/chat/completions';
+export interface AgentOptions {
+    sessionId?: string;
+    title?: string;
+    history?: ChatCompletionMessageParam[];
+    signal?: AbortSignal;
+}
+export interface AgentResult {
+    text: string;
+    sessionId: string;
+    history: ChatCompletionMessageParam[];
+}
+/** Print the assistant's FINAL response — the summary shown when all work is done. */
+export declare function printAssistantResponse(text: string): void;
+export declare function runAgent(userMessage: string, options?: AgentOptions): Promise<AgentResult>;

package/dist/agent.js

@@ -0,0 +1,321 @@
+import OpenAI from 'openai';
+import { SYSTEM_PROMPT } from './system-prompt.js';
+import { TOOL_DEFS, executeTool } from './tools.js';
+import { loadConfig } from './config.js';
+import { createSpinner } from './spinner.js';
+import { createSession, appendUserMessage, appendAssistantMessage, appendToolResult, } from './convex-client.js';
+const MAX_TURNS = 500;
+const MAX_OUTPUT_TOKENS = 300_000; // 300k max output tokens
+// ── Terminal display helpers ────────────────────────────────────────
+const COL = () => process.stdout.columns || 80;
+// Gruvbox color palette
+const GRUVBOX_GREEN = '\x1b[38;2;184;187;3m'; // bright green #b8bb26
+const GRUVBOX_GRAY = '\x1b[38;2;146;131;116m'; // gray #928374
+const GRUVBOX_RED = '\x1b[38;2;251;73;52m'; // bright red #fb4934
+const GRUVBOX_FG = '\x1b[38;2;235;219;178m'; // foreground #ebdbb2
+const GRUVBOX_DIM = '\x1b[38;2;102;92;84m'; // dark gray #665c54
+const GRUVBOX_AQUA = '\x1b[38;2;142;192;124m'; // aqua #8ec07c
+const RESET = '\x1b[0m';
+/** File-oriented tools get green; bash/grep/find get grey */
+const FILE_TOOLS = new Set(['read', 'write', 'edit']);
+/** Build a compact tool detail string from args */
+function toolDetail(name, args) {
+    switch (name) {
+        case 'read': {
+            let d = String(args.path || '?');
+            if (args.offset)
+                d += ` [L${args.offset}${args.limit ? `-${Number(args.offset) + Number(args.limit) - 1}` : '+'}]`;
+            return d;
+        }
+        case 'write':
+            return String(args.path || '?');
+        case 'edit': {
+            let d = String(args.path || '?');
+            if (Array.isArray(args.edits))
+                d += ` (${args.edits.length} edit${args.edits.length !== 1 ? 's' : ''})`;
+            return d;
+        }
+        case 'bash':
+        case 'grep':
+        case 'find':
+        case 'ls':
+            return String(args.command || args.pattern || args.path || '?');
+        default:
+            return JSON.stringify(args);
+    }
+}
+/** Print a compact tool line: "  tool: detail…  ✓" with status right-aligned.
+ *  Before printing, stop the spinner so the line renders clean. */
+function displayToolLine(name, args, ok, spin) {
+    // Stop spinner temporarily to print the tool line cleanly
+    if (spin?.running) {
+        spin.stop();
+    }
+    const statusIcon = ok ? '✓' : '✗';
+    const statusColor = ok ? GRUVBOX_GREEN : GRUVBOX_RED;
+    const toolColor = FILE_TOOLS.has(name) ? GRUVBOX_GREEN : GRUVBOX_GRAY;
+    const prefix = `${toolColor}${name}${RESET}: `;
+    const suffix = ` ${statusColor}${statusIcon}${RESET}`;
+    let detail = toolDetail(name, args);
+    process.stdout.write(`${prefix}${detail}${suffix}\n`);
+    // Restart spinner after the tool line
+    if (spin) {
+        spin.start('Working…');
+    }
+}
+// ── Convex helpers ──────────────────────────────────────────────────
+async function safeCall(fn, label) {
+    try {
+        return await fn();
+    }
+    catch {
+        return undefined;
+    }
+}
+// ── API retry with exponential backoff ─────────────────────────────
+async function withRetry(fn, maxRetries = 3, baseDelay = 1000) {
+    let lastErr;
+    for (let i = 0; i <= maxRetries; i++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastErr = err;
+            if (err.name === 'AbortError' || err.name === 'Canceled')
+                throw err;
+            if (i < maxRetries && (err.status === 429 || err.status >= 500)) {
+                const delay = baseDelay * Math.pow(2, i) + Math.random() * 1000;
+                process.stderr.write(`${GRUVBOX_GRAY}[retry ${i + 1}/${maxRetries}] ${err.status || 'error'}, waiting ${(delay / 1000).toFixed(1)}s...${RESET}\n`);
+                await new Promise((r) => setTimeout(r, delay));
+                continue;
+            }
+            throw lastErr;
+        }
+    }
+    throw lastErr;
+}
+// ── Response formatting ─────────────────────────────────────────────
+function stripThinking(text) {
+    let cleaned = text.replace(/<thinking[^>]*>[\s\S]*?<\/thinking>/gi, '');
+    cleaned = cleaned.replace(/<\/think>[\s\S]*?<\/think>/g, '');
+    cleaned = cleaned.replace(/\n{3,}/g, '\n\n');
+    return cleaned.trim();
+}
+/** Print the assistant's FINAL response — the summary shown when all work is done. */
+export function printAssistantResponse(text) {
+    const cols = COL();
+    const FG = '\x1b[38;2;235;219;178m'; // #ebdbb2
+    const YELLOW = '\x1b[38;2;250;189;47m'; // #fabd2f
+    const BLUE = '\x1b[38;2;131;165;152m'; // #83a598
+    const GRAY = '\x1b[38;2;146;131;116m'; // #928374
+    const DIM = '\x1b[38;2;102;92;84m'; // #665c54
+    const CODE = '\x1b[38;2;213;196;161m'; // #d5c4a1
+    const AQUA = '\x1b[38;2;142;192;124m'; // #8ec07c
+    const RESET2 = '\x1b[0m';
+    const pathRe = /\b(?:\.?\/?[\w.-]+)+\/[\w.-]+(?:\/[\w.-]+)*(?:\.\w+)?\b/;
+    const sep = DIM + '─'.repeat(Math.min(cols - 2, 60)) + RESET2;
+    console.log('');
+    console.log(sep);
+    const lines = text.split('\n');
+    for (const line of lines) {
+        const stripped = line.replace(/\x1b\[[0-9;]*m/g, '');
+        if (stripped.trim() === '') {
+            console.log('');
+            continue;
+        }
+        if (/^[─═━]{3,}/.test(stripped.trim()) && stripped.trim().length > 3) {
+            console.log(DIM + line + RESET2);
+            continue;
+        }
+        if (/^\s*─+\s*.+\s*─+\s*$/.test(stripped)) {
+            console.log(YELLOW + line + RESET2);
+            continue;
+        }
+        let baseColor = FG;
+        let bulletMarker = '';
+        let bulletRest = '';
+        let bulletPrefix = '';
+        const bulletMatch = stripped.match(/^(\s*)([•\-]|\d+\.)(\s)/);
+        if (bulletMatch) {
+            bulletPrefix = line.slice(0, bulletMatch[1].length);
+            bulletMarker = line.slice(bulletMatch[1].length, bulletMatch[1].length + bulletMatch[2].length);
+            bulletRest = line.slice(bulletMatch[1].length + bulletMatch[2].length);
+        }
+        else if (/^ {2,}(?!•|-|\d+\.)(\S)/.test(stripped)) {
+            baseColor = CODE;
+        }
+        const content = bulletMatch ? bulletRest : line;
+        if (pathRe.test(stripped)) {
+            let colored = '';
+            let lastIdx = 0;
+            let match;
+            const re = new RegExp(pathRe.source, 'g');
+            while ((match = re.exec(content)) !== null) {
+                colored += content.slice(lastIdx, match.index) + BLUE + match[0] + RESET2;
+                lastIdx = match.index + match[0].length;
+            }
+            colored += content.slice(lastIdx);
+            if (bulletMatch) {
+                console.log(bulletPrefix + AQUA + bulletMarker + RESET2 + baseColor + colored + RESET2);
+            }
+            else {
+                console.log(baseColor + colored + RESET2);
+            }
+        }
+        else if (bulletMatch) {
+            console.log(bulletPrefix + AQUA + bulletMarker + RESET2 + baseColor + bulletRest + RESET2);
+        }
+        else {
+            console.log(baseColor + line + RESET2);
+        }
+    }
+    console.log(sep);
+    console.log('');
+}
+// ── Agent loop ──────────────────────────────────────────────────────
+export async function runAgent(userMessage, options = {}) {
+    const config = await loadConfig();
+    if (!config.apiKey) {
+        throw new Error('No API key configured. Run with --setup to save your DeepSeek API key, or set DEEPSEEK_API_KEY env var.');
+    }
+    const client = new OpenAI({
+        baseURL: config.baseURL,
+        apiKey: config.apiKey,
+    });
+    const toolNames = TOOL_DEFS.map((t) => t.function.name);
+    // Create or resume Convex session (best-effort)
+    let sessionId = options.sessionId || 'local';
+    const hasRealSession = sessionId !== 'local';
+    const isNewSession = !options.sessionId;
+    if (isNewSession) {
+        const created = await safeCall(() => createSession(config.convexUrl, options.title || userMessage.slice(0, 100), config.model, SYSTEM_PROMPT, toolNames), 'createSession');
+        if (created)
+            sessionId = created;
+    }
+    if (hasRealSession || sessionId !== 'local') {
+        safeCall(() => appendUserMessage(config.convexUrl, sessionId, userMessage), 'appendUserMessage');
+    }
+    // Build message array: system prompt + existing history + new user message
+    const messages = [
+        { role: 'system', content: SYSTEM_PROMPT },
+    ];
+    if (options.history && options.history.length > 0) {
+        for (const m of options.history) {
+            if (m.role !== 'system') {
+                messages.push(m);
+            }
+        }
+    }
+    messages.push({ role: 'user', content: userMessage });
+    // ── Spinner for the agent loop ─────────────────────────────────
+    const spin = createSpinner();
+    spin.start('Thinking…');
+    for (let turn = 0; turn < MAX_TURNS; turn++) {
+        // Check for cancellation (Ctrl+C)
+        if (options.signal?.aborted) {
+            spin.stop();
+            const msg = '\n[Cancelled by user]';
+            process.stderr.write(`${msg}\n`);
+            return { text: msg, sessionId, history: messages };
+        }
+        // Update spinner message before API call
+        spin.update('Thinking…');
+        const response = await withRetry(() => {
+            return client.chat.completions.create({
+                model: config.model,
+                messages,
+                tools: TOOL_DEFS,
+                tool_choice: 'auto',
+                temperature: 0.2,
+                max_tokens: MAX_OUTPUT_TOKENS,
+                // Enable thinking/reasoning — DeepSeek specific params
+                ...{
+                    thinking: { type: 'enabled' },
+                    reasoning_effort: 'max',
+                },
+            });
+        }).catch((err) => {
+            if (err.name === 'AbortError' || err.name === 'Canceled') {
+                return null;
+            }
+            throw err;
+        });
+        // Cancelled mid-request
+        if (!response) {
+            spin.stop();
+            const msg = '\n[Cancelled by user]';
+            return { text: msg, sessionId, history: messages };
+        }
+        const choice = response.choices[0];
+        if (!choice) {
+            spin.stop();
+            safeCall(() => appendAssistantMessage(config.convexUrl, sessionId, '(error: no response)', null), 'appendAssistantMessage');
+            return { text: 'Error: No response from model.', sessionId, history: messages };
+        }
+        const { message } = choice;
+        const usage = response.usage
+            ? {
+                input: response.usage.prompt_tokens || 0,
+                output: response.usage.completion_tokens || 0,
+                total: response.usage.total_tokens || 0,
+            }
+            : undefined;
+        // ── Tool calls — show what commands are being executed ─────────
+        if (message.tool_calls && message.tool_calls.length > 0) {
+            const toolCallsMeta = message.tool_calls.map((tc) => ({
+                id: tc.id,
+                name: tc.function.name,
+                arguments: tc.function.arguments,
+            }));
+            safeCall(() => appendAssistantMessage(config.convexUrl, sessionId, message.content || null, toolCallsMeta.length > 0 ? toolCallsMeta : null, usage), 'appendAssistantMessage');
+            messages.push({
+                role: 'assistant',
+                content: message.content || null,
+                tool_calls: message.tool_calls,
+            });
+            // Execute each tool call, showing what's running
+            for (const tc of message.tool_calls) {
+                let args = {};
+                try {
+                    args = JSON.parse(tc.function.arguments);
+                }
+                catch { /* keep empty */ }
+                // Update spinner to show what we're about to run
+                spin.update(`Running ${tc.function.name}…`);
+                const result = await executeTool({
+                    id: tc.id,
+                    function: {
+                        name: tc.function.name,
+                        arguments: tc.function.arguments,
+                    },
+                }, config.workDir);
+                const ok = !result.content.startsWith('Error');
+                // Display the tool line (stops spinner, prints line, restarts spinner)
+                displayToolLine(tc.function.name, args, ok, spin);
+                messages.push({
+                    role: 'tool',
+                    tool_call_id: result.tool_call_id,
+                    content: result.content,
+                });
+                const isError = !ok;
+                safeCall(() => appendToolResult(config.convexUrl, sessionId, result.tool_call_id, tc.function.name, result.content, isError), 'appendToolResult');
+            }
+            // Continue loop to next API call (spinner still running)
+            continue;
+        }
+        // ── Final text response — the summary ──────────────────────────
+        spin.stop();
+        const rawText = message.content || '';
+        const text = stripThinking(rawText) || '(empty response)';
+        safeCall(() => appendAssistantMessage(config.convexUrl, sessionId, text, null, usage), 'appendAssistantMessage');
+        // Print a blank line then the final summary
+        console.log('');
+        printAssistantResponse(text);
+        return { text, sessionId, history: messages };
+    }
+    // Max turns reached
+    spin.stop();
+    const msg = 'Agent reached maximum turns without completing the task.';
+    safeCall(() => appendAssistantMessage(config.convexUrl, sessionId, msg, null), 'appendAssistantMessage');
+    return { text: msg, sessionId, history: messages };
+}

package/dist/config.d.ts

@@ -0,0 +1,19 @@
+export interface Config {
+    /** DeepSeek API base URL */
+    baseURL: string;
+    /** API key (loaded from encrypted storage or env var) */
+    apiKey: string;
+    /** Model name */
+    model: string;
+    /** Working directory */
+    workDir: string;
+    /** Convex deployment URL */
+    convexUrl: string;
+    /** Whether the key came from encrypted storage */
+    keyFromFile: boolean;
+    /** Whether running in dev mode */
+    isDev: boolean;
+}
+export declare function loadConfig(): Promise<Config>;
+/** Check if an API key is configured */
+export declare function hasApiKey(): Promise<boolean>;

package/dist/config.js

@@ -0,0 +1,53 @@
+import { loadKey, hasKey } from './crypto.js';
+// Convex deployments
+const CONVEX_DEV = 'https://dazzling-jackal-33.convex.cloud';
+const CONVEX_PROD = 'https://friendly-pigeon-624.convex.cloud';
+function isDevMode() {
+    // Explicit env var always wins
+    if (process.env.NODE_ENV === 'production')
+        return false;
+    if (process.env.NODE_ENV === 'development')
+        return true;
+    // Heuristic: running via tsx (src/*.ts) = dev; compiled dist/*.js = prod
+    const main = process.argv[1] || '';
+    if (main.endsWith('.ts') || main.includes('/src/'))
+        return true;
+    // Heuristic: node_modules/.bin or global install = prod
+    if (main.includes('/node_modules/') || main.includes('/.local/lib/node_modules/'))
+        return false;
+    // Default to dev (safer for local dev)
+    return true;
+}
+let cachedConfig = null;
+export async function loadConfig() {
+    if (cachedConfig)
+        return cachedConfig;
+    // Try encrypted file first, then env var
+    let apiKey = '';
+    let keyFromFile = false;
+    const savedKey = await loadKey();
+    if (savedKey) {
+        apiKey = savedKey;
+        keyFromFile = true;
+    }
+    else if (process.env.DEEPSEEK_API_KEY) {
+        apiKey = process.env.DEEPSEEK_API_KEY;
+    }
+    const isDev = isDevMode();
+    cachedConfig = {
+        baseURL: 'https://api.deepseek.com/v1',
+        apiKey,
+        model: process.env.DEEPSEEK_MODEL || 'deepseek-v4-pro',
+        workDir: process.env.WORK_DIR || process.cwd(),
+        convexUrl: process.env.CONVEX_URL || (isDev ? CONVEX_DEV : CONVEX_PROD),
+        keyFromFile,
+        isDev,
+    };
+    return cachedConfig;
+}
+/** Check if an API key is configured */
+export async function hasApiKey() {
+    if (process.env.DEEPSEEK_API_KEY)
+        return true;
+    return hasKey();
+}

package/dist/convex-client.d.ts

@@ -0,0 +1,41 @@
+export interface SessionInfo {
+    _id: string;
+    _creationTime: number;
+    title: string;
+    model: string;
+    systemPrompt: string;
+    toolNames: string[];
+    createdAt: number;
+    updatedAt: number;
+}
+export interface MessageContent {
+    type: string;
+    text?: string;
+    id?: string;
+    name?: string;
+    arguments?: unknown;
+    toolCallId?: string;
+    content?: string;
+}
+/** Create a new session in Convex. Returns the session ID. */
+export declare function createSession(convexUrl: string, title: string, model: string, systemPrompt: string, toolNames: string[]): Promise<string>;
+/** Append a user message to the session */
+export declare function appendUserMessage(convexUrl: string, sessionId: string, text: string): Promise<string>;
+/** Append an assistant message (with optional tool calls and usage) */
+export declare function appendAssistantMessage(convexUrl: string, sessionId: string, text: string | null, toolCalls: Array<{
+    id: string;
+    name: string;
+    arguments: string;
+}> | null, usage?: {
+    input: number;
+    output: number;
+    total: number;
+}): Promise<string>;
+/** Append a tool result message */
+export declare function appendToolResult(convexUrl: string, sessionId: string, toolCallId: string, toolName: string, result: string, isError: boolean): Promise<string>;
+/** List recent sessions */
+export declare function listSessions(convexUrl: string): Promise<SessionInfo[]>;
+/** Get a full session with messages */
+export declare function getSession(convexUrl: string, sessionId: string): Promise<(SessionInfo & {
+    messages: any[];
+}) | null>;

package/dist/convex-client.js

@@ -0,0 +1,99 @@
+// ── Types ───────────────────────────────────────────────────────────
+// ── Convex HTTP helpers ─────────────────────────────────────────────
+async function convexMutation(convexUrl, name, args) {
+    const res = await fetch(`${convexUrl}/api/mutation`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ path: name, format: 'json', args }),
+    });
+    if (!res.ok) {
+        const err = await res.text();
+        throw new Error(`Convex mutation ${name} failed (${res.status}): ${err}`);
+    }
+    const json = await res.json();
+    if (json.status === 'error') {
+        throw new Error(`Convex mutation ${name} error: ${json.errorMessage || JSON.stringify(json)}`);
+    }
+    // Convex wraps results in { status: "success", value: ... }
+    return json.value;
+}
+async function convexQuery(convexUrl, name, args) {
+    const res = await fetch(`${convexUrl}/api/query`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ path: name, format: 'json', args }),
+    });
+    if (!res.ok) {
+        const err = await res.text();
+        throw new Error(`Convex query ${name} failed (${res.status}): ${err}`);
+    }
+    const json = await res.json();
+    if (json.status === 'error') {
+        throw new Error(`Convex query ${name} error: ${json.errorMessage || JSON.stringify(json)}`);
+    }
+    // Convex wraps results in { status: "success", value: ... }
+    return json.value;
+}
+// ── Session operations ──────────────────────────────────────────────
+/** Create a new session in Convex. Returns the session ID. */
+export async function createSession(convexUrl, title, model, systemPrompt, toolNames) {
+    return convexMutation(convexUrl, 'sessions:create', {
+        title,
+        model,
+        systemPrompt,
+        toolNames,
+    });
+}
+/** Append a user message to the session */
+export async function appendUserMessage(convexUrl, sessionId, text) {
+    return convexMutation(convexUrl, 'sessions:appendMessage', {
+        sessionId,
+        role: 'user',
+        content: [{ type: 'text', text }],
+        timestamp: Date.now(),
+    });
+}
+/** Append an assistant message (with optional tool calls and usage) */
+export async function appendAssistantMessage(convexUrl, sessionId, text, toolCalls, usage) {
+    const content = [];
+    if (text) {
+        content.push({ type: 'text', text });
+    }
+    if (toolCalls) {
+        for (const tc of toolCalls) {
+            content.push({
+                type: 'tool_call',
+                id: tc.id,
+                name: tc.name,
+                arguments: tc.arguments,
+            });
+        }
+    }
+    return convexMutation(convexUrl, 'sessions:appendMessage', {
+        sessionId,
+        role: 'assistant',
+        content,
+        timestamp: Date.now(),
+        usage,
+    });
+}
+/** Append a tool result message */
+export async function appendToolResult(convexUrl, sessionId, toolCallId, toolName, result, isError) {
+    return convexMutation(convexUrl, 'sessions:appendMessage', {
+        sessionId,
+        role: 'toolResult',
+        content: [{ type: 'tool_result', toolCallId, content: result }],
+        toolCallId,
+        toolName,
+        isError,
+        timestamp: Date.now(),
+    });
+}
+/** List recent sessions */
+export async function listSessions(convexUrl) {
+    return convexQuery(convexUrl, 'sessions:list', {});
+}
+/** Get a full session with messages */
+export async function getSession(convexUrl, sessionId) {
+    return convexQuery(convexUrl, 'sessions:get', { sessionId });
+}