sidekick-shared 0.23.1 → 0.24.1

package/dist/schemas/transcript.js

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

package/dist/schemas/usageNormalization.d.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+export declare const normalizedUsageSchema: z.ZodObject<{
+    uncachedInputTokens: z.ZodNumber;
+    cacheReadTokens: z.ZodNumber;
+    cacheWriteTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    reasoningTokens: z.ZodNumber;
+    reasoningIncludedInOutput: z.ZodBoolean;
+    cacheInclusiveInputTokens: z.ZodNumber;
+    billableOutputTokens: z.ZodNumber;
+    totalTokens: z.ZodNumber;
+    model: z.ZodOptional<z.ZodString>;
+    reportedCostUsd: z.ZodOptional<z.ZodNumber>;
+    provenance: z.ZodObject<{
+        provider: z.ZodOptional<z.ZodString>;
+        semantics: z.ZodEnum<{
+            "anthropic-additive-cache": "anthropic-additive-cache";
+            "openai-inclusive-cache": "openai-inclusive-cache";
+            "sidekick-disjoint": "sidekick-disjoint";
+        }>;
+        source: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const normalizedUsageCostSchema: z.ZodObject<{
+    costUsd: z.ZodNullable<z.ZodNumber>;
+    source: z.ZodEnum<{
+        unpriced: "unpriced";
+        "provider-reported": "provider-reported";
+        "explicit-pricing": "explicit-pricing";
+        "model-catalog": "model-catalog";
+    }>;
+    modelId: z.ZodOptional<z.ZodString>;
+    usage: z.ZodObject<{
+        uncachedInputTokens: z.ZodNumber;
+        cacheReadTokens: z.ZodNumber;
+        cacheWriteTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        reasoningTokens: z.ZodNumber;
+        reasoningIncludedInOutput: z.ZodBoolean;
+        cacheInclusiveInputTokens: z.ZodNumber;
+        billableOutputTokens: z.ZodNumber;
+        totalTokens: z.ZodNumber;
+        model: z.ZodOptional<z.ZodString>;
+        reportedCostUsd: z.ZodOptional<z.ZodNumber>;
+        provenance: z.ZodObject<{
+            provider: z.ZodOptional<z.ZodString>;
+            semantics: z.ZodEnum<{
+                "anthropic-additive-cache": "anthropic-additive-cache";
+                "openai-inclusive-cache": "openai-inclusive-cache";
+                "sidekick-disjoint": "sidekick-disjoint";
+            }>;
+            source: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+}, z.core.$strip>;

package/dist/schemas/usageNormalization.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizedUsageCostSchema = exports.normalizedUsageSchema = void 0;
+const zod_1 = require("zod");
+const normalizedUsageObjectSchema = zod_1.z.object({
+    uncachedInputTokens: zod_1.z.number().finite().nonnegative(),
+    cacheReadTokens: zod_1.z.number().finite().nonnegative(),
+    cacheWriteTokens: zod_1.z.number().finite().nonnegative(),
+    outputTokens: zod_1.z.number().finite().nonnegative(),
+    reasoningTokens: zod_1.z.number().finite().nonnegative(),
+    reasoningIncludedInOutput: zod_1.z.boolean(),
+    cacheInclusiveInputTokens: zod_1.z.number().finite().nonnegative(),
+    billableOutputTokens: zod_1.z.number().finite().nonnegative(),
+    totalTokens: zod_1.z.number().finite().nonnegative(),
+    model: zod_1.z.string().optional(),
+    reportedCostUsd: zod_1.z.number().finite().nonnegative().optional(),
+    provenance: zod_1.z.object({
+        provider: zod_1.z.string().optional(),
+        semantics: zod_1.z.enum(['anthropic-additive-cache', 'openai-inclusive-cache', 'sidekick-disjoint']),
+        source: zod_1.z.string().optional(),
+    }),
+});
+exports.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' });
+    }
+});
+exports.normalizedUsageCostSchema = zod_1.z.object({
+    costUsd: zod_1.z.number().finite().nonnegative().nullable(),
+    source: zod_1.z.enum(['provider-reported', 'explicit-pricing', 'model-catalog', 'unpriced']),
+    modelId: zod_1.z.string().optional(),
+    usage: exports.normalizedUsageSchema,
+});

package/dist/sessionTranscripts.d.ts

@@ -0,0 +1,16 @@
+import type { SessionProviderBase, ProviderId } from './providers/types';
+import { type CanonicalSessionTranscript, type ProjectSessionTranscriptOptions } from './transcript';
+export interface ProviderSessionIndex {
+    provider: ProviderId;
+    sessionId: string;
+    sessionPath: string;
+    label: string | null;
+    modifiedAt: string;
+}
+export interface ListRecentSessionsOptions {
+    limit?: number;
+}
+/** List recent sessions using the provider's existing discovery and metadata APIs. */
+export declare function listRecentSessions(provider: SessionProviderBase, workspacePath: string, options?: ListRecentSessionsOptions): ProviderSessionIndex[];
+/** Read a canonical transcript through a provider's existing reader. */
+export declare function readSessionTranscript(provider: SessionProviderBase, sessionPath: string, options?: Omit<ProjectSessionTranscriptOptions, 'provider' | 'sessionId' | 'sourcePath'>): CanonicalSessionTranscript;

package/dist/sessionTranscripts.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listRecentSessions = listRecentSessions;
+exports.readSessionTranscript = readSessionTranscript;
+const node_fs_1 = require("node:fs");
+const transcript_1 = require("./transcript");
+/** List recent sessions using the provider's existing discovery and metadata APIs. */
+function listRecentSessions(provider, workspacePath, options = {}) {
+    const limit = Math.max(0, options.limit ?? 20);
+    return provider
+        .findAllSessions(workspacePath)
+        .map((sessionPath) => ({
+        provider: provider.id,
+        sessionId: provider.getSessionId(sessionPath),
+        sessionPath,
+        label: provider.extractSessionLabel(sessionPath),
+        modifiedAt: sessionModifiedAt(provider, sessionPath).toISOString(),
+    }))
+        .sort((left, right) => right.modifiedAt.localeCompare(left.modifiedAt))
+        .slice(0, limit);
+}
+function sessionModifiedAt(provider, sessionPath) {
+    const metadata = provider.getSessionMetadata?.(sessionPath);
+    if (metadata)
+        return metadata.mtime;
+    try {
+        return (0, node_fs_1.statSync)(sessionPath).mtime;
+    }
+    catch {
+        return new Date(0);
+    }
+}
+/** Read a canonical transcript through a provider's existing reader. */
+function readSessionTranscript(provider, sessionPath, options = {}) {
+    const reader = provider.createReader(sessionPath);
+    try {
+        return (0, transcript_1.projectSessionTranscript)(reader.readAll(), {
+            ...options,
+            provider: provider.id,
+            sessionId: provider.getSessionId(sessionPath),
+            sourcePath: sessionPath,
+        });
+    }
+    finally {
+        reader.flush();
+    }
+}

package/dist/tokenEstimation.d.ts

@@ -0,0 +1,24 @@
+export type TokenEstimationMethod = 'exact' | 'sidekick-fallback-v1';
+export type TokenEstimationConfidence = 'exact' | 'medium' | 'low';
+export interface ExactTokenCounterContext {
+    model?: string;
+}
+export type ExactTokenCounter = (text: string, context: ExactTokenCounterContext) => number | null | undefined;
+export interface TokenEstimationOptions extends ExactTokenCounterContext {
+    exactCounter?: ExactTokenCounter;
+}
+export interface TokenEstimate {
+    count: number;
+    method: TokenEstimationMethod;
+    confidence: TokenEstimationConfidence;
+    provenance: string;
+}
+/**
+ * Estimate tokens without bundling a tokenizer.
+ *
+ * Fallback v1 counts Latin/source-code runs at 3.5 UTF-16 characters per
+ * token, CJK code points at one token, emoji at two, and other non-ASCII code
+ * points at one. The result is deliberately conservative for context budgets.
+ */
+export declare function estimateTextTokens(text: string, options?: TokenEstimationOptions): TokenEstimate;
+export declare function estimateSerializedTokens(value: unknown, options?: TokenEstimationOptions): TokenEstimate;

package/dist/tokenEstimation.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateTextTokens = estimateTextTokens;
+exports.estimateSerializedTokens = estimateSerializedTokens;
+const CJK = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/u;
+const EMOJI = /\p{Extended_Pictographic}/u;
+/**
+ * Estimate tokens without bundling a tokenizer.
+ *
+ * Fallback v1 counts Latin/source-code runs at 3.5 UTF-16 characters per
+ * token, CJK code points at one token, emoji at two, and other non-ASCII code
+ * points at one. The result is deliberately conservative for context budgets.
+ */
+function estimateTextTokens(text, options = {}) {
+    if (text.length === 0) {
+        return { count: 0, method: 'sidekick-fallback-v1', confidence: 'medium', provenance: 'empty' };
+    }
+    let exact;
+    try {
+        exact = options.exactCounter?.(text, { model: options.model });
+    }
+    catch {
+        exact = undefined;
+    }
+    if (typeof exact === 'number' && Number.isFinite(exact) && exact >= 0) {
+        return {
+            count: Math.ceil(exact),
+            method: 'exact',
+            confidence: 'exact',
+            provenance: options.model ?? 'injected-counter',
+        };
+    }
+    let asciiChars = 0;
+    let conservativeTokens = 0;
+    for (const codePoint of text) {
+        if (EMOJI.test(codePoint))
+            conservativeTokens += 2;
+        else if (CJK.test(codePoint))
+            conservativeTokens += 1;
+        else if ((codePoint.codePointAt(0) ?? 128) <= 127)
+            asciiChars += codePoint.length;
+        else
+            conservativeTokens += 1;
+    }
+    const count = Math.ceil(asciiChars / 3.5) + conservativeTokens;
+    return {
+        count: Number.isFinite(count) && count >= 0 ? count : 0,
+        method: 'sidekick-fallback-v1',
+        confidence: conservativeTokens > 0 ? 'low' : 'medium',
+        provenance: 'chars-per-token-3.5+cjk1+emoji2',
+    };
+}
+function estimateSerializedTokens(value, options = {}) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(value) ?? '';
+    }
+    catch {
+        serialized = String(value);
+    }
+    return estimateTextTokens(serialized, options);
+}

