@phnx-labs/agents-cli 1.20.88 → 1.20.89

package/dist/lib/session/remote-active.d.ts

@@ -9,7 +9,10 @@ export declare const NO_FANOUT_ENV = "AGENTS_SESSIONS_LOCAL";
  * Parse a peer's `--active --json` stdout into active sessions, tagging each
  * with `machine`. Defensive against version skew / partial output: non-JSON or
  * a non-array yields `[]`, and non-object entries are dropped rather than
- * throwing. Exported for unit testing without a live tailnet.
+ * throwing. `viewingIn` arrives as a display string from a current peer and as
+ * an `{app, tab}` object from one that predates the flattening, so it is
+ * normalized here — the single boundary where a foreign row becomes internal.
+ * Exported for unit testing without a live tailnet.
  */
 export declare function parseRemoteActive(stdout: string, machine: string): ActiveSession[];
 export interface RemoteActiveResult {

package/dist/lib/session/remote-active.js

@@ -15,6 +15,7 @@
  * `spawn`, not the sync `sshExec`) so N peers cost one round-trip, not N.
  */
 import { gatherRemoteAgentsJson } from '../remote-agents-json.js';
+import { parseViewingIn } from './viewing-in.js';
 /**
  * Recursion guard, passed as an env var (not a CLI flag) so an OLDER remote
  * `agents` that predates this feature ignores it harmlessly instead of erroring
@@ -25,7 +26,10 @@ export const NO_FANOUT_ENV = 'AGENTS_SESSIONS_LOCAL';
  * Parse a peer's `--active --json` stdout into active sessions, tagging each
  * with `machine`. Defensive against version skew / partial output: non-JSON or
  * a non-array yields `[]`, and non-object entries are dropped rather than
- * throwing. Exported for unit testing without a live tailnet.
+ * throwing. `viewingIn` arrives as a display string from a current peer and as
+ * an `{app, tab}` object from one that predates the flattening, so it is
+ * normalized here — the single boundary where a foreign row becomes internal.
+ * Exported for unit testing without a live tailnet.
  */
 export function parseRemoteActive(stdout, machine) {
     let parsed;
@@ -40,7 +44,9 @@ export function parseRemoteActive(stdout, machine) {
     const out = [];
     for (const x of parsed) {
         if (x && typeof x === 'object' && !Array.isArray(x)) {
-            out.push({ ...x, machine });
+            const row = { ...x, machine };
+            row.viewingIn = parseViewingIn(x.viewingIn);
+            out.push(row);
         }
     }
     return out;

package/dist/lib/session/viewing-in.d.ts

@@ -27,6 +27,37 @@ export interface ViewingIn {
     /** 1-based tab number within that app, when it can be resolved. */
     tab?: number;
 }
+/**
+ * The one display form of "where is this session being watched" — `'codium tab 3'`
+ * when a client is attached, the bare app name when the tab can't be resolved, and
+ * `'detached'` when the pane is live but nobody is looking at it (the terminal that
+ * displayed it was closed or crashed).
+ *
+ * `undefined` means **we do not know**, and it covers two different situations that
+ * must not be confused with `'detached'`: a session that isn't tmux-hosted (no pane
+ * to attach to, so it isn't on this axis at all), and a tmux session whose pane the
+ * locator could not resolve (`mapPanesToTargets` returned nothing for this socket,
+ * or the row was never enriched). {@link resolveViewingIn} answers `undefined` for
+ * BOTH "no client attached" and "could not locate the pane", so the pane's resolved
+ * `tmuxTarget` is what separates them: without it there is no evidence of absence,
+ * only absence of evidence. Claiming `'detached'` there would invent an orphaned
+ * session — and a consumer acts on that claim (Factory's picker pre-ticks every
+ * detached row for rescue), so the wrong answer resumes a session nobody asked for.
+ *
+ * Shared by the `--active` row renderer and the `--json` serializer so a machine
+ * consumer reads exactly the string a human sees, instead of re-deriving "detached"
+ * from an absent field.
+ */
+export declare function viewingInLabel(s: Pick<ActiveSession, 'provenance' | 'viewingIn' | 'tmuxTarget'>): string | undefined;
+/**
+ * Wire form -> internal form for a row arriving from another machine's
+ * `--active --json`. The fan-out reaches peers whose CLI may predate
+ * {@link viewingInLabel} and still emit the `{app, tab}` object, so this boundary
+ * normalizes both shapes into one — the ONLY place either shape is accepted.
+ * `'detached'` maps to undefined, which is what "no attached client" means
+ * internally; {@link viewingInLabel} regenerates the word from the pane.
+ */
+export declare function parseViewingIn(raw: unknown): ViewingIn | undefined;
 /** Injection seams so `resolveViewingIn` is unit-testable without a live tmux/ps/osascript. */
 export interface ViewingInDeps {
     /** Ghostty surfaces (window/tab/cwd/title). Enumerated once by the caller and shared. */

package/dist/lib/session/viewing-in.js

@@ -26,6 +26,53 @@ import { hostFromPid } from './active.js';
 import { enumerateGhosttyTabs, assignGhosttyTabs } from './ghostty-tabs.js';
 import { getTerminalsDir } from '../state.js';
 const execFileAsync = promisify(execFile);
+/**
+ * The one display form of "where is this session being watched" — `'codium tab 3'`
+ * when a client is attached, the bare app name when the tab can't be resolved, and
+ * `'detached'` when the pane is live but nobody is looking at it (the terminal that
+ * displayed it was closed or crashed).
+ *
+ * `undefined` means **we do not know**, and it covers two different situations that
+ * must not be confused with `'detached'`: a session that isn't tmux-hosted (no pane
+ * to attach to, so it isn't on this axis at all), and a tmux session whose pane the
+ * locator could not resolve (`mapPanesToTargets` returned nothing for this socket,
+ * or the row was never enriched). {@link resolveViewingIn} answers `undefined` for
+ * BOTH "no client attached" and "could not locate the pane", so the pane's resolved
+ * `tmuxTarget` is what separates them: without it there is no evidence of absence,
+ * only absence of evidence. Claiming `'detached'` there would invent an orphaned
+ * session — and a consumer acts on that claim (Factory's picker pre-ticks every
+ * detached row for rescue), so the wrong answer resumes a session nobody asked for.
+ *
+ * Shared by the `--active` row renderer and the `--json` serializer so a machine
+ * consumer reads exactly the string a human sees, instead of re-deriving "detached"
+ * from an absent field.
+ */
+export function viewingInLabel(s) {
+    if (s.provenance?.mux?.kind !== 'tmux' || !s.provenance.mux.pane)
+        return undefined;
+    if (!s.viewingIn)
+        return s.tmuxTarget ? 'detached' : undefined;
+    return s.viewingIn.tab != null ? `${s.viewingIn.app} tab ${s.viewingIn.tab}` : s.viewingIn.app;
+}
+/**
+ * Wire form -> internal form for a row arriving from another machine's
+ * `--active --json`. The fan-out reaches peers whose CLI may predate
+ * {@link viewingInLabel} and still emit the `{app, tab}` object, so this boundary
+ * normalizes both shapes into one — the ONLY place either shape is accepted.
+ * `'detached'` maps to undefined, which is what "no attached client" means
+ * internally; {@link viewingInLabel} regenerates the word from the pane.
+ */
+export function parseViewingIn(raw) {
+    if (raw && typeof raw === 'object') {
+        const app = raw.app;
+        const tab = raw.tab;
+        return typeof app === 'string' ? { app, tab: typeof tab === 'number' ? tab : undefined } : undefined;
+    }
+    if (typeof raw !== 'string' || !raw || raw === 'detached')
+        return undefined;
+    const m = raw.match(/^(.+?) tab (\d+)$/);
+    return m ? { app: m[1], tab: parseInt(m[2], 10) } : { app: raw };
+}
 /** Apps whose tab index is published by the extension via live-terminals.json. */
 const EDITOR_APPS = new Set(['code', 'cursor', 'codium', 'windsurf']);
 /** The tmux session name a session's pane belongs to, from `session:window.pane`. */

package/dist/lib/state.d.ts

@@ -109,6 +109,12 @@ export declare function getCacheDir(): string;
 export declare function getPackagesDir(): string;
 /** Path to routine YAML definitions (~/.agents/routines/). */
 export declare function getRoutinesDir(): string;
+/**
+ * Path to webhook handler YAML definitions (~/.agents/webhooks/). Handlers are
+ * one-off triggers for agents/workflows/commands/routines, layered the same way
+ * as routines (project > user > system).
+ */
+export declare function getWebhooksDir(): string;
 /**
  * Path to built-in routine definitions shipped in the system repo
  * (`~/.agents/.system/routines/`). Unioned under the user routines dir by
@@ -117,6 +123,11 @@ export declare function getRoutinesDir(): string;
  * disables the built-in). The daemon fires these; the directory need not exist.
  */
 export declare function getSystemRoutinesDir(): string;
+/**
+ * Path to built-in webhook handler definitions shipped in the system repo
+ * (`~/.agents/.system/webhooks/`). Layered under user handlers by `listHandlers()`.
+ */
+export declare function getSystemWebhooksDir(): string;
 /**
  * Path to a project-scoped routines directory (`<project>/.agents/routines/`),
  * or null when no project `.agents/` is found by walking up from cwd.
@@ -130,6 +141,12 @@ export declare function getSystemRoutinesDir(): string;
  * it does not auto-enable firing. See `lib/routines-project.ts`.
  */
 export declare function getProjectRoutinesDir(cwd?: string): string | null;
+/**
+ * Path to a project-scoped webhook handlers directory
+ * (`<project>/.agents/webhooks/`), or null when no project `.agents/` is found
+ * by walking up from cwd.
+ */
+export declare function getProjectWebhooksDir(cwd?: string): string | null;
 /** Path to routine execution logs (~/.agents/.history/runs/). */
 export declare function getRunsDir(): string;
 /** Path to monitor YAML definitions (~/.agents/monitors/). */

package/dist/lib/state.js

@@ -72,6 +72,7 @@ const SYSTEM_PLUGINS_DIR = path.join(SYSTEM_AGENTS_DIR, 'plugins');
 // Unioned under user routines by listJobs()/readJob() so a routine shipped here
 // fires for every install, while a user routine of the same name overrides it.
 const SYSTEM_ROUTINES_DIR = path.join(SYSTEM_AGENTS_DIR, 'routines');
+const SYSTEM_WEBHOOKS_DIR = path.join(SYSTEM_AGENTS_DIR, 'webhooks');
 const SYSTEM_PROMPTCUTS_FILE = path.join(SYSTEM_AGENTS_DIR, 'hooks', 'promptcuts.yaml');
 const SYSTEM_MCP_CONFIG_FILE = path.join(SYSTEM_AGENTS_DIR, 'mcp.json');
 const SYSTEM_INSTRUCTIONS_FILE = path.join(SYSTEM_AGENTS_DIR, 'instructions.md');
@@ -82,6 +83,7 @@ const HISTORY_DIR = path.join(USER_AGENTS_DIR, '.history');
 const CACHE_DIR = path.join(USER_AGENTS_DIR, '.cache');
 // Top-level user dirs (config/definitions only — runtime moves into .history/.cache).
 const ROUTINES_DIR = path.join(USER_AGENTS_DIR, 'routines');
+const WEBHOOKS_DIR = path.join(USER_AGENTS_DIR, 'webhooks');
 // Monitor definitions (event-triggered watchers). Sibling of ROUTINES_DIR: a
 // monitor is a routine whose trigger is a watched source instead of a clock.
 const MONITORS_DIR = path.join(USER_AGENTS_DIR, 'monitors');
@@ -306,7 +308,13 @@ export function getCacheDir() { return CACHE_DIR; }
 /** Path to cloned packages (~/.agents/.cache/packages/). */
 export function getPackagesDir() { return PACKAGES_DIR; }
 /** Path to routine YAML definitions (~/.agents/routines/). */
-export function getRoutinesDir() { return ROUTINES_DIR; }
+export function getRoutinesDir() { return process.env.AGENTS_ROUTINES_DIR ?? ROUTINES_DIR; }
+/**
+ * Path to webhook handler YAML definitions (~/.agents/webhooks/). Handlers are
+ * one-off triggers for agents/workflows/commands/routines, layered the same way
+ * as routines (project > user > system).
+ */
+export function getWebhooksDir() { return process.env.AGENTS_WEBHOOKS_DIR ?? WEBHOOKS_DIR; }
 /**
  * Path to built-in routine definitions shipped in the system repo
  * (`~/.agents/.system/routines/`). Unioned under the user routines dir by
@@ -314,7 +322,12 @@ export function getRoutinesDir() { return ROUTINES_DIR; }
  * user routine of the same name overrides it (a user copy with `enabled: false`
  * disables the built-in). The daemon fires these; the directory need not exist.
  */
-export function getSystemRoutinesDir() { return SYSTEM_ROUTINES_DIR; }
+export function getSystemRoutinesDir() { return process.env.AGENTS_SYSTEM_ROUTINES_DIR ?? SYSTEM_ROUTINES_DIR; }
+/**
+ * Path to built-in webhook handler definitions shipped in the system repo
+ * (`~/.agents/.system/webhooks/`). Layered under user handlers by `listHandlers()`.
+ */
+export function getSystemWebhooksDir() { return process.env.AGENTS_SYSTEM_WEBHOOKS_DIR ?? SYSTEM_WEBHOOKS_DIR; }
 /**
  * Path to a project-scoped routines directory (`<project>/.agents/routines/`),
  * or null when no project `.agents/` is found by walking up from cwd.
@@ -333,6 +346,17 @@ export function getProjectRoutinesDir(cwd = process.cwd()) {
         return null;
     return path.join(projectAgentsDir, 'routines');
 }
+/**
+ * Path to a project-scoped webhook handlers directory
+ * (`<project>/.agents/webhooks/`), or null when no project `.agents/` is found
+ * by walking up from cwd.
+ */
+export function getProjectWebhooksDir(cwd = process.cwd()) {
+    const projectAgentsDir = getProjectAgentsDir(cwd);
+    if (!projectAgentsDir)
+        return null;
+    return path.join(projectAgentsDir, 'webhooks');
+}
 /** Path to routine execution logs (~/.agents/.history/runs/). */
 export function getRunsDir() { return RUNS_DIR; }
 /** Path to monitor YAML definitions (~/.agents/monitors/). */
@@ -506,6 +530,8 @@ export function ensureAgentsDir() {
         fs.mkdirSync(PACKAGES_DIR, opts);
     if (!fs.existsSync(ROUTINES_DIR))
         fs.mkdirSync(ROUTINES_DIR, opts);
+    if (!fs.existsSync(WEBHOOKS_DIR))
+        fs.mkdirSync(WEBHOOKS_DIR, opts);
     if (!fs.existsSync(RUNS_DIR))
         fs.mkdirSync(RUNS_DIR, opts);
     if (!fs.existsSync(VERSIONS_DIR))
@@ -524,6 +550,8 @@ export function ensureAgentsDir() {
         fs.mkdirSync(SYSTEM_PERMISSIONS_DIR, opts);
     if (!fs.existsSync(SYSTEM_SUBAGENTS_DIR))
         fs.mkdirSync(SYSTEM_SUBAGENTS_DIR, opts);
+    if (!fs.existsSync(SYSTEM_WEBHOOKS_DIR))
+        fs.mkdirSync(SYSTEM_WEBHOOKS_DIR, opts);
     try {
         fs.chmodSync(SYSTEM_AGENTS_DIR, 0o700);
     }

package/dist/lib/triggers/handlers.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Webhook handler config layer.
+ *
+ * Handlers are one-off triggers stored in `~/.agents/webhooks/*.yml` (plus
+ * project/system layers). They complement routine triggers: a matching webhook
+ * can run an agent, workflow, shell command, or delegate to a routine.
+ */
+import type { JobConfig, RunMeta, WebhookContext } from '../routines.js';
+import type { AgentId } from '../types.js';
+import type { IncomingWebhook, WebhookSource } from './webhook.js';
+export interface WebhookHandler {
+    name: string;
+    enabled?: boolean;
+    devices?: string[];
+    source: WebhookSource;
+    event?: string;
+    action?: string;
+    stateTo?: string;
+    stateFrom?: string;
+    teamKey?: string;
+    label?: string;
+    repo?: string;
+    branch?: string;
+    /**
+     * Where to run the action. A device name (`yosemite-s0`) runs there over SSH;
+     * `fleet` picks any eligible online worker; `fleet/<platform>` (or
+     * `<platform>/fleet`, or a bare `linux`/`macos`/`windows`) restricts that pick
+     * to one platform. Omitted runs locally.
+     */
+    host?: string;
+    run?: {
+        agent?: AgentId;
+        workflow?: string;
+        command?: string;
+        prompt?: string;
+        /** Environment variables injected into the spawned process. */
+        env?: Record<string, string>;
+    };
+    routine?: string;
+}
+export interface FiredHandler {
+    handlerName: string;
+    runId?: string;
+    exitCode?: number;
+    output?: string;
+}
+export interface HandlerHostResolution {
+    /** Resolved execution host, or undefined to run locally. */
+    host?: string;
+    /** Strategy that should be set on the JobConfig. */
+    hostStrategy?: 'host' | 'fleet';
+}
+/**
+ * Resolve a handler `host` expression to a concrete host or local execution.
+ *
+ * - Specific device name (e.g. `yosemite-s0`) → run there over SSH, or locally
+ *   if it names this machine.
+ * - `fleet` → pick any online worker device.
+ * - `fleet/<platform>` or `<platform>/fleet` (e.g. `fleet/linux`, `linux/fleet`)
+ *   → pick any online worker on that platform. `linux` alone is accepted as a
+ *   shorthand for `fleet/linux`.
+ *
+ * Throws when a fleet expression matches no eligible device, rather than
+ * silently falling back to this machine — `fleet/linux` must never land on a
+ * macOS box.
+ */
+export declare function resolveHandlerHost(host: string | undefined): HandlerHostResolution;
+/**
+ * List all webhook handlers, scanning project > user > system webhook dirs.
+ * Higher layers shadow lower ones of the same name (first-seen wins).
+ */
+export declare function listHandlers(cwd?: string): WebhookHandler[];
+/** Pure matcher: does this handler match the incoming webhook? */
+export declare function handlerMatchesWebhook(handler: WebhookHandler, webhook: IncomingWebhook): boolean;
+/**
+ * Build the variable-substitution context for a webhook. Linear events expose
+ * `issue` and `updatedFrom`; GitHub events expose `repository`, `pull_request`,
+ * and `issue`.
+ */
+export declare function buildWebhookContext(webhook: IncomingWebhook): WebhookContext;
+export interface ExecuteHandlerOptions {
+    dispatchAgent?: (config: JobConfig) => Promise<RunMeta>;
+    dispatchWorkflow?: (config: JobConfig) => Promise<RunMeta>;
+    execCommand?: (command: string) => Promise<{
+        exitCode: number;
+        output: string;
+    }>;
+    dispatchRoutine?: (config: JobConfig) => Promise<RunMeta>;
+}
+/**
+ * Execute a handler's action. Runs the configured agent/workflow/command or
+ * delegates to a routine, substituting `{{...}}` placeholders from the webhook
+ * context.
+ */
+export declare function executeHandler(handler: WebhookHandler, webhook: IncomingWebhook, opts?: ExecuteHandlerOptions): Promise<FiredHandler>;