@duyquangnvx/agent-cli 0.17.0 → 0.18.0

package/docs/example/store.ts

@@ -0,0 +1,62 @@
+import { join } from "node:path";
+import type { CliError, Context } from "@duyquangnvx/agent-cli";
+import * as z from "zod";
+import { cliError } from "./define.js";
+
+export const linkSchema = z.object({
+  id: z.number().int(),
+  url: z.string(),
+  tags: z.array(z.string()),
+  snapshot: z.string().optional(),
+});
+
+export type Link = z.infer<typeof linkSchema>;
+
+/** A run's files and the folder their paths resolve against. */
+export type RunFiles = Pick<Context, "cwd" | "files">;
+
+export const LINKS_FILE = "links.json";
+
+export function linksPath(cwd: string): string {
+  return join(cwd, LINKS_FILE);
+}
+
+// File content is a boundary: parse it, and turn a bad file into an error the caller can act on.
+export async function readLinks(ctx: RunFiles): Promise<Link[]> {
+  if (!(await ctx.files.exists(LINKS_FILE))) {
+    return [];
+  }
+  const text = new TextDecoder().decode(await ctx.files.read(LINKS_FILE));
+  try {
+    return z.array(linkSchema).parse(JSON.parse(text));
+  } catch (error) {
+    throw cliError(
+      "CORRUPT_DATA",
+      {
+        message: `${linksPath(ctx.cwd)} is not valid links data`,
+        hint: `fix it or delete it to start with no links`,
+      },
+      { cause: error },
+    );
+  }
+}
+
+export async function writeLinks(ctx: RunFiles, links: readonly Link[]): Promise<void> {
+  await ctx.files.write(LINKS_FILE, `${JSON.stringify(links, null, 2)}\n`);
+}
+
+function notFound(id: number): CliError {
+  return cliError("LINK_NOT_FOUND", {
+    message: `no link with id ${id}`,
+    hint: "list the links to see their ids",
+    next: [["list"]],
+  });
+}
+
+export async function linkWithId(ctx: RunFiles, id: number): Promise<Link> {
+  const link = (await readLinks(ctx)).find((candidate) => candidate.id === id);
+  if (link === undefined) {
+    throw notFound(id);
+  }
+  return link;
+}

package/docs/example/tsdown.config.ts

