@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/config-keys.js

@@ -1,20 +1,6 @@
-/**
- * Unified config key grammar for `agents config`.
- *
- * Translates user-facing dotted keys like `run.claude@*.tier.best` into the
- * existing storage locations (run.defaults, model.tiers, config.*,
- * defaultBrowserProfile, deviceConfig.*) so the new command barrel can sit on
- * top of the current YAML schema without a migration.
- */
 import { AGENTS } from './agents.js';
 import { MODEL_TIERS } from './model-tiers.js';
 import { VERSION_RE } from './run-defaults.js';
-/**
- * The AGI Menu preference leaf names under `menubar.menu.*` (PHNX-3999). The
- * types, defaults, and enum validation for each live in `device-config.ts`'s
- * CONFIG_KEYS (user scope); this list is only the parser's allow-set so an
- * unknown `menubar.menu.<x>` fails loud here instead of at the store.
- */
 export const MENUBAR_MENU_PROPERTIES = [
     'defaultProject',
     'workingRowsShown',
@@ -34,6 +20,12 @@ export const MENUBAR_MENU_PROPERTIES = [
     'headlessAgent',
     'headlessFallbackAgent',
     'headlessPlacement',
+    'pinnedProjects',
+    'tabOrder',
+    'hiddenTabs',
+    'groupTicketsByMilestone',
+    'prGroupOpen',
+    'prGroupMerged',
 ];
 const DEVICE_CONFIG_PROPERTIES = [
     'browser.viewer',
@@ -50,7 +42,6 @@ const DEVICE_CONFIG_PROPERTIES = [
     'computer.host',
     'formFactor',
 ];
-/** Split an agent@version token into its parts. Accepts both `@` and `:`. */
 function parseAgentVersion(token) {
     const sep = token.includes('@') ? '@' : ':';
     const [agentPart, versionPart = '*'] = token.split(sep);
@@ -63,33 +54,9 @@ function parseAgentVersion(token) {
     }
     return { agent: agent, version: versionPart };
 }
-/** Normalize agent@version to use `@` consistently. */
 export function formatAgentVersion(agent, version) {
     return `${agent}@${version}`;
 }
-/**
- * Parse a unified config key into its structured representation.
- *
- * Supported forms:
- *   run.<agent@version>.model
- *   run.<agent@version>.mode
- *   run.<agent@version>.effort
- *   run.<agent@version>.tier.<cheap|default|best|ultra>
- *   interactive.host
- *   auto.pool
- *   browser.profile
- *   project.root
- *   devices.<name>.role
- *   devices.<name>.max-agents
- *   devices.<name>.scheduler
- *   devices.<name>.daemon
- *   devices.<name>.watchdog
- *   devices.<name>.tmux
- *   devices.<name>.browser.remote-control
- *   devices.<name>.browser.task-idle-minutes
- *   devices.<name>.notes
- *   devices.<name>.browser.profile
- */
 export function parseConfigKey(key) {
     const raw = key.trim();
     if (!raw)
@@ -153,7 +120,6 @@ export function parseConfigKey(key) {
             property: deviceMatch[2],
         };
     }
-    // Provide helpful errors for common mistakes.
     if (raw.startsWith('run.')) {
         throw new Error(`Invalid run config key '${key}'. Expected run.<agent@version>.<model|mode|effort> or run.<agent@version>.tier.<cheap|default|best|ultra>.`);
     }
@@ -183,7 +149,6 @@ export function parseConfigKey(key) {
     }
     throw new Error(`Unknown config scope in '${key}'. Use one of: run, interactive, auto, browser, project, devices, summarizer, updates, menubar.`);
 }
-/** Render a parsed key back to its canonical dotted string. */
 export function formatConfigKey(parsed) {
     switch (parsed.scope) {
         case 'run':
@@ -211,7 +176,6 @@ export function formatConfigKey(parsed) {
             return `menubar.menu.${parsed.property}`;
     }
 }
-/** List every canonical key the command documents, with wildcards expanded to a concrete example. */
 export function listKnownConfigKeys() {
     const keys = [];
     keys.push('run.<agent@version>.model', 'run.<agent@version>.mode', 'run.<agent@version>.effort');
@@ -227,11 +191,6 @@ export function listKnownConfigKeys() {
     }
     return keys;
 }
-/**
- * Map a parsed device property to the internal device-config key name.
- * This is the bridge between the friendly `agents config` surface and the
- * existing CONFIG_KEYS registry in lib/device-config.ts.
- */
 export function devicePropertyToConfigName(property) {
     switch (property) {
         case 'role':
@@ -262,10 +221,6 @@ export function devicePropertyToConfigName(property) {
             return 'formFactor';
     }
 }
-/**
- * Map a parsed key to the human-readable "where is this stored" note.
- * Useful for `agents config list --source` output.
- */
 export function configKeyStorageHint(parsed) {
     switch (parsed.scope) {
         case 'run':
@@ -279,7 +234,6 @@ export function configKeyStorageHint(parsed) {
             return 'config.autoPool';
         case 'browser': {
             if (parsed.property === 'device') {
-                // User scope: one value in the central agents.yaml that syncs fleet-wide.
                 return 'config.defaultBrowserDevice (central agents.yaml; syncs fleet-wide)';
             }
             const yamlKey = parsed.property === 'viewer' ? 'browserViewer' : 'defaultBrowserProfile';

package/dist/lib/config-transfer.d.ts

@@ -1,16 +1,2 @@
-/**
- * Move `source` onto `dest` across possibly-different volumes. `renameSync` is
- * atomic but throws EXDEV when `~/.agents` lives on a different filesystem than
- * `$HOME`; fall back to copy-then-remove so the restore still completes. The
- * source is removed only after the copy succeeds, so a mid-copy failure never
- * destroys the sole surviving copy.
- */
 export declare function moveDirCrossDevice(source: string, dest: string): void;
-/**
- * Copy `source` to `dest`, dropping any symlink whose target resolves back into
- * `~/.agents`. Managed resources (skills/commands) are synced into a version home
- * as symlinks into `~/.agents`; copying them verbatim would leave the result full
- * of links that dangle the moment `~/.agents` is disposed. Stripping them yields a
- * clean, self-contained copy — which is the entire point of an export.
- */
 export declare function copyDirStrippingAgentsSymlinks(source: string, dest: string, agentsDir: string): void;

package/dist/lib/config-transfer.js

@@ -1,20 +1,5 @@
-/**
- * Primitives for moving an agent config directory across the agents-cli boundary.
- *
- * Both helpers were part of {@link ./uninstall.ts} and are unchanged — teardown was
- * simply the first caller. Other config-transfer paths need the same operations, so
- * they live here rather than being duplicated or imported out of a module named for
- * teardown.
- */
 import * as fs from 'fs';
 import * as path from 'path';
-/**
- * Move `source` onto `dest` across possibly-different volumes. `renameSync` is
- * atomic but throws EXDEV when `~/.agents` lives on a different filesystem than
- * `$HOME`; fall back to copy-then-remove so the restore still completes. The
- * source is removed only after the copy succeeds, so a mid-copy failure never
- * destroys the sole surviving copy.
- */
 export function moveDirCrossDevice(source, dest) {
     try {
         fs.renameSync(source, dest);
@@ -26,20 +11,10 @@ export function moveDirCrossDevice(source, dest) {
         fs.rmSync(source, { recursive: true, force: true });
     }
 }
-/**
- * Copy `source` to `dest`, dropping any symlink whose target resolves back into
- * `~/.agents`. Managed resources (skills/commands) are synced into a version home
- * as symlinks into `~/.agents`; copying them verbatim would leave the result full
- * of links that dangle the moment `~/.agents` is disposed. Stripping them yields a
- * clean, self-contained copy — which is the entire point of an export.
- */
 export function copyDirStrippingAgentsSymlinks(source, dest, agentsDir) {
     const inside = agentsDir + path.sep;
     fs.cpSync(source, dest, {
         recursive: true,
-        // `force: true` is Node's default, but Bun drops it when a `filter` is supplied —
-        // existing files are then silently left alone. `dist/bin/agents` is bun-compiled,
-        // so this is a production path, not just a test artifact. State it explicitly.
         force: true,
         filter: (src) => {
             try {
@@ -51,7 +26,6 @@ export function copyDirStrippingAgentsSymlinks(source, dest, agentsDir) {
                 }
             }
             catch {
-                /* unreadable entry — let cpSync surface it on the real copy */
             }
             return true;
         },

package/dist/lib/convert.d.ts

@@ -1,19 +1,2 @@
-/**
- * Format conversion between Markdown (Claude/Codex) and TOML (Gemini) command files.
- *
- * Handles frontmatter parsing and bidirectional translation so that slash commands
- * authored in one format can be synced to agents that expect the other.
- */
-/** Convert a Markdown command file to Gemini's TOML format, translating $ARGUMENTS to {{args}}. */
 export declare function markdownToToml(skillName: string, markdown: string): string;
-/**
- * Convert a Markdown command file to a Goose recipe YAML object.
- *
- * Goose has no native slash-command file format — a slash command is a recipe
- * (registered in `config.yaml` under `slash_commands`). The recipe schema matches
- * the one agents-cli already emits for Goose workflow/subagent recipes:
- * `version`, `title`, `description`, `instructions`, `prompt`. The Markdown body
- * (with `$ARGUMENTS` preserved) becomes both `instructions` and `prompt`.
- * Returns a plain object so the caller can `yaml.stringify` it.
- */
 export declare function markdownToGooseRecipe(commandName: string, markdown: string): Record<string, unknown>;

package/dist/lib/convert.js

@@ -1,10 +1,3 @@
-/**
- * Format conversion between Markdown (Claude/Codex) and TOML (Gemini) command files.
- *
- * Handles frontmatter parsing and bidirectional translation so that slash commands
- * authored in one format can be synced to agents that expect the other.
- */
-/** Extract YAML frontmatter and body from a Markdown string. Returns empty frontmatter if none found. */
 function parseMarkdownFrontmatter(content) {
     const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
     if (!match) {
@@ -23,7 +16,6 @@ function parseMarkdownFrontmatter(content) {
     }
     return { frontmatter, body };
 }
-/** Convert a Markdown command file to Gemini's TOML format, translating $ARGUMENTS to {{args}}. */
 export function markdownToToml(skillName, markdown) {
     const { frontmatter, body } = parseMarkdownFrontmatter(markdown);
     const description = frontmatter.description || `Run ${skillName} command`;
@@ -40,16 +32,6 @@ export function markdownToToml(skillName, markdown) {
     ];
     return lines.join('\n');
 }
-/**
- * Convert a Markdown command file to a Goose recipe YAML object.
- *
- * Goose has no native slash-command file format — a slash command is a recipe
- * (registered in `config.yaml` under `slash_commands`). The recipe schema matches
- * the one agents-cli already emits for Goose workflow/subagent recipes:
- * `version`, `title`, `description`, `instructions`, `prompt`. The Markdown body
- * (with `$ARGUMENTS` preserved) becomes both `instructions` and `prompt`.
- * Returns a plain object so the caller can `yaml.stringify` it.
- */
 export function markdownToGooseRecipe(commandName, markdown) {
     const { frontmatter, body } = parseMarkdownFrontmatter(markdown);
     const description = frontmatter.description || `Run ${commandName} command`;

package/dist/lib/crabbox/cli.d.ts

@@ -1,230 +1,74 @@
-/**
- * Typed wrapper over the external `crabbox` binary (github.com/openclaw/crabbox).
- *
- * crabbox leases ephemeral cloud boxes (Hetzner/DO/EC2/…), syncs the dirty
- * checkout, and runs commands on them. We use it as the transport for
- * `agents run --lease`: warm a box → run the agent on it via `crabbox run` →
- * stop it. crabbox owns the SSH connection, so agents-cli never needs a direct
- * ssh target (unlike the host-dispatch model).
- *
- * crabbox talks to its cloud provider's API for list/status/warmup/stop, which
- * needs a provider token (e.g. HCLOUD_TOKEN) in the environment. We inject it
- * from a secrets bundle when one is configured (see `crabboxEnv`).
- */
 import type { SecretsBundle } from '../secrets-types.js';
-/** A crabbox machine as reported by `crabbox list --json`. */
 export interface CrabboxBox {
-    /** Provider machine name, e.g. `crabbox-blue-hermit-1039689b`. */
     name: string;
-    /** Provider run state, e.g. `running`. */
     status: string;
-    /** Friendly slug used with `--id`, e.g. `blue-hermit`. */
     slug: string;
-    /** Lease id, e.g. `cbx_9968746bb15c`. */
     lease: string;
-    /** crabbox bootstrap state; `ready` once the box is usable. */
     state: string;
-    /** Public IPv4, when the provider exposes one. */
     ip?: string;
-    /** Tailnet IPv4 (100.x), when the box was leased with `--network tailscale`. */
     tailscaleIPv4?: string;
-    /** Tailnet MagicDNS FQDN, when the box joined the tailnet. */
     tailscaleFQDN?: string;
     profile?: string;
     class?: string;
-    /** True when running + bootstrap-complete. */
     ready: boolean;
-    /** crabbox `keep` label — a kept box survives `crabbox cleanup` past its TTL. */
     keep: boolean;
-    /** Unix seconds the box was created, or null when the label is absent. */
     createdAt: number | null;
-    /** Unix seconds the lease expires, or null. */
     expiresAt: number | null;
-    /** Unix seconds the box was last touched (reused / run against), or null. */
     lastTouchedAt: number | null;
-    /** Idle-timeout window in seconds, or null. */
     idleTimeoutSecs: number | null;
 }
 interface CrabboxOptions {
-    /**
-     * Name of a secrets bundle whose env (e.g. `HCLOUD_TOKEN`) crabbox needs to
-     * reach its cloud provider. Resolved via agents-cli's own keychain-backed
-     * secrets. When unset, crabbox runs with the ambient environment / its own
-     * `crabbox login` credentials.
-     */
     secretsBundle?: string;
-    /**
-     * Hard cap (ms) on a single crabbox invocation that hits the provider API
-     * (`list`). Prevents a slow/unreachable provider from hanging an ambient
-     * command like `agents devices`. Defaults to 8s; callers on a fast/interactive
-     * path (devices list, `agents ssh` fall-through) pass a shorter bound.
-     */
     timeoutMs?: number;
 }
-/** Locate the crabbox binary, or throw an actionable error. */
 export declare function findCrabbox(): string;
-/** The first bundle that declares a provider token key, or undefined. Pure over `bundles`. */
 export declare function pickLeaseBundleFromList(bundles: SecretsBundle[]): string | undefined;
-/** The first bundle + key that declares a Tailscale auth key, or undefined. Pure over `bundles`. */
 export declare function pickTailscaleBundleFromList(bundles: SecretsBundle[]): {
     name: string;
     key: string;
 } | undefined;
-/** Test seam: drop every crabboxEnv secrets memo so each test resolves fresh. */
 export declare function resetCrabboxSecretsMemosForTest(): void;
-/** A resolved lease bundle: its name, plus (auto-detect only) the exact keys to inject. */
 interface ResolvedLeaseBundle {
     name: string;
-    /** When set (auto-detect), inject ONLY these keys — not the whole bundle. */
     keys?: string[];
 }
-/**
- * The secrets bundle to feed crabbox, resolved in priority order:
- *   1. `AGENTS_LEASE_SECRETS_BUNDLE` env var          — explicit, no keychain
- *   2. `lease.secretsBundle` config (set by `lease setup`) — explicit, no keychain
- *   3. auto-detect: the first keychain bundle DECLARING a provider token key
- *
- * Tiers 1–2 are the frictionless steady state (env + config are plain, no keychain
- * read). Tier 3 is a fallback that DOES read bundle metadata via `listBundles()`
- * (one batched keychain unlock, ~7-day broker cache) — so it only runs when
- * neither env nor config is set, and `crabboxEnv` memoizes the result for the
- * process (it is called several times per lease, and we don't want a scan each
- * time). Once `lease setup` persists the choice (tier 2), tier 3 never runs.
- * Returns undefined when nothing matches — crabbox then falls back to `crabbox login`.
- */
 export declare function resolveLeaseBundle(): ResolvedLeaseBundle | undefined;
-/** Persist `lease.secretsBundle` in agents config so `--lease` needs no env var. */
 export declare function setLeaseSecretsBundle(name: string): void;
-/** Build the child env for crabbox, injecting a secrets bundle when configured. */
 export declare function crabboxEnv(opts: CrabboxOptions): NodeJS.ProcessEnv;
-/** All crabbox machines the broker knows about. */
 export declare function crabboxList(opts?: CrabboxOptions): CrabboxBox[];
-/** Find one box by slug, or null. */
 export declare function crabboxFind(slug: string, opts?: CrabboxOptions): CrabboxBox | null;
-/**
- * Whether `crabbox status` reports the box SSH-ready (`ready=true`). A box whose
- * cloud-init bootstrap failed still LISTS as `running` but never becomes ready —
- * selecting it burns the full SSH wait before hard-failing. `crabbox status`
- * flips ready=true only once sshd answers, so warm-pool reuse gates on it
- * (mirrors scripts/sandbox.sh's `box_ready`).
- */
 export declare function crabboxStatusReady(slug: string, opts?: CrabboxOptions): boolean;
 interface PoolMatchOptions {
-    /**
-     * Lease pool label (shared default, or `.crabbox.yaml leaseProfile:` opt-in;
-     * see config.ts). Both sides normalize an unset profile to
-     * DEFAULT_CRABBOX_PROFILE, so profile-less runs match unlabeled boxes.
-     */
     profile?: string;
-    /**
-     * Network mode of the run (default 'public'). A tailnet-joined box is never
-     * handed to a public run, nor a public box to a tailnet run — reachability and
-     * exposure differ, so the pool is partitioned by it.
-     */
     netMode?: 'public' | 'tailscale';
-    /** Injectable clock (unix seconds) for the expiry check. */
     nowSecs?: number;
 }
-/**
- * Warm boxes in the profile pool this run could reuse: `running`, same profile
- * label, same network mode, lease unexpired — most-recently-touched first.
- *
- * Readiness is NOT required here (deliberately mirrors sandbox.sh's
- * `running_slugs_for_profile`, which filters on `status` only): the list `state`
- * label can lag, so the caller gates each candidate on `crabboxStatusReady`
- * before committing. A not-ready box is skipped, never stopped — a concurrent
- * run may be mid-boot on it, and crabbox's idle timeout reaps genuine duds.
- */
 export declare function poolReusableBoxes(boxes: CrabboxBox[], opts?: PoolMatchOptions): CrabboxBox[];
 interface WarmupOptions extends CrabboxOptions {
     class?: string;
     profile?: string;
-    /** Provision web code-server capability on the box. */
     code?: boolean;
-    /** Cloud backend override (crabbox provider id, e.g. hetzner/aws/do). */
     provider?: string;
-    /**
-     * Network mode for the leased box. `'public'` (default) leases with a public
-     * IP; `'tailscale'` joins the box to the tailnet (`--network tailscale`,
-     * tagged `tag:crabbox`) so it is reachable only over Tailscale. The caller
-     * (command layer) decides WHEN to enable this — F5 here is plumbing only.
-     */
     netMode?: 'public' | 'tailscale';
 }
-/**
- * Lease a box and block until it is ready. Returns the leased box.
- *
- * We diff `crabbox list` before/after so we reliably identify the box this call
- * created even if warmup's stdout format changes — the new lease id is the one
- * that wasn't present before.
- */
 export declare function crabboxWarmup(opts?: WarmupOptions): Promise<CrabboxBox>;
-/**
- * Poll until the box reports ready, or throw after timeoutMs.
- * `sleep` is injectable so tests don't wall-clock wait.
- */
 export declare function crabboxWaitReady(slug: string, opts?: CrabboxOptions & {
     timeoutMs?: number;
     intervalMs?: number;
     sleep?: (ms: number) => Promise<void>;
 }): Promise<CrabboxBox>;
 interface CrabboxRunOptions extends CrabboxOptions {
-    /** Called with each chunk of combined stdout/stderr as it streams. */
     onData?: (chunk: string) => void;
-    /** Force a full remote resync before running. */
     fullResync?: boolean;
-    /** Refresh an existing lease with this idle window before running. */
     renewIdleTimeoutSecs?: number;
 }
-/**
- * Upload `script` to the box via `crabbox run --script-stdin` and run it.
- *
- * The script body travels over stdin and is written to a file on the box before
- * execution — it never appears in argv / `ps` / shell history, which is why this
- * is the transport for credential provisioning (the token contents live only in
- * the uploaded script, then the file is removed by the script itself).
- * Streams combined output; resolves with the remote exit code (null on dispatch failure).
- */
 export declare function crabboxRunScript(slug: string, script: string, opts?: CrabboxRunOptions): Promise<number | null>;
-/**
- * Parse crabbox's shell-quoted `ssh` command (`'ssh' '-i' '<key>' … 'crabbox@ip'`)
- * into an argv array. Exported for testing.
- */
 export declare function parseCrabboxSshArgv(stdout: string): string[] | null;
-/**
- * The concrete `ssh` argv crabbox uses to reach box `slug` — including the
- * per-lease identity key and known_hosts crabbox provisions under its own config
- * dir. A raw `ssh crabbox@ip` fails `publickey`; this is the only auth that works.
- * `crabbox ssh --id` PRINTS the command (it doesn't connect — that's `crabbox
- * connect`), and `--reclaim` makes it resolve regardless of which repo holds the
- * lease claim (matching `crabboxRunScript`). Returns null when crabbox can't
- * resolve the box (caller treats setup-copy / `agents ssh` as best-effort).
- */
 export declare function crabboxSshArgv(slug: string, opts?: CrabboxOptions): string[] | null;
-/** Release the lease / delete the box. Best-effort; never throws. */
 export declare function crabboxStop(slug: string, opts?: CrabboxOptions): boolean;
-/** Never reap a box touched within this many seconds, regardless of idle-timeout. */
 export declare const REAP_MIN_IDLE_SECS = 3600;
-/**
- * Whether a box is a genuine orphan that is safe to reap.
- *
- * Reap-safe ONLY when BOTH hold: the lease has already expired (`expiresAt` in the
- * past) AND the box has not been touched for a safety window of
- * `max(2 × idleTimeout, 1h)`. The freshness guard is what makes this safe against
- * a TOCTOU race: a box a concurrent run just reused (`cbx_acquire_box`) has a
- * recent `lastTouchedAt` and is never eligible. Reaping by `profile`/`ready` alone
- * — as `crabbox cleanup` cannot (it skips `keep=true`, which every real orphan is)
- * — would kill in-use boxes. Boxes with unknown age (`expiresAt`/`lastTouchedAt`
- * null) are never reaped. `nowSecs` is injected so tests don't wall-clock.
- */
 export declare function isReapSafe(box: CrabboxBox, nowSecs: number): boolean;
-/** The reap-safe orphans among `boxes`, most-stale (oldest touch) first. */
 export declare function reapSafeOrphans(boxes: CrabboxBox[], nowSecs: number): CrabboxBox[];
-/**
- * List reap-safe orphans and (unless `dryRun`) stop them. Returns the candidates
- * considered and the slugs actually stopped. Best-effort per box — a stop failure
- * is skipped, never thrown. Backs `agents devices lease prune` and the 403 auto-reap opt-in.
- */
 export declare function reapOrphans(opts?: CrabboxOptions & {
     nowSecs?: number;
     dryRun?: boolean;