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
- Merge examples 08 (runTasks) and 09 (runTeam) into a single Gemma 4 example
- Renumber: structured output → 09, task retry → 10
- Move Author and Contributors sections to bottom in both READMEs
- Add Author section to English README
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
Add examples/09-gemma4-auto-orchestration.ts demonstrating runTeam()
with Gemma 4 as the coordinator — the framework's key feature running
fully local. The coordinator successfully decomposes goals into JSON
task arrays, schedules dependencies, and synthesises results.
Verified on gemma4:e2b (5.1B params) with Ollama 0.20.0-rc1.
Add examples/08-gemma4-local.ts demonstrating a pure-local multi-agent
team using Gemma 4 via Ollama — zero API cost. Two agents (researcher +
summarizer) collaborate through a task pipeline with bash, file_write,
and file_read tools. Verified on gemma4:e2b with Ollama 0.20.0-rc1.
Update both READMEs: add example 08 to the examples table and note
Gemma 4 as a verified local model with tool-calling support.
Document 5 features we evaluated and chose not to implement
(handoffs, checkpointing, A2A, MCP, dashboard) to maintain
our "simplest multi-agent framework" positioning.
Closes#17, #20.
- Add Supported Providers table with 4 verified providers (Anthropic, OpenAI,
Copilot, Ollama) and note that other OpenAI-compatible providers are unverified
- Update Contributing to distinguish baseURL verification (#25) from new adapters
- Note that local models via Ollama require no API key in Quick Start
Remove ~160 lines of duplicated code snippets from both READMEs.
Link to the runnable scripts in examples/ instead — single source of truth,
type-checked by npm run lint.
- 06-local-model.ts: mix Ollama (local) + Claude (cloud) in a runTasks pipeline,
demonstrating baseURL and apiKey placeholder for OpenAI-compatible servers
- 07-fan-out-aggregate.ts: MapReduce pattern using AgentPool.runParallel() to
fan out analysis to 3 perspective agents, then aggregate via a synthesizer
crypto.randomUUID() is not globally available in Node 18. Import
randomUUID from node:crypto explicitly so the framework works on
all supported Node versions (>=18).
- 5 test files, 61 test cases covering TaskQueue, SharedMemory,
ToolExecutor, ToolRegistry, and Semaphore
- GitHub Actions CI running lint + test on Node 18/20/22
- CONTRIBUTING.md with setup, commands, and PR workflow
- Pull request template with checklist
isTaskReady() rejects non-pending tasks on its first line, but
unblockDependents() passed blocked tasks directly to it. This meant
dependent tasks stayed blocked forever after their dependencies
completed, breaking any workflow with task dependencies.
Fix: pass a pending-status copy so isTaskReady only checks the
dependency condition.
- Add Ollama/local model agent example in multi-model teams section
- Update "Model Agnostic" description to mention local models and baseURL
- Update contributing section to reflect built-in OpenAI-compatible support
- Add author block with Xiaohongshu link in Chinese README
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
1. Fix header comment — document correct env var precedence
(apiKey → GITHUB_COPILOT_TOKEN → GITHUB_TOKEN → device flow)
2. Use application/x-www-form-urlencoded for device code endpoint
3. Use application/x-www-form-urlencoded for poll endpoint
4. Add mutex (promise-based) on #getSessionToken to prevent
concurrent token refreshes and duplicate device flow prompts
5. Add DeviceCodeCallback + CopilotAdapterOptions so callers can
control device flow output instead of hardcoded console.log
6. Extract shared OpenAI wire-format helpers into openai-common.ts,
imported by both openai.ts and copilot.ts (-142 lines net)
7. Update createAdapter JSDoc to mention copilot env vars
- Add CopilotAdapter with OAuth2 device flow authentication
- Token exchange via /copilot_internal/v2/token with caching
- Premium request multiplier system (getCopilotMultiplier)
- Full model metadata catalog (COPILOT_MODELS)
- Add 'copilot' to SupportedProvider and provider union types
- Add example: examples/05-copilot-test.ts
JackChen
JackChen
Deathwing