@phnx-labs/agents-cli 1.19.1 → 1.20.0

package/dist/lib/routines-format.js

@@ -0,0 +1,173 @@
+/**
+ * Pure display helpers for `agents routines list`.
+ *
+ * No external dependencies. All functions are pure (no I/O, no side effects).
+ */
+// ---------------------------------------------------------------------------
+// humanizeCron
+// ---------------------------------------------------------------------------
+const DAY_NAMES = ['Sundays', 'Mondays', 'Tuesdays', 'Wednesdays', 'Thursdays', 'Fridays', 'Saturdays'];
+/**
+ * Convert a cron expression to a human-readable phrase.
+ *
+ * Handles the common patterns. For anything unrecognized, returns the raw
+ * expression so the user still sees something useful. NEVER throws.
+ */
+export function humanizeCron(expr, _tz) {
+    try {
+        const parts = expr.trim().split(/\s+/);
+        if (parts.length !== 5)
+            return expr;
+        const [minute, hour, dom, month, dow] = parts;
+        // every minute: * * * * *
+        if (minute === '*' && hour === '*' && dom === '*' && month === '*' && dow === '*') {
+            return 'every minute';
+        }
+        // every N minutes: */N * * * *
+        const everyMinMatch = minute.match(/^\*\/(\d+)$/);
+        if (everyMinMatch && hour === '*' && dom === '*' && month === '*' && dow === '*') {
+            const n = parseInt(everyMinMatch[1], 10);
+            return `every ${n} minute${n === 1 ? '' : 's'}`;
+        }
+        // every N hours: 0 */N * * *
+        const everyHourMatch = hour.match(/^\*\/(\d+)$/);
+        if (everyHourMatch && minute === '0' && dom === '*' && month === '*' && dow === '*') {
+            const n = parseInt(everyHourMatch[1], 10);
+            return `every ${n} hour${n === 1 ? '' : 's'}`;
+        }
+        // Only proceed with time-of-day patterns when hour and minute are fixed integers
+        const hourNum = /^\d+$/.test(hour) ? parseInt(hour, 10) : null;
+        const minNum = /^\d+$/.test(minute) ? parseInt(minute, 10) : null;
+        if (hourNum === null || minNum === null)
+            return expr;
+        const timeStr = formatTime12(hourNum, minNum);
+        // daily at HH:MM: M H * * *
+        if (dom === '*' && month === '*' && dow === '*') {
+            return `daily at ${timeStr}`;
+        }
+        // weekdays: M H * * 1-5
+        if (dom === '*' && month === '*' && dow === '1-5') {
+            return `weekdays at ${timeStr}`;
+        }
+        // specific day of week: M H * * D  (single digit 0-6)
+        if (dom === '*' && month === '*' && /^\d$/.test(dow)) {
+            const dayIdx = parseInt(dow, 10);
+            if (dayIdx >= 0 && dayIdx <= 6) {
+                return `${DAY_NAMES[dayIdx]} at ${timeStr}`;
+            }
+        }
+        // specific day of month: M H D * *
+        if (/^\d+$/.test(dom) && month === '*' && dow === '*') {
+            const d = parseInt(dom, 10);
+            return `monthly on day ${d} at ${timeStr}`;
+        }
+        // every N hours with fixed minute: M */N * * *  (already handled above for M=0; catch M != 0)
+        if (everyHourMatch && dom === '*' && month === '*' && dow === '*') {
+            const n = parseInt(everyHourMatch[1], 10);
+            return `every ${n} hour${n === 1 ? '' : 's'} at :${String(minNum).padStart(2, '0')}`;
+        }
+        return expr;
+    }
+    catch {
+        return expr;
+    }
+}
+/** Format an hour (0-23) + minute (0-59) as "H:MM AM/PM". */
+function formatTime12(hour, minute) {
+    const period = hour < 12 ? 'AM' : 'PM';
+    const h = hour % 12 === 0 ? 12 : hour % 12;
+    const m = String(minute).padStart(2, '0');
+    return `${h}:${m} ${period}`;
+}
+// ---------------------------------------------------------------------------
+// humanizeNextRun
+// ---------------------------------------------------------------------------
+const WEEKDAY_NAMES = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+const MONTH_NAMES = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+/**
+ * Convert a next-run Date into a human phrase relative to `now`.
+ *
+ * - null            → '-'
+ * - same calendar day  → 'today 9:00 AM'
+ * - next calendar day  → 'tomorrow 9:00 AM'
+ * - within 7 days   → 'Mon 9:00 AM'
+ * - further out      → 'Jun 15, 9:00 AM'
+ */
+export function humanizeNextRun(date, now, tz) {
+    if (!date)
+        return '-';
+    try {
+        const locale = 'en-US';
+        const tzOpts = tz ? { timeZone: tz } : {};
+        // Extract calendar date components for both dates using the same timezone.
+        const toYMD = (d) => {
+            const fmt = new Intl.DateTimeFormat(locale, { year: 'numeric', month: 'numeric', day: 'numeric', ...tzOpts });
+            const parts = fmt.formatToParts(d);
+            const get = (type) => parseInt(parts.find((p) => p.type === type)?.value ?? '0', 10);
+            return { y: get('year'), m: get('month'), day: get('day') };
+        };
+        const nowYMD = toYMD(now);
+        const dateYMD = toYMD(date);
+        // Diff in whole calendar days (ignoring time-of-day)
+        const nowMidnight = Date.UTC(nowYMD.y, nowYMD.m - 1, nowYMD.day);
+        const dateMidnight = Date.UTC(dateYMD.y, dateYMD.m - 1, dateYMD.day);
+        const diffDays = Math.round((dateMidnight - nowMidnight) / 86400000);
+        // Time string for the date
+        const timeFmt = new Intl.DateTimeFormat(locale, { hour: 'numeric', minute: '2-digit', hour12: true, ...tzOpts });
+        const timeStr = timeFmt.format(date);
+        if (diffDays === 0)
+            return `today ${timeStr}`;
+        if (diffDays === 1)
+            return `tomorrow ${timeStr}`;
+        if (diffDays < 7) {
+            const weekdayIdx = new Intl.DateTimeFormat(locale, { weekday: 'short', ...tzOpts })
+                .formatToParts(date)
+                .find((p) => p.type === 'weekday')?.value;
+            return `${weekdayIdx ?? WEEKDAY_NAMES[date.getDay()]} ${timeStr}`;
+        }
+        // Further out: "Jun 15, 9:00 AM"
+        const monthName = MONTH_NAMES[dateYMD.m - 1];
+        return `${monthName} ${dateYMD.day}, ${timeStr}`;
+    }
+    catch {
+        return date.toLocaleString();
+    }
+}
+// ---------------------------------------------------------------------------
+// formatRepoLink
+// ---------------------------------------------------------------------------
+/**
+ * Parse a repo string into a display label and an optional hyperlink target.
+ *
+ * Rules:
+ *   - undefined / empty          → display '-', href null
+ *   - 'owner/name' (one slash)   → display 'owner/name', href 'https://github.com/owner/name/pulls'
+ *   - 'https://...' or 'http://…' → display hostname+path, href the URL verbatim
+ *   - anything else              → display raw string, href null
+ */
+export function formatRepoLink(repo) {
+    if (!repo || repo.trim() === '') {
+        return { display: '-', href: null };
+    }
+    const trimmed = repo.trim();
+    // Absolute URL
+    if (trimmed.startsWith('https://') || trimmed.startsWith('http://')) {
+        try {
+            const url = new URL(trimmed);
+            const display = url.hostname + url.pathname.replace(/\/$/, '');
+            return { display, href: trimmed };
+        }
+        catch {
+            return { display: trimmed, href: null };
+        }
+    }
+    // GitHub shorthand: owner/name (exactly one slash, no scheme, no extra slashes)
+    if (/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(trimmed)) {
+        return {
+            display: trimmed,
+            href: `https://github.com/${trimmed}/pulls`,
+        };
+    }
+    // Anything else: plain text, no link
+    return { display: trimmed, href: null };
+}

