sidekick-shared 0.27.6 → 0.28.0

package/dist/esm/schemas/quota.js

@@ -0,0 +1,132 @@
+/**
+ * Zod schemas for runtime validation of quota state.
+ *
+ * These schemas mirror the TypeScript interfaces in `quota.ts`,
+ * `peakHours.ts`, `quotaPresentation.ts`, and `providerQuota.ts` (keep in
+ * sync when those change). They let consumers validate quota payloads at
+ * process/IPC boundaries without hand-mirroring the interfaces.
+ *
+ * @module schemas/quota
+ */
+import { z } from 'zod';
+import { QUOTA_PROVIDER_IDS, RUNTIME_QUOTA_PROVIDER_IDS } from '../providerIds';
+// ── QuotaWindow ──
+export const quotaWindowSchema = z.object({
+    utilization: z.number(),
+    resetsAt: z.string(),
+});
+// ── QuotaState ──
+export const quotaFailureKindSchema = z.enum([
+    'auth',
+    'network',
+    'rate_limit',
+    'server',
+    'unknown',
+]);
+export const quotaProviderIdSchema = z.enum(QUOTA_PROVIDER_IDS);
+export const quotaSourceSchema = z.enum([
+    'api',
+    'session',
+    'cache',
+    'statusline',
+]);
+export const quotaCapturedSourceSchema = z.enum([
+    'api',
+    'session',
+    'statusline',
+]);
+export const quotaFreshnessSchema = z.enum(['fresh', 'aging', 'stale']);
+export const codexResetCreditSchema = z.object({
+    title: z.string().optional(),
+    status: z.string(),
+    resetType: z.string().optional(),
+    expiresAt: z.string(),
+    grantedAt: z.string().optional(),
+});
+export const codexResetCreditsSnapshotSchema = z.object({
+    availableCount: z.number(),
+    totalEarnedCount: z.number().optional(),
+    credits: z.array(codexResetCreditSchema),
+    source: z.enum(['api', 'cache']).optional(),
+    capturedAt: z.string().optional(),
+});
+export const quotaStateSchema = z.object({
+    fiveHour: quotaWindowSchema,
+    sevenDay: quotaWindowSchema,
+    available: z.boolean(),
+    error: z.string().optional(),
+    failureKind: quotaFailureKindSchema.optional(),
+    httpStatus: z.number().optional(),
+    retryAfterMs: z.number().optional(),
+    projectedFiveHour: z.number().optional(),
+    projectedSevenDay: z.number().optional(),
+    providerId: quotaProviderIdSchema.optional(),
+    source: quotaSourceSchema.optional(),
+    capturedSource: quotaCapturedSourceSchema.optional(),
+    capturedAt: z.string().optional(),
+    stale: z.boolean().optional(),
+    ageMs: z.number().finite().nonnegative().optional(),
+    freshness: quotaFreshnessSchema.optional(),
+    fiveHourLabel: z.string().optional(),
+    sevenDayLabel: z.string().optional(),
+    limitId: z.string().optional(),
+    limitName: z.string().optional(),
+    credits: z.unknown().optional(),
+    resetCredits: codexResetCreditsSnapshotSchema.optional(),
+    planType: z.string().optional(),
+    rateLimitReachedType: z.string().optional(),
+});
+// ── PeakHoursState ──
+export const peakHoursStateSchema = z.object({
+    status: z.enum(['peak', 'off_peak', 'unknown']),
+    isPeak: z.boolean(),
+    sessionLimitSpeed: z.enum(['normal', 'faster', 'unknown']),
+    label: z.string(),
+    peakHoursDescription: z.string(),
+    nextChange: z.string().nullable(),
+    minutesUntilChange: z.number().nullable(),
+    note: z.string(),
+    updatedAt: z.string(),
+    unavailable: z.boolean(),
+    notApplicable: z.boolean().optional(),
+    source: z.enum(['promoclock', 'schedule']).optional(),
+});
+// ── QuotaFailureDescriptor ──
+export const quotaFailureDescriptorSchema = z.object({
+    severity: z.enum(['info', 'warning', 'error']),
+    title: z.string(),
+    message: z.string(),
+    detail: z.string().optional(),
+    alertKey: z.string(),
+    isRetryable: z.boolean(),
+});
+// ── ProviderQuotaState / ProviderQuotaMap ──
+export const runtimeQuotaProviderSchema = z.enum(RUNTIME_QUOTA_PROVIDER_IDS);
+/** Fields ProviderQuotaState adds on top of QuotaState, minus the provider tag. */
+const providerQuotaExtensionShape = {
+    accountLabel: z.string().optional(),
+    accountDetail: z.string().optional(),
+    peakHours: peakHoursStateSchema.nullable().optional(),
+    failure: quotaFailureDescriptorSchema.nullable().optional(),
+};
+export const providerQuotaStateSchema = quotaStateSchema.extend({
+    runtimeProvider: runtimeQuotaProviderSchema,
+    ...providerQuotaExtensionShape,
+});
+export const claudeProviderQuotaStateSchema = quotaStateSchema.extend({
+    runtimeProvider: z.literal('claude'),
+    ...providerQuotaExtensionShape,
+});
+export const codexProviderQuotaStateSchema = quotaStateSchema.extend({
+    runtimeProvider: z.literal('codex'),
+    ...providerQuotaExtensionShape,
+});
+export const zaiProviderQuotaStateSchema = quotaStateSchema.extend({
+    runtimeProvider: z.literal('zai'),
+    ...providerQuotaExtensionShape,
+});
+export const providerQuotaMapSchema = z.object({
+    claude: claudeProviderQuotaStateSchema.optional(),
+    codex: codexProviderQuotaStateSchema.optional(),
+    zai: zaiProviderQuotaStateSchema.optional(),
+});

