design(runtime): model subagent orchestration as a supervised stream graph

Problem

Maka already has a bounded Swarm Engine and is considering a first-class Swarm Mode in #1324. That model is a strong leaf executor for a batch of independent child AgentRuns, but multi-stage agent work introduces a different problem:

child work produces messages and lifecycle events over time, not only one final value;
downstream work may become ready after one event, several inputs, a quorum, or a terminal signal;
branches can complete out of order;
semantic problems such as drift, contradiction, weak evidence, or redundant work cannot be detected from dependency counters alone;
concurrency/resource scheduling and graph semantics should not become one monolithic "smart scheduler";
we should not rewrite the existing Agent runtime merely to add graph orchestration.

A conventional agent DAG often models each node as an opaque function and waits for a final result. That discards the most useful property Maka already has: a main agent that understands the user's goal and can monitor, explain, and intervene while child agents work.

Desired outcome

Explore a scheduling model where existing agent activity is projected as a stream-processing graph:

a bounded piece of work performed by a subagent is an operator instance;
each agent message or lifecycle event is a stream record;
edges route records between operators;
each operator owns its local readiness/buffering semantics;
a deterministic graph scheduler manages topology, lifecycle, dependency propagation, and resource permits;
the existing main agent supervises the graph as a semantic control plane on behalf of the user.

The Agent runtime remains the source of truth and continues to own sessions, turns, messages, tool calls, permissions, cancellation, persistence, and child AgentRuns. The graph layer is an adapter/projection over those existing events and invokes existing runtime actions.

Inspiration: Acero's separation of concerns

Apache Arrow Acero is useful here less as an implementation to copy and more as an architectural reference.

Acero does not have a central scheduler that repeatedly scans the whole graph and decides which operator understands the next record. Instead:

The execution plan validates and starts consumers before producers.
Records flow downstream and trigger operator-local state transitions.
Stateful operators buffer input and decide when their own internal work is ready.
Backpressure/cancellation travels upstream.
A separate async task scheduler tracks dynamically created tasks, failures, completion, and resource throttling.

Relevant sources:

The useful principle is:

The graph owns topology and lifecycle; records drive state transitions; operators own readiness; the resource scheduler only schedules runnable work.

Proposed model

flowchart TB
    U["User"] <--> M["Main agent<br/>semantic supervisor"]

    M -->|"create/adjust/control"| G["Graph scheduler<br/>deterministic control"]
    G --> R["Resource scheduler<br/>permits, cost, fairness"]

    R --> A["Existing Agent runtime"]
    A --> O1["Subagent operator A"]
    A --> O2["Subagent operator B"]
    A --> O3["Join / verify operator"]

    O1 --> E["Event stream projection"]
    O2 --> E
    O3 --> E

    E --> G
    E -->|"meta-stream"| M
    G -->|"start/send/resume/cancel via existing APIs"| A

1. Data plane: existing Agent runtime

No new agent loop is required. An operator adapter starts or resumes an ordinary child AgentRun using existing runtime APIs. Messages, tool activity, permissions, and terminal state continue to be persisted by the runtime.

2. Stream projection

Runtime activity is normalized into records such as:

OperatorStarted
MessageProduced
ProgressUpdated
OperatorBlocked
OperatorCompleted
OperatorFailed
OperatorCancelled
ResourceWaiting
BackpressureApplied
GraphQuiescent

A record can carry references instead of duplicating large payloads:

interface AgentStreamRecord {
  graphId: string;
  operatorId: string;
  agentRunId?: string;
  recordId: string;
  parentRecordId?: string;
  type: string;
  logicalTime: number;
  payloadRef?: string;
  status?: string;
  resourceUsage?: unknown;
}

Completion, failure, and cancellation are records too. Unlike Acero's known batch count, agent streams will usually need an explicit terminal record rather than a predeclared total.

3. Operator-local readiness

The graph scheduler should not contain the semantics of every research, review, debate, join, or synthesis node.

Examples:

a map-style operator can act on every incoming record;
a reviewer may wait for one candidate artifact;
a reducer may wait for all declared branches;
a quorum operator may continue after (k) successful results;
a contradiction checker may accumulate evidence until a policy fires;
a pipeline breaker may fully materialize a substream before synthesis.

Each operator updates its state first, then emits records or declares runnable work. This keeps graph mechanics generic and domain semantics local.

4. Separate resource scheduling

Structural readiness does not imply immediate execution.

A resource scheduler can independently enforce:

maximum child concurrency;
per-provider/model limits;
session/global fairness;
token or monetary budgets;
estimated context/memory cost;
Retry-After/backoff;
workspace isolation constraints.

