@autonoma-ai/planner 0.1.26 → 0.1.28
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +169 -275
- package/dist/index.js +1867 -1728
- package/dist/index.js.map +1 -1
- package/package.json +22 -3
package/README.md
CHANGED
|
@@ -1,311 +1,202 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://raw.githubusercontent.com/Autonoma-AI/autonoma/main/.github/assets/banner.webp" alt="Autonoma - an agent reads your pull request, runs your app, and reports what broke" width="100%">
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<div align="center">
|
|
6
|
+
|
|
7
|
+
<picture>
|
|
8
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Autonoma-AI/autonoma/main/.github/assets/wordmark-dark.svg">
|
|
9
|
+
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Autonoma-AI/autonoma/main/.github/assets/wordmark-light.svg">
|
|
10
|
+
<img alt="Autonoma" src="https://raw.githubusercontent.com/Autonoma-AI/autonoma/main/.github/assets/wordmark-light.svg" width="240">
|
|
11
|
+
</picture>
|
|
12
|
+
|
|
13
|
+
<br/>
|
|
14
|
+
<br/>
|
|
15
|
+
|
|
1
16
|
# @autonoma-ai/planner
|
|
2
17
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
18
|
+
**One command sets Autonoma up, start to finish.**
|
|
19
|
+
|
|
20
|
+
A **preview environment**, a complete **end-to-end test suite** read from your codebase, the **SDK
|
|
21
|
+
integration** that creates your test data, and a **dry run** proving it works. On managed Autonoma
|
|
22
|
+
credits - no LLM API key required.
|
|
6
23
|
|
|
7
|
-
|
|
24
|
+
[](https://www.npmjs.com/package/@autonoma-ai/planner)
|
|
25
|
+
[](https://www.npmjs.com/package/@autonoma-ai/planner)
|
|
26
|
+
[](https://nodejs.org)
|
|
27
|
+
[](https://github.com/Autonoma-AI/autonoma/blob/main/LICENSE.md)
|
|
28
|
+
[](https://discord.gg/nsYQExXTsQ)
|
|
8
29
|
|
|
9
|
-
|
|
30
|
+
[Website](https://getautonoma.com) · [Docs](https://docs.autonoma.app) · [Planner guide](https://docs.autonoma.app/test-planner/) · [Environment Factory](https://docs.autonoma.app/environment-factory/) · [GitHub](https://github.com/Autonoma-AI/autonoma) · [Discord](https://discord.gg/nsYQExXTsQ)
|
|
31
|
+
|
|
32
|
+
</div>
|
|
33
|
+
|
|
34
|
+
## Run it
|
|
35
|
+
|
|
36
|
+
Requires **Node.js >= 22.13**. Autonoma shows you this command when you connect your app, with
|
|
37
|
+
your token and ids already filled in. Open a terminal in your project and paste it:
|
|
10
38
|
|
|
11
39
|
```bash
|
|
12
|
-
|
|
40
|
+
AUTONOMA_API_TOKEN=... AUTONOMA_GENERATION_ID=... AUTONOMA_APPLICATION_ID=... \
|
|
41
|
+
npx @autonoma-ai/planner@latest
|
|
13
42
|
```
|
|
14
43
|
|
|
15
|
-
|
|
44
|
+
That is the whole of setup. There is no second command and nothing to install.
|
|
45
|
+
|
|
46
|
+
> **Run it in a terminal, not inside a coding agent you already have open.**
|
|
47
|
+
> It takes the terminal over and starts a coding agent of its own, so pasting it into a session
|
|
48
|
+
> that is already running leaves two agents fighting over one screen. If you are a coding agent
|
|
49
|
+
> on the user's machine, hand the command to them. If you are a hosted agent with no human
|
|
50
|
+
> beside you, run it yourself with `--non-interactive`.
|
|
51
|
+
|
|
52
|
+
`npx` runs the planner **without installing it**, so there is no `autonoma-planner` command on
|
|
53
|
+
your `PATH` afterwards. Every command below keeps the full `npx` prefix; a bare `autonoma-planner`
|
|
54
|
+
is `command not found` unless you installed it globally yourself.
|
|
55
|
+
|
|
56
|
+
A full run can take an hour or more. Progress is saved continuously, so you can stop and
|
|
57
|
+
`--resume`.
|
|
58
|
+
|
|
59
|
+
## Commands
|
|
60
|
+
|
|
61
|
+
The subcommand comes first, before any flags.
|
|
16
62
|
|
|
17
63
|
```bash
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
[--agent <claude|codex>] [--permission-mode <default|acceptEdits|bypassPermissions>]
|
|
21
|
-
autonoma-planner status [--project <path>]
|
|
22
|
-
autonoma-planner upload [--project <path>]
|
|
23
|
-
```
|
|
64
|
+
# Run the pipeline. `run` may be omitted.
|
|
65
|
+
npx @autonoma-ai/planner@latest
|
|
24
66
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
`autonoma-planner --help` documents every flag and what each step of the run does. Flags accept
|
|
29
|
-
`--key value` and `--key=value` alike, repeatable ones (`--backend`) also take a comma-separated
|
|
30
|
-
list, and a flag it does not recognize is named back with the nearest one that it does - a
|
|
31
|
-
misspelled `--non-interactive` would otherwise leave the run waiting on questions nobody can
|
|
32
|
-
answer.
|
|
33
|
-
|
|
34
|
-
### The dashboard (TUI)
|
|
35
|
-
|
|
36
|
-
On an interactive terminal the pipeline phase runs inside a live Ink dashboard: a horizontal
|
|
37
|
-
pipeline strip across the top (step status, spinner on the running step, sub-progress), the
|
|
38
|
-
file list on the left (each generated file with its status - a test also carries its review
|
|
39
|
-
verdict there: `REVIEWING`, `✓ REVIEWED`, or `FIXING` while a fix agent rewrites it), and a
|
|
40
|
-
wide document viewer showing
|
|
41
|
-
the file currently being written, live from disk - known documents (frontmatter, pages.json)
|
|
42
|
-
render as readable cards and tables instead of raw source. An IDE-style ACTIVITY panel at the
|
|
43
|
-
bottom streams the agent's tool calls. Navigate with arrows or `h/j/k/l` (left/right switch
|
|
44
|
-
between the file list and the viewer - right from the list opens the selected file; up/down
|
|
45
|
-
move the cursor or scroll), `f` re-follows the newest file, `g`/`G` jump top/bottom, `?` opens
|
|
46
|
-
a help modal explaining the current step with docs links, and Ctrl+C twice exits with progress
|
|
47
|
-
saved. Questions (resume?, scope selection, step failures) render as an ACTION REQUIRED modal
|
|
48
|
-
inside the dashboard; the terminal is handed over only for the
|
|
49
|
-
SDK-integration handoff below, and the dashboard comes back when the agent exits.
|
|
50
|
-
|
|
51
|
-
Piped output, CI, and `--non-interactive` keep the plain line-based output. See
|
|
52
|
-
`docs/ui-design-brief.md` for the design rationale; `pnpm ui:gallery` steps through every
|
|
53
|
-
dashboard state with fixture data (Tab / Shift+Tab).
|
|
54
|
-
Pass a past run's output directory - `pnpm ui:gallery ~/.autonoma/<slug>` - to add a scene
|
|
55
|
-
backed by real files, so navigation and scrolling can be tested on real documents.
|
|
56
|
-
|
|
57
|
-
`upload` re-uploads everything already generated in `~/.autonoma/<app>/` - the recipe and the
|
|
58
|
-
artifacts (test cases, `AUTONOMA.md`, `scenarios.md`, `entity-audit.md`) - without re-running the
|
|
59
|
-
whole planner. Useful when an upload failed. Both the recipe and artifact endpoints are idempotent,
|
|
60
|
-
so it is safe to run repeatedly. It needs the same `AUTONOMA_API_TOKEN` and `AUTONOMA_GENERATION_ID`
|
|
61
|
-
env vars as a run (`AUTONOMA_API_URL` stays optional - the host defaults to production). Note that if
|
|
62
|
-
a recipe submit fails during a run, the full recipe JSON is also printed to stdout so it can be
|
|
63
|
-
recovered even from an ephemeral container.
|
|
64
|
-
|
|
65
|
-
### Preview environments (when the run starts from onboarding)
|
|
66
|
-
|
|
67
|
-
A run launched from Autonoma's connect screen begins one step earlier than the pipeline
|
|
68
|
-
below: with the **preview environment**, a real deployment of your app that Autonoma builds
|
|
69
|
-
per pull request and tests against. The CLI registers the Autonoma MCP server with your
|
|
70
|
-
coding agent and then starts a fresh session on the job - registering first is the whole
|
|
71
|
-
trick, because an agent only loads its MCP servers at startup and so can never pick up one
|
|
72
|
-
it registered itself.
|
|
73
|
-
|
|
74
|
-
The CLI decides this from your app's onboarding status, so it only happens when there is
|
|
75
|
-
something to do:
|
|
76
|
-
|
|
77
|
-
- Started from the connect screen, with no preview yet: preview environment, then the
|
|
78
|
-
pipeline.
|
|
79
|
-
- Started from **Finish setup**, or with a preview you set up by hand: straight to the
|
|
80
|
-
pipeline, exactly as before.
|
|
81
|
-
- No `AUTONOMA_APPLICATION_ID` (a standalone run against any repo): straight to the
|
|
82
|
-
pipeline, and nothing here applies.
|
|
83
|
-
|
|
84
|
-
Once a run is past the preview environment, it tells Autonoma it is driving the app, and
|
|
85
|
-
the web app replaces the setup steps with a note pointing you back at this terminal -
|
|
86
|
-
there is nothing to do in both places at once. "Take over" in the web app hands the steps
|
|
87
|
-
back to you; a run in progress keeps going, so stop it here too.
|
|
88
|
-
|
|
89
|
-
Completion is read from Autonoma, not from your agent - an interactive session does not
|
|
90
|
-
exit when its work is done, and its exit code says nothing about whether a preview
|
|
91
|
-
deployed. That also makes it work the same whether your previews are Autonoma-hosted, on
|
|
92
|
-
Vercel, or from your own pipeline. If the preview does not finish, the run continues to
|
|
93
|
-
generate your test suite and warns you: only scenario dry runs need a live preview.
|
|
94
|
-
|
|
95
|
-
### Monorepos
|
|
96
|
-
|
|
97
|
-
The run starts by mapping your repository - discovering which folder(s) are frontends, which are
|
|
98
|
-
backends/data layers, and which are unrelated - so every later step scans only the relevant code
|
|
99
|
-
instead of the whole tree. In an interactive run you pick the frontend to test (and its backends)
|
|
100
|
-
from a menu. To scope non-interactively, pass:
|
|
101
|
-
|
|
102
|
-
- `--frontend <path>` - the one frontend directory to plan tests for.
|
|
103
|
-
- `--backends <path,path>` - comma-separated backend/data-layer directories it depends on. Omit to
|
|
104
|
-
default to the dependencies the mapper inferred for that frontend.
|
|
105
|
-
|
|
106
|
-
For a single-app repo the mapper resolves the scope on its own and no flags are needed.
|
|
107
|
-
|
|
108
|
-
### Running without a human
|
|
109
|
-
|
|
110
|
-
`--non-interactive` is the path a hosted agent takes, and it runs the whole thing in one
|
|
111
|
-
invocation - there is never a list of steps for a caller to sequence. Because nobody can be asked
|
|
112
|
-
anything, every input that would have been a question is also a flag: `--agent`, `--frontend`,
|
|
113
|
-
`--backend`, `--permission-mode`, `--resume`, `--fresh`.
|
|
114
|
-
|
|
115
|
-
What the run does about the questions it cannot ask:
|
|
116
|
-
|
|
117
|
-
- **It never opens a browser.** The coding agent's Autonoma connection is authorized with the
|
|
118
|
-
`AUTONOMA_API_TOKEN` the run already holds. The browser sign-in is refused outright without a
|
|
119
|
-
terminal rather than attempted - it would not fail, it would hang on a callback nobody triggers.
|
|
120
|
-
- **It says what it assumed.** Where it proceeds on an answer nobody gave - continuing from a
|
|
121
|
-
previous run's output, say - it prints what was assumed and the flag that would have said
|
|
122
|
-
otherwise.
|
|
123
|
-
- **It reports each step as it starts and finishes**, with its position in the run and how long it
|
|
124
|
-
took, so the process that launched it can tell work from a stall.
|
|
125
|
-
- **It refuses rather than guesses** when the choice would be arbitrary: several frontends and no
|
|
126
|
-
`--frontend` pauses with the flag to pass, and both coding agents installed with no `--agent`
|
|
127
|
-
skips the handoff and says to name one.
|
|
128
|
-
|
|
129
|
-
## SDK integration handoff (test-data step)
|
|
130
|
-
|
|
131
|
-
The "Set up test data" step wires the Autonoma SDK "environment factory" into your app so the
|
|
132
|
-
platform can seed and tear down realistic test data through your app's own creation code. Instead
|
|
133
|
-
of a copy-paste guide, the CLI hands the whole integration to your **locally-installed coding agent**
|
|
134
|
-
(Claude Code or Codex CLI) in
|
|
135
|
-
one interactive, autonomous session - like `git commit` with no `-m` opening your editor. You watch
|
|
136
|
-
it install the SDK, build the endpoint, write the factories, **generate the test-data recipe**, and
|
|
137
|
-
validate each entity itself: for every entity it runs `up`, checks your database for the new rows,
|
|
138
|
-
runs `down`, and checks they're gone. It finishes with `sdk up --repeat 3`, which seeds the whole
|
|
139
|
-
recipe three times over **without tearing down in between** - the only check that catches a value
|
|
140
|
-
the recipe reuses across runs, since every other check tears down before the next seed and so
|
|
141
|
-
passes a recipe that can only ever exist once. A collision there is the unique constraint your
|
|
142
|
-
customer would hit the first time they run two tests at the same time; the command reports which
|
|
143
|
-
instance failed, then removes every instance it created. It drives the endpoint through the CLI's own signed client
|
|
144
|
-
(`autonoma-planner sdk discover|up|down`), so its checks use the exact request signing and the exact
|
|
145
|
-
recipe-token substitution the platform uses. Before it declares the session done it must also run
|
|
146
|
-
`autonoma-planner sdk check --recipe <file>`, which holds the recipe FILE to the format Autonoma
|
|
147
|
-
accepts on upload - the same gate the CLI applies the moment the agent exits, so a rejected recipe
|
|
148
|
-
is a fix the agent makes while it's still running rather than a re-launch afterwards. All of that
|
|
149
|
-
happens on a branch it cuts from your
|
|
150
|
-
repo's default branch, and it pushes the finished integration as a pull request rather than leaving
|
|
151
|
-
the changes loose in your working tree. When it reports the session complete, the CLI uploads
|
|
152
|
-
the recipe it produced and continues to test generation.
|
|
153
|
-
|
|
154
|
-
- `--agent <name>` - preselect the agent to hand off to (`claude` or `codex`). Omit to auto-detect;
|
|
155
|
-
if both are installed you're prompted to pick once and that choice is remembered for later runs
|
|
156
|
-
(in `~/.autonoma/preferences.json`), and headless - where there is nobody to ask - the first is
|
|
157
|
-
used and named in a warning. The flag always wins over what was remembered.
|
|
158
|
-
- `--permission-mode <mode>` - how much autonomy the agent runs with: `default` (approve each
|
|
159
|
-
command), `acceptEdits` (auto-edit files, approve commands), or `bypassPermissions` (fully
|
|
160
|
-
autonomous, the default). Both the agent and the mode you pick are persisted for `--resume`. For
|
|
161
|
-
Codex these map onto its sandbox/approval model (always `--sandbox danger-full-access` because the
|
|
162
|
-
integration must install the SDK and reach the network, with approval strictness as the only lever;
|
|
163
|
-
`bypassPermissions` uses `--dangerously-bypass-approvals-and-sandbox`).
|
|
164
|
-
|
|
165
|
-
If no supported agent is installed (or you decline the handoff), the CLI writes the full
|
|
166
|
-
integration instructions to `~/.autonoma/<app>/integration-prompt.md` and pauses so you can
|
|
167
|
-
implement them in whatever assistant you have, then `--resume` to continue. `--non-interactive`
|
|
168
|
-
runs are unchanged: they emit a data-only recipe with no implementation or validation.
|
|
67
|
+
# Show what a previous run completed. Local only - reads saved progress, no network.
|
|
68
|
+
npx @autonoma-ai/planner@latest status
|
|
169
69
|
|
|
170
|
-
|
|
70
|
+
# Re-send everything already generated on disk. Idempotent, and the fix when a run
|
|
71
|
+
# finished but an artifact did not arrive. Needs the same env vars as a run.
|
|
72
|
+
AUTONOMA_API_TOKEN=... AUTONOMA_GENERATION_ID=... \
|
|
73
|
+
npx @autonoma-ai/planner@latest upload
|
|
171
74
|
|
|
172
|
-
|
|
75
|
+
# Every flag, and what each step of the run does.
|
|
76
|
+
npx @autonoma-ai/planner@latest --help
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
> **`--resume` will not retry a failed upload.** It continues from the first *step* that is not
|
|
80
|
+
> finished, so a run where every step finished and only the upload failed prints
|
|
81
|
+
> `All steps complete.` and exits. Use `upload` for that.
|
|
82
|
+
|
|
83
|
+
## Flags
|
|
173
84
|
|
|
174
85
|
```
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
86
|
+
--project <path> target a repo other than the current directory
|
|
87
|
+
--frontend <path> in a monorepo, the frontend directory to plan tests for
|
|
88
|
+
--backend <path> a backend/data layer it talks to. Repeatable, or comma-separated
|
|
89
|
+
--coding-agent <name> which agent handles the preview and SDK steps: claude | codex
|
|
90
|
+
--permission-mode <mode> its autonomy: bypassPermissions (default) | acceptEdits | default
|
|
91
|
+
--non-interactive run unattended, with no questions
|
|
92
|
+
--resume continue from where a previous run stopped
|
|
93
|
+
--fresh discard a previous run's output and start over
|
|
94
|
+
--step <name> run a single step and stop - for debugging, not for sequencing a run
|
|
95
|
+
--model <id> pick a different Autonoma-hosted model (still no key needed)
|
|
96
|
+
--slug <name> override the output folder name under ~/.autonoma/
|
|
185
97
|
```
|
|
186
98
|
|
|
187
|
-
`
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
99
|
+
`--agent` and `--backends` are accepted as aliases of `--coding-agent` and `--backend`. Flags take
|
|
100
|
+
`--key value` and `--key=value` alike, and an unrecognized flag is named back with the nearest one
|
|
101
|
+
that exists - a misspelled `--non-interactive` would otherwise leave the run waiting on questions
|
|
102
|
+
nobody can answer.
|
|
191
103
|
|
|
192
|
-
##
|
|
104
|
+
## What it does
|
|
193
105
|
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
106
|
+
| # | Step | Output |
|
|
107
|
+
| --- | --- | --- |
|
|
108
|
+
| 1 | **Preview environment** - hands your coding agent the job of setting up a real per-PR deployment. Skipped when you already have one. | a live preview |
|
|
109
|
+
| 2 | **Map your project structure** - finds your frontend(s) and backend(s), so later steps scan only what matters. | `project-map.json` |
|
|
110
|
+
| 3 | **Find your pages** - maps every page and route. | `pages.json` |
|
|
111
|
+
| 4 | **Build a knowledge base** - learns your features, flows and UI patterns. | `AUTONOMA.md` |
|
|
112
|
+
| 5 | **Map your data models** - finds what your app stores and how each record is created. | `entity-audit.md` |
|
|
113
|
+
| 6 | **Design test scenarios** - decides the realistic data each test runs against. | `scenarios.md` |
|
|
114
|
+
| 7 | **Set up test data** - hands the Environment Factory integration to your coding agent, which implements it, validates it live, and produces the recipe. | `recipe.json` |
|
|
115
|
+
| 8 | **Generate the tests** - writes the E2E tests as natural-language markdown, then uploads the suite. | `qa-tests/` |
|
|
198
116
|
|
|
199
|
-
|
|
117
|
+
Steps 1 and 7 hand the terminal to your **locally installed coding agent** (Claude Code or Codex
|
|
118
|
+
CLI) the way `git commit` opens your editor - the dashboard steps aside, and control comes back
|
|
119
|
+
when the agent exits.
|
|
200
120
|
|
|
201
|
-
|
|
121
|
+
<p align="center">
|
|
122
|
+
<img src="https://docs.autonoma.app/img/test-planner/tui-handoff.png" alt="The planner's terminal just before the handoff: a modal over the dimmed dashboard badged UP NEXT, headed 'Handing off to Claude Code', explaining that the terminal is about to switch and that you come straight back afterwards, with a footer reading 'Continuing in 10s - enter continue now'" width="100%">
|
|
123
|
+
</p>
|
|
202
124
|
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
provisions and tears down every scenario against it, one at a time.
|
|
125
|
+
If neither agent is installed, the planner writes the full instructions to
|
|
126
|
+
`~/.autonoma/<app>/integration-prompt.md` so you can implement them with any assistant, then
|
|
127
|
+
continue with `--resume`.
|
|
207
128
|
|
|
208
|
-
|
|
209
|
-
healthy app they need no judgement - only the credentials and the app id the run already holds.
|
|
129
|
+
## Watch it work
|
|
210
130
|
|
|
211
|
-
|
|
212
|
-
problems. A build gets a generous ceiling (20 minutes - it covers a cold image build). A pull
|
|
213
|
-
request with no preview environment gets a minute, since that state is either a webhook that has
|
|
214
|
-
not caught up yet or a draft pull request that will never get one.
|
|
131
|
+
A full run takes a while, so on an interactive terminal the pipeline runs inside a live dashboard.
|
|
215
132
|
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
nothing - which is exactly what an API call cannot do. The agent gets the Autonoma MCP and the
|
|
220
|
-
job of making both facts true, and the run ends when Autonoma reports them, not when the agent
|
|
221
|
-
says so. A run whose dry run passed first time spawns nothing.
|
|
133
|
+
<p align="center">
|
|
134
|
+
<img src="https://docs.autonoma.app/img/test-planner/tui-dashboard.png" alt="The planner's terminal dashboard mid-run: a top bar with the project, elapsed time and an ETA; the seven pipeline steps as a strip with two ticked and 'Build knowledge base' active at 9 of 24 pages; a FILES list on the left; AUTONOMA.md streaming in live on the right, marked WRITING LIVE; and an ACTIVITY feed logging each agent call" width="100%">
|
|
135
|
+
</p>
|
|
222
136
|
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
137
|
+
The steps run as a strip across the top, the files produced sit on the left, and the document being
|
|
138
|
+
written right now streams from disk on the right - so you can read the knowledge base, scenarios
|
|
139
|
+
and tests as they are produced. Navigate with arrows or `h/j/k/l`, `f` to follow the newest file,
|
|
140
|
+
`?` for help, Ctrl+C twice to exit with progress saved.
|
|
226
141
|
|
|
227
|
-
|
|
228
|
-
answering, scenarios provisioning, and whether Autonoma is reviewing your pull requests. It
|
|
229
|
-
takes the app live itself once the preview is verified: your coding agent is told to do that,
|
|
230
|
-
but the run stops the agent the moment the preview is confirmed, which is the same moment it
|
|
231
|
-
would have.
|
|
142
|
+
Piped output, CI and `--non-interactive` keep plain line-based output.
|
|
232
143
|
|
|
233
|
-
##
|
|
144
|
+
## Output
|
|
234
145
|
|
|
235
|
-
|
|
236
|
-
| ------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
237
|
-
| `AUTONOMA_API_TOKEN` | yes | Autonoma API token. Authenticates the planner, which runs on managed Autonoma credits through our LLM proxy - no LLM key needed. Injected by the Autonoma app; create one at https://autonoma.app/settings/api-keys to run standalone. Also used to upload artifacts. |
|
|
238
|
-
| `OPENROUTER_MODEL` | no | Override the default model (OpenRouter-style model id, forwarded by the proxy). |
|
|
239
|
-
| `AUTONOMA_API_URL` | no | Base URL of the Autonoma API. Defaults to `https://autonoma.app`; override to target an alpha/preview host. |
|
|
240
|
-
| `AUTONOMA_GENERATION_ID` | for upload | The setup id artifacts are uploaded against. Injected by onboarding. |
|
|
241
|
-
| `AUTONOMA_APPLICATION_ID` | no | The application this run belongs to. Lets the CLI read onboarding state (so it can skip work the app has already had done) and mint pairing codes for the coding agents it hands off to. Injected by onboarding. |
|
|
242
|
-
| `AUTONOMA_SHARED_SECRET` | no | Per-application secret used to sign SDK/webhook requests. Injected by onboarding. |
|
|
243
|
-
| `AUTONOMA_DISTINCT_ID` | no | PostHog identity so CLI events join the signup funnel. Injected by onboarding. |
|
|
244
|
-
| `DONT_TRACK` | no | Set to `1`/`true` to disable all telemetry - events, log shipping and session replay. |
|
|
146
|
+
Artifacts are written to `~/.autonoma/<project-slug>/` as they are produced:
|
|
245
147
|
|
|
246
|
-
|
|
247
|
-
|
|
148
|
+
```
|
|
149
|
+
~/.autonoma/<app>/
|
|
150
|
+
├── project-map.json # discovered frontends/backends + the scope chosen for this run
|
|
151
|
+
├── AUTONOMA.md # knowledge base
|
|
152
|
+
├── scenarios.md # test-data scenario descriptions
|
|
153
|
+
├── entity-audit.md # database model audit
|
|
154
|
+
├── recipe.json # scenario recipes; the coding agent generates and validates it
|
|
155
|
+
├── integration-prompt.md # rendered SDK-integration instructions
|
|
156
|
+
└── qa-tests/ # generated test cases (markdown)
|
|
157
|
+
├── INDEX.md # table of contents, written last from the files on disk
|
|
158
|
+
└── _invalid/ # tests that failed structural validation; never uploaded
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
When the run is attached to an Autonoma application it uploads these itself - there is no manual
|
|
162
|
+
upload step. Without credentials it just leaves them on disk.
|
|
163
|
+
|
|
164
|
+
## Environment variables
|
|
165
|
+
|
|
166
|
+
The command Autonoma gives you already carries these; the only one you set by hand is a token for
|
|
167
|
+
a standalone run.
|
|
168
|
+
|
|
169
|
+
| Variable | Required | Purpose |
|
|
170
|
+
| --- | --- | --- |
|
|
171
|
+
| `AUTONOMA_API_TOKEN` | yes | The run's credential. It runs on managed Autonoma credits through our LLM proxy, so no LLM key is needed. Create one under **Settings → API keys**. |
|
|
172
|
+
| `AUTONOMA_APPLICATION_ID` | no | The app this run belongs to. With it the run also sets up the preview environment and validates the result; without it the planner runs standalone against any repo. |
|
|
173
|
+
| `AUTONOMA_GENERATION_ID` | for upload | The setup its artifacts are uploaded against. |
|
|
174
|
+
| `AUTONOMA_SHARED_SECRET` | no | Signs the SDK and webhook requests the run makes on your behalf. |
|
|
175
|
+
| `AUTONOMA_API_URL` | no | Point at a non-production Autonoma. Defaults to production. |
|
|
176
|
+
| `AUTONOMA_DISTINCT_ID` | no | PostHog identity, so CLI events join the signup funnel. |
|
|
177
|
+
| `OPENROUTER_MODEL` | no | Override the default model (an OpenRouter-style id, forwarded by the proxy). |
|
|
178
|
+
| `DONT_TRACK` | no | `1`/`true` disables all telemetry - events, log shipping and session replay. |
|
|
179
|
+
| `AUTONOMA_DEBUG` | no | `1`/`true` prints diagnostic breadcrumbs to stderr **and** writes a full JSONL transcript to `~/.autonoma/debug/<run-id>.jsonl`. |
|
|
180
|
+
| `AUTONOMA_DEBUG_FILE` | no | Write that transcript to this path instead, without the stderr noise. Independent of `DONT_TRACK` - it never leaves your machine. |
|
|
248
181
|
|
|
249
182
|
## Telemetry
|
|
250
183
|
|
|
251
|
-
Three lanes, all to PostHog, all off
|
|
252
|
-
|
|
253
|
-
- **Events**
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
| `generation_id` | The onboarding setup the run is fulfilling - the join back to an Autonoma record. |
|
|
268
|
-
| `posthogDistinctId` | The person, when the app launched the CLI with an identity; otherwise an anonymous per-machine device id. |
|
|
269
|
-
| `project_slug`, `cli_version`, `node_version` | Which project, which build, which runtime. |
|
|
270
|
-
|
|
271
|
-
To read one run: filter logs by `service.name = autonoma-planner` and the `generation_id` (or `run_id`)
|
|
272
|
-
you are chasing, ordered earliest-first.
|
|
273
|
-
|
|
274
|
-
Log records carry **metadata only** - step names, agent and tool names, file paths, patterns, commands,
|
|
275
|
-
durations, and error messages. Model prose and reasoning, prompts, and the contents of any file the
|
|
276
|
-
agent read or wrote are never sent; those are what would carry a user's source code off their machine.
|
|
277
|
-
Records are truncated and a single run is capped at 5000 of them, so a stuck agent loop cannot flood
|
|
278
|
-
ingestion - the cap being reached is itself logged.
|
|
279
|
-
|
|
280
|
-
### Session replay
|
|
281
|
-
|
|
282
|
-
An interactive run is recorded and plays back in PostHog's normal session-replay player, alongside web
|
|
283
|
-
recordings for the same person. It uses the run id as its `$session_id`, so a recording, its events and
|
|
284
|
-
its logs all resolve to one another.
|
|
285
|
-
|
|
286
|
-
`DONT_TRACK=1` turns it off along with the other two lanes - one switch, no partial opt-out.
|
|
287
|
-
|
|
288
|
-
**This lane captures more than the others, and it is worth being explicit about it.** Events and logs
|
|
289
|
-
are deliberately metadata-only - no prompts, no model prose, no file contents. A replay is a verbatim
|
|
290
|
-
copy of the dashboard, and the dashboard renders repository paths and the contents of the files the run
|
|
291
|
-
generates. Anything visible on screen is in the recording. Keystrokes are the one exception: printable
|
|
292
|
-
characters are recorded as a placeholder, never the literal key, so the upload is not a transcript of
|
|
293
|
-
the keyboard.
|
|
294
|
-
|
|
295
|
-
How it works (`src/replay/`):
|
|
296
|
-
|
|
297
|
-
- Frames come from an off-screen render of the same `<App>` the user sees, using Ink's `debug`
|
|
298
|
-
mode, which writes a complete frame with no cursor escapes. Scraping the terminal repaint stream
|
|
299
|
-
would not work, because Ink can emit either full redraws or per-line incremental updates.
|
|
300
|
-
- Each frame becomes a synthetic DOM: one `<div>` per terminal row, spans for each colour run.
|
|
301
|
-
- Frames are diffed row by row, so a repaint uploads only the rows that changed. A full snapshot of
|
|
302
|
-
the dashboard is tens of kilobytes; a typical repaint is a few hundred bytes.
|
|
303
|
-
- Keystrokes are emitted as rrweb input events, because PostHog derives the active/inactive split
|
|
304
|
-
from interaction events alone. Without them a run of pure repaints reads as entirely idle and the
|
|
305
|
-
player's inactivity-skipping has nothing to skip to. Printable characters are recorded as a
|
|
306
|
-
placeholder rather than the literal key, so the upload is not a transcript of the keyboard.
|
|
307
|
-
- Capture is rate limited to 2 fps, batched under PostHog's size limit, and capped per run. Any
|
|
308
|
-
failure is swallowed - a recording is never worth failing a run over.
|
|
184
|
+
Three lanes, all to PostHog, all off together with `DONT_TRACK=1` - one switch, no partial opt-out.
|
|
185
|
+
|
|
186
|
+
- **Events** - run and step lifecycle (`cli_run_started`, `cli_step_completed`, `$exception`).
|
|
187
|
+
- **Logs** - the run's narrative, shipped as OTLP records under the service name
|
|
188
|
+
`autonoma-planner`.
|
|
189
|
+
- **Session replay** - the dashboard itself, as rrweb events.
|
|
190
|
+
|
|
191
|
+
Events and logs carry **metadata only**: step names, agent and tool names, file paths, durations
|
|
192
|
+
and error messages. Model prose, prompts, and the contents of any file the agent read or wrote are
|
|
193
|
+
never sent.
|
|
194
|
+
|
|
195
|
+
**Session replay captures more, and it is worth being explicit.** A replay is a verbatim copy of
|
|
196
|
+
the dashboard, which renders repository paths and the contents of the files the run generates -
|
|
197
|
+
anything visible on screen is in the recording. Keystrokes are the exception: printable characters
|
|
198
|
+
are recorded as a placeholder, never the literal key, so the upload is not a transcript of your
|
|
199
|
+
keyboard.
|
|
309
200
|
|
|
310
201
|
## Development
|
|
311
202
|
|
|
@@ -315,4 +206,7 @@ pnpm dev # run from source (tsx)
|
|
|
315
206
|
pnpm build # bundle with tsup
|
|
316
207
|
pnpm typecheck
|
|
317
208
|
pnpm test
|
|
209
|
+
pnpm ui:gallery # step through every dashboard state with fixture data
|
|
318
210
|
```
|
|
211
|
+
|
|
212
|
+
See `docs/ui-design-brief.md` for the dashboard's design rationale.
|