@phnx-labs/agents-cli 1.20.91 → 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/session/bash-command.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Parses the raw command strings agents pass to Bash tool calls into structured
+ * metadata: the executable, category, subcommand, and a display summary. Used by
+ * session rendering and the activity-log hook so `agents sessions` and
+ * `agents activity` can summarize what actually happened instead of printing a
+ * wall of shell.
+ */
+export type BashCategory = 'vcs' | 'build-test' | 'install' | 'remote' | 'http' | 'media' | 'upscaling' | 'metadata' | 'probe' | 'search' | 'shell' | 'wait' | 'other';
+export interface BashToolInfo {
+    category: BashCategory;
+    signal: 'high' | 'mid' | 'low';
+    action: string;
+    aliases?: string[];
+}
+export interface BashCommandInfo {
+    tool: string;
+    category: BashCategory;
+    subcommand: string;
+    action: string;
+    summary: string;
+    signal: 'high' | 'mid' | 'low';
+}
+export declare function unwrapCommand(cmd: string): string;
+/**
+ * Split a possibly-compound Bash command into simple commands, then tokenize each
+ * with shlex. Returns an empty array for empty input.
+ */
+export declare function tokenizeBash(cmd: string): string[][];
+/**
+ * Classify the first simple command in a Bash string. Returns coarse metadata
+ * (tool name, category, subcommand, human action) used for summaries and
+ * activity logging. Unknown executables fall back to `other`.
+ */
+export declare function classifyBashCommand(command: string): BashCommandInfo;
+/**
+ * Stable bucket key for grouping similar Bash commands in summaries. Commands run
+ * through a remote wrapper (ssh/scp/rsync) get an `ssh→` prefix on the inner key,
+ * so `ssh host "git push"` buckets as `ssh→git push`, distinct from a local push.
+ */
+export declare function bucketKey(command: string): string;
+/**
+ * Detect high-signal Bash-driven milestones (video renders, upscales, metadata
+ * edits, git commits/pushes/worktrees, PR opens). Returns null for routine
+ * commands.
+ */
+export declare function detectBashMilestone(command: string): {
+    event: string;
+    detail: string;
+} | null;
+/**
+ * Human-readable category label for renderers.
+ */
+export declare function categoryLabel(category: BashCategory): string;