@phnx-labs/agents-cli 1.20.16 → 1.20.18

package/dist/lib/models.js

@@ -710,6 +710,27 @@ export function resolveModel(agent, version, requested) {
         warning: `model "${requested}" not in known catalog for ${agent}@${version}; forwarding as-is${hint}`,
     };
 }
+/**
+ * Resolve the model id an `agents run` will ACTUALLY use, for cost estimation
+ * (issue #346). The run path resolves the model in this precedence:
+ *   1. explicit `--model` (or profile/workflow/runDefaults value) — `requested`
+ *   2. otherwise the agent CLI's own built-in default, which we read from the
+ *      extracted catalog's `isDefault` model.
+ * Returns null only when we have neither — the caller must then treat the
+ * estimate as unpriced rather than silently using an unpriced placeholder id
+ * like `${agent}-default`.
+ */
+export function resolveEffectiveModel(agent, version, requested) {
+    if (requested && requested.trim() !== '') {
+        const resolved = resolveModel(agent, version, requested);
+        return resolved.canonical ?? resolved.forwarded;
+    }
+    const catalog = getModelCatalog(agent, version);
+    if (!catalog)
+        return null;
+    const def = catalog.models.find((m) => m.isDefault);
+    return def?.id ?? null;
+}
 /** 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)];

package/dist/lib/plugin-marketplace.js

@@ -209,17 +209,24 @@ export function validateClaudePluginManifest(manifest) {
         const value = m[field];
         if (value === undefined || value === null)
             continue;
+        // How-to-fix written so a human OR a coding agent reading stderr can act
+        // without further investigation. Deleting the field is the recommended fix:
+        // Claude auto-discovers skills/commands/agents from their directories, which
+        // is why every well-formed plugin omits these fields entirely.
+        const fix = `Fix: delete the "${field}" field from plugin.json (recommended — Claude ` +
+            `auto-discovers from the ${field}/ directory), or rewrite every entry as a ` +
+            `"./"-relative path (e.g. "./${field}/<name>").`;
         const entries = Array.isArray(value) ? value : [value];
         for (const entry of entries) {
             if (typeof entry !== 'string') {
-                warnings.push(`plugin.json field "${field}" must contain relative paths starting with "./" ` +
-                    `(e.g. "./${field}/<name>"); found a non-string value. Claude Code will reject the whole plugin.`);
+                warnings.push(`field "${field}" must be a "./"-relative path string or an array of them; ` +
+                    `found a non-string entry. Claude Code silently rejects the ENTIRE plugin. ${fix}`);
                 break;
             }
             if (!entry.startsWith('./')) {
-                warnings.push(`plugin.json field "${field}" entry "${entry}" must be a relative path starting with "./" ` +
-                    `(e.g. "./${field}/${entry}"). Claude Code rejects the entire plugin otherwise — ` +
-                    `remove the field to auto-discover from ${field}/, or use relative paths.`);
+                warnings.push(`field "${field}" entry "${entry}" must be a relative path starting with "./" ` +
+                    `(e.g. "./${field}/${entry}"), not a bare name. Claude Code silently rejects the ` +
+                    `ENTIRE plugin — no commands or skills load. ${fix}`);
                 break;
             }
         }
@@ -268,7 +275,10 @@ export function syncMarketplaceManifest(spec, agent, versionHome) {
             continue;
         }
         for (const warning of validateClaudePluginManifest(manifest)) {
-            process.stderr.write(`agents-cli: plugin '${manifest.name ?? entry.name}': ${warning}\n`);
+            // Reference the plugin by name, not the marketplace-copy path: that copy is
+            // regenerated from source on every sync, so editing it gets stomped. The fix
+            // belongs in the plugin's SOURCE .claude-plugin/plugin.json.
+            process.stderr.write(`agents-cli: plugin '${manifest.name ?? entry.name}' has a Claude-invalid manifest — ${warning}\n`);
         }
         entries.push({
             name: manifest.name,

package/dist/lib/plugins.js

@@ -13,6 +13,7 @@ import * as path from 'path';
 import { execFileSync } from 'child_process';
 import { getPluginsDir, getTrashPluginsDir, getExtraPluginsDir, getProjectPluginsDir } from './state.js';
 import { IS_WINDOWS, isWindowsAbsolutePath, homeDir } from './platform/index.js';
+import { assertSafeGitTransport } from './git.js';
 import { listInstalledVersions, getVersionHomePath } from './versions.js';
 import { AGENTS, agentConfigDirName } from './agents.js';
 import { capableAgents, isCapable } from './capabilities.js';
@@ -1078,11 +1079,13 @@ export async function installPlugin(spec) {
         fs.cpSync(resolvedSource, targetRoot, { recursive: true });
     }
     else {
-        // Git clone
+        // Git clone. Validate the transport (blocks ext::/file:///http:///leading-"-")
+        // and pass "--" so the source can never be parsed as a git option.
+        assertSafeGitTransport(resolvedSource);
         if (fs.existsSync(targetRoot)) {
             fs.rmSync(targetRoot, { recursive: true, force: true });
         }
-        execFileSync('git', ['clone', '--depth', '1', resolvedSource, targetRoot], {
+        execFileSync('git', ['clone', '--depth', '1', '--', resolvedSource, targetRoot], {
             stdio: 'pipe',
         });
     }

package/dist/lib/pricing/cost.d.ts

@@ -0,0 +1,46 @@
+/** A single usage record: one model and the tokens it consumed in each direction. */
+export interface TokenUsage {
+    model?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+}
+/**
+ * USD cost of one usage record. Returns 0 when the model is missing or unpriced
+ * (cost is additive — an unknown model contributes nothing, not NaN). Cache
+ * read/write tokens are priced at their dedicated rates when the table exposes
+ * them, otherwise they fall back to the input rate (the standard LiteLLM
+ * convention for models that don't publish a separate cache price).
+ */
+export declare function costOfUsage(u: TokenUsage): number;
+/** Sum the USD cost of every usage record in a session. */
+export declare function costOfSession(usages: TokenUsage[]): number;
+/**
+ * Format a USD amount for human display. Cents-precise, with a "<$0.01" floor
+ * so tiny-but-nonzero sessions don't render as "$0.00" and read as free.
+ */
+export declare function formatUsd(usd: number): string;
+/** Token bundle accepted by the #346 estimator/actual-cost helpers. */
+interface EstimatorTokens {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+}
+/**
+ * Pre-flight cost estimate for a model + token bundle (issue #346's budget
+ * gate). Returns the resolved canonical model id (`modelMatched`) so callers
+ * can warn when an estimate fell back to $0 because the model is unpriced.
+ */
+export declare function estimateCost(model: string, tokens: EstimatorTokens): {
+    usd: number;
+    modelMatched: string | null;
+};
+/** Actual (post-hoc) cost of a model + observed usage. Thin alias over costOfUsage. */
+export declare function actualCost(model: string, usage: EstimatorTokens): {
+    usd: number;
+};
+/** True when the model resolves to a priced entry in the table. */
+export declare function isModelPriced(model: string): boolean;
+export {};

