@loicngr/kobo 1.4.10 → 1.4.12

package/AGENTS.md

@@ -16,9 +16,9 @@ Single-user, single-machine dev tool. No auth, no multi-tenant concerns.
 
 **Database** — Single SQLite file under the **Kōbō home directory** (`~/.config/kobo/kobo.db` by default, overridable via `KOBO_HOME`). Fresh-install schema lives in `src/server/db/schema.ts` (`initSchema`); incremental migrations live in `src/server/db/migrations.ts`. **The project is in production** — every schema change MUST ship as a migration that preserves data, never as a breaking change to `initSchema` alone. See [Database migrations](#database-migrations) below.
 
-**Kōbō home directory** — `KOBO_HOME` env var overrides everything. Otherwise `$XDG_CONFIG_HOME/kobo/`, else `~/.config/kobo/`. Contains `kobo.db`, `settings.json`, `skills.json`. **Development uses `./data/`** via the `KOBO_HOME=./data` prefix in the `dev` npm script, so local dev never touches your real `~/.config/kobo/` and can run in parallel with a production-installed Kōbō (`npx @loicngr/kobo`). See `src/server/utils/paths.ts`.
+**Kōbō home directory** — `KOBO_HOME` env var overrides everything. Otherwise `$XDG_CONFIG_HOME/kobo/`, else `~/.config/kobo/`. Contains `kobo.db`, `settings.json`, `skills.json`, `templates.json`. **Development uses `./data/`** via the `KOBO_HOME=./data` prefix in the `dev` npm script, so local dev never touches your real `~/.config/kobo/` and can run in parallel with a production-installed Kōbō (`npx @loicngr/kobo`). See `src/server/utils/paths.ts`.
 
-**Tests** — vitest (18 test files, 355+ tests at time of writing). No frontend test infrastructure.
+**Tests** — vitest (24 backend test files, 544+ tests; 5 frontend test files, 45+ tests at time of writing). Frontend tests cover Pinia stores and pure utility modules; Vue components are not tested (type-check + manual smoke only).
 
 ## Commands
 
@@ -33,8 +33,10 @@ npm run dev:client                  # frontend only (quasar dev)
 npm run dev:all                     # both concurrently
 
 # Check & test
-npx tsc --noEmit                    # type check (the project's primary quality gate)
-npm test                            # run full vitest suite
+npm run lint                        # biome check (linting + formatting)
+npx tsc --noEmit                    # type check backend (the project's primary quality gate)
+npm test                            # run full vitest suite (backend + client tests)
+(cd src/client && npm test)         # client tests only (stores, utils)
 npm run test:watch                  # vitest in watch mode
 
 # Build & run
@@ -56,7 +58,8 @@ src/
 │   │   └── migrations.ts           # incremental migrations, bumped per feature
 │   ├── services/                   # business logic — pure functions over db + external processes
 │   │   ├── workspace-service.ts    # workspaces + tasks + agent_sessions CRUD
-│   │   ├── agent-manager.ts        # spawns Claude Code CLI, streams stdout, tracks sessions
+│   │   ├── agent-manager.ts        # spawns Claude Code CLI, streams stdout, tracks sessions, interrupt/stop
+│   │   ├── templates-service.ts    # prompt templates CRUD (JSON file persistence, seeding)
 │   │   ├── dev-server-service.ts   # per-workspace dev server lifecycle (docker or npm process)
 │   │   ├── websocket-service.ts    # emit / emitEphemeral to subscribed clients
 │   │   ├── worktree-service.ts     # git worktree create/remove
@@ -65,14 +68,17 @@ src/
 │   │   └── pr-template-service.ts  # pure template variable substitution
 │   ├── routes/                     # Hono handlers, thin layer over services
 │   │   ├── workspaces.ts           # /api/workspaces/* — the main surface
+│   │   ├── templates.ts            # /api/templates — prompt templates CRUD
+│   │   ├── plans.ts                # /api/workspaces/:id/plans — plan file browser (read-only)
 │   │   ├── dev-server.ts, git.ts, notion.ts, settings.ts
 │   ├── utils/
-│   │   ├── git-ops.ts              # pushBranch, getCommitsBetween, delete{Local,Remote}Branch…
+│   │   ├── git-ops.ts              # pushBranch, pullBranch, getCommitsBetween, delete{Local,Remote}Branch…
 │   │   └── process-tracker.ts      # per-workspace spawned-process map
 ├── client/                         # Vue 3 + Quasar SPA
 │   └── src/
-│       ├── stores/                 # pinia: workspace, websocket, settings, dev-server
-│       ├── components/             # WorkspaceList, NotionPanel, AcceptancePanel, ChatInput, GitPanel…
+│       ├── stores/                 # pinia: workspace, websocket, settings, dev-server, templates
+│       ├── components/             # WorkspaceList, NotionPanel, AcceptancePanel, ChatInput, GitPanel, PlansPanel…
+│       ├── utils/                  # expand-template (template variable substitution), formatters…
 │       ├── pages/                  # WorkspacePage, CreatePage, SettingsPage
 │       └── router/
 ├── mcp-server/                     # standalone MCP server spawned per workspace
@@ -87,7 +93,7 @@ src/
 |---|---|
 | `workspaces` | the unit of work — id, name, project_path, source_branch, working_branch, status, notion_url, model, dev_server_status, `archived_at`, timestamps |
 | `tasks` | workspace sub-items — title, status, `is_acceptance_criterion`, sort_order; CASCADE DELETE on workspace |
-| `agent_sessions` | Claude Code CLI invocations — pid, `claude_session_id`, status, started_at, ended_at |
+| `agent_sessions` | Claude Code CLI invocations — pid, `claude_session_id`, status, started_at, ended_at, `name` |
 | `ws_events` | persisted WebSocket events for replay on reconnect — type, payload, session_id, created_at |
 
 `status` enum: `created | extracting | brainstorming | executing | completed | idle | error | quota`. Transitions are validated in `updateWorkspaceStatus` against `VALID_TRANSITIONS`.
@@ -188,7 +194,7 @@ The frontend uses `vue-i18n` v10 with 5 supported locales: English (`en`), Frenc
 
 - **TDD for backend** — write the failing test, confirm it fails for the right reason, implement minimally, confirm it passes, commit. One commit per logical unit. See existing tests in `src/__tests__/workspace-service.test.ts` for the setup pattern (fresh in-memory DB per test via `resetDb()`).
 - **Route tests** use `vi.mock()` on service modules before imports (see `src/__tests__/routes-workspaces.test.ts`). Keep mocks complete — missing exports cause obscure failures.
-- **No frontend test infra.** Type-check via `npx tsc --noEmit` is the frontend gate. Manual smoke testing covers UI behavior.
+- **Frontend tests** cover Pinia stores (`workspace-store`, `settings-store`, `templates-store`) and pure utility modules (`expand-template`). Run with `cd src/client && npm test`. Vue components are **not** tested — type-check via `npx tsc --noEmit` + manual smoke testing covers UI behavior.
 - **`beforeEach(() => vi.clearAllMocks())`** is the convention for all route test files.
 
 ## Git workflow

package/README.md

@@ -17,7 +17,11 @@ Think of it as an apprentice's hall: you hand out missions, each apprentice sets
 - **Notion integration** — pull workspace missions straight from Notion pages, extract markdown, and use it as the source of truth for acceptance criteria
 - **Per-workspace dev servers** — start/stop Docker or Node dev servers scoped to each branch, with log streaming
 - **Conventional-commit enforcement** — project-level git conventions are written to `.ai/.git-conventions.md` inside every workspace so Claude follows them during commits
-- **Pull request automation** — one-click `push` and `open-pr` endpoints integrate with the GitHub CLI, using a configurable prompt template
+- **Pull request automation** — one-click `push`, `pull`, and `open-pr` endpoints integrate with the GitHub CLI, using a configurable prompt template
+- **Multi-session support** — create multiple Claude agent sessions per workspace, each with its own chat history; resume completed sessions via `--resume`; sessions are named and persisted in localStorage
+- **Prompt templates** — personal library of reusable prompts with variable substitution (`{working_branch}`, `{commit_count}`, etc.), insertable from the chat input via `/` autocomplete; editable in Settings > Templates
+- **Plan browser** — read-only viewer for markdown plan files produced by agents, rendered directly in the right-side panel
+- **Soft interrupt** — pause an agent mid-execution (SIGINT, like pressing Escape in Claude Code) without killing the process; the agent stops the current tool and waits for the next message
 - **Archive instead of delete** — soft-remove workspaces without losing the worktree, branches, or history; unarchive restores the exact pre-archive state
 
 ## Tech stack

package/dist/mcp-server/kobo-tasks-server.js

@@ -319,7 +319,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             if (fs.existsSync(thoughtsDir)) {
                 const files = fs.readdirSync(thoughtsDir).filter((f) => f.endsWith('.md'));
                 for (const file of files) {
-                    ticketContent += fs.readFileSync(path.join(thoughtsDir, file), 'utf-8') + '\n';
+                    ticketContent += `${fs.readFileSync(path.join(thoughtsDir, file), 'utf-8')}\n`;
                 }
             }
             return ok({

package/dist/server/db/migrations.js

@@ -26,6 +26,37 @@ export const migrations = [
             db.prepare('ALTER TABLE workspaces ADD COLUMN has_unread INTEGER NOT NULL DEFAULT 0').run();
         },
     },
+    {
+        version: 5,
+        name: 'add-agent-session-name',
+        migrate: (db) => {
+            db.exec('ALTER TABLE agent_sessions ADD COLUMN name TEXT');
+        },
+    },
+    {
+        version: 6,
+        name: 'backfill-ws-events-session-id',
+        migrate: (db) => {
+            // Before this release, ws_events.session_id stored the Claude-generated
+            // session ID. The frontend now filters by agent_sessions.id (internal nanoid),
+            // so existing rows are invisible in the activity feed. Rewrite any
+            // ws_events.session_id that matches an agent_sessions.claude_session_id to
+            // the corresponding agent_sessions.id.
+            db.exec(`
+        UPDATE ws_events
+        SET session_id = (
+          SELECT a.id FROM agent_sessions a
+          WHERE a.claude_session_id = ws_events.session_id
+          LIMIT 1
+        )
+        WHERE session_id IS NOT NULL
+          AND EXISTS (
+            SELECT 1 FROM agent_sessions a
+            WHERE a.claude_session_id = ws_events.session_id
+          )
+      `);
+        },
+    },
 ];
 /** Current schema version — always equals the highest migration version. */
 export const SCHEMA_VERSION = migrations.length > 0 ? migrations[migrations.length - 1].version : 1;

package/dist/server/db/schema.js

@@ -37,7 +37,8 @@ export function initSchema(db) {
       claude_session_id TEXT,
       status TEXT NOT NULL DEFAULT 'running',
       started_at TEXT NOT NULL,
-      ended_at TEXT
+      ended_at TEXT,
+      name TEXT
     );
 
     CREATE TABLE IF NOT EXISTS ws_events (

package/dist/server/index.js

@@ -4,20 +4,23 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { serve } from '@hono/node-server';
 import { Hono } from 'hono';
-import { WebSocketServer } from 'ws';
+import WebSocket, { WebSocketServer } from 'ws';
 import { closeDb, getDb } from './db/index.js';
 import { runMigrations } from './db/migrations.js';
 import devServerRouter from './routes/dev-server.js';
 import gitRouter from './routes/git.js';
 import imagesRouter from './routes/images.js';
 import notionRouter from './routes/notion.js';
+import plansRouter from './routes/plans.js';
 import settingsRouter from './routes/settings.js';
+import templatesRouter from './routes/templates.js';
 import workspacesRouter from './routes/workspaces.js';
 import { getAvailableSkills, sendMessage, setBackendPort, startAgent, startWatchdog, stopAgent, stopWatchdog, } from './services/agent-manager.js';
 import { startDevServer, stopDevServer } from './services/dev-server-service.js';
 import { startPrWatcher, stopPrWatcher } from './services/pr-watcher-service.js';
+import { createTerminal, destroyAllTerminals, getTerminal } from './services/terminal-service.js';
 import { emit, handleConnection, setMessageHandler } from './services/websocket-service.js';
-import { getLatestSession, getWorkspace, updateWorkspaceStatus } from './services/workspace-service.js';
+import { getActiveSession, getWorkspace, updateWorkspaceStatus } from './services/workspace-service.js';
 import { getClientSpaPath, getKoboHome, getPackageVersion } from './utils/paths.js';
 import { initProcessCleanup, killAll as killAllTrackedProcesses } from './utils/process-tracker.js';
 // Runtime prerequisite check — warn if the claude CLI is missing. Don't block
@@ -47,6 +50,8 @@ app.route('/api/notion', notionRouter);
 app.route('/api/git', gitRouter);
 app.route('/api/settings', settingsRouter);
 app.route('/api/dev-server', devServerRouter);
+app.route('/api/templates', templatesRouter);
+app.route('/api/workspaces', plansRouter);
 // Skills endpoint
 app.get('/api/skills', (c) => c.json(getAvailableSkills()));
 const PORT = parseInt(process.env.SERVER_PORT || process.env.PORT || '3000', 10);
@@ -100,27 +105,117 @@ const server = serve({
 });
 // Create WebSocketServer attached to the HTTP server
 const wss = new WebSocketServer({ noServer: true });
+const terminalWss = new WebSocketServer({ noServer: true });
 // Wire WebSocket connections to websocket-service.handleConnection()
 wss.on('connection', (ws) => {
     handleConnection(ws);
 });
+// Wire terminal WebSocket connections
+terminalWss.on('connection', (ws, workspaceId) => {
+    let currentPty = getTerminal(workspaceId);
+    let dataDisposable = null;
+    let exitDisposable = null;
+    function attachListeners(ptyInstance) {
+        // Dispose previous listeners to avoid stacking on reconnect
+        dataDisposable?.dispose();
+        exitDisposable?.dispose();
+        dataDisposable = ptyInstance.onData((output) => {
+            if (ws.readyState === WebSocket.OPEN) {
+                ws.send(Buffer.from(output), { binary: true });
+            }
+        });
+        exitDisposable = ptyInstance.onExit(({ exitCode }) => {
+            if (ws.readyState === WebSocket.OPEN) {
+                ws.send(JSON.stringify({ type: 'exited', code: exitCode }));
+                ws.close();
+            }
+        });
+    }
+    ws.on('close', () => {
+        dataDisposable?.dispose();
+        exitDisposable?.dispose();
+        dataDisposable = null;
+        exitDisposable = null;
+    });
+    ws.on('error', (err) => {
+        console.error(`[terminal] WebSocket error for workspace ${workspaceId}:`, err);
+    });
+    ws.on('message', (data, isBinary) => {
+        if (isBinary) {
+            if (currentPty) {
+                currentPty.write(data.toString());
+            }
+            return;
+        }
+        let msg;
+        try {
+            msg = JSON.parse(data.toString());
+        }
+        catch {
+            return; // Invalid JSON — ignore
+        }
+        if (msg.type === 'create') {
+            if (!currentPty) {
+                const workspace = getWorkspace(workspaceId);
+                if (!workspace) {
+                    ws.send(JSON.stringify({ type: 'error', message: 'Workspace not found' }));
+                    return;
+                }
+                if (workspace.archivedAt) {
+                    ws.send(JSON.stringify({ type: 'error', message: 'Workspace is archived' }));
+                    return;
+                }
+                const cwd = `${workspace.projectPath}/.worktrees/${workspace.workingBranch}`;
+                try {
+                    currentPty = createTerminal(workspaceId, cwd);
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    ws.send(JSON.stringify({ type: 'error', message }));
+                    return;
+                }
+            }
+            attachListeners(currentPty);
+            ws.send(JSON.stringify({ type: 'ready' }));
+            return;
+        }
+        if (msg.type === 'resize' && msg.cols && msg.rows) {
+            if (currentPty) {
+                const cols = Math.max(1, Math.floor(msg.cols));
+                const rows = Math.max(1, Math.floor(msg.rows));
+                try {
+                    currentPty.resize(cols, rows);
+                }
+                catch (err) {
+                    console.error(`[terminal] resize failed for workspace ${workspaceId}:`, err);
+                }
+            }
+            return;
+        }
+    });
+});
 // Wire websocket-service message handler to agent-manager
 setMessageHandler((type, payload) => {
     const p = payload;
     if (type === 'chat:message' && p?.workspaceId && p?.content) {
+        // Prefer the session explicitly selected by the client (sessionId hint),
+        // falling back to the running/most-recent non-idle session so idle sessions
+        // never steal the tagging.
+        const activeSession = getActiveSession(p.workspaceId);
+        const sessionTag = p.sessionId ?? activeSession?.id ?? undefined;
         // Persist user message so it survives page refresh
-        const latestSession = getLatestSession(p.workspaceId);
-        emit(p.workspaceId, 'user:message', { content: p.content, sender: 'user' }, latestSession?.claudeSessionId ?? undefined);
+        emit(p.workspaceId, 'user:message', { content: p.content, sender: 'user' }, sessionTag);
         try {
             sendMessage(p.workspaceId, p.content);
         }
         catch {
-            // Agent not running — resume the existing session
+            // Agent not running — resume the session hinted by the client if any,
+            // otherwise the most-recent active session.
             try {
                 const workspace = getWorkspace(p.workspaceId);
                 if (workspace) {
                     const worktreePath = `${workspace.projectPath}/.worktrees/${workspace.workingBranch}`;
-                    startAgent(p.workspaceId, worktreePath, p.content, workspace.model, true, workspace.permissionMode);
+                    startAgent(p.workspaceId, worktreePath, p.content, workspace.model, true, workspace.permissionMode, p.sessionId);
                     updateWorkspaceStatus(p.workspaceId, 'executing');
                 }
             }
@@ -177,6 +272,16 @@ server.on('upgrade', (request, socket, head) => {
             wss.emit('connection', ws, request);
         });
     }
+    else if (pathname.startsWith('/ws/terminal/')) {
+        const workspaceId = pathname.slice('/ws/terminal/'.length);
+        if (!workspaceId) {
+            socket.destroy();
+            return;
+        }
+        terminalWss.handleUpgrade(request, socket, head, (ws) => {
+            terminalWss.emit('connection', ws, workspaceId);
+        });
+    }
     else {
         socket.destroy();
     }
@@ -192,6 +297,14 @@ function gracefulShutdown(signal) {
     wss.close(() => {
         console.log('[kobo] WebSocket server closed');
     });
+    terminalWss.close();
+    try {
+        destroyAllTerminals();
+        console.log('[kobo] Terminals killed');
+    }
+    catch {
+        // Best-effort
+    }
     server.close(() => {
         console.log('[kobo] HTTP server closed');
     });

package/dist/server/routes/plans.js

@@ -0,0 +1,89 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { Hono } from 'hono';
+import * as workspaceService from '../services/workspace-service.js';
+/** Hono sub-router for workspace plan file browsing (read-only). */
+const app = new Hono();
+/** Directories inside the worktree where plan files may live. */
+const PLAN_DIRS = ['docs/plans', 'docs/superpowers/plans'];
+/** Only .md files are listed. */
+const MD_EXT = '.md';
+// GET /:id/plans — list plan files in the workspace worktree
+app.get('/:id/plans', (c) => {
+    try {
+        const id = c.req.param('id');
+        const workspace = workspaceService.getWorkspace(id);
+        if (!workspace) {
+            return c.json({ error: `Workspace '${id}' not found` }, 404);
+        }
+        const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
+        const plans = [];
+        for (const dir of PLAN_DIRS) {
+            const absDir = path.join(worktreePath, dir);
+            if (!existsSync(absDir))
+                continue;
+            try {
+                const entries = readdirSync(absDir);
+                for (const entry of entries) {
+                    if (!entry.endsWith(MD_EXT))
+                        continue;
+                    try {
+                        const absFile = path.join(absDir, entry);
+                        const stat = statSync(absFile);
+                        if (!stat.isFile())
+                            continue;
+                        plans.push({
+                            path: `${dir}/${entry}`,
+                            name: entry,
+                            modifiedAt: stat.mtime.toISOString(),
+                        });
+                    }
+                    catch {
+                        // Skip files we can't stat
+                    }
+                }
+            }
+            catch {
+                // Skip directories we can't read
+            }
+        }
+        // Sort by modifiedAt descending (most recent first)
+        plans.sort((a, b) => new Date(b.modifiedAt).getTime() - new Date(a.modifiedAt).getTime());
+        return c.json({ plans });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
+// GET /:id/plan-file?path=<relative> — read a single plan file
+app.get('/:id/plan-file', (c) => {
+    try {
+        const id = c.req.param('id');
+        const filePath = c.req.query('path');
+        if (!filePath) {
+            return c.json({ error: 'Missing path query parameter' }, 400);
+        }
+        const workspace = workspaceService.getWorkspace(id);
+        if (!workspace) {
+            return c.json({ error: `Workspace '${id}' not found` }, 404);
+        }
+        // Security: normalize the path and verify it stays within allowed directories
+        const normalized = path.normalize(filePath);
+        if (normalized.includes('..') || !PLAN_DIRS.some((dir) => normalized.startsWith(dir))) {
+            return c.json({ error: 'Invalid path: must be under docs/plans/ or docs/superpowers/plans/' }, 400);
+        }
+        const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
+        const absPath = path.join(worktreePath, normalized);
+        if (!existsSync(absPath)) {
+            return c.json({ error: `Plan file not found: ${normalized}` }, 404);
+        }
+        const content = readFileSync(absPath, 'utf-8');
+        return c.json({ content, path: normalized });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
+export default app;

package/dist/server/routes/templates.js

@@ -0,0 +1,82 @@
+import { Hono } from 'hono';
+import * as templatesService from '../services/templates-service.js';
+/** Hono sub-router for prompt templates CRUD. */
+const app = new Hono();
+// GET /api/templates — list all templates
+app.get('/', (c) => {
+    try {
+        return c.json({ templates: templatesService.listTemplates() });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
+/**
+ * Classify a service error into the correct HTTP status based on the error
+ * message markers exported by templates-service.ts. Unknown / I/O errors
+ * fall through to 500 so disk-full or permission failures are not disguised
+ * as client errors.
+ */
+function statusForServiceError(message) {
+    if (message.includes('already exists'))
+        return 409;
+    if (message.startsWith('Invalid '))
+        return 400;
+    return 500;
+}
+// POST /api/templates — create a new template
+app.post('/', async (c) => {
+    try {
+        const body = await c.req
+            .json()
+            .catch(() => ({}));
+        if (!body.slug || !body.description || !body.content) {
+            return c.json({ error: 'slug, description, and content are required' }, 400);
+        }
+        const template = templatesService.createTemplate({
+            slug: body.slug,
+            description: body.description,
+            content: body.content,
+        });
+        return c.json(template, 201);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, statusForServiceError(message));
+    }
+});
+// PATCH /api/templates/:slug — update description and/or content
+app.patch('/:slug', async (c) => {
+    try {
+        const slug = c.req.param('slug');
+        const body = await c.req
+            .json()
+            .catch(() => ({}));
+        const updated = templatesService.updateTemplate(slug, body);
+        if (!updated) {
+            return c.json({ error: `Template '${slug}' not found` }, 404);
+        }
+        return c.json(updated);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, statusForServiceError(message));
+    }
+});
+// DELETE /api/templates/:slug — delete a template
+app.delete('/:slug', (c) => {
+    try {
+        const slug = c.req.param('slug');
+        const ok = templatesService.deleteTemplate(slug);
+        if (!ok) {
+            return c.json({ error: `Template '${slug}' not found` }, 404);
+        }
+        return c.json({ ok: true });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
+export default app;