@phnx-labs/agents-cli 1.20.63 → 1.20.65

package/dist/lib/routines.d.ts

@@ -66,8 +66,16 @@ export interface JobConfig {
     schedule?: string;
     /** Event/webhook fire condition. Optional when `schedule` is set. */
     trigger?: JobTrigger;
-    agent: AgentId;
+    /** Which agent runs the routine. Optional — omitted for `workflow`/`command` routines. Exactly one of agent/workflow/command must be set. */
+    agent?: AgentId;
     workflow?: string;
+    /**
+     * A plain shell command run directly instead of an agent/workflow — no LLM,
+     * no auth, no rotation, no tokens, no sandbox overlay. For deterministic
+     * housekeeping routines (version-check, `npm i -g`, `git pull`, notify).
+     * Mutually exclusive with `agent` and `workflow`.
+     */
+    command?: string;
     mode: 'plan' | 'edit' | 'auto' | 'skip' | 'full';
     effort: 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';
     timeout: string;
@@ -83,6 +91,17 @@ export interface JobConfig {
      * overdue; everywhere else it is inert and `run` refuses with a pointer.
      */
     devices?: string[];
+    /**
+     * Execution placement — run the job body on this machine over SSH (a
+     * registered host, device, capability tag, or user@host) instead of locally.
+     * Distinct from `devices`: `devices` says which daemon may FIRE the job,
+     * `host` says where the dispatched run EXECUTES. CLI flag: `--run-on`
+     * (`--host` on routines commands already means "manage routines on that
+     * machine" via the remote passthrough).
+     */
+    host?: string;
+    /** Working directory on the host for `host:`-placed runs. */
+    remoteCwd?: string;
     variables?: Record<string, string>;
     sandbox?: boolean;
     allow?: JobAllowConfig;
@@ -104,8 +123,10 @@ export interface JobConfig {
 export interface RunMeta {
     jobName: string;
     runId: string;
-    agent: AgentId;
+    agent?: AgentId;
     workflow?: string;
+    /** The shell command that ran, for command-mode routines (no agent). */
+    command?: string;
     pid: number | null;
     /** Process birth time (epoch ms) recorded at spawn for pid-reuse detection. */
     spawnedAt?: number;
@@ -113,6 +134,11 @@ export interface RunMeta {
     startedAt: string;
     completedAt: string | null;
     exitCode: number | null;
+    /** Set for `host:`-placed runs — where the job body executes (no local pid). */
+    host?: string;
+    /** The host-task sidecar id backing a `host:` run; the daemon monitor
+     *  finalizes the run by reconciling it against the remote `.exit`. */
+    hostTaskId?: string;
 }
 /**
  * True when the job may execute on this machine: no `devices` allowlist (or
@@ -205,6 +231,15 @@ export declare function getLatestRun(jobName: string): RunMeta | null;
 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;
+/**
+ * Runs directory for a single job, with the (untrusted) job name contained to a
+ * single segment beneath the runs dir — same guard as `getJobHomePath`. The name
+ * comes from routine YAML and can arrive via a synced config repo; every runs-dir
+ * sink (run dir, meta read/write, last-report read) routes through here so a
+ * crafted `name` like `../../../../tmp/x` can't `mkdirSync`/write `stdout.log`,
+ * `meta.json`, or `report.md` outside `~/.agents/.history/runs`.
+ */
+export declare function getJobRunsDir(jobName: string): string;
 /** 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. */

package/dist/lib/routines.js

@@ -11,7 +11,7 @@ import * as path from 'path';
 import * as yaml from 'yaml';
 import { Cron } from 'croner';
 import { getRoutinesDir, getSystemRoutinesDir, getRunsDir, ensureAgentsDir, getProjectRoutinesDir } from './state.js';
-import { safeJoin } from './paths.js';
+import { safeJoin, isSafeSegmentName } from './paths.js';
 import { atomicWriteFileSync } from './fs-atomic.js';
 import { ALL_AGENT_IDS } from './agents.js';
 import { machineId, normalizeHost } from './machine-id.js';
@@ -274,6 +274,13 @@ export function validateJob(config) {
     if (!config.name || typeof config.name !== 'string') {
         errors.push('name is required');
     }
+    else if (!isSafeSegmentName(config.name)) {
+        // The name becomes a filesystem path segment (overlay HOME under the
+        // routines dir). Reject separators, '.'/'..', and null bytes so a synced
+        // config can't traverse out of ~/.agents/routines.
+        errors.push(`invalid name ${JSON.stringify(config.name)}: must be a single path segment ` +
+            `(no '/', '\\\\', or null bytes, and not '.' or '..')`);
+    }
     const hasSchedule = Boolean(config.schedule && typeof config.schedule === 'string');
     const hasTrigger = config.trigger !== undefined;
     if (!hasSchedule && !hasTrigger) {
@@ -298,11 +305,16 @@ export function validateJob(config) {
     }
     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');
+    const hasCommand = Boolean(config.command && typeof config.command === 'string');
+    const set = [hasAgent, hasWorkflow, hasCommand].filter(Boolean).length;
+    if (set === 0) {
+        errors.push('exactly one of agent, workflow, or command is required');
+    }
+    else if (set > 1) {
+        errors.push('exactly one of agent, workflow, or command may be set (not more)');
     }
-    else if (hasAgent && hasWorkflow) {
-        errors.push('exactly one of agent or workflow must be set (not both)');
+    if (config.command !== undefined && (typeof config.command !== 'string' || config.command.trim() === '')) {
+        errors.push('command must be a non-empty shell command string');
     }
     if (hasAgent && config.agent && !ALL_AGENT_IDS.includes(config.agent)) {
         errors.push(`agent must be one of: ${ALL_AGENT_IDS.join(', ')}`);
@@ -336,7 +348,8 @@ export function validateJob(config) {
     if (config.effort && !['low', 'medium', 'high', 'xhigh', 'max', 'auto'].includes(config.effort)) {
         errors.push('effort must be low, medium, high, xhigh, max, or auto');
     }
-    if (!config.prompt || typeof config.prompt !== 'string') {
+    // command routines run a plain shell and never build a prompt; agent/workflow routines require one.
+    if (!hasCommand && (!config.prompt || typeof config.prompt !== 'string')) {
         errors.push('prompt is required');
     }
     if (config.timeout && !parseTimeout(config.timeout)) {
@@ -350,6 +363,25 @@ export function validateJob(config) {
     if (config.device !== undefined) {
         errors.push('singular "device" key is no longer supported — replace with devices: [<name>] (an array)');
     }
+    if (config.host !== undefined) {
+        if (typeof config.host !== 'string' || config.host.trim() === '') {
+            errors.push('host must be a non-empty machine name (a registered host, device, capability tag, or user@host)');
+        }
+        // v1: the workflow bundle and the loop driver (with its signal files) live
+        // on the firing machine — neither can cross SSH to the target yet.
+        if (config.workflow) {
+            errors.push("host: can't be combined with workflow: yet (the bundle lives on the firing machine) — run the workflow locally or convert it to a plain prompt");
+        }
+        if (config.loop) {
+            errors.push("host: can't be combined with loop: yet (the loop driver and its signal files live on the firing machine)");
+        }
+        if (config.command) {
+            errors.push("host: can't be combined with command: yet (a plain shell command has no agent to place remotely) — run it locally, or convert it to a prompt");
+        }
+    }
+    if (config.remoteCwd !== undefined && config.host === undefined) {
+        errors.push('remoteCwd only applies to host:-placed routines — set host: too, or drop it');
+    }
     if (config.devices !== undefined) {
         if (!Array.isArray(config.devices)) {
             errors.push('devices must be an array of device names (as shown by `agents devices`)');
@@ -445,7 +477,7 @@ export function resolveJobPrompt(config) {
     // Last report (special handling)
     const latestRun = getLatestRun(config.name);
     if (latestRun) {
-        const reportPath = path.join(getRunsDir(), config.name, latestRun.runId, 'report.md');
+        const reportPath = path.join(getJobRunsDir(config.name), latestRun.runId, 'report.md');
         if (fs.existsSync(reportPath)) {
             const report = fs.readFileSync(reportPath, 'utf-8');
             prompt = prompt.replace(/\{last_report\}/g, report);
@@ -481,8 +513,7 @@ export function parseTimeout(timeout) {
 }
 /** List all run metadata entries for a job, sorted chronologically. */
 export function listRuns(jobName) {
-    const runsDir = getRunsDir();
-    const jobRunsDir = path.join(runsDir, jobName);
+    const jobRunsDir = getJobRunsDir(jobName);
     if (!fs.existsSync(jobRunsDir))
         return [];
     const entries = fs.readdirSync(jobRunsDir, { withFileTypes: true })
@@ -505,13 +536,13 @@ export function getLatestRun(jobName) {
 /** Persist run metadata to its run directory as meta.json. */
 export function writeRunMeta(meta) {
     ensureAgentsDir();
-    const runDir = path.join(getRunsDir(), meta.jobName, meta.runId);
+    const runDir = path.join(getJobRunsDir(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');
+    const metaPath = path.join(getJobRunsDir(jobName), runId, 'meta.json');
     if (!fs.existsSync(metaPath))
         return null;
     try {
@@ -521,9 +552,20 @@ export function readRunMeta(jobName, runId) {
         return null;
     }
 }
+/**
+ * Runs directory for a single job, with the (untrusted) job name contained to a
+ * single segment beneath the runs dir — same guard as `getJobHomePath`. The name
+ * comes from routine YAML and can arrive via a synced config repo; every runs-dir
+ * sink (run dir, meta read/write, last-report read) routes through here so a
+ * crafted `name` like `../../../../tmp/x` can't `mkdirSync`/write `stdout.log`,
+ * `meta.json`, or `report.md` outside `~/.agents/.history/runs`.
+ */
+export function getJobRunsDir(jobName) {
+    return safeJoin(getRunsDir(), jobName);
+}
 /** Get the filesystem path for a specific run's directory. */
 export function getRunDir(jobName, runId) {
-    return path.join(getRunsDir(), jobName, runId);
+    return path.join(getJobRunsDir(jobName), runId);
 }
 /** Discover routine YAML files in a repository's routines/ directory. */
 export function discoverJobsFromRepo(repoPath) {

package/dist/lib/runner.d.ts

@@ -77,6 +77,7 @@ export declare function buildRoutineSpawnEnv(baseEnv: Record<string, string>, ag
  */
 export declare function executeJob(config: JobConfig, deps?: LoopDeps): Promise<RunResult>;
 /** Spawn a job as a detached process and return immediately with run metadata. */
+/** 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;