@phnx-labs/agents-cli 1.12.0 → 1.14.2

package/dist/lib/rotate.js

@@ -0,0 +1,327 @@
+/**
+ * Account rotation across agent versions.
+ *
+ * Detects which installed versions have expired credentials and rotates
+ * authentication tokens so users maintain active sessions across version switches.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { getAccountInfo } from './agents.js';
+import { readMeta, writeMeta, getAgentsDir } from './state.js';
+import { listInstalledVersions, getVersionHomePath, resolveVersion } from './versions.js';
+import { getUsageInfoByIdentity, getUsageLookupKey, isClaudeAuthValid, } from './usage.js';
+export const RUN_STRATEGIES = ['pinned', 'available', 'balanced'];
+/**
+ * Return a run strategy when the input is valid, otherwise null.
+ *
+ * `'rotate'` is accepted as a deprecated alias for `'balanced'` so old yaml
+ * configs and `--strategy rotate` invocations keep working. The legacy alias
+ * normalizes to `'balanced'` and uses the weighted-random algorithm.
+ */
+export function normalizeRunStrategy(value) {
+    if (typeof value !== 'string')
+        return null;
+    if (value === 'rotate')
+        return 'balanced';
+    return RUN_STRATEGIES.includes(value) ? value : null;
+}
+/** Read project-local run strategy from the nearest agents.yaml, if present. */
+export function getProjectRunStrategy(agent, startPath) {
+    let dir = path.resolve(startPath);
+    const userAgentsYaml = path.join(getAgentsDir(), 'agents.yaml');
+    while (dir !== path.dirname(dir)) {
+        const manifestPath = path.join(dir, 'agents.yaml');
+        if (manifestPath !== userAgentsYaml && fs.existsSync(manifestPath)) {
+            try {
+                const parsed = yaml.parse(fs.readFileSync(manifestPath, 'utf-8'));
+                const strategy = normalizeRunStrategy(parsed?.run?.[agent]?.strategy);
+                if (strategy)
+                    return strategy;
+            }
+            catch {
+                // Ignore malformed project config and keep walking, matching version resolution.
+            }
+        }
+        dir = path.dirname(dir);
+    }
+    return null;
+}
+/** Resolve the configured strategy: project agents.yaml, then ~/.agents-system/agents.yaml, then pinned. */
+export function getConfiguredRunStrategy(agent, startPath = process.cwd()) {
+    return getProjectRunStrategy(agent, startPath)
+        ?? normalizeRunStrategy(readMeta().run?.[agent]?.strategy)
+        ?? 'pinned';
+}
+/** Persist the global run strategy used by bare `agents run <agent>`. */
+export function setGlobalRunStrategy(agent, strategy) {
+    const meta = readMeta();
+    if (!meta.run)
+        meta.run = {};
+    meta.run[agent] = { ...(meta.run[agent] ?? {}), strategy };
+    writeMeta(meta);
+}
+function isRotationEligible(candidate) {
+    return !!candidate.email
+        && candidate.authValid
+        && hasUsageAvailable(candidate);
+}
+function isAvailableEligible(candidate) {
+    return !!candidate.email
+        && candidate.authValid
+        && hasUsageAvailable(candidate);
+}
+function hasUsageAvailable(candidate) {
+    const usedPercent = getRoutingUsedPercent(candidate.usageSnapshot);
+    if (usedPercent !== null) {
+        return usedPercent < 100;
+    }
+    if (candidate.usageStatus === 'out_of_credits' || candidate.usageStatus === 'rate_limited') {
+        return false;
+    }
+    return true;
+}
+function getRoutingUsedPercent(snapshot) {
+    if (!snapshot || snapshot.windows.length === 0)
+        return null;
+    const routingWindows = snapshot.windows.filter((window) => window.key !== 'session');
+    const windows = routingWindows.length > 0 ? routingWindows : snapshot.windows;
+    return Math.max(...windows.map((window) => window.usedPercent));
+}
+function compareCandidates(a, b) {
+    const au = getRoutingUsedPercent(a.usageSnapshot);
+    const bu = getRoutingUsedPercent(b.usageSnapshot);
+    if (au !== null || bu !== null) {
+        if (au === null)
+            return 1;
+        if (bu === null)
+            return -1;
+        if (au !== bu)
+            return au - bu;
+    }
+    const ta = a.lastActive ? a.lastActive.getTime() : 0;
+    const tb = b.lastActive ? b.lastActive.getTime() : 0;
+    if (ta !== tb)
+        return ta - tb;
+    return Math.random() - 0.5;
+}
+function dedupeAndSortCandidates(candidates) {
+    const byEmail = new Map();
+    for (const c of candidates) {
+        const email = c.email;
+        const existing = byEmail.get(email);
+        if (!existing) {
+            byEmail.set(email, c);
+            continue;
+        }
+        if (compareCandidates(c, existing) < 0)
+            byEmail.set(email, c);
+    }
+    return [...byEmail.values()].sort(compareCandidates);
+}
+/**
+ * Pick a healthy candidate using weighted random by remaining capacity.
+ *
+ * Each healthy candidate gets weight = max(1, 100 - usedPercent) where
+ * usedPercent is the highest-utilized non-session window (week / sonnet_week
+ * for Claude). An account at 10% used gets weight 90; one at 90% used gets
+ * weight 10 — so the fresher account is 9× more likely to be picked. Over N
+ * calls, traffic distributes across healthy accounts proportional to their
+ * headroom, with no stampede on the lowest-usage one. Stateless — parallel
+ * callers naturally fan out via the random roll.
+ *
+ * Eligibility: signed in (email present), auth valid, and usage available
+ * (any non-session window strictly under 100%, or local flag not exhausted
+ * when no live snapshot exists).
+ *
+ * Dedupe: when multiple versions share an email, collapse to one candidate
+ * per email (the least-recently-active version). Prevents two parallel pods
+ * from "balancing" to different versions but hitting the same Anthropic
+ * account and both 429ing.
+ *
+ * Returns null if no candidate is eligible — callers fall back to the pinned
+ * version so behavior stays predictable.
+ */
+export function pickBalancedCandidate(candidates) {
+    const healthy = [];
+    const excluded = [];
+    for (const c of candidates) {
+        if (!isRotationEligible(c)) {
+            excluded.push(c);
+            continue;
+        }
+        healthy.push(c);
+    }
+    if (healthy.length === 0)
+        return null;
+    const sorted = dedupeAndSortCandidates(healthy);
+    const deduped = new Set(sorted);
+    for (const c of healthy) {
+        if (!deduped.has(c))
+            excluded.push(c);
+    }
+    const picked = weightedRandomByCapacity(sorted);
+    return { picked, healthy: sorted, excluded };
+}
+/**
+ * Pick one candidate from `sorted` using weights proportional to remaining
+ * routing capacity. Floor each weight at 1 so a near-exhausted-but-still-
+ * eligible candidate can still be picked occasionally. When usage is unknown
+ * (no live snapshot), treat the candidate as full-capacity (weight 100) — we
+ * have no signal to deprioritize it.
+ */
+function weightedRandomByCapacity(sorted) {
+    const weights = sorted.map((c) => {
+        const used = getRoutingUsedPercent(c.usageSnapshot);
+        if (used === null)
+            return 100;
+        return Math.max(1, 100 - used);
+    });
+    const total = weights.reduce((sum, w) => sum + w, 0);
+    if (total <= 0)
+        return sorted[0];
+    let roll = Math.random() * total;
+    for (let i = 0; i < sorted.length; i++) {
+        roll -= weights[i];
+        if (roll <= 0)
+            return sorted[i];
+    }
+    return sorted[sorted.length - 1];
+}
+/**
+ * Pick an available candidate. Prefers the configured pinned version when that
+ * version has usage available; otherwise routes to the candidate with the most
+ * usage headroom.
+ */
+export function pickAvailableCandidate(candidates, preferredVersion) {
+    const healthy = [];
+    const excluded = [];
+    for (const c of candidates) {
+        if (!isAvailableEligible(c)) {
+            excluded.push(c);
+            continue;
+        }
+        healthy.push(c);
+    }
+    if (healthy.length === 0)
+        return null;
+    const sorted = dedupeAndSortCandidates(healthy);
+    const deduped = new Set(sorted);
+    for (const c of healthy) {
+        if (!deduped.has(c))
+            excluded.push(c);
+    }
+    const preferred = preferredVersion
+        ? sorted.find((candidate) => candidate.version === preferredVersion)
+        : undefined;
+    return { picked: preferred ?? sorted[0], healthy: sorted, excluded };
+}
+async function collectRunCandidates(agent) {
+    const versions = listInstalledVersions(agent);
+    const rows = await Promise.all(versions.map(async (version) => {
+        const home = getVersionHomePath(agent, version);
+        const info = await getAccountInfo(agent, home);
+        const authValid = info.email
+            ? agent === 'claude' ? await isClaudeAuthValid(home) : true
+            : false;
+        return {
+            agent,
+            version,
+            home,
+            info,
+            email: info.email,
+            usageStatus: info.usageStatus,
+            authValid,
+            lastActive: info.lastActive,
+        };
+    }));
+    const { usageByKey } = await getUsageInfoByIdentity(rows.map(({ home, info, version }) => ({
+        agentId: agent,
+        home,
+        cliVersion: version,
+        info,
+    })));
+    return rows.map(({ home: _home, info, ...candidate }) => {
+        const usageKey = getUsageLookupKey(info);
+        const usageSnapshot = usageKey
+            ? usageByKey.get(usageKey)?.snapshot ?? null
+            : null;
+        return { ...candidate, usageSnapshot };
+    });
+}
+/**
+ * Pick a healthy version for `agent` using weighted random by remaining
+ * capacity. See `pickBalancedCandidate` for algorithm details.
+ *
+ * No external state — health and capacity are both read off per-version
+ * AccountInfo (same data `agents view` surfaces). The weighted random roll
+ * keeps parallel callers fanned out without rotation files or locks.
+ *
+ * Returns null if no installed version is eligible. Callers fall back to the
+ * global default so behavior stays predictable — we never refuse to run.
+ */
+export async function selectBalancedVersion(agent) {
+    return pickBalancedCandidate(await collectRunCandidates(agent));
+}
+/** Select the configured version if available, otherwise another available version. */
+export async function selectAvailableVersion(agent, preferredVersion) {
+    return pickAvailableCandidate(await collectRunCandidates(agent), preferredVersion);
+}
+/**
+ * Resolve the version `agents run` should use when the caller did not pin
+ * one with `@version`. The caller supplies the effective strategy; if that
+ * strategy cannot find a usable candidate, fall back to the pinned
+ * workspace/global version.
+ */
+/**
+ * Record a rotation pick so parallel callers see it as recently-used.
+ * Writes a stamp file per agent — lightweight, no locking needed since
+ * a torn write just means the next reader sees a stale timestamp (harmless).
+ */
+function recordRotationPick(agent, version) {
+    const stampPath = path.join(getAgentsDir(), `rotate-stamp-${agent}.json`);
+    try {
+        fs.writeFileSync(stampPath, JSON.stringify({ version, ts: Date.now() }), 'utf-8');
+    }
+    catch { /* best effort — doesn't block the run */ }
+}
+/**
+ * Read the most recent rotation pick for an agent. Returns null if no stamp
+ * or stamp is older than 60 seconds (stale).
+ */
+function readRotationStamp(agent) {
+    const stampPath = path.join(getAgentsDir(), `rotate-stamp-${agent}.json`);
+    try {
+        const raw = JSON.parse(fs.readFileSync(stampPath, 'utf-8'));
+        if (Date.now() - raw.ts < 60_000)
+            return raw.version;
+    }
+    catch { /* missing or corrupt — treat as no stamp */ }
+    return null;
+}
+export async function resolveRunVersion(agent, strategy, cwd = process.cwd()) {
+    const fallback = resolveVersion(agent, cwd);
+    if (strategy === 'pinned') {
+        return { version: fallback, rotation: null };
+    }
+    const rotation = strategy === 'available'
+        ? await selectAvailableVersion(agent, fallback)
+        : await selectBalancedVersion(agent);
+    if (rotation) {
+        // `available` is sticky to the pinned default when healthy. Use the 60s
+        // anti-collision stamp to nudge parallel callers off the same version.
+        // `balanced` doesn't need this — its weighted random roll already
+        // distributes naturally across healthy accounts.
+        if (strategy === 'available') {
+            const recentPick = readRotationStamp(agent);
+            if (recentPick === rotation.picked.version && rotation.healthy.length > 1) {
+                const alt = rotation.healthy.find(c => c.version !== recentPick);
+                if (alt)
+                    rotation.picked = alt;
+            }
+            recordRotationPick(agent, rotation.picked.version);
+        }
+        return { version: rotation.picked.version, rotation };
+    }
+    return { version: fallback, rotation: null };
+}

