@phnx-labs/agents-cli 1.20.82 → 1.20.84

package/dist/lib/routines.js

@@ -586,6 +586,122 @@ export function isPastEndAt(config, now = new Date()) {
         return false;
     return now.getTime() >= end;
 }
+export function parseOneShotLikeSchedule(schedule) {
+    if (!schedule)
+        return null;
+    const parts = schedule.trim().split(/\s+/);
+    if (parts.length !== 5)
+        return null;
+    const [minuteRaw, hourRaw, dayRaw, monthRaw, weekdayRaw] = parts;
+    if (weekdayRaw !== '*')
+        return null;
+    if (![minuteRaw, hourRaw, dayRaw, monthRaw].every((p) => /^\d+$/.test(p)))
+        return null;
+    const minute = parseInt(minuteRaw, 10);
+    const hour = parseInt(hourRaw, 10);
+    const day = parseInt(dayRaw, 10);
+    const month = parseInt(monthRaw, 10);
+    if (minute < 0 || minute > 59)
+        return null;
+    if (hour < 0 || hour > 23)
+        return null;
+    if (month < 1 || month > 12)
+        return null;
+    if (day < 1 || day > 31)
+        return null;
+    return { minute, hour, day, month };
+}
+export function isOneShotLikeSchedule(schedule) {
+    return parseOneShotLikeSchedule(schedule) !== null;
+}
+export function isOneShotRoutine(config) {
+    return Boolean(config.runOnce || isOneShotLikeSchedule(config.schedule));
+}
+function zonedParts(date, timezone) {
+    const parts = new Intl.DateTimeFormat('en-US', {
+        timeZone: timezone,
+        year: 'numeric',
+        month: 'numeric',
+        day: 'numeric',
+        hour: 'numeric',
+        minute: 'numeric',
+        hour12: false,
+        hourCycle: 'h23',
+    }).formatToParts(date);
+    const get = (type) => parseInt(parts.find((p) => p.type === type)?.value ?? '0', 10);
+    return {
+        year: get('year'),
+        month: get('month'),
+        day: get('day'),
+        hour: get('hour'),
+        minute: get('minute'),
+    };
+}
+function zonedDateToUtc(year, parts, timezone) {
+    const targetUtc = Date.UTC(year, parts.month - 1, parts.day, parts.hour, parts.minute, 0, 0);
+    let candidate = new Date(targetUtc);
+    for (let i = 0; i < 4; i++) {
+        const actual = zonedParts(candidate, timezone);
+        const actualUtc = Date.UTC(actual.year, actual.month - 1, actual.day, actual.hour, actual.minute, 0, 0);
+        const delta = actualUtc - targetUtc;
+        if (delta === 0)
+            break;
+        candidate = new Date(candidate.getTime() - delta);
+    }
+    const verify = zonedParts(candidate, timezone);
+    if (verify.year !== year ||
+        verify.month !== parts.month ||
+        verify.day !== parts.day ||
+        verify.hour !== parts.hour ||
+        verify.minute !== parts.minute) {
+        return null;
+    }
+    return candidate;
+}
+export function oneShotScheduleFireDate(schedule, now = new Date(), timezone) {
+    const parts = parseOneShotLikeSchedule(schedule);
+    if (!parts)
+        return null;
+    if (timezone) {
+        try {
+            const year = zonedParts(now, timezone).year;
+            return zonedDateToUtc(year, parts, timezone);
+        }
+        catch {
+            return null;
+        }
+    }
+    const fireAt = new Date(now.getFullYear(), parts.month - 1, parts.day, parts.hour, parts.minute, 0, 0);
+    if (fireAt.getFullYear() !== now.getFullYear() ||
+        fireAt.getMonth() !== parts.month - 1 ||
+        fireAt.getDate() !== parts.day ||
+        fireAt.getHours() !== parts.hour ||
+        fireAt.getMinutes() !== parts.minute) {
+        return null;
+    }
+    return fireAt;
+}
+export function isPastOneShotRoutine(config, now = new Date()) {
+    if (!isOneShotRoutine(config))
+        return false;
+    const fireAt = oneShotScheduleFireDate(config.schedule, now, config.timezone);
+    return Boolean(fireAt && now.getTime() >= fireAt.getTime());
+}
+export function hasCompletedOneShotRun(config, now = new Date()) {
+    if (!isPastOneShotRoutine(config, now))
+        return false;
+    const fireAt = oneShotScheduleFireDate(config.schedule, now, config.timezone);
+    if (!fireAt)
+        return false;
+    const latest = getLatestRun(config.name);
+    if (!latest || latest.status === 'running')
+        return false;
+    const startedAt = Date.parse(latest.startedAt);
+    return Number.isFinite(startedAt) && startedAt >= fireAt.getTime() - 60_000;
+}
+export function shouldPurgeCompletedOneShotRoutine(config, now = new Date()) {
+    return hasCompletedOneShotRun(config, now);
+}
 /** Expand built-in and user-defined template variables in a job's prompt string. */
 export function resolveJobPrompt(config) {
     const now = new Date();

package/dist/lib/scheduler.js

@@ -6,7 +6,7 @@
  * on startup and reloads them on SIGHUP.
  */
 import { Cron } from 'croner';
-import { listJobs, deleteJob, isPastEndAt, setJobEnabled, jobRunsOnThisDevice } from './routines.js';
+import { listJobs, deleteJob, isPastEndAt, isPastOneShotRoutine, isOneShotRoutine, setJobEnabled, shouldPurgeCompletedOneShotRoutine, jobRunsOnThisDevice, } from './routines.js';
 /** In-memory cron scheduler that triggers a callback when jobs fire. */
 export class JobScheduler {
     jobs = new Map();
@@ -20,9 +20,15 @@ export class JobScheduler {
             // Trigger-only jobs (no cron schedule) fire via the webhook receiver,
             // not the cron loop — skip them here. Jobs pinned to another device
             // (routines are fleet-synced) never enter this machine's cron loop.
-            if (config.enabled && config.schedule && jobRunsOnThisDevice(config)) {
-                this.schedule(config);
+            if (!config.enabled || !config.schedule || !jobRunsOnThisDevice(config))
+                continue;
+            if (shouldPurgeCompletedOneShotRoutine(config)) {
+                deleteJob(config.name);
+                continue;
             }
+            if (isPastOneShotRoutine(config))
+                continue;
+            this.schedule(config);
         }
     }
     schedule(config) {
@@ -30,6 +36,12 @@ export class JobScheduler {
         if (!config.schedule)
             return;
         this.unschedule(config.name);
+        if (shouldPurgeCompletedOneShotRoutine(config)) {
+            deleteJob(config.name);
+            return;
+        }
+        if (isPastOneShotRoutine(config))
+            return;
         // catch: true — a throw from one job's callback should not kill the
         // whole cron loop. Each invocation of onTrigger is already wrapped in
         // try/catch, but a synchronous throw before the await would otherwise
@@ -59,7 +71,7 @@ export class JobScheduler {
                 console.error(`Job '${config.name}' failed:`, err.message);
             }
             // One-shot jobs: remove after first execution
-            if (config.runOnce) {
+            if (isOneShotRoutine(config)) {
                 this.unschedule(config.name);
                 deleteJob(config.name);
             }

package/dist/lib/session/active.d.ts

@@ -147,6 +147,26 @@ export interface ActiveSession {
      */
     machine?: string;
     teamName?: string;
+    /**
+     * For a teams teammate: the session id of the ORCHESTRATOR that spawned the
+     * team (the agent that ran `agents teams add`, captured from AGENTS_SESSION_ID
+     * at spawn). Lets the listing answer "which session spun up this team" and
+     * group teammates under their orchestrator. Distinct from `sessionId`, which is
+     * the teammate's OWN transcript.
+     */
+    orchestratorSessionId?: string;
+    /** Display label for the orchestrator (its topic/label), resolved when the
+     * orchestrator is itself present in the active set. Display-only. */
+    orchestratorLabel?: string;
+    /**
+     * For a teams teammate: a one-line summary of the mission it was spawned with
+     * (the `prompt` stored on the teammate record — the team's task/target), so the
+     * listing answers "what is this team working on", not just its name. Survives
+     * before the teammate has produced any transcript (a pending/staged teammate
+     * still shows its target). Distinct from `topic`, which is derived from the
+     * teammate's own transcript once it starts.
+     */
+    assignedTask?: string;
     agentId?: string;
     cloudProvider?: string;
     cloudTaskId?: string;
@@ -327,6 +347,12 @@ interface LiveSignals {
  * {@link resolveFallbackStatus} reports the honest live floor (`running`).
  */
 export declare function computeLiveSignals(kind: string, sessionFile: string | undefined, cwd: string | undefined, pidAlive: boolean): LiveSignals;
+/**
+ * One-line summary of a teammate's spawn prompt — the team's task/target. Takes
+ * the first non-empty line, strips a leading `MISSION:`/`CONTEXT:`/`TASK:` label,
+ * and truncates. Exported for tests.
+ */
+export declare function summarizeMission(prompt: string | null | undefined): string | undefined;
 /** Live teams teammates. Reuses AgentManager which already polls PIDs via `kill -0`. */
 export declare function listTeamsActive(): Promise<ActiveSession[]>;
 /** Live editor-terminal agents across every IDE window. */
@@ -445,6 +471,13 @@ export declare function listTmuxAgentSessions(): Promise<ActiveSession[]>;
  * terminal/headless row for the same session id.
  */
 export declare function getActiveSessions(opts?: ActiveQueryOptions): Promise<ActiveSession[]>;
+/**
+ * Resolve each teams row's `orchestratorLabel` from the orchestrator's own row,
+ * when that orchestrator session is itself in the active set (it usually is — the
+ * agent that ran `agents teams add` is running). Falls back to nothing, so the
+ * renderer shows the short id. Pure over the array; exported for tests.
+ */
+export declare function annotateOrchestratorLabels(sessions: ActiveSession[]): void;
 /**
  * Match an SSH client IP to a registered device (pure — testable with a plain
  * registry object). Returns the device name + ssh login user when the IP is a

package/dist/lib/session/active.js

@@ -576,21 +576,45 @@ function quickExtractTopic(sessionFile) {
     }
     return undefined;
 }
+/**
+ * One-line summary of a teammate's spawn prompt — the team's task/target. Takes
+ * the first non-empty line, strips a leading `MISSION:`/`CONTEXT:`/`TASK:` label,
+ * and truncates. Exported for tests.
+ */
+export function summarizeMission(prompt) {
+    if (!prompt)
+        return undefined;
+    const firstLine = prompt.split('\n').map((l) => l.trim()).find(Boolean);
+    if (!firstLine)
+        return undefined;
+    const cleaned = firstLine.replace(/^(MISSION|CONTEXT|TASK|GOAL|OBJECTIVE)\s*[:\-—]\s*/i, '').trim();
+    if (!cleaned)
+        return undefined;
+    return cleaned.length > 80 ? `${cleaned.slice(0, 79)}…` : cleaned;
+}
 /** Live teams teammates. Reuses AgentManager which already polls PIDs via `kill -0`. */
 export async function listTeamsActive() {
     const mgr = new AgentManager();
     const running = await mgr.listRunning();
     return running.map((a) => {
-        const sessionId = a.parentSessionId ?? a.remoteSessionId ?? undefined;
-        const sessionFile = findSessionFileForKind(a.agentType, a.cwd ?? undefined, sessionId ?? undefined);
+        // The teammate's OWN transcript is `remoteSessionId` (captured from its first
+        // stream event). `parentSessionId` is the ORCHESTRATOR that spawned the team
+        // (AGENTS_SESSION_ID at spawn) — a link, not this teammate's id. Keying the
+        // row off the orchestrator conflated the two (a teammate showed the
+        // orchestrator's id/topic and lineage was invisible); resolve the teammate's
+        // own session for the row and expose the orchestrator separately.
+        const ownSessionId = a.remoteSessionId ?? undefined;
+        const sessionFile = findSessionFileForKind(a.agentType, a.cwd ?? undefined, ownSessionId);
         const topic = sessionFile ? quickExtractTopic(sessionFile) : undefined;
         const pidAlive = a.pid ? isPidAlive(a.pid) : true;
         const { state, tokPerSec } = computeLiveSignals(a.agentType, sessionFile, a.cwd ?? undefined, pidAlive);
+        const resolvedId = ownSessionId ?? sessionIdFromFile(sessionFile);
         return applyState({
             context: 'teams',
             kind: a.agentType,
             pid: a.pid ?? undefined,
-            sessionId: sessionId ?? sessionIdFromFile(sessionFile),
+            sessionId: resolvedId,
+            orchestratorSessionId: a.parentSessionId ?? undefined,
             cwd: a.cwd ?? undefined,
             label: a.name ?? undefined,
             topic,
@@ -599,11 +623,12 @@ export async function listTeamsActive() {
             startedAtMs: a.startedAt.getTime(),
             lastActivityMs: sessionFileTimes(sessionFile).mtimeMs,
             teamName: a.taskName,
+            assignedTask: summarizeMission(a.prompt),
             agentId: a.agentId,
             // The frozen actor stamped on the teammate record (RUSH-2028) — who ran
             // this teammate, surfaced as the owner in --active (RUSH-2018); sidecar
             // fallback for a teammate record predating the actor field.
-            owner: resolveOwner(a.actor, sessionId ?? sessionIdFromFile(sessionFile)),
+            owner: resolveOwner(a.actor, resolvedId),
         }, state, sessionFile, pidAlive);
     });
 }
@@ -1287,8 +1312,28 @@ export async function getActiveSessions(opts = {}) {
     await enrichProvenance(merged);
     await resolveOrigins(merged);
     foldPresence(merged);
+    annotateOrchestratorLabels(merged);
     return merged;
 }
+/**
+ * Resolve each teams row's `orchestratorLabel` from the orchestrator's own row,
+ * when that orchestrator session is itself in the active set (it usually is — the
+ * agent that ran `agents teams add` is running). Falls back to nothing, so the
+ * renderer shows the short id. Pure over the array; exported for tests.
+ */
+export function annotateOrchestratorLabels(sessions) {
+    const byId = new Map();
+    for (const s of sessions)
+        if (s.sessionId)
+            byId.set(s.sessionId, s);
+    for (const s of sessions) {
+        if (!s.orchestratorSessionId)
+            continue;
+        const orch = byId.get(s.orchestratorSessionId);
+        if (orch)
+            s.orchestratorLabel = orch.label || orch.topic || undefined;
+    }
+}
 /**
  * Fold detach/attach presence onto each row from the detach store. A stored
  * record wins (`background`/`parked`); otherwise a live terminal session is

package/dist/lib/state.js

@@ -619,6 +619,62 @@ function writeIfChanged(filePath, content) {
  * All callers funnel through writeMeta → here, so nothing else changes. Empty
  * `agents:` / `versions:` are not written (no empty committed files).
  */
+/**
+ * Serialize the central (synced) meta to `agents.yaml` WITHOUT destroying the
+ * hand-written comments in the committed file.
+ *
+ * `yaml.stringify(central)` drops every comment, so the freshly-written bytes
+ * never equal the comment-annotated file on disk — `writeIfChanged`'s byte
+ * compare then rewrites on EVERY meta write, leaving `agents.yaml` perpetually
+ * dirty and wedging `agents sync` ("Blocked by local changes"). Instead we parse
+ * the existing file into a `yaml.Document` (which preserves comments + ordering)
+ * and edit only the keys that actually changed — untouched keys, and all their
+ * comments, are left byte-stable. If nothing central changed we return the exact
+ * existing bytes, so a device-field-only write no longer touches `agents.yaml` at
+ * all. Falls back to plain stringify only when the file doesn't exist yet.
+ */
+function serializeCentral(central) {
+    const isEmpty = Object.keys(central).length === 0;
+    let existing = null;
+    try {
+        existing = fs.readFileSync(META_FILE, 'utf-8');
+    }
+    catch {
+        /* first write — no file yet */
+    }
+    if (existing == null) {
+        // Empty central → header only. `yaml.stringify({})` emits `{}` (a FLOW empty
+        // map); once that lands on disk, a later parseDocument sees a flow root and
+        // doc.set() below would inherit flow, flow-ifying the whole file. Writing just
+        // the header avoids seeding that poison.
+        return isEmpty ? META_HEADER : META_HEADER + yaml.stringify(central);
+    }
+    const doc = yaml.parseDocument(existing);
+    const current = doc.toJSON() ?? {};
+    let changed = false;
+    for (const [k, v] of Object.entries(central)) {
+        if (JSON.stringify(current[k]) !== JSON.stringify(v)) {
+            doc.set(k, v);
+            changed = true;
+        }
+    }
+    for (const k of Object.keys(current)) {
+        if (!(k in central)) {
+            doc.delete(k);
+            changed = true;
+        }
+    }
+    // No central field changed → keep the file byte-identical (comments intact), so
+    // writeIfChanged skips it and the churn loop never starts.
+    if (!changed)
+        return existing;
+    // Everything cleared → header only (never leave a flow `{}` behind).
+    // Otherwise force BLOCK style: an existing flow root (e.g. a legacy `{}`) would
+    // otherwise make the edited nodes render flow (`disabledCommands: [ teams ]`
+    // instead of a `- teams` block list). collectionStyle pins the whole doc block
+    // while parseDocument still preserves comments + key ordering.
+    return isEmpty ? META_HEADER : doc.toString({ collectionStyle: 'block' });
+}
 function writeMetaUnlocked(meta) {
     const { agents, isolatedAgents, versions, defaultBrowserProfile, ...central } = meta;
     // Write the machine-local files FIRST, then strip central — so a crash mid-write
@@ -656,7 +712,7 @@ function writeMetaUnlocked(meta) {
         fs.mkdirSync(path.dirname(vrPath), { recursive: true });
         writeIfChanged(vrPath, JSON.stringify(versions, null, 2) + '\n');
     }
-    writeIfChanged(META_FILE, META_HEADER + yaml.stringify(central));
+    writeIfChanged(META_FILE, serializeCentral(central));
     metaCache = null;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.82",
+  "version": "1.20.84",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",
@@ -55,6 +55,7 @@
     "start": "node dist/index.js",
     "test": "node ./node_modules/vitest/vitest.mjs run",
     "test:remote": "scripts/sandbox.sh 'bun install && bun run build && bun run test'",
+    "verify-docs": "scripts/verify-docs.sh",
     "test:watch": "node ./node_modules/vitest/vitest.mjs"
   },
   "keywords": [