An operator becomes runnable because of graph state; it starts only after acquiring the required permits. This preserves a clean boundary between graph semantics and capacity policy.

5. Main agent as semantic supervisor

This is the key difference from a conventional stream engine.

The main agent subscribes to a meta-stream and can detect conditions a mechanical scheduler cannot:

work is running but drifting from the user's intent;
two branches contradict each other;
evidence is already sufficient and remaining branches can stop;
a failed branch should be reframed or replaced;
a new verification operator is needed;
user input changes the objective;
a partial result should be reported now;
the graph is mechanically active but semantically stuck.

The main agent may emit auditable control records:

AddOperator
CancelOperator
PauseSubgraph
ResumeSubgraph
ChangePriority
RequestMoreEvidence
ReplaceInput
InvalidateResult
AcceptPartialResult

Normal records must not require main-agent approval to reach downstream operators. Otherwise the main agent becomes a serial bottleneck and the graph degenerates into ordinary tool calling. The graph should run autonomously within policy and wake the main agent for semantic decisions, exceptions, milestones, and user communication.

Important semantics to preserve

Ordering is metadata, not global serialization

Child branches should be free to complete out of order. Records can carry logical sequence, partition, and lineage metadata. Only operators that require deterministic order should resequence their input.

Backpressure is a control stream

Backpressure should travel upstream separately from data. It can mean more than queue size:

downstream message backlog;
main-agent review backlog;
provider throttling;
exhausted token/cost budget;
permission waiting;
unavailable workspace isolation.

Pause/resume commands need monotonic versions so stale concurrent control messages cannot overwrite a newer state.

Completion uses structured concurrency

A graph is not finished merely because the root prompt returned. It is finished when:

all non-detached operator work has reached terminal state;
all dynamically created tracked work has settled;
required sink/finalizer work has completed;
no runnable or externally awaited work remains.

The first failure does not always imply one global policy. Operators or subgraphs should explicitly choose fail-fast, all-settled, quorum, retry, partial continuation, or supervisor-decision policies.

Observability is part of the design

Every scheduling and supervisory decision should retain graph/operator/record lineage so Desktop, CLI, Headless, trace, and evidence can answer:

Why did this child start?
Which record made it ready?
Why is it waiting?
Who paused/cancelled/reprioritized it?
Which results contributed to the final response?
Was a decision mechanical, policy-driven, main-agent-driven, or user-driven?

Relationship to #1324

This proposal does not replace the bounded Swarm Engine or block Swarm Mode.

agent_swarm remains a useful bounded leaf executor.
feat: add Swarm Mode as a first-class orchestration policy #1324 remains the product/orchestration policy for deciding when to use that executor.
A future graph operator may invoke a bounded swarm.
This issue explores the layer above individual batches: multi-stage, event-driven, observable orchestration with main-agent supervision.

It should remain a follow-up design effort; #1324 correctly keeps a general DAG engine out of its first delivery.

Non-goals

Rewriting the Agent runtime or introducing a second source of truth.
Making every agent token pass through a central LLM scheduler.
Requiring the main agent to approve normal record delivery.
Copying Acero's APIs or assuming Arrow batches match agent messages.
Implementing arbitrary cyclic/distributed stream processing in the first iteration.
Hiding scheduling state only inside prompts.
Silently widening child permissions.

Suggested investigation path

Define a read-only event projection over current AgentRun and message state.
Build a trace-only graph visualizer from real Swarm runs, without changing execution.
Specify the minimal record envelope and operator lifecycle.
Prototype two operator types over existing runtime APIs:
- map/fan-out;
- all-settled or quorum join.
Add a deterministic replay test: the same persisted event sequence should reconstruct the same graph state.
Expose the meta-stream to the main agent and prototype one auditable intervention, such as adding a verification branch.
Evaluate resource permits independently from graph readiness.
Only then decide whether any runtime-facing contract is missing.

Open questions

What is the correct record granularity: every message, semantic message boundaries, tool transitions, or a configurable projection?
Which graph mutations may the main agent perform without additional user authorization?
How should graph state be reconstructed after crash/resume without duplicating side effects?
When should a subagent be a long-lived operator versus one operator activation?
How should backpressure interact with permission waits and human input?
Which policies are deterministic runtime policy and which require main-agent judgment?
Can cyclic conversational patterns be represented initially as repeated activations over an acyclic execution graph?

Definition of a successful design

A prototype can observe existing AgentRuns as a stream graph, reconstruct graph state from durable events, automatically run simple fan-out/join work through existing runtime APIs, keep resource scheduling separate, and allow the main agent to monitor and perform one traceable semantic intervention without becoming the data-path bottleneck or requiring an Agent runtime rewrite.

