@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/dist/lib/runner.d.ts

@@ -1,12 +1,25 @@
+/**
+ * Job execution engine for routines.
+ *
+ * Builds agent-specific CLI commands from job configs, spawns them with
+ * sandboxed or unsandboxed environments, captures stdout to log files,
+ * enforces timeouts, and extracts the final assistant report from the
+ * agent's stream-JSON output.
+ */
 import type { JobConfig, RunMeta } from './routines.js';
 import type { AgentId } from './types.js';
+/** Result of a completed job execution, including metadata and optional report. */
 export interface RunResult {
     meta: RunMeta;
     reportPath: string | null;
 }
+/** Build the full CLI argv for executing a job, applying mode, model, and permission flags. */
 export declare function buildJobCommand(config: JobConfig, resolvedPrompt: string): string[];
+/** Execute a job synchronously (waits for completion or timeout before resolving). */
 export declare function executeJob(config: JobConfig): Promise<RunResult>;
+/** Spawn a job as a detached process and return immediately with run metadata. */
 export declare function executeJobDetached(config: JobConfig): Promise<RunMeta>;
+/** Extract the final assistant message from a stream-JSON log file as a markdown report. */
 export declare function extractReport(stdoutPath: string, agentType: AgentId): string | null;
+/** Scan all runs marked "running" and finalize any whose process has exited. */
 export declare function monitorRunningJobs(): void;
-//# sourceMappingURL=runner.d.ts.map

package/dist/lib/runner.js

@@ -1,3 +1,11 @@
+/**
+ * Job execution engine for routines.
+ *
+ * Builds agent-specific CLI commands from job configs, spawns them with
+ * sandboxed or unsandboxed environments, captures stdout to log files,
+ * enforces timeouts, and extracts the final assistant report from the
+ * agent's stream-JSON output.
+ */
 import { spawn } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -6,11 +14,13 @@ import { resolveJobPrompt, parseTimeout, writeRunMeta, getRunDir, } from './rout
 import { getRunsDir } from './state.js';
 import { prepareJobHome, buildSpawnEnv } from './sandbox.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
+/** CLI command templates per agent, with {prompt} as a placeholder. */
 const AGENT_COMMANDS = {
     claude: ['claude', '-p', '--verbose', '{prompt}', '--output-format', 'stream-json', '--permission-mode', 'plan'],
     codex: ['codex', 'exec', '--sandbox', 'workspace-write', '{prompt}', '--json'],
     gemini: ['gemini', '{prompt}', '--output-format', 'stream-json'],
 };
