@phnx-labs/agents-cli 1.20.71 → 1.20.73

package/dist/commands/cloud.js

@@ -10,6 +10,7 @@ import { MissingTargetError, MAX_IMAGES_PER_DISPATCH } from '../lib/cloud/types.
 import { normalizeTriggerEvent, validateTrigger, writeJob, jobExists, GITHUB_TRIGGER_EVENTS } from '../lib/routines.js';
 import { machineId } from '../lib/machine-id.js';
 import { emit } from '../lib/events.js';
+import { shareRuntimeEnv } from '../lib/share/config.js';
 /** Map a supported image file extension to its wire mimeType. Rejects anything else. */
 function imageMimeFromPath(file) {
     const ext = path.extname(file).toLowerCase();
@@ -155,6 +156,8 @@ Examples:
     })
         .option('--branch <name>', 'Target git branch')
         .option('--on <event>', 'Register this run as an event trigger instead of dispatching now: pull_request (pr), push, issue_comment, workflow_run. Persists a trigger-bound routine.')
+        .option('--action <name>', 'GitHub webhook action filter for --on triggers (e.g. labeled)')
+        .option('--label <name>', 'GitHub label filter for --on triggers')
         .option('--name <name>', 'Routine name to register under (with --on). Defaults to a generated name.')
         .option('-p, --prompt <text>', 'Inline prompt (alternative to positional argument)')
         .option('--timeout <duration>', 'Kill after duration (e.g., 30m, 2h)')
@@ -205,7 +208,7 @@ Examples:
         // Resolve prompt: --prompt flag, positional arg, or file
         let prompt = options.prompt || positionalPrompt;
         if (!prompt)
-            die('Prompt is required. Pass it as an argument or with --prompt.');
+            die('Prompt is required. Pass it as an argument or with --prompt.', 1, { json, hint: 'agents cloud run "<task>" --repo <owner/repo>' });
         // If prompt is a file path, read it and tell the user
         if (fs.existsSync(prompt) && fs.statSync(prompt).isFile()) {
             const filePath = prompt;
@@ -220,7 +223,7 @@ Examples:
         // something to the host provider, so it implies --provider host rather
         // than silently riding along to a cloud backend that would ignore it.
         if (options.host && options.provider && options.provider !== 'host') {
-            die(`--host targets your own machines (--provider host), not ${options.provider}. Drop --host, or use --provider host.`);
+            die(`--host targets your own machines (--provider host), not ${options.provider}. Drop --host, or use --provider host.`, 1, { json });
         }
         const explicitProvider = options.provider ?? (options.host ? 'host' : undefined);
         // Agent-aware: with no --provider, the agent routes to its native cloud
@@ -245,6 +248,9 @@ Examples:
             model: options.model,
             providerOptions: {},
         };
+        const shareEnv = shareRuntimeEnv({ agentOnly: true });
+        if (shareEnv)
+            dispatchOptions.env = shareEnv;
         if (options.env)
             dispatchOptions.providerOptions.env = options.env;
         if (options.computer)