中文设计说明

问题

Maka 已经拥有有界的 Swarm Engine，并在 #1324 中讨论 first-class Swarm Mode。它很适合作为“一批彼此独立的 child AgentRun”的叶子执行器，但多阶段 Agent 工作还有另一类问题：

child 在运行过程中持续产生消息和生命周期事件，而不只是一个最终结果；
下游可能在收到一条消息、多个输入、达到 quorum，或者看到终止信号后才 ready；
多个分支会乱序完成；
偏离用户目标、证据薄弱、结果矛盾、重复劳动等语义问题，无法仅靠依赖计数器发现；
图语义和并发/资源调度不应被揉成一个无所不知的“智能调度器”；
我们不应该为了图调度去重写现有 Agent runtime。

传统 Agent DAG 往往把节点当成一个输入输出函数，只等待最终结果。这样会丢掉 Maka 已有的关键能力：主 Agent 理解用户目标，能够在 child 工作期间持续监控、解释和干预。

期望结果

探索一种把现有 Agent 活动投影为流处理图的调度模型：

subagent 执行的一项有界工作是一个 operator instance；
每条 Agent 消息或生命周期事件是一条 stream record；
edge 负责在 operator 之间路由 record；
每个 operator 自己拥有 readiness、buffering 和局部状态语义；
确定性的 graph scheduler 负责拓扑、生命周期、依赖传播和资源许可；
现有主 Agent站在图之上，代表用户充当语义监督控制面。

Agent runtime 继续作为唯一事实来源，负责 Session、Turn、Message、工具调用、权限、取消、持久化和 child AgentRun。Graph 层只是在既有事件之上的 adapter/projection，并通过既有 runtime action 启动、恢复、发消息或取消 AgentRun。

Acero 带来的启发

Apache Arrow Acero 值得借鉴的不是 API，而是关注点分离：

ExecPlan 校验图，并按 consumer 先于 producer 的顺序启动。
Record 向下游流动，触发 operator-local 状态转换。
Stateful operator 自己缓冲输入，并判断内部工作何时 ready。
Backpressure、cancel、stop 沿图向上游传播。
独立的 async task scheduler 负责动态任务、失败、完成和资源节流。

最重要的原则是：

Graph 负责拓扑与生命周期；record 驱动状态转换；operator 拥有 readiness；resource scheduler 只调度已经 runnable 的工作。

建议模型

1. 数据平面：继续使用现有 Agent runtime

不增加第二套 agent loop。Operator adapter 使用既有 runtime API 创建或恢复普通 child AgentRun。消息、工具活动、权限和终止状态仍由 Runtime 持久化。

2. Stream projection

把运行活动规范化为 record，例如：

OperatorStarted
MessageProduced
ProgressUpdated
OperatorBlocked
OperatorCompleted
OperatorFailed
OperatorCancelled
ResourceWaiting
BackpressureApplied
GraphQuiescent

Record 应优先保存 payload reference，而不是复制大块正文。建议至少包含：

graphId / operatorId / agentRunId
recordId / parentRecordId
recordType / logicalTime
payloadRef / status / resourceUsage

完成、失败、取消也都是 record。Agent stream 通常无法像 Acero 一样提前知道 batch 总数，因此更适合使用显式 terminal record。

3. Operator-local readiness

Graph scheduler 不应该理解 research、review、debate、join、synthesis 的全部业务语义。

map operator 可以对每条输入行动；
reviewer 等待一个候选 artifact；
reducer 等待所有声明分支；
quorum operator 在成功数达到 k 后继续；
contradiction checker 持续积累证据直到策略触发；
pipeline breaker 完整物化一个子流后再综合。

Operator 应先原子地更新自己的局部状态，再 emit record 或声明 runnable work。这样 scheduler 保持通用，领域语义留在 operator 内。

4. 图 readiness 与资源调度分离

结构上 ready 不代表立刻执行。独立 resource scheduler 可以控制：

最大 child 并发；
provider/model 限额；
Session 与全局公平性；
token、金额和上下文预算；
Retry-After 与退避；
workspace isolation 条件。

Operator 因图状态而 runnable，拿到 permit 后才真正启动。这样资源策略不会污染图语义。

5. 主 Agent作为语义 supervisor

这是它与普通流引擎最不同、也最独特的部分。

主 Agent订阅 meta-stream，可以发现机械调度器无法理解的问题：

工作仍在运行，但已经偏离用户意图；
多个分支互相矛盾；
证据已经足够，可以提前停止剩余分支；
失败分支应该换一个问题重新执行；
需要追加验证或反驳 operator；
用户中途修改目标；
应该立即给用户阶段性结果；
图在机械上活跃，但语义上没有进展。

