Hand-wiring a multi-agent graph in a framework is fragile; handing the task to a closed endpoint hides the routing, prices at the ceiling, and blocks the EU. Coryphaeus runs in your process over your pool with your keys, a Regent decides the arrangement per task and shows you the graph, the roles, and the cost.
Coryphaeus composes several frontier models as one coordinated team. You register a pool of agents and
inject your own model caller, and it decides per task which agents to activate, assigns the Thinker,
Worker, and Verifier roles, runs an inspectable topology, and returns the answer plus an auditable graph,
the cost, and the provenance. Your code is two lines:
new Coryphaeus({ client, agents }), then coryphaeus.run(task).
A pluggable Regent estimates complexity and picks a topology, single, pipeline, parallel, or cascade, casting agents into roles. Each call goes through the injectable client and becomes a node in the agent graph, priced against the agent's cost profile. A budget tracker forecasts each step and refuses any that would breach the ceiling, a parallel debate ends in a governed synthesizer with provenance, and a tamper-evident hash-chained audit trail records what was composed. The core never speaks a provider API.
Take a real production scene: a hard task that one model alone answers unevenly, so you want several frontier models working together, under control, with the cost and the routing visible.
Open composition is the middle ground between a brittle hand-wired graph and an opaque closed box; it keeps the routing, the roles, and the cost in your hands, on your infrastructure, with every decision exposed as an auditable graph.
install to your first auditable run.pnpm add @takk/coryphaeusnpm install @takk/coryphaeusyarn add @takk/coryphaeusbun add @takk/coryphaeusThe core has no runtime dependencies and a node-free core. Every @takk sibling is an optional
peer; install only what you compose with.
# nothing else is required to start experimenting
# optional: install a sibling you compose with, for example
pnpm add @takk/keymesh @takk/modelchainimport { Coryphaeus, createEchoClient, defineAgent } from '@takk/coryphaeus';
const pool = [
defineAgent({ id: 'planner', provider: 'openai', model: 'o-planner', roles: ['thinker'] }),
defineAgent({ id: 'builder', provider: 'anthropic', model: 'claude-builder', roles: ['worker'] }),
defineAgent({ id: 'checker', provider: 'google', model: 'gemini-checker', roles: ['verifier'] }),
];
// Inject your model caller; createEchoClient is a deterministic offline stand-in.
const coryphaeus = new Coryphaeus({ client: createEchoClient(), agents: pool });
const result = await coryphaeus.run({ input: 'Draft a migration plan with a rollback path.' });
result.topology; // the Regent's choice, here 'pipeline'
result.cost.costUsd; // total USD across every step
result.nodes; // the auditable agent graphimport { createOrchestrateTool } from '@takk/coryphaeus/adapter';
// A framework-agnostic descriptor (name, description, JSON Schema, handler) that
// matches what MCP servers and tool-calling APIs expect. Its name is 'coryphaeus_orchestrate'.
const tool = createOrchestrateTool(coryphaeus);
const result = await tool.handler({
task: 'Audit the dependency tree for known advisories.',
complexity: 'high',
});
// the host fixes the agent pool; the caller only sends a taskA coordinator decides, per task, which agents to activate, the role each plays, the topology, and the budget. The 1.0 Regent is a transparent heuristic; a learned strategy slots in behind the same seam.
Routing is a decision you can read and override, not an opaque router you have to trust.
Single for the fast path, pipeline for Thinker to Worker to Verifier, parallel for an independent debate then a governed synthesizer, and cascade for cheapest-first escalation on low confidence.
Pick the shape the task deserves, instead of forcing every job through one fixed workflow.
Thinker, Worker, and Verifier are first-class and overridable, with system scaffolds you can see and replace, the deliberate opposite of an endpoint that hides how each agent is framed.
You control how the team thinks, builds, and checks, instead of trusting a hidden cast.
The orchestration runs in your process, on your infrastructure, with your keys. The core never speaks a provider API; no vendor sits in the middle of every call, and the EU and EEA are not blocked.
Run frontier composition where a closed, region-locked endpoint cannot follow you.
Each agent carries a cost profile. The orchestrator forecasts the dollar cost of an arrangement before any
call and enforces a hard ceiling, raising a typed BUDGET_EXCEEDED before a breaching step.
Cost is a number you set up front, instead of a surprise at the ceiling of a vendor pool.
A fast mode favors a single worker for the lowest latency, the analogue of a single-shot
call; a deep mode favors multi-agent collaboration. You choose the trade per task.
Tune speed against depth yourself, instead of waiting on a box that decides for you.
An append-only log of every run and decision, with a SHA-256 hash-chain you append to and
verifyChain via the Web Crypto API.
Prove an answer was composed by the recorded arrangement, in Node, edge runtimes, or the browser, when a decision is questioned.
Every run is a graph: a node per agent invocation with its role, model, and cost, and an edge per dependency. It renders to JSON, Graphviz DOT, or Mermaid.
Log, render, diff, and review exactly how an answer was built, instead of a black-box route you cannot inspect.
Every published version signed with npm publish --provenance through GitHub Actions OIDC.
Lockfile committed, zero required runtime dependencies, node-free core.
Verify in one command that the tarball you installed was built from the source commit you trust.
The Regent picks one of four coordination shapes per task, and you can force one. Each is declarable and inspectable, and renders to a graph; the only knobs are the cascade threshold and the budget.
| Topology | What it is | When the Regent picks it |
|---|---|---|
single |
One worker answers directly, the lowest-latency path and the analogue of a single-shot call. | Low complexity, or a fast latency budget. |
pipeline |
Thinker to Worker to Verifier in sequence; each stage refines the last, the last node is the answer. | Medium complexity in deep mode. |
parallel |
Independent workers run concurrently, then a governed synthesizer merges them with provenance. | High complexity in deep mode with two or more workers. |
cascade |
The cheapest capable agent first, escalating to a stronger one only when a tier is not confident enough. | High complexity in fast mode. Cost-aware. |
The 1.0 Regent is a transparent heuristic that selects the topology from complexity and latency; a learned coordinator (policies via bandits) is a later release behind the same RegentStrategy seam.
| Entry point | Subpath export | Runtime | Use it when |
|---|---|---|---|
| Toolkit barrel | @takk/coryphaeus |
node-free | You want the orchestrator, the Regent, roles, topologies, budget, the graph, audit, and the adapters. |
| Orchestrator | @takk/coryphaeus/orchestrator |
node-free | You want the Coryphaeus facade on its own to plan, forecast, and run. |
| Client adapters and tool | @takk/coryphaeus/adapter |
node-free | You want the OpenAI-style or Vercel client adapter, or the orchestrate tool for an MCP server. |
| Node loaders | @takk/coryphaeus/node |
Node only | You need to load an agent roster, a task, or a saved run graph from JSON files. |
The coryphaeus binary runs the compiled engine. plan shows the Regent's arrangement
and a cost forecast; run orchestrates a task offline with the deterministic client behind
--mock; graph renders a saved run to DOT or Mermaid; audit-verify checks
a sealed chain. Real provider runs use the library API with an injected client.
# show the regent's arrangement and a cost forecast, no execution
npx @takk/coryphaeus plan task.json --agents agents.json# orchestrate with the deterministic client and save the run
npx @takk/coryphaeus run task.json --agents agents.json --mock --out run.json
npx @takk/coryphaeus graph run.json --format mermaid
npx @takk/coryphaeus audit-verify chain.json
npx @takk/coryphaeus --version
# exit codes: 0 ok, 2 usage or input, 30 budget exceeded, 20 broken chainSeal every run and decision into a tamper-evident, hash-chained log. And because each run is explicit,
run returns the answer, the topology, the per-step cost, the provenance, and the full agent
graph, so the composition is never a black box. Both are node-free and need no external service.
import { AuditChain, verifyChain } from '@takk/coryphaeus/audit';
const chain = new AuditChain();
// Seal each run into the chain as it completes, then record a decision.
await coryphaeus.run({ input: 'Triage the alert.' }, { chain });
await chain.append({ kind: 'decision', approved: true });
await verifyChain(chain.toArray()); // { valid: true }, until any entry is alteredconst result = await coryphaeus.run({ input: 'Summarize the incident.' });
// {
// run: 'a1b2c3...',
// output: '...', // the final answer
// topology: 'pipeline', // the Regent's choice
// cost: { costUsd: 0.0031, inputTokens: 494, ... },
// provenance: { finalNode: 'n2', contributors: ['n0', 'n1', 'n2'] },
// nodes: [ ... ], edges: [ ... ] // the auditable graph
// }The result carries the topology the Regent chose, the per-step cost, and the provenance, so you can see how the answer was composed and what it cost. Seal each run into the audit chain with no runtime dependency, the governance seam for a non-human entity orchestrating a pool of models it operates.
The other approaches solve part of the problem. The contrast clarifies where Coryphaeus sits.
| Capability | Coryphaeus | Closed endpoint | Agent framework | Vercel AI SDK | Hand-rolled |
|---|---|---|---|---|---|
| Distribution | npm library | hosted endpoint | npm library | npm library | your repo |
| Transparent routing | auditable graph | black box | hand-wired | thin primitives | varies |
| Adaptive arrangement | Regent | learned, hidden | fixed in code | none | none |
| Cost forecast and ceiling | yes | pool ceiling | manual | no | varies |
| Provider-agnostic | injectable | pool fixed | yes | yes | varies |
| Local-first sovereignty | your infra | region-locked | yes | yes | yes |
| Tamper-evident audit | yes | no | no | no | no |
| Zero deps, node-free | yes | n/a | deps | deps | varies |
| License | Apache-2.0 | proprietary | mixed | Apache-2.0 | your call |
The honest summary: a closed endpoint is fine when you do not need to see inside, and a single direct call is fine for an easy task. Pick Coryphaeus when you want several frontier models composed under control, the routing and cost visible, sovereignty over where it runs, and a tamper-evident trail, all in one node-free TypeScript library you embed in production.
Coryphaeus is transparent orchestration over an injectable client, and that has boundaries. They are documented, and where reality bends them, there is an explicit choice rather than a silent fudge.
| Assumption or property | What it means | How Coryphaeus handles it |
|---|---|---|
| Heuristic Regent | The 1.0 coordinator selects a topology by transparent rules, not a learned router. | Every choice is explained in the arrangement's rationale; a learned strategy is a documented later release behind the same seam. |
| Injectable client | The core never speaks a provider API; the answer quality is the injected client's and the providers'. | You provide the model caller; Coryphaeus orchestrates and audits it, and tests run against a deterministic mock. |
| Flat topologies | An arrangement is one of single, pipeline, parallel, or cascade. | Recursive self-composition (an agent that is itself an orchestrator) is a documented non-goal for 1.0. |
| Cost is forecast then measured | The pre-dispatch forecast uses a chars-per-token heuristic. | Actual cost is recomputed from the result's reported token counts and recorded per node; the forecast only gates dispatch. |
| Confidence-driven cascade | A cascade escalates on a self-reported confidence the client may return. | When no confidence is reported a tier is treated as fully confident, so a silent client never escalates past the first. |
| Budget is a hard ceiling | The ceiling is enforced before a breaching step is dispatched. | It raises a typed BUDGET_EXCEEDED rather than reporting an overrun after the fact. |
| Provenance from the graph | Provenance is which agents contributed to the final answer. | It is read off the edges by walking back from the final node, not asserted by the agents. |
| Integrity, not identity | The audit seal proves a log was not altered after sealing. | A SHA-256 hash chain via Web Crypto, an integrity seal, not a signature. |
93 tests passing under Vitest 4 with 98% coverage, across 12 suites on the Node 20, 22,
and 24 matrix. Five runnable examples and a composition benchmark orchestrate against the built artifact
end to end. Run pnpm test on a fresh clone to reproduce.
TypeScript 6 in maximum strict mode (exactOptionalPropertyTypes,
useUnknownInCatchVariables, noUncheckedIndexedAccess,
noImplicitOverride, noImplicitReturns). Zero errors under tsc
--noEmit.
Biome 2.5 clean across src and tests. publint clean and
@arethetypeswrong/cli green across all twelve subpaths. Dual ESM + CJS with separate
.d.ts and .d.cts per subpath.
The Regent picks the documented topology for each complexity and latency, the budget guard trips before a breaching call, the cascade escalates only until confidence clears the threshold, and the audit chain detects a tampered entry at exactly its index. Every invariant is a test.
A smoke test exercises the compiled ESM and CJS artifacts and spawns the compiled CLI as a single Node process, run on the Node 20, 22, and 24 matrix.
Committed pnpm lockfile, zero required runtime dependencies, node-free core, and SLSA provenance
attestation on every published version. Verify with npm view @takk/coryphaeus@1.0.0 --json | jq
.dist.attestations.
Yes. 93 tests pass under Vitest 4 with 98% coverage; TypeScript 6 maximum strict mode is clean; Biome 2.5
lint is clean; publint and @arethetypeswrong/cli are clean across all twelve
subpaths. The suite and the distribution smoke test are run on the Node 20, 22, and 24 matrix. Every
published release carries SLSA provenance produced by GitHub Actions.
Because no single model is best at everything; different providers lead on programming, mathematics, security, and long context. Composing several as a team raises the ceiling on a hard task. For an easy task, Coryphaeus agrees with you: the Regent picks the single-worker topology and answers directly, the lowest-latency, lowest-cost path. You only pay for composition when the task warrants it.
You can, and many do. The cost is a fixed graph in code that you rewrite when you change providers or roles, and that you must instrument yourself for cost and audit. Coryphaeus moves the arrangement decision into a pluggable Regent, exposes it as a graph, and builds the cost forecast, the budget ceiling, and the audit trail in, so the orchestration adapts per task instead of being frozen at authoring time.
No. The core is orchestration logic over an injectable client. You provide the model caller, an OpenAI-style chat function, a Vercel AI SDK call, a local model, or a deterministic mock, and the orchestrator drives it. That keeps the package provider-agnostic, dependency-free, and testable with no network, and it means your provider keys live in your client, never in Coryphaeus.
Yes. The core is node-free; the audit seal uses the Web Crypto API, not node:crypto. Import
@takk/coryphaeus or @takk/coryphaeus/edge on any runtime with Web Crypto. Only
@takk/coryphaeus/node, the JSON and CSV loaders, requires the Node standard library.
Coryphaeus holds the agent descriptors you register, the task text you pass, and the run results it builds, nothing else. It makes no outbound network calls of its own; the only model calls are the ones your injected client makes to your chosen providers. With the file loaders, only the roster, task, or run files you point it at are read from disk, and no provider credentials are ever held by Coryphaeus.
Per task, the Regent estimates complexity, reads your latency preference, and chooses a topology and a cast of agents, assigning each a role. The 1.0 Regent is a transparent heuristic, and every choice is explained in the arrangement's rationale. You can force a topology, swap in your own strategy behind the same seam, or simply read the rationale to see why it composed the team it did.
No, and the docs are explicit about it. Each entry is chained to the previous one through a SHA-256 hash of its canonical form, so any later edit breaks the chain. It is an integrity seal, not a signature: it does not prove who produced the log. Signed and timestamped seals for stronger third-party evidence are on the roadmap.
Any of them. Because you inject the client, Coryphaeus composes OpenAI, Anthropic, Google, a local model, or a mix, treated uniformly as black-box agents. Adapters are included for an OpenAI-style chat function and the Vercel AI SDK, so wrapping your existing call is two lines.
In-process memory by default, with portable JSON snapshots via snapshot() and
fromSnapshot(), the agent pool and the scalar configuration. For disk-backed input, load an
agent roster, a task, or a saved run from JSON with @takk/coryphaeus/node. For an edge runtime,
snapshot to your own KV store between invocations.
Each agent carries a cost profile. Coryphaeus forecasts the dollar cost of an arrangement before any call,
and a budget tracker refuses any step that would breach the ceiling you set, raising a typed
BUDGET_EXCEEDED. A cascade topology further tries the cheapest capable agent first and
escalates only when a tier is not confident enough.
Every release is published with npm publish --provenance. Check the attestations with
npm view @takk/coryphaeus@<version> --json | jq .dist.attestations. The attestation
links the tarball you installed to the GitHub Actions workflow that built it from a specific source commit.
Strict SemVer 2.0.0, starting from 1.0.0. The binding stability surface is documented in SPEC.md section 5. Major bumps require a deprecation cycle; security fixes follow the disclosure flow in SECURITY.md.