package/dist/esm/schemas/quotaHistory.js

@@ -0,0 +1,40 @@
+/**
+ * Zod schemas for runtime validation of quota history records.
+ *
+ * These schemas mirror the TypeScript interfaces in `quotaHistory.ts`
+ * (keep in sync when those change). They let consumers validate quota
+ * history payloads at process/IPC boundaries without hand-mirroring
+ * the interfaces.
+ *
+ * @module schemas/quotaHistory
+ */
+import { z } from 'zod';
+// ── QuotaHistoryRuntimeProvider ──
+export const quotaHistoryRuntimeProviderSchema = z.enum([
+    'claude',
+    'codex',
+    'zai',
+]);
+// ── QuotaHistorySample ──
+export const quotaHistorySampleSchema = z.object({
+    timestamp: z.string(),
+    runtimeProvider: quotaHistoryRuntimeProviderSchema,
+    providerId: z.string(),
+    workspaceId: z.string(),
+    fiveHour: z.object({ utilization: z.number(), resetsAt: z.string() }),
+    sevenDay: z.object({ utilization: z.number(), resetsAt: z.string() }),
+    available: z.boolean(),
+    error: z.string().optional(),
+    source: z.enum(['session', 'cache', 'api', 'statusline']).optional(),
+    stale: z.boolean().optional(),
+});
+// ── QuotaHistoryDailyBucket ──
+export const quotaHistoryDailyBucketSchema = z.object({
+    date: z.string(),
+    samples: z.number(),
+    maxUtilizationFiveHour: z.number(),
+    maxUtilizationSevenDay: z.number(),
+    avgUtilizationFiveHour: z.number(),
+    avgUtilizationSevenDay: z.number(),
+    anyUnavailable: z.boolean(),
+});

package/dist/esm/schemas/sessionEvent.js

