@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/resources/workflows.js

@@ -1,10 +1,3 @@
-/**
- * Workflows resource handler.
- *
- * Workflows are directory bundles with a WORKFLOW.md containing YAML frontmatter.
- * They optionally contain subagents/, skills/, and plugins/ subdirectories.
- * Resolution order (docs/07-entrypoints): project > user > plugin > extra > system.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { getProjectAgentsDir, getUserWorkflowsDir, getSystemWorkflowsDir, getEnabledExtraRepos, } from '../state.js';
@@ -32,7 +25,6 @@ function listWorkflowsInDir(dir) {
         return [];
     }
 }
-/** Precedence-ordered (dir, layer) pairs for name lookup / listing. */
 function orderedWorkflowSearchDirs(cwd) {
     const dirs = getLayerDirs(cwd);
     const out = [];
@@ -47,7 +39,6 @@ function orderedWorkflowSearchDirs(cwd) {
     out.push({ dir: dirs.system, layer: 'system' });
     return out;
 }
-/** Map a resolved absolute workflow dir to its origin layer (best-effort). */
 function layerForWorkflowPath(workflowPath, cwd) {
     const abs = path.resolve(workflowPath);
     const under = (root) => {
@@ -65,7 +56,6 @@ function layerForWorkflowPath(workflowPath, cwd) {
         if (under(path.join(extra.dir, 'workflows')))
             return 'system';
     }
-    // Plugin marketplaces (and anything else plugin-shaped).
     return 'plugin';
 }
 class WorkflowsHandlerImpl {
@@ -97,7 +87,6 @@ class WorkflowsHandlerImpl {
         return results.sort((a, b) => a.name.localeCompare(b.name));
     }
     resolve(_agent, name, cwd) {
-        // Delegate to resolveWorkflowRef so bare, workflow:, and name@source share one path.
         const workflowPath = resolveWorkflowRef(name, cwd ?? process.cwd());
         if (!workflowPath)
             return null;
@@ -119,8 +108,6 @@ class WorkflowsHandlerImpl {
         };
     }
     sync(_agent, _versionHome, _cwd) {
-        // Version-home copies are written by syncResourcesToVersion in versions.ts.
-        // exec.ts resolves workflows at run time from source dirs directly.
     }
     format(_agent) {
         return 'md';

package/dist/lib/resources.d.ts

@@ -1,89 +1,31 @@
-/**
- * Unified resource discovery for agents.
- * Scans filesystem (source of truth) to find all installed resources for an agent.
- */
 import type { AgentId } from './types.js';
 import { type SkillParseError } from './plugins/skills.js';
-/** Resource kind — matches the subdirectory name under each repo root. */
 export type ResourceKind = 'commands' | 'skills' | 'hooks' | 'rules' | 'mcp' | 'clis' | 'permissions' | 'subagents' | 'workflows' | 'profiles' | 'routers' | 'secrets';
-/** A resource resolved with its origin. */
 export interface ResolvedResource {
     name: string;
-    /** Absolute path to the resource file or directory. */
     path: string;
-    /**
-     * Source layer: 'project' | 'user' | 'system' for built-in layers,
-     * or the alias name (e.g. 'rush') for extra repos registered in agents.yaml.
-     */
     source: string;
-    /**
-     * Absolute path to the DotAgents repo root this resource resolved from (the
-     * project/user/system/extra-repo dir — one level above the `kind`
-     * subdirectory). DotAgents repos are git-tracked (plugins.ts), so this pairs
-     * with {@link snapshotSha} to answer "which commit of which repo".
-     */
     repoRoot: string;
-    /**
-     * Short HEAD sha of `repoRoot`'s git checkout, lazily resolved (a getter,
-     * not computed at construction) and memoized per repoRoot
-     * (`git.ts` `resolveSnapshotSha`) — a caller that never inspects provenance
-     * never pays for the git shell-out, and resolving many resources from the
-     * same repo pays for exactly one. `undefined` when `repoRoot` isn't a git
-     * repo (or has no commits).
-     */
     readonly snapshotSha: string | undefined;
-    /**
-     * Alternate names this resource declares in its frontmatter `aliases:`, which
-     * {@link resolveResource} matches in addition to the canonical name. Lazily
-     * read from disk on first access and memoized, so listing resources never pays
-     * for it unless a caller inspects an alias. `undefined` when the resource
-     * declares none (or for a kind that doesn't support aliases — only `skills` and
-     * `commands` do), mirroring {@link snapshotSha} so a strict `toEqual` on a
-     * ResolvedResource ignores the absent field.
-     */
     readonly aliases: string[] | undefined;
 }
-/**
- * True when `rawName` (a filename with its extension already stripped) names a
- * directory doc rather than a resource of `kind`. Exported so every enumerator
- * shares one definition — `listCentralCommands` and `discoverCommands` in
- * `commands.ts` do their own `readdirSync` scans, and without this they would
- * list a `README` that `resolveResource` then refuses to open.
- */
 export declare function isDirectoryDoc(kind: ResourceKind, rawName: string): boolean;
-/**
- * Resolve a single resource by kind + name using project > user > system precedence.
- * For file-based resources the path ends in `.md`, `.yaml`, or `.yml` as appropriate.
- * Returns null when the resource does not exist in any scope.
- *
- * Extra repos are searched last (after system) to match syncResourcesToVersion order.
- */
 export declare function resolveResource(kind: ResourceKind, name: string, cwd?: string): ResolvedResource | null;
-/**
- * List all resources of a given kind across project, user, and system scopes.
- * Returns a deduplicated union (project wins on name collision), each entry
- * annotated with its origin source.
- */
 export declare function listResources(kind: ResourceKind, cwd?: string): ResolvedResource[];
-/** A single installed resource (command, skill, memory file, or hook). */
 export interface ResourceEntry {
     name: string;
     path: string;
     scope: 'user' | 'project';
-    /** One-line description pulled from frontmatter; not all resource kinds have one. */
     description?: string;
 }
-/** A skill resource entry with optional rule count. */
 export interface SkillResourceEntry extends ResourceEntry {
     ruleCount?: number;
 }
-/** An MCP server resource entry. */
 interface McpResourceEntry {
     name: string;
     scope: 'user' | 'project';
     version?: string;
 }
-/** All resources installed for a specific agent. */
 interface AgentResources {
     agentId: AgentId;
     commands: ResourceEntry[];
@@ -94,18 +36,11 @@ interface AgentResources {
     hooks: ResourceEntry[];
     workflows: ResourceEntry[];
 }
-/** Options for resource discovery. */
 interface GetAgentResourcesOptions {
     cwd?: string;
     scope?: 'user' | 'project' | 'all';
-    /** For MCP scanning - whether the CLI is installed */
     cliInstalled?: boolean;
-    /** Version home to scan for user-scoped resources */
     home?: string;
 }
-/**
- * Get all resources installed for a specific agent by scanning the filesystem.
- * This is the source of truth - not the tracking data in agents.yaml.
- */
 export declare function getAgentResources(agentId: AgentId, options?: GetAgentResourcesOptions): AgentResources;
 export {};

package/dist/lib/resources.js

@@ -1,7 +1,3 @@
-/**
- * Unified resource discovery for agents.
- * Scans filesystem (source of truth) to find all installed resources for an agent.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { AGENTS, listInstalledMcpsWithScope } from './agents.js';
@@ -16,11 +12,6 @@ import { isCapable } from './capabilities.js';
 import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, } from './state.js';
 import { isNameActiveInResourceProfile } from './resource-profiles.js';
 import { resolveSnapshotSha } from './git.js';
-/**
- * The declared frontmatter `aliases:` of a single resource, or `[]` for a kind
- * that doesn't support aliases. Only `skills` (SKILL.md) and `commands` carry
- * them today. `resourcePath` is the skill directory or the command file.
- */
 function resourceAliases(kind, resourcePath) {
     if (kind === 'skills')
         return parseSkillMetadata(resourcePath)?.aliases ?? [];
@@ -28,7 +19,6 @@ function resourceAliases(kind, resourcePath) {
         return parseCommandMetadata(resourcePath)?.aliases ?? [];
     return [];
 }
-/** Build a ResolvedResource with lazy, memoized `snapshotSha` and `aliases` getters. */
 function withProvenance(base, kind) {
     let aliasesComputed = false;
     let aliasesCache;
@@ -40,8 +30,6 @@ function withProvenance(base, kind) {
         get aliases() {
             if (!aliasesComputed) {
                 const found = resourceAliases(kind, base.path);
-                // Undefined (not []) when none, so a strict toEqual on a ResolvedResource
-                // ignores it — the same convention snapshotSha uses.
                 aliasesCache = found.length > 0 ? found : undefined;
                 aliasesComputed = true;
             }
@@ -69,37 +57,12 @@ function resourceIsActive(kind, name, source) {
     const activeKind = profiledKind(kind);
     return activeKind ? isNameActiveInResourceProfile(activeKind, name, source) : true;
 }
-/**
- * Documentation filenames that live *beside* resources, describing the directory
- * rather than being a resource in it. A DotAgents repo keeps a `README.md` (for
- * humans) and an `AGENTS.md` (for agents) in each resource dir, with
- * `CLAUDE.md`/`GEMINI.md` symlinked to the latter. Without this filter every one
- * of them materializes as a resource — `commands/README.md` installs a bogus
- * `/README` slash command into every agent home.
- *
- * `rules` is exempt: there `AGENTS.md` IS the resource (the composed ruleset that
- * syncs as each agent's memory file), not documentation about the directory.
- */
 const DOC_BASENAMES = new Set(['readme', 'agents', 'claude', 'gemini']);
-/**
- * True when `rawName` (a filename with its extension already stripped) names a
- * directory doc rather than a resource of `kind`. Exported so every enumerator
- * shares one definition — `listCentralCommands` and `discoverCommands` in
- * `commands.ts` do their own `readdirSync` scans, and without this they would
- * list a `README` that `resolveResource` then refuses to open.
- */
 export function isDirectoryDoc(kind, rawName) {
     if (kind === 'rules')
         return false;
     return DOC_BASENAMES.has(rawName.toLowerCase());
 }
-/**
- * Resolve a single resource by kind + name using project > user > system precedence.
- * For file-based resources the path ends in `.md`, `.yaml`, or `.yml` as appropriate.
- * Returns null when the resource does not exist in any scope.
- *
- * Extra repos are searched last (after system) to match syncResourcesToVersion order.
- */
 export function resolveResource(kind, name, cwd) {
     const projectDir = getProjectAgentsDir(cwd);
     const extraRepos = getEnabledExtraRepos();
@@ -112,7 +75,6 @@ export function resolveResource(kind, name, cwd) {
     for (const [dir, source, repoRoot] of candidates) {
         if (!fs.existsSync(dir))
             continue;
-        // Try exact name (for directories like skills/subagents)
         const exactPath = path.join(dir, name);
         if (fs.existsSync(exactPath)) {
             if (resourceIsActive(kind, name, source)) {
@@ -120,8 +82,6 @@ export function resolveResource(kind, name, cwd) {
             }
             continue;
         }
-        // Try with common file extensions. A directory doc (README/AGENTS/CLAUDE/
-        // GEMINI) describes the directory and is never itself a resource.
         if (isDirectoryDoc(kind, name))
             continue;
         for (const ext of ['.md', '.yaml', '.yml']) {
@@ -134,11 +94,6 @@ export function resolveResource(kind, name, cwd) {
             }
         }
     }
-    // Alias fallback (skills/commands only). A resource may declare `aliases:` in
-    // its frontmatter; match `name` against those AFTER every layer's canonical
-    // lookup above has missed, so a canonical resource named `name` always wins a
-    // collision regardless of layer. Layer precedence still applies among aliases,
-    // and entries are sorted so a same-layer alias collision resolves deterministically.
     if (kind === 'skills' || kind === 'commands') {
         for (const [dir, source, repoRoot] of candidates) {
             if (!fs.existsSync(dir))
@@ -161,18 +116,12 @@ export function resolveResource(kind, name, cwd) {
                     continue;
                 if (!resourceIsActive(kind, rawName, source))
                     continue;
-                // Resolve to the canonical resource (its real name), not the alias.
                 return withProvenance({ name: rawName, path: resourcePath, source, repoRoot }, kind);
             }
         }
     }
     return null;
 }
-/**
- * List all resources of a given kind across project, user, and system scopes.
- * Returns a deduplicated union (project wins on name collision), each entry
- * annotated with its origin source.
- */
 export function listResources(kind, cwd) {
     const seen = new Set();
     const results = [];
@@ -184,14 +133,6 @@ export function listResources(kind, cwd) {
         [path.join(getSystemAgentsDir(), kind), 'system', getSystemAgentsDir()],
         ...extraRepos.map((e) => [path.join(e.dir, kind), e.alias, e.dir]),
     ];
-    // Hooks use a one-level event-group layout (hooks/pre-tool-use/git-guard.sh).
-    // A flat readdir treats `pre-tool-use` as the resource name, so `system:*`
-    // pattern expansion never includes nested scripts — and `agents sync --force`
-    // leaves stale flat copies in version homes forever. Mirror getAvailableResources:
-    // expand group dirs that hold scripts (install name = basename with extension),
-    // keep fixture-only dirs as bundles, and keep top-level scripts as resources.
-    // Keep this logic self-contained (no hooks.ts import) so vi.mock of hooks.js
-    // in versions tests does not break listResources.
     if (kind === 'hooks') {
         const HOOK_SCRIPT_EXTS = new Set([
             '.sh', '.bash', '.zsh', '.py', '.js', '.ts', '.mjs', '.cjs', '.rb', '.pl', '.ps1', '.cmd', '.bat',
@@ -232,7 +173,6 @@ export function listResources(kind, cwd) {
                 if (stat.isFile()) {
                     if (!isHookScriptName(name, stat.mode))
                         continue;
-                    // Docs that live beside hooks (README/AGENTS) are not resources.
                     const raw = name.replace(/\.(md|yaml|yml)$/, '');
                     if (isDirectoryDoc(kind, raw))
                         continue;
@@ -291,7 +231,6 @@ export function listResources(kind, cwd) {
                     }
                 }
                 else {
-                    // Fixture-only directory bundle (hooks/tests/fixtures/…).
                     if (seen.has(name))
                         continue;
                     if (!resourceIsActive(kind, name, source))
@@ -322,10 +261,6 @@ export function listResources(kind, cwd) {
             if (entry.name.startsWith('.'))
                 continue;
             const rawName = entry.name.replace(/\.(md|yaml|yml)$/, '');
-            // Not isFile(): a Dirent for a symlink reports isFile() === false, and
-            // CLAUDE.md/GEMINI.md are symlinks to AGENTS.md by convention. Anything
-            // that is not a directory is a candidate doc; a resource directory that
-            // happens to be named `agents/` is still a real resource.
             if (!entry.isDirectory() && isDirectoryDoc(kind, rawName))
                 continue;
             if (seen.has(rawName))
@@ -343,10 +278,6 @@ export function listResources(kind, cwd) {
     }
     return results;
 }
-/**
- * Get all resources installed for a specific agent by scanning the filesystem.
- * This is the source of truth - not the tracking data in agents.yaml.
- */
 export function getAgentResources(agentId, options = {}) {
     const { cwd = process.cwd(), scope = 'all', cliInstalled = true, home } = options;
     const agent = AGENTS[agentId];
@@ -355,14 +286,12 @@ export function getAgentResources(agentId, options = {}) {
             return true;
         return resourceScope === scope;
     };
-    // Commands
     const commands = [];
     for (const cmd of listInstalledCommandsWithScope(agentId, cwd, { home })) {
         if (shouldInclude(cmd.scope)) {
             commands.push({ name: cmd.name, path: cmd.path, scope: cmd.scope, description: cmd.description });
         }
     }
-    // Skills
     const skills = [];
     const skillErrors = [];
     for (const skill of listInstalledSkillsWithScope(agentId, cwd, { home, errors: skillErrors })) {
@@ -376,10 +305,8 @@ export function getAgentResources(agentId, options = {}) {
             });
         }
     }
-    // MCP
     const mcp = [];
     const mcpByName = new Map();
-    // Project/user-scoped MCP definitions from .agents/mcp
     for (const server of listMcpServerConfigs(cwd)) {
         const scope = server.scope || 'user';
         if (shouldInclude(scope) && !mcpByName.has(server.name)) {
@@ -397,7 +324,6 @@ export function getAgentResources(agentId, options = {}) {
         }
     }
     mcp.push(...mcpByName.values());
-    // Memory/Instructions
     const memory = [];
     for (const instr of listInstalledInstructionsWithScope(agentId, cwd, { home })) {
         if (instr.exists && shouldInclude(instr.scope)) {
@@ -408,9 +334,6 @@ export function getAgentResources(agentId, options = {}) {
             });
         }
     }
-    // Hooks — routed through the resource-inventory chokepoint (RUSH-2238) so
-    // inspect/doctor/view share one listing and one (absolute-hooksDir-safe)
-    // path resolution.
     const hooks = [];
     for (const ref of listOnDiskHooks(agentId, { cwd, home })) {
         const hookScope = ref.source;
@@ -418,7 +341,6 @@ export function getAgentResources(agentId, options = {}) {
             hooks.push({ name: ref.name, path: ref.path, scope: hookScope });
         }
     }
-    // Workflows
     const workflows = [];
     if (isCapable(agentId, 'workflows')) {
         for (const w of WorkflowsHandler.listAll(agentId, cwd)) {

package/dist/lib/routers.d.ts

@@ -1,92 +1,25 @@
-/**
- * Router management -- named, task-typed allowlists of (harness, model/tier,
- * account) that constrain an Agent Router decision. A router is a
- * generalization of a profile (a profile ≡ a router pinned to one harness and
- * one account). Stored as YAML files under ~/.agents/routers/.
- *
- * Routers resolve as a layered resource (project > user > system, like other
- * resources -- see resources.ts) but are always CREATED in the user layer,
- * mirroring profiles.ts.
- */
-/** Per-harness allowlist inside a router: eligible models/tiers + linked accounts. */
 export interface RouterHarnessAllowlist {
-    /** Concrete model ids and/or tier tokens (cheap|default|best|ultra) eligible under this router. */
     models: string[];
-    /** Durable credential accounts eligible under this router. Routing is limited to these. */
     accounts?: string[];
 }
-/** A named router: a reusable, task-typed allowlist of harnesses x models/tiers x accounts. */
 export interface Router {
     name: string;
-    /** Free-text task type this router serves (e.g. "research", "prod-refactor"). */
     task?: string;
-    /** Allowlist -- only these harness x model/tier x account combos are eligible under this router. */
     harnesses: Record<string, RouterHarnessAllowlist>;
-    /** Scoped policy weights, applied within the router (consumed by routing, a later ticket). */
     weights?: {
         cost?: number;
         success?: number;
         headroom?: number;
     };
-    /** Opt-in re-route of a pinned target when it's exhausted (consumed by routing, a later ticket). */
     hijack?: boolean;
 }
-/** Directory this machine writes router YAML files to (user layer). */
 export declare function routersDir(): string;
-/** Validate a router name against the allowed pattern. Throws on invalid input. */
 export declare function validateRouterName(name: string): void;
-/** Check whether a router resolves, project > user > system (like other resources). */
 export declare function routerExists(name: string, cwd?: string): boolean;
-/**
- * The layer a router currently resolves from ('project' | 'user' | 'system' |
- * an extra-repo alias), or null if it doesn't resolve. `writeRouter` and
- * `deleteRouter` only ever touch the user layer, so a caller that edits or
- * removes a router MUST check this first -- editing a router that resolves
- * from a non-user layer would silently write to a user-layer file that stays
- * permanently shadowed (the edit "succeeds" but is never read back).
- */
 export declare function routerSource(name: string, cwd?: string): string | null;
-/** Read a router, resolved project > user > system. Throws if not found or malformed. */
 export declare function readRouter(name: string, cwd?: string): Router;
-/** Write a router to disk atomically (write-to-tmp then rename). Always writes the user layer. */
 export declare function writeRouter(router: Router): void;
-/** Delete a router from the user layer. Returns false if it did not exist there. */
 export declare function deleteRouter(name: string): boolean;
-/**
- * Rename a router on disk, re-keying the user-layer file and preserving every
- * field (harness allowlists, weights, linked accounts, hijack flag).
- *
- * Throws if `oldName` does not resolve, if it resolves from a non-user layer
- * (renaming would write a shadowed user-layer copy -- see {@link routerSource}),
- * or if `newName` already resolves in any layer. There is no `--force` /
- * overwrite path -- a collision is a hard error directing the user to remove
- * the target first.
- */
 export declare function renameRouter(oldName: string, newName: string): void;
-/**
- * Fail-loud token validation (E1 of the Agent Router spec): a router MUST NOT
- * persist a harness id or model/tier token this machine cannot vouch for.
- * Throws naming the first invalid token found; the caller (route.ts) never
- * calls {@link writeRouter} when this throws, so an invalid `create`/`allow`
- * writes nothing.
- *
- * A harness id must be a real, registered agent (`AGENTS` in agents.ts) --
- * checked regardless of whether that harness is installed on this machine,
- * since a router is fleet-wide config and the harness may only run
- * elsewhere. A model/tier token is valid when it is one of the four
- * cross-harness tier tokens (cheap|default|best|ultra, always installable-
- * agnostic), OR a concrete model id this machine can actually verify: either
- * one of the harness's resolved tier rungs (`resolveTierMap` -- covers
- * curated/no-catalog harnesses like Droid with zero install required) or a
- * member of its extracted catalog (`getModelCatalog`, when a version of that
- * harness is installed here). A concrete id for a harness with neither --
- * not installed here, no curated ladder -- cannot be verified and is
- * rejected rather than accepted unverified.
- */
 export declare function validateRouter(router: Router): void;
-/**
- * List every router resolved project > user > system (deduplicated union,
- * project wins on a name collision -- same precedence as {@link resolveResource}).
- * Malformed files are silently skipped, surfaced via `agents route view <name>`.
- */
 export declare function listRouters(cwd?: string): Router[];

package/dist/lib/routers.js

@@ -1,13 +1,3 @@
-/**
- * Router management -- named, task-typed allowlists of (harness, model/tier,
- * account) that constrain an Agent Router decision. A router is a
- * generalization of a profile (a profile ≡ a router pinned to one harness and
- * one account). Stored as YAML files under ~/.agents/routers/.
- *
- * Routers resolve as a layered resource (project > user > system, like other
- * resources -- see resources.ts) but are always CREATED in the user layer,
- * mirroring profiles.ts.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
@@ -18,32 +8,21 @@ import { isTierToken, resolveTierMap, MODEL_TIERS } from './model-tiers.js';
 import { getModelCatalog } from './models.js';
 import { resolveVersion } from './installations/versions.js';
 const ROUTER_NAME_PATTERN = /^[a-z0-9][a-z0-9-_]{0,48}$/i;
-/** Directory this machine writes router YAML files to (user layer). */
 export function routersDir() {
     return path.join(getUserAgentsDir(), 'routers');
 }
 function routerPath(name) {
     return path.join(routersDir(), `${name}.yml`);
 }
-/** Validate a router name against the allowed pattern. Throws on invalid input. */
 export function validateRouterName(name) {
     if (!ROUTER_NAME_PATTERN.test(name)) {
         throw new Error(`Invalid router name '${name}'. Use letters, digits, dash, underscore (max 48 chars).`);
     }
 }
-/** Check whether a router resolves, project > user > system (like other resources). */
 export function routerExists(name, cwd) {
     validateRouterName(name);
     return resolveResource('routers', name, cwd) !== null;
 }
-/**
- * The layer a router currently resolves from ('project' | 'user' | 'system' |
- * an extra-repo alias), or null if it doesn't resolve. `writeRouter` and
- * `deleteRouter` only ever touch the user layer, so a caller that edits or
- * removes a router MUST check this first -- editing a router that resolves
- * from a non-user layer would silently write to a user-layer file that stays
- * permanently shadowed (the edit "succeeds" but is never read back).
- */
 export function routerSource(name, cwd) {
     validateRouterName(name);
     return resolveResource('routers', name, cwd)?.source ?? null;
@@ -60,7 +39,6 @@ function parseRouterFile(file, name) {
         parsed.harnesses = {};
     return parsed;
 }
-/** Read a router, resolved project > user > system. Throws if not found or malformed. */
 export function readRouter(name, cwd) {
     validateRouterName(name);
     const resolved = resolveResource('routers', name, cwd);
@@ -69,7 +47,6 @@ export function readRouter(name, cwd) {
     }
     return parseRouterFile(resolved.path, name);
 }
-/** Write a router to disk atomically (write-to-tmp then rename). Always writes the user layer. */
 export function writeRouter(router) {
     validateRouterName(router.name);
     const dir = routersDir();
@@ -80,7 +57,6 @@ export function writeRouter(router) {
     fs.writeFileSync(tmp, body, 'utf-8');
     fs.renameSync(tmp, file);
 }
-/** Delete a router from the user layer. Returns false if it did not exist there. */
 export function deleteRouter(name) {
     validateRouterName(name);
     const file = routerPath(name);
@@ -89,16 +65,6 @@ export function deleteRouter(name) {
     fs.unlinkSync(file);
     return true;
 }
-/**
- * Rename a router on disk, re-keying the user-layer file and preserving every
- * field (harness allowlists, weights, linked accounts, hijack flag).
- *
- * Throws if `oldName` does not resolve, if it resolves from a non-user layer
- * (renaming would write a shadowed user-layer copy -- see {@link routerSource}),
- * or if `newName` already resolves in any layer. There is no `--force` /
- * overwrite path -- a collision is a hard error directing the user to remove
- * the target first.
- */
 export function renameRouter(oldName, newName) {
     validateRouterName(newName);
     const source = routerSource(oldName);
@@ -118,26 +84,6 @@ export function renameRouter(oldName, newName) {
     writeRouter(router);
     deleteRouter(oldName);
 }
-/**
- * Fail-loud token validation (E1 of the Agent Router spec): a router MUST NOT
- * persist a harness id or model/tier token this machine cannot vouch for.
- * Throws naming the first invalid token found; the caller (route.ts) never
- * calls {@link writeRouter} when this throws, so an invalid `create`/`allow`
- * writes nothing.
- *
- * A harness id must be a real, registered agent (`AGENTS` in agents.ts) --
- * checked regardless of whether that harness is installed on this machine,
- * since a router is fleet-wide config and the harness may only run
- * elsewhere. A model/tier token is valid when it is one of the four
- * cross-harness tier tokens (cheap|default|best|ultra, always installable-
- * agnostic), OR a concrete model id this machine can actually verify: either
- * one of the harness's resolved tier rungs (`resolveTierMap` -- covers
- * curated/no-catalog harnesses like Droid with zero install required) or a
- * member of its extracted catalog (`getModelCatalog`, when a version of that
- * harness is installed here). A concrete id for a harness with neither --
- * not installed here, no curated ladder -- cannot be verified and is
- * rejected rather than accepted unverified.
- */
 export function validateRouter(router) {
     for (const [harness, allowlist] of Object.entries(router.harnesses)) {
         if (!ALL_AGENT_IDS.includes(harness)) {
@@ -163,11 +109,6 @@ export function validateRouter(router) {
         }
     }
 }
-/**
- * List every router resolved project > user > system (deduplicated union,
- * project wins on a name collision -- same precedence as {@link resolveResource}).
- * Malformed files are silently skipped, surfaced via `agents route view <name>`.
- */
 export function listRouters(cwd) {
     const routers = [];
     for (const resolved of listResources('routers', cwd)) {
@@ -175,7 +116,6 @@ export function listRouters(cwd) {
             routers.push(parseRouterFile(resolved.path, resolved.name));
         }
         catch {
-            // Skip malformed router files.
         }
     }
     return routers.sort((a, b) => a.name.localeCompare(b.name));

package/dist/lib/routine-activation.d.ts

@@ -1,36 +1,13 @@
 export declare function normalizeRoutineNames(names: Iterable<string>): string[];
-/** null means this device has not materialized activation state yet. */
 export declare function enabledRoutineNames(): string[] | null;
 export declare function routineEnabledOnThisDevice(name: string): boolean | null;
 export declare function replaceEnabledRoutines(names: Iterable<string>): string[];
-/**
- * Add or remove one routine on this machine. `legacyEnabledNames` seeds the
- * manifest the first time an upgraded host changes activation, preserving every
- * other routine that was effectively enabled under the old definition fields.
- */
 export declare function setRoutineEnabledOnThisDevice(name: string, enabled: boolean, legacyEnabledNames?: Iterable<string>): string[];
-/** Read-only fleet view from synced device documents. Never writes a peer file. */
 export declare function devicesWithRoutineEnabled(name: string): string[];
-/** Which devices enable which routines, read in one pass. */
 export interface RoutineDeviceIndex {
-    /** Routine name → the devices whose allowlist names it, sorted. */
     byRoutine: Map<string, string[]>;
-    /**
-     * True when at least one device document declares a `routines:` list. Until
-     * then no routine is "dark" — the fleet simply has not materialized its
-     * activation state yet, and saying "will not fire" would be wrong.
-     */
     materialized: boolean;
-    /** Device files that could not be read, reported instead of thrown. */
     errors: string[];
 }
-/**
- * Build the whole fleet's activation map in one pass over `devices/`.
- *
- * `devicesWithRoutineEnabled` answers this for a single routine and throws on a
- * corrupt peer file — the right contract for a command acting on one routine,
- * the wrong one for a listing, where a single unreadable device document would
- * blank out every row (and re-walking `devices/` per routine is quadratic).
- */
 export declare function routineDeviceIndex(): RoutineDeviceIndex;
 export declare function currentRoutineDevice(): string;