sidekick-shared 0.27.6 → 0.28.0

package/dist/providers/codexRollouts.js

@@ -0,0 +1,261 @@
+"use strict";
+/**
+ * Codex rollout-file helpers shared by the provider and by callers that only
+ * list rollouts: bounded first-line reads, session_meta and cwd lookups, and
+ * the async session-file listing. Kept apart from the provider class so a
+ * listing does not bundle the provider's stats, context and reader code.
+ */
+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.getSessionsDirs = getSessionsDirs;
+exports.readFirstLines = readFirstLines;
+exports.readSessionMeta = readSessionMeta;
+exports.readFirstLineAsync = readFirstLineAsync;
+exports.parseSessionMetaLine = parseSessionMetaLine;
+exports.readSessionCwd = readSessionCwd;
+exports.readSessionCwdAsync = readSessionCwdAsync;
+exports.initializeCounters = initializeCounters;
+exports.cwdMatches = cwdMatches;
+exports.normalizePath = normalizePath;
+exports.listCodexSessionFilesAsync = listCodexSessionFilesAsync;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const codexPaths_1 = require("../codexPaths");
+const directoryListingCache_1 = require("./directoryListingCache");
+const rolloutWalker_1 = require("./rolloutWalker");
+/** Every directory across the monitored homes that may hold rollouts, archived ones included. */
+function getSessionsDirs() {
+    return (0, codexPaths_1.getCodexSessionsDirs)();
+}
+/**
+ * Read the first N complete lines from a file using chunked reads.
+ * Handles arbitrarily long lines (Codex session_meta can be 10KB+).
+ */
+function readFirstLines(filePath, maxLines, maxBytes = 256 * 1024) {
+    const lines = [];
+    let fd;
+    try {
+        fd = fs.openSync(filePath, 'r');
+    }
+    catch {
+        return [];
+    }
+    let pending = '';
+    let totalRead = 0;
+    const chunkSize = 16384;
+    try {
+        while (totalRead < maxBytes && lines.length < maxLines) {
+            const buf = Buffer.alloc(Math.min(chunkSize, maxBytes - totalRead));
+            const bytesRead = fs.readSync(fd, buf, 0, buf.length, totalRead);
+            if (bytesRead === 0)
+                break;
+            totalRead += bytesRead;
+            pending += buf.toString('utf-8', 0, bytesRead);
+            let nlIdx;
+            while ((nlIdx = pending.indexOf('\n')) !== -1 && lines.length < maxLines) {
+                lines.push(pending.substring(0, nlIdx));
+                pending = pending.substring(nlIdx + 1);
+            }
+        }
+        if (pending.trim() && lines.length < maxLines) {
+            lines.push(pending);
+        }
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return lines;
+}
+/** Read session_meta from the beginning of a rollout file. */
+function readSessionMeta(rolloutPath) {
+    try {
+        const lines = readFirstLines(rolloutPath, 1);
+        const firstLine = lines[0]?.trim();
+        if (!firstLine)
+            return null;
+        const parsed = JSON.parse(firstLine);
+        if (parsed.type === 'session_meta') {
+            return parsed.payload;
+        }
+    }
+    catch {
+        // Skip
+    }
+    return null;
+}
+/**
+ * First line of a rollout, chunk-read under the same 256 KiB cap as
+ * readFirstLines(). `complete` is false while the line has no newline yet
+ * (a rollout that was just created) or the file could not be read, so
+ * callers know not to cache the answer.
+ */
+async function readFirstLineAsync(rolloutPath) {
+    // Mirrors readSessionMeta()/readFirstLines(): chunk-read until the first
+    // line is complete under the same 256 KiB cap — session_meta carries
+    // `instructions` and can far exceed a single chunk.
+    const maxBytes = 256 * 1024;
+    const chunkSize = 64 * 1024;
+    let handle = null;
+    try {
+        handle = await fs.promises.open(rolloutPath, 'r');
+        const chunks = [];
+        let totalRead = 0;
+        let newlineFound = false;
+        while (totalRead < maxBytes && !newlineFound) {
+            const buffer = Buffer.alloc(Math.min(chunkSize, maxBytes - totalRead));
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, totalRead);
+            if (bytesRead === 0)
+                break;
+            const chunk = buffer.subarray(0, bytesRead);
+            chunks.push(chunk);
+            totalRead += bytesRead;
+            newlineFound = chunk.includes(0x0a);
+        }
+        const firstLine = Buffer.concat(chunks).toString('utf8').split('\n', 1)[0]?.trim();
+        return { line: firstLine || null, complete: newlineFound || totalRead >= maxBytes };
+    }
+    catch {
+        return { line: null, complete: false };
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+function parseSessionMetaLine(line) {
+    if (!line)
+        return null;
+    try {
+        const parsed = JSON.parse(line);
+        return parsed.type === 'session_meta' ? parsed.payload : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read the CWD from a rollout file's session_meta. Cached per path, bounded
+ * so a long-lived host watching a large history cannot grow it without limit
+ * (insertion order doubles as an eviction order).
+ */
+const CWD_CACHE_LIMIT = 5000;
+const cwdCache = new Map();
+function rememberCwd(rolloutPath, cwd) {
+    if (!cwdCache.has(rolloutPath) && cwdCache.size >= CWD_CACHE_LIMIT) {
+        const oldest = cwdCache.keys().next().value;
+        if (oldest !== undefined)
+            cwdCache.delete(oldest);
+    }
+    cwdCache.set(rolloutPath, cwd);
+}
+function readSessionCwd(rolloutPath) {
+    const cached = cwdCache.get(rolloutPath);
+    if (cached !== undefined)
+        return cached;
+    const meta = readSessionMeta(rolloutPath);
+    const cwd = meta?.cwd || null;
+    rememberCwd(rolloutPath, cwd);
+    return cwd;
+}
+/** Async twin of readSessionCwd, sharing its cache so repeat listings do no content reads. */
+async function readSessionCwdAsync(rolloutPath) {
+    const cached = cwdCache.get(rolloutPath);
+    if (cached !== undefined)
+        return cached;
+    const { line, complete } = await readFirstLineAsync(rolloutPath);
+    const cwd = parseSessionMetaLine(line)?.cwd || null;
+    // A rollout observed before its session_meta line is flushed has no cwd
+    // yet; caching that null would hide the session from its workspace until
+    // the entry aged out, so only conclusive answers are remembered.
+    if (cwd !== null || complete)
+        rememberCwd(rolloutPath, cwd);
+    return cwd;
+}
+/** Built-in enumerators report explicit zeros rather than leaving a counter unset. */
+function initializeCounters(stats) {
+    if (!stats)
+        return;
+    stats.directoriesListed ??= 0;
+    stats.directoriesStatted ??= 0;
+    stats.filesStatted ??= 0;
+}
+/** Check if a session's CWD matches a workspace path. */
+function cwdMatches(sessionCwd, workspacePath) {
+    const normalizedSession = normalizePath(sessionCwd);
+    const normalizedWorkspace = normalizePath(workspacePath);
+    return (normalizedSession === normalizedWorkspace ||
+        normalizedWorkspace.startsWith(normalizedSession + path.sep) ||
+        normalizedSession.startsWith(normalizedWorkspace + path.sep));
+}
+/** Normalize a path using realpathSync. */
+function normalizePath(input) {
+    try {
+        return fs.realpathSync(input);
+    }
+    catch {
+        return path.resolve(input);
+    }
+}
+/**
+ * List rollout files across the monitored Codex homes, newest first. With
+ * `workspacePath`, keeps rollouts whose session_meta cwd equals, contains, or
+ * sits inside it.
+ */
+async function listCodexSessionFilesAsync(workspacePath, options = {}, cache = new directoryListingCache_1.DirectoryListingCache()) {
+    const results = [];
+    initializeCounters(options.stats);
+    // One capped walk across the homes (deduplicated, newest first) through
+    // the directory cache. With a workspace filter the limit applies after
+    // filtering, so the walk itself is bounded only by its file cap.
+    const files = await (0, rolloutWalker_1.walkRolloutFilesAsync)(getSessionsDirs(), {
+        limit: workspacePath ? undefined : options.limit,
+        since: options.since,
+        cache,
+        revalidateRecent: options.revalidateRecent,
+        stats: options.stats,
+    });
+    for (const file of files) {
+        if (options.limit !== undefined && results.length >= options.limit)
+            break;
+        const info = { ...file };
+        if (workspacePath) {
+            const cwd = await readSessionCwdAsync(file.path);
+            if (!cwd || !cwdMatches(cwd, workspacePath))
+                continue;
+            info.workspacePath = cwd;
+        }
+        results.push(info);
+    }
+    return results;
+}

package/dist/providers/detect.js

@@ -42,12 +42,12 @@ exports._resetProviderDetectionCache = _resetProviderDetectionCache;
 exports.getAllDetectedProviders = getAllDetectedProviders;
 exports.detectProvider = detectProvider;
 const fs = __importStar(require("fs"));
-const os = __importStar(require("os"));
 const path = __importStar(require("path"));
-const codexProfiles_1 = require("../codexProfiles");
+const codexPaths_1 = require("../codexPaths");
 const openCode_1 = require("./openCode");
+const claudePaths_1 = require("../claudePaths");
 function getCodexHomes() {
-    return (0, codexProfiles_1.getCodexMonitoringHomes)();
+    return (0, codexPaths_1.getCodexMonitoringHomes)();
 }
 function hasCodexStateDb(codexHome) {
     try {
@@ -160,7 +160,7 @@ function getCodexActivityMtime() {
     return latest;
 }
 function getProviderPaths() {
-    const claudeBase = path.join(os.homedir(), '.claude', 'projects');
+    const claudeBase = (0, claudePaths_1.getClaudeProjectsDir)();
     const openCodeDataDir = (0, openCode_1.getOpenCodeDataDir)();
     const codexHomes = getCodexHomes();
     return {

package/dist/readers/plans.js

@@ -43,12 +43,12 @@ exports.writePlans = writePlans;
 exports.readClaudeCodePlanFiles = readClaudeCodePlanFiles;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-const os = __importStar(require("os"));
 const plan_1 = require("../types/plan");
 const paths_1 = require("../paths");
 const helpers_1 = require("./helpers");
 const planExtractor_1 = require("../parsers/planExtractor");
 const atomic_1 = require("../writers/atomic");
+const claudePaths_1 = require("../claudePaths");
 async function readPlans(slug, opts) {
     const filePath = (0, paths_1.getProjectDataPath)(slug, 'plans');
     const store = await (0, helpers_1.readJsonStore)(filePath);
@@ -178,8 +178,8 @@ async function writePlans(slug, plans) {
  * sessions in the given workspace. Maps session JSONL slugs to plan filenames.
  */
 async function readClaudeCodePlanFiles(workspacePath) {
-    const claudePlansDir = path.join(os.homedir(), '.claude', 'plans');
-    const claudeProjectsDir = path.join(os.homedir(), '.claude', 'projects');
+    const claudePlansDir = path.join((0, claudePaths_1.getLiveClaudeHome)(), 'plans');
+    const claudeProjectsDir = (0, claudePaths_1.getClaudeProjectsDir)();
     // Find the project directory in ~/.claude/projects/
     const cwd = workspacePath || process.cwd();
     const encoded = (0, paths_1.encodeWorkspacePath)(path.resolve(cwd));

package/dist/schemas/index.d.ts

@@ -17,6 +17,8 @@ export { normalizedUsageSchema, normalizedUsageCostSchema } from './usageNormali
 export type { NormalizedUsage, NormalizedUsageCost } from '../usageNormalization';
 export { tokenEstimateSchema } from './tokenEstimation';
 export type { TokenEstimate } from '../tokenEstimation';
+export { providerAuthenticationEvidenceSchema, providerFailureEvidenceSchema, providerRetryAfterSchema, providerFailureDiagnosisSchema, } from './providerFailure';
+export type { ProviderAuthenticationEvidence, ProviderFailureDiagnosis, ProviderFailureEvidence, ProviderRetryAfter, } from '../providerFailure';
 export { transcriptSourceProvenanceSchema, canonicalTranscriptBlockSchema, canonicalToolCallSchema, canonicalTranscriptMessageSchema, canonicalSessionTranscriptSchema, } from './transcript';
 export type { CanonicalSessionTranscript, CanonicalTranscriptMessage, CanonicalToolCall, TranscriptSourceProvenance, } from '../transcript';
 export { observationProvenanceV1Schema, observedAgentSessionV1Schema, observedValueV1Schema, pendingUserRequestV1Schema, providerCapabilitiesV1Schema, providerSessionAdapterV1Schema, sessionEvidenceRefV1Schema, } from './observedSessionV1';

package/dist/schemas/index.js

@@ -12,8 +12,8 @@
  * subpath is self-sufficient for boundary-validation modules.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.activeAccountStatusSchema = exports.activeProviderAccountStatusSchema = exports.quotaHistoryDailyBucketSchema = exports.quotaHistorySampleSchema = exports.quotaHistoryRuntimeProviderSchema = exports.providerQuotaMapSchema = exports.zaiProviderQuotaStateSchema = exports.codexProviderQuotaStateSchema = exports.claudeProviderQuotaStateSchema = exports.providerQuotaStateSchema = exports.runtimeQuotaProviderSchema = exports.quotaFailureDescriptorSchema = exports.peakHoursStateSchema = exports.codexResetCreditsSnapshotSchema = exports.codexResetCreditSchema = exports.quotaSourceSchema = exports.quotaProviderIdSchema = exports.quotaFailureKindSchema = exports.quotaStateSchema = exports.quotaWindowSchema = exports.sessionEvidenceRefV1Schema = exports.providerSessionAdapterV1Schema = exports.providerCapabilitiesV1Schema = exports.pendingUserRequestV1Schema = exports.observedValueV1Schema = exports.observedAgentSessionV1Schema = exports.observationProvenanceV1Schema = exports.canonicalSessionTranscriptSchema = exports.canonicalTranscriptMessageSchema = exports.canonicalToolCallSchema = exports.canonicalTranscriptBlockSchema = exports.transcriptSourceProvenanceSchema = exports.tokenEstimateSchema = exports.normalizedUsageCostSchema = exports.normalizedUsageSchema = exports.toolResultSessionEventSchema = exports.toolUseSessionEventSchema = exports.systemSessionEventSchema = exports.summarySessionEventSchema = exports.assistantSessionEventSchema = exports.userSessionEventSchema = exports.extractSessionEvents = exports.permissionModeSchema = exports.sessionEventSchema = exports.sessionMessageSchema = exports.messageUsageSchema = exports.SESSION_PROVIDER_IDS = exports.RUNTIME_QUOTA_PROVIDER_IDS = exports.QUOTA_PROVIDER_IDS = exports.ACCOUNT_PROVIDER_IDS = void 0;
-exports.stateFileWriterSchema = exports.stateFileSessionSchema = exports.stateFileQuotaWindowSchema = exports.stateFileQuotaSchema = exports.stateFileContextSchema = exports.stateFileBillingBlockSchema = exports.stateFileAccountSchema = exports.sidekickStateFileSchema = exports.assistantTurnToolRefSchema = exports.assistantTurnToolGroupStepSchema = exports.assistantTurnTimelineItemSchema = exports.assistantTurnSubagentStatusSchema = exports.assistantTurnSubagentSchema = exports.assistantTurnReasoningTimelineItemSchema = exports.assistantTurnProjectionSchema = exports.assistantTurnProcessStepSchema = exports.assistantTurnProcessSchema = exports.assistantTurnNarrationStepSchema = exports.assistantTurnEventTypeSchema = exports.assistantTurnEventSchema = exports.accountLaunchEnvSchema = exports.syncReportSchema = exports.providerSyncReportSchema = exports.lastSwitchRecordSchema = exports.switchAccountResultSchema = exports.runningAccountConsumerSchema = exports.accountConsumerKindSchema = exports.runningProcessSchema = exports.accountViewSchema = exports.accountHealthSchema = exports.accountHealthSidecarSchema = exports.accountHealthSourceSchema = exports.accountHealthStateSchema = exports.listAllAccountsResultSchema = exports.savedAccountProfileSchema = exports.accountEntrySchema = exports.accountLoginStatusSchema = exports.beginAccountLoginResultSchema = exports.accountManagerResultSchema = exports.accountProviderIdSchema = void 0;
+exports.quotaHistoryRuntimeProviderSchema = exports.providerQuotaMapSchema = exports.zaiProviderQuotaStateSchema = exports.codexProviderQuotaStateSchema = exports.claudeProviderQuotaStateSchema = exports.providerQuotaStateSchema = exports.runtimeQuotaProviderSchema = exports.quotaFailureDescriptorSchema = exports.peakHoursStateSchema = exports.codexResetCreditsSnapshotSchema = exports.codexResetCreditSchema = exports.quotaSourceSchema = exports.quotaProviderIdSchema = exports.quotaFailureKindSchema = exports.quotaStateSchema = exports.quotaWindowSchema = exports.sessionEvidenceRefV1Schema = exports.providerSessionAdapterV1Schema = exports.providerCapabilitiesV1Schema = exports.pendingUserRequestV1Schema = exports.observedValueV1Schema = exports.observedAgentSessionV1Schema = exports.observationProvenanceV1Schema = exports.canonicalSessionTranscriptSchema = exports.canonicalTranscriptMessageSchema = exports.canonicalToolCallSchema = exports.canonicalTranscriptBlockSchema = exports.transcriptSourceProvenanceSchema = exports.providerFailureDiagnosisSchema = exports.providerRetryAfterSchema = exports.providerFailureEvidenceSchema = exports.providerAuthenticationEvidenceSchema = exports.tokenEstimateSchema = exports.normalizedUsageCostSchema = exports.normalizedUsageSchema = exports.toolResultSessionEventSchema = exports.toolUseSessionEventSchema = exports.systemSessionEventSchema = exports.summarySessionEventSchema = exports.assistantSessionEventSchema = exports.userSessionEventSchema = exports.extractSessionEvents = exports.permissionModeSchema = exports.sessionEventSchema = exports.sessionMessageSchema = exports.messageUsageSchema = exports.SESSION_PROVIDER_IDS = exports.RUNTIME_QUOTA_PROVIDER_IDS = exports.QUOTA_PROVIDER_IDS = exports.ACCOUNT_PROVIDER_IDS = void 0;
+exports.stateFileWriterSchema = exports.stateFileSessionSchema = exports.stateFileQuotaWindowSchema = exports.stateFileQuotaSchema = exports.stateFileContextSchema = exports.stateFileBillingBlockSchema = exports.stateFileAccountSchema = exports.sidekickStateFileSchema = exports.assistantTurnToolRefSchema = exports.assistantTurnToolGroupStepSchema = exports.assistantTurnTimelineItemSchema = exports.assistantTurnSubagentStatusSchema = exports.assistantTurnSubagentSchema = exports.assistantTurnReasoningTimelineItemSchema = exports.assistantTurnProjectionSchema = exports.assistantTurnProcessStepSchema = exports.assistantTurnProcessSchema = exports.assistantTurnNarrationStepSchema = exports.assistantTurnEventTypeSchema = exports.assistantTurnEventSchema = exports.accountLaunchEnvSchema = exports.syncReportSchema = exports.providerSyncReportSchema = exports.lastSwitchRecordSchema = exports.switchAccountResultSchema = exports.runningAccountConsumerSchema = exports.accountConsumerKindSchema = exports.runningProcessSchema = exports.accountViewSchema = exports.accountHealthSchema = exports.accountHealthSidecarSchema = exports.accountHealthSourceSchema = exports.accountHealthStateSchema = exports.listAllAccountsResultSchema = exports.savedAccountProfileSchema = exports.accountEntrySchema = exports.accountLoginStatusSchema = exports.beginAccountLoginResultSchema = exports.accountManagerResultSchema = exports.accountProviderIdSchema = exports.activeAccountStatusSchema = exports.activeProviderAccountStatusSchema = exports.quotaHistoryDailyBucketSchema = exports.quotaHistorySampleSchema = void 0;
 var providerIds_1 = require("../providerIds");
 Object.defineProperty(exports, "ACCOUNT_PROVIDER_IDS", { enumerable: true, get: function () { return providerIds_1.ACCOUNT_PROVIDER_IDS; } });
 Object.defineProperty(exports, "QUOTA_PROVIDER_IDS", { enumerable: true, get: function () { return providerIds_1.QUOTA_PROVIDER_IDS; } });
@@ -36,6 +36,11 @@ Object.defineProperty(exports, "normalizedUsageSchema", { enumerable: true, get:
 Object.defineProperty(exports, "normalizedUsageCostSchema", { enumerable: true, get: function () { return usageNormalization_1.normalizedUsageCostSchema; } });
 var tokenEstimation_1 = require("./tokenEstimation");
 Object.defineProperty(exports, "tokenEstimateSchema", { enumerable: true, get: function () { return tokenEstimation_1.tokenEstimateSchema; } });
+var providerFailure_1 = require("./providerFailure");
+Object.defineProperty(exports, "providerAuthenticationEvidenceSchema", { enumerable: true, get: function () { return providerFailure_1.providerAuthenticationEvidenceSchema; } });
+Object.defineProperty(exports, "providerFailureEvidenceSchema", { enumerable: true, get: function () { return providerFailure_1.providerFailureEvidenceSchema; } });
+Object.defineProperty(exports, "providerRetryAfterSchema", { enumerable: true, get: function () { return providerFailure_1.providerRetryAfterSchema; } });
+Object.defineProperty(exports, "providerFailureDiagnosisSchema", { enumerable: true, get: function () { return providerFailure_1.providerFailureDiagnosisSchema; } });
 var transcript_1 = require("./transcript");
 Object.defineProperty(exports, "transcriptSourceProvenanceSchema", { enumerable: true, get: function () { return transcript_1.transcriptSourceProvenanceSchema; } });
 Object.defineProperty(exports, "canonicalTranscriptBlockSchema", { enumerable: true, get: function () { return transcript_1.canonicalTranscriptBlockSchema; } });

package/dist/schemas/providerFailure.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Zod schema for runtime validation of provider-failure diagnoses.
+ *
+ * The enums are built from the same `as const` arrays that define the
+ * TypeScript unions in `providerFailure.ts`, so a new failure code or recovery
+ * action reaches the schema without a second edit.
+ *
+ * @module schemas/providerFailure
+ */
+import { z } from 'zod';
+export declare const providerAuthenticationEvidenceSchema: z.ZodObject<{
+    credentialKind: z.ZodEnum<{
+        unknown: "unknown";
+        "api-key": "api-key";
+        oauth: "oauth";
+    }>;
+    state: z.ZodEnum<{
+        unknown: "unknown";
+        expired: "expired";
+        missing: "missing";
+        authenticated: "authenticated";
+        "signed-out": "signed-out";
+        rejected: "rejected";
+    }>;
+    checkedAt: z.ZodString;
+    source: z.ZodEnum<{
+        "local-check": "local-check";
+        "provider-response": "provider-response";
+    }>;
+}, z.core.$strip>;
+export declare const providerFailureEvidenceSchema: z.ZodObject<{
+    source: z.ZodEnum<{
+        message: "message";
+        "structured-error": "structured-error";
+        "http-status": "http-status";
+        "authentication-check": "authentication-check";
+    }>;
+    rule: z.ZodEnum<{
+        unknown: "unknown";
+        timeout: "timeout";
+        missing_credentials: "missing_credentials";
+        oauth_reauthentication_required: "oauth_reauthentication_required";
+        api_credentials_rejected: "api_credentials_rejected";
+        authentication_rejected: "authentication_rejected";
+        invalid_provider_session: "invalid_provider_session";
+        service_unavailable: "service_unavailable";
+        connection_failed: "connection_failed";
+        rate_limited: "rate_limited";
+        overloaded: "overloaded";
+        execution_policy_denied: "execution_policy_denied";
+        runtime_unavailable: "runtime_unavailable";
+        context_overflow: "context_overflow";
+    }>;
+    checkedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const providerRetryAfterSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"delay">;
+    delayMs: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"date">;
+    at: z.ZodString;
+}, z.core.$strip>], "kind">;
+export declare const providerFailureDiagnosisSchema: z.ZodObject<{
+    provider: z.ZodEnum<{
+        "claude-code": "claude-code";
+        codex: "codex";
+    }>;
+    credentialKind: z.ZodEnum<{
+        unknown: "unknown";
+        "api-key": "api-key";
+        oauth: "oauth";
+    }>;
+    diagnosis: z.ZodEnum<{
+        unknown: "unknown";
+        timeout: "timeout";
+        missing_credentials: "missing_credentials";
+        oauth_reauthentication_required: "oauth_reauthentication_required";
+        api_credentials_rejected: "api_credentials_rejected";
+        authentication_rejected: "authentication_rejected";
+        invalid_provider_session: "invalid_provider_session";
+        service_unavailable: "service_unavailable";
+        connection_failed: "connection_failed";
+        rate_limited: "rate_limited";
+        overloaded: "overloaded";
+        execution_policy_denied: "execution_policy_denied";
+        runtime_unavailable: "runtime_unavailable";
+        context_overflow: "context_overflow";
+    }>;
+    recovery: z.ZodEnum<{
+        sign_in: "sign_in";
+        update_credentials: "update_credentials";
+        check_authentication: "check_authentication";
+        start_new_session: "start_new_session";
+        retry_later: "retry_later";
+        check_connection: "check_connection";
+        review_execution_policy: "review_execution_policy";
+        repair_runtime: "repair_runtime";
+        reduce_context: "reduce_context";
+        inspect_error: "inspect_error";
+    }>;
+    evidence: z.ZodArray<z.ZodObject<{
+        source: z.ZodEnum<{
+            message: "message";
+            "structured-error": "structured-error";
+            "http-status": "http-status";
+            "authentication-check": "authentication-check";
+        }>;
+        rule: z.ZodEnum<{
+            unknown: "unknown";
+            timeout: "timeout";
+            missing_credentials: "missing_credentials";
+            oauth_reauthentication_required: "oauth_reauthentication_required";
+            api_credentials_rejected: "api_credentials_rejected";
+            authentication_rejected: "authentication_rejected";
+            invalid_provider_session: "invalid_provider_session";
+            service_unavailable: "service_unavailable";
+            connection_failed: "connection_failed";
+            rate_limited: "rate_limited";
+            overloaded: "overloaded";
+            execution_policy_denied: "execution_policy_denied";
+            runtime_unavailable: "runtime_unavailable";
+            context_overflow: "context_overflow";
+        }>;
+        checkedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    authentication: z.ZodOptional<z.ZodObject<{
+        credentialKind: z.ZodEnum<{
+            unknown: "unknown";
+            "api-key": "api-key";
+            oauth: "oauth";
+        }>;
+        state: z.ZodEnum<{
+            unknown: "unknown";
+            expired: "expired";
+            missing: "missing";
+            authenticated: "authenticated";
+            "signed-out": "signed-out";
+            rejected: "rejected";
+        }>;
+        checkedAt: z.ZodString;
+        source: z.ZodEnum<{
+            "local-check": "local-check";
+            "provider-response": "provider-response";
+        }>;
+    }, z.core.$strip>>;
+    httpStatus: z.ZodOptional<z.ZodNumber>;
+    retryAfter: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"delay">;
+        delayMs: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"date">;
+        at: z.ZodString;
+    }, z.core.$strip>], "kind">>;
+}, z.core.$strip>;

package/dist/schemas/providerFailure.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Zod schema for runtime validation of provider-failure diagnoses.
+ *
+ * The enums are built from the same `as const` arrays that define the
+ * TypeScript unions in `providerFailure.ts`, so a new failure code or recovery
+ * action reaches the schema without a second edit.
+ *
+ * @module schemas/providerFailure
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.providerFailureDiagnosisSchema = exports.providerRetryAfterSchema = exports.providerFailureEvidenceSchema = exports.providerAuthenticationEvidenceSchema = void 0;
+const zod_1 = require("zod");
+const providerIds_1 = require("../providerIds");
+const providerFailure_1 = require("../providerFailure");
+exports.providerAuthenticationEvidenceSchema = zod_1.z.object({
+    credentialKind: zod_1.z.enum(providerFailure_1.PROVIDER_CREDENTIAL_KINDS),
+    state: zod_1.z.enum(providerFailure_1.PROVIDER_AUTHENTICATION_STATES),
+    checkedAt: zod_1.z.string(),
+    source: zod_1.z.enum(providerFailure_1.PROVIDER_AUTHENTICATION_SOURCES),
+});
+exports.providerFailureEvidenceSchema = zod_1.z.object({
+    source: zod_1.z.enum(providerFailure_1.PROVIDER_FAILURE_EVIDENCE_SOURCES),
+    rule: zod_1.z.enum(providerFailure_1.PROVIDER_FAILURE_CODES),
+    checkedAt: zod_1.z.string().optional(),
+});
+exports.providerRetryAfterSchema = zod_1.z.discriminatedUnion('kind', [
+    zod_1.z.object({ kind: zod_1.z.literal('delay'), delayMs: zod_1.z.number() }),
+    zod_1.z.object({ kind: zod_1.z.literal('date'), at: zod_1.z.string() }),
+]);
+exports.providerFailureDiagnosisSchema = zod_1.z.object({
+    provider: zod_1.z.enum(providerIds_1.ACCOUNT_PROVIDER_IDS),
+    credentialKind: zod_1.z.enum(providerFailure_1.PROVIDER_CREDENTIAL_KINDS),
+    diagnosis: zod_1.z.enum(providerFailure_1.PROVIDER_FAILURE_CODES),
+    recovery: zod_1.z.enum(providerFailure_1.PROVIDER_RECOVERY_ACTIONS),
+    evidence: zod_1.z.array(exports.providerFailureEvidenceSchema),
+    authentication: exports.providerAuthenticationEvidenceSchema.optional(),
+    httpStatus: zod_1.z.number().optional(),
+    retryAfter: exports.providerRetryAfterSchema.optional(),
+});

package/dist/sessionPromptHistory.d.ts

@@ -13,7 +13,7 @@
  * `sessionIds` continues. Scope fails closed as in `collectPromptHistory()`,
  * and replies or signals that belong to an out-of-scope prompt are dropped.
  */
-import { type PromptHistoryEntry, type PromptHistoryExclusion, type PromptHistoryProvider } from './promptHistory';
+import { type PromptHistoryEntry, type PromptHistoryExclusion, type PromptHistoryProvider, type PromptHistorySessionRef } from './promptHistory';
 import { type PromptHistoryReply, type PromptHistorySignal } from './sessionPromptSignals';
 export interface SessionPromptHistoryInclude {
     /** Interrupts, rejected and failed tool calls, compactions, API errors, rollbacks. */
@@ -40,8 +40,14 @@ export interface CollectSessionPromptHistoryOptions {
     includeWorktrees?: boolean;
     /** Default both. */
     providers?: PromptHistoryProvider[];
-    /** Only these sessions (exact ids). */
+    /** Only these sessions (exact ids, any provider). */
     sessionIds?: string[];
+    /**
+     * Only these sessions, matched on provider and id, or on the exact file
+     * when `sessionKey` is given. Combined with `sessionIds`, a session that
+     * matches either is read.
+     */
+    sessionRefs?: PromptHistorySessionRef[];
     /** Only sessions whose file changed at or after this. Each comes back whole. */
     since?: Date;
     /** Return at most this many sessions, most recently modified first. */
@@ -51,7 +57,7 @@ export interface CollectSessionPromptHistoryOptions {
     bounds?: SessionPromptHistoryBounds;
     signal?: AbortSignal;
 }
-export interface PromptHistorySessionPrompt extends Omit<PromptHistoryEntry, 'provider' | 'sessionId'> {
+export interface PromptHistorySessionPrompt extends Omit<PromptHistoryEntry, 'provider' | 'sessionId' | 'sessionKey'> {
     /** With `include.replies`: the agent's last text for this prompt's turn. */
     reply?: PromptHistoryReply;
 }
@@ -80,11 +86,10 @@ export interface PromptHistorySession {
     droppedPrompts: number;
     /** Records left out as oversized or malformed (see `exclusions`). */
     excludedRecords: number;
+    /** Opaque key of the session file; tells apart two files with one session id. */
+    sessionKey?: string;
 }
-export interface PromptHistorySessionRef {
-    provider: PromptHistoryProvider;
-    sessionId: string;
-}
+export type { PromptHistorySessionRef };
 export type SessionPromptHistoryBound = 'maxSessions' | 'maxSessionBytes' | 'maxTotalBytes' | 'deadline' | 'aborted';
 export interface SessionPromptHistoryStats {
     /** Session files that matched the provider, id, and `since` filters. */

package/dist/sessionPromptHistory.js

@@ -117,6 +117,7 @@ async function collectSessionPromptHistory(options) {
     const refOf = ({ candidate }) => ({
         provider: candidate.provider,
         sessionId: candidate.sessionId,
+        sessionKey: candidate.key,
     });
     let totalBytes = 0;
     for (let index = 0; index < selected.length && sessions.length < limit; index++) {
@@ -224,9 +225,19 @@ async function selectCandidates(options, listingRoots) {
     const sinceMs = options.since ? options.since.getTime() : null;
     const providers = options.providers ?? ['claude-code', 'codex'];
     let candidates = await (0, promptHistory_1.listCandidates)(providers, listingRoots, sinceMs);
-    if (options.sessionIds) {
-        const wanted = new Set(options.sessionIds);
-        candidates = candidates.filter((candidate) => wanted.has(candidate.sessionId));
+    if (options.sessionIds || options.sessionRefs) {
+        const ids = new Set(options.sessionIds ?? []);
+        const keys = new Set();
+        const refs = new Set();
+        for (const ref of options.sessionRefs ?? []) {
+            if (ref.sessionKey)
+                keys.add(ref.sessionKey);
+            else
+                refs.add(`${ref.provider}:${ref.sessionId}`);
+        }
+        candidates = candidates.filter((candidate) => ids.has(candidate.sessionId) ||
+            keys.has(candidate.key) ||
+            refs.has(`${candidate.provider}:${candidate.sessionId}`));
     }
     const selected = [];
     for (const candidate of candidates) {
@@ -251,6 +262,7 @@ function buildSession(candidate, entries, lastOrdinal, extraction, include, read
     const session = {
         provider: candidate.provider,
         sessionId: candidate.sessionId,
+        sessionKey: candidate.key,
         startedAt: extraction.firstTimestamp ?? ordered[0].timestamp,
         lastActivityAt: extraction.lastTimestamp ?? ordered[ordered.length - 1].timestamp,
         cwds: distinct(ordered.map((entry) => entry.cwd)),

package/dist/sessionPromptSignals.d.ts

@@ -9,6 +9,7 @@
  * ordinals of `collectPromptHistory()`.
  */
 import type { PromptHistoryProvider } from './promptHistory';
+import { type ToolCategory } from './toolCategory';
 export type PromptHistorySignalKind = 'interrupt' | 'toolRejected' | 'toolError' | 'compaction' | 'apiError' | 'rollback';
 export interface PromptHistorySignal {
     kind: PromptHistorySignalKind;
@@ -18,6 +19,14 @@ export interface PromptHistorySignal {
     afterOrdinal: number;
     /** The tool involved, for `toolRejected` and `toolError`, when the log names it. */
     tool?: string;
+    /** What `tool` does (`shell`, `file_edit`, `mcp`, …), from `classifyTool()`. */
+    toolCategory?: ToolCategory;
+    /**
+     * The MCP server of an MCP tool call: from `mcp__<server>__<tool>` names
+     * (Claude Code) or the call's own server field (Codex, whose `tool` is the
+     * bare tool name).
+     */
+    mcpServer?: string;
     /**
      * `toolRejected`: the reason the person typed, untruncated. `toolError` and
      * `apiError`: the error text, cut to 1024 characters (`textTruncated`).