Coryphaeus

Open, local-first, provider-agnostic multi-agent orchestrator. Compose frontier models as a coordinated team with Thinker, Worker, and Verifier roles, inspectable topologies, explicit cost budgets, and an auditable agent graph, all running on your own infrastructure with your own keys, for Massive Intelligence (IM) systems.

Coryphaeus is the open behavioral analogue of a closed multi-agent endpoint, delivered as a zero-runtime-dependency NPM library that runs in your process, not someone else's. A frontier model is strong, but no single model is best at everything, programming, mathematics, security, and long context are won by different providers. Composing several models as a coordinated team raises the ceiling, and the market answer so far is to either hand-wire fragile graphs in a framework or hand the whole task to a closed endpoint that hides which model answered, prices at the top of its pool, blocks the EU, and runs minutes-long. Coryphaeus takes the third path: a pluggable Regent decides, per task, which agents to activate, assigns the roles, runs an inspectable topology, governs verification and synthesis, and emits everything as an auditable agent graph. You always see the recipe.

Core promise: zero required runtime dependencies, two-line setup, an injectable client so the orchestration logic stays provider-agnostic and testable offline, transparent routing with the Regent's decision and rationale on every run, explicit USD budgets with a pre-dispatch forecast and a hard ceiling, four declarable topologies, a tamper-evident audit trail over Web Crypto, a node-free core that runs in Node, edge runtimes, and the browser, ESM plus CJS dual distribution, and a framework-agnostic tool adapter that binds to any MCP server, OpenAI-compatible endpoint, or the Vercel AI SDK with no hard dependency.

---

Why Coryphaeus

Composing frontier models as a team is a coordination problem with a control constraint. You want the strongest possible answer from a pool of black-box models, without giving up visibility into how it was produced, what it cost, or where it ran. The two reflexive answers both fail. Hand-wiring a graph in a framework fixes the roles and topology in code and rewrites everything when you change providers. Outsourcing to a closed endpoint buys you a single opaque box: you cannot see which model answered, you pay at the ceiling of the pool, the latency is whatever the box decides, and in the EU and EEA you may not be able to use it at all. Coryphaeus uses the correct primitive: a learned-or-heuristic coordinator that picks an arrangement per task and exposes it, over a pool you own, with a budget you set, on infrastructure you control.

What sets it apart from a closed orchestration endpoint:

• Open and local-first. It runs in your process, on your infrastructure, with your keys. No regional block, no vendor in the middle of every call. Sovereignty is the default, not a tier.
• Transparent routing. Every run returns the Regent's chosen topology, the role each agent played, the per-step cost, and a plain-language rationale. The agent graph is the receipt; nothing about the composition is hidden.
• Explicit cost control. Stacking model calls is the cost risk, so Coryphaeus forecasts the dollar cost of an arrangement before any model is called and enforces a hard ceiling that raises a typed BUDGET_EXCEEDED before a breaching step is ever dispatched.
• Latency control. A fast mode favors a single worker, the analogue of a base single-shot call; a deep mode favors multi-agent collaboration. You choose the trade per task.
• Configurable roles. Thinker, Worker, and Verifier are first-class and overridable, the opposite of an endpoint that hides them. You see and control how each agent is framed.
• Provider-agnostic by construction. The core never speaks a provider API. You inject a client, an OpenAI-style chat function, a Vercel AI SDK call, a local model, or a deterministic mock, and the same orchestration logic runs against any of them.
• Inspectable topologies. Single, pipeline (Thinker to Worker to Verifier), parallel (independent workers then a governed synthesizer), and cascade (cheapest first, escalate on low confidence). Each is declarable and renders to JSON, Graphviz DOT, or Mermaid.
• Proves what was composed. A tamper-evident SHA-256 hash-chained audit trail of runs and decisions, the evidence a review asks for when an answer is questioned, sealed over the Web Crypto API.

---

Install

pnpm add @takk/coryphaeus
# or: npm install @takk/coryphaeus
# or: yarn add @takk/coryphaeus
# or: bun add @takk/coryphaeus

The core has zero required runtime dependencies. Every @takk sibling is an optional peer; install only what you compose with.

---

Quickstart

import { agentClientFromChat, Coryphaeus, defineAgent } from "@takk/coryphaeus";