@@ -0,0 +1,216 @@
+/**
+ * Zod schemas for runtime validation of session events.
+ *
+ * These schemas mirror the TypeScript interfaces in `types/sessionEvent.ts`
+ * and can be used to validate raw JSONL data before processing.
+ *
+ * @module schemas/sessionEvent
+ */
+import { z } from 'zod';
+import { normalizedUsageSchema } from './usageNormalization';
+// ── MessageUsage ──
+export const messageUsageSchema = z.object({
+    input_tokens: z.number(),
+    output_tokens: z.number(),
+    cache_creation_input_tokens: z.number().optional(),
+    cache_read_input_tokens: z.number().optional(),
+    reported_cost: z.number().optional(),
+    reasoning_tokens: z.number().optional(),
+});
+// ── SessionMessage ──
+export const sessionMessageSchema = z.object({
+    role: z.string(),
+    id: z.string().optional(),
+    sourceLabel: z.string().optional(),
+    model: z.string().optional(),
+    usage: messageUsageSchema.optional(),
+    normalizedUsage: normalizedUsageSchema.optional(),
+    usageKind: z.enum(['call', 'correction']).optional(),
+    content: z.unknown().optional(),
+    // Streaming lines can carry `stop_reason: null`; rejecting it dropped the
+    // whole event (text, tools, and usage), so normalize it to absent.
+    stop_reason: z
+        .string()
+        .nullish()
+        .transform((value) => value ?? undefined),
+});
+// ── PermissionMode ──
+export const permissionModeSchema = z.enum([
+    'default',
+    'acceptEdits',
+    'bypassPermissions',
+    'plan',
+]);
+// ── SessionEvent ──
+const eventBaseShape = {
+    timestamp: z.string(),
+    entrypoint: z.string().optional(),
+    isMeta: z.boolean().optional(),
+    isSidechain: z.boolean().optional(),
+    isCompactSummary: z.boolean().optional(),
+    origin: z.object({ kind: z.string().optional() }).optional(),
+    promptSource: z.string().optional(),
+    cwd: z.string().optional(),
+    gitBranch: z.string().optional(),
+    permissionMode: permissionModeSchema.optional(),
+    rateLimits: z
+        .object({
+        primary: z
+            .object({
+            usedPercent: z.number(),
+            windowMinutes: z.number(),
+            resetsAt: z.number(),
+        })
+            .optional(),
+        secondary: z
+            .object({
+            usedPercent: z.number(),
+            windowMinutes: z.number(),
+            resetsAt: z.number(),
+        })
+            .optional(),
+    })
+        .optional(),
+    compaction: z
+        .object({
+        tokensBefore: z.number().nonnegative(),
+        tokensAfter: z.number().nonnegative(),
+    })
+        .optional(),
+    providerMetadata: z
+        .object({
+        providerId: z.string().optional(),
+        source: z.string().optional(),
+        retryAttempts: z.array(z.number()).optional(),
+        finishReasons: z.array(z.string()).optional(),
+        providerError: z
+            .object({
+            type: z.string().optional(),
+            message: z.string().optional(),
+            code: z.union([z.string(), z.number()]).optional(),
+        })
+            .optional(),
+    })
+        .optional(),
+};
+const compactionSchema = z
+    .object({
+    tokensBefore: z.number().finite().int().nonnegative(),
+    tokensAfter: z.number().finite().int().nonnegative(),
+})
+    .refine((value) => value.tokensAfter <= value.tokensBefore, {
+    message: 'tokensAfter must not exceed tokensBefore',
+});
+export const userSessionEventSchema = z.object({
+    type: z.literal('user'),
+    message: sessionMessageSchema,
+    ...eventBaseShape,
+});
+export const assistantSessionEventSchema = z.object({
+    type: z.literal('assistant'),
+    message: sessionMessageSchema,
+    ...eventBaseShape,
+});
+const summaryWithMessageSchema = z.object({
+    type: z.literal('summary'),
+    message: sessionMessageSchema,
+    summary: z.string().min(1).optional(),
+    ...eventBaseShape,
+    compaction: compactionSchema.optional(),
+});
+const summaryWithTextSchema = z.object({
+    type: z.literal('summary'),
+    message: sessionMessageSchema.optional(),
+    summary: z.string().min(1),
+    ...eventBaseShape,
+    compaction: compactionSchema.optional(),
+});
+const summaryWithCompactionSchema = z.object({
+    type: z.literal('summary'),
+    message: sessionMessageSchema.optional(),
+    summary: z.string().min(1).optional(),
+    ...eventBaseShape,
+    compaction: compactionSchema,
+});
+export const summarySessionEventSchema = z.union([
+    summaryWithMessageSchema,
+    summaryWithTextSchema,
+    summaryWithCompactionSchema,
+]);
+export const systemSessionEventSchema = z.object({
+    type: z.literal('system'),
+    message: sessionMessageSchema.optional(),
+    ...eventBaseShape,
+});
+export const toolUseSessionEventSchema = z.object({
+    type: z.literal('tool_use'),
+    message: sessionMessageSchema.optional(),
+    ...eventBaseShape,
+    tool: z.object({ name: z.string(), input: z.record(z.string(), z.unknown()) }),
+});
+export const toolResultSessionEventSchema = z.object({
+    type: z.literal('tool_result'),
+    message: sessionMessageSchema.optional(),
+    ...eventBaseShape,
+    result: z.object({
+        tool_use_id: z.string(),
+        output: z.unknown().optional(),
+        is_error: z.boolean().optional(),
+    }),
+});
+export const sessionEventSchema = z.union([
+    userSessionEventSchema,
+    assistantSessionEventSchema,
+    summarySessionEventSchema,
+    systemSessionEventSchema,
+    toolUseSessionEventSchema,
+    toolResultSessionEventSchema,
+]);
+// ── Progress unwrapping ──
+/** Recursion bound for nested progress envelopes; real data nests 1 level. */
+const MAX_PROGRESS_DEPTH = 8;
+/**
+ * Extracts canonical SessionEvents from a raw JSONL value.
+ *
+ * Claude Code wraps subagent/SDK events as
+ * `{ type: 'progress', data: { message: <SessionEvent> } }`, which
+ * `sessionEventSchema` alone rejects. This helper tries a direct parse,
+ * then unwraps progress envelopes (recursively, in case of nesting).
+ * Returns zero events for unrecognized input — never throws.
+ */
+export function extractSessionEvents(raw, depth = 0) {
+    return extractSessionEventsWithProvenance(raw, depth, {});
+}
+function extractSessionEventsWithProvenance(raw, depth, inherited) {
+    const direct = sessionEventSchema.safeParse(raw);
+    if (direct.success)
+        return [{ ...inherited, ...direct.data }];
+    if (depth >= MAX_PROGRESS_DEPTH)
+        return [];
+    if (typeof raw === 'object' && raw !== null && raw.type === 'progress') {
+        const provenance = { ...inherited, ...progressProvenance(raw) };
+        const data = raw.data;
+        if (typeof data === 'object' && data !== null) {
+            const message = data.message;
+            if (typeof message === 'object' && message !== null) {
+                return extractSessionEventsWithProvenance(message, depth + 1, provenance);
+            }
+        }
+    }
+    return [];
+}
+function progressProvenance(raw) {
+    const value = raw;
+    const provenance = {};
+    if (typeof value.entrypoint === 'string')
+        provenance.entrypoint = value.entrypoint;
+    if (typeof value.isMeta === 'boolean')
+        provenance.isMeta = value.isMeta;
+    if (typeof value.isSidechain === 'boolean')
+        provenance.isSidechain = value.isSidechain;
+    if (typeof value.cwd === 'string')
+        provenance.cwd = value.cwd;
+    if (typeof value.gitBranch === 'string')
+        provenance.gitBranch = value.gitBranch;
+    return provenance;
+}

