sideby 0.3.0 → 0.4.0

package/dist/src/families/codex/rate-limits.js

@@ -0,0 +1,92 @@
+// Codex `rate_limits` in rollout `token_count` events: the windows the Quota reader and the handoff hook share.
+// The hook runs on every tool call, so this module imports only Node built-ins (spec §3.17).
+import { open } from 'node:fs/promises';
+export const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+export const isNum = (v) => typeof v === 'number' && Number.isFinite(v);
+const MAX_RESETS_AT_SECONDS = 1e11;
+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(),
+    };
+}
+/** The windows of one `token_count` payload, or null when its `rate_limits` is missing or malformed. */
+export 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 } : {}) };
+}
+/** How much of a rollout's end the hook reads: `token_count` events come at least once per turn. */
+const TAIL_BYTES = 256 * 1024;
+/**
+ * The windows of the last well-formed `rate_limits` in the rollout's last 256 KB, or null. A line cut by the read
+ * window or still being written is skipped. Codex writes `rate_limits` after caching them, so they may lag.
+ */
+export async function lastRateLimits(file) {
+    let text;
+    try {
+        const fh = await open(file, 'r');
+        try {
+            const { size } = await fh.stat();
+            const start = Math.max(0, size - TAIL_BYTES);
+            const buf = Buffer.alloc(size - start);
+            await fh.read(buf, 0, buf.length, start);
+            text = buf.toString('utf8');
+            if (start > 0)
+                text = text.slice(text.indexOf('\n') + 1);
+        }
+        finally {
+            await fh.close();
+        }
+    }
+    catch {
+        return null;
+    }
+    const lines = text.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i];
+        if (!line.includes('rate_limits'))
+            continue;
+        let o;
+        try {
+            o = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!isObj(o) || !isObj(o.payload) || o.payload.type !== 'token_count')
+            continue;
+        const rl = rateLimits(o.payload);
+        if (rl)
+            return rl.windows;
+    }
+    return null;
+}

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

@@ -1,5 +1,6 @@
 import { FileMemo, type FileStats } from '../../core/file-memo.ts';
 import type { QuotaResult, QuotaWindow, UsageResult } from '../../types.ts';