// 1. Describe your pool. Each agent is a black box: an id, a provider, a model, the roles it may play, its cost.
const pool = [
  defineAgent({ id: "planner", provider: "openai", model: "o-planner", roles: ["thinker"], quality: 0.9, cost: { inputPerMTok: 5, outputPerMTok: 15 } }),
  defineAgent({ id: "builder", provider: "anthropic", model: "claude-builder", roles: ["worker"], quality: 0.82, cost: { inputPerMTok: 3, outputPerMTok: 15 } }),
  defineAgent({ id: "checker", provider: "google", model: "gemini-checker", roles: ["verifier"], quality: 0.86, cost: { inputPerMTok: 1, outputPerMTok: 5 } }),
];

// 2. Inject your model caller. The orchestrator never speaks a provider API directly; you wrap your own.
const client = agentClientFromChat(async ({ model, system, messages }) => {
  // call your OpenAI-compatible endpoint for `model` with `system` and `messages`, return { content, usage }
  return { content: "...", usage: { inputTokens: 0, outputTokens: 0 } };
});

// 3. Orchestrate. The Regent picks the arrangement; the run comes back as an auditable graph.
const coryphaeus = new Coryphaeus({ client, agents: pool });
const result = await coryphaeus.run({ input: "Draft a sharded-database migration plan with a rollback path." });

console.log(result.topology);                 // "pipeline", chosen for a medium-complexity task
console.log(result.output);                   // the final answer
console.log(result.cost.costUsd);             // total USD across every step
console.log(result.provenance.contributors);  // which graph nodes produced the answer

run plans an arrangement, executes it through your injected client, and returns the final answer plus the full agent graph, the cost tally, and the provenance. Nothing about the routing is hidden.

---

Use a real provider

The injected client is the only place a provider is touched, so wiring a real endpoint is a small function. Any OpenAI-compatible endpoint:

import { agentClientFromChat } from "@takk/coryphaeus";

const client = agentClientFromChat(async ({ model, system, messages }) => {
  const res = await fetch("https://api.openai.com/v1/chat/completions", {
    method: "POST",
    headers: { "content-type": "application/json", authorization: `Bearer ${process.env.OPENAI_API_KEY}` },
    body: JSON.stringify({ model, messages: [{ role: "system", content: system }, ...messages] }),
  });
  const json = await res.json();
  return {
    content: json.choices[0].message.content,
    usage: { inputTokens: json.usage.prompt_tokens, outputTokens: json.usage.completion_tokens },
  };
});

Or the Vercel AI SDK, where you own the provider object:

import { agentClientFromVercel } from "@takk/coryphaeus";
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

const client = agentClientFromVercel(({ model, system, messages }) =>
  generateText({ model: openai(model), system, messages }),
);

The same orchestration runs against either, and against a local model, a mock, or a mix, because the core never knows which provider answered.

---

See the plan before you run it

import { Coryphaeus, createEchoClient, defineAgent } from "@takk/coryphaeus";

const coryphaeus = new Coryphaeus({ client: createEchoClient(), agents: pool });

const arrangement = coryphaeus.plan({ input: "Quick lookup." });
arrangement.topology;   // "single", a low-complexity task takes the fast path
arrangement.rationale;  // a plain-language explanation of the choice

const forecast = coryphaeus.forecast({ input: longTaskText });
forecast.estimatedCostUsd;  // the dollar cost before any model is called
forecast.perStep;           // the cost attributed to each agent and role

plan returns the Regent's arrangement without executing it. forecast prices that arrangement before any model call, so cost is a decision you make up front, not a surprise on the invoice. createEchoClient is a deterministic offline client for local runs and tests; production injects a provider-backed client.

---

Topologies

The Regent picks one of four coordination shapes per task, and you can force one. Each is inspectable and renders to a graph.

// Force a parallel debate: independent workers answer, a verifier synthesizes with provenance.
import { Coryphaeus, createRegent } from "@takk/coryphaeus";

const coryphaeus = new Coryphaeus({
  client,
  agents: pool,
  regent: createRegent({ forceTopology: "parallel", maxParallelWorkers: 3 }),
});
const result = await coryphaeus.run({ input: hardTask });

Topology	Shape	When the heuristic picks it
single	One worker answers directly.	Low complexity, or fast latency. The analogue of a single-shot call.
pipeline	Thinker to Worker to Verifier, each stage refines the last.	Medium complexity in deep mode.
parallel	Independent workers, then a governed synthesizer merges them.	High complexity in deep mode with two or more workers.
cascade	Cheapest agent first, escalate only when a tier is not confident enough.	High complexity in fast mode. Cost-aware.

A cascade reads the optional confidence a client may report on each result and stops escalating once a tier clears the threshold (default 0.7), so a provider that returns a confidence signal, or a verifier that scores its own answer, drives cost-aware escalation.

---

The auditable agent graph

