You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maka.apache.org by "chinawch007 (via GitHub)" <gi...@apache.org> on 2026/10/02 05:58:36 UTC
Re: [D] [Discussion] Condition-driven waiting and wake-up for Sessions [maka]
GitHub user chinawch007 edited a discussion: [Discussion] Condition-driven waiting and wake-up for Sessions
I would like to discuss a concrete implementation path for condition-driven waiting and wake-up: replace model-driven status checks and long-held tool calls with structured waits owned by Runtime Host, then continue the original work through existing execution admission when an actionable result becomes available.
This is not a new workflow engine or a replacement for Goal, Session, Turn, or recovery authority. The near-term target is a common mechanism with **ShellRun, GitHub CI, PR/review state, and external-file readiness** adapters. The interfaces and PR boundaries below are proposals, not implemented APIs or an approved design.
## 1. Motivation: distinguish three ways of waiting
A common development task is to change code, push, and wait for CI. In one such execution, the agent first repeatedly scheduled `sleep → query GitHub`, then switched to a polling loop inside a single script. Both approaches kept the same execution Turn open.
Maka also has a separate path: after a Turn settles, the Goal evaluator can return `waiting`, and an exponential timer schedules another execution to check again. The current interval starts at 5 seconds and is capped at 5 minutes; the timer itself does not verify CI.
By **Host observation with condition-driven continuation**, I mean handing the wait to background code that does not depend on model reasoning: the agent declares a resource and a condition, Host saves that declaration, and the current execution can end. Host then receives notifications or reads source state periodically. Only a matching result, timeout, or actionable exception requests a follow-up under existing execution rules.
For example, when waiting for CI on a specific commit, background code distinguishes “still running” from “finished”; the model need not return periodically to ask. When CI finishes, Host delivers the commit identity, result, and log references to the original Session so the model can analyze them or verify completion. This continues the original task rather than keeping a tool call open throughout the wait.
| Approach | Model work while nothing changes | Execution and recovery |
| --- | --- | --- |
| Model-scheduled checks, or periodic Goal rechecks | May repeatedly invoke the model and process the same context | The former holds an execution open; the latter creates check executions |
| Polling inside one foreground tool script | No model call for each script iteration | The tool has not returned, so the current execution remains open |
| Host observation with condition-driven continuation | No work-model calls for unchanged observations | The current execution can end; the wait remains durable and a result later enters admission |
The benefits are fewer unnecessary model calls, releasing an execution slot held only for waiting, and consistent cancellation, deadlines, recovery, and result delivery.
More concretely:
- **Less model work without new information.** Avoid repeatedly feeding “CI has not finished” back to the model just to decide to wait again, along with repeated tool decisions and low-value context. The model primarily participates in registering a wait and handling a meaningful result.
- **Separate unfinished work from occupied execution.** The current execution can end while the Goal and wait remain. The system can then handle subsequent work or user input under existing admission rules without keeping an execution active solely to wait.
- **Return results to the correct task.** Bind the wait to a Session, objective, and resource version. This avoids manual status relaying and scripts that finish with output but no defined continuation path.
- **Make long waits manageable.** Users and Host can identify the target, deadline, blocking reason, and cancellation action. After restart, source facts can be rechecked under existing recovery policy rather than relying on the model to reconstruct the earlier intent.
- **Reuse reliability rules across sources.** ShellRun, CI, and files should not each invent duplicate handling, stale-version filtering, deadlines, and delivery tracking. New integrations can concentrate on source-specific condition semantics.
Compared with repeated model-scheduled checks, the main gain is less unnecessary reasoning and context processing. Compared with a single polling script, it is primarily releasing execution occupancy, durable waiting, and reliable continuation.
There is also a separate accounting issue: check Turns settled through the normal waiting path can consume Goal work iterations. It is the Turn—not each HTTP request—that counts. Work iterations and wait lifetime should be separate, but removing the former bound must coincide with a TTL, observation limits, and a wake bound. We must not introduce an unbounded intermediate behavior.
## 2. Proposed architecture and model interaction
The core needs three responsibilities, not three independent execution systems:
```text
User task → model proposes a structured wait
↓
Host validates, persists, and yields execution
↓
Source adapter: notification / polling / reconciliation
↓
Verify condition, resource version, and control identity
↓
Persist result and its link to existing continuation
↓
Existing Session execution admission → next model execution
```
### Model-facing entry point
Provide a high-level tool, provisionally `WaitForEvent`. The model should not have to compose “create watcher, save continuation, suspend Session” correctly.
Illustrative request:
```json
{
"source": "shell_run",
"resource": {"taskRef": "maka://runtime/background-tasks/task-123"},
"condition": {"type": "terminal", "version": 1},
"timeoutSeconds": 3600
}
```
The model proposes a resource and condition. Host binds Session, Turn, Goal identity, and permissions from trusted call context. If the condition already holds, the result can be delivered immediately; otherwise Host registers the wait and yields the current execution. **Yielding must be a runtime control operation, not merely text asking the model to stop.**
The initial registration acknowledgement is separate from the eventual result. On delivery, the model receives the original objective, wait reason, resource version, and bounded evidence references. Timeout, failure, cancellation, or invalidation may also require handling. A wake is not proof that the overall goal succeeded.
### Host-side capabilities to add and connect
This section describes changes in Runtime Host and the state it exposes to clients. Adapters are its integration layer for individual sources, not another execution backend.
- **Manage durable wait records.** Host stores task ownership, resource identity, condition version, deadline, cancellation, and delivery linkage to answer “who is waiting for what, and is this wait still valid?” Reference existing conversation and task results rather than duplicating history, logs, or credentials. Invalidation, Session removal, and expiry also need defined cleanup.
- **Unify observation transports.** Adapters handle authentication, reads/subscriptions, and source-specific condition results. ShellRun can combine terminal notifications with record reads, CI can use API queries, and files can use notifications plus scanning. Host manages observation startup, cancellation, frequency, deadlines, and recovery; adapters own SHA, run-attempt, and file-readiness semantics.
- **Connect explicit waits to existing Goal control.** Registration must allow the current execution to end correctly and prevent legacy waiting timers or evaluator failures from bypassing the wait. Link results to existing `pendingContinuation` and execution identity rather than maintaining a competing running/pending authority.
- **Deliver results reliably without taking over admission.** Persist recoverable delivery intent before requesting execution through existing root-Turn admission. Defer while the Session is busy and recheck eligibility if the Goal was paused or replaced. After restart, reconcile already-admitted execution under existing policy so one result is neither lost nor executed twice.
- **Expose understandable state and controls.** Project the resource, latest observation, deadline, source errors, and delivery progress to clients, with cancellation controls. Clients should distinguish waiting on a condition, waiting for admission, and processing a result. Unchanged checks should not generate notifications or mislabel inactive waiting as running or requiring user action.
## 3. Correctness and lifecycle requirements
1. **Reconcile current facts first.** A condition may hold before registration. Close the read/subscribe race with reconciliation, cursors, or a source-specific protocol.
2. **Deduplicate at two boundaries.** Repeated intake of one event differs from distinct events satisfying one wait. Start with one-shot subscriptions: at most one effective successor per subscription.
3. **Fence by identity and version.** Old SHAs, run attempts, Goal generations, and cancelled subscriptions must not start current work.
4. **Preserve pending, failed, and unknown outcomes.** A network error is not CI failure; a lost process handle is not proof of process death; a missing file is not proof its producer stopped.
5. **Make delivery recoverable.** Crashes between condition resolution, durable intent, and admission must not silently lose delivery or duplicate effective execution. Do not promise exactly-once arbitrary external side effects.
6. **Integrate with Goal scheduling.** A legacy waiting timer or evaluator failure must not bypass an explicit wait. Real model executions still use normal accounting and settlement.
7. **Bound lifetime and resources.** TTL bounds duration, backoff bounds query frequency, and a wake limit bounds successor executions. They are not interchangeable. Restart must not reset the absolute deadline.
8. **Multiple events do not imply concurrent root executions.** Observe concurrently, then aggregate or queue results. Define aggregation, early completion, and cancellation of remaining observations at registration.
“Any success / all success / any failure” is not a complete generic condition language. PR closure can satisfy a condition without representing business success; collecting test results may require all tasks to reach a terminal state. Start with a few deterministic templates: one task becoming terminal, all conditions in a declared set being satisfied, all tasks settling, and CI-specific fail-fast aggregation. Do not expose arbitrary expressions.
## 4. Scope and restart boundaries
### Existing mechanisms to cover or preserve
| Existing scenario | Treatment |
| --- | --- |
| CI, PR state, and explicit file conditions | Replace with structured observation and continuation |
| A registered wait on a background ShellRun | Consume reliable terminal facts and deliver its result |
| Goal waiting without an identifiable condition | Keep the fallback; do not guess a subscription |
| Session admission's `whenIdle` | Reuse as admission infrastructure, not a regular event source |
| Graph supervisor wake | Do not migrate wholesale; Graph terminal facts could become an adapter later |
| Permission prompts, AskUserQuestion, forms | Preserve existing interaction and authorization authority |
| ScheduledTask time triggers and short tool requests | Do not reimplement |
| Unknown side effects after ordinary execution crashes | Do not replace runtime recovery with event waiting |
A ShellRun is a command managed by Maka's process manager with a task record. Built-in foreground and background Bash use this path, but helper processes inside other tools, remote jobs, and external user terminals are not automatically equivalent wait targets. Background tasks are the initial focus; not every command completion should invoke the model.
### Condition categories in the near-term scope
| Category | Included? | Example and boundary |
| --- | --- | --- |
| Existing standard events | Yes | A CI run becomes terminal, a PR merges, a managed command exits |
| New conditions over general-purpose data | Yes, through supported bounded templates | A completion marker appears; manifest entries and checksums match; an explicit CSV set contains required columns |
| Conditions requiring semantic understanding | No, not as near-term watcher predicates | “The supplier's reply adequately explains the failure” |
| Conditions currently unobservable | No | Verbal approval with no connected record |
The model may propose parameters for a data condition; Host validates them and runs deterministic checks. This does not permit arbitrary model-generated observer code. “No directory changes for five minutes” proves a stability interval, not that every expected upload finished. Reject or clarify conditions that cannot be expressed or verified.
### Preserve current product behavior after interruption
**This change does not redefine when continuation or rerunning requires approval.** It restores wait facts, checks source state, and hands valid results to existing Session/Goal control and recovery:
- Follow existing paths when they permit a valid continuation.
- Do not bypass an existing confirmation requirement or a paused Goal because an event arrived or Host restarted.
- Re-observe a still-running task; deliver a terminal result; retain explicit diagnostics for unknown state.
- Do not redispatch an old command merely because a ShellRun is `orphaned`, unreachable, or missing a result.
Recovering a wait is not recovering a process or granting retry authority. Automatic replay of side-effecting operations is not an implicit promise of this optimization.
## 5. Security and authorization
Validate four separate capabilities: **registering a wait, observing a source, creating a follow-up, and performing concrete actions**.
- The model proposes a resource and condition; it cannot establish permission using `userAuthorized: true`. Host supplies trusted identity and policy context. Reuse the existing confirmation mechanism where confirmation is required.
- Enforce repository, path, Session, and ShellRun visibility. Knowing a task ID does not make a user-owned terminal readable by the model.
- Keep credentials in existing credential management and persist references only. Comments, logs, and event payloads are untrusted data, not new instructions or authorization.
- Recheck control identity and scope at registration and admission to handle replacement, revocation, and late events.
- A conservative option for initial follow-ups is `analyze-only`: verification, analysis, and reporting only. If adopted, enforce this boundary through actual capabilities, not prompting alone.
- Subscription does not authorize code modification, commit, push, or merge. Carrying an existing Goal's action authorization into an external follow-up needs an explicit policy decision, not an implicit MVP expansion.
This does not alter the general permission mode of existing Goals. It prevents a new wake entry point from bypassing it.
## 6. Architecture acceptance criteria
The first user-visible slice should satisfy at least:
| Scenario | Required invariant |
| --- | --- |
| External state remains unchanged | No repeated work-model execution; observation respects TTL and frequency limits |
| Registration yields | The current execution ends correctly rather than holding a tool call open |
| Duplicate or equivalent notifications | No duplicate effective successor for a one-shot wait |
| Completion precedes or races registration | Current-state reconciliation prevents a missed delivery |
| Old versions, cancellation, pause, archive | No stale work starts and no user control is undone |
| Session is busy | Existing admission serializes or coordinates execution |
| Restart between resolution and admission | Durable wait/delivery identity is recovered under existing recovery policy |
| Source unavailable or outcome unknown | No false satisfaction and no blind replay |
| Idle waits no longer consume work iterations | Independent wait bounds are active; real model work remains budgeted |
| A second provider is added | No provider-specific core fields or changes to the Session wake protocol |
| Conversation and UI | Waiting, admission, execution completion, and goal achievement remain distinct |
Compare the same real scenario before and after implementation: model calls, tokens, API requests, detection-to-admission latency, missed/duplicate deliveries, and user intervention. The research does not establish numerical performance gains; baseline measurements and implementation tests must do that.
## 7. Near-term plan: three core PRs and four adapter PRs
Split the core around three independently testable questions: **how to retain a wait, how to decide it has a result, and how to return that result to the original task**. The first three PRs establish the protocol with test sources. The fourth proves a user-visible ShellRun flow before adding external adapters.
### PR 1: contracts and persistence—retain what we are waiting for
Define and persist the resource, condition version, task ownership, deadline, cancellation, and delivery identity. Handle duplicate registration, stale updates, Session cleanup, and schema migration so later components read one authoritative record rather than maintaining separate in-memory copies.
- **Validation:** creation, cancellation, and reopening storage preserve the record and its validity; duplicate registrations and old revisions cannot overwrite newer state.
- **Boundary:** no production watchers or model calls. Deliver contracts required by the following PRs, not a speculative general workflow schema.
### PR 2: Host observation and condition management—observe without model work
Introduce the adapter interface and wait manager for initial reads, notifications, background polling, TTL, limits, cancellation, and startup reconciliation. Adapters return explicit condition outcomes and the manager persists them; this layer does not start the model directly.
- **Validation:** use a controlled clock and fake providers for already-completed conditions, unchanged state, duplicate notifications, source outages, and restart. Verify no missed results, unbounded queries, or treating failed reads as satisfied conditions.
- **Boundary:** no real GitHub credentials or public notification service yet. Deliver results to test consumers, keeping observation separate from execution admission.
### PR 3: execution bridge and Goal integration—admit one effective follow-up
Connect wait registration, yielding the current execution, blocking unconditioned Goal continuation, and result delivery. Reuse existing continuation and root-Turn admission, carry typed provenance, and check current Goal validity, permissions, and Session availability.
Integrate normal budget accounting and settlement, including replacement limits when idle waits stop consuming work iterations. Reconcile crash windows such as a saved result whose execution has not been admitted; do not create another background execution queue.
- **Validation:** use real admission with a fake model to exercise “register → current execution ends → no model calls without change → condition resolves → one effective successor,” including pause, cancellation, busy admission, and restart.
- **Boundary:** do not expose the production tool before a real source is ready. Do not redefine existing recovery approval or replay policy.
### PR 4: ShellRun—ship the first usable long-task wait
Let the model register waits on background ShellRuns it is authorized to observe, consuming reliable terminal facts and result references. Completion, failure, cancellation, and `orphaned` state need explicit outcomes. If the task finished before registration, read the existing record rather than waiting for another notification.
Expose the tool, minimal status display, and cancellation so users can actually “run tests and continue handling the result when finished.” Keep resource-cleanup callbacks in their existing role and do not turn every command completion into a model wake.
- **Validation:** long-test results return to the correct Session; duplicate notifications do not duplicate execution; cancelled waits stay cancelled; restart follows task facts and existing policy.
- **Boundary:** do not restart commands merely because a process handle was lost, or assume helper processes and external user terminals are observable ShellRuns.
### PR 5: GitHub CI—apply the same protocol to a remote condition
Add explicitly authorized GitHub connections and API observation bound to repository, head SHA, and run/attempt, with defined run-terminal or check-set conditions. Handle success, failure, cancellation, throttling, credential loss, and offline reconciliation without letting old commits trigger current work.
- **Validation:** deliver results for the current target; stale SHAs, repeated state, and query errors do not cause incorrect wakes; no Webhook setup is required. As the second source, GitHub must not require provider-specific core fields or a new wake protocol.
- **Boundary:** define “this run is terminal” separately from “all required checks satisfy the policy,” rather than hiding both behind an ambiguous “CI complete.”
### PR 6: PR/review—reuse GitHub integration for collaboration conditions
Build on existing authentication, observation, and identity handling to support merge, closure, review arrival, and explicit approval conditions. Registration binds the target PR and applicable revision, identity, or role requirements; the adapter verifies them.
- **Validation:** distinguish closed-without-merge, approval arrival, and current merge requirements. Historical reviews or dismissed approvals must not be mistaken for current valid facts.
- **Boundary:** match structured collaboration events, not whether a maintainer “truly agrees with the design.” Pass comment content to subsequent analysis without treating it as authorization.
### PR 7: file readiness—deterministic conditions for externally delivered data
Combine filesystem notifications with current-state scans for completion markers, explicit manifests, and a small set of bounded checks—for example, declared files with matching checksums or an explicit CSV set containing required columns. The model supplies template parameters, not arbitrary observer scripts.
- **Validation:** recheck readiness when files predate registration, writes are incomplete, notifications are missed, files are replaced, or Host restarts. Path permissions remain enforced.
- **Boundary:** creation is not complete writing, and a quiet directory is not complete delivery. Without a completeness contract, report pending or unknown rather than guessing.
PRs 1–3 separate responsibilities, not authorities. PRs 3 and 4 may merge if that makes review easier; keep the series close enough to avoid long-lived unused abstractions. Reuse execution persistence and outbox ownership rather than adding an independent wake database or a second execution queue.
**Deduplication, cancellation, deadlines, permissions, and restart safety ship with the first usable slice.** They are not post-release hardening for a version that can lose wakes or wait indefinitely. Accounting changes may land at integration, but replacement bounds must become effective with them.
Goal is a reasonable first execution consumer. If ordinary Session follow-ups must also ship initially, define their ownership and admission tests explicitly rather than assuming coverage. Additional sources, transports, and implementation precedents are in the [appendix](./event-wakeup-research-appendix.en.md).
<details>
<summary>中文说明(点击展开)</summary>
我想讨论一条条件驱动等待与唤醒的具体实施路线:将“等待外部条件”从模型反复查询或长时间挂起的工具调用,转为 Runtime Host 管理的结构化等待;有值得处理的新结果时,再经现有执行入口继续原任务。
这不是另建一套工作流引擎,也不替换现有 Goal、Session、Turn 或恢复权威。短期希望完成共同机制,并接入 **ShellRun、GitHub CI、PR/review 状态和外部文件就绪**。以下接口和 PR 划分是讨论建议,尚未实现或形成维护共识。
## 1. 为什么改:三种等待方式的区别
一个实际开发流程是:修改代码、push,然后等待 CI。在一次这样的执行中,先多次由模型安排 `sleep → 查询 GitHub`,后来改为一个脚本内部轮询;两种方式都发生在同一个尚未结束的 Turn 内。
Maka 也已有另一条路径:Turn 结束后,Goal evaluator 判断 `waiting`,退避定时器再安排一次执行检查条件。当前退避为 5 秒起、最高间隔 5 分钟;定时器本身并不核验 CI。
这里提出的“**Host 观测+条件驱动恢复**”,是把等待交给不依赖模型推理的后台程序:Agent 登记“等待哪个对象、什么条件成立”,Host 保存这份记录,当前执行即可结束。之后由 Host 接收通知或定期读取状态,只有条件满足、超时或出现需要处理的异常时,才按现有规则安排后续执行。
例如等待指定提交的 CI,后台程序负责辨认“仍在运行”与“已结束”;模型不必每隔一段时间回来询问。CI 结束后,Host 将对应提交、结果和日志引用交给原 Session,由模型继续分析或核验任务是否完成。这里恢复的是原任务的后续执行,不是把一个长时间未返回的工具调用继续挂着。
| 方式 | 无变化时的模型参与 | 执行占用与恢复 |
| --- | --- | --- |
| 模型逐次安排查询,或 Goal 定时重查 | 可能重复调用模型、处理相同上下文 | 前者保持当前执行;后者不断创建检查执行 |
| 单个工具脚本内部轮询 | 脚本循环不调用模型 | 工具未返回,当前执行仍未结束 |
| Host 观测+条件驱动恢复 | 无变化时不调用工作模型 | 当前执行可以结束;等待事实保留,结果到来后再接纳后续执行 |
主要收益是减少无效模型调用、释放纯等待占用的执行位置,以及统一等待的取消、期限、恢复和结果交付。
具体来说:
- **减少没有新信息时的模型工作。** 不再反复把“CI 还没结束”送回模型,让它重新决定是否继续等;同时减少重复工具调用和低价值上下文。模型主要在登记等待和处理有意义的结果时参与。
- **将任务未完成与当前执行占用分开。** 当前执行可以结束,Goal 和等待记录仍然存在。这样系统可以按既有接纳规则处理后续工作或用户输入,不必用一个活跃执行维持单纯的等待。
- **让结果自动回到正确的任务。** 等待绑定具体 Session、目标与资源版本,避免用户手工搬运状态,也避免临时脚本结束后只有一条输出、却没有明确的接续路径。
- **让长时间等待可管理。** 用户和 Host 能知道在等什么、等到何时、为何受阻,以及如何取消。重启后可重新核验事实并沿用现有恢复策略,不依赖模型重新猜测之前的等待意图。
- **让新来源复用同一套可靠性规则。** ShellRun、CI 和文件无需各自实现重复通知、旧版本过滤、超时和交付跟踪;后续接入主要聚焦来源自身的条件语义。
相对模型反复查询,收益主要体现在减少无效推理与上下文处理;相对单个脚本内部轮询,收益更集中在释放执行占用、持久化等待和可靠接续。
还有一个独立问题:当前按正常 waiting 路径结算的检查 Turn 仍可能消耗 Goal 工作轮次。这里计入轮次的是 Turn,不是每次 HTTP 请求。应将工作轮次与等待期限分开,但取消旧的轮次消耗时,必须同时提供 TTL、观测限制和唤醒次数上限,不能产生无界等待。
## 2. 建议的架构与模型交互
核心应有三个职责,而不是三个独立的执行系统:
```text
用户任务 → 模型提出结构化等待
↓
Host 校验、持久化、让出当前执行
↓
来源适配器:通知 / 轮询 / 断线补查
↓
核验条件、对象版本和当前控制身份
↓
持久化结果与既有 continuation 的关联
↓
现有 Session 执行接纳 → 后续模型执行
```
### 模型入口
提供一个高层等待工具,例如暂称 `WaitForEvent`。不要求模型组合“创建 watcher、保存 continuation、暂停 Session”等底层操作。
示意请求:
```json
{
"source": "shell_run",
"resource": {"taskRef": "maka://runtime/background-tasks/task-123"},
"condition": {"type": "terminal", "version": 1},
"timeoutSeconds": 3600
}
```
模型提出等待对象与条件;Host 从可信调用上下文绑定 Session、Turn、Goal 身份和权限。条件已满足时可以直接交付结果;否则登记等待并让出当前执行。**让出必须是运行时控制行为,不能仅靠工具文本要求模型“不要继续”。**
“已登记”等初始回执与未来的最终结果分离。结果到达后,模型获得原目标、等待原因、资源版本和有界证据引用,继续在原权限范围内处理。超时、失败、取消或条件失效也可以是需要处理的结果;唤醒不等于目标成功。
### Host 后台需要增加和衔接的能力
这一部分描述 Runtime Host 的后台改动,以及它向客户端提供的状态;适配器是其中面向具体事件来源的接入层,不是另一个执行后台。
- **管理持久化的等待记录。** Host 需要保存所属任务、资源身份、条件版本、期限、取消状态和交付关联,回答“谁在等什么、这份等待现在是否仍有效”。记录应引用已有会话和任务结果,而不是复制完整历史、日志或凭据;目标失效、Session 删除或等待过期时,还需按规则回收。
- **统一接入不同的观测方式。** 适配器负责认证、查询或订阅,并把来源事实解释成受支持的条件结果。例如 ShellRun 使用终态通知加记录读取,CI 使用 API 查询,文件使用通知加扫描。Host 统一管理观测的启动、取消、频率、期限和恢复,适配器负责 SHA、run attempt、文件就绪等专属语义。
- **把明确等待接到已有 Goal 控制上。** 登记成功后,应让当前执行正确结束,并阻止旧 waiting timer 或 evaluator 失败路径绕过等待。等待结果需要关联已有 `pendingContinuation` 和执行身份;不能为了方便再维护另一套“正在运行/等待执行”的权威状态。
- **可靠交付结果,而不直接抢占执行。** 条件满足时,先保存可恢复的交付意图,再通过已有 root-Turn admission 请求执行;Session 忙时等待接纳,Goal 已暂停或被替换时重新判断资格。重启后也沿用现有恢复策略核验已接纳的执行,避免同一结果丢失或启动两次。
- **提供可解释的状态与控制入口。** Host 应向客户端投影等待对象、最近观察、截止时间、来源异常及交付进展,并提供取消等操作。客户端据此区分“等待条件”“等待执行接纳”“正在处理结果”,不把每次无变化检查都变成通知,也不把静止等待误显示为运行或必须由用户处理。
## 3. 正确性与生命周期注意事项
1. **先核验当前事实。** 条件可能在登记前已经满足;订阅与读取之间的竞态也必须通过补查、游标或来源协议闭合。
2. **两层去重。** 重复接收同一事件与不同事件满足同一等待是两种问题。初期建议 one-shot:一份订阅至多产生一个有效后继执行。
3. **绑定正确版本。** 旧 SHA、旧 run attempt、旧 Goal generation 或已取消订阅,不能启动当前任务。
4. **区分未满足、失败与未知。** 网络错误不等于 CI 失败;丢失进程句柄不证明进程死亡;未出现文件不证明生产者中断。
5. **结果交付可恢复。** 条件满足、保存恢复意图、执行接纳之间的崩溃不能造成静默丢失或重复有效执行。不承诺任意外部副作用的端到端 exactly-once。
6. **显式等待约束 Goal 调度。** 旧 waiting timer 或 evaluator 调用失败,不能绕过有效等待直接继续。实际模型执行仍须进入正常预算与结算路径。
7. **限制生命周期与资源。** TTL 限制等多久,退避限制查多频繁,唤醒上限限制创建多少次执行;三者不能互相替代。重启不应重置绝对截止时间。
8. **多个事件不等于多个并发执行。** 可同时观察多个对象,但结果须聚合或排队。登记时明确聚合语义、提前结束和剩余观察的取消规则。
多条件不宜只用“any 成功/all 成功/any 失败”概括所有来源。PR 关闭是条件满足,不一定是业务成功;汇总测试还需要“全部进入终态”。短期可提供少量确定模板,例如单任务终态、明确集合全部满足、全部终态,以及 CI 的“任一 required check 失败,或全部通过”,不开放任意表达式。
## 4. 修改范围与中断恢复边界
### 覆盖什么,不覆盖什么
| 现有场景 | 本次处理方式 |
| --- | --- |
| 等 CI、PR 状态、明确文件条件 | 转为结构化条件观测与恢复 |
| 明确登记等待的后台 ShellRun | 消费可靠终态事实,完成后交付结果 |
| 无可识别条件的 Goal waiting | 保留兼容行为,不猜测其等待对象 |
| Session 执行通道的 `whenIdle` | 直接复用,属于接纳基础,不迁成普通事件源 |
| Graph supervisor wake | 不整体迁移;以后可消费 Graph 终态 |
| 权限请求、AskUserQuestion、表单 | 保留既有交互和授权权威 |
| ScheduledTask 时间调度、短工具请求 | 不重新实现 |
| 普通执行崩溃后的未知副作用恢复 | 不由事件等待框架取代 |
ShellRun 指经 Maka 受管进程管理器执行、具有任务记录的命令。内置 Bash 的前台与后台都走这条路径,但其他工具内部的进程、远端 job、用户外部终端不自动成为同类等待对象。首期重点是后台任务;不应把所有命令完成都转换成模型唤醒。
### 短期支持的条件类别
| 类别 | 是否纳入 | 示例与边界 |
| --- | --- | --- |
| 已有标准事件 | 是 | CI run 终态、PR merged、受管命令结束 |
| 通用数据上的新条件 | 是,以受支持的有界条件模板表达 | 完成标记出现;manifest 文件齐全且校验通过;明确 CSV 清单均具备所需列 |
| 需要语义理解 | 否,不作为短期 watcher 的条件判定 | “供应商回复是否足以解释故障” |
| 目前无法观察 | 否 | 未接入任何记录的口头批准 |
通用数据条件可以由模型提出参数,再由 Host 校验并执行确定性检查;不是允许模型提交任意观察代码。“目录安静五分钟”只能证明稳定期,不能擅自等同于“所有文件已经上传”。无法表达或验证的条件应明确拒绝或请求澄清。
### 中断后沿用现有产品逻辑
**本次不重新定义是否自动续跑或重跑的产品策略。** 新机制负责恢复等待事实、核验来源状态,并交给现有 Session/Goal 控制与恢复路径:
- 现有策略允许有效 continuation 继续时,沿用该路径。
- 现有策略要求人工确认,或 Goal 已暂停时,不因事件到达或 Host 重启绕过。
- 任务仍在运行则按有效等待继续观察;已终态则交付结果;状态未知则保留明确诊断。
- 不因 ShellRun `orphaned`、失联或未记录结果而自动重派旧命令。
恢复等待不等于恢复进程,也不等于授予新的重试权限。自动重试有副作用的操作不属于这个优化的隐含承诺。
## 5. 安全与权限
需要分别核验:**登记等待、读取来源、创建后续执行、执行具体动作**。
- 模型只提出对象和条件,不能用 `userAuthorized: true` 等参数自证授权。身份与权限来自 Host 上下文;确需确认时复用现有可信交互机制。
- 遵守仓库、路径、Session 和 ShellRun 的可见性;用户交互终端不会因已知 task ID 就自动成为模型可读取内容。
- 凭据由现有机制管理,等待记录只保存引用。外部评论、日志和事件 payload 是不可信数据,不是新的指令或权限。
- 注册后和实际接纳前都核验有效控制身份与范围,防止任务替换、文件替换和权限撤销后的迟到执行。
- 初期 follow-up 可采用 `analyze-only`(仅核验、分析和汇报)作为保守范围;若采用,应由实际能力限制执行,而非只靠提示词。
- 自动修改、commit、push、merge 不是订阅本身的授权。若要把既有 Goal 的动作授权带入外部 follow-up,应单独确认规则,不隐式扩展本次 MVP。
这不改变已有 Goal 的一般权限模式,而是明确:外部唤醒入口不能成为绕过它的新通道。
## 6. 架构验收条件
首个用户可用版本至少通过以下验证:
| 场景 | 应满足的不变量 |
| --- | --- |
| 外部状态长期不变 | 不反复启动工作模型;观测遵守 TTL 和频率限制 |
| 登记后让出 | 当前执行正确结束,不只是挂着一个工具调用 |
| 重复或多个等价通知 | 同一 one-shot 等待不产生重复有效后继 |
| 先完成后登记、事件与登记并发 | 能读取当前事实,不漏恢复 |
| 旧版本、取消、暂停、归档 | 不恢复失效任务,不撤销用户控制 |
| Session busy | 通过已有接纳协调,不并发抢入 |
| 条件结果与后继接纳之间重启 | 能找到等待及交付身份,按现有恢复策略处理 |
| 来源失联或结果未知 | 不假报满足,不盲目重跑 |
| 工作轮次不再用于空等待 | 独立等待限制同时生效;实际模型工作仍计预算 |
| 接入第二个 provider | 不向核心加入专属业务字段,不改 Session 唤醒协议 |
| 对话与 UI | 能区分等待、已接纳、执行完成和目标达成 |
按同一真实案例比较模型调用、token、API 请求量、检测到接纳的延迟、重复/漏恢复以及用户介入次数。当前调研没有证明具体性能收益数字;这些应由基线和实现后的测试给出。
## 7. 短期开发计划:三个核心 PR,四个来源 PR
核心部分按三个可分别验证的问题拆分:**怎样保存等待、怎样判定等待有了结果、怎样将结果交回原任务**。前三项先用测试来源建立协议,第四项用 ShellRun 形成第一个用户可用闭环,再增加外部适配器。
### PR 1:契约与持久化——重启后仍知道在等什么
定义并保存等待对象、条件版本、所属任务、截止时间、取消状态及交付身份。处理重复登记、旧记录更新、Session 清理和 schema 迁移,使后续组件能够读取同一份权威事实,而不是各自保存一份内存状态。
- **交付验证:**创建、取消和重新打开存储后,记录及有效性保持一致;重复登记和旧 revision 不会覆盖新状态。
- **边界:**不启动生产 watcher,不调用模型;只交付后续 PR 确实需要的存储契约,不预建任意工作流 schema。
### PR 2:Host 观测与条件管理——没有新结果时由后台继续观察
建立来源适配器接口和等待管理器,处理首次状态读取、通知接收、后台轮询、TTL、限流、取消及启动后校准。适配器返回明确的条件结果,管理器将其持久化;这一层不直接启动模型。
- **交付验证:**用可控时钟和 fake provider 模拟“登记前已完成”“长期不变化”“重复通知”“来源失联”和重启,验证不漏结果、不无限查询、不把失败查询当作满足条件。
- **边界:**尚不接真实 GitHub 凭据或公网通知服务;结果先交付给测试消费者,保持观测与执行接纳分离。
### PR 3:执行桥接与 Goal 整合——结果到来后只安排一次有效后续执行
把登记等待、让出当前执行、阻止无条件 Goal 续跑,以及结果交付连接起来。复用已有 continuation 和 root-Turn admission,携带明确来源身份,并检查 Goal 是否仍有效、权限是否仍允许、Session 是否繁忙。
同时接入正常预算和结算路径,明确等待不占用工作轮次时的替代限制。对“结果已保存但执行尚未接纳”等崩溃窗口做恢复核验,而不是另建一个后台执行队列。
- **交付验证:**通过真实接纳路径与 fake model 完成“登记 → 当前执行结束 → 无变化时无模型调用 → 条件满足 → 一次有效后继”的测试,并覆盖暂停、取消、繁忙与重启。
- **边界:**未具备真实来源前不开放生产工具;不改变现有中断恢复的审批或重跑规则。
### PR 4:ShellRun——交付第一个可用的长任务等待流程
允许模型对自己有权访问的后台 ShellRun 登记等待,消费任务可靠终态和结果引用。正常完成、失败、取消或 `orphaned` 都有明确结果;任务早于登记结束时,直接读取已有记录,不等待下一次通知。
这一项同时开放等待工具、最小状态展示和取消入口,让用户能够实际体验“运行测试,结束后继续处理结果”。现有资源清理回调保持原职责,不将所有命令结束都自动变成唤醒。
- **交付验证:**长测试完成后,结果回到正确 Session;重复通知不重复执行;已取消等待不会恢复;重启后按任务事实和现有策略处理。
- **边界:**不因为丢失进程句柄而自动重启命令;不把其他工具内部或用户外部终端中的进程默认为可观察 ShellRun。
### PR 5:GitHub CI——用相同协议处理远端条件
增加明确授权的 GitHub 连接与 API 观测,绑定 repo、head SHA、run/attempt,支持约定的 run 终态或检查集合条件。处理成功、失败、取消、限流、凭据失效和离线后的补查,避免旧提交结果误触发当前任务。
- **交付验证:**当前目标 CI 的结果能够交付;旧 SHA、重复状态和查询异常不会错误唤醒;用户无需配置 Webhook。作为第二种来源,不应为接入 GitHub 修改核心唤醒协议或增加其专属字段。
- **边界:**“指定 run 完成”和“全部 required checks 满足”必须分别定义,不能用一个含糊的“CI 完成”替代两者。
### PR 6:PR/review——复用 GitHub 接入,增加协作条件
在已有认证、轮询和资源身份基础上,增加 merged、closed、review 到达及明确审批条件。登记时绑定目标 PR 和适用的版本、身份或角色要求,再由适配器核验是否满足。
- **交付验证:**能够区分关闭但未合并、收到 approval 和当前合并要求已满足;历史 review 或被撤销的审批不能误当成当前有效事实。
- **边界:**只判定结构化协作事件,不让 watcher 判断“maintainer 是否真正认可方案”;评论内容交给后续执行分析,不作为新授权。
### PR 7:文件就绪——支持外部程序交付的确定性数据条件
使用文件系统通知与当前状态扫描,支持完成标记、明确 manifest,以及少量有界校验模板,例如声明的文件齐全且校验通过,或指定 CSV 集合具备所需列。模型可以填写模板参数,但不能提交任意观察脚本。
- **交付验证:**文件在登记前已就绪、写入尚未完成、通知丢失、文件被替换或 Host 重启时,都能按约定重新核验;路径权限持续生效。
- **边界:**文件创建不等于写完,目录稳定不等于全部交付;缺少完整性依据时应报告未满足或未知,不擅自猜测。
PR 1–3 是依职责拆分,不是另建三套权威。PR 3 与 PR 4 可按规模合并;各项可紧邻评审,不应留下长期无人使用的抽象。现有执行存储和 outbox 应复用,避免独立 wake 数据库或第二条执行队列。
**去重、取消、期限、权限和恢复安全必须随首个用户闭环交付。** 不能先开放一个会漏唤醒或无限等待的版本,再把这些列为上线后增强。等待计量调整可以落在整合阶段,但与替代边界必须同时生效。
首个执行消费者建议从 Goal 开始;如果普通 Session follow-up 也必须首期开放,应明确其所有权和接纳测试,而不是自动假定已被覆盖。更多来源、传输方式和可复用经验列在[附录](./event-wakeup-research-appendix.zh-CN.md)。
</details>
---
Preparation note: this draft combines discussion, code-path inspection, and official framework documentation, with assistance from Maka. It is input for review, not a claim of implementation, completed benchmarking, or design approval.
GitHub link: https://github.com/apache/maka/discussions/5920
----
This is an automatically sent email for dev@maka.apache.org.
To unsubscribe, please send an email to: dev-unsubscribe@maka.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maka.apache.org
For additional commands, e-mail: dev-help@maka.apache.org