@phnx-labs/agents-cli 1.14.1 → 1.14.3

package/dist/lib/migrate.js

@@ -76,10 +76,87 @@ function migratePromptcutsIntoHooks() {
         catch { /* best-effort */ }
     }
 }
+/**
+ * Move installed agent versions from the legacy single-root layout
+ * (~/.agents/versions/<agent>/<ver>/) into the system root
+ * (~/.agents-system/versions/<agent>/<ver>/).
+ *
+ * Pre-split installs put binaries and home dirs under ~/.agents/. After the
+ * split, the system code only scans ~/.agents-system/versions/, so without
+ * this migration the versions become invisible to listInstalledVersions and
+ * every command that depends on it (view, prune, run).
+ *
+ * Idempotent and non-destructive: if a same-named dest already exists we
+ * leave the legacy copy in place so the user can reconcile manually.
+ */
+function migrateUserVersionsToSystem() {
+    const userVersions = path.join(USER_DIR, 'versions');
+    const sysVersions = path.join(SYSTEM_DIR, 'versions');
+    if (!fs.existsSync(userVersions))
+        return;
+    let movedCount = 0;
+    let skippedCount = 0;
+    let agentEntries;
+    try {
+        agentEntries = fs.readdirSync(userVersions, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const agent of agentEntries) {
+        if (!agent.isDirectory())
+            continue;
+        const srcAgentDir = path.join(userVersions, agent.name);
+        const dstAgentDir = path.join(sysVersions, agent.name);
+        try {
+            fs.mkdirSync(dstAgentDir, { recursive: true, mode: 0o700 });
+        }
+        catch { /* best-effort */ }
+        let verEntries;
+        try {
+            verEntries = fs.readdirSync(srcAgentDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const ver of verEntries) {
+            if (!ver.isDirectory())
+                continue;
+            const src = path.join(srcAgentDir, ver.name);
+            const dst = path.join(dstAgentDir, ver.name);
+            if (fs.existsSync(dst)) {
+                skippedCount++;
+                continue;
+            }
+            try {
+                fs.renameSync(src, dst);
+                movedCount++;
+            }
+            catch { /* best-effort, leave legacy in place */ }
+        }
+        try {
+            if (fs.readdirSync(srcAgentDir).length === 0)
+                fs.rmdirSync(srcAgentDir);
+        }
+        catch { /* best-effort */ }
+    }
+    try {
+        if (fs.readdirSync(userVersions).length === 0)
+            fs.rmdirSync(userVersions);
+    }
+    catch { /* best-effort */ }
+    if (movedCount > 0) {
+        console.log(`Migrated ${movedCount} version dir${movedCount === 1 ? '' : 's'} from ~/.agents/versions/ to ~/.agents-system/versions/`);
+    }
+    if (skippedCount > 0) {
+        console.log(`Skipped ${skippedCount} version dir${skippedCount === 1 ? '' : 's'} already present in ~/.agents-system/versions/ (kept legacy copy at ~/.agents/versions/)`);
+    }
+}
 /** Run all idempotent migrations. Safe to call multiple times. */
 export function runMigration() {
     migrateAgentsYaml();
     deleteSystemPromptsJson();
     migrateSystemConfigJson();
     migratePromptcutsIntoHooks();
+    migrateUserVersionsToSystem();
 }

package/dist/lib/pty-client.js

@@ -9,7 +9,7 @@ import * as fs from 'fs';
 import { spawn, execSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import * as path from 'path';
-import { getSocketPath, isPtyServerRunning } from './pty-server.js';
+import { getSocketPath, getPtyLogPath, isPtyServerRunning } from './pty-server.js';
 const CONNECT_TIMEOUT_MS = 5000;
 const RESPONSE_TIMEOUT_MS = 30000;
 /**
@@ -33,7 +33,7 @@ async function ensureServer() {
         return;
     // Find the entry point to spawn the server
     const { bin, args } = getServerSpawnArgs();
-    const logPath = path.join(path.dirname(getSocketPath()), 'pty.log');
+    const logPath = getPtyLogPath();
     const logFd = fs.openSync(logPath, 'a');
     const child = spawn(bin, args, {
         stdio: ['ignore', logFd, logFd],
@@ -57,7 +57,7 @@ async function ensureServer() {
         }
         await new Promise(r => setTimeout(r, 100));
     }
-    throw new Error('PTY server failed to start within 5 seconds. Check ~/.agents/pty.log');
+    throw new Error('PTY server failed to start within 5 seconds. Check ~/.agents-system/helpers/pty/logs.jsonl');
 }
 function getServerSpawnArgs() {
     // Prefer the dist/index.js from the same installation as this code.

package/dist/lib/pty-server.js

@@ -53,9 +53,12 @@ export function captureProcessStartTime(pid) {
 }
 // --- Constants ---
 const SENTINEL = '__AGENTS_PTY_DONE__';
+const PTY_DIR = 'helpers/pty';
 const SOCKET_NAME = 'pty.sock';
 const PID_FILE = 'pty.pid';
-const LOG_FILE = 'pty.log';
+const LOG_FILE = 'logs.jsonl';
+const LOG_MAX_SIZE = 5 * 1024 * 1024; // 5 MB
+const LOG_ROTATE_COUNT = 3;
 const SESSION_IDLE_MS = 30 * 60 * 1000; // 30 min
 const SERVER_IDLE_MS = 60 * 60 * 1000; // 1 hour
 // --- Path helpers ---
@@ -79,17 +82,24 @@ function buildPtyEnv() {
     }
     return env;
 }
+/** Get the PTY helper directory, creating it if needed. */
+function getPtyDir() {
+    const dir = path.join(getAgentsDir(), PTY_DIR);
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
 /** Get the unix socket path for the PTY server. */
 export function getSocketPath() {
-    return path.join(getAgentsDir(), SOCKET_NAME);
+    return path.join(getPtyDir(), SOCKET_NAME);
 }
 /** Get the path to the PTY server PID file. */
 export function getPtyPidPath() {
-    return path.join(getAgentsDir(), PID_FILE);
+    return path.join(getPtyDir(), PID_FILE);
 }
 /** Get the path to the PTY server log file. */
 export function getPtyLogPath() {
-    return path.join(getAgentsDir(), LOG_FILE);
+    const logDir = getPtyDir();
+    return path.join(logDir, LOG_FILE);
 }
 /** Check if the PTY server process is alive by probing the stored PID. */
 export function isPtyServerRunning() {
@@ -112,11 +122,30 @@ export function isPtyServerRunning() {
     }
 }
 // --- Logging ---
+function rotateLogsIfNeeded(logPath) {
+    try {
+        const stat = fs.statSync(logPath);
+        if (stat.size < LOG_MAX_SIZE)
+            return;
+        for (let i = LOG_ROTATE_COUNT - 1; i >= 1; i--) {
+            const older = `${logPath}.${i}`;
+            const newer = i === 1 ? logPath : `${logPath}.${i - 1}`;
+            if (fs.existsSync(newer)) {
+                fs.renameSync(newer, older);
+            }
+        }
+        if (fs.existsSync(logPath)) {
+            fs.renameSync(logPath, `${logPath}.1`);
+        }
+    }
+    catch { }
+}
 function log(level, message) {
-    const ts = new Date().toISOString();
-    const line = `[${ts}] [${level}] ${message}\n`;
+    const logPath = getPtyLogPath();
+    rotateLogsIfNeeded(logPath);
+    const entry = { ts: new Date().toISOString(), level, message };
     try {
-        fs.appendFileSync(getPtyLogPath(), line, 'utf-8');
+        fs.appendFileSync(logPath, JSON.stringify(entry) + '\n', 'utf-8');
     }
     catch { }
 }

package/dist/lib/resources.js

@@ -8,7 +8,7 @@ import { AGENTS, listInstalledMcpsWithScope } from './agents.js';
 import { listInstalledCommandsWithScope } from './commands.js';
 import { listInstalledSkillsWithScope } from './skills.js';
 import { listInstalledHooksWithScope } from './hooks.js';
-import { listInstalledInstructionsWithScope } from './memory.js';
+import { listInstalledInstructionsWithScope } from './rules/rules.js';
 import { getEffectiveHome } from './versions.js';
 import { listMcpServerConfigs } from './mcp.js';
 import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, } from './state.js';

package/dist/lib/rotate.d.ts

@@ -25,32 +25,51 @@ export interface RotateResult {
     excluded: RotateCandidate[];
 }
 export declare const RUN_STRATEGIES: RunStrategy[];
-/** Return a run strategy when the input is valid, otherwise null. */
+/**
+ * Return a run strategy when the input is valid, otherwise null.
+ *
+ * `'rotate'` is accepted as a deprecated alias for `'balanced'` so old yaml
+ * configs and `--strategy rotate` invocations keep working. The legacy alias
+ * normalizes to `'balanced'` and uses the weighted-random algorithm.
+ */
 export declare function normalizeRunStrategy(value: unknown): RunStrategy | null;
 /** Read project-local run strategy from the nearest agents.yaml, if present. */
 export declare function getProjectRunStrategy(agent: AgentId, startPath: string): RunStrategy | null;
-/** Resolve the configured strategy: project agents.yaml, then ~/.agents-system/agents.yaml, then pinned. */
+/**
+ * Resolve the configured strategy. Lookup order:
+ *   1. project-local agents.yaml (nearest to `startPath`)
+ *   2. ~/.agents-system/agents.yaml
+ *   3. default: `available` (use the pinned default version when healthy,
+ *      otherwise fall through to a healthy account so a single rate-limited
+ *      account doesn't block the run).
+ */
 export declare function getConfiguredRunStrategy(agent: AgentId, startPath?: string): RunStrategy;
 /** Persist the global run strategy used by bare `agents run <agent>`. */
 export declare function setGlobalRunStrategy(agent: AgentId, strategy: RunStrategy): void;
 /**
- * Pure selection: given a set of candidates, return the best one for the
- * next run. Kept separate from I/O so it can be unit-tested with fixtures.
+ * Pick a healthy candidate using weighted random by remaining capacity.
+ *
+ * Each healthy candidate gets weight = max(1, 100 - usedPercent) where
+ * usedPercent is the highest-utilized non-session window (week / sonnet_week
+ * for Claude). An account at 10% used gets weight 90; one at 90% used gets
+ * weight 10 — so the fresher account is 9× more likely to be picked. Over N
+ * calls, traffic distributes across healthy accounts proportional to their
+ * headroom, with no stampede on the lowest-usage one. Stateless — parallel
+ * callers naturally fan out via the random roll.
+ *
+ * Eligibility: signed in (email present), auth valid, and usage available
+ * (any non-session window strictly under 100%, or local flag not exhausted
+ * when no live snapshot exists).
+ *
+ * Dedupe: when multiple versions share an email, collapse to one candidate
+ * per email (the least-recently-active version). Prevents two parallel pods
+ * from "balancing" to different versions but hitting the same Anthropic
+ * account and both 429ing.
  *
- * Eligibility: signed in (email present) and not out of credits.
- * Dedupe: when multiple versions share an email (same Anthropic account
- * installed under several agent versions), collapse to one candidate per
- * email — the least-recently-active version. Without this, two parallel
- * pods could "rotate" to different versions but hit the same account and
- * both 429 against the same Anthropic quota.
- * Primary order: lowest live usage utilization wins. Least-recently-active is
- * the tie-breaker when usage is equal or unavailable. Never-used versions sort
- * oldest so fresh installs are tried before recently-used ones.
- * Tie-break: random — when two candidates share a `lastActive` timestamp
- * (common when N pods read the same snapshot), distribute across them so
- * parallel callers fan out instead of all picking the same version.
+ * Returns null if no candidate is eligible — callers fall back to the pinned
+ * version so behavior stays predictable.
  */
-export declare function pickRotateCandidate(candidates: RotateCandidate[]): RotateResult | null;
+export declare function pickBalancedCandidate(candidates: RotateCandidate[]): RotateResult | null;
 /**
  * Pick an available candidate. Prefers the configured pinned version when that
  * version has usage available; otherwise routes to the candidate with the most
@@ -58,19 +77,17 @@ export declare function pickRotateCandidate(candidates: RotateCandidate[]): Rota
  */
 export declare function pickAvailableCandidate(candidates: RotateCandidate[], preferredVersion?: string | null): RotateResult | null;
 /**
- * Rotate across installed versions of an agent and pick the best one for the
- * next run. "Best" means: signed in, usage available, and lowest usage
- * utilization, with least-recently-active as a tie-breaker.
+ * Pick a healthy version for `agent` using weighted random by remaining
+ * capacity. See `pickBalancedCandidate` for algorithm details.
  *
- * No external state: rotation and health are both read off per-version
- * AccountInfo — the same data `agents view` already surfaces. `lastActive`
- * advances naturally after each run, so the cursor is self-maintaining.
+ * No external state — health and capacity are both read off per-version
+ * AccountInfo (same data `agents view` surfaces). The weighted random roll
+ * keeps parallel callers fanned out without rotation files or locks.
  *
- * Returns null if no installed version is eligible (either nothing installed
- * or every account is exhausted / not signed in). Callers fall back to the
+ * Returns null if no installed version is eligible. Callers fall back to the
  * global default so behavior stays predictable — we never refuse to run.
  */
-export declare function selectRotateVersion(agent: AgentId): Promise<RotateResult | null>;
+export declare function selectBalancedVersion(agent: AgentId): Promise<RotateResult | null>;
 /** Select the configured version if available, otherwise another available version. */
 export declare function selectAvailableVersion(agent: AgentId, preferredVersion?: string | null): Promise<RotateResult | null>;
 export declare function resolveRunVersion(agent: AgentId, strategy: RunStrategy, cwd?: string): Promise<{

package/dist/lib/rotate.js

@@ -11,12 +11,26 @@ import { getAccountInfo } from './agents.js';
 import { readMeta, writeMeta, getAgentsDir } from './state.js';
 import { listInstalledVersions, getVersionHomePath, resolveVersion } from './versions.js';
 import { getUsageInfoByIdentity, getUsageLookupKey, isClaudeAuthValid, } from './usage.js';
-export const RUN_STRATEGIES = ['pinned', 'available', 'rotate'];
-/** Return a run strategy when the input is valid, otherwise null. */
+const ROTATE_DIR = 'helpers/rotate';
+function getRotateDir() {
+    const dir = path.join(getAgentsDir(), ROTATE_DIR);
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
+export const RUN_STRATEGIES = ['pinned', 'available', 'balanced'];
+/**
+ * Return a run strategy when the input is valid, otherwise null.
+ *
+ * `'rotate'` is accepted as a deprecated alias for `'balanced'` so old yaml
+ * configs and `--strategy rotate` invocations keep working. The legacy alias
+ * normalizes to `'balanced'` and uses the weighted-random algorithm.
+ */
 export function normalizeRunStrategy(value) {
-    return typeof value === 'string' && RUN_STRATEGIES.includes(value)
-        ? value
-        : null;
+    if (typeof value !== 'string')
+        return null;
+    if (value === 'rotate')
+        return 'balanced';
+    return RUN_STRATEGIES.includes(value) ? value : null;
 }
 /** Read project-local run strategy from the nearest agents.yaml, if present. */
 export function getProjectRunStrategy(agent, startPath) {
@@ -39,11 +53,18 @@ export function getProjectRunStrategy(agent, startPath) {
     }
     return null;
 }
-/** Resolve the configured strategy: project agents.yaml, then ~/.agents-system/agents.yaml, then pinned. */
+/**
+ * Resolve the configured strategy. Lookup order:
+ *   1. project-local agents.yaml (nearest to `startPath`)
+ *   2. ~/.agents-system/agents.yaml
+ *   3. default: `available` (use the pinned default version when healthy,
+ *      otherwise fall through to a healthy account so a single rate-limited
+ *      account doesn't block the run).
+ */
 export function getConfiguredRunStrategy(agent, startPath = process.cwd()) {
     return getProjectRunStrategy(agent, startPath)
         ?? normalizeRunStrategy(readMeta().run?.[agent]?.strategy)
-        ?? 'pinned';
+        ?? 'available';
 }
 /** Persist the global run strategy used by bare `agents run <agent>`. */
 export function setGlobalRunStrategy(agent, strategy) {
@@ -112,23 +133,29 @@ function dedupeAndSortCandidates(candidates) {
     return [...byEmail.values()].sort(compareCandidates);
 }
 /**
- * Pure selection: given a set of candidates, return the best one for the
- * next run. Kept separate from I/O so it can be unit-tested with fixtures.
+ * Pick a healthy candidate using weighted random by remaining capacity.
+ *
+ * Each healthy candidate gets weight = max(1, 100 - usedPercent) where
+ * usedPercent is the highest-utilized non-session window (week / sonnet_week
+ * for Claude). An account at 10% used gets weight 90; one at 90% used gets
+ * weight 10 — so the fresher account is 9× more likely to be picked. Over N
+ * calls, traffic distributes across healthy accounts proportional to their
+ * headroom, with no stampede on the lowest-usage one. Stateless — parallel
+ * callers naturally fan out via the random roll.
  *
- * Eligibility: signed in (email present) and not out of credits.
- * Dedupe: when multiple versions share an email (same Anthropic account
- * installed under several agent versions), collapse to one candidate per
- * email — the least-recently-active version. Without this, two parallel
- * pods could "rotate" to different versions but hit the same account and
- * both 429 against the same Anthropic quota.
- * Primary order: lowest live usage utilization wins. Least-recently-active is
- * the tie-breaker when usage is equal or unavailable. Never-used versions sort
- * oldest so fresh installs are tried before recently-used ones.
- * Tie-break: random — when two candidates share a `lastActive` timestamp
- * (common when N pods read the same snapshot), distribute across them so
- * parallel callers fan out instead of all picking the same version.
+ * Eligibility: signed in (email present), auth valid, and usage available
+ * (any non-session window strictly under 100%, or local flag not exhausted
+ * when no live snapshot exists).
+ *
+ * Dedupe: when multiple versions share an email, collapse to one candidate
+ * per email (the least-recently-active version). Prevents two parallel pods
+ * from "balancing" to different versions but hitting the same Anthropic
+ * account and both 429ing.
+ *
+ * Returns null if no candidate is eligible — callers fall back to the pinned
+ * version so behavior stays predictable.
  */
-export function pickRotateCandidate(candidates) {
+export function pickBalancedCandidate(candidates) {
     const healthy = [];
     const excluded = [];
     for (const c of candidates) {
@@ -146,7 +173,33 @@ export function pickRotateCandidate(candidates) {
         if (!deduped.has(c))
             excluded.push(c);
     }
-    return { picked: sorted[0], healthy: sorted, excluded };
+    const picked = weightedRandomByCapacity(sorted);
+    return { picked, healthy: sorted, excluded };
+}
+/**
+ * Pick one candidate from `sorted` using weights proportional to remaining
+ * routing capacity. Floor each weight at 1 so a near-exhausted-but-still-
+ * eligible candidate can still be picked occasionally. When usage is unknown
+ * (no live snapshot), treat the candidate as full-capacity (weight 100) — we
+ * have no signal to deprioritize it.
+ */
+function weightedRandomByCapacity(sorted) {
+    const weights = sorted.map((c) => {
+        const used = getRoutingUsedPercent(c.usageSnapshot);
+        if (used === null)
+            return 100;
+        return Math.max(1, 100 - used);
+    });
+    const total = weights.reduce((sum, w) => sum + w, 0);
+    if (total <= 0)
+        return sorted[0];
+    let roll = Math.random() * total;
+    for (let i = 0; i < sorted.length; i++) {
+        roll -= weights[i];
+        if (roll <= 0)
+            return sorted[i];
+    }
+    return sorted[sorted.length - 1];
 }
 /**
  * Pick an available candidate. Prefers the configured pinned version when that
@@ -210,20 +263,18 @@ async function collectRunCandidates(agent) {
     });
 }
 /**
- * Rotate across installed versions of an agent and pick the best one for the
- * next run. "Best" means: signed in, usage available, and lowest usage
- * utilization, with least-recently-active as a tie-breaker.
+ * Pick a healthy version for `agent` using weighted random by remaining
+ * capacity. See `pickBalancedCandidate` for algorithm details.
  *
- * No external state: rotation and health are both read off per-version
- * AccountInfo — the same data `agents view` already surfaces. `lastActive`
- * advances naturally after each run, so the cursor is self-maintaining.
+ * No external state — health and capacity are both read off per-version
+ * AccountInfo (same data `agents view` surfaces). The weighted random roll
+ * keeps parallel callers fanned out without rotation files or locks.
  *
- * Returns null if no installed version is eligible (either nothing installed
- * or every account is exhausted / not signed in). Callers fall back to the
+ * Returns null if no installed version is eligible. Callers fall back to the
  * global default so behavior stays predictable — we never refuse to run.
  */
-export async function selectRotateVersion(agent) {
-    return pickRotateCandidate(await collectRunCandidates(agent));
+export async function selectBalancedVersion(agent) {
+    return pickBalancedCandidate(await collectRunCandidates(agent));
 }
 /** Select the configured version if available, otherwise another available version. */
 export async function selectAvailableVersion(agent, preferredVersion) {
@@ -241,7 +292,7 @@ export async function selectAvailableVersion(agent, preferredVersion) {
  * a torn write just means the next reader sees a stale timestamp (harmless).
  */
 function recordRotationPick(agent, version) {
-    const stampPath = path.join(getAgentsDir(), `rotate-stamp-${agent}.json`);
+    const stampPath = path.join(getRotateDir(), `stamp-${agent}.json`);
     try {
         fs.writeFileSync(stampPath, JSON.stringify({ version, ts: Date.now() }), 'utf-8');
     }
@@ -252,7 +303,7 @@ function recordRotationPick(agent, version) {
  * or stamp is older than 60 seconds (stale).
  */
 function readRotationStamp(agent) {
-    const stampPath = path.join(getAgentsDir(), `rotate-stamp-${agent}.json`);
+    const stampPath = path.join(getRotateDir(), `stamp-${agent}.json`);
     try {
         const raw = JSON.parse(fs.readFileSync(stampPath, 'utf-8'));
         if (Date.now() - raw.ts < 60_000)
@@ -268,17 +319,21 @@ export async function resolveRunVersion(agent, strategy, cwd = process.cwd()) {
     }
     const rotation = strategy === 'available'
         ? await selectAvailableVersion(agent, fallback)
-        : await selectRotateVersion(agent);
+        : await selectBalancedVersion(agent);
     if (rotation) {
-        // If another process just picked the same version (within 60s), try the
-        // next healthy candidate to distribute load across accounts.
-        const recentPick = readRotationStamp(agent);
-        if (recentPick === rotation.picked.version && rotation.healthy.length > 1) {
-            const alt = rotation.healthy.find(c => c.version !== recentPick);
-            if (alt)
-                rotation.picked = alt;
+        // `available` is sticky to the pinned default when healthy. Use the 60s
+        // anti-collision stamp to nudge parallel callers off the same version.
+        // `balanced` doesn't need this — its weighted random roll already
+        // distributes naturally across healthy accounts.
+        if (strategy === 'available') {
+            const recentPick = readRotationStamp(agent);
+            if (recentPick === rotation.picked.version && rotation.healthy.length > 1) {
+                const alt = rotation.healthy.find(c => c.version !== recentPick);
+                if (alt)
+                    rotation.picked = alt;
+            }
+            recordRotationPick(agent, rotation.picked.version);
         }
-        recordRotationPick(agent, rotation.picked.version);
         return { version: rotation.picked.version, rotation };
     }
     return { version: fallback, rotation: null };

package/dist/lib/rules/compile.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Rules file compilation -- resolving @-imports into a single flat file.
+ *
+ * Agents that do not natively resolve `@path/to/file` imports (Codex, Cursor)
+ * need a pre-compiled rules file with all imports inlined. This module
+ * handles that expansion for both user-scope (writes into version home) and
+ * project-scope (writes into the workspace).
+ */
+import type { AgentId } from '../types.js';
+import { type RulesLayer } from './compose.js';
+/** Sidecar manifest recording source file hashes for staleness detection. */
+export interface CompileManifest {
+    compiledAt: string;
+    sources: {
+        path: string;
+        sha256: string;
+        mtime?: number;
+        size?: number;
+    }[];
+}
+/** Result of resolving @-imports in a rules file. */
+export interface ResolveResult {
+    /** Fully-inlined content. */
+    content: string;
+    /** Absolute paths of every file read during resolution (including the root). */
+    sources: string[];
+}
+/**
+ * Expand all `@path/to/file` imports in `content`, recursively up to
+ * MAX_DEPTH. Imports inside fenced code blocks and inline code spans are
+ * left alone, matching Claude Code's parser. Missing files are left as-is
+ * (silent skip), matching the documented behavior.
+ *
+ * Relative paths resolve against `baseDir`; absolute and tilde-prefixed
+ * paths resolve against the filesystem root / home directory.
+ */
+export declare function resolveImports(content: string, baseDir: string): ResolveResult;
+/** True if the agent's native runtime resolves `@path` imports in its rules file. */
+export declare function supportsRulesImports(agentId: AgentId): boolean;
+/**
+ * Fast staleness check. Returns true when:
+ *  - the compiled file or its manifest is missing
+ *  - any recorded source file is missing
+ *  - any recorded source's sha256 no longer matches
+ *
+ * For agents that support @-imports natively, always returns false — there's
+ * nothing to compile.
+ */
+export declare function isRulesStale(agentId: AgentId, version: string): boolean;
+/**
+ * Resolve the source `rules/AGENTS.md` (with all @-imports expanded) and
+ * write the result into the version home, alongside a sidecar manifest that
+ * records source file hashes for staleness detection.
+ *
+ * Agents that natively resolve @-imports are skipped (no-op) — their sync
+ * uses the standard copyFileSync path in `syncResourcesToVersion`.
+ */
+export declare function compileRulesForAgent(agentId: AgentId, version: string): {
+    compiled: boolean;
+    compiledPath: string;
+    sources: number;
+};
+/**
+ * Recompile rules if stale. Safe to call on every agent invocation — the
+ * staleness check is fast (sha256 of 8-10 small files, ~10-20ms). Returns
+ * true if a recompile happened, false otherwise.
+ */
+export declare function ensureRulesFresh(agentId: AgentId, version: string): boolean;
+export interface ProjectCompileResult {
+    /** True when cwd/AGENTS.md was newly written or rewritten. */
+    compiled: boolean;
+    /** Absolute path to cwd/AGENTS.md. Empty when no project rules dir was present. */
+    agentsPath: string;
+    /** Per-agent instruction filenames symlinked (or copied) to AGENTS.md. */
+    symlinks: string[];
+    /** Number of source files inlined (root + recursive @-imports). */
+    sources: number;
+    /** Per-agent files we left alone because the user wrote/owns them. */
+    skippedClobber: string[];
+}
+/**
+ * Compile project-scope rules into a workspace's root memory files so each
+ * agent's native loader picks them up.
+ *
+ * Composes rules from all available layers (project > user > extras > system)
+ * with project highest priority — so a project's `subrules/` and `rules.yaml`
+ * shadow user/system fragments and presets. Writes `cwd/AGENTS.md` with
+ * COMPILED_HEADER_PROJECT and creates symlinks (CLAUDE.md, GEMINI.md,
+ * .cursorrules, etc.) → AGENTS.md so every agent finds its expected file at
+ * cwd. The agent's own loader merges this project-level file with its
+ * user-level rules (in version home) at runtime.
+ *
+ * Don't-clobber guard: if `cwd/AGENTS.md` exists without our header, the user
+ * authored it — leave it alone and report via `skippedClobber`. Same for any
+ * pre-existing per-agent file or symlink that doesn't already point at
+ * AGENTS.md.
+ *
+ * No-op when `cwd/.agents/rules/` does not exist. Idempotent on repeated
+ * calls — content equality short-circuits the write.
+ */
+export declare function compileRulesForProject(cwd: string, opts?: {
+    preset?: string;
+    layers?: RulesLayer[];
+}): ProjectCompileResult;