Every run is a graph: a node per agent invocation (its role, model, input, output, tokens, and cost) and an edge per data dependency. It renders to JSON, Graphviz DOT, or Mermaid.

import { renderDot, renderMermaid } from "@takk/coryphaeus";

const result = await coryphaeus.run({ input: task });
result.nodes;       // every agent invocation with its measured cost
result.edges;       // how the answer flowed between agents
renderDot(result);  // paste into any DOT renderer
renderMermaid(result);

This is the answer to the loudest criticism of a closed endpoint, that its routing is a black box. Here the whole arrangement is a value you can log, render, diff, and review.

---

Cost and latency control

// A hard ceiling stops a run before a breaching step is dispatched.
try {
  await coryphaeus.run({ input: task }, { budgetUsd: 0.01 });
} catch (error) {
  error.code; // "BUDGET_EXCEEDED" when the forecast would breach the ceiling
}

// Trade latency for depth per task.
await coryphaeus.run({ input: task, latencyMode: "fast" }); // a single worker, lowest latency
await coryphaeus.run({ input: task, latencyMode: "deep" }); // multi-agent collaboration

Unpredictable cost and high latency are two of the criticisms a closed endpoint draws. Coryphaeus makes both a knob: the budget is forecast and enforced, and the latency mode is yours to set.

---

Entry points

Twelve subpath exports, each importable on its own. The core is node-free; only node touches a Node built-in.

Import	What it gives you
@takk/coryphaeus	The full toolkit barrel: the orchestrator, the Regent, roles, topologies, budget, synthesis, the graph, audit, and the adapters.
@takk/coryphaeus/orchestrator	The Coryphaeus facade: register agents, plan, forecast, run, snapshot.
@takk/coryphaeus/regent	The RegentStrategy seam, the heuristic regent, and complexity estimation.
@takk/coryphaeus/roles	Thinker, Worker, and Verifier definitions and their overridable system scaffolds.
@takk/coryphaeus/topology	The single, pipeline, parallel, and cascade executors.
@takk/coryphaeus/agent	Agent descriptors, branded ids, the registry, and the deterministic echo client.
@takk/coryphaeus/graph	The agent-graph builder and the JSON, DOT, and Mermaid renderers, plus provenance.
@takk/coryphaeus/budget	Token estimation, cost pricing, and the BudgetTracker with a hard ceiling.
@takk/coryphaeus/synthesis	The governed synthesizer scaffold and the deterministic merge.
@takk/coryphaeus/adapter	The OpenAI-style and Vercel AI SDK client adapters and the orchestrate tool.
@takk/coryphaeus/audit	Append-only SHA-256 hash-chained audit log of runs and decisions, via Web Crypto.
@takk/coryphaeus/node	JSON loaders for an agent roster, a task, and a saved run graph.
@takk/coryphaeus/edge	The node-free core, re-exported for edge runtimes and the browser.

---

A tool for a non-human entity

The adapter exposes Coryphaeus as a framework-agnostic tool a non-human entity can call to compose a fleet of models with a single call. The descriptor shape, a name, a description, a JSON Schema, and a handler, matches what MCP servers and tool-calling APIs expect, and input arriving from a model is parsed defensively. The agent pool is fixed by the host, not the caller.

import { createOrchestrateTool } from "@takk/coryphaeus/adapter";

// Register the tool with your MCP server or tool-calling API; its name is "coryphaeus_orchestrate".
const tool = createOrchestrateTool(coryphaeus);
const result = await tool.handler({
  task: "Audit the dependency tree for known advisories and propose pinned versions.",
  complexity: "high",
});

This is the loop a non-human entity (NHE) closes over a pool of models it operates: it composes them per task, sees the graph it produced, and pays only what it agreed to.

---

Tamper-evident audit trail

import { AuditChain, verifyChain } from "@takk/coryphaeus/audit";

const chain = new AuditChain();
await coryphaeus.run({ input: task }, { chain });           // seal the run as it completes
await chain.append({ kind: "decision", approved: true });

await verifyChain(chain.toArray()); // { valid: true }, until any entry is altered

Each run and each decision is recorded append-only and chained to the previous one through a SHA-256 hash of its canonical form. Any later edit, deletion, or reordering breaks the chain and verifyChain reports the first broken entry. The seal is an integrity seal, not a digital signature: it proves the record was not tampered with, not who produced it. The chain uses the Web Crypto API, so the audit surface runs in Node, edge runtimes, and the browser.

---

CLI

Coryphaeus ships a command-line tool that runs the real orchestrator. Because the CLI carries no provider credentials, run orchestrates with a deterministic offline client behind --mock; real runs use the library API with an injected client.

