The short-circuit block in runTeam() called this.runAgent(), which emits
its own agent_start/agent_complete events and increments completedTaskCount.
The short-circuit block then emitted the same events again, and
buildTeamRunResult() incremented the count a second time.
Fix: call buildAgent() + agent.run() directly, bypassing runAgent().
Events and counting are handled once by the short-circuit block and
buildTeamRunResult() respectively.
Addresses all five review points from @JackChen-me on PR #70:
1. Extract shared keyword helpers into src/utils/keywords.ts so the
short-circuit selector and Scheduler.capability-match cannot drift.
Both orchestrator.ts and scheduler.ts now import the same module.
2. selectBestAgent now mirrors Scheduler.capability-match exactly,
including the asymmetric use of agent.model: agentKeywords includes
model, agentText does not. This restores parity with the documented
capability-match behaviour.
3. Remove isSimpleGoal and selectBestAgent from the public barrel
(src/index.ts). They remain exported from orchestrator.ts for unit
tests but are no longer part of the package API surface.
4. Forward the AbortSignal from runTeam(options) through the
short-circuit path. runAgent() now accepts an optional
{ abortSignal } argument; runTeam's short-circuit branch passes
the caller's signal so cancellation works for simple goals too.
5. Tighten the collaborate/coordinate complexity regexes so they only
fire on imperative directives ("collaborate with X", "coordinate
the team") and not on descriptive uses ("explain how pods
coordinate", "what is microservice collaboration").
Also fixes a pre-existing test failure in token-budget.test.ts:
"enforces orchestrator budget in runTeam" was using "Do work" as its
goal which now short-circuits, so the coordinator path the test was
exercising never ran. Switched to a multi-step goal.
Adds 60 new tests across short-circuit.test.ts and the new
keywords.test.ts covering all five fixes.
Co-Authored-By: Claude <noreply@anthropic.com>
When a goal is short (<200 chars) and contains no multi-step or
coordination signals, runTeam() now dispatches directly to the
best-matching agent — skipping the coordinator decomposition and
synthesis round-trips. This saves ~2 LLM calls worth of tokens
and latency for genuinely simple goals.
Complexity detection uses regex patterns for sequencing markers
(first...then, step N, numbered lists), coordination language
(collaborate, coordinate, work together), parallel execution
signals, and multi-deliverable patterns.
Agent selection reuses the same keyword-affinity scoring as the
capability-match scheduler strategy to pick the most relevant
agent from the team roster.
- Add isSimpleGoal() and selectBestAgent() (exported for testing)
- Add 35 unit tests covering heuristic edge cases and integration
- Update existing runTeam tests to use complex goals
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes#61
Thread AbortSignal from the top-level API through RunContext to
executeQueue(), enabling graceful cancellation in Express, Next.js,
serverless, and CLI scenarios.
Changes:
- Added optional to RunContext interface
- now accepts
- now accepts
- executeQueue() checks signal.aborted before each dispatch round
and skips remaining tasks when cancelled
- Signal is forwarded to coordinator's run() and per-task pool.run()
so in-flight LLM calls are also cancelled
- Full backward compatibility: both methods work without options
The abort infrastructure already existed at lower layers
(AgentRunner, Agent, AgentPool) — this commit bridges the last gap
at the orchestrator level.
Co-authored-by: JasonOA888 <JasonOA888@users.noreply.github.com>
* feat(orchestrator): add onApproval callback for human-in-the-loop (#32)
Add an optional `onApproval` callback to OrchestratorConfig that gates
between task execution rounds. After each batch of parallel tasks
completes, the callback receives the completed tasks and the tasks about
to start, returning true to continue or false to abort gracefully.
Key changes:
- Add 'skipped' to TaskStatus for user-initiated abort (distinct from 'failed')
- Add skip(), skipRemaining(), cascadeSkip() to TaskQueue
- Add 'task_skipped' to OrchestratorEvent for progress monitoring
- Approval gate in executeQueue() with try/catch for callback errors
- Synthesis prompt now includes skipped tasks section
- 17 new tests covering queue skip operations and orchestrator integration
Closes#32
* docs: clarify onApproval contract and add missing test scenarios
- Document skip() cascade semantics, skipRemaining() in-flight constraint,
and onApproval trigger conditions / mutation warning
- Add concurrency safety comment on completedThisRound
- Note task_skipped as breaking union addition on OrchestratorEvent
- Add 3 test scenarios: single-batch no-callback, mixed success/failure
batch, and onProgress task_skipped event relay
Add lightweight onTrace callback to OrchestratorConfig that emits
structured span events (llm_call, tool_call, task, agent) with timing,
token usage, and runId correlation. Zero overhead when not subscribed.
Closes#18
Use Number.isFinite() to sanitize maxRetries, retryDelayMs, and
retryBackoff before entering the retry loop. Prevents unbounded
retries from Infinity or broken loop bounds from NaN.
* feat: add task-level retry with exponential backoff
Add `maxRetries`, `retryDelayMs`, and `retryBackoff` to task config.
When a task fails and retries remain, the orchestrator waits with
exponential backoff and re-runs the task with a fresh agent conversation.
A `task_retry` event is emitted via `onProgress` for observability.
Cascade failure only occurs after all retries are exhausted.
Closes#30
* fix: address review — extract executeWithRetry, add delay cap, fix tests
- Extract `executeWithRetry()` as a testable exported function
- Add `computeRetryDelay()` with 30s max cap (prevents runaway backoff)
- Remove retry fields from `ParsedTaskSpec` (dead code for runTeam path)
- Deduplicate retry event emission (single code path for both error types)
- Injectable delay function for test determinism
- Rewrite tests to call the real `executeWithRetry`, not a copy
- 15 tests covering: success, retry+success, retry+failure, backoff
calculation, delay cap, delay function injection, no-retry default
* fix: clamp negative maxRetries/retryBackoff to safe values
- maxRetries clamped to >= 0 (negative values treated as no retry)
- retryBackoff clamped to >= 1 (prevents zero/negative delay oscillation)
- retryDelayMs clamped to >= 0
- Add tests for negative maxRetries and negative backoff
Addresses Codex review P1 on #37
* fix: accumulate token usage across retry attempts
Previously only the final attempt's tokenUsage was returned, causing
under-reporting of actual model consumption when retries occurred.
Now all attempts' token counts are summed in the returned result.
Addresses Codex review P2 (token usage) on #37
- Include error feedback user turn in mergedMessages to maintain
alternating user/assistant roles required by Anthropic API
- Use explicit undefined check instead of ?? for structured merge
to preserve null as a valid structured output value
When `outputSchema` is set on AgentConfig, the agent's final text output
is parsed as JSON, validated against the Zod schema, and exposed via
`result.structured`. On validation failure a single retry with error
feedback is attempted automatically.
Closes#29
Enable connecting to any OpenAI-compatible API (Ollama, vLLM, LM Studio,
etc.) by adding baseURL and apiKey fields to AgentConfig and
OrchestratorConfig, threaded through to adapter constructors.
- OpenAIAdapter and AnthropicAdapter accept optional baseURL
- createAdapter() forwards baseURL to both adapters, warns if used with copilot
- All execution paths (runAgent, runTeam coordinator, buildPool) merge defaults
- Fully backward compatible — omitting new fields preserves existing behavior
JackChen
MrAvalonApple
JackChen
EchoOfZion
Ibrahim Kazimov
Jason