Anatomy of a Proactive Repository Agent: A dsh-superagent Code Teardown

The shape: a plugin bundle inside DSH

dsh-superagent has no model, session, or tool runtime of its own. Every @deepseek-ai/dsh-* package is a peer dependency; the repository contributes orchestration only.

cordis.patch.yml also defines two agent presets: dsh-superagent-worker for executors and dsh-superagent-router for the main Session. The worker keeps files, search, shell, web, skills, todo, and subagents; the router removes writes, web, and subagents, leaving the minimum needed to route.

That means it is not an app you start with node index.js. Reading it requires accepting DSH's session, tool, permission, and workspace model first.

Layers: three dependency rules

The tree has six layers: core, app, executor, sources, infra, and client. What matters is not the folders but three rules.

• Engine alone writes Triggers, Threads, Decisions, Tickets, and Assignments; a Source writes only its cursor and Thread meta.
• Callers receive Pick views such as EngineForSources, EngineForMainSession, EngineForPeople, EngineForSettings, and EngineForExecutor; methods outside a role do not exist in the type.
• core performs no I/O and sources never depend back on app, so the domain rules run against in-memory repositories (src/core/memory.ts).

Code: dependency rules in docs/007-architecture.md:255-274, role interfaces in src/core/engine.ts:261-270, ports in src/core/ports.ts.

Domain model: five aggregates, one main chain

The system has one main chain: Triggers enter a Thread, a batch on that Thread enters Eval, Eval produces a Decision, an accept produces a Mandate and a Ticket, and the Ticket binds an Assignment to an Executor.

1. 01TriggerImmutable event, deterministic id, threads[0] is the primary Thread
2. 02ThreadTimeline plus subscriptions; at most one Eval runs on a Thread
3. 03EvalOne judgment over a batch; records strength, basis, deadline, and primary
4. 04Decisionaccept, ignore, stop, or unavailable, with reasons and audit
5. 05MandateImmutable authorization: strength, policyVersion, basis, actor, scope
6. 06TicketUnit of work; holds Mandate, Channels, Inputs, Assignments, follows
7. 07AssignmentBinds a Ticket to one Executor run; pending → running → ended
8. 08Report / ReplyWorker progress and result; the main Session turns them into human-facing messages

Three shared predicates keep the rules in one place: followupOwners decides which Ticket owns a human message, waitsForPerson decides whether automated input is held, and ticketStage derives the panel stage. The five Engine parts reuse them instead of re-implementing the rules.

Task flow: from a message to a delivery

The task changes carrier and decision maker at every stage. Every later module implements this table.

• An Eval's deadline starts when the candidate reaches the main Session; an undelivered candidate never expires.
• An expired Eval requeues twice; the third expiry records unavailable. A processing pause shifts the deadline forward.
• A Trigger that already started a Ticket cannot start a second one; a repeated accept returns the original Ticket.
• After a Ticket ends, a new human message on its Thread resumes it under the same Mandate, with no new Eval.

Code: src/core/intake.ts:19-62, src/core/evals.ts:71-156, src/core/tickets.ts:37-56, src/core/model.ts:75-88.

Authorization: the model proposes, the host disposes

This is the heaviest part of the project. Authorization is deterministic code in three layers: Gate, admission table, and Mandate. It is not a prompt asking the model to follow rules, and the model proposes only inside that boundary.

Three accept modes decide the fate of inferred candidates: off produces none; observe assesses normally but records only a would_accept audit; auto actually creates Tickets. The default is observe: shadow decisions first.

A Mandate records its basis: source, receiving scope, row, sender, matched rules, and via (addressed, followup, admission, or bot). Before an ended Ticket resumes, revalidate checks that the Source still listens, the sender is still allowed, the admission cell has not weakened, and inferred work still has auto mode with its rules enabled.

Code: gate and revalidate in src/policy.ts:189-240, assessmentOutcome in src/policy.ts:40-61, policyEffects in src/policy.ts:143-165.

Runtime: a two-second clock and durable side effects

Runtime is the composition root and holds no domain rules. It manually builds Store, Setup, Prompts, Effects, SourceRegistry, Sessions, Settings, DshExecutor, MasterAssessor, Outbox, Engine, and Passes in dependency order. Because Executor and Assessor call back into Engine, they receive a getter rather than a constructed object.

Later is the key to this queue: it means the work cannot run now, such as while paused, while slots are full, or while a Source is not installed. It does not count as a failure; it simply reschedules after the initial delay, so normal backpressure never looks like an error.

Side effects land in the database first and execute after commit, so a crash leaves at most a pending row, never an action that happened without a record. That is the basis of recovery.

Execution: one Ticket, one Session, one directory

The worker runs in a DSH Session; its code is not in this repository. The host starts the Session, delivers messages, and collects reports. Investigation, implementation, testing, and PR creation happen in the worker model.

1. 01Accept computes execution metadataShort name, directory, assignment text; creates only a pending Assignment, not the directory
2. 02launch effectRecheck Ticket/Assignment → take a slot → prepare the directory (10-minute limit)
3. 03Create or restore the Sessionworker-<ticketId>, worker preset, role model, prompt/skills/tools, danger-full-access
4. 04First assignment messageAssignment up to 1,500 chars plus the source Trigger and batch; later messages carry only the delta
5. 05Worker turnInvestigate, implement, run checks; long commands go to the background; each Input is visible at the next step
6. 06reportprogress, waiting, ready, blocked, failed, or dropped; questions use attention
7. 07End or continueready, PR close, dropped, or stop ends it; a human message can resume it