package/dist/transcript.d.ts

@@ -0,0 +1,98 @@
+import type { ProviderId } from './providers/types';
+import type { SessionEvent } from './types/sessionEvent';
+import { type NormalizedUsage, type NormalizedUsageCost } from './usageNormalization';
+export type TranscriptFidelity = 'snippet' | 'full';
+export interface TranscriptSourceProvenance {
+    provider?: ProviderId | string;
+    sessionId?: string;
+    sourcePath?: string;
+    source?: string;
+    entrypoint?: string;
+    isMeta?: boolean;
+    isSidechain?: boolean;
+    originalRole?: string;
+    eventIndex: number;
+    eventType: SessionEvent['type'];
+    eventId?: string;
+}
+export interface CanonicalTranscriptBlock {
+    type: 'text' | 'thinking' | 'tool_use' | 'tool_result' | 'image' | 'unknown';
+    text?: string;
+    toolName?: string;
+    toolUseId?: string;
+    input?: unknown;
+    output?: unknown;
+    isError?: boolean;
+    command?: string;
+    truncated?: boolean;
+    raw?: unknown;
+}
+export interface CanonicalTranscriptMessage {
+    id?: string;
+    role: 'user' | 'assistant' | 'system' | 'summary' | 'tool';
+    timestamp: string;
+    model?: string;
+    sourceLabel?: string;
+    content: CanonicalTranscriptBlock[];
+    text: string;
+    usage?: NormalizedUsage;
+    cost?: NormalizedUsageCost;
+    tools: CanonicalToolCall[];
+    commands: string[];
+    source: TranscriptSourceProvenance;
+}
+export interface CanonicalToolCall {
+    id?: string;
+    name: string;
+    timestamp: string;
+    input?: unknown;
+    output?: unknown;
+    isError?: boolean;
+    command?: string;
+    source: TranscriptSourceProvenance;
+}
+export interface CanonicalTranscriptUsageTotals {
+    uncachedInputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    cacheInclusiveInputTokens: number;
+    billableOutputTokens: number;
+    totalTokens: number;
+}
+export interface CanonicalSessionTranscript {
+    provider?: ProviderId | string;
+    sessionId?: string;
+    sourcePath?: string;
+    cwd?: string;
+    gitBranch?: string;
+    startedAt?: string;
+    endedAt?: string;
+    models: string[];
+    messages: CanonicalTranscriptMessage[];
+    tools: CanonicalToolCall[];
+    commands: string[];
+    usage: {
+        events: NormalizedUsage[];
+        costs: NormalizedUsageCost[];
+        totals: CanonicalTranscriptUsageTotals;
+        totalCostUsd: number | null;
+    };
+    provenance: {
+        source: 'session-events';
+        fidelity: TranscriptFidelity;
+        eventCount: number;
+    };
+}
+export interface ProjectSessionTranscriptOptions {
+    provider?: ProviderId | string;
+    sessionId?: string;
+    sourcePath?: string;
+    fidelity?: TranscriptFidelity;
+    /** Maximum characters per text/serialized block in snippet mode. Default 2000. */
+    maxContentChars?: number;
+    includeUnknownBlocks?: boolean;
+}
+/** Project canonical provider events into a bounded or full-fidelity transcript. */
+export declare function projectSessionTranscript(events: SessionEvent[], options?: ProjectSessionTranscriptOptions): CanonicalSessionTranscript;