DeepSeek retired the V4-Flash model and named the current generation
`deepseek-flash`, with no version in the name. `deepseek-v4-flash` is still
accepted, but DeepSeek documents it as a temporary compatibility name and
already serves those requests from V4.1-Flash.
The repository handed that name to users in the places most likely to be
copied: the `oma` CLI default for `provider: 'deepseek'`, the adapter JSDoc
that ships in the type declarations, the provider table in docs, the
scaffolder env template, and every DeepSeek example. A copied name that the
vendor calls temporary has an expiry date the reader cannot see.
The provider table and the adapter JSDoc also stated that `deepseek-v4-flash`
resolves to DeepSeek-V4-Flash-0731. That model is retired, so the sentence
described a routing that no longer happens.
Two corrections of the same kind travel with it. The thinking-mode note
claimed the V4 models run at `high` effort, but the adapter forwards whatever
effort the caller passes and sets none itself, so the claim is dropped rather
than restated. Three `examples/basics` headers offered `deepseek-chat`, which
DeepSeek retired outright on 2026-07-24 and which no longer resolves at all.
The release bot moves to the same name. Callers that pass an explicit model
are unaffected, and the old name keeps working for as long as DeepSeek
accepts it.
Left unchanged on purpose: `bench/config.json`, whose values are frozen
controls for an already-run benchmark; the AtlasCloud pages, whose IDs come
from that vendor's own model library; and the changelog history.
AI SDK 7 deprecates `StreamTextResult.fullStream` in favor of `stream`.
The example pins `ai@^7.0.0`, so the reference route was reading a
deprecated property that new readers would copy into their own code.
`packages/core/src/llm/ai-sdk.ts` keeps `fullStream` deliberately. Core
declares `ai` as a peer dependency across `^5.0.0 || ^6.0.0 || ^7.0.0`,
and `StreamTextResult` in v5 and v6 exposes no `stream` property at all,
so switching there would break those consumers at runtime. `fullStream`
is deprecated in v7 but not removed, so it stays correct for all three.
Verified with `tsc --noEmit` against the example's own tsconfig.
Anyone following this example got a blank article back. The route read
the team's answer from agentResults.get('coordinator'), but a goal this
short is routed to the single-agent path, where the orchestrator
publishes the answer under the winning agent's own name instead. The
lookup returned undefined, the ?? '' fallback swallowed it, and the app
streamed an empty Team Output section.
- Pass an explicit mode: 'team' so the demo runs the topology this
example teaches. Explicit mode outranks the router.
- Read the terminal agent as a fallback so the route returns the article
under either topology.
- Check success before streaming. A plan validation failure leaves the
coordinator's unparsed plan under the 'coordinator' key, so testing
for an empty string would stream planning scratch as the article.
- Raise maxDuration to 360 and say "a few minutes" in the placeholder,
to match the measured team path: seven runs on deepseek-v4-flash took
137 to 311 seconds, median 217, from one machine.
The examples index is the first page most visitors open after the root
README, but it never said the scripts import the framework source and
need a repository checkout, which examples run without an API key, or
that four integrations existed at all.
- Add a "Run an example" block (clone, install, key, npx tsx) and note
the two exceptions: observability-v2 needs a build, apps have their
own start scripts. Explain how to port a script into a real project.
- Add a "No API key needed" table for the seven offline examples.
- Let the basics scripts switch provider through OMA_PROVIDER and
OMA_MODEL instead of hard-coding Claude, following the convention the
cookbook already uses.
- List external-agent-acp, external-agent-process, with-engram, and
with-tencentdb-memory, and fail test:example-catalog when a catalog
entry has no link in the index so it cannot drift again.
- Reorder sections so the 20-row providers table no longer sits between
basics and the patterns and cookbook tables; mark production/ as empty.
- Align integrations/README.md with the apps grouping and define the
mcp-<server>.ts versus with-<product>/ naming by example shape.
Every observability example used an in-process exporter, which proves the
adapter's semantics but never serializes a span or opens a socket. Nothing in
the repository showed the path an OpenTelemetry user actually takes, so the
exporter choice, Resource, auth headers, and shutdown order were left for each
reader to reconstruct.
`otlp-backend.ts` runs OTel SDK to OTLP/HTTP exporter to HTTP to a backend, and
prints what crossed the wire. The backend is a loopback listener the example
starts itself, so it still needs no API key, no external collector, and no
internet access; `OTLP_URL` and `OTLP_HEADERS` redirect the same payload to a
hosted vendor.
It also demonstrates two things that are easy to get wrong. `service.name`
belongs to the provider's Resource, and a provider built without one files
every span under `unknown_service:node`. Tool input and output require both
halves of the capture opt-in, so the example sets the core policy and the
adapter mode together and states what the run exports without them.
`runToolDemo` joins the shared demo runtime so the example can show a real
`execute_tool` span; the existing `runDemo` export is unchanged. The example is
registered in the catalog and in the smoke script, which now runs eight
examples.
packages/core/tsconfig.json excludes `examples`, and no CI job compiled
them, so the only automated coverage for 63 catalogued examples was
catalog metadata and file existence. An example could reference a removed
option or a changed constructor signature and stay green forever.
Core's `lint` script now runs against a new `tsconfig.lint.json` that
compiles `src/` and `examples/` together. The existing CI `lint` job and
the documented `npm run lint -w @open-multi-agent/core` step both pick it
up with no workflow change.
Turning the gate on surfaced six examples that no longer compiled:
- patterns/cross-provider-reasoning.ts called `new Agent(config)`; the
constructor takes `(config, registry, executor)`.
- integrations/external-agent-acp.ts passed `onProgress` through
`RunTeamOptions`, where it does not exist. It belongs on
`OrchestratorConfig`.
- cookbook/contract-review-dag.ts and cookbook/incident-postmortem-dag.ts
declared `dependsOn?: readonly string[]`, not assignable to
`RunTaskSpec.dependsOn`.
- cookbook/paper-replication-triage.ts built a header object whose union
type was not assignable to `Record<string, string>`.
- integrations/with-engram/engram-store.ts assigned `res.json()`
(`unknown`) straight to `EngramFact[]`.
`examples/fixtures/` is agent input rather than compiled code, and the
self-contained example projects resolve `@open-multi-agent/core` from the
built package, so both are excluded from the pass.
Map OMA thinking controls to DeepSeek's native request shape, keep the provider-specific max effort isolated from other OpenAI-family adapters, and refresh model guidance and canary coverage.
* feat(core): add unified run viewer
* feat(cli): export run viewer from trace store
* docs(core): add deterministic run viewer demo
* fix(examples): resolve workspace paths in typecheck
* fix(dashboard): center detail status labels
* fix(dashboard): remove DAG status rails
* fix(dashboard): enlarge DAG task cards
* fix(dashboard): clarify run summary header
* docs: align readmes with run viewer
* feat(agent): orchestrate external coding agents over ACP (#204)
Add an AgentBackend seam so an Agent can run on either the LLM AgentRunner
or an external agent. First backend: an ACP client that drives a coding CLI
(e.g. Claude Code via its ACP adapter) as a first-class team member — same
task DAG, shared memory, cascade, and token budget as LLM agents.
- Extract AgentBackend ({ run, stream }) that AgentRunner already implements;
Agent.getBackend() branches on AgentConfig.backend.
- AcpBackend spawns the agent over stdio JSON-RPC and maps session updates to
a RunResult (text, tool calls, usage); handles permissions and abort.
- ACP SDK as a lazy optional peer; new /acp subpath export.
- docs/external-agents.md, a hybrid-team example, and tests (in-process fake
agent + subprocess integration).
Experimental: ACP is young; token accounting maps ACP's single context
figure and client-side fs proxying is not implemented yet.
* fix(agent): harden ACP backend after review (#204)
Follow-up fixes on the ACP external-agent backend (PR #360):
- Token accounting: usage_update.used is a cumulative context-size gauge, not a
per-turn delta. Record each turn's increment so summing across a reused session
telescopes to the latest figure instead of double-counting.
- systemPrompt: ACP has no system-prompt field, so prepend the agent's systemPrompt
to the session's first turn (once). It was previously dropped and only fed
coordinator routing.
- Abort: when the signal is already aborted before a turn starts, return empty
output without prompting (no in-flight turn to cancel).
- Startup: clear the cached start() promise on failure so a later run retries
instead of re-throwing the same rejection forever.
- Permissions: auto-approve now prefers least-privilege allow_once over a
session-wide allow_always.
Docs (external-agents.md, CLAUDE.md) updated to match. ACP tests 10 to 15;
lint + full suite (1135) green.
Drive Open Design's stdio MCP server from OMA to generate N landing-page
variants in parallel via runTasks(). Each variant's async flow
(create_project, start_run, poll get_run to a terminal status) is handled
by deterministic code, not LLM polling; the worker model only drafts the
design brief. Reference-lane example alongside mcp-github and
mcp-bilig-workpaper, plus its two README index entries.
Widen the ai peer range to include v7, bump dev deps (ai@7, @ai-sdk/provider@4, @ai-sdk/openai@4), update the with-vercel-ai-sdk example (ai@7, @ai-sdk/react@4, @ai-sdk/openai-compatible@3) and migrate it to the v7 standalone UI-stream helpers, and document that the bridge needs Node 22 while core stays 18.
* docs(examples): prefix example run commands with packages/core/
Examples live under packages/core/, and both READMEs document running them from the repo root (npx tsx packages/core/examples/<path>.ts), but the in-file Run: headers and a few READMEs still used the bare examples/ path. The repo root has no top-level examples/, so copy-pasting those commands from root failed with file-not-found.
Prefixes 67 run/cd commands across 56 files (53 example scripts + examples/README.md + two integration READMEs). Markdown links that use the bare examples/ path are correct relative links and are left unchanged.
* docs: prefix two stale examples/ path references in docs/
context-management.md and tool-configuration.md referenced bare examples/ paths that do not resolve from the repo root. Make the first a relative link (matching the convention in model-routing.md) and prefix the second with packages/core/. Follow-up to the run-command fixes in this PR.
* refactor(repo): monorepo groundwork for an easier first run
Trying OMA for the first time costs more than it should: a lot to read before anything runs, and no one-command way to watch a team actually work. The plan is to fix that with a `npm create oma` scaffold (a multi-agent demo that runs on the first try) and an npm README that leads with getting started. Neither lands cleanly until core lives in its own package, so this PR does that part first.
This is groundwork, not the payoff: nothing changes for anyone installing `@open-multi-agent/core` today. It turns the repo into an npm-workspaces monorepo with core in `packages/core/`, and splits the README into a GitHub landing page (root) and the npm package page (`packages/core/`). Doing it now, while the repo is small, avoids migrating twice.
The published package is byte-identical: same name, same three runtime dependencies, same entry points, guarded by an isolated-install smoke test. `npm ci` + lint + test (1060) + build pass; the tarball still ships only `dist/`, `README.md`, `LICENSE`, and `package.json`.
* build: restore cross-platform optional deps in package-lock.json
Regenerating the lockfile on macOS pruned the non-host rollup/esbuild optional binaries (npm/cli#4828), so Linux CI could not load @rollup/rollup-linux-x64-gnu and vitest failed to start. Rebuild the lock from the pre-migration base so every platform variant is present again. Verified with npm ci + lint + build + test (1060).
* fix(examples,docs): correct monorepo paths and anchors after the packages/core move
with-vercel-ai-sdk example (pre-existing, surfaced by the move):
- package.json: the @open-multi-agent/core file: link was file:../../, which
resolves to packages/core/examples (no manifest). Corrected to file:../../..
(packages/core); predev cd updated to match.
- package-lock.json regenerated: was linking ../.. and pinning a stale core
1.4.0; now links ../../.. at 1.7.0.
- README: setup paths and the file: note updated.
docs missed by the move:
- docs/cli.md: repo-clone build output is now packages/core/dist/cli/oma.js;
the quick-start anchor now lives in the package README.
- CONTRIBUTING.md: the architecture anchor and src/ entry-point paths now live
under packages/core/.
Jack Chen