[PUBLISHED ON NPMJS] @takk/coryphaeus@1.0.0

STATUS: PUBLISHED ON NPMJS. This version was published to the npm registry on 2026-06-29T20:54:27Z with provenance attestation. View on npm: https://www.npmjs.com/package/@takk/coryphaeus/v/1.0.0

STATUS: REVIEW REQUIRED, NOT YET ON NPMJS. This GitHub Release was created by the release.yml workflow. The Creator must review the contents (tag, changelog, attached commit, pack-smoke result in the workflow logs) and then explicitly run npm-publish.yml to publish this version to the npm registry.

1.0.0 - 2026-06-29T20:37:23Z

Initial stable release. Coryphaeus is a universal, zero-runtime-dependency NPM library and CLI that composes several frontier models as one coordinated team, the open, local-first, provider-agnostic control plane for multi-agent Massive Intelligence (IM) systems and non-human entities. A pluggable Regent decides, per task, which agents to activate, assigns the Thinker, Worker, and Verifier roles, runs an inspectable coordination topology, forecasts and enforces a cost budget, governs verification and synthesis, and emits everything as an auditable agent graph. The core never speaks a provider API; it is orchestration logic over an injectable client, which keeps it provider-agnostic, node-free, and testable offline.

Added

Orchestrator

