How dsh-superagent works: five designs behind a proactive coding agent

Each design solves one failure mode that trips up ordinary coding agents, and each has a decades-old ancestor in systems engineering. The sections below unpack them one by one.

Design 1 is the Router-Worker split, and it comes with an attention discipline attached. Plenty of agents, the moment they take on a big task, say refactoring a module, have their session completely tied up. New messages go unanswered; changing course mid-flight means killing the process by force.

dsh-superagent splits interaction and labor into two separate populations of sessions. A Router, the main session, faces the human: it stays resident up front and holds the user's global memory, preferences, and conversational context. Behind it hang multiple Workers, execution sessions started on demand, running code changes, tests, or documentation digs in parallel. The structure buys a naturally sessionless experience: whenever the user speaks, the Router is there and answers. It never goes catatonic just because the system is mid-edit on some code.

Better still is the attention discipline that comes with it, strict to the point of asceticism. No junk progress updates while work is under way: the system speaks at exactly two kinds of moments, when a human has to make a call, or when a usable milestone has landed.

Each time it needs a human, it asks exactly one structured question, with the options laid out. Never a vague, open-ended "what do you think?" The process itself stays extremely quiet.

And reporting is honest to the bone: a draft is labeled a draft and flagged unfinished; a failure is reported as a failure, with the reason. No varnish.

This is the front-of-house manager and the kitchen of a respectable restaurant. The Router is the floor manager in a crisp suit, stationed out front. He keeps your taste preferences in his head, your allergies, the table you sat at last time. The cooks in the back, the Workers, just put their heads down and fire dishes; they do not make small talk with diners. Ask for water mid-course, or a question about a dish, and the manager answers on the spot. You will never catch the entire service staff folded into the kitchen while the dining room sits empty.

The more telling part is how well-mannered he is. While the cooks are chopping scallions and heating oil, the manager will not appear at your table every twenty seconds to narrate: "Sir, we've started on the scallions." "The pan is hot now." He approaches your table on two occasions only. Either a dish is ready for you to taste, or the kitchen has sold out of its last sea bass and he arrives with the menu to ask one structured question: "The sea bass is gone tonight. Would you like grouper, or red snapper?"

Design 2 is the event-driven architecture with per-source threads. You can think of it as the epoll of agents. A traditional agent is either a single one-way loop (the classic ReAct: think a step, call a tool, look at the result), and once that loop is spinning, an incoming GitHub issue or chat message simply has no way in; or it crudely spawns a fresh agent per message, and now several agents, each reading truncated context from different moments in time, make their own decisions, step on each other at commit time, and brawl.

dsh-superagent's answer is different. Every external input, whether newly pushed code, an issue, or a group-chat message, is wrapped on arrival into a Trigger: an immutable event, a record of something that has already happened and can no longer be altered. The system weaves these events into Threads, processing threads, keyed by data source.

The core rule is tight. One Thread runs at most one Eval (an evaluation task) at any moment. If an Eval is in flight, newly arriving events are neither dropped nor allowed to barge in; they park in a queue and merge into the next batch once the current evaluation finishes. Across Threads, everything runs fully in parallel. That strikes the balance between parallelism and consistency.

And there is one more grace note: before any of these events reach the expensive LLM, they pass through a coarse screen of lightweight rules and small models, which bins the chitchat, the machine-generated notifications, and the meaningless noise. The core pipeline never pays for garbage input.

You can read this as the ticket rail on the kitchen wall. Every dining table maps to its own stack of order tickets. When the same table adds dishes, the new ticket is clipped, obediently, to the very end of that table's stack. The cook finishes what is in the wok, reaches up, takes the next ticket, keeps going. One table's food leaves the kitchen in strict arrival order; you will not see two cooks both claim the same table's ticket and send out two identical plates of hot-and-sour shredded potatoes.

Table 1 and Table 2, meanwhile, are entirely separate stacks. Two cooks can work two burners at once, each on their own tickets. And before a waiter's tickets enter the kitchen at all, a runner plays gatekeeper: the order voided by mistake and the doodles a kid drew on a napkin are binned out in the front of house, never once entering the kitchen's line of sight.

Design 3 is the async ReAct loop: a 5-second rule, a wakeup mechanism, and a watchdog. The classic fear when a large model writes code: it issues a shell command to compile something or run the full unit-test suite, and then the whole session just sits there, waiting.

dsh-superagent sets a hard number. Any foreground shell command still running past five seconds is automatically demoted to a background task. Once the command moves to the background, the Worker is instantly free; in the very next loop iteration it can take new messages, read other code, plan the next move. When the background task or subtask completes, a wakeup mechanism rouses the corresponding Worker: the output is in, keep reasoning from here.

To fence off infinite loops and runaway tasks, every background task carries a hard thirty-minute ceiling. Time is up, and it is killed outright, with the report saying, plainly, "terminated on timeout."

