@soleone/factory 0.1.0 → 0.2.1

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 CHANGED
@@ -1,50 +1,76 @@
1
1
  # factory
2
2
 
3
- Runs your coding agents overnight. Say `factory start` before bed: it takes the candidates [workwork](https://github.com/Soleone/workwork) finds across your repos, cheapest human attention first, and hands them one at a time to headless `claude` and `pi`, each in a fresh git worktree, until their usage limits run out or the clock says stop. In the morning `factory report` lists what each agent did, with the PR or issue it opened.
3
+ Works a queue of coding tasks with headless `claude` and `pi`, until their usage limits run out. You pick tasks from what [workwork](https://github.com/Soleone/workwork) finds across your repos, or let auto mode keep the queue topped up. In the morning, the results list what each agent did, with the PR or issue it opened.
4
4
 
5
5
  ```sh
6
6
  npm install -g @soleone/factory
7
+ factory serve # http://127.0.0.1:7040
7
8
  ```
8
9
 
9
- Needs node 22+, git, [workwork](https://github.com/Soleone/workwork) 0.2+ (for `--json`), and whichever of `claude` and `pi` you use, logged in.
10
+ Needs node 22+, git, [workwork](https://github.com/Soleone/workwork) with `--json` support, and whichever of `claude` and `pi` you use, logged in.
10
11
 
11
- ```sh
12
- factory start [--until 08:00] [--windows 2] [--agents claude,pi] [--levels auto,skim,decide] [--max-items N]
13
- factory run [same flags] # the same loop in the foreground; start = run, detached
14
- factory status # running or not, what each worker is doing, counts
15
- factory stop # stops the loop and its agents; unfinished items go back in the queue
16
- factory report [--all] # the last run (or every run): outcome, agent, item, PR/issue link or log
17
- ```
12
+ ## How it works
13
+
14
+ - **Repos** are yours on GitHub, cloned under `$SRC`, which is where workwork looks. The folder button right of the tabs lists the ones you haven't cloned yet, newest first, and clones one into a folder of `$SRC` you pick.
15
+ - **Jobs** are workwork candidates in the queue. Your picks always go first, in the order you give them; auto jobs follow. A job can name its agent, model and effort. Once an agent has started a job, the job stays with that agent.
16
+ - **Auto mode** only fills the queue: while the factory is on, it keeps up to 5 of its jobs per agent queued, cheapest attention first, with repos taking turns. It never re-queues a candidate that already had a job. You can limit it to some levels and plays.
17
+ - **The factory** is what works the queue, one worker per agent. With nothing to do it waits, and it picks up new jobs within seconds. Turning it on starts a **run** with its own agents, models, efforts, limit and end time, defaulting to the settings.
18
+ - **Limits:** a limit of 1 (the default) stops an agent at its first usage-limit hit, so only the current allowance gets used. A limit of 2 waits for one reset and stops at the second hit. "None" always waits for the reset, which it logs. Once every agent has stopped, the factory turns itself off. Three quick failures in a row also count as a limit hit, so a broken login can't burn through the queue.
19
+ - **Failures:** a failed or timed-out job gets one more try by the same agent. After that it waits for you to retry it.
20
+ - **Agents report back** through the CLI, which factory names in each prompt: `note` for what's worth knowing later, `result` for a summary with a confidence, follow-up tasks and the PR link, and `ask` for the rare decision only you can make; the prompt tells agents to decide everything else themselves and note the call. A job whose agent asked waits for your answer, on the page or with `factory answer`. Then it goes back in the queue, and the next attempt gets the earlier notes, your answer and the branch with the earlier work. Retries get the same.
21
+ - **Jobs can wait on each other:** `--after <job>` holds one until the other is done, and drops it if the other fails or is removed (a retry brings it back). **Review with** queues a review of a job's PR by another agent, which posts its findings as a PR comment.
18
22
 
19
- Also `--timeout MIN` (default 60) per item, and `--claude-model` / `--pi-model`, passed through as `--model`. There is no config file.
23
+ ## Reviewing results
20
24
 
21
- ## How a night goes
25
+ Results waiting for your answer come first under **Waiting for you**; a dot marks those that ended since you last looked. **Activity** lists everything that happened, newest first, with what the agents said. The tab, filter and an opened job stay in the URL, so a link opens the same view.
22
26
 
23
- One worker per agent, all taking from one queue that a single process hands out, so two agents never get the same item. The queue is `workwork --all --json`, minus what the ledger says is done, auto before skim before decide, taking turns between repos so one repo doesn't take the night. When it runs dry it asks workwork again; when workwork has nothing new, the run ends.
27
+ Each result links the PR or issue the agent opened. From the page you can read a PR's description and diff, merge it, rebase it onto its base when GitHub reports conflicts, or close it. Rebasing never guesses: if git stops on a conflict, nothing is pushed and the page lists the files.
24
28
 
25
- For each item: `git fetch`, `git worktree add --detach` at `origin/HEAD` (your checkout is never touched), `workwork prompt <id>` on the agent's stdin, output to `agent.log`. The agent runs in its own process group and is killed with everything it started after `--timeout`. A worktree with commits that aren't on a remote, or with uncommitted changes, is kept and the report says where; otherwise it's removed.
29
+ **Merge train:** select several results and merge them in one go. PRs merge one after another per repo, since each merge moves the base under the next one; repos go in parallel. The train waits for checks, rebases a PR that conflicts, and skips one it can't merge, with the reason. What it did with each PR shows on the job and in Activity. When a rebase stops on real conflicts, a job to resolve them goes to the front of the queue, so an agent picks it up on the next run.
26
30
 
27
- A failed or timed-out item gets one more try, by the other agent. After two failures it's skipped for good.
31
+ ## Live Agent
28
32
 
29
- ## Limits and windows
33
+ 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.
30
34
 
31
- When an agent hits its usage limit, the item goes back to the front of the queue and that worker sleeps until the reset time in the message, plus 2 minutes (30 minutes when the message doesn't say). After its `--windows`th limit (default 2: the current 5-hour window and the next one) the worker stops. The run ends when every worker has stopped, `--until` has passed (nothing new starts after it), or `--max-items` have started.
35
+ Settings > Live Agent picks the agent (Claude Code or Pi), its model and effort. The same model and effort pickers serve runs. Model choices are short lists: Pi's scoped models (`enabledModels` in Pi's settings, the ones Ctrl+P cycles through), and Claude Code's current models (opus, sonnet, fable, haiku). The efforts on offer are the chosen model's. When one of Pi's extensions asks something mid-chat, the page shows the question. The chat survives a restart of `factory serve`: the page shows it again and the agent resumes its own session, so it still knows what was said. New chat starts over.
32
36
 
33
- The limit messages are the ones the tools really print: Claude Code's `You've hit your session limit · resets 3pm (Europe/Berlin)` (and weekly, Opus, Sonnet, spend limits, with or without a date) and the older `Claude AI usage limit reached|<epoch>`; pi's `You have hit your ChatGPT usage limit (plus plan). Try again in ~42 min.` and the raw `usage_limit_reached` / `resets_in_seconds`. Three failures in a row that each took under a minute count as a limit too, so a broken login or a message nobody has seen yet can't burn through the queue.
37
+ ## Commands
34
38
 
35
- `--until` and resets without a time zone use the machine's local time; set `TZ` if that isn't yours.
39
+ The page and the CLI do the same things on the same state; `serve` is only an interface, and the factory runs without it.
40
+
41
+ ```sh
42
+ factory start [run options] # turn on, in the background (factory run: in the foreground)
43
+ factory stop # turn off; jobs in progress go back to the queue
44
+ factory status # on or off, what each agent does, the queue
45
+ factory add <id>... [--repo DIR] [--agent NAME] [--model M] [--effort E] [--after JOB]
46
+ factory remove <job> | retry <job> | answer <job> "<text>"
47
+ factory review <job> --agent pi # another agent reviews the job's PR once it's done
48
+ factory wait <job> [--timeout MIN] # block until it's done, failed or waiting for you
49
+ factory tail # follow every job event, one line each
50
+ factory auto on|off
51
+ factory report [--all] # the last run (or every run): outcome, agent, PR/issue link or log
52
+ factory serve [--port 7040] [--host 127.0.0.1]
53
+ ```
54
+
55
+ Run options: `--agents claude,pi`, `--limit N|none`, `--until HH:MM` (start nothing new after), `--model claude=opus`, `--effort pi=high` (claude's `--effort`, pi's `--thinking`), `--timeout MIN`.
56
+
57
+ `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
+
59
+ ## Worktrees
60
+
61
+ Each agent gets one worktree per repo, under the state folder, reused from job to job so installed dependencies survive. Before every job it's reset to a freshly fetched `origin/HEAD`, and untracked files are removed but ignored ones are kept. Your own checkout is never touched. If an agent leaves commits that aren't on a remote, or uncommitted changes, they're saved to a branch `factory/<job>-<attempt>` in the repo, and the result says so.
36
62
 
37
63
  ## State
38
64
 
39
65
  In `$DATA/apps/factory/` when `DATA` is set, otherwise `~/.local/share/factory/`:
40
66
 
41
- - `ledger.jsonl`: one line per finished attempt, `{run, id, repo, play, level, agent, start, end, outcome, url?, log, worktree?, error?}`; outcome is `done`, `failed`, `limited` or `timeout`
42
- - `runs/<run>/<item>/`: `prompt.md` and `agent.log`
43
- - `worktrees/<run>/<item>/`: kept worktrees
44
- - `factory.pid`, `factory.log`: the running loop and its output
45
- - `status.json`: rewritten on every change, read by `factory status`
46
-
47
- An item that was running when the loop stopped has no ledger line, so the next run takes it again.
67
+ - `settings.json`: registered agents with their model and effort, the agent Live Agent uses, limit, until, timeout, auto mode (on, levels, plays, repos)
68
+ - `jobs.jsonl`: append-only events (add, remove, move, start, attempt, requeue, retry), so the CLI, the factory and the page never overwrite each other
69
+ - `candidates.json`: the cached `workwork --all --json`, which takes minutes; refreshed from the page, or by auto mode when older than 6 hours
70
+ - `runs/<run>/<job>-<attempt>/`: `prompt.md` and `agent.log`
71
+ - `chat.json`, `chat.jsonl`, `chat-sessions/`: the Live Agent session, what the page shows, and Pi's session files (Claude Code keeps its own)
72
+ - `worktrees/<agent>/<repo>/`
73
+ - `status.json`, `factory.pid`, `factory.log`: the current run
48
74
 
49
75
  ## Why not an LLM loop
50
76
 
@@ -54,10 +80,29 @@ This replaces an assistant that ran the night from inside chat turns. It stopped
54
80
 
55
81
  ```sh
56
82
  pnpm install
57
- vp check && vp test run && pnpm exec knip
58
- pnpm release # tag, changelog, npm publish
83
+ pn dev
84
+ vp check && vp test run && kit check
59
85
  ```
60
86
 
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/`.
88
+
89
+ ### Try the UI with dummy data
90
+
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.
92
+
93
+ 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
+
95
+ ### Release
96
+
97
+ From `main` with a clean working tree, authenticated Git push access, and pnpm logged in to npm (`pn whoami`):
98
+
99
+ ```sh
100
+ pn release # choose patch, minor or major, then confirm each step
101
+ pn release --dry-run # preview without changing files, publishing or pushing
102
+ ```
103
+
104
+ With Vite+, `pn` is shorthand for `pnpm`. The release command asks for the version, updates `CHANGELOG.md` from conventional commits, commits and tags `vX.Y.Z`, and pushes. Factory publishes `@soleone/factory` to npm locally rather than building native apps in Actions. Checks and tests run before releasing; `prepublishOnly` builds the CLI before publishing. Dry runs skip these hooks, so run the development checks above separately.
105
+
61
106
  ## License
62
107
 
63
108
  MIT