Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
41 commits
Select commit Hold shift + click to select a range
0c7ebbc
Add a Postgres event log with projections
jacobprall Nov 17, 2026
f81b630
Share the Workflows database pool with tasks
jacobprall Nov 17, 2026
2d4cf70
Name event subjects in one place
jacobprall Nov 17, 2026
0e5b8fe
Record agent runs in the event log and stream them live
jacobprall Nov 17, 2026
d94f2cb
Coordinate runs on Postgres instead of the status comment
jacobprall Nov 17, 2026
25665fd
Keep an agent run's outcome when a failed write meets a full queue
jacobprall Nov 17, 2026
9363b91
Merge live agent events (plan 05)
jacobprall Nov 17, 2026
442ab8d
Relay agent runs live from the Sandbox through the host
jacobprall Nov 17, 2026
6e2681b
Run agents on Pi 1.5.2 through createAgentSession
jacobprall Nov 17, 2026
ba273d1
Describe the factory as it is: event log, live streams, and Pi in the…
jacobprall Nov 17, 2026
9c6cac1
Key events by channel thread instead of GitHub subject
jacobprall Nov 17, 2026
6efdf75
Link factory-db to Workflows through its env group after the Blueprint
jacobprall Nov 17, 2026
4f282e7
Keep webhook delivery IDs exact in doctor
jacobprall Nov 17, 2026
9db85ed
State the factory's design principles in the architecture doc
jacobprall Nov 17, 2026
1e86f05
Say thread in the design principles
jacobprall Nov 17, 2026
b9c76b4
Clip agent run events by JSON-encoded bytes
jacobprall Nov 17, 2026
8fbc650
Reword the thread ownership principle
jacobprall Nov 17, 2026
4f9cfe5
Coordinate runs by starting them on their thread
jacobprall Nov 17, 2026
6d35311
Fix unsafe optional chaining in recorder tests
jacobprall Nov 17, 2026
d12eba6
Decide what deliveries mean from Postgres, not GitHub labels
jacobprall Nov 17, 2026
64367f9
Keep agent run relay offsets exact and follow runs that haven't started
jacobprall Nov 17, 2026
97ef5e5
Speed up blob uploads and Sandbox calls; clarify shell policy and SSE…
jacobprall Nov 17, 2026
e98817e
Enforce module barrels, verify webhook HMAC over raw bytes, share hel…
jacobprall Nov 17, 2026
68cc2a6
Split modules that mixed definitions with host machinery
jacobprall Nov 18, 2026
19c371c
Cut implementation-detail tests from setup script and GitHub suites
jacobprall Nov 18, 2026
ca53dca
Cut implementation-detail tests from workflow and run suites
jacobprall Nov 18, 2026
298f6af
Cut implementation-detail tests from gateway, store, and format suites
jacobprall Nov 18, 2026
b7fec74
Cut implementation-detail tests from sandbox and runner suites
jacobprall Nov 18, 2026
ba8d44b
Share one fake fetch across setup script and GitHub client tests
jacobprall Nov 18, 2026
d61ea83
Share one set of GitHub, sandbox, and agent fakes across workflow tests
jacobprall Nov 18, 2026
9aa57ac
Strip comments from the codebase
jacobprall Nov 18, 2026
69c9ed5
Ask agents not to write code comments
jacobprall Nov 18, 2026
08e590a
update documentation
jacobprall Nov 18, 2026
7e6b868
Strip comments from the root config files
jacobprall Nov 18, 2026
2be1550
Recover submissions a model mangles with tool-call markup
jacobprall Nov 18, 2026
988729a
Cancel a displaced root that is paused on its child
jacobprall Nov 18, 2026
28bf0a1
Explain the architecture, labels, and channels in the README
jacobprall Nov 18, 2026
3b09e42
Give every pull request its own thread
jacobprall Nov 18, 2026
6faaa01
Ship the event log schema as one migration
jacobprall Nov 18, 2026
dbf16b7
Restructure the README around how the factory works and how to deploy it
jacobprall Nov 19, 2026
1ab2232
Restore the template framing and a security section in the README
jacobprall Nov 19, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,17 @@

# Both services: Render API key (the gateway starts tasks; workflows manage sandboxes and cancel runs).
RENDER_API_KEY=
# Both services: Postgres. On Render, the Blueprint links factory-db to the gateway and
# `npm run setup:render -- --link-database` gives Workflows the same URL; locally, use a local Postgres or
# factory-db's external URL with ?sslmode=verify-full. See docs/configuration.md#database.
DATABASE_URL=