@@ -272,21 +278,25 @@ Examples:
         if (options.on) {
             const event = normalizeTriggerEvent(options.on);
             if (!event) {
-                die(`Unknown --on event "${options.on}". Use one of: ${GITHUB_TRIGGER_EVENTS.join(', ')} (aliases: pr, comment, workflow).`);
+                die(`Unknown --on event "${options.on}". Use one of: ${GITHUB_TRIGGER_EVENTS.join(', ')} (aliases: pr, comment, workflow).`, 1, { json });
             }
             const trigger = { type: 'github_event', event: event };
             if (repoValues[0])
                 trigger.repo = repoValues[0];
             if (options.branch)
                 trigger.branch = options.branch;
+            if (options.action)
+                trigger.action = options.action;
+            if (options.label)
+                trigger.label = options.label;
             const triggerErrors = validateTrigger(trigger);
             if (triggerErrors.length > 0)
-                die(`Invalid trigger: ${triggerErrors.join(', ')}`);
+                die(`Invalid trigger: ${triggerErrors.join(', ')}`, 1, { json });
             dispatchOptions.trigger = trigger;
             const routineName = options.name
                 || `cloud-${event}-${(repoValues[0] || 'any').replace(/[^a-z0-9]+/gi, '-')}`.toLowerCase();
             if (jobExists(routineName)) {
-                die(`A routine named "${routineName}" already exists. Pass --name to register under a different name.`);
+                die(`A routine named "${routineName}" already exists. Pass --name to register under a different name.`, 1, { json });
             }
             const routine = {
                 name: routineName,
@@ -329,15 +339,15 @@ Examples:
         const caps = provider.capabilities();
         if (imagePaths.length > 0) {
             if (!caps.images)
-                die(`${provider.name} does not support image attachments.`);
+                die(`${provider.name} does not support image attachments.`, 1, { json });
             if (imagePaths.length > MAX_IMAGES_PER_DISPATCH) {
-                die(`Too many images: ${imagePaths.length}. Max is ${MAX_IMAGES_PER_DISPATCH} per dispatch.`);
+                die(`Too many images: ${imagePaths.length}. Max is ${MAX_IMAGES_PER_DISPATCH} per dispatch.`, 1, { json });
             }
             dispatchOptions.images = imagePaths.map(readImageAttachment);
         }
         if (skillIds.length > 0) {
             if (!caps.skills)
-                die(`${provider.name} does not support ride-along skills.`);
+                die(`${provider.name} does not support ride-along skills.`, 1, { json });
             dispatchOptions.skills = skillIds.map(parseSkillRef);
         }
         // Dispatch. On a missing pre-provisioned target (Codex env / Factory
@@ -362,18 +372,18 @@ Examples:
             if (err instanceof MissingTargetError) {
                 const picked = await pickMissingTarget(provider, err, json);
                 if (!picked) {
-                    die(err.guidance ? `${err.message}\n\n${err.guidance}` : err.message);
+                    die(err.guidance ? `${err.message}\n\n${err.guidance}` : err.message, 1, { json });
                 }
                 dispatchOptions.providerOptions[err.kind] = picked;
                 try {
                     task = await dispatchOnce();
                 }
                 catch (err2) {
-                    die(err2.message);
+                    die(err2.message, 1, { json });
                 }
             }
             else {
-                die(err.message);
+                die(err.message, 1, { json });
             }
         }
         // Persist locally

package/dist/commands/commands.js

@@ -43,6 +43,7 @@ When to use:
 `);
     commandsCmd
         .command('list [agent]')
+        .option('--json', 'Emit machine-readable JSON instead of the table/picker')
         .description('Show which slash commands are installed and which agent versions they are synced to')
         .option('-a, --agent <agent>', 'Filter to a specific agent (alternative to positional arg)')
         .action(async (agentArg, options) => {
@@ -73,6 +74,7 @@ When to use:
             centralPath: getCommandsDir(),
             filterAgent,
             filterVersion,
+            json: options.json,
         });
     });
     commandsCmd

package/dist/commands/doctor.js

@@ -352,13 +352,13 @@ function parseTargetArg(arg) {
         const versions = listInstalledVersions(agent);
         if (versions.length === 0)
             return { error: `${AGENTS[agent].name} has no installed versions. Run \`agents add ${agent}@<version>\` first.` };
-        return { agent, versions };
+        return { agent, versions, versionExplicit: false };
     }
     if (versionPart === 'default') {
         const def = getGlobalDefault(agent);
         if (!def)
             return { error: `${AGENTS[agent].name} has no default version pinned. Run \`agents use ${agent}@<version>\`.` };
-        return { agent, versions: [def] };
+        return { agent, versions: [def], versionExplicit: true };
     }
     const spec = parseAgentSpec(`${agent}@${versionPart}`);
     if (!spec)