package/dist/esm/schemas/stateFile.js

@@ -0,0 +1,75 @@
+/**
+ * Zod schema for the public `state.json` contract (`schemaVersion: 1`).
+ *
+ * Mirrors the interfaces in `stateFile.ts` (keep in sync when those change;
+ * fields are only ever added). Consumers validating the file from another
+ * process import this from `sidekick-shared/schemas`.
+ *
+ * @module schemas/stateFile
+ */
+import { z } from 'zod';
+export const stateFileWriterSchema = z.enum([
+    'statusline',
+    'cli-dashboard',
+    'vscode-dashboard',
+]);
+export const stateFileQuotaWindowSchema = z.object({
+    utilization: z.number(),
+    resetsAt: z.string(),
+});
+export const stateFileQuotaSchema = z.object({
+    fiveHour: stateFileQuotaWindowSchema,
+    sevenDay: stateFileQuotaWindowSchema,
+    source: z.enum(['api', 'session', 'cache', 'statusline']).nullable(),
+    capturedSource: z.enum(['api', 'session', 'statusline']).nullable(),
+    capturedAt: z.string().nullable(),
+    ageMs: z.number().nullable(),
+    freshness: z.enum(['fresh', 'aging', 'stale']).nullable(),
+});
+export const stateFileAccountSchema = z.object({
+    providerId: z.enum(['claude-code', 'codex']),
+    id: z.string().nullable(),
+    label: z.string().nullable(),
+});
+export const stateFileContextSchema = z.object({
+    usedPercentage: z.number().nullable(),
+    contextWindowSize: z.number().nullable(),
+    totalInputTokens: z.number().nullable(),
+    totalOutputTokens: z.number().nullable(),
+    totalTokens: z.number().nullable().optional(),
+});
+export const stateFileSessionSchema = z.object({
+    sessionId: z.string().nullable(),
+    cwd: z.string().nullable(),
+    model: z.string().nullable(),
+    costUsd: z.number().nullable(),
+    durationMs: z.number().nullable(),
+    linesAdded: z.number().nullable(),
+    linesRemoved: z.number().nullable(),
+    promptCacheHitRatio: z.number().nullable(),
+});
+export const stateFileBillingBlockSchema = z.object({
+    start: z.string(),
+    end: z.string(),
+    isActive: z.boolean(),
+    tokens: z.number(),
+    costUsd: z.number(),
+    costProvenance: z.enum(['reported', 'estimated', 'mixed', 'unpriced', 'none']),
+    burnRatePerMinute: z.number(),
+    projectedTokens: z.number(),
+    projectedCostUsd: z.number(),
+    remainingMs: z.number(),
+});
+export const sidekickStateFileSchema = z.object({
+    schemaVersion: z.literal(1),
+    writtenAt: z.string(),
+    writer: stateFileWriterSchema,
+    account: stateFileAccountSchema.nullable(),
+    quota: z.object({
+        claude: stateFileQuotaSchema.nullable(),
+        codex: stateFileQuotaSchema.nullable(),
+    }),
+    context: stateFileContextSchema.nullable(),
+    session: stateFileSessionSchema.nullable(),
+    billingBlock: stateFileBillingBlockSchema.nullable(),
+});

