@phnx-labs/agents-cli 1.20.11 → 1.20.13

package/dist/lib/settings-manifest.js

@@ -0,0 +1,163 @@
+/**
+ * Settings carry-forward between version homes.
+ *
+ * Every installed version gets an isolated `home/`, so user-authored
+ * preferences (settings.json, config.toml, keybindings, auth) written while
+ * running one version do not exist in a freshly installed one. Resources
+ * managed in ~/.agents/ (commands, skills, hooks, rules, MCP YAML, plugins,
+ * subagents) are synced into every version home by syncResourcesToVersion and
+ * are deliberately NOT listed here — copying them would fight that sync.
+ *
+ * The manifest below classifies the remaining per-agent files, and
+ * carryForwardSettings() fills gaps in a target version home from a source
+ * version home. It never overwrites a value the target already has: scalars
+ * keep the target's value, objects merge recursively, arrays union. That makes
+ * the operation idempotent and safe to run on every `agents add` / `agents use`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as TOML from 'smol-toml';
+import { getBackupsDir } from './state.js';
+const SETTINGS_MANIFEST = {
+    claude: [
+        { rel: '.claude/settings.json', strategy: 'json-merge' },
+        { rel: '.claude/settings.local.json', strategy: 'copy-if-absent' },
+        { rel: '.claude/keybindings.json', strategy: 'copy-if-absent' },
+    ],
+    codex: [
+        {
+            rel: '.codex/config.toml',
+            strategy: 'toml-merge',
+            stateKeys: ['notice', 'windows_wsl_setup_acknowledged'],
+        },
+        { rel: '.codex/auth.json', strategy: 'copy-if-absent', restrictMode: true },
+        { rel: '.codex/instructions.md', strategy: 'copy-if-absent' },
+        { rel: '.codex/hooks.json', strategy: 'copy-if-absent' },
+        { rel: '.codex/prompts', strategy: 'dir-entries' },
+        { rel: '.codex/rules', strategy: 'dir-entries' },
+    ],
+};
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Fill gaps in `target` from `source` without overwriting target values:
+ * missing keys are copied, plain objects recurse, and everything else —
+ * scalars AND arrays — keeps the target's value. Arrays deliberately do not
+ * union: other writers (factory sync, hooks registration) mutate array entries
+ * in place, so a union would keep re-appending stale pre-mutation copies from
+ * the source on every carry (e.g. a user hook duplicated after the system
+ * hooks were merged into it). Returns a new object.
+ */
+export function fillGaps(target, source) {
+    const out = { ...target };
+    for (const [key, sourceValue] of Object.entries(source)) {
+        if (!(key in out)) {
+            out[key] = sourceValue;
+            continue;
+        }
+        const targetValue = out[key];
+        if (isPlainObject(targetValue) && isPlainObject(sourceValue)) {
+            out[key] = fillGaps(targetValue, sourceValue);
+        }
+        // scalar, array, or type mismatch: target wins
+    }
+    return out;
+}
+function stripStateKeys(obj, stateKeys) {
+    if (!stateKeys?.length)
+        return obj;
+    const out = { ...obj };
+    for (const key of stateKeys)
+        delete out[key];
+    return out;
+}
+function backupFile(backupRoot, home, rel) {
+    const src = path.join(home, rel);
+    const dest = path.join(backupRoot, rel);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+}
+/**
+ * Carry user settings forward from one version home into another. Both paths
+ * are version-home roots (the directory containing `.claude/` / `.codex/`).
+ * Only fills gaps — never overwrites target values — so it is idempotent.
+ */
+export function carryForwardSettings(agent, fromHome, toHome) {
+    const manifest = SETTINGS_MANIFEST[agent];
+    const result = { applied: [] };
+    if (!manifest || !fs.existsSync(fromHome) || fromHome === toHome)
+        return result;
+    const backupRoot = path.join(getBackupsDir(), 'settings-carry', agent, new Date().toISOString().replace(/[:.]/g, '-'));
+    for (const entry of manifest) {
+        const sourcePath = path.join(fromHome, entry.rel);
+        const targetPath = path.join(toHome, entry.rel);
+        if (!fs.existsSync(sourcePath))
+            continue;
+        try {
+            switch (entry.strategy) {
+                case 'copy-if-absent': {
+                    if (fs.existsSync(targetPath))
+                        break;
+                    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+                    fs.copyFileSync(sourcePath, targetPath);
+                    if (entry.restrictMode)
+                        fs.chmodSync(targetPath, 0o600);
+                    result.applied.push(entry.rel);
+                    break;
+                }
+                case 'dir-entries': {
+                    if (!fs.statSync(sourcePath).isDirectory())
+                        break;
+                    let copied = false;
+                    fs.mkdirSync(targetPath, { recursive: true });
+                    for (const name of fs.readdirSync(sourcePath)) {
+                        const childTarget = path.join(targetPath, name);
+                        if (fs.existsSync(childTarget))
+                            continue;
+                        fs.cpSync(path.join(sourcePath, name), childTarget, { recursive: true });
+                        copied = true;
+                    }
+                    if (copied)
+                        result.applied.push(entry.rel);
+                    break;
+                }
+                case 'json-merge':
+                case 'toml-merge': {
+                    const parse = entry.strategy === 'json-merge'
+                        ? (text) => JSON.parse(text)
+                        : (text) => TOML.parse(text);
+                    const stringify = entry.strategy === 'json-merge'
+                        ? (obj) => JSON.stringify(obj, null, 2) + '\n'
+                        : (obj) => TOML.stringify(obj) + '\n';
+                    const source = stripStateKeys(parse(fs.readFileSync(sourcePath, 'utf-8')), entry.stateKeys);
+                    if (!fs.existsSync(targetPath)) {
+                        if (Object.keys(source).length === 0)
+                            break;
+                        fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+                        fs.writeFileSync(targetPath, stringify(source), 'utf-8');
+                        result.applied.push(entry.rel);
+                        break;
+                    }
+                    const targetText = fs.readFileSync(targetPath, 'utf-8');
+                    const targetObj = parse(targetText);
+                    const merged = fillGaps(targetObj, source);
+                    // Compare parsed content, not text: other writers format differently,
+                    // and a semantic no-op must not trigger a rewrite/backup every switch.
+                    if (JSON.stringify(merged) === JSON.stringify(targetObj))
+                        break;
+                    backupFile(backupRoot, toHome, entry.rel);
+                    result.backupDir = backupRoot;
+                    fs.writeFileSync(targetPath, stringify(merged), 'utf-8');
+                    result.applied.push(entry.rel);
+                    break;
+                }
+            }
+        }
+        catch {
+            // A malformed source or target file must not break install/use.
+            // Leave the target untouched for this entry and move on.
+        }
+    }
+    return result;
+}

