@phnx-labs/agents-cli 1.20.90 → 1.20.92

package/dist/lib/projects.js

@@ -0,0 +1,301 @@
+/**
+ * Named project definitions — the layer above the `--project <slug>` convention.
+ *
+ * `agents run --project <slug>` already resolves a bare name to a working
+ * directory by pure convention (`<projectRoot>/<slug>`, see `project-root.ts`).
+ * This module adds editable definitions on top: one YAML file per project under
+ * `~/.agents/projects/<name>.yaml`, sitting beside the existing `routines/`,
+ * `monitors/`, and `teams/` dirs in the user repo (so definitions sync across
+ * machines for free via `agents push/pull`). A defined project can name itself
+ * independently of its folder, bind more than one repo, pin a monorepo subpath,
+ * describe context subdirectories an agent should start from, carry a Linear
+ * link and external integrations, and set an explicit default path.
+ *
+ * Portable by construction: `root`/`defaultPath` are stored home-relative
+ * (`~/…`) via `toHomeRelative`, so the same definition re-roots on any machine
+ * whose home differs — the exact mechanism `project-root.ts` already relies on.
+ *
+ * Resolution stays additive: an undefined slug still resolves exactly as today
+ * (see `resolveProjectRef`), a defined one overrides it.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { getProjectsDir } from './state.js';
+import { safeJoin } from './paths.js';
+import { toHomeRelative, expandLocalHome } from './project-root.js';
+import { resolveProjectKey } from './project-key.js';
+/** A project name safe to use as a filename: no separators, `..`, or leading dot. */
+export function isSafeProjectName(name) {
+    return (typeof name === 'string' &&
+        name.length > 0 &&
+        name.length <= 64 &&
+        /^[a-z0-9][a-z0-9._-]*$/i.test(name) &&
+        name !== '.' &&
+        name !== '..');
+}
+/** Absolute path to a project's YAML definition. Throws on an unsafe name. */
+export function projectDefPath(name) {
+    if (!isSafeProjectName(name)) {
+        throw new Error(`Invalid project name: "${name}" (letters, digits, ., _, - only)`);
+    }
+    return safeJoin(getProjectsDir(), `${name}.yaml`);
+}
+/**
+ * Validate a raw parsed object into a `ProjectDef`, throwing an actionable error
+ * on the first problem. A malformed document or identity (bad/mismatched name)
+ * throws; malformed entries inside the optional lists (`repos`/`contexts`/
+ * `integrations`) are dropped so one bad row can't sink an otherwise good def.
+ */
+export function validateProjectDef(raw, sourceName) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error(`Project ${sourceName ?? ''} is not a YAML mapping`.trim());
+    }
+    const o = raw;
+    // The filename is the identity; a `name:` field is optional but, when present,
+    // must be a valid slug — a malformed one is a loud error, not a silent fallback.
+    const hasNameField = 'name' in o && o.name !== undefined && o.name !== null;
+    let name;
+    if (hasNameField) {
+        if (typeof o.name !== 'string' || !isSafeProjectName(o.name)) {
+            throw new Error(`Project ${sourceName ?? ''}: "name" must be a valid slug (got ${JSON.stringify(o.name)})`);
+        }
+        name = o.name;
+    }
+    else {
+        name = sourceName;
+    }
+    if (!name || !isSafeProjectName(name)) {
+        throw new Error('Project definition is missing a valid "name"');
+    }
+    // The filename IS the stable id — a def whose `name:` disagrees with its
+    // filename would resolve under one name and list under another.
+    if (hasNameField && sourceName && name !== sourceName) {
+        throw new Error(`Project ${sourceName}: "name" (${JSON.stringify(name)}) must match the filename — the filename is the stable id`);
+    }
+    const def = { name };
+    if (typeof o.description === 'string')
+        def.description = o.description;
+    if (typeof o.root === 'string')
+        def.root = o.root;
+    if (typeof o.defaultPath === 'string')
+        def.defaultPath = o.defaultPath;
+    if (typeof o.repo === 'string')
+        def.repo = o.repo;
+    if (Array.isArray(o.repos)) {
+        def.repos = o.repos.flatMap((r) => {
+            if (r && typeof r === 'object' && typeof r.slug === 'string') {
+                const rr = r;
+                const repo = { slug: rr.slug };
+                if (typeof rr.subpath === 'string')
+                    repo.subpath = rr.subpath;
+                return [repo];
+            }
+            return [];
+        });
+    }
+    if (Array.isArray(o.contexts)) {
+        def.contexts = o.contexts.flatMap((c) => {
+            if (c &&
+                typeof c === 'object' &&
+                typeof c.path === 'string' &&
+                typeof c.purpose === 'string') {
+                const cc = c;
+                return [{ path: cc.path, purpose: cc.purpose }];
+            }
+            return [];
+        });
+    }
+    if (Array.isArray(o.integrations)) {
+        def.integrations = o.integrations.flatMap((i) => {
+            if (i &&
+                typeof i === 'object' &&
+                typeof i.kind === 'string' &&
+                typeof i.url === 'string') {
+                const ii = i;
+                const integ = { kind: ii.kind, url: ii.url };
+                if (typeof ii.label === 'string')
+                    integ.label = ii.label;
+                return [integ];
+            }
+            return [];
+        });
+    }
+    if (o.linear && typeof o.linear === 'object' && !Array.isArray(o.linear)) {
+        const l = o.linear;
+        def.linear = {};
+        if (typeof l.projectId === 'string')
+            def.linear.projectId = l.projectId;
+        if (typeof l.url === 'string')
+            def.linear.url = l.url;
+    }
+    if (Array.isArray(o.docs))
+        def.docs = o.docs.filter((d) => typeof d === 'string');
+    return def;
+}
+/**
+ * Load a single project definition by name. Returns undefined when the file is
+ * absent (the common "not a defined project, fall back to convention" case) but
+ * throws when a file EXISTS and is malformed — a broken definition is loud.
+ */
+export function loadProjectDef(name) {
+    if (!isSafeProjectName(name))
+        return undefined;
+    let raw;
+    try {
+        raw = fs.readFileSync(projectDefPath(name), 'utf8');
+    }
+    catch {
+        return undefined; // absent — not a defined project
+    }
+    return validateProjectDef(yaml.parse(raw), name);
+}
+/**
+ * List every defined project, sorted by name. Skips (does not throw on) a
+ * malformed file so one bad definition can't break `projects list`; the loader
+ * for a single named project stays strict.
+ */
+export function listProjectDefs() {
+    let files;
+    try {
+        // Definitions are `<name>.yaml` (what projectDefPath/loadProjectDef read). We
+        // deliberately do NOT list `.yml` here — accepting it would then ENOENT in the
+        // loader and silently drop the project. One extension, one code path.
+        files = fs.readdirSync(getProjectsDir()).filter((f) => f.endsWith('.yaml'));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of files) {
+        const name = f.replace(/\.yaml$/, '');
+        try {
+            const def = loadProjectDef(name);
+            if (def)
+                out.push(def);
+        }
+        catch {
+            /* malformed — skip in the listing */
+        }
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Persist a project definition, normalizing `root`/`defaultPath` to home-relative
+ * so it stays portable across machines. Creates the projects dir on first write.
+ */
+export function writeProjectDef(def) {
+    const validated = validateProjectDef(def, def.name);
+    const normalized = {
+        ...validated,
+        root: validated.root ? toHomeRelative(expandLocalHome(validated.root)) : undefined,
+        defaultPath: validated.defaultPath
+            ? toHomeRelative(expandLocalHome(validated.defaultPath))
+            : undefined,
+    };
+    // Drop undefined keys so the YAML stays clean.
+    const clean = Object.fromEntries(Object.entries(normalized).filter(([, v]) => v !== undefined));
+    const target = projectDefPath(def.name);
+    fs.mkdirSync(getProjectsDir(), { recursive: true });
+    fs.writeFileSync(target, yaml.stringify(clean), 'utf8');
+    return target;
+}
+/** Delete a project definition. Returns true if a file was removed. Never touches the repo. */
+export function removeProjectDef(name) {
+    try {
+        fs.unlinkSync(projectDefPath(name));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The cwd an agent lands in for a defined project: `defaultPath` when set, else
+ * `root`. Home-relative when `forRemote` (the remote shell expands `~`), else
+ * expanded against the local home. Returns undefined when neither is set.
+ */
+export function projectBasePath(def, forRemote) {
+    const base = def.defaultPath ?? def.root;
+    if (!base)
+        return undefined;
+    return forRemote ? base : expandLocalHome(base);
+}
+function projectRootsAbs(defs) {
+    const out = [];
+    for (const def of defs) {
+        const raw = def.root ?? def.defaultPath;
+        if (!raw)
+            continue;
+        out.push({ name: def.name, abs: path.resolve(expandLocalHome(raw)) });
+    }
+    return out;
+}
+/** True when `child` is `parent` or nested under it (path-segment aware). */
+function isUnder(child, parent) {
+    if (child === parent)
+        return true;
+    const withSep = parent.endsWith(path.sep) ? parent : parent + path.sep;
+    return child.startsWith(withSep);
+}
+/**
+ * Which defined project a session belongs to, derived from its working
+ * directory. A session whose `cwd` sits inside a project's repo root (or a
+ * worktree under it) is a member; the LONGEST matching root wins so a nested
+ * project beats its parent. Returns undefined when no definition contains the
+ * path.
+ *
+ * The comparison is against the LOCAL home: roots and the cwd are both expanded
+ * with `expandLocalHome` and resolved, so this matches sessions whose cwd shares
+ * this machine's home layout. A session recorded on a different-home machine
+ * (`/Users/x/…` vs `/home/x/…`) will not match until the fleet-wide,
+ * home-relative variant lands (see the deferred item in docs/11-projects.md).
+ */
+export function projectNameForCwd(cwd, defs) {
+    if (!cwd)
+        return undefined;
+    const abs = path.resolve(expandLocalHome(cwd));
+    let best;
+    let bestLen = -1;
+    for (const { name, abs: root } of projectRootsAbs(defs)) {
+        if (isUnder(abs, root) && root.length > bestLen) {
+            best = name;
+            bestLen = root.length;
+        }
+    }
+    return best;
+}
+/**
+ * The canonical project label for a cwd, for every surface that buckets work by
+ * project (the activity timeline, feed posts, the sessions overview): the
+ * DEFINED project whose root contains the cwd (longest root wins, so a
+ * multi-repo project reads as one bucket), else the repository-level key from
+ * {@link resolveProjectKey}. `defs` comes from {@link listProjectDefs}, which is
+ * fail-open — with no definitions this degrades to exactly today's behavior.
+ */
+export function resolveProjectNameForCwd(cwd, defs) {
+    if (!cwd)
+        return undefined;
+    return projectNameForCwd(cwd, defs) ?? resolveProjectKey(cwd);
+}
+/**
+ * Resolve a defined project's ref to a working directory, mirroring
+ * `buildProjectPath`'s `forRemote` contract (a home-relative `~/…` for the
+ * remote shell to expand, an absolute local path otherwise). A `@worktree`
+ * lands under the repo ROOT's `.agents/worktrees/`, not the `defaultPath`
+ * subdir — worktrees are per-repo, not per-focus. Returns undefined when the
+ * definition carries no `root`/`defaultPath` (caller falls back to convention).
+ */
+export function resolveDefinedProjectPath(def, worktree, forRemote) {
+    if (worktree) {
+        const rootRaw = def.root ?? def.defaultPath;
+        if (!rootRaw)
+            return undefined;
+        const wt = `${rootRaw}/.agents/worktrees/${worktree}`;
+        return forRemote ? wt : path.resolve(expandLocalHome(wt));
+    }
+    const base = projectBasePath(def, forRemote);
+    if (!base)
+        return undefined;
+    return forRemote ? base : path.resolve(base);
+}

package/dist/lib/remote-agents-json.d.ts

@@ -3,10 +3,19 @@ export interface RemoteAgentsJsonOptions<T> {
     noFanoutEnv: string;
     hosts?: string[];
     parse: (stdout: string, machine: string) => T[];
+    /**
+     * Suppress the per-device "unreachable — skipped" stderr line. The skipped
+     * names still come back in {@link RemoteAgentsJsonResult.skipped}, so a caller
+     * that fans out by DEFAULT can report them once, compactly, instead of
+     * printing a line per offline box above its output. Never a silent drop.
+     */
+    quiet?: boolean;
 }
 export interface RemoteAgentsJsonResult<T> {
     items: T[];
     deviceCount: number;
+    /** Devices that were dialed but answered with an error / no CLI / a timeout. */
+    skipped: string[];
 }
 /** Build the command one peer runs, with a guard that prevents recursive fan-out. */
 export declare function remoteAgentsJsonCommand(args: string[], noFanoutEnv: string, os?: string): string;

package/dist/lib/remote-agents-json.js

@@ -11,7 +11,7 @@ import chalk from 'chalk';
 import { SSH_OPTS, controlOpts, assertValidSshTarget, shellQuote } from './ssh-exec.js';
 import { sshTargetFor } from './devices/connect.js';
 import { resolveExplicitTargets } from './devices/resolve-target.js';
-import { loadDevices, isControlDevice } from './devices/registry.js';
+import { loadDevices, isControlDevice, isDialableDevice } from './devices/registry.js';
 import { remoteShellFor, buildWindowsAgentsCommand } from './hosts/remote-cmd.js';
 import { machineId, normalizeHost } from './machine-id.js';
 const REMOTE_TIMEOUT_MS = 12_000;
@@ -59,10 +59,12 @@ export async function gatherRemoteAgentsJson(options) {
             devices = await loadDevices();
         }
         catch {
-            return { items: [], deviceCount: 0 };
+            return { items: [], deviceCount: 0, skipped: [] };
         }
         for (const device of Object.values(devices)) {
-            if (device.tailscale?.online !== true)
+            // Live SSH-probe verdict first, cached tailscale snapshot only as a
+            // fallback — see isDialableDevice (mirrors session/remote-list.ts).
+            if (!isDialableDevice(device))
                 continue;
             if (normalizeHost(device.name) === self)
                 continue;
@@ -87,14 +89,18 @@ export async function gatherRemoteAgentsJson(options) {
             }
         }
     }
+    const skipped = [];
     const results = await Promise.all(targets.map(async (target) => {
         const command = remoteAgentsJsonCommand(options.args, options.noFanoutEnv, target.os);
         const result = await sshCapture(target.target, command);
         if (result.code !== 0) {
-            process.stderr.write(chalk.gray(`  ${target.name}: unreachable or no agents CLI — skipped\n`));
+            skipped.push(target.name);
+            if (!options.quiet) {
+                process.stderr.write(chalk.gray(`  ${target.name}: unreachable or no agents CLI — skipped\n`));
+            }
             return [];
         }
         return options.parse(result.stdout, target.machine);
     }));
-    return { items: results.flat(), deviceCount: targets.length };
+    return { items: results.flat(), deviceCount: targets.length, skipped };
 }

package/dist/lib/routines-project.js

@@ -269,6 +269,12 @@ export function syncProjectRoutines(projectRoot) {
             if (job.devices === undefined && existing.devices && existing.devices.length > 0) {
                 job.devices = existing.devices;
             }
+            // Carry the original creation stamp across. A sync rebuilds the config
+            // from the PROJECT yaml, which never carries `createdAt`, so without this
+            // every `agents routines sync` would re-stamp it to now — walking the
+            // overdue floor forward and hiding real missed fires for project routines.
+            if (existing.createdAt)
+                job.createdAt = existing.createdAt;
         }
         // Placement that leaves the firing machine must pin devices to avoid
         // every fleet daemon dispatching once.

package/dist/lib/routines.d.ts

@@ -122,6 +122,28 @@ export interface JobConfig {
      * overdue; everywhere else it is inert and `run` refuses with a pointer.
      */
     devices?: string[];
+    /**
+     * Whether a fire this device missed (daemon down, laptop asleep, wedged event
+     * loop) is run late. Defaults to true: croner only schedules forward from
+     * "now", so without catch-up a missed fire is simply lost and the routine
+     * silently does not run.
+     *
+     * Set `catchup: false` for a routine whose value is tied to its clock — a
+     * 9am standup brief is worthless at 3pm. An opted-out routine still records
+     * the miss (a `missed` run), it just is not re-run.
+     */
+    catchup?: boolean;
+    /**
+     * When this routine came into existence, ISO 8601. Stamped once by
+     * {@link writeJob}, like `actor`.
+     *
+     * Overdue detection needs it: `detectOverdueJobs` walks back a week for the
+     * most recent expected fire, so without a floor a brand-new routine is
+     * "overdue" for occurrences that happened before it was written. Harmless
+     * when catch-up was a manual command; with auto-catchup it would run every
+     * newly created routine once, immediately.
+     */
+    createdAt?: string;
     /**
      * Environment variables injected into the spawned run, on top of the sandbox
      * overlay's own. Merged by `buildSpawnEnv`, so it applies to both the
@@ -217,7 +239,14 @@ export interface RunMeta {
     pid: number | null;
     /** Process birth time (epoch ms) recorded at spawn for pid-reuse detection. */
     spawnedAt?: number;
-    status: 'running' | 'completed' | 'failed' | 'timeout';
+    /**
+     * `missed` is not an execution outcome — it is the record that a scheduled
+     * fire never happened (the daemon was down, asleep, or wedged when it came
+     * due). Without it a miss leaves no trace at all and the listing keeps
+     * showing the previous run's status as if it were current. Written by
+     * `claimMissedFire` (catchup.ts), never by the runner.
+     */
+    status: 'running' | 'completed' | 'failed' | 'timeout' | 'missed';
     startedAt: string;
     completedAt: string | null;
     exitCode: number | null;

package/dist/lib/routines.js

@@ -274,6 +274,12 @@ export function writeJob(config) {
     // only a brand-new routine (no actor yet) gets the current resolver.
     if (!config.actor)
         config.actor = resolveActor().id;
+    // Stamped once, on first write, and preserved by every later edit (an edit
+    // re-writes a config loaded from disk, which already carries it). This is the
+    // floor overdue detection uses so a routine is never judged against fires
+    // that predate it.
+    if (!config.createdAt)
+        config.createdAt = new Date().toISOString();
     const jobsDir = getRoutinesDir();
     const ymlPath = safeJoin(jobsDir, config.name + '.yml');
     const yamlPath = safeJoin(jobsDir, config.name + '.yaml');
@@ -294,6 +300,8 @@ export function writeJob(config) {
         delete output.enabled;
     if (output.runOnce === false || output.runOnce === undefined)
         delete output.runOnce;
+    if (output.catchup === true || output.catchup === undefined)
+        delete output.catchup;
     const devArr = output.devices;
     if (!devArr || devArr.length === 0)
         delete output.devices;
@@ -515,6 +523,9 @@ export function validateJob(config) {
             }
         }
     }
+    if (config.catchup !== undefined && typeof config.catchup !== 'boolean') {
+        errors.push('catchup must be a boolean (false to skip running a missed fire late)');
+    }
     // Off-box placement without a devices pin fires on every fleet daemon and
     // each dispatches once (RUSH-1980). Enforce the pin at validation so hand
     // edits and devices --clear cannot re-open the hole.

package/dist/lib/secrets/list-filter.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Filters for `agents secrets list`.
+ *
+ * The listing had no filtering at all: `--host`/`--device` pick a machine and
+ * `--json` picks a format, but nothing selected over the bundles themselves. On
+ * a fleet with fifty-odd bundles the answerable questions — which ones read with
+ * no Touch ID at all, which hold a raw literal, which have already expired, what
+ * has not been touched in three months — meant piping the table through grep, or
+ * were simply unanswerable.
+ *
+ * Everything here is pure: parsing produces a `SecretsListFilter`, and
+ * `bundleMatchesFilter` is a predicate over a bundle plus the ambient facts it
+ * cannot derive itself (which bundles the broker currently holds, and the
+ * current time). That keeps the whole surface unit-testable without a keychain.
+ *
+ * Shape follows the `agents sessions` house style: comma-separated lists, an
+ * unknown value is a loud error naming the valid set (never a silent ignore),
+ * and every axis narrows independently so they AND-compose.
+ */
+import { type SecretsBundle, type SecretsPolicy, type SecretsBackend, type SecretType } from './bundles.js';
+/** Ref kinds a var's value can have, from `describeBundle`. */
+export declare const REF_KINDS: readonly ["literal", "keychain", "env", "file", "exec"];
+export type RefKind = typeof REF_KINDS[number];
+/** Default window for `--expiring` with no argument — matches the EXPIRING column. */
+export declare const DEFAULT_EXPIRING_DAYS = 30;
+/** A parsed, validated filter. Every field is optional; absent ⇒ that axis does
+ * not narrow. All present axes must match (AND). */
+export interface SecretsListFilter {
+    /** Case-insensitive substring over bundle name and description. */
+    query?: string;
+    policy?: SecretsPolicy[];
+    backend?: SecretsBackend[];
+    type?: SecretType[];
+    kind?: RefKind[];
+    /** true ⇒ only bundles the broker holds; false ⇒ only those it does not. */
+    held?: boolean;
+    /** Only bundles with at least one var whose `expires` is already past. */
+    expired?: boolean;
+    /** Only bundles with at least one var expiring within this many days. */
+    expiringDays?: number;
+    /** Only bundles whose `last_used` is older than this epoch-ms (or never used). */
+    unusedBefore?: number;
+}
+/** The raw option bag commander hands us. */
+export interface SecretsListFilterOpts {
+    policy?: string;
+    backend?: string;
+    type?: string;
+    kind?: string;
+    held?: boolean;
+    notHeld?: boolean;
+    expired?: boolean;
+    expiring?: string | boolean;
+    unused?: string;
+}
+/**
+ * Validate one comma-separated enum list. An unknown value throws and names the
+ * whole valid set — a silent ignore would let `--policy hodl` quietly return
+ * every bundle, which reads as "nothing matches that" and is worse than an error.
+ * Values are lowercased, matching `parsePolicyOpt`'s handling of policy names.
+ */
+export declare function parseEnumList<T extends string>(raw: string, flag: string, valid: readonly T[]): T[];
+/** Build a validated filter from commander's option bag. Throws on bad input. */
+export declare function parseListFilters(opts: SecretsListFilterOpts, query?: string): SecretsListFilter;
+/** True when any axis is set — used to decide whether the empty state should
+ * explain itself rather than claim there are no bundles at all. */
+export declare function filterIsActive(f: SecretsListFilter): boolean;
+/** Expiry tallies for one bundle: how many vars are already past, and how many
+ * fall due within `withinDays`. */
+export declare function bundleExpiry(b: SecretsBundle, now: number, withinDays?: number): {
+    expired: number;
+    soon: number;
+};
+/** Ambient facts a bundle can't answer about itself. */
+export interface FilterContext {
+    /** Bundle name → hold expiry epoch-ms, from the broker. Empty off macOS. */
+    held: Map<string, number>;
+    now: number;
+}
+/** Does this bundle satisfy every set axis? Pure. */
+export declare function bundleMatchesFilter(b: SecretsBundle, f: SecretsListFilter, ctx: FilterContext): boolean;
+/** Sort fields for `--sort`. `name` is the default and matches `listBundles()`. */
+export declare const SORT_FIELDS: readonly ["name", "used", "created", "updated", "expiry"];
+export type SortField = typeof SORT_FIELDS[number];
+export declare function parseSortField(raw: string | undefined): SortField;
+/** Sort a copy. Time fields are most-recent-first (the useful direction for
+ * "what did I touch lately"); `expiry` is soonest-first; ties fall back to name
+ * so the order is stable. */
+export declare function sortBundles(bundles: SecretsBundle[], field: SortField): SecretsBundle[];
+/** Human summary of the active filters, for the empty state. `sessions` only
+ * echoes --project/--all on a miss, which leaves you guessing which flag emptied
+ * the list; naming every active axis is the difference between "nothing matched"
+ * and knowing what to relax. */
+export declare function describeFilter(f: SecretsListFilter): string;