@phnx-labs/agents-cli 1.20.87 → 1.20.89

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/staleness/detectors/commands.js

@@ -1,13 +1,14 @@
 /**
- * Commands detector — mirrors versions.ts:343-357. Inspects the version home,
+ * Commands detector — mirrors the command dispatch in versions.ts. Inspects the version home,
  * returns command names. Honors the commands-as-skills marker for skills-only
- * agents (kimi, Codex >= 0.117.0, …); falls back to scanning
- * `{agentDir}/<commandsSubdir>/` for the native path.
+ * agents (Kimi, Codex >= 0.117.0, …), treats the native file as authoritative
+ * for dual-write targets (the skill copy is deliberately absent on a name
+ * collision), and scans `{agentDir}/<commandsSubdir>/` for native-only targets.
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import { AGENTS, MANAGED_AGENT_IDS, agentConfigDirName } from '../../agents.js';
-import { shouldInstallCommandAsSkill, listCommandSkillsInVersion } from '../../command-skills.js';
+import { listCommandSkillsInVersion, shouldInstallCommandAsSkill, } from '../../command-skills.js';
 import { lazyAgentMap } from '../writers/lazy-map.js';
 function buildCommandsDetector(agent) {
     return {
@@ -23,9 +24,17 @@ function buildCommandsDetector(agent) {
             if (!fs.existsSync(commandsDir))
                 return [];
             const ext = agentConfig.format === 'toml' ? '.toml' : '.md';
-            return fs.readdirSync(commandsDir)
+            const nativeCommands = fs.readdirSync(commandsDir)
                 .filter(f => f.endsWith(ext))
                 .map(f => f.replace(new RegExp(`\\${ext}$`), ''));
+            // For a dual-write target the native file is the authoritative record that
+            // the command synced. The skill copy is derived, and
+            // installCommandSkillToVersion deliberately writes none when a real skill
+            // source already owns the name -- requiring both copies reported those
+            // commands missing forever and drove an `agents refresh` loop no sync could
+            // clear. This also matches `agents doctor`/`prune`, which read the
+            // unfiltered listCommandsInVersionHome.
+            return nativeCommands;
         },
     };
 }

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

@@ -44,6 +44,8 @@ export interface SyncManifest {
     v: typeof MANIFEST_VERSION;
     syncedAt: string;
     commands: Record<string, FileEntry>;
+    /** Command names the version writer emitted during the preceding full sync. */
+    writtenCommands?: string[];
     skills: Record<string, DirEntry>;
     hooks: Record<string, FileEntry>;
     rules: RulesEntry;

package/dist/lib/staleness/writers/commands.js

@@ -1,12 +1,14 @@
 /**
  * Commands writer.
  *
- * Two physical formats, picked per-(agent, version) at write time:
+ * Two physical formats, selected per-(agent, version) at write time. Most
+ * agents receive one format; dual-write registry targets receive both:
  *
  *  - command-as-skill — fires when `shouldInstallCommandAsSkill(agent, version)`
  *    is true. Used for Codex >= 0.117.0 (commands capability ends, skills
  *    capability remains) and agents with skills but no native command-file dir
- *    such as kimi. Writes `{agentDir}/skills/<name>/SKILL.md` with the
+ *    such as Kimi. Cursor also receives this format in addition to its IDE
+ *    command file. Writes `{agentDir}/skills/<name>/SKILL.md` with the
  *    `agents_command` marker; the agent picks it up as a slash-command equivalent.
  *
  *  - native command file — `{agentDir}/<commandsSubdir>/<name>.md` (or .toml
@@ -23,7 +25,7 @@ import { supports } from '../../capabilities.js';
 import { safeJoin } from '../../paths.js';
 import { markdownToToml } from '../../convert.js';
 import { commandAppliesTo, parseCommandMetadata } from '../../commands.js';
-import { installCommandSkillToVersion, shouldInstallCommandAsSkill } from '../../command-skills.js';
+import { installCommandSkillToVersion, shouldAlsoInstallCommandAsSkill, shouldInstallCommandAsSkill, } from '../../command-skills.js';
 import { installGooseCommandToVersion } from '../../goose-commands.js';
 import { resolveCommandSource, trustedSkillRoots } from './sources.js';
 import { lazyAgentMap } from './lazy-map.js';
@@ -35,6 +37,7 @@ function buildCommandsWriter(agent) {
             const agentConfig = AGENTS[agent];
             const agentDir = path.join(versionHome, agentConfigDirName(agent));
             const commandsAsSkills = shouldInstallCommandAsSkill(agent, version);
+            const commandsAlsoAsSkills = shouldAlsoInstallCommandAsSkill(agent, version);
             const supportsCommands = supports(agent, 'commands', version).ok;
             // Version-gated agents (e.g. goose skills >= 1.25.0) are registered but
             // may be called at a version too old for both paths — skip gracefully.
@@ -54,23 +57,25 @@ function buildCommandsWriter(agent) {
                 const metadata = parseCommandMetadata(srcFile);
                 if (!commandAppliesTo(agent, version, metadata).ok)
                     continue;
-                if (commandsAsSkills) {
+                if (commandsAsSkills || commandsAlsoAsSkills) {
                     const installed = installCommandSkillToVersion(agentDir, cmd, srcFile, skillRoots);
+                    // installed.skipped means a real skill source already owns this name,
+                    // which is a deliberate no-op, not a failure — the native file is still written.
                     if (!installed.success)
                         continue;
                 }
-                else if (agent === 'goose') {
+                if (supportsCommands && agent === 'goose') {
                     // Goose: recipe YAML + config.yaml slash_commands entry, not a file copy.
                     const installed = installGooseCommandToVersion(versionHome, cmd, srcFile);
                     if (!installed.success)
                         continue;
                 }
-                else if (agentConfig.format === 'toml') {
+                else if (supportsCommands && agentConfig.format === 'toml') {
                     const content = fs.readFileSync(srcFile, 'utf-8');
                     const tomlContent = markdownToToml(cmd, content);
                     fs.writeFileSync(safeJoin(commandsTarget, `${cmd}.toml`), tomlContent);
                 }
-                else {
+                else if (supportsCommands) {
                     fs.copyFileSync(srcFile, safeJoin(commandsTarget, `${cmd}.md`));
                 }
                 synced.push(cmd);
@@ -84,6 +89,7 @@ function buildCommandsWriter(agent) {
 // Registration covers two cases:
 //   - native commands (claude, codex < 0.117.0, grok, etc.) — `commands` cap
 //   - commands-as-skills (kimi, codex >= 0.117.0)
+//   - dual-write commands plus command-skills (cursor)
 //
 // Agents that have skills but use a NATIVE non-file slash-command system
 // (openclaw → Gateway-based commands) are NOT registered. They declare

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>;