@hwip/cli 0.0.1 → 0.1.0

package/dist/schedule-command.js

@@ -0,0 +1,260 @@
+"use strict";
+/**
+ * `hwip schedule` — add, list and remove scheduled sessions (F8).
+ *
+ * This only writes and reads the files in `schedule.ts`. The listener starts the sessions
+ * (`schedule-runner.ts`), so nothing here needs a running listener except the sessions firing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleSchedule = exports.liveScheduleDeps = exports.runSchedule = exports.buildSchedule = exports.describeWhen = void 0;
+const args_js_1 = require("./args.js");
+const schedule_js_1 = require("./schedule.js");
+const config_js_1 = require("./config.js");
+const listener_process_js_1 = require("./listener-process.js");
+const remote_agents_js_1 = require("./remote-agents.js");
+const schedule_ready_js_1 = require("./schedule-ready.js");
+const wrapper_js_1 = require("./wrapper.js");
+const worktree_js_1 = require("./worktree.js");
+const USAGE = "usage: hwip schedule add <agent> (--at HH:MM [--days daily|weekdays|mon,wed,…] | --every <N>m|<N>h) [--prompt <text>] [--label <x>] [--wt <branch>] [--max-runtime <N>m|<N>h] [-- <agent args…>]\n"
+    + '       hwip schedule [list] [--json]\n'
+    + '       hwip schedule rm <id>';
+const LISTENER_NOTE = "hwip: schedules start only while the listener runs ('hwip listener --install-service' keeps it running at login)";
+/** A value flag's text: undefined when not given; an error when given without a value. */
+const flagText = (flags, name) => {
+    const value = flags[name];
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    if (typeof value !== 'string')
+        return { ok: false, error: `--${name} needs a value` };
+    return { ok: true, value };
+};
+/** `daily 09:00`, `weekdays 09:00`, `mon,wed 09:00`, `every 30m`, `every 2h`. */
+const describeWhen = (when) => {
+    if (when.kind === 'every')
+        return when.minutes % 60 === 0 ? `every ${when.minutes / 60}h` : `every ${when.minutes}m`;
+    const days = when.days.join(',');
+    const label = days === schedule_js_1.ALL_DAYS.join(',') ? 'daily' : days === schedule_js_1.WEEKDAYS.join(',') ? 'weekdays' : when.days.map((d) => schedule_js_1.DAY_NAMES[d]).join(',');
+    return `${label} ${when.at}`;
+};
+exports.describeWhen = describeWhen;
+/** The schedule `hwip schedule add <words>` asks for, before it has an id. */
+const buildSchedule = async (words, deps) => {
+    const cut = words.indexOf('--');
+    const own = cut < 0 ? words : words.slice(0, cut);
+    const agentArgs = cut < 0 ? [] : words.slice(cut + 1);
+    // `parseArgs` reads the words after the program name and script; the first word is the agent.
+    const flags = (0, args_js_1.parseArgs)(['node', 'hwip', ...own]);
+    const agentWord = String(flags._command);
+    if (!agentWord)
+        return { ok: false, error: 'schedule add needs an agent (hwip cc, codex, …)' };
+    const agent = (0, remote_agents_js_1.findAgentBySubcommand)(agentWord);
+    if (!agent)
+        return { ok: false, error: `'${agentWord}' is not an agent hwip can start` };
+    if (flags._arg1)
+        return { ok: false, error: `unexpected word '${String(flags._arg1)}'` };
+    const read = (name) => flagText(flags, name);
+    const [at, days, every, prompt, label, wt, maxRuntime] = ['at', 'days', 'every', 'prompt', 'label', 'wt', 'max-runtime'].map(read);
+    const bad = [at, days, every, prompt, label, wt, maxRuntime].find((r) => !r.ok);
+    if (bad && !bad.ok)
+        return bad;
+    const value = (r) => (r.ok ? r.value : undefined);
+    const when = (0, schedule_js_1.parseWhen)({ at: value(at), days: value(days), every: value(every) });
+    if (!when.ok)
+        return when;
+    if (value(prompt) !== undefined && value(prompt).trim() === '')
+        return { ok: false, error: '--prompt must not be empty' };
+    if (value(prompt) !== undefined && !deps.promptKinds().includes(agent.kind)) {
+        const names = remote_agents_js_1.REMOTE_AGENTS.filter((a) => deps.promptKinds().includes(a.kind)).map((a) => a.subcommands[0]).join(', ');
+        return {
+            ok: false,
+            error: `${agentWord} cannot take a scheduled --prompt: hwip has no rule that tells when it is idle, and a prompt typed into a dialog would answer it. `
+                + `--prompt works with: ${names || '(none right now)'}. A schedule without --prompt is fine.`,
+        };
+    }
+    if (value(wt) !== undefined && value(label) !== undefined)
+        return { ok: false, error: '--wt and --label cannot be combined: a worktree session is named for its branch' };
+    let runtime = (0, schedule_js_1.defaultMaxRuntimeMin)(when.value);
+    if (value(maxRuntime) !== undefined) {
+        const parsed = (0, schedule_js_1.parseDuration)(value(maxRuntime), '--max-runtime', '90m or 2h');
+        if (!parsed.ok)
+            return parsed;
+        runtime = parsed.value;
+    }
+    const cwd = deps.projectDir();
+    let project = (0, wrapper_js_1.safeBasename)(cwd);
+    const branch = value(wt)?.trim();
+    if (branch !== undefined) {
+        const root = deps.checkoutRoot(cwd);
+        if (!root)
+            return { ok: false, error: '--wt needs a git checkout with a main worktree' };
+        if (!branch || branch.startsWith('-') || !(await deps.validBranch(root, branch))) {
+            return { ok: false, error: `'${branch}' is not a valid branch name` };
+        }
+        // The worktree directory `ensureWorktree` makes, and so the name the wrapper gives the session.
+        const dirName = (0, worktree_js_1.worktreeDirName)(root, branch);
+        if (!dirName)
+            return { ok: false, error: `'${branch}' is not a usable worktree name` };
+        project = dirName;
+    }
+    const createdAt = new Date(deps.now()).toISOString();
+    const text = value(prompt);
+    const make = (id) => {
+        const name = branch === undefined && value(label) !== undefined ? (0, wrapper_js_1.sanitizeLabel)(value(label)) : `sched-${id}`;
+        return {
+            v: 1,
+            id,
+            createdAt,
+            source: 'cli',
+            agentKind: agent.kind,
+            cwd,
+            label: name,
+            session: `${(0, wrapper_js_1.tmuxSessionName)(project)}-${name}`,
+            ...(branch !== undefined ? { wt: branch } : {}),
+            ...(agentArgs.length > 0 ? { agentArgs } : {}),
+            ...(text !== undefined ? { prompt: text } : {}),
+            when: when.value,
+            maxRuntimeMin: runtime,
+        };
+    };
+    // The checks that need no id run now, so a refusal costs no id and no file.
+    const probe = (0, schedule_js_1.validateSchedule)(make('aaaaaa'));
+    return probe.ok ? { ok: true, value: { make, agentName: agent.displayName } } : probe;
+};
+exports.buildSchedule = buildSchedule;
+/** An ISO date, or null for a time outside what a Date holds (a damaged or hand-edited file). */
+const isoOrNull = (ms) => (ms !== null && Number.isFinite(new Date(ms).getTime()) ? new Date(ms).toISOString() : null);
+const formatTime = (ms) => {
+    if (!Number.isFinite(new Date(ms).getTime()))
+        return '-';
+    const d = new Date(ms);
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+};
+const handleAdd = async (words, json, deps) => {
+    const built = await (0, exports.buildSchedule)(words, deps);
+    if (!built.ok) {
+        deps.err(`hwip schedule: ${built.error}`);
+        return 2;
+    }
+    const added = (0, schedule_js_1.addSchedule)(built.value.make);
+    if (!added.ok) {
+        deps.err(`hwip schedule: ${added.error}`);
+        return 2;
+    }
+    const { schedule } = added;
+    const next = (0, schedule_js_1.nextOccurrence)(schedule.when, deps.now(), Date.parse(schedule.createdAt));
+    if (json) {
+        deps.out(JSON.stringify({ ...schedule, nextAt: isoOrNull(next) }));
+    }
+    else {
+        deps.out(`scheduled ${schedule.id}: ${built.value.agentName} in ${(0, wrapper_js_1.safeBasename)(schedule.cwd)}, ${(0, exports.describeWhen)(schedule.when)}`
+            + `${next === null ? '' : `, next ${formatTime(next)}`} (session ${schedule.session}, ends after ${schedule.maxRuntimeMin}m)`);
+    }
+    if (!deps.listenerRunning())
+        deps.err(LISTENER_NOTE);
+    return 0;
+};
+const handleList = (json, deps) => {
+    const { schedules, unreadable } = (0, schedule_js_1.listSchedules)();
+    const state = (0, schedule_js_1.readScheduleState)().schedules;
+    const now = deps.now();
+    const rows = schedules.map((schedule) => {
+        const next = (0, schedule_js_1.nextOccurrence)(schedule.when, now, Date.parse(schedule.createdAt));
+        const last = state[schedule.id]?.last;
+        return { schedule, next, last, running: state[schedule.id]?.running !== undefined };
+    });
+    if (json) {
+        deps.out(JSON.stringify(rows.map(({ schedule, next, last, running }) => ({
+            id: schedule.id,
+            agent: schedule.agentKind,
+            cwd: schedule.cwd,
+            label: schedule.label,
+            session: schedule.session,
+            when: schedule.when,
+            maxRuntimeMin: schedule.maxRuntimeMin,
+            source: schedule.source,
+            nextAt: isoOrNull(next),
+            last: last ? { outcome: last.outcome, at: isoOrNull(last.at) } : null,
+            running,
+        }))));
+    }
+    else if (rows.length === 0) {
+        deps.out("no schedules (add one with 'hwip schedule add')");
+    }
+    else {
+        for (const { schedule, next, last, running } of rows) {
+            deps.out([
+                schedule.id,
+                schedule.agentKind,
+                (0, wrapper_js_1.safeBasename)(schedule.cwd),
+                (0, exports.describeWhen)(schedule.when),
+                `next ${next === null ? '-' : formatTime(next)}`,
+                `last ${last ? `${last.outcome} ${formatTime(last.at)}` : '-'}${running ? ' (running)' : ''}`,
+            ].join('  '));
+        }
+    }
+    if (unreadable > 0)
+        deps.err(`hwip schedule: ${unreadable} file${unreadable === 1 ? '' : 's'} in ${(0, schedule_js_1.schedulesDir)()} could not be read and ${unreadable === 1 ? 'was' : 'were'} skipped`);
+    if (rows.length > 0 && !deps.listenerRunning())
+        deps.err(LISTENER_NOTE);
+    return 0;
+};
+const handleRemove = (id, deps) => {
+    if (!id) {
+        deps.err('hwip schedule: rm needs a schedule id');
+        return 2;
+    }
+    const removed = (0, schedule_js_1.removeSchedule)(id);
+    if (removed === 'invalid') {
+        deps.err(`hwip schedule: '${id}' is not a schedule id`);
+        return 2;
+    }
+    if (removed === 'missing') {
+        deps.err(`hwip schedule: no schedule ${id}`);
+        return 1;
+    }
+    deps.out(`removed ${id}. A session it already started keeps running; end it yourself if you want it gone.`);
+    return 0;
+};
+const JSON_ON = new Set(['--json', '--json=true', '--json=1', '--json=yes']);
+/** `words`: argv after `schedule`. Returns the exit code. */
+const runSchedule = async (words, deps) => {
+    // `--json` is lifted out first: the flag parser would hand it the next word (`--json list`, `add --json cc`).
+    const cut = words.indexOf('--');
+    const head = cut < 0 ? words : words.slice(0, cut);
+    const json = head.some((w) => JSON_ON.has(w));
+    const plain = [...head.filter((w) => !JSON_ON.has(w)), ...(cut < 0 ? [] : words.slice(cut))];
+    const sub = plain.length === 0 ? 'list' : plain[0];
+    const rest = plain.slice(1);
+    switch (sub) {
+        case 'add':
+            return handleAdd(rest, json, deps);
+        case 'list':
+            if (rest.length > 0)
+                break;
+            return handleList(json, deps);
+        case 'rm':
+            if (rest.length > 1)
+                break;
+            return handleRemove(rest[0], deps);
+        default:
+    }
+    deps.err(rest.length > 0 && (sub === 'list' || sub === 'rm')
+        ? `hwip schedule: unexpected word '${rest[sub === 'list' ? 0 : 1]}'\n${USAGE}`
+        : `hwip schedule: unknown subcommand '${sub}'\n${USAGE}`);
+    return 2;
+};
+exports.runSchedule = runSchedule;
+const liveScheduleDeps = () => ({
+    now: () => Date.now(),
+    projectDir: wrapper_js_1.detectProjectDir,
+    checkoutRoot: (dir) => (0, config_js_1.checkoutOf)(dir)?.root ?? null,
+    validBranch: (root, name) => (0, worktree_js_1.isValidBranchName)(root, name),
+    listenerRunning: () => (0, listener_process_js_1.runningListenerPid)() !== null,
+    promptKinds: () => (0, schedule_ready_js_1.promptableScheduleKinds)(remote_agents_js_1.REMOTE_AGENTS.map((a) => a.kind)),
+    out: (line) => console.log(line),
+    err: (line) => console.error(line),
+});
+exports.liveScheduleDeps = liveScheduleDeps;
+const handleSchedule = (words) => (0, exports.runSchedule)(words, (0, exports.liveScheduleDeps)());
+exports.handleSchedule = handleSchedule;

