Affan Ahmed

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.

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.