@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/dist/lib/models.js

@@ -1,9 +1,18 @@
+/**
+ * Model catalog extraction, caching, and resolution for all supported agents.
+ *
+ * Each agent ships its model list differently -- Claude and Codex embed it in
+ * compiled bundles/binaries, Gemini exports it from a JS module, and OpenCode/
+ * Cursor/OpenClaw expose it via CLI commands. This module provides a unified
+ * `getModelCatalog()` and `resolveModel()` interface over all of them, backed
+ * by a file-system cache keyed on source mtime.
+ */
 import * as fs from 'fs';
 import * as path from 'path';
-import * as os from 'os';
 import { execFileSync } from 'child_process';
 import { getVersionDir } from './versions.js';
-const CACHE_PATH = path.join(os.homedir(), '.agents', '.models-cache.json');
+import { getAgentsDir } from './state.js';
+const CACHE_PATH = path.join(getAgentsDir(), '.models-cache.json');
 /**
  * Bump when the extractor logic changes shape in an incompatible way so cached
  * catalogs from older agents-cli builds are re-extracted.
@@ -13,6 +22,7 @@ let memoryCache = null;
 function cacheKey(agent, version) {
     return `${agent}@${version}`;
 }
+/** Load the cache file from disk (or return the in-memory copy). */
 function loadCache() {
     if (memoryCache)
         return memoryCache;
@@ -22,7 +32,7 @@ function loadCache() {
             memoryCache = raw;
         }
         else {
-            // Legacy (pre-schema) or stale-schema cache — drop it.
+            // Legacy (pre-schema) or stale-schema cache -- drop it.
             memoryCache = { schema: CACHE_SCHEMA_VERSION, entries: {} };
         }
     }
@@ -31,6 +41,7 @@ function loadCache() {
     }
     return memoryCache;
 }
