@phnx-labs/agents-cli 1.18.0 → 1.18.2

package/dist/lib/staleness/index.js

@@ -0,0 +1,122 @@
+/**
+ * Staleness library entrypoint. Aggregates per-resource checkers into the
+ * two operations the rest of the codebase needs:
+ *
+ *   - `buildManifest(agent, version, cwd)` — snapshot current state.
+ *   - `isStale(manifest, agent, version, cwd)` — true when any tracked
+ *     resource has drifted from its stored fingerprint.
+ *
+ * `loadManifest` / `saveManifest` round-trip the on-disk JSON. The format
+ * version stays at 1; new optional fields (workflows, plugins) on old files
+ * read as empty maps which forces a single re-sync.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getVersionsDir } from '../state.js';
+import { commandsChecker } from './checkers/commands.js';
+import { skillsChecker } from './checkers/skills.js';
+import { hooksChecker } from './checkers/hooks.js';
+import { mcpChecker } from './checkers/mcp.js';
+import { subagentsChecker } from './checkers/subagents.js';
+import { workflowsChecker } from './checkers/workflows.js';
+import { pluginsChecker } from './checkers/plugins.js';
+import { buildPermissions, isPermissionsStale } from './checkers/permissions.js';
+import { buildRules, isRulesStale } from './checkers/rules.js';
+import { MANIFEST_VERSION, } from './types.js';
+import { nameSetDiffers } from './fingerprint.js';
+export { MANIFEST_VERSION } from './types.js';
+/**
+ * Standard checkers — uniform contract. Rules and permissions have extra
+ * context (agent/version, preset env) so they're wired explicitly below.
+ */
+const STANDARD_CHECKERS = [
+    { checker: commandsChecker, field: 'commands' },
+    { checker: skillsChecker, field: 'skills' },
+    { checker: hooksChecker, field: 'hooks' },
+    { checker: mcpChecker, field: 'mcp' },
+    { checker: subagentsChecker, field: 'subagents' },
+    { checker: workflowsChecker, field: 'workflows' },
+    { checker: pluginsChecker, field: 'plugins' },
+];
+// ─── Public API ──────────────────────────────────────────────────────────────
+function manifestPath(agent, version) {
+    return path.join(getVersionsDir(), agent, version, 'home', '.sync-manifest.json');
+}
+export function loadManifest(agent, version) {
+    const p = manifestPath(agent, version);
+    try {
+        const raw = JSON.parse(fs.readFileSync(p, 'utf-8'));
+        if (raw.v !== MANIFEST_VERSION)
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveManifest(agent, version, manifest) {
+    const p = manifestPath(agent, version);
+    const tmp = p + '.tmp';
+    try {
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(tmp, JSON.stringify(manifest, null, 2));
+        fs.renameSync(tmp, p);
+    }
+    catch {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch { /* ignore */ }
+    }
+}
+export function buildManifest(agent, version, cwd) {
+    const manifest = {
+        v: MANIFEST_VERSION,
+        syncedAt: new Date().toISOString(),
+        commands: {},
+        skills: {},
+        hooks: {},
+        rules: { files: {} },
+        mcp: {},
+        permissions: { groups: {}, permissionPreset: null },
+        subagents: {},
+        workflows: {},
+        plugins: {},
+    };
+    for (const { checker, field } of STANDARD_CHECKERS) {
+        const target = manifest[field];
+        for (const name of checker.listNames(cwd)) {
+            const entry = checker.build(name, cwd);
+            if (entry !== null)
+                target[name] = entry;
+        }
+    }
+    manifest.rules = buildRules(agent, version, cwd);
+    manifest.permissions = buildPermissions();
+    return manifest;
+}
+/**
+ * True when any tracked resource has drifted from the stored manifest.
+ * Walks every resource type in turn and returns true at the first miss —
+ * sync detection should be cheap when nothing changed.
+ */
+export function isStale(manifest, agent, version, cwd) {
+    for (const { checker, field } of STANDARD_CHECKERS) {
+        const storedMap = (manifest[field] ?? {});
+        const currentNames = checker.listNames(cwd);
+        if (nameSetDiffers(Object.keys(storedMap), currentNames))
+            return true;
+        for (const name of currentNames) {
+            const entry = storedMap[name];
+            if (entry === undefined)
+                return true;
+            if (!checker.isFresh(name, entry, cwd))
+                return true;
+        }
+    }
+    if (isPermissionsStale(manifest.permissions))
+        return true;
+    if (isRulesStale(manifest.rules, agent, version, cwd))
+        return true;
+    return false;
+}

package/dist/lib/staleness/layers.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Layer resolution for resources. Encapsulates which DotAgents repos a given
+ * resource type reads from and in what precedence. Centralized so every
+ * checker, plus the sync writer, agrees on the same set.
+ *
+ * Resolution model:
+ *   - "first-wins" (commands, skills, mcp, subagents, workflows, plugins):
+ *     project > user > system > extras. Same-named entries shadow.
+ *   - "first-wins, no project" (hooks): security exclusion — see
+ *     `src/lib/versions.ts:1832-1836` for the rationale. User > system > extras.
+ *   - "merged" (permissions): every layer contributes; first-wins on name.
+ *   - "composed" (rules): preset + subrules resolved per-name across layers.
+ */
+/** Layer of provenance for a single resource entry. */
+export type LayerScope = 'project' | 'user' | 'system' | 'extra';
+export interface Layer {
+    scope: LayerScope;
+    /** Absolute path of the repo root (e.g. `~/.agents`). */
+    base: string;
+    /** Set only when scope === 'extra'. */
+    alias?: string;
+}
+export declare function clearLayerCache(): void;
+/** All layers a "first-wins with project" resource consults, in precedence order. */
+export declare function firstWinsLayers(cwd: string): Layer[];
+/** Hooks-only: layers excluding project (security exclusion). */
+export declare function hookLayers(): Layer[];
+/**
+ * Resolve a single resource by name. Returns the first matching layer's
+ * absolute path plus the layer scope, or null when no layer has it.
+ */
+export declare function resolveByName(layers: Layer[], relative: string, predicate: (full: string) => boolean): {
+    path: string;
+    layer: Layer;
+} | null;
+/** Convenience: list names found by reading a relative subdir across all given layers. */
+export declare function listAcrossLayers(layers: Layer[], relative: string, filter: (name: string, fullPath: string) => boolean): string[];

package/dist/lib/staleness/layers.js

@@ -0,0 +1,100 @@
+/**
+ * Layer resolution for resources. Encapsulates which DotAgents repos a given
+ * resource type reads from and in what precedence. Centralized so every
+ * checker, plus the sync writer, agrees on the same set.
+ *
+ * Resolution model:
+ *   - "first-wins" (commands, skills, mcp, subagents, workflows, plugins):
+ *     project > user > system > extras. Same-named entries shadow.
+ *   - "first-wins, no project" (hooks): security exclusion — see
+ *     `src/lib/versions.ts:1832-1836` for the rationale. User > system > extras.
+ *   - "merged" (permissions): every layer contributes; first-wins on name.
+ *   - "composed" (rules): preset + subrules resolved per-name across layers.
+ */
+import * as path from 'path';
+import * as fs from 'fs';
+import { getProjectAgentsDir, getUserAgentsDir, getAgentsDir, getEnabledExtraRepos, } from '../state.js';
+// ─── Per-process memoization ─────────────────────────────────────────────────
+//
+// `firstWinsLayers(cwd)` and `hookLayers()` get called from every checker for
+// every resource — easily 50+ times per `isStale` call. Each call invokes
+// `getProjectAgentsDir(cwd)` (walks up the filesystem) and `getEnabledExtraRepos()`
+// (reads agents.yaml). Memoizing at process scope eliminates the redundancy.
+//
+// Safety: in a CLI invocation, neither cwd nor the user/system base dirs
+// change mid-process, so the cache is always correct. Tests that exercise
+// different HOMEs/cwds run in separate subprocesses (per `_harness.ts`), so
+// the module's process-scope cache resets between scenarios.
+//
+// `clearLayerCache()` is exposed for tests or long-running daemons that need
+// to force re-discovery.
+const firstWinsCache = new Map();
+let hookLayersCache = null;
+export function clearLayerCache() {
+    firstWinsCache.clear();
+    hookLayersCache = null;
+}
+/** All layers a "first-wins with project" resource consults, in precedence order. */
+export function firstWinsLayers(cwd) {
+    const cached = firstWinsCache.get(cwd);
+    if (cached)
+        return cached;
+    const layers = [];
+    const project = getProjectAgentsDir(cwd);
+    if (project)
+        layers.push({ scope: 'project', base: project });
+    layers.push({ scope: 'user', base: getUserAgentsDir() });
+    layers.push({ scope: 'system', base: getAgentsDir() });
+    for (const extra of getEnabledExtraRepos()) {
+        layers.push({ scope: 'extra', base: extra.dir, alias: extra.alias });
+    }
+    firstWinsCache.set(cwd, layers);
+    return layers;
+}
+/** Hooks-only: layers excluding project (security exclusion). */
+export function hookLayers() {
+    if (hookLayersCache)
+        return hookLayersCache;
+    const layers = [];
+    layers.push({ scope: 'user', base: getUserAgentsDir() });
+    layers.push({ scope: 'system', base: getAgentsDir() });
+    for (const extra of getEnabledExtraRepos()) {
+        layers.push({ scope: 'extra', base: extra.dir, alias: extra.alias });
+    }
+    hookLayersCache = layers;
+    return layers;
+}
+/**
+ * Resolve a single resource by name. Returns the first matching layer's
+ * absolute path plus the layer scope, or null when no layer has it.
+ */
+export function resolveByName(layers, relative, predicate) {
+    for (const layer of layers) {
+        const full = path.join(layer.base, relative);
+        if (predicate(full))
+            return { path: full, layer };
+    }
+    return null;
+}
+/** Convenience: list names found by reading a relative subdir across all given layers. */
+export function listAcrossLayers(layers, relative, filter) {
+    const seen = new Set();
+    for (const layer of layers) {
+        const dir = path.join(layer.base, relative);
+        let entries;
+        try {
+            entries = fs.readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            if (name.startsWith('.'))
+                continue;
+            if (!filter(name, path.join(dir, name)))
+                continue;
+            seen.add(name);
+        }
+    }
+    return Array.from(seen);
+}

package/dist/lib/staleness/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Public types for the staleness library. The on-disk manifest shape stays
+ * at `v: 1` for backward compatibility — see `src/lib/sync-manifest.ts` for
+ * the loader/saver that consumes these.
+ */
+import type { Fingerprint } from './fingerprint.js';
+export declare const MANIFEST_VERSION: 1;
+/** A single-file resource (commands, hooks, MCP server YAML, permission groups). */
+export interface FileEntry {
+    source: Fingerprint;
+}
+/** A directory resource (skills, subagents, workflows). */
+export interface DirEntry {
+    /** Winning source dir, absolute. */
+    dirPath: string;
+    /** All files inside the dir, sorted by absolute path. */
+    files: Fingerprint[];
+}
+/** Rules section — fingerprints of every source file (rules.yaml + active subrules). */
+export interface RulesEntry {
+    files: Record<string, FileEntry>;
+}
+/**
+ * Permissions section — merged across layers (every group across every scope
+ * contributes; same name first-wins user > system). Plus the active preset
+ * env value, since preset selection changes which groups are applied.
+ */
+export interface PermEntry {
+    groups: Record<string, FileEntry>;
+    permissionPreset: string | null;
+}
+/**
+ * Plugin entry. Plugins have a complex layout (`.claude-plugin/plugin.json`
+ * plus optional `skills/`, `commands/`, ...). We fingerprint the entire
+ * plugin root, same shape as a DirEntry.
+ */
+export type PluginEntry = DirEntry;
+/**
+ * Full manifest. `workflows` and `plugins` are optional so older v1 files
+ * stay loadable; missing fields are treated as empty maps — name-set diff
+ * then triggers a single re-sync that fills them in.
+ */
+export interface SyncManifest {
+    v: typeof MANIFEST_VERSION;
+    syncedAt: string;
+    commands: Record<string, FileEntry>;
+    skills: Record<string, DirEntry>;
+    hooks: Record<string, FileEntry>;
+    rules: RulesEntry;
+    mcp: Record<string, FileEntry>;
+    permissions: PermEntry;
+    subagents: Record<string, DirEntry>;
+    workflows?: Record<string, DirEntry>;
+    plugins?: Record<string, PluginEntry>;
+}
+export type ResourceType = 'commands' | 'skills' | 'hooks' | 'mcp' | 'rules' | 'subagents' | 'workflows' | 'plugins' | 'permissions';

package/dist/lib/staleness/types.js

@@ -0,0 +1,6 @@
+/**
+ * Public types for the staleness library. The on-disk manifest shape stays
+ * at `v: 1` for backward compatibility — see `src/lib/sync-manifest.ts` for
+ * the loader/saver that consumes these.
+ */
+export const MANIFEST_VERSION = 1;

package/dist/lib/state.d.ts

@@ -125,6 +125,8 @@ export declare function getSessionsDbPath(): string;
 export declare function getTeamsDir(): string;
 /** Path to teams execution history (~/.agents/.history/teams/agents/). */
 export declare function getTeamsAgentsDir(): string;
+/** Path to the team registry — list of named teams with timestamps. Durable runtime, per-machine. */
+export declare function getTeamsRegistryPath(): string;
 /** Path to cloud dispatch cache (~/.agents/.cache/cloud/). */
 export declare function getCloudDir(): string;
 /** Path to terminal session metadata (~/.agents/.cache/terminals/). */

package/dist/lib/state.js

@@ -282,6 +282,8 @@ export function getSessionsDbPath() { return SESSIONS_DB_PATH; }
 export function getTeamsDir() { return TEAMS_DIR; }
 /** Path to teams execution history (~/.agents/.history/teams/agents/). */
 export function getTeamsAgentsDir() { return TEAMS_AGENTS_DIR; }
+/** Path to the team registry — list of named teams with timestamps. Durable runtime, per-machine. */
+export function getTeamsRegistryPath() { return path.join(HISTORY_DIR, 'teams', 'registry.json'); }
 /** Path to cloud dispatch cache (~/.agents/.cache/cloud/). */
 export function getCloudDir() { return CLOUD_DIR; }
 /** Path to terminal session metadata (~/.agents/.cache/terminals/). */

package/dist/lib/teams/agents.d.ts

@@ -1,4 +1,3 @@
-import { type AgentConfig } from './persistence.js';
 import { AgentType } from './parsers.js';
 /**
  * Compute the Lowest Common Ancestor (LCA) of multiple file paths.
@@ -31,20 +30,10 @@ export type { AgentType } from './parsers.js';
  * Returns null on any error so callers can skip the guard rather than crash.
  */
 export declare function captureProcessStartTime(pid: number): string | null;
-export declare const AGENT_COMMANDS: Record<AgentType, string[]>;
 /**
- * Rewrite a plan-mode command into edit mode (writes inside cwd allowed,
- * approval prompts may still appear). Pure function — exported for tests.
- */
-export declare function applyEditMode(agentType: AgentType, cmd: string[]): string[];
-/**
- * Rewrite a plan-mode command into full mode (writes + approval gates
- * bypassed). Pure function — exported for tests.
- */
-export declare function applyFullMode(agentType: AgentType, cmd: string[]): string[];
-/**
- * Reasoning-intensity knob wired into buildReasoningFlags.
- * Does not select a model; use --model separately to pin a specific model per teammate.
+ * Reasoning-intensity knob. Passed through to `agents run --effort`, which
+ * translates it into per-agent reasoning flags (claude --effort, codex
+ * model_reasoning_effort override). Mode (plan/edit/full) is a separate knob.
  */
 export type EffortLevel = 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';
 declare const VALID_MODES: readonly ["plan", "edit", "full"];
@@ -165,16 +154,13 @@ export declare class AgentManager {
     private filterByCwd;
     private cleanupAgeDays;
     private defaultMode;
-    private agentConfigs;
-    private constructorAgentConfigs;
     private initPromise;
     private cloudDispatcher;
     private constructorAgentsDir;
-    constructor(maxAgents?: number, agentsDir?: string | null, defaultMode?: Mode | null, filterByCwd?: string | null, cleanupAgeDays?: number, agentConfigs?: Record<AgentType, AgentConfig> | null);
+    constructor(maxAgents?: number, agentsDir?: string | null, defaultMode?: Mode | null, filterByCwd?: string | null, cleanupAgeDays?: number);
     private initialize;
     private doInitialize;
     getDefaultMode(): Mode;
-    setModelOverrides(agentConfigs: Record<AgentType, AgentConfig>): void;
     /**
      * Register the callback used to dispatch cloud-backed teammates when their
      * --after deps resolve. Called once at CLI startup by `agents teams`.
@@ -206,9 +192,14 @@ export declare class AgentManager {
      * (returns empty list).
      */
     startReady(taskName: string): Promise<AgentProcess[]>;
+    /**
+     * Build the argv to spawn for a teammate. Delegates to `agents run` so the
+     * agent's CLI flags, version routing, mode handling (plan/edit/full), model
+     * injection, and reasoning-intensity flags are owned by a single canonical
+     * exec path (src/lib/exec.ts). The team runner just supplies prompt + mode
+     * and reads stream-json events off stdout.
+     */
     private buildCommand;
-    private applyEditMode;
-    private applyFullMode;
     get(agentId: string): Promise<AgentProcess | null>;
     /**
      * Resolve a teammate reference to a single agent_id within a team.