@soleone/factory 0.2.2 → 0.3.0
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 +104 -34
- package/dist/cli.mjs +9401 -470
- package/dist/web/assets/index-C8Ojugvg.css +2 -0
- package/dist/web/assets/index-Defxavgr.js +80 -0
- package/dist/web/index.html +2 -2
- package/package.json +4 -3
- package/dist/web/assets/index-1ZYZbwXO.js +0 -80
- package/dist/web/assets/index-BYLnECQ_.css +0 -2
package/README.md
CHANGED
|
@@ -1,38 +1,70 @@
|
|
|
1
1
|
# factory
|
|
2
2
|
|
|
3
|
-
Works
|
|
3
|
+
Works coding tasks with headless `claude` and `pi`, until their usage limits run out. Two modes share one queue:
|
|
4
|
+
|
|
5
|
+
- **Maintenance:** small independent jobs from what [workwork](https://github.com/Soleone/workwork) finds across your repos. You pick them, or auto mode keeps the queue topped up overnight. In the morning, the results list what each agent did, with the PR it opened.
|
|
6
|
+
- **Goals:** one large task, split into a graph of jobs that run in dependency order, several at once where they don't touch the same files, each building on the last, across usage resets. Every job merges into the goal's own integration branch; the final PR into main is yours to merge.
|
|
4
7
|
|
|
5
8
|
```sh
|
|
6
9
|
npm install -g @soleone/factory
|
|
7
10
|
factory serve # http://127.0.0.1:7040
|
|
8
11
|
```
|
|
9
12
|
|
|
10
|
-
Needs node 22+, git, [workwork](https://github.com/Soleone/workwork) with `--json` support, and whichever of `claude` and `pi` you use, logged in.
|
|
13
|
+
Needs node 22+, git, [workwork](https://github.com/Soleone/workwork) with `--json` support, `gh`, and whichever of `claude` and `pi` you use, logged in.
|
|
11
14
|
|
|
12
15
|
## How it works
|
|
13
16
|
|
|
14
|
-
- **
|
|
15
|
-
- **
|
|
16
|
-
- **
|
|
17
|
-
- **
|
|
18
|
-
- **
|
|
19
|
-
- **
|
|
20
|
-
- **
|
|
21
|
-
- **
|
|
17
|
+
- **Jobs** are what the agents work. A model only ever does one job, as a child process that exits. Scheduling, checks, merges, limits and retries are plain code.
|
|
18
|
+
- **Sessions:** an attempt at a job is one agent session. Factory talks to it as often as it needs: when the agent stops without reporting a result, or one of the job's checks (gates) fails, it sends up to two follow-ups in the same session, quoting how the run ended or what failed. After an answered question, a usage reset or a restart it resumes the session. Only a new attempt starts fresh, with the earlier attempts' notes and kept work.
|
|
19
|
+
- **Live:** both runners stream JSON events, so the page shows each worker's current tool call ("editing src/sidebar.rs") and context size without the agent's help, and agents report steps in their own words. An attempt times out only after `idle` minutes (default 10) without a sign of life; a long run that keeps working is never cut off.
|
|
20
|
+
- **Tiers:** a job can ask for `communicator` (taste and writing: decomposition, UX, copy), `builder` (architecture, tricky logic, reviews) or `grunt` (well-specified mechanical work). Settings list each tier's presets in order; a job runs on the first one whose usage limit isn't hit and has a free worker. A job that fails twice moves up a tier.
|
|
21
|
+
- **Pools and workers:** a pool is one account's usage limit (claude, or pi's provider). Each preset can run several workers; a limit hit pauses every worker of the pool until the reset. More workers on one pool spend its allowance sooner; the gain is across pools.
|
|
22
|
+
- **Compaction:** each preset compacts its context at `compactAt` tokens (200k, 90k for Haiku, below their price steps). Claude Code gets `--autocompact`; pi reads it from its own settings, so factory checks those at start-up and prints what to add if they don't match.
|
|
23
|
+
- **Worktrees:** a pool of worktrees per repo, under the state folder, reused from job to job so installed dependencies survive. A job's worktree stays with it while it waits for an answer. Before a new job it's reset; untracked files go, ignored ones stay. Commits or changes an agent leaves unpushed are saved to `factory/<job>-<attempt>`. Your own checkout is never touched.
|
|
24
|
+
- **Touches:** jobs that say which files they change (globs) never run at the same time as another job that may change the same ones.
|
|
25
|
+
|
|
26
|
+
### Maintenance
|
|
27
|
+
|
|
28
|
+
- Picks go first, in the order you give them; auto jobs follow. While the factory is on, auto mode keeps up to 5 of its jobs per worker queued, cheapest attention first, with repos taking turns, and never re-queues a candidate that already had a job.
|
|
29
|
+
- **Limits:** a limit of 1 (the default) stops a pool at its first usage-limit hit, so only the current allowance gets used. A limit of 2 waits for one reset; "none" always waits. Three quick failures in a row stop a worker, so a broken login can't burn through the queue.
|
|
30
|
+
- **Failures:** a job that fails gets one more attempt; then it waits for you to retry it, and jobs that wait on it are held until then.
|
|
31
|
+
- **Reviewing results:** each result links its PR. From the page you can read its description and diff, merge it, rebase it, or close it, and put several on the **merge train**, which merges them one after another per repo, rebasing as it goes. A rebase that stops on real conflicts queues a job to resolve them.
|
|
22
32
|
|
|
23
|
-
|
|
33
|
+
### Goals
|
|
34
|
+
|
|
35
|
+
```sh
|
|
36
|
+
factory goal new "GPUI client for Tasks" --repo ~/src/tasks --brief brief.md
|
|
37
|
+
factory goal show gpui-client # the graph before anything runs: tiers, critical path, estimate
|
|
38
|
+
factory goal approve gpui-client
|
|
39
|
+
```
|
|
24
40
|
|
|
25
|
-
|
|
41
|
+
- **Planning:** `goal new` queues a communicator to decompose the goal into a plan, which factory validates and imports, then waits for your approval. `goal import plan.json` takes a plan you wrote, with someone or something else; [spec/plan-format.md](spec/plan-format.md) describes the format (JSON or YAML) and `goal check` validates one.
|
|
42
|
+
- **Branches:** the goal gets `goal/<slug>` on origin. Each node works on `node/<slug>/<key>`, started from the integration branch's head; it commits and pushes but never opens a PR. Factory runs its gates, rebases it onto the integration branch, opens the PR and merges it, then runs the goal's own gates. A conflict queues a job to resolve it; a red integration branch pauses the goal and queues a fix.
|
|
43
|
+
- **Memory:** `.factory/<slug>.md` on the integration branch holds the goal's summary and the decisions each node leaves for the next. Prompts carry the goal summary, what a node's dependencies delivered, and a pointer to the memory.
|
|
44
|
+
- **Checkpoints:** a node can pause the goal for your approval once it's merged, and so does an attempt budget when it runs out (approving adds the same again). At each milestone (a node with children, done) factory rebases the integration branch onto main and queues a replan; a node that fails for good queues one too. A replan may change only what hasn't started, and one that changes more than a quarter of it waits for you.
|
|
45
|
+
- **Reviews:** a node can ask for a review by another tier before it merges; findings become a fix on its branch.
|
|
46
|
+
- **Needs:** a node that needs something no worker has (`display`, `gpu`, an emulator) still runs, verifies what it can, and lands on the unverified checklist for you.
|
|
47
|
+
- **In Tasks:** with `"store": "tasks"` and `"tasks": { "home": "..." }` in settings, goals and their nodes also show in a Tasks home, kept in step every few seconds. Canceling one there, editing a node that hasn't started, or adding a subtask under a goal (tag it #grunt, #builder or #communicator) comes back to factory.
|
|
26
48
|
|
|
27
|
-
|
|
49
|
+
## Agents report back
|
|
28
50
|
|
|
29
|
-
|
|
51
|
+
Through the CLI, which factory names in each prompt (the job is `$FACTORY_JOB`):
|
|
52
|
+
|
|
53
|
+
```sh
|
|
54
|
+
factory step "<what you're doing>" [--done N --of M] # progress; the page shows the latest
|
|
55
|
+
factory note "<text>" # worth knowing later
|
|
56
|
+
factory ask "<question>" --assume "<default>" # carry on with the default; you answer later
|
|
57
|
+
factory ask "<question>" # the job waits for your answer
|
|
58
|
+
factory result "<summary>" --confidence high --url LINK --followup "<task>" --unverified "<what>"
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
The prompt tells agents to decide what a reasonable engineer would and note the call. An assumption you answer with "fine" closes; any other answer queues a job to change it. A plain question pauses the job until you answer, on the page or with `factory answer`, and the same session picks up from there. `factory report` ends with what waits on you: unverified work and assumptions to confirm.
|
|
30
62
|
|
|
31
63
|
## Live Agent
|
|
32
64
|
|
|
33
65
|
Live Agent, the robot button right of the tabs, is a chat with an agent about what to queue. It reads the candidates, the queue and past results, proposes a few jobs that won't step on each other, and adds them through the CLI once you agree. It never turns the factory on, merges or closes PRs, or changes your repos. That is an instruction to the agent, not a sandbox: it has a shell, like the agents doing jobs. Results that failed, or that the train skipped, have an **Ask** button that starts the chat with the question already written.
|
|
34
66
|
|
|
35
|
-
Settings > Live Agent picks the agent (Claude Code or Pi), its model and effort.
|
|
67
|
+
Settings > Live Agent picks the agent (Claude Code or Pi), its model and effort. Model choices are short lists: Pi's scoped models (`enabledModels` in Pi's settings) and Claude Code's current models. The chat survives a restart of `factory serve`.
|
|
36
68
|
|
|
37
69
|
## Commands
|
|
38
70
|
|
|
@@ -40,41 +72,79 @@ The page and the CLI do the same things on the same state; `serve` is only an in
|
|
|
40
72
|
|
|
41
73
|
```sh
|
|
42
74
|
factory start [run options] # turn on, in the background (factory run: in the foreground)
|
|
43
|
-
factory stop
|
|
44
|
-
factory status # on or off,
|
|
45
|
-
factory add <id>... [--repo DIR] [--agent NAME] [--model M] [--effort E] [--after JOB]
|
|
46
|
-
factory
|
|
75
|
+
factory stop [--kill] # turn off; agents at work finish their turn, the next start records it
|
|
76
|
+
factory status # on or off, each pool and its workers, the queue
|
|
77
|
+
factory add <id>... [--repo DIR] [--agent NAME] [--model M] [--effort E] [--after JOB]...
|
|
78
|
+
factory add --prompt FILE --tier grunt [--repo DIR] # a job of your own, without workwork
|
|
79
|
+
factory remove <job> | retry <job> | answer <job> "<text>" | verify <job> [NEED]
|
|
47
80
|
factory review <job> --agent pi # another agent reviews the job's PR once it's done
|
|
48
|
-
factory wait <job> [--timeout MIN]
|
|
81
|
+
factory wait <job> [--timeout MIN]
|
|
49
82
|
factory tail # follow every job event, one line each
|
|
50
83
|
factory auto on|off
|
|
51
|
-
factory report [--all]
|
|
84
|
+
factory report [--all] # the last run (or every run), then what waits on you
|
|
85
|
+
factory goal new|import|check|show|approve|pause|resume|cancel|replan ...
|
|
52
86
|
factory serve [--port 7040] [--host 127.0.0.1]
|
|
53
87
|
```
|
|
54
88
|
|
|
55
|
-
Run options: `--agents claude,pi
|
|
89
|
+
Run options: `--agents claude,pi` (a worker each, for jobs without a tier), `--limit N|none` (per pool), `--until HH:MM` (start nothing new after), `--model claude=opus`, `--effort pi=high` (claude's `--effort`, pi's `--thinking`), `--idle MIN`.
|
|
56
90
|
|
|
57
91
|
`serve` listens on 127.0.0.1. Anyone who can reach it can queue jobs and turn the factory on, and the agents run with full permissions, so it amounts to running commands on your machine. Reach it from a phone through something like `tailscale serve`, not with `--host 0.0.0.0` on a network you don't trust.
|
|
58
92
|
|
|
59
|
-
##
|
|
93
|
+
## Settings
|
|
94
|
+
|
|
95
|
+
`settings.json` in the state folder, also edited from the page:
|
|
96
|
+
|
|
97
|
+
```json
|
|
98
|
+
{
|
|
99
|
+
"agents": { "claude": {}, "pi": {} },
|
|
100
|
+
"presets": [
|
|
101
|
+
{ "id": "opus", "agent": "claude", "model": "opus", "effort": "high" },
|
|
102
|
+
{
|
|
103
|
+
"id": "sol",
|
|
104
|
+
"agent": "pi",
|
|
105
|
+
"model": "openai-codex/gpt-6.2-sol",
|
|
106
|
+
"effort": "high",
|
|
107
|
+
"workers": 2
|
|
108
|
+
},
|
|
109
|
+
{
|
|
110
|
+
"id": "luna",
|
|
111
|
+
"agent": "pi",
|
|
112
|
+
"model": "openai-codex/gpt-6-luna",
|
|
113
|
+
"effort": "max",
|
|
114
|
+
"workers": 3
|
|
115
|
+
},
|
|
116
|
+
{ "id": "haiku", "agent": "claude", "model": "haiku", "workers": 2 }
|
|
117
|
+
],
|
|
118
|
+
"tiers": { "communicator": ["opus"], "builder": ["sol", "opus"], "grunt": ["luna", "haiku"] },
|
|
119
|
+
"limit": 1,
|
|
120
|
+
"idle": 10,
|
|
121
|
+
"capabilities": ["display"],
|
|
122
|
+
"env": {
|
|
123
|
+
"/home/me/src/tasks": { "RUSTC_WRAPPER": "sccache", "CARGO_TARGET_DIR": "{worktree}/target" }
|
|
124
|
+
},
|
|
125
|
+
"store": "local"
|
|
126
|
+
}
|
|
127
|
+
```
|
|
60
128
|
|
|
61
|
-
|
|
129
|
+
A preset may also set `pool` (default: claude, or pi's provider), `compactAt` and `followups` (default 2). `env` applies per repo to agents and gates; `{worktree}` becomes the worktree's path. A tier without presets runs on the run's agents.
|
|
62
130
|
|
|
63
131
|
## State
|
|
64
132
|
|
|
65
133
|
In `$DATA/apps/factory/` when `DATA` is set, otherwise `~/.local/share/factory/`:
|
|
66
134
|
|
|
67
|
-
- `settings.json
|
|
68
|
-
- `jobs.jsonl`: append-only events
|
|
69
|
-
- `candidates.json`: the cached `workwork --all --json`,
|
|
70
|
-
- `runs/<run>/<job>-<attempt>/`: `prompt.md` and `agent.log`
|
|
71
|
-
- `
|
|
72
|
-
- `
|
|
73
|
-
- `
|
|
135
|
+
- `settings.json`
|
|
136
|
+
- `jobs.jsonl`: append-only events, so the CLI, the factory and the page never overwrite each other; the queue, goals and results are what replaying it gives
|
|
137
|
+
- `candidates.json`: the cached `workwork --all --json`, refreshed from the page, or by auto mode when older than 6 hours
|
|
138
|
+
- `runs/<run>/<job>-<attempt>/`: `prompt.md`, `turn-N.md` for each later turn, and `agent.log` with the runner's event stream
|
|
139
|
+
- `running/<job>.json`: an attempt in progress or paused: its session, worktree and turn
|
|
140
|
+
- `sessions/`: pi's session files for job attempts (Claude Code keeps its own)
|
|
141
|
+
- `chat.json`, `chat.jsonl`, `chat-sessions/`: the Live Agent
|
|
142
|
+
- `worktrees/<repo>/<n>/`
|
|
143
|
+
- `status.json`, `factory.pid`, `factory.log`: the current run, its pools and workers
|
|
74
144
|
|
|
75
145
|
## Why not an LLM loop
|
|
76
146
|
|
|
77
|
-
This replaces an assistant that ran the night from inside chat turns. It stopped whenever a turn ended, built its own queue, guards and "authorization" out of prompts, then got blocked by them, and rewrote its own instructions after every failure. The tasks themselves went fine. So here the loop is plain code, and a model only ever does one task, as a child process that exits. Nothing a model says decides what runs next,
|
|
147
|
+
This replaces an assistant that ran the night from inside chat turns. It stopped whenever a turn ended, built its own queue, guards and "authorization" out of prompts, then got blocked by them, and rewrote its own instructions after every failure. The tasks themselves went fine. So here the loop is plain code, and a model only ever does one task, as a child process that exits. Nothing a model says decides what runs next, except through a plan that code validates.
|
|
78
148
|
|
|
79
149
|
## Development
|
|
80
150
|
|
|
@@ -84,11 +154,11 @@ pn dev
|
|
|
84
154
|
vp check && vp test run && kit check
|
|
85
155
|
```
|
|
86
156
|
|
|
87
|
-
The page is built on the [kit](https://github.com/Soleone/kit) web stack: Vite+, React, shadcn base-nova and the @soleone theme. `src/backend/` holds the CLI, the factory and the server; `src/` the page. `pn dev` runs Vite with hot reload at http://localhost:7040 in front of `factory serve` on 7041, which restarts when `src/backend/` changes. It uses your real state folder, so Turn on starts real agents. `pn build` bundles the CLI to `dist/cli.mjs` and the page to `dist/web/`.
|
|
157
|
+
The page is built on the [kit](https://github.com/Soleone/kit) web stack: Vite+, React, shadcn base-nova and the @soleone theme. `src/backend/` holds the CLI, the factory and the server; `src/` the page. `pn dev` runs Vite with hot reload at http://localhost:7040 in front of `factory serve` on 7041, which restarts when `src/backend/` changes. It uses your real state folder, so Turn on starts real agents. `pn build` bundles the CLI to `dist/cli.mjs` and the page to `dist/web/`. The Tasks store test runs against Tasks' own checkout (`$SRC/products/tasks/bin/tasks-cli`, or `TASKS_CLI`) and is skipped without it.
|
|
88
158
|
|
|
89
159
|
### Try the UI with dummy data
|
|
90
160
|
|
|
91
|
-
Run `pnpm dev:demo` and open [factory (demo)](http://localhost:7042). Browse sample candidates, reorder the queue, retry a failed job, review sample PRs, or try the run and settings controls. Turn on shows simulated workers without executing any jobs.
|
|
161
|
+
Run `pnpm dev:demo` and open [factory (demo)](http://localhost:7042). Browse sample candidates, reorder the queue, retry a failed job, review sample PRs, open the sample goal's graph, or try the run and settings controls. Turn on shows simulated workers without executing any jobs.
|
|
92
162
|
|
|
93
163
|
The demo does not start `factory serve`, call `workwork` or GitHub, or read or write your real Factory state. Changes are shared across tabs and reset when you restart the demo server.
|
|
94
164
|
|