@phnx-labs/agents-cli 1.20.71 → 1.20.73

package/dist/commands/resource-view.js

@@ -14,6 +14,14 @@ import { isInteractiveTerminal, isPromptCancelled, printWithPager } from './util
 import { terminalWidth, truncateToWidth, padToWidth, stringWidth, stripAnsi } from '../lib/session/width.js';
 /** Display a resource list: interactive picker in TTY mode, plain table otherwise. */
 export async function showResourceList(opts) {
+    if (opts.json) {
+        // Strip the non-serializable buildDetail thunk; emit the row metadata plus
+        // each resource's per-agent-version sync targets. One shared JSON contract
+        // for every resource `list` built on this helper.
+        const rows = opts.rows.map(({ buildDetail, ...row }) => row);
+        console.log(JSON.stringify(rows, null, 2));
+        return;
+    }
     if (opts.rows.length === 0) {
         console.log(chalk.gray(opts.emptyMessage));
         return;

package/dist/commands/resources.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `agents resources` — show the merged DotAgents resource surface.
+ */
+import type { Command } from 'commander';
+export declare function registerResourcesCommand(program: Command): void;

package/dist/commands/resources.js

@@ -0,0 +1,95 @@
+/**
+ * `agents resources` — show the merged DotAgents resource surface.
+ */
+import * as path from 'path';
+import chalk from 'chalk';
+import { listResources } from '../lib/resources.js';
+import { terminalWidth, truncateToWidth, stringWidth } from '../lib/session/width.js';
+const DRILLABLE_KINDS = [
+    'skills',
+    'commands',
+    'mcp',
+    'hooks',
+    'rules',
+    'plugins',
+    'workflows',
+    'subagents',
+];
+const KIND_LABELS = {
+    skills: 'Skills',
+    commands: 'Commands',
+    mcp: 'MCP',
+    hooks: 'Hooks',
+    rules: 'Rules',
+    plugins: 'Plugins',
+    workflows: 'Workflows',
+    subagents: 'Subagents',
+};
+export function registerResourcesCommand(program) {
+    program
+        .command('resources')
+        .description('Show the merged DotAgents resources resolved across project, user, system, and extras')
+        .option('--merged', 'Show the merged first-wins resource surface (default)')
+        .addHelpText('after', `
+Examples:
+  agents resources
+  agents resources --merged
+`)
+        .action((options) => {
+        void options;
+        renderMergedResources();
+    });
+}
+function renderMergedResources() {
+    const groups = DRILLABLE_KINDS.map((kind) => ({
+        kind,
+        rows: listResources(kind),
+    }));
+    const total = groups.reduce((sum, group) => sum + group.rows.length, 0);
+    if (total === 0) {
+        console.log(chalk.gray('No merged resources found.'));
+        return;
+    }
+    console.log(chalk.bold(`Resources (${total} merged)`));
+    for (const group of groups) {
+        console.log();
+        console.log(chalk.bold(`${KIND_LABELS[group.kind]} (${group.rows.length})`));
+        if (group.rows.length === 0) {
+            console.log(chalk.gray('  none'));
+            continue;
+        }
+        for (const line of renderResourceRows(group.rows))
+            console.log(line);
+    }
+}
+function renderResourceRows(rows) {
+    const nameW = Math.min(28, Math.max('Name'.length, ...rows.map((row) => stringWidth(row.name))));
+    const layerW = Math.min(16, Math.max('Layer'.length, ...rows.map((row) => stringWidth(row.source))));
+    const prefixW = 2 + nameW + 2 + layerW + 2;
+    const pathW = Math.max(12, terminalWidth() - prefixW);
+    const lines = [
+        `  ${chalk.bold(pad(row('Name', nameW), nameW))}  ${chalk.bold(pad(row('Layer', layerW), layerW))}  ${chalk.bold('Path')}`,
+        `  ${chalk.gray(`${'-'.repeat(nameW)}  ${'-'.repeat(layerW)}  ${'-'.repeat(Math.min(pathW, 40))}`)}`,
+    ];
+    for (const resource of rows) {
+        lines.push(`  ${chalk.cyan(pad(truncateToWidth(resource.name, nameW), nameW))}  ${pad(resource.source, layerW)}  ${chalk.gray(truncateToWidth(formatPath(resource.path), pathW))}`);
+    }
+    return lines;
+}
+function row(value, width) {
+    return truncateToWidth(value, width);
+}
+function pad(value, width) {
+    return value + ' '.repeat(Math.max(0, width - stringWidth(value)));
+}
+function formatPath(value) {
+    const home = process.env.HOME;
+    if (home) {
+        const rel = path.relative(home, value);
+        if (rel === '')
+            return '~';
+        if (!rel.startsWith('..') && !path.isAbsolute(rel))
+            return `~/${rel}`;
+    }
+    return value;
+}

package/dist/commands/routines.d.ts

@@ -6,11 +6,13 @@
  * Also exposes scheduler lifecycle controls (start/stop/status/logs).
  */
 import type { Command } from 'commander';
+import type { RunMeta } from '../lib/routines.js';
 /**
  * Human-friendly wall-clock a run took (e.g. "  · 3 min", "  · 45 sec"), or ""
  * when it hasn't completed or timestamps are unparseable. Leading separator lets
  * callers drop it straight into a status line.
  */
 export declare function formatRunDuration(startedAt: string, completedAt: string | null): string;
+export declare function buildRunsJson(runs: RunMeta[]): Record<string, unknown>[];
 /** Register the `agents routines` command tree. */
 export declare function registerRoutinesCommands(program: Command): void;

package/dist/commands/routines.js

@@ -58,7 +58,11 @@ function fireConditionLabel(job) {
             const scope = job.trigger.repo
                 ? ` (${job.trigger.repo}${job.trigger.branch ? `@${job.trigger.branch}` : ''})`
                 : '';
-            return `on github:${job.trigger.event}${scope}`;
+            const filters = [
+                job.trigger.action ? `action=${job.trigger.action}` : null,
+                job.trigger.label ? `label=${job.trigger.label}` : null,
+            ].filter(Boolean).join(', ');
+            return `on github:${job.trigger.event}${scope}${filters ? ` (${filters})` : ''}`;
         }
         const filters = [
             job.trigger.action ? `action=${job.trigger.action}` : null,
@@ -83,6 +87,10 @@ function parseRoutineTrigger(options) {
             trigger.repo = options.repo;
         if (typeof options.branch === 'string')
             trigger.branch = options.branch;
+        if (typeof options.action === 'string')
+            trigger.action = options.action;
+        if (typeof options.label === 'string')
+            trigger.label = options.label;
         return trigger;
     }
     if (sourceMaybe === 'linear') {
@@ -97,22 +105,47 @@ function parseRoutineTrigger(options) {
     }
     throw new Error('--on source must be github or linear');
 }
-/** Start or reload the background scheduler so newly-added jobs fire on time. */
-function ensureSchedulerRunning() {
+/**
+ * Start or reload the background scheduler so newly-added jobs fire on time.
+ * `quiet` suppresses human status lines for JSON callers.
+ */
+function ensureSchedulerRunning(opts = {}) {
+    const log = opts.stderr ? console.error : console.log;
     if (isDaemonRunning()) {
         signalDaemonReload();
-        console.log(chalk.gray('Scheduler reloaded'));
+        if (!opts.quiet)
+            log(chalk.gray('Scheduler reloaded'));
         return;
     }
     const result = startDaemon();
+    if (opts.quiet)
+        return;
     if (result.pid) {
-        console.log(chalk.green(`Scheduler started (PID: ${result.pid}). It will run in the background and fire routines on schedule.`));
-        console.log(chalk.gray(`Stop anytime with: agents routines stop`));
+        log(chalk.green(`Scheduler started (PID: ${result.pid}). It will run in the background and fire routines on schedule.`));
+        log(chalk.gray(`Stop anytime with: agents routines stop`));
     }
     else {
-        console.log(chalk.yellow('Could not start the scheduler. Start it manually with: agents routines start'));
+        log(chalk.yellow('Could not start the scheduler. Start it manually with: agents routines start'));
     }
 }
+function writeJson(payload) {
+    process.stdout.write(JSON.stringify(payload) + '\n');
+}
+function runMetaJson(run) {
+    return {
+        jobId: run.jobName,
+        jobName: run.jobName,
+        runId: run.runId,
+        status: run.status,
+        startedAt: run.startedAt,
+        completedAt: run.completedAt,
+        exitCode: run.exitCode,
+        errorMessage: run.errorMessage ?? null,
+    };
+}
+export function buildRunsJson(runs) {
+    return runs.map(runMetaJson);
+}
 /** Detect Ctrl+C or premature stream close during an interactive prompt. */
 function isPromptCancelled(err) {
     return (err instanceof Error &&
@@ -296,6 +329,8 @@ export function registerRoutinesCommands(program) {
                     nextRun: nextRun ? nextRun.toISOString() : null,
                     nextRunHuman: humanizeNextRun(nextRun ?? null, nowJson, job.timezone),
                     lastStatus: latestRun?.status ?? null,
+                    exitCode: latestRun?.exitCode ?? null,
+                    failureReason: latestRun?.errorMessage ?? null,
                     lastRunStartedAt: latestRun?.startedAt ?? null,
                     lastRunCompletedAt: latestRun?.completedAt ?? null,
                 };
@@ -394,25 +429,26 @@ export function registerRoutinesCommands(program) {
         .option('--on <source:event>', 'Webhook trigger instead of/in addition to a schedule: github:pull_request or linear:Issue')
         .option('--repo <owner/name>', 'GitHub repo filter for --on github:<event>')
         .option('--branch <name>', 'GitHub branch filter for --on github:<event>')
-        .option('--action <name>', 'Linear action filter for --on linear:<event> (e.g. update)')
+        .option('--action <name>', 'Webhook action filter for --on triggers (GitHub: labeled/opened; Linear: update)')
         .option('--team-key <key>', 'Linear team key filter for --on linear:<event> (e.g. RUSH)')
-        .option('--label <name>', 'Linear issue label filter for --on linear:Issue')
+        .option('--label <name>', 'Label filter for --on triggers (GitHub label name or Linear issue label)')
         .option('--end-at <iso>', 'Stop firing on or after this ISO 8601 timestamp (e.g., "2026-12-31T23:59:00Z"); routine auto-disables.')
         .option('--disabled', 'Create the routine but keep it paused (enable later with resume)')
         .option('--resume <sessionId>', 'At fire time, resume this existing session id (via `agents run <agent> --resume`) instead of starting fresh — the actual session reopens with full context and the prompt becomes its next turn. Powers self-scheduled wake-ups (e.g. /hibernate). Requires --agent claude or codex; runs un-sandboxed (the session store lives in the real home, not the job overlay).')
+        .option('--json', 'Emit machine-readable JSON with the created routine id and status')
         .action(async (nameOrPath, options) => {
         // Check if inline mode (has flags) or file mode
         const hasInlineFlags = options.schedule || options.agent || options.workflow || options.command || options.prompt || options.at || options.on;
         if (hasInlineFlags) {
             // Inline mode: create job from flags
             if (!nameOrPath) {
-                console.log(chalk.red('Job name is required'));
-                console.log(chalk.gray('Usage: agents routines add <name> --schedule "..." --agent <agent> --prompt "..."'));
+                console.error(chalk.red('Job name is required'));
+                console.error(chalk.gray('Usage: agents routines add <name> --schedule "..." --agent <agent> --prompt "..."'));
                 process.exit(1);
             }
             // Validate mutually exclusive --agent / --workflow / --command
             if ([options.agent, options.workflow, options.command].filter(Boolean).length > 1) {
-                console.log(chalk.red('--agent, --workflow, and --command are mutually exclusive; specify exactly one'));
+                console.error(chalk.red('--agent, --workflow, and --command are mutually exclusive; specify exactly one'));
                 process.exit(1);
             }
             let schedule = options.schedule;
@@ -422,31 +458,31 @@ export function registerRoutinesCommands(program) {
                 trigger = parseRoutineTrigger(options);
             }
             catch (err) {
-                console.log(chalk.red(err.message));
+                console.error(chalk.red(err.message));
                 process.exit(1);
             }
             // Handle --at for one-shot jobs
             if (options.at) {
                 const parsed = parseAtTime(options.at);
                 if (!parsed) {
-                    console.log(chalk.red(`Invalid --at format: ${options.at}`));
-                    console.log(chalk.gray('Supported formats: "14:30" or "2026-02-24 09:00"'));
+                    console.error(chalk.red(`Invalid --at format: ${options.at}`));
+                    console.error(chalk.gray('Supported formats: "14:30" or "2026-02-24 09:00"'));
                     process.exit(1);
                 }
                 schedule = parsed.schedule;
                 runOnce = parsed.runOnce;
             }
             if (!schedule && !trigger) {
-                console.log(chalk.red('Schedule or trigger is required (use --schedule, --at, or --on)'));
+                console.error(chalk.red('Schedule or trigger is required (use --schedule, --at, or --on)'));
                 process.exit(1);
             }
             if (!options.agent && !options.workflow && !options.command) {
-                console.log(chalk.red('An agent, workflow, or command is required (use --agent, --workflow, or --command)'));
+                console.error(chalk.red('An agent, workflow, or command is required (use --agent, --workflow, or --command)'));
                 process.exit(1);
             }
             // Command routines run a plain shell and take no prompt; agent/workflow routines require one.
             if (!options.command && !options.prompt) {
-                console.log(chalk.red('Prompt is required (use --prompt)'));
+                console.error(chalk.red('Prompt is required (use --prompt)'));
                 process.exit(1);
             }
             // Parse and validate --devices against the fleet registry.
@@ -459,7 +495,7 @@ export function registerRoutinesCommands(program) {
             // this machine unless the user chose an explicit eligibility set.
             if (options.runOn && !devices) {
                 devices = [machineId()];
-                console.log(chalk.gray(`--run-on set with no --devices: pinned firing to this machine (${devices[0]}).`));
+                console.error(chalk.gray(`--run-on set with no --devices: pinned firing to this machine (${devices[0]}).`));
             }
             const config = {
                 name: nameOrPath,
@@ -483,13 +519,28 @@ export function registerRoutinesCommands(program) {
             };
             const errors = validateJob(config);
             if (errors.length > 0) {
-                console.log(chalk.red('Validation errors:'));
+                console.error(chalk.red('Validation errors:'));
                 for (const err of errors) {
-                    console.log(chalk.red(`  - ${err}`));
+                    console.error(chalk.red(`  - ${err}`));
                 }
                 process.exit(1);
             }
             writeJob(config);
+            if (options.json) {
+                writeJson({
+                    ok: true,
+                    added: nameOrPath,
+                    job: config,
+                    jobId: config.name,
+                    name: config.name,
+                    status: 'added',
+                    enabled: config.enabled,
+                    schedule: config.schedule ?? null,
+                    trigger: config.trigger ?? null,
+                });
+                ensureSchedulerRunning({ quiet: true });
+                return;
+            }
             console.log(chalk.green(`Job '${nameOrPath}' added`));
             if (runOnce) {
                 console.log(chalk.gray(`One-shot job scheduled for: ${options.at}`));
@@ -499,14 +550,14 @@ export function registerRoutinesCommands(program) {
         else {
             // File mode: load from YAML file
             if (!nameOrPath) {
-                console.log(chalk.red('File path or job name with flags is required'));
-                console.log(chalk.gray('Usage: agents routines add <path-to-job.yml>'));
-                console.log(chalk.gray('   or: agents routines add <name> --schedule "..." --agent <agent> --prompt "..."'));
+                console.error(chalk.red('File path or job name with flags is required'));
+                console.error(chalk.gray('Usage: agents routines add <path-to-job.yml>'));
+                console.error(chalk.gray('   or: agents routines add <name> --schedule "..." --agent <agent> --prompt "..."'));
                 process.exit(1);
             }
             const resolved = path.resolve(nameOrPath);
             if (!fs.existsSync(resolved)) {
-                console.log(chalk.red(`File not found: ${resolved}`));
+                console.error(chalk.red(`File not found: ${resolved}`));
                 process.exit(1);
             }
             const content = fs.readFileSync(resolved, 'utf-8');
@@ -515,16 +566,16 @@ export function registerRoutinesCommands(program) {
                 parsed = yaml.parse(content);
             }
             catch (err) {
-                console.log(chalk.red(`Invalid YAML: ${err.message}`));
+                console.error(chalk.red(`Invalid YAML: ${err.message}`));
                 process.exit(1);
             }
             const name = parsed.name || path.basename(resolved).replace(/\.ya?ml$/, '');
             parsed.name = name;
             const errors = validateJob(parsed);
             if (errors.length > 0) {
-                console.log(chalk.red('Validation errors:'));
+                console.error(chalk.red('Validation errors:'));
                 for (const err of errors) {
-                    console.log(chalk.red(`  - ${err}`));
+                    console.error(chalk.red(`  - ${err}`));
                 }
                 process.exit(1);
             }
@@ -539,9 +590,24 @@ export function registerRoutinesCommands(program) {
             // with no eligibility pin would fire from every daemon in the fleet.
             if (config.host && (!config.devices || config.devices.length === 0)) {
                 config.devices = [machineId()];
-                console.log(chalk.gray(`host: set with no devices pin: pinned firing to this machine (${config.devices[0]}).`));
+                console.error(chalk.gray(`host: set with no devices pin: pinned firing to this machine (${config.devices[0]}).`));
             }
             writeJob(config);
+            if (options.json) {
+                writeJson({
+                    ok: true,
+                    added: name,
+                    job: config,
+                    jobId: config.name,
+                    name: config.name,
+                    status: 'added',
+                    enabled: config.enabled,
+                    schedule: config.schedule ?? null,
+                    trigger: config.trigger ?? null,
+                });
+                ensureSchedulerRunning({ quiet: true });
+                return;
+            }
             console.log(chalk.green(`Job '${name}' added`));
             ensureSchedulerRunning();
         }
@@ -644,13 +710,22 @@ export function registerRoutinesCommands(program) {
     routinesCmd
         .command('runs [name]')
         .description('See execution history: run IDs, completion status, and start times (up to last 10 runs)')
-        .action(async (name) => {
+        .option('--json', 'Emit machine-readable JSON with run ids and statuses')
+        .action(async (name, options) => {
         if (!name) {
             name = await pickJob('Select job to view runs', undefined, ['agents routines runs <name>']) ?? undefined;
             if (!name)
                 return;
         }
         const runs = listRuns(name);
+        if (options.json) {
+            writeJson({
+                jobId: name,
+                name,
+                runs: buildRunsJson(runs.slice(-10)),
+            });
+            return;
+        }
         if (runs.length === 0) {
             console.log(chalk.yellow(`No runs found for job '${name}'`));
             return;
@@ -668,7 +743,8 @@ export function registerRoutinesCommands(program) {
     routinesCmd
         .command('run [name]')
         .description('Execute a routine right now in the foreground. Ignores the schedule; useful for testing before enabling.')
-        .action(async (name) => {
+        .option('--json', 'Emit machine-readable JSON with the run id and status')
+        .action(async (name, options) => {
         if (!name) {
             name = await pickJob('Select job to run', undefined, ['agents routines run <name>']) ?? undefined;
             if (!name)
@@ -682,20 +758,42 @@ export function registerRoutinesCommands(program) {
         // the trusted user layer.
         const job = readJob(name);
         if (!job) {
-            console.log(chalk.red(`Job '${name}' not found`));
+            if (options.json) {
+                writeJson({ error: `Job '${name}' not found` });
+                process.exit(1);
+            }
+            console.error(chalk.red(`Job '${name}' not found`));
             process.exit(1);
         }
         const eligibility = checkJobDeviceEligibility(job);
         if (eligibility) {
-            console.log(chalk.red(eligibility.message));
-            console.log(chalk.gray(`  ${eligibility.suggestion}`));
+            if (options.json) {
+                writeJson({ error: eligibility.message, hint: eligibility.suggestion });
+                process.exit(1);
+            }
+            console.error(chalk.red(eligibility.message));
+            console.error(chalk.gray(`  ${eligibility.suggestion}`));
             process.exit(1);
         }
         const runLabel = job.command ? 'command' : job.workflow ? `workflow: ${job.workflow}` : `agent: ${job.agent}`;
-        console.log(chalk.bold(`Running job '${name}' (${runLabel}, mode: ${job.mode})\n`));
-        const spinner = ora('Executing...').start();
+        // A spinner writes to stderr but its human framing is noise for a JSON consumer.
+        const spinner = options.json ? null : ora('Executing...').start();
+        if (!options.json)
+            console.log(chalk.bold(`Running job '${name}' (${runLabel}, mode: ${job.mode})\n`));
         try {
             const result = await executeJob(job);
+            const logPath = `${getRunDir(name, result.meta.runId)}/stdout.log`;
+            if (options.json) {
+                writeJson({
+                    ok: true,
+                    job: name,
+                    logDir: getRunDir(name, result.meta.runId),
+                    ...runMetaJson(result.meta),
+                    logPath,
+                    reportPath: result.reportPath ?? null,
+                });
+                return;
+            }
             if (result.meta.status === 'completed') {
                 spinner.succeed(`Job completed (exit code: ${result.meta.exitCode})`);
             }
@@ -706,13 +804,17 @@ export function registerRoutinesCommands(program) {
                 spinner.fail(`Job failed (exit code: ${result.meta.exitCode})`);
             }
             console.log(chalk.gray(`  Run: ${result.meta.runId}`));
-            console.log(chalk.gray(`  Log: ${getRunDir(name, result.meta.runId)}/stdout.log`));
+            console.log(chalk.gray(`  Log: ${logPath}`));
             if (result.reportPath) {
                 console.log(chalk.bold('\nReport:\n'));
                 console.log(fs.readFileSync(result.reportPath, 'utf-8'));
             }
         }
         catch (err) {
+            if (options.json) {
+                writeJson({ error: err.message });
+                process.exit(1);
+            }
             spinner.fail('Execution failed');
             console.error(chalk.red(err.message));
             process.exit(1);