# Show the regent's arrangement and a cost forecast for a task, no execution.
npx @takk/coryphaeus plan task.json --agents agents.json

# Orchestrate the task offline with the deterministic client, writing the full run to a file.
npx @takk/coryphaeus run task.json --agents agents.json --mock --out run.json

# Render a saved run graph to Graphviz DOT, Mermaid, or JSON.
npx @takk/coryphaeus graph run.json --format mermaid

# Verify a sealed audit chain.
npx @takk/coryphaeus audit-verify chain.json

Exit codes are explicit: 0 ok, 2 usage or input error, 30 the budget ceiling tripped, 20 a broken audit chain. See examples/ for runnable demos that orchestrate against the built artifact end to end.

---

How it works, in one paragraph

A task carries an input and optional hints (complexity, latency mode). The Regent estimates complexity, reads the latency preference, and selects a topology and a cast of agents, assigning each a role and explaining the choice in a rationale. The topology executor runs the arrangement through the injected client: a single worker answers directly; a pipeline threads each stage's output forward as context for the next; a parallel debate dispatches independent workers concurrently and hands their answers to a governed synthesizer; a cascade tries the cheapest agent first and escalates only when a tier's confidence falls below the threshold. Every invocation becomes a node in the agent graph, priced against the agent's cost profile, and a budget tracker forecasts each step and refuses any that would breach the ceiling. Provenance is read off the graph by walking the edges back from the final node. Optionally the whole run is sealed into a SHA-256 hash chain over the Web Crypto API. The core never speaks a provider API; it is orchestration logic over an injectable client, which is what keeps it provider-agnostic, node-free, and testable with no network.

---

What the examples show

The runnable demos in examples/ orchestrate against the built artifact, with every number produced by execution:

• orchestration-graph runs a medium task as a pipeline and prints the graph, the provenance, and the DOT render.
• budget-forecast forecasts a task's cost, runs it under a generous ceiling, then trips a tight ceiling to show enforcement.
• cascade-escalation runs a fast hard task across a cheap, a mid, and a frontier worker, escalating tier by tier until confidence clears the threshold, and reports the cost climbing with it.
• auditable-trail seals three runs into one chain, verifies it, then tampers with a sealed cost and watches verification break at exactly that entry.
• adapter-and-tool wraps an OpenAI-style chat function as the client and exposes the orchestrator as an MCP-shaped tool.

---

Does composition actually help?

A fair question, and benchmarks/composition-benchmark.mjs answers it with measured, reproducible numbers run through the built orchestrator. It is a mechanism demonstration under a controlled error model with known ground truth, the agents are deterministic mocks with declared accuracy, not a claim about any specific LLM's quality. Each regime runs 4000 tasks on a fixed seed:

Regime	Single worker	Composed	Result
Parallel majority, independent errors	60.6% accurate	81.4% accurate	error cut 52.8% (the Condorcet effect)
Parallel majority, correlated errors	59.4% accurate	59.4% accurate	no gain, the honest limit
Pipeline Worker then Verifier (recall 0.5)	60.5% accurate	80.4% accurate	verifier recovers about recall times the error rate

The takeaway is honest in both directions: composing independent agents and taking the majority, or threading a verifier behind a worker, measurably reduces error; but when agents fail together, composition is not a free lunch. Coryphaeus gives you the topology and the graph to see which case you are in. Reproduce with pnpm run build && node benchmarks/composition-benchmark.mjs.

---

Quality

• 93 tests across 12 suites, all passing under Vitest on Node 20, 22, and 24.
• Coverage: statements 98%, branches 87.47%, functions 100%, lines 97.94%.
• Lint clean under Biome.
• Typecheck clean under TypeScript in maximum strict mode (exactOptionalPropertyTypes, useUnknownInCatchVariables, noUncheckedIndexedAccess, noPropertyAccessFromIndexSignature).
• publint clean and @arethetypeswrong/cli green across all twelve subpaths.
• size-limit under budget on every bundle (brotli core 6.17 kB).
• Distribution smoke test exercising the compiled ESM and CJS artifacts and the compiled CLI spawned as a single Node process.
• Zero required runtime dependencies; a node-free core that runs in Node, edge runtimes, and the browser; dual ESM plus CJS; TypeScript-first.

See SPEC.md for the formal specification, public surface, and stability promise.

---

FAQ

How is this different from a closed multi-agent endpoint? A closed endpoint is one opaque box: you cannot see which model answered, you pay at the ceiling of its pool, the latency is whatever it decides, and it may be unavailable in your region. Coryphaeus runs in your process over your pool with your keys, exposes the routing as a graph, forecasts and caps cost, and lets you pick the latency mode. The composition is open and yours.

