Orchestrated Dispatch Design

[devxiyang]

Orchestrated Dispatch Design

Goal

Extend agent-dispatch from a single-task durable runner into a general orchestration framework for AI agent backends.

The framework should support:

• parent / child / merge task orchestration
• isolated execution environments
• durable state and recovery
• prompt-driven decomposition and coordination
• artifact-based aggregation

This design is intentionally not code-task specific. Code generation is one important use case, but not the only one.

---

Design Principles

1. Runtime provides primitives, prompts provide intelligence

The Rust runtime should stay small and reliable.

Runtime responsibilities:

• durable task state
• parent / child relationships
• execution environments
• artifact storage
• mailbox / escalation channels
• task lifecycle and recovery

Prompt responsibilities:

• deciding whether to split work
• drafting child briefs
• defining coordination contracts
• deciding when to escalate
• defining merge / aggregation behavior

2. Hard protocol, soft policy

Some things must be enforced by the framework:

• where artifacts live
• how child tasks are linked to a parent
• how escalation works
• how completion is marked
• how environments are provisioned

Most higher-level collaboration behavior should remain prompt-driven:

• how to decompose work
• what boundaries to choose
• what contracts matter
• how detailed merge logic should be

3. Treat outputs as artifacts, not only model replies

Each task should produce durable artifacts.

Examples:

• output.md
• summary.json
• report.yaml
• patch.diff
• generated directories
• references to an isolated worktree

Merge tasks should consume artifacts, not conversation memory.

4. Worktree is an environment strategy, not the framework itself

For repo-writing tasks, git worktree is a strong default isolation model.

But the orchestration framework should support multiple environment kinds:

• none
• workspace
• git_worktree
• filesystem_copy
• artifact_only
• external

---

Core Concepts

Task roles

A task may play one of these roles:

• Standalone
• Parent
• Child
• Merge

Shared context

A parent task may define shared context consumed by all child tasks.

Examples:

• global objective
• constraints
• input resources
• terminology
• assumptions
• shared protocol notes

Child brief

Each child task gets its own brief.

A brief may include:

• local objective
• scope / boundaries
• allowed resources
• expected outputs
• contract notes
• escalation instructions

Environment

Each task may request an execution environment.

The runtime provisions it and records it durably.

Aggregation

A merge task reads child artifacts and produces a parent-level result.

Aggregation is general:

• summary
• structured merge
• decision
• integration
• publish

---

Suggested Data Model

Task role metadata

Add orchestration metadata to task state.

Example shape:

orchestration:
  role: Standalone | Parent | Child | Merge
  parent_task_id: <uuid?>
  child_task_ids: [<uuid>...]
  depends_on: [<uuid>...]
  merge_task_id: <uuid?>

Environment spec

environment:
  kind: none | workspace | git_worktree | filesystem_copy | artifact_only | external
  source: optional source reference
  writable_scope: optional restrictions
  exported_paths: optional artifact paths
  cleanup_policy: retain | cleanup_on_success | cleanup_on_completion

Contract spec

contract:
  objective: string
  scope: list
  constraints: list
  inputs: list
  outputs: list
  shared_protocols: list
  escalation_policy: string

Artifact manifest

Each task should be able to publish a manifest describing its outputs.

Example:

{
  "kind": "code-change",
  "summary": "implemented auth adapter",
  "artifacts": [
    "output.md",
    "patch.diff",
    "test-report.md"
  ],
  "environment": {
    "kind": "git_worktree",
    "path": "..."
  }
}

---

Artifact Protocol

A parent task should be able to create and read orchestration artifacts under its task directory.

Suggested layout:

.dispatch/tasks/<parent-id>/
  shared-context.md
  orchestration/
    plan.md
    children/
      child-auth.brief.md
      child-ui.brief.md
    manifests/
      child-auth.json
      child-ui.json
    merge-brief.md

Each child task still has its own normal task directory.

Suggested child additions:

.dispatch/tasks/<child-id>/
  brief.md
  manifest.json
  output.md
  context.md
  mailbox/

---

Escalation Protocol

Child tasks should not silently expand scope or rewrite shared contracts.

If a child finds a conflict, ambiguity, or missing dependency, it should escalate.

Examples:

• interface mismatch
• boundary is too narrow
• required input missing
• another child likely owns the change
• parent decision needed

The runtime should only provide the channel.
The prompt defines how and when to use it.

Possible implementation:

• child writes a mailbox question
• parent or user answers
• parent may update shared context and re-dispatch affected children

---

Environment Strategy

Generic model

A task may request an isolated mutable sandbox when needed.

git_worktree

Recommended default for repository-writing tasks.

Why:

• strong isolation between child tasks
• independent diffs
• easier integration later
• lower risk of shared workspace corruption

Suggested behavior:

• create a worktree per child task
• record the worktree path in task artifacts / manifest
• let the child work only inside that environment
• keep the worktree for debugging unless cleanup is requested

Other environment kinds

• workspace: use current workspace directly
• filesystem_copy: for non-git writable tasks
• artifact_only: for read/summarize/report tasks
• none: for pure coordination / merge tasks that only read artifacts

---

Execution Flow

Phase 1: parent planning

1. Create a parent task in orchestrate mode.
2. The parent agent reads the user request.
3. The parent decides whether to stay standalone or split.
4. If splitting, the parent produces:
   • shared-context.md
   • child briefs
   • optional merge brief
   • optional environment requests

Phase 2: child execution

1. Runtime reads child briefs.
2. Runtime creates child tasks.
3. Runtime provisions environments for each child.
4. Child tasks execute independently.
5. Child tasks publish artifacts and manifests.
6. Child tasks escalate through mailbox when required.

Phase 3: merge / aggregation

1. Runtime creates a merge task when dependencies are satisfied.
2. Merge task reads:
   • shared context
   • child manifests
   • child outputs
   • optional environment references
3. Merge task produces final parent-level output.

---

Status Semantics

Parent tasks need derived status semantics.

Suggested rules:

• any child Failed -> parent Failed or AwaitingUser depending on escalation policy
• any child AwaitingUser -> parent AwaitingUser
• any child Running -> parent Running
• all children Completed, merge not complete -> parent Running
• merge Completed -> parent Completed

This should be implemented as aggregation logic over child task state, not inferred from chat history.

---

First Version Scope

In scope

• parent / child / merge task roles
• orchestration artifacts
• shared context + child brief files
• child task creation from parent-generated briefs
• git_worktree environment support
• artifact manifest support
• merge task creation after children complete
• mailbox-based escalation

Out of scope

• arbitrary DAG scheduling
• automatic conflict resolution
• child-to-child direct messaging
• sophisticated resource schedulers
• policy-heavy decomposition logic in Rust
• code-specific orchestration rules baked into runtime

---

Why this fits agent-dispatch

The current project already has the right foundation:

• durable task store
• resumable sessions
• append-only event logs
• mailbox protocol
• backend abstraction

This design keeps those strengths and adds orchestration without turning the runtime into a giant heuristic engine.

The long-term shape should be:

• reliable runtime primitives in Rust
• smart orchestration behavior in prompts
• optional policy layers for specialized workflows

In short:

The framework handles reliable execution. The prompts handle intelligent coordination.