@phnx-labs/agents-cli 1.20.64 → 1.20.65

package/dist/lib/hosts/run-target.js

@@ -0,0 +1,99 @@
+/**
+ * Shared host-run dispatch — the one path every surface uses to run an agent on
+ * another machine: `agents run --host` (commands/exec.ts), the `host` cloud
+ * provider (`agents cloud run --provider host`), and host-placed routines.
+ *
+ * Wraps the two steps every caller needs and previously lived inline in
+ * exec.ts's `--host` branch:
+ *   1. resolution — name → capability tag → error, with the same fall-through
+ *      semantics as `agents run --host` (only "Multiple hosts tagged…" is a
+ *      resolution verdict; "no host tagged" degrades to unknown-host), and
+ *   2. headless dispatch — session-id mint (Claude only), detached SSH launch,
+ *      and LOCAL session-index registration so the run shows in `agents sessions`.
+ *
+ * Interactive dispatch stays in exec.ts: it is inherently tied to the caller's
+ * TTY and has no other consumers.
+ */
+import { randomUUID } from 'crypto';
+import { resolveHost, resolveHostByCap } from './registry.js';
+import { dispatchToHost } from './dispatch.js';
+import { registerHostSession } from './session-index.js';
+/**
+ * Resolution failed with a user-actionable message the caller should print
+ * verbatim. Distinct from `DeviceOffloadUnsupportedError` (which propagates to
+ * the top-level catch) so callers can tell "bad name" from "bad auth method".
+ */
+export class HostResolutionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HostResolutionError';
+    }
+}
+/**
+ * Resolve a `--host` value the way `agents run` does: exact name (providers →
+ * devices → `user@host`), then capability tag. Throws `HostResolutionError`
+ * for an ambiguous tag or an unknown name; lets `DeviceOffloadUnsupportedError`
+ * (password-auth device) propagate untouched for the top-level catch.
+ */
+export async function resolveHostRunTarget(name, opts = {}) {
+    let host = await resolveHost(name);
+    if (!host) {
+        try {
+            host = await resolveHostByCap(name, opts.any);
+        }
+        catch (e) {
+            const msg = e.message ?? '';
+            // Ambiguity is a verdict, not a miss — surface it. "No host tagged"
+            // falls through to the generic unknown-host error below.
+            if (msg.startsWith('Multiple hosts'))
+                throw new HostResolutionError(msg);
+        }
+    }
+    if (!host)
+        throw new HostResolutionError(`Unknown host "${name}". List hosts: agents hosts list`);
+    return host;
+}
+/**
+ * Dispatch a headless prompt run onto a resolved host: mint the forced session
+ * id (Claude is the only agent that accepts `--session-id`; on resume the
+ * remote session keeps its id), launch detached over SSH, and register the run
+ * in the LOCAL session index. Returns the task record and the remote exit code
+ * (`-1` = follow window closed while the run continues).
+ */
+export async function dispatchPromptToHost(host, opts) {
+    const sessionId = opts.agent === 'claude' && !opts.resume ? randomUUID() : undefined;
+    const result = await dispatchToHost(host, {
+        agent: opts.agent,
+        prompt: opts.prompt,
+        version: opts.version,
+        mode: opts.mode,
+        model: opts.model,
+        remoteCwd: opts.remoteCwd,
+        sessionId,
+        name: opts.name,
+        resume: opts.resume,
+        follow: opts.follow !== false,
+        timeoutMs: opts.timeoutMs,
+        effort: opts.effort,
+        env: opts.env,
+        addDir: opts.addDir,
+        timeout: opts.timeout,
+        strategy: opts.strategy,
+        balanced: opts.balanced,
+        fallback: opts.fallback,
+        loop: opts.loop,
+        maxIterations: opts.maxIterations,
+        budget: opts.budget,
+        until: opts.until,
+        interval: opts.interval,
+        json: opts.json,
+        verbose: opts.verbose,
+        yes: opts.yes,
+        acp: opts.acp,
+        autoSecrets: opts.autoSecrets,
+        passthroughArgs: opts.passthroughArgs,
+        copyCreds: opts.copyCreds,
+    });
+    registerHostSession(result.task, { cwd: opts.cwd ?? process.cwd(), prompt: opts.prompt });
+    return result;
+}

package/dist/lib/hosts/types.d.ts