package/dist/lib/pricing/cost.js

@@ -0,0 +1,71 @@
+/**
+ * Token-usage → USD cost math, built on the offline pricing table.
+ *
+ * `costOfUsage` is the single multiply-by-price primitive every other helper
+ * (and issue #346's budget pre-flight estimator) routes through. It returns 0
+ * for unknown/unpriced models rather than throwing — cost is additive, and a
+ * single unknown model in a session shouldn't blow up the whole rollup.
+ */
+import { getModelPricing } from './table.js';
+/**
+ * USD cost of one usage record. Returns 0 when the model is missing or unpriced
+ * (cost is additive — an unknown model contributes nothing, not NaN). Cache
+ * read/write tokens are priced at their dedicated rates when the table exposes
+ * them, otherwise they fall back to the input rate (the standard LiteLLM
+ * convention for models that don't publish a separate cache price).
+ */
+export function costOfUsage(u) {
+    if (!u.model)
+        return 0;
+    const pricing = getModelPricing(u.model);
+    if (!pricing)
+        return 0;
+    const input = u.inputTokens ?? 0;
+    const output = u.outputTokens ?? 0;
+    const cacheRead = u.cacheReadTokens ?? 0;
+    const cacheWrite = u.cacheCreationTokens ?? 0;
+    const cacheReadRate = pricing.cacheReadPerToken ?? pricing.inputPerToken;
+    const cacheWriteRate = pricing.cacheWritePerToken ?? pricing.inputPerToken;
+    return (input * pricing.inputPerToken +
+        output * pricing.outputPerToken +
+        cacheRead * cacheReadRate +
+        cacheWrite * cacheWriteRate);
+}
+/** Sum the USD cost of every usage record in a session. */
+export function costOfSession(usages) {
+    let total = 0;
+    for (const u of usages)
+        total += costOfUsage(u);
+    return total;
+}
+/**
+ * Format a USD amount for human display. Cents-precise, with a "<$0.01" floor
+ * so tiny-but-nonzero sessions don't render as "$0.00" and read as free.
+ */
+export function formatUsd(usd) {
+    if (!Number.isFinite(usd) || usd <= 0)
+        return '$0.00';
+    if (usd < 0.01)
+        return '<$0.01';
+    return `$${usd.toFixed(2)}`;
+}
+/**
+ * Pre-flight cost estimate for a model + token bundle (issue #346's budget
+ * gate). Returns the resolved canonical model id (`modelMatched`) so callers
+ * can warn when an estimate fell back to $0 because the model is unpriced.
+ */
+export function estimateCost(model, tokens) {
+    const pricing = getModelPricing(model);
+    const usd = costOfUsage({ model, ...tokens });
+    // modelMatched is the input model when priced, null when unknown — callers
+    // only need the priced/unpriced signal, not the internal canonical key.
+    return { usd, modelMatched: pricing ? model : null };
+}
+/** Actual (post-hoc) cost of a model + observed usage. Thin alias over costOfUsage. */
+export function actualCost(model, usage) {
+    return { usd: costOfUsage({ model, ...usage }) };
+}
+/** True when the model resolves to a priced entry in the table. */
+export function isModelPriced(model) {
+    return getModelPricing(model) !== null;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Canonical, reusable pricing module.
+ *
+ * Public surface re-exported here is the contract issue #346 (budget
+ * enforcement) imports against — keep it stable.
+ */
+export { type ModelPricing, PRICING_VERSION, getModelPricing, listPricedModels, } from './table.js';
+export { type TokenUsage, costOfUsage, costOfSession, formatUsd, estimateCost, actualCost, isModelPriced, } from './cost.js';

