@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/add-dir.d.ts

@@ -1,65 +1,19 @@
-/**
- * Cross-harness application of project / `--add-dir` directory grants.
- *
- * A multi-repo project binds several checkouts; the primary becomes cwd and the
- * rest become grants so the agent can read and write the siblings. How a grant
- * lands depends on the harness:
- *
- * - `native-flag`  — Claude, Kimi, Cursor: repeatable `--add-dir <path>`
- * - `codex-policy` — Codex: folded into the named edit profile's workspace_roots
- *                    (handled in buildExecCommand / codex-policy, not here)
- * - `grok-sandbox` — Grok: OS sandbox is off by default (siblings already
- *                    writable); when a non-off sandbox is active, write a
- *                    project-local profile with `read_write` and select it.
- *                    Always appends a short `--rules` note so the model knows
- *                    the siblings are in scope.
- * - `none`         — harness has no multi-root surface; grants are ignored
- *                    (caller may warn). Not a configuration mistake — the CLI
- *                    has nowhere to put the grant.
- *
- * Capability honesty: only strategies that actually change the launch count as
- * support. Silent no-ops stay `none`.
- */
 import type { AgentId } from './types.js';
 type AddDirStrategy = 'native-flag' | 'codex-policy' | 'grok-sandbox' | 'none';
-/** How each harness consumes directory grants. Keep in lockstep with apply* below. */
 export declare const ADD_DIR_STRATEGY: Record<AgentId, AddDirStrategy>;
-/** Expand `~` / `$HOME` and de-dupe, preserving order. */
 export declare function normalizeAddDirs(dirs: string[] | undefined): string[];
-/** Profile name written into `.grok/sandbox.toml` under the run cwd. */
 export declare const GROK_PROJECT_SANDBOX_PROFILE = "agents-project";
-/** Whether Grok's active sandbox needs a custom profile with extra read_write. */
 export declare function grokNeedsSandboxWiden(env?: NodeJS.ProcessEnv): boolean;
-/**
- * Ensure `.grok/sandbox.toml` under `cwd` defines `[profiles.agents-project]`
- * with `read_write` covering every grant, **extending the active base profile**
- * (so `GROK_SANDBOX=strict` does not silently widen to `workspace`).
- * Returns the profile name to pass as `--sandbox`, or null when not needed.
- *
- * Idempotent: rewrites only the managed profile block.
- */
 export declare function ensureGrokProjectSandboxProfile(cwd: string, dirs: string[], opts?: {
     extendsBase?: string;
 }): string | null;
-/**
- * Short rules blob so Grok's model treats sibling dirs as in-scope.
- * Wording tracks whether we actually widened the sandbox for write access.
- */
 export declare function grokAddDirRules(dirs: string[], opts?: {
     writeGranted?: boolean;
 }): string;
-/**
- * Apply directory grants on the argv for harnesses handled here.
- * Codex is intentionally excluded — its path lives next to codexPolicyArgs.
- *
- * @returns true when any argv / on-disk change was made for the grants
- */
 export declare function applyAddDirs(agent: AgentId, cmd: string[], dirs: string[] | undefined, opts?: {
     cwd?: string;
     env?: NodeJS.ProcessEnv;
 }): boolean;
-/** Whether this harness effectively consumes directory grants. */
 export declare function supportsAddDir(agent: AgentId): boolean;
-/** One-line note for harnesses that ignore grants (used by callers that want to warn). */
 export declare function addDirUnsupportedNote(agent: AgentId): string | null;
 export {};

package/dist/lib/add-dir.js

