@hwip/cli 0.0.1 → 0.1.0

package/dist/schedule-remote.js

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * What the phone sees and says about schedules (F8 slices 06 and 07). The decisions live here so
+ * `listener.ts` only wires them: this file reads the schedule files and the runner's state, and
+ * takes the phone's words at face value for nothing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyPhoneSchedule = exports.livePhoneScheduleDeps = exports.scheduleAnswer = exports.phoneScheduleList = exports.LIST_MAX_BYTES = exports.LIST_PROMPT_CHARS = void 0;
+const node_path_1 = require("node:path");
+const schedule_js_1 = require("./schedule.js");
+const schedule_ready_js_1 = require("./schedule-ready.js");
+const session_registry_js_1 = require("./session-registry.js");
+const wrapper_js_1 = require("./wrapper.js");
+/** The longest prompt the list carries; the full text is in the file on this machine. */
+exports.LIST_PROMPT_CHARS = 500;
+/** The sealed list must fit one relay frame (cf. `DIFF_SEALED_MAX_BYTES`), counted in UTF-8 bytes. */
+exports.LIST_MAX_BYTES = 24 * 1024;
+/** Prompt lengths tried in turn until the list fits; the last drops prompts altogether. */
+const PROMPT_CHARS_STEPS = [exports.LIST_PROMPT_CHARS, 200, 80, 0];
+/** `text` cut to `max` UTF-16 units with an ellipsis, minus a surrogate pair the cut would split. */
+const clip = (text, max) => {
+    if (text.length <= max)
+        return text;
+    const cut = text.slice(0, max - 1);
+    const last = cut.charCodeAt(cut.length - 1);
+    return `${last >= 0xd800 && last <= 0xdbff ? cut.slice(0, -1) : cut}…`;
+};
+const isoOrNull = (ms) => {
+    if (ms === null)
+        return null;
+    const date = new Date(ms);
+    return Number.isNaN(date.getTime()) ? null : date.toISOString();
+};
+/** The schedules on this machine for the app, oldest first, prompts cut to `promptChars`. Null when the directory could not be listed or holds more than a machine may: an empty list would then be a lie. */
+const phoneScheduleList = (now, promptChars = exports.LIST_PROMPT_CHARS) => {
+    const read = (0, schedule_js_1.listSchedules)();
+    if (read.incomplete)
+        return null;
+    const state = (0, schedule_js_1.readScheduleState)().schedules;
+    const schedules = read.schedules.map((schedule) => {
+        const last = state[schedule.id]?.last;
+        const lastAt = last ? isoOrNull(last.at) : null;
+        return {
+            id: schedule.id,
+            source: schedule.source,
+            agentKind: schedule.agentKind,
+            project: (0, node_path_1.basename)(schedule.cwd),
+            session: schedule.session,
+            when: schedule.when,
+            ...(schedule.prompt !== undefined && promptChars > 0 ? { prompt: clip(schedule.prompt, promptChars) } : {}),
+            maxRuntimeMin: schedule.maxRuntimeMin,
+            nextAt: isoOrNull((0, schedule_js_1.nextOccurrence)(schedule.when, now, Date.parse(schedule.createdAt))),
+            ...(last && lastAt ? { last: { outcome: last.outcome, at: lastAt } } : {}),
+        };
+    });
+    return { schedules, unreadable: read.unreadable };
+};
+exports.phoneScheduleList = phoneScheduleList;
+/**
+ * The list as one answer. The text that gets sealed names the request and the time it answers, so a relay
+ * cannot hand an older sealed list back as the answer to a newer request. Prompts are cut shorter, step by
+ * step, until the answer fits a frame; it is an error only when even the list without prompts does not.
+ */
+const scheduleAnswer = (now, requestId, at) => {
+    for (const promptChars of PROMPT_CHARS_STEPS) {
+        const listing = (0, exports.phoneScheduleList)(now, promptChars);
+        if (!listing)
+            return { ok: false, error: 'read_failed' };
+        const { schedules, unreadable } = listing;
+        const sealed = JSON.stringify({ v: 1, requestId, at, schedules, ...(unreadable > 0 ? { unreadable } : {}) });
+        if (Buffer.byteLength(sealed) <= exports.LIST_MAX_BYTES)
+            return { ok: true, listing, sealed };
+    }
+    return { ok: false, error: 'too_large' };
+};
+exports.scheduleAnswer = scheduleAnswer;
+exports.livePhoneScheduleDeps = {
+    now: Date.now,
+    recall: (session, agentKind) => (agentKind === undefined ? (0, session_registry_js_1.recallSession)(session) : (0, session_registry_js_1.recallRun)(session, agentKind)),
+    directoryExists: session_registry_js_1.sessionDirectoryExists,
+    canPrompt: schedule_ready_js_1.canPromptKind,
+};
+const refuse = (reason, why) => ({ ok: false, reason, why });
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const CREATE_KEYS = new Set(['op', 'when', 'prompt', 'agentKind', 'maxRuntimeMin']);
+/** Stands in for the run time while the rest of a request is checked; the shortest `validateSchedule` takes. */
+const SHORTEST_RUN_MIN = 5;
+/** The fields every schedule made from a phone request has, whatever the request says: all but `id` come from this machine's record. */
+const fromRecord = (entry, id, now) => ({
+    v: 1,
+    id,
+    createdAt: new Date(now).toISOString(),
+    source: 'phone',
+    agentKind: entry.agentKind,
+    cwd: entry.cwd,
+    label: `sched-${id}`,
+    session: `${(0, wrapper_js_1.tmuxSessionName)((0, wrapper_js_1.safeBasename)(entry.cwd))}-sched-${id}`,
+});
+const create = (request, session, deps) => {
+    // Whatever else the request carries — a directory, arguments, a label — is refused, not ignored: it was meant to be used.
+    const extra = Object.keys(request).find((k) => !CREATE_KEYS.has(k));
+    if (extra !== undefined)
+        return refuse('schedule_invalid', `a create carries ${extra}`);
+    const { when, prompt, agentKind, maxRuntimeMin } = request;
+    if (agentKind !== undefined && typeof agentKind !== 'string')
+        return refuse('schedule_invalid', 'agentKind is not text');
+    // Directory and agent are what this machine recorded for the session, never what the phone says.
+    const entry = deps.recall(session, agentKind);
+    // The session name is in the clear, so not knowing it can be told as it is. A session known under other agents only
+    // is read off sealed text (the agent the request named), so it goes out as a bad request.
+    if (!entry) {
+        const knownUnderAnother = agentKind !== undefined && deps.recall(session) !== null;
+        return knownUnderAnother ? refuse('schedule_invalid', 'that agent never ran under that session name') : refuse('unknown_session', 'no recorded session by that name');
+    }
+    if (!deps.directoryExists(entry))
+        return refuse('unknown_session', 'the recorded directory is gone');
+    if (!deps.canPrompt(entry.agentKind))
+        return refuse('schedule_invalid', `${entry.agentKind} cannot take a scheduled prompt`);
+    const now = deps.now();
+    const checked = (0, schedule_js_1.validateSchedule)({ ...fromRecord(entry, 'aaaaaa', now), when, prompt, maxRuntimeMin: maxRuntimeMin ?? SHORTEST_RUN_MIN });
+    if (!checked.ok)
+        return refuse('schedule_invalid', checked.error);
+    const runtime = typeof maxRuntimeMin === 'number' ? maxRuntimeMin : (0, schedule_js_1.defaultMaxRuntimeMin)(checked.value.when);
+    const added = (0, schedule_js_1.addSchedule)((id) => ({ ...checked.value, ...fromRecord(entry, id, now), maxRuntimeMin: runtime }));
+    if (added.ok)
+        return { ok: true };
+    return refuse(added.failure === 'limit' ? 'schedule_limit' : added.failure === 'io' ? 'schedule_failed' : 'schedule_invalid', added.error);
+};
+const remove = (request, session) => {
+    if (Object.keys(request).some((k) => k !== 'op' && k !== 'id'))
+        return refuse('schedule_invalid', 'a remove carries only an id');
+    const { id } = request;
+    if (typeof id !== 'string')
+        return refuse('schedule_invalid', 'a remove needs an id');
+    // The push names the schedule's own session, so a request for one schedule cannot remove another.
+    const read = (0, schedule_js_1.listSchedules)();
+    // A list that is not all of them cannot say a schedule is not there: that is this machine's trouble, not the request's.
+    if (read.incomplete)
+        return refuse('schedule_failed', 'the schedules could not be listed');
+    const target = read.schedules.find((schedule) => schedule.id === id);
+    if (!target || target.session !== session)
+        return refuse('schedule_invalid', 'no such schedule for that session');
+    // Gone by the time it is removed (the person, or `hwip schedule rm`, was first) is the state asked for.
+    const removed = (0, schedule_js_1.removeSchedule)(id);
+    return removed === 'invalid' ? refuse('schedule_invalid', 'not a schedule id') : { ok: true };
+};
+/**
+ * Carry out one change the phone asked for: `{ op: 'create', when, prompt, agentKind?, maxRuntimeMin? }` for the
+ * recorded session `session`, or `{ op: 'remove', id }` for the schedule whose session that is. Nothing here
+ * types into a session. `request` is whatever the phone sealed, so every field is checked as it is used.
+ */
+const applyPhoneSchedule = (request, session, deps = exports.livePhoneScheduleDeps) => {
+    if (!isRecord(request))
+        return refuse('schedule_invalid', 'the request is not an object');
+    try {
+        if (request.op === 'create')
+            return create(request, session, deps);
+        if (request.op === 'remove')
+            return remove(request, session);
+    }
+    catch (err) {
+        // A file that would not read or write is this machine's trouble, not a mistake in the request.
+        return refuse('schedule_failed', err instanceof Error ? err.message : String(err));
+    }
+    return refuse('schedule_invalid', 'op is neither create nor remove');
+};
+exports.applyPhoneSchedule = applyPhoneSchedule;