+/** Build the full CLI argv for executing a job, applying mode, model, and permission flags. */
 export function buildJobCommand(config, resolvedPrompt) {
     const template = AGENT_COMMANDS[config.agent];
     if (!template) {
@@ -31,6 +41,12 @@ export function buildJobCommand(config, resolvedPrompt) {
         }
         if (config.allow?.dirs) {
             for (const dir of config.allow.dirs) {
+                // Reject leading '-' so a routine YAML can't smuggle an argv flag like
+                // `--dangerously-skip-permissions` past the sandbox by hiding it as an
+                // allow.dirs entry.
+                if (dir.startsWith('-')) {
+                    throw new Error(`allow.dirs entries must not start with '-': ${JSON.stringify(dir)}`);
+                }
                 const resolved = dir.replace(/^~/, os.homedir());
                 cmd.push('--add-dir', resolved);
             }
@@ -89,6 +105,7 @@ function appendModelAndReasoning(cmd, config) {
 function generateRunId() {
     return new Date().toISOString().replace(/[:.]/g, '-');
 }
+/** Execute a job synchronously (waits for completion or timeout before resolving). */
 export async function executeJob(config) {
     const resolvedPrompt = resolveJobPrompt(config);
     const cmd = buildJobCommand(config, resolvedPrompt);
@@ -98,7 +115,7 @@ export async function executeJob(config) {
     const runDir = getRunDir(config.name, runId);
     fs.mkdirSync(runDir, { recursive: true });
     const stdoutPath = path.join(runDir, 'stdout.log');
-    const stdoutFd = fs.openSync(stdoutPath, 'w');
+    const stdoutFd = fs.openSync(stdoutPath, 'w', 0o600);
     let spawnEnv = useSandbox ? buildSpawnEnv(overlayHome) : { ...process.env };
     if (config.timezone) {
         spawnEnv.TZ = config.timezone;
@@ -179,6 +196,7 @@ export async function executeJob(config) {
         child.unref();
     });
 }
+/** Spawn a job as a detached process and return immediately with run metadata. */
 export async function executeJobDetached(config) {
     const resolvedPrompt = resolveJobPrompt(config);
     const cmd = buildJobCommand(config, resolvedPrompt);
@@ -188,7 +206,7 @@ export async function executeJobDetached(config) {
     const runDir = getRunDir(config.name, runId);
     fs.mkdirSync(runDir, { recursive: true });
     const stdoutPath = path.join(runDir, 'stdout.log');
-    const stdoutFd = fs.openSync(stdoutPath, 'w');
+    const stdoutFd = fs.openSync(stdoutPath, 'w', 0o600);
     let spawnEnv = useSandbox ? buildSpawnEnv(overlayHome) : { ...process.env };
     if (config.timezone) {
         spawnEnv.TZ = config.timezone;
@@ -233,6 +251,7 @@ function extractAndSaveReport(stdoutPath, agentType, runDir) {
     }
     return null;
 }
+/** Extract the final assistant message from a stream-JSON log file as a markdown report. */
 export function extractReport(stdoutPath, agentType) {
     if (!fs.existsSync(stdoutPath))
         return null;
@@ -273,6 +292,7 @@ export function extractReport(stdoutPath, agentType) {
         return null;
     }
 }
+/** Scan all runs marked "running" and finalize any whose process has exited. */
 export function monitorRunningJobs() {
     const runsDir = getRunsDir();
     if (!fs.existsSync(runsDir))
@@ -308,4 +328,3 @@ export function monitorRunningJobs() {
         }
     }
 }
-//# sourceMappingURL=runner.js.map

package/dist/lib/sandbox.d.ts

@@ -1,10 +1,25 @@
+/**
+ * Sandbox environment for routine job execution.
+ *
+ * Creates an overlay HOME directory per job with symlinked allowed
+ * directories and agent-specific config files (permissions, settings).
+ * The spawned agent process sees only the overlay, limiting filesystem
+ * access to explicitly allowed paths.
+ */
 import type { JobConfig } from './routines.js';
+/** Build a restricted environment for a sandboxed process, setting HOME to the overlay. */
 export declare function buildSpawnEnv(overlayHome: string, extraEnv?: Record<string, string>): Record<string, string>;
+/** Get the overlay HOME directory path for a named job. */
 export declare function getJobHomePath(name: string): string;
+/** Create a fresh overlay HOME for a job, including agent config and allowed-dir symlinks. */
 export declare function prepareJobHome(config: JobConfig): string;
+/** Remove a job's overlay HOME directory entirely. */
 export declare function cleanJobHome(name: string): void;
+/** Symlink allowed directories into the overlay HOME, skipping paths outside the real HOME. */
 export declare function symlinkAllowedDirs(overlayHome: string, dirs: string[]): void;
+/** Generate a Claude settings.json in the overlay with scoped permissions from the job config. */
 export declare function generateClaudeConfig(overlayHome: string, config: JobConfig): void;
+/** Generate a Codex config.toml in the overlay with model and approval-mode settings. */
 export declare function generateCodexConfig(overlayHome: string, config: JobConfig): void;
+/** Generate a Gemini settings.json in the overlay from the job's config block. */
 export declare function generateGeminiConfig(overlayHome: string, config: JobConfig): void;
-//# sourceMappingURL=sandbox.d.ts.map

package/dist/lib/sandbox.js

@@ -1,8 +1,18 @@
+/**
+ * Sandbox environment for routine job execution.
+ *
+ * Creates an overlay HOME directory per job with symlinked allowed
+ * directories and agent-specific config files (permissions, settings).
+ * The spawned agent process sees only the overlay, limiting filesystem
+ * access to explicitly allowed paths.
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
+import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
 import { getRoutinesDir } from './state.js';
 const REAL_HOME = os.homedir();
+/** Environment variables forwarded from the parent process into the sandbox. */
 const ENV_ALLOWLIST = [
     'PATH',
     'SHELL',
@@ -25,13 +35,20 @@ const ENV_ALLOWLIST = [
     'NO_COLOR',
     'FORCE_COLOR',
 ];
-// Tools safe to grant as wildcards (no filesystem access)
+/** Tools safe to grant as wildcards (no filesystem access). */
 const SAFE_TOOLS = {
     web_search: 'WebSearch(*)',
     web_fetch: 'WebFetch(*)',
 };
-// Bare tool names that get scoped to allow.dirs, never wildcarded
+/** Bare tool names that get scoped to allow.dirs, never wildcarded. */
 const DIR_SCOPED_TOOLS = new Set(['read', 'write', 'edit', 'glob', 'grep', 'notebook_edit']);
+function tomlString(value) {
+    if (/[\r\n]/.test(value)) {
+        throw new Error(`TOML value contains newline: ${JSON.stringify(value)}`);
+    }
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+/** Build a restricted environment for a sandboxed process, setting HOME to the overlay. */
 export function buildSpawnEnv(overlayHome, extraEnv) {
     const env = { HOME: overlayHome };
     for (const key of ENV_ALLOWLIST) {
@@ -44,9 +61,11 @@ export function buildSpawnEnv(overlayHome, extraEnv) {
     }
     return env;
 }
+/** Get the overlay HOME directory path for a named job. */
 export function getJobHomePath(name) {
     return path.join(getRoutinesDir(), name, 'home');
 }
+/** Create a fresh overlay HOME for a job, including agent config and allowed-dir symlinks. */
 export function prepareJobHome(config) {
     const overlayHome = getJobHomePath(config.name);
     cleanJobHome(config.name);
@@ -65,12 +84,14 @@ export function prepareJobHome(config) {
     }
     return overlayHome;
 }
+/** Remove a job's overlay HOME directory entirely. */
 export function cleanJobHome(name) {
     const overlayHome = getJobHomePath(name);
     if (fs.existsSync(overlayHome)) {
         fs.rmSync(overlayHome, { recursive: true, force: true });
     }
 }
+/** Symlink allowed directories into the overlay HOME, skipping paths outside the real HOME. */
 export function symlinkAllowedDirs(overlayHome, dirs) {
     for (const dir of dirs) {
         const expanded = dir.replace(/^~/, REAL_HOME);
@@ -99,6 +120,7 @@ export function symlinkAllowedDirs(overlayHome, dirs) {
         }
     }
 }
+/** Generate a Claude settings.json in the overlay with scoped permissions from the job config. */
 export function generateClaudeConfig(overlayHome, config) {
     const claudeDir = path.join(overlayHome, '.claude');
     fs.mkdirSync(claudeDir, { recursive: true });
@@ -156,13 +178,14 @@ export function generateClaudeConfig(overlayHome, config) {
     };
     fs.writeFileSync(path.join(claudeDir, 'settings.json'), JSON.stringify(settings, null, 2), 'utf-8');
 }
+/** Generate a Codex config.toml in the overlay with model and approval-mode settings. */
 export function generateCodexConfig(overlayHome, config) {
     const codexDir = path.join(overlayHome, '.codex');
     fs.mkdirSync(codexDir, { recursive: true });
     const lines = [];
     const model = config.config?.model;
     if (model) {
-        lines.push(`model = "${model}"`);
+        lines.push(`model = ${tomlString(model)}`);
     }
     if (config.mode === 'edit') {
         lines.push('approval_mode = "full-auto"');
@@ -175,7 +198,7 @@ export function generateCodexConfig(overlayHome, config) {
             if (key === 'model')
                 continue;
             if (typeof value === 'string') {
-                lines.push(`${key} = "${value}"`);
+                lines.push(`${key} = ${tomlString(value)}`);
             }
             else if (typeof value === 'boolean' || typeof value === 'number') {
                 lines.push(`${key} = ${value}`);
@@ -184,18 +207,18 @@ export function generateCodexConfig(overlayHome, config) {
     }
     fs.writeFileSync(path.join(codexDir, 'config.toml'), lines.join('\n') + '\n', 'utf-8');
 }
+/** Generate a Gemini settings.json in the overlay from the job's config block. */
 export function generateGeminiConfig(overlayHome, config) {
-    const geminiDir = path.join(overlayHome, '.gemini');
-    fs.mkdirSync(geminiDir, { recursive: true });
-    const settings = {};
-    if (config.config?.model) {
-        settings.model = config.config.model;
-    }
-    if (config.config) {
-        for (const [key, value] of Object.entries(config.config)) {
-            settings[key] = value;
+    const settingsPath = path.join(overlayHome, '.gemini', 'settings.json');
+    updateGeminiSettings(settingsPath, (settings) => {
+        if (config.config?.model) {
+            settings.model = config.config.model;
         }
-    }
-    fs.writeFileSync(path.join(geminiDir, 'settings.json'), JSON.stringify(settings, null, 2), 'utf-8');
+        if (config.config) {
+            for (const [key, value] of Object.entries(config.config)) {
+                settings[key] = value;
+            }
+        }
+        setGeminiAutoUpdateDisabled(settings);
+    });
 }
-//# sourceMappingURL=sandbox.js.map

package/dist/lib/scheduler.d.ts

@@ -1,4 +1,12 @@
+/**
+ * Cron-based job scheduler for routines.
+ *
+ * Wraps the croner library to manage scheduled jobs in-memory. The daemon
+ * process creates a single JobScheduler instance that loads enabled jobs
+ * on startup and reloads them on SIGHUP.
+ */
 import type { JobConfig } from './routines.js';
+/** In-memory cron scheduler that triggers a callback when jobs fire. */
 export declare class JobScheduler {
     private jobs;
     private onTrigger;
@@ -15,4 +23,3 @@ export declare class JobScheduler {
         enabled: boolean;
     }>;
 }
-//# sourceMappingURL=scheduler.d.ts.map

package/dist/lib/scheduler.js

@@ -1,5 +1,13 @@
+/**
+ * Cron-based job scheduler for routines.
+ *
+ * Wraps the croner library to manage scheduled jobs in-memory. The daemon
+ * process creates a single JobScheduler instance that loads enabled jobs
+ * on startup and reloads them on SIGHUP.
+ */
 import { Cron } from 'croner';
 import { listJobs, deleteJob } from './routines.js';
+/** In-memory cron scheduler that triggers a callback when jobs fire. */
 export class JobScheduler {
     jobs = new Map();
     onTrigger;
@@ -66,4 +74,3 @@ export class JobScheduler {
         return result;
     }
 }
-//# sourceMappingURL=scheduler.js.map

package/dist/lib/secrets/AgentsKeychain.app/Contents/Info.plist

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleIdentifier</key>
+  <string>com.phnx-labs.agents-keychain</string>
+  <key>CFBundleName</key>
+  <string>AgentsKeychain</string>
+  <key>CFBundleExecutable</key>
+  <string>AgentsKeychain</string>
+  <key>CFBundlePackageType</key>
+  <string>APPL</string>
+  <key>CFBundleVersion</key>
+  <string>1</string>
+  <key>CFBundleShortVersionString</key>
+  <string>1.0</string>
+  <key>LSMinimumSystemVersion</key>
+  <string>12.0</string>
+  <key>LSUIElement</key>
+  <true/>
+</dict>
+</plist>

package/dist/lib/secrets/AgentsKeychain.app/Contents/_CodeSignature/CodeResources

@@ -0,0 +1,123 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>files</key>
+	<dict/>
+	<key>files2</key>
+	<dict>
+		<key>embedded.provisionprofile</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			2vfA/eR3dTYgNc/fXhdADUPkp5tRIepPzE3FCLfDx4w=
+			</data>
+		</dict>
+	</dict>
+	<key>rules</key>
+	<dict>
+		<key>^Resources/</key>
+		<true/>
+		<key>^Resources/.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^Resources/.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Resources/Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^version.plist$</key>
+		<true/>
+	</dict>
+	<key>rules2</key>
+	<dict>
+		<key>.*\.dSYM($|/)</key>
+		<dict>
+			<key>weight</key>
+			<real>11</real>
+		</dict>
+		<key>^(.*/)?\.DS_Store$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>2000</real>
+		</dict>
+		<key>^(Frameworks|SharedFrameworks|PlugIns|Plug-ins|XPCServices|Helpers|MacOS|Library/(Automator|Spotlight|LoginItems))/</key>
+		<dict>
+			<key>nested</key>
+			<true/>
+			<key>weight</key>
+			<real>10</real>
+		</dict>
+		<key>^.*</key>
+		<true/>
+		<key>^Info\.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^PkgInfo$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^Resources/</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^Resources/.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^Resources/.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Resources/Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^[^/]+$</key>
+		<dict>
+			<key>nested</key>
+			<true/>
+			<key>weight</key>
+			<real>10</real>
+		</dict>
+		<key>^embedded\.provisionprofile$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^version\.plist$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+	</dict>
+</dict>
+</plist>

package/dist/lib/{secrets-bundles.d.ts → secrets/bundles.d.ts}

@@ -1,10 +1,21 @@
-import { type BundleValue, type SecretRef } from './secrets.js';
+/**
+ * Secret bundles -- named sets of keychain-backed environment variables.
+ *
+ * Each bundle is a YAML file in ~/.agents/secrets/ declaring key names.
+ * Values live in the macOS Keychain and are injected into the agent's
+ * environment at spawn time via `agents run --secrets <bundle>`.
+ */
+import { type BundleValue, type SecretRef } from './index.js';
+/** A named set of environment variable definitions backed by various secret providers. */
 export interface SecretsBundle {
     name: string;
     description?: string;
     allow_exec?: boolean;
+    /** When true, keychain-backed values are stored in iCloud Keychain so they sync across the user's Macs. */
+    icloud_sync?: boolean;
     vars: Record<string, BundleValue>;
 }
+/** Validate a bundle name against the allowed pattern. Throws on invalid input. */
 export declare function validateBundleName(name: string): void;
 export declare function validateEnvKey(key: string): void;
 export declare function bundleExists(name: string): boolean;
@@ -26,4 +37,3 @@ export declare function keychainItemsForBundle(bundle: SecretsBundle): Array<{
 }>;
 export declare function parseDotenv(content: string): Record<string, string>;
 export type { SecretRef };
-//# sourceMappingURL=secrets-bundles.d.ts.map

package/dist/lib/{secrets-bundles.js → secrets/bundles.js}

@@ -1,10 +1,18 @@
+/**
+ * Secret bundles -- named sets of keychain-backed environment variables.
+ *
+ * Each bundle is a YAML file in ~/.agents/secrets/ declaring key names.
+ * Values live in the macOS Keychain and are injected into the agent's
+ * environment at spawn time via `agents run --secrets <bundle>`.
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { getSecretsDir } from './state.js';
-import { parseBundleValue, resolveRef, secretsKeychainItem, } from './secrets.js';
+import { getSecretsDir, getUserSecretsDir } from '../state.js';
+import { parseBundleValue, resolveRef, secretsKeychainItem, } from './index.js';
 const BUNDLE_NAME_PATTERN = /^[a-z0-9][a-z0-9-_]{0,48}$/i;
 const ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Validate a bundle name against the allowed pattern. Throws on invalid input. */
 export function validateBundleName(name) {
     if (!BUNDLE_NAME_PATTERN.test(name)) {
         throw new Error(`Invalid bundle name '${name}'. Use letters, digits, dash, underscore (max 48 chars).`);
@@ -16,7 +24,14 @@ export function validateEnvKey(key) {
     }
 }
 function bundlePath(name) {
-    return path.join(getSecretsDir(), `${name}.yml`);
+    // Check user dir first (for reads), write to user dir
+    const userPath = path.join(getUserSecretsDir(), `${name}.yml`);
+    if (fs.existsSync(userPath))
+        return userPath;
+    const systemPath = path.join(getSecretsDir(), `${name}.yml`);
+    if (fs.existsSync(systemPath))
+        return systemPath;
+    return userPath; // default write location
 }
 export function bundleExists(name) {
     return fs.existsSync(bundlePath(name));
@@ -36,6 +51,7 @@ export function readBundle(name) {
         name: parsed.name || name,
         description: parsed.description,
         allow_exec: Boolean(parsed.allow_exec),
+        icloud_sync: Boolean(parsed.icloud_sync),
         vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
     };
     for (const key of Object.keys(bundle.vars)) {
@@ -48,12 +64,13 @@ export function writeBundle(bundle) {
     for (const key of Object.keys(bundle.vars)) {
         validateEnvKey(key);
     }
-    const dir = getSecretsDir();
+    const dir = getUserSecretsDir();
     fs.mkdirSync(dir, { recursive: true });
     const body = yaml.stringify({
         name: bundle.name,
         description: bundle.description,
         allow_exec: bundle.allow_exec ? true : undefined,
+        icloud_sync: bundle.icloud_sync ? true : undefined,
         vars: bundle.vars,
     });
     const file = bundlePath(bundle.name);
@@ -70,18 +87,22 @@ export function deleteBundle(name) {
     return true;
 }
 export function listBundles() {
-    const dir = getSecretsDir();
-    if (!fs.existsSync(dir))
-        return [];
-    const entries = fs.readdirSync(dir).filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'));
+    const seen = new Set();
     const bundles = [];
-    for (const entry of entries) {
-        const name = entry.replace(/\.(yml|yaml)$/, '');
-        try {
-            bundles.push(readBundle(name));
-        }
-        catch {
-            // Skip malformed bundles; surfaced via `agents secrets view <name>`.
+    for (const dir of [getUserSecretsDir(), getSecretsDir()]) {
+        if (!fs.existsSync(dir))
+            continue;
+        for (const entry of fs.readdirSync(dir).filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'))) {
+            const name = entry.replace(/\.(yml|yaml)$/, '');
+            if (seen.has(name))
+                continue;
+            seen.add(name);
+            try {
+                bundles.push(readBundle(name));
+            }
+            catch {
+                // Skip malformed bundles; surfaced via `agents secrets view <name>`.
+            }
         }
     }
     return bundles.sort((a, b) => a.name.localeCompare(b.name));
@@ -114,13 +135,14 @@ export function resolveBundleEnv(bundle) {
         try {
             env[key] = resolveRef(parsed.ref, {
                 allowExec: bundle.allow_exec,
+                iCloudSync: bundle.icloud_sync,
                 keychainItemFor: (shortId) => secretsKeychainItem(bundle.name, shortId),
             });
         }
         catch (err) {
             const msg = err.message;
             if (parsed.ref.provider === 'keychain' && /not found/.test(msg)) {
-                throw new Error(`${msg} Run: agents secrets set ${bundle.name} ${key}`);
+                throw new Error(`${msg} Run: agents secrets add ${bundle.name} ${key}`);
             }
             throw new Error(`Bundle '${bundle.name}' key '${key}': ${msg}`);
         }
@@ -165,4 +187,3 @@ export function parseDotenv(content) {
     }
     return out;
 }
-//# sourceMappingURL=secrets-bundles.js.map

package/dist/lib/secrets/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * macOS Keychain integration for secure credential storage.
+ *
+ * Calls a compiled Swift helper (keychain-helper.swift) to store and retrieve
+ * API keys and tokens via the Security framework, with kSecAttrSynchronizable
+ * set so iCloud Keychain syncs them across the user's Macs.
+ */
+/** Supported secret resolution backends. */
+export type SecretProvider = 'keychain' | 'env' | 'file' | 'exec';
+/** A typed reference to a secret, consisting of a provider and a provider-specific value. */
+export interface SecretRef {
+    provider: SecretProvider;
+    value: string;
+}
+/**
+ * A bundle YAML value: either a string (literal or provider-prefixed ref) or
+ * an object `{value: string}` used to escape a literal that would otherwise
+ * be parsed as a ref (e.g. a URL that happens to start with 'env:').
+ */
+export type BundleValue = string | {
+    value: string;
+};
+/** Parse a bundle YAML value into either a literal string or a typed secret ref. */
+export declare function parseBundleValue(raw: BundleValue): {
+    literal: string;
+} | {
+    ref: SecretRef;
+};
+/** Serialize a secret ref back to its `provider:value` string form. */
+export declare function serializeRef(ref: SecretRef): string;
+/** Build the keychain item name for a profile provider token. */
+export declare function profileKeychainItem(provider: string): string;
+/** Build the keychain item name for a secrets-bundle key. */
+export declare function secretsKeychainItem(bundle: string, key: string): string;
+/** Check if a keychain item exists (macOS only). */
+export declare function hasKeychainToken(item: string, sync?: boolean): boolean;
+/** Retrieve a secret value from the macOS Keychain. Throws if not found. */
+export declare function getKeychainToken(item: string, sync?: boolean): string;
+/** Store or update a secret value in the macOS Keychain. iCloud-synced when sync=true. */
+export declare function setKeychainToken(item: string, value: string, sync?: boolean): void;
+/** Delete a keychain item. Returns true if it existed. */
+export declare function deleteKeychainToken(item: string, sync?: boolean): boolean;
+/** Options controlling how secret refs are resolved. */
+export interface ResolveOptions {
+    /** Translate a short keychain ID to a fully namespaced item name. */
+    keychainItemFor?: (shortId: string) => string;
+    /** Allow exec: refs. When false (default), exec refs throw. */
+    allowExec?: boolean;
+    /** Restrict env: refs to this allowlist. When undefined, any env var may be read. */
+    envAllowlist?: string[];
+    /** Read keychain refs from the iCloud-synced keychain backend. */
+    iCloudSync?: boolean;
+}
+/** Resolve a secret ref to its plaintext value using the appropriate provider. */
+export declare function resolveRef(ref: SecretRef, opts?: ResolveOptions): string;