# Gateway.
PORT=3000
# Secret configured on the GitHub App's webhook.
GITHUB_WEBHOOK_SECRET=
# Bearer token for the gateway's event streams. setup:render generates one when this is empty.
EVENTS_READ_TOKEN=
# Slug of the factory-workflows service; tasks start as <slug>/<task>.
RENDER_WORKFLOW_SLUG=factory-workflows

Expand Down
15 changes: 15 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,21 @@ jobs:
check:
runs-on: ubuntu-latest
timeout-minutes: 15
# Tests that need concurrent transactions run against this; PGlite runs one transaction at a time.
services:
postgres:
image: postgres:17
env:
POSTGRES_PASSWORD: postgres
ports:
- 5432:5432
options: >-
--health-cmd pg_isready
--health-interval 5s
--health-timeout 5s
--health-retries 10
env:
TEST_DATABASE_URL: postgresql://postgres:postgres@localhost:5432/postgres
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
Expand Down
51 changes: 35 additions & 16 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,21 +29,35 @@ software-factory deploys two processes:
- `app/entrypoints/workflows.ts` registers and runs tasks.

Agents run inside Render Sandboxes. Only code in the Workflows service writes
to GitHub. GitHub and Render Workflows hold application state; there is no
database.
to GitHub. Postgres holds factory state as an append-only event log
(`app/db/`), including which run owns each thread (a GitHub issue or pull
request, keyed `github:owner/name#issue-12`); only the two services connect to
it, and both apply its migrations at startup. GitHub holds
issues, specifications, pull requests, and reviews, and Render Workflows holds
task execution. The status comment is a view and is never read back.

Postgres, not GitHub labels, decides what a delivery means. Trigger labels are
commands, removed when their run starts. A comment resumes an issue only while
its latest root run finished waiting for a reply. Every issue and pull request
is its own thread; Autopilot starts PR Reviewer as a separate run on the draft
pull request it opens.

Two dependency rules are mandatory:

1. The Sandbox runner bundle (`app/runner/`, `app/harness/`, the agent
definitions in `app/agents/registry.ts`, and `app/schemas/`) imports no
host-only code: GitHub, Sandboxes, Workflows, claims, events, or config.
`tests/agents-catalog.test.ts` enforces it.
definitions in `app/agents/`, `app/schemas/`, and `app/util/`)
imports no host-only code: GitHub, Sandboxes, Workflows, runs, events, the
database, config, `app/agent-runs/` (running an agent from the host), or
`app/runner-bundle/` (building the bundle). `tests/agents-catalog.test.ts`
enforces it.
2. `app/gateway/` does not import GitHub authentication, Sandboxes, agents, or
workflows. The gateway holds no GitHub credential and runs no model.
workflows. The gateway holds no GitHub credential and runs no model. It
builds thread keys with the dependency-free `app/threads/`.