主 Agent的干预也应成为可审计 control record：

AddOperator
CancelOperator
PauseSubgraph
ResumeSubgraph
ChangePriority
RequestMoreEvidence
ReplaceInput
InvalidateResult
AcceptPartialResult

正常数据不应等待主 Agent逐条批准，否则主 Agent会成为串行瓶颈，graph 退化成普通工具调用。图应在策略边界内自主运行，只在语义决策、异常、里程碑和用户沟通时唤醒主 Agent。

需要保留的重要语义

顺序是 metadata，不是全局串行化

Child 分支可以乱序完成。Record 携带 logical sequence、partition 和 lineage；只有确实要求确定性顺序的 operator 才进行 resequence。

Backpressure 是反向控制流

Backpressure 不只意味着队列长度，还可以来自：

下游消息积压；
主 Agent审阅积压；
provider 限流；
token/cost budget 耗尽；
permission wait；
workspace isolation 不可用。

Pause/resume 应带单调递增版本，避免旧的并发控制消息覆盖新状态。

完成采用 structured concurrency

Root prompt 返回不代表 graph 已完成。只有在非 detached operator、动态派生工作、sink/finalizer 全部 settled，且没有 runnable 或等待中的外部工作时，graph 才完成。

失败策略不应全局写死。Operator 或 subgraph 可以显式选择 fail-fast、all-settled、quorum、retry、partial continuation 或 supervisor-decision。

可观测性属于设计本身

Trace/evidence 应能回答：

为什么这个 child 被启动？
哪条 record 使它 ready？
它为什么在等待？
谁暂停、取消或调整了优先级？
哪些结果贡献了最终回答？
决策来自机械规则、资源策略、主 Agent还是用户？

与 #1324 的关系

本方案不会替代或阻塞 Swarm Engine / Swarm Mode：

agent_swarm 继续作为有界叶子执行器；
feat: add Swarm Mode as a first-class orchestration policy #1324 继续定义产品层何时采用 Swarm；
未来某个 graph operator 可以调用 bounded swarm；
本 issue 研究的是 batch 之上的层：多阶段、事件驱动、可观测、由主 Agent监督的 orchestration。

因此它应作为 #1324 之后的独立设计方向，不能扩大 #1324 首轮交付范围。

非目标

重写 Agent runtime 或建立第二份事实来源；
让每个 token 都经过中央 LLM scheduler；
要求主 Agent批准正常 record 传递；
原样复制 Acero API；
首轮实现任意 cyclic/distributed stream processing；
把关键调度状态只藏在 prompt 中；
静默扩大 child 权限。

建议调研与原型路径

在现有 AgentRun 和 Message 之上建立只读事件投影。
用真实 Swarm run 构建 trace-only graph visualizer，不改变执行。
定义最小 record envelope 和 operator lifecycle。
通过现有 runtime API 原型化 map/fan-out 与 all-settled/quorum join。
加入 deterministic replay：相同持久化事件序列必须重建出相同 graph state。
把 meta-stream 暴露给主 Agent，并实现一次可审计干预，例如追加验证分支。
独立评估 resource permit，而不是把它混入 readiness。
最后再判断现有 Runtime 是否真的缺少必要契约。

开放问题

Record 粒度应该是每条消息、语义消息边界、工具状态转换，还是可配置 projection？
哪些 graph mutation 可由主 Agent自主执行，哪些需要用户授权？
Crash/resume 后如何重建 graph，同时避免重复副作用？
Subagent 应该是长生命周期 operator，还是一次 operator activation？
Backpressure 如何与 permission wait 和 human input 结合？
哪些策略必须确定性执行，哪些必须交给主 Agent判断？
对话式循环能否先表示为无环执行图上的重复 activation？

成功设计的定义

原型能够把既有 AgentRun 观察为 stream graph；根据持久化事件重建 graph state；通过现有 runtime API 自动运行简单 fan-out/join；保持 resource scheduling 与 graph readiness 分离；并允许主 Agent执行一次可追踪的语义干预，同时不成为数据路径瓶颈，也不要求重写 Agent runtime。

Been thinking through the architecture of this proposal and ran into a few tensions that feel worth discussing early — sharing as open questions, not objections. The layering itself (projection over RuntimeEvent, LLM at the edges, resource permits separated) feels right; most of the friction shows up where the Acero analogy meets agent reality.

