Skip to main content

Software factory overview

The software factory (phase P3) turns a task description into a reviewed pull request. A client submits a job against an allowlisted repository at a pinned commit; a durable Temporal workflow runs a plan, code, test and review loop in per-job sandboxes; a human approves the result; the worker pushes a deterministic commit to a fork and opens a pull request. The goal of the design is that an untrusted model can propose a change but cannot publish one: every byte that leaves the sandbox is parsed, filtered and re-derived on the host, and a human gate binds to a digest of those bytes.

Status. The source documents state that the factory is built and tested locally only (a Linux VM, a scripted fake model, a fake git remote). Nothing in the deploy runbook has run on the VPS or against real GitHub; the GitHub Apps, the fork layout, runsc, TLS for the control link and real-key runs are all marked UNVERIFIED with a named owner (Job lifecycle, docs/deploy-factory.md).

End-to-end flow​

Where the code lives​

ConcernLocation
Contracts (statuses, limits, digests, policy schema)packages/agent-types/src/factory.ts
Intake, read, approval and cancel routesapps/api/src/factory.ts
Workflowpackages/agent-workflows/src/workflows/factory.ts, contract in factory-shared.ts
Activitiesapps/worker/src/factory/activities.ts
Patch parser, filter, secret scan, hardened gitapps/worker/src/factory/patch.ts, secrets.ts, apply.ts, outfile.ts
GitHub (two Apps, fork, PR)apps/worker/src/factory/git-host.ts, github-app.ts, local-git.ts
Sandbox runtime, test containerapps/worker/src/sandbox/*
Sandbox runner (inside the container)apps/sandbox-runner/src/runner.ts
Factory worker entry and configapps/worker/src/factory-main.ts, apps/worker/src/factory/config.ts
Tablespackages/db/src/schema.ts, store in packages/db/src/factory.ts

Design principles​

  1. Postgres decides. Job and step state, attempt counters, fences, approvals and artifacts live in Postgres. Temporal payloads carry ids, digests and small enums only. The approval signal wakes the workflow; the decision is read from Postgres.
  2. The sandbox is untrusted. It holds only a per-job token. The host takes exactly one regular file out of it, and the completion of a step is a host fact, not the runtime's claim.
  3. The host never runs repository code. No package manager, hooks or filters on the worker; the host only parses text, applies it with hardened git and archives it.
  4. Approvals bind to bytes. A digest over job, repo, base commit and artifact digest; openPr re-derives everything from the approved bytes before it pushes.
  5. Least credential per component. The factory worker holds the GitHub App keys and the gateway worker control token but never an Anthropic key; the API holds no GitHub credential; the gateway holds the Anthropic key; the sandboxes hold a single short-lived token.
  6. Fail closed. Any error in a security check ends the step or the job (kill switch read error, scrub error, unparseable manifest, preflight failure).

Components and trust​

Job at a glance​

ItemValue
Workflow type, id, queuefactoryJobWorkflow, factory-<jobId>, agentforge-factory
Roles and caps (default, USD per step)planner 0.10, coder 0.25, reviewer 0.10
Per-job budgetrequest budgetUsd up to 2, ceiling FACTORY_MAX_JOB_USD default 0.5
Iterations1 to 5, default 3
Step timeoutFACTORY_STEP_TIMEOUT_MS default 600 s, max 840 s
Approval TTL72 hours default, up to 7 days
Active jobs per client2 by default
Gatesfactory.pr always, factory.plan optional
Statusesqueued, planning, awaiting_plan_approval, coding, validating, testing, reviewing, awaiting_pr_approval, opening_pr, pr_opened, failed, cancelled

Per-repo policy​

Operator-owned knobs live in a strict JSON file per repository, <FACTORY_POLICY_DIR>/<repo name>.json, parsed as FactoryRepoPolicy. An unknown key is a startup error. A repository with no file gets the defaults (the factory.pr gate only). They are not part of the gateway's policy.

KeyDefaultMeaning
idrequired (default when no file)policy id, ^[a-z0-9-]{1,64}$
tests.command['pnpm', 'test']fixed argv for the test container
tests.requiredtruea non-passing test blocks acceptance
tests.timeoutMs300000 (max 840000)test run bound
patch.allowBinaryfalseallow binary hunks (their decoded bytes are scanned)
patch.allowNonAsciifalsedeclared; not wired in the patch parser (see Patch policy)
patch.protected[]extra protected path globs, added to the defaults
patch.githubAllow[].github/** globs explicitly allowed (workflows stay forbidden)
approvals.fourEyesfalsedeclared; not enforced anywhere (see Gates and approvals)
gates['factory.pr']gates to add; factory.pr is always present
qualityabsentCodeCrucible policy; absent means CodeCrucible is off for the repo

Section map​

  • Job lifecycle: states, the workflow, activities, budget, cancellation, tables and limits, worker configuration.
  • Gates and approvals: digests, the approval transaction, expiry races, roles, the four-eyes gap.
  • Patch policy: the validation pipeline, protected paths, reason codes, secret scan, publishing a pull request.
  • Sandbox roles: the planner, coder, reviewer and test containers, the Docker contract, workspace in and out.

Related: REST API for the routes, Runtimes and CLI for the runtime port the sandbox runtime implements, Sandbox and Threat model for security analysis, Deploy runbooks for deployment.

Sources​

  • packages/agent-types/src/factory.ts (FACTORY_LIMITS, FactoryStatus, FactoryRepoPolicy, effectiveGates)
  • packages/agent-workflows/src/workflows/factory.ts, packages/agent-workflows/src/workflows/factory-shared.ts
  • apps/api/src/factory.ts, apps/api/src/config.ts (FACTORY_*)
  • apps/worker/src/factory/config.ts (loadPolicies, loadFactoryConfig), apps/worker/src/factory-main.ts
  • docs/deploy-factory.md
  • .omc/plans/p3-software-factory.md (sections 0, 4, 5, 6)