sideby 0.2.2 → 0.4.0

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

@@ -0,0 +1,219 @@
+// How Grok Build takes part in a Handoff (spec §3.17). It has no public Quota, so it starts one only after a turn
+// failed at the limit. Interactive `grok` has no launch option for hooks: `sideby handoff setup grok` adds
+// `hooks/sideby-handoff.json` to the Main Account and Doctor copies it to the others (verified 2026-10-09).
+// The hook inherits Grok's sandbox, so the profile decides whether a run may start or receive.
+import { mkdir, readFile, rm, rmdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { sha256, writeFileAtomic } from '../../core/fs-safe.js';
+import { sidebyBinProblem } from '../../core/launch.js';
+import { tildify } from '../../core/paths.js';
+import { carryArgs, hasOption, optionValue, promptAfterDashes, } from '../shared/handoff-args.js';
+import { tomlValue } from '../shared/toml.js';
+import { grokBrief } from './brief.js';
+/** From `grok --help`. */
+export const GROK_ARGS = {
+    valued: [
+        '--agent',
+        '--agents',
+        '--allow',
+        '--cwd',
+        '--debug-file',
+        '--deny',
+        '--disallowed-tools',
+        '--json-schema',
+        '--leader-socket',
+        '-m',
+        '--model',
+        '--max-turns',
+        '--output-format',
+        '-p',
+        '--single',
+        '--permission-mode',
+        '--prompt-file',
+        '--prompt-json',
+        '--reasoning-effort',
+        '--rules',
+        '-s',
+        '--session-id',
+        '--sandbox',
+        '--system-prompt-override',
+        '--tools',
+        '--worktree-ref',
+    ],
+    optional: ['-r', '--resume', '-w', '--worktree'],
+    drop: ['-c', '--continue', '-r', '--resume', '-s', '--session-id', '--fork-session', '--restore-code'],
+};
+export const ETC_GROK = '/etc/grok';
+export const HOOK_FILE = 'sideby-handoff.json';
+const str = (v) => (typeof v === 'string' ? v : undefined);
+const bool = (v) => (typeof v === 'boolean' ? v : undefined);
+const first = (...vs) => vs.find((v) => v !== undefined);
+/**
+ * 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 function grokPolicy(layers, args, env) {
+    const read = (key) => (t) => t === null ? undefined : tomlValue(t, ...key);
+    const profileIn = read(['sandbox', 'profile']);
+    const leaderIn = read(['cli', 'use_leader']);
+    const pinIn = read(['', 'allow_managed_hooks_only']);
+    const profile = first(str(profileIn(layers.etcRequirements)), str(profileIn(layers.homeRequirements)), optionValue(args, ['--sandbox']), env.GROK_SANDBOX || undefined, str(profileIn(layers.config)), str(profileIn(layers.homeManaged)), str(profileIn(layers.etcManaged))) ?? 'off';
+    const leaderFlag = hasOption(args, ['--no-leader'])
+        ? false
+        : hasOption(args, ['--leader'])
+            ? true
+            : undefined;
+    const leader = first(bool(leaderIn(layers.etcRequirements)), bool(leaderIn(layers.homeRequirements)), leaderFlag, bool(leaderIn(layers.config)), bool(leaderIn(layers.homeManaged)), bool(leaderIn(layers.etcManaged))) ?? false;
+    const managedHooksOnly = [
+        layers.etcRequirements,
+        layers.homeRequirements,
+        layers.homeManaged,
+        layers.etcManaged,
+    ].some((t) => bool(pinIn(t)) === true);
+    return { profile, leader, managedHooksOnly };
+}
+async function textOrNull(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+async function readLayers(home) {
+    return {
+        etcRequirements: await textOrNull(join(ETC_GROK, 'requirements.toml')),
+        homeRequirements: await textOrNull(join(home, 'requirements.toml')),
+        config: await textOrNull(join(home, 'config.toml')),
+        homeManaged: await textOrNull(join(home, 'managed_config.toml')),
+        etcManaged: await textOrNull(join(ETC_GROK, 'managed_config.toml')),
+    };
+}
+const HEADLESS = ['-p', '--single', '--prompt-file', '--prompt-json'];
+export function grokEligibility(policy, args, home) {
+    if (hasOption(args, HEADLESS))
+        return { start: false, receive: false, reason: 'a headless run (`-p`) has nobody to hand over to' };
+    const extra = policy.leader && !hasOption(args, ['--leader-socket'])
+        ? { args: ['--leader-socket', join(home, 'leader.sock')] }
+        : {};
+    const { profile } = policy;
+    if (profile === 'off' || profile === 'devbox') {
+        if (policy.managedHooksOnly)
+            return {
+                start: false,
+                receive: true,
+                reason: 'allow_managed_hooks_only keeps sideby’s hook from running',
+                ...extra,
+            };
+        return { start: true, receive: true, ...extra };
+    }
+    if (profile === 'workspace' || profile === 'read-only')
+        return {
+            start: false,
+            receive: true,
+            reason: `the \`${profile}\` sandbox cannot write sideby’s handoff files, so this run can only take over`,
+            ...extra,
+        };
+    return {
+        start: false,
+        receive: false,
+        reason: `the \`${profile}\` sandbox profile cannot read sideby’s handoff files`,
+    };
+}
+const hookCommand = (event) => `sideby handoff-hook grok ${event}`;
+/** The whole file setup writes; teardown removes it only while it is still exactly this. */
+export function grokHookFileText() {
+    const hooks = {
+        hooks: {
+            Stop: [{ hooks: [{ type: 'command', command: hookCommand('Stop') }] }],
+            // Observation hooks get 5 seconds by default; putting a Brief together may take longer.
+            StopFailure: [{ hooks: [{ type: 'command', command: hookCommand('StopFailure'), timeout: 60 }] }],
+        },
+    };
+    return `${JSON.stringify(hooks, null, 2)}\n`;
+}
+const hookFile = (ctx) => join(ctx.home, '.grok', 'hooks', HOOK_FILE);
+async function plan(ctx) {
+    const file = hookFile(ctx);
+    const shown = tildify(file, ctx.home);
+    const want = grokHookFileText();
+    const have = await textOrNull(file);
+    if (have === want)
+        return { status: 'enabled', file, diff: '', message: `already set up in ${shown}` };
+    if (have !== null)
+        return {
+            status: 'blocked',
+            file,
+            diff: '',
+            message: `${shown} exists and is not sideby's; move it away and retry`,
+        };
+    const problem = await sidebyBinProblem(ctx.env, 'Grok runs `sideby handoff-hook` when a turn ends');
+    if (problem)
+        return { status: 'blocked', file, diff: '', message: problem };
+    return {
+        status: 'ready',
+        file,
+        diff: `--- /dev/null\n+++ ${shown}\n${want
+            .trimEnd()
+            .split('\n')
+            .map((l) => `+${l}`)
+            .join('\n')}\n`,
+        message: `adds ${shown} so Grok tells sideby when a turn hits the usage limit; then run \`sideby doctor grok --fix\` to copy it to every Grok account; undo with \`sideby handoff teardown grok\``,
+    };
+}
+export const grokHookSetup = {
+    summary: 'Adds one sideby hook file to ~/.grok/hooks so a Grok session that hits its usage limit can hand over.',
+    plan,
+    async apply(ctx) {
+        const p = await plan(ctx);
+        if (p.status !== 'ready')
+            return p;
+        await mkdir(join(ctx.home, '.grok', 'hooks'), { recursive: true });
+        await writeFileAtomic(p.file, grokHookFileText(), 0o644);
+        return { ...p, status: 'enabled' };
+    },
+    async teardown(ctx) {
+        const file = hookFile(ctx);
+        const shown = tildify(file, ctx.home);
+        const have = await textOrNull(file);
+        if (have === null)
+            return { ok: true, message: `${shown} is not there; nothing to undo` };
+        if (sha256(have) !== sha256(grokHookFileText()))
+            return {
+                ok: false,
+                message: `${shown} changed since setup; delete it yourself if you no longer want it`,
+            };
+        await rm(file);
+        // Setup may have made the directory; an empty one goes too, so the Main Account is back as it was.
+        await rmdir(join(ctx.home, '.grok', 'hooks')).catch(() => { });
+        return {
+            ok: true,
+            message: `removed ${shown}; run \`sideby doctor grok --fix\` to remove the copies in other Grok accounts`,
+        };
+    },
+};
+export const grokHandoff = {
+    starts: ['limit'],
+    promptArgs: promptAfterDashes,
+    continueArgs: (args) => carryArgs(args, GROK_ARGS),
+    resumeArgs: (id) => ['--resume', id],
+    async eligibility(args, account, env) {
+        let layers;
+        try {
+            layers = await readLayers(account.dir);
+        }
+        catch (err) {
+            return {
+                start: false,
+                receive: false,
+                reason: `cannot read Grok's config to tell its sandbox: ${err.message}`,
+            };
+        }
+        return grokEligibility(grokPolicy(layers, args, env), args, account.dir);
+    },
+    briefFromSession: grokBrief,
+    hookSetup: grokHookSetup,
+};

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

@@ -4,6 +4,7 @@ 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';
+import { grokHandoff } from './handoff.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)';
@@ -71,6 +72,7 @@ export const grokFamily = {
     model: readModel,
     identity: grokIdentity,
     resumedSession: resumeFlagSession,
+    handoff: grokHandoff,
     // One directory per session, grouped by working directory: sessions/<encoded cwd>/<id>/.
     sessionWrittenAt: (account, id) => groupedEntryWrittenAt(join(account.dir, 'sessions'), id, 'dir'),
 };

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

@@ -0,0 +1,2 @@
+import type { FamilyHandoff } from '../../types.ts';
+export declare const piHandoff: FamilyHandoff;

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

@@ -0,0 +1,13 @@
+import { hasOption, promptAfterDashes } from '../shared/handoff-args.js';
+export const piHandoff = {
+    starts: [],
+    promptArgs: promptAfterDashes,
+    // pi never starts a Handoff, so it never continues one of its own sessions with the user's arguments.
+    continueArgs: () => [],
+    resumeArgs: (id) => ['--session', id],
+    async eligibility(args) {
+        if (hasOption(args, ['-p', '--print']))
+            return { start: false, receive: false, reason: 'a headless run (`-p`) has nobody to hand over to' };
+        return { start: false, receive: true };
+    },
+};

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

@@ -4,6 +4,7 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { lstatOrNull } from '../../core/fs-safe.js';
 import { BUILTIN_LOGOS } from '../logos.js';
+import { piHandoff } from './handoff.js';
 /** `auth.json` exists after `/login`; its contents are never read. */
 async function loginState(account) {
     return (await lstatOrNull(join(account.dir, 'auth.json'))) ? 'logged-in' : 'logged-out';
@@ -45,6 +46,7 @@ export const piFamily = {
     login: { args: null, hint: 'pi signs in inside the app: start it and type /login' },
     loginState,
     model,
+    handoff: piHandoff,
 };
 export const piPlugin = {
     name: 'pi',

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

@@ -0,0 +1,24 @@
+export interface SessionDigest {
+    /** The first thing the user asked. */
+    firstUser?: string;
+    /** The last text messages, oldest first. */
+    recent: {
+        role: 'user' | 'assistant';
+        text: string;
+    }[];
+    /** Files the session edited or wrote, in first-touched order. */
+    files: string[];
+}
+export declare const MAX_PIECE = 2000;
+export declare const RECENT = 6;
+export declare const clip: (s: string, max?: number) => string;
+/** Keeps the last `RECENT` messages and each edited path once. */
+export declare class DigestBuilder {
+    private d;
+    user(text: string): void;
+    assistant(text: string): void;
+    file(path: unknown): void;
+    private push;
+    result(): SessionDigest | undefined;
+}
+export declare function formatDigest(d: SessionDigest): string;

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

@@ -0,0 +1,42 @@
+// A Handoff Brief put together from a session's local records, without a model (spec §3.17 "sideby 拼的 Brief").
+// Only conversation text and edited paths are taken, never tool output, each piece clipped.
+export const MAX_PIECE = 2000;
+export const RECENT = 6;
+export const clip = (s, max = MAX_PIECE) => (s.length > max ? `${s.slice(0, max)}…` : s);
+/** Keeps the last `RECENT` messages and each edited path once. */
+export class DigestBuilder {
+    d = { recent: [], files: [] };
+    user(text) {
+        const t = text.trim();
+        if (!t)
+            return;
+        this.d.firstUser ??= clip(t);
+        this.push('user', t);
+    }
+    assistant(text) {
+        const t = text.trim();
+        if (t)
+            this.push('assistant', t);
+    }
+    file(path) {
+        if (typeof path === 'string' && path && !this.d.files.includes(path))
+            this.d.files.push(path);
+    }
+    push(role, text) {
+        this.d.recent.push({ role, text: clip(text) });
+        if (this.d.recent.length > RECENT)
+            this.d.recent.shift();
+    }
+    result() {
+        return this.d.firstUser || this.d.recent.length || this.d.files.length ? this.d : undefined;
+    }
+}
+export function formatDigest(d) {
+    const out = ['## Task (first request)', '', d.firstUser ?? '(not found)', ''];
+    out.push('## Last messages', '');
+    for (const m of d.recent)
+        out.push(`**${m.role}:** ${m.text}`, '');
+    out.push('## Files edited', '');
+    out.push(...(d.files.length ? d.files.map((f) => `- ${f}`) : ['(none found)']), '');
+    return out.join('\n');
+}

package/dist/src/families/shared/handoff-args.d.ts

@@ -0,0 +1,18 @@
+export interface ArgRules {
+    /** Options whose value is the next argument. */
+    valued: readonly string[];
+    /** Options taking one or more values, up to the next option (Claude's `--add-dir <directories...>`). */
+    variadic?: readonly string[];
+    /** Options whose value may be left out: the next argument is theirs unless it starts with `-`. */
+    optional?: readonly string[];
+    /** Options left out of the next session, with their values. */
+    drop: readonly string[];
+}
+/** The options to carry over; every positional (a subcommand, a session id, the old prompt) and `--` onwards go. */
+export declare function carryArgs(args: readonly string[], rules: ArgRules): string[];
+/** True when `args` (before `--`) contain any of `names`, alone or as `name=value`. */
+export declare function hasOption(args: readonly string[], names: readonly string[]): boolean;
+/** The value of the first of `names` in `args` (`--x v` or `--x=v`), before `--`. */
+export declare function optionValue(args: readonly string[], names: readonly string[]): string | undefined;
+/** First prompt after `--`, so an option that takes several values cannot swallow it. */
+export declare const promptAfterDashes: (prompt: string) => string[];

package/dist/src/families/shared/handoff-args.js

@@ -0,0 +1,57 @@
+// Host arguments for the next session of a Handoff (spec §3.17 "启动参数"): keep the user's options, drop the ones
+// that resume or continue a session, and drop the old first prompt. Each Family lists which of its options take a
+// value, from its `--help`, so a value is never mistaken for the prompt.
+/** The options to carry over; every positional (a subcommand, a session id, the old prompt) and `--` onwards go. */
+export function carryArgs(args, rules) {
+    const kept = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--')
+            break;
+        if (!a.startsWith('-') || a === '-')
+            continue;
+        const name = a.includes('=') ? a.slice(0, a.indexOf('=')) : a;
+        const inline = name !== a;
+        const drop = rules.drop.includes(name);
+        const take = [a];
+        if (!inline) {
+            if (rules.valued.includes(name) && i + 1 < args.length)
+                take.push(args[++i]);
+            else if (rules.variadic?.includes(name))
+                while (i + 1 < args.length && !args[i + 1].startsWith('-'))
+                    take.push(args[++i]);
+            else if (rules.optional?.includes(name) && i + 1 < args.length && !args[i + 1].startsWith('-'))
+                take.push(args[++i]);
+        }
+        if (!drop)
+            kept.push(...take);
+    }
+    return kept;
+}
+/** True when `args` (before `--`) contain any of `names`, alone or as `name=value`. */
+export function hasOption(args, names) {
+    for (const a of args) {
+        if (a === '--')
+            return false;
+        const name = a.includes('=') ? a.slice(0, a.indexOf('=')) : a;
+        if (names.includes(name))
+            return true;
+    }
+    return false;
+}
+/** The value of the first of `names` in `args` (`--x v` or `--x=v`), before `--`. */
+export function optionValue(args, names) {
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--')
+            return undefined;
+        const eq = a.indexOf('=');
+        if (eq > 0 && names.includes(a.slice(0, eq)))
+            return a.slice(eq + 1);
+        if (names.includes(a))
+            return args[i + 1];
+    }
+    return undefined;
+}
+/** First prompt after `--`, so an option that takes several values cannot swallow it. */
+export const promptAfterDashes = (prompt) => ['--', prompt];

package/dist/src/families/shared/sessions.d.ts

@@ -1,8 +1,12 @@
 export declare const isSessionId: (s: string | undefined) => s is string;
 /** The id after `--resume <id>`, `--resume=<id>` or `-r <id>`; Claude Code and Grok Build share this form. */
 export declare function resumeFlagSession(args: readonly string[]): string | undefined;
+/** The arguments without the by-id resume `resumeFlagSession` reads; the rest keep their order (ADR-0009). */
+export declare function withoutResumeFlag(args: readonly string[]): string[];
 /** The first UUID after the `resume` subcommand (`codex resume [options] <id>`). */
 export declare function resumeSubcommandSession(args: readonly string[]): string | undefined;
+/** Modification time in ms of `path` when it is a directory (Claude `session-env/<id>`, ADR-0009). */
+export declare const dirWrittenAt: (path: string) => Promise<number | undefined>;
 /** `<dir>/*` + `/<entry>`: one level of grouping directories (Claude projects, Grok working directories). */
 export declare function groupedEntryWrittenAt(dir: string, entry: string, type: 'file' | 'dir'): Promise<number | undefined>;
 /** A file anywhere under `dir` whose name ends with `suffix` (Codex `sessions/YYYY/MM/DD/rollout-…-<id>.jsonl`). */

package/dist/src/families/shared/sessions.js

@@ -23,6 +23,23 @@ export function resumeFlagSession(args) {
     }
     return undefined;
 }