1. Projection vs authority. While the graph is read-only, "pure projection, runtime as single source of truth" holds. Once the scheduler drives execution (start/cancel/pause), its decisions gain causal authority: after a crash you must know whether a CancelOperator took effect, so control decisions need to be durable, idempotent, and part of recovery. That seems to force a choice — either control facts enter the RuntimeEvent authority model (the runtime has to understand graph concepts), or the graph keeps its own control facts (a second source of truth). Is the honest framing maybe "two authority domains with an explicit boundary" rather than "one source of truth + projection"?

2. Pause semantics for non-pausable producers. Acero's backpressure assumes producers pause cheaply. An agent's upstream is a mid-generation LLM plus side-effecting tools; pausing record consumption doesn't pause the provider stream. For agents, "stop" is nearly synonymous with cancel. Maybe the honest move is to give up mid-flight pause and split backpressure into two mechanisms: admission control (withhold permits, don't start — lossless, cheap) for throttling/budget/concurrency pressure, and cancel + safe resume (lossy, expensive) for semantic stops. The existing safe_replay/blocked revalidation and ToolRecoveryMode machinery already looks like it's building toward the second half. Monotonic pause/resume versions stay useful — for the admission side, not a true pause.

3. Completion predicate needs a protocol. "Done when all non-detached work is settled" is a predicate; the hard part is keeping it stable. If a sink declares completion the same moment the supervisor sends AddOperator, who wins? AcceptPartialResult / CancelOperator / child-terminal concurrency needs conflict rules and idempotency keys, plus an explicit topology-closed / admission-closed signal — maybe a two-phase "closing the graph" step.