package/dist/lib/shims.d.ts

@@ -77,7 +77,7 @@ export interface ConflictInfo {
  *         top-level entry add/remove — deep edits to plugin contents won't
  *         trigger auto-resync, run `agents sync` for that.
  */
-export declare const SHIM_SCHEMA_VERSION = 17;
+export declare const SHIM_SCHEMA_VERSION = 18;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.

package/dist/lib/shims.js

@@ -11,10 +11,9 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { execFileSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { confirm, select } from '@inquirer/prompts';
-import { IS_WINDOWS } from './platform/index.js';
+import { IS_WINDOWS, prependToWindowsUserPath } from './platform/index.js';
 import { getShimsDir, getVersionsDir, getBackupsDir, ensureAgentsDir } from './state.js';
 export { getShimsDir };
 import { AGENTS } from './agents.js';
@@ -203,7 +202,7 @@ async function promptConflictStrategy(conflictInfos) {
  *         top-level entry add/remove — deep edits to plugin contents won't
  *         trigger auto-resync, run `agents sync` for that.
  */
-export const SHIM_SCHEMA_VERSION = 17;
+export const SHIM_SCHEMA_VERSION = 18;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 function shellQuote(value) {
@@ -273,7 +272,7 @@ export KIMI_CODE_HOME="$VERSION_DIR/home/${configDirName}"
 # Shim for ${agentConfig.name}
 # ${SHIM_VERSION_MARKER} ${SHIM_SCHEMA_VERSION}
 
-AGENTS_USER_DIR="$HOME/.agents"
+AGENTS_USER_DIR="\${AGENTS_USER_DIR:-$HOME/.agents}"
 AGENTS_BIN=${agentsBin}
 AGENT="${agent}"
 CLI_COMMAND="${cliCommand}"
@@ -1579,36 +1578,22 @@ export function addShimsToPath(overrides) {
  * Register the shims dir on the Windows User PATH via the .NET environment API,
  * which writes the registry AND broadcasts WM_SETTINGCHANGE — the correct analog
  * of editing a shell rc file (no `setx` truncation, no manual step). Idempotent:
- * a no-op when the dir is already present. The shims dir is passed via an env var
- * so it is never interpolated into the PowerShell script text.
+ * a no-op when the shims dir is already first in the User PATH. Moves it to the
+ * front when it exists but is in the wrong position (e.g. appended by an old
+ * install) so it overrides any npm/global installs that appear later. The shims
+ * dir is passed via an env var so it is never interpolated into the script text.
  */
 function addShimsToWindowsUserPath(shimsDir) {
-    const script = [
-        '$d = $env:AGENTS_SHIMS_DIR',
-        "$u = [Environment]::GetEnvironmentVariable('Path','User')",
-        "if ($null -eq $u) { $u = '' }",
-        "$parts = @($u -split ';' | Where-Object { $_ -ne '' })",
-        "if ($parts -contains $d) { 'present' } else {",
-        "  [Environment]::SetEnvironmentVariable('Path', (($parts + $d) -join ';'), 'User')",
-        "  'added'",
-        '}',
-    ].join('\n');
-    try {
-        const out = execFileSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], {
-            encoding: 'utf-8',
-            env: { ...process.env, AGENTS_SHIMS_DIR: shimsDir },
-            stdio: ['ignore', 'pipe', 'pipe'],
-        }).trim();
-        return {
-            success: true,
-            alreadyPresent: out.includes('present'),
-            location: 'your user PATH',
-            reloadHint: 'Open a new terminal for the change to take effect.',
-        };
-    }
-    catch (err) {
-        return { success: false, error: `Could not update the Windows user PATH: ${err.message}` };
+    const r = prependToWindowsUserPath(shimsDir);
+    if (!r.success) {
+        return { success: false, error: r.error };
     }
+    return {
+        success: true,
+        alreadyPresent: r.alreadyPresent,
+        location: 'your user PATH',
+        reloadHint: 'Open a new terminal for the change to take effect.',
+    };
 }
 export function listAgentsWithInstalledVersions() {
     const versionsDir = getVersionsDir();

package/dist/lib/staleness/detectors/subagents.js

@@ -1,5 +1,6 @@
 /**
  * Subagents detector. Claude: flat .md files under `<agentDir>/agents/`.
+ * Droid: flat .md files under `<versionHome>/.factory/droids/`.
  * OpenClaw: subdirectories containing AGENTS.md under `<versionHome>/.openclaw/`.
  * Mirrors versions.ts:521-539.
  */
@@ -21,6 +22,20 @@ function buildClaudeDetector() {
         },
     };
 }
+function buildDroidDetector() {
+    return {
+        kind: 'subagents',
+        agent: 'droid',
+        list({ versionHome }) {
+            const droidsDir = path.join(versionHome, '.factory', 'droids');
+            if (!fs.existsSync(droidsDir))
+                return [];
+            return fs.readdirSync(droidsDir)
+                .filter(f => f.endsWith('.md'))
+                .map(f => f.replace('.md', ''));
+        },
+    };
+}
 function buildOpenclawDetector() {
     return {
         kind: 'subagents',
@@ -37,6 +52,7 @@ function buildOpenclawDetector() {
 }
 const handlers = {
     claude: buildClaudeDetector,
+    droid: buildDroidDetector,
     openclaw: buildOpenclawDetector,
 };
 export const subagentsDetectors = lazyAgentMap(() => {

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

@@ -1,7 +1,9 @@
 /**
  * Subagents writer. Claude flattens each subagent into a single .md file
- * under `<agentDir>/agents/`. OpenClaw copies the full subagent directory
- * (with AGENT.md renamed to AGENTS.md) into `<versionHome>/.openclaw/<name>/`.
+ * under `<agentDir>/agents/`. Droid (Factory AI) flattens each into a custom
+ * droid .md under `<versionHome>/.factory/droids/`. OpenClaw copies the full
+ * subagent directory (with AGENT.md renamed to AGENTS.md) into
+ * `<versionHome>/.openclaw/<name>/`.
  *
  * Source-side discovery is `listInstalledSubagents` from lib/subagents.ts —
  * it reads user + system layers only (project layer excluded for the same
@@ -10,7 +12,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { capableAgents } from '../../capabilities.js';
-import { listInstalledSubagents, transformSubagentForClaude, syncSubagentToOpenclaw } from '../../subagents.js';
+import { listInstalledSubagents, transformSubagentForClaude, transformSubagentForDroid, syncSubagentToOpenclaw } from '../../subagents.js';
 import { safeJoin } from '../../paths.js';
 import { lazyAgentMap } from './lazy-map.js';
 function buildSubagentsWriter(agent) {
@@ -32,6 +34,12 @@ function buildSubagentsWriter(agent) {
                         fs.writeFileSync(safeJoin(agentsDir, `${sub.name}.md`), transformSubagentForClaude(sub.path));
                         synced.push(sub.name);
                     }
+                    else if (agent === 'droid') {
+                        const droidsDir = path.join(versionHome, '.factory', 'droids');
+                        fs.mkdirSync(droidsDir, { recursive: true });
+                        fs.writeFileSync(safeJoin(droidsDir, `${sub.name}.md`), transformSubagentForDroid(sub.path));
+                        synced.push(sub.name);
+                    }
                     else if (agent === 'openclaw') {
                         const target = safeJoin(path.join(versionHome, '.openclaw'), sub.name);
                         const r = syncSubagentToOpenclaw(sub.path, target);

package/dist/lib/subagents.d.ts

@@ -47,6 +47,15 @@ export declare function removeSubagent(name: string): {
  * Combines AGENT.md frontmatter + body with other files as sections
  */
 export declare function transformSubagentForClaude(subagentDir: string): string;
+/**
+ * Transform a subagent into a Factory AI Droid "custom droid" .md file.
+ *
+ * Mirrors transformSubagentForClaude (flatten frontmatter + body + appended
+ * .md sections), but emits only frontmatter keys Factory recognizes
+ * (name, description, model). Factory has no `color` field, so it is dropped.
+ * See https://docs.factory.ai/cli/configuration/custom-droids.
+ */
+export declare function transformSubagentForDroid(subagentDir: string): string;
 /**
  * Sync a subagent to an OpenClaw workspace
  * Copies full directory, renames AGENT.md to AGENTS.md

package/dist/lib/subagents.js

@@ -229,6 +229,39 @@ export function transformSubagentForClaude(subagentDir) {
     }
     return result;
 }
+/**
+ * Transform a subagent into a Factory AI Droid "custom droid" .md file.
+ *
+ * Mirrors transformSubagentForClaude (flatten frontmatter + body + appended
+ * .md sections), but emits only frontmatter keys Factory recognizes
+ * (name, description, model). Factory has no `color` field, so it is dropped.
+ * See https://docs.factory.ai/cli/configuration/custom-droids.
+ */
+export function transformSubagentForDroid(subagentDir) {
+    const agentMd = path.join(subagentDir, 'AGENT.md');
+    const frontmatter = parseSubagentFrontmatter(agentMd);
+    const body = getSubagentBody(agentMd);
+    if (!frontmatter) {
+        throw new Error(`Invalid AGENT.md in ${subagentDir}`);
+    }
+    const frontmatterYaml = yaml.stringify({
+        name: frontmatter.name,
+        description: frontmatter.description,
+        ...(frontmatter.model && { model: frontmatter.model }),
+    }).trim();
+    let result = `---\n${frontmatterYaml}\n---\n\n${body}`;
+    const files = fs.readdirSync(subagentDir)
+        .filter(f => f.endsWith('.md') && f !== 'AGENT.md')
+        .sort();
+    for (const file of files) {
+        const filePath = path.join(subagentDir, file);
+        const content = fs.readFileSync(filePath, 'utf-8').trim();
+        const sectionName = file.replace('.md', '');
+        const title = sectionName.charAt(0).toUpperCase() + sectionName.slice(1).toLowerCase();
+        result += `\n\n## ${title}\n\n${content}`;
+    }
+    return result;
+}
 /**
  * Sync a subagent to an OpenClaw workspace
  * Copies full directory, renames AGENT.md to AGENTS.md

package/dist/lib/teams/agents.js

@@ -173,7 +173,7 @@ export function captureProcessStartTime(pid) {
     }
 }
 /** Agent types the team runner supports. */
-const TEAM_AGENT_TYPES = ['codex', 'cursor', 'gemini', 'claude', 'opencode', 'grok', 'antigravity', 'kimi'];
+const TEAM_AGENT_TYPES = ['codex', 'cursor', 'gemini', 'claude', 'opencode', 'grok', 'antigravity', 'kimi', 'droid'];
 // Suffix appended to all prompts to ensure agents provide a summary
 const PROMPT_SUFFIX = `
 

package/dist/lib/teams/parsers.d.ts

@@ -1,5 +1,5 @@
 /** Supported agent CLI types for team spawning. */
-export type AgentType = 'codex' | 'gemini' | 'cursor' | 'claude' | 'opencode' | 'grok' | 'antigravity' | 'kimi';
+export type AgentType = 'codex' | 'gemini' | 'cursor' | 'claude' | 'opencode' | 'grok' | 'antigravity' | 'kimi' | 'droid';
 /** Normalize a raw JSON event from any agent type into an array of unified event objects. */
 export declare function normalizeEvents(agentType: AgentType, raw: any): any[];
 /** Normalize a raw JSON event, returning only the first unified event (convenience wrapper). */

package/dist/lib/teams/parsers.js

@@ -31,6 +31,12 @@ export function normalizeEvents(agentType, raw) {
     else if (agentType === 'antigravity') {
         return normalizeAntigravity(raw);
     }
+    // droid (Factory AI) intentionally falls through to the generic normalizer
+    // below: its `-o stream-json` JSONL event schema is not yet verified against
+    // a live run (the documented `debug` format differs from stream-json). Events
+    // still stream and render; structured tool/file categorization will be added
+    // once a real `droid exec -o stream-json` sample is captured. Do NOT guess the
+    // schema here — a wrong discriminator silently mislabels every event.
     const timestamp = new Date().toISOString();
     return [{
             type: raw.type || 'unknown',

package/dist/lib/types.d.ts

@@ -6,7 +6,7 @@
  * formats for each supported agent.
  */
 /** Unique identifier for a supported AI coding agent. */
-export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'roo' | 'antigravity' | 'grok' | 'kimi';
+export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'roo' | 'antigravity' | 'grok' | 'kimi' | 'droid';
 /** How `agents run <agent>` chooses an installed version when none is pinned. */
 export type RunStrategy = 'pinned' | 'available' | 'balanced';
 /** Per-agent run strategy config. */

package/dist/lib/versions.d.ts

@@ -126,6 +126,10 @@ export declare function isVersionInstalled(agent: AgentId, version: string): boo
  * Get the latest available version from npm for an agent.
  */
 export declare function getLatestNpmVersion(agent: AgentId): Promise<string | null>;
+/**
+ * Get the oldest published version from npm for an agent.
+ */
+export declare function getOldestNpmVersion(agent: AgentId): Promise<string | null>;
 /**
  * Check if 'latest' version is already installed (by resolving to actual version).
  */
@@ -133,6 +137,13 @@ export declare function isLatestInstalled(agent: AgentId): Promise<{
     installed: boolean;
     version: string | null;
 }>;
+/**
+ * Check if 'oldest' published version is already installed (by resolving to actual version).
+ */
+export declare function isOldestInstalled(agent: AgentId): Promise<{
+    installed: boolean;
+    version: string | null;
+}>;
 /**
  * List all installed versions for an agent.
  */
@@ -210,6 +221,7 @@ export declare function resolveVersion(agent: AgentId, projectPath?: string): st
  *
  *   undefined / "" / "default"  -> undefined  (caller falls back to project pin or global default)
  *   "latest"                    -> highest installed version (process.exit if none installed)
+ *   "oldest"                    -> lowest installed version (process.exit if none installed)
  *   "x.y.z" (installed)         -> "x.y.z"
  *   "x.y.z" (not installed)     -> process.exit with installed-list hint
  *
@@ -221,9 +233,9 @@ export declare function resolveVersion(agent: AgentId, projectPath?: string): st
 export declare function resolveVersionAlias(agent: AgentId, raw: string | undefined | null): string | undefined;
 /**
  * Loose variant of resolveVersionAlias for record-filter contexts (sessions,
- * team history). Same `default`/`latest` semantics, but explicit versions
- * pass through unchanged so historical records of uninstalled versions remain
- * queryable.
+ * team history). Same `default`/`latest`/`oldest` semantics, but explicit
+ * versions pass through unchanged so historical records of uninstalled versions
+ * remain queryable.
  */
 export declare function resolveVersionAliasLoose(agent: AgentId, raw: string | undefined | null): string | undefined;
 /**