Read the canonical
[security invariants](docs/architecture.md#security-invariants) before
changing credentials, claims, Sandboxes, publishing, or GitHub writes.
changing credentials, run coordination, Sandboxes, publishing, or GitHub
writes.

## Code conventions

Expand All @@ -56,16 +70,17 @@ changing credentials, claims, Sandboxes, publishing, or GitHub writes.
- Build agent output objects with `z.strictObject`. Bound strings and arrays.
- Keep task inputs and results small and JSON-serializable.
- Open Sandboxes through `withSandbox`. In GitHub tasks, call
`claim.trackSandbox()` immediately after opening one.
`run.trackSandbox()` immediately after opening one.
- Use `ExpectedFailure` only for expected messages safe to publish on GitHub.
Keep outcome names in snake_case.
- Quote generated shell arguments with `shq`. Put long or
security-sensitive Sandbox commands in `sandbox/` scripts.
- Pass model text through `app/format/` before writing it to GitHub.
- Inject GitHub, Sandbox, agent, and run-control dependencies into task
implementations. Tests use fakes, never live services.
- Comment security reasons, platform constraints, and required ordering. Do
not narrate obvious code.
- Don't write code comments. Name things so the code explains itself, and
put constraints in docs or tests. Tool directives (`biome-ignore`,
`shellcheck`, shebangs) are the only exception.

## Tests

Expand All @@ -92,9 +107,10 @@ strict output schemas.
- Configuration key: update `FactoryConfig` in `factory.config.ts` and
`docs/configuration.md`. Check what the type system can't in
`validateConfig` (`app/config/index.ts`).
- Environment variable: update `.env.example`, `SERVICE_ENV` and, for a
secret, `ENV_GROUPS` in `scripts/lib/requirements.ts`, and
`docs/configuration.md`. Secrets belong in an env group, not a
- Environment variable: update `.env.example`, `SERVICE_ENV` and `ENV_GROUPS`
in `scripts/lib/requirements.ts` (unless `render.yaml` wires it directly),
and `docs/configuration.md`. Add non-harness secrets to `SECRET_ENV` so
`doctor` and `preflight` redact them. Secrets belong in an env group, not a
`sync: false` entry in `render.yaml`. Never link a group with GitHub App
credentials or a model key to the gateway.
- App permission, event, or label: update
Expand All @@ -104,9 +120,12 @@ strict output schemas.
derive the key list, and Sandbox allow-lists include every harness's
hosts. It must give the model only the factory's tools; add it to `HARNESSES` in
`tests/helpers/runner.ts` if it can run the conformance suite.
- `sandbox/`: refresh every repository snapshot after deployment. Changes to
`app/runner/`, `app/harness/`, or agents reach Sandboxes with the Workflows
deploy, because each Sandbox replaces a stale runner bundle when it opens.
- Database migration: keep `app/db/migrations/` additive, because one service
can run old code while the other migrates. Derive projections in
`app/db/projections.ts` only from events so `npm run db:rebuild` can
recreate them.
- Deploy and snapshot impact: check
[What must be redeployed](docs/configuration.md#what-must-be-redeployed).

## Verify

Expand Down
44 changes: 21 additions & 23 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Contributing

Read [Architecture](docs/architecture.md) before changing claims, credentials,
Sandboxes, publishing, or GitHub authority. Use the
Read [Architecture](docs/architecture.md) before changing run coordination,
credentials, Sandboxes, publishing, or GitHub authority. Use the
[extension runbook](docs/runbooks/extend.md) for agents, Workflows tasks, and
GitHub triggers.

Expand All @@ -18,7 +18,9 @@ npm ci
cp .env.example .env
```

Fill `.env` without committing it. Start each process in its own terminal:
Fill `.env` without committing it. `DATABASE_URL` can point at a local
Postgres; see [Database](docs/configuration.md#database). Start each process
in its own terminal:

```bash
# Terminal 1
Expand All @@ -28,6 +30,9 @@ npm run dev:workflows
RENDER_USE_LOCAL_DEV=true npm run dev:gateway
```

`RENDER_USE_LOCAL_DEV=true` directs the Render SDK to start tasks on the local
`dev:workflows` server instead of the Render API.

Expose port 3000 over public HTTPS:

```bash
Expand Down Expand Up @@ -67,6 +72,17 @@ calls. Vitest replaces `factory.config.ts` with the explicit configuration in
subjects, permissions, or expected verification commands. Keep configuration
compatibility cases in that fixture and exercise them through routing and tasks.

Database tests run on PGlite, in-process Postgres, through
`tests/helpers/db.ts`. PGlite runs one transaction at a time, so tests that
need concurrent transactions or connections run only when `TEST_DATABASE_URL`
points at a Postgres server where the user can create databases. CI sets it.
Name those files `*-postgres.test.ts`: Vitest runs them one at a time, since a
transaction anywhere on the server holds back readers of a thread's events.

```bash
TEST_DATABASE_URL=postgresql://postgres@localhost:5432/postgres npx vitest run --project postgres
```

Run additional checks when relevant:

```bash
Expand Down Expand Up @@ -100,31 +116,13 @@ Follow [docs/runbooks/extend.md](docs/runbooks/extend.md) to:
The runbook is the canonical procedure. Keep implementation details in code
and architectural reasons in [Architecture](docs/architecture.md).

## Add persistent state

The default template has no database. GitHub owns collaboration artifacts,
Render Workflows owns task execution, and telemetry goes to logs.

Add a database only for new data with its own lifecycle, such as a searchable
spec library, budgets, or retained run history:

1. Add a Render Postgres database to the `production` environment's
`databases` list in `render.yaml`.
2. Wire `DATABASE_URL` into only the services that need it.
3. Run migrations from a service `preDeployCommand`.
4. Use the internal connection string on Render. Local tools use the external
connection with TLS.

Do not move claim ownership into the database. The status comment must remain
the single source of truth for the run that owns an issue or pull request.

## Documentation ownership

- `README.md`: product entry point.
- `docs/quickstart.md`: human setup handoff.
- `docs/runbooks/setup.md`: first-deployment agent protocol.
- `docs/configuration.md`: settings, run control, deployment checks, and
snapshot procedures.
- `docs/configuration.md`: settings, environment groups, and Day-2 operations
(runs, event streams, snapshots, deployment checks, and the database).
- `docs/architecture.md`: state, boundaries, invariants, and accepted risks.
- `docs/runbooks/extend.md`: extension agent protocol.
- `CONTRIBUTING.md`: local development and verification.
Expand Down
Loading
Loading