Does Coryphaeus call any model itself? 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 mock), and the orchestrator drives it. That is what keeps the package provider-agnostic, dependency-free, and testable with no network.

How does it control cost? Each agent carries a cost profile. The orchestrator 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 needed.

Which providers does it support? 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 OpenAI-style chat and the Vercel AI SDK.

Can a non-human entity drive it? Yes. The adapter exposes the orchestrator as a framework-agnostic tool (coryphaeus_orchestrate) with a JSON Schema and a handler, ready to register with an MCP server or any tool-calling API. The pool is fixed by the host, never by the caller.

Does this work in Cloudflare Workers, Vercel Edge, Bun, and Deno? Yes. The core is node-free; the audit seal uses the Web Crypto API, not node:crypto. Import @takk/coryphaeus or @takk/coryphaeus/edge anywhere with Web Crypto. Only @takk/coryphaeus/node requires Node.

---

Contributing

See .github/CONTRIBUTING.md for the contributor guide. Substantive proposals open a GitHub Issue first; trivial fixes can go straight to a PR. All commits require DCO sign-off (git commit -s). Non-trivial contributions are governed by the Contributor License Agreement.

Community and support

• Issues and feature requests. Open a GitHub issue at davccavalcante/coryphaeus/issues. Include the package version, a minimal reproduction, expected versus actual behavior, and where relevant the plan() or run() output.
• Security disclosures. Do not open public issues for vulnerabilities. Follow the responsible-disclosure flow in SECURITY.md, contact davcavalcante@proton.me (or say@takk.ag) with the [SECURITY] prefix.
• Code of Conduct. This project follows the Contributor Covenant 2.1. Participation in any Coryphaeus space implies agreement.
• Contributions. All non-trivial contributions go through the Contributor License Agreement. Tests, lint, typecheck, and build must be green before review (pnpm verify).

---

Author

Created by David C Cavalcante, davcavalcante@proton.me (preferred), say@takk.ag (Takk relay), linkedin.com/in/hellodav, x.com/davccavalcante, takk.ag.

Coryphaeus is part of a broader portfolio of NPM packages targeting Massive Intelligence (IM) native infrastructure for 2026-2030, built at Takk Innovate Studio. Open, auditable behavioral composition of black-box models is foundational infrastructure for that era, the control plane that lets a fleet of non-human entities act as one without surrendering control of how.

---

Related research by the author

The architectural philosophy behind Coryphaeus, composing many intelligences as one coordinated entity while keeping every decision inspectable, echoes the author's research frameworks:

• MAIC (Massive Artificial Intelligence Consciousness), a systemic intelligence framework designed to coordinate, supervise, and govern large-scale Massive Intelligence ecosystems, providing global context awareness, alignment, and orchestration across multiple models, agents, and decision layers.
• HIM (Hybrid Entity Intelligence Model), a hybrid intelligence layer that integrates Massive Intelligence systems with human-defined logic, rules, heuristics, and strategic intent, interpreting objectives and structuring decision-making before and after model execution.
• NHE (Noumenal Higher-order Entity), a non-human cognitive entity with a defined functional identity and operational agency within a Massive Intelligence ecosystem, operating through coordinated intelligence layers while maintaining a non-anthropomorphic identity.

These frameworks are published independently of Coryphaeus and are separate works:

• Research papers: The Soul of the Machine, Beyond Consciousness in LLMs, The Cave of Silence.
• PhilPapers profile: David Cortes Cavalcante.
• Hugging Face: TeleologyHI.
• GitHub: davccavalcante, Takk8IS.

---

Sponsors

Join the journey as the portfolio continues to ship Massive Intelligence (IM) native infrastructure. Your support is the cornerstone of this work.

• Sponsor on GitHub: github.com/sponsors/davccavalcante
• USDT (TRC-20): TS1vuhMAhFpbd7y68cu5ZtP9PsXVmZWmeh

---

Privacy

Coryphaeus runs entirely inside your own process and infrastructure. It makes no outbound calls to the author, collects no telemetry, and ships no analytics. The only model calls are the ones your injected client makes to the providers you choose. See PRIVACY.md for the full data-handling notice, including how the optional file loaders read an agent roster and a task from disk.

---

License

Licensed under the Apache License 2.0. See LICENSE for the full text and NOTICE for attribution and third-party component licenses. You may use, modify, and distribute the code under the terms of that license, including its patent grant and attribution requirements.