package/dist/esm/schemas/tokenEstimation.js

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+export const tokenEstimateSchema = z.object({
+    count: z.number().finite().nonnegative(),
+    method: z.enum(['exact', 'sidekick-fallback-v1']),
+    confidence: z.enum(['exact', 'medium', 'low']),
+    provenance: z.string(),
+});

package/dist/esm/schemas/transcript.js

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import { normalizedUsageCostSchema, normalizedUsageSchema } from './usageNormalization';
+export const transcriptSourceProvenanceSchema = z.object({
+    provider: z.string().optional(),
+    sessionId: z.string().optional(),
+    sourcePath: z.string().optional(),
+    source: z.string().optional(),
+    entrypoint: z.string().optional(),
+    isMeta: z.boolean().optional(),
+    isSidechain: z.boolean().optional(),
+    originalRole: z.string().optional(),
+    eventIndex: z.number().int().nonnegative(),
+    eventType: z.enum(['user', 'assistant', 'tool_use', 'tool_result', 'summary', 'system']),
+    eventId: z.string().optional(),
+});
+export const canonicalTranscriptBlockSchema = z.object({
+    type: z.enum(['text', 'thinking', 'tool_use', 'tool_result', 'image', 'unknown']),
+    text: z.string().optional(),
+    toolName: z.string().optional(),
+    toolUseId: z.string().optional(),
+    input: z.unknown().optional(),
+    output: z.unknown().optional(),
+    isError: z.boolean().optional(),
+    command: z.string().optional(),
+    truncated: z.boolean().optional(),
+    raw: z.unknown().optional(),
+});
+export const canonicalToolCallSchema = z.object({
+    id: z.string().optional(),
+    name: z.string(),
+    timestamp: z.string(),
+    input: z.unknown().optional(),
+    output: z.unknown().optional(),
+    isError: z.boolean().optional(),
+    command: z.string().optional(),
+    source: transcriptSourceProvenanceSchema,
+});
+export const canonicalTranscriptMessageSchema = z.object({
+    id: z.string().optional(),
+    role: z.enum(['user', 'assistant', 'system', 'summary', 'tool']),
+    timestamp: z.string(),
+    model: z.string().optional(),
+    sourceLabel: z.string().optional(),
+    content: z.array(canonicalTranscriptBlockSchema),
+    text: z.string(),
+    usage: normalizedUsageSchema.optional(),
+    cost: normalizedUsageCostSchema.optional(),
+    tools: z.array(canonicalToolCallSchema),
+    commands: z.array(z.string()),
+    source: transcriptSourceProvenanceSchema,
+});
+export const canonicalSessionTranscriptSchema = z.object({
+    provider: z.string().optional(),
+    sessionId: z.string().optional(),
+    sourcePath: z.string().optional(),
+    cwd: z.string().optional(),
+    gitBranch: z.string().optional(),
+    startedAt: z.string().optional(),
+    endedAt: z.string().optional(),
+    models: z.array(z.string()),
+    messages: z.array(canonicalTranscriptMessageSchema),
+    tools: z.array(canonicalToolCallSchema),
+    commands: z.array(z.string()),
+    usage: z.object({
+        events: z.array(normalizedUsageSchema),
+        costs: z.array(normalizedUsageCostSchema),
+        totals: z.object({
+            uncachedInputTokens: z.number().finite().nonnegative(),
+            cacheReadTokens: z.number().finite().nonnegative(),
+            cacheWriteTokens: z.number().finite().nonnegative(),
+            outputTokens: z.number().finite().nonnegative(),
+            reasoningTokens: z.number().finite().nonnegative(),
+            cacheInclusiveInputTokens: z.number().finite().nonnegative(),
+            billableOutputTokens: z.number().finite().nonnegative(),
+            totalTokens: z.number().finite().nonnegative(),
+        }),
+        totalCostUsd: z.number().finite().nonnegative().nullable(),
+        pricedCostUsd: z.number().finite().nonnegative(),
+        unpricedEvents: z.number().int().nonnegative(),
+    }),
+    provenance: z.object({
+        source: z.literal('session-events'),
+        fidelity: z.enum(['snippet', 'full']),
+        eventCount: z.number().int().nonnegative(),
+    }),
+});