And one role in this system is the indispensable backstop: the Watchdog, the man standing beside the stoves watching the fire. Model rate limits, a stuck agent, a task past its deadline: his to handle. For a large-model API, a 429, network jitter, rate limits, even a crashed Worker are everyday weather. An ordinary agent dies on contact; if the human happens to be asleep, the whole night is written off. The Watchdog works like a daemon process in an operating system: it catches the failure and owns the backoff-and-retry, the restart, or the graceful fallback.

In the kitchen, this is simply that burner firepower is finite. The chef drops his ingredients in. A flash-fried pork dish is decided in under five seconds, and the chef plates it right there at the wok. But when he has put a whole old hen in for a slow stock, he will not stand at the pot for two hours. Within five seconds that pot is moved to the small simmer burner beside it, a bell timer is set, and the chef turns back to the cutting board to prep cold dishes.

When the timer rings, he is called over to the little burner to lift the lid and reduce the sauce. If the simmer blows past its mark by half an hour with nothing to show, the rule of the kitchen is kill the fire and pour it out; no squatting on the burner. And there is always the stove patrol, hands clasped behind his back (the Watchdog): whether today is Huaiyang or Sichuan, he watches only the gas valves and the flames. The soup boils over and douses the fire, or the line pressure wobbles, and the chef does not have to think about it. The patrol is there first: valve off, relight, steady the flame. One pot boiling over does not shut down the kitchen.

Design 4 is the permissions stack: a versioned Policy, a Mandate slip, and a planned shadow mode. Handing an agent autonomy is dangerous work. One unguarded moment and it drops the production database, or files a stack of absurd pull requests in a public repository. Plenty of systems try to prevent this with a natural-language admonition in the prompt, "please be careful," and to a large model that admonition is wind past the ears.

Line one: a versioned Policy, the rule base. The admission criteria for taking a job are fixed in machine-readable configuration; every revision carries its own version number; there is no room for maybe.

Line two: the Mandate, an authorization slip that states what this job may do and under which version of the rules, checkable after the fact. Once an evaluation passes and the job is accepted, the system issues a completely immutable slip, printed plainly with the scope of execution, the strength of permission, and the policy version it rests on. The entire chain of work runs on this slip, and any of it can be audited and held to account later.

Line three, planned in the design document: a record-only shadow mode. For proactive behaviors the team does not yet trust, the system first runs in shadow. As the blueprint has it, the agent is only permitted to record, "had you let me act, I would have run these three commands and modified this file," and nothing is executed. After days, even weeks, of log review, once its judgment has proven stable and reliable, the switch is pushed and real authority is granted.

The floor principle is restraint: always narrow before wide; start from the shortest whitelist of permissions.

This is how a kitchen treats a cook on probation. The shop keeps an unambiguous employee handbook, house rules, third edition (the Policy). Each morning the new cook clocks in, and the manager hangs a badge around his neck for the day's station (the Mandate). It is steel-stamped and spelled out: today you work only at cutting board three; you prep only carrots and potatoes; you do not, at any point, open the cabinet where the abalone and dried scallops are kept. If a dish goes wrong tonight, you pull the badge and trace exactly who approved what, under which rule.

For new dishes the shop intends to launch, the head chef puts him on shadow shifts. He stands at the edge of the board with pen and paper, working out in his head how much salt, how the wok should be tossed, but he may only write the steps down. The spatula is off limits. After close, the head chef reads the notebook through, page by page, checking the ratios. A full week of this; and only when the newcomer's grasp has proven exact and never once out of bounds is he allowed, for the first time, to fire a wok for real.

Design 5 is Stored Work: book the ledger entry before the action, and recover the whole chain afterward. Anyone who builds distributed systems knows the most fragile thing in the world is state that lives only in memory. The network can drop at any moment. The server can restart at any moment. The LLM API can hand back malformed garbage at any moment.

The core design: write the ledger entry before the action. Every critical action the system takes, whether dispatching work to a Worker, delivering a notification, or replying to a human sentence, must first land in the persistent database, and only then does the actual network call go out.

Take the Outbox. Every outbound message queues to disk first, and an independent mechanism guarantees it goes out strictly in conversation order, with exponential-backoff retry built in. A network tantrum never results in the same message sent three times, and no message is ever lost.

More striking is the recovery story. Even if the machine is force-restarted in the middle of the night, an unfinished dispatch wakes up carrying a recovery note. The note, in plain language, reminds the re-awakened Worker: you just went through a restart; do not blindly start over from the top. Inspect the working directory; look at the local Git history; confirm which steps actually completed; only then decide whether to re-invoke the external actions. It goes one step further than that: even whether a single message has been read is committed to storage before the LLM call is made. Never re-send a message; never drop a state.

