@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/dist/lib/convert.js

@@ -1,3 +1,10 @@
+/**
+ * Format conversion between Markdown (Claude/Codex) and TOML (Gemini) command files.
+ *
+ * Handles frontmatter parsing and bidirectional translation so that slash commands
+ * authored in one format can be synced to agents that expect the other.
+ */
+/** Extract YAML frontmatter and body from a Markdown string. Returns empty frontmatter if none found. */
 export function parseMarkdownFrontmatter(content) {
     const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
     if (!match) {
@@ -16,6 +23,7 @@ export function parseMarkdownFrontmatter(content) {
     }
     return { frontmatter, body };
 }
+/** Convert a Markdown command file to Gemini's TOML format, translating $ARGUMENTS to {{args}}. */
 export function markdownToToml(skillName, markdown) {
     const { frontmatter, body } = parseMarkdownFrontmatter(markdown);
     const description = frontmatter.description || `Run ${skillName} command`;
@@ -32,6 +40,7 @@ export function markdownToToml(skillName, markdown) {
     ];
     return lines.join('\n');
 }
+/** Convert a Gemini TOML command file back to Markdown format, translating {{args}} to $ARGUMENTS. */
 export function tomlToMarkdown(toml) {
     const nameMatch = toml.match(/name\s*=\s*"([^"]+)"/);
     const descMatch = toml.match(/description\s*=\s*"([^"]+)"/);
@@ -42,4 +51,3 @@ export function tomlToMarkdown(toml) {
     const lines = ['---', `description: ${description}`, '---', '', prompt, ''];
     return lines.join('\n');
 }
-//# sourceMappingURL=convert.js.map

package/dist/lib/daemon.d.ts

@@ -1,22 +1,42 @@
+/**
+ * Daemon lifecycle management for the routines scheduler.
+ *
+ * The daemon is a long-running process that holds a JobScheduler and
+ * triggers jobs on their cron schedules. It can be managed via launchd
+ * (macOS), systemd (Linux), or as a plain detached process. PID tracking,
+ * log output, reload (SIGHUP), and graceful shutdown are handled here.
+ */
+/** Read the stored daemon PID from disk. Returns null if not present or invalid. */
 export declare function readDaemonPid(): number | null;
+/** Write the daemon PID to the pid file. */
 export declare function writeDaemonPid(pid: number): void;
+/** Remove the daemon PID file. */
 export declare function removeDaemonPid(): void;
+/** Check if the daemon process is alive by sending signal 0 to the stored PID. */
 export declare function isDaemonRunning(): boolean;
+/** Append a timestamped log line to the daemon log file (owner-only permissions). */
 export declare function log(level: string, message: string): void;
+/** Main daemon loop: load jobs, schedule crons, monitor runs, and handle signals. */
 export declare function runDaemon(): Promise<void>;
+/** Generate a macOS launchd plist for auto-starting the daemon. */
 export declare function generateLaunchdPlist(): string;
+/** Generate a Linux systemd user unit for auto-starting the daemon. */
 export declare function generateSystemdUnit(): string;
+/** Start the daemon via launchd, systemd, or as a detached process. */
 export declare function startDaemon(): {
     pid: number | null;
     method: string;
 };
+/** Stop the daemon, unloading it from launchd/systemd if applicable. */
 export declare function stopDaemon(): boolean;
+/** Get current daemon status including running state, PID, and enabled job count. */
 export declare function getDaemonStatus(): {
     running: boolean;
     pid: number | null;
     jobCount: number;
     logPath: string;
 };
+/** Read the daemon log, optionally limited to the last N lines. */
 export declare function readDaemonLog(lines?: number): string;
+/** Send SIGHUP to the daemon to trigger a job reload. */
 export declare function signalDaemonReload(): boolean;
-//# sourceMappingURL=daemon.d.ts.map

package/dist/lib/daemon.js