• Coryphaeus (@takk/coryphaeus/orchestrator): the facade most callers use. It exposes register, registerAll, and unregister for the agent pool, agents, plan (the Regent's arrangement without execution), forecast (the USD cost of an arrangement before any model call), run (execute and return a RunResult), snapshot, and a static fromSnapshot. Run options carry a fixed runId, a per-run budgetUsd ceiling, an AuditChain to seal into, and a timestamp.

Regent

• RegentStrategy, HeuristicRegent, and createRegent (@takk/coryphaeus/regent): the pluggable coordinator. The 1.0 Regent is a transparent heuristic that estimates complexity from input length (estimateComplexity, thresholds configurable), reads the latency mode, and selects a topology and a cast of agents, explaining each choice in the arrangement's rationale. A learned strategy is a later release behind the same seam, with no change to the executor.

Topologies

• executeArrangement and the single, pipeline, parallel, and cascade executors (@takk/coryphaeus/topology). Single answers with one worker; pipeline threads Thinker to Worker to Verifier so each stage refines the last; parallel dispatches independent workers concurrently and hands their answers to a governed synthesizer with provenance; cascade tries the cheapest agent first and escalates only when a tier reports confidence below the threshold (default 0.7). Budget is reserved against the running ledger before any concurrent dispatch.

Roles

• Thinker, Worker, and Verifier (@takk/coryphaeus/roles): ROLES, ROLE_SCAFFOLDS, roleLabel, roleScaffold, composeSystem (the role scaffold prepended to the task's own system instruction), canPlay, and assertRole. The scaffolds are exported and overridable, the deliberate opposite of an endpoint that hides them.

Agents and the injectable client

• defineAgent, agentId, nodeId, runId, qualityOf, costRank, AgentRegistry, and createEchoClient (@takk/coryphaeus/agent). An agent is any model from any provider, described by an id, a provider, a model, the roles it may play, a cost profile, and a quality weight, validated and frozen. createEchoClient is a deterministic offline client for the CLI --mock path, the tests, and local runs.
• The AgentClient.invoke(invocation) contract is the seam that keeps the core provider-agnostic. An optional self-reported confidence on a result drives cost-aware cascade escalation.

Budget

• estimateTokens, costOf, emptyTally, addToTally, BudgetTracker, and ZERO_COST (@takk/coryphaeus/budget): token estimation from text, USD pricing against a per-agent cost profile (a cached rate defaults to the input rate), and a running ledger with an optional hard ceiling. The orchestrator forecasts each step and assertCanAfford raises a typed BUDGET_EXCEEDED before a breaching call is dispatched.

Synthesis

• SYNTHESIS_SCAFFOLD, composeSynthesisSystem, and governedSynthesis (@takk/coryphaeus/synthesis): the governed aggregator that a parallel arrangement ends in, either an agent synthesizer over the worker contributions or a deterministic, model-free merge that keeps provenance.

The auditable agent graph

• AgentGraph, renderDot, renderMermaid, and provenanceOf (@takk/coryphaeus/graph): every run is a graph, a node per agent invocation carrying its role, model, input, output, tokens, and cost, and an edge per dependency. It renders to JSON, Graphviz DOT, or Mermaid, and provenance is read off the edges by walking back from the final node.

Adapters and the tool

• agentClientFromChat, agentClientFromVercel, toAdapterRequest, createOrchestrateTool, describeOrchestrateTool, parseOrchestrateInput, toJsonSafe, and ORCHESTRATE_TOOL_NAME (@takk/coryphaeus/adapter). Two-line bridges wrap an OpenAI-style chat function or a Vercel AI SDK call as the injected client, and the orchestrator is exposed as a framework-agnostic tool (name coryphaeus_orchestrate) with a JSON Schema and a JSON-safe handler, ready to register with an MCP server or any tool-calling API. Model-supplied input is parsed defensively; the agent pool is fixed by the host, never the caller.

Audit trail

• AuditChain, verifyChain, sha256Hex, and GENESIS_HASH (@takk/coryphaeus/audit): an append-only, SHA-256 hash-chained log of runs and decisions over the Web Crypto API, so the surface stays node-free. 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.

Node loaders and the edge mirror

• loadAgents, loadTask, loadRun, and readJsonFile (@takk/coryphaeus/node): the only entry that touches a Node built-in, reading an agent roster, a task, or a saved run graph from JSON. @takk/coryphaeus/edge re-exports the node-free core for Cloudflare Workers, Vercel Edge, Bun, Deno, and the browser.

CLI

• The coryphaeus binary: plan <task.json> --agents <agents.json> (the Regent's arrangement and a cost forecast, no execution), run ... --mock (orchestrate offline with the deterministic client, optionally writing the run to a file), graph <run.json> (render a saved run to DOT, Mermaid, or JSON), and audit-verify <chain.json>. Exit codes: 0 ok, 2 usage or input error, 30 the budget ceiling tripped, 20 a broken audit chain. The CLI carries no provider credentials; real runs use the library API with an injected client.

Errors

• CoryphaeusError with a stable, machine-readable code (@takk/coryphaeus): INVALID_CONFIG, INVALID_AGENT, INVALID_TASK, INVALID_ROLE, INVALID_TOPOLOGY, INVALID_ARRANGEMENT, BUDGET_EXCEEDED, INVALID_STATE, INVALID_SNAPSHOT, NUMERIC. Callers branch on error.code, never on the message.

Examples and the composition benchmark

• Five runnable examples that orchestrate against the built dist: an orchestration graph with DOT render, a budget forecast and ceiling enforcement, a cascade escalation across cheap, mid, and frontier tiers, an auditable trail with tamper detection, and a chat adapter plus the orchestrate tool.
• A composition benchmark (benchmarks/composition-benchmark.mjs) that runs the built orchestrator over a controlled error model with known ground truth, 4000 tasks per regime on a fixed seed. It measures the error reduction the topologies contribute: parallel majority over independent errors cuts error 52.8% (60.6% to 81.4% accurate, the Condorcet effect); the same majority over correlated errors adds nothing (the honest limit); a pipeline Worker then Verifier with recall 0.5 lifts accuracy from 60.5% to 80.4%. It is a mechanism demonstration, not an LLM quality claim.

Engineering

• Zero required runtime dependencies; a node-free core (the audit seal uses the Web Crypto API, not node:crypto); dual ESM and CJS distribution with separate .d.ts and .d.cts per subpath; twelve functional subpath exports plus ./package.json.
• TypeScript 6 in maximum strict mode (exactOptionalPropertyTypes, useUnknownInCatchVariables, noUncheckedIndexedAccess, noPropertyAccessFromIndexSignature, verbatimModuleSyntax, isolatedModules). Biome 2.5 lint clean.
• 93 tests across 12 suites passing under Vitest 4 on Node 20, 22, and 24. Coverage: statements 98%, branches 87.47%, functions 100%, lines 97.94%, above the 80/80/80/80 thresholds.
• publint clean and @arethetypeswrong/cli green across all twelve subpaths. size-limit under budget on every bundle (brotli core 6.17 kB). A distribution smoke test exercises the compiled ESM and CJS artifacts and spawns the compiled CLI as a single Node process.
• SLSA provenance attestation on every published version via GitHub Actions OIDC.

Not in 1.0 (documented non-goals)

• A learned Regent (the 1.0 Regent is a transparent heuristic; a learned strategy with policies via bandits is planned behind the same RegentStrategy seam).
• Recursive self-composition, streaming token output, a built-in transport or provider SDKs, a runnable MCP server binary, and signed and timestamped audit seals, all planned for later releases.