package/dist/esm/schemas/usageNormalization.js

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+const normalizedUsageObjectSchema = z.object({
+    uncachedInputTokens: z.number().finite().nonnegative(),
+    cacheReadTokens: z.number().finite().nonnegative(),
+    cacheWriteTokens: z.number().finite().nonnegative(),
+    outputTokens: z.number().finite().nonnegative(),
+    reasoningTokens: z.number().finite().nonnegative(),
+    reasoningIncludedInOutput: z.boolean(),
+    cacheInclusiveInputTokens: z.number().finite().nonnegative(),
+    billableOutputTokens: z.number().finite().nonnegative(),
+    totalTokens: z.number().finite().nonnegative(),
+    model: z.string().optional(),
+    reportedCostUsd: z.number().finite().nonnegative().optional(),
+    provenance: z.object({
+        provider: z.string().optional(),
+        semantics: z.enum(['anthropic-additive-cache', 'openai-inclusive-cache', 'sidekick-disjoint']),
+        source: z.string().optional(),
+    }),
+});
+export const normalizedUsageSchema = normalizedUsageObjectSchema.superRefine((usage, context) => {
+    const expectedInput = usage.uncachedInputTokens + usage.cacheReadTokens + usage.cacheWriteTokens;
+    const expectedOutput = usage.outputTokens + (usage.reasoningIncludedInOutput ? 0 : usage.reasoningTokens);
+    if (usage.cacheInclusiveInputTokens !== expectedInput) {
+        context.addIssue({ code: 'custom', message: 'cacheInclusiveInputTokens is inconsistent' });
+    }
+    if (usage.billableOutputTokens !== expectedOutput) {
+        context.addIssue({ code: 'custom', message: 'billableOutputTokens is inconsistent' });
+    }
+    if (usage.totalTokens !== expectedInput + expectedOutput) {
+        context.addIssue({ code: 'custom', message: 'totalTokens is inconsistent' });
+    }
+});
+export const normalizedUsageCostSchema = z.object({
+    costUsd: z.number().finite().nonnegative().nullable(),
+    source: z.enum(['provider-reported', 'explicit-pricing', 'model-catalog', 'unpriced']),
+    modelId: z.string().optional(),
+    usage: normalizedUsageSchema,
+});