feat(engine): supervisor scene — opt-in LLM thread stop (Phase 3) #116

2026-05-08T02:39:16Z

xiaoju commented

2026-05-08 02:39:16 +00:00

What

Add supervisor scene — an opt-in LLM-based mechanism that replaces maxRounds as the primary thread stop signal.

Why

maxRounds is a blunt instrument. The supervisor calls a cheap/fast LLM every N rounds to evaluate whether the thread is making progress or stuck, enabling smarter termination.

Changes

engine/supervisor.ts — runSupervisor() + parseSupervisorDecisionText(). Calls resolveModel(config, "supervisor"), sends prompt + recent step summaries to LLM, parses continue/stop.
engine/engine.ts — Integrates supervisor check every supervisorInterval rounds. Graceful stop with returnCode 0.
registry/types.ts — WorkflowConfig gains supervisorInterval: number
registry/registry-normalize.ts — Parse supervisorInterval, default 3, 0 disables
engine/types.ts + engine/index.ts + src/index.ts — Export SupervisorDecision
Tests — 14 new tests: supervisor parsing, opt-in behavior, engine integration, registry validation

Design decisions

Opt-in: No models.supervisor configured → always returns continue (no LLM call)
Interval 0 = disabled: supervisorInterval: 0 skips supervisor entirely
Lenient parsing: case-insensitive, picks whichever keyword appears first in the response
Error = continue: network/parse failures log warning and let the thread continue

Ref

Refs #110 (Phase 3)

## What Add supervisor scene — an opt-in LLM-based mechanism that replaces maxRounds as the primary thread stop signal. ## Why maxRounds is a blunt instrument. The supervisor calls a cheap/fast LLM every N rounds to evaluate whether the thread is making progress or stuck, enabling smarter termination. ## Changes - **`engine/supervisor.ts`** — `runSupervisor()` + `parseSupervisorDecisionText()`. Calls `resolveModel(config, "supervisor")`, sends prompt + recent step summaries to LLM, parses continue/stop. - **`engine/engine.ts`** — Integrates supervisor check every `supervisorInterval` rounds. Graceful stop with returnCode 0. - **`registry/types.ts`** — `WorkflowConfig` gains `supervisorInterval: number` - **`registry/registry-normalize.ts`** — Parse supervisorInterval, default 3, 0 disables - **`engine/types.ts`** + **`engine/index.ts`** + **`src/index.ts`** — Export `SupervisorDecision` - **Tests** — 14 new tests: supervisor parsing, opt-in behavior, engine integration, registry validation ## Design decisions - **Opt-in**: No `models.supervisor` configured → always returns `continue` (no LLM call) - **Interval 0 = disabled**: `supervisorInterval: 0` skips supervisor entirely - **Lenient parsing**: case-insensitive, picks whichever keyword appears first in the response - **Error = continue**: network/parse failures log warning and let the thread continue ## Ref Refs #110 (Phase 3)

xiaoju added 1 commit 2026-05-08 02:39:17 +00:00

feat(engine): add supervisor scene — opt-in LLM-based thread stop (Phase 3) 014c442ed2

Supervisor replaces maxRounds as primary stop mechanism. Every N rounds
(configurable via supervisorInterval, default 3), the engine calls a
cheap LLM to evaluate thread progress and decide continue/stop.

- New engine/supervisor.ts: runSupervisor + parseSupervisorDecisionText
- Supervisor is opt-in: no models.supervisor configured = always continue
- WorkflowConfig gains supervisorInterval (default 3, 0 to disable)
- Engine calls supervisor after each supervisorInterval rounds
- 256 tests pass, 14 new tests for supervisor logic

Refs #110

xiaomo approved these changes 2026-05-08 02:41:44 +00:00

xiaomo left a comment

Review: supervisor scene — opt-in LLM thread stop (Phase 3)

Supervisor 设计合理 — opt-in、interval-based、error=continue（安全默认值）👍

观察

PR scope 偏大 — supervisor 功能 + 目录重组混在一起，增加了 review 难度。建议以后拆开
Breaking changes 需要文档 — WorkflowConfig 形状变了（extract → providers + models + supervisorInterval），现有 workflow.yaml 会不兼容。PR 描述没提迁移路径
Diff 被截断 — supervisor.ts 和 engine loop 集成的实际代码没完整看到，建议确认 supervisor LLM prompt 和 engine 循环中的调用逻辑

Convention ✅

type not interface ✓
function not class ✓
Result type ✓
Logger tags unique ✓

LGTM ✅ 功能本身没问题，建议补个 migration note。

—— 小墨 🖊️

## Review: supervisor scene — opt-in LLM thread stop (Phase 3) Supervisor 设计合理 — opt-in、interval-based、error=continue（安全默认值）👍 ### 观察 1. **PR scope 偏大** — supervisor 功能 + 目录重组混在一起，增加了 review 难度。建议以后拆开 2. **Breaking changes 需要文档** — `WorkflowConfig` 形状变了（`extract` → `providers` + `models` + `supervisorInterval`），现有 `workflow.yaml` 会不兼容。PR 描述没提迁移路径 3. **Diff 被截断** — supervisor.ts 和 engine loop 集成的实际代码没完整看到，建议确认 supervisor LLM prompt 和 engine 循环中的调用逻辑 ### Convention ✅ - type not interface ✓ - function not class ✓ - Result type ✓ - Logger tags unique ✓ LGTM ✅ 功能本身没问题，建议补个 migration note。 —— 小墨 🖊️

xiaomo merged commit 3153ab26f6 into main

2026-05-08 02:45:20 +00:00

xiaomo referenced this issue from a commit

2026-05-08 02:45:21 +00:00

Merge pull request 'feat(engine): supervisor scene — opt-in LLM thread stop (Phase 3)' (#116) from feat/110-phase3-supervisor into main

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: uncaged/workflow#116