@@ -1,36 +1,12 @@
-/**
- * Cross-harness application of project / `--add-dir` directory grants.
- *
- * A multi-repo project binds several checkouts; the primary becomes cwd and the
- * rest become grants so the agent can read and write the siblings. How a grant
- * lands depends on the harness:
- *
- * - `native-flag`  — Claude, Kimi, Cursor: repeatable `--add-dir <path>`
- * - `codex-policy` — Codex: folded into the named edit profile's workspace_roots
- *                    (handled in buildExecCommand / codex-policy, not here)
- * - `grok-sandbox` — Grok: OS sandbox is off by default (siblings already
- *                    writable); when a non-off sandbox is active, write a
- *                    project-local profile with `read_write` and select it.
- *                    Always appends a short `--rules` note so the model knows
- *                    the siblings are in scope.
- * - `none`         — harness has no multi-root surface; grants are ignored
- *                    (caller may warn). Not a configuration mistake — the CLI
- *                    has nowhere to put the grant.
- *
- * Capability honesty: only strategies that actually change the launch count as
- * support. Silent no-ops stay `none`.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { expandLocalHome } from './project-root.js';
-/** How each harness consumes directory grants. Keep in lockstep with apply* below. */
 export const ADD_DIR_STRATEGY = {
     claude: 'native-flag',
     kimi: 'native-flag',
     cursor: 'native-flag',
     codex: 'codex-policy',
     grok: 'grok-sandbox',
-    // No multi-root CLI surface today (single --dir / project path).
     opencode: 'none',
     openclaw: 'none',
     copilot: 'none',
@@ -42,7 +18,6 @@ export const ADD_DIR_STRATEGY = {
     muse: 'none',
     warp: 'none',
 };
-/** Expand `~` / `$HOME` and de-dupe, preserving order. */
 export function normalizeAddDirs(dirs) {
     if (!dirs?.length)
         return [];
@@ -57,25 +32,12 @@ export function normalizeAddDirs(dirs) {
     }
     return out;
 }
-/**
- * Append native `--add-dir` flags for harnesses that take them (Claude, Kimi, Cursor).
- * No-op for other strategies — call sites route by ADD_DIR_STRATEGY.
- */
 function appendNativeAddDirFlags(cmd, dirs) {
     for (const dir of dirs) {
         cmd.push('--add-dir', dir);
     }
 }
-/** Profile name written into `.grok/sandbox.toml` under the run cwd. */
 export const GROK_PROJECT_SANDBOX_PROFILE = 'agents-project';
-/**
- * Active Grok sandbox profile from the env, if a non-off profile is set.
- * Returns null when sandbox is off / unset / devbox (no widen needed).
- *
- * Only `GROK_SANDBOX` is consulted — a profile set only in config.toml is not
- * visible here (Grok does not expose it on the CLI), so those runs still get
- * the rules note but not a custom widen. Prefer env when launching sandboxed.
- */
 function grokActiveSandboxProfile(env = process.env) {
     const raw = (env.GROK_SANDBOX ?? '').trim();
     if (!raw)
@@ -83,30 +45,19 @@ function grokActiveSandboxProfile(env = process.env) {
     const lower = raw.toLowerCase();
     if (lower === 'off' || lower === 'devbox')
         return null;
-    // Never extend our own managed profile (would recurse).
     if (lower === GROK_PROJECT_SANDBOX_PROFILE.toLowerCase())
         return 'workspace';
     return raw;
 }
-/** Whether Grok's active sandbox needs a custom profile with extra read_write. */
 export function grokNeedsSandboxWiden(env = process.env) {
     return grokActiveSandboxProfile(env) !== null;
 }
-/**
- * Ensure `.grok/sandbox.toml` under `cwd` defines `[profiles.agents-project]`
- * with `read_write` covering every grant, **extending the active base profile**
- * (so `GROK_SANDBOX=strict` does not silently widen to `workspace`).
- * Returns the profile name to pass as `--sandbox`, or null when not needed.
- *
- * Idempotent: rewrites only the managed profile block.
- */
 export function ensureGrokProjectSandboxProfile(cwd, dirs, opts = {}) {
     if (!dirs.length)
         return null;
     if (!cwd)
         return null;
     const base = opts.extendsBase ?? 'workspace';
-    // Refuse to extend ourselves or an empty name.
     const extendsBase = !base || base.toLowerCase() === GROK_PROJECT_SANDBOX_PROFILE.toLowerCase()
         ? 'workspace'
         : base;
@@ -130,7 +81,6 @@ export function ensureGrokProjectSandboxProfile(cwd, dirs, opts = {}) {
         existing = fs.readFileSync(sandboxPath, 'utf-8');
     }
     catch {
-        // create fresh
     }
     const begin = '# BEGIN agents-cli managed';
     const end = '# END agents-cli managed';
@@ -138,14 +88,11 @@ export function ensureGrokProjectSandboxProfile(cwd, dirs, opts = {}) {
     const beginIdx = existing.indexOf(begin);
     const endIdx = existing.indexOf(end);
     if (beginIdx !== -1 && endIdx !== -1 && endIdx > beginIdx) {
-        // Replace through end of the end-marker line
         const afterEnd = existing.indexOf('\n', endIdx);
         const endCut = afterEnd === -1 ? existing.length : afterEnd + 1;
         next = existing.slice(0, beginIdx) + managedBlock + existing.slice(endCut);
     }
     else if (existing.trim()) {
-        // If a hand-written [profiles.agents-project] already exists without our
-        // markers, refuse to append a second block with the same name.
         const bare = new RegExp(`\\[profiles\\.${GROK_PROJECT_SANDBOX_PROFILE}\\]`);
         if (bare.test(existing)) {
             return null;
@@ -159,10 +106,6 @@ export function ensureGrokProjectSandboxProfile(cwd, dirs, opts = {}) {
     fs.writeFileSync(sandboxPath, next, 'utf-8');
     return GROK_PROJECT_SANDBOX_PROFILE;
 }
-/**
- * Short rules blob so Grok's model treats sibling dirs as in-scope.
- * Wording tracks whether we actually widened the sandbox for write access.
- */
 export function grokAddDirRules(dirs, opts = {}) {
     const list = dirs.map((d) => `- ${d}`).join('\n');
     const access = opts.writeGranted === false
@@ -174,12 +117,6 @@ export function grokAddDirRules(dirs, opts = {}) {
         'Treat these as first-class workspace roots alongside the primary cwd.',
     ].join('\n');
 }
-/**
- * Apply directory grants on the argv for harnesses handled here.
- * Codex is intentionally excluded — its path lives next to codexPolicyArgs.
- *
- * @returns true when any argv / on-disk change was made for the grants
- */
 export function applyAddDirs(agent, cmd, dirs, opts = {}) {
     const normalized = normalizeAddDirs(dirs);
     if (normalized.length === 0)
@@ -192,14 +129,13 @@ export function applyAddDirs(agent, cmd, dirs, opts = {}) {
     if (strategy === 'grok-sandbox') {
         const env = opts.env ?? process.env;
         const activeBase = grokActiveSandboxProfile(env);
-        let writeGranted = true; // default off sandbox = unrestricted FS
+        let writeGranted = true;
         if (activeBase) {
             const cwd = opts.cwd ?? process.cwd();
             const profile = ensureGrokProjectSandboxProfile(cwd, normalized, {
                 extendsBase: activeBase,
             });
             if (profile) {
-                // Drop a prior --sandbox <x> pair so the managed profile wins.
                 for (let i = cmd.length - 2; i >= 0; i--) {
                     if (cmd[i] === '--sandbox') {
                         cmd.splice(i, 2);
@@ -209,23 +145,18 @@ export function applyAddDirs(agent, cmd, dirs, opts = {}) {
                 writeGranted = true;
             }
             else {
-                // Could not write the profile (e.g. hand-owned agents-project block).
                 writeGranted = false;
             }
         }
-        // Model awareness always — even when the OS sandbox is off.
         cmd.push('--rules', grokAddDirRules(normalized, { writeGranted }));
         return true;
     }
-    // codex-policy / none — not applied here
     return false;
 }
-/** Whether this harness effectively consumes directory grants. */
 export function supportsAddDir(agent) {
     const s = ADD_DIR_STRATEGY[agent];
     return s === 'native-flag' || s === 'codex-policy' || s === 'grok-sandbox';
 }
-/** One-line note for harnesses that ignore grants (used by callers that want to warn). */
 export function addDirUnsupportedNote(agent) {
     if (supportsAddDir(agent))
         return null;

package/dist/lib/address.d.ts

@@ -20,37 +20,20 @@
  */
 export declare const ADDRESS_SCHEMES: readonly ["ssh", "cdp", "vnc", "tcp", "wss", "ws", "firefox-bidi"];
 export type AddressScheme = (typeof ADDRESS_SCHEMES)[number];
-/** Ports a scheme implies when the address carries none. `tcp` has no default. */
 export declare const DEFAULT_PORTS: Readonly<Partial<Record<AddressScheme, number>>>;
 export interface Address {
     scheme: AddressScheme;
     user?: string;
     host: string;
-    /** The port written in the authority, if any. See {@link addressPort} for the default. */
     port?: number;
-    /** A non-root path (`wss://hub/devtools` → `/devtools`). */
     path?: string;
     query: Record<string, string>;
-    /** The trimmed input, for messages. */
     raw: string;
 }
 export declare function parseAddress(input: string): Address;
-/** The effective port: written, else the scheme's default, else undefined. */
 export declare function addressPort(addr: Address): number | undefined;
-/** `user@host` (or bare `host`) for an `ssh` address — what OpenSSH is given. */
 export declare function sshTarget(addr: Address): string;
-/**
- * OpenSSH options carrying a non-default SSH port. `-o Port=N` rather than
- * `-p`/`-P` so the same argv serves both `ssh` and `scp`.
- */
 export declare function sshPortArgs(addr: Address): string[];
-/** `host:port` for a `vnc` address, defaulting the RFB display port. */
 export declare function vncEndpoint(addr: Address): string;
-/** `host:port` for a `tcp` address. A helper RPC endpoint has no default port. */
 export declare function tcpEndpoint(addr: Address): string;
-/**
- * The DevTools port a browser endpoint means. On `ssh://` the authority port is
- * the SSH port, so the DevTools port comes only from `?port=`; `cdp://` and
- * `ssh://` default to 9222, path-addressed sockets (`wss://`) have none.
- */
 export declare function browserEndpointPort(addr: Address): number | undefined;

package/dist/lib/address.js

@@ -19,14 +19,12 @@
  * loud, and so does any scheme not listed above.
  */
 export const ADDRESS_SCHEMES = ['ssh', 'cdp', 'vnc', 'tcp', 'wss', 'ws', 'firefox-bidi'];
-/** Ports a scheme implies when the address carries none. `tcp` has no default. */
 export const DEFAULT_PORTS = {
     ssh: 22,
     cdp: 9222,
     vnc: 5901,
 };
 const SCHEME_SET = new Set(ADDRESS_SCHEMES);
-/** A bare OpenSSH target: `host` or `user@host`, letters, digits, `.`, `_`, `-`. */
 const IMPLICIT_SSH = /^[A-Za-z0-9._-]+(@[A-Za-z0-9._-]+)?$/;
 export function parseAddress(input) {
     const raw = input.trim();
@@ -84,35 +82,27 @@ export function parseAddress(input) {
         raw,
     };
 }
-/** The effective port: written, else the scheme's default, else undefined. */
 export function addressPort(addr) {
     return addr.port ?? DEFAULT_PORTS[addr.scheme];
 }
-/** `user@host` (or bare `host`) for an `ssh` address — what OpenSSH is given. */
 export function sshTarget(addr) {
     if (addr.scheme !== 'ssh') {
         throw new Error(`expected ssh:// or user@host, got ${addr.scheme}:// (${addr.raw})`);
     }
     return addr.user ? `${addr.user}@${addr.host}` : addr.host;
 }
-/**
- * OpenSSH options carrying a non-default SSH port. `-o Port=N` rather than
- * `-p`/`-P` so the same argv serves both `ssh` and `scp`.
- */
 export function sshPortArgs(addr) {
     if (addr.scheme !== 'ssh') {
         throw new Error(`expected ssh:// or user@host, got ${addr.scheme}:// (${addr.raw})`);
     }
     return addr.port === undefined ? [] : ['-o', `Port=${addr.port}`];
 }
-/** `host:port` for a `vnc` address, defaulting the RFB display port. */
 export function vncEndpoint(addr) {
     if (addr.scheme !== 'vnc') {
         throw new Error(`expected vnc://, got ${addr.scheme}:// (${addr.raw})`);
     }
     return `${addr.host}:${addressPort(addr)}`;
 }
-/** `host:port` for a `tcp` address. A helper RPC endpoint has no default port. */
 export function tcpEndpoint(addr) {
     if (addr.scheme !== 'tcp') {
         throw new Error(`expected tcp://, got ${addr.scheme}:// (${addr.raw})`);
@@ -122,11 +112,6 @@ export function tcpEndpoint(addr) {
     }
     return `${addr.host}:${addr.port}`;
 }
-/**
- * The DevTools port a browser endpoint means. On `ssh://` the authority port is
- * the SSH port, so the DevTools port comes only from `?port=`; `cdp://` and
- * `ssh://` default to 9222, path-addressed sockets (`wss://`) have none.
- */
 export function browserEndpointPort(addr) {
     const fromQuery = addr.query.port ? Number.parseInt(addr.query.port, 10) : undefined;
     if (fromQuery !== undefined) {

package/dist/lib/agent-cli-commands.d.ts

@@ -1,11 +1 @@
-/**
- * Agent CLI binary names — the `cliCommand` field of each harness in AGENTS.
- *
- * Leaf module with zero imports. brand.ts uses this for reservedBrandNames so
- * the eager index.ts → brand.js graph never pulls agents.ts / versions.ts on
- * every invocation (RUSH-2331). agents.ts AGENTS[*].cliCommand values are
- * pinned equal by agent-cli-commands.test.ts — when a harness is added or
- * renamed, both this list and AGENTS must change together.
- */
-/** Every managed harness CLI binary name (no `agents` / `ag`). */
 export declare const AGENT_CLI_COMMANDS: readonly string[];

package/dist/lib/agent-cli-commands.js

@@ -1,13 +1,3 @@
-/**
- * Agent CLI binary names — the `cliCommand` field of each harness in AGENTS.
- *
- * Leaf module with zero imports. brand.ts uses this for reservedBrandNames so
- * the eager index.ts → brand.js graph never pulls agents.ts / versions.ts on
- * every invocation (RUSH-2331). agents.ts AGENTS[*].cliCommand values are
- * pinned equal by agent-cli-commands.test.ts — when a harness is added or
- * renamed, both this list and AGENTS must change together.
- */
-/** Every managed harness CLI binary name (no `agents` / `ag`). */
 export const AGENT_CLI_COMMANDS = [
     'claude',
     'codex',

package/dist/lib/agent-modes.d.ts

@@ -1,49 +1,20 @@
-/**
- * Permission-mode catalog for a harness.
- *
- * Source of truth is AGENTS[id].capabilities.modes plus the native CLI flags
- * in AGENT_COMMANDS.modeFlags. This is the modes analog of the model catalog
- * (`agents models`) — what a human or orchestrating agent reads before
- * `agents run <agent> --mode …` / `agents teams add … --mode …`.
- */
 import type { AgentId, Mode } from './types.js';
-/** Human description for each canonical permission mode. */
 export declare const MODE_DESCRIPTIONS: Record<Mode, string>;
 export interface AgentModeEntry {
     mode: Mode;
-    /** Native CLI flags agents-cli forwards for this mode (empty = harness default). */
     flags: string[];
     description: string;
-    /** First entry in capabilities.modes — the safest native mode. */
     isDefault: boolean;
 }
 export interface AgentModesCatalog {
     agent: AgentId;
-    /** Modes this harness natively supports, in declaration order. */
     modes: AgentModeEntry[];
-    /** capabilities.modes[0] — safest native mode; run may still default elsewhere (e.g. CLI plan, teams edit). */
     defaultMode: Mode;
-    /**
-     * Configured run.defaults mode for this agent@version, when set.
-     * Null means no pin — CLI default (plan for most harnesses) or modes[0] applies.
-     */
     configuredMode: Mode | null;
     configuredModeSource: string | null;
-    /**
-     * Whether plan works in a headless (`-p` / prompt) run. false means a headless
-     * --mode plan degrades (see resolveHeadlessMode). undefined = assumed true.
-     */
     headlessPlan: boolean;
-    /** Canonical modes this harness does NOT list in capabilities.modes. */
     unsupported: Mode[];
-    /** Notes an orchestrator should read before picking a mode. */
     notes: string[];
 }
-/**
- * Build the permission-mode catalog for one harness.
- * `version` only affects the configured run.defaults lookup (modes themselves
- * are per-agent today, not version-gated).
- */
 export declare function getAgentModesCatalog(agent: AgentId, version?: string | null, cwd?: string): AgentModesCatalog;
-/** Format native flags for display, e.g. `--permission-mode plan` or `(harness default)`. */
 export declare function formatModeFlags(flags: string[]): string;

package/dist/lib/agent-modes.js

@@ -1,46 +1,21 @@
-/**
- * Permission-mode catalog for a harness.
- *
- * Source of truth is AGENTS[id].capabilities.modes plus the native CLI flags
- * in AGENT_COMMANDS.modeFlags. This is the modes analog of the model catalog
- * (`agents models`) — what a human or orchestrating agent reads before
- * `agents run <agent> --mode …` / `agents teams add … --mode …`.
- */
 import { ALL_MODES } from './types.js';
 import { AGENTS } from './agents.js';
 import { AGENT_COMMANDS, defaultModeFor } from './exec.js';
 import { resolveRunDefaults } from './run-defaults.js';
-/** Human description for each canonical permission mode. */
 export const MODE_DESCRIPTIONS = {
     plan: 'read-only investigation; no writes, no shell side-effects',
     edit: 'may edit files; prompts for shell / risky operations',
     auto: 'more autonomy than edit; the exact policy is per-harness (see notes)',
     skip: 'bypass every permission prompt (dangerously-skip-permissions)',
 };
-/**
- * What `auto` actually does, per harness. Two genuinely different mechanisms
- * wear the same mode name, and conflating them is a safety error in both
- * directions: telling a claude operator that auto never prompts invites an
- * unattended run that stalls on a risky-operation gate, and telling a codex
- * operator that auto prompts for risky work asserts a gate codex does not have.
- * Absent entry = no extra note; the row's own text suffices.
- */
 const AUTO_SEMANTICS = {
-    // Classifier-style: still escalates. --permission-mode auto / --autopilot.
     claude: 'a smart classifier auto-approves safe operations and still prompts for risky ones.',
     copilot: 'a smart classifier auto-approves safe operations and still prompts for risky ones.',
-    // Approvals off, sandbox kept: never escalates. A denied command just fails.
     codex: 'approval_policy=never over the same sandbox as edit — it never prompts, and a sandbox-denied command fails instead of raising an approval request.',
     muse: 'runs --disable-approval, which turns approvals off while keeping the sandbox — like codex, it never prompts and a denied command fails.',
-    // Native autonomy dial at its top setting.
     droid: 'runs --auto high, droid\'s full-autonomy setting.',
     kimi: "runs kimi's native --auto.",
 };
-/**
- * Build the permission-mode catalog for one harness.
- * `version` only affects the configured run.defaults lookup (modes themselves
- * are per-agent today, not version-gated).
- */
 export function getAgentModesCatalog(agent, version, cwd = process.cwd()) {
     const supported = AGENTS[agent].capabilities.modes;
     const defaultMode = defaultModeFor(agent);
@@ -61,11 +36,6 @@ export function getAgentModesCatalog(agent, version, cwd = process.cwd()) {
     if (unsupported.includes('auto')) {
         notes.push(`--mode auto degrades to edit on ${agent} (no native auto classifier).`);
     }
-    // MODE_DESCRIPTIONS is one flat Record<Mode, string> rendered for every agent,
-    // so it cannot name any single harness's mechanism without lying about the
-    // others: claude/copilot auto STILL PROMPTS for risky operations, while codex
-    // auto never prompts at all. The row states only what is true everywhere; the
-    // mechanism rides here, per harness.
     const autoSemantics = AUTO_SEMANTICS[agent];
     if (autoSemantics && supported.includes('auto')) {
         notes.push(`${agent} --mode auto: ${autoSemantics}`);
@@ -90,7 +60,6 @@ export function getAgentModesCatalog(agent, version, cwd = process.cwd()) {
         notes,
     };
 }
-/** Format native flags for display, e.g. `--permission-mode plan` or `(harness default)`. */
 export function formatModeFlags(flags) {
     if (flags.length === 0)
         return '(harness default)';