package/dist/lib/pricing/index.js

@@ -0,0 +1,8 @@
+/**
+ * Canonical, reusable pricing module.
+ *
+ * Public surface re-exported here is the contract issue #346 (budget
+ * enforcement) imports against — keep it stable.
+ */
+export { PRICING_VERSION, getModelPricing, listPricedModels, } from './table.js';
+export { costOfUsage, costOfSession, formatUsd, estimateCost, actualCost, isModelPriced, } from './cost.js';

package/dist/lib/pricing/prices.json

@@ -0,0 +1,138 @@
+{
+    "version": "2026-06-24",
+    "models": {
+        "claude-opus-4": {
+            "inputPerToken": 0.000005,
+            "outputPerToken": 0.000025,
+            "cacheReadPerToken": 0.0000005,
+            "cacheWritePerToken": 0.00000625
+        },
+        "claude-sonnet-4": {
+            "inputPerToken": 0.000003,
+            "outputPerToken": 0.000015,
+            "cacheReadPerToken": 0.0000003,
+            "cacheWritePerToken": 0.00000375
+        },
+        "claude-haiku-4": {
+            "inputPerToken": 0.000001,
+            "outputPerToken": 0.000005,
+            "cacheReadPerToken": 0.0000001,
+            "cacheWritePerToken": 0.00000125
+        },
+        "claude-fable-5": {
+            "inputPerToken": 0.00001,
+            "outputPerToken": 0.00005,
+            "cacheReadPerToken": 0.000001,
+            "cacheWritePerToken": 0.0000125
+        },
+        "claude-mythos-5": {
+            "inputPerToken": 0.00001,
+            "outputPerToken": 0.00005,
+            "cacheReadPerToken": 0.000001,
+            "cacheWritePerToken": 0.0000125
+        },
+        "claude-3-5-sonnet": {
+            "inputPerToken": 0.000003,
+            "outputPerToken": 0.000015,
+            "cacheReadPerToken": 0.0000003,
+            "cacheWritePerToken": 0.00000375
+        },
+        "claude-3-5-haiku": {
+            "inputPerToken": 0.0000008,
+            "outputPerToken": 0.000004,
+            "cacheReadPerToken": 0.00000008,
+            "cacheWritePerToken": 0.000001
+        },
+        "claude-3-opus": {
+            "inputPerToken": 0.000015,
+            "outputPerToken": 0.000075,
+            "cacheReadPerToken": 0.0000015,
+            "cacheWritePerToken": 0.00001875
+        },
+        "gpt-5.5": {
+            "inputPerToken": 0.000005,
+            "outputPerToken": 0.00003,
+            "cacheReadPerToken": 0.0000005
+        },
+        "gpt-5.4": {
+            "inputPerToken": 0.0000025,
+            "outputPerToken": 0.000015,
+            "cacheReadPerToken": 0.00000025
+        },
+        "gpt-5.4-mini": {
+            "inputPerToken": 0.00000075,
+            "outputPerToken": 0.0000045,
+            "cacheReadPerToken": 0.000000075
+        },
+        "gpt-5.4-nano": {
+            "inputPerToken": 0.0000002,
+            "outputPerToken": 0.00000125,
+            "cacheReadPerToken": 0.00000002
+        },
+        "gpt-5": {
+            "inputPerToken": 0.00000125,
+            "outputPerToken": 0.00001,
+            "cacheReadPerToken": 0.000000125
+        },
+        "gpt-4.1": {
+            "inputPerToken": 0.000002,
+            "outputPerToken": 0.000008,
+            "cacheReadPerToken": 0.0000005
+        },
+        "gpt-4.1-mini": {
+            "inputPerToken": 0.0000004,
+            "outputPerToken": 0.0000016,
+            "cacheReadPerToken": 0.0000001
+        },
+        "gpt-4.1-nano": {
+            "inputPerToken": 0.0000001,
+            "outputPerToken": 0.0000004,
+            "cacheReadPerToken": 0.000000025
+        },
+        "gpt-4o": {
+            "inputPerToken": 0.0000025,
+            "outputPerToken": 0.00001,
+            "cacheReadPerToken": 0.00000125
+        },
+        "gpt-4o-mini": {
+            "inputPerToken": 0.00000015,
+            "outputPerToken": 0.0000006,
+            "cacheReadPerToken": 0.000000075
+        },
+        "o3": {
+            "inputPerToken": 0.000002,
+            "outputPerToken": 0.000008,
+            "cacheReadPerToken": 0.0000005
+        },
+        "o4-mini": {
+            "inputPerToken": 0.0000011,
+            "outputPerToken": 0.0000044,
+            "cacheReadPerToken": 0.000000275
+        },
+        "gemini-2.5-pro": {
+            "inputPerToken": 0.00000125,
+            "outputPerToken": 0.00001,
+            "cacheReadPerToken": 0.0000003125
+        },
+        "gemini-2.5-flash": {
+            "inputPerToken": 0.0000003,
+            "outputPerToken": 0.0000025,
+            "cacheReadPerToken": 0.000000075
+        },
+        "gemini-2.5-flash-lite": {
+            "inputPerToken": 0.0000001,
+            "outputPerToken": 0.0000004,
+            "cacheReadPerToken": 0.000000025
+        },
+        "gemini-1.5-pro": {
+            "inputPerToken": 0.00000125,
+            "outputPerToken": 0.000005,
+            "cacheReadPerToken": 0.0000003125
+        },
+        "gemini-1.5-flash": {
+            "inputPerToken": 0.000000075,
+            "outputPerToken": 0.0000003,
+            "cacheReadPerToken": 0.00000001875
+        }
+    }
+}