package/dist/schedule-runner.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Starts scheduled sessions on time (F8). The listener calls `tick(now)` on a timer; everything the tick touches
+ * outside this file (the clock, tmux, `hwip <agent> --detach`, the state file) comes in through `deps`, so a
+ * fake clock and fakes drive every case in the tests.
+ *
+ * What a tick decides, per schedule: how many due times passed since its cursor, whether the newest is still
+ * worth running (`GRACE_MS`; older ones are `missed` and never run late), and whether the session may start.
+ * The cursor is written before anything is launched, so a listener killed in between skips that run instead of
+ * starting it twice.
+ */
+import { type Schedule, type ScheduleList, type ScheduleStateFile } from './schedule.js';
+/** How often the listener ticks. */
+export declare const TICK_MS = 30000;
+/** A due time older than this when the tick sees it (the machine slept, the listener was down) is missed, not run. */
+export declare const GRACE_MS = 120000;
+/** After a launch exits 0, how long before the session has to be there. */
+export declare const START_CHECK_MS = 2000;
+/** A launch that has not exited by then is given up on. */
+export declare const LAUNCH_TIMEOUT_MS = 30000;
+/** The same for `--wt`: the launch first makes the worktree (`git worktree add`, and whatever its hooks do), which a big repo does not finish in 30 s. */
+export declare const LAUNCH_WT_TIMEOUT_MS = 120000;
+/** After a push that did not go out, how long until the next try; doubled on every failure up to the cap. */
+export declare const PUSH_RETRY_MS = 30000;
+export declare const PUSH_RETRY_MAX_MS: number;
+/** How often the listener polls sessions that are waiting for their prompt (only while one is). */
+export declare const PROMPT_POLL_MS = 5000;
+/**
+ * How long after the start a session may take to become ready for its prompt; later, the prompt is given up on. Ready
+ * takes two polls in a row on the same idle screen (`schedule-ready.ts`), so the earliest prompt goes one poll after
+ * the session is idle, and a retry after a failed inject two polls later.
+ */
+export declare const PROMPT_WAIT_MS = 90000;
+/** Scheduled sessions running at once. */
+export declare const MAX_RUNNING = 3;
+export type LaunchResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/** What became of a push: `retry` is worth another try later; `rejected` is the server's no (4xx, a quota among them), which trying again cannot change. */
+export type NotifyOutcome = 'sent' | 'retry' | 'rejected';
+/**
+ * What a failed push means for trying again. Only the server saying no to this very push is final: a 4xx (a daily
+ * limit among them). The client's own timeout (reported as 408), a proxy asking for credentials (407) and a page that
+ * is not the API's (a captive portal) are the network failing, and the push is worth sending again when it is back.
+ */
+export declare const notifyFailureOutcome: (e: unknown) => Exclude<NotifyOutcome, "sent">;
+export interface ScheduleRunnerDeps {
+    listSchedules: () => ScheduleList;
+    readState: () => ScheduleStateFile;
+    /** Replaces the state file atomically; false when it could not. */
+    writeState: (state: ScheduleStateFile) => boolean;
+    sessionExists: (session: string) => boolean;
+    /** The session is known to be over. Not the same as `!sessionExists`: when tmux cannot be asked, nobody knows. */
+    sessionEnded: (session: string) => boolean;
+    directoryExists: (cwd: string) => boolean;
+    /** The `hwip` subcommand that starts an agent kind; undefined for a kind the table does not have. */
+    subcommandFor: (kind: string) => string | undefined;
+    /** Runs `hwip <args>` in `cwd` and resolves when it has exited, or gives up after `timeoutMs`. */
+    launch: (args: string[], cwd: string, timeoutMs: number) => Promise<LaunchResult>;
+    sleep: (ms: number) => Promise<void>;
+    log: (line: string) => void;
+    /** Whether a prompt can ever be typed into this kind of agent: its detection rules can say `idle` (see `schedule-ready.ts`). */
+    canPrompt: (agentKind: string) => boolean;
+    /** The agent in `session` is up and its rules say it is idle: the screen is not a dialog or a task in progress. */
+    ready: (session: string, agentKind: string) => boolean;
+    /** Types `prompt` into the session and submits it; false when it was not delivered (rate limit, no pane, …). */
+    inject: (session: string, prompt: string) => boolean;
+    /** Asks the session to end the way a phone's exit request does (the agent's quit command, then signals). It never kills the tmux session. */
+    endSession: (session: string) => void;
+    /** Tells the person (title, body). */
+    notify: (title: string, body: string) => Promise<NotifyOutcome>;
+    /** The wall clock (default `Date.now`); a launch takes seconds, and the schedules after it are judged by the time it ends. */
+    clock?: () => number;
+}
+/**
+ * The arguments of `hwip` that start `schedule`'s session. One array element per argument, never a string for a shell:
+ * `agentArgs` are passed on as typed, whatever they contain.
+ */
+export declare const launchArgs: (schedule: Schedule, subcommand: string) => string[];
+export interface ScheduleRunner {
+    /** Starts what is due, then looks after the sessions already running. Every `TICK_MS`. */
+    tick: (now: number) => Promise<void>;
+    /** Looks after the running sessions only (their prompt, their runtime cap). Every `PROMPT_POLL_MS`; does nothing while no prompt is waiting. */
+    poll: (now: number) => Promise<void>;
+}
+export declare const createScheduleRunner: (deps: ScheduleRunnerDeps) => ScheduleRunner;
+//# sourceMappingURL=schedule-runner.d.ts.map