TopicEvent
Append-only, and the record of what happened. Provider-neutral kinds such as TEXT, TOOL_CALL and UI_MUTATION, so an adapter replays normalised history.
Siteplan runs as one Django project under ASGI: HTTP views, WebSocket consumers and a JSON API in the same process that owns the ORM. Two deployment processes come from the same image, and where an agent run executes is a policy — not a rewrite.
The tempting shape is a realtime service in front of Django. It is rejected for a specific reason: there is no missing capability that justifies a second auth plane and a second migration consumer.
| Alternative | Verdict | Reason |
|---|---|---|
| Django ASGI + Channels + Ninja | Chosen | One deploy, one schema owner, one auth plane. Reuses the existing HTMX, Alpine and Tailwind stack. |
| Django + separate FastAPI service | Rejected | Adds a second auth plane, a second migration consumer and a second deploy for no missing capability. |
| WSGI with polling or SSE only | Rejected as primary | SSE is one-way and still needs Redis across instances. Polling cannot push approvals. Kept as a documented degradation path. |
| Celery for agent runs | Deferred | Postgres SKIP LOCKED plus a Redis wake-up is enough for the first release, and Celery can replace the worker behind the same interface. |
Postgres is the truth. Redis carries fan-out and wakes the worker. The browser talks HTTP and WebSocket to the same application.
Every write goes through append_event. That is not tidiness — it is what
makes ordering, idempotency and authorization hold across instances.
seq is gapless and monotonic across instances.(topic, client_event_id) returns the original event after a retry.seq; subscribers re-read the row from Postgres.def append_event(*, topic_id, kind, sender, payload,
run=None, caused_by=None, client_event_id=None):
with transaction.atomic():
topic = Topic.objects.select_for_update().get(pk=topic_id)
if client_event_id:
existing = TopicEvent.objects.filter(
topic=topic, client_event_id=client_event_id).first()
if existing:
return existing
if sender.actor_type == "AGENT":
check_agent_grants(sender.agent, kind=kind, payload=payload)
topic.last_seq += 1
topic.save(update_fields=["last_seq"])
event = TopicEvent.objects.create(
topic=topic, seq=topic.last_seq, kind=kind, sender=sender,
payload=payload, run=run, caused_by=caused_by,
client_event_id=client_event_id)
apply_projections(event)
transaction.on_commit(lambda: fanout(topic_id, event.seq))
return event
created_at is display metadata only. It is never used for ordering or
resumption — wall-clock timestamps collide and cannot support dedupe.
Append-only, and the record of what happened. Provider-neutral kinds such as TEXT, TOOL_CALL and UI_MUTATION, so an adapter replays normalised history.
A cache of the current state at a version, keyed by a stable widget id. Rebuildable from zero with a projection rebuild command.
Projections of ARTIFACT_PUBLISHED, ARTIFACT_PINNED, ARTIFACT_UNPINNED and TASK_CHANGED — so a pin can be rebuilt and an artifact re-derived.
The client stores its last seq per topic and sends it on connect.
seq > n from Postgres in bounded pages.seq is dropped. That closes the replay/live race.
A UI mutation carries base_version. If it does not match the canvas's current
version, the append is rejected with a conflict event and the producer re-reads state.
A provider adapter says which engine runs a session. It does not say where the session runs. Keeping them independent is what allows the same adapter to run in-process today and in a container or on a VM later — with no change to the adapter or the event pipeline.
"Support CLI agents" means one adapter per tool, not one generic flag. Start with the two tools the team actually uses.
| Placement | Status | Isolation |
|---|---|---|
| in_process | built | none |
| subprocess | built | process, same uid |
| sandboxed | specified | filesystem namespaces |
| container | specified | namespaces + cgroups |
| remote | specified | host or VM |
@runtime_checkable
class Executor(Protocol):
placement: str
def capabilities(self) -> PlacementCapabilities: ...
def start(self, session: "RunSession") -> AsyncIterator[RunChunk]: ...
async def cancel(self, run_id: uuid.UUID) -> None: ...
async def teardown(self, run_id: uuid.UUID, epoch: int) -> None: ...
Executor.start returns an async iterator with the same shape as
AgentRuntime.start, so the worker's translate loop is identical for every
placement. The provider adapter never learns where it ran.
teardown is separate from cancel and must succeed even when the session already died — that is what prevents orphaned containers.epoch numbers the attempt, so cleanup is idempotent and a stale attempt cannot delete a live one.Siteplan is installed on-premise rather than run as SaaS. An administrator who trusts the people on the box should not have to stand up a container runtime, a storage pool and an image pipeline before an agent can run.
That choice fixes the threat model, so it is stated plainly: a subprocess is containment, not a boundary. An agent holding a shell is arbitrary code execution as the worker's uid. What a trusting local placement still guarantees is non-collision and the right account — and each guarantee is required, not optional.
One directory per topic and requester, mode 0700. Two people in a room never share a checkout, and runs within one workstream serialise instead of interleaving writes.
A run never inherits the worker's credentials. Sharing a subscription is one account provisioned into several roots; a personal subscription is one user's root with their own account.
The organization's placement policy and the run's recorded placement say which guarantees are in force, so an admin cannot believe they have a boundary they do not have.
Both resolve to a recorded value on the run, so an auditor can answer "which engine, and where" after any config change.
A manual switch appends a binding and a RUNTIME_CHANGED event, so the timeline shows where the engine changed. A switch never renumbers or rewrites existing events.
"May this actor use this verb." Coarse and auditable: topic.post, canvas.write, artifact.publish, artifact.pin, dataset.query, dynapp.write, task.assign, agent.manage, browser.open. Default-deny, expiring, revocable — resolved by one helper called from the append path, the API endpoints and tool dispatch.
"Which rows may this actor see." Resolved from the viewer at read time — the same membership union that defines room access — and never stored on an artifact, a pin or a grant. A membership change takes effect immediately.
| Rule | Why it exists |
|---|---|
No tool.invoke:sql | Arbitrary SQL turns a prompt injection into a database read. A validated dataset spec is the only path. |
| Aggregates after row filtering | A count computed before filtering leaks the existence of rows the viewer cannot read. |
| Secrets never in argv or the environment | Both are readable on a shared host and inherited by child processes. |
| BROWSER content in a sandboxed iframe | Deliberately without allow-same-origin, so the framed page runs on an opaque origin. |
| Approval bound to a payload hash | An approval cannot be replayed for a different action. |
| One hop for triggers | An agent may not trigger an agent, or the bill is unbounded by construction. |
Every step names real files and leaves the existing tests green. The first four — ASGI, the event log, the actor flag and the WebSocket consumer — are the foundation everything else stands on.
| # | Step | What is verified |
|---|---|---|
| 1 | ASGI skeleton | Existing tests pass; /, /app/ and /cms/ still serve; a ping consumer echoes. |
| 2 | Organization, team, room, topic, event log | Concurrent appends produce unique monotonic seq; a duplicate client event returns the original; a fork creates a child with a required subject. |
| 3 | Actor flag | Existing auth tests pass, and agent users cannot log in. |
| 4 | WebSocket consumer | Anonymous closes 4401, non-member closes 4403, reconnect resumes with no gaps or duplicates. |
| 5 | Agent domain | Clone copies configs and never secrets; grant expiry works; the approval state machine works. |
| 6 | Generative UI and canvas | Invalid payloads rejected; a patch updates one widget; every widget string is wrapped for translation. |
| 7 | JSON API | OpenAPI serves; tenancy is enforced; actions re-resolve against stored widgets. |
| 8 | Runtime and worker | A fake provider drives a run to DONE; cancellation works; SKIP LOCKED does not double-claim; steps sum to the run cost. |
| 9 | Executor seam and placements | A subprocess CLI run has no DATABASE_URL or REDIS_URL; a killed worker leaves no orphan. |
| 10 | Dynamic apps | Create a model with a relation, persist records, enforce organization scoping. |
| 11 | i18n and hardening | msgfmt --check passes and no unwrapped UI strings remain. |
| 12 | Objectives and tasks | A task assigned to an agent creates a topic and a queued run; an objective with no linked work is visibly empty. |
| 13 | Artifacts and pins | Promote a canvas to a team pin, pin the same artifact org-wide, resolve per viewer, confirm a guest sees neither. |
| 14 | Datasets and data binding | Two viewers of one artifact receive different rows from the same pin; a query outside scope renders a permission state. |
| 15 | Participation and triggers | An agent is rostered, mentioned and fires on a cron; a trigger that tries to start a second run is refused. |
| 16 | Tool mediation and agent API | A CLI placement performs a tool call through the same dispatch; a finished run's token is rejected; no executor opens a database connection. |
Deploy delta: one REDIS_URL, an ASGI web command, one sync_dynamic_models
build step, and one background worker from the same image.