dsh-superagent source analysis

dsh-superagent Source: Trigger, Ticket, Policy & Subscription

Author
DeepSeekAgent.io Editorial Team
Published
Updated

The most important contribution in dsh-superagent-prototype is not another wrapper around Subagents. It is a domain model for a long-running Agent. Messages, authority, work, execution, and recovery become persistent concepts; the model participates only where semantic judgment is needed.

This article follows one event from intake to completion through Source, Trigger, Thread, Eval, Policy, Mandate, Ticket, Assignment, and Subscription.

Source: where events enter

A Source is an event-stream implementation plus one configured instance. The prototype includes GitHub and optional Feishu Sources. A Source owns read positions, converts external events into immutable Triggers, maps them to Threads and reply Channels, and removes the Agent's own messages or events outside its configured scope.

It is therefore an integration boundary, not merely a webhook handler.

Trigger and Thread: event versus context

A Trigger is an immutable event with actor and Source metadata. A Thread is an ordered sequence of Triggers, such as an issue, a pull-request review thread, or a Feishu topic.

One Trigger may correlate several Threads, but correlation adds context only. It does not grant authority. Seeing related information is deliberately separate from receiving permission to start work.

Eval: deciding whether work should exist

A Trigger not owned by an existing Ticket enters Eval. Eval has two layers:

  1. a deterministic Gate checks sender identity, mention state, allowed lists, receiving scope, and the admission table;
  2. a model Assessment decides whether an inferred candidate matches an enabled proactive rule.

Eval records a Decision: accept, stop, ignore, or unavailable. Explicit requests can be routed directly. Inferred proactive candidates need assessment, and the default observe mode records a positive result without creating a Ticket.

Policy and Mandate: who authorized what

Policy contains Source-specific allowed lists, admission tables, bot lists, proactive rules, and accept mode. Every change creates a Policy version.

An accepted Decision creates a Mandate that records the version, Source and sender, explicit or inferred strength, allowed scope, and matched rules. The Mandate is the Ticket's authority. A Worker may process follow-ups inside that scope but cannot expand it because a comment asks for unrelated work.

Ticket: durable work, not a model call

A Ticket is an authorized unit of work. It can outlive multiple Assignments while retaining Channels, Inputs, Subscriptions, and references to Decisions. Restarting or replacing an Executor does not delete the task.

Ticket state is also independent of Session state. A Ticket can wait for a person or review, resume after a follow-up, and continue under a new Assignment without pretending that one model turn is the entire lifecycle.

Assignment and Executor: who runs this attempt

An Assignment binds a Ticket to one Executor instance. Each Ticket has an isolated Worker Session and directory. A retry ends the current Assignment and begins another on the same Ticket, directory, branch, and pull request.

Workers report progress, waiting, ready, blocked, failed, or dropped. Pull-request state, human follow-ups, and unread Inputs all affect whether the Ticket is actually finished.

Subscription: routing later events

Subscription is the many-to-many relation between Tickets and Threads. When a Ticket follows an issue and its pull request, later comments, CI results, and reviews return to the same Worker.

Subscription adds context but does not grant new authority. An out-of-scope human request is handed back to the Router for a new Eval. Ended Tickets may retain subscriptions so a later human follow-up can resume the work; bots and CI do not wake ended Tickets on their own.

Why this model supports continuity

Conventional agents often keep operational state inside conversation history. dsh-superagent stores critical facts explicitly:

  • Source stores the external cursor;
  • Trigger stores the original event;
  • Decision stores why the event was accepted or ignored;
  • Mandate stores authority;
  • Ticket stores the work lifecycle;
  • Assignment stores each execution attempt;
  • Subscription stores future routing.

The model handles semantic decisions and implementation; the host handles idempotence, authority, and recovery. Continuity comes from this structure, not an infinitely long context window.

One GitHub issue end to end

GitHub comment
  → Source records Trigger
  → Thread groups issue context
  → Gate checks sender and mention
  → Eval records accept Decision
  → Mandate stores scope and Policy version
  → Ticket is created
  → Assignment starts an Executor Session
  → Worker prepares a directory and opens a PR
  → Ticket subscribes to the PR Thread
  → review and CI Triggers return to the Ticket
  → PR closes and Ticket ends
  → a later human follow-up may resume it

That sequence is also the most useful reading order: begin with 001-domain.md, continue through authorization and execution, then inspect Source, storage, and panel code.

Related reading

References