@@ -2,13 +2,14 @@
  * Agent-host provider contract.
  *
  * A `HostProvider` answers "what are my hosts, and how do I reach them?" — the
- * pluggable directory/metadata/reachability layer. v1 ships only the `local`
- * provider (ssh-config ∪ inline registry); `rush`/`tailscale`/`crabbox` are
- * additive fast-follows behind this same contract. Capability-gated so partial
- * providers are first-class (mirrors the cloud provider registry).
+ * pluggable directory/metadata/reachability layer. Shipped providers: `local`
+ * (ssh-config ∪ inline registry) and `devices` (the Tailscale fleet from
+ * `agents devices`); `rush`/`crabbox` remain additive fast-follows behind this
+ * same contract. Capability-gated so partial providers are first-class
+ * (mirrors the cloud provider registry).
  */
 import type { HostEntry } from '../types.js';
-export type HostProviderId = 'local';
+export type HostProviderId = 'local' | 'devices';
 export type HostStatus = 'online' | 'offline' | 'unknown';
 /** A host as seen at runtime: its persisted entry plus name/provider/status. */
 export interface Host extends HostEntry {
@@ -17,6 +18,23 @@ export interface Host extends HostEntry {
     /** True when the host has an explicit overlay/inline entry in the registry. */
     enrolled?: boolean;
     status?: HostStatus;
+    /**
+     * False when the host is listed for honesty but can't carry a `--host` run
+     * (today: password-auth devices — offload rides BatchMode=yes ssh). Absent
+     * means dispatchable. Cap routing and target pickers filter on this.
+     */
+    dispatchable?: boolean;
+}
+/**
+ * Thrown when a device resolves but can't be used as an offload target because
+ * it authenticates with a password. The offload path runs over `sshExec`, whose
+ * `SSH_OPTS` force `BatchMode=yes` (no password prompts), so only key / ssh-config
+ * auth can carry a `--host` run. Named so the top-level catch prints the message
+ * cleanly instead of a stack trace. (Lives here, not registry.ts, so providers
+ * can throw it without a circular import; registry.ts re-exports it.)
+ */
+export declare class DeviceOffloadUnsupportedError extends Error {
+    constructor(name: string);
 }
 export interface HostProviderCapabilities {
     /** Can list/track hosts. */

package/dist/lib/hosts/types.js

@@ -2,11 +2,29 @@
  * Agent-host provider contract.
  *
  * A `HostProvider` answers "what are my hosts, and how do I reach them?" — the
- * pluggable directory/metadata/reachability layer. v1 ships only the `local`
- * provider (ssh-config ∪ inline registry); `rush`/`tailscale`/`crabbox` are
- * additive fast-follows behind this same contract. Capability-gated so partial
- * providers are first-class (mirrors the cloud provider registry).
+ * pluggable directory/metadata/reachability layer. Shipped providers: `local`
+ * (ssh-config ∪ inline registry) and `devices` (the Tailscale fleet from
+ * `agents devices`); `rush`/`crabbox` remain additive fast-follows behind this
+ * same contract. Capability-gated so partial providers are first-class
+ * (mirrors the cloud provider registry).
  */
+/**
+ * Thrown when a device resolves but can't be used as an offload target because
+ * it authenticates with a password. The offload path runs over `sshExec`, whose
+ * `SSH_OPTS` force `BatchMode=yes` (no password prompts), so only key / ssh-config
+ * auth can carry a `--host` run. Named so the top-level catch prints the message
+ * cleanly instead of a stack trace. (Lives here, not registry.ts, so providers
+ * can throw it without a circular import; registry.ts re-exports it.)
+ */
+export class DeviceOffloadUnsupportedError extends Error {
+    constructor(name) {
+        super(`Device "${name}" uses password auth, which --host offload can't use yet ` +
+            `(runs go over ssh with BatchMode=yes). Switch it to key auth with ` +
+            `\`agents devices set ${name} --auth key\`, or enroll it as a host with ` +
+            `\`agents hosts add ${name}\`.`);
+        this.name = 'DeviceOffloadUnsupportedError';
+    }
+}
 /**
  * The ssh target string for a host: the bare name for ssh-config hosts (ssh
  * resolves HostName/User/Port/Identity), else `user@address` (or `address`).

package/dist/lib/linear-autoclose.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Linear auto-close: close Linear issues whose linked GitHub PRs have merged.
+ *
+ * The pure decision function `shouldCloseIssue` is the only logic here —
+ * it is unit-tested and shared with the command routine's equivalent
+ * shell check.  The rest (Linear GraphQL, gh invocations) lives in the
+ * routine YAML's `command:` shell script so the routine stays self-contained
+ * and independent of the CLI build.
+ *
+ * @see apps/cli/routines/linear-autoclose.yml
+ */
+/**
+ * Subset of `gh pr view --json state,mergedAt` output that drives the
+ * close decision.  State is one of: OPEN | CLOSED | MERGED (gh GraphQL).
+ */
+export interface PrInfo {
+    /** gh GraphQL PR state: 'OPEN' | 'CLOSED' | 'MERGED' */
+    state: string;
+    /** ISO-8601 merge timestamp, or null when the PR was not merged. */
+    mergedAt: string | null;
+}
+/**
+ * Pure decision: returns true when the PR has been merged and its linked
+ * Linear issue should therefore be closed.
+ *
+ * A PR is considered merged only when both conditions hold:
+ *   1. `state === 'MERGED'`  — gh marks CLOSED (rejected) separately from MERGED
+ *   2. `mergedAt !== null`   — defensive guard; a merged PR always carries a timestamp
+ */
+export declare function shouldCloseIssue(pr: PrInfo): boolean;

package/dist/lib/linear-autoclose.js

@@ -0,0 +1,22 @@
+/**
+ * Linear auto-close: close Linear issues whose linked GitHub PRs have merged.
+ *
+ * The pure decision function `shouldCloseIssue` is the only logic here —
+ * it is unit-tested and shared with the command routine's equivalent
+ * shell check.  The rest (Linear GraphQL, gh invocations) lives in the
+ * routine YAML's `command:` shell script so the routine stays self-contained
+ * and independent of the CLI build.
+ *
+ * @see apps/cli/routines/linear-autoclose.yml
+ */
+/**
+ * Pure decision: returns true when the PR has been merged and its linked
+ * Linear issue should therefore be closed.
+ *
+ * A PR is considered merged only when both conditions hold:
+ *   1. `state === 'MERGED'`  — gh marks CLOSED (rejected) separately from MERGED
+ *   2. `mergedAt !== null`   — defensive guard; a merged PR always carries a timestamp
+ */
+export function shouldCloseIssue(pr) {
+    return pr.state === 'MERGED' && pr.mergedAt !== null;
+}

package/dist/lib/mcp.d.ts

@@ -44,10 +44,35 @@ export declare function parseMcpServerConfig(filePath: string): McpYamlConfig |
  * command-line options or that contain characters unsafe for argv/identifier use.
  */
 export declare function validateMcpServerName(name: string): void;
+/** Path to the user-owned project-trust store (never inside a repo). */
+export declare function getMcpTrustStorePath(): string;
+/**
+ * Whether the project that owns `projectAgentsDir` has been explicitly trusted
+ * for MCP auto-apply. Untrusted by default (fail closed).
+ */
+export declare function isProjectMcpTrusted(projectAgentsDir: string): boolean;
+/**
+ * Record explicit trust for the project containing `cwd` so its project-scoped
+ * MCP servers may be registered/spawned. Returns the trusted project root, or
+ * null when `cwd` is not inside a project (no `.agents/` to trust).
+ */
+export declare function trustProjectMcp(cwd?: string): string | null;
+/** Revoke MCP trust for the project containing `cwd`. Returns true if it was trusted. */
+export declare function untrustProjectMcp(cwd?: string): boolean;
 /**
  * List all MCP server configs from ~/.agents/mcp/.
+ *
+ * When `enforceProjectTrust` is set, project-scoped configs are included only
+ * for a project the user has explicitly trusted (see `isProjectMcpTrusted`) —
+ * this is the choke point that keeps an untrusted cloned repo's MCP servers out
+ * of the register/spawn path. It ALSO fixes name-collision shadowing: an
+ * untrusted project entry is dropped before dedup, so it can never mask a
+ * same-named user entry. Display callers omit the flag to surface project
+ * entries (command+args and all) regardless of trust.
  */
-export declare function listMcpServerConfigs(cwd?: string): InstalledMcpServer[];
+export declare function listMcpServerConfigs(cwd?: string, options?: {
+    enforceProjectTrust?: boolean;
+}): InstalledMcpServer[];
 /**
  * Scan a repository for MCP server YAML configs.
  * Looks under <repoPath>/mcp/*.yaml — same on-disk layout as ~/.agents/mcp/.
@@ -70,6 +95,7 @@ export declare function installMcpConfigCentrally(sourcePath: string): {
  */
 export declare function getMcpServersByName(names?: string[], options?: {
     cwd?: string;
+    enforceProjectTrust?: boolean;
 }): InstalledMcpServer[];
 /**
  * Assemble the JSON payload Claude's `--mcp-config` flag expects from a set of

package/dist/lib/mcp.js

@@ -12,9 +12,9 @@ import * as path from 'path';
 import * as yaml from 'yaml';
 import { execFileSync } from 'child_process';
 import * as os from 'os';
-import { getMcpDir, getUserMcpDir, getProjectAgentsDir, getVersionsDir } from './state.js';
+import { getMcpDir, getUserMcpDir, getProjectAgentsDir, getVersionsDir, getUserAgentsDir } from './state.js';
 import { getBinaryPath, getVersionHomePath } from './versions.js';
-import { IS_WINDOWS, needsWindowsShell } from './platform/index.js';
+import { IS_WINDOWS, execFileShellSpec } from './platform/index.js';
 import { AGENTS } from './agents.js';
 import { isCapable } from './capabilities.js';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
@@ -93,13 +93,116 @@ function isStringRecord(value) {
         return false;
     return Object.values(value).every((item) => typeof item === 'string');
 }
+// ─── Project MCP trust (RUSH-1776) ───────────────────────────────────────────
+// Project-scoped MCP configs (<repo>/.agents/mcp/*.yaml) are UNTRUSTED by
+// default. An MCP server is an arbitrary command spawned under the agent's
+// authority, so merely cloning a hostile repo must never auto-register or run
+// it. A project's MCP servers enter the register/spawn path only after the user
+// explicitly trusts that project (`agents mcp trust`), recorded in a user-owned
+// store OUTSIDE any repo so a cloned repo can't grant itself trust. User- and
+// system-scoped MCPs (~/.agents/mcp/*) are always trusted.
+/** Path to the user-owned project-trust store (never inside a repo). */
+export function getMcpTrustStorePath() {
+    return path.join(getUserAgentsDir(), 'mcp-trust.yaml');
+}
+/**
+ * Key a project by its ROOT (parent of `.agents/`), resolved through symlinks
+ * so the key is stable no matter how the cwd was spelled.
+ */
+function normalizeProjectKey(projectAgentsDir) {
+    const root = path.dirname(projectAgentsDir);
+    try {
+        return fs.realpathSync(root);
+    }
+    catch {
+        return path.resolve(root);
+    }
+}
+function readTrustedProjects() {
+    const storePath = getMcpTrustStorePath();
+    if (!fs.existsSync(storePath))
+        return new Set();
+    let parsed;
+    try {
+        parsed = yaml.parse(fs.readFileSync(storePath, 'utf-8'));
+    }
+    catch {
+        return new Set();
+    }
+    const list = parsed && typeof parsed === 'object' && Array.isArray(parsed.trustedProjects)
+        ? parsed.trustedProjects
+        : [];
+    const out = new Set();
+    for (const entry of list) {
+        if (typeof entry !== 'string' || entry.length === 0)
+            continue;
+        try {
+            out.add(fs.realpathSync(entry));
+        }
+        catch {
+            out.add(path.resolve(entry));
+        }
+    }
+    return out;
+}
+function writeTrustedProjects(trusted) {
+    const storePath = getMcpTrustStorePath();
+    fs.mkdirSync(path.dirname(storePath), { recursive: true });
+    fs.writeFileSync(storePath, yaml.stringify({ trustedProjects: Array.from(trusted).sort() }), 'utf-8');
+}
+/**
+ * Whether the project that owns `projectAgentsDir` has been explicitly trusted
+ * for MCP auto-apply. Untrusted by default (fail closed).
+ */
+export function isProjectMcpTrusted(projectAgentsDir) {
+    return readTrustedProjects().has(normalizeProjectKey(projectAgentsDir));
+}
+/**
+ * Record explicit trust for the project containing `cwd` so its project-scoped
+ * MCP servers may be registered/spawned. Returns the trusted project root, or
+ * null when `cwd` is not inside a project (no `.agents/` to trust).
+ */
+export function trustProjectMcp(cwd = process.cwd()) {
+    const projectAgentsDir = getProjectAgentsDir(cwd);
+    if (!projectAgentsDir)
+        return null;
+    const key = normalizeProjectKey(projectAgentsDir);
+    const trusted = readTrustedProjects();
+    if (!trusted.has(key)) {
+        trusted.add(key);
+        writeTrustedProjects(trusted);
+    }
+    return key;
+}
+/** Revoke MCP trust for the project containing `cwd`. Returns true if it was trusted. */
+export function untrustProjectMcp(cwd = process.cwd()) {
+    const projectAgentsDir = getProjectAgentsDir(cwd);
+    if (!projectAgentsDir)
+        return false;
+    const key = normalizeProjectKey(projectAgentsDir);
+    const trusted = readTrustedProjects();
+    if (!trusted.delete(key))
+        return false;
+    writeTrustedProjects(trusted);
+    return true;
+}
 /**
  * List all MCP server configs from ~/.agents/mcp/.
+ *
+ * When `enforceProjectTrust` is set, project-scoped configs are included only
+ * for a project the user has explicitly trusted (see `isProjectMcpTrusted`) —
+ * this is the choke point that keeps an untrusted cloned repo's MCP servers out
+ * of the register/spawn path. It ALSO fixes name-collision shadowing: an
+ * untrusted project entry is dropped before dedup, so it can never mask a
+ * same-named user entry. Display callers omit the flag to surface project
+ * entries (command+args and all) regardless of trust.
  */
-export function listMcpServerConfigs(cwd = process.cwd()) {
+export function listMcpServerConfigs(cwd = process.cwd(), options = {}) {
     const dirs = [];
     const projectAgentsDir = getProjectAgentsDir(cwd);
-    if (projectAgentsDir) {
+    const includeProject = projectAgentsDir !== null
+        && (!options.enforceProjectTrust || isProjectMcpTrusted(projectAgentsDir));
+    if (projectAgentsDir && includeProject) {
         dirs.push({ scope: 'project', dir: path.join(projectAgentsDir, 'mcp') });
     }
     // User dir first (wins on name collision), then system
@@ -175,7 +278,10 @@ export function installMcpConfigCentrally(sourcePath) {
  * Otherwise returns all servers.
  */
 export function getMcpServersByName(names, options = {}) {
-    const allServers = listMcpServerConfigs(options.cwd);
+    // This feeds the register/spawn path (installMcpServers, workflow assembly),
+    // so untrusted project-scoped servers are excluded by default (fail closed).
+    const enforceProjectTrust = options.enforceProjectTrust ?? true;
+    const allServers = listMcpServerConfigs(options.cwd, { enforceProjectTrust });
     if (!names || names.length === 0) {
         return allServers;
     }
@@ -228,20 +334,24 @@ function installMcpViaClaude(binaryPath, server, versionHome) {
             server.config.command,
             ...(server.config.args || [])
         ];
-        execFileSync(binaryPath, args, {
+        // RUSH-1752: user-controlled MCP command/args must not reach cmd.exe unquoted.
+        const spec = execFileShellSpec(binaryPath, args);
+        execFileSync(spec.command, spec.args, {
             stdio: 'pipe',
             timeout: 30000,
             env: execEnv,
-            shell: needsWindowsShell(binaryPath),
+            shell: spec.shell,
         });
     }
     else {
         // claude mcp add --scope user --transport http -- <name> <url>
-        execFileSync(binaryPath, ['mcp', 'add', '--scope', 'user', '--transport', 'http', '--', server.name, server.config.url], {
+        const httpArgs = ['mcp', 'add', '--scope', 'user', '--transport', 'http', '--', server.name, server.config.url];
+        const spec = execFileShellSpec(binaryPath, httpArgs);
+        execFileSync(spec.command, spec.args, {
             stdio: 'pipe',
             timeout: 30000,
             env: execEnv,
-            shell: needsWindowsShell(binaryPath),
+            shell: spec.shell,
         });
     }
 }
@@ -259,11 +369,13 @@ function installMcpViaCodex(binaryPath, server, versionHome) {
             server.config.command,
             ...(server.config.args || [])
         ];
-        execFileSync(binaryPath, args, {
+        // RUSH-1752: user-controlled MCP command/args must not reach cmd.exe unquoted.
+        const spec = execFileShellSpec(binaryPath, args);
+        execFileSync(spec.command, spec.args, {
             stdio: 'pipe',
             timeout: 30000,
             env: { ...process.env, HOME: versionHome },
-            shell: needsWindowsShell(binaryPath),
+            shell: spec.shell,
         });
     }
     // Note: Codex may not support HTTP MCPs
@@ -314,7 +426,9 @@ function registerMcpCommand(agentId, name, commandSpec, scope, transport, option
             ? ['mcp', 'add', '--transport', transport, '--scope', scope, '--', name, ...commandArgs]
             : ['mcp', 'add', '--', name, ...commandArgs];
         const env = options.home ? { ...process.env, HOME: options.home } : process.env;
-        execFileSync(bin, args, { stdio: 'pipe', timeout: 30000, env, shell: needsWindowsShell(bin) });
+        // RUSH-1752: user-controlled MCP command/args must not reach cmd.exe unquoted.
+        const spec = execFileShellSpec(bin, args);
+        execFileSync(spec.command, spec.args, { stdio: 'pipe', timeout: 30000, env, shell: spec.shell });
         return { success: true };
     }
     catch (err) {

package/dist/lib/monitors/config.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Monitor (event-triggered watcher) configuration, validation, and CRUD.
+ *
+ * A monitor is a routine whose trigger is a *watched source* instead of a
+ * *clock*. It watches a SOURCE, detects a CONDITION change, and fires an ACTION —
+ * reusing the routines daemon, dispatch engine, device model, and notify path.
+ *
+ * Monitors are YAML files in ~/.agents/monitors/. This module owns the on-disk
+ * shape (mirroring lib/routines.ts read/write helpers), hand-rolled validation
+ * (mirroring validateJob — no zod), and the device-owner eligibility gate.
+ */
+import type { AgentId } from '../types.js';
+/** Source types a monitor can watch. */
+export type MonitorSourceType = 'command' | 'poll' | 'poll-http' | 'webhook' | 'ws' | 'file' | 'device';
+/** Webhook source filters — reuse the github/linear matcher shape from triggers/webhook.ts. */
+export interface MonitorWebhookSource {
+    source: 'github' | 'linear';
+    event: string;
+    repo?: string;
+    branch?: string;
+    action?: string;
+    teamKey?: string;
+    label?: string;
+}
+/**
+ * What a monitor watches. Exactly one source-payload field is populated, keyed by
+ * `type`: `command`/`interval` for command/poll, `url`/`interval` for poll-http,
+ * `wsUrl` for ws, `path` for file, `device` for device, `webhook` for webhook.
+ */
+export interface MonitorSource {
+    type: MonitorSourceType;
+    /** Shell command whose stdout is the observation (command, poll). */
+    command?: string;
+    /** Re-evaluation interval (poll, poll-http; optional for command/file/device). e.g. `30s`, `15m`, `8h`. */
+    interval?: string;
+    /** URL to GET (poll-http). */
+    url?: string;
+    /** WebSocket URL; each frame is an observation (ws). */
+    wsUrl?: string;
+    /** File or directory to watch (file). */
+    path?: string;
+    /** A registered fleet device whose health/reachability is the observation (device). */
+    device?: string;
+    /** Webhook trigger filters (webhook). */
+    webhook?: MonitorWebhookSource;
+}
+/** How an observation becomes a fire. */
+export type MonitorConditionMode = 'on-change' | 'match' | 'every';
+export interface MonitorCondition {
+    mode: MonitorConditionMode;
+    /** Regex (required for `match` mode) — fire when the observation matches. */
+    match?: string;
+    /**
+     * What counts as "the same event" for de-duplication. When set, the dedupe
+     * signature is the first regex match of this expression against the
+     * observation (so re-observing the same token is silent); when omitted, the
+     * full observation is the signature.
+     */
+    dedupeKey?: string;
+}
+/** Action types a monitor can fire. */
+export type MonitorActionType = 'run' | 'routine' | 'notify' | 'webhook-out';
+/**
+ * What a monitor does on a fire. Shares the run-shaped fields (agent, prompt,
+ * mode, effort, timeout) conceptually with JobConfig (lib/routines.ts) so
+ * dispatch reuses the routines path (executeJobDetached). The fired event is
+ * injected into the prompt as `{event}`.
+ */
+export interface ActionConfig {
+    type: MonitorActionType;
+    /** run: which agent to spawn. */
+    agent?: AgentId;
+    /** run: the prompt; `{event}` is replaced with the fired event summary. */
+    prompt?: string;
+    /** run: execution mode (shared with routines). */
+    mode?: 'plan' | 'edit' | 'auto' | 'skip' | 'full';
+    /** run: reasoning effort (shared with routines). */
+    effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';
+    /** run: kill the action if it runs longer than this (e.g. `10m`). */
+    timeout?: string;
+    /** routine: name of an existing routine to fire. */
+    routine?: string;
+    /** notify: channel for the notification (default `telegram`). */
+    notifyChannel?: string;
+    /** webhook-out: URL to POST the event to. */
+    url?: string;
+}
+/** Full monitor configuration (persisted as YAML in ~/.agents/monitors/). */
+export interface MonitorConfig {
+    name: string;
+    enabled: boolean;
+    source: MonitorSource;
+    condition: MonitorCondition;
+    action: ActionConfig;
+    /**
+     * Pin-to-one OWNER device — the single machine whose daemon evaluates the
+     * source and fires. Exactly-once for v1 (no distributed lock). When set, only
+     * that machine is eligible; everywhere else the monitor is inert.
+     */
+    device?: string;
+    /**
+     * Fleet allowlist (advanced) — each listed device evaluates and fires
+     * independently, like routines' `devices`. Mutually exclusive with `device`.
+     */
+    devices?: string[];
+    /** Execute the ACTION on this machine over SSH (placement), distinct from the owner that fires it. */
+    runOn?: string;
+    /** Firehose guard: auto-pause the monitor if it fires more than `max` times per `per`. */
+    rateLimit?: {
+        max: number;
+        per: string;
+    };
+    /** User-defined prompt variables (expanded like routines' variables). */
+    variables?: Record<string, string>;
+    /** Pin the agent version for `run` actions (omit to use the run strategy). */
+    version?: string;
+}
+/**
+ * A fired event. `summary` is injected into the action prompt as `{event}`;
+ * `payload` carries the structured observation for `webhook-out` and inspection.
+ */
+export interface MonitorEvent {
+    monitorName: string;
+    firedAt: string;
+    summary: string;
+    payload: Record<string, unknown>;
+}
+/**
+ * Parse a human interval string (e.g. `30s`, `15m`, `8h`, `1d`, `1h30m`) into
+ * milliseconds. Unlike routines' parseTimeout, seconds are supported (polls tick
+ * in seconds). Returns null on empty/unparseable/zero input.
+ */
+export declare function parseInterval(interval: string): number | null;
+/**
+ * True when the monitor may evaluate + fire on this machine. Owner semantics:
+ * `device` (single owner, exactly-once) → only that machine; else `devices`
+ * (allowlist) → any listed machine; else unrestricted. Both sides normalize so
+ * `Yosemite-S0` and `yosemite-s0.tailnet.ts.net` agree with `yosemite-s0`.
+ */
+export declare function monitorRunsOnThisDevice(config: Pick<MonitorConfig, 'device' | 'devices'>): boolean;
+/**
+ * Validate a partial monitor config, returning a list of human-readable errors.
+ * Hand-rolled like validateJob (lib/routines.ts) — no zod. Rejects: no source,
+ * two sources, no action, two actions, match-mode without `match`, plus the
+ * per-type field/shape checks.
+ */
+export declare function validateMonitor(config: Partial<MonitorConfig>): string[];
+/** List all monitor configs in ~/.agents/monitors/. */
+export declare function listMonitors(): MonitorConfig[];
+/** Read a single monitor config by name. Returns null if not found or corrupt. */
+export declare function readMonitor(name: string): MonitorConfig | null;
+/** Get the filesystem path of a monitor's YAML config, or null if not found. */
+export declare function getMonitorPath(name: string): string | null;
+/** Write a monitor config to disk atomically, omitting fields that match defaults. */
+export declare function writeMonitor(config: MonitorConfig): void;
+/** Delete a monitor config file by name. Returns true if the file existed. */
+export declare function deleteMonitor(name: string): boolean;
+/** Enable or disable a monitor by name. */
+export declare function setMonitorEnabled(name: string, enabled: boolean): void;
+/** Check whether a monitor with the given name exists on disk. */
+export declare function monitorExists(name: string): boolean;