4. Synthesized terminal records. The issue notes agent streams need explicit terminal records (unlike Acero's known batch count). But who emits the terminal record when an operator process dies? The scheduler presumably needs liveness detection (heartbeats/timeouts) to synthesize one, or structured-concurrency completion waits forever. That machinery has real semantics — how long before an operator is declared dead vs partitioned? — and isn't in the design yet.

5. Supervisor liveness. Moving approval off the data path is right, but "main agent detects a semantically stuck graph" assumes someone wakes it. If the supervisor is throttled, crashed, or simply never scheduled, a stuck graph stays stuck — unless the deterministic layer gets timeout fallbacks, at which point the deterministic layer is doing supervision and the LLM becomes advisory. Maybe the answer is worth stating explicitly: the deterministic layer owns liveness supervision (stuck detection, timeouts); the LLM owns semantic judgment on escalation only.

6. Pipelining vs the partial-event contract. RuntimeEvent's contract says partial chunks are excluded from model history and superseded by later events. If operators consume partials, downstream can act on input that "never existed," threatening replay. This seems avoidable by declaring operator inputs = committed (non-partial) facts only — pipelining still works at message/artifact granularity. Residual questions: does compaction ever rewrite facts a downstream operator already consumed (lineage validity after compaction)? Are committed facts stable across resume/replay?

7. Control vocabulary bandwidth. The supervisor intervenes through a fixed verb set, while its semantic bandwidth is free text. Every new intervention type means record type + scheduler semantics + replay support, in lockstep — the classic DSL-rigidity path. Is there an escape hatch, e.g. a generic advisory record carrying free-text guidance into an operator's input, keeping the typed vocabulary only for lifecycle actions?

None of these feel like blockers to the layering — they feel like the places where the design earns its next level of precision. Especially curious how you're thinking about 1 and 2.

中文对照

在琢磨这个提案的架构时碰到几个值得早讨论的 tension——作为开放问题分享，不是反对意见。分层本身（基于 RuntimeEvent 的投影、LLM 在边缘、资源 permit 分离）感觉是对的；摩擦主要出现在 Acero 类比碰上 agent 现实的地方。

1. 投影 vs 权威。 图只读时，"纯投影、runtime 唯一事实来源"成立。一旦调度器驱动执行（启动/取消/暂停），它的决策就有了因果权威：崩溃后必须知道 CancelOperator 是否生效，这要求控制决策持久化、幂等、参与恢复。这似乎逼出一个二选一——要么控制事实进入 RuntimeEvent 权威模型（runtime 被迫理解图概念），要么图自己存控制事实（第二事实来源）。更诚实的框架或许是"两个权威域 + 显式边界"，而不是"单一事实来源 + 投影"？

2. 不可暂停生产者的 pause 语义。 Acero 的背压假设生产者可以廉价暂停。Agent 的上游是正在生成的 LLM 和有副作用的工具；暂停 record 消费并不能暂停 provider 流。对 agent 来说，"停"几乎就是取消的同义词。也许诚实的做法是放弃中途暂停，把背压拆成两种机制：入场控制（不发 permit、不启动——无损、便宜）承接限流/预算/并发压力；取消 + 安全 resume（有损、昂贵）承接语义停止。现有的 safe_replay/blocked revalidation 和 ToolRecoveryMode 看起来已经在为后一半铺路。单调递增的 pause/resume 版本号仍然有用——用于入场控制一侧，而不是真正的 pause。

3. 完成判定需要协议。 "所有非 detached 工作 settled 才算完成"是个谓词；难的是让它稳定。如果 sink 宣布完成的同一瞬间 supervisor 发来 AddOperator，谁赢？AcceptPartialResult / CancelOperator / child 终止并发时需要冲突规则和幂等键，外加显式的 topology-closed / admission-closed 信号——也许需要一个两阶段的"关闭图"步骤。

4. 代发终止 record。 Issue 指出 agent 流需要显式终止 record（不像 Acero 预知 batch 总数）。但 operator 进程死了，谁替它发终止 record？调度器大概需要活性检测（心跳/超时）来代发，否则结构化并发的完成条件永远等不到。这套机制有真实的语义——多久算 operator 死亡 vs 分区？——目前还不在设计里。

5. 监督者活性。 把审批移出数据路径是对的，但"主 agent 检测语义卡住"假设了有人唤醒它。如果监督者被限流、崩溃或就是没被调度，卡住的图永远卡住——除非确定性层加超时兜底，而那样确定性层就已经在做监督，LLM 退化为顾问。也许答案值得写明：确定性层负责活性监督（卡住检测、超时），LLM 只负责升级后的语义判断。

6. Pipelining vs partial 事件契约。 RuntimeEvent 契约规定 partial chunk 不进模型历史、会被后续事件取代。如果 operator 消费 partial，下游可能基于"从未存在"的输入行动，威胁重放。声明 operator 输入仅限 committed（非 partial）事实似乎可以规避——pipelining 在消息/产物粒度上依然成立。剩余问题：compaction 会不会改写下游已消费的事实（compaction 后的 lineage 有效性）？committed 事实在 resume/replay 中是否稳定？

7. 控制词汇表带宽。 Supervisor 只能通过固定动词表干预，而它的语义带宽是自由文本。每加一种干预类型 = record 类型 + 调度器语义 + replay 支持三处联动——经典的 DSL 僵化路径。有没有逃生舱，比如一个通用的 advisory record 把自由文本指导带进 operator 输入，把类型化词汇表只留给生命周期动作？

这些都不是分层的 blocker——它们是设计走向下一层精度的地方。特别想听听你对 1 和 2 的想法。

feat(runtime): derive operator-local graph readiness (#1446)

Proposed delivery path after #1468

The graph work has reached an important boundary: the durable data-plane loop is largely in place, and #1468 closes the supervisor schedule-to-runtime loop for operators that already exist in a Session-backed topology.

After #1468, I propose keeping the path to a first playable Desktop Graph Mode deliberately narrow. Resource permits, global fairness, arbitrary cyclic topology, full backpressure, and a node-canvas UI should not block the first usable integration.

PR 1 — Dynamic operator bootstrap

Turn scheduled agent_id work into a real Session-backed operator instead of returning agent_topology_required.

create a linked child Session from the trusted catalog agent snapshot;
assign stable graph/operator identities and bind the operator to that Session;
add the minimal monotonic topology extension needed to connect the requested input frontier;
re-enter the existing schedule reconciler so the new operator uses the same durable claim and child-Session execution path;
make crash/retry idempotent across child creation, topology publication, claim admission, and first Runtime activation;
keep arbitrary edge deletion, cycles, and general topology rewriting out of this slice.

Exit condition: a supervisor schedule can request work by agent_id, materialize the operator, and execute it without any pre-created child Session fixture.

PR 2 — Host-managed graph coordinator

Compose the existing graph primitives into one recoverable lifecycle owned by the runtime host / Desktop main process.

bind one graph lifecycle to its root supervisor Session;
provide trusted graphId, stores, topology, executor, and observation context;
expose view_agent_graph and update_agent_graph only to the bound main-agent supervisor;
trigger reconciliation after durable schedule updates and relevant committed Runtime facts;
ensure only one coordinator drives a graph at a time while allowing multiple clients to observe it;
recover active graphs after restart and integrate stop/archive/session termination;
retain the rule that supervisor observation is beside the data path, never an approval gate.

This is the main difference from Swarm: agent_swarm is an exclusive tool contained in one root turn, while a graph is a host-managed, recoverable object that may span several supervisor decisions.

Exit condition: Headless/runtime-host can start, observe, stop, restart, and continue a complete graph invocation without test-only composition.

PR 3 — Graph read model and client boundary

Give Desktop and future clients an authoritative graph-facing API instead of making renderers reconstruct topology from raw Session events.

Suggested surface:

graphs.getSnapshot(rootSessionId)
graphs.subscribe(rootSessionId)
graphs.inspectOperator(operatorId)
graphs.stop(...)

The bounded snapshot should include:

operators and directed edges;
running, waiting, blocked, and terminal state;
operator-local readiness / wait reasons;
durable scheduled work and stop/replace status;
child Session and AgentRun references;
the latest relevant supervisor control decisions;
opaque pagination for large terminal history.

The subscription must support reconnect and replay from durable state. Multiple Desktop, TUI, Headless, or remote clients should be able to observe the same host-owned graph without becoming execution authorities.

Exit condition: a client can reconnect to an active or completed graph and reconstruct the same bounded view without scanning JSONL or inferring state from presentation events.

PR 4 — Desktop Graph Mode MVP

Add the first user-facing integration, reusing the outer interaction patterns already established by Swarm Mode.

add a trusted graph orchestration mode at Session and one-turn override boundaries;
add Composer toggle and /graph on, /graph off, /graph <task> entry points;
handle pending/running/waiting restrictions and localized error/status copy;
display a compact live graph card/list with operator status, wait reason, progress, and selected results;
let users open the linked child Session for an operator;
expose stop/finish state without requiring a full node-canvas editor;
add Desktop host contracts, renderer tests, localization tests, and reconnect/restart coverage.

Exit condition — first playable Graph Mode: from an ordinary Desktop conversation, the user can enable Graph Mode, ask for a multi-stage task, watch the main agent supervise dynamically created operators, open their child Sessions, survive a Desktop restart, and receive the final selected results.

Optional PR 5 — Full graph visualization and interactive inspection

This is an experience layer, not a blocker for the MVP.

node/edge canvas or scalable graph explorer;
record lineage and “why ready / why waiting” explanations;
activation, usage, tool activity, and artifact drill-down;
schedule/control history showing whether decisions came from deterministic policy, the main agent, or the user;
incremental layout, pagination, and large-graph performance.

Explicitly deferred from the playable path

The following remain valuable but orthogonal follow-ups:

resource permits, provider/model limits, and cross-Session fairness;
token/cost budgeting beyond the existing hard activation bound;
arbitrary topology deletion, rewiring, or cycles;
true mid-flight pause for non-pausable LLM/tool producers;
a complete backpressure policy;
a polished graph canvas.

For the first Desktop delivery, the existing maxNewActivations structural bound plus current Session/runtime cancellation semantics are sufficient. These four required slices keep the correctness boundary reviewable while avoiding another long detour before users can actually exercise the graph.

中文方案

#1468 之后的建议交付路径

Graph 已经走到一个重要边界：durable data-plane loop 基本完成，#1468 会把 supervisor schedule 对“已有 Session-backed operator”的 stop、replace、start 真正转成 Runtime action。

接下来应该把“第一次可以在 Desktop 玩到 Graph Mode”的路径刻意收窄。Resource permits、全局公平性、任意有环动态图、完整 backpressure 和节点画布都不应成为首次可用版本的 blocker。

PR 1 — 动态 Operator Bootstrap

把 schedule 中的 agent_id work 从 agent_topology_required 变成真实的 Session-backed operator：

从可信 catalog agent snapshot 创建 linked child Session；
分配稳定的 graph/operator identity，并绑定到该 Session；
只实现连接请求输入 frontier 所需的单调 topology 扩展；
回到现有 schedule reconciler，继续复用 durable claim + child Session execution；
保证 child 创建、topology 发布、claim admission 和首次 Runtime activation 跨 crash/retry 幂等；
不在这一刀实现任意删边、环或通用 topology 重写。

完成标准： supervisor 可以直接按 agent_id 请求新工作，无需预先准备 child Session fixture，就能物化并执行 operator。

PR 2 — Host-managed Graph Coordinator

把现有 graph primitives 组合成 runtime host / Desktop main 拥有的可恢复生命周期：

graph lifecycle 与 root supervisor Session 绑定；
提供可信的 graphId、store、topology、executor 和 observation context；
view_agent_graph / update_agent_graph 只暴露给绑定的主 Agent；
durable schedule 更新或相关 committed Runtime fact 到达时触发 reconcile；
同一 graph 只允许一个 coordinator 驱动，但允许多个 client 旁观；
支持重启恢复，并接入 stop/archive/session termination；
supervisor 继续站在数据路径旁边，而不是正常 record delivery 的审批门。

这也是 Graph 和 Swarm 最关键的差异：agent_swarm 是一个 root turn 内的 exclusive tool；Graph 是 host-managed、可恢复、可能跨多次 supervisor 决策的长期对象。

完成标准： Headless/runtime-host 不依赖测试拼装即可启动、观察、停止、重启并继续完整 graph invocation。

PR 3 — Graph Read Model 与 Client Boundary

给 Desktop 和未来 client 一个权威 Graph API，不让 renderer 扫描 SessionEvent 自己猜 topology：

graphs.getSnapshot(rootSessionId)
graphs.subscribe(rootSessionId)
graphs.inspectOperator(operatorId)
graphs.stop(...)

有界 snapshot 至少包含：

operators 与有向 edges；
running、waiting、blocked、terminal；
operator-local readiness / wait reason；
durable schedule work 与 stop/replace 状态；
child Session / AgentRun 引用；
最近相关 supervisor control decision；
大量 terminal history 的 opaque pagination。

订阅需要支持 reconnect，并从 durable state 重放。同一个 host-owned graph 可以被 Desktop、TUI、Headless 或 remote client 同时观察，但 client 不成为 execution authority。

完成标准： client 重连 active/completed graph 后，无需扫描 JSONL 或依赖 presentation event 推测，就能恢复同一个有界视图。

PR 4 — Desktop Graph Mode MVP

复用 Swarm Mode 已建立的外层交互形式，接入第一次真正可玩的用户路径：

Session 与单 turn override 增加可信的 graph orchestration mode；
Composer toggle，以及 /graph on、/graph off、/graph <任务>；
pending/running/waiting 限制和中英文状态/错误文案；
用紧凑的 live graph card/list 展示 operator 状态、等待原因、进度和选中结果；
点击 operator 可以打开对应 child Session；
展示 stop/finish 状态，但不要求先做完整节点画布；
增加 Desktop host contract、renderer、localization、reconnect/restart 测试。

首次可玩完成标准： 用户从普通 Desktop 对话开启 Graph Mode，提交多阶段任务，观察主 Agent 监督动态创建的 operators，打开各 child Session，经历 Desktop restart 后继续观察，并最终收到选中的结果。

可选 PR 5 — 完整 Graph Visualization

这属于体验增强，不阻塞 MVP：

node/edge canvas 或可扩展 graph explorer；
record lineage 与“为什么 ready / 为什么 waiting”；
activation、usage、tool activity、artifact 下钻；
标注调度决定来自确定性 policy、主 Agent 还是用户；
增量布局、分页和大图性能。

明确不阻塞首次可玩的后续项

resource permit、provider/model 限额和跨 Session 公平性；
超出 hard activation bound 的 token/cost budget；
任意 topology 删除、重连或环；
对不可暂停 LLM/tool producer 的真正 mid-flight pause；
完整 backpressure policy；
精致的 graph canvas。

首次 Desktop 交付使用现有 maxNewActivations 结构上限与 Session/runtime cancellation 已经足够。这四个必需 PR 能让 correctness 边界保持可 review，同时避免再次绕很久才让用户真正玩到 Graph。

design(runtime): model subagent orchestration as a supervised stream graph #1341

Description

Problem

Desired outcome

Inspiration: Acero's separation of concerns

Proposed model

1. Data plane: existing Agent runtime

2. Stream projection

3. Operator-local readiness

4. Separate resource scheduling

5. Main agent as semantic supervisor

Important semantics to preserve

Ordering is metadata, not global serialization

Backpressure is a control stream

Completion uses structured concurrency

Observability is part of the design

Relationship to #1324

Non-goals

Suggested investigation path

Open questions

Definition of a successful design

问题

期望结果

Acero 带来的启发

建议模型

1. 数据平面：继续使用现有 Agent runtime

2. Stream projection

3. Operator-local readiness

4. 图 readiness 与资源调度分离

5. 主 Agent作为语义 supervisor

需要保留的重要语义

顺序是 metadata，不是全局串行化

Backpressure 是反向控制流

完成采用 structured concurrency

可观测性属于设计本身

与 #1324 的关系

非目标

建议调研与原型路径

开放问题

成功设计的定义

Activity

Astro-Han commented on Jul 22, 2026

likun666661 commented on Jul 25, 2026

Proposed delivery path after #1468

PR 1 — Dynamic operator bootstrap

PR 2 — Host-managed graph coordinator

PR 3 — Graph read model and client boundary

PR 4 — Desktop Graph Mode MVP

Optional PR 5 — Full graph visualization and interactive inspection

Explicitly deferred from the playable path

#1468 之后的建议交付路径

PR 1 — 动态 Operator Bootstrap

PR 2 — Host-managed Graph Coordinator

PR 3 — Graph Read Model 与 Client Boundary

PR 4 — Desktop Graph Mode MVP

可选 PR 5 — 完整 Graph Visualization

明确不阻塞首次可玩的后续项

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions