@phnx-labs/agents-cli 1.16.0 → 1.17.0

package/dist/lib/session/discover.js

@@ -13,23 +13,22 @@ import * as crypto from 'crypto';
 import * as readline from 'readline';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
-import { getAgentsDir, getUserAgentsDir } from '../state.js';
+import { getAgentsDir, getHistoryDir } from '../state.js';
 const execFileAsync = promisify(execFile);
 import { AGENTS, getCliVersion } from '../agents.js';
 import { walkForFiles } from '../fs-walk.js';
 import { getConfigSymlinkVersion } from '../shims.js';
 import { SESSION_AGENTS } from './types.js';
 import { extractSessionTopic } from './prompt.js';
-import { getDB, getScanStampByPath, getScanStampsForPaths, recordScans, syncLabels, upsertSessionsBatch, querySessions, countSessions, ftsSearch, } from './db.js';
+import { getDB, getScanStampByPath, getScanStampsForPaths, recordScans, syncLabels, upsertSessionsBatch, querySessions, countSessions, ftsSearch, tryClaimScan, releaseScan, } from './db.js';
 const HOME = os.homedir();
 // Versions can live under either repo: the user repo (current canonical
-// location, ~/.agents/versions/) or the system repo (legacy / npm-shipped,
+// location, ~/.agents/.history/versions/) or the system repo (legacy / npm-shipped,
 // ~/.agents-system/versions/). Both must be scanned — sessions written by
 // any installed version end up in that version's projects/ dir, and the user
 // can be running one repo's version while another repo holds older versions
 // whose JSONLs the user still wants to search.
-const VERSIONS_ROOTS = [getUserAgentsDir(), getAgentsDir()];
-const AGENTS_DIR = getAgentsDir();
+const VERSIONS_ROOTS = [getHistoryDir(), getAgentsDir()];
 const RUSH_SESSIONS_DIR = path.join(HOME, '.rush', 'sessions');
 const HERMES_SESSIONS_DIR = path.join(HOME, '.hermes', 'sessions');
 /** How long OpenClaw channel/cron snapshots stay valid before we re-shell-out. */
@@ -39,24 +38,36 @@ const cachedAgentVersions = new Map();
 /**
  * Discover sessions. Scans only files whose (mtime, size) have changed since
  * the last run; everything else is served from the SQLite cache.
+ *
+ * Only one process runs the incremental scan at a time. When many agents boot
+ * simultaneously (e.g. after a restart), the first to claim the scan slot does
+ * the work; the rest skip parsing entirely and serve from the DB. The claim is
+ * stored in the `meta` table — crash-safe via dead-PID detection and a 2-min
+ * TTL, no external lock files needed.
  */
 export async function discoverSessions(options) {
     // Touch the DB so the schema is ready and connection is cached for this run.
     getDB();
     const agents = options?.agent ? [options.agent] : SESSION_AGENTS;
     const onProgress = options?.onProgress;
-    // Incrementally re-scan changed files across all selected agents in parallel.
-    await Promise.all(agents.map(agent => {
-        switch (agent) {
-            case 'claude': return scanClaudeIncremental(onProgress);
-            case 'codex': return scanCodexIncremental(onProgress);
-            case 'gemini': return scanGeminiIncremental(onProgress);
-            case 'opencode': return scanOpenCodeIncremental();
-            case 'openclaw': return scanOpenClawIncremental();
-            case 'rush': return scanRushIncremental(onProgress);
-            case 'hermes': return scanHermesIncremental(onProgress);
+    if (tryClaimScan(process.pid)) {
+        try {
+            await Promise.all(agents.map(agent => {
+                switch (agent) {
+                    case 'claude': return scanClaudeIncremental(onProgress);
+                    case 'codex': return scanCodexIncremental(onProgress);
+                    case 'gemini': return scanGeminiIncremental(onProgress);
+                    case 'opencode': return scanOpenCodeIncremental();
+                    case 'openclaw': return scanOpenClawIncremental();
+                    case 'rush': return scanRushIncremental(onProgress);
+                    case 'hermes': return scanHermesIncremental(onProgress);
+                }
+            }));
         }
-    }));
+        finally {
+            releaseScan(process.pid);
+        }
+    }
     const sessions = querySessions(buildQueryOptions(options, agents, { includeLimit: true }));
     return sessions;
 }
@@ -202,7 +213,7 @@ export function getAgentSessionDirs(agent, subdir) {
         }
         catch { /* dir unreadable */ }
     }
