sidekick-shared 0.19.3 → 0.21.0

package/README.md

@@ -7,6 +7,16 @@ Shared data access library for [Sidekick Agent Hub](https://github.com/cesarandr
 
 Types, parsers, providers, readers, formatters, aggregation, search, reporting, credentials, and quota for AI agent session monitoring. Used by both the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=CesarAndresLopez.sidekick-for-max) and the [CLI dashboard](https://www.npmjs.com/package/sidekick-agent-hub).
 
+## Recent additions
+
+- **Assistant-turn projection** — `segmentAssistantTurn()` / `assistantTurnEventsFromSessionEvents()` segment a provider-normalized turn into a browser-safe Timeline + Process + Answer shape (see [Assistant Turns](#api-overview)).
+- **Session-context snapshots** — `buildSessionContextSnapshot()` / `calculateSessionContextPressure()` expose layered evidence sources and low/medium/high context pressure.
+- **Zod boundary schemas** — runtime validation for data crossing process/IPC boundaries, importable fs-free from [`sidekick-shared/schemas`](#supported-import-paths).
+- **Opus 4.8 & Fable 5 model info** — 1M-token context windows and pricing, plus forgiving (trim/lowercase) model-ID lookups.
+- **Node-only asset extraction** — `gatherAssetsForCwd()` collects URLs, file paths, commands, and plans from recent Claude Code and Codex sessions.
+
+See the [full changelog](https://github.com/cesarandreslopez/sidekick-agent-hub/blob/main/CHANGELOG.md) for everything.
+
 ## Installation
 
 ```bash
@@ -33,11 +43,13 @@ npm install sidekick-shared
 | **Quota** | Claude Max subscription quota fetching (5-hour and 7-day windows) and Codex rate-limit extraction from event streams |
 | **Provider Status** | API health checking via status.claude.com and status.openai.com (indicator, components, incidents) |
 | **Schemas** | Zod schemas for runtime validation of data crossing process/IPC boundaries — JSONL session events (`sessionEventSchema`, `messageUsageSchema`, `sessionMessageSchema`), assistant turns, quota, account status, and quota history — plus `extractSessionEvents()` to unwrap `progress`-wrapped events. Also published fs-free via the [`sidekick-shared/schemas`](#supported-import-paths) subpath |
-| **Extractors** | Pure functions for single-event processing: `extractTokenUsage()`, `extractToolCall()` (top-level `tool_use`), `extractToolCalls()` (assistant content blocks) |
+| **Extractors** | Pure functions for single-event processing: `extractTokenUsage()`, `extractToolCall()` (top-level `tool_use`), `extractToolCalls()` (assistant content blocks), plus Node-only session asset extraction (`gatherAssetsForCwd()`, `readClaudeAssets()`, `readCodexAssets()`) for URLs, file paths, commands, and plans |
 | **Model Info & Pricing** | Model family parsing (Anthropic / OpenAI / Google, including legacy `claude-3-opus-…` and `claude-3-5-sonnet-…` IDs), context-window lookup (including Fable 5 / Opus 4.8 / Opus 4.7 / Sonnet 4.7 1M and GPT-5.x variants), pricing tables with optional LiteLLM hydration, null-aware cost (`calculateCost()`), provenance-preserving cost (`calculateCostWithProvenance()`, `mergeCostSources()`), and display helpers (`shortModelName()`, `getModelDisplayInfo()`, `compareModelIds()`, `sortModelIds()`, `formatCost()`) |
 | **Quota Polling** | `QuotaPoller` class with exponential backoff, active/idle intervals, and cached fallback |
 | **Multi-Provider Quota** | `MultiProviderQuotaService` orchestrates Claude polling + peak-hours + account labels + Codex quota updates behind one typed `{ claude?, codex? }` event stream. `CodexQuotaWatcher` watches the active Codex rollout for live rate limits with snapshot fallback |
 | **Accounts** | Multi-provider account registry (v2) with per-provider active account, save/switch/remove, v1 migration, `ensureDefaultAccounts()` for first-run bootstrap of the active system Claude/Codex credentials as a "Default" saved account, and `getActiveAccountStatus()` for a single-pass active-account read across providers |
+| **Account Management 2.0** | Provider-neutral acquisition + switching: `beginAccountLogin()` / `getAccountLoginStatus()` / `finalizeAccountLogin()` / `spawnAccountLogin()` drive a TTY-less, profile-isolated login that doesn't disturb the active account until finalization; `listAllAccounts()` and `switchAccount()` expose a shared switcher across Claude and Codex. Claude accounts get canonical profile homes with account-scoped macOS keychain suffixes and startup migration from legacy flat backups |
+| **Terminal sync & auto-switch** | Opt-in terminal profile pointers, shell-hook/launcher helpers, and a default-off `AutoSwitchController` (`decideAutoSwitch()`) that moves to a healthier saved account when quota crosses a configured threshold |
 | **Codex Profiles** | Codex account lifecycle — prepare, finalize, switch, remove — switching atomically swaps the profile's backed-up credentials into the system `~/.codex/auth.json`, with rotated-token staleness protection, one-time dual-home migration, and legacy multi-home session monitoring |
 | **Quota Snapshots** | Persistent quota caching per provider/account for offline fallback |
 | **Phrases** | Curated humorous phrases for loading/idle states, available as a flat `ALL_PHRASES` array or grouped via `PHRASE_CATEGORIES` for category-aware UI |
@@ -184,6 +196,33 @@ const tools = extractToolCalls(event);           // ToolCall[]    — assistant
 const toolFromEvent = extractToolCall(event);    // ToolCall | null — top-level `tool_use` events
 ```
 
+### Extract actionable assets from recent sessions
+
+Use the Node-only root API to collect URLs, filesystem-validated paths, commands the agent suggested for the user to run, and plan-mode plans from recent Claude Code and Codex sessions for exactly one working directory.
+
+This API powers `sidekick extract` and was contributed by [@B33pBeeps](https://github.com/B33pBeeps) (Juan Fourie), adapted from his MIT-licensed [`trawl`](https://github.com/B33pBeeps/trawl) project.
+
+```typescript
+import { gatherAssetsForCwd } from 'sidekick-shared';
+
+const assets = gatherAssetsForCwd({
+  cwd: '/path/to/project',
+  agents: ['claude', 'codex'],
+  caps: { url: 20, path: 20, command: 20, plan: 10 },
+});
+
+console.log(assets.urls);
+console.log(assets.paths);
+console.log(assets.commands);
+console.log(assets.plans);
+
+// Each item keeps stable text/display fields plus optional provenance:
+// { agent: 'claude' | 'codex', sessionPath, source }
+console.log(assets.urls[0]?.agent);
+```
+
+The extractor is safe for CLI and VS Code extension-host code, but not for browser or webview bundles because it reads session files and validates paths with Node filesystem APIs.
+
 ### Project session context evidence
 
 Build a provider-neutral snapshot of what an assistant has "seen" in a session — layered evidence sources, context pressure, and observed capabilities. Read it through any session provider, or build it directly from a canonical `SessionEvent[]`.

package/dist/accountManager.d.ts

@@ -0,0 +1,52 @@
+import { type AccountProviderId, type SavedAccountProfile } from './accountRegistry';
+import { type AccountEntry, type AccountManagerResult } from './accounts';
+export interface BeginAccountLoginSuccess {
+    success: true;
+    loginId: string;
+    alreadyComplete?: boolean;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    configDir?: string;
+}
+export interface BeginAccountLoginFailure {
+    success: false;
+    error: string;
+}
+export type BeginAccountLoginResult = BeginAccountLoginSuccess | BeginAccountLoginFailure;
+export type AccountLoginState = 'pending' | 'authenticated' | 'failed';
+export interface AccountLoginStatus {
+    state: AccountLoginState;
+    email?: string;
+    error?: string;
+}
+export interface FinalizeAccountLoginOptions {
+    activate?: boolean;
+}
+export interface AccountLoginCommand {
+    command: string;
+    args: string[];
+}
+export interface SpawnAccountLoginOptions extends FinalizeAccountLoginOptions {
+    onStatus?: (status: AccountLoginStatus) => void;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    stdio?: 'inherit' | 'pipe';
+    loginCommand?: AccountLoginCommand;
+}
+export interface ListAllAccountsResult {
+    claude: AccountEntry[];
+    codex: SavedAccountProfile[];
+    activeByProvider: Record<AccountProviderId, string | null>;
+}
+export declare function resolveClaudeLoginCommand(opts?: {
+    loginCommand?: AccountLoginCommand;
+}): AccountLoginCommand;
+export declare function beginAccountLogin(provider: AccountProviderId, label: string, opts?: {
+    loginCommand?: AccountLoginCommand;
+}): BeginAccountLoginResult;
+export declare function getAccountLoginStatus(provider: AccountProviderId, loginId: string): AccountLoginStatus;
+export declare function finalizeAccountLogin(provider: AccountProviderId, loginId: string, opts?: FinalizeAccountLoginOptions): AccountManagerResult;
+export declare function spawnAccountLogin(provider: AccountProviderId, label: string, opts?: SpawnAccountLoginOptions): Promise<AccountManagerResult>;
+export declare function switchAccount(provider: AccountProviderId, id: string): AccountManagerResult;
+export declare function listAllAccounts(): ListAllAccountsResult;

package/dist/accountManager.js

@@ -0,0 +1,344 @@
+"use strict";
+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.resolveClaudeLoginCommand = resolveClaudeLoginCommand;
+exports.beginAccountLogin = beginAccountLogin;
+exports.getAccountLoginStatus = getAccountLoginStatus;
+exports.finalizeAccountLogin = finalizeAccountLogin;
+exports.spawnAccountLogin = spawnAccountLogin;
+exports.switchAccount = switchAccount;
+exports.listAllAccounts = listAllAccounts;
+const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const accountRegistry_1 = require("./accountRegistry");
+const accounts_1 = require("./accounts");
+const claudeProfiles_1 = require("./claudeProfiles");
+const credentialIO_1 = require("./credentialIO");
+const codexProfiles_1 = require("./codexProfiles");
+function getClaudeProfileDir(loginId) {
+    return path.dirname((0, claudeProfiles_1.getClaudeProfileHome)(loginId));
+}
+function getPendingClaudeProfilePath(loginId) {
+    return path.join(getClaudeProfileDir(loginId), 'profile.json');
+}
+function atomicWriteJson(filePath, data, mode = 0o600) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const tmp = `${filePath}.tmp`;
+    const json = JSON.stringify(data, null, 2);
+    JSON.parse(json);
+    try {
+        fs.writeFileSync(tmp, json, { encoding: 'utf8', mode });
+        fs.renameSync(tmp, filePath);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch { /* nothing to clean up */ }
+        throw err;
+    }
+}
+function readPendingClaudeProfile(loginId) {
+    try {
+        return JSON.parse(fs.readFileSync(getPendingClaudeProfilePath(loginId), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function writePendingClaudeProfile(loginId, pending) {
+    (0, claudeProfiles_1.ensureClaudeProfileDirs)(loginId);
+    atomicWriteJson(getPendingClaudeProfilePath(loginId), pending);
+}
+function removePendingClaudeProfile(loginId) {
+    try {
+        fs.rmSync(getPendingClaudeProfilePath(loginId), { force: true });
+    }
+    catch { /* best effort */ }
+}
+function getClaudeCredentialsBackupPath(uuid) {
+    return path.join((0, accountRegistry_1.getAccountsDir)(), 'credentials', `${uuid}.credentials.json`);
+}
+function getClaudeConfigBackupPath(uuid) {
+    return path.join((0, accountRegistry_1.getAccountsDir)(), 'configs', `${uuid}.config.json`);
+}
+function readClaudeOauthAccount(home) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(home, '.claude.json'), 'utf8'));
+        return raw?.oauthAccount ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function copyClaudeProfileToCanonicalHome(sourceHome, accountUuid, credentials) {
+    const canonicalHome = (0, claudeProfiles_1.getClaudeProfileHome)(accountUuid);
+    fs.mkdirSync(canonicalHome, { recursive: true, mode: 0o700 });
+    if (path.resolve(sourceHome) !== path.resolve(canonicalHome)) {
+        try {
+            fs.cpSync(sourceHome, canonicalHome, { recursive: true, force: true });
+        }
+        catch {
+            // The credential and identity files are re-written below when possible.
+        }
+    }
+    const sourceConfig = path.join(sourceHome, '.claude.json');
+    if (fs.existsSync(sourceConfig)) {
+        fs.copyFileSync(sourceConfig, path.join(canonicalHome, '.claude.json'));
+    }
+    (0, credentialIO_1.writeActiveCredentials)(credentials, canonicalHome);
+}
+function parseClaudeLoginArgs(raw) {
+    const trimmed = raw?.trim();
+    return trimmed ? trimmed.split(/\s+/) : null;
+}
+function resolveClaudeLoginCommand(opts = {}) {
+    if (opts.loginCommand)
+        return opts.loginCommand;
+    return {
+        command: 'claude',
+        args: parseClaudeLoginArgs(process.env.SIDEKICK_CLAUDE_LOGIN_ARGS) ?? ['/login'],
+    };
+}
+function beginAccountLogin(provider, label, opts = {}) {
+    if (provider === 'codex') {
+        const prepared = (0, codexProfiles_1.prepareCodexAccount)(label);
+        if (!prepared.success || !prepared.profileId || !prepared.codexHome) {
+            return { success: false, error: prepared.error ?? 'Could not prepare Codex account login.' };
+        }
+        if (prepared.needsLogin === false) {
+            return {
+                success: true,
+                loginId: prepared.profileId,
+                alreadyComplete: true,
+                configDir: prepared.codexHome,
+            };
+        }
+        const loginCommand = opts.loginCommand ?? { command: 'codex', args: ['login'] };
+        return {
+            success: true,
+            loginId: prepared.profileId,
+            command: loginCommand.command,
+            args: loginCommand.args,
+            env: { CODEX_HOME: prepared.codexHome },
+            configDir: prepared.codexHome,
+        };
+    }
+    const trimmedLabel = label.trim();
+    if (!trimmedLabel) {
+        return { success: false, error: 'Claude accounts require a non-empty label.' };
+    }
+    const loginId = (0, crypto_1.randomUUID)();
+    const home = (0, claudeProfiles_1.getClaudeProfileHome)(loginId);
+    writePendingClaudeProfile(loginId, {
+        label: trimmedLabel,
+        addedAt: new Date().toISOString(),
+    });
+    const loginCommand = resolveClaudeLoginCommand(opts);
+    return {
+        success: true,
+        loginId,
+        command: loginCommand.command,
+        args: loginCommand.args,
+        env: { CLAUDE_CONFIG_DIR: home },
+        configDir: home,
+    };
+}
+function getAccountLoginStatus(provider, loginId) {
+    if (provider === 'codex') {
+        const codexHome = (0, codexProfiles_1.getCodexProfileHome)(loginId);
+        if (!(0, codexProfiles_1.isCodexProfileAuthenticated)(codexHome)) {
+            return { state: 'pending' };
+        }
+        const metadata = (0, codexProfiles_1.readCodexAccountMetadata)(codexHome);
+        return {
+            state: 'authenticated',
+            email: metadata.email,
+        };
+    }
+    const home = (0, claudeProfiles_1.getClaudeProfileHome)(loginId);
+    const identity = (0, claudeProfiles_1.readClaudeProfileIdentity)(home);
+    return (0, claudeProfiles_1.isClaudeProfileAuthenticated)(home)
+        ? { state: 'authenticated', email: identity?.email }
+        : { state: 'pending' };
+}
+function finalizeAccountLogin(provider, loginId, opts = {}) {
+    if (provider === 'codex') {
+        return (0, codexProfiles_1.finalizeCodexAccount)(loginId, opts);
+    }
+    const home = (0, claudeProfiles_1.getClaudeProfileHome)(loginId);
+    const identity = (0, claudeProfiles_1.readClaudeProfileIdentity)(home);
+    if (!identity) {
+        return { success: false, error: 'Claude profile is not authenticated yet.' };
+    }
+    const credentials = (0, credentialIO_1.readActiveCredentials)(home);
+    if (!credentials) {
+        return { success: false, error: 'Could not read Claude profile credentials.' };
+    }
+    const oauthAccount = readClaudeOauthAccount(home);
+    if (!oauthAccount) {
+        return { success: false, error: 'Could not read Claude profile config.' };
+    }
+    const pending = readPendingClaudeProfile(loginId);
+    atomicWriteJson(getClaudeCredentialsBackupPath(identity.uuid), credentials);
+    atomicWriteJson(getClaudeConfigBackupPath(identity.uuid), oauthAccount);
+    copyClaudeProfileToCanonicalHome(home, identity.uuid, credentials);
+    (0, accountRegistry_1.upsertSavedAccountProfile)({
+        id: identity.uuid,
+        providerId: 'claude-code',
+        providerAccountId: identity.uuid,
+        email: identity.email,
+        label: pending?.label,
+        addedAt: pending?.addedAt ?? new Date().toISOString(),
+        metadata: {
+            email: identity.email,
+        },
+    });
+    removePendingClaudeProfile(loginId);
+    if (loginId !== identity.uuid) {
+        removePendingClaudeProfile(identity.uuid);
+    }
+    if (opts.activate === false) {
+        return { success: true };
+    }
+    return (0, accounts_1.switchToAccount)(identity.uuid);
+}
+function emitStatus(opts, status) {
+    opts.onStatus?.(status);
+    return status;
+}
+function waitForNextPoll(ms, signal) {
+    if (ms <= 0)
+        return Promise.resolve(true);
+    if (signal?.aborted)
+        return Promise.resolve(false);
+    return new Promise(resolve => {
+        const timer = setTimeout(() => {
+            cleanup();
+            resolve(true);
+        }, ms);
+        const onAbort = () => {
+            cleanup();
+            resolve(false);
+        };
+        const cleanup = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+async function spawnAccountLogin(provider, label, opts = {}) {
+    if (opts.signal?.aborted) {
+        return { success: false, error: 'Account login aborted.' };
+    }
+    const begin = beginAccountLogin(provider, label, { loginCommand: opts.loginCommand });
+    if (!begin.success)
+        return { success: false, error: begin.error };
+    if (begin.alreadyComplete) {
+        return finalizeAccountLogin(provider, begin.loginId, { activate: opts.activate ?? true });
+    }
+    if (!begin.command) {
+        return { success: false, error: 'Account login command was not prepared.' };
+    }
+    let childExited = false;
+    let childExitCode = null;
+    const timeoutMs = opts.timeoutMs ?? 180_000;
+    const deadline = Date.now() + timeoutMs;
+    let child;
+    try {
+        child = (0, child_process_1.spawn)(begin.command, begin.args ?? [], {
+            env: { ...process.env, ...(begin.env ?? {}) },
+            stdio: opts.stdio ?? 'inherit',
+        });
+    }
+    catch (err) {
+        return { success: false, error: `Could not spawn account login: ${err}` };
+    }
+    child.on('exit', code => {
+        childExited = true;
+        childExitCode = code;
+    });
+    while (true) {
+        if (opts.signal?.aborted) {
+            child.kill();
+            emitStatus(opts, { state: 'failed', error: 'Account login aborted.' });
+            return { success: false, error: 'Account login aborted.' };
+        }
+        const status = emitStatus(opts, getAccountLoginStatus(provider, begin.loginId));
+        if (status.state === 'authenticated') {
+            return finalizeAccountLogin(provider, begin.loginId, { activate: opts.activate ?? true });
+        }
+        if (childExited) {
+            const finalStatus = emitStatus(opts, getAccountLoginStatus(provider, begin.loginId));
+            if (finalStatus.state === 'authenticated') {
+                return finalizeAccountLogin(provider, begin.loginId, { activate: opts.activate ?? true });
+            }
+            emitStatus(opts, {
+                state: 'failed',
+                error: `Account login exited before authentication completed${childExitCode === null ? '.' : ` (exit ${childExitCode}).`}`,
+            });
+            return { success: false, error: 'Account login did not complete.' };
+        }
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0) {
+            emitStatus(opts, { state: 'failed', error: 'Account login timed out.' });
+            return { success: false, error: 'Account login timed out.' };
+        }
+        const shouldContinue = await waitForNextPoll(Math.min(2_000, remainingMs), opts.signal);
+        if (!shouldContinue) {
+            child.kill();
+            emitStatus(opts, { state: 'failed', error: 'Account login aborted.' });
+            return { success: false, error: 'Account login aborted.' };
+        }
+    }
+}
+function switchAccount(provider, id) {
+    return provider === 'codex'
+        ? (0, codexProfiles_1.switchToCodexAccount)(id)
+        : (0, accounts_1.switchToAccount)(id);
+}
+function listAllAccounts() {
+    return {
+        claude: (0, accounts_1.listAccounts)(),
+        codex: (0, codexProfiles_1.listCodexAccounts)(),
+        activeByProvider: (0, accountRegistry_1.readSavedAccountRegistry)()?.activeByProvider ?? {
+            'claude-code': null,
+            codex: null,
+        },
+    };
+}

package/dist/accounts.d.ts

@@ -32,6 +32,9 @@ export declare function writeAccountRegistry(registry: AccountRegistry): void;
 export declare function readActiveClaudeAccount(): ActiveAccountInfo | null;
 export declare function addCurrentAccount(label?: string): AccountManagerResult;
 export declare function switchToAccount(uuid: string): AccountManagerResult;
+export declare function resolveActiveClaudeHome(): string;
+export declare function applyActiveClaudeToLiveHome(): AccountManagerResult;
+export declare function reconcileClaudeAuthState(): void;
 export declare function removeAccount(uuid: string): AccountManagerResult;
 export declare function listAccounts(): AccountEntry[];
 export declare function getActiveAccount(): AccountEntry | null;