package/dist/schedule-launch.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Runs `hwip <agent> --detach …` for a scheduled session, as a child of the listener (F8). The child gets the schedule's
+ * directory as its cwd and none of the project-dir env vars, so it resolves its project from that directory and not from
+ * whatever shell once started the listener; and it is told it is the listener's own, so it does not "repair" the listener
+ * that is running it (see `LISTENER_LAUNCH_ENV`).
+ */
+import { execFile as nodeExecFile } from 'child_process';
+import type { LaunchResult } from './schedule-runner.js';
+export interface LaunchDeps {
+    execFile?: typeof nodeExecFile;
+    cliPath?: () => string | null;
+    env?: NodeJS.ProcessEnv;
+}
+export declare const launchHwip: (argv: string[], cwd: string, timeoutMs: number, deps?: LaunchDeps) => Promise<LaunchResult>;
+//# sourceMappingURL=schedule-launch.d.ts.map

package/dist/schedule-launch.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * Runs `hwip <agent> --detach …` for a scheduled session, as a child of the listener (F8). The child gets the schedule's
+ * directory as its cwd and none of the project-dir env vars, so it resolves its project from that directory and not from
+ * whatever shell once started the listener; and it is told it is the listener's own, so it does not "repair" the listener
+ * that is running it (see `LISTENER_LAUNCH_ENV`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.launchHwip = void 0;
+const child_process_1 = require("child_process");
+const config_js_1 = require("./config.js");
+const listener_process_js_1 = require("./listener-process.js");
+const launchHwip = (argv, cwd, timeoutMs, deps = {}) => new Promise((resolve) => {
+    const cliPath = (deps.cliPath ?? listener_process_js_1.resolveCliPath)();
+    if (!cliPath)
+        return resolve({ ok: false, error: 'cannot find the hwip cli entry' });
+    const env = { ...(deps.env ?? process.env), [listener_process_js_1.LISTENER_LAUNCH_ENV]: '1' };
+    for (const key of config_js_1.PROJECT_DIR_ENV_VARS)
+        delete env[key];
+    (deps.execFile ?? child_process_1.execFile)(process.execPath, [cliPath, ...argv], { cwd, env, encoding: 'utf-8', timeout: timeoutMs }, (err, _stdout, stderr) => {
+        resolve(err ? { ok: false, error: stderr || err.message } : { ok: true });
+    });
+});
+exports.launchHwip = launchHwip;

package/dist/schedule-ready.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Whether a scheduled session's agent may be typed at (F8). A prompt typed into a terminal that is still starting up
+ * is lost or lands in the wrong place, and one typed into a dialog answers it: Enter on a trust or permission prompt
+ * accepts the default, with nobody there to read it. So the only sign this feature accepts is the agent's own state
+ * rules saying `idle` for the screen as it is now. An agent without an `idle` rule is never typed at — a screen that
+ * has stopped changing proves nothing, a static dialog stops changing too.
+ *
+ * The rules are the bundled ones, never the OTA manifest. A phone's input is typed by a person who has seen the
+ * screen; a schedule is typed by nobody. The OTA manifest is checked for its shape only (not signed) and replaces
+ * the bundle whole, so a rule set it carried could call an approval dialog `idle` and have the user's prompt plus
+ * Enter typed into it. Phone input and state reports keep using the OTA rules.
+ *
+ * One idle read is not enough either: a dialog can open after the composer is drawn (codex shows its start-up
+ * dialogs before the composer, but nothing promises every dialog does), and a read taken just before it opened says
+ * `idle`. So a session is ready only when two reads in a row — the last poll's and this one, taken right before the
+ * prompt is typed — show the same screen and the rules call it `idle`. Any change in between starts over. Digits are
+ * left out of the comparison, so a footer's clock, cost or token count does not keep a resting agent from ever being
+ * ready. The earlier read counts only while it is recent: a schedule's next run starts under the same session name,
+ * and its first read must not pair with the last screen of the run before.
+ */
+import { type DetectionManifest } from './agent-state.js';
+export interface ReadyDeps {
+    /** The pane's foreground program is the agent of this kind (not the shell it started from). */
+    foregroundIsAgent: (session: string, agentKind: string) => boolean;
+    /** The pane's text as it is now, or null when it cannot be read. */
+    screenOf: (session: string) => string | null;
+    /** The detection rules' verdict on that text. */
+    stateOf: (screen: string, agentKind: string) => string;
+    now?: () => number;
+}
+/** How old the earlier of the two reads may be: two polls, so one slow tick still pairs and a past run never does. */
+export declare const READ_PAIR_MAX_MS: number;
+/** Whether the rules in `manifest` can ever say `idle` for `kind`: a rule that is on, and that decides the state. */
+export declare const hasIdleRule: (manifest: DetectionManifest, kind: string) => boolean;
+/** The kinds among `kinds` that a prompt can be scheduled for. */
+export declare const promptableKinds: (manifest: DetectionManifest, kinds: readonly string[]) => string[];
+export declare const createReadyCheck: (deps: ReadyDeps) => ((session: string, agentKind: string) => boolean);
+/** Whether a schedule may carry a prompt for `kind`: the bundled rules have an `idle` rule for it. */
+export declare const canPromptKind: (kind: string) => boolean;
+/** `promptableKinds` over the bundled rules — what `schedule add --prompt` accepts. */
+export declare const promptableScheduleKinds: (kinds: readonly string[]) => string[];
+/** The state the bundled rules give a pane's text. */
+export declare const scheduleScreenState: (content: string, kind: string) => string;
+//# sourceMappingURL=schedule-ready.d.ts.map

package/dist/schedule-ready.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * Whether a scheduled session's agent may be typed at (F8). A prompt typed into a terminal that is still starting up
+ * is lost or lands in the wrong place, and one typed into a dialog answers it: Enter on a trust or permission prompt
+ * accepts the default, with nobody there to read it. So the only sign this feature accepts is the agent's own state
+ * rules saying `idle` for the screen as it is now. An agent without an `idle` rule is never typed at — a screen that
+ * has stopped changing proves nothing, a static dialog stops changing too.
+ *
+ * The rules are the bundled ones, never the OTA manifest. A phone's input is typed by a person who has seen the
+ * screen; a schedule is typed by nobody. The OTA manifest is checked for its shape only (not signed) and replaces
+ * the bundle whole, so a rule set it carried could call an approval dialog `idle` and have the user's prompt plus
+ * Enter typed into it. Phone input and state reports keep using the OTA rules.
+ *
+ * One idle read is not enough either: a dialog can open after the composer is drawn (codex shows its start-up
+ * dialogs before the composer, but nothing promises every dialog does), and a read taken just before it opened says
+ * `idle`. So a session is ready only when two reads in a row — the last poll's and this one, taken right before the
+ * prompt is typed — show the same screen and the rules call it `idle`. Any change in between starts over. Digits are
+ * left out of the comparison, so a footer's clock, cost or token count does not keep a resting agent from ever being
+ * ready. The earlier read counts only while it is recent: a schedule's next run starts under the same session name,
+ * and its first read must not pair with the last screen of the run before.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scheduleScreenState = exports.promptableScheduleKinds = exports.canPromptKind = exports.createReadyCheck = exports.promptableKinds = exports.hasIdleRule = exports.READ_PAIR_MAX_MS = void 0;
+const agent_rules_default_js_1 = require("./agent-rules.default.js");
+const agent_state_js_1 = require("./agent-state.js");
+const schedule_runner_js_1 = require("./schedule-runner.js");
+/** How old the earlier of the two reads may be: two polls, so one slow tick still pairs and a past run never does. */
+exports.READ_PAIR_MAX_MS = 2 * schedule_runner_js_1.PROMPT_POLL_MS;
+/** A screen as the two reads compare it: digits do not count. */
+const settledForm = (screen) => screen.replace(/\p{Nd}/gu, '0');
+/** Whether the rules in `manifest` can ever say `idle` for `kind`: a rule that is on, and that decides the state. */
+const hasIdleRule = (manifest, kind) => {
+    const disabled = new Set(manifest.disabledRuleIds ?? []);
+    return (manifest.agents[kind] ?? []).some((rule) => rule.state === 'idle' && !rule.skipStateUpdate && !disabled.has(rule.id));
+};
+exports.hasIdleRule = hasIdleRule;
+/** The kinds among `kinds` that a prompt can be scheduled for. */
+const promptableKinds = (manifest, kinds) => kinds.filter((kind) => (0, exports.hasIdleRule)(manifest, kind));
+exports.promptableKinds = promptableKinds;
+const createReadyCheck = (deps) => {
+    const now = deps.now ?? Date.now;
+    /** Per session, the idle screen the previous read saw and when. */
+    const lastIdle = new Map();
+    return (session, agentKind) => {
+        const screen = deps.foregroundIsAgent(session, agentKind) ? deps.screenOf(session) : null;
+        const previous = lastIdle.get(session);
+        if (screen === null || deps.stateOf(screen, agentKind) !== 'idle') {
+            lastIdle.delete(session);
+            return false;
+        }
+        const at = now();
+        const form = settledForm(screen);
+        if (previous?.screen !== form || at - previous.at > exports.READ_PAIR_MAX_MS) {
+            lastIdle.set(session, { screen: form, at });
+            return false;
+        }
+        // Spent: if the prompt then fails to go in, the next try reads twice again.
+        lastIdle.delete(session);
+        return true;
+    };
+};
+exports.createReadyCheck = createReadyCheck;
+/** Whether a schedule may carry a prompt for `kind`: the bundled rules have an `idle` rule for it. */
+const canPromptKind = (kind) => (0, exports.hasIdleRule)(agent_rules_default_js_1.DEFAULT_MANIFEST, kind);
+exports.canPromptKind = canPromptKind;
+/** `promptableKinds` over the bundled rules — what `schedule add --prompt` accepts. */
+const promptableScheduleKinds = (kinds) => (0, exports.promptableKinds)(agent_rules_default_js_1.DEFAULT_MANIFEST, kinds);
+exports.promptableScheduleKinds = promptableScheduleKinds;
+/** The state the bundled rules give a pane's text. */
+const scheduleScreenState = (content, kind) => (0, agent_state_js_1.evaluateState)(content, kind, agent_rules_default_js_1.DEFAULT_MANIFEST).state;
+exports.scheduleScreenState = scheduleScreenState;

package/dist/schedule-remote.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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.
+ */
+import { type ScheduleOutcome, type ScheduleWhen } from './schedule.js';
+import { type KnownSession } from './session-registry.js';
+/** One schedule as the app lists it. No directory path and no agent arguments: the phone never names or reads either. */
+export interface PhoneScheduleItem {
+    id: string;
+    source: 'cli' | 'phone';
+    agentKind: string;
+    /** The directory's name, not its path. */
+    project: string;
+    session: string;
+    when: ScheduleWhen;
+    prompt?: string;
+    maxRuntimeMin: number;
+    /** ISO time of the next run; null when there is none. */
+    nextAt: string | null;
+    last?: {
+        outcome: ScheduleOutcome;
+        at: string;
+    };
+}
+/** The longest prompt the list carries; the full text is in the file on this machine. */
+export declare const LIST_PROMPT_CHARS = 500;
+/** The sealed list must fit one relay frame (cf. `DIFF_SEALED_MAX_BYTES`), counted in UTF-8 bytes. */
+export declare const LIST_MAX_BYTES: number;
+/** What `phoneScheduleList` found: the schedules it could read, and how many files it could not. */
+export interface ScheduleListing {
+    schedules: PhoneScheduleItem[];
+    /** Files that were there but unreadable or invalid (`hwip schedule` says so on stderr). */
+    unreadable: number;
+}
+/** 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. */
+export declare const phoneScheduleList: (now: number, promptChars?: number) => ScheduleListing | null;
+/** The answer to a list request: what the app reads (the sealed text) and the list in it, or why there is none. */
+export type ScheduleAnswer = {
+    ok: true;
+    listing: ScheduleListing;
+    sealed: string;
+} | {
+    ok: false;
+    error: 'read_failed' | 'too_large';
+};
+/**
+ * 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.
+ */
+export declare const scheduleAnswer: (now: number, requestId: string, at: string) => ScheduleAnswer;
+/** The reasons a phone's schedule request is not carried out; they are `agent.command.refused` codes (`command-refusal.ts`). */
+export type PhoneScheduleRefusal = 'schedule_invalid' | 'schedule_limit' | 'schedule_failed' | 'unknown_session';
+export type PhoneScheduleResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: PhoneScheduleRefusal;
+    why: string;
+};
+export interface PhoneScheduleDeps {
+    now: () => number;
+    /** The newest run of that tmux name (of that agent, when given) this machine recorded. */
+    recall: (session: string, agentKind?: string) => KnownSession | null;
+    directoryExists: (entry: KnownSession) => boolean;
+    /** Whether the agent can be typed a prompt by a schedule (`schedule-ready.ts`). */
+    canPrompt: (agentKind: string) => boolean;
+}
+export declare const livePhoneScheduleDeps: PhoneScheduleDeps;
+/**
+ * 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.
+ */
+export declare const applyPhoneSchedule: (request: unknown, session: string, deps?: PhoneScheduleDeps) => PhoneScheduleResult;
+//# sourceMappingURL=schedule-remote.d.ts.map