@phnx-labs/agents-cli 1.20.92 → 1.21.0

package/dist/lib/channels/send.js

@@ -0,0 +1,112 @@
+import { registerBuiltinProviders } from './providers/index.js';
+import { resolveTransport } from './resolve.js';
+const OWNER_ALIAS = 'owner';
+/** True when the destination token means “the configured owner”. */
+export function isOwnerAlias(to) {
+    return (to ?? '').trim().toLowerCase() === OWNER_ALIAS;
+}
+/** Compose body + optional URL lines (skip urls already present in the body). */
+export function composeSendText(text, urls) {
+    const body = text.trim();
+    const extra = (urls ?? [])
+        .map((u) => u.trim())
+        .filter(Boolean)
+        .filter((u) => !body.includes(u));
+    if (extra.length === 0)
+        return body;
+    return body ? `${body}\n${extra.join('\n')}` : extra.join('\n');
+}
+/** Read notify.owner; null when either field is missing. */
+export function readOwnerDest(meta) {
+    const owner = meta.notify?.owner;
+    const channel = owner?.channel?.trim();
+    const to = owner?.to?.trim();
+    if (!channel || !to)
+        return null;
+    return { channel, to };
+}
+/**
+ * Resolve CLI/config into a send envelope. Pure except for reading `meta` —
+ * no I/O, no provider registration — so unit tests do not need a real PATH.
+ */
+export function resolveSendEnvelope(input, meta) {
+    const positional = (input.positionalText ?? '').trim();
+    const flagged = (input.text ?? '').trim();
+    if (positional && flagged && positional !== flagged) {
+        return {
+            ok: false,
+            error: 'Pass the message once: use --text, or a positional argument, not both with different values.',
+        };
+    }
+    const rawText = flagged || positional;
+    const urls = (input.urls ?? []).map((u) => u.trim()).filter(Boolean);
+    const text = composeSendText(rawText, urls);
+    if (!text) {
+        return {
+            ok: false,
+            error: 'Message is empty. Pass --text "…", a positional message, and/or --url.',
+        };
+    }
+    // Owner defaults fill only missing fields (and expand the bare "owner" alias).
+    // Explicit --channel/--to always win; a complete notify.owner is NOT required
+    // when both flags are already set (same merge-then-require shape as main).
+    const ownerCfg = meta.notify?.owner;
+    const ownerChannel = ownerCfg?.channel?.trim() || '';
+    const ownerTo = ownerCfg?.to?.trim() || '';
+    let channel = (input.channel ?? '').trim();
+    let to = (input.to ?? '').trim();
+    const usedOwnerAlias = isOwnerAlias(to);
+    if (input.ownerMode || usedOwnerAlias) {
+        if (!channel)
+            channel = ownerChannel;
+        if (!to || usedOwnerAlias)
+            to = ownerTo;
+    }
+    if (!channel || !to) {
+        const hint = input.ownerMode || usedOwnerAlias
+            ? 'Set notify.owner.{channel,to} in agents.yaml, or pass --channel and --to explicitly.'
+            : 'Need --channel and --to (or --to owner with notify.owner configured). ' +
+                'Example: agents send --channel desktop --to local --text "hi"';
+        return { ok: false, error: hint };
+    }
+    const attachments = [
+        ...(input.attachments ?? []),
+    ]
+        .map((p) => p.trim())
+        .filter(Boolean);
+    return {
+        ok: true,
+        envelope: {
+            text,
+            channel,
+            to,
+            thread: input.thread?.trim() || undefined,
+            attachments: attachments.length ? attachments : undefined,
+            from: input.from?.trim() || undefined,
+            dryRun: input.dryRun,
+        },
+    };
+}
+/**
+ * Register providers, resolve transport, deliver. Used by the CLI and by any
+ * internal caller that already has a resolved envelope.
+ */
+export async function deliverEnvelope(envelope, meta) {
+    registerBuiltinProviders();
+    const provider = resolveTransport(envelope.channel, meta);
+    return provider.send(envelope.text, {
+        target: envelope.to,
+        thread: envelope.thread,
+        attachments: envelope.attachments,
+        from: envelope.from,
+        dryRun: envelope.dryRun,
+    });
+}
+/** Resolve + deliver in one step (CLI happy path). */
+export async function sendMessage(input, meta) {
+    const resolved = resolveSendEnvelope(input, meta);
+    if (!resolved.ok)
+        return { error: resolved.error };
+    const result = await deliverEnvelope(resolved.envelope, meta);
+    return { result, envelope: resolved.envelope };
+}