+export { windowLabel } from './rate-limits.ts';
 export declare const MAX_QUOTA_FILES = 20;
 export interface RolloutFile {
     path: string;
@@ -8,7 +9,6 @@ export interface RolloutFile {
 }
 /** 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: {
@@ -64,4 +64,3 @@ export declare const codexUsageMemo: FileMemo<FileUsage>;
  * 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

@@ -8,15 +8,10 @@ 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';
+import { isNum, isObj, rateLimits } from './rate-limits.js';
+export { windowLabel } from './rate-limits.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');
@@ -75,45 +70,6 @@ async function* tokenCounts(file, read = { failed: false }) {
         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;
@@ -127,7 +83,7 @@ async function fileLimits(file) {
     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();
+export const codexQuotaMemo = new FileMemo({ name: 'codex-quota', version: 1 });
 /** 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);
@@ -231,7 +187,7 @@ async function fileUsage(file) {
     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();
+export const codexUsageMemo = new FileMemo({ name: 'codex-usage', version: 1 });
 /**
  * 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

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

@@ -0,0 +1,16 @@
+import { FileMemo } from '../../core/file-memo.ts';
+import type { Account, ReadContext, TuningResult } from '../../types.ts';
+/** What one rollout contributes: per `token_count` the context size, and each compaction's before and after. */
+interface Summary {
+    /** `[ts, model, ctx, window]` */
+    turns: [number, string, number, number][];
+    /** `[ts, model, pre, post]` */
+    compactions: [number, string, number, number][];
+    failed: boolean;
+}
+/** Per-rollout summaries per Account directory; a rollout is parsed again only after it changed. */
+export declare const codexTuningMemo: FileMemo<Summary>;
+/** The Account's configured threshold, or null for the Host default. Takes one top-level key; nothing else is kept. */
+export declare function readCompactLimit(dir: string): Promise<number | null>;
+export declare function readCodexTuning(account: Account, ctx: ReadContext): Promise<TuningResult>;
+export {};

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

@@ -0,0 +1,145 @@
+// Context tuning for a Codex Account (spec §3.18): observation only. The default Compaction Threshold and its
+// scope have no first-hand source, so this shows how large the context was when Codex compacted, never a
+// suggestion. The one Host config value read is `model_auto_compact_token_limit` from the Account's `config.toml`.
+import { createReadStream } from 'node:fs';
+import { readFile, 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 { getOrCreate, tuningResult, } from '../../core/tuning.js';
+import { listRollouts } from './rollout.js';
+const DAY_MS = 86_400_000;
+const CONFIG_MAX_BYTES = 1_000_000;
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : 0);
+async function parseFile(file, since) {
+    const out = { turns: [], compactions: [], failed: false };
+    let model = '';
+    let last = 0;
+    let pending = null;
+    try {
+        const rl = createInterface({ input: createReadStream(file), crlfDelay: Number.POSITIVE_INFINITY });
+        for await (const line of rl) {
+            if (!line.includes('token_count') && !line.includes('"compacted"') && !line.includes('turn_context'))
+                continue;
+            let row;
+            try {
+                row = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (!isObj(row))
+                continue;
+            const payload = isObj(row.payload) ? row.payload : {};
+            const ts = typeof row.timestamp === 'string' ? Date.parse(row.timestamp) : Number.NaN;
+            if (row.type === 'turn_context') {
+                if (typeof payload.model === 'string' && payload.model)
+                    model = payload.model;
+            }
+            else if (row.type === 'compacted') {
+                if (Number.isFinite(ts) && last > 0)
+                    pending = { ts, model, pre: last };
+            }
+            else if (row.type === 'event_msg' && payload.type === 'token_count') {
+                const info = isObj(payload.info) ? payload.info : null;
+                const usage = info && isObj(info.last_token_usage) ? info.last_token_usage : null;
+                const ctx = usage ? num(usage.input_tokens) : 0;
+                if (!ctx || !Number.isFinite(ts))
+                    continue;
+                last = ctx;
+                if (pending) {
+                    if (pending.ts >= since && pending.model)
+                        out.compactions.push([pending.ts, pending.model, pending.pre, ctx]);
+                    pending = null;
+                }
+                if (ts >= since && model)
+                    out.turns.push([ts, model, ctx, num(info?.model_context_window)]);
+            }
+        }
+    }
+    catch {
+        out.failed = true;
+    }
+    return out;
+}
+/** Per-rollout summaries per Account directory; a rollout is parsed again only after it changed. */
+export const codexTuningMemo = new FileMemo({ name: 'codex-tuning', version: 1 });
+/** The Account's configured threshold, or null for the Host default. Takes one top-level key; nothing else is kept. */
+export async function readCompactLimit(dir) {
+    try {
+        const file = join(dir, 'config.toml');
+        const st = await stat(file);
+        if (!st.isFile() || st.size > CONFIG_MAX_BYTES)
+            return null;
+        for (const raw of (await readFile(file, 'utf8')).split('\n')) {
+            const line = raw.trim();
+            if (line.startsWith('['))
+                return null; // a table starts: no top-level key is left
+            const m = /^model_auto_compact_token_limit\s*=\s*([0-9_]+)\s*(#.*)?$/.exec(line);
+            if (m) {
+                const n = Number((m[1] ?? '').replaceAll('_', ''));
+                return Number.isFinite(n) && n > 0 ? n : null;
+            }
+        }
+    }
+    catch {
+        // unreadable config: the Host default
+    }
+    return null;
+}
+export async function readCodexTuning(account, ctx) {
+    const now = ctx.now.getTime();
+    const since = now - USAGE_DAYS * DAY_MS;
+    const files = (await listRollouts(account.dir)).filter((f) => f.mtimeMs >= since);
+    if (!files.length)
+        return {
+            status: 'unavailable',
+            reason: 'no-session',
+            detail: `no Codex session in the last ${USAGE_DAYS} days`,
+        };
+    const memo = codexTuningMemo.pass(account.dir);
+    const byModel = new Map();
+    const entry = (model) => getOrCreate(byModel, model, () => ({
+        sessions: [],
+        compactions: [],
+        window: 0,
+        maxCtx: 0,
+    }));
+    for (const f of files) {
+        const s = await memo.get(f.path, f.stats, () => parseFile(f.path, since), (v) => !v.failed);
+        const perModel = new Map();
+        for (const [ts, model, c, window] of s.turns) {
+            if (ts > now || ts < since)
+                continue;
+            const e = entry(model);
+            e.window = Math.max(e.window, window);
+            e.maxCtx = Math.max(e.maxCtx, c);
+            const list = getOrCreate(perModel, model, () => []);
+            list.push({ ts, ctx: c, out: 0, write5m: 0, write1h: 0 });
+        }
+        for (const [model, turns] of perModel)
+            entry(model).sessions.push(turns);
+        for (const [ts, model, pre, post] of s.compactions) {
+            if (ts > now || ts < since)
+                continue;
+            entry(model).compactions.push({ ts, trigger: 'unknown', pre, post });
+        }
+    }
+    memo.done();
+    if (!byModel.size)
+        return {
+            status: 'unavailable',
+            reason: 'no-session',
+            detail: `no Codex token counts in the last ${USAGE_DAYS} days`,
+        };
+    const configured = await readCompactLimit(account.dir);
+    const records = [...byModel].map(([model, e]) => ({
+        model,
+        sessions: e.sessions,
+        compactions: e.compactions,
+        contextWindow: e.window || e.maxCtx,
+    }));
+    return tuningResult(USAGE_DAYS, records, { configured, known: () => false, mayRecommend: false });
+}

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

@@ -0,0 +1,5 @@
+import type { Account } from '../../types.ts';
+export declare function grokBrief(account: Account, session: {
+    id?: string;
+    transcriptPath?: string;
+}): Promise<string | undefined>;

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

@@ -0,0 +1,74 @@
+// A Brief from a Grok Build session (`sessions/<encoded cwd>/<id>/chat_history.jsonl`), for when the session hit its
+// limit before writing one. Grok's hook input carries the session id but no transcript path.
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { DigestBuilder, formatDigest } from '../shared/brief.js';
+const EDIT_TOOL = /edit|write|replace|patch/i;
+async function findSession(dir, id) {
+    try {
+        for (const d of await readdir(join(dir, 'sessions'), { withFileTypes: true })) {
+            if (!d.isDirectory())
+                continue;
+            const p = join(dir, 'sessions', d.name, id, 'chat_history.jsonl');
+            try {
+                await stat(p);
+                return p;
+            }
+            catch {
+                // not under this directory
+            }
+        }
+    }
+    catch {
+        // no sessions yet
+    }
+    return undefined;
+}
+export async function grokBrief(account, session) {
+    const file = session.transcriptPath ?? (session.id ? await findSession(account.dir, session.id) : undefined);
+    if (!file)
+        return undefined;
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const b = new DigestBuilder();
+    for (const line of text.split('\n')) {
+        let o;
+        try {
+            o = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (o.type === 'user' && Array.isArray(o.content)) {
+            for (const c of o.content)
+                if (c?.type === 'text' && typeof c.text === 'string')
+                    b.user(c.text);
+        }
+        else if (o.type === 'assistant') {
+            if (typeof o.content === 'string')
+                b.assistant(o.content);
+            for (const call of Array.isArray(o.tool_calls)
+                ? o.tool_calls
+                : []) {
+                if (typeof call?.name !== 'string' ||
+                    !EDIT_TOOL.test(call.name) ||
+                    typeof call.arguments !== 'string')
+                    continue;
+                try {
+                    const args = JSON.parse(call.arguments);
+                    b.file(args.path ?? args.file_path ?? args.target_file);
+                }
+                catch {
+                    // arguments not JSON
+                }
+            }
+        }
+    }
+    const d = b.result();
+    return d ? formatDigest(d) : undefined;
+}

package/dist/src/families/grok/handoff-hook.d.ts

@@ -0,0 +1,4 @@
+import { type HookReader } from '../../handoff/reader.ts';
+/** Substrings that mean the usage pool or credits are used up. `StopFailure.error` has no class of its own for it. */
+export declare const GROK_USED_UP: string[];
+export declare const grokHookReader: HookReader;

package/dist/src/families/grok/handoff-hook.js

@@ -0,0 +1,26 @@
+// Grok Build for the handoff hook (spec §3.17): no public Quota, so only a turn that failed at the limit starts a
+// Handoff. Leaf module. The wording comes from the grok 1.0.50 binary; check it again when Grok changes.
+import { field } from '../../handoff/reader.js';
+/** Substrings that mean the usage pool or credits are used up. `StopFailure.error` has no class of its own for it. */
+export const GROK_USED_UP = [
+    'You hit your weekly limit',
+    'You hit your free usage limit',
+    'reached your free Grok Build usage limit',
+    'usage limit reached',
+    'out of credits',
+    'usage balance exhausted',
+    'spending cap',
+    'credit limit for your plan',
+    'free-usage-exhausted',
+    'status 402',
+];
+export const grokHookReader = {
+    limitHit(input) {
+        if (field(input, 'subagentType'))
+            return false;
+        // `status 403` is not listed: alone it may be a refused request, and next to a used-up message that message
+        // matches by itself. A plain "rate limit … try again later" is transient and matches nothing here.
+        const text = `${field(input, 'errorDetails') ?? ''}\n${field(input, 'lastAssistantMessage') ?? ''}`;
+        return GROK_USED_UP.some((s) => text.includes(s));
+    },
+};

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

@@ -0,0 +1,47 @@
+import type { Env, FamilyHandoff, QuotaSetup } from '../../types.ts';
+import { type ArgRules } from '../shared/handoff-args.ts';
+/** From `grok --help`. */
+export declare const GROK_ARGS: ArgRules;
+export declare const ETC_GROK = "/etc/grok";
+export declare const HOOK_FILE = "sideby-handoff.json";
+/** The text of Grok's config layers that decide the sandbox, leader and hook policy; missing files are null. */
+export interface GrokLayers {
+    etcRequirements: string | null;
+    homeRequirements: string | null;
+    config: string | null;
+    homeManaged: string | null;
+    etcManaged: string | null;
+}
+/**
+ * The effective sandbox profile, leader setting and managed-hooks pin, in Grok's precedence (spec §3.17):
+ * requirements (`/etc` over `$GROK_HOME`, a pin) > command line > environment > `config.toml` > managed config
+ * (`$GROK_HOME` over `/etc`) > the default `off`.
+ */
+export declare function grokPolicy(layers: GrokLayers, args: readonly string[], env: Env): {
+    profile: string;
+    leader: boolean;
+    managedHooksOnly: boolean;
+};
+export declare function grokEligibility(policy: ReturnType<typeof grokPolicy>, args: readonly string[], home: string): {
+    args: string[];
+    start: boolean;
+    receive: boolean;
+    reason: string;
+} | {
+    args?: undefined;
+    start: boolean;
+    receive: boolean;
+    reason: string;
+} | {
+    args: string[];
+    start: boolean;
+    receive: boolean;
+} | {
+    args?: undefined;
+    start: boolean;
+    receive: boolean;
+};
+/** The whole file setup writes; teardown removes it only while it is still exactly this. */
+export declare function grokHookFileText(): string;
+export declare const grokHookSetup: QuotaSetup;
+export declare const grokHandoff: FamilyHandoff;