@phnx-labs/agents-cli 1.12.0 → 1.14.2

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

@@ -0,0 +1,39 @@
+/**
+ * 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;
+export declare function readBundle(name: string): SecretsBundle;
+export declare function writeBundle(bundle: SecretsBundle): void;
+export declare function deleteBundle(name: string): boolean;
+export declare function listBundles(): SecretsBundle[];
+export interface BundleEntryInfo {
+    key: string;
+    kind: 'literal' | 'keychain' | 'env' | 'file' | 'exec';
+    detail: string;
+}
+export declare function describeBundle(bundle: SecretsBundle): BundleEntryInfo[];
+export declare function resolveBundleEnv(bundle: SecretsBundle): Record<string, string>;
+export declare function keychainRef(key: string): string;
+export declare function keychainItemsForBundle(bundle: SecretsBundle): Array<{
+    key: string;
+    item: string;
+}>;
+export declare function parseDotenv(content: string): Record<string, string>;
+export type { SecretRef };

package/dist/lib/secrets/bundles.js

@@ -0,0 +1,189 @@
+/**
+ * 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, 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).`);
+    }
+}
+export function validateEnvKey(key) {
+    if (!ENV_KEY_PATTERN.test(key)) {
+        throw new Error(`Invalid environment variable name '${key}'. Must match [A-Za-z_][A-Za-z0-9_]*.`);
+    }
+}
+function bundlePath(name) {
+    // 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));
+}
+export function readBundle(name) {
+    validateBundleName(name);
+    const file = bundlePath(name);
+    if (!fs.existsSync(file)) {
+        throw new Error(`Secrets bundle '${name}' not found.`);
+    }
+    const raw = fs.readFileSync(file, 'utf-8');
+    const parsed = yaml.parse(raw);
+    if (!parsed || typeof parsed !== 'object') {
+        throw new Error(`Bundle '${name}' is malformed.`);
+    }
+    const bundle = {
+        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)) {
+        validateEnvKey(key);
+    }
+    return bundle;
+}
+export function writeBundle(bundle) {
+    validateBundleName(bundle.name);
+    for (const key of Object.keys(bundle.vars)) {
+        validateEnvKey(key);
+    }
+    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);
+    const tmp = `${file}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, body, 'utf-8');
+    fs.renameSync(tmp, file);
+}
+export function deleteBundle(name) {
+    validateBundleName(name);
+    const file = bundlePath(name);
+    if (!fs.existsSync(file))
+        return false;
+    fs.unlinkSync(file);
+    return true;
+}
+export function listBundles() {
+    const seen = new Set();
+    const bundles = [];
+    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));
+}
+export function describeBundle(bundle) {
+    const out = [];
+    for (const [key, raw] of Object.entries(bundle.vars)) {
+        const parsed = parseBundleValue(raw);
+        if ('literal' in parsed) {
+            out.push({ key, kind: 'literal', detail: '' });
+        }
+        else {
+            out.push({ key, kind: parsed.ref.provider, detail: parsed.ref.value });
+        }
+    }
+    return out;
+}
+// Walk the bundle and produce a flat env map. Keychain refs are translated via
+// the bundle-scoped naming scheme so two bundles with the same short ID never
+// collide. Throws on the first missing secret so `agents run` fails loudly
+// rather than silently injecting empty strings.
+export function resolveBundleEnv(bundle) {
+    const env = {};
+    for (const [key, raw] of Object.entries(bundle.vars)) {
+        const parsed = parseBundleValue(raw);
+        if ('literal' in parsed) {
+            env[key] = parsed.literal;
+            continue;
+        }
+        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 add ${bundle.name} ${key}`);
+            }
+            throw new Error(`Bundle '${bundle.name}' key '${key}': ${msg}`);
+        }
+    }
+    return env;
+}
+// Build a keychain ref expression from a bundle+key pair, for storage in YAML.
+export function keychainRef(key) {
+    return `keychain:${key}`;
+}
+// Iterate all keychain-backed keys in a bundle for cleanup on rm/unset.
+export function keychainItemsForBundle(bundle) {
+    const items = [];
+    for (const [key, raw] of Object.entries(bundle.vars)) {
+        const parsed = parseBundleValue(raw);
+        if ('ref' in parsed && parsed.ref.provider === 'keychain') {
+            items.push({ key, item: secretsKeychainItem(bundle.name, parsed.ref.value) });
+        }
+    }
+    return items;
+}
+// Parse a dotenv string into key=value pairs, preserving last-wins on duplicates.
+export function parseDotenv(content) {
+    const out = {};
+    for (const raw of content.split('\n')) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const stripped = line.startsWith('export ') ? line.slice('export '.length) : line;
+        const eq = stripped.indexOf('=');
+        if (eq <= 0)
+            continue;
+        const key = stripped.slice(0, eq).trim();
+        let value = stripped.slice(eq + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        if (ENV_KEY_PATTERN.test(key)) {
+            out[key] = value;
+        }
+    }
+    return out;
+}