sideby 0.10.0 → 0.12.0

package/dist/src/core/handoff-chain.d.ts

@@ -14,6 +14,8 @@ export interface PlanFile {
     at: string;
     decision: 'pick' | 'wait' | 'none';
     pick?: string;
+    /** For `wait`: when the full window resets and the session goes on by itself. */
+    until?: string;
     prepareAt: number;
     threshold: number;
     /** False when the session cannot write its Brief: no preparing step, and the threshold only ends the turn. */
@@ -26,6 +28,8 @@ export interface RunState {
     prepareSentAt?: string;
     thresholdSentAt?: string;
     stopBlocked?: boolean;
+    /** The user was told this run waits for a reset instead of moving on (ADR-0018). */
+    waitNoticeSentAt?: string;
     sessionId?: string;
     transcriptPath?: string;
 }
@@ -42,6 +46,12 @@ export interface ReadyFile {
     sessionId?: string;
     transcriptPath?: string;
 }
+/** The parent kept a session that hit its limit, to wait for the reset at `until` (ADR-0018). */
+export interface WaitingFile {
+    runId: string;
+    until: string;
+    at: string;
+}
 export interface ChainHop {
     ref: string;
     startedAt: string;
@@ -57,6 +67,7 @@ export declare const FILES: {
     readonly plan: 'plan.json';
     readonly ready: 'ready.json';
     readonly request: 'request.json';
+    readonly waiting: 'waiting.json';
     readonly chain: 'chain.json';
     readonly run: (runId: string) => string;
 };
@@ -73,7 +84,10 @@ export declare function writeJsonFile(path: string, value: unknown): Promise<voi
 /**
  * `sideby handoff ready` (spec §3.17): asks the parent to hand over after this turn. Works only inside a run sideby
  * started with Auto Handoff; `briefFile`, when given, is copied into the chain directory (mode 600); `to` is the
- * Account ref to hand over to.
+ * Account ref to hand over to. While the session waits for a reset (`waiting.json`, typed as `! sideby handoff ready`),
+ * no turn will end to pick up a request, so it writes `ready.json` at once (`now`).
  * Returns the request, or null outside such a run.
  */
-export declare function requestHandoff(env: Readonly<Record<string, string | undefined>>, briefFile?: string, to?: string): Promise<ReadyFile | null>;
+export declare function requestHandoff(env: Readonly<Record<string, string | undefined>>, briefFile?: string, to?: string, now?: Date): Promise<(ReadyFile & {
+    now: boolean;
+}) | null>;

package/dist/src/core/handoff-chain.js

@@ -1,7 +1,8 @@
 // The files one Handoff chain keeps under `<state>/handoffs/<chain>/` (spec §3.17). The handoff hook runs on every
 // tool call, so this module imports only Node built-ins and leaf modules (never the Runtime or a Family index).
-// The parent `sideby run` writes `plan.json` and `chain.json`; the hook writes `run-<id>.json` and `ready.json`;
-// `sideby handoff ready` writes `request.json`. Every file is mode 600 in a mode 700 directory.
+// The parent `sideby run` writes `plan.json`, `chain.json` and, while a session waits for a reset, `waiting.json`; the
+// hook writes `run-<id>.json` and `ready.json`; `sideby handoff ready` writes `request.json` (`ready.json` while the
+// session waits). Every file is mode 600 in a mode 700 directory.
 import { randomBytes } from 'node:crypto';
 import { chmod, mkdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
@@ -16,6 +17,7 @@ export const FILES = {
     plan: 'plan.json',
     ready: 'ready.json',
     request: 'request.json',
+    waiting: 'waiting.json',
     chain: 'chain.json',
     run: (runId) => `run-${runId}.json`,
 };
@@ -51,10 +53,11 @@ export async function writeJsonFile(path, value) {
 /**
  * `sideby handoff ready` (spec §3.17): asks the parent to hand over after this turn. Works only inside a run sideby
  * started with Auto Handoff; `briefFile`, when given, is copied into the chain directory (mode 600); `to` is the
- * Account ref to hand over to.
+ * Account ref to hand over to. While the session waits for a reset (`waiting.json`, typed as `! sideby handoff ready`),
+ * no turn will end to pick up a request, so it writes `ready.json` at once (`now`).
  * Returns the request, or null outside such a run.
  */
-export async function requestHandoff(env, briefFile, to) {
+export async function requestHandoff(env, briefFile, to, now = new Date()) {
     const runId = env[HANDOFF_ENV.run];
     const dir = env[HANDOFF_ENV.dir];
     if (!runId || !dir)
@@ -66,11 +69,21 @@ export async function requestHandoff(env, briefFile, to) {
     }
     const request = {
         runId,
-        at: new Date().toISOString(),
+        at: now.toISOString(),
         trigger: 'manual',
         ...(brief ? { brief, briefSource: 'user' } : {}),
         ...(to ? { to } : {}),
     };
+    const waiting = await readJsonFile(join(dir, FILES.waiting));
+    if (waiting && waiting.runId === runId && Date.parse(waiting.until) > now.getTime()) {
+        const state = (await readJsonFile(join(dir, FILES.run(runId)))) ?? {};
+        await writeJsonFile(join(dir, FILES.ready), {
+            ...request,
+            ...(state.sessionId ? { sessionId: state.sessionId } : {}),
+            ...(state.transcriptPath ? { transcriptPath: state.transcriptPath } : {}),
+        });
+        return { ...request, now: true };
+    }
     await writeJsonFile(join(dir, FILES.request), request);
-    return request;
+    return { ...request, now: false };
 }

package/dist/src/core/handoff-run.js

@@ -132,9 +132,12 @@ export function hookEntryWorks(env) {
     });
 }
 /** The decision, or `none` with the reason when sideby cannot tell (an account removed mid-chain, say). */
-async function decide(rt, account, used, to) {
+async function decide(rt, account, used, to, manual = false) {
     try {
-        return await rt.handoffDecision(account, used, to !== undefined ? { to } : {});
+        return await rt.handoffDecision(account, used, {
+            ...(to !== undefined ? { to } : {}),
+            ...(manual ? { manual: true } : {}),
+        });
     }
     catch (err) {
         return { kind: 'none', reason: err.message };
@@ -230,6 +233,7 @@ opts = {}) {
                         at: new Date().toISOString(),
                         decision: d.kind,
                         ...(d.kind === 'pick' ? { pick: d.ref } : {}),
+                        ...(d.kind === 'wait' ? { until: d.until } : {}),
                         prepareAt: settings.prepareAt,
                         threshold: settings.threshold,
                         ...(elig.agentBrief === false ? { agentBrief: false } : {}),
@@ -246,27 +250,48 @@ opts = {}) {
         await writePlan();
         const refresh = setInterval(() => void writePlan(), PLAN_REFRESH_MS);
         const host = spawnHost({ ...launch, args, env });
-        const watcher = watchReady(dir, runId);
-        const outcome = await Promise.race([
-            host.exited.then((code) => ({ kind: 'exit', code })),
-            watcher.ready.then((ready) => ({ kind: 'ready', ready })),
-        ]);
+        const exited = host.exited.then((code) => ({ kind: 'exit', code }));
+        // Nothing to move on to (or better to wait): leave the session alone, keep listening (the user may still ask to
+        // move on while it waits, ADR-0018), and say why once it ends.
+        let kept;
+        let outcome;
+        for (;;) {
+            const watcher = watchReady(dir, runId);
+            const got = await Promise.race([
+                exited,
+                watcher.ready.then((ready) => ({ kind: 'ready', ready })),
+            ]);
+            watcher.stop();
+            if (got.kind === 'exit') {
+                outcome = got;
+                break;
+            }
+            const d = await decide(rt, account, used, got.ready.to, got.ready.trigger === 'manual');
+            if (d.kind === 'pick') {
+                outcome = { ...got, decision: d };
+                break;
+            }
+            await rm(join(dir, FILES.ready), { force: true });
+            if (d.kind === 'wait')
+                await writeJsonFile(join(dir, FILES.waiting), {
+                    runId,
+                    until: d.until,
+                    at: new Date().toISOString(),
+                });
+            kept = d;
+        }
         clearInterval(refresh);
-        watcher.stop();
         stopped = true;
         await pending;
+        await rm(join(dir, FILES.waiting), { force: true });
         if (outcome.kind === 'exit') {
-            await noteUnhandedHighQuota(rt, account, used, settings.threshold, io);
+            if (kept)
+                io.err(`sideby: ${account.ref} did not hand over: ${explain(kept)}`);
+            else
+                await noteUnhandedHighQuota(rt, account, used, settings.threshold, io);
             return outcome.code;
         }
-        // Nothing to move on to (or better to wait): leave the session alone and say why once it ends.
-        const decision = await decide(rt, account, used, outcome.ready.to);
-        if (decision.kind !== 'pick') {
-            await rm(join(dir, FILES.ready), { force: true });
-            const code = await host.exited;
-            io.err(`sideby: ${account.ref} did not hand over: ${explain(decision)}`);
-            return code;
-        }
+        const decision = outcome.decision;
         // The session is ready: end the Host, give it time to save, never kill it.
         host.child.kill('SIGTERM');
         const ended = await Promise.race([
@@ -356,5 +381,5 @@ export async function readyDecision(rt, env, to) {
     }
     const account = await rt.resolve(ref);
     const chain = await readJsonFile(join(dir, FILES.chain));
-    return decide(rt, account, chain?.hops.map((h) => h.ref) ?? [account.ref], to);
+    return decide(rt, account, chain?.hops.map((h) => h.ref) ?? [account.ref], to, true);
 }

package/dist/src/core/handoff-select.d.ts

@@ -15,6 +15,8 @@ export interface SelectCandidate {
     installed: boolean;
     /** Whether its Family can start as the next Account (has `handoff`, and the run would be eligible). */
     receive: boolean;
+    /** A session stopped at the limit continues by itself at the reset (`FamilyHandoff.resumesAtReset`); set for the origin. */
+    resumesAtReset?: boolean;
 }
 /** An Account the Handoff Order lists that was left out, and why (spec §3.21). */
 export interface SkippedAccount {
@@ -55,4 +57,6 @@ export declare function selectNext(input: {
      * an Account whose Quota came back); every other rule still applies.
      */
     to?: string;
+    /** The user asked to hand over (`sideby handoff ready`): never wait for a reset (ADR-0018). */
+    manual?: boolean;
 }): HandoffDecision;

package/dist/src/core/handoff-select.js

@@ -15,7 +15,8 @@ export function sameOrganization(a, b) {
  * reaches the threshold (spec §3.17 "选号" 1: plan.json and the Panel, decided before the moment comes).
  */
 function waitUntil(origin, s, now, ahead) {
-    if (origin.quota.status !== 'ok' || s.waitIfResetWithinMinutes <= 0)
+    // Waiting only makes sense when the session goes on by itself at the reset (ADR-0018).
+    if (origin.quota.status !== 'ok' || s.waitIfResetWithinMinutes <= 0 || origin.resumesAtReset !== true)
         return undefined;
     const open = origin.quota.windows.filter((w) => !windowReset(w.resetsAt, now));
     const top = Math.max(0, ...open.map((w) => w.usedPercent));
@@ -60,7 +61,7 @@ export function selectNext(input) {
             return { kind: 'none', reason: `${input.to} is not an account sideby can find` };
         return toTarget(origin, target, s, new Set(s.crossOrganization.map(refOf)), now);
     }
-    const until = waitUntil(origin, s, now, input.ahead === true);
+    const until = input.manual ? undefined : waitUntil(origin, s, now, input.ahead === true);
     if (until)
         return { kind: 'wait', until };
     const allowed = new Set(s.crossOrganization.map(refOf));

package/dist/src/core/update.d.ts

@@ -0,0 +1,209 @@
+import type { Env } from '../types.ts';
+import type { Paths } from './paths.ts';
+export declare const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+export declare const CHECK_INTERVAL_MS: number;
+export declare const NOTICE_INTERVAL_MS: number;
+/** After a failed check (offline, a mirror without the endpoint) the next one waits this long. */
+export declare const RETRY_INTERVAL_MS: number;
+/** A failed Auto Update of one version is tried again after this long (a mirror may not have it yet). */
+export declare const AUTO_RETRY_MS: number;
+export declare const RELEASE_NOTES: (v: string) => string;
+/** What `update.json` in the state directory holds. Every field is optional; a broken file reads as `{}`. */
+export interface UpdateCache {
+    /** When the registry last answered. */
+    checkedAt?: string;
+    /** When a check was last tried, answered or not. */
+    triedAt?: string;
+    /** The `latest` dist-tag it answered. */
+    latest?: string;
+    /** When a background check last looked at Auto Update (installed, or waited for a running session). */
+    autoTriedAt?: string;
+    /** The last Update Notice the CLI printed. */
+    notified?: {
+        version: string;
+        at: string;
+    };
+    /** The last Auto Update; `shown` once the CLI has said so. */
+    auto?: {
+        from: string;
+        to: string;
+        at: string;
+        ok: boolean;
+        message: string;
+        shown?: boolean;
+    };
+}
+export type InstallKind = 'npm' | 'pnpm' | 'bun' | 'volta' | 'npx' | 'project' | 'source';
+export interface InstallMethod {
+    kind: InstallKind;
+    /** The installed package folder (real path). */
+    packageDir: string;
+    /** True when sideby can run the Update itself (npm, pnpm or bun global, and npm's folders are writable). */
+    canUpdate: boolean;
+    /** Why it cannot, in a phrase that follows "sideby cannot update itself: ". */
+    reason?: string;
+    /** npm only: the prefix whose `lib/node_modules` holds sideby. */
+    prefix?: string;
+}
+/** Swapped in tests through `bindUpdateDeps`; the real machine otherwise. */
+export interface UpdateDeps {
+    fetch: typeof fetch;
+    now: () => Date;
+    /** Real path of the running sideby package. */
+    packageDir: () => Promise<string>;
+    writable: (dir: string) => Promise<boolean>;
+    alive: (pid: number) => boolean;
+    /** Runs a program, streaming its output to `onOutput`; resolves with the exit code and the whole output. */
+    exec: (file: string, args: readonly string[], opts: {
+        env: Env;
+        onOutput?: (text: string) => void;
+    }) => Promise<{
+        code: number;
+        output: string;
+    }>;
+    /** Starts `sideby ui --background --no-open --port <port>` from the newly installed code, detached; false when it could not start. */
+    restartPanel: (env: Env, port: number) => Promise<boolean>;
+}
+/** Internal, for tests: replaces parts of the machine. Not part of the plugin or Portal contract. */
+export declare function bindUpdateDeps(deps: Partial<UpdateDeps>): () => void;
+/** -1, 0 or 1 like a sort comparator; a prerelease sorts before its release. Null when either is not a version. */
+export declare function compareVersions(a: string, b: string): number | null;
+/** `latest` is newer than `current`. */
+export declare const isNewer: (latest: string | undefined, current: string) => latest is string;
+/**
+ * The jump keeps the major version (0.11 → 0.12, 1.2 → 1.9). Auto Update only takes these; 0.x → 1.0 or 1.x → 2.0
+ * only gets a notice.
+ */
+export declare function sameLine(from: string, to: string): boolean;
+/** True in CI, where a notice is noise and a check is a request nobody reads. */
+export declare const inCi: (env: Env) => boolean;
+type UpdateSettings = {
+    update?: {
+        check?: boolean;
+        auto?: boolean;
+    };
+};
+/** Why Update Checks are off, or null when they are on (spec §3.23). */
+export declare function checksOff(env: Env, config: UpdateSettings): string | null;
+export declare function readUpdateCache(paths: Paths): Promise<UpdateCache>;
+/**
+ * Merges a change into the cache file. The file is read again first, and `change` may be a function of what is there
+ * now, so a writer that decides from an older read (the CLI marking an Auto Update shown) never overwrites a newer
+ * field another process wrote meanwhile.
+ */
+export declare function updateUpdateCache(paths: Paths, change: Partial<UpdateCache> | ((now: UpdateCache) => Partial<UpdateCache>)): Promise<UpdateCache>;
+/** A check is due: no answer within a day, and no attempt within the hour (so being offline costs one try an hour). */
+export declare function checkDue(cache: UpdateCache, now: Date): boolean;
+/**
+ * Auto Update is on and the cache names a newer version it has not installed: never tried, or a failed try a day
+ * ago. Lets the CLI start a background check even when a Panel already ran today's check.
+ */
+export declare function autoPending(cache: UpdateCache, current: string, config: UpdateSettings, now: Date): boolean;
+/** Asks the registry for the `latest` dist-tag. Throws with a message that names the registry and what to do. */
+export declare function fetchLatest(env: Env): Promise<string>;
+/** Runs one Update Check and records it, answered or not. Never throws. */
+export declare function refreshUpdateCheck(paths: Paths, env: Env): Promise<UpdateCache>;
+/**
+ * The Update Notice line the CLI may print now, or null. Once per new version per day; `current` is the running
+ * version.
+ */
+export declare function noticeLine(cache: UpdateCache, current: string, now: Date): string | null;
+/** What the CLI says once about the last Auto Update, or null. */
+export declare function autoUpdateLine(cache: UpdateCache): string | null;
+/**
+ * What the CLI does after a command (spec §3.23), decided from the cache: the lines to print (the Auto Update result,
+ * then the Update Notice), the change that records them, and whether to start a background check. The caller prints,
+ * writes `record` with `updateUpdateCache` and starts the check; nothing here touches the machine.
+ */
+export declare function afterCommandPlan(cache: UpdateCache, current: string, config: UpdateSettings, env: Env, now: Date): {
+    lines: string[];
+    record: ((cur: UpdateCache) => Partial<UpdateCache>) | null;
+    startCheck: boolean;
+};
+/** Where the running copy comes from (spec §3.23 table); reads only paths. */
+export declare function installMethod(env: Env): Promise<InstallMethod>;
+/**
+ * The command an Update runs (or that the user runs) for `version`; `run` is set only when sideby may run it. With
+ * `SIDEBY_UPDATE_REGISTRY`, installs use that registry too, so the version the check found is the one fetched.
+ */
+export declare function updateCommand(method: InstallMethod, version: string, env?: Env): {
+    text: string;
+    run?: {
+        file: string;
+        args: string[];
+    };
+};
+/**
+ * Records that this process runs a Host (`run`, `login`, `next`, `resume`) so an Auto Update waits for it; returns the
+ * function that removes the record. Failing to write the record never stops a Launch.
+ */
+export declare function markRunning(paths: Paths, pid?: number): Promise<() => Promise<void>>;
+/** Pids of sideby processes that run a Host now; records of processes that ended are removed. */
+export declare function runningSessions(paths: Paths): Promise<number[]>;
+export interface UpdatePlan {
+    current: string;
+    latest: string;
+    available: boolean;
+    method: InstallMethod;
+    /** The command for the user to see; `canRun` says whether sideby runs it after a confirmation. */
+    command: string;
+    canRun: boolean;
+    releaseNotes: string;
+}
+export declare function planFrom(method: InstallMethod, current: string, latest: string, env?: Env): UpdatePlan;
+/** The Install Method as outputs show it: no folder of this machine. */
+export declare const shownMethod: (m: InstallMethod) => {
+    kind: InstallKind;
+    canUpdate: boolean;
+    reason?: string | undefined;
+};
+/** The plan as `sideby update --json` and the Panel show it (schemas/update.json). */
+export declare function shownPlan(plan: UpdatePlan): {
+    current: string;
+    latest: string;
+    available: boolean;
+    method: {
+        kind: InstallKind;
+        canUpdate: boolean;
+        reason?: string | undefined;
+    };
+    command: string;
+    canRun: boolean;
+    releaseNotes: string;
+};
+/** Asks the registry now (whatever the switches say: the user asked) and returns what an Update would do. */
+export declare function planUpdate(paths: Paths, env: Env): Promise<UpdatePlan>;
+export interface UpdateResult {
+    ok: boolean;
+    /** Exit code of the install command; absent when it did not run. */
+    code?: number;
+    output: string;
+    message: string;
+    /** A background Panel was running and is starting again from the new code. */
+    restartedPanel: boolean;
+    /** Another Update held the lock; nothing ran. */
+    busy?: boolean;
+}
+/**
+ * Runs the Update the plan names, then starts a running background Panel again from the new code. The caller has
+ * shown the plan and got a confirmation (or this is an Auto Update). One Update runs at a time on this machine (the
+ * CLI, a Panel and an Auto Update share the lock). `panelPort` gives the port of the background Panel to restart, or
+ * null when none runs. A successful Update is recorded as said, so no notice for it follows.
+ */
+export declare function applyUpdate(paths: Paths, plan: UpdatePlan, env: Env, opts?: {
+    onOutput?: (text: string) => void;
+    panelPort?: () => Promise<number | null>;
+}): Promise<UpdateResult>;
+/** What keeps an Auto Update from installing `plan` until the user acts (an install it cannot update, a major version). */
+export declare function lastingBlocker(plan: UpdatePlan): string | null;
+/**
+ * Whether an Auto Update may install `plan` now (spec §3.23), and if not, why. Running sessions are looked up
+ * last because that removes records of ended processes.
+ */
+export declare function autoUpdateBlocker(paths: Paths, plan: UpdatePlan): Promise<string | null>;
+/**
+ * Body of the detached `sideby update-check`: an Update Check when one is due, then an Auto Update when config
+ * `update.auto` is on and nothing blocks it. Only one runs at a time; it never throws.
+ */
+export declare function backgroundCheck(paths: Paths, env: Env, config: UpdateSettings, panelPort: () => Promise<number | null>): Promise<void>;
+export {};