+/** The arguments without the by-id resume `resumeFlagSession` reads; the rest keep their order (ADR-0009). */
+export function withoutResumeFlag(args) {
+    const end = args.indexOf('--');
+    const opts = end === -1 ? args : args.slice(0, end);
+    const kept = [];
+    for (let i = 0; i < opts.length; i++) {
+        const a = opts[i];
+        if (a.startsWith('--resume=') && isSessionId(a.slice('--resume='.length)))
+            continue;
+        if ((a === '--resume' || a === '-r') && isSessionId(opts[i + 1])) {
+            i++;
+            continue;
+        }
+        kept.push(a);
+    }
+    return end === -1 ? kept : [...kept, ...args.slice(end)];
+}
 /** The first UUID after the `resume` subcommand (`codex resume [options] <id>`). */
 export function resumeSubcommandSession(args) {
     const opts = options(args);
@@ -43,6 +60,8 @@ async function firstWrittenAt(paths, type) {
     }
     return undefined;
 }
+/** Modification time in ms of `path` when it is a directory (Claude `session-env/<id>`, ADR-0009). */
+export const dirWrittenAt = (path) => firstWrittenAt([path], 'dir');
 async function subdirs(dir) {
     try {
         return (await readdir(dir, { withFileTypes: true }))

package/dist/src/families/shared/toml.d.ts

@@ -3,3 +3,8 @@
  * Only a whole-line header ends the top level, so a multi-line array line such as `  ["a"],` does not.
  */
 export declare function topLevelTomlString(text: string, key: string): string | undefined;
+/**
+ * A string or boolean `key` in `[table]`, or as `table.key = …` at the top level; `table` '' means the top level.
+ * Enough for the few policy keys sideby reads (Grok's sandbox profile); not a TOML parser.
+ */
+export declare function tomlValue(text: string, table: string, key: string): string | boolean | undefined;

package/dist/src/families/shared/toml.js

@@ -14,3 +14,33 @@ export function topLevelTomlString(text, key) {
     }
     return undefined;
 }
+/**
+ * A string or boolean `key` in `[table]`, or as `table.key = …` at the top level; `table` '' means the top level.
+ * Enough for the few policy keys sideby reads (Grok's sandbox profile); not a TOML parser.
+ */
+export function tomlValue(text, table, key) {
+    const value = /^\s*(?:"([^"]*)"|'([^']*)'|(true|false))\s*(#.*)?$/;
+    let current = '';
+    for (const line of text.split(/\r?\n/)) {
+        const header = /^\s*\[\s*([A-Za-z0-9_.-]+)\s*\]\s*(#.*)?$/.exec(line);
+        if (header) {
+            current = header[1];
+            continue;
+        }
+        if (TABLE_HEADER.test(line)) {
+            current = '\0';
+            continue;
+        }
+        const kv = /^\s*([A-Za-z0-9_.-]+)\s*=(.*)$/.exec(line);
+        if (!kv)
+            continue;
+        const full = current ? `${current}.${kv[1]}` : kv[1];
+        if (full !== (table ? `${table}.${key}` : key))
+            continue;
+        const m = value.exec(kv[2]);
+        if (!m)
+            return undefined;
+        return m[3] ? m[3] === 'true' : (m[1] ?? m[2]);
+    }
+    return undefined;
+}

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

@@ -0,0 +1,16 @@
+import type { Env, HandoffHookEvent } from '../types.ts';
+import { type HookInput } from './reader.ts';
+export declare const HOOK_COMMAND = "sideby handoff-hook";
+/** Families whose hooks this entry understands; only they can start a Handoff. */
+export declare const HOOK_FAMILIES: readonly string[];
+/** What one hook call decided: output for the Host, and files to write. Separate from I/O for the tests. */
+export declare function decide(opts: {
+    family: string;
+    event: HandoffHookEvent;
+    input: HookInput;
+    env: Env;
+    now: Date;
+}): Promise<{
+    output?: unknown;
+}>;
+export declare function runHandoffHook(argv: readonly string[], env: Env, stdin: AsyncIterable<Uint8Array | string>, stdout: NodeJS.WritableStream): Promise<number>;