sidekick-shared 0.22.0 → 0.23.0

package/dist/analytics/qualityScore.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scoreSessionQuality = scoreSessionQuality;
+exports.calculateQualityTrend = calculateQualityTrend;
+function awarded(maximum, ratio) {
+    return Math.round(maximum * Math.max(0, Math.min(1, ratio)) * 10) / 10;
+}
+function scoreSessionQuality(metrics) {
+    const latencyMs = metrics.latencyStats?.avgFirstTokenLatencyMs ?? 0;
+    const latencyRatio = latencyMs > 0 ? 1 - Math.min(1, latencyMs / 15_000) : 1;
+    const completedCalls = metrics.toolStats.reduce((sum, tool) => sum + tool.completedCount, 0);
+    const errorRate = completedCalls > 0 ? metrics.errorRollup.totalFailures / completedCalls : 0;
+    const contextTokens = Math.max(1, metrics.tokens.inputTokens + metrics.tokens.cacheReadTokens + metrics.tokens.cacheWriteTokens);
+    const evicted = metrics.compactionEvents.reduce((sum, event) => sum + event.tokensReclaimed, 0);
+    const contextRatio = 1 - Math.min(1, evicted / contextTokens);
+    const start = metrics.sessionStartTime ? Date.parse(metrics.sessionStartTime) : NaN;
+    const end = metrics.lastEventTime ? Date.parse(metrics.lastEventTime) : NaN;
+    let bypassMs = 0;
+    for (let index = 0; index < metrics.permissionModeHistory.length; index++) {
+        const change = metrics.permissionModeHistory[index];
+        if (change.mode !== 'bypassPermissions')
+            continue;
+        const from = Date.parse(change.timestamp);
+        const to = Date.parse(metrics.permissionModeHistory[index + 1]?.timestamp ?? metrics.lastEventTime ?? '');
+        if (Number.isFinite(from) && Number.isFinite(to))
+            bypassMs += Math.max(0, to - from);
+    }
+    const sessionMs = Number.isFinite(start) && Number.isFinite(end) ? Math.max(1, end - start) : 1;
+    const bypassRatio = Math.min(1, bypassMs / sessionMs);
+    const tasks = Array.from(metrics.taskState.tasks.values()).filter((task) => task.status !== 'deleted');
+    const completedTasks = tasks.filter((task) => task.status === 'completed').length;
+    const goalGates = tasks.filter((task) => task.isGoalGate);
+    const completedGates = goalGates.filter((task) => task.status === 'completed').length;
+    const taskRatio = tasks.length > 0 ? completedTasks / tasks.length : 1;
+    const goalRatio = goalGates.length > 0 ? completedGates / goalGates.length : taskRatio;
+    const outcomeRatio = taskRatio * 0.6 + goalRatio * 0.4;
+    const factors = [
+        {
+            id: 'latency',
+            label: 'Response latency',
+            contribution: awarded(15, latencyRatio),
+            maximum: 15,
+            detail: latencyMs > 0 ? `${Math.round(latencyMs)}ms average first token` : 'No latency penalty',
+        },
+        {
+            id: 'reliability',
+            label: 'Tool reliability',
+            contribution: awarded(30, 1 - Math.min(1, errorRate * 2)),
+            maximum: 30,
+            detail: `${metrics.errorRollup.totalFailures}/${completedCalls} completed tool calls failed`,
+        },
+        {
+            id: 'context',
+            label: 'Context stability',
+            contribution: awarded(15, contextRatio),
+            maximum: 15,
+            detail: `${metrics.compactionCount} compactions, ${evicted} tokens evicted`,
+        },
+        {
+            id: 'permission_safety',
+            label: 'Permission safety',
+            contribution: awarded(10, 1 - bypassRatio),
+            maximum: 10,
+            detail: `${Math.round(bypassRatio * 100)}% of observed time bypassing permissions`,
+        },
+        {
+            id: 'outcomes',
+            label: 'Task outcomes',
+            contribution: awarded(30, outcomeRatio),
+            maximum: 30,
+            detail: `${completedTasks}/${tasks.length} tasks and ${completedGates}/${goalGates.length} goal gates completed`,
+        },
+    ];
+    return {
+        score: Math.round(factors.reduce((sum, factor) => sum + factor.contribution, 0)),
+        beta: true,
+        factors,
+    };
+}
+function calculateQualityTrend(records, now = new Date()) {
+    const end = now.getTime();
+    const week = 7 * 24 * 60 * 60 * 1000;
+    const eligible = records.filter((record) => record.qualityScore > 0 && Number.isFinite(Date.parse(record.endTime)));
+    const current = eligible.filter((record) => {
+        const at = Date.parse(record.endTime);
+        return at >= end - week && at <= end;
+    });
+    const previous = eligible.filter((record) => {
+        const at = Date.parse(record.endTime);
+        return at >= end - 2 * week && at < end - week;
+    });
+    const average = (items) => items.length > 0
+        ? Math.round((items.reduce((sum, item) => sum + item.qualityScore, 0) / items.length) * 10) /
+            10
+        : null;
+    const currentWeekAverage = average(current);
+    const previousWeekAverage = average(previous);
+    const delta = currentWeekAverage != null && previousWeekAverage != null
+        ? Math.round((currentWeekAverage - previousWeekAverage) * 10) / 10
+        : null;
+    return {
+        currentWeekAverage,
+        previousWeekAverage,
+        delta,
+        direction: delta == null
+            ? 'insufficient'
+            : delta > 0.5
+                ? 'improving'
+                : delta < -0.5
+                    ? 'declining'
+                    : 'flat',
+        currentWeekSessions: current.length,
+        previousWeekSessions: previous.length,
+    };
+}

