@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/codex-home.js

@@ -36,34 +36,14 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-/** macOS Unix-domain socket path cap: `sizeof(sockaddr_un.sun_path)` in <sys/un.h>. */
 export const SUN_LEN = 104;
-/** Suffix codex appends to CODEX_HOME to reach its app-server control socket. */
 export const CODEX_CONTROL_SOCKET_SUFFIX = '/app-server-control/app-server-control.sock';
-/**
- * True when this CODEX_HOME's derived control-socket path would overflow
- * SUN_LEN on macOS.
- */
 export function codexHomeOverflowsSunLen(home) {
     return home.length + CODEX_CONTROL_SOCKET_SUFFIX.length > SUN_LEN;
 }
-/**
- * The short codex home used when an origin home overflows.
- * `~/.agents/.codex-homes/<key>/.codex` keeps the socket path well under
- * SUN_LEN while staying stable across reboots (unlike $TMPDIR) and isolated
- * per origin.
- */
 export function shortCodexHome(agentsUserDir, key) {
     return path.join(agentsUserDir, '.codex-homes', key, '.codex');
 }
-/**
- * The short-home key for a codex config home: the version for a version home,
- * `a-<accountId prefix>` for an account slot under `<historyDir>/accounts/codex/`.
- * Twelve hex characters keep the socket path under SUN_LEN for any home dir
- * (`~/.agents/.codex-homes/a-XXXXXXXXXXXX/.codex` + suffix = 99 bytes on a
- * `/Users/<user>` prefix); the origin-link check in {@link resolveCodexHome}
- * is what rules out two accounts sharing a prefix.
- */
 export function codexShortKey(home, version, historyDir) {
     const slotsRoot = path.resolve(historyDir, 'accounts', 'codex');
     const resolved = path.resolve(home);
@@ -93,35 +73,8 @@ function isSymlinkOnto(link, target) {
         return false;
     }
 }