Code: src/executor/dsh.ts:97-111, 247-285, 424-470; slots at dsh.ts:165-199; background and handoff at dsh.ts:588-672.

Sources: translating the outside world into Triggers

A Source is a pluggable event adapter. A kind declares its configuration schema, panel fields, listening scope, channel, thread reader, Policy part, environment variables, and health entries. The Registry owns instances, exclusive health claims, and Policy part merging.

A subscribed Thread keeps polling while it has a live Ticket or its last activity or end is within 14 days (POLL_HORIZON_MS). After that window, only ordinary notifications or live events bring new messages.

A Source decides what is pushed. Workers still read what they need with gh or lark-cli; subscriptions only decide which messages are pushed to a Ticket.

Code: the protocol in src/sources/kind.ts, pollRound in src/sources/github.ts:280-296, and the 14-day window in src/sources/poll.ts:6-15.

Model interfaces: 14 + 6 tools and an attention budget

The main Session and workers have separate tool surfaces and prompts. The host separates routing from implementation, so the main Session does not become a second engineer.

Assessment context is deliberately bounded: the Trigger is capped at 4,000 characters; the window is the first five messages plus five on each side of the Trigger, with 1,200 characters for near neighbours, 400 for others, and 50-character stubs; full text requires orchestrator_eval_read by id.

Prompt assembly is fixed: shared → role → three team sections (Communication, Ticket scope, Delivery requirements) → subscriptions → replies → dispatch or work → admission → handoff → execution environment → Policy. Policy always comes last; teams may override built-in parts but not the generated sections.

Code: tools in src/app/tools/main.ts and executor.ts; assessment context in src/app/assessment.ts:36-37,183-220; prompt order in src/app/prompts.ts:102-118; drift checks in tests/model-surface.spec.ts.

What is novel: what is worth copying

Most parts come from mature fields: capability-based authorization, workflow engines, transactional outbox, and event sourcing. What is rare is the combination and the insistence on boundaries in an agent setting.

1. Gate + Mandate + revalidation：It takes who may ask the agent to work out of the prompt and turns it into a versioned, auditable, revocable capability. The host rechecks after the model judges.
2. Follow-up ownership：A human message on a Thread with a Ticket belongs to that Ticket's worker; the main Session may only stop it; the worker may hand it back once. This prevents duplicate dispatch and message stealing, the usual failure of multi-session agents.
3. Observe-mode shadow decisions：Inferred candidates are assessed normally, but the result is recorded only as would_accept; no Ticket is created. Rules are calibrated on real traffic before switching to auto. Rare in agent products, common in operations.
4. Transactional effect queue：Assessment, launch, delivery, relay, notice, and reply all land in SQLite before execution, each with its own concurrency, backoff, and ordering. Agent orchestration gets workflow-engine reliability with one database file.
5. Ticket state independent of its Session：A Ticket can replace Assignments, stay idle after its Session exits, and be resumed by a human message under the same Mandate. The execution instance and the authorization object are separate, so recovery is written down instead of inferred from whether a Session still exists.

Limits: what it explicitly does not solve

The README states that this is a research prototype, not production software, and that some paper designs are not implemented here. Stating the limits clearly matters more than treating it as a platform.

One overlooked cost: the main Session is deliberately kept from reading code. That keeps routing clean, but when an assessment needs technical feasibility, it relies on thread context and limited repository reads; mistakes surface later as a worker handback or drop.

Code index: where to start

With one hour, read in this order. Start with each file's JSDoc, then jump to the core method.

• model.tsDomain types and invariants; start with Trigger, Mandate, Ticket, and Assignment.
• engine.tsThe single write entry; read the role interfaces and each command's JSDoc.
• evals.tsBatching, gate, timeout, and Decision; understand how accept creates a Ticket.
• tickets.tsLifecycle, subscriptions, Inputs, resume/stop/retry; the densest part.
• dsh.tsWhere a Ticket becomes a Session: launch, delivery, slots, recovery.
• effects.tsThe durable effect queue; understand Later and backpressure.
• policy.tsGate, admission, Mandate revalidation, and policyEffects.
• sources/kind.tsThe Source plugin protocol; read the fields and optional capabilities.
• tools/main.tsThe main Session's 14 tools; read alongside prompts/dispatch.md.
• prompts/What the model actually reads; start with shared, orchestrator, dispatch, work, and admission.

The tests are documentation too: tests/core-engine.spec.ts covers domain rules, tests/runtime.spec.ts runs the whole app on a simulated DSH host, and tests/model-surface.spec.ts checks the model-facing surface for drift.

Conclusion: use it as a reference architecture, not a platform

What makes dsh-superagent worth reading is that it decomposes proactivity into auditable steps: who triggers, who authorizes, who executes, and who decides the end. It wraps the model's judgment in deterministic code instead of asking for a smarter model.

It is not a production platform to copy wholesale: no real sandbox, no multi-tenancy, and no data pruning. As a reference architecture, however, it grounds the four hardest parts of a proactive agent (authorization, ownership, recovery, and attention budget) in concrete files and functions.