-    const backupsBase = path.join(AGENTS_DIR, 'backups', agent);
+    const backupsBase = path.join(getHistoryDir(), 'backups', agent);
     if (fs.existsSync(backupsBase)) {
         try {
             for (const ts of fs.readdirSync(backupsBase)) {

package/dist/lib/shims.d.ts

@@ -13,15 +13,6 @@ export interface ConflictInfo {
     version: string;
     conflicts: string[];
 }
-/**
- * Detect conflicting files between source and destination directories.
- * Returns list of filenames that exist in both locations (excluding symlinks in dest).
- */
-export declare function detectConflicts(src: string, dest: string, prefix?: string): string[];
-/**
- * Prompt user for conflict resolution strategy.
- */
-export declare function promptConflictStrategy(conflictInfos: ConflictInfo[]): Promise<ConflictStrategy | null>;
 /**
  * Generate the shim script content for an agent.
  *
@@ -57,8 +48,10 @@ export declare function promptConflictStrategy(conflictInfos: ConflictInfo[]): P
  *        and capability flag `memoryImports` → `rulesImports`.
  *   v8 — versions moved from ~/.agents-system/versions to ~/.agents/versions
  *        (two-repo split: system = shipped defaults, user = operational state).
+ *   v9 — claude shim exports CLAUDE_CODE_OAUTH_TOKEN from per-version
+ *        .oauth_token file on Linux (keychain-less sandbox fallback).
  */
-export declare const SHIM_SCHEMA_VERSION = 9;
+export declare const SHIM_SCHEMA_VERSION = 10;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.
@@ -128,14 +121,6 @@ export declare function removeVersionedAlias(agent: AgentId, version: string): b
  * Check if a versioned alias exists.
  */
 export declare function versionedAliasExists(agent: AgentId, version: string): boolean;
-/**
- * Detect conflicts that would occur when switching config symlink for an agent/version.
- * This allows collecting conflicts upfront before prompting for a strategy.
- *
- * Returns null if no migration is needed (already symlink or doesn't exist),
- * or ConflictInfo with the list of conflicting files.
- */
-export declare function detectMigrationConflicts(agent: AgentId, version: string): ConflictInfo | null;
 /**
  * Switch the agent's config symlink to point to a specific version.
  * e.g., ~/.claude -> ~/.agents/versions/claude/2.0.65/home/.claude/
@@ -185,14 +170,6 @@ export declare function switchHomeFileSymlinks(agent: AgentId, version: string):
  *   - Symlink points elsewhere: replace it.
  */
 export declare function ensureClaudeInsideSymlink(version: string): void;
-/**
- * Apply `ensureClaudeInsideSymlink` to every installed Claude version.
- * Safe to call repeatedly; per-version calls are idempotent.
- */
-export declare function ensureAllClaudeInsideSymlinks(): {
-    migrated: string[];
-    errors: string[];
-};
 /**
  * Get the current config symlink target version, if any.
  */
@@ -201,17 +178,6 @@ export declare function getConfigSymlinkVersion(agent: AgentId): string | null;
  * Check if shim exists for an agent.
  */
 export declare function shimExists(agent: AgentId): boolean;
-/**
- * Read the schema version embedded in an existing on-disk shim. Returns
- * `null` if the shim doesn't exist or has no version marker (pre-v2 shim).
- */
-export declare function readShimSchemaVersion(agent: AgentId): number | null;
-/**
- * True if the on-disk shim's schema version matches `SHIM_SCHEMA_VERSION`.
- * False means either the shim is missing, is pre-v2 (no marker), or is an
- * older version that needs regeneration.
- */
-export declare function isShimCurrent(agent: AgentId): boolean;
 /**
  * Regenerate the shim if it's missing or outdated. Returns a status describing
  * what happened — callers can surface a one-line notice to the user ("Updated
@@ -276,10 +242,6 @@ export declare function addShimsToPath(overrides?: {
     error?: string;
 };
 export declare function listAgentsWithInstalledVersions(): AgentId[];
-/**
- * Create shims for all installed agents.
- */
-export declare function ensureAllShims(): void;
 /**
  * Resource diff between two versions. Each field lists resources present in
  * the current version but missing from the target.
@@ -295,17 +257,7 @@ export interface ResourceDiff {
     }[];
     mcp: string[];
 }
-/**
- * Compare resources between two versions.
- * Returns resources that exist in currentVersion but not in targetVersion.
- */
-export declare function compareVersionResources(agent: AgentId, currentVersion: string, targetVersion: string): ResourceDiff;
 /**
  * Check if a ResourceDiff has any differences.
  */
 export declare function hasResourceDiff(diff: ResourceDiff): boolean;
-/**
- * Copy resources from one version to another.
- * Only copies resources listed in the diff (i.e., ones missing in target).
- */
-export declare function copyResourcesToVersion(agent: AgentId, fromVersion: string, toVersion: string, diff: ResourceDiff): void;

package/dist/lib/shims.js

@@ -44,7 +44,7 @@ function shouldIgnore(name) {
  * Detect conflicting files between source and destination directories.
  * Returns list of filenames that exist in both locations (excluding symlinks in dest).
  */
-export function detectConflicts(src, dest, prefix = '') {
+function detectConflicts(src, dest, prefix = '') {
     const conflicts = [];
     if (!fs.existsSync(src) || !fs.existsSync(dest)) {
         return conflicts;
@@ -93,7 +93,7 @@ export function detectConflicts(src, dest, prefix = '') {
 /**
  * Prompt user for conflict resolution strategy.
  */
-export async function promptConflictStrategy(conflictInfos) {
+async function promptConflictStrategy(conflictInfos) {
     const totalConflicts = conflictInfos.reduce((sum, info) => sum + info.conflicts.length, 0);
     if (totalConflicts === 0) {
         return null; // No conflicts, no prompt needed
@@ -171,8 +171,10 @@ export async function promptConflictStrategy(conflictInfos) {
  *        and capability flag `memoryImports` → `rulesImports`.
  *   v8 — versions moved from ~/.agents-system/versions to ~/.agents/versions
  *        (two-repo split: system = shipped defaults, user = operational state).
+ *   v9 — claude shim exports CLAUDE_CODE_OAUTH_TOKEN from per-version
+ *        .oauth_token file on Linux (keychain-less sandbox fallback).
  */
-export const SHIM_SCHEMA_VERSION = 9;
+export const SHIM_SCHEMA_VERSION = 10;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 /**
@@ -189,6 +191,12 @@ export function generateShimScript(agent) {
 # selected version's config directory so switching versions also switches the
 # live Claude account.
 export CLAUDE_CONFIG_DIR="$VERSION_DIR/home/${configDirName}"
+# On Linux sandboxes (no keychain), fall back to a per-version token file.
+# The env var always wins if already set; no-op on macOS.
+if [ "\$(uname -s)" = "Linux" ] && [ -z "\${CLAUDE_CODE_OAUTH_TOKEN:-}" ] && [ -f "\$CLAUDE_CONFIG_DIR/.oauth_token" ]; then
+  CLAUDE_CODE_OAUTH_TOKEN=\$(cat "\$CLAUDE_CONFIG_DIR/.oauth_token")
+  export CLAUDE_CODE_OAUTH_TOKEN
+fi
 `
         : agent === 'codex'
             ? `
@@ -543,7 +551,7 @@ function getVersionConfigPath(agent, version) {
  * Returns null if no migration is needed (already symlink or doesn't exist),
  * or ConflictInfo with the list of conflicting files.
  */
-export function detectMigrationConflicts(agent, version) {
+function detectMigrationConflicts(agent, version) {
     const configPath = getAgentConfigPath(agent);
     const versionConfigPath = getVersionConfigPath(agent, version);
     try {
@@ -837,7 +845,7 @@ export function ensureClaudeInsideSymlink(version) {
  * Apply `ensureClaudeInsideSymlink` to every installed Claude version.
  * Safe to call repeatedly; per-version calls are idempotent.
  */
-export function ensureAllClaudeInsideSymlinks() {
+function ensureAllClaudeInsideSymlinks() {
     const versionsDir = getVersionsDir();
     const claudeVersionsDir = path.join(versionsDir, 'claude');
     const migrated = [];
@@ -975,7 +983,7 @@ export function shimExists(agent) {
  * Read the schema version embedded in an existing on-disk shim. Returns
  * `null` if the shim doesn't exist or has no version marker (pre-v2 shim).
  */
-export function readShimSchemaVersion(agent) {
+function readShimSchemaVersion(agent) {
     if (!shimExists(agent))
         return null;
     try {
@@ -996,7 +1004,7 @@ export function readShimSchemaVersion(agent) {
  * False means either the shim is missing, is pre-v2 (no marker), or is an
  * older version that needs regeneration.
  */
-export function isShimCurrent(agent) {
+function isShimCurrent(agent) {
     const version = readShimSchemaVersion(agent);
     return version === SHIM_SCHEMA_VERSION;
 }
@@ -1309,7 +1317,7 @@ export function listAgentsWithInstalledVersions() {
 /**
  * Create shims for all installed agents.
  */
-export function ensureAllShims() {
+function ensureAllShims() {
     const versionsDir = getVersionsDir();
     if (!fs.existsSync(versionsDir)) {
         return;
@@ -1331,7 +1339,7 @@ export function ensureAllShims() {
  * Compare resources between two versions.
  * Returns resources that exist in currentVersion but not in targetVersion.
  */
-export function compareVersionResources(agent, currentVersion, targetVersion) {
+function compareVersionResources(agent, currentVersion, targetVersion) {
     const agentConfig = AGENTS[agent];
     const currentPath = getVersionConfigPath(agent, currentVersion);
     const targetPath = getVersionConfigPath(agent, targetVersion);
@@ -1420,7 +1428,7 @@ export function hasResourceDiff(diff) {
  * Copy resources from one version to another.
  * Only copies resources listed in the diff (i.e., ones missing in target).
  */
-export function copyResourcesToVersion(agent, fromVersion, toVersion, diff) {
+function copyResourcesToVersion(agent, fromVersion, toVersion, diff) {
     const agentConfig = AGENTS[agent];
     const fromPath = getVersionConfigPath(agent, fromVersion);
     const toPath = getVersionConfigPath(agent, toVersion);

package/dist/lib/sqlite.js

@@ -66,12 +66,18 @@ class Database {
     pragma(stmt) {
         this.inner.exec(`PRAGMA ${stmt}`);
     }
-    // Wrap fn in BEGIN/COMMIT, ROLLBACK on throw. Manual on both runtimes
-    // because node:sqlite has no `db.transaction(fn)` and the manual form is
-    // identical in shape to what better-sqlite3 / bun:sqlite produce.
+    // Wrap fn in BEGIN IMMEDIATE/COMMIT, ROLLBACK on throw. Manual on both
+    // runtimes because node:sqlite has no `db.transaction(fn)`.
+    //
+    // BEGIN IMMEDIATE (not BEGIN DEFERRED) is required for write transactions in
+    // WAL mode. BEGIN DEFERRED upgrades the lock lazily on the first write; if
+    // another writer already committed since the transaction started, SQLite
+    // returns SQLITE_BUSY_SNAPSHOT (a sub-code of SQLITE_BUSY that the busy
+    // handler does NOT retry). BEGIN IMMEDIATE claims the write lock upfront so
+    // the busy handler fires correctly and respects busy_timeout.
     transaction(fn) {
         return (...args) => {
-            this.inner.exec('BEGIN');
+            this.inner.exec('BEGIN IMMEDIATE');
             try {
                 const result = fn(...args);
                 this.inner.exec('COMMIT');

package/dist/lib/state.d.ts

@@ -89,6 +89,8 @@ export declare function getUserRulesDir(): string;
 export declare function getUserMcpDir(): string;
 export declare function getUserPermissionsDir(): string;
 export declare function getUserSubagentsDir(): string;
+export declare function getSystemWorkflowsDir(): string;
+export declare function getUserWorkflowsDir(): string;
 export declare function getUserSecretsDir(): string;
 export declare function getUserPromptcutsPath(): string;
 /** Bucket root for durable runtime data (~/.agents/.history/). */
@@ -163,6 +165,7 @@ export declare function getTrashHooksDir(): string;
 export declare function getTrashPluginsDir(): string;
 /** Path to soft-deleted subagents (~/.agents/trash/subagents/). */
 export declare function getTrashSubagentsDir(): string;
+export declare function getTrashWorkflowsDir(): string;
 /**
  * Path to a single user-level extra DotAgent repo clone (~/.agents-<alias>/).
  *
@@ -194,8 +197,18 @@ export declare function writeMeta(meta: Meta): void;
 export declare function updateMeta(updates: Partial<Meta>): Meta;
 /** Derive a filesystem-safe local clone path for a package source URL. */
 export declare function getPackageLocalPath(source: string): string;
-import type { AgentId, ResourceType, VersionResources } from './types.js';
-export declare function recordVersionResources(agent: AgentId, version: string, resourceType: ResourceType, resources: string[]): void;
+import type { AgentId, ResourceType, VersionResources, ResourcePattern } from './types.js';
+/**
+ * @deprecated No-op. Use ensureVersionResourcePatterns instead.
+ * Kept for backward compat with command files that still call it.
+ */
+export declare function recordVersionResources(_agent: AgentId, _version: string, _resourceType: ResourceType, _resources: string[]): void;
+/**
+ * Write default resource selection patterns for an agent@version.
+ * Only writes each field when it is not already set, preserving user customization.
+ * Pass all resource types you want to initialize in one call to batch the write.
+ */
+export declare function ensureVersionResourcePatterns(agent: AgentId, version: string, updates: Partial<Record<Exclude<keyof VersionResources, 'rulesPreset'>, ResourcePattern[]>>): void;
 export declare function getVersionResources(agent: AgentId, version: string): VersionResources | null;
 export declare function clearVersionResources(agent: AgentId, version: string): void;
 /** Active rules preset for an agent@version. Defaults to "default" when unset. */

package/dist/lib/state.js

@@ -23,7 +23,7 @@ import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
 import { SEEDED_REGISTRIES } from './types.js';
-const HOME = os.homedir();
+const HOME = process.env.HOME ?? os.homedir();
 // ─── Root directories ─────────────────────────────────────────────────────────
 /** System repo — npm-shipped, read-only from user commands. */
 const SYSTEM_AGENTS_DIR = path.join(HOME, '.agents-system');
@@ -41,6 +41,7 @@ const SYSTEM_RULES_DIR = path.join(SYSTEM_AGENTS_DIR, 'rules');
 const SYSTEM_MCP_DIR = path.join(SYSTEM_AGENTS_DIR, 'mcp');
 const SYSTEM_PERMISSIONS_DIR = path.join(SYSTEM_AGENTS_DIR, 'permissions');
 const SYSTEM_SUBAGENTS_DIR = path.join(SYSTEM_AGENTS_DIR, 'subagents');
+const SYSTEM_WORKFLOWS_DIR = path.join(SYSTEM_AGENTS_DIR, 'workflows');
 const SYSTEM_PROMPTCUTS_FILE = path.join(SYSTEM_AGENTS_DIR, 'hooks', 'promptcuts.yaml');
 const SYSTEM_MCP_CONFIG_FILE = path.join(SYSTEM_AGENTS_DIR, 'mcp.json');
 const SYSTEM_INSTRUCTIONS_FILE = path.join(SYSTEM_AGENTS_DIR, 'instructions.md');
@@ -88,6 +89,7 @@ const USER_RULES_DIR = path.join(USER_AGENTS_DIR, 'rules');
 const USER_MCP_DIR = path.join(USER_AGENTS_DIR, 'mcp');
 const USER_PERMISSIONS_DIR = path.join(USER_AGENTS_DIR, 'permissions');
 const USER_SUBAGENTS_DIR = path.join(USER_AGENTS_DIR, 'subagents');
+const USER_WORKFLOWS_DIR = path.join(USER_AGENTS_DIR, 'workflows');
 const USER_SECRETS_DIR = path.join(USER_AGENTS_DIR, 'secrets');
 const USER_PROMPTCUTS_FILE = path.join(USER_AGENTS_DIR, 'hooks', 'promptcuts.yaml');
 const META_HEADER = `# agents-cli metadata
@@ -238,6 +240,8 @@ export function getUserRulesDir() { return USER_RULES_DIR; }
 export function getUserMcpDir() { return USER_MCP_DIR; }
 export function getUserPermissionsDir() { return USER_PERMISSIONS_DIR; }
 export function getUserSubagentsDir() { return USER_SUBAGENTS_DIR; }
+export function getSystemWorkflowsDir() { return SYSTEM_WORKFLOWS_DIR; }
+export function getUserWorkflowsDir() { return USER_WORKFLOWS_DIR; }
 export function getUserSecretsDir() { return USER_SECRETS_DIR; }
 export function getUserPromptcutsPath() { return USER_PROMPTCUTS_FILE; }
 // ─── User operational path getters ────────────────────────────────────────────
@@ -316,6 +320,7 @@ export function getTrashHooksDir() { return path.join(TRASH_DIR, 'hooks'); }
 export function getTrashPluginsDir() { return path.join(TRASH_DIR, 'plugins'); }
 /** Path to soft-deleted subagents (~/.agents/trash/subagents/). */
 export function getTrashSubagentsDir() { return path.join(TRASH_DIR, 'subagents'); }
+export function getTrashWorkflowsDir() { return path.join(TRASH_DIR, 'workflows'); }
 /**
  * Path to a single user-level extra DotAgent repo clone (~/.agents-<alias>/).
  *
@@ -552,9 +557,19 @@ export function getPackageLocalPath(source) {
         .replace(/\//g, '-');
     return path.join(PACKAGES_DIR, sanitized);
 }
-export function recordVersionResources(agent, version, resourceType, resources) {
-    if (resources.length === 0)
-        return;
+/**
+ * @deprecated No-op. Use ensureVersionResourcePatterns instead.
+ * Kept for backward compat with command files that still call it.
+ */
+export function recordVersionResources(_agent, _version, _resourceType, _resources) {
+    // intentional no-op — tracking moved to pattern-based ensureVersionResourcePatterns
+}
+/**
+ * Write default resource selection patterns for an agent@version.
+ * Only writes each field when it is not already set, preserving user customization.
+ * Pass all resource types you want to initialize in one call to batch the write.
+ */
+export function ensureVersionResourcePatterns(agent, version, updates) {
     const meta = readMeta();
     if (!meta.versions)
         meta.versions = {};
@@ -562,10 +577,16 @@ export function recordVersionResources(agent, version, resourceType, resources)
         meta.versions[agent] = {};
     if (!meta.versions[agent][version])
         meta.versions[agent][version] = {};
-    const existing = meta.versions[agent][version][resourceType] || [];
-    const merged = [...new Set([...existing, ...resources])];
-    meta.versions[agent][version][resourceType] = merged;
-    writeMeta(meta);
+    const vr = meta.versions[agent][version];
+    let changed = false;
+    for (const [type, patterns] of Object.entries(updates)) {
+        if (!vr[type] || vr[type].length === 0) {
+            vr[type] = patterns;
+            changed = true;
+        }
+    }
+    if (changed)
+        writeMeta(meta);
 }
 export function getVersionResources(agent, version) {
     const meta = readMeta();

package/dist/lib/types.d.ts

@@ -288,30 +288,49 @@ export interface ResolvedPackage {
     skillEntry?: SkillEntry;
 }
 /** Categories of resources that can be synced into an agent version home. */
-export type ResourceType = 'commands' | 'skills' | 'hooks' | 'memory' | 'mcp' | 'permissions' | 'subagents' | 'plugins';
-/** Map of resource names synced to a specific agent version, keyed by type. */
+export type ResourceType = 'commands' | 'skills' | 'hooks' | 'memory' | 'mcp' | 'permissions' | 'subagents' | 'plugins' | 'workflows';
+/**
+ * A resource selection pattern stored in agents.yaml versions:
+ *   "system:*"      — all resources from ~/.agents-system/
+ *   "user:*"        — all resources from ~/.agents/
+ *   "rush:*"        — all resources from ~/.agents-rush/  (extra repo alias)
+ *   "project:*"     — all resources from .agents/ in the project root
+ *   "user:foo"      — specifically "foo" from ~/.agents/
+ *   "!user:temp"    — exclude "temp" from the user repo
+ */
+export type ResourcePattern = string;
+/** Sync specification for a specific agent@version, keyed by resource type. */
 export interface VersionResources {
-    commands?: string[];
-    skills?: string[];
-    hooks?: string[];
-    memory?: string[];
-    mcp?: string[];
-    permissions?: string[];
-    subagents?: string[];
-    plugins?: string[];
     /**
-     * Active rule preset for this agent@version. The composer reads layered
-     * `rules.yaml` files and emits this preset's subrules as the agent's
-     * single instruction file. Absent/null means the literal "default" preset.
+     * Active rule preset. Absent/null means "default".
      */
     rulesPreset?: string;
+    skills?: ResourcePattern[];
+    commands?: ResourcePattern[];
+    hooks?: ResourcePattern[];
+    subagents?: ResourcePattern[];
+    plugins?: ResourcePattern[];
+    workflows?: ResourcePattern[];
+    permissions?: ResourcePattern[];
+    mcp?: ResourcePattern[];
+}
+/** A userConfig field declared in a plugin manifest. */
+export interface PluginUserConfigField {
+    key: string;
+    description: string;
+    required?: boolean;
+    default?: string;
 }
-/** Manifest file (plugin.yaml) at the root of a plugin bundle. */
+/** Manifest file (plugin.json) at the root of a plugin bundle. */
 export interface PluginManifest {
     name: string;
     description: string;
     version: string;
     agents?: AgentId[];
+    /** Interactive config fields prompted at install time. Values stored in .user-config.json. */
+    userConfig?: PluginUserConfigField[];
+    /** Other plugin names this plugin depends on. Missing deps produce a warning. */
+    dependencies?: string[];
 }
 /** A plugin found on disk with its parsed manifest and resource inventory. */
 export interface DiscoveredPlugin {
@@ -321,6 +340,16 @@ export interface DiscoveredPlugin {
     skills: string[];
     hooks: string[];
     scripts: string[];
+    /** Slash-command .md files in the plugin's commands/ directory (names without extension). */
+    commands: string[];
+    /** Subagent .md files in the plugin's agents/ directory (names without extension). */
+    agentDefs: string[];
+    /** Executable files in the plugin's bin/ directory. */
+    bin: string[];
+    /** Whether the plugin root contains a .mcp.json file. */
+    hasMcp: boolean;
+    /** Whether the plugin root contains a settings.json with non-permission keys to merge. */
+    hasSettings: boolean;
 }
 /** Frontmatter fields parsed from a subagent's agent.md file. */
 export interface SubagentFrontmatter {

package/dist/lib/versions.d.ts

@@ -15,6 +15,7 @@ export interface ResourceSelection {
     permissions?: string[] | 'all';
     subagents?: string[] | 'all';
     plugins?: string[] | 'all';
+    workflows?: string[] | 'all';
 }
 /**
  * Available resources in ~/.agents/ for syncing.
@@ -33,6 +34,7 @@ export interface AvailableResources {
     permissions: string[];
     subagents: string[];
     plugins: string[];
+    workflows: string[];
     promptcuts: boolean;
 }
 /**
@@ -215,6 +217,7 @@ export interface SyncResult {
     mcp: string[];
     subagents: string[];
     plugins: string[];
+    workflows: string[];
 }
 /** Diff between central ~/.agents/ resources and what is synced to a version home. */
 export interface ResourceDiff {