@hecer/yoke 1.13.0 → 1.15.0

package/dist/code-intelligence/mcp-server.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { CodeIntelligenceCoordinator } from './coordinator.js';
+import { TOOL_DEFINITIONS } from './contracts.js';
+import { loadConfig } from '../retrofit/config.js';
+const INPUT_SCHEMAS = {
+    code_context: { type: 'object', required: ['workspace_id', 'query'], properties: { workspace_id: { type: 'string' }, query: { type: 'string' }, snapshot_id: { type: 'string' }, mode: { type: 'string', enum: ['orient', 'locate', 'explain'] }, paths: { type: 'array', items: { type: 'string' } }, include_docs: { type: 'boolean' }, token_budget: { type: 'integer' }, timeout_ms: { type: 'integer' } } },
+    code_symbol: { type: 'object', required: ['workspace_id', 'snapshot_id'], properties: { workspace_id: { type: 'string' }, snapshot_id: { type: 'string' }, symbol_id: { type: 'string' }, query: { type: 'string' }, path: { type: 'string' }, include: { type: 'array' } } },
+    code_trace: { type: 'object', required: ['workspace_id', 'snapshot_id', 'symbol_id', 'direction', 'relations'], properties: { workspace_id: { type: 'string' }, snapshot_id: { type: 'string' }, symbol_id: { type: 'string' }, direction: { type: 'string', enum: ['in', 'out'] }, relations: { type: 'array' }, max_depth: { type: 'integer' }, max_nodes: { type: 'integer' } } },
+    code_impact: { type: 'object', required: ['workspace_id', 'snapshot_id'], properties: { workspace_id: { type: 'string' }, snapshot_id: { type: 'string' }, targets: { type: 'array' }, plan_id: { type: 'string' }, include_docs: { type: 'boolean' }, require_semantic: { type: 'boolean' } } },
+    code_edit_preview: { type: 'object', required: ['workspace_id', 'snapshot_id', 'operations', 'validation_profile'], properties: { workspace_id: { type: 'string' }, snapshot_id: { type: 'string' }, operations: { type: 'array' }, validation_profile: { type: 'string', enum: ['default', 'extended'] } } },
+    code_edit_apply: { type: 'object', required: ['workspace_id', 'plan_id', 'expected_snapshot_id', 'idempotency_key'], properties: { workspace_id: { type: 'string' }, plan_id: { type: 'string' }, expected_snapshot_id: { type: 'string' }, idempotency_key: { type: 'string' } } },
+};
+function arg(name, args) { return args.find(value => value.startsWith(`--${name}=`))?.slice(name.length + 3); }
+function summary(response) { return `status=${response.status} snapshot=${response.snapshot_id} warnings=${response.warnings.length} (full result in structuredContent)`; }
+export async function runCodeIntelligenceServer(argv = process.argv.slice(2)) {
+    const workspace = arg('workspace', argv) ?? process.cwd();
+    const configured = loadConfig(workspace)?.codeIntelligence;
+    const mode = arg('mode', argv) ?? configured?.mode ?? 'active';
+    const coordinator = new CodeIntelligenceCoordinator(workspace, {
+        mode,
+        policy: { excludePatterns: configured?.policy?.excludePatterns, maxFileBytes: configured?.policy?.maxFileBytes },
+        limits: { maxBytes: configured?.limits?.maxBytes, maxBackends: configured?.limits?.maxBackends },
+        graft: configured?.graft, graphify: configured?.graphify, serena: configured?.serena,
+    });
+    let framing = 'line';
+    let buffer = Buffer.alloc(0);
+    const send = (message) => {
+        const payload = JSON.stringify(message);
+        if (framing === 'line')
+            process.stdout.write(`${payload}\n`);
+        else
+            process.stdout.write(`Content-Length: ${Buffer.byteLength(payload, 'utf8')}\r\n\r\n${payload}`);
+    };
+    const handle = async (message) => {
+        if (message.method === 'notifications/initialized' || message.method?.startsWith('notifications/'))
+            return;
+        if (message.method === 'initialize') {
+            send({ jsonrpc: '2.0', id: message.id, result: { protocolVersion: '2025-11-25', capabilities: { tools: {} }, serverInfo: { name: 'yoke-code-intelligence', version: '0.1.0' } } });
+            return;
+        }
+        if (message.method === 'tools/list') {
+            send({ jsonrpc: '2.0', id: message.id, result: { tools: TOOL_DEFINITIONS.map(tool => ({ ...tool, inputSchema: INPUT_SCHEMAS[tool.name] })) } });
+            return;
+        }
+        if (message.method === 'tools/call') {
+            const name = message.params?.name;
+            const response = await coordinator.dispatch(name, message.params?.arguments ?? {});
+            send({ jsonrpc: '2.0', id: message.id, result: { content: [{ type: 'text', text: summary(response) }], structuredContent: response, isError: response.status === 'error' || response.status === 'blocked' } });
+            return;
+        }
+        if (message.id !== undefined)
+            send({ jsonrpc: '2.0', id: message.id, error: { code: -32601, message: `method not found: ${message.method}` } });
+    };
+    process.stdin.on('data', chunk => {
+        buffer = Buffer.concat([buffer, Buffer.from(chunk)]);
+        while (buffer.length) {
+            let raw;
+            if (/^Content-Length:/i.test(buffer.toString('ascii', 0, Math.min(buffer.length, 32)))) {
+                framing = 'content-length';
+                const end = buffer.indexOf('\r\n\r\n');
+                if (end < 0)
+                    return;
+                const header = buffer.subarray(0, end).toString('ascii');
+                const match = /Content-Length:\s*(\d+)/i.exec(header);
+                if (!match) {
+                    buffer = buffer.subarray(end + 4);
+                    continue;
+                }
+                const length = Number(match[1]);
+                if (buffer.length < end + 4 + length)
+                    return;
+                raw = buffer.subarray(end + 4, end + 4 + length).toString('utf8');
+                buffer = buffer.subarray(end + 4 + length);
+            }
+            else {
+                const end = buffer.indexOf(10);
+                if (end < 0)
+                    return;
+                raw = buffer.subarray(0, end).toString('utf8').trim();
+                buffer = buffer.subarray(end + 1);
+            }
+            if (!raw)
+                continue;
+            try {
+                void handle(JSON.parse(raw));
+            }
+            catch { /* malformed protocol input is ignored */ }
+        }
+    });
+    await new Promise(resolve => { const stop = () => { process.off('SIGTERM', stop); process.off('SIGINT', stop); void coordinator.close().finally(resolve); }; process.once('SIGTERM', stop); process.once('SIGINT', stop); process.stdin.once('end', stop); });
+}
+if (process.argv[1]?.endsWith('code-intelligence-server.js'))
+    void runCodeIntelligenceServer();

