@phnx-labs/agents-cli 1.22.9 → 1.22.11

package/dist/lib/secrets/headless.js

@@ -5,22 +5,13 @@
  * importing bundles.ts (which already imports index.ts).
  */
 /**
- * True when the current process is a background / non-interactive context that
- * must NEVER raise a Keychain biometry prompt on the interactive user's screen —
- * a prompt nobody is watching. Two signals, either sufficient:
+ * True when the current process was structurally launched by an agent runtime
+ * that must NEVER raise a Keychain biometry prompt on the user's screen:
  *   - `AGENTS_RUNTIME` is `headless`, `teams`, or `terminal` — i.e. ANY agent
  *     launch, interactive included, and inherited by everything spawned beneath
  *     one (set on the child env by `agents run --headless`, scheduled routines,
  *     teammates, and interactive runs — see exec.ts:430, runner.ts,
  *     teams/agents.ts).
- *   - neither stdin nor stdout is a TTY (a detached/backgrounded task whose
- *     stdio is redirected to a log — e.g. a release script run in the
- *     background as `( ... ) >log 2>&1 </dev/null`).
- * `AGENTS_SECRETS_NO_PROMPT=1` forces headless-safe; `=0` force-allows a prompt
- * even in a non-TTY context. An `eval "$(agents secrets export X)"` typed in a
- * PLAIN shell has no AGENTS_RUNTIME, so it is not classified headless and still
- * prompts. Run beneath an agent it inherits AGENTS_RUNTIME and resolves
- * broker-only — the agent, not the human, is the caller there.
  *
  * Only **macOS keychain** reads pop an interactive Touch ID sheet — the secrets
  * broker itself is a no-op off darwin (see agent.ts), and libsecret (Linux) /
@@ -33,31 +24,12 @@
  * fast with an actionable error instead of hijacking Touch ID. This generalizes
  * the per-caller broker-only pattern used across the headless secrets readers.
  */