package/dist/lib/routines.d.ts

@@ -1,9 +1,19 @@
+/**
+ * Scheduled job (routine) configuration and run history management.
+ *
+ * Routines are YAML files in ~/.agents/routines/ that define recurring or
+ * one-shot agent tasks. This module handles CRUD operations on job configs,
+ * run metadata persistence, prompt variable expansion, and one-shot "at" time
+ * scheduling.
+ */
 import type { AgentId } from './types.js';
+/** Tool/site/directory allow-list for sandboxed job execution. */
 export interface JobAllowConfig {
     tools?: string[];
     sites?: string[];
     dirs?: string[];
 }
+/** Full configuration for a scheduled routine (persisted as YAML). */
 export interface JobConfig {
     name: string;
     schedule: string;
@@ -21,6 +31,7 @@ export interface JobConfig {
     version?: string;
     runOnce?: boolean;
 }
+/** Metadata for a single job execution, persisted as JSON in the run directory. */
 export interface RunMeta {
     jobName: string;
     runId: string;
@@ -31,24 +42,40 @@ export interface RunMeta {
     completedAt: string | null;
     exitCode: number | null;
 }
+/** List all job configs from ~/.agents/routines/. */
 export declare function listJobs(): JobConfig[];
+/** Read a single job config by name. Returns null if not found. */
 export declare function readJob(name: string): JobConfig | null;
+/** Write a job config to disk, omitting fields that match defaults. */
 export declare function writeJob(config: JobConfig): void;
+/** Delete a job config file by name. Returns true if the file existed. */
 export declare function deleteJob(name: string): boolean;
+/** Enable or disable a job by name. */
 export declare function setJobEnabled(name: string, enabled: boolean): void;
+/** Validate a partial job config, returning a list of human-readable errors. */
 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. */
 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[];
+/** Get the most recent run for a job, or null if never run. */
 export declare function getLatestRun(jobName: string): RunMeta | null;
+/** Persist run metadata to its run directory as meta.json. */
 export declare function writeRunMeta(meta: RunMeta): void;
+/** Read run metadata from disk. Returns null if missing or corrupt. */
 export declare function readRunMeta(jobName: string, runId: string): RunMeta | null;
+/** Get the filesystem path for a specific run's directory. */
 export declare function getRunDir(jobName: string, runId: string): string;
+/** Discover routine YAML files in a repository's routines/ directory. */
 export declare function discoverJobsFromRepo(repoPath: string): Array<{
     name: string;
     path: string;
 }>;
+/** Check whether a job with the given name exists on disk. */
 export declare function jobExists(name: string): boolean;
+/** Get the filesystem path of a job's YAML config file, or null if not found. */
 export declare function getJobPath(name: string): string | null;
 /**
  * Parse an "at" time string into a one-shot cron expression.
@@ -62,9 +89,10 @@ export declare function parseAtTime(atTime: string): {
     schedule: string;
     runOnce: boolean;
 } | null;
+/** Check if an installed job's normalized YAML matches the source file. */
 export declare function jobContentMatches(name: string, sourcePath: string): boolean;
+/** Install a job by reading and validating a YAML source file. */
 export declare function installJobFromSource(sourcePath: string, name: string): {
     success: boolean;
     error?: string;
 };
-//# sourceMappingURL=routines.d.ts.map

package/dist/lib/routines.js

@@ -1,15 +1,26 @@
+/**
+ * Scheduled job (routine) configuration and run history management.
+ *
+ * Routines are YAML files in ~/.agents/routines/ that define recurring or
+ * one-shot agent tasks. This module handles CRUD operations on job configs,
+ * run metadata persistence, prompt variable expansion, and one-shot "at" time
+ * scheduling.
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { Cron } from 'croner';
 import { getRoutinesDir, getRunsDir, ensureAgentsDir } from './state.js';
+import { safeJoin } from './paths.js';
 import { ALL_AGENT_IDS } from './agents.js';
+/** Default values applied to every job config when fields are omitted. */
 const JOB_DEFAULTS = {
     mode: 'plan',
     effort: 'auto',
     timeout: '30m',
     enabled: true,
 };
+/** List all job configs from ~/.agents/routines/. */
 export function listJobs() {
     ensureAgentsDir();
     const jobsDir = getRoutinesDir();
@@ -24,11 +35,12 @@ export function listJobs() {
     }
     return jobs;
 }
+/** Read a single job config by name. Returns null if not found. */
 export function readJob(name) {
     ensureAgentsDir();
     const jobsDir = getRoutinesDir();
     for (const ext of ['.yml', '.yaml']) {
-        const filePath = path.join(jobsDir, name + ext);
+        const filePath = safeJoin(jobsDir, name + ext);
         if (fs.existsSync(filePath)) {
             return readJobFile(filePath);
         }
@@ -51,10 +63,11 @@ function readJobFile(filePath) {
         return null;
     }
 }
+/** Write a job config to disk, omitting fields that match defaults. */
 export function writeJob(config) {
     ensureAgentsDir();
     const jobsDir = getRoutinesDir();
-    const filePath = path.join(jobsDir, config.name + '.yml');
+    const filePath = safeJoin(jobsDir, config.name + '.yml');
     const output = { ...config };
     if (output.mode === 'plan')
         delete output.mode;
@@ -68,10 +81,11 @@ export function writeJob(config) {
         delete output.runOnce;
     fs.writeFileSync(filePath, yaml.stringify(output), 'utf-8');
 }
+/** Delete a job config file by name. Returns true if the file existed. */
 export function deleteJob(name) {
     const jobsDir = getRoutinesDir();
     for (const ext of ['.yml', '.yaml']) {
-        const filePath = path.join(jobsDir, name + ext);
+        const filePath = safeJoin(jobsDir, name + ext);
         if (fs.existsSync(filePath)) {
             fs.unlinkSync(filePath);
             return true;
@@ -79,6 +93,7 @@ export function deleteJob(name) {
     }
     return false;
 }
+/** Enable or disable a job by name. */
 export function setJobEnabled(name, enabled) {
     const job = readJob(name);
     if (!job)
@@ -86,6 +101,7 @@ export function setJobEnabled(name, enabled) {
     job.enabled = enabled;
     writeJob(job);
 }
+/** Validate a partial job config, returning a list of human-readable errors. */
 export function validateJob(config) {
     const errors = [];
     if (!config.name || typeof config.name !== 'string') {
@@ -123,6 +139,7 @@ export function validateJob(config) {
     }
     return errors;
 }
+/** Expand built-in and user-defined template variables in a job's prompt string. */
 export function resolveJobPrompt(config) {
     const now = new Date();
     const tz = config.timezone || Intl.DateTimeFormat().resolvedOptions().timeZone;
@@ -162,6 +179,7 @@ export function resolveJobPrompt(config) {
     }
     return prompt;
 }
+/** Parse a human-readable timeout string (e.g. "30m", "2h", "1h30m") into milliseconds. */
 export function parseTimeout(timeout) {
     const match = timeout.match(/^(?:(\d+)h)?(?:(\d+)m)?$/);
     if (!match)
@@ -171,6 +189,7 @@ export function parseTimeout(timeout) {
     const ms = (hours * 60 + minutes) * 60 * 1000;
     return ms > 0 ? ms : null;
 }
+/** List all run metadata entries for a job, sorted chronologically. */
 export function listRuns(jobName) {
     const runsDir = getRunsDir();
     const jobRunsDir = path.join(runsDir, jobName);
@@ -188,16 +207,19 @@ export function listRuns(jobName) {
     }
     return runs;
 }
+/** Get the most recent run for a job, or null if never run. */
 export function getLatestRun(jobName) {
     const runs = listRuns(jobName);
     return runs.length > 0 ? runs[runs.length - 1] : null;
 }
+/** Persist run metadata to its run directory as meta.json. */
 export function writeRunMeta(meta) {
     ensureAgentsDir();
     const runDir = path.join(getRunsDir(), meta.jobName, meta.runId);
     fs.mkdirSync(runDir, { recursive: true });
     fs.writeFileSync(path.join(runDir, 'meta.json'), JSON.stringify(meta, null, 2), 'utf-8');
 }
+/** Read run metadata from disk. Returns null if missing or corrupt. */
 export function readRunMeta(jobName, runId) {
     const metaPath = path.join(getRunsDir(), jobName, runId, 'meta.json');
     if (!fs.existsSync(metaPath))
@@ -209,9 +231,11 @@ export function readRunMeta(jobName, runId) {
         return null;
     }
 }
+/** Get the filesystem path for a specific run's directory. */
 export function getRunDir(jobName, runId) {
     return path.join(getRunsDir(), jobName, runId);
 }
+/** Discover routine YAML files in a repository's routines/ directory. */
 export function discoverJobsFromRepo(repoPath) {
     const jobsPath = path.join(repoPath, 'routines');
     if (!fs.existsSync(jobsPath))
@@ -223,13 +247,15 @@ export function discoverJobsFromRepo(repoPath) {
         path: path.join(jobsPath, f),
     }));
 }
+/** Check whether a job with the given name exists on disk. */
 export function jobExists(name) {
     return readJob(name) !== null;
 }
+/** Get the filesystem path of a job's YAML config file, or null if not found. */
 export function getJobPath(name) {
     const jobsDir = getRoutinesDir();
     for (const ext of ['.yml', '.yaml']) {
-        const filePath = path.join(jobsDir, name + ext);
+        const filePath = safeJoin(jobsDir, name + ext);
         if (fs.existsSync(filePath)) {
             return filePath;
         }
@@ -282,6 +308,7 @@ export function parseAtTime(atTime) {
     }
     return null;
 }
+/** Check if an installed job's normalized YAML matches the source file. */
 export function jobContentMatches(name, sourcePath) {
     const existing = readJob(name);
     if (!existing)
@@ -300,6 +327,7 @@ export function jobContentMatches(name, sourcePath) {
         return false;
     }
 }
+/** Install a job by reading and validating a YAML source file. */
 export function installJobFromSource(sourcePath, name) {
     try {
         const content = fs.readFileSync(sourcePath, 'utf-8');
@@ -322,4 +350,3 @@ export function installJobFromSource(sourcePath, name) {
         return { success: false, error: err.message };
     }
 }
-//# sourceMappingURL=routines.js.map

package/dist/lib/runner.d.ts

@@ -1,12 +1,25 @@
+/**
+ * Job execution engine for routines.
+ *
+ * Builds agent-specific CLI commands from job configs, spawns them with
+ * sandboxed or unsandboxed environments, captures stdout to log files,
+ * enforces timeouts, and extracts the final assistant report from the
+ * agent's stream-JSON output.
+ */
 import type { JobConfig, RunMeta } from './routines.js';
 import type { AgentId } from './types.js';
+/** Result of a completed job execution, including metadata and optional report. */
 export interface RunResult {
     meta: RunMeta;
     reportPath: string | null;
 }
+/** Build the full CLI argv for executing a job, applying mode, model, and permission flags. */
 export declare function buildJobCommand(config: JobConfig, resolvedPrompt: string): string[];
+/** Execute a job synchronously (waits for completion or timeout before resolving). */
 export declare function executeJob(config: JobConfig): Promise<RunResult>;
+/** Spawn a job as a detached process and return immediately with run metadata. */
 export declare function executeJobDetached(config: JobConfig): Promise<RunMeta>;
+/** Extract the final assistant message from a stream-JSON log file as a markdown report. */
 export declare function extractReport(stdoutPath: string, agentType: AgentId): string | null;
+/** Scan all runs marked "running" and finalize any whose process has exited. */
 export declare function monitorRunningJobs(): void;
-//# sourceMappingURL=runner.d.ts.map