@@ -366,7 +366,7 @@ function parseTargetArg(arg) {
     if (!isVersionInstalled(agent, versionPart)) {
         return { error: `${AGENTS[agent].name}@${versionPart} is not installed. Installed: ${listInstalledVersions(agent).join(', ') || '(none)'}` };
     }
-    return { agent, versions: [versionPart] };
+    return { agent, versions: [versionPart], versionExplicit: true };
 }
 function parseKindFilter(arg) {
     if (!arg)
@@ -601,10 +601,14 @@ async function runFix(parsed, opts) {
     // left to heal's neutral default rather than process.cwd().
     if (!opts.json)
         console.log(chalk.bold('Healing…'));
+    // `agents doctor <agent> --fix` is a SWEEP, same as the bare form — leave the
+    // version list to heal() so it applies its isolated-copy filter. Passing the
+    // enumerated list here would smuggle isolated versions past that filter.
+    // A named version (`<agent>@<version>`) is explicit consent and is passed through.
     const result = await heal({
         mode: 'full',
         agent: parsed?.agent,
-        versions: parsed?.versions,
+        versions: parsed?.versionExplicit ? parsed.versions : undefined,
     });
     if (opts.json) {
         console.log(JSON.stringify(result, null, 2));

package/dist/commands/events.d.ts

@@ -1,16 +1,17 @@
 /**
- * `agents events` — read the structured audit/event log.
+ * `agents events` — read the unified event stream.
  *
- * The event log (`~/.agents/events.jsonl`) records every
- * `agents <module> <cmd>` invocation plus richer typed events (secrets access,
- * version installs, ...), each stamped with who ran it and from where (OS user,
- * local vs SSH, remote client IP). This command reads it back — the audit trail
- * for "who accessed a secret / created a team / started an agent, and from which
- * host?".
+ * One stream over BOTH operational events (`~/.agents/events.jsonl`: every
+ * `agents <module> <cmd>` invocation plus typed events like secrets access,
+ * version installs) AND agent-semantic events (the per-session activity logs:
+ * plans, PRs, worktrees, sub-agents, artifacts). Each is stamped with who ran
+ * it and from where. This is the audit trail for "who accessed a secret /
+ * created a team" AND the activity trail for "what did the agents just do".
  *
- * Filter by `--module` (top-level group, e.g. teams), `--command` (path prefix,
- * e.g. "teams create"), `--event` (typed event), `--agent`, and `--since`.
- * `--follow` tails today's log live.
+ * Filter by `--module` (top-level group, e.g. teams; `activity` for agent
+ * events), `--command` (path prefix), `--event` (typed event), `--agent`, and
+ * `--since`. `--audit` restricts to operational events only. `--follow` tails
+ * today's operational log live.
  */
 import type { Command } from 'commander';
 export declare function registerEventsCommand(program: Command): void;

package/dist/commands/events.js

@@ -1,20 +1,22 @@
 /**
- * `agents events` — read the structured audit/event log.
+ * `agents events` — read the unified event stream.
  *
- * The event log (`~/.agents/events.jsonl`) records every
- * `agents <module> <cmd>` invocation plus richer typed events (secrets access,
- * version installs, ...), each stamped with who ran it and from where (OS user,
- * local vs SSH, remote client IP). This command reads it back — the audit trail
- * for "who accessed a secret / created a team / started an agent, and from which
- * host?".
+ * One stream over BOTH operational events (`~/.agents/events.jsonl`: every
+ * `agents <module> <cmd>` invocation plus typed events like secrets access,
+ * version installs) AND agent-semantic events (the per-session activity logs:
+ * plans, PRs, worktrees, sub-agents, artifacts). Each is stamped with who ran
+ * it and from where. This is the audit trail for "who accessed a secret /
+ * created a team" AND the activity trail for "what did the agents just do".
  *
- * Filter by `--module` (top-level group, e.g. teams), `--command` (path prefix,
- * e.g. "teams create"), `--event` (typed event), `--agent`, and `--since`.
- * `--follow` tails today's log live.
+ * Filter by `--module` (top-level group, e.g. teams; `activity` for agent
+ * events), `--command` (path prefix), `--event` (typed event), `--agent`, and
+ * `--since`. `--audit` restricts to operational events only. `--follow` tails
+ * today's operational log live.
  */
 import chalk from 'chalk';
 import * as fs from 'fs';
-import { query, getLogsPath } from '../lib/events.js';
+import { getLogsPath } from '../lib/events.js';
+import { readUnifiedEvents } from '../lib/event-stream.js';
 /** Parse `--since`: relative offsets (30s/5m/2h/7d/4w) or an ISO/absolute date. */
 function parseSince(s) {
     const m = s.match(/^(\d+)([smhdw])$/);
@@ -42,6 +44,11 @@ function detailFor(r) {
     if (r.command)
         return r.command;
     const bits = [];
+    // Agent-semantic (activity) events carry detail/url instead of a command.
+    if (typeof r.detail === 'string')
+        bits.push(r.detail);
+    if (typeof r.url === 'string')
+        bits.push(chalk.gray(r.url));
     if (typeof r.team === 'string')
         bits.push(`team=${r.team}`);
     if (typeof r.bundle === 'string')
@@ -66,23 +73,24 @@ function renderRow(r) {
 export function registerEventsCommand(program) {
     program
         .command('events')
-        .description('Read the structured audit/event log (who ran what, from where)')
-        .option('--module <name>', 'Only events from this command group (e.g. teams, secrets)')
+        .description('Read the unified event stream (operational + agent activity)')
+        .option('--module <name>', 'Only events from this group (e.g. teams, secrets, activity)')
         .option('--command <path>', 'Only this command path — prefix match (e.g. "teams create")')
-        .option('--event <type>', 'Only this typed event (repeatable, e.g. secrets.get)', collect, [])
+        .option('--event <type>', 'Only this typed event (repeatable, e.g. secrets.get, pr.opened)', collect, [])
         .option('--agent <name>', 'Only events tagged with this agent')
         .option('--since <time>', 'Only events newer than this (e.g. 2h, 7d, or ISO date)')
+        .option('--audit', 'Operational events only (skip agent activity)')
         .option('--limit <n>', 'Max records to show (default 50)', '50')
         .option('--json', 'Output raw records as JSON')
-        .option('-f, --follow', "Tail today's log live")
+        .option('-f, --follow', "Tail today's operational log live")
         .addHelpText('after', `
 Examples:
-  agents events                          Recent activity across everything
-  agents events --module teams           Team lifecycle (create / add / disband)
+  agents events                          Everything — ops + agent activity
+  agents events --module activity        Agent activity only (plans / PRs / worktrees)
+  agents events --audit                  Operational events only (secrets / teams / ...)
+  agents events --event pr.opened --since 7d
   agents events --module secrets         Every secret accessed or revealed
-  agents events --command "teams create" Just team creations
-  agents events --event secrets.get --since 7d --json
-  agents events -f                       Live tail`)
+  agents events -f                       Live tail (operational)`)
         .action(async (options) => {
         if (options.follow) {
             await followLog();
@@ -97,13 +105,14 @@ Examples:
             console.error(chalk.red(err.message));
             process.exit(2);
         }
-        const records = query({
+        const records = readUnifiedEvents({
             startDate,
             eventTypes: options.event && options.event.length ? options.event : undefined,
             agent: options.agent,
             command: options.command,
             module: options.module,
             limit,
+            includeActivity: !options.audit,
         });
         if (options.json) {
             console.log(JSON.stringify(records, null, 2));

package/dist/commands/exec.d.ts

@@ -21,6 +21,7 @@ export declare function runAccountPickerConflicts(options: {
     strategy?: string;
     balanced?: boolean;
     lease?: string | boolean;
+    box?: string;
     host?: string;
     device?: string;
     on?: string;
@@ -34,6 +35,39 @@ export interface CopyCredsGateHost {
     /** `devices` = registered Tailscale fleet host; `local` = ssh-config/inline. */
     provider?: string;
 }
+/**
+ * Whether `cwd` is inside a git work tree.
+ *
+ * `--lease` / `--box` sync the working directory to the box through crabbox,
+ * which enumerates the files to copy with `git ls-files`. Outside a git repo
+ * that exits 128 (`fatal: not a git repository`) and the whole run dies at
+ * "build sync file list: exit status 128" — AFTER the box is provisioned and
+ * billed. Checking this up front lets the caller fail fast, before provisioning.
+ */
+export declare function isInsideGitWorkTree(cwd: string): boolean;
+/** Absolute git toplevel for `cwd`, or null when it is not a git repo. */
+export declare function gitToplevel(cwd: string): string | null;
+/**
+ * Network mode for a `--lease` run (F5, RUSH-1924). `--tailscale` forces the
+ * tailnet, `--no-tailscale` forces public, and neither (undefined) defaults to
+ * the tailnet ONLY in a reuse context (`--reuse`, `--box`, or a picked warm
+ * box) — a one-shot solo `--lease` stays public. Pure so it is unit-testable;
+ * the caller downgrades to `'public'` when no auth key is configured.
+ */
+export declare function computeNetMode(opts: {
+    tailscale?: boolean;
+    reuseContext: boolean;
+}): 'public' | 'tailscale';
+/** True when `repoRoot` is in the remembered always-fresh set. Pure. */
+export declare function isAlwaysFreshRepo(repos: string[], repoRoot: string): boolean;
+/** Add `repoRoot` to the always-fresh set (idempotent). Pure. */
+export declare function addAlwaysFreshRepo(repos: string[], repoRoot: string): string[];
+/** Path to the always-fresh state file under the USER agents dir (CLI-written per-user preference, never the maintainer-owned `.system` repo). */
+export declare function leaseFreshReposPath(): string;
+/** Read the remembered always-fresh repo roots (empty on any read/parse error). */
+export declare function readAlwaysFreshRepos(): string[];
+/** Persist the always-fresh repo roots. Best-effort — never throws. */
+export declare function writeAlwaysFreshRepos(repos: string[]): void;
 /** Outcome of the `--copy-creds` security gate (RUSH-1767). */
 export interface CopyCredsGateDecision {
     /** Ship credentials? True only when the host key is pinned in the managed store. */