package/dist/lib/pricing/table.d.ts

@@ -0,0 +1,17 @@
+/** Per-token USD prices for a single model. Cache fields optional (not all vendors expose them). */
+export interface ModelPricing {
+    inputPerToken: number;
+    outputPerToken: number;
+    cacheReadPerToken?: number;
+    cacheWritePerToken?: number;
+}
+/** Date-stamped version of the pricing table (e.g. "2026-06-24"). */
+export declare const PRICING_VERSION: string;
+/**
+ * Resolve per-token pricing for a model id. Tolerant of vendor prefixes,
+ * version dashes, and date suffixes. Returns null when no canonical key is a
+ * substring of the normalized id (i.e. genuinely unknown model).
+ */
+export declare function getModelPricing(modelId: string): ModelPricing | null;
+/** List every canonical model id that carries a price. */
+export declare function listPricedModels(): string[];

package/dist/lib/pricing/table.js

@@ -0,0 +1,73 @@
+/**
+ * Offline, versioned per-model pricing table.
+ *
+ * The canonical data lives in `prices.json` (LiteLLM-style per-token USD map)
+ * and is imported with a `type: json` attribute so it survives `tsc` emit AND
+ * Node ESM's import-attribute requirement at runtime (the package is ESM).
+ *
+ * `getModelPricing` is prefix/suffix-tolerant: real model identifiers carry
+ * vendor prefixes (`us.anthropic.`), version dashes (`claude-opus-4-8`), and
+ * date suffixes (`-20250514`), none of which appear in the canonical keys. We
+ * normalize the input, then match against the LONGEST canonical key the
+ * normalized id contains so `claude-opus-4` wins over a hypothetical
+ * `claude-opus` when both are present.
+ */
+import pricesData from './prices.json' with { type: 'json' };
+const PRICES = pricesData;
+/** Date-stamped version of the pricing table (e.g. "2026-06-24"). */
+export const PRICING_VERSION = PRICES.version;
+const MODELS = PRICES.models;
+// Canonical keys sorted longest-first so containment matching prefers the most
+// specific key (e.g. "gemini-2.5-flash-lite" before "gemini-2.5-flash").
+const KEYS_BY_LENGTH = Object.keys(MODELS).sort((a, b) => b.length - a.length);
+/**
+ * Normalize a raw model id into the dash-delimited token space the canonical
+ * keys live in. Strips vendor prefixes (`anthropic/`, `us.anthropic.`,
+ * `models/`, `openai/`), lowercases, and collapses any non [a-z0-9.] run to a
+ * single dash so `claude-opus-4-8`, `Claude Opus 4`, and `claude.opus.4` all
+ * normalize to a comparable form.
+ */
+function normalizeModelId(modelId) {
+    let id = modelId.trim().toLowerCase();
+    // Drop a leading vendor segment: "anthropic/claude-..", "us.anthropic.claude-..",
+    // "google/gemini-..", "models/gemini-..", "openai/gpt-..".
+    id = id.replace(/^[a-z]+\//, ''); // "anthropic/x" -> "x"
+    id = id.replace(/^[a-z]+\.[a-z]+\./, ''); // "us.anthropic.x" -> "x"
+    id = id.replace(/^models\//, ''); // already handled, defensive
+    // Collapse separators to single dashes, keep dots (gpt-5.4) intact.
+    id = id.replace(/[\s_]+/g, '-').replace(/-+/g, '-');
+    return id;
+}
+/**
+ * Resolve per-token pricing for a model id. Tolerant of vendor prefixes,
+ * version dashes, and date suffixes. Returns null when no canonical key is a
+ * substring of the normalized id (i.e. genuinely unknown model).
+ */
+export function getModelPricing(modelId) {
+    if (!modelId)
+        return null;
+    const norm = normalizeModelId(modelId);
+    // Exact key first (fast path + unambiguous).
+    if (MODELS[norm])
+        return MODELS[norm];
+    // Containment match, longest canonical key wins. The canonical key must
+    // appear as a dash-bounded prefix of the normalized id so "claude-opus-4"
+    // matches "claude-opus-4-8" and "claude-opus-4-20250514" but a stray
+    // "gpt-4" inside "gpt-40-turbo-experimental" still requires the boundary.
+    for (const key of KEYS_BY_LENGTH) {
+        if (norm === key || norm.startsWith(key + '-') || norm.startsWith(key + '.')) {
+            return MODELS[key];
+        }
+    }
+    // Last resort: canonical key contained anywhere (handles "anthropic-claude-opus-4"
+    // style ids the prefix strip missed). Still longest-first.
+    for (const key of KEYS_BY_LENGTH) {
+        if (norm.includes(key))
+            return MODELS[key];
+    }
+    return null;
+}
+/** List every canonical model id that carries a price. */
+export function listPricedModels() {
+    return Object.keys(MODELS);
+}

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

@@ -0,0 +1,134 @@
+/**
+ * The secrets-agent: a local broker that holds resolved bundle env in memory
+ * after a single Touch ID unlock, so concurrent agent processes don't each pop
+ * their own prompt.
+ *
+ * Why this exists: every secret item carries a biometry access control, and
+ * macOS refuses to cache that across processes — N concurrent `agents run`
+ * spawns = N Touch ID prompts (see src/lib/secrets/bundles.ts). The Swift
+ * helper's LAContext only deduplicates reads *within one process*. This broker
+ * is the ssh-agent answer: `agents secrets unlock <bundle>` decrypts the bundle
+ * once (one prompt), ships the resolved env here, and every later read returns
+ * from memory over a user-only Unix socket — no prompt.
+ *
+ * Security model (deliberate): while a bundle is unlocked, any same-user
+ * process that can reach the socket reads it silently. That's strictly the same
+ * trust boundary the keychain already concedes (docs/secrets.md: the ACL is
+ * user-presence, not code-identity — any same-user process can pop the prompt
+ * and read), minus the visible prompt. We bound it with: explicit per-bundle
+ * opt-in (nothing is held unless you `unlock` it), an absolute TTL, auto-lock
+ * on screen-lock / sleep, and `agents secrets lock`. Nothing ever touches disk.
+ *
+ * macOS only: Linux libsecret has no biometry prompt, so there's nothing to
+ * deduplicate — every entry point here no-ops off darwin.
+ */
+import type { SecretsBundle } from './bundles.js';
+/** Default lifetime of an unlocked bundle when `--ttl` is not given. */
+export declare const DEFAULT_TTL_MS: number;
+export interface StoredBundle {
+    bundle: SecretsBundle;
+    env: Record<string, string>;
+    /** epoch ms; the entry is gone once Date.now() passes this. */
+    expiresAt: number;
+}
+/** One unlocked bundle as reported by `status`. */
+export interface AgentStatusEntry {
+    name: string;
+    expiresAt: number;
+    keyCount: number;
+}
+export type Request = {
+    cmd: 'ping';
+} | {
+    cmd: 'get';
+    name: string;
+} | {
+    cmd: 'load';
+    name: string;
+    bundle: SecretsBundle;
+    env: Record<string, string>;
+    ttlMs: number;
+} | {
+    cmd: 'lock';
+    name?: string;
+} | {
+    cmd: 'status';
+};
+export type Response = {
+    ok: true;
+    cmd: 'ping';
+    version: number;
+} | {
+    ok: true;
+    cmd: 'get';
+    hit: false;
+} | {
+    ok: true;
+    cmd: 'get';
+    hit: true;
+    bundle: SecretsBundle;
+    env: Record<string, string>;
+} | {
+    ok: true;
+    cmd: 'load';
+} | {
+    ok: true;
+    cmd: 'lock';
+    wiped: number;
+} | {
+    ok: true;
+    cmd: 'status';
+    entries: AgentStatusEntry[];
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Pure request handler over the in-memory store. Extracted so the store
+ * semantics (lazy expiry on get/status, lock-one vs lock-all, load TTL) are
+ * unit-testable with a controlled `now`, without a socket or a spawned process.
+ * Mutates `store` in place; returns the wire response.
+ */
+export declare function handleAgentRequest(store: Map<string, StoredBundle>, req: Request, now?: number): Response;
+/**
+ * Run the broker in the foreground. Spawned detached by ensureAgentRunning via
+ * `agents secrets _agent-run`. Holds the store in memory, serves the socket,
+ * sweeps expired entries, wipes on screen-lock/sleep, and self-exits when idle.
+ */
+export declare function runSecretsAgent(): Promise<void>;
+/** True if a broker socket exists at all. Cheap; gates the sync read so the
+ * never-unlocked path stays a single stat. */
+export declare function agentSocketExists(): boolean;
+/**
+ * Synchronous read for the hot path. Returns the cached resolved bundle, or
+ * null if the agent isn't running / doesn't hold this bundle / anything fails
+ * (soft — caller falls through to the real keychain). macOS only.
+ */
+export declare function agentGetSync(name: string): {
+    bundle: SecretsBundle;
+    env: Record<string, string>;
+} | null;
+/** True when `secrets.agent.auto` is enabled in agents.yaml. Best-effort; a
+ * missing/unreadable meta reads as off. */
+export declare function secretsAgentAutoEnabled(): boolean;
+/**
+ * Fire-and-forget: populate the broker with a freshly-resolved bundle so the
+ * NEXT process reads it without a prompt. Used by the auto-cache path after a
+ * real keychain read of a `session`-tier bundle. Adds no latency to the caller
+ * — it spawns the agent (if needed) and a detached loader, both unref'd, then
+ * returns immediately. Entirely best-effort; never throws. macOS only.
+ */
+export declare function agentAutoLoadSync(name: string, bundle: SecretsBundle, env: Record<string, string>, ttlMs: number): void;
+/** Store a resolved bundle in the broker. Returns false on transport failure. */
+export declare function agentLoad(name: string, bundle: SecretsBundle, env: Record<string, string>, ttlMs: number): Promise<boolean>;
+/** Wipe one bundle (or all if name omitted) from the broker. Returns the count
+ * wiped, or 0 when no broker is running. */
+export declare function agentLock(name?: string): Promise<number>;
+/** List currently-unlocked bundles, or [] when no broker is running. */
+export declare function agentStatus(): Promise<AgentStatusEntry[]>;
+/**
+ * Ensure a broker is running and reachable, spawning one detached if not.
+ * Returns true once the socket answers a ping. On protocol-version skew, kills
+ * the stale broker and respawns. macOS only.
+ */
+export declare function ensureAgentRunning(timeoutMs?: number): Promise<boolean>;