sideby 0.3.0 → 0.4.1

package/dist/src/handoff/hook.js

@@ -0,0 +1,166 @@
+// Entry for `sideby handoff-hook <family> <event>` (spec §3.17). A Host runs it on PostToolUse, Stop and
+// StopFailure, so it imports only Node built-ins and leaf modules: never the Runtime, a Family index or
+// core/accounts.ts. It never fails the Host: any problem means no output and exit 0.
+import { rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { FILES, HANDOFF_ENV, readJsonFile, writeJsonFile, } from '../core/handoff-chain.js';
+import { claudeHookReader } from '../families/claude/handoff-hook.js';
+import { codexHookReader } from '../families/codex/handoff-hook.js';
+import { grokHookReader } from '../families/grok/handoff-hook.js';
+import { endTurnMessage, prepareMessage, stopMessage, thresholdMessage } from './messages.js';
+import { field } from './reader.js';
+export const HOOK_COMMAND = 'sideby handoff-hook';
+const READERS = {
+    claude: claudeHookReader,
+    codex: codexHookReader,
+    grok: grokHookReader,
+};
+/** Families whose hooks this entry understands; only they can start a Handoff. */
+export const HOOK_FAMILIES = Object.keys(READERS);
+const EVENTS = new Set(['PostToolUse', 'Stop', 'StopFailure']);
+async function readAll(stream) {
+    const chunks = [];
+    try {
+        for await (const c of stream)
+            chunks.push(typeof c === 'string' ? Buffer.from(c) : Buffer.from(c));
+    }
+    catch {
+        // keep what arrived
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+const contextOutput = (text) => ({
+    hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: text },
+});
+const blockOutput = (reason) => ({ decision: 'block', reason });
+async function mtimeMs(path) {
+    try {
+        return (await stat(path)).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+/** What one hook call decided: output for the Host, and files to write. Separate from I/O for the tests. */
+export async function decide(opts) {
+    const { family, event, input, env, now } = opts;
+    const runId = env[HANDOFF_ENV.run];
+    const dir = env[HANDOFF_ENV.dir];
+    const reader = READERS[family];
+    // Not a run sideby started for a Handoff, or another Family's hook (Grok also runs Claude's settings hooks).
+    if (!runId || !dir || env[HANDOFF_ENV.family] !== family || !reader)
+        return {};
+    const plan = await readJsonFile(join(dir, FILES.plan));
+    const usable = plan && plan.runId === runId ? plan : null;
+    const runFile = join(dir, FILES.run(runId));
+    const state = (await readJsonFile(runFile)) ?? {};
+    const sessionId = field(input, 'session_id', 'sessionId');
+    const transcriptPath = field(input, 'transcript_path', 'transcriptPath');
+    const session = {
+        ...(sessionId ? { sessionId } : {}),
+        ...(transcriptPath ? { transcriptPath } : {}),
+    };
+    const save = (next) => writeJsonFile(runFile, { ...next, ...session });
+    const readyFile = join(dir, FILES.ready);
+    const ready = async (r) => {
+        if (await readJsonFile(readyFile))
+            return;
+        await writeJsonFile(readyFile, { runId, at: now.toISOString(), ...session, ...r });
+    };
+    const threshold = usable?.threshold ?? 95;
+    const pressure = reader.pressure ? await reader.pressure(input, env, now) : null;
+    if (event === 'StopFailure') {
+        if (reader.limitHit?.(input, pressure, threshold))
+            await ready({ trigger: 'limit' });
+        return {};
+    }
+    if (event === 'Stop') {
+        // Grok also fires Stop when the session ends; only a finished turn counts.
+        const reason = field(input, 'reason');
+        if (reason && reason !== 'end_turn')
+            return {};
+        const request = await readJsonFile(join(dir, FILES.request));
+        if (request && request.runId === runId) {
+            await ready({ ...request, trigger: 'manual' });
+            await rm(join(dir, FILES.request), { force: true });
+            return {};
+        }
+        if (!usable)
+            return {};
+        if (state.thresholdSentAt && usable.agentBrief === false) {
+            await ready({ trigger: 'threshold' });
+            return {};
+        }
+        if (state.thresholdSentAt) {
+            const written = await mtimeMs(usable.brief);
+            if (written !== null && written > Date.parse(state.thresholdSentAt))
+                await ready({ trigger: 'threshold', brief: usable.brief, briefSource: 'agent' });
+            else if (!state.stopBlocked && input.stop_hook_active !== true && input.stopHookActive !== true) {
+                await save({ ...state, stopBlocked: true });
+                return { output: blockOutput(stopMessage(usable.brief)) };
+            }
+            else
+                await ready({ trigger: 'threshold' });
+            return {};
+        }
+        // A turn without tool calls: the threshold is first seen here.
+        if (pressure !== null && pressure >= threshold && usable.decision === 'pick') {
+            if (usable.agentBrief === false) {
+                await ready({ trigger: 'threshold' });
+                return {};
+            }
+            await save({ ...state, thresholdSentAt: now.toISOString(), stopBlocked: true });
+            return { output: blockOutput(thresholdMessage(usable.brief, pressure)) };
+        }
+        return {};
+    }
+    // PostToolUse
+    if (!usable || pressure === null)
+        return {};
+    if (pressure >= usable.threshold && usable.decision === 'pick' && !state.thresholdSentAt) {
+        await save({ ...state, thresholdSentAt: now.toISOString() });
+        const text = usable.agentBrief === false ? endTurnMessage(pressure) : thresholdMessage(usable.brief, pressure);
+        return { output: contextOutput(text) };
+    }
+    if (usable.agentBrief === false)
+        return {};
+    if (pressure >= usable.prepareAt && !state.prepareSentAt && !state.thresholdSentAt) {
+        await save({ ...state, prepareSentAt: now.toISOString() });
+        return { output: contextOutput(prepareMessage(usable.brief, pressure)) };
+    }
+    return {};
+}
+export async function runHandoffHook(argv, env, stdin, stdout) {
+    // `sideby run` asks this first, so an older sideby on PATH without the hook entry is caught before any hook runs.
+    if (argv[0] === '--check') {
+        stdout.write('ok\n');
+        return 0;
+    }
+    try {
+        const [family, event] = argv;
+        if (!family || !event || !EVENTS.has(event) || !env[HANDOFF_ENV.run])
+            return 0;
+        let input;
+        try {
+            input = JSON.parse(await readAll(stdin));
+        }
+        catch {
+            return 0;
+        }
+        if (input === null || typeof input !== 'object' || Array.isArray(input))
+            return 0;
+        const r = await decide({
+            family,
+            event: event,
+            input: input,
+            env,
+            now: new Date(),
+        });
+        if (r.output)
+            stdout.write(`${JSON.stringify(r.output)}\n`);
+    }
+    catch {
+        // never fail the Host
+    }
+    return 0;
+}

package/dist/src/handoff/messages.d.ts

@@ -0,0 +1,7 @@
+export declare function prepareMessage(brief: string, pressure: number): string;
+export declare function thresholdMessage(brief: string, pressure: number): string;
+/** At the threshold when the session cannot write a Brief: sideby puts one together from its records. */
+export declare function endTurnMessage(pressure: number): string;
+export declare function stopMessage(brief: string): string;
+/** The next session's first prompt: the Brief's path only, never its text (it would show in a process list). */
+export declare function firstPrompt(fromRef: string, brief: string): string;

package/dist/src/handoff/messages.js

@@ -0,0 +1,27 @@
+// Text the handoff hook puts in front of the model, and the first prompt of the next session (spec §3.17).
+// English, since Hosts and models read it; complete in itself, so it works without any skill installed.
+const TEMPLATE = [
+    'the goal of the task',
+    'what is done',
+    'the remaining steps',
+    'key decisions and why',
+    'the files that matter',
+].join('; ');
+const RULES = 'Reference specs, ADRs, commits and diffs by path instead of repeating them, list the skills the next agent should use, and never include keys, passwords or personal data.';
+export function prepareMessage(brief, pressure) {
+    return `sideby: this account's quota is at ${Math.round(pressure)}%, so another account may take over soon. Write a handoff brief to ${brief} now (${TEMPLATE}). ${RULES} Keep it current after each step, then go on with the task.`;
+}
+export function thresholdMessage(brief, pressure) {
+    return `sideby: this account's quota is at ${Math.round(pressure)}%. Finish the current step, update the handoff brief at ${brief} (${TEMPLATE}; ${RULES}), then end your turn. sideby will start the next account from that brief.`;
+}
+/** At the threshold when the session cannot write a Brief: sideby puts one together from its records. */
+export function endTurnMessage(pressure) {
+    return `sideby: this account's quota is at ${Math.round(pressure)}%. Finish the current step and end your turn; sideby will start the next account and tell it what you did.`;
+}
+export function stopMessage(brief) {
+    return `sideby: before you stop, update the handoff brief at ${brief} (${TEMPLATE}; ${RULES}), then end your turn.`;
+}
+/** The next session's first prompt: the Brief's path only, never its text (it would show in a process list). */
+export function firstPrompt(fromRef, brief) {
+    return `This task was handed over from ${fromRef} by sideby because its quota ran low. Read ${brief} first, then continue the task it describes.`;
+}

package/dist/src/handoff/reader.d.ts

@@ -0,0 +1,11 @@
+import type { Env } from '../types.ts';
+/** The hook's stdin, parsed: field names differ per Host (snake_case for Claude and Codex, camelCase for Grok). */
+export type HookInput = Record<string, unknown>;
+export interface HookReader {
+    /** Quota Pressure in percent now, or null when unknown. Families without a Quota source leave it out. */
+    pressure?(input: HookInput, env: Env, now: Date): Promise<number | null>;
+    /** Whether a `StopFailure` means the Quota is used up, not a transient rate limit or an overloaded server. */
+    limitHit?(input: HookInput, pressure: number | null, threshold: number): boolean;
+}
+/** The first string field among `names`, so one reader accepts both spellings. */
+export declare function field(input: HookInput, ...names: string[]): string | undefined;

package/dist/src/handoff/reader.js

@@ -0,0 +1,9 @@
+/** The first string field among `names`, so one reader accepts both spellings. */
+export function field(input, ...names) {
+    for (const n of names) {
+        const v = input[n];
+        if (typeof v === 'string')
+            return v;
+    }
+    return undefined;
+}

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

@@ -1,4 +1,5 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type HandoffSettings } from '../core/config.ts';
 import type { AccountStatus, DoctorHistory, FamilyInfo, Runtime } from '../runtime.ts';
 import type { Account, FamilyLogo, QuotaResult, QuotaSetupPlan, UsageResult } from '../types.ts';
 import { type PanelTheme } from './theme.ts';
@@ -85,6 +86,11 @@ export interface PanelState {
      * at least two subscription Accounts, some Quota data and a pick; API Accounts are left out as in the CLI default.
      */
     handoff?: Record<string, string>;
+    /** Auto Handoff settings (spec §3.17) and the Families that can start one; readiness comes from /api/handoff/status. */
+    autoHandoff: {
+        settings: HandoffSettings;
+        starters: string[];
+    };
 }
 /** 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>;

package/dist/src/panel/handler.js

@@ -4,7 +4,11 @@ import { aliasesByAccount } from '../core/accounts.js';
 import { aliasArgs, aliasRefs } from '../core/config.js';
 import { UserError } from '../core/errors.js';
 import { planHandoff } from '../core/handoff.js';
+import { configureHandoff, handoffStatus } from '../core/handoff-status.js';
+import { tildify } from '../core/paths.js';
+import { MIN_CALLS } from '../core/tuning.js';
 import { buildId, packageVersion } from '../core/version.js';
+import { HOOK_FAMILIES } from '../handoff/hook.js';
 import { renderPage } from './page.js';
 import { resolveTheme } from './theme.js';
 export const PANEL_VERSION = packageVersion();
@@ -212,8 +216,48 @@ async function buildState(rt, opts) {
         ...(history ? { history } : {}),
         ...(rt.config.aliases ? { configAliases: aliasRefs(rt.config.aliases) } : {}),
         ...(Object.keys(handoff).length ? { handoff } : {}),
+        autoHandoff: {
+            settings: rt.handoffSettings(),
+            starters: [...rt.families.values()]
+                .filter((f) => f.handoff?.starts.length && HOOK_FAMILIES.includes(f.id))
+                .map((f) => f.id),
+        },
     };
 }
+/** The `change` of a /api/handoff/configure body, with every field checked; unknown fields are refused. */
+function handoffChange(body) {
+    const c = body.change;
+    if (!c || typeof c !== 'object' || Array.isArray(c))
+        throw new HttpError(400, '"change" must be an object');
+    const out = {};
+    for (const [k, v] of Object.entries(c)) {
+        if (k === 'auto' || k === 'sameFamily') {
+            if (typeof v !== 'boolean')
+                throw new HttpError(400, `"${k}" must be true or false`);
+            out[k] = v;
+        }
+        else if (k === 'prepareAt' ||
+            k === 'threshold' ||
+            k === 'waitIfResetWithinMinutes' ||
+            k === 'countdownSeconds') {
+            if (!Number.isInteger(v) || v < 0)
+                throw new HttpError(400, `"${k}" must be a whole number`);
+            out[k] = v;
+        }
+        else if (k === 'orders') {
+            if (!Array.isArray(v) ||
+                !v.every((o) => o &&
+                    typeof o.family === 'string' &&
+                    Array.isArray(o.order) &&
+                    o.order.every((n) => typeof n === 'string')))
+                throw new HttpError(400, '"orders" must be a list of { family, order: [account] }');
+            out.orders = v.map((o) => ({ family: o.family, order: [...o.order] }));
+        }
+        else
+            throw new HttpError(400, `unknown setting "${k}"`);
+    }
+    return out;
+}
 /** Runs write requests one at a time; a few may wait, the rest are told to retry. */
 function writeQueue() {
     let tail = Promise.resolve();
@@ -283,6 +327,72 @@ export function createPanelHandler(opts) {
                 return { family, summary: setup.summary, plan };
             },
         },
+        // Context tuning (spec §3.18): replays recent local sessions; reads only, so a read-only Panel allows it.
+        // The setting lives in a settings file that Accounts often share, so the answer comes grouped by file: one
+        // suggestion and one thing to apply per group, with every Account's details alongside.
+        '/api/tuning': {
+            writes: () => false,
+            async run(body) {
+                const account = optString(body, 'account');
+                const rt = await getRuntime();
+                const home = rt.paths.home;
+                const { accounts, groups } = await rt.tuneGroups(account ? await rt.resolve(account) : undefined);
+                return {
+                    minCalls: MIN_CALLS,
+                    accounts,
+                    groups: groups.map((g) => ({ ...g, id: g.file, file: tildify(g.file, home) })),
+                };
+            },
+        },
+        // Using a suggestion writes one key of the Account's settings (ADR-0012): without `confirm` it only shows the plan.
+        '/api/tuning/apply': {
+            writes: (body) => body.confirm === true,
+            async run(body) {
+                const account = optString(body, 'account');
+                if (!account)
+                    throw new HttpError(400, '"account" is required');
+                const value = body.value;
+                if (typeof value !== 'number' && value !== null)
+                    throw new HttpError(400, '"value" must be a number of tokens, or null for the default');
+                const rt = await getRuntime();
+                const found = await rt.resolve(account);
+                const home = rt.paths.home;
+                const show = (p) => ({ ...p, file: tildify(p.file, home) });
+                if (!optBool(body, 'confirm')) {
+                    const plan = await rt.tuneApplyPlan(found, value);
+                    return { ref: found.ref, applied: false, plan: show(plan), message: plan.reason ?? '' };
+                }
+                const r = await rt.tuneApply(found, value);
+                return { ref: found.ref, applied: r.ok, plan: show(r.plan), message: r.message };
+            },
+        },
+        '/api/tuning/undo': {
+            async run(body) {
+                const account = optString(body, 'account');
+                if (!account)
+                    throw new HttpError(400, '"account" is required');
+                const rt = await getRuntime();
+                const found = await rt.resolve(account);
+                const r = await rt.tuneUndo(found);
+                return { ref: found.ref, undone: r.ok, message: r.message };
+            },
+        },
+        // Auto Handoff (spec §3.17): readiness reads only; configure shows the config change unless `confirm`.
+        '/api/handoff/status': {
+            writes: () => false,
+            async run() {
+                return handoffStatus(await getRuntime());
+            },
+        },
+        '/api/handoff/configure': {
+            writes: (body) => body.confirm === true,
+            async run(body) {
+                const change = handoffChange(body);
+                const rt = await getRuntime();
+                const r = await configureHandoff(rt, change, { apply: optBool(body, 'confirm') });
+                return { ...r, file: tildify(r.file, rt.paths.home) };
+            },
+        },
         // Undo for the setup above; the Runtime turns a teardown that throws into `{ ok: false, message }`.
         '/api/quota/teardown': {
             async run(body) {

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

@@ -87,6 +87,12 @@ declare const en: {
     'need.quota-high.other': string;
     'need.health-warn.one': string;
     'need.health-warn.other': string;
+    'why.error': string;
+    'why.health-fail': string;
+    'why.signed-out': string;
+    'why.not-installed': string;
+    'why.quota-high': string;
+    'why.health-warn': string;
     'tb.search': string;
     'tb.searchPh': string;
     'tb.family': string;
@@ -117,6 +123,7 @@ declare const en: {
     'group.toggle': string;
     'group.attention.one': string;
     'group.attention.other': string;
+    'group.attentionShow': string;
     'acct.alias': string;
     'acct.aliasArgs': string;
     'acct.api': string;
@@ -130,6 +137,7 @@ declare const en: {
     'acct.notInstalled': string;
     'acct.readError': string;
     'acct.installHost': string;
+    'acct.nearLimit': string;
     'acct.installIt': string;
     'quota.pctUsed': string;
     'quota.pctLeft': string;
@@ -224,6 +232,57 @@ declare const en: {
     'menu.copyEmail': string;
     'menu.check': string;
     'menu.like': string;
+    'menu.tune': string;
+    'page.accounts': string;
+    'page.tuning': string;
+    'tune.title': string;
+    'tune.intro': string;
+    'tune.loading': string;
+    'tune.none': string;
+    'tune.noSource': string;
+    'tune.unreadable': string;
+    'tune.calls': string;
+    'tune.now': string;
+    'tune.hostDefault': string;
+    'tune.best': string;
+    'tune.saved': string;
+    'tune.compactions.one': string;
+    'tune.compactions.other': string;
+    'tune.noCompactions': string;
+    'tune.groupShared': string;
+    'tune.basis': string;
+    'tune.outOfRange': string;
+    'tune.overrides': string;
+    'tune.groupNone': string;
+    'tune.details': string;
+    'tune.detailsObserved': string;
+    'tune.use': string;
+    'tune.setting': string;
+    'tune.hostDefaultLong': string;
+    'tune.suggestedTag': string;
+    'tune.useThis': string;
+    'tune.working': string;
+    'tune.confirmTitle': string;
+    'tune.change': string;
+    'tune.file': string;
+    'tune.willCreate': string;
+    'tune.shared': string;
+    'tune.newSessions': string;
+    'tune.confirm': string;
+    'tune.done': string;
+    'tune.already': string;
+    'tune.applied': string;
+    'tune.undo': string;
+    'tune.undone': string;
+    'tune.reason.already-best': string;
+    'tune.reason.insufficient-calls': string;
+    'tune.reason.no-compactions': string;
+    'tune.reason.no-optimum': string;
+    'tune.reason.unknown-model': string;
+    'tune.reason.observe-only': string;
+    'tpage.title': string;
+    'tpage.none': string;
+    'tpage.idle': string;
     'nf.title': string;
     'nf.intro': string;
     'nf.tool': string;
@@ -264,6 +323,45 @@ declare const en: {
     'nf.aliasNotAdded': string;
     'nf.shellFileUpdated': string;
     'nf.shellFileSame': string;
+    'ah.button': string;
+    'ah.on': string;
+    'ah.off': string;
+    'ah.title': string;
+    'ah.intro': string;
+    'ah.auto': string;
+    'ah.sameFamily': string;
+    'ah.sameFamilyWarn': string;
+    'ah.prepareAt': string;
+    'ah.threshold': string;
+    'ah.wait': string;
+    'ah.countdown': string;
+    'ah.badLevels': string;
+    'ah.order': string;
+    'ah.byQuota': string;
+    'ah.myOrder': string;
+    'ah.byQuotaHint': string;
+    'ah.add': string;
+    'ah.up': string;
+    'ah.down': string;
+    'ah.remove': string;
+    'ah.emptyOrder': string;
+    'ah.readiness': string;
+    'ah.checking': string;
+    'ah.ready': string;
+    'ah.notYet': string;
+    'ah.takesOver': string;
+    'ah.steps': string;
+    'ah.review': string;
+    'ah.apply': string;
+    'ah.applying': string;
+    'ah.nothing': string;
+    'ah.saved': string;
+    'ah.changes': string;
+    'ah.hint': string;
+    'ah.setUp': string;
+    'ah.dismiss': string;
+    'toast.ahOn': string;
+    'toast.ahOff': string;
     'qs.title': string;
     'qs.preparing': string;
     'qs.changes': string;