-export function isHeadlessSecretsContext(env = process.env, platform = process.platform, 
-// Injected so the TTY branch below is testable: it is the branch that decides a
-// plain human shell still prompts, which is this guard's entire safety argument,
-// and reading process.* directly made it unreachable from a test.
-tty = { stdin: process.stdin.isTTY, stdout: process.stdout.isTTY }) {
+export function isHeadlessSecretsContext(env = process.env, platform = process.platform) {
     if (platform !== 'darwin')
         return false; // no biometry prompt to suppress off-darwin
-    const override = env.AGENTS_SECRETS_NO_PROMPT;
-    if (override === '1')
-        return true;
-    if (override === '0')
-        return false;
-    // Every AGENT-LAUNCH runtime resolves broker-only, interactive included.
-    // `terminal` was missing, which made an agent terminal the one launch path
-    // still allowed to pop Touch ID: exec.ts sets AGENTS_RUNTIME='terminal' for an
-    // interactive run (exec.ts:430), that fell through to the TTY check below, and
-    // a TTY meant "a human is watching, so prompting is fine". It is not fine —
-    // opening a terminal is not a request to authenticate, and a launch that needs
-    // a locked bundle should say so and point at `agents secrets unlock`, not grab
-    // the fingerprint sensor. AGENTS_RUNTIME is INHERITED by everything spawned under
-    // an agent, so `agents secrets export` run beneath one resolves broker-only too —
-    // correctly: there the agent, not the human, is the caller. A plain shell carries
-    // no AGENTS_RUNTIME, so a person running it themselves still gets the sheet.
+    // Every agent-launch runtime resolves broker-only, interactive included.
     const runtime = env.AGENTS_RUNTIME;
     if (runtime === 'headless' || runtime === 'teams' || runtime === 'terminal')
         return true;
-    return !tty.stdin && !tty.stdout;
+    return false;
 }

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

@@ -143,6 +143,14 @@ export declare function healHmacKeyNoAclOnce(rec: HmacKeyRecord): boolean;
  * see readAndResolveBundleEnv.
  */
 export declare function keychainServiceAlias(item: string): string;
+/**
+ * One-shot per process: activate hashing on machines with nothing to move,
+ * finish a crash-interrupted delete phase (silent), and run the interactive
+ * one-time re-key when cleartext-named items exist and a human is present.
+ * Never throws — a failed attempt leaves the process on cleartext names
+ * (exact pre-#316 behavior) and the next process retries.
+ */
+export declare function maybeAutoRekey(): void;
 /** One re-keyed (or failed) item, by its old cleartext service name. */
 export interface RekeyPlanItem {
     oldService: string;

package/dist/lib/secrets/index.js

@@ -247,30 +247,7 @@ export function readHmacKeyRecord() {
     catch {
         return null;
     }
-    const record = parseHmacKeyRecord(raw);
-    // Converge a stale-ACL'd hmackey to silent, on the HOT read path. An old helper
-    // (pre the metadata/hmackey no-ACL migration fix) re-stamped this
-    // contractually-no-ACL item with a biometry ACL, so the read just above pops the
-    // generic "Agents CLI needs to authenticate" sheet on EVERY hashed lookup — the
-    // `agents devices list` stats probe the SessionStart hook runs, and every other
-    // background hashed read. `maybeAutoRekey`'s one-shot heal only fires on a
-    // cleartext-bundle resolve and is bypassed for the hmackey/hashed-name path
-    // (prepareServiceName returns early for HMAC_KEY_ITEM before maybeAutoRekey), so
-    // it never converged exactly these reads and the machine prompted forever.
-    // Re-store the record no-ACL once per machine here (the read that produced it has
-    // already happened — and already prompted if the item was ACL'd); every
-    // subsequent read, in this process and all future ones, is silent.
-    if (record && !record.healedNoAcl) {
-        try {
-            healHmacKeyNoAclOnce(record);
-            record.healedNoAcl = true;
-        }
-        catch {
-            // A failed no-ACL re-store leaves the item still ACL'd (a still-prompting
-            // read) rather than a silent wrong state; the next process retries.
-        }
-    }
-    return record;
+    return parseHmacKeyRecord(raw);
 }
 function writeHmacKeyRecord(rec) {
     // JSON.stringify drops undefined fields (used to clear pendingDeletes).
@@ -325,15 +302,13 @@ function resolveHashState() {
 export function keychainServiceAlias(item) {
     return prepareServiceName(item);
 }
-function prepareServiceName(item, opts) {
+function prepareServiceName(item) {
     if (rawScopeDepth > 0)
         return item;
     if (!isOurItem(item))
         return item;
     if (item === HMAC_KEY_ITEM || item.startsWith(HASHED_SERVICE_PREFIX))
         return item;
-    if (opts?.autoRekey)
-        maybeAutoRekey();
     const st = resolveHashState();
     if (!st.active || !st.key)
         return item;
@@ -354,7 +329,6 @@ function prepareListPrefix(prefix) {
         return { prefix };
     if (prefix.startsWith(HASHED_SERVICE_PREFIX))
         return { prefix };
-    maybeAutoRekey();
     const st = resolveHashState();
     if (!st.active || !st.key)
         return { prefix };
@@ -429,7 +403,7 @@ function finishPendingDeletes(rec) {
  * Never throws — a failed attempt leaves the process on cleartext names
  * (exact pre-#316 behavior) and the next process retries.
  */
-function maybeAutoRekey() {
+export function maybeAutoRekey() {
     if (autoRekeyAttempted || rekeyRunning || rawScopeDepth > 0)
         return;
     autoRekeyAttempted = true;
@@ -446,10 +420,14 @@ function maybeAutoRekey() {
         return;
     const st = resolveHashState();
     if (st.active) {
-        // The stale-ACL'd-hmackey heal now runs on the hot read path
-        // (readHmacKeyRecord), which the resolveHashState() above just went through —
-        // so st.record is already healed here regardless of how this machine reached
-        // "hashing active". Nothing to do but finish any pending deletes.
+        if (st.record && !st.record.healedNoAcl) {
+            try {
+                healHmacKeyNoAclOnce(st.record);
+            }
+            catch {
+                /* the next explicit unlock retries */
+            }
+        }
         if (st.record?.pendingDeletes?.length) {
             try {
                 finishPendingDeletes(st.record);
@@ -820,7 +798,7 @@ export function getKeychainToken(item, context = {}) {
     // Errors keep the requested (human-readable) name; the storage name may be
     // an opaque hash.
     const requested = item;
-    item = prepareServiceName(item, { autoRekey: true });
+    item = prepareServiceName(item);
     if (backend)
         return backend.get(item);
     assertRawKeychainReadAllowed(requested, context);
@@ -848,6 +826,7 @@ export function getKeychainToken(item, context = {}) {
             ...process.env,
             AGENTS_KEYCHAIN_PROMPT: keychainOperationPrompt(context),
             AGENTS_KEYCHAIN_PROMPT_BASE: keychainOperationPrompt({ ...context, duration: undefined }),
+            AGENTS_KEYCHAIN_SKIP_AUTH_UI: context.silentNoAcl ? '1' : '0',
         },
         stdio: ['ignore', 'pipe', 'pipe'],
     });
@@ -890,7 +869,7 @@ export function getKeychainTokens(items, context = {}) {
     // whether those were cleartext (hashed here) or already-hashed (enumerated).
     const requestedByStorage = new Map();
     const storageItems = items.map((item) => {
-        const storage = prepareServiceName(item, { autoRekey: true });
+        const storage = prepareServiceName(item);
         if (!requestedByStorage.has(storage))
             requestedByStorage.set(storage, item);
         return storage;
@@ -939,6 +918,7 @@ export function getKeychainTokens(items, context = {}) {
             ...process.env,
             AGENTS_KEYCHAIN_PROMPT: keychainOperationPrompt(context),
             AGENTS_KEYCHAIN_PROMPT_BASE: keychainOperationPrompt({ ...context, duration: undefined }),
+            AGENTS_KEYCHAIN_SKIP_AUTH_UI: context.silentNoAcl ? '1' : '0',
             // The signed helper's own vocabulary is unchanged (it predates the rename
             // and ships as a separately-versioned binary), so map to its legacy token.
             AGENTS_KEYCHAIN_DEFAULT_POLICY: (context.defaultPolicy ?? 'hold') === 'hold' ? 'daily' : context.defaultPolicy,
@@ -1037,7 +1017,7 @@ export function setKeychainToken(item, value, opts) {
     if (/[\x00=\r\n]/.test(item))
         throw new Error('Secret item name contains invalid characters.');
     const requested = item;
-    item = prepareServiceName(item, { autoRekey: true });
+    item = prepareServiceName(item);
     if (backend) {
         backend.set(item, value, opts);
         return;

package/dist/lib/share/config.js

@@ -9,7 +9,7 @@
 //   `cloudflare` bundle.
 import { randomBytes } from 'node:crypto';
 import { readMeta, updateMeta } from '../state.js';
-import { bundleExists, bundleItemStore, bundlePolicy, isHeadlessSecretsContext, keychainRef, readAndResolveBundleEnv, readBundle, writeBundle, } from '../secrets/bundles.js';
+import { bundleExists, bundleItemStore, bundlePolicy, keychainRef, readAndResolveBundleEnv, readBundle, writeBundle, } from '../secrets/bundles.js';
 import { secretsKeychainItem } from '../secrets/index.js';
 export const SHARE_BUNDLE = 'share';
 export const SHARE_TOKEN_KEY = 'WRITE_TOKEN';
@@ -76,10 +76,8 @@ export function storeWriteToken(token) {
 export function readWriteTokenFromBundle() {
     const { env } = readAndResolveBundleEnv(SHARE_BUNDLE, {
         caller: 'share',
-        // Explicit `agents share` command (a human published a file): a headless agent
-        // subprocess resolves broker-only, an interactive human may unlock. This is NOT
-        // an agent LAUNCH read (that is exec.ts's --secrets injection, always agentOnly).
-        agentOnly: isHeadlessSecretsContext(),
+        // Explicit share commands are reads, not authorization to authenticate.
+        agentOnly: true,
     });
     const token = env[SHARE_TOKEN_KEY];
     if (!token) {
@@ -136,8 +134,8 @@ export function readCloudflareCreds(bundle = DEFAULT_CF_BUNDLE, override) {
     }
     const { env } = readAndResolveBundleEnv(bundle, {
         caller: 'share',
-        // Explicit `agents share setup` provisioning read — not an agent launch.
-        agentOnly: isHeadlessSecretsContext(),
+        // Setup is still a read; only `agents secrets unlock` may authenticate.
+        agentOnly: true,
     });
     const find = (re) => {
         for (const [k, v] of Object.entries(env))

package/dist/lib/state.d.ts

@@ -113,7 +113,7 @@ export declare function getUserSecretsDir(): string;
  * value-free usage telemetry (which bundle was created/imported/exported/viewed/
  * accessed/unlocked, when, by whom), never a secret value. It is a derived index
  * fed FROM the emitSecretAudit chokepoint alongside the append-only
- * ~/.agents/events.jsonl audit log — the same way sessions.db indexes session
+ * ~/.agents/.history/events/events.jsonl audit log — the same way sessions.db indexes session
  * metadata off the real session flow — not a second write path.
  */
 export declare function getSecretsDbPath(): string;

package/dist/lib/state.js

@@ -372,7 +372,7 @@ export function getUserSecretsDir() { return USER_SECRETS_DIR; }
  * value-free usage telemetry (which bundle was created/imported/exported/viewed/
  * accessed/unlocked, when, by whom), never a secret value. It is a derived index
  * fed FROM the emitSecretAudit chokepoint alongside the append-only
- * ~/.agents/events.jsonl audit log — the same way sessions.db indexes session
+ * ~/.agents/.history/events/events.jsonl audit log — the same way sessions.db indexes session
  * metadata off the real session flow — not a second write path.
  */
 export function getSecretsDbPath() {

package/dist/lib/types.d.ts

@@ -79,7 +79,7 @@ export interface BudgetConfig {
     require_confirm_over?: number;
 }
 /** Preview features that users can opt into via `agents beta`. */
-export type BetaFeatureName = 'factory' | 'projects';
+export type BetaFeatureName = 'factory';
 /** Subset of chalk color names used for agent-specific terminal output. */
 export type ChalkColor = 'magenta' | 'green' | 'blue' | 'cyan' | 'yellowBright' | 'redBright' | 'whiteBright' | 'blueBright' | 'greenBright' | 'magentaBright' | 'cyanBright';
 /** Static configuration for a single agent -- paths, capabilities, and format conventions. */
@@ -610,6 +610,12 @@ export interface DiscoveredPlugin {
     commands: string[];
     /** Subagent .md files in the plugin's agents/ directory (names without extension). */
     agentDefs: string[];
+    /**
+     * Workflow directory names under the plugin's `workflows/` (each must contain
+     * WORKFLOW.md). Phase 5 packaging: plugins may package workflows as entrypoints;
+     * `agents run <name>` resolves them via project > user > plugin > extra > system.
+     */
+    workflows: string[];
     /** Memory fact basenames from the plugin's memory/ directory (without .md). */
     memory: string[];
     /** Executable files in the plugin's bin/ directory. */

package/dist/lib/workflows.d.ts

@@ -312,11 +312,25 @@ export declare const GROK_WORKFLOW_MARKER = "agents_workflow";
 export declare function transformWorkflowForGrok(workflowPath: string, name: string): string;
 /** Read the agents_workflow marker from a Grok `.rhai` file, if present. */
 export declare function grokWorkflowMarker(filePath: string): string | null;
+/**
+ * Plugin `workflows/` directories in discovery order (project → user → system →
+ * extra). Used by name resolution and listing so a plugin-packaged workflow is
+ * runnable via `agents run <name>` without a separate install into
+ * ~/.agents/workflows/ (Phase 5 packaging). Within the plugin band, project
+ * plugins beat user/system plugins (same first-hit-wins as other layers).
+ */
+export declare function listPluginWorkflowDirs(cwd?: string): string[];
+/**
+ * True when `ref` is a single bare workflow name (no path separators, no `..`).
+ * Name lookup must not path-join multi-segment or traversal refs into search roots.
+ */
+export declare function isBareWorkflowName(ref: string): boolean;
 /**
  * Resolve an `agents run <workflow>` reference.
  *
  * Directories are accepted anywhere on disk when they contain WORKFLOW.md.
- * Name lookup keeps the normal resource precedence: project > user > system > extras.
+ * Name lookup precedence (docs/07-entrypoints): project > user > plugin > extra > system.
+ * Bare name only; `name@plugin` disambiguation is a follow-up.
  */
 export declare function resolveWorkflowRef(ref: string, cwd?: string): string | null;
 /**
@@ -326,10 +340,11 @@ export declare function resolveWorkflowRef(ref: string, cwd?: string): string |
  */
 export declare function discoverWorkflowsFromRepo(repoPath: string): DiscoveredWorkflow[];
 /**
- * List all workflows in central storage.
- * User layer (~/.agents/workflows/) wins over system (~/.agents/.system/workflows/).
+ * List all workflows in central storage + plugin packages.
+ * Precedence: user > plugin > extra > system (first writer wins; project is
+ * cwd-scoped and handled by resolveWorkflowRef / the resource handler).
  */
-export declare function listInstalledWorkflows(): Map<string, InstalledWorkflow>;
+export declare function listInstalledWorkflows(cwd?: string): Map<string, InstalledWorkflow>;
 /** Copy a workflow directory into user central storage (~/.agents/workflows/<name>/). */
 export declare function installWorkflowCentrally(sourcePath: string, name: string): {
     success: boolean;

package/dist/lib/workflows.js

@@ -10,7 +10,7 @@ import * as os from 'os';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { capableAgents, supports } from './capabilities.js';
-import { getProjectAgentsDir, getSystemWorkflowsDir, getUserWorkflowsDir, getTrashWorkflowsDir, getEnabledExtraRepos, } from './state.js';
+import { getProjectAgentsDir, getSystemWorkflowsDir, getUserWorkflowsDir, getTrashWorkflowsDir, getEnabledExtraRepos, getPluginsDir, getSystemPluginsDir, getProjectPluginsDir, } from './state.js';
 import { listInstalledVersions, getVersionHomePath } from './versions.js';
 /**
  * Hard upper bound on items a single `for_each` expands, absent an explicit
@@ -522,22 +522,94 @@ function resolveWorkflowPath(ref, cwd) {
     const candidate = path.isAbsolute(expanded) ? expanded : path.resolve(cwd, expanded);
     return isWorkflowDir(candidate) ? candidate : null;
 }
+/**
+ * Plugin `workflows/` directories in discovery order (project → user → system →
+ * extra). Used by name resolution and listing so a plugin-packaged workflow is
+ * runnable via `agents run <name>` without a separate install into
+ * ~/.agents/workflows/ (Phase 5 packaging). Within the plugin band, project
+ * plugins beat user/system plugins (same first-hit-wins as other layers).
+ */
+export function listPluginWorkflowDirs(cwd = process.cwd()) {
+    const pluginRoots = [];
+    const pluginsDirs = [];
+    const projectPlugins = getProjectPluginsDir(cwd);
+    if (projectPlugins)
+        pluginsDirs.push(projectPlugins);
+    pluginsDirs.push(getPluginsDir(), getSystemPluginsDir());
+    for (const extra of getEnabledExtraRepos()) {
+        pluginsDirs.push(path.join(extra.dir, 'plugins'));
+    }
+    for (const pluginsDir of pluginsDirs) {
+        if (!fs.existsSync(pluginsDir))
+            continue;
+        let entries;
+        try {
+            entries = fs.readdirSync(pluginsDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.'))
+                continue;
+            // Directories and symlinks-to-directories (plugin marketplaces often symlink).
+            const pluginRoot = path.join(pluginsDir, entry.name);
+            let isDir = entry.isDirectory();
+            if (!isDir && entry.isSymbolicLink()) {
+                try {
+                    isDir = fs.statSync(pluginRoot).isDirectory();
+                }
+                catch {
+                    isDir = false;
+                }
+            }
+            if (!isDir)
+                continue;
+            const workflowsDir = path.join(pluginRoot, 'workflows');
+            if (fs.existsSync(workflowsDir))
+                pluginRoots.push(workflowsDir);
+        }
+    }
+    return pluginRoots;
+}
+/**
+ * True when `ref` is a single bare workflow name (no path separators, no `..`).
+ * Name lookup must not path-join multi-segment or traversal refs into search roots.
+ */
+export function isBareWorkflowName(ref) {
+    if (!ref || ref === '.' || ref === '..')
+        return false;
+    if (ref.includes('/') || ref.includes('\\'))
+        return false;
+    if (ref.includes('..'))
+        return false;
+    // Reject absolute paths (posix or Windows).
+    if (path.isAbsolute(ref))
+        return false;
+    return path.basename(ref) === ref;
+}
 /**
  * Resolve an `agents run <workflow>` reference.
  *
  * Directories are accepted anywhere on disk when they contain WORKFLOW.md.
- * Name lookup keeps the normal resource precedence: project > user > system > extras.
+ * Name lookup precedence (docs/07-entrypoints): project > user > plugin > extra > system.
+ * Bare name only; `name@plugin` disambiguation is a follow-up.
  */
 export function resolveWorkflowRef(ref, cwd = process.cwd()) {
     const direct = resolveWorkflowPath(ref, cwd);
     if (direct)
         return direct;
+    // Name lookup only — reject traversal / multi-segment so path.join(dir, ref)
+    // cannot escape a workflows root (absolute paths already handled above).
+    if (!isBareWorkflowName(ref))
+        return null;
     const projectAgentsDir = getProjectAgentsDir(cwd);
     const searchDirs = [
         ...(projectAgentsDir ? [path.join(projectAgentsDir, 'workflows')] : []),
         getUserWorkflowsDir(),
-        getSystemWorkflowsDir(),
+        ...listPluginWorkflowDirs(cwd),
         ...getEnabledExtraRepos().map(r => path.join(r.dir, 'workflows')),
+        getSystemWorkflowsDir(),
     ];
     for (const dir of searchDirs) {
         const workflowPath = path.join(dir, ref);
@@ -592,16 +664,18 @@ export function discoverWorkflowsFromRepo(repoPath) {
     return results;
 }
 /**
- * List all workflows in central storage.
- * User layer (~/.agents/workflows/) wins over system (~/.agents/.system/workflows/).
+ * List all workflows in central storage + plugin packages.
+ * Precedence: user > plugin > extra > system (first writer wins; project is
+ * cwd-scoped and handled by resolveWorkflowRef / the resource handler).
  */
-export function listInstalledWorkflows() {
+export function listInstalledWorkflows(cwd = process.cwd()) {
     const result = new Map();
     const extraRepos = getEnabledExtraRepos();
     const searchDirs = [
         getUserWorkflowsDir(),
-        getSystemWorkflowsDir(),
+        ...listPluginWorkflowDirs(cwd),
         ...extraRepos.map(r => path.join(r.dir, 'workflows')),
+        getSystemWorkflowsDir(),
     ];
     for (const dir of searchDirs) {
         if (!fs.existsSync(dir))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.9",
+  "version": "1.22.11",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",