sidekick-shared 0.27.5 → 0.28.0

package/dist/esm/formatters/sessionDump.js

@@ -0,0 +1,328 @@
+/**
+ * Session dump formatters — text, markdown, and JSON output.
+ *
+ * Extracted from sidekick-cli's dump command so both the CLI and VS Code
+ * extension can produce identical session reports from AggregatedMetrics.
+ *
+ * @module formatters/sessionDump
+ */
+import { describeCostProvenance } from '../aggregation/costProvenance';
+import { formatDurationMs, formatTokenCount } from '../formatting';
+import { formatTokenBreakdown, TOKEN_MAIN_THREAD_LABEL, TOKEN_SESSION_TOTAL_LABEL, TOKEN_SUBAGENTS_LABEL, TOKEN_TOTAL_LABEL, } from '../tokenSummary';
+import { combineSessionTokenTotals } from '../sessionTokenTotals';
+/** Main thread (the aggregated transcript) plus the session's subagents. */
+function sessionTokens(metrics, options) {
+    return combineSessionTokenTotals(metrics.tokens, options.subagents ?? []);
+}
+// ── JSON output ──
+/**
+ * Serialize aggregated metrics as pretty-printed JSON, plus a `tokenSummary`
+ * block in the shared vocabulary: `mainThread`, per-subagent summaries,
+ * `subagentTotal`, and `combined` (main thread plus subagents).
+ */
+export function formatSessionJson(metrics, options = {}) {
+    return (JSON.stringify({ ...metrics, tokenSummary: sessionTokens(metrics, options) }, null, 2) + '\n');
+}
+// ── Text output ──
+/**
+ * Format aggregated metrics as a plain-text report.
+ */
+export function formatSessionText(metrics, options = {}) {
+    const width = options.width ?? 120;
+    const expand = options.expand ?? false;
+    const lines = [];
+    const hr = '\u2500'.repeat(Math.min(width, 80));
+    // Header
+    lines.push(hr);
+    lines.push(formatHeader(metrics));
+    lines.push(hr);
+    lines.push('');
+    // Token summary
+    lines.push(...formatTokenSummary(metrics, sessionTokens(metrics, options)));
+    lines.push('');
+    // Model stats
+    if (metrics.modelStats.length > 0) {
+        lines.push('Models:');
+        for (const m of metrics.modelStats) {
+            lines.push(`  ${m.model}: ${m.calls} calls, ${fmtTokens(m.tokens)} total incl. cache, ${fmtCost(m.cost)}`);
+        }
+        lines.push('');
+    }
+    // Tool stats
+    if (metrics.toolStats.length > 0) {
+        lines.push('Tools:');
+        const sorted = [...metrics.toolStats].sort((a, b) => b.successCount + b.failureCount - (a.successCount + a.failureCount));
+        for (const t of sorted) {
+            const total = t.successCount + t.failureCount;
+            const failStr = t.failureCount > 0 ? ` (${t.failureCount} failed)` : '';
+            const avgMs = t.completedCount > 0 ? Math.round(t.totalDuration / t.completedCount) : 0;
+            const durationStr = avgMs > 0 ? ` avg ${avgMs}ms` : '';
+            lines.push(`  ${t.name}: ${total}${failStr}${durationStr}`);
+        }
+        lines.push('');
+    }
+    // Compaction / truncation
+    if (metrics.compactionCount > 0 || metrics.truncationCount > 0) {
+        const parts = [];
+        if (metrics.compactionCount > 0)
+            parts.push(`${metrics.compactionCount} compaction(s)`);
+        if (metrics.truncationCount > 0)
+            parts.push(`${metrics.truncationCount} truncation(s)`);
+        lines.push(`Context management: ${parts.join(', ')}`);
+        lines.push('');
+    }
+    // Timeline
+    lines.push(hr);
+    lines.push('Timeline:');
+    lines.push(hr);
+    const filteredEvents = expand
+        ? metrics.timeline
+        : metrics.timeline.filter((e) => e.noiseLevel !== 'noise');
+    if (filteredEvents.length === 0) {
+        lines.push('  (no events)');
+    }
+    else {
+        for (const event of filteredEvents) {
+            const ts = formatTimestamp(event.timestamp);
+            const icon = getTimelineEventIcon(event.type);
+            const summary = truncateToWidth(event.description, width - ts.length - 4);
+            lines.push(`${ts} ${icon} ${summary}`);
+        }
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+// ── Markdown output ──
+/**
+ * Format aggregated metrics as a markdown report.
+ */
+export function formatSessionMarkdown(metrics, options = {}) {
+    const expand = options.expand ?? false;
+    const sessionFileName = options.sessionFileName;
+    const lines = [];
+    // Title
+    lines.push('# Session Report');
+    lines.push('');
+    // Summary
+    lines.push('## Summary');
+    lines.push('');
+    lines.push(`| Metric | Value |`);
+    lines.push(`|--------|-------|`);
+    if (sessionFileName) {
+        lines.push(`| Session file | \`${sessionFileName}\` |`);
+    }
+    lines.push(`| Started | ${metrics.sessionStartTime || 'N/A'} |`);
+    lines.push(`| Last event | ${metrics.lastEventTime || 'N/A'} |`);
+    lines.push(`| Duration | ${formatDuration(metrics.sessionStartTime, metrics.lastEventTime)} |`);
+    lines.push(`| Messages | ${metrics.messageCount} |`);
+    lines.push(`| Events | ${metrics.eventCount} |`);
+    lines.push(`| Model | ${metrics.currentModel || 'N/A'} |`);
+    lines.push(`| Provider | ${metrics.providerId || 'N/A'} |`);
+    lines.push('');
+    // Tokens
+    lines.push('## Tokens');
+    lines.push('');
+    lines.push(`| Category | Count |`);
+    lines.push(`|----------|-------|`);
+    lines.push(`| Input | ${fmtTokens(metrics.tokens.inputTokens)} |`);
+    lines.push(`| Output | ${fmtTokens(metrics.tokens.outputTokens)} |`);
+    lines.push(`| Cache write | ${fmtTokens(metrics.tokens.cacheWriteTokens)} |`);
+    lines.push(`| Cache read | ${fmtTokens(metrics.tokens.cacheReadTokens)} |`);
+    const tokens = sessionTokens(metrics, options);
+    if (tokens.mainThread.billedOutsideBuckets > 0) {
+        lines.push(`| Reasoning (billed separately) | ${fmtTokens(tokens.mainThread.billedOutsideBuckets)} |`);
+    }
+    if (tokens.subagents.length > 0) {
+        lines.push(`| ${TOKEN_MAIN_THREAD_LABEL} — ${TOKEN_TOTAL_LABEL} | ${fmtTokens(tokens.mainThread.total)} |`);
+        lines.push(`| ${TOKEN_SUBAGENTS_LABEL} (${tokens.subagents.length}) — ${TOKEN_TOTAL_LABEL} | ${fmtTokens(tokens.subagentTotal.total)} |`);
+        lines.push(`| **${TOKEN_SESSION_TOTAL_LABEL}** | **${fmtTokens(tokens.combined.total)}** |`);
+    }
+    else {
+        lines.push(`| ${TOKEN_TOTAL_LABEL} | ${fmtTokens(tokens.mainThread.total)} |`);
+    }
+    if (metrics.tokens.costUsd > 0) {
+        lines.push(`| Cost | ${fmtCost(metrics.tokens.costUsd)} (${describeCostProvenance(metrics.tokens)}) |`);
+    }
+    else if (metrics.tokens.unpricedCalls > 0) {
+        lines.push(`| Cost | — (${describeCostProvenance(metrics.tokens)}) |`);
+    }
+    lines.push('');
+    // Model stats
+    if (metrics.modelStats.length > 0) {
+        lines.push('## Models');
+        lines.push('');
+        lines.push(`| Model | Calls | ${TOKEN_TOTAL_LABEL} | Cost |`);
+        lines.push(`|-------|-------|--------|------|`);
+        for (const m of metrics.modelStats) {
+            lines.push(`| ${m.model} | ${m.calls} | ${fmtTokens(m.tokens)} | ${fmtCost(m.cost)} |`);
+        }
+        lines.push('');
+    }
+    // Tool calls
+    if (metrics.toolStats.length > 0) {
+        lines.push('## Tool Calls');
+        lines.push('');
+        lines.push(`| Tool | Total | Failed | Avg Duration |`);
+        lines.push(`|------|-------|--------|--------------|`);
+        const sorted = [...metrics.toolStats].sort((a, b) => b.successCount + b.failureCount - (a.successCount + a.failureCount));
+        for (const t of sorted) {
+            const total = t.successCount + t.failureCount;
+            const avgMs = t.completedCount > 0 ? Math.round(t.totalDuration / t.completedCount) : 0;
+            lines.push(`| ${t.name} | ${total} | ${t.failureCount} | ${avgMs > 0 ? `${avgMs}ms` : '-'} |`);
+        }
+        lines.push('');
+    }
+    // Context events
+    if (metrics.compactionCount > 0 || metrics.truncationCount > 0) {
+        lines.push('## Context Management');
+        lines.push('');
+        if (metrics.compactionCount > 0) {
+            lines.push(`- **Compactions:** ${metrics.compactionCount}`);
+            for (const c of metrics.compactionEvents) {
+                lines.push(`  - At ${formatTimestamp(c.timestamp instanceof Date ? c.timestamp.toISOString() : String(c.timestamp))}: ${fmtTokens(c.contextBefore)} -> ${fmtTokens(c.contextAfter)} tokens`);
+            }
+        }
+        if (metrics.truncationCount > 0) {
+            lines.push(`- **Truncations:** ${metrics.truncationCount}`);
+        }
+        lines.push('');
+    }
+    // Subagents
+    if (metrics.subagents.length > 0) {
+        lines.push('## Subagents');
+        lines.push('');
+        lines.push(`| Type | Description | Status | Duration |`);
+        lines.push(`|------|-------------|--------|----------|`);
+        for (const s of metrics.subagents) {
+            const dur = s.durationMs ? `${Math.round(s.durationMs / 1000)}s` : '-';
+            lines.push(`| ${s.subagentType} | ${s.description} | ${s.status} | ${dur} |`);
+        }
+        lines.push('');
+    }
+    if (tokens.subagents.length > 0) {
+        lines.push('## Subagent Tokens');
+        lines.push('');
+        lines.push(`| Agent | Type | Description | ${TOKEN_TOTAL_LABEL} |`);
+        lines.push(`|-------|------|-------------|--------|`);
+        for (const agent of tokens.subagents) {
+            lines.push(`| ${agent.agentId} | ${agent.agentType ?? '-'} | ${agent.description ?? '-'} | ${fmtTokens(agent.summary.total)} |`);
+        }
+        lines.push('');
+    }
+    // Timeline
+    lines.push('## Timeline');
+    lines.push('');
+    const filteredEvents = expand
+        ? metrics.timeline
+        : metrics.timeline.filter((e) => e.noiseLevel !== 'noise');
+    if (filteredEvents.length === 0) {
+        lines.push('_(no events)_');
+    }
+    else {
+        lines.push('```');
+        for (const event of filteredEvents) {
+            const ts = formatTimestamp(event.timestamp);
+            const icon = getTimelineEventIcon(event.type);
+            lines.push(`${ts} ${icon} ${event.description}`);
+        }
+        lines.push('```');
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+// ── Formatting helpers ──
+function formatHeader(metrics) {
+    const parts = [];
+    if (metrics.providerId)
+        parts.push(metrics.providerId);
+    if (metrics.currentModel)
+        parts.push(metrics.currentModel);
+    const duration = formatDuration(metrics.sessionStartTime, metrics.lastEventTime);
+    if (duration !== 'N/A')
+        parts.push(duration);
+    parts.push(`${metrics.messageCount} messages`);
+    parts.push(`${metrics.eventCount} events`);
+    return parts.join(' | ');
+}
+function formatTokenSummary(metrics, tokens) {
+    const t = metrics.tokens;
+    let first = `Tokens: ${formatTokenBreakdown(tokens.mainThread, fmtTokens)}`;
+    if (t.costUsd > 0)
+        first += `  Cost: ${fmtCost(t.costUsd)} (${describeCostProvenance(t)})`;
+    const lines = [first];
+    if (tokens.subagents.length > 0) {
+        lines.push(`${TOKEN_SUBAGENTS_LABEL} (${tokens.subagents.length}): ${formatTokenBreakdown(tokens.subagentTotal, fmtTokens)}`);
+        lines.push(`${TOKEN_SESSION_TOTAL_LABEL}: ${fmtTokens(tokens.combined.total)}`);
+    }
+    return lines;
+}
+/** @internal Exported for tests. */
+export function fmtTokens(n) {
+    return formatTokenCount(n);
+}
+/** @internal Exported for tests. */
+export function fmtCost(cost) {
+    if (cost <= 0)
+        return '$0.00';
+    if (cost < 0.01)
+        return `$${cost.toFixed(4)}`;
+    return `$${cost.toFixed(2)}`;
+}
+/** @internal Exported for tests. */
+export function formatTimestamp(iso) {
+    try {
+        const d = new Date(iso);
+        if (isNaN(d.getTime()))
+            return '??:??:??';
+        const h = d.getHours().toString().padStart(2, '0');
+        const m = d.getMinutes().toString().padStart(2, '0');
+        const s = d.getSeconds().toString().padStart(2, '0');
+        return `${h}:${m}:${s}`;
+    }
+    catch {
+        return '??:??:??';
+    }
+}
+/** @internal Exported for tests. */
+export function formatDuration(start, end) {
+    if (!start || !end)
+        return 'N/A';
+    try {
+        const ms = new Date(end).getTime() - new Date(start).getTime();
+        return formatDurationMs(ms);
+    }
+    catch {
+        return 'N/A';
+    }
+}
+/** Map TimelineEvent.type to a display icon. */
+function getTimelineEventIcon(type) {
+    switch (type) {
+        case 'user_prompt':
+            return '\u25b6'; // right-pointing triangle
+        case 'assistant_response':
+            return '\u2726'; // four-pointed star
+        case 'tool_call':
+            return '\u2699'; // gear
+        case 'tool_result':
+            return '\u2190'; // left arrow
+        case 'compaction':
+            return '\u21bb'; // clockwise arrow
+        case 'error':
+            return '\u2718'; // heavy ballot X
+        case 'session_start':
+            return '\u25cf'; // black circle
+        case 'session_end':
+            return '\u25cb'; // white circle
+        default:
+            return ' ';
+    }
+}
+function truncateToWidth(text, maxLen) {
+    if (maxLen < 10)
+        maxLen = 10;
+    const clean = text.replace(/\s+/g, ' ').trim();
+    if (clean.length <= maxLen)
+        return clean;
+    return clean.substring(0, maxLen - 3) + '...';
+}

package/dist/esm/formatters/toolSummary.js

@@ -0,0 +1,226 @@
+/**
+ * Rich tool summary formatters.
+ *
+ * Registry of per-tool formatters that produce contextual one-liner summaries.
+ * Replaces the generic field-fallback `summarizeToolInput()` with tool-specific
+ * formatting inspired by tail-claude's 19+ tool formatters.
+ *
+ * @module formatters/toolSummary
+ */
+// ── Helpers ──
+function truncate(text, maxLen) {
+    const clean = text.replace(/\s+/g, ' ').trim();
+    return clean.length > maxLen ? clean.substring(0, maxLen - 3) + '...' : clean;
+}
+function basename(filePath) {
+    const parts = filePath.replace(/\\/g, '/').split('/');
+    return parts[parts.length - 1] || filePath;
+}
+function hostname(url) {
+    try {
+        const u = new URL(url);
+        return u.hostname + (u.pathname !== '/' ? u.pathname : '');
+    }
+    catch {
+        return truncate(url, 60);
+    }
+}
+function countLines(content) {
+    if (typeof content !== 'string')
+        return null;
+    const lines = content.split('\n').length;
+    return lines;
+}
+// ── Per-Tool Formatters ──
+const formatRead = (input) => {
+    const filePath = input.file_path;
+    if (!filePath)
+        return '';
+    const name = basename(filePath);
+    const offset = input.offset;
+    const limit = input.limit;
+    if (offset && limit)
+        return `${name}:${offset}-${offset + limit}`;
+    if (offset)
+        return `${name}:${offset}+`;
+    if (limit)
+        return `${name} (${limit} lines)`;
+    return name;
+};
+const formatWrite = (input) => {
+    const filePath = input.file_path;
+    if (!filePath)
+        return '';
+    const name = basename(filePath);
+    const lines = countLines(input.content);
+    if (lines !== null)
+        return `${name} — ${lines} lines`;
+    return name;
+};
+const formatEdit = (input) => {
+    const filePath = input.file_path;
+    if (!filePath)
+        return '';
+    const name = basename(filePath);
+    const oldStr = input.old_string;
+    const newStr = input.new_string;
+    const oldLines = oldStr ? oldStr.split('\n').length : 0;
+    const newLines = newStr ? newStr.split('\n').length : 0;
+    if (oldLines || newLines)
+        return `${name} — ${oldLines}→${newLines} lines`;
+    return name;
+};
+const formatBash = (input) => {
+    // Prefer description field (Claude Code provides human-readable descriptions)
+    if (typeof input.description === 'string' && input.description.length > 0) {
+        return truncate(input.description, 80);
+    }
+    if (typeof input.command === 'string') {
+        // Take just the first line of multi-line commands
+        const firstLine = input.command.split('\n')[0];
+        return truncate(firstLine, 80);
+    }
+    return '';
+};
+const formatGrep = (input) => {
+    const pattern = input.pattern;
+    if (!pattern)
+        return '';
+    const glob = input.glob;
+    const path = input.path;
+    const type = input.type;
+    const parts = [truncate(pattern, 40)];
+    if (glob)
+        parts.push(`in ${glob}`);
+    else if (type)
+        parts.push(`in *.${type}`);
+    else if (path)
+        parts.push(`in ${basename(path)}`);
+    return parts.join(' ');
+};
+const formatGlob = (input) => {
+    const pattern = input.pattern;
+    if (!pattern)
+        return '';
+    const path = input.path;
+    if (path)
+        return `${pattern} in ${basename(path)}`;
+    return pattern;
+};
+const formatTask = (input) => {
+    const subagentType = input.subagent_type;
+    const description = input.description;
+    const prompt = input.prompt;
+    const parts = [];
+    if (subagentType)
+        parts.push(`[${subagentType}]`);
+    if (description)
+        parts.push(truncate(description, 60));
+    else if (prompt)
+        parts.push(truncate(prompt, 60));
+    return parts.join(' ') || '';
+};
+const formatWebFetch = (input) => {
+    const url = input.url;
+    if (!url)
+        return '';
+    return hostname(url);
+};
+const formatWebSearch = (input) => {
+    const query = input.query;
+    if (!query)
+        return '';
+    return truncate(query, 80);
+};
+const formatToolSearch = (input) => {
+    const query = input.query;
+    if (!query)
+        return '';
+    return truncate(query, 80);
+};
+const formatNotebookEdit = (input) => {
+    const filePath = input.file_path;
+    const cellNumber = input.cell_number;
+    if (!filePath)
+        return '';
+    const name = basename(filePath);
+    if (cellNumber !== undefined)
+        return `${name} cell ${cellNumber}`;
+    return name;
+};
+const formatTaskCreate = (input) => {
+    const subject = input.subject;
+    if (subject)
+        return truncate(subject, 80);
+    return '';
+};
+const formatTaskUpdate = (input) => {
+    const taskId = input.task_id;
+    const status = input.status;
+    if (taskId && status)
+        return `${taskId} → ${status}`;
+    if (taskId)
+        return taskId;
+    return '';
+};
+// ── Registry ──
+const TOOL_FORMATTERS = {
+    Read: formatRead,
+    Write: formatWrite,
+    Edit: formatEdit,
+    Bash: formatBash,
+    Grep: formatGrep,
+    Glob: formatGlob,
+    Task: formatTask,
+    WebFetch: formatWebFetch,
+    WebSearch: formatWebSearch,
+    ToolSearch: formatToolSearch,
+    NotebookEdit: formatNotebookEdit,
+    TaskCreate: formatTaskCreate,
+    TaskUpdate: formatTaskUpdate,
+};
+// ── Generic fallback ──
+function genericFallback(input) {
+    if (typeof input.command === 'string')
+        return truncate(input.command, 80);
+    if (typeof input.file_path === 'string')
+        return truncate(input.file_path, 80);
+    if (typeof input.pattern === 'string')
+        return truncate(input.pattern, 80);
+    if (typeof input.query === 'string')
+        return truncate(input.query, 80);
+    if (typeof input.path === 'string')
+        return truncate(input.path, 80);
+    if (typeof input.url === 'string')
+        return truncate(input.url, 80);
+    for (const val of Object.values(input)) {
+        if (typeof val === 'string' && val.length > 0)
+            return truncate(val, 80);
+    }
+    return '';
+}
+// ── Public API ──
+/**
+ * Produces a contextual one-liner summary for a tool call.
+ *
+ * Uses a registry of per-tool formatters for known tools (Read, Write, Edit,
+ * Bash, Grep, Glob, Task, WebFetch, WebSearch, etc.) and falls back to
+ * generic field extraction for unknown tools.
+ *
+ * @param toolName - The canonical tool name (e.g., "Read", "Bash")
+ * @param input - The tool's input parameters
+ * @returns A human-readable one-liner summary (may be empty string)
+ */
+export function formatToolSummary(toolName, input) {
+    // Strip MCP prefixes: "mcp__server__tool" → use "tool" for matching
+    const baseName = toolName.includes('__') ? (toolName.split('__').pop() ?? toolName) : toolName;
+    const formatter = TOOL_FORMATTERS[toolName] ?? TOOL_FORMATTERS[baseName];
+    if (formatter) {
+        const result = formatter(input);
+        if (result)
+            return result;
+    }
+    return genericFallback(input);
+}
+// Re-export truncate for use by other formatters
+export { truncate };

package/dist/esm/formatting.js

@@ -0,0 +1,82 @@
+/**
+ * Pure display formatting helpers shared by CLI, extension host, webviews,
+ * and downstream apps.
+ *
+ * This module intentionally has no Node-only imports.
+ *
+ * @module formatting
+ */
+/** Format a token count with compact `k` / `M` suffixes. */
+export function formatTokenCount(value, options = {}) {
+    if (!Number.isFinite(value))
+        return '0';
+    const n = Math.trunc(value);
+    const sign = n < 0 ? '-' : '';
+    const abs = Math.abs(n);
+    const thousandsSuffix = options.suffixCase === 'upper' ? 'K' : 'k';
+    if (abs >= 1_000_000)
+        return `${sign}${(abs / 1_000_000).toFixed(1)}M`;
+    if (abs >= 1_000)
+        return `${sign}${(abs / 1_000).toFixed(1)}${thousandsSuffix}`;
+    return `${n}`;
+}
+/** Format an elapsed duration in milliseconds. */
+export function formatDurationMs(ms, options = {}) {
+    const invalid = options.invalid ?? 'N/A';
+    if (!Number.isFinite(ms) || ms < 0)
+        return invalid;
+    const style = options.style ?? 'spaced';
+    const separator = style === 'compact' ? '' : ' ';
+    const secondsFractionDigits = options.secondsFractionDigits ?? 0;
+    if (ms < 1000) {
+        if (options.includeMilliseconds)
+            return `${Math.round(ms)}ms`;
+        return `${(ms / 1000).toFixed(Math.max(1, secondsFractionDigits))}s`;
+    }
+    const seconds = ms / 1000;
+    if (seconds < 60) {
+        if (secondsFractionDigits > 0)
+            return `${seconds.toFixed(secondsFractionDigits)}s`;
+        return `${Math.floor(seconds)}s`;
+    }
+    const totalSeconds = Math.floor(seconds);
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const remainingSeconds = totalSeconds % 60;
+    if (hours > 0) {
+        return `${hours}h${separator}${minutes}m${separator}${remainingSeconds}s`;
+    }
+    return `${minutes}m${separator}${remainingSeconds}s`;
+}
+/**
+ * Calendar-date key (`YYYY-MM-DD`) in the machine's local time zone.
+ *
+ * Sidekick buckets "today", daily history, and heatmaps by the user's local
+ * day, so every writer and reader of a date key goes through this helper.
+ * A UTC key would move late-evening work onto the next day for anyone west
+ * of Greenwich and onto the previous day for anyone east of it.
+ */
+export function formatLocalDateKey(value = new Date()) {
+    const date = typeof value === 'number' ? new Date(value) : value;
+    if (Number.isNaN(date.getTime()))
+        return '';
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+}
+/** Parse a `YYYY-MM-DD` key produced by `formatLocalDateKey` back into local midnight. */
+export function parseLocalDateKey(key) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(key);
+    if (!match)
+        return null;
+    const date = new Date(Number(match[1]), Number(match[2]) - 1, Number(match[3]));
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+/** Shift a `YYYY-MM-DD` key by whole local days (DST-safe). */
+export function addLocalDays(key, days) {
+    const date = parseLocalDateKey(key);
+    if (!date)
+        return key;
+    return formatLocalDateKey(new Date(date.getFullYear(), date.getMonth(), date.getDate() + days));
+}

package/dist/esm/handoffUrl.js

@@ -0,0 +1,23 @@
+const ALLOWED_PLACEHOLDERS = new Set(['sessionId', 'provider', 'projectPath']);
+/** Renders an external handoff URL using identifiers only. */
+export function renderHandoffUrlTemplate(template, identifiers) {
+    if (!template.trim())
+        throw new Error('No handoff URL template is configured.');
+    const rendered = template.replace(/\{([^}]+)\}/g, (_match, name) => {
+        if (!ALLOWED_PLACEHOLDERS.has(name)) {
+            throw new Error(`Unsupported handoff URL placeholder: {${name}}`);
+        }
+        return encodeURIComponent(identifiers[name]);
+    });
+    let url;
+    try {
+        url = new URL(rendered);
+    }
+    catch {
+        throw new Error('The rendered handoff URL is invalid.');
+    }
+    if (['javascript:', 'data:', 'file:'].includes(url.protocol)) {
+        throw new Error(`Unsafe handoff URL protocol: ${url.protocol}`);
+    }
+    return url.toString();
+}