package/dist/lib/routines.d.ts

@@ -18,12 +18,14 @@ export interface JobConfig {
     name: string;
     schedule: string;
     agent: AgentId;
+    workflow?: string;
     mode: 'plan' | 'edit' | 'full';
     effort: 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';
     timeout: string;
     enabled: boolean;
     prompt: string;
     timezone?: string;
+    repo?: string;
     variables?: Record<string, string>;
     sandbox?: boolean;
     allow?: JobAllowConfig;
@@ -36,6 +38,7 @@ export interface RunMeta {
     jobName: string;
     runId: string;
     agent: AgentId;
+    workflow?: string;
     pid: number | null;
     status: 'running' | 'completed' | 'failed' | 'timeout';
     startedAt: string;
@@ -56,7 +59,10 @@ export declare function setJobEnabled(name: string, enabled: boolean): void;
 export declare function validateJob(config: Partial<JobConfig>): string[];
 /** Expand built-in and user-defined template variables in a job's prompt string. */
 export declare function resolveJobPrompt(config: JobConfig): string;
-/** Parse a human-readable timeout string (e.g. "30m", "2h", "1h30m") into milliseconds. */
+/** Parse a human-readable timeout string (e.g. "10m", "2h", "1h30m", "3d", "1w") into milliseconds.
+ *  Accepts combinations of w (weeks), d (days), h (hours), m (minutes).
+ *  Returns null if the string is empty, matches nothing, totals zero, or exceeds 1 week.
+ */
 export declare function parseTimeout(timeout: string): number | null;
 /** List all run metadata entries for a job, sorted chronologically. */
 export declare function listRuns(jobName: string): RunMeta[];

package/dist/lib/routines.js

@@ -17,7 +17,7 @@ import { ALL_AGENT_IDS } from './agents.js';
 const JOB_DEFAULTS = {
     mode: 'plan',
     effort: 'auto',
-    timeout: '30m',
+    timeout: '10m',
     enabled: true,
 };
 /** List all job configs from ~/.agents/routines/. */
@@ -73,7 +73,7 @@ export function writeJob(config) {
         delete output.mode;
     if (output.effort === 'auto')
         delete output.effort;
-    if (output.timeout === '30m')
+    if (output.timeout === '10m')
         delete output.timeout;
     if (output.enabled === true)
         delete output.enabled;
@@ -119,12 +119,22 @@ export function validateJob(config) {
             errors.push(`invalid cron expression: "${config.schedule}"`);
         }
     }
-    if (!config.agent || typeof config.agent !== 'string') {
-        errors.push('agent is required');
+    const hasAgent = Boolean(config.agent && typeof config.agent === 'string');
+    const hasWorkflow = Boolean(config.workflow && typeof config.workflow === 'string');
+    if (!hasAgent && !hasWorkflow) {
+        errors.push('exactly one of agent or workflow is required');
     }
-    if (config.agent && !ALL_AGENT_IDS.includes(config.agent)) {
+    else if (hasAgent && hasWorkflow) {
+        errors.push('exactly one of agent or workflow must be set (not both)');
+    }
+    if (hasAgent && config.agent && !ALL_AGENT_IDS.includes(config.agent)) {
         errors.push(`agent must be one of: ${ALL_AGENT_IDS.join(', ')}`);
     }
+    if (hasWorkflow && config.workflow) {
+        if (!/^[a-z0-9][a-z0-9_-]*$/.test(config.workflow)) {
+            errors.push('workflow must be a lowercase alphanumeric name (hyphens and underscores allowed, e.g. autodev)');
+        }
+    }
     if (config.mode && !['plan', 'edit', 'full'].includes(config.mode)) {
         errors.push('mode must be plan, edit, or full');
     }
@@ -135,7 +145,7 @@ export function validateJob(config) {
         errors.push('prompt is required');
     }
     if (config.timeout && !parseTimeout(config.timeout)) {
-        errors.push('timeout must be like 30m, 2h, 1h30m');
+        errors.push('timeout must be like 10m, 2h, 3d, 1w (max 1w)');
     }
     return errors;
 }
@@ -179,15 +189,25 @@ export function resolveJobPrompt(config) {
     }
     return prompt;
 }
-/** Parse a human-readable timeout string (e.g. "30m", "2h", "1h30m") into milliseconds. */
+/** Parse a human-readable timeout string (e.g. "10m", "2h", "1h30m", "3d", "1w") into milliseconds.
+ *  Accepts combinations of w (weeks), d (days), h (hours), m (minutes).
+ *  Returns null if the string is empty, matches nothing, totals zero, or exceeds 1 week.
+ */
 export function parseTimeout(timeout) {
-    const match = timeout.match(/^(?:(\d+)h)?(?:(\d+)m)?$/);
+    const match = timeout.match(/^(?:(\d+)w)?(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?$/);
     if (!match)
         return null;
-    const hours = parseInt(match[1] || '0', 10);
-    const minutes = parseInt(match[2] || '0', 10);
-    const ms = (hours * 60 + minutes) * 60 * 1000;
-    return ms > 0 ? ms : null;
+    const weeks = parseInt(match[1] || '0', 10);
+    const days = parseInt(match[2] || '0', 10);
+    const hours = parseInt(match[3] || '0', 10);
+    const minutes = parseInt(match[4] || '0', 10);
+    const ms = ((weeks * 7 + days) * 24 * 60 + hours * 60 + minutes) * 60 * 1000;
+    if (ms <= 0)
+        return null;
+    const ONE_WEEK_MS = 7 * 24 * 60 * 60 * 1000; // 604800000
+    if (ms > ONE_WEEK_MS)
+        return null;
+    return ms;
 }
 /** List all run metadata entries for a job, sorted chronologically. */
 export function listRuns(jobName) {

package/dist/lib/runner.js

@@ -23,6 +23,14 @@ const AGENT_COMMANDS = {
 };
 /** Build the full CLI argv for executing a job, applying mode, model, and permission flags. */
 export function buildJobCommand(config, resolvedPrompt) {
+    // Workflow branch: delegate to `agents run <workflow>` which handles subagent
+    // injection, WORKFLOW.md orchestration, and model selection via frontmatter.
+    // appendModelAndReasoning is intentionally skipped — the workflow frontmatter
+    // owns model selection. No --timeout flag: the runner enforces its own SIGTERM/SIGKILL.
+    if (config.workflow) {
+        const cmd = ['agents', 'run', config.workflow, resolvedPrompt, '--mode', config.mode];
+        return cmd;
+    }
     const template = AGENT_COMMANDS[config.agent];
     if (!template) {
         throw new Error(`Unsupported agent for daemon jobs: ${config.agent}`);
@@ -130,10 +138,14 @@ export async function executeJob(config) {
     if (config.timezone) {
         spawnEnv.TZ = config.timezone;
     }
+    // Workflows run via `agents run <workflow>` which delegates to claude under the hood.
+    // Use 'claude' as the effective agent for report extraction and metadata when workflow is set.
+    const effectiveAgent = config.workflow ? 'claude' : config.agent;
     const meta = {
         jobName: config.name,
         runId,
-        agent: config.agent,
+        agent: effectiveAgent,
+        ...(config.workflow ? { workflow: config.workflow } : {}),
         pid: null,
         status: 'running',
         startedAt: new Date().toISOString(),
@@ -141,7 +153,7 @@ export async function executeJob(config) {
         exitCode: null,
     };
     writeRunMeta(meta);
-    const timeoutMs = parseTimeout(config.timeout) || 30 * 60 * 1000;
+    const timeoutMs = parseTimeout(config.timeout) || 10 * 60 * 1000;
     return new Promise((resolve) => {
         const child = spawn(cmd[0], cmd.slice(1), {
             stdio: ['ignore', stdoutFd, stdoutFd],
@@ -173,7 +185,7 @@ export async function executeJob(config) {
             meta.completedAt = new Date().toISOString();
             writeRunMeta(meta);
             timer.end({ status: 'timeout', runId });
-            const reportPath = extractAndSaveReport(stdoutPath, config.agent, runDir);
+            const reportPath = extractAndSaveReport(stdoutPath, effectiveAgent, runDir);
             resolve({ meta, reportPath });
         }, timeoutMs);
         child.on('exit', (code) => {
@@ -190,7 +202,7 @@ export async function executeJob(config) {
             meta.completedAt = new Date().toISOString();
             writeRunMeta(meta);
             timer.end({ status: meta.status, exitCode: code ?? undefined, runId });
-            const reportPath = extractAndSaveReport(stdoutPath, config.agent, runDir);
+            const reportPath = extractAndSaveReport(stdoutPath, effectiveAgent, runDir);
             resolve({ meta, reportPath });
         });
         child.on('error', (err) => {
@@ -226,10 +238,12 @@ export async function executeJobDetached(config) {
     if (config.timezone) {
         spawnEnv.TZ = config.timezone;
     }
+    const effectiveAgent = config.workflow ? 'claude' : config.agent;
     const meta = {
         jobName: config.name,
         runId,
-        agent: config.agent,
+        agent: effectiveAgent,
+        ...(config.workflow ? { workflow: config.workflow } : {}),
         pid: null,
         status: 'running',
         startedAt: new Date().toISOString(),

package/dist/lib/scheduler.js

@@ -24,7 +24,14 @@ export class JobScheduler {
     }
     schedule(config) {
         this.unschedule(config.name);
-        const cron = new Cron(config.schedule, async () => {
+        // 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
+        // bubble up; defense in depth.
+        const cronOptions = { catch: true };
+        if (config.timezone)
+            cronOptions.timezone = config.timezone;
+        const cron = new Cron(config.schedule, cronOptions, async () => {
             try {
                 await this.onTrigger(config);
             }

package/dist/lib/secrets/{AgentsKeychain.app/Contents/Info.plist → Agents CLI.app/Contents/Info.plist }

@@ -5,9 +5,11 @@
   <key>CFBundleIdentifier</key>
   <string>com.phnx-labs.agents-keychain</string>
   <key>CFBundleName</key>
-  <string>AgentsKeychain</string>
+  <string>Agents CLI</string>
+  <key>CFBundleDisplayName</key>
+  <string>Agents CLI</string>
   <key>CFBundleExecutable</key>
-  <string>AgentsKeychain</string>
+  <string>Agents CLI</string>
   <key>CFBundlePackageType</key>
   <string>APPL</string>
   <key>CFBundleVersion</key>

package/dist/lib/secrets/bundles.d.ts

@@ -62,7 +62,11 @@ export declare function validateSecretType(t: string): asserts t is SecretType;
 export declare function validateExpiresFutureDated(iso: string): void;
 export declare function bundleExists(name: string): boolean;
 export declare function readBundle(name: string): SecretsBundle;
-export declare function writeBundle(bundle: SecretsBundle): void;
+export interface WriteBundleOptions {
+    /** Emit a secrets.set audit event. Internal bookkeeping writes turn this off. */
+    emitEvent?: boolean;
+}
+export declare function writeBundle(bundle: SecretsBundle, opts?: WriteBundleOptions): void;
 export declare function deleteBundle(name: string): boolean;
 export declare function listBundles(): SecretsBundle[];
 export interface BundleEntryInfo {
@@ -71,7 +75,34 @@ export interface BundleEntryInfo {
     detail: string;
 }
 export declare function describeBundle(bundle: SecretsBundle): BundleEntryInfo[];
-export declare function resolveBundleEnv(bundle: SecretsBundle): Record<string, string>;
+/** Options for resolveBundleEnv. */
+export interface ResolveBundleOptions {
+    /**
+     * Human-readable label for who is requesting the secrets. Shown to the
+     * user under the Touch ID prompt so they know what's about to read.
+     * Example: "agent claude", "command curl", "browser profile".
+     * When omitted the prompt only names the bundle.
+     */
+    caller?: string;
+}
+export declare function resolveBundleEnv(bundle: SecretsBundle, opts?: ResolveBundleOptions): Record<string, string>;
+/**
+ * Read a bundle's metadata AND resolve its env in a single Touch ID prompt.
+ *
+ * `readBundle` + `resolveBundleEnv` issued two separate `LAContext` calls
+ * (metadata read via `get-auth`, then secret values via `get-batch`) which
+ * surfaced as two consecutive Touch ID prompts. macOS does not honor
+ * "Always Allow" for items protected with `kSecAttrAccessControl`+biometry,
+ * so caching at the OS level was never an option. This collapses both reads
+ * into one `get-batch` call: we enumerate the bundle's secret items first
+ * (silent — `list` returns attrs only and does not trigger biometry) and
+ * include the metadata item in the same batch. One prompt, correctly scoped
+ * to the bundle name and caller.
+ */
+export declare function readAndResolveBundleEnv(name: string, opts?: ResolveBundleOptions): {
+    bundle: SecretsBundle;
+    env: Record<string, string>;
+};
 export declare function keychainRef(key: string): string;
 /** Options for rotateBundleSecret. */
 export interface RotateOptions {