This is the thick, yellowed expediting ledger at the kitchen pass. A cook who finishes a plate of braised pork does not pick it up and sprint for the dining room. He walks to the pass and writes, in a careful hand, one line: "18:05, Table 3, braised pork out of the wok, runner Li has the plate." Stamp. Only then does Li carry it away. If Li slips on the way and the plate hits the floor, nobody has to reconstruct events from memory; the front desk opens the ledger and re-fires per the fallback procedure.

And for real trouble: the building blacks out, power returns half an hour later, and the kitchen does not dissolve into headless chaos. The manager takes the ledger from the pass and reconciles by flashlight: which dishes have reached their tables; which the guests have already started; which had, in fact, only just hit the wok and were never plated. The accounts are clean. No cook, because of one power cut, sleepily re-fires a braised pork for Table 3, a table that finished theirs to the last piece long ago.

Hold these five designs up to a personal automation stack that has been growing for a couple of years, and the engineering wounds hiding under "it runs, good enough" have almost nowhere left to hide. Five of them, one per design.

First sore point: alarm-driven versus event-driven, the missing intake layer. A homegrown system that depends on a roster of scheduled tasks waking at fixed hours (to-dos at eight, unread mail at noon, notes in the evening) has no give. For hours on end nothing happens, and the scheduled tasks keep polling empty air; then several real events land at once and all fire at the same instant, clumped, fighting for resources. Worse, every intake tends to get its own hand-written trigger layer, so the logic scatters across the house. The fix is direct: tear down the independent alarm clocks and gather every external intake into one queue-and-sort layer, sorted by origin into its own thread and evaluated serially. Fully asleep when idle; sorted and orderly when events arrive.

Second sore point: the health report versus the stove patrol. A "daily physical" that periodically checks whether the data-sync process has died can only push a shrill notification to a phone: "Attention: the sync process exited abnormally two hours ago." If that lands while the owner is asleep, it accomplishes nothing; the system stays down. A physical exam is not an attending physician. A real engineering system needs a supervisor standing by the stoves with authority of his own to act: compute the exponential backoff itself when rate-limited, kill the timed-out process when a subtask goes zombie, clean up the temp files, record the reason. While the human sleeps, the system has to learn to rescue itself within its boundaries.

Third sore point: prose for humans versus machine-readable warrants. A rules file of several thousand words, full of essay-grade passages like "exercise care when modifying important files," banks entirely on the model's conscience; change to a different model version and it misreads the intent with some regularity, or simply cuts loose. Rules must collapse into machine-readable, exactly checkable configuration lists, enforced by tamper-proof vouchers against a versioned policy, with the ticket checked before the action. And shadow mode is the missing transition: run a new automation for one week with its only permitted output being an observation log of what it intended to do, then graduate it to production.

Fourth sore point: crash, rerun everything. Marker files and boolean flags fear exactly two things, a power cut and a network blip. A fifteen-minute multi-step task dies at minute fourteen with the marker still sitting on disk; the next scheduler pass sees the marker and skips, or you delete it by hand and the whole task washes again from the first step, so the first half's side effects run twice. Stored Work is the fix: every step and pending message lands in a lightweight database with an explicit state machine, and after a restart the new process reads the ledger, picks up its recovery note, and resumes from step five.

Fifth sore point: notification bombardment. When every subsystem pushes its own notifications (a push here, an email there, a chat ping elsewhere), the phone screen fills with the system talking to itself, and eventually everything gets set to Do Not Disturb, which promptly swallows the genuinely important failure alarms along with the rest. Every outbound message must converge through a single front-of-house layer. All muttering during the work stays in the logs; when the daily automation runs without incident, there is nothing to report. Only two events justify a knock: an immediately usable result, or a fork the preset rules do not cover and a human must choose. And when it knocks, it carries exactly one structured, cleanly optioned, single-choice slip.

Take dsh-superagent's design apart and something interesting falls out. Front-and-back separation. Event-driven processing. Async, non-blocking tasks. The outbox pattern. Versioned authorization slips. Daemon processes. Not one of these is an unprecedented new theory. Nearly all of it is common sense, chewed over for decades in operating systems, networking, and distributed architecture.

But in the agent field, swept up in fervor and thick with grand nouns and concept packaging, taking this plain engineering common sense and doing all of it, in one pass, without discount, is itself extraordinarily rare. The prototype's real value is not that it tells a mystical story about intelligence. It is that somebody sat down and, with the coldest, tightest engineering skeleton, welded a wobbling experiment into a machine that runs true.

Rarest of all, they published the blueprint, repository name dsh-superagent-prototype, laid out plainly for anyone to read. Fairness obliges one caveat: the open-source release is a research prototype and differs from the internal version, and parts of the design, shadow mode among them, remain at the blueprint stage. That takes nothing from the document's reference value. The opposite: writing plainly which parts are verified common sense and which are the next step's direction is itself engineering honesty.

A proactive agent runs when you are not watching, and unattended sessions spend tokens steadily. DeepSeek Coding Plans pair an official key with a direct API connection at a discount, in one-off and explicitly selected recurring options, while stock lasts.