A self-improving RLM agent for coding workflows and long-running autonomous tasks.
Rust
docs(coding-agent): document autonomous CLI options (#578)
Seth Kartena56471ebdcc5
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.mdindex cd59f8b210..ceb8223e4d 100644--- a/packages/coding-agent/CHANGELOG.md+++ b/packages/coding-agent/CHANGELOG.md@@ -2,6 +2,7 @@## [Unreleased]+- Changed top-level CLI help and documentation to expose autonomous mode, quality gates, and their limits.- Fixed long-running thinking timers to display hours and days instead of unbounded minutes.## [0.4.0] - 2026-08-01diff --git a/packages/coding-agent/README.md b/packages/coding-agent/README.mdindex 8b5f95c16d..de82a67d62 100644--- a/packages/coding-agent/README.md+++ b/packages/coding-agent/README.md@@ -596,6 +596,23 @@ Available built-in tools: `ipython`Combine `--no-*` with explicit flags to load exactly what you need, ignoring settings.json (e.g., `--no-extensions -e ./my-ext.ts`).+### Autonomous Options++Autonomous mode is disabled by default. `--autonomous` or any of its sub-options enables host-managed continuations for unattended work.++| Option | Description |+|--------|-------------|+| `--autonomous` | Continue until gates pass or a limit prevents another continuation |+| `--autonomous-gate <command>` | Add a repeatable shell command that must pass before completion |+| `--autonomous-gate-retries <n>` | Positive per-gate retry limit; default `3` |+| `--autonomous-gate-timeout-ms <n>` | Positive per-gate timeout in milliseconds; default `300000` |+| `--autonomous-max-continuations <n>` | Positive host follow-up limit; default `3` |+| `--autonomous-max-turns <n>` | Positive assistant-turn limit; default `12` |+| `--autonomous-max-tokens <n>` | Positive token limit; default `80000` |+| `--autonomous-timeout-ms <n>` | Positive wall-clock limit in milliseconds; default `1800000` |++Gates run before the continuation, turn, token, and wall-clock limits are evaluated; every configured gate must pass for autonomous completion. See the [usage guide](docs/usage.md#autonomous-options) for validation rules, retry behavior, and detailed limit interactions.+### Other Options| Option | Description |diff --git a/packages/coding-agent/docs/usage.md b/packages/coding-agent/docs/usage.mdindex 6e783d9f79..894f508495 100644--- a/packages/coding-agent/docs/usage.md+++ b/packages/coding-agent/docs/usage.md@@ -249,18 +249,44 @@ prime-agent --no-extensions -e ./my-extension.ts### Autonomous Options-| Option | Description |-|--------|-------------|-| `--autonomous` | Continue until host-observable terminal evidence exists |-| `--autonomous-gate <command>` | Run a command before autonomous mode may finish; repeatable |-| `--autonomous-gate-retries <n>` | Maximum retries for each failed gate; default is 3 |-| `--autonomous-gate-timeout-ms <n>` | Timeout for each gate command |-| `--autonomous-max-continuations <n>` | Maximum autonomous follow-up messages; default is 3 |-| `--autonomous-max-turns <n>` | Maximum assistant turns; default is 12 |-| `--autonomous-max-tokens <n>` | Maximum tokens; default is 80000 |-| `--autonomous-timeout-ms <n>` | Maximum wall-clock duration; default is 1800000 milliseconds |-| `--goal <objective>` | Start the session with an active persistent goal; only seeds new top-level sessions (rlmDepth 0) with no existing goal state |-| `--goal-token-budget <n>` | Positive integer token budget for the initial goal; requires `--goal` |+Autonomous mode is a host policy for unattended work. It starts disabled. `--autonomous` enables it, and supplying any `--autonomous-*` sub-option also enables it. The host starts each enabled run with fresh continuation, turn, token, and elapsed-time counters.++| Option | Behavior, units, and default |+|--------|------------------------------|+| `--autonomous` | Enable autonomous continuations. With no gates, the host keeps requesting work until a limit prevents another continuation. |+| `--autonomous-gate <command>` | Add a shell command that must pass before the run can finish. Repeatable commands run in CLI order; the default is no gates. |+| `--autonomous-gate-retries <n>` | Set the per-gate retry limit. Default: `3`. A failed gate can continue while its recorded attempt is at most this value; the next failed attempt exhausts the gate. |+| `--autonomous-gate-timeout-ms <n>` | Set the timeout for each gate process in milliseconds. Default: `300000` (5 minutes). A timed-out gate is failed and its process tree is stopped. |+| `--autonomous-max-continuations <n>` | Set the maximum host-injected follow-up messages. Default: `3`. |+| `--autonomous-max-turns <n>` | Set the maximum assistant responses counted while autonomous mode is enabled. Default: `12`. |+| `--autonomous-max-tokens <n>` | Set the maximum accumulated tokens. Default: `80000`; accounting includes input, output, and cache-write tokens, but excludes cache-read tokens. |+| `--autonomous-timeout-ms <n>` | Set the maximum elapsed autonomous time in milliseconds. Default: `1800000` (30 minutes). |++All `<n>` values must be positive integers: zero, negative, fractional, and non-numeric values are rejected. Value-taking autonomous flags require a separate argument, not `--flag=value`. A missing value is rejected, and a following long option is not consumed as a value. Repeating a numeric flag uses its last value; repeating `--autonomous-gate` appends another gate.++After each assistant response, configured gates run before the ordinary continuation limits are evaluated. All gates must pass for the run to finish. A failed gate supplies bounded command output to the next continuation so the agent can repair it; Prime Agent avoids rerunning an unchanged failed gate and advances its attempt count instead. A passing gate permits completion even if a continuation, turn, token, or time limit has otherwise been reached. If a gate does not pass, or if there are no gates, the host can inject another continuation only while all four limits remain below their configured values. Limits are checked in this order: continuations, turns, tokens, then elapsed time. Reaching one prevents another automatic continuation; it does not imply task success.++For example, this noninteractive run uses a locally available model configuration, skips startup network operations, and bounds every autonomous budget while requiring the project check to pass:++```bash+prime-agent -p \+ --autonomous \+ --autonomous-gate "npm run check" \+ --autonomous-gate-retries 2 \+ --autonomous-gate-timeout-ms 300000 \+ --autonomous-max-continuations 3 \+ --autonomous-max-turns 12 \+ --autonomous-max-tokens 80000 \+ --autonomous-timeout-ms 1800000 \+ --model openai/gpt-5.1-codex \+ --offline \+ --thinking high \+ "Fix the failing check and report the verified result."+```++`--offline` disables startup network operations; it does not supply model credentials or make provider inference offline. Choose a model already configured for the local environment.++Goals are separate from autonomous mode: `--goal <objective>` starts a persistent goal only for a new root session with no existing goal state, while autonomous mode decides whether the host should inject another continuation. `--goal-token-budget <n>` is a positive-integer token budget for that initial goal and requires `--goal`.### Other Optionsdiff --git a/packages/coding-agent/src/cli/command-registry.ts b/packages/coding-agent/src/cli/command-registry.tsindex 76b794ffab..0980b67982 100644--- a/packages/coding-agent/src/cli/command-registry.ts+++ b/packages/coding-agent/src/cli/command-registry.ts@@ -158,16 +158,88 @@ export const PUBLIC_COMMAND_NAMES = new Set(export const REMOVED_COMMAND_NAMES = new Set(["app", "daemon", "install", "manage", "remove", "uninstall"]);-const TOP_LEVEL_OPTIONS = [- ["-p, --print", "Print a response and exit"],- ["-c, --continue", "Continue the previous session"],- ["-r, --resume <path|id>", "Resume a session"],- ["--model <pattern>", "Choose a model"],- ["--thinking <level>", "Set the reasoning level"],- ["--offline", "Disable startup network operations"],- ["-v, --version", "Show version and exit"],- ["-h, --help", "Show this help"],-] as const;+type TopLevelOption = readonly [option: string, summary: string];++const TOP_LEVEL_OPTION_GROUPS: ReadonlyArray<{ heading: string; options: readonly TopLevelOption[] }> = [+ {+ heading: "Run options",+ options: [+ ["-p, --print", "Print a response and exit"],+ ["--mode <text|json|rpc|daemon>", "Select the output mode (default: text)"],+ ["--cwd <dir>", "Use a specific working directory"],+ ["--offline", "Disable startup network operations"],+ ["--verbose", "Force verbose startup"],+ ["--daemon-socket <path>", "Use a specific daemon socket"],+ ],+ },+ {+ heading: "Model options",+ options: [+ ["--provider <name>", "Select a model provider"],+ ["--model <id>", "Select a model"],+ ["--api-key <key>", "Use an API key for this run"],+ ["--models <patterns>", "Set comma-separated models for cycling"],+ ["--thinking <level>", "Set reasoning: off, minimal, low, medium, high, xhigh, max"],+ ],+ },+ {+ heading: "Session options",+ options: [+ ["-c, --continue", "Continue the previous session"],+ ["-r, --resume <path|id>", "Resume a saved session"],+ ["--fork <path|id>", "Fork a saved session into a new session"],+ ["--session-dir <dir>", "Use a custom session directory"],+ ["--no-session", "Do not save the session"],+ ["--goal <objective>", "Seed a persistent goal for a new root session"],+ ["--goal-token-budget <n>", "Set a positive token budget for --goal"],+ ],+ },+ {+ heading: "Tool and resource options",+ options: [+ ["-t, --tools <list>", "Allowlist comma-separated tool names"],+ ["-nt, --no-tools", "Disable all tools by default"],+ ["-nbt, --no-builtin-tools", "Disable built-in tools by default"],+ ["-e, --extension <source>", "Load an extension (repeatable)"],+ ["-ne, --no-extensions", "Disable extension discovery"],+ ["--skill <path>", "Load a skill (repeatable)"],+ ["-ns, --no-skills", "Disable skill discovery"],+ ["--prompt-template <path>", "Load a prompt template (repeatable)"],+ ["-np, --no-prompt-templates", "Disable prompt template discovery"],+ ["--theme <path>", "Load a theme (repeatable)"],+ ["--no-themes", "Disable theme discovery"],+ ["-nc, --no-context-files", "Disable AGENTS.md and CLAUDE.md discovery"],+ ],+ },+ {+ heading: "Prompt options",+ options: [+ ["--system-prompt <text>", "Replace the default system prompt"],+ ["--append-system-prompt <text>", "Append to the system prompt (repeatable)"],+ ["--", "Treat all following arguments as messages"],+ ],+ },+ {+ heading: "Autonomous options",+ options: [+ ["--autonomous", "Continue until gates pass or a limit is reached"],+ ["--autonomous-gate <command>", "Run a completion gate (repeatable)"],+ ["--autonomous-gate-retries <n>", "Set positive retries per failed gate (default: 3)"],+ ["--autonomous-gate-timeout-ms <n>", "Set positive per-gate timeout in ms (default: 300000)"],+ ["--autonomous-max-continuations <n>", "Set positive follow-up limit (default: 3)"],+ ["--autonomous-max-turns <n>", "Set positive assistant-turn limit (default: 12)"],+ ["--autonomous-max-tokens <n>", "Set positive token limit (default: 80000)"],+ ["--autonomous-timeout-ms <n>", "Set positive wall-clock limit in ms (default: 1800000)"],+ ],+ },+ {+ heading: "Help",+ options: [+ ["-v, --version", "Show version and exit"],+ ["-h, --help", "Show this help"],+ ],+ },+];export function getCommandSpec(path: readonly string[]): CommandSpec | undefined {return COMMAND_SPECS.find(@@ -213,7 +285,7 @@ export function findCommandSuggestion(input: string, candidates: readonly stringexport function formatTopLevelHelp(): string {const commands = COMMAND_SPECS.filter((spec) => spec.path.length === 1);const commandWidth = Math.max(...commands.map((spec) => spec.path[0]!.length));- const optionWidth = Math.max(...TOP_LEVEL_OPTIONS.map(([option]) => option.length));+ const options = TOP_LEVEL_OPTION_GROUPS.map((group) => formatOptionGroup(group.heading, group.options)).join("\n\n");return `${APP_NAME} - AI coding assistant with an IPython toolUsage:@@ -221,7 +293,7 @@ Usage:${APP_NAME} <command> [args...]Options:-${TOP_LEVEL_OPTIONS.map(([option, summary]) => ` ${option.padEnd(optionWidth)} ${summary}`).join("\n")}+${options}Commands:${commands.map((spec) => ` ${spec.path[0]!.padEnd(commandWidth)} ${spec.summary}`).join("\n")}@@ -229,6 +301,11 @@ ${commands.map((spec) => ` ${spec.path[0]!.padEnd(commandWidth)} ${spec.summarRun "${APP_NAME} help <command>" for command details.`;}+function formatOptionGroup(heading: string, options: readonly TopLevelOption[]): string {+ const width = Math.max(...options.map(([option]) => option.length));+ return `${heading}:\n${options.map(([option, summary]) => ` ${option.padEnd(width)} ${summary}`).join("\n")}`;+}+export function formatCommandHelp(path: readonly string[]): string | undefined {const spec = getCommandSpec(path);if (!spec) {diff --git a/packages/coding-agent/test/public-command.test.ts b/packages/coding-agent/test/public-command.test.tsindex b4c88e737e..ef94add836 100644--- a/packages/coding-agent/test/public-command.test.ts+++ b/packages/coding-agent/test/public-command.test.ts@@ -303,16 +303,29 @@ describe("public command routing", () => {});});- it("formats concise top-level help", () => {+ it("formats complete top-level help, including autonomous options", () => {const help = formatTopLevelHelp();expect(help).toContain("Options:");- expect(help).toContain("-p, --print");+ expect(help).toContain("Run options:");+ expect(help).toContain("Autonomous options:");+ for (const option of [+ "--autonomous",+ "--autonomous-gate <command>",+ "--autonomous-gate-retries <n>",+ "--autonomous-gate-timeout-ms <n>",+ "--autonomous-max-continuations <n>",+ "--autonomous-max-turns <n>",+ "--autonomous-max-tokens <n>",+ "--autonomous-timeout-ms <n>",+ ]) {+ expect(help).toContain(option);+ }+ expect(help).toContain("default: 300000");+ expect(help).toContain("default: 1800000");expect(help).toContain("Commands:");expect(help).toContain("shutdown");- expect(help).not.toContain("daemon");expect(help).not.toContain("Environment Variables:");expect(help).not.toContain("Examples:");expect(help).not.toContain("Built-in Tool Names:");- expect(help).not.toContain("--autonomous");});});