docs(factory): add the Running Factory runbook (local + cloud) - #60
Conversation
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
Warning Review limit reachedNext included review available in 49 minutes. View limit detailsLimit details: You’ve used the included review currently available. You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. Review configuration: ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Team Run ID: 📒 Files selected for processing (3)
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Team Run ID: 📒 Files selected for processing (2)
Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review. 📝 WalkthroughWalkthroughAdds a complete Running Factory runbook. It covers local, cloud, and hosted operation, including setup, dispatch, recovery, leases, tokens, and telemetry. The Factory navigation now includes the runbook and shows version ChangesFactory operations documentation
Estimated code review effort: 3 (Moderate) | ~20 minutes Merge Risk: ⚪ Minimal · up to The new Running Factory runbook is published through Factory navigation and documentation checks pass. No current merge-blocking risk is identified. Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ef4e7fb690
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| agent-relay cloud enroll --token ocl_node_enr_… | ||
|
|
||
| # each boot — node up auto-discovers agent-relay.ts in the working directory | ||
| agent-relay node up |
There was a problem hiding this comment.
node up
When readers follow this runbook with Agent Relay 11.3.0 or earlier, node up prints the active workspace key, but this executable block has neither a version gate nor the warning present on the linked where-it-runs page, and the prerequisites merely say Agent Relay must be installed. Require 11.3.1 or later before this command so copying the runbook into a logged or transcribed terminal does not expose an administrative credential.
AGENTS.md reference: AGENTS.md:L25-L31
Useful? React with 👍 / 👎.
| ### Hosted control plane in Cloud | ||
|
|
||
| `@agent-relay/factory/hosted` is the worker-safe control-plane entrypoint — no Node filesystem or process dependency, the complete sweep (`reconcile invocation completions → discover → triage → dispatch → merge gate → idempotent writeback`) driven by your host: |
There was a problem hiding this comment.
This new section documents a control plane that runs in a Cloud worker, while the page presented above as the conceptual map still states in where-it-runs.mdx:66-72 that Cloud only receives reporting, no hosted Factory runs the loop, and running in Cloud is merely coming soon. Readers following the cross-link now receive mutually exclusive availability guidance, so update that page alongside this section or clearly distinguish this self-hosted worker API from the unavailable offering.
Useful? React with 👍 / 👎.
|
|
||
| | Symptom | Cause | Fix | | ||
| |---|---|---| | ||
| | `Live state changed before writeback` | The run died after claiming the issue | `gh issue edit <n> --remove-label factory:in-progress`, re-dispatch | |
There was a problem hiding this comment.
gh auth
For the documented default github.identity: "auto" setup, the prerequisites explicitly say users do not need gh auth login, yet this recovery command invokes gh issue edit. After a crash in that standard configuration, the prescribed cleanup therefore fails for users who followed the prerequisites exactly; either require/authenticate gh for this recovery path or provide a cleanup command that uses Factory's connected App identity.
Useful? React with 👍 / 👎.
|
Preview deployed!
This is a Cloudflare Workers preview version of this PR's build. |
…uns, gh-free recovery, Guides nav group
|
Review feedback addressed in 423f0a6:
|
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
2 issues found and verified against the latest diff
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="web/content/docs/factory/running.mdx">
<violation number="1" location="web/content/docs/factory/running.mdx:107">
P1: Require Agent Relay 11.3.1 or later before `agent-relay node up`; older versions print the active workspace key, so this copyable command can expose an administrative credential.</violation>
<violation number="2" location="web/content/docs/factory/running.mdx:121">
P3: This page documents a hosted control plane (`@agent-relay/factory/hosted`, `createHostedFactory`, `DurableObjectHostedFactoryStateStore`), but the existing 'Where it runs' page in the same Factory nav group says 'There is no hosted Factory that runs the loop for you yet: the control plane is something you run, on a machine you choose.' The two pages contradict each other. Align the 'Where it runs' claim (or the hosted section) so the docs don't present opposite answers about whether a cloud-hosted control plane exists.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| agent-relay cloud enroll --token ocl_node_enr_… | ||
|
|
||
| # each boot — node up auto-discovers agent-relay.ts in the working directory | ||
| agent-relay node up |
There was a problem hiding this comment.
P1: Require Agent Relay 11.3.1 or later before agent-relay node up; older versions print the active workspace key, so this copyable command can expose an administrative credential.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At web/content/docs/factory/running.mdx, line 103:
<comment>Require Agent Relay 11.3.1 or later before `agent-relay node up`; older versions print the active workspace key, so this copyable command can expose an administrative credential.</comment>
<file context>
@@ -0,0 +1,175 @@
+agent-relay cloud enroll --token ocl_node_enr_…
+
+# each boot — node up auto-discovers agent-relay.ts in the working directory
+agent-relay node up
+```
+
</file context>
| agent-relay node up | |
| # Requires Agent Relay >= 11.3.1; older versions print the active workspace key | |
| agent-relay node up |
|
|
||
| Run **one** control-plane host per workspace; multiple processes on that host are fenced by a shared lock. Active/active across hosts is deliberately unsupported. For production, point `AGENT_RELAY_STATE_DIR` at a directory distinct from any project broker and set `fleetHealth.requireDedicatedBroker: true` — Factory then refuses to silently reuse an interactive broker. `batchSize` defaults to 1 and is capped at 5. | ||
|
|
||
| ### Hosted control plane in Cloud |
There was a problem hiding this comment.
P3: This page documents a hosted control plane (@agent-relay/factory/hosted, createHostedFactory, DurableObjectHostedFactoryStateStore), but the existing 'Where it runs' page in the same Factory nav group says 'There is no hosted Factory that runs the loop for you yet: the control plane is something you run, on a machine you choose.' The two pages contradict each other. Align the 'Where it runs' claim (or the hosted section) so the docs don't present opposite answers about whether a cloud-hosted control plane exists.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At web/content/docs/factory/running.mdx, line 117:
<comment>This page documents a hosted control plane (`@agent-relay/factory/hosted`, `createHostedFactory`, `DurableObjectHostedFactoryStateStore`), but the existing 'Where it runs' page in the same Factory nav group says 'There is no hosted Factory that runs the loop for you yet: the control plane is something you run, on a machine you choose.' The two pages contradict each other. Align the 'Where it runs' claim (or the hosted section) so the docs don't present opposite answers about whether a cloud-hosted control plane exists.</comment>
<file context>
@@ -0,0 +1,175 @@
+
+Run **one** control-plane host per workspace; multiple processes on that host are fenced by a shared lock. Active/active across hosts is deliberately unsupported. For production, point `AGENT_RELAY_STATE_DIR` at a directory distinct from any project broker and set `fleetHealth.requireDedicatedBroker: true` — Factory then refuses to silently reuse an interactive broker. `batchSize` defaults to 1 and is capped at 5.
+
+### Hosted control plane in Cloud
+
+`@agent-relay/factory/hosted` is the worker-safe control-plane entrypoint — no Node filesystem or process dependency, the complete sweep (`reconcile invocation completions → discover → triage → dispatch → merge gate → idempotent writeback`) driven by your host:
</file context>
1 participant
What
A new Factory docs page, Running Factory (
/docs/factory/running), in the style of the Relayfile run-locally/cloud guides: a hands-on runbook for running the loop on one machine first, then each half in the cloud.Resource not accessible by integration)factory init, a durable broker identity (AGENT_RELAY_STATE_DIR+AGENT_RELAY_BROKER_NAME, why restarts collide without it), dry-run, the dispatch sequence (claim → isolated worktree → implementer → PR publish → reviewer → human review,mergePolicy: never),fleetHealthtuning for large workspaces, and a crash-recovery table with the three post-crash residues and their one-line fixes--backend relay, enrollment,agent-relay.ts,factory.node.json,repo:<label>tags, lease-fenced takeover, one-host-per-workspace, dedicated broker isolation) and the hosted control plane via@agent-relay/factory/hosted(createHostedFactory+DurableObjectHostedFactoryStateStore, the ports table,runOnce/ingestCompletion, epoch fencing, token roles)Also registers the page in the Run nav group and bumps the sidebar version badge from the stale
0.1.34to the published0.1.86.Why
The local runbook is distilled from a verified end-to-end run today (issue → dispatch → implementer agent → app-authored PR #7 → review → human merge on
AgentWorkforce/factory-test-infra), including every failure mode hit along the way. The hosted-cloud section is written against the actualsrc/hostedAPI surface, not just the README.Verification
npm --workspace web run test— 31/31 pass (product-docs, docs-markdown-components, llms-txt, code-fence-meta)content/docs/factory/running.mdx)Summary by cubic
Adds a Running Factory runbook covering local dispatch and cloud deployment, and registers it in the Guides nav group. The page covers prerequisites, the full local loop, crash recovery, and both cloud shapes (CLI control plane with fleet nodes, hosted control plane). Aligns Where it runs with the hosted control plane, gates
node upon Agent Relay 11.3.1, and bumps the sidebar version badge from0.1.34to0.1.86.Written for commit 423f0a6. Summary will update on new commits.