@duyquangnvx/agent-cli 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,74 @@ What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duy
 
 ## Unreleased
 
+## v0.5.0 (2026-10-19)
+
+### Added
+
+- A command-tree CLI may declare `defineCli({ tools })`, the tools `doctor` checks besides its Commands' own. `doctor` reports one row per tool from the CLI's `tools` and every Command's, once per name, a missing one as a problem with its `install` as the fix. A Command still requires only its own `tools`, so the CLI's list never makes a Command refuse with `TOOL_MISSING`.
+- A Command may declare `hidden: true`. It routes and runs when named, and its own `--help` works, but it is left out of text help, `--help --json`, the root examples and "did you mean" suggestions for a misspelt Command.
+- A Command may declare `operator: true`, an Operator Command only a person at a terminal runs. When a Coding agent is detected, the run fails before its input is read, stdin included, with the new Runtime code `NEEDS_OPERATOR` (exit 2, exported as a constant), whose hint is `ask the operator to type: ! <command line as typed>`; `--json` alone does not refuse. Text help marks it `(operator only)` in a listing and with an `Operator Command:` line in its own help, and `--help --json` carries `operator` on every Command, `true` on an Operator Command and `false` on the rest.
+- A Command may declare `help`, a paragraph printed as written after the options in text help. `--help --json` carries it as `help`, which is `null` on a Command without one.
+- `ctx.spawn(command, args, { progress: true })` passes each line of the child's stdout and stderr through `ctx.progress` as it arrives, and still resolves to the whole output, which `check: true` uses for `TOOL_FAILED`. A `Spawn` passed as `runCli`'s `spawn` option receives an `onLine` callback when the caller asked for progress, to emit the child's lines.
+- On Windows, `ctx.spawn` runs a `.cmd` or `.bat` tool, such as one npm installed, found on `PATH` through `PATHEXT` or given by its path. Each argument reaches the tool as given: it is quoted, then escaped for `cmd.exe`, which otherwise expands `%VAR%` and acts on `&`, `|`, `<`, `>`, `^`, `(`, `)` and `!` even inside quotes, twice for a `.cmd` shim that hands its arguments to a second `cmd.exe` parse, as cross-spawn does.
+- A field of a Command's `options` may be a `z.array(...)`, optionally wrapped in optional or default, which collects every occurrence of its flag in order: `--ref a --ref=b --ref c` gives `ref: ["a", "b", "c"]`. Each value is coerced like a scalar option of the element's type, and an issue on one names it, as in `--row "x": ...`. None gives an empty array for the schema to judge, or leaves an optional field out so its default applies. Text help shows the flag as `--ref <value>...`, and `--help --json` gives it the array schema. `defineCommand` throws for an array of booleans. A repeated scalar flag still keeps its last value.
+- `ctx.commandLine({ add?, remove? })` returns the command line as the caller typed it, starting with the CLI's name and shell-quoted, with each flag in `remove` dropped along with its value (`--from 3`, `--from=3`, every time it was given) and the words in `add` placed before any `--`, for a hint naming the exact command to run next. It is the helper the Runtime's own hints (`--confirm`, `--yes`, `--force`, a page's `next`) are built with.
+- A run deadline's `resume(input, commandLine)` receives `ctx.commandLine` as its second argument. A `resume` taking only `input` still type-checks.
+- `ctx.poll(check, { intervalMs, signal })` also stops when `signal` aborts, ending with its reason, so `signal: ctx.deadline(ms)` stops polling at a `--wait` deadline rather than one interval after it.
+- `INTERRUPTED` and `DEADLINE_EXCEEDED` are exported as constants, so a Command tells `ctx.signal.reason` apart and throws its own `INTERRUPTED` with a hint it computes, which wins over the Runtime's. The skill teaches it.
+- A `doctor` row may return `{ state: "skipped", message }` for a check it did not run, such as "not checked: the bridge is down". It shows in text and `--json` and never fails `doctor`.
+- On Ctrl-C or SIGTERM, `doctor` prints the rows finished so far, in text or `--json`, before the run ends with 130 or 143. Rows cut short are left out.
+- With no copy of the skill installed, `doctor`'s `skill` row gives the fix `npx -y skills add <source> --skill <cli name> -g`, which installs only this CLI's skill from a repo holding several, and stays ok. The source is `defineCli({ skill: { source } })` as given, else the package.json `repository` URL with `git+` dropped, `.git` added if missing and `#release` appended, for an `https`, `http`, `ssh` or `git` URL or an scp-style `git@host:group/repo`; a GitHub `owner/repo` shorthand is kept as it is. With no `repository`, one that is neither, or a package.json that cannot be read or parsed, the row gives no fix.
+- `orStdin(schema)` marks one string field of a Command's `args` as also reading stdin: when its operand is exactly `-`, the Runtime reads stdin to its end as UTF-8, before `plan`, `run` or `start`, and the field's schema judges the text, so an empty or invalid text fails with `INVALID_INPUT` like typed text, the issue naming the field `from stdin` instead of quoting the text. Ctrl-C and the run deadline stop a read that never ends; a deadline hit there hints to pipe the text in. When stdin is a terminal, a progress line first says what is read and how to end it (Ctrl-D, or Ctrl-Z then Enter on Windows). Text help shows the field as `<name|->` (`[name|-]` when optional), and `--help --json` marks it `"stdin": true`. `defineCommand` throws for two such args, or for the marker on an option. `runCli` takes `stdin`, a string or a readable stream, read by a `-`; absent, a `-` reads an empty text. The type `StdinSource` is exported.
+- The ports factory's `PortsBase` adds `progress`, `fileError`, `version`, `build` and `self`, which `Context` carries too: a bridge or store writes progress lines (JSON Lines under `--json`) and classifies a failure of its own file as a Command does. `version` and `build` are the CLI's version and bundler stamp as `--version` prints them, `build` absent when unbundled. `self` is the command line that reruns the CLI, `[process.execPath, ...process.execArgv, bin]` from `runCli`'s `bin`, or `[name]`, found on `PATH`, without one, for spawning a hidden Command. The type `BuildStamp` is exported.
+- `ctx.fileError(error, { path, access })` turns an errno failure of a Command's own file access, such as a SQLite store or a log it opens itself, into the Runtime's classified error, with the same codes and hints as `ctx.files`; any other error comes back unchanged. The type `FileAccess` is exported.
+- The Runtime code `NOT_A_FILE` (exit 1), raised for EISDIR, such as `ctx.files.read` of a folder, naming the path. It is exported as a constant.
+- `runCli` takes a `platform` option, which replaces `process.platform` in picking the wording of hints, the `PERMISSION_DENIED` hint and how to end stdin, so a test checks the Windows wording on any OS.
+- `ctx.files.write(path, data, { exclusive, mode })`: `exclusive: true` fails with `ALREADY_EXISTS` when anything is at the path, never leaving half a file there, and `mode` sets the file's permission bits whatever mode an older file had. The type `WriteOptions` is exported.
+- `ctx.files.stat(path)` returns `{ size, id }`, where `id` is the same for every link to one file (device and inode), or `undefined` when nothing is at the path or a part of it is a file. The type `FileStat` is exported.
+- The agent-cli skill's example `links` has `import <text|->`, which saves every link found in a text, read from stdin when given `-`, tags each with every repeated `--tag`, and explains its stdin form in a `help` paragraph. The scaffolded template's `card` takes an optional message to write under the greeting, read from stdin when given `-`, signs the card from every repeated `--from`, and states its cost in a `help` paragraph; its tests cover each.
+
+### Changed
+
+- **Breaking:** `DoctorFinding` is a union over `state`: `ok` (`message`, `fix?`), `problem` (`message`, `fix?`, `code?`) and `skipped` (`message`). A row that throws a `CliError` keeps its code, and `doctor --json` rows carry `code`.
+- **Breaking:** `doctor` fails with one error per non-advisory problem row, with the row's code or `DOCTOR_PROBLEMS` without one, so it exits by the first of 1, 2, 3 and 75 that any of them has, not always 2: an expired session exits 3, a network failure 75. Each error's message is `<cli> doctor found a problem in <row>: <message>`. The report still prints on stdout.
+- **Breaking:** the `Files` interface gains `stat`, and its `write` receives the write options, so every fake passed as `runCli`'s `files` option must implement `stat`. The scaffolded template's fake and the skill's example implement it.
+- **Breaking:** more errno are classified, naming the path: EROFS and EBUSY fail with `PERMISSION_DENIED` (exit 2, with the sandbox hint under a Coding agent), EDQUOT with `DISK_FULL` (exit 2), and ENOTDIR and ENAMETOOLONG with `NOT_FOUND` (exit 1). Each was exit 70 before, so a write Claude Code's Linux sandbox denies with EROFS no longer reads as a bug.
+- **Breaking:** for a Command with `outputs`, after every guard passes and before `apply`, the Runtime creates each output's folder and a temp file in it, so a denied folder fails with `PERMISSION_DENIED` naming the folder before `apply` runs; `--dry-run` and a refused guard create nothing. Without `--force`, the first write to each output during `apply`, through `ctx.files` or a port's `files`, is exclusive: it fails with `ALREADY_EXISTS`, whose hint names the command line with `--force`, if the file appeared meanwhile. A later write to an output the run already wrote replaces it; with `--force` every write replaces.
+- **Breaking:** agent detection follows gh's marker list: `AI_AGENT` (an agent name), `AGENT=amp`, `CODEX_SANDBOX`, `CODEX_CI`, `CODEX_THREAD_ID`, `GEMINI_CLI`, `COPILOT_CLI`, `OPENCODE`, `ANTIGRAVITY_AGENT`, `AUGMENT_AGENT`, `REPL_ID`, `CLAUDE_CODE_IS_COWORK`, `CLAUDECODE`, `CLAUDE_CODE`, `CURSOR_TRACE_ID`, `CURSOR_AGENT`, `CURSOR_EXTENSION_HOST_ROLE=agent-exec`, `TERM_PROGRAM=kiro`, a `.pi/agent` folder on `PATH`, or `GOOSE_PROVIDER`. A marker set to an empty string no longer counts, and `CI` alone no longer counts as an agent, so a usage error in a CI job prints the error and hint without the full help, and a CI job on a TTY gets colour.
+- **Breaking:** under `--json`, stderr is JSON Lines (ADR 0006): each `ctx.progress(message)` writes `{"progress":"<message>"}` as it happens, the Runtime's own progress lines (`finishing <name>`, the `stopping… (Ctrl-C again to quit now)` notice, the stdin announcement) and a spawned child's lines under `progress: true` are written the same way, and a failure's `{"errors":[…]}` stays the last line, so every stderr line parses as JSON. Without `--json`, progress stays plain text. The agent-cli skill and the scaffolded skill say so.
+- On Windows, the `PERMISSION_DENIED` hint says a program may hold the path open, and to close it, then run the same command again.
+- `ctx.files.write` through a symlink replaces the link's target and keeps the link.
+- On Windows, a replacing `ctx.files.write` retries a transient EPERM or EBUSY, such as an antivirus scan holding the file, for about half a second before failing with `PERMISSION_DENIED`.
+- `doctor` and `update` run the npm beside the Node running the CLI (`npm`, or `npm.cmd` on Windows), with that Node first on its `PATH`, so under nvm they install into that Node; with no npm beside it, they run the npm on `PATH` as before. `runCli` gains the option `node`, the path `runProcess` passes as `process.execPath`; absent, npm comes from `PATH`.
+
+### Fixed
+
+- On Windows, an interrupt kills the child `ctx.spawn` started, or the npm `doctor` and `update` run, together with every process it started (`taskkill /T /F`), so Ctrl-C leaves no orphaned processes.
+- `ctx.files.exists` answers false for a path under a file instead of failing.
+
+## v0.4.0 (2026-10-19)
+
+### Added
+
+- The last field of a Command's `args` may be a `z.array(...)`, optionally wrapped in optional or default, which takes every remaining operand: `tool preview a b c` gives `dirs: ["a", "b", "c"]`. None gives an empty array for the schema to judge, or leaves an optional field out so its default applies. Each operand is coerced like a scalar arg of the element's type, and an issue on one names it and its position, as in `<values...> "x" (argument 3): ...`. Text help shows the field as `<name...>` (`[name...]` when optional), and `--help --json` gives it the array schema. `defineCommand` throws when an array field is not the last of `args`.
+- The ports factory receives `PortsBase`, the run's base context: `env`, `cwd`, `packageRoot`, `secret`, `spawn`, `files`, `clock` and `signal`, the same classified, cwd-resolved helpers a Command gets, so an adapter reads a secret or the package root as a Command does. Under `runCli` it sees the test's `env`, `cwd`, `clock`, `files` and `spawn`, and the `ports` option still replaces its result. It runs when a run first reads `ctx.ports`, at most once, and what it throws exits by its Exit class like a Command error; a run that never reads them, such as `doctor` or `update`, never calls it, and a `doctor` row that reads them reports the error as its problem. A factory written as `() => Ports` still type-checks; the type `PortsBase` is exported.
+- A write or destructive Command may declare `force: "<what it replaces>"`, which gives it the Standard flag `--force` with that sentence as the flag's description in help and help JSON. A Command gets `--force` from `outputs`, `force` or both; with `outputs`, `--force` still lifts `OUTPUT_EXISTS`, and `outputs` alone keeps the generic description. `ctx.force` is true only when the caller passed `--force` to a Command that has it, and `plan` sees it under `--dry-run` too. `defineCommand` throws when a read or serve Command declares `force`, or when the sentence is empty.
+- `ctx.files.read(path)` returns a file's bytes as a `Uint8Array`; `ctx.files.list(folder)` returns the names in a folder, sorted, never the Runtime's temp files; `ctx.files.remove(path)` removes a file or a folder with everything in it, and succeeds when the path does not exist; `ctx.files.mkdir(path, { exclusive? })` creates a folder and its missing parents, and with `exclusive: true` fails when the folder exists. Each resolves its path against `ctx.cwd` and fails as `write` does: `PERMISSION_DENIED` (exit 2, with the sandbox hint under a Coding agent), `DISK_FULL` (exit 2) or `NOT_FOUND` (exit 1), naming the path. The type `MkdirOptions` is exported.
+- The Runtime code `ALREADY_EXISTS` (exit 1), raised for EEXIST, such as an exclusive `mkdir` of an existing folder, naming the path, with a hint to pass another path or remove that one. `ALREADY_EXISTS`, `PERMISSION_DENIED`, `DISK_FULL` and `NOT_FOUND` are exported as constants, so a Command catches one with `error instanceof CliError && error.code === ALREADY_EXISTS`.
+
+### Changed
+
+- **Breaking:** `doctor` exits 0 when only its `install` or `registry` row is a problem (not a global install, a newer version on the registry, or the registry unreachable). Those rows still show `problem` with their fix, in text and `--json`, and the fix stays under `next`.
+- **Breaking:** the `Files` interface gains `read`, `list`, `remove` and `mkdir`, so every fake passed as `runCli`'s `files` option must implement them. The scaffolded template's fake and the skill's example implement them.
+- **Breaking:** `ctx.files.write` creates missing parent folders, so a write into a missing folder no longer fails with `NOT_FOUND`.
+- The agent-cli skill teaches every 0.4.0 feature: the ports factory reading `PortsBase`, array positionals, `force` with `ctx.force`, and `ctx.files`' `read`, `list`, `remove` and `mkdir` with a caught `ALREADY_EXISTS`. Its example `links` gains `bundle <folder> <ids...>`, which writes shortcut files into a new folder and replaces an existing one under `--force`, a `web` port that `links check` uses and whose factory reads `LINKS_TOKEN`, and reads `links.json` through `ctx.files`.
+
+### Fixed
+
+- Under a Coding agent, a `PERMISSION_DENIED` on a read (`ctx.files.read`, `list` or `exists`, an unreadable `.env`, a tool `ctx.spawn` cannot run) asks the user to allow reading the path in the sandbox, not to add it to the sandbox's write list.
+- A `$XDG_CONFIG_HOME/<cli>/.env` the Runtime cannot read makes `ctx.secret` fail with `PERMISSION_DENIED` (exit 2) naming the file, with the sandbox hint under an agent, instead of exit 70. A missing `.env` still means no secrets.
+
 ## v0.3.0 (2026-10-19)
 
 ### Added

package/dist/agent-cli.d.ts

@@ -1,8 +1,8 @@
 import { type Cli, type CommandTreeCli, type DefineCommand, type NoPorts, type SingleCommandCli } from "./define.js";
 type PortsFactory<Ports> = NoPorts extends Ports ? {
-    readonly ports?: () => Ports;
+    readonly ports?: CommandTreeCli<Ports>["ports"];
 } : {
-    readonly ports: () => Ports;
+    readonly ports: NonNullable<CommandTreeCli<Ports>["ports"]>;
 };
 type CliDeclaration<Ports, Settings> = (Omit<CommandTreeCli<Ports, Settings>, "ports"> & PortsFactory<Ports>) | (Omit<SingleCommandCli<Ports, Settings>, "ports"> & PortsFactory<Ports>);
 export interface AgentCli<Ports, Settings> {

package/dist/agent-cli.js

@@ -12,7 +12,7 @@ function defineCli(cli) {
     if (cli.commands === undefined)
         return cli;
     const { commands } = cli;
-    const taken = Object.keys(builtInCommands(cli, undefined)).filter((name) => commands[name] !== undefined);
+    const taken = Object.keys(builtInCommands(cli, { bin: undefined, node: undefined })).filter((name) => commands[name] !== undefined);
     if (taken.length > 0) {
         throw new Error(`${cli.name} defines ${taken.join(", ")}, a built-in Command it cannot replace`);
     }

package/dist/agent-cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-cli.js","sourceRoot":"","sources":["../src/agent-cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAIL,gBAAgB,GAGjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAgBnD,SAAS,aAAa,CAAkB,GAAyB;IAC/D,MAAM,UAAU,GAAG,cAAc,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;IACpD,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,GAAG,GAAG,CAAC,IAAI,aAAa,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,8CAA8C,CAC5F,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,SAAS,CAAkB,GAAyB;IAC3D,aAAa,CAAC,GAAG,CAAC,CAAC;IACnB,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS;QAAE,OAAO,GAAG,CAAC;IAC3C,MAAM,EAAE,QAAQ,EAAE,GAAG,GAAG,CAAC;IACzB,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC,MAAM,CAC/D,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,SAAS,CACvC,CAAC;IACF,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,GAAG,GAAG,CAAC,IAAI,YAAY,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,wCAAwC,CAChF,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ;IACtB,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAmB,EAAE,SAAS,EAAE,CAAC;AAC3E,CAAC"}
+{"version":3,"file":"agent-cli.js","sourceRoot":"","sources":["../src/agent-cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAIL,gBAAgB,GAGjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAgBnD,SAAS,aAAa,CAAkB,GAAyB;IAC/D,MAAM,UAAU,GAAG,cAAc,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;IACpD,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,GAAG,GAAG,CAAC,IAAI,aAAa,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,8CAA8C,CAC5F,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,SAAS,CAAkB,GAAyB;IAC3D,aAAa,CAAC,GAAG,CAAC,CAAC;IACnB,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS;QAAE,OAAO,GAAG,CAAC;IAC3C,MAAM,EAAE,QAAQ,EAAE,GAAG,GAAG,CAAC;IACzB,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,MAAM,CACzF,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,SAAS,CACvC,CAAC;IACF,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,GAAG,GAAG,CAAC,IAAI,YAAY,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,wCAAwC,CAChF,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ;IACtB,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAmB,EAAE,SAAS,EAAE,CAAC;AAC3E,CAAC"}

package/dist/agent.d.ts

@@ -1,4 +1,6 @@
-import type { Env } from "./define.js";
-export declare const AGENT_VARIABLES: readonly ["CLAUDECODE", "CODEX_CI", "CODEX_SANDBOX", "GEMINI_CLI", "CURSOR_AGENT", "CI"];
-/** Whether a Coding agent, not a person, is running the Agent CLI. */
+import type { Env } from "./context.js";
+/**
+ * Whether a Coding agent, not a person, is running the Agent CLI. Some Coding agents run commands
+ * in a PTY, so a TTY alone doesn't mean a person is watching.
+ */
 export declare function isAgent(env: Env): boolean;

package/dist/agent.js

@@ -1,14 +1,35 @@
-// Some Coding agents run commands in a PTY, so a TTY alone doesn't mean a person is watching.
-export const AGENT_VARIABLES = [
-    "CLAUDECODE",
-    "CODEX_CI",
-    "CODEX_SANDBOX",
-    "GEMINI_CLI",
-    "CURSOR_AGENT",
-    "CI",
+const AGENT_NAME = /^[a-zA-Z0-9_-]+$/u;
+const isSet = (name) => (env) => (env[name] ?? "") !== "";
+const equals = (name, value) => (env) => env[name] === value;
+// Copied in order from gh, which keeps it current as agents appear:
+// https://github.com/cli/cli/blob/17142e08db2e300b37e6da1ddcfb651eb6d9c587/internal/agents/detect.go
+const MARKERS = [
+    (env) => AGENT_NAME.test(env.AI_AGENT ?? ""),
+    equals("AGENT", "amp"),
+    isSet("CODEX_SANDBOX"),
+    isSet("CODEX_CI"),
+    isSet("CODEX_THREAD_ID"),
+    isSet("GEMINI_CLI"),
+    isSet("COPILOT_CLI"),
+    isSet("OPENCODE"),
+    isSet("ANTIGRAVITY_AGENT"),
+    isSet("AUGMENT_AGENT"),
+    isSet("REPL_ID"),
+    isSet("CLAUDE_CODE_IS_COWORK"),
+    isSet("CLAUDECODE"),
+    isSet("CLAUDE_CODE"),
+    isSet("CURSOR_TRACE_ID"),
+    isSet("CURSOR_AGENT"),
+    equals("CURSOR_EXTENSION_HOST_ROLE", "agent-exec"),
+    equals("TERM_PROGRAM", "kiro"),
+    (env) => ["/.pi/agent", "\\.pi\\agent"].some((dir) => (env.PATH ?? "").includes(dir)),
+    isSet("GOOSE_PROVIDER"),
 ];
-/** Whether a Coding agent, not a person, is running the Agent CLI. */
+/**
+ * Whether a Coding agent, not a person, is running the Agent CLI. Some Coding agents run commands
+ * in a PTY, so a TTY alone doesn't mean a person is watching.
+ */
 export function isAgent(env) {
-    return AGENT_VARIABLES.some((name) => env[name] !== undefined);
+    return MARKERS.some((marker) => marker(env));
 }
 //# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAEA,8FAA8F;AAC9F,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,YAAY;IACZ,UAAU;IACV,eAAe;IACf,YAAY;IACZ,cAAc;IACd,IAAI;CACI,CAAC;AAEX,sEAAsE;AACtE,MAAM,UAAU,OAAO,CAAC,GAAQ;IAC9B,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC,CAAC;AACjE,CAAC"}
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAG,mBAAmB,CAAC;AAEvC,MAAM,KAAK,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,GAAQ,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC;AACvE,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,KAAa,EAAE,EAAE,CAAC,CAAC,GAAQ,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC;AAElF,oEAAoE;AACpE,qGAAqG;AACrG,MAAM,OAAO,GAAuC;IAClD,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC;IAC5C,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC;IACtB,KAAK,CAAC,eAAe,CAAC;IACtB,KAAK,CAAC,UAAU,CAAC;IACjB,KAAK,CAAC,iBAAiB,CAAC;IACxB,KAAK,CAAC,YAAY,CAAC;IACnB,KAAK,CAAC,aAAa,CAAC;IACpB,KAAK,CAAC,UAAU,CAAC;IACjB,KAAK,CAAC,mBAAmB,CAAC;IAC1B,KAAK,CAAC,eAAe,CAAC;IACtB,KAAK,CAAC,SAAS,CAAC;IAChB,KAAK,CAAC,uBAAuB,CAAC;IAC9B,KAAK,CAAC,YAAY,CAAC;IACnB,KAAK,CAAC,aAAa,CAAC;IACpB,KAAK,CAAC,iBAAiB,CAAC;IACxB,KAAK,CAAC,cAAc,CAAC;IACrB,MAAM,CAAC,4BAA4B,EAAE,YAAY,CAAC;IAClD,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC;IAC9B,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IACrF,KAAK,CAAC,gBAAgB,CAAC;CACxB,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,GAAQ;IAC9B,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;AAC/C,CAAC"}

package/dist/built-ins.d.ts

@@ -1,3 +1,8 @@
 import type { Commands, CommandTreeCli } from "./define.js";
+/** How the CLI was started: the script, and the Node running it. */
+export interface Launch {
+    readonly bin: string | undefined;
+    readonly node: string | undefined;
+}
 /** The Commands the Runtime adds to a multi-Command CLI: `update` only when it declares an install. */
-export declare function builtInCommands(cli: CommandTreeCli, bin: string | undefined): Commands;
+export declare function builtInCommands(cli: CommandTreeCli, launch: Launch): Commands;

package/dist/built-ins.js

@@ -1,10 +1,10 @@
 import { doctorCommand } from "./doctor.js";
 import { updateCommand } from "./update.js";
 /** The Commands the Runtime adds to a multi-Command CLI: `update` only when it declares an install. */
-export function builtInCommands(cli, bin) {
+export function builtInCommands(cli, launch) {
     return {
-        doctor: doctorCommand(cli, bin),
-        ...(cli.install === undefined ? {} : { update: updateCommand(cli, cli.install, bin) }),
+        doctor: doctorCommand(cli, launch),
+        ...(cli.install === undefined ? {} : { update: updateCommand(cli, cli.install, launch) }),
     };
 }
 //# sourceMappingURL=built-ins.js.map

package/dist/built-ins.js.map

@@ -1 +1 @@
-{"version":3,"file":"built-ins.js","sourceRoot":"","sources":["../src/built-ins.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,uGAAuG;AACvG,MAAM,UAAU,eAAe,CAAC,GAAmB,EAAE,GAAuB;IAC1E,OAAO;QACL,MAAM,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC;QAC/B,GAAG,CAAC,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC;KACvF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"built-ins.js","sourceRoot":"","sources":["../src/built-ins.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAQ5C,uGAAuG;AACvG,MAAM,UAAU,eAAe,CAAC,GAAmB,EAAE,MAAc;IACjE,OAAO;QACL,MAAM,EAAE,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC;QAClC,GAAG,CAAC,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,CAAC;KAC1F,CAAC;AACJ,CAAC"}

package/dist/command-spec.d.ts

@@ -9,6 +9,9 @@ export interface CommandSpec {
     readonly commandLine: string;
     readonly command: Command;
     readonly description: string;
+    readonly help: string | undefined;
+    readonly hidden: boolean;
+    readonly operator: boolean;
     readonly effect: Command["effect"];
     readonly examples: readonly Example[];
     readonly args: readonly InputField[];
@@ -24,5 +27,7 @@ export interface GroupSpec {
     readonly commands: Readonly<Record<string, SpecNode>>;
 }
 export type SpecNode = CommandSpec | GroupSpec;
+/** The group's Commands and groups that help and suggestions may name: hidden Commands left out. */
+export declare function visibleCommands({ commands }: GroupSpec): Readonly<Record<string, SpecNode>>;
 export declare function commandSpec(commandLine: string, command: Command): CommandSpec;
 export declare function groupSpec(commandLine: string, commands: Commands): GroupSpec;

package/dist/command-spec.js

@@ -2,11 +2,19 @@ import { isCommand } from "./define.js";
 import { standardFlagsFor } from "./flags.js";
 import { argFields, optionFields } from "./input.js";
 import { listSpec } from "./list.js";
+import { hasPlan } from "./planned.js";
+/** The group's Commands and groups that help and suggestions may name: hidden Commands left out. */
+export function visibleCommands({ commands }) {
+    return Object.fromEntries(Object.entries(commands).filter(([, node]) => node.kind === "group" || !node.hidden));
+}
 function declaredOf(command) {
-    const planned = command.effect === "write" || command.effect === "destructive";
+    if (!hasPlan(command)) {
+        return { outputs: false, force: undefined, cost: false };
+    }
     return {
-        outputs: planned && command.outputs !== undefined,
-        cost: planned && command.cost !== undefined,
+        outputs: command.outputs !== undefined,
+        force: command.force,
+        cost: command.cost !== undefined,
     };
 }
 export function commandSpec(commandLine, command) {
@@ -16,6 +24,9 @@ export function commandSpec(commandLine, command) {
         commandLine,
         command,
         description: command.description,
+        help: command.help,
+        hidden: command.hidden === true,
+        operator: command.operator === true,
         effect: command.effect,
         examples: command.examples,
         args: argFields(command.args),

package/dist/command-spec.js.map

@@ -1 +1 @@
-{"version":3,"file":"command-spec.js","sourceRoot":"","sources":["../src/command-spec.ts"],"names":[],"mappings":"AACA,OAAO,EAA6C,SAAS,EAAE,MAAM,aAAa,CAAC;AACnF,OAAO,EAAoC,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAChF,OAAO,EAAE,SAAS,EAAmB,YAAY,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAiB,QAAQ,EAAE,MAAM,WAAW,CAAC;AA0BpD,SAAS,UAAU,CAAC,OAAgB;IAClC,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,KAAK,OAAO,IAAI,OAAO,CAAC,MAAM,KAAK,aAAa,CAAC;IAC/E,OAAO;QACL,OAAO,EAAE,OAAO,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS;QACjD,IAAI,EAAE,OAAO,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS;KAC5C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,WAAmB,EAAE,OAAgB;IAC/D,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E,OAAO;QACL,IAAI,EAAE,SAAS;QACf,WAAW;QACX,OAAO;QACP,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,IAAI,EAAE,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC;QAC7B,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC;QACtC,aAAa,EAAE,gBAAgB,CAAC,OAAO,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC;QAC1E,IAAI;QACJ,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,OAAO,CAAC,MAAM;KACvC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,WAAmB,EAAE,QAAkB;IAC/D,OAAO;QACL,IAAI,EAAE,OAAO;QACb,WAAW;QACX,QAAQ,EAAE,MAAM,CAAC,WAAW,CAC1B,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,WAAW,IAAI,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,CAC5F;KACF,CAAC;AACJ,CAAC;AAED,SAAS,MAAM,CAAC,WAAmB,EAAE,IAAwB;IAC3D,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;AACzF,CAAC"}
+{"version":3,"file":"command-spec.js","sourceRoot":"","sources":["../src/command-spec.ts"],"names":[],"mappings":"AACA,OAAO,EAA6C,SAAS,EAAE,MAAM,aAAa,CAAC;AACnF,OAAO,EAAoC,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAChF,OAAO,EAAE,SAAS,EAAmB,YAAY,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAiB,QAAQ,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AA6BvC,oGAAoG;AACpG,MAAM,UAAU,eAAe,CAAC,EAAE,QAAQ,EAAa;IACrD,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CACrF,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,OAAgB;IAClC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAC3D,CAAC;IACD,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,OAAO,KAAK,SAAS;QACtC,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,IAAI,EAAE,OAAO,CAAC,IAAI,KAAK,SAAS;KACjC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,WAAmB,EAAE,OAAgB;IAC/D,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E,OAAO;QACL,IAAI,EAAE,SAAS;QACf,WAAW;QACX,OAAO;QACP,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,MAAM,EAAE,OAAO,CAAC,MAAM,KAAK,IAAI;QAC/B,QAAQ,EAAE,OAAO,CAAC,QAAQ,KAAK,IAAI;QACnC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,IAAI,EAAE,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC;QAC7B,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC;QACtC,aAAa,EAAE,gBAAgB,CAAC,OAAO,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC;QAC1E,IAAI;QACJ,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,OAAO,CAAC,MAAM;KACvC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,WAAmB,EAAE,QAAkB;IAC/D,OAAO;QACL,IAAI,EAAE,OAAO;QACb,WAAW;QACX,QAAQ,EAAE,MAAM,CAAC,WAAW,CAC1B,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,WAAW,IAAI,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,CAC5F;KACF,CAAC;AACJ,CAAC;AAED,SAAS,MAAM,CAAC,WAAmB,EAAE,IAAwB;IAC3D,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;AACzF,CAAC"}

package/dist/confirm.js

@@ -1,13 +1,17 @@
 import { UsageError } from "./errors.js";
 import { CONFIRM_FLAG } from "./flags.js";
-import { commandLineWith } from "./invocation.js";
+import { commandLineOf } from "./invocation.js";
 export const CONFIRMATION_REQUIRED = "CONFIRMATION_REQUIRED";
 export const CONFIRMATION_MISMATCH = "CONFIRMATION_MISMATCH";
 export function checkConfirmation({ invocation, commandLine, given }, expected) {
     if (given === expected) {
         return;
     }
-    const hint = `to confirm, run \`${commandLineWith(invocation, CONFIRM_FLAG.flag, expected)}\``;
+    const confirmed = commandLineOf(invocation, {
+        remove: [CONFIRM_FLAG.flag],
+        add: [CONFIRM_FLAG.flag, expected],
+    });
+    const hint = `to confirm, run \`${confirmed}\``;
     if (given === undefined) {
         throw new UsageError({
             code: CONFIRMATION_REQUIRED,

package/dist/confirm.js.map

@@ -1 +1 @@
-{"version":3,"file":"confirm.js","sourceRoot":"","sources":["../src/confirm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAmB,MAAM,iBAAiB,CAAC;AAEnE,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAuB,CAAC;AAC7D,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAuB,CAAC;AAQ7D,MAAM,UAAU,iBAAiB,CAC/B,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,EAAgB,EAChD,QAAgB;IAEhB,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvB,OAAO;IACT,CAAC;IACD,MAAM,IAAI,GAAG,qBAAqB,eAAe,CAAC,UAAU,EAAE,YAAY,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC;IAC/F,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,UAAU,CAAC;YACnB,IAAI,EAAE,qBAAqB;YAC3B,OAAO,EAAE,KAAK,WAAW,+BAA+B,YAAY,CAAC,IAAI,EAAE;YAC3E,IAAI;SACL,CAAC,CAAC;IACL,CAAC;IACD,MAAM,IAAI,UAAU,CAAC;QACnB,IAAI,EAAE,qBAAqB;QAC3B,OAAO,EAAE,GAAG,YAAY,CAAC,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,mCAAmC,WAAW,IAAI;QACxG,IAAI;KACL,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"confirm.js","sourceRoot":"","sources":["../src/confirm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAmB,MAAM,iBAAiB,CAAC;AAEjE,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAuB,CAAC;AAC7D,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAuB,CAAC;AAQ7D,MAAM,UAAU,iBAAiB,CAC/B,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,EAAgB,EAChD,QAAgB;IAEhB,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvB,OAAO;IACT,CAAC;IACD,MAAM,SAAS,GAAG,aAAa,CAAC,UAAU,EAAE;QAC1C,MAAM,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC;QAC3B,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,QAAQ,CAAC;KACnC,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,qBAAqB,SAAS,IAAI,CAAC;IAChD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,UAAU,CAAC;YACnB,IAAI,EAAE,qBAAqB;YAC3B,OAAO,EAAE,KAAK,WAAW,+BAA+B,YAAY,CAAC,IAAI,EAAE;YAC3E,IAAI;SACL,CAAC,CAAC;IACL,CAAC;IACD,MAAM,IAAI,UAAU,CAAC;QACnB,IAAI,EAAE,qBAAqB;QAC3B,OAAO,EAAE,GAAG,YAAY,CAAC,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,mCAAmC,WAAW,IAAI;QACxG,IAAI;KACL,CAAC,CAAC;AACL,CAAC"}

package/dist/context.d.ts

@@ -0,0 +1,102 @@
+import type * as z from "zod";
+import type { Clock } from "./clock.js";
+import type { FileAccess } from "./errno.js";
+import type { Files } from "./files.js";
+import type { CommandLineChange } from "./invocation.js";
+import type { Secret } from "./secrets.js";
+import type { ContextSpawn } from "./spawn.js";
+export type Env = Readonly<Record<string, string | undefined>>;
+export interface PollOptions {
+    readonly intervalMs: number;
+    /** Stops the polling when it aborts, as `ctx.signal` does; pass `ctx.deadline(ms)` for a wait. */
+    readonly signal?: AbortSignal;
+}
+/** The commit a build was made from and when, stamped by the bundler. */
+export interface BuildStamp {
+    readonly sha: string;
+    readonly dirty: boolean;
+    readonly builtAt: string;
+}
+export interface Context<Ports = unknown, Settings = unknown> {
+    readonly cwd: string;
+    readonly env: Env;
+    /** The CLI's version, as `--version` prints it. */
+    readonly version: string;
+    /** The bundler's stamp, as `--version` prints it; absent when the CLI runs unbundled. */
+    readonly build: BuildStamp | undefined;
+    /**
+     * The command line that reruns this CLI, to spawn one of its hidden Commands: Node, its flags and
+     * the bin, or the CLI's name, found on PATH, when run without a bin.
+     */
+    readonly self: readonly string[];
+    /** The folder holding this CLI's `package.json`, for reading files shipped in the package. */
+    readonly packageRoot: string;
+    /** Writes a plain line to stderr, for long work; it never reaches stdout. */
+    progress(message: string): void;
+    /**
+     * Aborts when the run is interrupted (Ctrl-C) or hits the Command's run deadline; pass it to
+     * `fetch` and child processes.
+     */
+    readonly signal: AbortSignal;
+    /** Returns a signal that also aborts, with `DEADLINE_EXCEEDED`, once `ms` have passed. */
+    deadline(ms: number): AbortSignal;
+    /**
+     * Runs a step that must not stop halfway: the run waits for it even when stopped, and then
+     * prints `finishing <name>` on stderr.
+     */
+    runToEnd<T>(name: string, work: () => Promise<T>): Promise<T>;
+    /**
+     * Records the data done so far, in the shape `render` takes; the last call wins. A run that then
+     * fails, hits a deadline or is interrupted prints it; a returned value replaces it.
+     */
+    deliver(data: unknown): void;
+    /** The outside systems the CLI declared with `agentCli<Ports>()`. */
+    readonly ports: Ports;
+    /**
+     * Reads, lists, removes and atomically writes files and folders, paths resolved against `cwd`; a
+     * failure fails the run with `PERMISSION_DENIED`, `DISK_FULL`, `NOT_FOUND`, `NOT_A_FILE` or
+     * `ALREADY_EXISTS`.
+     */
+    readonly files: Files;
+    /**
+     * Runs a child process, killed when the run is interrupted; `check: true` fails the run with
+     * `TOOL_FAILED` and the tail of its stderr when it exits non-zero.
+     */
+    readonly spawn: ContextSpawn;
+    /** Deadlines, `poll` and the grace period after an interrupt run on it. */
+    readonly clock: Clock;
+    /**
+     * Calls `check` until it returns a value other than `undefined`, sleeping `intervalMs` between
+     * calls; it stops when `ctx.signal` or the given `signal` aborts.
+     */
+    poll<T>(check: () => T | undefined | Promise<T | undefined>, options: PollOptions): Promise<T>;
+    /** The Project file found by walking up from `cwd`, parsed by the CLI's schema. */
+    readonly project: Project<Settings> | undefined;
+    /** Reads `name` from the env, then from `$XDG_CONFIG_HOME/<cli>/.env`, with where it came from. */
+    secret(name: string): Secret | undefined;
+    /**
+     * Classifies an errno failure of the CLI's own file access, such as a store it opens itself, as
+     * `ctx.files` does; any other error comes back unchanged.
+     */
+    fileError(error: unknown, at: FileAccess): unknown;
+    /** Whether the caller passed `--force`; always false for a Command without it. */
+    readonly force: boolean;
+    /**
+     * The command line as the caller typed it, starting with the CLI's name and shell-quoted, with
+     * each flag in `remove` dropped along with its value and the words in `add` placed before any
+     * `--`; for the hint that names the command to run next.
+     */
+    commandLine(change?: CommandLineChange): string;
+}
+/** The slice of `Context` the ports factory receives, which exists before the ports do. */
+export type PortsBase = Pick<Context, "env" | "cwd" | "packageRoot" | "secret" | "spawn" | "files" | "clock" | "signal" | "progress" | "version" | "build" | "self" | "fileError">;
+export interface Project<Settings = unknown> {
+    /** The folder holding the Project file. */
+    readonly root: string;
+    readonly settings: Settings;
+}
+/** Names the Project file and the schema its JSON must match. */
+export interface ProjectFile<Settings = unknown> {
+    readonly file: string;
+    readonly schema: z.ZodType<Settings>;
+}

package/dist/context.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":""}

package/dist/cost.js

@@ -1,6 +1,6 @@
 import { CliError } from "./errors.js";
 import { YES_FLAG } from "./flags.js";
-import { commandLineWith } from "./invocation.js";
+import { commandLineOf } from "./invocation.js";
 export const NOT_CONFIRMED = "NOT_CONFIRMED";
 /** Refuses a run whose Plan states a cost the caller has not approved with `--yes`. */
 export function checkCost({ invocation, commandLine, yes }, cost) {
@@ -10,7 +10,7 @@ export function checkCost({ invocation, commandLine, yes }, cost) {
     throw new CliError({
         code: NOT_CONFIRMED,
         message: `\`${commandLine}\` needs ${YES_FLAG.flag}: ${cost}`,
-        hint: `to approve the cost, run \`${commandLineWith(invocation, YES_FLAG.flag)}\``,
+        hint: `to approve the cost, run \`${commandLineOf(invocation, { add: [YES_FLAG.flag] })}\``,
     });
 }
 //# sourceMappingURL=cost.js.map

package/dist/cost.js.map

@@ -1 +1 @@
-{"version":3,"file":"cost.js","sourceRoot":"","sources":["../src/cost.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,eAAe,EAAmB,MAAM,iBAAiB,CAAC;AAEnE,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC;AAQ7C,uFAAuF;AACvF,MAAM,UAAU,SAAS,CACvB,EAAE,UAAU,EAAE,WAAW,EAAE,GAAG,EAAY,EAC1C,IAAwB;IAExB,IAAI,IAAI,KAAK,SAAS,IAAI,GAAG,EAAE,CAAC;QAC9B,OAAO;IACT,CAAC;IACD,MAAM,IAAI,QAAQ,CAAC;QACjB,IAAI,EAAE,aAAa;QACnB,OAAO,EAAE,KAAK,WAAW,YAAY,QAAQ,CAAC,IAAI,KAAK,IAAI,EAAE;QAC7D,IAAI,EAAE,8BAA8B,eAAe,CAAC,UAAU,EAAE,QAAQ,CAAC,IAAI,CAAC,IAAI;KACnF,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"cost.js","sourceRoot":"","sources":["../src/cost.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,aAAa,EAAmB,MAAM,iBAAiB,CAAC;AAEjE,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC;AAQ7C,uFAAuF;AACvF,MAAM,UAAU,SAAS,CACvB,EAAE,UAAU,EAAE,WAAW,EAAE,GAAG,EAAY,EAC1C,IAAwB;IAExB,IAAI,IAAI,KAAK,SAAS,IAAI,GAAG,EAAE,CAAC;QAC9B,OAAO;IACT,CAAC;IACD,MAAM,IAAI,QAAQ,CAAC;QACjB,IAAI,EAAE,aAAa;QACnB,OAAO,EAAE,KAAK,WAAW,YAAY,QAAQ,CAAC,IAAI,KAAK,IAAI,EAAE;QAC7D,IAAI,EAAE,8BAA8B,aAAa,CAAC,UAAU,EAAE,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI;KAC5F,CAAC,CAAC;AACL,CAAC"}

package/dist/define.d.ts

@@ -1,75 +1,13 @@
 import type * as z from "zod";
-import type { Clock } from "./clock.js";
+import type { BuildStamp, Context, PortsBase, ProjectFile } from "./context.js";
 import type { ErrorTable } from "./error-table.js";
-import type { Files } from "./files.js";
 import { type StandardFlagName } from "./flags.js";
 import type { Page, PageInput, RowSchema } from "./list.js";
-import type { Secret } from "./secrets.js";
-import type { ContextSpawn } from "./spawn.js";
 import type { Style } from "./style.js";
-export type Env = Readonly<Record<string, string | undefined>>;
 export interface Example {
     readonly command: string;
     readonly note: string;
 }
-export interface PollOptions {
-    readonly intervalMs: number;
-}
-export interface Context<Ports = unknown, Settings = unknown> {
-    readonly cwd: string;
-    readonly env: Env;
-    /** The folder holding this CLI's `package.json`, for reading files shipped in the package. */
-    readonly packageRoot: string;
-    /** Writes a plain line to stderr, for long work; it never reaches stdout. */
-    progress(message: string): void;
-    /**
-     * Aborts when the run is interrupted (Ctrl-C) or hits the Command's run deadline; pass it to
-     * `fetch` and child processes.
-     */
-    readonly signal: AbortSignal;
-    /** Returns a signal that also aborts, with `DEADLINE_EXCEEDED`, once `ms` have passed. */
-    deadline(ms: number): AbortSignal;
-    /**
-     * Runs a step that must not stop halfway: the run waits for it even when stopped, and then
-     * prints `finishing <name>` on stderr.
-     */
-    runToEnd<T>(name: string, work: () => Promise<T>): Promise<T>;
-    /**
-     * Records the data done so far, in the shape `render` takes; the last call wins. A run that then
-     * fails, hits a deadline or is interrupted prints it; a returned value replaces it.
-     */
-    deliver(data: unknown): void;
-    /** The outside systems the CLI declared with `agentCli<Ports>()`. */
-    readonly ports: Ports;
-    /** Writes files atomically and tells whether one exists; a failure fails the run with `PERMISSION_DENIED`, `DISK_FULL` or `NOT_FOUND`. */
-    readonly files: Files;
-    /**
-     * Runs a child process, killed when the run is interrupted; `check: true` fails the run with
-     * `TOOL_FAILED` and the tail of its stderr when it exits non-zero.
-     */
-    readonly spawn: ContextSpawn;
-    /** Deadlines, `poll` and the grace period after an interrupt run on it. */
-    readonly clock: Clock;
-    /**
-     * Calls `check` until it returns a value other than `undefined`, sleeping `intervalMs` between
-     * calls; it stops when `ctx.signal` aborts.
-     */
-    poll<T>(check: () => T | undefined | Promise<T | undefined>, options: PollOptions): Promise<T>;
-    /** The Project file found by walking up from `cwd`, parsed by the CLI's schema. */
-    readonly project: Project<Settings> | undefined;
-    /** Reads `name` from the env, then from `$XDG_CONFIG_HOME/<cli>/.env`, with where it came from. */
-    secret(name: string): Secret | undefined;
-}
-export interface Project<Settings = unknown> {
-    /** The folder holding the Project file. */
-    readonly root: string;
-    readonly settings: Settings;
-}
-/** Names the Project file and the schema its JSON must match. */
-export interface ProjectFile<Settings = unknown> {
-    readonly file: string;
-    readonly schema: z.ZodType<Settings>;
-}
 export type InputSchema = z.ZodObject;
 export type NoPorts = Record<never, never>;
 export type NoInput = z.ZodObject<Record<never, never>>;
@@ -87,13 +25,25 @@ export interface Tool {
 /** Bounds a whole run, so a long run stops before the caller's own timeout and can be continued. */
 export interface RunDeadline<In> {
     readonly ms: number;
-    /** The command line that continues the work, given as the hint of the run's `DEADLINE_EXCEEDED`. */
-    resume(input: In): string;
+    /**
+     * The command line that continues the work, given as the hint of the run's `DEADLINE_EXCEEDED`;
+     * `commandLine` is `ctx.commandLine`.
+     */
+    resume(input: In, commandLine: Context["commandLine"]): string;
 }
 interface CommandBase<Args extends InputSchema, Options extends InputSchema> {
     readonly name: string;
     readonly description: string;
+    /** A paragraph printed after the options in text help, and carried as `help` in help JSON. */
+    readonly help?: string;
     readonly examples: readonly Example[];
+    /** Left out of help, help JSON, the root examples and suggestions, but still routed and run. */
+    readonly hidden?: boolean;
+    /**
+     * Only a person at a terminal runs it: under a Coding agent the run fails with `NEEDS_OPERATOR`
+     * before `plan`, `run` or `start`, naming the line the operator types.
+     */
+    readonly operator?: true;
     /** Missing ones fail the run with `TOOL_MISSING` before `plan`, `run` or `start`. */
     readonly tools?: readonly Tool[];
     readonly args?: Args;
@@ -135,6 +85,11 @@ interface PlannedCommand<Args extends InputSchema, Options extends InputSchema,
      * a run refuses with `OUTPUT_EXISTS` when any of them exists.
      */
     outputs?(plan: Plan): readonly string[];
+    /**
+     * What `--force` replaces for this Command, shown as the flag's help. Declaring it adds
+     * `--force`, which `plan` and `apply` read as `ctx.force`.
+     */
+    readonly force?: string;
 }
 export interface WriteCommand<Args extends InputSchema, Options extends InputSchema, Plan, Data, Ports = unknown, Settings = unknown> extends PlannedCommand<Args, Options, Plan, Data, Ports, Settings> {
     readonly effect: "write";
@@ -159,16 +114,16 @@ interface CliBase<Ports, Settings> {
     readonly name: string;
     readonly version: string;
     /** The commit the build was made from and when, stamped by the bundler; `--version` prints it. */
-    readonly build?: {
-        readonly sha: string;
-        readonly dirty: boolean;
-        readonly builtAt: string;
-    };
+    readonly build?: BuildStamp;
     /** Every code the CLI throws; a code missing here exits 70, as a bug. */
     readonly errors?: ErrorTable;
-    /** Builds the real ports when a Command runs; `runCli`'s `ports` replaces them in a test. */
-    readonly ports?: () => Ports;
+    /** Builds the real ports when a run first reads `ctx.ports`; `runCli`'s `ports` replaces them in a test. */
+    readonly ports?: (base: PortsBase) => Ports;
     readonly project?: ProjectFile<Settings>;
+    /** Where `npx skills add` installs the CLI's skill from; read from package.json `repository` when absent. */
+    readonly skill?: {
+        readonly source: string;
+    };
 }
 /** Where an Agent CLI is published and how it is installed; `doctor` and `update` read it. */
 export interface GlobalInstall {
@@ -176,12 +131,22 @@ export interface GlobalInstall {
     readonly package: string;
     readonly registry: string;
 }
-export interface DoctorFinding {
-    readonly state: "ok" | "problem";
+/** What a `doctor` row found. A skipped row was not checked, and never fails `doctor`. */
+export type DoctorFinding = {
+    readonly state: "ok";
+    readonly message: string;
+    readonly fix?: string;
+} | {
+    readonly state: "problem";
     readonly message: string;
     /** The command that fixes the problem. */
     readonly fix?: string;
-}
+    /** A code of the Error table or the Runtime's that `doctor` fails with; `DOCTOR_PROBLEMS` when absent. */
+    readonly code?: string;
+} | {
+    readonly state: "skipped";
+    readonly message: string;
+};
 /** A row the CLI adds to `doctor`, for a system it depends on. */
 export interface DoctorCheck<Ports = unknown, Settings = unknown> {
     readonly name: string;
@@ -203,6 +168,8 @@ export interface CommandTreeCli<Ports = unknown, Settings = unknown> extends Cli
         readonly node?: string;
     };
     readonly doctor?: readonly DoctorCheck<Ports, Settings>[];
+    /** Tools `doctor` checks besides the Commands' own; no Command requires them. */
+    readonly tools?: readonly Tool[];
 }
 /** An Agent CLI that is one Command, run with no Command name, as in `tool <args>`. */
 export interface SingleCommandCli<Ports = unknown, Settings = unknown> extends CliBase<Ports, Settings> {