package/dist/lib/daemon.d.ts

@@ -16,6 +16,19 @@ import { getAgentsBinPath } from './cli-entry.js';
  * broker is hosting, and never clobber a reachable (healthy) broker.
  */
 export declare function shouldTakeOverBroker(isHosting: boolean, brokerReachable: boolean): boolean;
+/**
+ * What a gate re-evaluation must do with the routines scheduler. The daemon
+ * re-evaluates `scheduler.enabled` on every SIGHUP reload so flipping the key
+ * takes effect without a daemon restart (and `routines add`'s reload signal on
+ * a re-enabled box boots the scheduler — the reload is truthful, not a no-op).
+ *
+ *   running + enabled   → reload (the normal SIGHUP path)
+ *   running + !enabled  → stop  (gate flipped off since boot)
+ *   !running + enabled  → boot  (gate flipped on since boot)
+ *   !running + !enabled → none  (stay dark)
+ */
+export type SchedulerGateTransition = 'reload' | 'stop' | 'boot' | 'none';
+export declare function schedulerGateTransition(running: boolean, enabled: boolean): SchedulerGateTransition;
 /** Read the stored daemon PID from disk. Returns null if not present or invalid. */
 export declare function readDaemonPid(): number | null;
 /** Write the daemon PID to the pid file. */

package/dist/lib/daemon.js

@@ -24,6 +24,7 @@ import { BrowserService } from './browser/service.js';
 import { BrowserIPCServer } from './browser/ipc.js';
 import { redactSecrets } from './redact.js';
 import { getAgentsBinPath, getCliLaunch, BUN_VIRTUAL_ROOT } from './cli-entry.js';
+import { isSchedulerEnabled, assertSchedulerEnabled } from './device-config.js';
 const PID_FILE = 'daemon.pid';
 const LOCK_FILE = 'daemon.lock';
 const LOG_FILE = 'logs.jsonl';
@@ -53,6 +54,11 @@ const WEDGE_THRESHOLD_TICKS = 3;
 export function shouldTakeOverBroker(isHosting, brokerReachable) {
     return !isHosting && !brokerReachable;
 }
