@autonoma-ai/planner 0.1.24 → 0.1.25
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 +122 -23
- package/dist/index.js +2457 -768
- package/dist/index.js.map +1 -1
- package/package.json +4 -1
package/README.md
CHANGED
|
@@ -15,9 +15,9 @@ npx @autonoma-ai/planner@latest
|
|
|
15
15
|
Commands:
|
|
16
16
|
|
|
17
17
|
```bash
|
|
18
|
-
autonoma-planner [run] [--project <path>] [--frontend <path>] [--
|
|
19
|
-
[--model <id>] [--step <name>] [--resume] [--non-interactive] \
|
|
20
|
-
[--agent <
|
|
18
|
+
autonoma-planner [run] [--project <path>] [--frontend <path>] [--backend <path>] \
|
|
19
|
+
[--model <id>] [--step <name>] [--resume] [--fresh] [--non-interactive] \
|
|
20
|
+
[--agent <claude|codex>] [--permission-mode <default|acceptEdits|bypassPermissions>]
|
|
21
21
|
autonoma-planner status [--project <path>]
|
|
22
22
|
autonoma-planner upload [--project <path>]
|
|
23
23
|
```
|
|
@@ -25,6 +25,12 @@ autonoma-planner upload [--project <path>]
|
|
|
25
25
|
`run` is the default and may be omitted. A run can take an hour or more; progress is saved, so you
|
|
26
26
|
can stop and `--resume` later.
|
|
27
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
|
+
|
|
28
34
|
### The dashboard (TUI)
|
|
29
35
|
|
|
30
36
|
On an interactive terminal the pipeline phase runs inside a live Ink dashboard: a horizontal
|
|
@@ -54,6 +60,36 @@ env vars as a run (`AUTONOMA_API_URL` stays optional - the host defaults to prod
|
|
|
54
60
|
a recipe submit fails during a run, the full recipe JSON is also printed to stdout so it can be
|
|
55
61
|
recovered even from an ephemeral container.
|
|
56
62
|
|
|
63
|
+
### Preview environments (when the run starts from onboarding)
|
|
64
|
+
|
|
65
|
+
A run launched from Autonoma's connect screen begins one step earlier than the pipeline
|
|
66
|
+
below: with the **preview environment**, a real deployment of your app that Autonoma builds
|
|
67
|
+
per pull request and tests against. The CLI registers the Autonoma MCP server with your
|
|
68
|
+
coding agent and then starts a fresh session on the job - registering first is the whole
|
|
69
|
+
trick, because an agent only loads its MCP servers at startup and so can never pick up one
|
|
70
|
+
it registered itself.
|
|
71
|
+
|
|
72
|
+
The CLI decides this from your app's onboarding status, so it only happens when there is
|
|
73
|
+
something to do:
|
|
74
|
+
|
|
75
|
+
- Started from the connect screen, with no preview yet: preview environment, then the
|
|
76
|
+
pipeline.
|
|
77
|
+
- Started from **Finish setup**, or with a preview you set up by hand: straight to the
|
|
78
|
+
pipeline, exactly as before.
|
|
79
|
+
- No `AUTONOMA_APPLICATION_ID` (a standalone run against any repo): straight to the
|
|
80
|
+
pipeline, and nothing here applies.
|
|
81
|
+
|
|
82
|
+
Once a run is past the preview environment, it tells Autonoma it is driving the app, and
|
|
83
|
+
the web app replaces the setup steps with a note pointing you back at this terminal -
|
|
84
|
+
there is nothing to do in both places at once. "Take over" in the web app hands the steps
|
|
85
|
+
back to you; a run in progress keeps going, so stop it here too.
|
|
86
|
+
|
|
87
|
+
Completion is read from Autonoma, not from your agent - an interactive session does not
|
|
88
|
+
exit when its work is done, and its exit code says nothing about whether a preview
|
|
89
|
+
deployed. That also makes it work the same whether your previews are Autonoma-hosted, on
|
|
90
|
+
Vercel, or from your own pipeline. If the preview does not finish, the run continues to
|
|
91
|
+
generate your test suite and warns you: only scenario dry runs need a live preview.
|
|
92
|
+
|
|
57
93
|
### Monorepos
|
|
58
94
|
|
|
59
95
|
The run starts by mapping your repository - discovering which folder(s) are frontends, which are
|
|
@@ -67,6 +103,27 @@ from a menu. To scope non-interactively, pass:
|
|
|
67
103
|
|
|
68
104
|
For a single-app repo the mapper resolves the scope on its own and no flags are needed.
|
|
69
105
|
|
|
106
|
+
### Running without a human
|
|
107
|
+
|
|
108
|
+
`--non-interactive` is the path a hosted agent takes, and it runs the whole thing in one
|
|
109
|
+
invocation - there is never a list of steps for a caller to sequence. Because nobody can be asked
|
|
110
|
+
anything, every input that would have been a question is also a flag: `--agent`, `--frontend`,
|
|
111
|
+
`--backend`, `--permission-mode`, `--resume`, `--fresh`.
|
|
112
|
+
|
|
113
|
+
What the run does about the questions it cannot ask:
|
|
114
|
+
|
|
115
|
+
- **It never opens a browser.** The coding agent's Autonoma connection is authorized with the
|
|
116
|
+
`AUTONOMA_API_TOKEN` the run already holds. The browser sign-in is refused outright without a
|
|
117
|
+
terminal rather than attempted - it would not fail, it would hang on a callback nobody triggers.
|
|
118
|
+
- **It says what it assumed.** Where it proceeds on an answer nobody gave - continuing from a
|
|
119
|
+
previous run's output, say - it prints what was assumed and the flag that would have said
|
|
120
|
+
otherwise.
|
|
121
|
+
- **It reports each step as it starts and finishes**, with its position in the run and how long it
|
|
122
|
+
took, so the process that launched it can tell work from a stall.
|
|
123
|
+
- **It refuses rather than guesses** when the choice would be arbitrary: several frontends and no
|
|
124
|
+
`--frontend` pauses with the flag to pass, and both coding agents installed with no `--agent`
|
|
125
|
+
skips the handoff and says to name one.
|
|
126
|
+
|
|
70
127
|
## SDK integration handoff (test-data step)
|
|
71
128
|
|
|
72
129
|
The "Set up test data" step wires the Autonoma SDK "environment factory" into your app so the
|
|
@@ -76,16 +133,25 @@ of a copy-paste guide, the CLI hands the whole integration to your **locally-ins
|
|
|
76
133
|
one interactive, autonomous session - like `git commit` with no `-m` opening your editor. You watch
|
|
77
134
|
it install the SDK, build the endpoint, write the factories, **generate the test-data recipe**, and
|
|
78
135
|
validate each entity itself: for every entity it runs `up`, checks your database for the new rows,
|
|
79
|
-
runs `down`, and checks they're gone. It finishes
|
|
80
|
-
recipe
|
|
136
|
+
runs `down`, and checks they're gone. It finishes with `sdk up --repeat 3`, which seeds the whole
|
|
137
|
+
recipe three times over **without tearing down in between** - the only check that catches a value
|
|
138
|
+
the recipe reuses across runs, since every other check tears down before the next seed and so
|
|
139
|
+
passes a recipe that can only ever exist once. A collision there is the unique constraint your
|
|
140
|
+
customer would hit the first time they run two tests at the same time; the command reports which
|
|
141
|
+
instance failed, then removes every instance it created. It drives the endpoint through the CLI's own signed client
|
|
81
142
|
(`autonoma-planner sdk discover|up|down`), so its checks use the exact request signing and the exact
|
|
82
|
-
recipe-token substitution the platform uses.
|
|
143
|
+
recipe-token substitution the platform uses. Before it declares the session done it must also run
|
|
144
|
+
`autonoma-planner sdk check --recipe <file>`, which holds the recipe FILE to the format Autonoma
|
|
145
|
+
accepts on upload - the same gate the CLI applies the moment the agent exits, so a rejected recipe
|
|
146
|
+
is a fix the agent makes while it's still running rather than a re-launch afterwards. All of that
|
|
147
|
+
happens on a branch it cuts from your
|
|
83
148
|
repo's default branch, and it pushes the finished integration as a pull request rather than leaving
|
|
84
149
|
the changes loose in your working tree. When it reports the session complete, the CLI uploads
|
|
85
150
|
the recipe it produced and continues to test generation.
|
|
86
151
|
|
|
87
152
|
- `--agent <name>` - preselect the agent to hand off to (`claude` or `codex`). Omit to auto-detect;
|
|
88
|
-
if both are installed you're prompted to pick
|
|
153
|
+
if both are installed you're prompted to pick, and headless - where there is nobody to ask - the
|
|
154
|
+
first is used and named in a warning.
|
|
89
155
|
- `--permission-mode <mode>` - how much autonomy the agent runs with: `default` (approve each
|
|
90
156
|
command), `acceptEdits` (auto-edit files, approve commands), or `bypassPermissions` (fully
|
|
91
157
|
autonomous, the default). Both the agent and the mode you pick are persisted for `--resume`. For
|
|
@@ -116,7 +182,7 @@ Artifacts are written to `~/.autonoma/<project-slug>/`:
|
|
|
116
182
|
```
|
|
117
183
|
|
|
118
184
|
`qa-tests/INDEX.md` is written once, at the end, from the files on disk - so it always matches
|
|
119
|
-
the suite beside it. Alongside the totals it names what the run could
|
|
185
|
+
the suite beside it. Alongside the totals it names what the run could _not_ deliver: features it
|
|
120
186
|
walked without producing a test, and tests the review cycle removed that nothing could put back.
|
|
121
187
|
Both are fixed by re-running the planner.
|
|
122
188
|
|
|
@@ -129,17 +195,50 @@ end of the run, and the setup is then marked complete so the onboarding UI advan
|
|
|
129
195
|
|
|
130
196
|
If the upload credentials are not set, the CLI just leaves the artifacts on disk and skips the upload.
|
|
131
197
|
|
|
198
|
+
## Scenario dry run (when the run started from onboarding)
|
|
199
|
+
|
|
200
|
+
Once the artifacts are up, the CLI proves the whole thing actually works: it picks the preview
|
|
201
|
+
environment carrying your SDK handler (the pull request the platform recognizes as the SDK's, or
|
|
202
|
+
your main preview), waits for it to deploy, asks the handler to describe your data models, then
|
|
203
|
+
provisions and tears down every scenario against it, one at a time.
|
|
204
|
+
|
|
205
|
+
The CLI makes those calls itself rather than asking your coding agent to make them, because on a
|
|
206
|
+
healthy app they need no judgement - only the credentials and the app id the run already holds.
|
|
207
|
+
|
|
208
|
+
Waiting is bounded twice, because "still building" and "no preview at all" are different
|
|
209
|
+
problems. A build gets a generous ceiling (20 minutes - it covers a cold image build). A pull
|
|
210
|
+
request with no preview environment gets a minute, since that state is either a webhook that has
|
|
211
|
+
not caught up yet or a draft pull request that will never get one.
|
|
212
|
+
|
|
213
|
+
**When that does not pass, the run hands it to a coding agent** rather than reporting the
|
|
214
|
+
problem and stopping. Everything that makes it fail needs a look at your repo and a decision -
|
|
215
|
+
the handler's pull request has no preview environment, the handler 404s, a recipe resolves to
|
|
216
|
+
nothing - which is exactly what an API call cannot do. The agent gets the Autonoma MCP and the
|
|
217
|
+
job of making both facts true, and the run ends when Autonoma reports them, not when the agent
|
|
218
|
+
says so. A run whose dry run passed first time spawns nothing.
|
|
219
|
+
|
|
220
|
+
There are two kinds of preview the calls themselves cannot validate - one built by **your own
|
|
221
|
+
pipeline**, signed with a secret that never leaves your side, and a **Vercel** deployment,
|
|
222
|
+
validated against the one you picked in the Autonoma app. Those are handed over the same way.
|
|
223
|
+
|
|
224
|
+
The run closes by reading back what Autonoma makes of your app - test suite uploaded, SDK
|
|
225
|
+
answering, scenarios provisioning, and whether Autonoma is reviewing your pull requests. It
|
|
226
|
+
takes the app live itself once the preview is verified: your coding agent is told to do that,
|
|
227
|
+
but the run stops the agent the moment the preview is confirmed, which is the same moment it
|
|
228
|
+
would have.
|
|
229
|
+
|
|
132
230
|
## Environment variables
|
|
133
231
|
|
|
134
|
-
| Variable
|
|
135
|
-
|
|
136
|
-
| `AUTONOMA_API_TOKEN`
|
|
137
|
-
| `OPENROUTER_MODEL`
|
|
138
|
-
| `AUTONOMA_API_URL`
|
|
139
|
-
| `AUTONOMA_GENERATION_ID`
|
|
140
|
-
| `
|
|
141
|
-
| `
|
|
142
|
-
| `
|
|
232
|
+
| Variable | Required | Purpose |
|
|
233
|
+
| ------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
234
|
+
| `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. |
|
|
235
|
+
| `OPENROUTER_MODEL` | no | Override the default model (OpenRouter-style model id, forwarded by the proxy). |
|
|
236
|
+
| `AUTONOMA_API_URL` | no | Base URL of the Autonoma API. Defaults to `https://autonoma.app`; override to target an alpha/preview host. |
|
|
237
|
+
| `AUTONOMA_GENERATION_ID` | for upload | The setup id artifacts are uploaded against. Injected by onboarding. |
|
|
238
|
+
| `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. |
|
|
239
|
+
| `AUTONOMA_SHARED_SECRET` | no | Per-application secret used to sign SDK/webhook requests. Injected by onboarding. |
|
|
240
|
+
| `AUTONOMA_DISTINCT_ID` | no | PostHog identity so CLI events join the signup funnel. Injected by onboarding. |
|
|
241
|
+
| `DONT_TRACK` | no | Set to `1`/`true` to disable all telemetry - events, log shipping and session replay. |
|
|
143
242
|
|
|
144
243
|
`AUTONOMA_API_TOKEN` + `AUTONOMA_GENERATION_ID` together enable automatic upload (the endpoint
|
|
145
244
|
defaults to production unless `AUTONOMA_API_URL` is set).
|
|
@@ -159,12 +258,12 @@ Three lanes, all to PostHog, all off when `DONT_TRACK=1`:
|
|
|
159
258
|
All three lanes are indexed by the same identifiers (`core/session.ts`), so one run resolves the same
|
|
160
259
|
way from any of them:
|
|
161
260
|
|
|
162
|
-
| Attribute
|
|
163
|
-
|
|
164
|
-
| `run_id` / `sessionId`
|
|
165
|
-
| `generation_id`
|
|
166
|
-
| `posthogDistinctId`
|
|
167
|
-
| `project_slug`, `cli_version`, `node_version` | Which project, which build, which runtime.
|
|
261
|
+
| Attribute | What it identifies |
|
|
262
|
+
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
|
263
|
+
| `run_id` / `sessionId` | This CLI invocation. `sessionId` is PostHog's own grouping key, so a run's logs sit together. |
|
|
264
|
+
| `generation_id` | The onboarding setup the run is fulfilling - the join back to an Autonoma record. |
|
|
265
|
+
| `posthogDistinctId` | The person, when the app launched the CLI with an identity; otherwise an anonymous per-machine device id. |
|
|
266
|
+
| `project_slug`, `cli_version`, `node_version` | Which project, which build, which runtime. |
|
|
168
267
|
|
|
169
268
|
To read one run: filter logs by `service.name = autonoma-planner` and the `generation_id` (or `run_id`)
|
|
170
269
|
you are chasing, ordered earliest-first.
|