@@ -1,3 +1,11 @@
+/**
+ * Daemon lifecycle management for the routines scheduler.
+ *
+ * The daemon is a long-running process that holds a JobScheduler and
+ * triggers jobs on their cron schedules. It can be managed via launchd
+ * (macOS), systemd (Linux), or as a plain detached process. PID tracking,
+ * log output, reload (SIGHUP), and graceful shutdown are handled here.
+ */
 import { spawn, execSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -7,12 +15,57 @@ import { listJobs as listAllJobs } from './routines.js';
 import { JobScheduler } from './scheduler.js';
 import { executeJobDetached, monitorRunningJobs } from './runner.js';
 const PID_FILE = 'daemon.pid';
+const LOCK_FILE = 'daemon.lock';
 const LOG_FILE = 'daemon.log';
-const PLIST_NAME = 'co.swarmify.agents-daemon';
+const PLIST_NAME = 'com.phnx-labs.agents-daemon';
 const SYSTEMD_UNIT = 'agents-daemon.service';
 function getPidPath() {
     return path.join(getAgentsDir(), PID_FILE);
 }
+function getLockPath() {
+    return path.join(getAgentsDir(), LOCK_FILE);
+}
+/**
+ * Acquire an exclusive start lock. Returns a release function on success,
+ * or null if another process already holds the lock. Uses O_EXCL to
+ * atomically create the file — no TOCTOU window.
+ */
+function acquireStartLock() {
+    const lockPath = getLockPath();
+    try {
+        const fd = fs.openSync(lockPath, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY);
+        fs.writeSync(fd, String(process.pid));
+        fs.closeSync(fd);
+        return () => {
+            try {
+                fs.unlinkSync(lockPath);
+            }
+            catch { /* already removed */ }
+        };
+    }
+    catch (err) {
+        if (err.code === 'EEXIST') {
+            // Lock file exists — check if the holder is still alive (stale lock recovery)
+            try {
+                const holderPid = parseInt(fs.readFileSync(lockPath, 'utf-8').trim(), 10);
+                if (!isNaN(holderPid)) {
+                    try {
+                        process.kill(holderPid, 0);
+                        return null; // holder is alive, lock is valid
+                    }
+                    catch {
+                        // holder is dead, remove stale lock and retry once
+                        fs.unlinkSync(lockPath);
+                        return acquireStartLock();
+                    }
+                }
+            }
+            catch { /* can't read lock file — treat as held */ }
+            return null;
+        }
+        throw err;
+    }
+}
 function getLogPath() {
     return path.join(getAgentsDir(), LOG_FILE);
 }
@@ -22,6 +75,7 @@ function getLaunchdPlistPath() {
 function getSystemdUnitPath() {
     return path.join(os.homedir(), '.config', 'systemd', 'user', `${SYSTEMD_UNIT}`);
 }
+/** Read the stored daemon PID from disk. Returns null if not present or invalid. */
 export function readDaemonPid() {
     const pidPath = getPidPath();
     if (!fs.existsSync(pidPath))
@@ -34,15 +88,18 @@ export function readDaemonPid() {
         return null;
     }
 }
+/** Write the daemon PID to the pid file. */
 export function writeDaemonPid(pid) {
     fs.writeFileSync(getPidPath(), String(pid), 'utf-8');
 }
+/** Remove the daemon PID file. */
 export function removeDaemonPid() {
     const pidPath = getPidPath();
     if (fs.existsSync(pidPath)) {
         fs.unlinkSync(pidPath);
     }
 }
+/** Check if the daemon process is alive by sending signal 0 to the stored PID. */
 export function isDaemonRunning() {
     const pid = readDaemonPid();
     if (!pid)
@@ -56,11 +113,27 @@ export function isDaemonRunning() {
         return false;
     }
 }
+/** Redact values that look like tokens or credentials in a log message. */
+function redactSecrets(message) {
+    let safe = message;
+    safe = safe.replace(/eyJ[A-Za-z0-9_-]{20,}/g, '[REDACTED_TOKEN]');
+    safe = safe.replace(/Bearer\s+\S+/gi, 'Bearer [REDACTED]');
+    safe = safe.replace(/(sk-[a-zA-Z0-9]{20,})/g, '[REDACTED_KEY]');
+    safe = safe.replace(/(ANTHROPIC_API_KEY|OPENAI_API_KEY|API_KEY|SECRET|TOKEN|PASSWORD)=\S+/gi, '$1=[REDACTED]');
+    return safe;
+}
+/** Append a timestamped log line to the daemon log file (owner-only permissions). */
 export function log(level, message) {
     const timestamp = new Date().toISOString();
-    const line = `[${timestamp}] [${level.toUpperCase()}] ${message}\n`;
-    fs.appendFileSync(getLogPath(), line, 'utf-8');
+    const line = `[${timestamp}] [${level.toUpperCase()}] ${redactSecrets(message)}\n`;
+    const logPath = getLogPath();
+    fs.appendFileSync(logPath, line, 'utf-8');
+    try {
+        fs.chmodSync(logPath, 0o600);
+    }
+    catch { /* best effort */ }
 }
+/** Main daemon loop: load jobs, schedule crons, monitor runs, and handle signals. */
 export async function runDaemon() {
     writeDaemonPid(process.pid);
     log('INFO', `Daemon started (PID: ${process.pid})`);
@@ -101,6 +174,7 @@ export async function runDaemon() {
     process.on('SIGINT', handleShutdown);
     await new Promise(() => { });
 }
+/** Generate a macOS launchd plist for auto-starting the daemon. */
 export function generateLaunchdPlist() {
     const agentsBin = getAgentsBinPath();
     const logPath = getLogPath();
@@ -132,6 +206,7 @@ export function generateLaunchdPlist() {
 </dict>
 </plist>`;
 }
+/** Generate a Linux systemd user unit for auto-starting the daemon. */
 export function generateSystemdUnit() {
     const agentsBin = getAgentsBinPath();
     return `[Unit]
@@ -156,11 +231,26 @@ function getAgentsBinPath() {
         return 'agents';
     }
 }
+/** Start the daemon via launchd, systemd, or as a detached process. */
 export function startDaemon() {
     if (isDaemonRunning()) {
         const pid = readDaemonPid();
         return { pid, method: 'already-running' };
     }
+    const releaseLock = acquireStartLock();
+    if (!releaseLock) {
+        // Another process is already starting the daemon
+        const pid = waitForPid(3000);
+        return { pid, method: 'already-starting' };
+    }
+    try {
+        return startDaemonLocked();
+    }
+    finally {
+        releaseLock();
+    }
+}
+function startDaemonLocked() {
     const platform = os.platform();
     if (platform === 'darwin') {
         try {
@@ -225,6 +315,7 @@ function waitForPid(timeoutMs) {
     }
     return readDaemonPid();
 }
+/** Stop the daemon, unloading it from launchd/systemd if applicable. */
 export function stopDaemon() {
     const platform = os.platform();
     if (platform === 'darwin') {
@@ -276,6 +367,7 @@ export function stopDaemon() {
     removeDaemonPid();
     return true;
 }
+/** Get current daemon status including running state, PID, and enabled job count. */
 export function getDaemonStatus() {
     const running = isDaemonRunning();
     const pid = readDaemonPid();
@@ -286,6 +378,7 @@ export function getDaemonStatus() {
     catch { /* job listing failed */ }
     return { running, pid, jobCount, logPath: getLogPath() };
 }
+/** Read the daemon log, optionally limited to the last N lines. */
 export function readDaemonLog(lines) {
     const logPath = getLogPath();
     if (!fs.existsSync(logPath))
@@ -296,6 +389,7 @@ export function readDaemonLog(lines) {
     const allLines = content.split('\n');
     return allLines.slice(-lines).join('\n');
 }
+/** Send SIGHUP to the daemon to trigger a job reload. */
 export function signalDaemonReload() {
     const pid = readDaemonPid();
     if (!pid)
@@ -308,4 +402,3 @@ export function signalDaemonReload() {
         return false;
     }
 }
-//# sourceMappingURL=daemon.js.map

package/dist/lib/drive-sync.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Remote drive sync for agent sessions and config.
+ *
+ * Provides rsync-based push/pull between the local ~/.agents/drive/
+ * directory and a remote host, plus attach/detach to swap the active
+ * agent's config directory symlink to the drive directory (for working
+ * with a remote machine's session data locally).
+ */
+/** Persisted drive configuration stored at ~/.agents/drive/config.json. */
 export interface DriveConfig {
     remote: string | null;
     attached: boolean;
@@ -8,13 +17,21 @@ export interface DriveConfig {
     lastPull: string | null;
     lastPush: string | null;
 }
+/** Read drive config from disk, returning defaults if missing. */
 export declare function readDriveConfig(): DriveConfig;
+/** Write drive config to disk. */
 export declare function writeDriveConfig(config: DriveConfig): void;
+/** Set the remote target (user@host) for rsync operations. */
 export declare function setRemote(target: string): void;
+/** Pull drive data from the remote host via rsync. */
 export declare function pull(): Promise<void>;
+/** Push local drive data to the remote host via rsync. */
 export declare function push(): Promise<void>;
+/** Attach drive by swapping the agent's config directory symlink to the drive directory. */
 export declare function attach(): void;
+/** Detach drive by restoring the agent's config directory to its previous symlink target. */
 export declare function detach(): void;
+/** Current drive state for display purposes. */
 export interface DriveStatus {
     remote: string | null;
     attached: boolean;
@@ -24,5 +41,5 @@ export interface DriveStatus {
     configDirTarget: string | null;
     homeFileTargets: Record<string, string | null>;
 }
+/** Gather current drive status by inspecting config, symlinks, and timestamps. */
 export declare function getDriveStatus(): DriveStatus;
-//# sourceMappingURL=drive-sync.d.ts.map

package/dist/lib/drive-sync.js

@@ -1,27 +1,61 @@
+/**
+ * Remote drive sync for agent sessions and config.
+ *
+ * Provides rsync-based push/pull between the local ~/.agents/drive/
+ * directory and a remote host, plus attach/detach to swap the active
+ * agent's config directory symlink to the drive directory (for working
+ * with a remote machine's session data locally).
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { exec } from 'child_process';
+import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { getDriveDir } from './state.js';
 import { AGENTS } from './agents.js';
-const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
+// `remote` flows from disk into rsync/ssh argv. Use a strict regex so a
+// tampered ~/.agents/drive/config.json can't sneak shell metacharacters or
+// argv flags (leading -) past the boundary.
+const REMOTE_RE = /^[a-zA-Z0-9._-]+@[a-zA-Z0-9._-]+$/;
+function assertValidRemote(remote) {
+    if (!REMOTE_RE.test(remote)) {
+        throw new Error(`Invalid drive remote: ${JSON.stringify(remote)}. Expected: user@host`);
+    }
+}
 const AGENT = 'claude';
 function configPath() {
     return path.join(getDriveDir(), 'config.json');
 }
+/** Read drive config from disk, returning defaults if missing. */
 export function readDriveConfig() {
     const p = configPath();
     if (fs.existsSync(p)) {
         try {
-            return JSON.parse(fs.readFileSync(p, 'utf-8'));
+            const parsed = JSON.parse(fs.readFileSync(p, 'utf-8'));
+            // Re-validate `remote` on every read. setRemote validates on write, but
+            // the file can be tampered with out-of-band (a malicious skill, a synced
+            // config from a hostile repo, etc.) and pull/push shell out with the value.
+            if (parsed.remote != null) {
+                assertValidRemote(parsed.remote);
+            }
+            return parsed;
         }
-        catch {
-            // Fall through to default
+        catch (err) {
+            // If the config is malformed or has a tainted remote, fail closed rather
+            // than silently fall back to defaults — a tainted remote that fell back
+            // to null would mask the attack.
+            if (err instanceof SyntaxError) {
+                // Bad JSON: fall through to defaults.
+            }
+            else {
+                throw err;
+            }
         }
     }
     return { remote: null, attached: false, previousTargets: null, lastPull: null, lastPush: null };
 }
+/** Write drive config to disk. */
 export function writeDriveConfig(config) {
     const dir = getDriveDir();
     if (!fs.existsSync(dir)) {
@@ -29,36 +63,43 @@ export function writeDriveConfig(config) {
     }
     fs.writeFileSync(configPath(), JSON.stringify(config, null, 2));
 }
+/** Set the remote target (user@host) for rsync operations. */
 export function setRemote(target) {
-    if (!target.match(/^[a-zA-Z0-9._-]+@[a-zA-Z0-9._-]+$/)) {
-        throw new Error(`Invalid remote: ${target}. Expected: user@host`);
-    }
+    assertValidRemote(target);
     const config = readDriveConfig();
     config.remote = target;
     writeDriveConfig(config);
 }
+/** Pull drive data from the remote host via rsync. */
 export async function pull() {
     const config = readDriveConfig();
     if (!config.remote)
         throw new Error('No remote configured. Run: agents drive remote <user@host>');
+    assertValidRemote(config.remote);
     const localDir = getDriveDir() + '/';
-    const remote = `${config.remote}:~/.agents/drive/`;
-    await execAsync(`rsync -az --exclude='config.json' ${remote} ${localDir}`);
+    const remoteSpec = `${config.remote}:~/.agents/drive/`;
+    // Argv form: no shell, no interpolation — even a tainted `config.remote` that
+    // somehow got past the regex cannot escape into command syntax.
+    await execFileAsync('rsync', ['-az', '--exclude=config.json', remoteSpec, localDir]);
     config.lastPull = new Date().toISOString();
     writeDriveConfig(config);
 }
+/** Push local drive data to the remote host via rsync. */
 export async function push() {
     const config = readDriveConfig();
     if (!config.remote)
         throw new Error('No remote configured. Run: agents drive remote <user@host>');
+    assertValidRemote(config.remote);
     const localDir = getDriveDir() + '/';
-    const remote = `${config.remote}:~/.agents/drive/`;
-    // Ensure remote directory exists
-    await execAsync(`ssh ${config.remote} 'mkdir -p ~/.agents/drive'`);
-    await execAsync(`rsync -az --exclude='config.json' ${localDir} ${remote}`);
+    const remoteSpec = `${config.remote}:~/.agents/drive/`;
+    // Ensure remote directory exists. ssh's command argument is one positional
+    // string; we hand it as a single argv element so no local shell sees it.
+    await execFileAsync('ssh', [config.remote, 'mkdir -p ~/.agents/drive']);
+    await execFileAsync('rsync', ['-az', '--exclude=config.json', localDir, remoteSpec]);
     config.lastPush = new Date().toISOString();
     writeDriveConfig(config);
 }
+/** Attach drive by swapping the agent's config directory symlink to the drive directory. */
 export function attach() {
     const config = readDriveConfig();
     if (config.attached)
@@ -123,6 +164,7 @@ export function attach() {
     config.attached = true;
     writeDriveConfig(config);
 }
+/** Detach drive by restoring the agent's config directory to its previous symlink target. */
 export function detach() {
     const config = readDriveConfig();
     if (!config.attached)
@@ -151,6 +193,7 @@ export function detach() {
     config.previousTargets = null;
     writeDriveConfig(config);
 }
+/** Gather current drive status by inspecting config, symlinks, and timestamps. */
 export function getDriveStatus() {
     const config = readDriveConfig();
     const home = os.homedir();
@@ -190,4 +233,3 @@ export function getDriveStatus() {
         homeFileTargets,
     };
 }
-//# sourceMappingURL=drive-sync.js.map

package/dist/lib/exec.d.ts

@@ -1,11 +1,16 @@
 import type { AgentId } from './types.js';
+/** Agent execution modes controlling tool access and autonomy level. */
 export type ExecMode = 'plan' | 'edit' | 'full';
+/** Reasoning effort levels passed to agents that support them. 'auto' defers to the agent's default. */
 export type ExecEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';
+/** Options for spawning an agent process. Omitting `prompt` launches the CLI interactively. */
 export interface ExecOptions {
     agent: AgentId;
     version?: string;
-    /** Omit to launch the CLI interactively — no prompt, no --print, stdio fully inherited. */
+    /** Omit to launch the CLI interactively -- no prompt, no --print, stdio fully inherited. */
     prompt?: string;
+    /** Force interactive mode even when a prompt is provided. */
+    interactive?: boolean;
     mode: ExecMode;
     effort: ExecEffort;
     cwd?: string;
@@ -18,8 +23,15 @@ export interface ExecOptions {
     verbose?: boolean;
     env?: Record<string, string>;
 }
+/** Parse an array of KEY=VALUE strings into an env record. Returns undefined for empty input. */
 export declare function parseExecEnv(entries: string[]): Record<string, string> | undefined;
+/**
+ * Build the process environment for an agent invocation.
+ * Pins CLAUDE_CONFIG_DIR for Claude and CODEX_HOME for Codex; strips the
+ * other agent's env var so it doesn't leak into unrelated invocations.
+ */
 export declare function buildExecEnv(options: ExecOptions): NodeJS.ProcessEnv;
+/** Describes how to translate ExecOptions into CLI arguments for a specific agent. */
 export interface AgentCommandTemplate {
     base: string[];
     promptFlag: 'positional' | string;
@@ -33,27 +45,33 @@ export interface AgentCommandTemplate {
     printFlags?: string[];
     verboseFlag?: string;
 }
+/** CLI command templates for every supported agent. */
 export declare const AGENT_COMMANDS: Record<AgentId, AgentCommandTemplate>;
+/** Assemble the full CLI argument array for an agent invocation. */
 export declare function buildExecCommand(options: ExecOptions): string[];
+/** Spawn an agent and return its exit code. Convenience wrapper over spawnAgent. */
 export declare function execAgent(options: ExecOptions): Promise<number>;
 /**
  * Patterns that indicate a rate/usage limit. Matching is intentionally broad
- * because providers phrase these differently — Anthropic uses "5-hour limit"
+ * because providers phrase these differently -- Anthropic uses "5-hour limit"
  * and "rate limit", OpenAI surfaces 429s, Google says "quota exceeded".
  * False positives here just trigger a fallback attempt; false negatives leave
  * the original error unhandled, which is worse.
  */
 export declare const RATE_LIMIT_PATTERNS: RegExp[];
+/** Return true if the text contains any known rate-limit or overload indicator. */
 export declare function detectRateLimit(text: string): boolean;
+/** An agent (with optional pinned version) in a fallback chain. */
 export interface FallbackEntry {
     agent: AgentId;
     /** Optional pinned version (e.g. '0.116.0'). When set, takes precedence over the active default. */
     version?: string;
 }
+/** ExecOptions extended with a fallback chain for rate-limit cascading. */
 export interface FallbackOptions extends ExecOptions {
     /** Ordered list of agents to try if the primary (options.agent) hits a rate limit. */
     fallback: FallbackEntry[];
-    /** Fallback requires a prompt — chain handoff doesn't apply to interactive sessions. */
+    /** Fallback requires a prompt -- chain handoff doesn't apply to interactive sessions. */
     prompt: string;
 }
 /**
@@ -63,7 +81,7 @@ export interface FallbackOptions extends ExecOptions {
  * When the prior agent was Claude we pin its session ID via `--session-id` so
  * `prevSessionId` is always defined; for other primaries we pass undefined and
  * get a simpler retry-with-context prompt. Claude understands `/continue <id>`
- * via its shipped skill — other agents fall through to an explicit instruction
+ * via its shipped skill -- other agents fall through to an explicit instruction
  * that points at the version-agnostic `agents sessions <id>` reader.
  */
 export declare function buildFallbackPrompt(prevAgent: AgentId, prevSessionId: string | undefined, nextAgent: AgentId, originalPrompt: string): string;
@@ -72,7 +90,7 @@ export declare function buildFallbackPrompt(prevAgent: AgentId, prevSessionId: s
  *
  * The primary agent gets the original prompt. Subsequent agents get a
  * `/continue <id>`-style handoff (see buildFallbackPrompt) when we can pin a
- * session ID — which today means Claude as primary (supports `--session-id`).
+ * session ID -- which today means Claude as primary (supports `--session-id`).
  * For other primaries, fallbacks run with the original prompt plus a
  * retry-with-context note, since we can't deterministically resolve their
  * auto-generated session IDs.
@@ -82,4 +100,3 @@ export declare function buildFallbackPrompt(prevAgent: AgentId, prevSessionId: s
  * instead of an opaque "all agents failed" message.
  */
 export declare function runWithFallback(options: FallbackOptions): Promise<number>;
-//# sourceMappingURL=exec.d.ts.map