specrails-desktop 2.0.0

package/server/dist/agent-refine-manager.js

@@ -0,0 +1,526 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentRefineManager = void 0;
+exports.validateAgentBody = validateAgentBody;
+exports.buildFirstTurnPrompt = buildFirstTurnPrompt;
+exports.refineSessionToJson = refineSessionToJson;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const readline_1 = require("readline");
+const crypto_1 = require("crypto");
+const tree_kill_1 = __importDefault(require("tree-kill"));
+const cli_prompt_1 = require("./util/cli-prompt");
+const agent_generator_1 = require("./agent-generator");
+const ai_invocations_1 = require("./ai-invocations");
+const result_event_1 = require("./result-event");
+const providers_1 = require("./providers");
+const agent_refine_db_1 = require("./agent-refine-db");
+const CUSTOM_PREFIX = /^custom-[a-z0-9][a-z0-9-]*$/;
+const SMART_TEST_DEBOUNCE_MS = 5_000;
+/**
+ * Manager for AI-driven iterative refinement of custom agent .md files.
+ *
+ * Mirrors ProposalManager: spawn `claude` with stream-json, capture session id
+ * on first turn, resume on follow-ups. Streams deltas + phase pills over WS.
+ */
+class AgentRefineManager {
+    _broadcast;
+    _db;
+    _projectPath;
+    _projectId;
+    _adapter;
+    _activeProcesses = new Map();
+    _bodyBuffers = new Map();
+    _disposed = false;
+    constructor(broadcast, db, projectPath, projectId, provider) {
+        this._broadcast = broadcast;
+        this._db = db;
+        this._projectPath = projectPath;
+        this._projectId = projectId;
+        this._adapter = (0, providers_1.getAdapter)(provider ?? 'claude');
+    }
+    isActive(refineId) {
+        return this._activeProcesses.has(refineId);
+    }
+    /**
+     * Tear down before the project's DB is closed (M12). Marks the manager disposed
+     * so in-flight close/error handlers short-circuit instead of writing to a
+     * closed connection (which throws synchronously inside the EventEmitter and,
+     * with no uncaughtException handler, crashes the whole app), and SIGTERMs any
+     * orphaned refine child. Idempotent.
+     */
+    shutdown() {
+        this._disposed = true;
+        for (const child of this._activeProcesses.values()) {
+            if (child.pid) {
+                try {
+                    (0, tree_kill_1.default)(child.pid, 'SIGTERM');
+                }
+                catch { /* ignore */ }
+            }
+        }
+        this._activeProcesses.clear();
+        this._bodyBuffers.clear();
+    }
+    /** Start a new refine session for the given custom agent. */
+    async startRefine(opts) {
+        if (!CUSTOM_PREFIX.test(opts.agentId)) {
+            throw new Error('not_a_custom_agent');
+        }
+        const file = this._agentFile(opts.agentId);
+        if (!fs_1.default.existsSync(file)) {
+            throw new Error('agent_not_found');
+        }
+        const body = fs_1.default.readFileSync(file, 'utf8');
+        const baseHash = sha256(body);
+        const baseVersion = this._currentVersion(opts.agentId);
+        const refineId = (0, crypto_1.randomUUID)();
+        (0, agent_refine_db_1.createRefineSession)(this._db, {
+            id: refineId,
+            agentId: opts.agentId,
+            baseVersion,
+            baseBodyHash: baseHash,
+            autoTest: opts.autoTest !== false,
+        });
+        // Seed history with the user's instruction so reconnects show full thread.
+        this._appendHistory(refineId, { role: 'user', content: opts.instruction, timestamp: Date.now() });
+        void this._runTurn(refineId, opts.instruction, /* isFirst */ true, body);
+        return { refineId };
+    }
+    /** Send a follow-up instruction on an existing session. */
+    async sendTurn(opts) {
+        const session = (0, agent_refine_db_1.getRefineSession)(this._db, opts.refineId);
+        if (!session)
+            throw new Error('session_not_found');
+        if (session.status === 'streaming')
+            throw new Error('turn_in_progress');
+        if (!session.session_id)
+            throw new Error('no_session_id');
+        this._appendHistory(opts.refineId, { role: 'user', content: opts.instruction, timestamp: Date.now() });
+        void this._runTurn(opts.refineId, opts.instruction, /* isFirst */ false, null);
+    }
+    /** Cancel an in-flight session. Idempotent. */
+    cancel(refineId) {
+        const child = this._activeProcesses.get(refineId);
+        if (child?.pid) {
+            try {
+                (0, tree_kill_1.default)(child.pid, 'SIGTERM');
+            }
+            catch { /* ignore */ }
+        }
+        const existing = (0, agent_refine_db_1.getRefineSession)(this._db, refineId);
+        if (existing) {
+            (0, agent_refine_db_1.updateRefineSession)(this._db, refineId, { status: 'cancelled', phase: 'idle' });
+        }
+        this._broadcast({
+            type: 'agent_refine_cancelled',
+            projectId: '',
+            refineId,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /** Toggle auto-test for a session. */
+    toggleAutoTest(refineId, enabled) {
+        const session = (0, agent_refine_db_1.getRefineSession)(this._db, refineId);
+        if (!session)
+            throw new Error('session_not_found');
+        (0, agent_refine_db_1.updateRefineSession)(this._db, refineId, { auto_test: enabled ? 1 : 0 });
+    }
+    /** Apply the current draft_body to disk through the standard write path. */
+    apply(opts) {
+        const session = (0, agent_refine_db_1.getRefineSession)(this._db, opts.refineId);
+        if (!session)
+            return { ok: false, reason: 'session_not_found' };
+        if (!session.draft_body)
+            return { ok: false, reason: 'invalid_state' };
+        const file = this._agentFile(session.agent_id);
+        if (!fs_1.default.existsSync(file))
+            return { ok: false, reason: 'agent_not_found' };
+        const currentBody = fs_1.default.readFileSync(file, 'utf8');
+        if (!opts.force && sha256(currentBody) !== session.base_body_hash) {
+            return { ok: false, reason: 'disk_changed' };
+        }
+        const draftName = extractFrontmatterName(session.draft_body);
+        const currentName = extractFrontmatterName(currentBody) ?? session.agent_id;
+        if (draftName && draftName !== currentName) {
+            return { ok: false, reason: 'name_changed' };
+        }
+        fs_1.default.writeFileSync(file, session.draft_body, 'utf8');
+        const maxVersion = this._db
+            .prepare(`SELECT COALESCE(MAX(version), 0) AS v FROM agent_versions WHERE agent_name = ?`)
+            .get(session.agent_id).v;
+        const nextVersion = maxVersion + 1;
+        this._db.prepare(`INSERT INTO agent_versions (agent_name, version, body, created_at) VALUES (?, ?, ?, ?)`).run(session.agent_id, nextVersion, session.draft_body, Date.now());
+        (0, agent_refine_db_1.updateRefineSession)(this._db, opts.refineId, { status: 'applied', phase: 'done' });
+        this._broadcast({
+            type: 'agent_refine_applied',
+            projectId: '',
+            refineId: opts.refineId,
+            agentId: session.agent_id,
+            version: nextVersion,
+            timestamp: new Date().toISOString(),
+        });
+        // Also broadcast the standard catalog change event so existing UI updates.
+        this._broadcast({ type: 'agent.changed', projectId: '', id: session.agent_id });
+        return { ok: true, version: nextVersion, body: session.draft_body };
+    }
+    /** Hard-delete a session (used by cleanup/admin paths). */
+    destroy(refineId) {
+        this.cancel(refineId);
+        (0, agent_refine_db_1.deleteRefineSession)(this._db, refineId);
+    }
+    // ─── Private ──────────────────────────────────────────────────────────────
+    _agentFile(agentId) {
+        // Per-provider on-disk layout:
+        //   claude → <project>/.claude/agents/<agentId>.md
+        //   codex  → <project>/.codex/skills/<agentId>/SKILL.md
+        // Future providers add their own branch via the adapter; the projectDir
+        // is already provider-aware.
+        if (this._adapter.id === 'codex') {
+            return path_1.default.join(this._projectPath, this._adapter.projectDirName, 'skills', agentId, 'SKILL.md');
+        }
+        return path_1.default.join(this._projectPath, this._adapter.projectDirName, 'agents', `${agentId}.md`);
+    }
+    _currentVersion(agentId) {
+        const row = this._db
+            .prepare(`SELECT COALESCE(MAX(version), 0) AS v FROM agent_versions WHERE agent_name = ?`)
+            .get(agentId);
+        return row.v;
+    }
+    _appendHistory(refineId, turn) {
+        const session = (0, agent_refine_db_1.getRefineSession)(this._db, refineId);
+        if (!session)
+            return;
+        (0, agent_refine_db_1.updateRefineSession)(this._db, refineId, { history: [...session.history, turn] });
+    }
+    async _runTurn(refineId, instruction, isFirst, bodyForFirstTurn) {
+        const session = (0, agent_refine_db_1.getRefineSession)(this._db, refineId);
+        if (!session)
+            return;
+        (0, agent_refine_db_1.updateRefineSession)(this._db, refineId, { status: 'streaming', phase: 'reading' });
+        this._emitPhase(refineId, 'reading');
+        const prompt = isFirst
+            ? buildFirstTurnPrompt({
+                agentId: session.agent_id,
+                currentBody: bodyForFirstTurn ?? '',
+                userInstruction: instruction,
+            })
+            : instruction;
+        const action = !isFirst && session.session_id && this._adapter.capabilities.nativeResume
+            ? 'chat-resume'
+            : 'agent-refine';
+        const refineModel = this._adapter.defaultModel();
+        const args = this._adapter.buildArgs(action, {
+            prompt,
+            model: refineModel,
+            sessionId: session.session_id ?? undefined,
+        });
+        let drafted = false;
+        const child = (0, cli_prompt_1.spawnAiCli)(this._adapter.binary, args, {
+            env: process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            cwd: this._projectPath,
+        });
+        this._activeProcesses.set(refineId, child);
+        this._bodyBuffers.set(refineId, '');
+        let capturedSessionId = null;
+        const adapterEvents = [];
+        const turnStartedAt = new Date().toISOString();
+        const reader = (0, readline_1.createInterface)({ input: child.stdout, crlfDelay: Infinity });
+        reader.on('line', (line) => {
+            const ev = this._adapter.parseStreamLine(line);
+            if (!ev)
+                return;
+            adapterEvents.push(ev);
+            switch (ev.kind) {
+                case 'session-started':
+                    if (!capturedSessionId)
+                        capturedSessionId = ev.sessionId;
+                    break;
+                case 'result': {
+                    const sid = ev.payload.session_id;
+                    if (sid && !capturedSessionId)
+                        capturedSessionId = sid;
+                    break;
+                }
+                case 'text-delta': {
+                    if (!drafted) {
+                        drafted = true;
+                        (0, agent_refine_db_1.updateRefineSession)(this._db, refineId, { phase: 'drafting' });
+                        this._emitPhase(refineId, 'drafting');
+                    }
+                    const prev = this._bodyBuffers.get(refineId) ?? '';
+                    const next = prev + ev.text;
+                    this._bodyBuffers.set(refineId, next);
+                    this._broadcast({
+                        type: 'agent_refine_stream',
+                        projectId: '',
+                        refineId,
+                        delta: ev.text,
+                        timestamp: new Date().toISOString(),
+                    });
+                    (0, agent_refine_db_1.updateRefineSession)(this._db, refineId, { draft_body: next });
+                    break;
+                }
+                case 'tool-use':
+                    this._broadcast({
+                        type: 'agent_refine_stream',
+                        projectId: '',
+                        refineId,
+                        delta: `<!--tool:${ev.name}-->`,
+                        timestamp: new Date().toISOString(),
+                    });
+                    break;
+                case 'other':
+                    break;
+            }
+        });
+        let stderr = '';
+        child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+        return new Promise((resolve) => {
+            child.on('error', (err) => {
+                this._activeProcesses.delete(refineId);
+                this._bodyBuffers.delete(refineId);
+                if (this._disposed) {
+                    resolve();
+                    return;
+                } // M12: project removed mid-flight; DB closing
+                this._emitError(refineId, `Failed to launch claude: ${err.message}`);
+                (0, agent_refine_db_1.updateRefineSession)(this._db, refineId, { status: 'error', phase: 'idle' });
+                resolve();
+            });
+            child.on('close', (code) => {
+                this._activeProcesses.delete(refineId);
+                const fullDraft = this._bodyBuffers.get(refineId) ?? '';
+                this._bodyBuffers.delete(refineId);
+                if (this._disposed) {
+                    resolve();
+                    return;
+                } // M12: project removed mid-flight; DB closing
+                // ai_invocations capture (surface='ai-edit'). One row per refine turn.
+                if (this._projectId) {
+                    try {
+                        const invStatus = code === 0 && fullDraft.trim() ? 'success' : 'failed';
+                        const { result: normalised, estimated } = (0, result_event_1.finaliseInvocationResult)(this._adapter, adapterEvents, { fallbackModel: refineModel });
+                        (0, ai_invocations_1.recordInvocation)(this._db, {
+                            id: (0, crypto_1.randomUUID)(),
+                            project_id: this._projectId,
+                            provider: this._adapter.id,
+                            surface: 'ai-edit',
+                            surface_ref_id: refineId,
+                            status: invStatus,
+                            started_at: turnStartedAt,
+                            finished_at: new Date().toISOString(),
+                            total_cost_usd_estimated: estimated,
+                            ...normalised,
+                        });
+                        this._broadcast({ type: 'spending.invalidated', projectId: this._projectId });
+                    }
+                    catch (err) {
+                        console.error('[agent-refine-manager] recordInvocation failed:', err);
+                    }
+                }
+                if (code !== 0 || !fullDraft.trim()) {
+                    this._emitError(refineId, code !== 0
+                        ? `claude exited with code ${code}${stderr ? `: ${stderr.slice(-300)}` : ''}`
+                        : 'claude returned empty output');
+                    (0, agent_refine_db_1.updateRefineSession)(this._db, refineId, { status: 'error', phase: 'idle' });
+                    resolve();
+                    return;
+                }
+                // Validation phase.
+                (0, agent_refine_db_1.updateRefineSession)(this._db, refineId, { phase: 'validating' });
+                this._emitPhase(refineId, 'validating');
+                const stripped = stripToolMarkers(fullDraft);
+                const validation = validateAgentBody(stripped, this._adapter.id);
+                if (!validation.ok) {
+                    this._emitError(refineId, `Frontmatter invalid: ${validation.error}`);
+                    (0, agent_refine_db_1.updateRefineSession)(this._db, refineId, { status: 'error', phase: 'idle', draft_body: stripped });
+                    resolve();
+                    return;
+                }
+                // Append assistant turn to history (use stripped body — markers gone).
+                this._appendHistory(refineId, {
+                    role: 'assistant',
+                    content: stripped,
+                    timestamp: Date.now(),
+                });
+                const patch = {
+                    status: 'ready',
+                    phase: 'done',
+                    draft_body: stripped,
+                    ...(capturedSessionId ? { session_id: capturedSessionId } : {}),
+                };
+                (0, agent_refine_db_1.updateRefineSession)(this._db, refineId, patch);
+                this._broadcast({
+                    type: 'agent_refine_ready',
+                    projectId: '',
+                    refineId,
+                    draftBody: stripped,
+                    timestamp: new Date().toISOString(),
+                });
+                this._emitPhase(refineId, 'done');
+                // Smart-mode auto-test: only run if enabled, body changed since last
+                // test, and >5s elapsed. Best-effort; failures are non-fatal.
+                const session2 = (0, agent_refine_db_1.getRefineSession)(this._db, refineId);
+                if (session2 && session2.auto_test === 1) {
+                    const draftHash = sha256(stripped);
+                    const recent = session2.last_test_at !== null && Date.now() - session2.last_test_at < SMART_TEST_DEBOUNCE_MS;
+                    const sameBody = session2.last_test_hash === draftHash;
+                    if (!recent && !sameBody) {
+                        void this._runAutoTest(refineId, session2.agent_id, stripped, draftHash);
+                    }
+                }
+                resolve();
+            });
+        });
+    }
+    async _runAutoTest(refineId, agentId, draftBody, draftHash) {
+        (0, agent_refine_db_1.updateRefineSession)(this._db, refineId, { phase: 'testing' });
+        this._emitPhase(refineId, 'testing');
+        const sampleTask = pickSampleTask(this._db, agentId);
+        try {
+            const result = await (0, agent_generator_1.testCustomAgent)(this._projectPath, { draftBody, sampleTask });
+            this._db.prepare(`INSERT INTO agent_tests (agent_name, draft_hash, sample_task_id, tokens, duration_ms, output, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`).run(agentId, result.draftHash, null, result.tokens, result.durationMs, result.output, Date.now());
+            (0, agent_refine_db_1.updateRefineSession)(this._db, refineId, {
+                last_test_at: Date.now(),
+                last_test_hash: draftHash,
+                phase: 'done',
+            });
+            this._appendHistory(refineId, {
+                role: 'system',
+                kind: 'test_result',
+                content: result.output,
+                timestamp: Date.now(),
+            });
+            this._broadcast({
+                type: 'agent_refine_test',
+                projectId: '',
+                refineId,
+                result: { output: result.output, tokens: result.tokens, durationMs: result.durationMs },
+                timestamp: new Date().toISOString(),
+            });
+        }
+        catch (err) {
+            this._emitError(refineId, `Auto-test failed: ${err.message}`);
+            (0, agent_refine_db_1.updateRefineSession)(this._db, refineId, { phase: 'done' });
+        }
+    }
+    _emitPhase(refineId, phase) {
+        this._broadcast({
+            type: 'agent_refine_phase',
+            projectId: '',
+            refineId,
+            phase,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    _emitError(refineId, error) {
+        this._broadcast({
+            type: 'agent_refine_error',
+            projectId: '',
+            refineId,
+            error,
+            timestamp: new Date().toISOString(),
+        });
+    }
+}
+exports.AgentRefineManager = AgentRefineManager;
+// ─── Helpers ───────────────────────────────────────────────────────────────
+function sha256(s) {
+    return (0, crypto_1.createHash)('sha256').update(s).digest('hex');
+}
+function stripToolMarkers(s) {
+    return s.replace(/<!--tool:[^>]+-->/g, '').trim();
+}
+function extractFrontmatterName(body) {
+    const fm = body.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!fm)
+        return null;
+    const m = fm[1].match(/^name:\s*(\S+)/m);
+    return m ? m[1].trim() : null;
+}
+function validateAgentBody(body, providerId = 'claude') {
+    const trimmed = body.trim();
+    if (!trimmed.startsWith('---'))
+        return { ok: false, error: 'missing YAML frontmatter' };
+    const fm = trimmed.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!fm)
+        return { ok: false, error: 'unterminated YAML frontmatter' };
+    const block = fm[1];
+    if (!/^name:\s*\S+/m.test(block))
+        return { ok: false, error: 'frontmatter must include `name:`' };
+    if (!/^description:/m.test(block))
+        return { ok: false, error: 'frontmatter must include `description:`' };
+    // Per-provider model field rules:
+    //   - claude: `.claude/agents/sr-*.md` frontmatter requires `model:` from
+    //     the short alias set (sonnet/opus/haiku) for the Task tool to resolve.
+    //   - codex: SKILL.md format has no `model:` field — model is decided at
+    //     spawn time via `--model`. Skip the model check entirely.
+    if (providerId === 'claude' && !/^model:\s*(sonnet|opus|haiku)/m.test(block)) {
+        return { ok: false, error: 'frontmatter `model:` must be sonnet|opus|haiku' };
+    }
+    return { ok: true };
+}
+function buildFirstTurnPrompt(opts) {
+    return [
+        'You are refining an existing custom agent. The user wants to iterate on its',
+        'definition. Output the COMPLETE refined `.md` file — full YAML frontmatter',
+        'between `---` separators, then the body. Do not include code fences,',
+        'commentary, or explanations. Start at `---`.',
+        '',
+        'Hard rules:',
+        '  1. Frontmatter MUST include `name`, `description`, and `model` (one of',
+        '     `sonnet`, `opus`, `haiku`).',
+        `  2. The frontmatter \`name\` MUST remain exactly: ${opts.agentId}`,
+        '  3. The id `name` is locked; renaming is a separate explicit action.',
+        '',
+        `Agent id: ${opts.agentId}`,
+        '',
+        'Current agent file:',
+        '```markdown',
+        opts.currentBody,
+        '```',
+        '',
+        `User refinement request:`,
+        opts.userInstruction,
+        '',
+        'Output only the new file content, starting with `---`.',
+    ].join('\n');
+}
+function pickSampleTask(db, agentId) {
+    try {
+        const row = db
+            .prepare(`SELECT output FROM agent_tests
+         WHERE agent_name = ? AND sample_task_id IS NOT NULL
+         ORDER BY created_at DESC LIMIT 1`)
+            .get(agentId);
+        if (row?.output)
+            return row.output;
+    }
+    catch { /* ignore */ }
+    return DEFAULT_SAMPLE_TASK;
+}
+const DEFAULT_SAMPLE_TASK = [
+    'Demonstrate how you would handle a small representative task within your',
+    'declared focus areas. Keep the answer under 150 words.',
+].join(' ');
+/** Build a public, JSON-friendly view of a session for the GET /refine/:id endpoint. */
+function refineSessionToJson(row) {
+    return {
+        id: row.id,
+        agentId: row.agent_id,
+        status: row.status,
+        phase: row.phase,
+        autoTest: row.auto_test === 1,
+        draftBody: row.draft_body,
+        history: row.history,
+        baseVersion: row.base_version,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}

package/server/dist/ai-invocations.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidSurfaceError = void 0;
+exports.recordInvocation = recordInvocation;
+exports.updateTicketIdForConversation = updateTicketIdForConversation;
+exports.listInvocationsForConversation = listInvocationsForConversation;
+exports.getTicketSpendingSummary = getTicketSpendingSummary;
+exports.getInvocationsByProvider = getInvocationsByProvider;
+const ALLOWED_SURFACES = new Set([
+    'job',
+    'quick-spec',
+    'explore-spec',
+    'ai-edit',
+    'smash',
+    'file-summary',
+]);
+class InvalidSurfaceError extends Error {
+    surface;
+    constructor(surface) {
+        super(`Invalid surface: ${surface}`);
+        this.surface = surface;
+        this.name = 'InvalidSurfaceError';
+    }
+}
+exports.InvalidSurfaceError = InvalidSurfaceError;
+function recordInvocation(db, input) {
+    if (!ALLOWED_SURFACES.has(input.surface)) {
+        throw new InvalidSurfaceError(input.surface);
+    }
+    if (!input.provider) {
+        throw new Error('recordInvocation: provider is required');
+    }
+    db.prepare(`
+    INSERT INTO ai_invocations (
+      id, project_id, provider, surface, surface_ref_id, ticket_id, conversation_id,
+      model, status, started_at, finished_at, duration_ms, duration_api_ms,
+      tokens_in, tokens_out, tokens_cache_read, tokens_cache_create,
+      total_cost_usd, total_cost_usd_estimated, num_turns, session_id
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(input.id, input.project_id, input.provider, input.surface, input.surface_ref_id ?? null, input.ticket_id ?? null, input.conversation_id ?? null, input.model ?? null, input.status, input.started_at, input.finished_at ?? null, input.duration_ms ?? null, input.duration_api_ms ?? null, input.tokens_in ?? null, input.tokens_out ?? null, input.tokens_cache_read ?? null, input.tokens_cache_create ?? null, input.total_cost_usd ?? null, input.total_cost_usd_estimated ? 1 : 0, input.num_turns ?? null, input.session_id ?? null);
+}
+function updateTicketIdForConversation(db, conversationId, ticketId) {
+    const result = db.prepare(`UPDATE ai_invocations SET ticket_id = ? WHERE conversation_id = ? AND ticket_id IS NULL`).run(ticketId, conversationId);
+    return result.changes;
+}
+function listInvocationsForConversation(db, conversationId) {
+    return db.prepare(`SELECT * FROM ai_invocations WHERE conversation_id = ? ORDER BY started_at ASC`).all(conversationId);
+}
+function getTicketSpendingSummary(db, ticketId) {
+    const rows = db.prepare(`SELECT surface, status, total_cost_usd, num_turns, duration_ms,
+            tokens_in, tokens_out, tokens_cache_read, tokens_cache_create
+     FROM ai_invocations WHERE ticket_id = ?`).all(ticketId);
+    const bySurface = {
+        job: { count: 0, costUsd: 0 },
+        'quick-spec': { count: 0, costUsd: 0 },
+        'explore-spec': { count: 0, costUsd: 0 },
+        'ai-edit': { count: 0, costUsd: 0 },
+        smash: { count: 0, costUsd: 0 },
+        'file-summary': { count: 0, costUsd: 0 },
+    };
+    let totalCostUsd = 0;
+    let totalTokens = 0;
+    let totalTurns = 0;
+    let activeDurationMs = 0;
+    for (const r of rows) {
+        bySurface[r.surface].count += 1;
+        bySurface[r.surface].costUsd += r.total_cost_usd ?? 0;
+        totalCostUsd += r.total_cost_usd ?? 0;
+        // Real total tokens = fresh input + output + cache-read + cache-create.
+        totalTokens +=
+            (r.tokens_in ?? 0) +
+                (r.tokens_out ?? 0) +
+                (r.tokens_cache_read ?? 0) +
+                (r.tokens_cache_create ?? 0);
+        totalTurns += r.num_turns ?? 0;
+        activeDurationMs += r.duration_ms ?? 0;
+    }
+    return { totalCostUsd, totalTokens, totalTurns, activeDurationMs, bySurface, totalRuns: rows.length };
+}
+/**
+ * Per-provider aggregation for the Analytics dashboard. Returns counts +
+ * authoritative cost (rows with total_cost_usd_estimated=0) and estimated
+ * cost (rows with total_cost_usd_estimated=1) split, so the UI can render the
+ * ~ badge and the "Includes estimated costs" footnote accurately.
+ *
+ * Spec: openspec/.../specs/project-spending/spec.md ("byProvider analytics breakdown")
+ */
+function getInvocationsByProvider(db, projectId, opts = {}) {
+    const params = [projectId];
+    let dateClause = '';
+    if (opts.fromIso) {
+        dateClause += ' AND started_at >= ?';
+        params.push(opts.fromIso);
+    }
+    if (opts.toIso) {
+        dateClause += ' AND started_at < ?';
+        params.push(opts.toIso);
+    }
+    const rows = db.prepare(`
+    SELECT
+      COALESCE(provider, 'claude') AS provider,
+      COUNT(*)                                                         AS count,
+      COALESCE(SUM(CASE WHEN total_cost_usd_estimated = 0 THEN total_cost_usd ELSE 0 END), 0) AS costUsd,
+      COALESCE(SUM(CASE WHEN total_cost_usd_estimated = 1 THEN total_cost_usd ELSE 0 END), 0) AS estimatedCostUsd
+    FROM ai_invocations
+    WHERE project_id = ?${dateClause}
+    GROUP BY provider
+    ORDER BY (costUsd + estimatedCostUsd) DESC
+  `).all(...params);
+    return rows;
+}