sideby 0.0.0-stage → 0.2.1

package/dist/src/families/claude/usage.js

@@ -0,0 +1,146 @@
+// Usage for a Claude Code Account, counted from its own session logs (`<dir>/projects/**/*.jsonl`).
+// One assistant message can be logged on several lines; the last line per `message.id` wins. Each file's parse is
+// remembered until the file changes (core/file-memo.ts), so a refresh reads only the logs that grew.
+import { createReadStream } from 'node:fs';
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { FileMemo } from '../../core/file-memo.js';
+import { USAGE_DAYS } from '../../core/quota-levels.js';
+import { dailyBuckets } from '../../core/usage-days.js';
+const DAY_MS = 86_400_000;
+async function listJsonl(dir, out = []) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        const p = join(dir, e.name);
+        // Dirent types do not follow symlinks, so a linked directory can never loop the walk.
+        if (e.isDirectory())
+            await listJsonl(p, out);
+        else if (e.isFile() && e.name.endsWith('.jsonl'))
+            out.push(p);
+    }
+    return out;
+}
+const count = (v) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : 0);
+async function parseFile(file) {
+    const out = { lines: 0, parsed: 0, rows: [], failed: false };
+    try {
+        const rl = createInterface({ input: createReadStream(file), crlfDelay: Number.POSITIVE_INFINITY });
+        for await (const line of rl) {
+            if (!line.trim())
+                continue;
+            out.lines++;
+            let row;
+            try {
+                row = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            out.parsed++;
+            if (row?.type !== 'assistant')
+                continue;
+            const usage = row.message?.usage;
+            if (typeof usage !== 'object' || usage === null)
+                continue;
+            const id = row.message?.id;
+            const key = typeof id === 'string'
+                ? id
+                : typeof row.requestId === 'string'
+                    ? `request:${row.requestId}`
+                    : `${file}:${out.lines}`;
+            out.rows.push([
+                key,
+                {
+                    timestamp: typeof row.timestamp === 'string' ? Date.parse(row.timestamp) : Number.NaN,
+                    session: typeof row.sessionId === 'string' ? row.sessionId : file,
+                    input: count(usage.input_tokens),
+                    output: count(usage.output_tokens),
+                    cacheRead: count(usage.cache_read_input_tokens),
+                    cacheWrite: count(usage.cache_creation_input_tokens),
+                },
+            ]);
+        }
+    }
+    catch {
+        // An unreadable file is skipped; the others still count.
+        out.failed = true;
+    }
+    return out;
+}
+/** Parsed session logs per Account directory; a file is parsed again only after it changed. */
+export const claudeUsageMemo = new FileMemo();
+export async function readClaudeUsage(account, ctx) {
+    const files = await listJsonl(join(account.dir, 'projects'));
+    if (!files.length)
+        return {
+            status: 'unavailable',
+            reason: 'no-session',
+            detail: 'no Claude Code sessions recorded for this account yet',
+        };
+    const now = ctx.now.getTime();
+    const since = now - USAGE_DAYS * DAY_MS;
+    const entries = new Map();
+    let lines = 0;
+    let parsed = 0;
+    const memo = claudeUsageMemo.pass(account.dir);
+    for (const file of files) {
+        const st = await stat(file).catch(() => null);
+        if (!st || st.mtimeMs < since)
+            continue;
+        const p = await memo.get(file, st, () => parseFile(file), (v) => !v.failed);
+        lines += p.lines;
+        parsed += p.parsed;
+        for (const [key, entry] of p.rows) {
+            // Re-insert so the last occurrence wins.
+            entries.delete(key);
+            entries.set(key, entry);
+        }
+    }
+    memo.done();
+    if (lines > 0 && parsed === 0)
+        return {
+            status: 'unavailable',
+            reason: 'unrecognized',
+            detail: `session logs in the last ${USAGE_DAYS} days could not be parsed as JSON lines`,
+        };
+    const sessions = new Set();
+    const days = dailyBuckets(ctx.now);
+    let last = Number.NEGATIVE_INFINITY;
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cacheReadTokens = 0;
+    let cacheWriteTokens = 0;
+    for (const e of entries.values()) {
+        if (!Number.isFinite(e.timestamp) || e.timestamp > now)
+            continue;
+        if (e.timestamp > last)
+            last = e.timestamp;
+        if (e.timestamp < since)
+            continue;
+        sessions.add(e.session);
+        inputTokens += e.input;
+        outputTokens += e.output;
+        cacheReadTokens += e.cacheRead;
+        cacheWriteTokens += e.cacheWrite;
+        days.add(e.timestamp, e.input + e.output + e.cacheRead + e.cacheWrite);
+    }
+    return {
+        status: 'ok',
+        days: USAGE_DAYS,
+        sessions: sessions.size,
+        inputTokens,
+        outputTokens,
+        cacheReadTokens,
+        cacheWriteTokens,
+        totalTokens: inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens,
+        daily: days.daily,
+        ...(Number.isFinite(last) ? { lastActivityAt: new Date(last).toISOString() } : {}),
+    };
+}

package/dist/src/families/codex/index.d.ts

@@ -0,0 +1,5 @@
+import type { Account, FamilyDef, Plugin } from '../../types.ts';
+/** The email claim of `tokens.id_token` in auth.json; the token and every other claim are dropped. */
+export declare function codexIdentity(account: Account): Promise<import("../../types.ts").AccountIdentity | undefined>;
+export declare const codexFamily: FamilyDef;
+export declare const codexPlugin: Plugin;

package/dist/src/families/codex/index.js

@@ -0,0 +1,70 @@
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { identityFromJsonFile, identityOf, jwtEmail } from '../../core/identity.js';
+import { BUILTIN_LOGOS } from '../logos.js';
+import { nestedFileWrittenAt, resumeSubcommandSession } from '../shared/sessions.js';
+import { topLevelTomlString } from '../shared/toml.js';
+import { readCodexQuota, readCodexUsage } from './rollout.js';
+const FILE_STORE_KEY = 'cli_auth_credentials_store';
+async function readModel(account) {
+    try {
+        return topLevelTomlString(await readFile(join(account.dir, 'config.toml'), 'utf8'), 'model');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The email claim of `tokens.id_token` in auth.json; the token and every other claim are dropped. */
+export function codexIdentity(account) {
+    return identityFromJsonFile(join(account.dir, 'auth.json'), (data) => identityOf(jwtEmail(data?.tokens?.id_token)));
+}
+export const codexFamily = {
+    id: 'codex',
+    title: 'Codex',
+    logo: BUILTIN_LOGOS.codex,
+    bin: 'codex',
+    installUrl: 'https://github.com/openai/codex',
+    selectVar: 'CODEX_HOME',
+    layout: { main: '.codex', account: '.codex-<name>' },
+    hijackVars: ['OPENAI_API_KEY', 'OPENAI_BASE_URL', 'CODEX_API_BASE_URL'],
+    apiVars: ['OPENAI_BASE_URL', 'OPENAI_API_KEY'],
+    sharedItems: [
+        { path: 'AGENTS.md', mode: 'link' },
+        { path: 'hooks.json', mode: 'link' },
+        { path: 'plugins', mode: 'link' },
+        { path: 'rules', mode: 'link' },
+        { path: 'skills', mode: 'link' },
+        { path: 'config.toml', mode: 'local-if-api' },
+        { path: 'auth.json', mode: 'info', credential: true },
+    ],
+    login: {
+        args: ['login'],
+        hint: "Sign in with ChatGPT in the browser; the login is saved to this account's auth.json",
+    },
+    // A non-main Account keeps its login in its own auth.json instead of the shared OS keyring.
+    defaultArgs(account, userArgs) {
+        if (account.isMain || userArgs.some((a) => a.includes(FILE_STORE_KEY)))
+            return [];
+        return ['-c', `${FILE_STORE_KEY}="file"`];
+    },
+    async loginState(account) {
+        try {
+            return (await stat(join(account.dir, 'auth.json'))).isFile() ? 'logged-in' : 'unknown';
+        }
+        catch (err) {
+            return err.code === 'ENOENT' ? 'logged-out' : 'unknown';
+        }
+    },
+    model: readModel,
+    identity: codexIdentity,
+    readQuota: (account) => readCodexQuota(account.dir),
+    readUsage: (account, ctx) => readCodexUsage(account.dir, ctx.now),
+    resumedSession: resumeSubcommandSession,
+    sessionWrittenAt: (account, id) => nestedFileWrittenAt(join(account.dir, 'sessions'), `-${id}.jsonl`),
+};
+export const codexPlugin = {
+    name: 'codex',
+    register(api) {
+        api.family(codexFamily);
+    },
+};

package/dist/src/families/codex/rollout.d.ts

@@ -0,0 +1,67 @@
+import { FileMemo, type FileStats } from '../../core/file-memo.ts';
+import type { QuotaResult, QuotaWindow, UsageResult } from '../../types.ts';
+export declare const MAX_QUOTA_FILES = 20;
+export interface RolloutFile {
+    path: string;
+    mtimeMs: number;
+    stats: FileStats;
+}
+/** Every rollout file under `<dir>/sessions`, newest mtime first. */
+export declare function listRollouts(dir: string): Promise<RolloutFile[]>;
+export declare function windowLabel(minutes: number): string;
+interface FileLimits {
+    /** The file's newest well-formed `rate_limits` (the later line on a tie), or null. */
+    best: {
+        at: number;
+        windows: QuotaWindow[];
+        plan?: string;
+    } | null;
+    failed: boolean;
+}
+/** Parsed `rate_limits` per Account directory; a rollout is read again only after it changed. */
+export declare const codexQuotaMemo: FileMemo<FileLimits>;
+/** Newest well-formed `rate_limits` across the newest rollout files, by event timestamp. */
+export declare function readCodexQuota(dir: string): Promise<QuotaResult>;
+interface Totals {
+    input: number;
+    cached: number;
+    output: number;
+    cacheWrite: number;
+}
+/**
+ * What each event adds, by index. `total_token_usage` is cumulative per segment: every field, cached input
+ * included, only grows until the Host starts a new segment, where they all start again from zero. A subagent's
+ * file starts from its parent's running total. So the first event adds its total minus the starting baseline
+ * (that total minus the first turn's own usage, zero for an ordinary session), an event where any field went
+ * down starts a new segment and adds its whole total, and any other event adds its growth. Every field of every
+ * increment is therefore zero or more, and any run of events sums to exactly what it added.
+ */
+export declare function fileDeltas(events: {
+    total: Totals;
+    turn: Totals | null;
+}[]): Totals[];
+/** Tokens one whole rollout file adds: the sum of its fileDeltas. */
+export declare function fileTokens(events: {
+    total: Totals;
+    turn: Totals | null;
+}[]): Totals | null;
+interface FileUsage {
+    /** Time of every `token_count` event, with or without totals. */
+    times: number[];
+    events: {
+        at: number;
+        total: Totals;
+        turn: Totals | null;
+    }[];
+    deltas: Totals[];
+    failed: boolean;
+}
+/** Parsed token totals per Account directory; a rollout is read again only after it changed. */
+export declare const codexUsageMemo: FileMemo<FileUsage>;
+/**
+ * Token totals for events in the last `days` x 24 h, from rollout files modified in that window (mtime only
+ * picks which files to read). Each event counts its fileDeltas increment, so a long session resumed today
+ * adds only its recent turns. `daily` spreads the same increments over local days.
+ */
+export declare function readCodexUsage(dir: string, now: Date, days?: number): Promise<UsageResult>;
+export {};

package/dist/src/families/codex/rollout.js

@@ -0,0 +1,298 @@
+// Reads Codex Quota and Usage from the Account's local rollout files (spec §3.7, ADR-0003).
+// No network, no credentials: only `token_count` events the Host writes into `sessions/**/rollout-*.jsonl`.
+// Each file's parse is remembered until the file changes (core/file-memo.ts), so a refresh reads only new rollouts.
+import { createReadStream } from 'node:fs';
+import { readdir, stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { createInterface } from 'node:readline';
+import { FileMemo } from '../../core/file-memo.js';
+import { USAGE_DAYS } from '../../core/quota-levels.js';
+import { dailyBuckets } from '../../core/usage-days.js';
+export const MAX_QUOTA_FILES = 20;
+const ROLLOUT = /^rollout-.*\.jsonl$/;
+const MAX_RESETS_AT_SECONDS = 1e11;
+function isObj(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function isNum(v) {
+    return typeof v === 'number' && Number.isFinite(v);
+}
+/** Every rollout file under `<dir>/sessions`, newest mtime first. */
+export async function listRollouts(dir) {
+    const root = join(dir, 'sessions');
+    let entries;
+    try {
+        entries = await readdir(root, { recursive: true, withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const e of entries) {
+        if (!e.isFile() || !ROLLOUT.test(e.name))
+            continue;
+        const path = join(e.parentPath, e.name);
+        try {
+            const st = await stat(path);
+            out.push({ path, mtimeMs: st.mtimeMs, stats: st });
+        }
+        catch {
+            // removed while scanning
+        }
+    }
+    return out.sort((a, b) => b.mtimeMs - a.mtimeMs);
+}
+/**
+ * Yields parsed `token_count` payloads with their event time; bad and truncated lines are skipped. A read error
+ * ends the file early and sets `read.failed`, so a caller does not remember a partial parse.
+ */
+async function* tokenCounts(file, read = { failed: false }) {
+    const lines = createInterface({ input: createReadStream(file), crlfDelay: Number.POSITIVE_INFINITY });
+    try {
+        for await (const line of lines) {
+            if (!line.includes('token_count'))
+                continue;
+            let o;
+            try {
+                o = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (!isObj(o) || !isObj(o.payload) || o.payload.type !== 'token_count')
+                continue;
+            const at = typeof o.timestamp === 'string' ? Date.parse(o.timestamp) : Number.NaN;
+            if (!Number.isFinite(at))
+                continue;
+            yield { at, payload: o.payload };
+        }
+    }
+    catch {
+        // unreadable file: keep what was read
+        read.failed = true;
+    }
+    finally {
+        lines.close();
+    }
+}
+export function windowLabel(minutes) {
+    if (minutes === 300)
+        return '5h';
+    if (minutes === 10080)
+        return '7d';
+    return `${minutes}m`;
+}
+function quotaWindow(raw) {
+    if (!isObj(raw))
+        return null;
+    const { used_percent: used, window_minutes: minutes, resets_at: resets } = raw;
+    if (!isNum(used) || !isNum(minutes) || minutes <= 0)
+        return null;
+    // Seconds since the epoch; a millisecond value would land tens of thousands of years ahead.
+    if (!isNum(resets) || resets <= 0 || resets >= MAX_RESETS_AT_SECONDS)
+        return null;
+    return {
+        label: windowLabel(minutes),
+        windowMinutes: minutes,
+        usedPercent: used,
+        resetsAt: new Date(resets * 1000).toISOString(),
+    };
+}
+function rateLimits(payload) {
+    const rl = payload.rate_limits;
+    if (!isObj(rl))
+        return null;
+    const primary = quotaWindow(rl.primary);
+    if (!primary)
+        return null;
+    const windows = [primary];
+    if (rl.secondary !== null && rl.secondary !== undefined) {
+        const secondary = quotaWindow(rl.secondary);
+        if (!secondary)
+            return null;
+        windows.push(secondary);
+    }
+    return { windows, ...(typeof rl.plan_type === 'string' ? { plan: rl.plan_type } : {}) };
+}
+async function fileLimits(file) {
+    const read = { failed: false };
+    let best = null;
+    for await (const { at, payload } of tokenCounts(file, read)) {
+        if (best && at < best.at)
+            continue;
+        const rl = rateLimits(payload);
+        if (rl)
+            best = { at, ...rl };
+    }
+    return { best, failed: read.failed };
+}
+/** Parsed `rate_limits` per Account directory; a rollout is read again only after it changed. */
+export const codexQuotaMemo = new FileMemo();
+/** Newest well-formed `rate_limits` across the newest rollout files, by event timestamp. */
+export async function readCodexQuota(dir) {
+    const files = (await listRollouts(dir)).slice(0, MAX_QUOTA_FILES);
+    if (files.length === 0)
+        return { status: 'unavailable', reason: 'no-session', detail: 'no Codex session in this account yet' };
+    let best = null;
+    const memo = codexQuotaMemo.pass(dir);
+    for (const f of files) {
+        // Same pick as reading every line in this order: the newest event wins, a later one on a tie.
+        const fb = (await memo.get(f.path, f.stats, () => fileLimits(f.path), (v) => !v.failed)).best;
+        if (fb && (!best || fb.at >= best.at))
+            best = { ...fb, file: f.path };
+    }
+    memo.done();
+    if (!best)
+        return {
+            status: 'unavailable',
+            reason: 'unrecognized',
+            detail: `no rate_limits event in the newest ${files.length} rollout file(s)`,
+        };
+    return {
+        status: 'ok',
+        windows: best.windows,
+        observedAt: new Date(best.at).toISOString(),
+        source: relative(dir, best.file),
+        ...(best.plan ? { plan: best.plan } : {}),
+    };
+}
+function parseTotals(t) {
+    if (!isObj(t) || !isNum(t.input_tokens) || !isNum(t.output_tokens))
+        return null;
+    return {
+        input: t.input_tokens,
+        cached: isNum(t.cached_input_tokens) ? t.cached_input_tokens : 0,
+        output: t.output_tokens,
+        cacheWrite: isNum(t.cache_write_input_tokens) ? t.cache_write_input_tokens : 0,
+    };
+}
+/** Cumulative totals so far in the session, plus this turn's own usage when the event carries it. */
+function totals(payload) {
+    const info = payload.info;
+    if (!isObj(info))
+        return null;
+    const total = parseTotals(info.total_token_usage);
+    return total ? { total, turn: parseTotals(info.last_token_usage) } : null;
+}
+const ZERO = { input: 0, cached: 0, output: 0, cacheWrite: 0 };
+const FIELDS = ['input', 'cached', 'output', 'cacheWrite'];
+const size = (t) => t.input + t.output + t.cacheWrite;
+const plus = (a, b) => ({
+    input: a.input + b.input,
+    cached: a.cached + b.cached,
+    output: a.output + b.output,
+    cacheWrite: a.cacheWrite + b.cacheWrite,
+});
+const minus = (a, b) => ({
+    input: Math.max(0, a.input - b.input),
+    cached: Math.max(0, a.cached - b.cached),
+    output: Math.max(0, a.output - b.output),
+    cacheWrite: Math.max(0, a.cacheWrite - b.cacheWrite),
+});
+/** True when any counter went down: each one only grows within a segment. */
+const dropped = (now, prev) => FIELDS.some((k) => now[k] < prev[k]);
+/**
+ * What each event adds, by index. `total_token_usage` is cumulative per segment: every field, cached input
+ * included, only grows until the Host starts a new segment, where they all start again from zero. A subagent's
+ * file starts from its parent's running total. So the first event adds its total minus the starting baseline
+ * (that total minus the first turn's own usage, zero for an ordinary session), an event where any field went
+ * down starts a new segment and adds its whole total, and any other event adds its growth. Every field of every
+ * increment is therefore zero or more, and any run of events sums to exactly what it added.
+ */
+export function fileDeltas(events) {
+    if (events.length === 0)
+        return [];
+    const first = events[0];
+    const baseline = first.turn ? minus(first.total, first.turn) : ZERO;
+    const out = [minus(first.total, baseline)];
+    let prev = first.total;
+    for (const e of events.slice(1)) {
+        out.push(dropped(e.total, prev) ? minus(e.total, ZERO) : minus(e.total, prev));
+        prev = e.total;
+    }
+    return out;
+}
+/** Tokens one whole rollout file adds: the sum of its fileDeltas. */
+export function fileTokens(events) {
+    if (events.length === 0)
+        return null;
+    return fileDeltas(events).reduce(plus, ZERO);
+}
+async function fileUsage(file) {
+    const read = { failed: false };
+    const times = [];
+    const events = [];
+    for await (const { at, payload } of tokenCounts(file, read)) {
+        times.push(at);
+        const t = totals(payload);
+        if (t)
+            events.push({ at, ...t });
+    }
+    return { times, events, deltas: fileDeltas(events), failed: read.failed };
+}
+/** Parsed token totals per Account directory; a rollout is read again only after it changed. */
+export const codexUsageMemo = new FileMemo();
+/**
+ * Token totals for events in the last `days` x 24 h, from rollout files modified in that window (mtime only
+ * picks which files to read). Each event counts its fileDeltas increment, so a long session resumed today
+ * adds only its recent turns. `daily` spreads the same increments over local days.
+ */
+export async function readCodexUsage(dir, now, days = USAGE_DAYS) {
+    const end = now.getTime();
+    const since = end - days * 24 * 60 * 60 * 1000;
+    const files = (await listRollouts(dir)).filter((f) => f.mtimeMs >= since);
+    if (files.length === 0)
+        return {
+            status: 'unavailable',
+            reason: 'no-session',
+            detail: `no Codex session in the last ${days} days`,
+        };
+    let sessions = 0;
+    let sawTokenCount = false;
+    let sawTotals = false;
+    let last = Number.NEGATIVE_INFINITY;
+    const daily = dailyBuckets(now, days);
+    const sum = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 };
+    const memo = codexUsageMemo.pass(dir);
+    for (const f of files) {
+        const { times, events, deltas } = await memo.get(f.path, f.stats, () => fileUsage(f.path), (v) => !v.failed);
+        if (times.length)
+            sawTokenCount = true;
+        for (const at of times)
+            if (at <= end && at > last)
+                last = at;
+        if (events.length)
+            sawTotals = true;
+        let used = ZERO;
+        let inWindow = false;
+        for (const [i, e] of events.entries()) {
+            if (e.at < since || e.at > end)
+                continue;
+            inWindow = true;
+            used = plus(used, deltas[i]);
+            daily.add(e.at, size(deltas[i]));
+        }
+        if (!inWindow)
+            continue;
+        sessions++;
+        const cached = Math.min(used.cached, used.input);
+        sum.inputTokens += used.input - cached;
+        sum.cacheReadTokens += cached;
+        sum.outputTokens += used.output;
+        sum.cacheWriteTokens += used.cacheWrite;
+    }
+    memo.done();
+    if (sessions === 0)
+        return sawTokenCount && !sawTotals
+            ? { status: 'unavailable', reason: 'unrecognized', detail: 'token_count events have no usable totals' }
+            : { status: 'unavailable', reason: 'no-session', detail: `no Codex turn in the last ${days} days` };
+    return {
+        status: 'ok',
+        days,
+        sessions,
+        ...sum,
+        totalTokens: sum.inputTokens + sum.outputTokens + sum.cacheReadTokens + sum.cacheWriteTokens,
+        daily: daily.daily,
+        ...(Number.isFinite(last) ? { lastActivityAt: new Date(last).toISOString() } : {}),
+    };
+}

package/dist/src/families/grok/index.d.ts

@@ -0,0 +1,8 @@
+import type { Account, FamilyDef, Plugin } from '../../types.ts';
+/**
+ * The `email` of the single sign-in entry in auth.json (keyed by the auth server, such as `https://auth.x.ai::<id>`).
+ * Only that field is read; tokens and every other field are dropped. Several entries give no answer.
+ */
+export declare function grokIdentity(account: Account): Promise<import("../../types.ts").AccountIdentity | undefined>;
+export declare const grokFamily: FamilyDef;
+export declare const grokPlugin: Plugin;

package/dist/src/families/grok/index.js

@@ -0,0 +1,82 @@
+import { lstat, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { identityFromJsonFile, identityOf } from '../../core/identity.js';
+import { BUILTIN_LOGOS } from '../logos.js';
+import { groupedEntryWrittenAt, resumeFlagSession } from '../shared/sessions.js';
+import { topLevelTomlString } from '../shared/toml.js';
+// Grok's sandbox rejects these paths when they are symlinks; doctor quotes the Host's own words.
+const HOOKS_DIR_MESSAGE = 'Grok hooks directory has wrong type (expected real directory)';
+const REAL_FILE_MESSAGE = 'Grok hooks-paths registry has wrong type (expected real file)';
+const AUTH_MESSAGE = 'the policy lock file under ~/.grok-00x is not accessible';
+/** `model = "..."` before the first `[table]` of config.toml. */
+async function readModel(account) {
+    let text;
+    try {
+        text = await readFile(join(account.dir, 'config.toml'), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    return topLevelTomlString(text, 'model');
+}
+/**
+ * The `email` of the single sign-in entry in auth.json (keyed by the auth server, such as `https://auth.x.ai::<id>`).
+ * Only that field is read; tokens and every other field are dropped. Several entries give no answer.
+ */
+export function grokIdentity(account) {
+    return identityFromJsonFile(join(account.dir, 'auth.json'), (data) => {
+        if (typeof data !== 'object' || data === null || Array.isArray(data))
+            return undefined;
+        const entries = Object.values(data);
+        if (entries.length !== 1)
+            return undefined;
+        const entry = entries[0];
+        return typeof entry === 'object' && entry !== null
+            ? identityOf(entry.email)
+            : undefined;
+    });
+}
+export const grokFamily = {
+    id: 'grok',
+    title: 'Grok Build',
+    logo: BUILTIN_LOGOS.grok,
+    bin: 'grok',
+    installUrl: 'https://docs.x.ai/build/overview',
+    selectVar: 'GROK_HOME',
+    layout: { main: '.grok', account: '.grok-<name>' },
+    hijackVars: ['XAI_API_KEY', 'GROK_MODELS_BASE_URL'],
+    apiVars: ['GROK_MODELS_BASE_URL', 'XAI_API_KEY'],
+    sharedItems: [
+        { path: 'skills', mode: 'link' },
+        { path: 'installed-plugins', mode: 'link' },
+        { path: 'hooks', mode: 'copy', hostMessage: HOOKS_DIR_MESSAGE },
+        { path: 'hooks-paths', mode: 'copy', hostMessage: REAL_FILE_MESSAGE },
+        { path: 'trusted_folders.toml', mode: 'local', hostMessage: REAL_FILE_MESSAGE },
+        { path: 'config.toml', mode: 'local-if-api', noSymlink: true, hostMessage: REAL_FILE_MESSAGE },
+        { path: 'auth.json', mode: 'info', noSymlink: true, credential: true, hostMessage: AUTH_MESSAGE },
+    ],
+    login: {
+        args: ['login'],
+        hint: "Sign in to your xAI account in the browser; the login is saved to this account's auth.json",
+    },
+    async loginState(account) {
+        try {
+            const st = await lstat(join(account.dir, 'auth.json'));
+            return st.isFile() ? 'logged-in' : 'unknown';
+        }
+        catch (err) {
+            return err.code === 'ENOENT' ? 'logged-out' : 'unknown';
+        }
+    },
+    model: readModel,
+    identity: grokIdentity,
+    resumedSession: resumeFlagSession,
+    // One directory per session, grouped by working directory: sessions/<encoded cwd>/<id>/.
+    sessionWrittenAt: (account, id) => groupedEntryWrittenAt(join(account.dir, 'sessions'), id, 'dir'),
+};
+export const grokPlugin = {
+    name: 'grok',
+    register(api) {
+        api.family(grokFamily);
+    },
+};

package/dist/src/families/index.d.ts

@@ -0,0 +1,3 @@
+import type { BuiltinPlugin } from '../plugins/loader.ts';
+/** Built-in Plugins in load order. Families register here; `account-script` is off unless enabled. */
+export declare const BUILTIN_PLUGINS: BuiltinPlugin[];