sidekick-shared 0.25.0 → 0.26.0

package/dist/usage/usageEvents.js

@@ -0,0 +1,322 @@
+"use strict";
+/**
+ * Usage events collected from session logs, cached per session.
+ *
+ * Feeds the billing-block view and the log-derived daily/weekly/monthly
+ * reports, so CLI-only users get numbers without the extension's history
+ * store. Each session is read once through its provider reader; the
+ * extracted usage is cached under `<configDir>/usage-cache/` keyed by the
+ * session's size and mtime, so a repeat run only re-reads sessions that
+ * changed. Token counts are cached raw and priced at load time, so a pricing
+ * catalog refresh never leaves stale costs behind. Cache files are touched on
+ * every hit and pruned least-recently-used, once per collection.
+ *
+ * Node-only: reads session files and the cache directory.
+ *
+ * @module usage/usageEvents
+ */
+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.MAX_USAGE_CACHE_FILES = exports.USAGE_CACHE_VERSION = void 0;
+exports.getUsageCacheDir = getUsageCacheDir;
+exports.pruneUsageCache = pruneUsageCache;
+exports.collectUsageEvents = collectUsageEvents;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const paths_1 = require("../paths");
+const sessionPreviews_1 = require("../sessionPreviews");
+const usageNormalization_1 = require("../usageNormalization");
+const atomic_1 = require("../writers/atomic");
+/** Bump when the cached record shape changes; older files are re-read. */
+exports.USAGE_CACHE_VERSION = 1;
+/**
+ * Most-recently-used cache files kept on disk. Sized for a busy month of
+ * sessions (files are a few KB each); a collection larger than this still
+ * completes, it just re-reads what was evicted. Pruning runs once after a
+ * collection, never during one, so a working set is never evicted mid-run.
+ */
+exports.MAX_USAGE_CACHE_FILES = 5000;
+function getUsageCacheDir() {
+    return path.join((0, paths_1.getConfigDir)(), 'usage-cache');
+}
+function cacheFilePath(dir, provider, sessionId) {
+    const safe = sessionId.replace(/[^A-Za-z0-9._-]/g, '_');
+    return path.join(dir, `${provider}--${safe}.json`);
+}
+function toMs(value, label) {
+    if (value === undefined)
+        return null;
+    const ms = value instanceof Date ? value.getTime() : Date.parse(value);
+    if (!Number.isFinite(ms))
+        throw new RangeError(`Invalid \`${label}\` value: ${String(value)}`);
+    return ms;
+}
+/** Mark a cache file as recently used so LRU pruning keeps it. Best-effort. */
+function touch(filePath) {
+    try {
+        const now = new Date();
+        fs.utimesSync(filePath, now, now);
+    }
+    catch {
+        // Read-only cache or vanished file; the next miss rewrites it.
+    }
+}
+function readCache(filePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        if (parsed?.version !== exports.USAGE_CACHE_VERSION || !Array.isArray(parsed.events))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Deletes all but the `keep` most recently used cache files (by mtime). Best-effort. */
+function pruneUsageCache(keep = exports.MAX_USAGE_CACHE_FILES, dir = getUsageCacheDir()) {
+    try {
+        const entries = fs
+            .readdirSync(dir)
+            .filter((name) => name.endsWith('.json'))
+            .map((name) => {
+            const filePath = path.join(dir, name);
+            try {
+                return { filePath, mtimeMs: fs.statSync(filePath).mtimeMs };
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((entry) => entry !== null)
+            .sort((a, b) => b.mtimeMs - a.mtimeMs);
+        let removed = 0;
+        for (const entry of entries.slice(Math.max(0, keep))) {
+            try {
+                fs.unlinkSync(entry.filePath);
+                removed += 1;
+            }
+            catch {
+                // Already gone; skip.
+            }
+        }
+        return removed;
+    }
+    catch {
+        return 0;
+    }
+}
+function cachedEventFromUsage(usage, timestamp, model) {
+    const record = {
+        t: timestamp,
+        m: model,
+        i: usage.uncachedInputTokens,
+        o: usage.outputTokens,
+        cw: usage.cacheWriteTokens,
+        cr: usage.cacheReadTokens,
+        bo: usage.billableOutputTokens,
+        tt: usage.totalTokens,
+    };
+    if (usage.reportedCostUsd !== undefined)
+        record.rc = usage.reportedCostUsd;
+    return record;
+}
+/** Price a cached event with the current catalog (or its provider-reported cost). */
+function priceCachedEvent(cached, provider, sessionId, project) {
+    const usage = {
+        uncachedInputTokens: cached.i,
+        cacheReadTokens: cached.cr,
+        cacheWriteTokens: cached.cw,
+        outputTokens: cached.o,
+        reasoningTokens: 0,
+        reasoningIncludedInOutput: true,
+        cacheInclusiveInputTokens: cached.i + cached.cr + cached.cw,
+        billableOutputTokens: cached.bo,
+        totalTokens: cached.tt,
+        ...(cached.rc !== undefined ? { reportedCostUsd: cached.rc } : {}),
+        provenance: { semantics: 'sidekick-disjoint' },
+    };
+    const priced = (0, usageNormalization_1.calculateNormalizedUsageCost)({
+        usage,
+        modelId: cached.m === 'unknown' ? undefined : cached.m,
+    });
+    return {
+        timestamp: cached.t,
+        provider,
+        sessionId,
+        project,
+        model: cached.m,
+        tokens: {
+            inputTokens: cached.i,
+            outputTokens: cached.o,
+            cacheWriteTokens: cached.cw,
+            cacheReadTokens: cached.cr,
+            totalTokens: cached.tt,
+        },
+        costUsd: priced.costUsd,
+        costProvenance: priced.source,
+    };
+}
+function readSessionUsage(provider, preview) {
+    const reader = provider.createReader(preview.filePath);
+    const events = reader.readAll();
+    reader.flush();
+    const cached = [];
+    for (const event of events) {
+        const usage = (0, usageNormalization_1.extractNormalizedUsage)(event);
+        if (!usage)
+            continue;
+        const timestamp = Date.parse(event.timestamp);
+        if (!Number.isFinite(timestamp))
+            continue;
+        cached.push(cachedEventFromUsage(usage, timestamp, event.message?.model ?? usage.model ?? 'unknown'));
+    }
+    return cached;
+}
+function yieldToEventLoop() {
+    return new Promise((resolve) => setImmediate(resolve));
+}
+/**
+ * Collect priced usage events for every session touched in the window.
+ *
+ * Sessions are enumerated with `listSessionPreviewsAsync` (the `since`
+ * cutoff applies to the session mtime there and to the event timestamp
+ * here), read once each unless the cache already holds their fingerprint,
+ * and yielded between reads so long-lived hosts stay responsive.
+ */
+async function collectUsageEvents(options) {
+    const sinceMs = toMs(options.since, 'since');
+    const untilMs = toMs(options.until, 'until');
+    const cacheDir = options.cacheDir ?? getUsageCacheDir();
+    const useCache = !options.noCache;
+    const listed = await (0, sessionPreviews_1.listSessionPreviewsAsync)(options.providers, {
+        since: options.since,
+        workspacePath: options.workspacePath,
+        limit: Number.MAX_SAFE_INTEGER,
+        concurrency: options.concurrency,
+    });
+    const diagnostics = [...listed.diagnostics];
+    for (const diagnostic of listed.diagnostics)
+        options.onDiagnostic?.(diagnostic);
+    const providerById = new Map(options.providers.map((provider) => [provider.id, provider]));
+    const events = [];
+    const sessions = [];
+    let cacheHits = 0;
+    let cacheMisses = 0;
+    let wroteCache = false;
+    for (const preview of listed.previews) {
+        const provider = providerById.get(preview.provider);
+        if (!provider)
+            continue;
+        const fingerprint = `${preview.sizeBytes}:${preview.modifiedAt}`;
+        const filePath = cacheFilePath(cacheDir, preview.provider, preview.sessionId);
+        let cachedEvents = null;
+        let project = preview.workspacePath;
+        let fromCache = false;
+        if (useCache) {
+            const cached = readCache(filePath);
+            if (cached && cached.fingerprint === fingerprint && cached.sessionId === preview.sessionId) {
+                cachedEvents = cached.events;
+                project = project ?? cached.project;
+                fromCache = true;
+                cacheHits += 1;
+                touch(filePath);
+            }
+        }
+        if (!cachedEvents) {
+            cacheMisses += 1;
+            try {
+                cachedEvents = readSessionUsage(provider, preview);
+            }
+            catch (error) {
+                const diagnostic = {
+                    providerId: preview.provider,
+                    kind: 'read_failed',
+                    severity: 'warning',
+                    phase: 'read',
+                    message: `Could not read usage for ${preview.provider} session ${preview.sessionId}: ${error instanceof Error ? error.message : String(error)}`,
+                };
+                diagnostics.push(diagnostic);
+                options.onDiagnostic?.(diagnostic);
+                continue;
+            }
+            if (useCache) {
+                const record = {
+                    version: exports.USAGE_CACHE_VERSION,
+                    provider: preview.provider,
+                    sessionId: preview.sessionId,
+                    fingerprint,
+                    project,
+                    events: cachedEvents,
+                };
+                try {
+                    await (0, atomic_1.atomicWriteJson)(filePath, record);
+                    wroteCache = true;
+                }
+                catch {
+                    // The cache is an accelerator; a failed write only costs a re-read.
+                }
+            }
+            await yieldToEventLoop();
+        }
+        let first = null;
+        let last = null;
+        let count = 0;
+        for (const cached of cachedEvents) {
+            if (sinceMs !== null && cached.t < sinceMs)
+                continue;
+            if (untilMs !== null && cached.t > untilMs)
+                continue;
+            events.push(priceCachedEvent(cached, preview.provider, preview.sessionId, project));
+            first = first === null ? cached.t : Math.min(first, cached.t);
+            last = last === null ? cached.t : Math.max(last, cached.t);
+            count += 1;
+        }
+        sessions.push({
+            provider: preview.provider,
+            sessionId: preview.sessionId,
+            filePath: preview.filePath,
+            project,
+            fingerprint,
+            firstTimestamp: first,
+            lastTimestamp: last,
+            eventCount: count,
+            fromCache,
+        });
+    }
+    if (wroteCache)
+        pruneUsageCache(exports.MAX_USAGE_CACHE_FILES, cacheDir);
+    events.sort((a, b) => a.timestamp - b.timestamp);
+    return { events, sessions, diagnostics, cacheHits, cacheMisses };
+}

package/dist/usage/usageReports.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Daily, weekly, monthly, and per-session usage rows bucketed from usage
+ * events by the time of each event, so a session that crosses midnight is
+ * split across the days it actually ran in. Browser-safe: no Node imports.
+ *
+ * @module usage/usageReports
+ */
+import type { AggregatedCostProvenance } from '../aggregation/types';
+import type { ProviderId } from '../providers/types';
+import type { TokenTotals } from '../types/historicalData';
+import type { UsageEventRecord } from './usageEvents';
+export type UsageGranularity = 'day' | 'week' | 'month' | 'session';
+/** Extra dimensions a bucket is split by, beyond the time key. */
+export type UsageGroupDimension = 'provider' | 'project' | 'model';
+export interface BucketUsageOptions {
+    granularity: UsageGranularity;
+    /** Key by the UTC calendar instead of the local calendar (default false). */
+    utc?: boolean;
+    /** First day of the week for `week` keys: 0 = Sunday, 1 = Monday (default). */
+    weekStartsOn?: 0 | 1;
+    /** Dimensions to group by in addition to the time key (default `['provider']`). */
+    groupBy?: readonly UsageGroupDimension[];
+}
+export interface UsageBucketRow {
+    /** `YYYY-MM-DD` for days and week starts, `YYYY-MM` for months, the session id for sessions. */
+    key: string;
+    granularity: UsageGranularity;
+    provider: ProviderId | null;
+    project: string | null;
+    /** Set when grouping by model; null for rows spanning every model. */
+    model: string | null;
+    /** Session id for `session` rows; null otherwise. */
+    sessionId: string | null;
+    /** Models seen in the row, most tokens first. */
+    models: string[];
+    calls: number;
+    /** Distinct sessions contributing to the row. */
+    sessions: number;
+    tokens: TokenTotals;
+    /** Provider-semantics-aware total (`summarizeTokens().total`). */
+    totalTokens: number;
+    /** Priced portion of the cost; read `costProvenance` before labelling it. */
+    costUsd: number;
+    costProvenance: AggregatedCostProvenance;
+    unpricedCalls: number;
+    /** First and last event in the row, ms since epoch. */
+    firstTimestamp: number;
+    lastTimestamp: number;
+}
+export interface UsageTotals {
+    calls: number;
+    sessions: number;
+    tokens: TokenTotals;
+    totalTokens: number;
+    costUsd: number;
+    costProvenance: AggregatedCostProvenance;
+    unpricedCalls: number;
+}
+/** The `YYYY-MM-DD` key of the week containing `ms`, starting on `weekStartsOn`. */
+export declare function weekKey(ms: number, options?: {
+    utc?: boolean;
+    weekStartsOn?: 0 | 1;
+}): string;
+/** The time key for one event at the requested granularity. */
+export declare function usageBucketKey(event: Pick<UsageEventRecord, 'timestamp' | 'sessionId'>, options: BucketUsageOptions): string;
+/**
+ * Group usage events into rows. Rows are sorted by key (sessions by first
+ * event), then provider, project, and model, so tables read oldest first.
+ */
+export declare function bucketUsage(events: readonly UsageEventRecord[], options: BucketUsageOptions): UsageBucketRow[];
+/**
+ * Sum rows that do not overlap (for example every row of one `bucketUsage`
+ * call). Pass the events too when rows are not per-session, so distinct
+ * sessions are counted once instead of once per row they appear in.
+ */
+export declare function summarizeUsageRows(rows: readonly UsageBucketRow[], events?: readonly UsageEventRecord[]): UsageTotals;

package/dist/usage/usageReports.js

@@ -0,0 +1,208 @@
+"use strict";
+/**
+ * Daily, weekly, monthly, and per-session usage rows bucketed from usage
+ * events by the time of each event, so a session that crosses midnight is
+ * split across the days it actually ran in. Browser-safe: no Node imports.
+ *
+ * @module usage/usageReports
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.weekKey = weekKey;
+exports.usageBucketKey = usageBucketKey;
+exports.bucketUsage = bucketUsage;
+exports.summarizeUsageRows = summarizeUsageRows;
+const costProvenance_1 = require("../aggregation/costProvenance");
+const formatting_1 = require("../formatting");
+function dayParts(ms, utc) {
+    const date = new Date(ms);
+    return utc
+        ? {
+            year: date.getUTCFullYear(),
+            month: date.getUTCMonth(),
+            day: date.getUTCDate(),
+            weekday: date.getUTCDay(),
+        }
+        : {
+            year: date.getFullYear(),
+            month: date.getMonth(),
+            day: date.getDate(),
+            weekday: date.getDay(),
+        };
+}
+function pad(value) {
+    return String(value).padStart(2, '0');
+}
+/** The `YYYY-MM-DD` key of the week containing `ms`, starting on `weekStartsOn`. */
+function weekKey(ms, options = {}) {
+    const utc = options.utc ?? false;
+    const start = options.weekStartsOn ?? 1;
+    const parts = dayParts(ms, utc);
+    const offset = (parts.weekday - start + 7) % 7;
+    if (utc) {
+        return new Date(Date.UTC(parts.year, parts.month, parts.day - offset))
+            .toISOString()
+            .slice(0, 10);
+    }
+    return (0, formatting_1.formatLocalDateKey)(new Date(parts.year, parts.month, parts.day - offset));
+}
+/** The time key for one event at the requested granularity. */
+function usageBucketKey(event, options) {
+    const utc = options.utc ?? false;
+    switch (options.granularity) {
+        case 'session':
+            return event.sessionId;
+        case 'week':
+            return weekKey(event.timestamp, { utc, weekStartsOn: options.weekStartsOn });
+        case 'month': {
+            const parts = dayParts(event.timestamp, utc);
+            return `${parts.year}-${pad(parts.month + 1)}`;
+        }
+        case 'day':
+        default:
+            return utc
+                ? new Date(event.timestamp).toISOString().slice(0, 10)
+                : (0, formatting_1.formatLocalDateKey)(event.timestamp);
+    }
+}
+function emptyTokens() {
+    return { inputTokens: 0, outputTokens: 0, cacheWriteTokens: 0, cacheReadTokens: 0 };
+}
+function addTokens(target, source) {
+    target.inputTokens += source.inputTokens;
+    target.outputTokens += source.outputTokens;
+    target.cacheWriteTokens += source.cacheWriteTokens;
+    target.cacheReadTokens += source.cacheReadTokens;
+}
+/**
+ * Group usage events into rows. Rows are sorted by key (sessions by first
+ * event), then provider, project, and model, so tables read oldest first.
+ */
+function bucketUsage(events, options) {
+    const groupBy = new Set(options.groupBy ?? ['provider']);
+    const isSession = options.granularity === 'session';
+    const byProvider = isSession || groupBy.has('provider');
+    const byProject = isSession || groupBy.has('project');
+    const byModel = groupBy.has('model');
+    const buckets = new Map();
+    for (const event of events) {
+        const key = usageBucketKey(event, options);
+        const provider = byProvider ? event.provider : null;
+        const project = byProject ? event.project : null;
+        const model = byModel ? event.model : null;
+        const id = [key, provider ?? '', project ?? '', model ?? ''].join('|');
+        let acc = buckets.get(id);
+        if (!acc) {
+            acc = {
+                row: {
+                    key,
+                    granularity: options.granularity,
+                    provider,
+                    project,
+                    model,
+                    sessionId: isSession ? event.sessionId : null,
+                    models: [],
+                    calls: 0,
+                    sessions: 0,
+                    tokens: emptyTokens(),
+                    totalTokens: 0,
+                    costUsd: 0,
+                    costProvenance: 'none',
+                    unpricedCalls: 0,
+                    firstTimestamp: event.timestamp,
+                    lastTimestamp: event.timestamp,
+                },
+                sessionIds: new Set(),
+                modelTokens: new Map(),
+                reportedCalls: 0,
+                estimatedCalls: 0,
+            };
+            buckets.set(id, acc);
+        }
+        const { row } = acc;
+        row.calls += 1;
+        addTokens(row.tokens, event.tokens);
+        row.totalTokens += event.tokens.totalTokens;
+        row.firstTimestamp = Math.min(row.firstTimestamp, event.timestamp);
+        row.lastTimestamp = Math.max(row.lastTimestamp, event.timestamp);
+        acc.sessionIds.add(event.sessionId);
+        acc.modelTokens.set(event.model, (acc.modelTokens.get(event.model) ?? 0) + event.tokens.totalTokens);
+        if (event.costUsd !== null) {
+            row.costUsd += event.costUsd;
+            if (event.costProvenance === 'provider-reported')
+                acc.reportedCalls += 1;
+            else
+                acc.estimatedCalls += 1;
+        }
+        else {
+            row.unpricedCalls += 1;
+        }
+    }
+    const rows = [];
+    for (const acc of buckets.values()) {
+        acc.row.sessions = acc.sessionIds.size;
+        acc.row.models = [...acc.modelTokens.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .map(([model]) => model);
+        acc.row.costProvenance = (0, costProvenance_1.classifyCostProvenance)({
+            reportedCalls: acc.reportedCalls,
+            estimatedCalls: acc.estimatedCalls,
+            unpricedCalls: acc.row.unpricedCalls,
+        });
+        rows.push(acc.row);
+    }
+    return rows.sort((a, b) => (isSession ? a.firstTimestamp - b.firstTimestamp : a.key.localeCompare(b.key)) ||
+        (a.provider ?? '').localeCompare(b.provider ?? '') ||
+        (a.project ?? '').localeCompare(b.project ?? '') ||
+        (a.model ?? '').localeCompare(b.model ?? ''));
+}
+/**
+ * Sum rows that do not overlap (for example every row of one `bucketUsage`
+ * call). Pass the events too when rows are not per-session, so distinct
+ * sessions are counted once instead of once per row they appear in.
+ */
+function summarizeUsageRows(rows, events) {
+    const totals = {
+        calls: 0,
+        sessions: 0,
+        tokens: emptyTokens(),
+        totalTokens: 0,
+        costUsd: 0,
+        costProvenance: 'none',
+        unpricedCalls: 0,
+    };
+    let reportedCalls = 0;
+    let estimatedCalls = 0;
+    const sessionIds = new Set();
+    for (const row of rows) {
+        totals.calls += row.calls;
+        addTokens(totals.tokens, row.tokens);
+        totals.totalTokens += row.totalTokens;
+        totals.costUsd += row.costUsd;
+        totals.unpricedCalls += row.unpricedCalls;
+        const priced = row.calls - row.unpricedCalls;
+        if (row.costProvenance === 'reported')
+            reportedCalls += priced;
+        else if (row.costProvenance === 'estimated')
+            estimatedCalls += priced;
+        else if (row.costProvenance === 'mixed') {
+            reportedCalls += 1;
+            estimatedCalls += 1;
+        }
+        if (row.sessionId)
+            sessionIds.add(row.sessionId);
+    }
+    if (events) {
+        for (const event of events)
+            sessionIds.add(event.sessionId);
+        totals.sessions = sessionIds.size;
+    }
+    else {
+        totals.sessions = sessionIds.size || rows.reduce((sum, row) => sum + row.sessions, 0);
+    }
+    totals.costProvenance = (0, costProvenance_1.classifyCostProvenance)({
+        reportedCalls,
+        estimatedCalls,
+        unpricedCalls: totals.unpricedCalls,
+    });
+    return totals;
+}

package/dist/watchers/factory.d.ts

@@ -9,6 +9,12 @@ export interface CreateWatcherOptions {
     sessionId?: string;
     callbacks: SessionWatcherCallbacks;
 }
+/**
+ * Resolve the session a command should act on: an exact or unique-prefix
+ * match of `sessionId` among the workspace's sessions, or the most recent
+ * session when no id is given. Throws with the available ids on a miss.
+ */
+export declare function resolveSessionPath(provider: SessionProviderBase, workspacePath: string, sessionId?: string): string;
 export declare function createWatcher(options: CreateWatcherOptions): {
     watcher: SessionWatcher;
     sessionPath: string;

package/dist/watchers/factory.js

@@ -36,6 +36,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSessionPath = resolveSessionPath;
 exports.createWatcher = createWatcher;
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
@@ -48,37 +49,41 @@ function getOpenCodeDataDir() {
         return path.join(xdg, 'opencode');
     return path.join(os.homedir(), '.local', 'share', 'opencode');
 }
-function createWatcher(options) {
-    const { provider, workspacePath, sessionId, callbacks } = options;
+/**
+ * Resolve the session a command should act on: an exact or unique-prefix
+ * match of `sessionId` among the workspace's sessions, or the most recent
+ * session when no id is given. Throws with the available ids on a miss.
+ */
+function resolveSessionPath(provider, workspacePath, sessionId) {
     const sessions = provider.findAllSessions(workspacePath);
     if (sessions.length === 0) {
         throw new Error(`No sessions found for ${provider.displayName} in ${workspacePath}`);
     }
-    let sessionPath;
-    if (sessionId) {
-        const matches = sessions.map((sessionPath) => ({
-            sessionPath,
-            id: provider.getSessionId(sessionPath),
-        }));
-        const exact = matches.filter((candidate) => candidate.id === sessionId);
-        const candidates = exact.length > 0 ? exact : matches.filter((candidate) => candidate.id.startsWith(sessionId));
-        if (candidates.length === 0) {
-            throw new Error(`Session ${sessionId} not found. Available: ${sessions
-                .slice(0, 5)
-                .map((s) => path.basename(s))
-                .join(', ')}`);
-        }
-        if (candidates.length > 1) {
-            throw new Error(`Session ${sessionId} is ambiguous. Matches: ${candidates
-                .slice(0, 5)
-                .map((candidate) => candidate.id)
-                .join(', ')}`);
-        }
-        sessionPath = candidates[0].sessionPath;
+    if (!sessionId)
+        return sessions[0]; // most recent
+    const matches = sessions.map((sessionPath) => ({
+        sessionPath,
+        id: provider.getSessionId(sessionPath),
+    }));
+    const exact = matches.filter((candidate) => candidate.id === sessionId);
+    const candidates = exact.length > 0 ? exact : matches.filter((candidate) => candidate.id.startsWith(sessionId));
+    if (candidates.length === 0) {
+        throw new Error(`Session ${sessionId} not found. Available: ${sessions
+            .slice(0, 5)
+            .map((s) => path.basename(s))
+            .join(', ')}`);
     }
-    else {
-        sessionPath = sessions[0]; // most recent
+    if (candidates.length > 1) {
+        throw new Error(`Session ${sessionId} is ambiguous. Matches: ${candidates
+            .slice(0, 5)
+            .map((candidate) => candidate.id)
+            .join(', ')}`);
     }
+    return candidates[0].sessionPath;
+}
+function createWatcher(options) {
+    const { provider, workspacePath, sessionId, callbacks } = options;
+    const sessionPath = resolveSessionPath(provider, workspacePath, sessionId);
     const watcher = createWatcherForProvider(provider, sessionPath, callbacks);
     return { watcher, sessionPath };
 }