package/dist/codexProfiles.js

@@ -382,6 +382,7 @@ function resolveActiveCodexAccount() {
             email: identity.email ?? match?.email ?? match?.metadata?.email,
             label: match?.label,
             providerAccountId: match?.providerAccountId ?? identity.workspaceId,
+            registryAccountId: match?.id,
             source: 'live',
         };
     }
@@ -392,6 +393,7 @@ function resolveActiveCodexAccount() {
             email: active.email ?? active.metadata?.email,
             label: active.label,
             providerAccountId: active.providerAccountId,
+            registryAccountId: active.id,
             source: 'registry',
         };
     }

package/dist/context/composer.d.ts

@@ -5,7 +5,8 @@ import type { PersistedTask } from '../types/taskPersistence';
 import type { DecisionEntry } from '../types/decisionLog';
 import type { KnowledgeNote } from '../types/knowledgeNote';
 import type { TokenTotals } from '../types/historicalData';
-import type { SessionProvider, SessionFileStats, ProviderId } from '../providers/types';
+import type { SessionProviderBase, SessionFileStats, ProviderId } from '../providers/types';
+import type { ProjectIdentity } from '../paths';
 export type Fidelity = 'full' | 'compact' | 'brief';
 export interface ContextResult {
     provider: ProviderId;
@@ -28,4 +29,4 @@ export interface ContextResult {
     } | null;
     sessionSummaries: SessionFileStats[];
 }
-export declare function composeContext(slug: string, fidelity: Fidelity, provider: SessionProvider, workspacePath?: string): Promise<ContextResult>;
+export declare function composeContext(project: string | ProjectIdentity, fidelity: Fidelity, provider: SessionProviderBase, workspacePath?: string): Promise<ContextResult>;

package/dist/context/composer.js

@@ -9,14 +9,14 @@ const decisions_1 = require("../readers/decisions");
 const notes_1 = require("../readers/notes");
 const history_1 = require("../readers/history");
 const handoff_1 = require("../readers/handoff");
