Skip to main content

Orchestration

The DSH chat agent is the game master. Characters, the record keeper, world and plot authors, image presenter, chronicler, and suggestion writer are bounded one-shot children. Their stable persona and tool list form a cacheable prefix; only the request-specific brief changes.

Turn protocol​

An ordinary turn follows this order:

  1. Validate the input and assemble the scene.
  2. Require judge_action before simulation. The ruling checks every world and player rule and distinguishes an impossible attempt from a forbidden command.
  3. Optionally publish a short scene preview.
  4. activate_characters selects reachable characters and asks each for a structured intent, optional utterance, and commitment.
  5. resolve_round records each outcome, public state, movement, and item operations. A failed, high-commitment character may retry once with the first attempt's outcome.
  6. Apply deterministic movement and item validation, commit visible state, run triggers, and enqueue the round for durable records.
  7. Repeat within maxRounds, or call narrate.
  8. Check that accepted utterances appear once, verbatim, and in order. After two refused repairs the engine repairs the payload itself.
  9. Return <roleplay-output> JSON to the renderer and record the turn exactly once.

Later rounds receive earlier outcomes from the same turn. Relationships influence activation priority, context, and recall cues; they are not a second action system.

/ooc starts a separate out-of-character turn. It requires ooc_ruling, cannot activate characters, and may decree state only after a legal ruling. Its effects still use ordinary validation, records, perceptions, snapshots, and narration.

/ask starts an out-of-character question turn. ooc_answer is its only action, and the answer is written by an agent that is given only what the player's character knows, so the game master cannot give away what is hidden: no ruling, no round, no preview, no time, no creation; narrate then delivers no segments and the answer rides in TurnOutput.ooc with question.

judge_action may name the place where the action happens (at, a place key). When the player's character is in another place that neither contains nor is inside it, the action is judged not to work whatever the game master said, with the reason that the character has to go there first. A character in no place, or a world without places, is no evidence and never blocks.

Background boundary​

Narration is the user-visible completion boundary. Record keeping, consolidation, off-stage action, suggestions, and images continue afterwards. Work that reads or changes story state calls TurnEngine.settle before proceeding; a later turn waits for an earlier failed record run and retries it once. Pending work is persisted, so restart, rewind, and branch do not silently lose it.

Triggers are evaluated at turn start, after every committed round, and after a time skip. Fired cues go only to their audience; pending beats must be explicitly addressed by narration and expire according to settings.

Child agents​

runChild starts a child through DSH's public sub-agent activation under the roleplay-helper preset, registers only its scoped tools, validates submit_result, enforces a call budget (once it is used up the child's other tools are withdrawn, so that a model made to call a tool at every step can only submit; it is stopped if it still does not within three steps), and reminds a child that stops before submitting. This is intentionally used instead of globally exposing character-specific tools such as recall_my_memories.

Order of fields. In every tool schema and helper answer, a field that others depend on comes before them: a selector that shapes what follows (who is asked, where the action happens) before the text it shapes, reasoning before the verdict it supports, and an amount after what it measures (how long a round took after its outcomes). A character first writes a short first-person thought. It is optional and read by no one, so an engine that does not write fields in order, or a model that leaves it out, gives the same result; the order is a best effort that costs nothing when it is not respected (a backend may sort the fields alphabetically or follow the order of earlier calls in the conversation; thought is asked for as required but not enforced when the answer is checked).

Sizes. Every text of a character's answer states its limit in the instructions (ANSWER_LIMITS, by language) and the most a request may produce is estimated from those limits: outputBudget(estimate, sampling.headroom), never more than the ceiling sampling.shortMaxTokens or sampling.maxTokens. A helper whose answer has no declared size uses the ceiling.

Faults are not story. A character that could not act because of a fault of the system is not recorded and the game master is not given the reason, only that nothing is to be written for it; the reason goes to the log and the run's record. Characters are shown names (with pronouns), never keys, and never the number of a turn or round.

Keep personas and tool declarations stable. Put changing scene data in the user brief. A tool must enforce every authority and consistency rule in code; prompt instructions are not a security boundary.

Extension seams​

The orchestration service exposes replaceable boundaries including activation planning, character context, output validation, retry policy, input validation, authoring, committing, narration, narration checking, and scene context. Replace the smallest boundary that owns the behaviour. Preserve its error semantics, cancellation, output schema, and lifecycle registration.

When adding a tool or stage, verify ordinary turns, OOC turns, retries, rewind, branch, cancellation, hot reload, and prefix stability. See DSH contracts before changing child composition or chat persistence.

The turn engine specification records the complete tool sequence, movement, items, time, routines, preview, suggestions, triggers, timeline operations, and timing boundaries.