@@ -0,0 +1,33 @@
+import { execFileSync } from "node:child_process";
+import { defineConfig } from "tsdown";
+
+function git(args: readonly string[]): string {
+  try {
+    return execFileSync("git", args, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+  } catch (error) {
+    throw new Error("the build stamps the commit it is made from: commit to git first", {
+      cause: error,
+    });
+  }
+}
+
+const dirty = git(["status", "--porcelain"]) !== "";
+const build = {
+  sha: git(["rev-parse", "--short=7", "HEAD"]),
+  dirty,
+  // A clean build stamps its commit's time, so a release that rebuilds a commit gets the same bundle.
+  builtAt: new Date(dirty ? Date.now() : git(["log", "-1", "--format=%cI", "HEAD"])).toISOString(),
+};
+
+export default defineConfig({
+  entry: ["bin.ts"],
+  platform: "node",
+  format: "esm",
+  fixedExtension: false,
+  // The bin bundles the Runtime and zod, so only this CLI's own release changes its behaviour.
+  deps: { onlyBundle: false },
+  define: { __AGENT_CLI_BUILD__: JSON.stringify(build) },
+});

package/docs/getting-started.md

@@ -0,0 +1,19 @@
+# Getting started
+
+```sh
+pnpm create @duyquangnvx/agent-cli <name> --description "One line saying what it does" --skill-hub-git https://github.com/<owner>/skills.git
+```
+
+The Scaffolder creates `./<name>`, a working Agent CLI whose example Commands you replace; run it with `--dry-run` first to list every file it would write. `--skill-hub-git` names the git URL of a Skill Hub each release commits the CLI skill to: it becomes `skill.source` in `defineCli`, `skillHub: { git }` in `scripts/release.ts` and the skill's install line in the README. `--skill-hub-api` with `--skill-page` names an API Skill Hub that gives each user their own install line, and the skill's page on it: `skillHub: { api }`, `skill.page`, and a README line naming the page. `--dependency` instead starts a Dependency install with a Packaged skill, which the CLI's `skill install` copies into a project ([`guides/shipping.md`](guides/shipping.md)).
+
+Its `defineCli` takes the CLI's `package.json` as `manifest`, so help, `--version` and `doctor` read the name, version, description and engines from there, and `--version` prints the build stamp `tsdown.config.ts` defines as `__AGENT_CLI_BUILD__`. Its `install: "global"` declares a Global install; a CLI each project pins as a devDependency declares a Dependency install instead ([`guides/shipping.md`](guides/shipping.md)).
+
+The repo declares its Commands in `src/cli.ts`, its Error table in `src/errors.ts`, its ports in `src/ports.ts` and the bin in `src/bin.ts`; `test/cli.test.ts` drives the CLI through `runCli`, and `skills/<name>/SKILL.md` is the CLI's own skill. Its `AGENTS.md` ends with the Runtime's Agents section, which points every session at these docs.
+
+The repo is started when:
+
+- the skill's home is set: a Skill Hub, or a Packaged skill;
+- the examples (`greet`, `card` and `LANGUAGE_UNSUPPORTED`) are gone from code, tests and `skills/<name>/SKILL.md`;
+- every real Command is [done](README.md#a-command-is-done-when);
+- that skill is rewritten around the real Commands, as its comments say.
+

package/docs/guides/commands.md

@@ -0,0 +1,35 @@
+# Commands
+
+Call `agentCli({ ports, project, errors })` once and share the `defineCommand`, `defineCli` and `cliError` it returns, as [`example/define.ts`](../example/define.ts) does: `ctx.ports` is the type the `ports` factory returns, and `ctx.project.settings` the output of the Project file's schema, which `doctor` reports in its `project` row. A CLI without ports leaves `ports` out. List each Command in `defineCli({ commands })` under the word the caller types; nest objects for groups (`commands: { voices: { list } }` gives `tool voices list`). A Command returns data and never prints:
+
+- `description`, one line, and `examples` with realistic full command lines starting with the CLI's name: help and `--help --json` lead with them, the name replaced by the Run-as. Put what one line cannot hold in `help`.
+- `.describe()` on every field of `args` and `options`: the descriptions become help.
+- `output`, the schema of the data, so `--help --json` publishes it. `run` must return the schema's input, and what prints is its parse: data it rejects fails the run as a bug (exit 70). A List Command declares `rows` instead, below.
+- The data names things the way the next call needs them: an id the next Command takes beside a name a person recognises, and a file by its absolute path (`resolve(ctx.cwd, file)`), since the caller's next shell may start in another folder.
+- `errors`, the codes of the Error table it throws ([`errors.md`](errors.md)), and `secrets`, each key it reads with `get` saying where to obtain it. `--help --json` publishes both, so an agent learns before the first call how a Command fails and which keys to ask the operator for:
+
+  ```ts
+  errors: ["LINK_NOT_FOUND", "CORRUPT_DATA", "UNREACHABLE"],
+  secrets: [{ name: "LINKS_TOKEN", get: "https://links.example.com/settings/tokens" }],
+  ```
+
+- `render`, optional, turns the data into short text; without it, text mode prints the data as [TOON](https://github.com/toon-format/toon). `links check` leaves it out; write one when a sentence reads better than the fields, as `links add` does. Its `style` is for emphasis, never for meaning, since it colours only for a person at a terminal.
+
+Rarer cases, each documented in the types:
+
+- `orStdin` on an arg, for text too long or too quoted for one shell word, as `links import` takes it.
+- A `z.array(...)` arg or option, for repeated values.
+- `operator: true`, for a step only a person at a terminal can take, such as a sign-in through the browser.
+- `hidden: true`, for a Command the CLI runs on itself, such as a daemon ([`local-state.md`](local-state.md)).
+
+Data over 30,000 characters spills to a file, so make a list that may grow a List Command, which `--limit` sizes instead.
+
+Reach the outside through `ctx`, so tests control it:
+
+- the working directory and environment as `ctx.cwd` and `ctx.env`;
+- the file system through `ctx.files`, whose failures name the path; a `node:fs` failure is a bug (exit 70). Pass `mode` to its `write` or `mkdir` for a file or folder holding tokens. Catch a file code from `runtimeCodes` to say what to do instead, as [`example/bundle.ts`](../example/bundle.ts) turns `ALREADY_EXISTS` into its own `BUNDLE_EXISTS`;
+- a key or token through `ctx.secret(name)`, for a name in the Command's `secrets`. The Runtime reads each declared Secret from the environment, then the CLI's `.env` at `ctx.envFile` (`~/.config/<name>/.env`, or under `$XDG_CONFIG_HOME`), an empty value counting as unset, and fails the run with `SECRET_MISSING` before any work, `--dry-run` included, when one is unset; so `ctx.secret` returns a `Secret`, never `undefined`. Messages name its `origin` and keep its `value` out of the agent's context. `doctor` reports every declared Secret; a key it should check that no Command requires goes in `defineCli({ secrets })`;
+- a program through `ctx.spawn`, listed in the Command's `tools`, so a missing one fails before any work and `doctor` checks it. Its `stdin` option feeds the program, from an async iterable for input too large to hold, and its `onLine` option receives each line the program writes as it comes;
+- `ctx.progress` while a long step runs, since a Coding agent may kill a CLI that stays silent;
+- `ctx.notice` for something the caller should know beside the data, such as that a copy it relies on is behind. A fact the next step acts on belongs in the data instead.
+

package/docs/guides/doctor.md

@@ -0,0 +1,52 @@
+# `doctor` rows
+
+Every multi-Command CLI has a built-in `doctor` that reports one row per check: `build`, `node`, the CLI's own rows, one per declared tool, `install`, `registry` and `skill`. Declare a tool the whole CLI relies on in `defineCli({ tools: [...] })` so `doctor` checks it without attaching it to one Command; no Command refuses for it unless it lists the tool in its own `tools`. Add a row for each outside system the CLI depends on, in `defineCli({ doctor: [...] })`, probing it through the port method a Command calls rather than a health endpoint, so a green row means the Command's own request works:
+
+```ts
+const store: DoctorCheck<Ports, Settings> = {
+  name: "store",
+  run: async (ctx) => {
+    const links = await readLinks(ctx);
+    return { state: "ok", message: `${linksPath(ctx.cwd)} holds ${links.length} links` };
+  },
+};
+```
+
+A row reads the project's settings as `ctx.project`, `undefined` when there is no Project file, as a Command does. When the file is unusable, reading `ctx.project` skips the row, since the `project` row already reports the file, so a row needs no branch for it:
+
+```ts
+const tag: DoctorCheck<Ports, Settings> = {
+  name: "tag",
+  run: (ctx) => {
+    const tag = ctx.project?.settings.tag;
+    return {
+      state: "ok",
+      message:
+        tag === undefined
+          ? "`links add` leaves a link untagged unless given --tag"
+          : `\`links add\` tags a link ${tag} unless given --tag`,
+    };
+  },
+};
+```
+
+A row returns one of:
+
+- `{ state: "ok", message, fix? }`;
+- `{ state: "problem", message, fix?, code? }`, where `fix` is the command that fixes the problem, which `doctor` gives as a Next step before its own rerun, and `code` is one of the Error table's or the Runtime's;
+- `{ state: "skipped", message }` for a row not checked, such as "not checked: the bridge is down", so one cause shows up as one problem. It never fails `doctor`.
+
+When any row is a problem, `doctor` fails with one error per problem row, its `code` or `DOCTOR_PROBLEMS` (exit 2) without one, so it exits by the class that must act first as any Command does: an expired session 3, a network failure 75. Give a problem the code of its real cause. A row that throws becomes its own problem, with a `CliError`'s message and hint as the message and its code as `code`. Each row runs under its own deadline, 10 s unless it sets `deadlineMs`, and `ctx.signal` aborts at that deadline, so pass it on. A row with `advisory: true` shows its problem and `fix` but never fails `doctor`.
+
+The Runtime's `secrets` row checks every Secret the CLI and its Commands declare, naming where each came from and never its value, so no row of yours reads a key.
+
+The `install` and `registry` rows follow `defineCli({ install })`, and are `skipped` without it. Both are advisory: a project may stay on an older release on purpose.
+
+- **Global install:** `install` checks that the CLI runs from npm's global folder, else gives the global install line; `registry` compares the build with the registry's latest and gives `<cli> update`.
+- **Dependency install:** `install` checks that the copy that runs is the one the project at the working directory installed. It is `skipped` with `registry` when the CLI runs from source or the project links the package from its workspace, which decides its version. Otherwise another copy than the project's gets `<run-as> doctor`, which runs the project's copy; a project that has not installed the package gets its install line (`pnpm install`, `npm install`) when a `package.json` at or above the working directory lists it, else its add line, and a copy whose `package.json` is unreadable gets the install line too; yarn and bun get no line. With no copy installed, npx refuses before the CLI starts, so these fixes reach only a CLI run from another copy. `registry` compares the build with the latest release npm finds from the project root and gives `pnpm up --latest …` or `npm install …@latest`, naming the `lockstep` packages; for yarn and bun it names the version to move to instead.
+
+The `skill` row follows `defineCli({ skill })` ([`shipping.md`](shipping.md)):
+
+- **Skill Hub, `{ source }`:** the row is always ok and names every installed copy against the running CLI; its fix installs the skill from the hub. Without `skill` it gives `skills update` for an older copy and nothing to install a missing one.
+- **Skill Hub, `{ page }`:** as for `{ source }`, but a copy `skills update` cannot reach gets no fix and the message names the page instead; what each copy gets is in the `skill` JSDoc of `defineCli`.
+- **Packaged skill, `{ packaged }`:** the row is advisory, and the Runtime also gives a Notice of its problem and, when it declares `agents`, an `agents` row; what each reports is in the `skill` JSDoc of `defineCli`. Do not check the Skill copy or the Agents section in your own rows or Notices.

package/docs/guides/effects-and-plans.md

@@ -0,0 +1,44 @@
+# Effects and Plans
+
+Name Commands so their leading words separate reads from changes (`links list`, `links remove`): a Coding agent's permission rules match command-line prefixes, so the operator can allow every read and still be asked about each change. A read Command takes no flag that changes anything. A write Command is _idempotent_: a second run after a success changes nothing, as `links archive` skips links already archived.
+
+An `act` Command changes the state of a program already running, such as a tap on a game in a browser tab: state that ends with that program. State that outlives it, such as a file or a remote service, is `write` or `destructive`. An Effect says what the Command itself changes, so a Command that runs the caller's script, such as an `eval`, is `act`, and its `help` says what the script can reach. Running an `act` Command again may act again.
+
+A `read` or `act` Command has `run(input, ctx)` and no Plan. A `write` or `destructive` Command splits the work in two, and the Runtime adds `--dry-run`, which prints the Plan and stops, through `renderPlan` when declared, else as `Would run <command>:` and the Plan in TOON indented under it:
+
+```ts
+plan: async ({ url, tag }, ctx) => {
+  const links = await readLinks(ctx);
+  const id = Math.max(0, ...links.map((link) => link.id)) + 1;
+  const tags = [tag ?? ctx.project?.settings.tag].filter((name) => name !== undefined);
+  return { add: { id, url, tags } };
+},
+apply: async (plan, ctx) => {
+  const links = await readLinks(ctx);
+  await ctx.runToEnd("saving the links", () => writeLinks(ctx, [...links, plan.add]));
+  return plan.add;
+},
+render: (link) => `Saved link ${link.id}: ${link.url}`,
+renderPlan: (plan) => `Would save link ${plan.add.id}: ${plan.add.url}`,
+```
+
+`plan` reads and validates only: every side effect lives in `apply`, so a dry run is always safe. Keep the Plan to paths, hashes and numbers and produce bytes in `apply`.
+
+A Command that writes files declares `outputs(plan)`, which earns it `--force` and refuses to replace an existing output without it. Write them in `apply` through `ctx.files` or a port's `files`. Refuse an output that is also an input by comparing `ctx.files.stat` ids; `--force` never covers that.
+
+```ts
+outputs: (plan) => [plan.file],
+apply: async (plan, ctx) => {
+  await ctx.files.write(plan.file, markdownOf(plan.links));
+  return { file: resolve(ctx.cwd, plan.file), count: plan.links.length };
+},
+```
+
+A `destructive` Command has `confirm(plan)`, the value the caller repeats as `--confirm`. Pick something the caller can see in the Plan, such as a name or URL:
+
+```ts
+confirm: (plan) => plan.remove.url,
+```
+
+When what `--force` replaces is not a list of files, such as a whole folder, declare `force` with a sentence saying what it replaces, and make the Plan say it too. A Plan that costs money declares `cost` (Paid calls in [`remote-services.md`](remote-services.md)). A `serve` Command keeps running, such as a preview server ([`long-runs.md`](long-runs.md)).
+

package/docs/guides/errors.md

@@ -0,0 +1,57 @@
+# Errors
+
+Declare every error code the CLI throws once, in its Error table: `defineErrors`, passed to `agentCli({ errors })`. Each code has the Exit class that must act on it (`caller`, `operator`, `source` or `wait`) and, optionally, a Zod schema for its `details`, the facts an agent acts on without parsing the message:
+
+```ts
+export const errors = defineErrors({
+  LINK_NOT_FOUND: { class: "caller" },
+  CORRUPT_DATA: { class: "caller" },
+  BUNDLE_EXISTS: { class: "caller" },
+  UNREACHABLE: { class: "source" },
+  ARCHIVE_FAILED: {
+    class: "source",
+    details: z.object({ id: z.number(), url: z.string() }),
+  },
+  CAPTURE_UNANSWERED: {
+    class: "operator",
+    details: z.object({ id: z.number(), url: z.string() }),
+  },
+});
+```
+
+When a `details` field is worth reading in text mode too, such as a stack, name it in the code's `print` rather than repeating it in the message, which `--json` would then carry twice.
+
+Each Command lists in `errors` the table codes it throws, its helpers' and ports' included, so a shared store's `CORRUPT_DATA` goes on every Command that reads the store. A run ending in a table code its Command does not declare, directly or as an `AggregateError` leaf, fails as a bug (exit 70) naming the code and the Command, so the Command's tests catch a missing one; `defineCli` throws on a code the table lacks. Runtime codes are never listed.
+
+Inside a Command, throw `ctx.fail(code, init, options?)`, typed to the Command's `errors` and each code's `details`, so an undeclared code is a type error. A helper outside a Command, such as [`example/store.ts`](../example/store.ts), throws through the `cliError` that `agentCli` returns, typed by the whole table.
+
+`next` lists the Next steps in order, each the words after the CLI's name, or `ctx.rerun({ remove?, add? })` for the caller's own line with flags changed; the Runtime starts each line with the Run-as and prints it on a `run:` line after the hint, and `--json` gives them as the error's `next`. The `hint` says whether and when to run them, and names no line itself. Set `retryAt` only when the source said when to come back:
+
+```ts
+throw ctx.fail(
+  "UNREACHABLE",
+  {
+    message: `${link.url} did not answer`,
+    hint: "check the address, then try again",
+    next: [["check", String(id)]],
+  },
+  { cause: error },
+);
+```
+
+The exit code is the failure's Exit class: 1 the caller, 2 the operator, 3 someone at the source, 75 nobody but time (wait, then run again), 70 a bug, 130 or 143 an interrupt by SIGINT or SIGTERM. A `UsageError` exits 1, for input your schemas could not reject: give it the code `INVALID_INPUT`.
+
+A code missing from the table, and anything else thrown, is a bug, exit 70, unless it wraps a missed deadline (Wrapping a failure in [`long-runs.md`](long-runs.md)). Its hint says to rerun under `<NAME>_DEBUG=1` for the stack trace and its `cause` chain, and to report it at package.json's `bugs` when declared.
+
+Every Runtime code is on the exported `runtimeCodes`, such as `runtimeCodes.OUTPUT_EXISTS` or `runtimeCodes.TOOL_FAILED`: catch, return and assert codes through it. A Command throws a Runtime code only where it means what the Runtime means by it: `INVALID_INPUT`, a file code from `ctx.fileError`, `TOOL_MISSING` or `TOOL_FAILED`. The others, such as `UNKNOWN_COMMAND` or `DOCTOR_PROBLEMS`, name the Runtime's own checks, so a Command only catches or asserts them.
+
+To report every problem a run found, throw an `AggregateError` of them, nested to group them if you like: each leaf prints with its hint, and the run exits with the first of 1, 2, 3, 75 that any of them has, or 70 when any is not a known `CliError`.
+
+```ts
+if (failures.length > 0) {
+  throw new AggregateError(failures, `${failures.length} links were not archived`);
+}
+```
+
+Parse files, responses and other outside input with a Zod schema and turn a failure into a `CliError` with a fix in its hint, as [`example/store.ts`](../example/store.ts) does for a corrupt data file.
+

package/docs/guides/lists.md

@@ -0,0 +1,18 @@
+# Lists: pagination and `--fields`
+
+A Command that lists many items is a List Command: a read Command that declares the schema of one row as `rows` in place of `output`. The Runtime adds `--limit`, `--cursor` and `--fields`, and each page gives the line for the next as a Next step. A list held whole in memory returns `paginate(items, { limit, cursor })`:
+
+```ts
+options: z.object({
+  tag: z.string().optional().describe("only show links with this tag"),
+}),
+rows: linkSchema,
+run: async ({ tag, limit, cursor }, ctx) => {
+  const links = await readLinks(ctx);
+  const matching = tag === undefined ? links : links.filter((link) => link.tags.includes(tag));
+  return paginate(matching, { limit, cursor });
+},
+```
+
+A source that pages itself, such as a remote API, returns `page(items, next)`, where `next` is the source's own cursor for the following page: ask the source for `limit` items from `cursor`, and pass its cursor through unchanged.
+

package/docs/guides/local-state.md

@@ -0,0 +1,28 @@
+# Local state: a daemon or a store that outlives a run
+
+## Versions of what outlives a run
+
+A daemon or a store outlives the CLI that made it, so the next run may be older or newer. Under nvm each Node version has its own global install, so two versions of the CLI run side by side.
+
+- **Compare builds, not only protocols:** `version`, then `build.builtAt`, both from `PortsBase` (`build` is absent in a source run, which counts as oldest). A daemon does not stop on its own, so a fix that keeps the protocol would otherwise wait for a reboot.
+- **A newer CLI replaces or rebuilds what is older; an older CLI refuses what is newer** with an `operator` code. Never downgrade: two CLIs that each "fix" the state flip it forever.
+- **A shipped protocol only grows:** new messages or optional fields, never a change or removal, so every side can read `{ type: "hello", protocol, build }`.
+
+## A daemon in the CLI's own package
+
+- **Start it as a `hidden` `serve` Command** through `ctx.spawnDetached(ctx.self[0], [...ctx.self.slice(1), "daemon"])`, which works from source and from the bundle alike and resolves with the `pid` once the Daemon has started. The Daemon outlives the run and Ctrl-C, and gets no stdio, so it logs to a file. In a test, `runCli({ spawnDetached })` records the call instead.
+- **A Daemon that a newer one replaces stops its work, then calls `ctx.end()`**, which ends its run with exit 0.
+- **Replace it by a protocol message, never a signal:** a Coding agent's sandbox blocks `kill`, and a daemon needs its permission to listen on a local port. The daemon decides while reading the client's `hello`, since an older daemon may refuse the rest of the handshake.
+- **The lowest free port in a fixed list wins**, instead of a lock file a crash leaves stale.
+- **Log a repeating refusal once per distinct cause**, or an outdated client's reconnects flood the log.
+- **A bridge to it reports what it is doing** while the Command waits, through `PortsBase`'s `progress`.
+
+## A store that is a cache
+
+- **Rebuild on a schema change; never migrate.** What must survive goes to a file the user named.
+- **Rebuild in place,** re-reading the version inside the store's own transaction, rather than deleting the file: deleting fails on Windows while another run holds it, and on POSIX that run writes to a file nobody sees again.
+- **Every Command that opens the store rebuilds it, read-only ones included**, and reports what it dropped in its data. A `doctor` row reports the store through a read-only connection and writes nothing; newer and corrupt are problems.
+- **Classify the store's failures once**, for reads and writes alike: `ctx.fileError` for an errno; a store that cannot be opened or is read-only, `operator`; a full disk, `DISK_FULL`; a corrupt file, `operator`, whose hint says to move the file aside. Only on the read path does a refused query become `caller`; otherwise an agent rewrites a correct query forever.
+- **Never delete a store the CLI thinks is corrupt:** rebuilding on a version change is the CLI's call, a damaged file the operator's.
+- **Check `ctx.signal` before every store write**, so nothing new is written after Ctrl-C.
+- **A lock wait that blocks the event loop also blocks Ctrl-C:** keep it short, and fail with a `wait` code when it runs out.

package/docs/guides/long-runs.md

@@ -0,0 +1,109 @@
+# Long runs: deadlines, Ctrl-C, jobs, queues, progress, servers and data that outlives a failure
+
+## Cancellation and deadlines
+
+- Pass `ctx.signal` to `fetch` and the ports, so Ctrl-C stops the work.
+- Run every call to a slow outside system under `ctx.deadline(ms)`, so the Command fails clearly instead of hanging the agent. A billed call that Ctrl-C must not cut short runs under `ctx.deadline(ms, { ignoreStop: true })` instead (Deadlines in [`remote-services.md`](remote-services.md)).
+- Give a rerun of the caller's line as a Next step from `ctx.rerun`, as in `next: [ctx.rerun({ remove: ["--from"], add: ["--from", String(next)] })]`, never by hand.
+- A run that could outlast the caller's tool timeout declares a `deadline`, whose `resume` returns the Next step that continues the work. Once that run deadline hits, the run ends with `DEADLINE_EXCEEDED` whatever the Command then throws, so `deliver` what is done and say in that data which work is still pending:
+
+  ```ts
+  deadline: {
+    ms: ARCHIVE_DEADLINE_MS,
+    // Archived links are skipped, so running the same command again continues the work.
+    resume: (_input, rerun) => rerun(),
+  },
+  ```
+
+- Wrap a step that must not stop halfway, such as writing a file, in `ctx.runToEnd`.
+- Poll through `ctx.poll`, which runs on `ctx.clock` so a test runs it instantly; pass `signal: ctx.deadline(ms)` to stop at a `--wait` deadline rather than one interval after it.
+
+  ```ts
+  capture = await ctx.poll(
+    async () => {
+      const status = await archive.status(job, ctx.signal);
+      return status.state === "pending" ? undefined : status;
+    },
+    { intervalMs: CAPTURE_POLL_MS },
+  );
+  ```
+
+## Work that outlives any deadline
+
+When remote work runs longer than a caller can wait, split it into two Commands: a `write` Command that starts the job and returns its id, and a `read` Command that takes the id and an optional `--wait <seconds>`, polls under `ctx.deadline`, and while the job still runs fails with a `wait` code whose hint is its own command line. Rerunning the start Command with the same input finds the running job where the service allows, rather than starting another.
+
+## Servers
+
+A `serve` Command keeps running, such as a preview server: `start(input, ctx)` returns data, which prints at once, and the run lasts until `ctx.signal` aborts. Stop the work on the signal:
+
+```ts
+await new Promise<void>((resolve) => server.listen(port, HOST, resolve));
+ctx.signal.addEventListener("abort", () => server.close(), { once: true });
+return { url: `http://${HOST}:${port}/` };
+```
+
+A serve Command may also end itself with `ctx.end()`, exit 0, such as a Daemon that a newer one replaces ([`local-state.md`](local-state.md)). `ctx.signal` does not abort then, so stop the work first. To start a server that outlives the run, spawn its `serve` Command with `ctx.spawnDetached`, never `ctx.spawn`, whose child the run waits for and stops on Ctrl-C.
+
+## Queues
+
+A Command that works through a list of free work stops at the first fatal error and at Ctrl-C: give each item `AbortSignal.any([ctx.signal, stop.signal])` and abort `stop` from the first failure. Paid work lets every item finish instead (Paid calls in [`remote-services.md`](remote-services.md)).
+
+- Write what a rerun resumes from (a manifest, the outputs list) before the queue starts, and `ctx.deliver` the shared list after each item, never a fresh copy per item, which turns quadratic.
+- Call `signal.throwIfAborted()` after taking a concurrency slot, so every waiting item sees the abort.
+- Start an item's error message with where it happened (`chapter 7, segment 31: …`).
+
+## Progress
+
+- One `ctx.progress` line per event: no `\r` and no spinners, since stderr is often a log file.
+- An ETA comes from the pace measured in this run, not a constant.
+- A tool silent for minutes looks hung: ask it for periodic output (`ffmpeg -progress pipe:1 -stats_period 10`) and turn the lines `onLine` receives into one `ctx.progress` line per period. `onLine: ctx.progress` passes on lines that already read as progress.
+- Each item's done line says what it took: time, and what it consumed (tokens, bytes); where a limit caps each call, the largest single call.
+- A fact that belongs to the result goes in the data, never only in progress, which a caller reading stdout never sees.
+
+## Wrapping a failure
+
+When you wrap an outside failure in your own `CliError`, let the abort reason through first, so an interrupt or a missed deadline keeps its own code, and then a `CliError` the port already classified:
+
+```ts
+} catch (error) {
+  // An interrupt or a missed deadline already carries the right error.
+  if (ctx.signal.aborted) {
+    throw ctx.signal.reason;
+  }
+  if (error instanceof CliError) {
+    throw error;
+  }
+  throw archiveFailed(link, error instanceof Error ? error.message : String(error), error);
+}
+```
+
+Keep the original error as `cause` whenever you wrap one, as `archiveFailed` does, and make an adapter or SDK wrapper do the same: an error that is not a `CliError` and whose `cause` chain holds a `ctx.deadline`'s abort is reported as that `DEADLINE_EXCEEDED`. Any other, a `CliError` keeping the abort as `cause` included, is reported as it is, even after a deadline fired.
+
+The Runtime's `INTERRUPTED` only names the caller's line to run again, unless it was stopped on purpose. When the Command knows more, such as what it finished or that a request was never sent, throw its own `CliError` with the code `INTERRUPTED` once `ctx.signal` aborted: it wins over the Runtime's and keeps exit 130 or 143. Compare `ctx.signal.reason` with `runtimeCodes.INTERRUPTED` and `runtimeCodes.DEADLINE_EXCEEDED`, so a missed deadline keeps its own error:
+
+```ts
+// A missed run deadline keeps its own error, whose Next step is already the resume line.
+function stoppedAfter(ctx: Context<Ports>, done: number, total: number): unknown {
+  const reason: unknown = ctx.signal.reason;
+  if (!(reason instanceof CliError && reason.code === runtimeCodes.INTERRUPTED)) {
+    return reason;
+  }
+  return new CliError({
+    code: runtimeCodes.INTERRUPTED,
+    message: `interrupted after archiving ${done} of ${total} links`,
+    hint: "unless it was stopped on purpose, run again to archive the rest",
+    next: [ctx.rerun()],
+  });
+}
+```
+
+## Data that outlives a failure
+
+Call `ctx.deliver` with the data done so far after each finished piece, so a run that then fails, hits a deadline or is interrupted still prints it and the caller keeps the finished work.
+
+```ts
+const done = { id: link.id, snapshot: await snapshotOf(link, ctx) };
+await ctx.runToEnd("saving the links", () => saveSnapshot(ctx, done));
+archived = [...archived, done];
+ctx.deliver(archived);
+```

package/docs/guides/remote-services.md

@@ -0,0 +1,124 @@
+# Remote services: ports, retries, work you cannot take back, paid calls, a Side task
+
+## Ports
+
+A port is an outside system the CLI talks to, such as an HTTP API, behind an interface. `agentCli({ ports })` takes the factory that builds the real ones, and `ctx.ports` is the type it returns; `runCli`'s `ports` option replaces them in a test. The factory receives `PortsBase`, the same helpers a Command gets, so an adapter reads its key or a shipped file as a Command does. Each port method takes the signal of its call, `ctx.signal`, or a `ctx.deadline`, as `Web.status` does. A port reads and checks its key when called, not in the factory: what the factory throws fails every Command that uses any port, and a missing key for one port must not fail Commands that use another. [`example/ports.ts`](../example/ports.ts) declares three:
+
+```ts
+export interface Ports {
+  readonly archive: Archive;
+  readonly web: Web;
+  readonly usage: Usage;
+}
+```
+
+```ts
+export function ports(): Ports {
+  return { archive: waybackArchive(), web, usage };
+}
+```
+
+A port's key comes from the Command that calls it: `links check` declares `LINKS_TOKEN` in its `secrets` and passes `ctx.secret("LINKS_TOKEN").value` to `Web.status`, so the Runtime checks the key before the run and `doctor` reports it.
+
+The rules below shape the adapter and the Command around it.
+
+## Failures and their Exit class
+
+Classify by who must act, through a schema over the response, never by its status alone:
+
+- 400, 404, 409, 422 and other refusals of what was sent: `caller`. The message quotes the input that was refused, truncated to about 80 characters with invisible characters escaped (`JSON.stringify` leaves U+2028 and bidi controls raw), and the hint suspects the input before the service.
+- A missing key, or one the service rejects (401): `operator`, the hint naming where the key came from (`secret.origin`, never its value, which must not reach an agent's context), or the `.env` to put it in, `envFile` from `ctx` or `PortsBase`.
+- No access (403), a lost session, a response whose layout the schema does not know: `source`.
+- 5xx, 408, 429, a network failure, a quota: `wait`, with `retryAt` from `Retry-After` or a quota's reset. A 429 that means out of credit is `operator`: someone tops it up. Each provider says which in its own body; an unrecognised 429 stays `wait`.
+- A Coding agent's sandbox refuses a host with a proxy `403` carrying `X-Proxy-Error: blocked-by-allowlist`: `operator`, the hint naming the host to allow.
+
+## Polite retries
+
+For a rate-limited API or a scraped site, the adapter retries one request, since it sees the status and `Retry-After`: it sleeps on `PortsBase`'s `clock` and reports each retry through its `progress`. An adapter that classifies a failure throws the `CliError` itself, which the Command passes through unchanged ([`long-runs.md`](long-runs.md) "Wrapping a failure"); one that does not, as [`example/ports.ts`](../example/ports.ts), throws a plain `Error` the Command wraps. Test the retries on the adapter alone, with a fake clock; a Command's tests fake the whole port. The Command owns what spans requests: concurrency, the minimum interval and the breaker.
+
+- Concurrency, minimum interval, retry delays (such as `[1000, 2000, 4000]`) and a breaker threshold are named constants. No flag changes them: politeness is not the caller's choice.
+- Retry only `wait`-class failures, and only a request safe to send twice (below): a 502 to a POST that starts a job is `wait`, but it is never resent. When `Retry-After` asks for no longer than the next delay, wait what it asks; when it asks for longer, or the delays run out, throw the `wait` code with `retryAt`. Sleep with the call's signal, so Ctrl-C ends a backoff.
+- The breaker trips after a run of consecutive failed requests, counting requests, not attempts, permanent failures included. A tripped breaker stops the queue; items never sent are reported as not attempted, not as failed.
+
+## Work you cannot take back
+
+A request that starts a job or bills may have reached the server although the client saw an error.
+
+- **Resend only what provably did not arrive:** a failure before the connection opened, a GET, a status the provider documents as not billed, or a request the server deduplicates by an id the client generated.
+- **An unanswered request is never resent:** a timeout waiting for headers, a socket dropped mid-request, a gateway 502, 504 or 408.
+  - When there is a job to fetch, it is still running: a `wait` code with the job id in `details` and the Command that fetches the result as its Next step.
+  - When there is nothing to fetch (a synchronous billed call), it is an `operator` code: whether to pay again is the operator's call. The hint says it may have been billed.
+- **Generate a job's id on the client and `ctx.deliver` it before sending**, so an interrupt or a failure still prints it.
+- **After a step that cannot be taken back, every Next step picks up what exists** (a fetch by id, or the run that skips finished outputs), never a plain rerun, which sends or bills twice. A Command's `deadline.resume` obeys the same rule.
+
+## Deadlines
+
+Metadata lookups need a deadline too ([`long-runs.md`](long-runs.md)).
+
+- **Layer them so the inner one fires first:** the server's limit < the adapter's timeout < the Command's `deadline.ms`, so the server answers and releases its lock before the client gives up. Cap input size so that a timeout can only mean "try again".
+- **A deadline stops sending; it never cuts a billed call in flight.** Run a sent paid call inside `ctx.runToEnd`, bounded by `ctx.deadline(ms, { ignoreStop: true })` instead of `ctx.signal`: it aborts with `DEADLINE_EXCEEDED` once `ms` have passed, and neither Ctrl-C nor the run `deadline` aborts it. Check `ctx.signal.aborted` before each new call.
+  - Its adapter maps that timeout to its own `operator` code, whose hint says the call may have been billed, keeping the timeout as `cause`: a `CliError` is always reported by its own code. From [`example/archive.ts`](../example/archive.ts):
+
+```ts
+try {
+  return await ctx.runToEnd("sending the capture", () =>
+    ctx.ports.archive.capture(link.url, ctx.deadline(CAPTURE_TIMEOUT_MS, { ignoreStop: true })),
+  );
+} catch (error) {
+  if (!(error instanceof CliError && error.code === runtimeCodes.DEADLINE_EXCEEDED)) throw error;
+  throw cliError(
+    "CAPTURE_UNANSWERED",
+    {
+      message: `the Wayback Machine did not answer the capture of ${link.url} in ${CAPTURE_TIMEOUT_MS} ms`,
+      hint: "it may have used one of today's captures: ask your user before running again",
+      next: [["archive", "--yes"]],
+      details: { id: link.id, url: link.url },
+    },
+    { cause: error },
+  );
+}
+```
+
+## Paid calls
+
+Declare `cost(plan)`, a sentence stating the price, so a run that spends money needs `--yes`, the operator's call:
+
+```ts
+cost: (plan) =>
+  plan.archive.length === 0
+    ? undefined
+    : `Archiving ${plan.archive.length} links uses ${plan.archive.length} of the Wayback Machine's daily captures.`,
+```
+
+Around it:
+
+- **A choice that decides the bill (a model, a route) has no default.** Without the option or a Project file setting, refuse in `plan` with a `caller` code whose `details` lists each choice and who it bills, so the agent asks its user. The result names who was billed.
+- **Refuse every cheap local mistake before the call that bills:** credentials, input, then outputs (`outputs(plan)` does that last one).
+- **A batch of paid calls lets every call finish:** cancelling siblings on the first failure discards work already billed. Write each result under a positional name (`<stem>-<i>.<ext>`) so the gaps show, then throw an `AggregateError` of the failures.
+- **A result rejected after billing is still written**, and the run then fails. A hint never asks for a rerun to see it, which pays again.
+- **Write a provenance record beside each billed output**, `<output>.json`: CLI version, time, command line, model, who was billed, the full prompt, each input's path and sha256, and the options sent. A rerun that finds an output whose record matches skips it, so the rerun fills only the gaps.
+- **No silent fallback to another billed route:** the hint names it, and the user chooses.
+
+## Wrapping an SDK
+
+- **The CLI checks shape; the library or server checks meaning.** Refuse ahead of the call only what would fail silently or bill for a discarded result, as a named constant citing its measurement. A copied table of server rules goes stale and refuses valid calls.
+- **One repeatable `--option key=value`** (an option typed `z.array(z.string())`) passes an SDK's open-ended options. Report the merged object that was sent, since SDKs drop unknown keys silently, and reject the keys `__proto__`, `constructor` and `prototype`.
+- **Classify a dependency's errors by their runtime shape through a schema**, not by its TypeScript types, which drift from what it throws.
+- **Audit what the SDK's own retry resends**, and switch off any retry the rules above forbid.
+
+## LLM calls
+
+- The SDK's `maxRetries` is the HTTP retry. A retry for a schema violation is a loop in the adapter outside the SDK call, so an HTTP retry never re-runs an attempt already billed.
+- Pass `apiKey` from `ctx.secret`; an SDK that reads `process.env` skips the CLI's `.env`.
+
+## A Side task beside every run
+
+Work that belongs to no Command, such as a usage count, goes in `defineCli({ sideTask })`, never in a Command: a Command cannot count a run a guard refuses, and the process exits once the output is written. The Side task starts once the input is parsed and runs beside the Command, so it adds no time to a fast run. The run waits for it at most `SIDE_TASK_WAIT_MS` (1 s) after the output is written, then aborts its `signal`. What it throws never reaches the caller, so test it through a fake port given to `runCli`, and read its failures under `<NAME>_DEBUG=1`. Return `undefined` to decline, such as for a dry run or an operator who opted out. [`example/cli.ts`](../example/cli.ts):
+
+```ts
+  // Counts only real runs, and only for an operator who named a collector.
+  sideTask: ({ command, dryRun, env, ports, signal }) => {
+    const url = env.LINKS_USAGE_URL;
+    return dryRun || url === undefined ? undefined : ports.usage.count(url, command, signal);
+  },
+```