-async function composeContext(slug, fidelity, provider, workspacePath) {
+async function composeContext(project, fidelity, provider, workspacePath) {
     // Fetch all data in parallel
     const [allTasks, allDecisions, allNotes, history, handoff] = await Promise.all([
-        (0, tasks_1.readTasks)(slug),
-        (0, decisions_1.readDecisions)(slug),
-        (0, notes_1.readNotes)(slug),
+        (0, tasks_1.readTasks)(project),
+        (0, decisions_1.readDecisions)(project),
+        (0, notes_1.readNotes)(project),
         (0, history_1.readHistory)(),
-        (0, handoff_1.readLatestHandoff)(slug),
+        (0, handoff_1.readLatestHandoff)(project),
     ]);
     // Get session summaries
     const sessionFiles = workspacePath ? provider.findAllSessions(workspacePath) : [];

package/dist/doctor.d.ts

@@ -0,0 +1,55 @@
+import { type ActiveAccountStatus } from './accountStatus';
+import { type ProjectIdentity } from './paths';
+import { type ProviderStatusState } from './providerStatus';
+import { type OpenCodeDbRuntimeStatus } from './providers/openCodeDatabase';
+export type HealthCheckStatus = 'ok' | 'warning' | 'error' | 'info';
+export interface HealthCheck {
+    id: 'project_slug' | 'session_discovery' | 'opencode_sqlite' | 'accounts' | 'provider_api' | 'deprecated_settings';
+    status: HealthCheckStatus;
+    title: string;
+    message: string;
+    repair?: string;
+}
+export interface DeprecatedSetting {
+    key: string;
+    replacement?: string;
+}
+export interface SessionDiagnostics {
+    workspacePath: string;
+    encodedPath: string;
+    expectedSessionDir: string;
+    expectedDirExists: boolean;
+    discoveredSessionDir: string | null;
+    existingProjectDirs: string[];
+    similarDirs: string[];
+    platform: string;
+    subdirectoryMatches: string[];
+    selectedSubdirectoryMatch: string | null;
+}
+export interface HealthReport {
+    schemaVersion: 1;
+    generatedAt: string;
+    project: ProjectIdentity;
+    status: 'healthy' | 'attention' | 'unhealthy';
+    checks: HealthCheck[];
+    accounts: ActiveAccountStatus;
+    openCode: OpenCodeDbRuntimeStatus;
+    providerStatus: {
+        claude: ProviderStatusState;
+        openai: ProviderStatusState;
+    };
+    sessions: SessionDiagnostics;
+}
+export interface DoctorOptions {
+    cwd?: string;
+    deprecatedSettings?: DeprecatedSetting[];
+    openCodeStatus?: OpenCodeDbRuntimeStatus;
+    fetchStatuses?: () => Promise<{
+        claude: ProviderStatusState;
+        openai: ProviderStatusState;
+    }>;
+}
+/** Collects the Claude Code path-resolution detail used by both host surfaces. */
+export declare function getSessionDiagnostics(workspacePath: string): SessionDiagnostics;
+export declare function runDoctor(options?: DoctorOptions): Promise<HealthReport>;
+export declare function formatHealthReport(report: HealthReport): string;

package/dist/doctor.js

@@ -0,0 +1,244 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSessionDiagnostics = getSessionDiagnostics;
+exports.runDoctor = runDoctor;
+exports.formatHealthReport = formatHealthReport;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const accountStatus_1 = require("./accountStatus");
+const paths_1 = require("./paths");
+const sessionPathResolver_1 = require("./parsers/sessionPathResolver");
+const providerStatus_1 = require("./providerStatus");
+const openCode_1 = require("./providers/openCode");
+const openCodeDatabase_1 = require("./providers/openCodeDatabase");
+/** Collects the Claude Code path-resolution detail used by both host surfaces. */
+function getSessionDiagnostics(workspacePath) {
+    const encodedPath = (0, sessionPathResolver_1.encodeWorkspacePath)(workspacePath);
+    const expectedSessionDir = (0, sessionPathResolver_1.getSessionDirectory)(workspacePath);
+    const projectsDir = path.join(os.homedir(), '.claude', 'projects');
+    let existingProjectDirs = [];
+    let expectedDirExists = false;
+    try {
+        if (fs.existsSync(projectsDir)) {
+            existingProjectDirs = fs
+                .readdirSync(projectsDir)
+                .filter((name) => {
+                try {
+                    return fs.statSync(path.join(projectsDir, name)).isDirectory();
+                }
+                catch {
+                    return false;
+                }
+            })
+                .sort();
+        }
+        expectedDirExists = fs.existsSync(expectedSessionDir);
+    }
+    catch {
+        // Diagnostics remain useful even if a directory cannot be read.
+    }
+    const discoveredSessionDir = (0, sessionPathResolver_1.discoverSessionDirectory)(workspacePath);
+    const workspaceBasename = path.basename(workspacePath).toLowerCase();
+    const similarDirs = existingProjectDirs.filter((directory) => {
+        const lower = directory.toLowerCase();
+        return (lower.includes(workspaceBasename) || workspaceBasename.includes(lower.split('-').pop() || ''));
+    });
+    const subdirectoryMatches = (0, sessionPathResolver_1.findSubdirectorySessionDirs)(workspacePath);
+    return {
+        workspacePath,
+        encodedPath,
+        expectedSessionDir,
+        expectedDirExists,
+        discoveredSessionDir,
+        existingProjectDirs,
+        similarDirs,
+        platform: process.platform,
+        subdirectoryMatches,
+        selectedSubdirectoryMatch: subdirectoryMatches.length > 0 ? (0, sessionPathResolver_1.getMostRecentlyActiveSessionDir)(subdirectoryMatches) : null,
+    };
+}
+function statusUnavailable() {
+    return {
+        indicator: 'none',
+        description: 'Status unavailable',
+        affectedComponents: [],
+        activeIncident: null,
+        updatedAt: new Date().toISOString(),
+    };
+}
+async function runDoctor(options = {}) {
+    const project = (0, paths_1.resolveProjectIdentity)(options.cwd);
+    const sessions = getSessionDiagnostics(project.cwd);
+    const accounts = (0, accountStatus_1.getActiveAccountStatus)();
+    let openCode = options.openCodeStatus;
+    if (!openCode) {
+        const database = new openCodeDatabase_1.OpenCodeDatabase((0, openCode_1.getOpenCodeDataDir)());
+        database.open();
+        openCode = database.getRuntimeStatus();
+    }
+    const providerStatus = await (options.fetchStatuses ??
+        (async () => {
+            const [claude, openai] = await Promise.all([(0, providerStatus_1.fetchProviderStatus)(), (0, providerStatus_1.fetchOpenAIStatus)()]);
+            return { claude, openai };
+        }))().catch(() => ({ claude: statusUnavailable(), openai: statusUnavailable() }));
+    const checks = [];
+    checks.push(project.hasLegacyMismatch
+        ? {
+            id: 'project_slug',
+            status: 'warning',
+            title: 'Project path resolves to a different slug',
+            message: `Legacy ${project.legacySlug}; canonical ${project.canonicalSlug}.`,
+            repair: `Open the resolved path (${project.resolvedCwd}) and merge any legacy project stores into the canonical slug. Sidekick readers keep the legacy fallback.`,
+        }
+        : {
+            id: 'project_slug',
+            status: 'ok',
+            title: 'Project identity',
+            message: `Canonical slug: ${project.canonicalSlug}`,
+        });
+    checks.push(sessions.discoveredSessionDir
+        ? {
+            id: 'session_discovery',
+            status: 'ok',
+            title: 'Session discovery',
+            message: `Found Claude Code sessions at ${sessions.discoveredSessionDir}.`,
+        }
+        : {
+            id: 'session_discovery',
+            status: 'warning',
+            title: 'Session discovery',
+            message: `No Claude Code session directory found for ${project.cwd}.`,
+            repair: `Start Claude Code in this project, or inspect ${sessions.expectedSessionDir}.`,
+        });
+    const openCodeCheck = openCode.available
+        ? {
+            id: 'opencode_sqlite',
+            status: 'ok',
+            title: 'OpenCode database',
+            message: 'OpenCode database and sqlite3 are available.',
+        }
+        : openCode.kind === 'db_missing'
+            ? {
+                id: 'opencode_sqlite',
+                status: 'info',
+                title: 'OpenCode database',
+                message: 'No OpenCode database was found; this is expected if OpenCode is not used.',
+            }
+            : {
+                id: 'opencode_sqlite',
+                status: 'warning',
+                title: 'OpenCode database',
+                message: openCode.message ?? `OpenCode database unavailable (${openCode.kind}).`,
+                repair: openCode.kind === 'sqlite_missing'
+                    ? 'Install sqlite3 and ensure the sqlite3 executable is on PATH, then rerun sidekick doctor.'
+                    : 'Make sqlite3 executable and verify the OpenCode database is readable.',
+            };
+    checks.push(openCodeCheck);
+    checks.push({
+        id: 'accounts',
+        status: accounts.ok ? 'ok' : 'warning',
+        title: 'Accounts and credentials',
+        message: accounts.ok
+            ? `Detected ${[accounts.claude.present && 'Claude', accounts.codex.present && 'Codex'].filter(Boolean).join(' and ')} credentials.`
+            : (accounts.error ?? 'No Claude or Codex credentials were detected.'),
+        ...(!accounts.ok
+            ? { repair: 'Sign in with claude or codex, then rerun sidekick doctor.' }
+            : {}),
+    });
+    const unavailableProviders = Object.entries(providerStatus)
+        .filter(([, status]) => status.description === 'Status unavailable')
+        .map(([name]) => name);
+    const degradedProviders = Object.entries(providerStatus)
+        .filter(([, status]) => status.indicator !== 'none')
+        .map(([name]) => name);
+    checks.push({
+        id: 'provider_api',
+        status: degradedProviders.length > 0 ? 'warning' : unavailableProviders.length > 0 ? 'info' : 'ok',
+        title: 'Provider API status',
+        message: degradedProviders.length > 0
+            ? `Provider incidents reported for: ${degradedProviders.join(', ')}.`
+            : unavailableProviders.length > 0
+                ? `Status pages unavailable for: ${unavailableProviders.join(', ')}.`
+                : 'Claude and OpenAI status pages report normal operation.',
+    });
+    const deprecatedSettings = options.deprecatedSettings ?? [];
+    checks.push({
+        id: 'deprecated_settings',
+        status: deprecatedSettings.length > 0 ? 'warning' : 'ok',
+        title: 'Deprecated settings',
+        message: deprecatedSettings.length > 0
+            ? deprecatedSettings
+                .map((setting) => `${setting.key}${setting.replacement ? ` → ${setting.replacement}` : ''}`)
+                .join(', ')
+            : 'No deprecated Sidekick settings detected.',
+        ...(deprecatedSettings.length > 0
+            ? {
+                repair: 'Move each configured value to its replacement and remove the deprecated setting.',
+            }
+            : {}),
+    });
+    const status = checks.some((check) => check.status === 'error')
+        ? 'unhealthy'
+        : checks.some((check) => check.status === 'warning')
+            ? 'attention'
+            : 'healthy';
+    return {
+        schemaVersion: 1,
+        generatedAt: new Date().toISOString(),
+        project,
+        status,
+        checks,
+        accounts,
+        openCode,
+        providerStatus,
+        sessions,
+    };
+}
+function formatHealthReport(report) {
+    const icon = { ok: '✓', warning: '!', error: '✕', info: '·' };
+    const lines = [
+        `Sidekick Doctor — ${report.status}`,
+        `Project: ${report.project.resolvedCwd}`,
+        '',
+    ];
+    for (const check of report.checks) {
+        lines.push(`${icon[check.status]} ${check.title}: ${check.message}`);
+        if (check.repair)
+            lines.push(`  Repair: ${check.repair}`);
+    }
+    return lines.join('\n');
+}

package/dist/errorHistory.d.ts

@@ -0,0 +1,32 @@
+import type { ErrorRollup, ErrorRollupEntry } from './aggregation/types';
+export declare const ERROR_HISTORY_SCHEMA_VERSION: 1;
+export interface ErrorHistorySessionRecord {
+    sessionId: string;
+    providerId: string;
+    project: string;
+    endedAt: string;
+    failures: ErrorRollupEntry[];
+    retryAttempts: number;
+    finishReasons: Array<{
+        reason: string;
+        count: number;
+    }>;
+}
+export interface ErrorHistoryStore {
+    schemaVersion: 1;
+    sessions: ErrorHistorySessionRecord[];
+    lastSaved: string;
+}
+export interface TopFailingTool {
+    tool: string;
+    failures: number;
+    categories: Record<string, number>;
+}
+export declare function appendErrorHistory(identity: {
+    sessionId: string;
+    providerId: string;
+    project: string;
+    endedAt?: string;
+}, rollup: ErrorRollup, filePath?: string): Promise<ErrorHistorySessionRecord>;
+export declare function readErrorHistory(filePath?: string): Promise<ErrorHistoryStore>;
+export declare function getTopFailingTools(days?: number, now?: Date, filePath?: string): Promise<TopFailingTool[]>;

package/dist/errorHistory.js

@@ -0,0 +1,94 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERROR_HISTORY_SCHEMA_VERSION = void 0;
+exports.appendErrorHistory = appendErrorHistory;
+exports.readErrorHistory = readErrorHistory;
+exports.getTopFailingTools = getTopFailingTools;
+const fs = __importStar(require("fs"));
+const paths_1 = require("./paths");
+const atomic_1 = require("./writers/atomic");
+exports.ERROR_HISTORY_SCHEMA_VERSION = 1;
+function emptyStore() {
+    return {
+        schemaVersion: exports.ERROR_HISTORY_SCHEMA_VERSION,
+        sessions: [],
+        lastSaved: new Date().toISOString(),
+    };
+}
+async function appendErrorHistory(identity, rollup, filePath = (0, paths_1.getGlobalDataPath)('error-history.json')) {
+    const record = {
+        ...identity,
+        endedAt: identity.endedAt ?? new Date().toISOString(),
+        failures: rollup.byToolCategory,
+        retryAttempts: rollup.retryAttempts,
+        finishReasons: rollup.finishReasons,
+    };
+    await (0, atomic_1.updateJsonStoreAtomic)(filePath, emptyStore, (store) => ({
+        ...store,
+        schemaVersion: exports.ERROR_HISTORY_SCHEMA_VERSION,
+        sessions: [...store.sessions, record],
+        lastSaved: record.endedAt,
+    }));
+    return record;
+}
+async function readErrorHistory(filePath = (0, paths_1.getGlobalDataPath)('error-history.json')) {
+    try {
+        const parsed = JSON.parse(await fs.promises.readFile(filePath, 'utf8'));
+        if (parsed.schemaVersion === exports.ERROR_HISTORY_SCHEMA_VERSION && Array.isArray(parsed.sessions))
+            return parsed;
+    }
+    catch {
+        // Missing and malformed history are represented as an empty store.
+    }
+    return emptyStore();
+}
+async function getTopFailingTools(days = 7, now = new Date(), filePath = (0, paths_1.getGlobalDataPath)('error-history.json')) {
+    const cutoff = now.getTime() - Math.max(1, days) * 24 * 60 * 60 * 1000;
+    const store = await readErrorHistory(filePath);
+    const tools = new Map();
+    for (const session of store.sessions) {
+        const endedAt = Date.parse(session.endedAt);
+        if (!Number.isFinite(endedAt) || endedAt < cutoff)
+            continue;
+        for (const failure of session.failures) {
+            const item = tools.get(failure.tool) ?? { tool: failure.tool, failures: 0, categories: {} };
+            item.failures += failure.count;
+            item.categories[failure.category] = (item.categories[failure.category] ?? 0) + failure.count;
+            tools.set(failure.tool, item);
+        }
+    }
+    return Array.from(tools.values()).sort((left, right) => right.failures - left.failures);
+}

package/dist/extractors/errorTaxonomy.d.ts

@@ -0,0 +1,6 @@
+/** Canonical error categories used across providers and Sidekick surfaces. */
+export type ErrorCategory = 'permission' | 'not_found' | 'timeout' | 'syntax' | 'exit_code' | 'tool_error' | 'other';
+/** Classifies provider and tool failures into the stable shared taxonomy. */
+export declare function categorizeError(output: unknown, providerErrorType?: string): ErrorCategory;
+/** Produces the compact error label used by the extension and CLI. */
+export declare function extractErrorMessage(content: unknown, toolName: string): string;

package/dist/extractors/errorTaxonomy.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.categorizeError = categorizeError;
+exports.extractErrorMessage = extractErrorMessage;
+function stringifyError(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value == null)
+        return '';
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+/** Classifies provider and tool failures into the stable shared taxonomy. */
+function categorizeError(output, providerErrorType) {
+    const type = (providerErrorType ?? '').toLowerCase();
+    const text = `${type} ${stringifyError(output)}`.toLowerCase();
+    if (type === 'autherror' ||
+        /permission denied|not permitted|unauthori[sz]ed|forbidden|authentication|access denied/.test(text)) {
+        return 'permission';
+    }
+    if (/not found|no such file|enoent|does not exist|unknown command/.test(text))
+        return 'not_found';
+    if (/timeout|timed out|deadline exceeded|etimedout/.test(text))
+        return 'timeout';
+    if (/syntax error|parse error|invalid syntax/.test(text))
+        return 'syntax';
+    if (/exit[ _-]?code|non[- ]zero exit|process exited/.test(text))
+        return 'exit_code';
+    if (type === 'apierror' ||
+        type === 'outputlengtherror' ||
+        /tool_use_error|tool error|output length|rate limit|retry attempt/.test(text)) {
+        return 'tool_error';
+    }
+    return 'other';
+}
+/** Produces the compact error label used by the extension and CLI. */
+function extractErrorMessage(content, toolName) {
+    let message = stringifyError(content) || 'Unknown error';
+    message = message.replace(/<\/?tool_use_error>/g, '').trim();
+    if (message.length > 150)
+        message = `${message.slice(0, 147)}...`;
+    return `${toolName}: ${message}`;
+}

package/dist/extractors/toolCall.d.ts

@@ -25,6 +25,15 @@ import type { SessionEvent, ToolCall } from '../types/sessionEvent';
  * ```
  */
 export declare function extractToolCalls(event: SessionEvent): ToolCall[];
+/**
+ * Stateful shared extractor that correlates provider-normalized tool uses with
+ * their later results. Completed calls always carry the canonical taxonomy.
+ */
+export declare class ToolCallTracker {
+    private readonly pending;
+    process(event: SessionEvent): ToolCall[];
+    reset(): void;
+}
 /**
  * Extracts a single top-level `tool_use` event.
  *