@phnx-labs/agents-cli 1.22.39 → 1.22.41

package/dist/lib/wrap.js

@@ -0,0 +1,70 @@
+/**
+ * Terminal word-wrap — one shared helper for the whole CLI.
+ *
+ * Multi-line word wrapping is the gap the single-line helpers in
+ * `session/width.ts` (`truncateToWidth`, `padToWidth`) do not fill. Anywhere that
+ * renders variable-length text into a fixed-width terminal wraps through THIS,
+ * never a per-field slice.
+ *
+ * Width is measured with `stringWidth` (from the canonical `session/width.ts`),
+ * NOT `String.length`: the text this wraps is routinely ANSI-coloured (chalk /
+ * marked-terminal output) and may carry OSC-8 hyperlinks, where `.length`
+ * over-counts the invisible escape bytes. Words are split on whitespace, so a
+ * wrap boundary always falls between escape sequences, never inside one.
+ */
+import { stringWidth } from './session/width.js';
+/**
+ * Hard-wrap `text` to `cols` visible columns.
+ *
+ * - Splits on existing newlines first (each paragraph wraps independently).
+ * - Wraps on whitespace; a single word wider than the available width is emitted
+ *   on its own line rather than split mid-word (and never mid-escape).
+ * - Width is the visible display width via `stringWidth`, so ANSI colour and
+ *   OSC-8 hyperlink escapes do not inflate the count.
+ * - `hangingIndent` pads every line AFTER the first with that many spaces, so a
+ *   labelled value ("Latest  <text>") keeps its continuation lines aligned under
+ *   the value. The wrapping width is `cols - indent`.
+ * - Floor: when `hangingIndent` is set, the width is floored at 8 so a
+ *   pathologically large indent still makes forward progress. With no indent the
+ *   floor is 1, so a legitimately small `cols` is respected, never overridden. A
+ *   non-finite `cols` degrades to the floor rather than silently disabling wrap.
+ *
+ * Returns the wrapped lines (never mutates input). An empty string yields [''].
+ */
+export function wrapToWidth(text, cols, hangingIndent = 0) {
+    const indent = Math.max(0, Math.trunc(hangingIndent));
+    const floor = indent > 0 ? 8 : 1;
+    const width = Number.isFinite(cols) ? Math.max(floor, cols - indent) : floor;
+    const pad = ' '.repeat(indent);
+    const out = [];
+    for (const para of String(text).split('\n')) {
+        const words = para.split(/\s+/).filter(w => w.length > 0);
+        if (words.length === 0) {
+            out.push('');
+            continue;
+        }
+        let line = '';
+        let lineWidth = 0;
+        for (const word of words) {
+            const wordWidth = stringWidth(word);
+            if (line === '') {
+                line = word;
+                lineWidth = wordWidth;
+            }
+            else if (lineWidth + 1 + wordWidth > width) {
+                out.push(line);
+                line = word;
+                lineWidth = wordWidth;
+            }
+            else {
+                line = `${line} ${word}`;
+                lineWidth += 1 + wordWidth;
+            }
+        }
+        if (line !== '')
+            out.push(line);
+    }
+    if (out.length === 0)
+        out.push('');
+    return out.map((l, i) => (i === 0 ? l : pad + l));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.39",
+  "version": "1.22.41",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",
@@ -24,6 +24,7 @@
     "dist/**/*.js",
     "dist/**/*.d.ts",
     "dist/**/*.json",
+    "dist/**/*.sh",
     "dist/bin/**",
     "dist/lib/secrets/Agents CLI.app/**",
     "dist/lib/menubar/MenubarHelper.app/**",

package/scripts/postinstall.js

@@ -291,7 +291,7 @@ To enable version-aware shims, add this to your shell config:
  * non-interactive login shell's PATH, so `bash -lc 'agents …'` fails with
  * command-not-found — which breaks `agents secrets export --host` (it runs
  * `bash -lc 'agents secrets import …'` on the remote) and the routines daemon
- * (src/lib/daemon.ts falls back to bare `agents`). This is the POSIX symmetric
+ * (src/lib/daemon/daemon.ts falls back to bare `agents`). This is the POSIX symmetric
  * counterpart of the Windows branch in main() that registers npm's global-bin
  * dir on the user PATH.
  *
@@ -406,7 +406,7 @@ async function healLongRunningProcesses() {
   // starts (SING-4a). If it was already running under a disable, stop and leave
   // it down so upgrade does not resurrect a killed switch.
   try {
-    const d = await import('../dist/lib/daemon.js');
+    const d = await import('../dist/lib/daemon/daemon.js');
     const { isDaemonEnabled } = await import('../dist/lib/device-config.js');
     const wasRunning = Boolean(d.isDaemonRunning?.());
     const enabled = typeof isDaemonEnabled === 'function' ? isDaemonEnabled() : true;

package/dist/commands/bench.d.ts

@@ -1,2 +0,0 @@
-import type { Command } from "commander";
-export declare function registerBenchCommand(program: Command): void;

package/dist/commands/bench.js

@@ -1,101 +0,0 @@
-import * as fs from "fs";
-import * as path from "path";
-import { fileURLToPath } from "url";
-import { detectSignedInRuntimes } from "../lib/crabbox/runtimes.js";
-import { listRuns, loadRun, loadTask, runCells, saveRun, } from "../lib/bench/index.js";
-import { setHelpSections } from "../lib/help.js";
-const TASKS_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../bench/tasks");
-function csv(value) {
-    return (value
-        ?.split(",")
-        .map((item) => item.trim())
-        .filter(Boolean) ?? []);
-}
-function taskIds(root = TASKS_ROOT) {
-    if (!fs.existsSync(root))
-        return [];
-    return fs
-        .readdirSync(root, { withFileTypes: true })
-        .filter((entry) => entry.isDirectory() &&
-        fs.existsSync(path.join(root, entry.name, "task.json")))
-        .map((entry) => entry.name)
-        .sort();
-}
-function renderResult(result) {
-    console.log(`Run ${result.run_id}${result.task_id ? ` · ${result.task_id}` : ""}`);
-    for (const cell of result.cells)
-        console.log(`${cell.status === "passed" ? "PASS" : "FAIL"}  ${cell.agent}${cell.model ? `/${cell.model}` : ""}  ${cell.wall_ms} ms  exit ${cell.exit ?? "spawn-error"}`);
-}
-export function registerBenchCommand(program) {
-    const bench = program
-        .command("bench")
-        .description("Run the same task across agent and model cells, with isolated fixtures and durable JSON results.");
-    setHelpSections(bench, {
-        examples: `agents bench list\nagents bench run hello-repo --agent claude,codex --model cheap,default\nagents bench results --json`,
-        notes: `Task definitions live under apps/cli/bench/tasks/<id>/task.json. Custom harness names accepted by agents run are valid --agent values.`,
-    });
-    bench
-        .command("list")
-        .description("List available benchmark tasks.")
-        .option("--json", "Emit JSON.")
-        .action((options) => {
-        const tasks = taskIds();
-        if (options.json)
-            console.log(JSON.stringify(tasks, null, 2));
-        else if (tasks.length === 0)
-            console.log("No benchmark tasks installed.");
-        else
-            tasks.forEach((id) => console.log(id));
-    });
-    bench
-        .command("results [run-id]")
-        .description("Show one saved run, or list saved runs newest first.")
-        .option("--json", "Emit JSON.")
-        .action((runId, options) => {
-        const value = runId ? loadRun(runId) : listRuns();
-        if (options.json)
-            console.log(JSON.stringify(value, null, 2));
-        else if (Array.isArray(value)) {
-            if (value.length === 0)
-                console.log("No benchmark results yet.");
-            else
-                value.forEach(renderResult);
-        }
-        else
-            renderResult(value);
-    });
-    bench
-        .command("run [task-id]")
-        .description("Run one task or prompt across an agent × model matrix.")
-        .option("--prompt <text>", "Prompt to benchmark instead of a house task.")
-        .option("--agent <names>", "Comma-separated native agents or custom harness names. Defaults to signed-in native agents.")
-        .option("--model <models>", "Comma-separated model tiers or concrete model ids.")
-        .option("--concurrency <n>", "Maximum cells running at once.", "3")
-        .option("--json", "Emit the saved JSON result.")
-        .action(async (taskId, options) => {
-        if (!!taskId === !!options.prompt)
-            throw new Error("Pass exactly one of <task-id> or --prompt.");
-        const task = taskId ? loadTask(taskId, TASKS_ROOT) : undefined;
-        const prompt = options.prompt ?? task.prompt;
-        let agents = csv(options.agent);
-        if (agents.length === 0)
-            agents = (await detectSignedInRuntimes())
-                .filter((runtime) => runtime.signedIn)
-                .map((runtime) => runtime.id);
-        if (agents.length === 0)
-            throw new Error("No signed-in native agents found. Pass --agent <name>.");
-        const models = csv(options.model);
-        const cells = agents.flatMap((agent) => models.length > 0
-            ? models.map((model) => ({ agent, model }))
-            : [{ agent }]);
-        const concurrency = Number(options.concurrency);
-        const result = await runCells({ task, prompt, cells, concurrency });
-        saveRun(result);
-        if (options.json)
-            console.log(JSON.stringify(result, null, 2));
-        else
-            renderResult(result);
-        if (result.cells.some((cell) => cell.status === "failed"))
-            process.exitCode = 1;
-    });
-}

package/dist/commands/cp.d.ts

@@ -1,84 +0,0 @@
-/**
- * `agents cp <src> <dst>` — first-class fleet file transfer.
- *
- * Accepts `host:path` on either side (local = bare absolute path). Resolves
- * `~` and `$HOME` remote paths ON the remote before transfer so a `$HOME` in
- * the remote spec can never silently expand to the local user's home directory
- * — the documented silent-failure class in `remote-dispatch-mutation-safety`.
- *
- * Reuses the same SSH fabric (SSH_OPTS, deviceIdentityArgs, resolveDeviceTarget)
- * that `agents ssh` and `--host` dispatch use.
- */
-import type { Command } from 'commander';
-/**
- * A remote endpoint — host (device name or user@device) and a path on that
- * host. The path may begin with `~` or `$HOME`; {@link resolveRemotePath}
- * expands those on the remote before transfer.
- */
-export interface RemoteEndpoint {
-    isRemote: true;
-    /** Device name, user@device, or ad-hoc host literal. */
-    host: string;
-    /** Path as given by the caller — may contain `~` or `$HOME`. */
-    path: string;
-}
-/** A local endpoint — an absolute local path. */
-export interface LocalEndpoint {
-    isRemote: false;
-    /** Absolute local path. */
-    path: string;
-}
-export type Endpoint = RemoteEndpoint | LocalEndpoint;
-/**
- * Parse one CLI token into an {@link Endpoint}.
- *
- * Grammar: `host:path` is remote; anything else is local. The host part must
- * not contain a `/` (that would be a local absolute path with a colon in it —
- * unusual but valid; the colon test covers the common fleet pattern and rejects
- * the almost-never-seen edge case in favour of local-path semantics).
- *
- * Windows drive letters (`C:path`) are excluded by requiring the host part to
- * be at least two characters and not a single capital letter.
- */
-export declare function parseEndpoint(token: string): Endpoint;
-/**
- * Resolve the remote HOME directory in one SSH round-trip. Returns the
- * absolute path (always starts with `/`), or throws on failure.
- */
-export declare function resolveRemoteHome(target: string, extraSshArgs: string[]): Promise<string>;
-/**
- * Pure home-prefix expansion. Given a remote HOME (already resolved on the
- * remote) and a raw path token, substitute a leading `~` or `$HOME`. Paths
- * without those prefixes are returned unchanged. Never consults
- * `process.env.HOME` — the local home must not leak into a remote path.
- */
-export declare function expandRemoteHomePrefix(rawPath: string, remoteHome: string): string;
-/**
- * Expand a remote path's leading `~` or literal `$HOME` to an absolute path
- * resolved **on the remote**, not locally. A path that already starts with `/`
- * is returned unchanged (no round-trip).
- *
- * This is the safeguard against the silent-failure class: a `$HOME` or `~`
- * that would expand to the **local** user's home if left in a shell command.
- */
-export declare function resolveRemotePath(rawPath: string, target: string, extraSshArgs: string[]): Promise<string>;
-/**
- * Build the argv for the `scp` invocation. Pure — no spawning — so it is
- * unit-testable.
- *
- * `scp` accepts ssh `-o` options, so `SSH_OPTS` flows through unchanged.
- * Identity args (`-i key -o IdentitiesOnly=yes`) are included only when a
- * single remote device is involved; for two-remote transfers the identity
- * applies to both connections, which works when the fleet uses a shared key.
- *
- * Remote endpoints are formatted as `user@host:path` (or bare `host:path`),
- * local endpoints as their absolute path. Paths have already been resolved
- * (no `~` or `$HOME`) by the time this is called.
- */
-export declare function buildScpArgv({ srcSpec, dstSpec, identityArgs, recursive, }: {
-    srcSpec: string;
-    dstSpec: string;
-    identityArgs: string[];
-    recursive: boolean;
-}): string[];
-export declare function registerCpCommand(program: Command): void;

package/dist/commands/cp.js

@@ -1,231 +0,0 @@
-/**
- * `agents cp <src> <dst>` — first-class fleet file transfer.
- *
- * Accepts `host:path` on either side (local = bare absolute path). Resolves
- * `~` and `$HOME` remote paths ON the remote before transfer so a `$HOME` in
- * the remote spec can never silently expand to the local user's home directory
- * — the documented silent-failure class in `remote-dispatch-mutation-safety`.
- *
- * Reuses the same SSH fabric (SSH_OPTS, deviceIdentityArgs, resolveDeviceTarget)
- * that `agents ssh` and `--host` dispatch use.
- */
-import { spawnSync } from 'child_process';
-import chalk from 'chalk';
-import { setHelpSections } from '../lib/help.js';
-import { resolveDeviceTarget } from '../lib/devices/resolve-target.js';
-import { sshTargetFor, deviceIdentityArgs } from '../lib/devices/connect.js';
-import { sshExec, SSH_OPTS } from '../lib/ssh-exec.js';
-/**
- * Parse one CLI token into an {@link Endpoint}.
- *
- * Grammar: `host:path` is remote; anything else is local. The host part must
- * not contain a `/` (that would be a local absolute path with a colon in it —
- * unusual but valid; the colon test covers the common fleet pattern and rejects
- * the almost-never-seen edge case in favour of local-path semantics).
- *
- * Windows drive letters (`C:path`) are excluded by requiring the host part to
- * be at least two characters and not a single capital letter.
- */
-export function parseEndpoint(token) {
-    const colonIdx = token.indexOf(':');
-    if (colonIdx > 1 && !token.startsWith('/')) {
-        const host = token.slice(0, colonIdx);
-        const path = token.slice(colonIdx + 1);
-        // A bare single uppercase letter before `:` looks like a Windows drive
-        // letter — treat as local to avoid a confusing error.
-        if (!/^[A-Z]$/.test(host) && !host.includes('/')) {
-            return { isRemote: true, host, path };
-        }
-    }
-    return { isRemote: false, path: token };
-}
-// ---------------------------------------------------------------------------
-// Remote path resolution — the core safeguard
-// ---------------------------------------------------------------------------
-/**
- * Resolve the remote HOME directory in one SSH round-trip. Returns the
- * absolute path (always starts with `/`), or throws on failure.
- */
-export async function resolveRemoteHome(target, extraSshArgs) {
-    const res = sshExec(target, 'printf "%s" "$HOME"', {
-        extraSshArgs,
-        timeoutMs: 10_000,
-    });
-    if (res.code !== 0) {
-        throw new Error(`Cannot resolve remote $HOME on ${target}: ${res.stderr.trim() || 'ssh exited ' + String(res.code)}`);
-    }
-    const home = res.stdout.trim();
-    if (!home || !home.startsWith('/')) {
-        throw new Error(`Remote $HOME on ${target} is not an absolute path: ${JSON.stringify(home)}`);
-    }
-    return home;
-}
-/**
- * Pure home-prefix expansion. Given a remote HOME (already resolved on the
- * remote) and a raw path token, substitute a leading `~` or `$HOME`. Paths
- * without those prefixes are returned unchanged. Never consults
- * `process.env.HOME` — the local home must not leak into a remote path.
- */
-export function expandRemoteHomePrefix(rawPath, remoteHome) {
-    if (rawPath === '~' || rawPath.startsWith('~/')) {
-        return rawPath === '~' ? remoteHome : remoteHome + rawPath.slice(1);
-    }
-    if (rawPath === '$HOME' || rawPath.startsWith('$HOME/')) {
-        return rawPath === '$HOME' ? remoteHome : remoteHome + rawPath.slice(5);
-    }
-    return rawPath;
-}
-/**
- * Expand a remote path's leading `~` or literal `$HOME` to an absolute path
- * resolved **on the remote**, not locally. A path that already starts with `/`
- * is returned unchanged (no round-trip).
- *
- * This is the safeguard against the silent-failure class: a `$HOME` or `~`
- * that would expand to the **local** user's home if left in a shell command.
- */
-export async function resolveRemotePath(rawPath, target, extraSshArgs) {
-    if (rawPath === '~' ||
-        rawPath.startsWith('~/') ||
-        rawPath === '$HOME' ||
-        rawPath.startsWith('$HOME/')) {
-        const home = await resolveRemoteHome(target, extraSshArgs);
-        return expandRemoteHomePrefix(rawPath, home);
-    }
-    return rawPath;
-}
-// ---------------------------------------------------------------------------
-// scp invocation
-// ---------------------------------------------------------------------------
-/**
- * Build the argv for the `scp` invocation. Pure — no spawning — so it is
- * unit-testable.
- *
- * `scp` accepts ssh `-o` options, so `SSH_OPTS` flows through unchanged.
- * Identity args (`-i key -o IdentitiesOnly=yes`) are included only when a
- * single remote device is involved; for two-remote transfers the identity
- * applies to both connections, which works when the fleet uses a shared key.
- *
- * Remote endpoints are formatted as `user@host:path` (or bare `host:path`),
- * local endpoints as their absolute path. Paths have already been resolved
- * (no `~` or `$HOME`) by the time this is called.
- */
-export function buildScpArgv({ srcSpec, dstSpec, identityArgs, recursive, }) {
-    const opts = [...SSH_OPTS, ...identityArgs];
-    if (recursive)
-        opts.push('-r');
-    // Two-remote transfers route through the local machine (-3) to avoid
-    // requiring direct SSH access between the two fleet boxes.
-    if (srcSpec.includes(':') && dstSpec.includes(':'))
-        opts.push('-3');
-    return [...opts, srcSpec, dstSpec];
-}
-async function resolveEndpoint(ep) {
-    if (!ep.isRemote) {
-        return { spec: ep.path, identityArgs: [] };
-    }
-    const device = await resolveDeviceTarget(ep.host);
-    if (!device) {
-        throw new Error(`Unknown device ${JSON.stringify(ep.host)}. Register it with \`agents devices add\` or check \`agents devices\`.`);
-    }
-    const target = sshTargetFor(device);
-    const idArgs = deviceIdentityArgs(device);
-    const resolvedPath = await resolveRemotePath(ep.path, target, idArgs);
-    if (!resolvedPath.startsWith('/')) {
-        throw new Error(`Remote path on ${ep.host} must be absolute after expansion, got: ${JSON.stringify(resolvedPath)}. Use an absolute path or start with ~/`);
-    }
-    return { spec: `${target}:${resolvedPath}`, identityArgs: idArgs };
-}
-// ---------------------------------------------------------------------------
-// Validation
-// ---------------------------------------------------------------------------
-/** Validate a local path: must be absolute. */
-function validateLocalPath(raw) {
-    if (!raw.startsWith('/')) {
-        throw new Error(`Local path must be absolute, got: ${JSON.stringify(raw)}`);
-    }
-}
-/** Validate a remote path: non-empty. */
-function validateRemotePath(raw, host) {
-    if (!raw) {
-        throw new Error(`Remote path for ${JSON.stringify(host)} is empty. Expected: ${host}:/abs/path`);
-    }
-}
-// ---------------------------------------------------------------------------
-// Command registration
-// ---------------------------------------------------------------------------
-export function registerCpCommand(program) {
-    const cmd = program
-        .command('cp <src> <dst>')
-        .description('Copy a file or directory between fleet hosts. Either endpoint may be host:path (remote) or an absolute local path.')
-        .option('-r, --recursive', 'Copy directories recursively')
-        .action(async (srcToken, dstToken, opts) => {
-        const recursive = opts.recursive ?? false;
-        const srcEp = parseEndpoint(srcToken);
-        const dstEp = parseEndpoint(dstToken);
-        if (!srcEp.isRemote && !dstEp.isRemote) {
-            process.stderr.write(chalk.red('error:') +
-                ' At least one endpoint must be remote (host:path). For local-only copies use `cp`.\n');
-            process.exit(1);
-        }
-        let srcResolved;
-        let dstResolved;
-        try {
-            // Validate shapes before any network calls.
-            if (!srcEp.isRemote)
-                validateLocalPath(srcEp.path);
-            if (srcEp.isRemote)
-                validateRemotePath(srcEp.path, srcEp.host);
-            if (!dstEp.isRemote)
-                validateLocalPath(dstEp.path);
-            if (dstEp.isRemote)
-                validateRemotePath(dstEp.path, dstEp.host);
-            [srcResolved, dstResolved] = await Promise.all([
-                resolveEndpoint(srcEp),
-                resolveEndpoint(dstEp),
-            ]);
-        }
-        catch (err) {
-            process.stderr.write(chalk.red('error:') + ' ' + err.message + '\n');
-            process.exit(1);
-        }
-        // Merge identity args: for two-remote transfers, omit per-device identity
-        // args (they apply to both connections via -3; a conflict would need
-        // separate -i per connection which scp doesn't support). A shared fleet
-        // key works without explicit -i.
-        const identityArgs = srcResolved.identityArgs.length > 0 && dstResolved.identityArgs.length === 0
-            ? srcResolved.identityArgs
-            : dstResolved.identityArgs.length > 0 && srcResolved.identityArgs.length === 0
-                ? dstResolved.identityArgs
-                : srcResolved.identityArgs.join(',') === dstResolved.identityArgs.join(',')
-                    ? srcResolved.identityArgs
-                    : []; // two remotes with different keys — skip per-device flag, use agent's default key
-        const argv = buildScpArgv({
-            srcSpec: srcResolved.spec,
-            dstSpec: dstResolved.spec,
-            identityArgs,
-            recursive,
-        });
-        const res = spawnSync('scp', argv, { stdio: 'inherit' });
-        const code = typeof res.status === 'number' ? res.status : 1;
-        if (code !== 0) {
-            // scp already printed a diagnostic; just exit non-zero.
-            process.exit(code);
-        }
-    });
-    setHelpSections(cmd, {
-        examples: `
-      agents cp yosemite-s0:/abs/data.json /tmp/data.json   # download a file from a fleet host
-      agents cp /tmp/build.tar.gz mac-mini:/abs/deploy/    # upload a local file to a fleet host
-      agents cp -r yosemite-s0:/abs/src/ mac-mini:/abs/dst/ # copy a directory between two fleet hosts
-      agents cp yosemite-s0:~/logs/run.log /tmp/run.log    # ~ is resolved on the remote host
-    `,
-        notes: `
-      Local paths must be absolute (use /abs/path, not ./relative).
-      Remote paths must be absolute after ~ / $HOME expansion.
-      Remote $HOME is resolved on the remote host — never in the local shell.
-      Both local-to-remote and remote-to-local transfers are supported.
-      Remote-to-remote transfers route through the local machine (-3).
-      Devices must be registered: 'agents devices' to list, 'agents devices add' to enroll.
-    `,
-    });
-}

package/dist/commands/login.d.ts

@@ -1,2 +0,0 @@
-import type { Command } from 'commander';
-export declare function registerLoginCommands(program: Command): void;

package/dist/lib/resources/commands.d.ts

@@ -1,46 +0,0 @@
-/**
- * Commands resource handler.
- *
- * Commands are slash-command definitions stored as .md files (Claude/Codex/Cursor/OpenCode)
- * or .toml files (Gemini). This handler resolves commands across layers (project > user > system),
- * handles format conversion during sync, and provides consistent list/resolve/sync behavior.
- */
-import type { AgentId, ResolvedItem, ResourceHandler, ResourceKind } from './types.js';
-/** Command item metadata. */
-export interface CommandItem {
-    name: string;
-    description: string;
-    content: string;
-    format: 'md' | 'toml';
-}
-/**
- * Commands resource handler implementing ResourceHandler<CommandItem>.
- */
-export declare class CommandsHandler implements ResourceHandler<CommandItem> {
-    readonly kind: ResourceKind;
-    /**
-     * List all commands across layers, with higher layer winning on name conflict.
-     * Returns a union of all commands, deduplicated by name.
-     */
-    listAll(agent: AgentId, cwd?: string): ResolvedItem<CommandItem>[];
-    /**
-     * Resolve a single command by name.
-     * Returns the winning layer's version, or null if not found.
-     */
-    resolve(agent: AgentId, name: string, cwd?: string): ResolvedItem<CommandItem> | null;
-    /**
-     * Sync resolved commands to the agent's version home directory.
-     * Copies/transforms commands as needed for the agent's expected format.
-     */
-    sync(agent: AgentId, versionHome: string, cwd?: string): void;
-    /**
-     * Get the file format this resource uses for a given agent.
-     */
-    format(agent: AgentId): 'md' | 'toml';
-    /**
-     * Get the target directory name in the agent's version home.
-     */
-    targetDir(agent: AgentId): string;
-}
-/** Singleton instance of the commands handler. */
-export declare const commandsHandler: CommandsHandler;