sideby 0.16.0 → 0.17.0

package/dist/src/families/claude/quota-cache.js

@@ -1,6 +1,7 @@
 // The Claude Quota cache: one module owns where it lives, how the Account is named, and how it is written,
 // read and validated. The status line tap writes it on every refresh, so this module imports only leaf
 // modules and Node built-ins (never the Family index, the Runtime or core/accounts.ts).
+import { createHash } from 'node:crypto';
 import { mkdir, readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
@@ -8,6 +9,9 @@ import { ACCOUNT_NAME } from '../../core/account-name.js';
 import { writeFileAtomic } from '../../core/fs-safe.js';
 import { resolvePaths } from '../../core/paths.js';
 import { CLAUDE_ACCOUNT_PREFIX, CLAUDE_MAIN_DIR } from './layout.js';
+const MAX_SESSIONS = 32;
+const SESSION_DAYS = 8;
+const SESSION_ID = /^[A-Za-z0-9._-]{1,128}$/;
 const WINDOWS = [
     { key: 'five_hour', label: '5h', minutes: 300 },
     { key: 'seven_day', label: '7d', minutes: 10_080 },
@@ -32,7 +36,7 @@ export function accountNameFromEnv(env) {
     const name = base.slice(CLAUDE_ACCOUNT_PREFIX.length);
     return name !== 'main' && ACCOUNT_NAME.test(name) ? name : null;
 }
-/** Extracts the 5h and 7d windows from status line JSON; null when there is nothing usable. */
+/** Extracts the 5h and 7d windows and the session id from status line JSON; null when there is nothing usable. */
 export function parseRateLimits(input, observedAt) {
     let data;
     try {
@@ -62,7 +66,15 @@ export function parseRateLimits(input, observedAt) {
             resetsAt: new Date(resets * 1000).toISOString(),
         });
     }
-    return windows.length ? { version: 1, observedAt: observedAt.toISOString(), windows } : null;
+    if (!windows.length)
+        return null;
+    const id = data.session_id;
+    return {
+        version: 1,
+        observedAt: observedAt.toISOString(),
+        windows,
+        ...(typeof id === 'string' && SESSION_ID.test(id) ? { sessionId: id } : {}),
+    };
 }
 /** Two readings belong to one window when their resets are less than a quarter of the window apart. */
 function sameWindow(a, b) {
@@ -76,33 +88,56 @@ const order = (label) => {
     const i = WINDOWS.findIndex((w) => w.label === label);
     return i < 0 ? WINDOWS.length : i;
 };
+/** What a session reported, as a short hash: equal hashes mean the session has made no request since. */
+function windowsHash(windows) {
+    const key = windows.map((w) => [w.label, w.usedPercent, w.resetsAt]);
+    return createHash('sha256').update(JSON.stringify(key)).digest('hex').slice(0, 16);
+}
+/** The newest {@link MAX_SESSIONS} sessions seen in the last {@link SESSION_DAYS} days before `now`. */
+function pruneSessions(sessions, now) {
+    const oldest = Date.parse(now) - SESSION_DAYS * 86_400_000;
+    const kept = Object.entries(sessions)
+        .filter(([, s]) => Date.parse(s.seenAt) >= oldest)
+        .sort((a, b) => Date.parse(b[1].seenAt) - Date.parse(a[1].seenAt))
+        .slice(0, MAX_SESSIONS);
+    return Object.fromEntries(kept);
+}
 /**
- * Merges a status line reading into the cached windows. Each session reports the Quota of its own last request, so an
- * idle session of the same Account reports older numbers, sometimes of a window that has already reset: within one
- * window the higher use wins, otherwise the later reset; a window the reading lacks is kept. Null when the reading
- * only repeats older numbers, so nothing is written and `observedAt` keeps the time of the newer reading.
+ * Merges a status line reading into the cache (spec §3.7). Each session reports the Quota of its own last request, so
+ * an idle session of the same Account keeps repeating older numbers. A reading whose session reported exactly these
+ * windows before carries nothing new: null, so nothing is written. A reading that changed, or the first of a session,
+ * is a fresh request result and wins for every window it has, the vendor's resets included; a window it lacks is
+ * kept. A reading without a session id falls back to: within one window the higher use wins, otherwise the reading
+ * wins; null when that only repeats the cache.
  */
 export function mergeQuotaCache(cached, next) {
+    const { sessionId, ...reading } = next;
+    const before = cached?.windows ?? [];
+    const keepLacking = (windows) => {
+        for (const c of before)
+            if (!windows.some((w) => w.label === c.label))
+                windows.push(c);
+        return windows.sort((a, b) => order(a.label) - order(b.label));
+    };
+    if (sessionId) {
+        const hash = windowsHash(reading.windows);
+        if (cached?.sessions?.[sessionId]?.hash === hash)
+            return null;
+        const sessions = pruneSessions({ ...cached?.sessions, [sessionId]: { hash, seenAt: reading.observedAt } }, reading.observedAt);
+        return { ...reading, windows: keepLacking([...reading.windows]), sessions };
+    }
     let older = false;
-    const windows = next.windows.map((w) => {
-        const c = cached.find((x) => x.label === w.label);
-        if (!c)
-            return w;
-        const keep = sameWindow(c, w)
-            ? c.usedPercent > w.usedPercent
-            : Date.parse(c.resetsAt) > Date.parse(w.resetsAt);
+    const windows = keepLacking(reading.windows.map((w) => {
+        const c = before.find((x) => x.label === w.label);
+        const keep = !!c && sameWindow(c, w) && c.usedPercent > w.usedPercent;
         if (keep)
             older = true;
         return keep ? c : w;
-    });
-    for (const c of cached)
-        if (!windows.some((w) => w.label === c.label))
-            windows.push(c);
-    windows.sort((a, b) => order(a.label) - order(b.label));
-    const unchanged = windows.length === cached.length && windows.every((w) => cached.some((c) => sameReading(c, w)));
+    }));
+    const unchanged = windows.length === before.length && windows.every((w) => before.some((c) => sameReading(c, w)));
     if (older && unchanged)
         return null;
-    return { ...next, windows };
+    return { ...reading, windows, ...(cached?.sessions ? { sessions: cached.sessions } : {}) };
 }
 /** Writes the cache atomically; creates the private parent directory first (writeFileAtomic does not). */
 export async function writeQuotaCache(stateDir, name, cache) {
@@ -147,5 +182,21 @@ export async function readQuotaCache(stateDir, name) {
         !Number.isFinite(Date.parse(cache.observedAt)) ||
         !windows.length)
         return { status: 'unrecognized', detail: `${file} has no usable quota windows` };
-    return { status: 'ok', observedAt: cache.observedAt, windows };
+    const sessions = validSessions(cache.sessions);
+    return { status: 'ok', observedAt: cache.observedAt, windows, ...(sessions ? { sessions } : {}) };
+}
+/** The well-formed session entries of a cache file; undefined when it has none (older files). */
+function validSessions(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return undefined;
+    const out = {};
+    for (const [id, v] of Object.entries(raw)) {
+        const s = v;
+        if (SESSION_ID.test(id) &&
+            typeof s?.hash === 'string' &&
+            typeof s.seenAt === 'string' &&
+            Number.isFinite(Date.parse(s.seenAt)))
+            out[id] = { hash: s.hash, seenAt: s.seenAt };
+    }
+    return Object.keys(out).length ? out : undefined;
 }

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

@@ -31,6 +31,13 @@ export const codexFamily = {
     layout: { main: '.codex', account: '.codex-<name>' },
     hijackVars: ['OPENAI_API_KEY', 'OPENAI_BASE_URL', 'CODEX_API_BASE_URL'],
     apiVars: ['OPENAI_BASE_URL', 'OPENAI_API_KEY'],
+    secretVar: 'OPENAI_API_KEY',
+    // `exec` refuses to run outside a git repo unless this flag is set (Codex 0.163.0 --help:
+    // allow running outside a Git repository). The probe's cwd is a temp directory.
+    probe: { args: ['exec', '--skip-git-repo-check', 'Reply with OK'] },
+    // `-i, --image <FILE>...` takes several values (Codex 0.163.0 --help); AI Tasks pass `--image=<path>`, one value
+    // per flag, so the prompt after it stays a positional argument.
+    imageArg: '--image',
     sharedItems: [
         { path: 'AGENTS.md', mode: 'link' },
         { path: 'hooks.json', mode: 'link' },

package/dist/src/families/codex/login-key.d.ts

@@ -0,0 +1,8 @@
+import type { Account } from '../../types.ts';
+/**
+ * A hash of `chatgpt_account_id` (the workspace) and `chatgpt_user_id` under the auth claim of `tokens.id_token`,
+ * cut to 16 hex characters, only for comparing two Accounts while the Runtime groups a Same Login. The payload is
+ * decoded as for the email (core/identity.ts); the token, both ids and every other claim are dropped at once.
+ * Undefined on any problem: the Account then simply does not group.
+ */
+export declare function codexLoginKey(account: Account): Promise<string | undefined>;

package/dist/src/families/codex/login-key.js

@@ -0,0 +1,33 @@
+// Codex's Login Key (ADR-0028): which ChatGPT workspace and user an Account is signed in as, kept only as a hash.
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const AUTH_CLAIM = 'https://api.openai.com/auth';
+// The shapes Codex writes; anything else gives no key rather than a key built from an unexpected value.
+const ACCOUNT_ID = /^[A-Za-z0-9-]{8,64}$/;
+const USER_ID = /^user-[A-Za-z0-9]{8,64}$/;
+/**
+ * A hash of `chatgpt_account_id` (the workspace) and `chatgpt_user_id` under the auth claim of `tokens.id_token`,
+ * cut to 16 hex characters, only for comparing two Accounts while the Runtime groups a Same Login. The payload is
+ * decoded as for the email (core/identity.ts); the token, both ids and every other claim are dropped at once.
+ * Undefined on any problem: the Account then simply does not group.
+ */
+export async function codexLoginKey(account) {
+    try {
+        const token = JSON.parse(await readFile(join(account.dir, 'auth.json'), 'utf8'))?.tokens?.id_token;
+        if (typeof token !== 'string')
+            return undefined;
+        const parts = token.split('.');
+        if (parts.length !== 3 || !parts[1])
+            return undefined;
+        const auth = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'))?.[AUTH_CLAIM];
+        const ws = auth?.chatgpt_account_id;
+        const user = auth?.chatgpt_user_id;
+        if (typeof ws !== 'string' || !ACCOUNT_ID.test(ws) || typeof user !== 'string' || !USER_ID.test(user))
+            return undefined;
+        return createHash('sha256').update(`codex\0${ws}\0${user}`).digest('hex').slice(0, 16);
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -49,6 +49,9 @@ export const grokFamily = {
     layout: { main: '.grok', account: '.grok-<name>' },
     hijackVars: ['XAI_API_KEY', 'GROK_MODELS_BASE_URL'],
     apiVars: ['GROK_MODELS_BASE_URL', 'XAI_API_KEY'],
+    secretVar: 'XAI_API_KEY',
+    // `-p` is one non-interactive prompt (Grok Build 1.0.60 --help, 2026-10-17).
+    probe: { args: ['-p', 'Reply with OK'] },
     sharedItems: [
         { path: 'skills', mode: 'link' },
         { path: 'installed-plugins', mode: 'link' },

package/dist/src/families/login-keys.d.ts

@@ -0,0 +1,6 @@
+import type { Account } from '../types.ts';
+/**
+ * Family id → its Login Key reader. Must list exactly the Families of `LOGIN_KEY_FAMILIES` (core/same-login.ts);
+ * a test keeps the two in step.
+ */
+export declare const LOGIN_KEY_READERS: ReadonlyMap<string, (account: Account) => Promise<string | undefined>>;

package/dist/src/families/login-keys.js

@@ -0,0 +1,6 @@
+import { codexLoginKey } from './codex/login-key.js';
+/**
+ * Family id → its Login Key reader. Must list exactly the Families of `LOGIN_KEY_FAMILIES` (core/same-login.ts);
+ * a test keeps the two in step.
+ */
+export const LOGIN_KEY_READERS = new Map([['codex', codexLoginKey]]);

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

@@ -41,6 +41,10 @@ export const piFamily = {
         'OPENAI_BASE_URL',
     ],
     apiVars: ['ANTHROPIC_API_KEY', 'ANTHROPIC_BASE_URL', 'OPENAI_API_KEY', 'OPENAI_BASE_URL'],
+    // First key in the proxy.env template `new --api` writes. The OpenAI key is still set with `--var`.
+    secretVar: 'ANTHROPIC_API_KEY',
+    // `-p` is one non-interactive prompt (pi 1.3.0 --help, 2026-10-17).
+    probe: { args: ['-p', 'Reply with OK'] },
     sharedItems: [
         { path: 'AGENTS.md', mode: 'link' },
         { path: 'auth.json', mode: 'info', credential: true },

package/dist/src/panel/background.js

@@ -7,7 +7,7 @@ import { mkdir, open, readFile, rename, rm, stat, writeFile } from 'node:fs/prom
 import { join } from 'node:path';
 import { loginShellPath } from '../core/login-path.js';
 import { buildId } from '../core/version.js';
-import { DEFAULT_PANEL_PORT, isSidebyPanel, panelIdentity, startPanelServer, } from './server.js';
+import { DEFAULT_PANEL_PORT, isSidebyPanel, panelIdentity, panelOwner, startPanelServer, } from './server.js';
 export const DETACHED_FLAG = 'serve-detached';
 const START_TIMEOUT_MS = 20_000;
 const LOCK_STALE_MS = 30_000;
@@ -85,7 +85,7 @@ export async function findRunningPanel(p, port) {
         if (check.status === 'stale')
             await rm(pidFilePath(p), { force: true });
     }
-    return (await isSidebyPanel(port)) ? `http://127.0.0.1:${port}/` : undefined;
+    return (await isSidebyPanel(port, panelOwner(p.home))) ? `http://127.0.0.1:${port}/` : undefined;
 }
 /**
  * Stops this state directory's background Panel when it runs another build than `build` (or is older than build
@@ -209,6 +209,7 @@ export async function serveDetached(opts) {
     const srv = await startPanelServer({
         runtimeFactory: async () => opts.runtimeFactory(await envReady),
         instance,
+        owner: panelOwner(opts.paths.home),
         ...(opts.port ? { port: opts.port } : {}),
         open: false,
         log,

package/dist/src/panel/handler.d.ts

@@ -1,7 +1,8 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import { type AppProfileStatus } from '../core/app-profiles.ts';
+import { type AutostartContext, type AutostartStatus } from '../core/autostart.ts';
 import { type BrowserReport } from '../core/browser-profiles.ts';
-import { type DisplayConfig, type HandoffSettings } from '../core/config.ts';
+import { type DisplayConfig, type HandoffSettings, type PanelConfig } from '../core/config.ts';
 import { type AccountModel } from '../core/model-choice.ts';
 import type { RemoteControlGroup } from '../core/remote-control.ts';
 import * as update from '../core/update.ts';
@@ -68,9 +69,15 @@ export declare function healthByAccount(history: DoctorHistory | undefined): Map
     fail: number;
     warn: number;
 }>;
-/** A Family as the page sees it: FamilyInfo plus the mark from its FamilyDef. */
+/** A Family as the page sees it: FamilyInfo plus the mark from its FamilyDef, and what the key box needs. */
 export type PanelFamily = FamilyInfo & {
     logo?: FamilyLogo;
+    /** The variable the key box writes by default (spec §3.28); null when the Family names none. */
+    keyVar?: string | null;
+    /** The Secret File holds keys even for a subscription (pi), so its accounts offer the key box too. */
+    keyAlways?: boolean;
+    /** What "Try it" runs (`sideby try`): the Host and the probe arguments; absent when it cannot be tried. */
+    tryCommand?: string[];
 };
 /** What the Panel shows about updates (spec §3.23); absent when the handler was created with `updates: false`. */
 export interface PanelUpdate {
@@ -155,7 +162,27 @@ export interface PanelState {
     display: DisplayConfig;
     /** Families that ask for Quota in a way that costs a request (spec §3.26), with their switch; absent when none. */
     quotaChecks?: QuotaCheckInfo[];
+    /** Config `panel` (spec §3.29): the theme and language the Panel shows; absent when neither is set. */
+    panel?: PanelConfig;
 }
+/**
+ * Internal, for tests: replaces parts of the machine the Panel's start-at-login switch uses (platform, launcher,
+ * `exec`, login home). Not part of the plugin or Portal contract.
+ */
+export declare function bindPanelAutostart(ctx: Partial<AutostartContext>): () => void;
+/**
+ * The start-at-login state as the page shows it (spec §3.29): the agent's path and what it starts, with the home
+ * folder as `~`, and nothing else of the machine.
+ */
+export declare function autostartView(s: AutostartStatus, home: string): {
+    supported: boolean;
+    reason?: string | undefined;
+    state: import("../core/autostart.ts").AutostartState;
+    path: string;
+    current: boolean;
+    programArguments?: string[] | undefined;
+    missing?: string[] | undefined;
+};
 /** The `handoff` map of the Panel state, from the statuses and Quota already read for the page. */
 export declare function handoffByFamily(rt: Runtime, accounts: readonly PanelAccount[], now: Date): Record<string, string>;
 export type RemoteControlView = Omit<RemoteControlGroup, 'file'> & {