package/dist/code-intelligence/snapshots.js

@@ -0,0 +1,117 @@
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, readdirSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+import { z } from 'zod';
+export const SnapshotFileSchema = z.object({ path: z.string().min(1), hash: z.string().length(64), size: z.number().int().nonnegative() });
+export const SnapshotSchema = z.object({
+    snapshot_id: z.string().length(64), workspace_id: z.string().min(1), root: z.string().min(1), head: z.string().nullable(),
+    files: z.array(SnapshotFileSchema), policy_hash: z.string().length(64), created_at: z.string(),
+});
+function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function inside(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !rel.startsWith(sep));
+}
+function globToRegExp(pattern) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*\*/g, '.*').replace(/\*/g, '[^/]*').replace(/\?/g, '.');
+    return new RegExp(`^${escaped}$`);
+}
+function excluded(path, policy) {
+    const standard = [/^\.git(?:\/|$)/, /^\.yoke\/code-intelligence(?:\/|$)/, /(^|\/)\.env(?:\.|$)/, /\.(?:pem|key|p12|pfx)$/i];
+    if (standard.some(re => re.test(path)))
+        return true;
+    return (policy.excludePatterns ?? []).some(pattern => globToRegExp(pattern).test(path));
+}
+function safeFile(root, rel, policy) {
+    const normalized = rel.replaceAll('\\', '/');
+    if (!normalized || normalized.startsWith('/') || normalized.split('/').some(part => part === '..') || excluded(normalized, policy))
+        return null;
+    const absolute = resolve(root, normalized);
+    if (!inside(root, absolute) || !existsSync(absolute))
+        return null;
+    const stat = lstatSync(absolute);
+    if (!stat.isFile() || stat.isSymbolicLink() || (policy.maxFileBytes && stat.size > policy.maxFileBytes))
+        return null;
+    return { path: normalized, bytes: readFileSync(absolute) };
+}
+function fallbackFiles(root, dir = root, output = []) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name === '.git' || entry.name === '.yoke' || entry.name === 'node_modules')
+            continue;
+        const absolute = join(dir, entry.name);
+        if (entry.isDirectory() && !entry.isSymbolicLink())
+            fallbackFiles(root, absolute, output);
+        else if (entry.isFile())
+            output.push(relative(root, absolute).replaceAll('\\', '/'));
+    }
+    return output;
+}
+function trackedAndUntracked(root) {
+    try {
+        const result = execFileSync('git', ['-C', root, 'ls-files', '-co', '--exclude-standard', '-z'], { encoding: 'buffer', stdio: ['ignore', 'pipe', 'ignore'] });
+        return result.toString('utf8').split('\0').filter(Boolean);
+    }
+    catch {
+        return fallbackFiles(root);
+    }
+}
+function head(root) {
+    try {
+        return execFileSync('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+export function workspaceId(workspaceRoot) {
+    return `workspace-${sha256(realpathSync(resolve(workspaceRoot))).slice(0, 24)}`;
+}
+export function assertSafePath(workspaceRoot, candidate, policy = {}) {
+    const root = realpathSync(resolve(workspaceRoot));
+    const absolute = resolve(root, candidate);
+    const rel = relative(root, absolute).replaceAll('\\', '/');
+    if (!inside(root, absolute) || rel === '' || excluded(rel, policy))
+        throw new Error(`path is outside the permitted workspace: ${candidate}`);
+    try {
+        if (lstatSync(absolute).isSymbolicLink())
+            throw new Error(`symbolic links are not allowed: ${candidate}`);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    return rel;
+}
+export function createSnapshot(workspaceRoot, policy = {}, workspace = workspaceId(workspaceRoot)) {
+    const root = realpathSync(resolve(workspaceRoot));
+    const files = trackedAndUntracked(root).map(path => safeFile(root, path, policy)).filter((value) => value !== null)
+        .sort((a, b) => a.path.localeCompare(b.path)).map(file => ({ path: file.path, hash: sha256(file.bytes), size: file.bytes.byteLength }));
+    const policyHash = sha256(JSON.stringify({ excludePatterns: policy.excludePatterns ?? [], maxFileBytes: policy.maxFileBytes ?? null }));
+    const identity = JSON.stringify({ workspace, root, head: head(root), files, policyHash });
+    const snapshot = SnapshotSchema.parse({ snapshot_id: sha256(identity), workspace_id: workspace, root, head: head(root), files, policy_hash: policyHash, created_at: new Date().toISOString() });
+    const dir = join(root, '.yoke', 'code-intelligence', 'snapshots');
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, `${snapshot.snapshot_id}.json`), JSON.stringify(snapshot, null, 2) + '\n', { mode: 0o600 });
+    return snapshot;
+}
+export function loadSnapshot(workspaceRoot, snapshotId) {
+    const root = realpathSync(resolve(workspaceRoot));
+    const file = join(root, '.yoke', 'code-intelligence', 'snapshots', `${snapshotId}.json`);
+    if (!existsSync(file))
+        throw new Error(`unknown snapshot: ${snapshotId}`);
+    const snapshot = SnapshotSchema.parse(JSON.parse(readFileSync(file, 'utf8')));
+    if (snapshot.root !== root)
+        throw new Error('snapshot belongs to another workspace');
+    return snapshot;
+}
+export function currentSnapshotMatches(workspaceRoot, snapshot, policy = {}) {
+    const current = createSnapshot(workspaceRoot, policy, snapshot.workspace_id);
+    return current.snapshot_id === snapshot.snapshot_id;
+}
+export function assertSnapshotCurrent(workspaceRoot, snapshot, policy = {}) {
+    if (!currentSnapshotMatches(workspaceRoot, snapshot, policy))
+        throw new Error('snapshot is stale; create a new snapshot before continuing');
+}

package/dist/code-intelligence/transactions.js

@@ -0,0 +1,60 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, openSync, closeSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { assertSnapshotCurrent } from './snapshots.js';
+import { readPlanApproval } from './edit-plans.js';
+function transactionDir(root) { return join(root, '.yoke', 'code-intelligence', 'transactions'); }
+function hash(value) { return createHash('sha256').update(JSON.stringify(value)).digest('hex'); }
+export function applyEditPlan(root, plan, snapshot, idempotencyKey) {
+    if (plan.expires_at <= new Date().toISOString())
+        throw new Error('edit plan has expired');
+    if (!readPlanApproval(root, plan))
+        throw new Error('edit plan requires Yoke control approval');
+    assertSnapshotCurrent(root, snapshot);
+    if (!existsSync(plan.diff_uri) || hash(readFileSync(plan.diff_uri, 'utf8')) !== plan.diff_hash)
+        throw new Error('edit plan diff has changed');
+    const sandboxHash = hash(plan.changed_paths.map(path => [path, existsSync(join(plan.sandbox_root, path)) ? readFileSync(join(plan.sandbox_root, path)).toString('base64') : null]));
+    if (sandboxHash !== plan.sandbox_hash)
+        throw new Error('edit plan sandbox has changed');
+    const dir = transactionDir(root);
+    mkdirSync(dir, { recursive: true });
+    const idem = join(dir, `${idempotencyKey}.json`);
+    if (existsSync(idem)) {
+        const prior = JSON.parse(readFileSync(idem, 'utf8'));
+        if (prior.plan_id !== plan.plan_id)
+            throw new Error('idempotency key is bound to another plan');
+        return prior;
+    }
+    const lock = join(dir, '.write.lock');
+    let handle;
+    try {
+        handle = openSync(lock, 'wx');
+    }
+    catch {
+        throw new Error('another code-intelligence transaction is active');
+    }
+    try {
+        const transactionId = `tx-${randomUUID()}`;
+        const worktree = join(root, '.yoke', 'code-intelligence', 'worktrees', transactionId);
+        mkdirSync(worktree, { recursive: true });
+        for (const path of plan.changed_paths) {
+            const source = join(plan.sandbox_root, path);
+            const target = join(worktree, path);
+            if (!existsSync(source))
+                continue;
+            mkdirSync(dirname(target), { recursive: true });
+            copyFileSync(source, target);
+        }
+        const result = { transaction_id: transactionId, plan_id: plan.plan_id, changed_paths: plan.changed_paths, worktree, new_snapshot_id: snapshot.snapshot_id, validation: plan.validation, committed: false, merged: false };
+        writeFileSync(idem, JSON.stringify(result, null, 2) + '\n', { mode: 0o600 });
+        return result;
+    }
+    finally {
+        if (handle !== undefined)
+            closeSync(handle);
+        try {
+            unlinkSync(lock);
+        }
+        catch { /* best effort */ }
+    }
+}

package/dist/dashboard/analytics.js

@@ -1,5 +1,6 @@
 import { readMeasurements } from '../observability/history.js';
-import { readEvents } from '../observability/events.js';
+import { EVENT_CAP, readEvents } from '../observability/events.js';
+import { DASHBOARD_LIMITS } from './contracts.js';
 export function parsePeriod(params, now = Date.now()) {
     const to = params.has('to') ? Date.parse(params.get('to')) : now;
     const from = params.has('from') ? Date.parse(params.get('from')) : to - 30 * 86400000;
@@ -9,7 +10,6 @@ export function parsePeriod(params, now = Date.now()) {
     return { from, to, bucket: bucket };
 }
 const finite = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0;
-const numeric = (value) => finite(value) ? value : 0;
 const name = (value) => typeof value === 'string' ? value.slice(0, 200) : 'unknown';
 function bucketOf(timestamp, bucket) {
     const date = new Date(timestamp);
@@ -20,12 +20,17 @@ function bucketOf(timestamp, bucket) {
     return date.toISOString().slice(0, 10);
 }
 function empty() {
-    return { inputTokens: 0, outputTokens: 0, cachedInputTokens: 0, cacheWriteInputTokens: 0, reportedCostUsd: 0,
-        measuredCalls: 0, unknownCalls: 0, costReportedCalls: 0, incompleteCosts: 0, callDurationMs: 0, attemptDurationMs: 0,
-        attempts: 0, successfulAttempts: 0, accepted: 0, repairs: 0, escalations: 0, unmeasuredAttempts: 0 };
+    return { inputTokens: null, outputTokens: null, cachedInputTokens: null, cacheWriteInputTokens: null, reasoningOutputTokens: null, reportedCostUsd: null,
+        measuredCalls: 0, unknownCalls: 0, costReportedCalls: 0, incompleteCosts: 0, callDurationMs: null, attemptDurationMs: null,
+        attempts: 0, successfulAttempts: 0, accepted: 0, repairs: 0, escalations: 0, unmeasuredAttempts: 0, activity: 0 };
+}
+function addMetric(target, key, value) {
+    if (finite(value))
+        target[key] = (target[key] ?? 0) + value;
 }
 export function aggregateMeasurements(events, period) {
-    const total = empty(), buckets = new Map(), models = new Map(), modelBuckets = new Map(), tasks = new Map(), phases = new Map();
+    const total = empty(), buckets = new Map(), models = new Map(), modelBuckets = new Map(), tasks = new Map();
+    const dimensions = { agents: new Map(), providers: new Map(), variants: new Map(), roles: new Map(), phases: new Map() };
     const modelDetails = new Map();
     const seen = new Set(), accepted = new Set();
     let earliest, latest;
@@ -42,23 +47,40 @@ export function aggregateMeasurements(events, period) {
             latest = event.timestamp;
         const data = event.data ?? {}, bucket = get(buckets, bucketOf(event.timestamp, period.bucket)), task = get(tasks, event.storyId ?? 'unattributed');
         const targets = [total, bucket, task];
+        for (const target of targets)
+            target.activity++;
         if (event.type === 'tokens') {
             const calls = Array.isArray(data.calls) && data.calls.length ? data.calls : [{ ...data, actualModel: data.model, durationMs: event.durationMs }];
             for (const item of calls) {
                 if (!item || typeof item !== 'object')
                     continue;
                 const call = item;
-                const provider = name(call.provider), model = name(call.actualModel), role = name(call.role);
+                const provider = name(call.provider ?? data.provider), model = name(call.actualModel ?? call.model ?? data.actualModel ?? data.model), role = name(call.role ?? data.role);
                 const key = JSON.stringify([provider, model, role]);
                 modelDetails.set(key, { provider, model, role });
-                for (const target of [...targets, get(models, key), get(modelBuckets, JSON.stringify([bucketOf(event.timestamp, period.bucket), provider, model, role]))]) {
-                    target.inputTokens += numeric(call.inputTokens);
-                    target.outputTokens += numeric(call.outputTokens);
-                    target.cachedInputTokens += numeric(call.cachedInputTokens);
-                    target.cacheWriteInputTokens += numeric(call.cacheWriteInputTokens);
-                    target.reportedCostUsd += numeric(call.totalCostUsd);
-                    target.callDurationMs += numeric(call.durationMs);
-                    const measured = finite(call.inputTokens) && finite(call.outputTokens) && call.usageAvailable !== false && call.measurementComplete !== false;
+                const dimensionTargets = [];
+                for (const [kind, value] of Object.entries({
+                    agents: name(call.agent ?? data.agent ?? data.agentName ?? data.provider),
+                    providers: provider,
+                    variants: name(call.variant ?? data.variant),
+                    roles: role,
+                })) {
+                    const dimension = get(dimensions[kind], value);
+                    dimension.activity++;
+                    dimensionTargets.push(dimension);
+                }
+                for (const target of [...targets, get(models, key), get(modelBuckets, JSON.stringify([bucketOf(event.timestamp, period.bucket), provider, model, role])), ...dimensionTargets]) {
+                    const usageAvailable = call.usageAvailable !== false && data.usageAvailable !== false && call.measurementComplete !== false && data.measurementComplete !== false;
+                    if (usageAvailable) {
+                        addMetric(target, 'inputTokens', call.inputTokens);
+                        addMetric(target, 'outputTokens', call.outputTokens);
+                        addMetric(target, 'cachedInputTokens', call.cachedInputTokens);
+                        addMetric(target, 'cacheWriteInputTokens', call.cacheWriteInputTokens);
+                        addMetric(target, 'reasoningOutputTokens', call.reasoningOutputTokens);
+                    }
+                    addMetric(target, 'reportedCostUsd', call.totalCostUsd);
+                    addMetric(target, 'callDurationMs', call.durationMs);
+                    const measured = finite(call.inputTokens) && finite(call.outputTokens) && usageAvailable;
                     if (measured)
                         target.measuredCalls++;
                     else
@@ -75,7 +97,11 @@ export function aggregateMeasurements(events, period) {
         }
         else if (event.type === 'phase-ended') {
             const phase = name(event.phase);
-            phases.set(phase, (phases.get(phase) ?? 0) + numeric(event.durationMs));
+            const phaseTarget = get(dimensions.phases, phase);
+            phaseTarget.activity++;
+            addMetric(phaseTarget, 'attemptDurationMs', event.durationMs);
+            if (phase === 'repairing')
+                phaseTarget.repairs++;
             if (phase === 'repairing')
                 for (const target of targets)
                     target.repairs++;
@@ -83,7 +109,7 @@ export function aggregateMeasurements(events, period) {
         else if (event.type === 'attempt-ended') {
             for (const target of targets) {
                 target.attempts++;
-                target.attemptDurationMs += numeric(event.durationMs);
+                addMetric(target, 'attemptDurationMs', event.durationMs);
                 if (['completed', 'passed'].includes(event.outcome ?? ''))
                     target.successfulAttempts++;
                 if (data.usageAvailable !== true)
@@ -99,25 +125,163 @@ export function aggregateMeasurements(events, period) {
             }
         }
     }
-    const decorate = (value) => ({ ...value,
-        tokensPerCallMinute: value.callDurationMs > 0 ? (value.inputTokens + value.outputTokens) / (value.callDurationMs / 60000) : null,
-        tokensPerAccepted: value.accepted ? (value.inputTokens + value.outputTokens) / value.accepted : null,
-        timePerAcceptedMs: value.accepted ? value.attemptDurationMs / value.accepted : null,
-        costState: value.costReportedCalls === 0 ? 'unknown' : value.costReportedCalls === value.measuredCalls && value.unknownCalls === 0 && value.unmeasuredAttempts === 0 && value.incompleteCosts === 0 ? 'measured' : 'partial',
-    });
-    return { total: { ...decorate(total), tokensPerElapsedMinute: (total.inputTokens + total.outputTokens) / ((period.to - period.from) / 60000) },
+    const decorate = (value) => {
+        const tokens = value.inputTokens !== null && value.outputTokens !== null ? value.inputTokens + value.outputTokens : null;
+        const costState = value.costReportedCalls === 0 ? 'unknown' : value.costReportedCalls === value.measuredCalls && value.unknownCalls === 0 && value.unmeasuredAttempts === 0 && value.incompleteCosts === 0 ? 'measured' : 'partial';
+        return { ...value,
+            tokensPerCallMinute: tokens !== null && value.callDurationMs !== null && value.callDurationMs > 0 ? tokens / (value.callDurationMs / 60000) : null,
+            tokensPerAccepted: tokens !== null && value.accepted ? tokens / value.accepted : null,
+            timePerAcceptedMs: value.accepted && value.attemptDurationMs !== null ? value.attemptDurationMs / value.accepted : null,
+            costState,
+            attention: value.unknownCalls + value.unmeasuredAttempts + value.incompleteCosts + Math.max(0, value.attempts - value.successfulAttempts) + value.repairs + value.escalations,
+            tokens: { input: value.inputTokens, output: value.outputTokens, cachedInput: value.cachedInputTokens, cacheWriteInput: value.cacheWriteInputTokens, reasoningOutput: value.reasoningOutputTokens, total: tokens },
+            calls: { measured: value.measuredCalls, unknown: value.unknownCalls, total: value.measuredCalls + value.unknownCalls },
+            outcomes: { attempts: value.attempts, successfulAttempts: value.successfulAttempts, accepted: value.accepted, repairs: value.repairs, escalations: value.escalations },
+            time: { callDurationMs: value.callDurationMs, attemptDurationMs: value.attemptDurationMs, elapsedMs: value.attemptDurationMs },
+            cost: { reportedUsd: value.reportedCostUsd, reportedCalls: value.costReportedCalls, incompleteCalls: value.incompleteCosts, state: costState, coverage: costState },
+        };
+    };
+    const dimensionRows = (kind) => [...dimensions[kind]].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([name, value]) => ({ name, ...decorate(value) }));
+    const phaseRows = dimensionRows('phases').map(row => ({ phase: row.name, durationMs: row.time.attemptDurationMs, ...row }));
+    const decoratedTotal = decorate(total);
+    return { total: { ...decoratedTotal, tokensPerElapsedMinute: decoratedTotal.tokensPerCallMinute === null && (total.inputTokens === null || total.outputTokens === null) ? null : (total.inputTokens + total.outputTokens) / ((period.to - period.from) / 60000) },
         buckets: [...buckets].sort(([a], [b]) => a.localeCompare(b)).map(([label, value]) => ({ label, ...decorate(value) })),
         models: [...models].map(([key, value]) => ({ ...modelDetails.get(key), ...decorate(value) })),
         modelBuckets: [...modelBuckets].sort(([a], [b]) => a.localeCompare(b)).map(([key, value]) => { const [label, provider, model, role] = JSON.parse(key); return { label, provider, model, role, ...decorate(value) }; }),
         tasks: [...tasks].map(([storyId, value]) => ({ storyId, ...decorate(value) })),
-        phases: [...phases].map(([phase, durationMs]) => ({ phase, durationMs })), earliest, latest, };
+        phases: phaseRows, earliest, latest,
+        dimensions: { agents: dimensionRows('agents'), providers: dimensionRows('providers'), variants: dimensionRows('variants'), roles: dimensionRows('roles'), phases: phaseRows },
+        agents: dimensionRows('agents'), providers: dimensionRows('providers'), variants: dimensionRows('variants'), roles: dimensionRows('roles'), };
+}
+export function parseRanking(params) {
+    const value = params.get('sort') ?? 'attention';
+    if (!['attention', 'activity', 'tokens', 'cost', 'acceptance', 'name'].includes(value))
+        throw Error('Choose a valid ranking: attention, activity, tokens, cost, acceptance or name');
+    return value;
+}
+function compareNames(left, right) { return left < right ? -1 : left > right ? 1 : 0; }
+function compareMetric(left, right) {
+    if (left === null && right === null)
+        return 0;
+    if (left === null)
+        return 1;
+    if (right === null)
+        return -1;
+    return right - left;
+}
+function rankingComparator(key) {
+    return (left, right) => {
+        if (key === 'name')
+            return compareNames(left.name, right.name) || compareNames(JSON.stringify(left), JSON.stringify(right));
+        return compareMetric(left[key], right[key]) || compareNames(left.name, right.name) || compareNames(JSON.stringify(left), JSON.stringify(right));
+    };
+}
+export function rankProjections(rows) {
+    const views = {};
+    for (const key of ['attention', 'activity', 'tokens', 'cost', 'acceptance', 'name'])
+        views[key] = [...rows].sort(rankingComparator(key));
+    return views;
+}
+function rankingRow(name, value) {
+    return { name, attention: value.attention, activity: value.activity, tokens: value.tokens.total, cost: value.cost.reportedUsd, acceptance: value.outcomes.accepted, costState: value.costState, total: value };
+}
+function dimensionRankings(aggregate, runs = []) {
+    return {
+        agents: rankProjections(aggregate.agents.map(row => rankingRow(row.name, row))),
+        providers: rankProjections(aggregate.providers.map(row => rankingRow(row.name, row))),
+        models: rankProjections(aggregate.models.map(row => rankingRow(row.model, row))),
+        variants: rankProjections(aggregate.variants.map(row => rankingRow(row.name, row))),
+        roles: rankProjections(aggregate.roles.map(row => rankingRow(row.name, row))),
+        phases: rankProjections(aggregate.dimensions.phases.map(row => rankingRow(row.name, row))),
+        runs: rankProjections(runs.map(run => rankingRow(run.runId, run.total))),
+    };
+}
+function projectEvents(root, period) {
+    const history = readMeasurements(root, period.from, period.to), seen = new Set();
+    const events = [...history.events, ...readEvents(root, EVENT_CAP)].filter(event => {
+        const time = Date.parse(event.timestamp);
+        if (seen.has(event.id) || !Number.isFinite(time) || time < period.from || time >= period.to)
+            return false;
+        seen.add(event.id);
+        return true;
+    }).sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+    return { events, errors: history.errors };
+}
+function textValue(value) { return typeof value === 'string' && value.length > 0 ? value.slice(0, 200) : undefined; }
+function eventMetadata(event) {
+    const direct = event, data = event.data ?? {};
+    const calls = Array.isArray(data.calls) ? data.calls.filter(item => item && typeof item === 'object') : [];
+    const sources = [direct, ...calls, data];
+    const first = (keys) => { for (const source of sources)
+        for (const key of keys) {
+            const value = textValue(source[key]);
+            if (value)
+                return value;
+        } return undefined; };
+    return { agent: first(['agent']), provider: first(['provider']), model: first(['actualModel', 'model']), variant: first(['variant']), role: first(['role']) };
+}
+function runProjections(events, period) {
+    const byRun = new Map();
+    for (const event of events)
+        byRun.set(event.runId, [...(byRun.get(event.runId) ?? []), event]);
+    return [...byRun].map(([runId, runEvents]) => {
+        const metadata = {}, phases = [], timestamps = runEvents.map(event => new Date(event.timestamp).toISOString());
+        for (const event of runEvents) {
+            const values = eventMetadata(event);
+            for (const key of ['agent', 'provider', 'model', 'variant', 'role'])
+                if (metadata[key] === undefined && values[key] !== undefined)
+                    metadata[key] = values[key];
+            const phase = textValue(event.phase ?? event.data?.phase);
+            if (phase && !phases.includes(phase))
+                phases.push(phase);
+        }
+        const total = aggregateMeasurements(runEvents, period).total;
+        return { runId, ...metadata, ...(phases.length ? { phase: phases[phases.length - 1], phases } : {}), timestamps, startedAt: timestamps[0], endedAt: timestamps[timestamps.length - 1], events: runEvents, total, analytics: total };
+    }).sort((left, right) => compareNames(left.startedAt, right.startedAt) || compareNames(left.runId, right.runId));
+}
+export function projectHistory(root, period, limit = DASHBOARD_LIMITS.events) {
+    if (!Number.isInteger(limit) || limit < 1 || limit > DASHBOARD_LIMITS.events)
+        throw Error('Limit must be an integer from 1 to ' + DASHBOARD_LIMITS.events);
+    const history = projectEvents(root, period), events = history.events.slice(-limit);
+    return { from: new Date(period.from).toISOString(), to: new Date(period.to).toISOString(), bucket: period.bucket, timezone: 'UTC', events, runs: runProjections(events, period), errors: history.errors,
+        coverage: 'Recorded measurements only. Earlier unrecorded or expired activity cannot be reconstructed. Usage is assigned to its reporting time; durations to their end time.' };
+}
+export function workspaceAnalytics(projects, period, sort = 'attention') {
+    const source = [];
+    const allEvents = [];
+    for (const project of projects.slice(0, DASHBOARD_LIMITS.projects)) {
+        if (project.error || !project.root) {
+            source.push({ project, analytics: null, errors: [project.error ?? 'Project directory is unavailable'] });
+            continue;
+        }
+        try {
+            const history = projectEvents(project.root, period);
+            allEvents.push(...history.events);
+            const aggregate = aggregateMeasurements(history.events, period);
+            source.push({ project, analytics: { ...aggregate, from: new Date(period.from).toISOString(), to: new Date(period.to).toISOString(), bucket: period.bucket, timezone: 'UTC', errors: history.errors, coverage: 'Recorded measurements only. Earlier unrecorded or expired activity cannot be reconstructed. Usage is assigned to its reporting time; durations to their end time.' }, errors: history.errors });
+        }
+        catch (error) {
+            source.push({ project, analytics: null, errors: [error.message] });
+        }
+    }
+    const aggregate = aggregateMeasurements(allEvents, period);
+    const runs = runProjections(allEvents, period);
+    const projectsWithMetrics = source.map(({ project, analytics, errors }) => {
+        const total = analytics?.total;
+        return { id: project.id, name: project.name, analytics, errors, attention: project.attention ?? ((project.error ? 1 : 0) + (total?.attention ?? 0)), activity: total?.activity ?? null, tokens: total?.tokens.total ?? null, cost: total?.cost.reportedUsd ?? null, acceptance: total?.outcomes.accepted ?? null, costState: total?.costState ?? 'unknown' };
+    });
+    const projectRankings = rankProjections(projectsWithMetrics);
+    const rankings = { projects: projectRankings, ...dimensionRankings(aggregate, runs) };
+    return { ...aggregate, from: new Date(period.from).toISOString(), to: new Date(period.to).toISOString(), bucket: period.bucket, timezone: 'UTC',
+        projects: projectRankings[sort], runs, rankings, errors: source.flatMap(row => row.errors) };
 }
 export function projectAnalytics(root, period) {
-    const history = readMeasurements(root, period.from, period.to);
-    const recent = readEvents(root, 1000);
-    return { ...aggregateMeasurements([...history.events, ...recent], period),
+    const history = projectEvents(root, period);
+    const aggregate = aggregateMeasurements(history.events, period);
+    const runs = runProjections(history.events, period);
+    return { ...aggregate,
         from: new Date(period.from).toISOString(), to: new Date(period.to).toISOString(), bucket: period.bucket, timezone: 'UTC',
-        errors: history.errors,
+        runs, rankings: dimensionRankings(aggregate, runs), errors: history.errors,
         coverage: 'Recorded measurements only. Earlier unrecorded or expired activity cannot be reconstructed. Usage is assigned to its reporting time; durations to their end time.',
     };
 }

package/dist/dashboard/contracts.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+export const DASHBOARD_LIMITS = {
+    projects: 500,
+    events: 100,
+    historyBytes: 32 * 1024 * 1024,
+    requestBytes: 16 * 1024,
+    fileBytes: 1_048_576,
+    noteChars: 4000,
+    changeChars: 8000,
+};
+export const DashboardControlPayloadSchema = z.object({ action: z.literal('pause') }).strict();
+export const DashboardResumePayloadSchema = z.object({ action: z.literal('resume') }).strict();
+export const DashboardNotePayloadSchema = z.object({ note: z.string().trim().min(1).max(DASHBOARD_LIMITS.noteChars) }).strict();
+export const DashboardChangePayloadSchema = z.object({ request: z.string().trim().min(1).max(DASHBOARD_LIMITS.changeChars) }).strict();
+export const DashboardControlResponseSchema = z.object({ status: z.literal('pause-requested') });
+export function parseDashboardLimit(value) {
+    if (value === null)
+        return DASHBOARD_LIMITS.events;
+    const limit = Number(value);
+    if (!Number.isInteger(limit) || limit < 1 || limit > DASHBOARD_LIMITS.events)
+        throw Error(`Limit must be an integer from 1 to ${DASHBOARD_LIMITS.events}`);
+    return limit;
+}