+/** Persist the in-memory cache to disk. Best-effort; failures are silent. */
 function saveCache() {
     if (!memoryCache)
         return;
@@ -48,9 +59,9 @@ function saveCache() {
  * Locate the file that authoritatively describes the installed model catalog
  * for a given (agent, version). The `kind` tells `getModelCatalog` how to
  * read it:
- *   bundle/binary — strings(1)-style extraction (claude/codex)
- *   js            — read + regex-parse an exported JS module (gemini)
- *   cli           — spawn the agent's own `models` command (opencode/cursor/openclaw)
+ *   bundle/binary -- strings(1)-style extraction (claude/codex)
+ *   js            -- read + regex-parse an exported JS module (gemini)
+ *   cli           -- spawn the agent's own `models` command (opencode/cursor/openclaw)
  *
  * Returns null if nothing usable is found.
  */
@@ -83,7 +94,7 @@ export function locateModelSource(agent, version) {
         return null;
     }
     if (agent === 'gemini') {
-        // Gemini ships a clean ES module with all constants and aliases — no need
+        // Gemini ships a clean ES module with all constants and aliases -- no need
         // to parse the minified CLI bundle.
         const modelsJs = path.join(versionDir, 'node_modules', '@google', 'gemini-cli-core', 'dist', 'src', 'config', 'models.js');
         if (fs.existsSync(modelsJs))
@@ -111,7 +122,7 @@ export function locateModelSource(agent, version) {
     }
     if (agent === 'cursor') {
         // cursor-agent is installed via curl script, not agents-cli. Version argument
-        // is accepted for API symmetry but ignored — cursor lives on PATH.
+        // is accepted for API symmetry but ignored -- cursor lives on PATH.
         const pathBin = findOnPath('cursor-agent');
         if (pathBin)
             return { path: pathBin, kind: 'cli' };
@@ -119,6 +130,7 @@ export function locateModelSource(agent, version) {
     }
     return null;
 }
+/** Search PATH for a command and return its absolute path, or null. */
 function findOnPath(command) {
     const pathEnv = process.env.PATH || '';
     const exts = process.platform === 'win32' ? (process.env.PATHEXT || '').split(';') : [''];
@@ -138,6 +150,7 @@ function findOnPath(command) {
     }
     return null;
 }
+/** Map the current Node.js platform/arch pair to a Rust-style target triple. */
 function currentTargetTriple() {
     switch (`${process.platform}-${process.arch}`) {
         case 'darwin-arm64': return 'aarch64-apple-darwin';
@@ -300,7 +313,7 @@ function extractGeminiCatalog(text) {
                 validIds.add(id);
         }
     }
-    // Fall back to any gemini-shaped id we saw in the constants map — useful
+    // Fall back to any gemini-shaped id we saw in the constants map -- useful
     // when the Set shape changes across gemini versions.
     if (validIds.size === 0) {
         for (const [name, value] of constants) {
@@ -336,7 +349,7 @@ function extractGeminiCatalog(text) {
         defaults.add(previewPro); // auto/pro alias resolves here
     const displayNameFor = (id) => {
         // Gemini has a `getDisplayString` for some aliases but the canonical id
-        // is human-readable enough ("gemini-3-pro-preview") — no separate map.
+        // is human-readable enough ("gemini-3-pro-preview") -- no separate map.
         return undefined;
     };
     const models = Array.from(validIds)
@@ -351,7 +364,7 @@ function extractGeminiCatalog(text) {
 }
 /**
  * Extract OpenCode's catalog by invoking `opencode models --verbose`. The
- * output is a sequence of `<provider>/<id>\n{json}` blocks — we parse every
+ * output is a sequence of `<provider>/<id>\n{json}` blocks -- we parse every
  * JSON block that follows a provider/id line.
  *
  * OpenCode caches the models.dev snapshot internally, so this is a local,
@@ -418,7 +431,7 @@ function extractOpenCodeCatalog(binaryPath) {
             if (seen.has(fullKey))
                 continue;
             seen.add(fullKey);
-            // obj.status can be "active" | "deprecated" | "preview" — surface only
+            // obj.status can be "active" | "deprecated" | "preview" -- surface only
             // when it isn't the default so the consumer can flag stale models.
             const nonDefaultStatus = obj.status && obj.status !== 'active' ? obj.status : undefined;
             models.push({
@@ -601,8 +614,14 @@ export function getModelCatalog(agent, version) {
         models,
         aliases,
     };
-    cache.entries[key] = { sourcePath: src.path, mtime, catalog };
-    saveCache();
+    // Don't cache empty CLI extractions: the CLI may have been mid-install,
+    // network-dependent, or transiently failing. Caching 0 models would mask
+    // the real catalog forever (mtime won't change). Bundle/binary/js sources
+    // are deterministic, so cache those even when empty.
+    if (src.kind !== 'cli' || models.length > 0) {
+        cache.entries[key] = { sourcePath: src.path, mtime, catalog };
+        saveCache();
+    }
     return catalog;
 }
 /**
@@ -642,6 +661,7 @@ export function resolveModel(agent, version, requested) {
         warning: `model "${requested}" not in known catalog for ${agent}@${version}; forwarding as-is${hint}`,
     };
 }
+/** Find the closest matching model ids/aliases using edit distance. */
 function pickSuggestions(requested, catalog) {
     const all = [...catalog.models.map((m) => m.id), ...Object.keys(catalog.aliases)];
     return all
@@ -651,6 +671,7 @@ function pickSuggestions(requested, catalog) {
         .slice(0, 3)
         .map((s) => s.id);
 }
+/** Normalized Levenshtein similarity (0..1, where 1 is identical). */
 function similarity(a, b) {
     const longer = a.length >= b.length ? a : b;
     const shorter = a.length >= b.length ? b : a;
@@ -659,6 +680,7 @@ function similarity(a, b) {
     const distance = levenshtein(longer, shorter);
     return (longer.length - distance) / longer.length;
 }
+/** Standard Levenshtein edit distance between two strings. */
 function levenshtein(a, b) {
     const m = a.length;
     const n = b.length;
@@ -703,4 +725,3 @@ export function buildReasoningFlags(agent, level) {
     }
     return [];
 }
-//# sourceMappingURL=models.js.map

package/dist/lib/onepassword.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 1Password CLI (op) integration for importing secrets from vaults.
+ */
+export interface OpVault {
+    id: string;
+    name: string;
+}
+export interface OpItemSummary {
+    id: string;
+    title: string;
+    category: string;
+    vault: {
+        id: string;
+        name: string;
+    };
+}
+export interface OpField {
+    id: string;
+    label: string;
+    type: string;
+    value?: string;
+    purpose?: string;
+}
+export interface OpItem extends OpItemSummary {
+    fields: OpField[];
+}
+export interface ImportableSecret {
+    envKey: string;
+    itemTitle: string;
+    fieldLabel: string;
+    value: string;
+}
+export interface SkippedField {
+    itemTitle: string;
+    fieldLabel: string;
+    reason: string;
+}
+export declare function assertOpAvailable(): void;
+export declare function listVaults(): OpVault[];
+export declare function listItems(vaultName: string): OpItemSummary[];
+export declare function getItem(itemId: string, vaultName: string): OpItem;
+export declare function toEnvKey(title: string): string;
+export declare function slugify(name: string): string;
+export declare function extractSecrets(items: OpItemSummary[], vaultName: string): {
+    secrets: ImportableSecret[];
+    skipped: SkippedField[];
+};
+export interface PasswordItemTemplate {
+    title: string;
+    category: 'PASSWORD';
+    tags: string[];
+    fields: Array<{
+        id: string;
+        type: 'CONCEALED';
+        purpose: 'PASSWORD';
+        label: string;
+        value: string;
+    }>;
+}
+export declare function buildPasswordItemTemplate(title: string, value: string): PasswordItemTemplate;
+export declare function itemExistsByTitle(title: string, vaultName: string): boolean;
+export declare function deleteItemByTitle(title: string, vaultName: string): void;
+export declare function createPasswordItem(title: string, value: string, vaultName: string): void;

package/dist/lib/onepassword.js

@@ -0,0 +1,186 @@
+/**
+ * 1Password CLI (op) integration for importing secrets from vaults.
+ */
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+function runOp(args, input) {
+    const result = spawnSync('op', args, {
+        stdio: [input !== undefined ? 'pipe' : 'ignore', 'pipe', 'pipe'],
+        encoding: 'utf-8',
+        maxBuffer: 10 * 1024 * 1024,
+        input,
+    });
+    if (result.error) {
+        if (result.error.code === 'ENOENT') {
+            return { ok: false, error: '1Password CLI not found. Install: brew install 1password-cli' };
+        }
+        return { ok: false, error: result.error.message };
+    }
+    if (result.status !== 0) {
+        const stderr = result.stderr?.trim() || '';
+        if (stderr.includes('not signed in') || stderr.includes('sign in') || stderr.includes('no active session')) {
+            return { ok: false, error: 'Not signed in to 1Password. Run: op signin' };
+        }
+        return { ok: false, error: stderr || `op exited with code ${result.status}` };
+    }
+    return { ok: true, stdout: result.stdout };
+}
+export function assertOpAvailable() {
+    // `op account list` works with both CLI session tokens and the 1Password
+    // desktop biometric integration; `op whoami` fails on the latter.
+    const result = runOp(['account', 'list', '--format=json']);
+    if (!result.ok) {
+        throw new Error(result.error);
+    }
+}
+export function listVaults() {
+    const result = runOp(['vault', 'list', '--format=json']);
+    if (!result.ok)
+        throw new Error(result.error);
+    return JSON.parse(result.stdout);
+}
+export function listItems(vaultName) {
+    const result = runOp(['item', 'list', '--vault', vaultName, '--format=json']);
+    if (!result.ok) {
+        if (result.error.includes('vault') && result.error.includes('not found')) {
+            const vaults = listVaults();
+            const available = vaults.map((v) => v.name).join(', ');
+            throw new Error(`Vault '${vaultName}' not found. Available: ${available || '(none)'}`);
+        }
+        throw new Error(result.error);
+    }
+    const items = JSON.parse(result.stdout);
+    return items || [];
+}
+export function getItem(itemId, vaultName) {
+    const result = runOp(['item', 'get', itemId, '--vault', vaultName, '--format=json', '--reveal']);
+    if (!result.ok)
+        throw new Error(result.error);
+    return JSON.parse(result.stdout);
+}
+export function toEnvKey(title) {
+    return title
+        .toUpperCase()
+        .replace(/[^A-Z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .replace(/^(\d)/, '_$1');
+}
+export function slugify(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+const IMPORTABLE_FIELD_TYPES = new Set([
+    'CONCEALED', 'concealed',
+    'STRING', 'string', 'text', 'TEXT',
+    'URL', 'url',
+]);
+const SKIP_FIELD_LABELS = new Set(['username', 'notesPlain', 'notes']);
+function pickBestField(fields) {
+    const dominated = fields.filter((f) => IMPORTABLE_FIELD_TYPES.has(f.type) &&
+        f.value &&
+        !SKIP_FIELD_LABELS.has(f.label?.toLowerCase() || ''));
+    if (dominated.length === 0)
+        return null;
+    // Prefer concealed fields (credentials/passwords)
+    const concealed = dominated.find((f) => f.type.toLowerCase() === 'concealed');
+    if (concealed)
+        return concealed;
+    // Then prefer fields labeled credential/password/secret/key/token
+    const secretLabels = ['credential', 'password', 'secret', 'key', 'token', 'api_key', 'apikey'];
+    const labeled = dominated.find((f) => secretLabels.includes(f.label?.toLowerCase() || ''));
+    if (labeled)
+        return labeled;
+    // Fall back to first importable field
+    return dominated[0];
+}
+export function extractSecrets(items, vaultName) {
+    const secrets = [];
+    const skipped = [];
+    for (const summary of items) {
+        let item;
+        try {
+            item = getItem(summary.id, vaultName);
+        }
+        catch (err) {
+            skipped.push({
+                itemTitle: summary.title,
+                fieldLabel: '*',
+                reason: err.message,
+            });
+            continue;
+        }
+        const field = pickBestField(item.fields || []);
+        if (!field) {
+            skipped.push({
+                itemTitle: item.title,
+                fieldLabel: '*',
+                reason: 'no importable fields',
+            });
+            continue;
+        }
+        if (field.value.includes('\n')) {
+            skipped.push({
+                itemTitle: item.title,
+                fieldLabel: field.label,
+                reason: 'contains newlines (keychain limitation)',
+            });
+            continue;
+        }
+        const envKey = toEnvKey(item.title);
+        secrets.push({
+            envKey,
+            itemTitle: item.title,
+            fieldLabel: field.label,
+            value: field.value,
+        });
+    }
+    return { secrets, skipped };
+}
+export function buildPasswordItemTemplate(title, value) {
+    return {
+        title,
+        category: 'PASSWORD',
+        tags: ['agents-cli'],
+        fields: [
+            { id: 'password', type: 'CONCEALED', purpose: 'PASSWORD', label: 'password', value },
+        ],
+    };
+}
+export function itemExistsByTitle(title, vaultName) {
+    const result = runOp(['item', 'get', title, '--vault', vaultName, '--format=json']);
+    if (result.ok)
+        return true;
+    if (/isn't an item|not found|no item found/i.test(result.error))
+        return false;
+    throw new Error(result.error);
+}
+export function deleteItemByTitle(title, vaultName) {
+    const result = runOp(['item', 'delete', title, '--vault', vaultName]);
+    if (!result.ok)
+        throw new Error(result.error);
+}
+export function createPasswordItem(title, value, vaultName) {
+    // op item create reads stdin templates only from a real pipe; spawnSync's
+    // input plumbing is detected as empty and op silently ignores the template.
+    // The supported alternative is --template <file>, which works reliably.
+    const template = JSON.stringify(buildPasswordItemTemplate(title, value));
+    const tmpFile = path.join(os.tmpdir(), `agents-op-tpl-${process.pid}-${Date.now()}.json`);
+    fs.writeFileSync(tmpFile, template, { mode: 0o600 });
+    try {
+        const result = runOp(['item', 'create', '--template', tmpFile, '--vault', vaultName]);
+        if (!result.ok)
+            throw new Error(result.error);
+    }
+    finally {
+        try {
+            fs.unlinkSync(tmpFile);
+        }
+        catch {
+            // best-effort cleanup
+        }
+    }
+}

package/dist/lib/paths.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Resolve base + name while preventing path-traversal attacks.
+ * Rejects path separators, null bytes, '.' and '..', and any resolved path
+ * that escapes the base directory. Dot-prefixed names like '.env.example'
+ * are allowed — actual traversal is caught by the containment check below.
+ * Allows spaces, unicode, and other common filename characters.
+ */
+export declare function safeJoin(base: string, name: string): string;

package/dist/lib/paths.js

@@ -0,0 +1,20 @@
+import * as path from 'path';
+/**
+ * Resolve base + name while preventing path-traversal attacks.
+ * Rejects path separators, null bytes, '.' and '..', and any resolved path
+ * that escapes the base directory. Dot-prefixed names like '.env.example'
+ * are allowed — actual traversal is caught by the containment check below.
+ * Allows spaces, unicode, and other common filename characters.
+ */
+export function safeJoin(base, name) {
+    if (!name ||
+        name === '.' || name === '..' ||
+        /[\/\\\x00]/.test(name) ||
+        name.length > 255) {
+        throw new Error(`Invalid name: ${name}`);
+    }
+    const resolved = path.resolve(base, name);
+    if (!resolved.startsWith(path.resolve(base) + path.sep))
+        throw new Error(`Path escape: ${name}`);
+    return resolved;
+}

package/dist/lib/permissions.d.ts

@@ -1,9 +1,11 @@
 import type { AgentId, PermissionSet, InstalledPermission, ClaudePermissions, OpenCodePermissions, CodexPermissions } from './types.js';
+/** Agents that support the permissions subsystem. */
 export declare const PERMISSIONS_CAPABLE_AGENTS: AgentId[];
+/** Filename used for Codex Starlark deny-rules generated from permission groups. */
 export declare const CODEX_RULES_FILENAME = "agents-deny.rules";
 /**
  * Convert canonical deny rules to Codex Starlark .rules format.
- * E.g. "Bash(git reset:*)" → prefix_rule(pattern=["git", "reset"], decision="forbidden")
+ * E.g. "Bash(git reset:*)" -> prefix_rule(pattern=["git", "reset"], decision="forbidden")
  */
 export declare function convertDenyToCodexRules(deny: string[]): string | null;
 /**
@@ -39,6 +41,27 @@ export declare function discoverPermissionGroups(): PermissionGroupInfo[];
  * Get total rule count across all permission groups.
  */
 export declare function getTotalPermissionRuleCount(): number;
+/**
+ * A permission set recipe — names a set and lists which groups it composes.
+ * Lives at ~/.agents/permissions/sets/<name>.yaml.
+ */
+export interface PermissionSetRecipe {
+    name: string;
+    description?: string;
+    includes: string[];
+}
+/** Env var that selects which set recipe to apply at sync time. */
+export declare const PERMISSION_SET_ENV_VAR = "AGENTS_PERMISSION_SET";
+/**
+ * Read a permission set recipe by name from ~/.agents/permissions/sets/.
+ * Returns null if the recipe file is missing or malformed.
+ */
+export declare function readPermissionSetRecipe(name: string): PermissionSetRecipe | null;
+/**
+ * Return the active permission set name from AGENTS_PERMISSION_SET env var,
+ * or null if unset. Caller decides the default behavior when null.
+ */
+export declare function getActivePermissionSetName(): string | null;
 /**
  * Build a PermissionSet from selected groups.
  * Concatenates allow/deny rules from each group.
@@ -201,4 +224,3 @@ export declare function saveDefaultPermissionSet(set: PermissionSet): {
     success: boolean;
     error?: string;
 };
-//# sourceMappingURL=permissions.d.ts.map