+export function schedulerGateTransition(running, enabled) {
+    if (running)
+        return enabled ? 'reload' : 'stop';
+    return enabled ? 'boot' : 'none';
+}
 function getDaemonDir() {
     const dir = getDaemonDirRoot();
     fs.mkdirSync(dir, { recursive: true });
@@ -398,7 +404,7 @@ export async function runDaemon() {
         log('ERROR', `Stray daemon reaper failed: ${err.message}`);
     }
     // #416: host the secrets broker socket-first — before the scheduler and the
-    // heavy browser/session-sync services — so `agents secrets` resolves within
+    // heavy browser services — so `agents secrets` resolves within
     // ms of daemon start. Only host when no broker is already reachable, so we
     // never orphan a live standalone broker's clients (that broker stays the
     // server until it idle-exits or the daemon restarts). Best-effort: a failure
@@ -419,7 +425,23 @@ export async function runDaemon() {
     catch (err) {
         log('WARN', `Secrets broker host skipped: ${err.message}`);
     }
-    const scheduler = new JobScheduler(async (config) => {
+    // scheduler.enabled=false in this machine's device doc means NO routines fire
+    // here — the scheduler and its catchup recovery simply never start, while the
+    // daemon keeps its other duties (secrets broker, browser IPC, session sync).
+    // The refusal message is the same one the start surfaces
+    // (`routines add` auto-start, manual `routines start`) raise. The gate is
+    // re-evaluated on every SIGHUP reload (handleReload below) via
+    // schedulerGateTransition, so flipping the key never needs a daemon restart.
+    const schedulerEnabledAtBoot = isSchedulerEnabled();
+    if (!schedulerEnabledAtBoot) {
+        try {
+            assertSchedulerEnabled();
+        }
+        catch (err) {
+            log('WARN', err.message);
+        }
+    }
+    const triggerJob = async (config) => {
         const jobLabel = config.command
             ? 'command'
             : config.workflow
@@ -458,7 +480,36 @@ export async function runDaemon() {
             }
             catch { /* best-effort */ }
         }
-    });
+    };
+    let scheduler = null;
+    let catchupInterval;
+    // Catchup overlap guard. Declared up here (not beside catchupPass) because
+    // bootScheduler() runs before catchupPass's textual position — a `let` down
+    // there would still be in its TDZ at the first call and crash the daemon.
+    let catchingUp = false;
+    // Boot the scheduler + catchup recovery. Called at daemon start when the gate
+    // allows, and again from handleReload when the gate flips on (function
+    // declarations hoist — catchupPass below is in scope).
+    function bootScheduler() {
+        scheduler = new JobScheduler(triggerJob);
+        scheduler.loadAll();
+        const scheduled = scheduler.listScheduled();
+        log('INFO', `Loaded ${scheduled.length} jobs`);
+        for (const job of scheduled) {
+            log('INFO', `  ${job.name} -> next: ${job.nextRun?.toISOString() || 'unknown'}`);
+        }
+        void catchupPass();
+        catchupInterval = setInterval(() => { void catchupPass(); }, CATCHUP_TICK_MS);
+    }
+    // Stop the scheduler + catchup recovery (gate flipped off on reload).
+    function stopScheduler() {
+        scheduler?.stopAll();
+        scheduler = null;
+        if (catchupInterval !== undefined) {
+            clearInterval(catchupInterval);
+            catchupInterval = undefined;
+        }
+    }
     // Materialise opted-in project routines into the user layer on every start
     // so a fresh daemon picks up project YAML without a separate sync step.
     try {
@@ -470,12 +521,8 @@ export async function runDaemon() {
     catch (err) {
         log('WARN', `Project routines sync failed: ${err.message}`);
     }
-    scheduler.loadAll();
-    const scheduled = scheduler.listScheduled();
-    log('INFO', `Loaded ${scheduled.length} jobs`);
-    for (const job of scheduled) {
-        log('INFO', `  ${job.name} -> next: ${job.nextRun?.toISOString() || 'unknown'}`);
-    }
+    if (schedulerEnabledAtBoot)
+        bootScheduler();
     // Monitor engine: event-triggered watchers, beside the cron scheduler. Same
     // daemon, same dispatch seam — a monitor is a routine whose trigger is a
     // watched source instead of a clock. Reloads on SIGHUP alongside the scheduler.
@@ -495,15 +542,16 @@ export async function runDaemon() {
     // `catchup: false`, RUN late. Runs on a timer as well as at startup: a startup
     // pass alone misses a fire lost while the daemon stayed up but its event loop
     // was wedged, or one lost across an OS suspend that the process survived.
-    // Overlap guard, same shape as runSessionSync/runHealCheck below. A pass
+    // Overlap guard, same shape as runHealCheck below. A pass
     // awaits executeJobDetached per job and an off-box (host/cloud) dispatch can
     // block for a while, so a slow pass could still be working when the next tick
     // fires. Both passes would then see a job the first has not yet reached as
     // overdue — the miss is recorded before the await, but only for jobs already
     // processed — and spawn it twice. The idempotency of the `missed` record
     // guards across passes, not within one that is mid-flight.
-    let catchingUp = false;
-    const catchupPass = async () => {
+    // Function declaration (hoisted) so bootScheduler() can schedule it. Its
+    // guard (`catchingUp`) is declared beside `scheduler` above for TDZ safety.
+    async function catchupPass() {
         if (catchingUp)
             return;
         catchingUp = true;
@@ -553,9 +601,7 @@ export async function runDaemon() {
             // throw must not leave the guard latched shut for the daemon's lifetime.
             catchingUp = false;
         }
-    };
-    await catchupPass();
-    const catchupInterval = setInterval(() => { void catchupPass(); }, CATCHUP_TICK_MS);
+    }
     // Before the BrowserService comes up, reap browser + tunnel processes
     // spawned by previous daemons that are no longer alive. Without this,
     // a daemon hard-crash (SIGKILL, OOM) would leak every browser and SSH
@@ -588,42 +634,6 @@ export async function runDaemon() {
         writeHeartbeat();
         monitorRunningJobs();
     }, MONITOR_TICK_MS);
-    // Cross-machine session sync: push this machine's transcripts to R2 and pull
-    // every other machine's, ~every 90s. Skipped silently when the r2.backups
-    // bundle is absent. An overlap guard prevents a slow cycle from stacking.
-    let syncing = false;
-    const runSessionSync = async () => {
-        if (syncing)
-            return;
-        syncing = true;
-        try {
-            const { isBetaEnabled } = await import('./beta.js');
-            // Off by default: session sync is an opt-in beta feature. Check the beta
-            // flag FIRST so a machine that hasn't opted in skips the keychain read
-            // (isSyncConfigured) entirely, not just the network cycle.
-            if (!isBetaEnabled('session-sync'))
-                return;
-            const { isSyncConfigured } = await import('./session/sync/config.js');
-            if (!isSyncConfigured())
-                return;
-            const { syncSessions } = await import('./session/sync/sync.js');
-            const r = await syncSessions();
-            if (r.pushed || r.pulled || r.errors.length) {
-                log('INFO', `sessions sync: pushed ${r.pushed}, pulled ${r.pulled}, merged ${r.merged}` +
-                    (r.errors.length ? `, ${r.errors.length} error(s): ${r.errors[0]}` : ''));
-            }
-            if (r.warnings.length)
-                log('WARN', `sessions sync: ${r.warnings[0]}`);
-        }
-        catch (err) {
-            log('ERROR', `sessions sync failed: ${err.message}`);
-        }
-        finally {
-            syncing = false;
-        }
-    };
-    const syncInterval = setInterval(() => { void runSessionSync(); }, 90_000);
-    void runSessionSync(); // kick once at startup
     // Resource safety check: heal gaps between what DotAgents repos define and
     // what's actually installed in each agent home — the slow rot that nothing
     // else catches (a non-default version left stale, a Claude-invalid plugin
@@ -875,27 +885,37 @@ export async function runDaemon() {
         catch (err) {
             log('WARN', `Project routines sync failed: ${err.message}`);
         }
-        scheduler.reloadAll();
-        const reloaded = scheduler.listScheduled();
-        log('INFO', `Reloaded ${reloaded.length} jobs`);
+        // Re-evaluate the scheduler.enabled gate: flipping the key takes effect on
+        // this reload, no daemon restart needed. A `routines add` on a re-enabled
+        // box signals exactly this reload, which boots the scheduler — the
+        // "Scheduler reloaded" it prints is then truthful, not a dead-end.
+        const transition = schedulerGateTransition(scheduler !== null, isSchedulerEnabled());
+        if (transition === 'boot') {
+            log('INFO', 'scheduler.enabled is now on — booting the scheduler');
+            bootScheduler();
+        }
+        else if (transition === 'stop') {
+            log('WARN', 'scheduler.enabled is now off — stopping the scheduler; no routines will fire on this device');
+            stopScheduler();
+        }
+        else if (transition === 'reload') {
+            scheduler.reloadAll();
+            const reloaded = scheduler.listScheduled();
+            log('INFO', `Reloaded ${reloaded.length} jobs`);
+        }
         try {
             monitorEngine.reload();
         }
         catch (err) {
             log('ERROR', `Monitor engine reload failed: ${err.message}`);
         }
-        // Drop the memoized R2 config so rotated/added sync credentials are re-read
-        // on the next cycle instead of waiting for a restart.
-        void import('./session/sync/config.js').then(m => m.clearR2ConfigCache());
     };
     const handleShutdown = async () => {
         log('INFO', 'Daemon shutting down');
-        scheduler.stopAll();
+        stopScheduler();
         monitorEngine.stop();
         await browserIPC.stop();
         clearInterval(monitorInterval);
-        clearInterval(catchupInterval);
-        clearInterval(syncInterval);
         clearInterval(healInterval);
         clearTimeout(healKickoff);
         clearInterval(autoDispatchInterval);

package/dist/lib/device-config.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Device/user config keys — typed read/write over the two-tier agents.yaml store.
+ *
+ * One registry (`CONFIG_KEYS`) maps each CLI dotted name to where it lives:
+ *   - user scope   → central `~/.agents/agents.yaml` under `config:` (syncs
+ *                    fleet-wide via `agents repo push/pull`)
+ *   - device scope → `~/.agents/devices/<host>/agents.yaml` under `config:`
+ *                    (per-machine; mirrors how `defaultBrowserProfile` is routed)
+ *
+ * This machine's keys go through the readMeta/updateMeta funnel (state.ts) so the
+ * partition/overlay logic stays the single writer. Another device's doc is
+ * read/written in place — the devices/ tree syncs via the DotAgents repo, so
+ * editing `devices/mac-mini/agents.yaml` locally is how `configure`/`note`
+ * target a peer (`--device`-style).
+ *
+ * `browser.profile` is NOT a `config:` key — it is the existing
+ * `Meta.defaultBrowserProfile` field; the registry entry documents the mapping
+ * and set/get route to it so there is one source of truth (no duplicate key).
+ *
+ * Unset always means today's behavior.
+ */
+/** Which tier of the agents.yaml store a key lives in. */
+export type ConfigScope = 'user' | 'device';
+/** Value type of a config key — drives validation and `--json` rendering. */
+export type ConfigType = 'string' | 'int' | 'bool' | 'string-list';
+/** One known config key. */
+export interface ConfigKeySpec {
+    /** CLI dotted name, e.g. `interactive.host`. */
+    name: string;
+    /** camelCase key under the YAML `config:` block. */
+    yamlKey: string;
+    scope: ConfigScope;
+    type: ConfigType;
+    /** One-line description for help/list output. */
+    description: string;
+    /**
+     * When set, the value lives in this top-level Meta field instead of the
+     * `config:` block (only `browser.profile` → `defaultBrowserProfile` today).
+     */
+    field?: 'defaultBrowserProfile';
+    /** Extra validation beyond the type check; return an error string or null. */
+    validate?: (value: unknown) => string | null;
+}
+/** A key with its resolved value and the layer that set it. */
+export interface ConfigEntry {
+    spec: ConfigKeySpec;
+    /** The stored value, or undefined when unset (unset = default behavior). */
+    value: unknown;
+    /** Which layer set it; undefined when unset. */
+    layer?: ConfigScope;
+}
+/** Options scoping a read/write to a specific device's doc (default: this machine). */
+export interface ConfigTarget {
+    device?: string;
+}
+export declare const CONFIG_KEYS: readonly ConfigKeySpec[];
+/** Look up a key spec by CLI dotted name, or throw listing the known keys. */
+export declare function configKeySpec(name: string): ConfigKeySpec;
+/** Get one config key's value and the layer that set it. */
+export declare function getConfigValue(name: string, opts?: ConfigTarget): ConfigEntry;
+/** List every known key with its value and the layer that set it. */
+export declare function listConfig(opts?: ConfigTarget): ConfigEntry[];
+/** Set a config key (validated). Device-scope keys target this machine unless `opts.device` names a peer. */
+export declare function setConfigValue(name: string, value: unknown, opts?: ConfigTarget): void;
+/** Unset a config key — restores default behavior. No-op when already unset. */
+export declare function unsetConfigValue(name: string, opts?: ConfigTarget): void;
+/** True unless this machine's device doc disables the routines scheduler. */
+export declare function isSchedulerEnabled(): boolean;
+/**
+ * Throw when the routines scheduler is disabled on this machine, naming the
+ * setting and the fix. The single message every scheduler-start surface
+ * (auto-start on `routines add`, manual `routines start`, the daemon's own
+ * scheduler init) refuses with.
+ */
+export declare function assertSchedulerEnabled(): void;
+/**
+ * Read the `agents.max-concurrent` cap for each named device from its synced
+ * device doc (no SSH). Devices without a cap are omitted — uncapped is the
+ * default. Used as an input to host ranking (teams placement, Factory
+ * auto-launch), never as a remote probe.
+ */
+export declare function readMaxConcurrentCaps(devices: string[]): Record<string, number>;