Skip to content

Add a Postgres event log, live agent streams, and channel-agnostic threads #84

Open

Description

@jacobprall

Goal

Turn the factory into a complete reference for an agentic app on Render, with one source of truth and agents you can watch, starting with the agent where it runs today, in the Sandbox:

  • Postgres holds an append-only event log. Projections (tables derived from the log in the same transaction) answer every "what is true now" question: who owns a thread, which run is active, which Sandbox it holds, what an agent run cost.
  • GitHub keeps repository content and the artifacts people read. The status comment becomes a view rendered from Postgres, not a lock.
  • Agents run on Pi 1.5.2 in the Sandbox. The runner reports events on its output, and the Workflows host relays them into the log as they arrive. Every agent run streams live over server-sent events (SSE), per agent run or per thread.
  • Channels: work happens on threads, keyed <channel>:<id>. GitHub is the first channel (github:owner/name#issue-12, github:owner/name#pr-34), so more channels can be added without touching the event log.

The design borrows from render-agents (event log, projections, live deltas over NOTIFY, the runner-as-sidecar idea) and keeps the factory's own strengths: the run kernel, typed submit, validated publishing, and the egress allow-list from #82.

What the PR delivers

Area Outcome
Event log factory-db in the Blueprint; an append-only events table with per-stream versions, ordered reads that never skip a late commit, a typed event catalog, projections, npm run db:rebuild, migrations applied by both services at startup, PGlite for npm test
Run coordination Claims, cancellation, and Sandbox tracking in Postgres. A claim is an event on the thread's stream, fenced by the stream's version. The status comment and factory:working are synced from Postgres and never read back
Live agent events Every runAgent call records its agent run (agent_run.*, assistant.message, tool.call, tool.result, usage), with the outcome and cost from the host's own reading of the result. Token deltas over NOTIFY, never stored. An agent_runs projection
Live relay run-agent.sh tees the runner's output; the Workflows host reads it as it arrives and resumes from a byte offset if the command stream drops. The root-owned output file stays authoritative
Streams (gateway) GET /threads/:thread/stream (any URL-encoded thread key), the GitHub alias GET /threads/github/:owner/:repo/:kind/:number/stream, and GET /agent-runs/:id/stream, behind EVENTS_READ_TOKEN
Pi 1.5.2 Driven through createAgentSession. The kernel's turn limit is enforced through a ModelRuntime wrapper; Pi's discovery is off, so no AGENTS.md, skill, prompt template, or extension loads from the checkout; Pi's cache warming is off, so it can't spend turns on its own
Setup npm run setup:render generates EVENTS_READ_TOKEN; after the Blueprint is applied, npm run setup:render -- --link-database copies the gateway's DATABASE_URL into the software-factory-workflows group (see Blueprint finding below). doctor checks the database and keeps webhook delivery IDs exact
Docs README, architecture (including design principles), configuration, setup runbook, contributing, and AGENTS.md describe the current design

Decisions

  • Postgres is required and is the source of truth for factory state. Every state change is an event; current state is a projection updated in the same transaction.
  • Ordered reads. Single-stream readers page by stream version; per-thread readers page by (tx, seq) below the oldest running transaction, so a late commit can never be skipped.
  • Nothing reads a GitHub comment to decide ownership. A new run takes ownership first and then stops the previous run, so the previous run is cut off even if cancelling it fails.
  • Only the Workflows host and the gateway write to Postgres. Nothing in a Sandbox gets a database credential, an endpoint, or a token, and the Sandbox allow-list doesn't change.
  • Runner output is untrusted. It only becomes assistant.*, tool.*, and usage events on its own agent run; outcomes, costs, and ownership come from the host.
  • Threads are channel-agnostic. The event log validates the <channel>:<id> shape and never parses the id. Deliveries are recorded on delivery:<channel>:<id>.
  • No fallbacks for state written before the upgrade: let runs finish before deploying.

Verification

  • npm run check: 321 tests pass; 8 real-Postgres tests (late-commit gap, version races, concurrent claims, two gateway instances, concurrent migrations) pass against Postgres in CI.
  • Pre-build spikes: a Sandbox command keeps running after its client disconnects and the Sandbox stays awake; tail -c +offset -f --pid resumes exactly; the watermark read closes the late-commit gap; PGlite supports the schema; the Pi turn-limit hook, lockdown, and single-file bundle work (bundle self-test passes on the Render base image).
  • Deployed end to end on a fork deployment: Triage → Spec-to-PR → PR Reviewer on a Go repository. Each stage claimed and released its thread; status comments were rendered from the log; both stream routes showed claims, progress, tool calls, usage, and model text live. Total: about 9 minutes and $0.49 in model spend across four agent runs.

Findings from the deployment

  • Blueprint sync can't give a workflow service DATABASE_URL from a database. fromDatabase on a workflow fails sync even after the database exists, and copying the gateway's value with fromService/envVarKey is rejected because references can't chain. The PR works around it with setup:render -- --link-database after the Blueprint is applied; the first Workflows deploy fails until then, and the runbook says so. Worth a fix on the Blueprint side.
  • sslmode=require is changing meaning in pg; the docs now recommend ?sslmode=verify-full for the external URL.
  • Sandbox API pacing: 130 back-to-back commands ran at 246 a minute without rate limiting, so the client's one-request-a-second pacing would dominate if tools ever ran remotely.

Follow-ups (not in this PR)

  • Credential brokering for the model key (Adopt Sandbox credential brokering when it ships #45), once early access is enabled: a brokered x-api-key would remove the key upload, the stdin handoff, and the key scrubbing. The GitHub fetch-token scrub stays: installation tokens are short-lived and per installation.
  • Workflow placement: Pi in a Workflows task with tools in the Sandbox and an allow-list without model hosts, plus a placement demo. Spike results (latency and pacing) are recorded for it.
  • Spec approval and artifact markers in Postgres.
  • A reserved-name check for channel names that would match the log's own stream prefixes (run, delivery, thread).

Trade-offs and risks

  • Postgres becomes required infrastructure. Free databases expire after 30 days, so the Blueprint uses a paid instance, which the Deploy to Render button will create.
  • The gateway gains a database credential that can write factory state. A compromised gateway can forge events.
  • Stream readers share one bearer token, and events can quote repository content and tool output.
  • Ownership is still check-then-act against GitHub writes; the window is narrower, not closed. Publishing still refuses to overwrite commits the factory didn't make.
  • A task Render cancels without running finally leaves its claim held until the next run or /factory cancel resolves it.
  • The runner bundle grows from 6.6 MB to 15.7 MB, uploaded once per snapshot.

Not planned

The render-agents reconciler, sandbox generations, chat with follow-up and steer messages, approvals, agent-to-agent messaging, and its web UI. Render Key Value for delta replay.

Activity

  1. added
    enhancementNew feature or request
    bothNeeds a person for part of it; an agent can do the code
    on Nov 17, 2026
  2. changed the title [-]Add a Postgres event log, live agent events, and a choice of where Pi runs[/-] [+]Add a Postgres event log and live agent events[/+] on Nov 17, 2026
  3. changed the title [-]Add a Postgres event log and live agent events[/-] [+]Add a Postgres event log, live agent streams, and channel-agnostic threads[/+] on Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bothNeeds a person for part of it; an agent can do the codeenhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions