How Sukuna runs a task, and how it got there
In September 2025 a Sukuna task ran inside the Django backend. Sukuna was Midsphere’s general agent: you give it a task and it works on its own cloud desktop, an E2B sandbox. Back then the sandbox was where the agent’s code ran and nothing more. The loop lived in a backend worker and streamed to the browser over a websocket. By the end of April 2026 the backend did two things for a run: find a sandbox and sign a token. This is how it got from one to the other, read out of the project’s commit history. The published code is at midsphere-ai/sukuna.
The timeline
| Date | What changed |
|---|---|
| 12 Sep 2025 | Websocket streaming from the backend |
| 19 Jan 2026 | ARQ replaced with Temporal, websockets replaced with SSE |
| 24 Feb | Backend agent views rewritten as a proxy to an agent server inside the sandbox |
| 26 Feb | Celery put on the start path and taken off it. Two-hour run timeout removed |
| 26 Mar | Agent server writes to the shared Postgres. Webhooks deleted |
| 5 Apr | Planner and executors. First context engine |
| 7 Apr | Delegation becomes a signal |
| 13 Apr | Backend stream relay deleted. Crashed runs get a terminal event |
| 16 Apr | Compaction moves to a per-tool registry |
| 17 Apr | Turn intervals and step caps raised. Executor result schema grows |
| 23 Apr | POST /sandbox/acquire |
The agent server was written in a separate repository and imported on 9 March, so its first two weeks are not in this history.
Moving the run
On 19 January I changed the job queue and the transport on the same day. The loop still ran in a backend worker. On 24 February the backend’s agent views became a proxy, and the loop ran in a server inside the sandbox.
Four commits on 26 February show what broke first. A redesign queued every start through Celery and added a reaper that failed any run older than two hours. Later that day the reaper lost its timeout. The commit message reads: “Running tasks can legitimately run for hours or days.” It now fails a run only when its sandbox is dead. The next commit made the start path wait for the agent server’s health check before posting the run. The last one took Celery off the start path, to remove “the queued → provisioning polling delay entirely”.
Through March the sandbox reported back by webhook: an outbox in the sandbox, an HMAC signature, a callback table in the backend. On 26 March I rewrote the agent server on the Django ORM against the same Postgres the backend uses, so it writes the run row, the events and the final status itself. That rewrite deleted the JWT check for direct streaming along with the webhook code. A commit later the same day restored it. Also that day, every sandbox kill in the backend became a pause.
Two stream paths existed side by side until 13 April: one relayed through the backend, one direct from the browser to the sandbox with a short-lived JWT. That day the relay, 856 lines, was deleted. The same day a crash handler went in. If the run task raises, a callback marks the row failed with run_task_crashed and writes a run_failed event, so open streams end. Two tests pin it.
On 23 April the backend got its one call per session, POST /sandbox/acquire. The docstring at the top of the backend views now starts “provisioner + auth only”. Start, inject, cancel, answer and stream all go from the client to the agent server.
One agent, then two
Until April one agent did everything. On 31 March I let it spawn copies of itself, with a hook that suggested when to. That lasted a week.
On 5 April I split it. A planner got two tools, plan and call_executor, and each executor was built new with the full tool set and its own context. call_executor was an ordinary function tool, so the executor ran inside the planner’s tool call. Two days later I replaced it. The commit says the executor’s events bypassed the stream, which “skipped usage tracking and lease enforcement”. Since 7 April delegate runs nothing. It records the task and returns:
return "Task accepted. Execution will begin after this turn ends."
The harness reads the signal when the planner’s step ends and runs the executor itself, up to 20 times per run. The same day self-spawn was switched off on every agent, and on 9 April the suggestion hook was removed.
The fixes that followed are the record of what went wrong.
- 8 April. The frontend treated an executor’s “completed” status as the end of the run. Sub-agent terminal statuses are now filtered out of the stream.
- 10 April. A regression test went in for a run where the planner called
delegate, an exception followed, and the harness left the loop before checking the signal. The log saiddelegations=0. The executor now runs anyway. - 13 April. Executors lost the ability to ask the user anything. A guardrail aborts any executor message that is not
info. Questions go back in aplanner_questionsfield and the planner asks. - 17 April. The result schema gained
key_findings,open_decisionsandsuggested_next_delegations. The commit says this “kills the read→re-summarize loop that dominated prior runs”, and the planner prompt now forbids delegating again to rediscover what is already inkey_findings. The same commit made the stall watchdog skip its count while a question to the user is pending, under the heading “Stream watchdog no longer kills legitimate pauses”.
One more cost shows up in a docstring. The harness used to send the planner every earlier executor result on each pass. The planner’s history already held them, so the input grew from 1.2K to 19.8K tokens across 16 delegations, about 160K in total. Now only the latest result is sent.
Also on 17 April I added scope rules for “scaffold” delegations to the planner prompt. The commit describes a live run where the planner asked for a scaffold and the executor wrote more than 30 files in one delegation. I reverted the rules the same day. The record does not say why.
The context engine
The commit before the split is titled “before adding new context engine”. Until then the framework’s own settings managed the window. On 5 April the engine arrived with two stages: compaction, which shrinks old tool calls in place, and summarisation, which dumps the history to disk and replaces it with a structured summary.
| 5 Apr | 16 Apr | 17 Apr | |
|---|---|---|---|
| Compact every | 50 turns | 50 turns | 150 turns |
| Summarise every | 150 turns | 150 turns | 400 turns |
| Token trigger | compact at 96,000, summarise at 128,000 | one budget, 128,000 | one budget, 128,000 |
| What a compacted call keeps | what the model declared when it made the call | what a per-tool registry lists | same |
| Recent messages protected | last 6 from compaction, last 4 from summary | none | none |
| Step cap, planner / executor | 50 / 75 | 50 / 75 | 200 / 250 |
In the first version the model filled in two extra arguments on every tool call, saying what to keep and what to replace the result with. On 16 April that moved into a registry in code, where each tool lists its essential arguments and a function builds a one-line pointer to the saved output. The recency windows went in the same commit. That commit is a 245-file checkpoint, so the history shows the change and not the reason.
The reason for the longer intervals is written down, in a comment above them:
# Tools in this codebase already return compact pointers (file paths,
# save-to-disk references) instead of dumping raw output, so per-turn
# token growth is small.
What I would do differently
Tie the step caps to the intervals. A comment in the config says each cap should ideally exceed the summarisation interval. It never did: 75 against 150, then 250 against 400. At the defaults, summarisation inside one executor has only ever fired on the token trigger.
Commit engine changes on their own. The registry, the single budget and the relay deletion all sit inside checkpoint commits, and that is where this account runs out of reasons.
Make the agent server restartable. Run tasks, notify channels and pending questions are dictionaries in one process, and startup forces a single worker. The events survive a restart of that process. The run does not.