-/**
- * Resolve a macOS SUN_LEN-safe CODEX_HOME for the given origin home, migrating
- * the home to a short real path (once, idempotently) when needed. `key` is the
- * short-home key from {@link codexShortKey} — it uniquely identifies the origin
- * (the version for a version home, `a-<accountId>` for a slot), so
- * `.codex-homes/<key>` can only ever be THIS origin's own short home. Two
- * different origins never map to one key, which is what makes every branch
- * below safe without guessing whose login a short home holds.
- *
- * On non-darwin platforms, or when the origin already fits, the origin is
- * returned unchanged. Otherwise the short home is authoritative for `key`, and
- * the origin is made a symlink onto it:
- *  - already linked onto it → return it (healthy, the common path).
- *  - linked onto a DIFFERENT target (a pre-fix layout where a slot's `.codex`
- *    was captured into a foreign version short home) → REPOINT to this key's own
- *    short home and warn; the foreign login is never run. The account may need a
- *    re-login, which is correct — its login was never isolated.
- *  - a real directory with the short home ALREADY present → a version/account
- *    reinstall recreated a fresh `.codex`; adopt the short home (which holds the
- *    real login), backing the fresh dir aside so freshly-synced resources are
- *    not lost. This is the case the earlier refuse-and-throw broke
- *    (`agents remove codex@x && agents add codex@x` then `agents run`).
- *  - a real directory with no short home yet → first migration: rename it into
- *    the short home and leave a symlink.
- *  - absent → create/adopt the short home and link the origin to it.
- * If any filesystem step fails the origin is returned (no worse than the pre-fix
- * behavior).
- */
 export function resolveCodexHome(originHome, agentsUserDir, key, platform = process.platform) {
+    // A short home never adopts a foreign login; repoint symlinks without deleting their targets.
     if (platform !== 'darwin')
         return originHome;
     if (!codexHomeOverflowsSunLen(originHome))
@@ -133,58 +86,35 @@ export function resolveCodexHome(originHome, agentsUserDir, key, platform = proc
     try {
         fs.mkdirSync(path.dirname(short), { recursive: true });
         if (origin?.isSymbolicLink()) {
-            // Mis-linked onto a foreign target (pre-fix bug): never run that identity.
-            // Repoint onto this key's own short home, creating it if absent.
             process.stderr.write(`[codex] ${originHome} was linked to a foreign home; repointing to ${short} `
                 + `(this account may need to log in again).\n`);
             if (!fs.existsSync(short))
                 fs.mkdirSync(short, { recursive: true });
-            fs.rmSync(originHome); // removes the symlink only, never its target
+            fs.rmSync(originHome);
             fs.symlinkSync(short, originHome);
         }
         else if (origin?.isDirectory()) {
             if (fs.existsSync(short)) {
-                // Reinstall: the fresh real `.codex` has re-derivable resources but no
-                // login; the short home holds the real login. Adopt the short home and
-                // set the fresh dir aside (non-destructive) rather than lose either.
                 const superseded = `${originHome}.superseded-${Date.now()}`;
                 fs.renameSync(originHome, superseded);
                 fs.symlinkSync(short, originHome);
             }
             else {
-                // First migration: relocate the deep home so config/auth/state stay
-                // intact, then leave a symlink behind so anything referencing the origin
-                // path still resolves (session discovery, the slot record, the shim).
                 fs.renameSync(originHome, short);
                 fs.symlinkSync(short, originHome);
             }
         }
         else {
-            // Fresh origin: create (or adopt) the short home and link the origin to it.
             fs.mkdirSync(short, { recursive: true });
             fs.mkdirSync(path.dirname(originHome), { recursive: true });
             fs.symlinkSync(short, originHome);
         }
     }
     catch {
-        // A filesystem step lost a race or hit a permission error. Fall back to the
-        // origin rather than crash the invocation.
         return originHome;
     }
     return isSymlinkOnto(originHome, short) ? short : originHome;
 }
-/**
- * Emit the bash block that a generated codex shim uses to export a
- * SUN_LEN-safe CODEX_HOME. Mirrors {@link resolveCodexHome} for the one origin
- * a shim ever sees, the version home: an account-slot launch reaches the shim
- * with CODEX_HOME already pinned by `buildExecEnv`, and the block below keeps a
- * caller-provided CODEX_HOME, so the slot key never has to be derived in bash.
- *
- * @param homeExpr      shell expression for the versioned codex home
- *                      (e.g. `$VERSION_DIR/home/.codex`)
- * @param shortBaseExpr shell expression for the per-version short base dir
- *                      (e.g. `$AGENTS_USER_DIR/.codex-homes/$VERSION`)
- */
 export function codexHomeShimBash(homeExpr, shortBaseExpr) {
     return `
 # Codex reads its config (approval_policy, sandbox_mode, MCP servers, rules)

package/dist/lib/codex-policy.d.ts

@@ -2,14 +2,6 @@ type CodexPolicyMode = 'plan' | 'edit' | 'auto' | 'skip';
 export declare const CODEX_PLAN_PROFILE = "agents-plan";
 export declare const CODEX_EDIT_PROFILE = "agents-edit";
 export declare const CODEX_AUTO_PROFILE = "agents-auto";
-/**
- * Writable roots for Codex's `edit` profile: the managed user `.agents` dir, the
- * baseline toolchain caches, and — when `cwd` is inside a repo — that repo's
- * `.agents` directory. The last entry is what lets an in-repo build write under
- * `.agents/worktrees/`; Codex's `workspace-write` sandbox hardcodes `.agents/`
- * read-only, and naming the directory as an explicit writable root is the only
- * thing that overrides it (a nested sub-path does not — bwrap refuses the mount).
- */
 export declare function codexEditWritableRoots(cwd?: string): string[];
 export declare function codexPermissionProfileConfig(mode: Exclude<CodexPolicyMode, 'skip'>, writableRoots?: string[]): string;
 /**
@@ -29,8 +21,6 @@ export declare function codexPermissionProfileConfig(mode: Exclude<CodexPolicyMo
  * `skip` remains the sole mode that removes it.
  */
 export declare function codexPolicyArgs(mode: CodexPolicyMode, writableRoots?: string[]): string[];
-/** Preserve whether --mode was omitted when a run is re-dispatched remotely. */
 export declare function modeForRemoteDispatch(mode: string, source: string | undefined): string | undefined;
-/** Only the untouched Commander default selects Codex's writable default. */
 export declare function modeWasImplicit(source: string | undefined, hasConfiguredDefault: boolean): boolean;
 export {};

package/dist/lib/codex-policy.js

@@ -8,19 +8,8 @@ export const CODEX_AUTO_PROFILE = 'agents-auto';
 function unique(values) {
     return [...new Set(values)];
 }
-/**
- * Writable roots for Codex's `edit` profile: the managed user `.agents` dir, the
- * baseline toolchain caches, and — when `cwd` is inside a repo — that repo's
- * `.agents` directory. The last entry is what lets an in-repo build write under
- * `.agents/worktrees/`; Codex's `workspace-write` sandbox hardcodes `.agents/`
- * read-only, and naming the directory as an explicit writable root is the only
- * thing that overrides it (a nested sub-path does not — bwrap refuses the mount).
- */
 export function codexEditWritableRoots(cwd) {
     const repoAgents = repoAgentsDirForCwd(cwd);
-    // Only widen the sandbox for a `.agents` that actually exists — most repos
-    // have none, and there is no point naming a directory that isn't there. (Codex
-    // tolerates a missing writable root, so this is tidiness, not a hard guard.)
     const repoRoots = repoAgents && fs.existsSync(repoAgents) ? [repoAgents] : [];
     return unique([getUserAgentsDir(), ...codexDefaultWritableRoots(), ...repoRoots]);
 }
@@ -68,11 +57,9 @@ export function codexPolicyArgs(mode, writableRoots = codexEditWritableRoots())
         `permissions.${profile}=${codexPermissionProfileConfig(mode, writableRoots)}`,
     ];
 }
-/** Preserve whether --mode was omitted when a run is re-dispatched remotely. */
 export function modeForRemoteDispatch(mode, source) {
     return source === 'default' ? undefined : mode;
 }
-/** Only the untouched Commander default selects Codex's writable default. */
 export function modeWasImplicit(source, hasConfiguredDefault) {
     return source === 'default' && !hasConfiguredDefault;
 }

package/dist/lib/command-skills.d.ts

@@ -1,15 +1,5 @@
-/**
- * Convert slash-command markdown files into Codex skills for Codex releases
- * that no longer load the legacy prompts/ directory.
- */
 import type { AgentId } from './types.js';
 export declare function shouldInstallCommandAsSkill(agent: AgentId, version: string): boolean;
-/**
- * Agents whose native command files serve a separate surface while their CLI
- * consumes the generated skill form. Keep this registry distinct from
- * `shouldInstallCommandAsSkill`: these targets need both writes, not a format
- * replacement.
- */
 export declare const COMMAND_SKILL_DUAL_WRITE_TARGETS: {
     cursor: true;
 };

package/dist/lib/command-skills.js

@@ -1,7 +1,3 @@
-/**
- * Convert slash-command markdown files into Codex skills for Codex releases
- * that no longer load the legacy prompts/ directory.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
@@ -52,12 +48,6 @@ function readSkillCommandMarker(skillMdPath) {
 export function shouldInstallCommandAsSkill(agent, version) {
     return !supports(agent, 'commands', version).ok && supports(agent, 'skills', version).ok;
 }
-/**
- * Agents whose native command files serve a separate surface while their CLI
- * consumes the generated skill form. Keep this registry distinct from
- * `shouldInstallCommandAsSkill`: these targets need both writes, not a format
- * replacement.
- */
 export const COMMAND_SKILL_DUAL_WRITE_TARGETS = {
     cursor: true,
 };

package/dist/lib/commands.d.ts

@@ -1,25 +1,11 @@
-/**
- * Slash command management -- discovery, installation, and syncing.
- *
- * Commands are markdown files in ~/.agents/commands/ exposed as `/command-name`
- * shortcuts by agents. This module discovers them, converts between formats
- * (markdown for Claude/Codex, TOML for Gemini), and installs them into
- * agent version homes.
- */
 import type { AgentId, CommandInstallation } from './types.js';
-/** Scope of a command: user-global or project-local. */
 type CommandScope = 'user' | 'project';
-/** Parsed metadata from a command file's YAML frontmatter. */
 interface CommandMetadata {
     name: string;
     description: string;
-    /** When set, sync only to these agents (aliases resolved at parse time). */
     agents?: AgentId[];
-    /** Minimum agent CLI version (inclusive) for this command. */
     since?: string;
-    /** Exclusive upper bound on agent CLI version for this command. */
     until?: string;
-    /** Alternate names this command also resolves under (frontmatter `aliases:`). */
     aliases?: string[];
 }
 type CommandApplyFailReason = 'unsupported' | 'agent_excluded' | 'too_old' | 'too_new';
@@ -30,19 +16,12 @@ type CommandApplyResult = {
     reason: CommandApplyFailReason;
     need?: string;
 };
-/**
- * Whether a slash command should sync to the given agent@version. Checks
- * frontmatter `agents` / `since` / `until` after the agent-level commands
- * (or commands-as-skills) capability gate.
- */
 export declare function commandAppliesTo(agent: AgentId, version: string, metadata: Pick<CommandMetadata, 'agents' | 'since' | 'until'> | null | undefined): CommandApplyResult;
-/** Result of validating command metadata. */
 export interface ValidationResult {
     valid: boolean;
     errors: string[];
     warnings: string[];
 }
-/** A command discovered in a repository's commands/ directory. */
 interface DiscoveredCommand {
     name: string;
     description: string;
@@ -50,32 +29,20 @@ interface DiscoveredCommand {
     isShared: boolean;
     validation: ValidationResult;
 }
-/** A command installed in an agent's config directory. */
 interface InstalledCommand {
     name: string;
     scope: CommandScope;
     path: string;
     description?: string;
 }
-/** Parse command metadata (name, description, targeting) from YAML frontmatter or TOML headers. */
 export declare function parseCommandMetadata(filePath: string): CommandMetadata | null;
-/** Discover all command markdown files in a repository's commands/ directory. */
 export declare function discoverCommands(repoPath: string): DiscoveredCommand[];
-/** Find the source path for a command in a repository. */
 export declare function resolveCommandSource(repoPath: string, commandName: string): string | null;
-/** Install a command into an agent's config directory, with optional format conversion. */
 export declare function installCommand(sourcePath: string, agentId: AgentId, commandName: string, method?: 'symlink' | 'copy'): CommandInstallation & {
     error?: string;
     warnings?: string[];
 };
-/**
- * Path to the commands dir of a specific version home (not the active one).
- * Respects per-agent commandsSubdir (e.g. 'prompts' for codex).
- */
 export declare function getVersionCommandsDir(agent: AgentId, version: string): string;
-/**
- * List command names (without extension) installed in a specific version home.
- */
 export declare function listCommandsInVersionHome(agent: AgentId, version: string): string[];
 export interface VersionCommandDiff {
     agent: AgentId;
@@ -83,46 +50,21 @@ export interface VersionCommandDiff {
     toAdd: string[];
     toUpdate: string[];
     matched: string[];
-    /** Installed but excluded by frontmatter agents/since/until — safe to remove. */
     toRemove: string[];
     orphans: string[];
 }
-/**
- * Compare a version home's commands against central. Returns the reconciliation diff.
- */
-/**
- * Flattened names of plugin-bundled commands (`<plugin>-<command>`), matching
- * exactly how `syncPluginToVersion` installs a plugin's `commands/<cmd>.md` as a
- * command-skill (plugins.ts → `installCommandSkillToVersion(agentDir,
- * `${plugin.name}-${cmd}`, …)`). These are source-managed by their plugin, so
- * the orphan detector must NOT flag them — else `prune cleanup` proposes
- * deleting live plugin commands (swarm-plan, code-review, …). Scans user +
- * system + extra marketplaces (no project layer), matching the trusted sources.
- */
 export declare function listPluginCommandNames(): Set<string>;
 export declare function diffVersionCommands(agent: AgentId, version: string): VersionCommandDiff;
-/**
- * Install a single command from central into a specific version home.
- * Handles markdown-to-TOML conversion when the agent requires it.
- */
 export declare function installCommandToVersion(agent: AgentId, version: string, commandName: string, method?: 'symlink' | 'copy'): {
     success: boolean;
     error?: string;
     skipped?: boolean;
     skipReason?: string;
 };
-/**
- * Remove a single command from a specific version home.
- * Soft-deletes to ~/.agents/.trash/commands/.
- */
 export declare function removeCommandFromVersion(agent: AgentId, version: string, commandName: string): {
     success: boolean;
     error?: string;
 };
-/**
- * Iterate all (agent, version) pairs that support commands and are installed,
- * optionally scoped to a single agent/version.
- */
 export declare function iterCommandsCapableVersions(filter?: {
     agent?: AgentId;
     version?: string;
@@ -130,33 +72,17 @@ export declare function iterCommandsCapableVersions(filter?: {
     agent: AgentId;
     version: string;
 }>;
-/** Remove a command from an agent's config directory. */
 export declare function uninstallCommand(agentId: AgentId, commandName: string): boolean;
-/**
- * List installed commands with scope information.
- * Pass options.home to read from a version-managed agent's home directory.
- */
 export declare function listInstalledCommandsWithScope(agentId: AgentId, cwd?: string, options?: {
     home?: string;
 }): InstalledCommand[];
-/**
- * Install a command to central ~/.agents/commands/ directory.
- * Shims will symlink this to per-agent directories for synced agents.
- */
 export declare function installCommandCentrally(sourcePath: string, commandName: string): {
     success: boolean;
     path: string;
     error?: string;
     warnings?: string[];
 };
-/**
- * List commands from user (~/.agents/commands/) and system (~/.agents/.system/commands/) dirs.
- * User dir takes priority; deduplication preserves first occurrence.
- */
 export declare function listCentralCommands(): string[];
-/**
- * Get detailed info about a command from central storage.
- */
 export declare function getCommandInfo(name: string): {
     name: string;
     description: string;