@phnx-labs/agents-cli 1.20.62 → 1.20.64

package/dist/lib/routines.d.ts

@@ -18,6 +18,10 @@ export interface JobAllowConfig {
 export type GithubTriggerEvent = 'pull_request' | 'push' | 'issue_comment' | 'workflow_run';
 /** Canonical set of accepted GitHub trigger events — single source for validation. */
 export declare const GITHUB_TRIGGER_EVENTS: readonly GithubTriggerEvent[];
+/** Linear webhook resource types a routine can be triggered by. */
+export type LinearTriggerEvent = 'Issue' | 'IssueLabel' | 'Comment' | 'Project' | 'Cycle';
+/** Canonical set of accepted Linear trigger events — single source for validation. */
+export declare const LINEAR_TRIGGER_EVENTS: readonly LinearTriggerEvent[];
 /**
  * Map a user-facing `--on` alias to a canonical GitHub trigger event.
  * Accepts the canonical names plus friendly shortcuts (e.g. `pr`, `pr_opened`
@@ -26,11 +30,11 @@ export declare const GITHUB_TRIGGER_EVENTS: readonly GithubTriggerEvent[];
 export declare function normalizeTriggerEvent(input: string): GithubTriggerEvent | null;
 /**
  * Event-based fire condition for a routine — an alternative (or complement) to
- * `schedule`. Currently only `github_event`: an incoming GitHub webhook whose
- * event (and optional repo/branch) match fires the job through the same
- * dispatch path a cron fire uses. See `src/lib/triggers/webhook.ts`.
+ * `schedule`. Incoming webhooks whose source-specific filters match fire the job
+ * through the same dispatch path a cron fire uses. See
+ * `src/lib/triggers/webhook.ts`.
  */
-export interface JobTrigger {
+export interface GithubJobTrigger {
     type: 'github_event';
     event: GithubTriggerEvent;
     /** `owner/name` — when set, only payloads for this repo match. */
@@ -38,6 +42,17 @@ export interface JobTrigger {
     /** git branch (ref short name) — when set, only payloads for this branch match. */
     branch?: string;
 }
+export interface LinearJobTrigger {
+    type: 'linear_event';
+    event: LinearTriggerEvent;
+    /** Linear action, e.g. `create`, `update`, `remove`. */
+    action?: string;
+    /** Issue identifier prefix such as `RUSH`; useful when one webhook spans teams. */
+    teamKey?: string;
+    /** Required issue label name. */
+    label?: string;
+}
+export type JobTrigger = GithubJobTrigger | LinearJobTrigger;
 /**
  * Full configuration for a routine (persisted as YAML).
  *
@@ -51,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;
@@ -89,8 +112,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;
@@ -126,16 +151,20 @@ export interface JobEligibilityResult {
  */
 export declare function checkJobDeviceEligibility(config: Pick<JobConfig, 'name' | 'devices'>): JobEligibilityResult | null;
 /**
- * List all job configs, scanning project > user routine dirs.
- * Project routines (`<project>/.agents/routines/`) shadow user routines of the
- * same name. Project discovery is opt-in via `cwd`; the daemon (which calls
- * `listJobs()` with no argument) only sees user routines.
+ * List all job configs, scanning project > user > system routine dirs.
+ * Higher layers shadow lower ones of the same name (first-seen wins): a project
+ * routine shadows a user routine, and a user routine shadows a built-in system
+ * routine (`~/.agents/.system/routines/`, shipped via gh:phnx-labs/.agents-system).
+ * Project discovery is opt-in via `cwd`; the daemon (which calls `listJobs()`
+ * with no argument) sees user + system routines, so a built-in routine fires for
+ * every install unless the user overrides or disables it by name.
  */
 export declare function listJobs(cwd?: string): JobConfig[];
 /**
- * Read a single job config by name, checking project > user.
+ * Read a single job config by name, checking project > user > system.
  * Project discovery is opt-in via `cwd`; daemon callers pass no argument and
- * only resolve user routines.
+ * resolve user + system routines (a user routine of the same name shadows a
+ * built-in system routine).
  */
 export declare function readJob(name: string, cwd?: string): JobConfig | null;
 /** Write a job config to disk, omitting fields that match defaults.
@@ -186,6 +215,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

@@ -10,8 +10,8 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { Cron } from 'croner';
-import { getRoutinesDir, getRunsDir, ensureAgentsDir, getProjectRoutinesDir } from './state.js';
-import { safeJoin } from './paths.js';
+import { getRoutinesDir, getSystemRoutinesDir, getRunsDir, ensureAgentsDir, getProjectRoutinesDir } from './state.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';
@@ -22,6 +22,14 @@ export const GITHUB_TRIGGER_EVENTS = [
     'issue_comment',
     'workflow_run',
 ];
+/** Canonical set of accepted Linear trigger events — single source for validation. */
+export const LINEAR_TRIGGER_EVENTS = [
+    'Issue',
+    'IssueLabel',
+    'Comment',
+    'Project',
+    'Cycle',
+];
 /**
  * Map a user-facing `--on` alias to a canonical GitHub trigger event.
  * Accepts the canonical names plus friendly shortcuts (e.g. `pr`, `pr_opened`
@@ -79,10 +87,13 @@ const JOB_DEFAULTS = {
     enabled: true,
 };
 /**
- * List all job configs, scanning project > user routine dirs.
- * Project routines (`<project>/.agents/routines/`) shadow user routines of the
- * same name. Project discovery is opt-in via `cwd`; the daemon (which calls
- * `listJobs()` with no argument) only sees user routines.
+ * List all job configs, scanning project > user > system routine dirs.
+ * Higher layers shadow lower ones of the same name (first-seen wins): a project
+ * routine shadows a user routine, and a user routine shadows a built-in system
+ * routine (`~/.agents/.system/routines/`, shipped via gh:phnx-labs/.agents-system).
+ * Project discovery is opt-in via `cwd`; the daemon (which calls `listJobs()`
+ * with no argument) sees user + system routines, so a built-in routine fires for
+ * every install unless the user overrides or disables it by name.
  */
 export function listJobs(cwd) {
     ensureAgentsDir();
@@ -95,6 +106,7 @@ export function listJobs(cwd) {
             dirs.push(projectDir);
     }
     dirs.push(getRoutinesDir());
+    dirs.push(getSystemRoutinesDir());
     for (const dir of dirs) {
         if (!fs.existsSync(dir))
             continue;
@@ -112,9 +124,10 @@ export function listJobs(cwd) {
     return jobs;
 }
 /**
- * Read a single job config by name, checking project > user.
+ * Read a single job config by name, checking project > user > system.
  * Project discovery is opt-in via `cwd`; daemon callers pass no argument and
- * only resolve user routines.
+ * resolve user + system routines (a user routine of the same name shadows a
+ * built-in system routine).
  */
 export function readJob(name, cwd) {
     ensureAgentsDir();
@@ -125,6 +138,7 @@ export function readJob(name, cwd) {
             dirs.push(projectDir);
     }
     dirs.push(getRoutinesDir());
+    dirs.push(getSystemRoutinesDir());
     for (const dir of dirs) {
         for (const ext of ['.yml', '.yaml']) {
             const filePath = safeJoin(dir, name + ext);
@@ -260,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) {
@@ -284,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(', ')}`);
@@ -322,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)) {
@@ -358,17 +385,35 @@ export function validateTrigger(trigger) {
         return ['trigger must be an object'];
     }
     const t = trigger;
-    if (t.type !== 'github_event') {
-        errors.push("trigger.type must be 'github_event'");
+    if (t.type !== 'github_event' && t.type !== 'linear_event') {
+        errors.push("trigger.type must be 'github_event' or 'linear_event'");
+        return errors;
+    }
+    if (t.type === 'github_event') {
+        const github = t;
+        if (!github.event || !GITHUB_TRIGGER_EVENTS.includes(github.event)) {
+            errors.push(`trigger.event must be one of: ${GITHUB_TRIGGER_EVENTS.join(', ')}`);
+        }
+        if (github.repo !== undefined && (typeof github.repo !== 'string' || !/^[^/\s]+\/[^/\s]+$/.test(github.repo))) {
+            errors.push('trigger.repo must be in owner/name form');
+        }
+        if (github.branch !== undefined && typeof github.branch !== 'string') {
+            errors.push('trigger.branch must be a string');
+        }
+        return errors;
     }
-    if (!t.event || !GITHUB_TRIGGER_EVENTS.includes(t.event)) {
-        errors.push(`trigger.event must be one of: ${GITHUB_TRIGGER_EVENTS.join(', ')}`);
+    const linear = t;
+    if (!linear.event || !LINEAR_TRIGGER_EVENTS.includes(linear.event)) {
+        errors.push(`trigger.event must be one of: ${LINEAR_TRIGGER_EVENTS.join(', ')}`);
     }
-    if (t.repo !== undefined && (typeof t.repo !== 'string' || !/^[^/\s]+\/[^/\s]+$/.test(t.repo))) {
-        errors.push('trigger.repo must be in owner/name form');
+    if (linear.action !== undefined && typeof linear.action !== 'string') {
+        errors.push('trigger.action must be a string');
     }
-    if (t.branch !== undefined && typeof t.branch !== 'string') {
-        errors.push('trigger.branch must be a string');
+    if (linear.teamKey !== undefined && (typeof linear.teamKey !== 'string' || !/^[A-Z][A-Z0-9]*$/.test(linear.teamKey))) {
+        errors.push('trigger.teamKey must be an uppercase Linear team key');
+    }
+    if (linear.label !== undefined && typeof linear.label !== 'string') {
+        errors.push('trigger.label must be a string');
     }
     return errors;
 }
@@ -413,7 +458,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);
@@ -449,8 +494,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 })
@@ -473,13 +517,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 {
@@ -489,9 +533,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) {