# @zhixuan92/multi-model-agent-core

**Runtime library for multi-model-agent.** Import it to run multi-provider agent tasks directly from your own Node program — same routing, supervision, and review pipeline, without the HTTP server.

> **Want the standalone service instead?** Install [`@zhixuan92/multi-model-agent`](https://www.npmjs.com/package/@zhixuan92/multi-model-agent) — it wraps this library in a local HTTP daemon that provisions eight canonical clients — Claude Code, Claude Desktop, Codex, Antigravity, Cursor, VS Code, opencode and Windsurf.

## Install

```bash
npm install @zhixuan92/multi-model-agent-core
```

Requires Node >= 22. ESM only.

## Quick example

```ts
import { loadConfigFromFile } from '@zhixuan92/multi-model-agent-core/config/load';
import { runTwoPhasePipeline, loadSkill, ExecutionRegistry } from '@zhixuan92/multi-model-agent-core';

const config = await loadConfigFromFile();
```

## What's inside

- **Provider runners** — Claude (via agent-sdk) and Codex (via CLI subprocess), plus any OpenAI-compatible endpoint
- **Unified task API** — all 12 task types (delegate, audit, review, debug, execute-plan, investigate, research, journal-record, journal-recall, orchestrate, spec, plan) flow through a single two-phase pipeline
- **Skill-driven prompts** — each task type has `implement.md` + `review.md` skill files that drive worker behavior
- **Model profile registry** — 32 model families with cost/tier/effort metadata for routing and cost computation
- **Bounded execution** — per-task wall-clock deadlines, idle-stall detection, abort signals, and cost tracking
- **Observability** — structured event envelopes, JSONL logging, telemetry upload with consent rules

## Subpath exports

| Subpath | What |
|---|---|
| `.` | Main entry — providers, task types, pipeline, config, reporting, observability |
| `./config/schema` | `parseConfig`, `multiModelConfigSchema`, `serverConfigSchema` |
| `./config/load` | `loadConfigFromFile`, `loadAuthToken` |
| `./config/model-profile-registry` | `findModelProfile`, `extractCanonicalModelName`, model family enum |
| `./bounded-execution/cost-compute` | `resolveRateCard`, per-run cost computation |
| `./types` | Cross-cutting types (task spec, run result, config, enums) |
| `./error-codes` | Error code constants |
| `./events/envelope-bus` | `EnvelopeBus` — pub/sub for structured observability |
| `./events/log-writer` | `LogWriter` — JSONL diagnostic sink |
| `./events/task-envelope` | `TaskEnvelope` + stage/finding types — per-task lifecycle shape |
| `./events/telemetry-uploader` | `TelemetryUploader` — wire record upload |
| `./events/stderr-log-subscriber` | `StderrLogSubscriber` — stderr event echo |
| `./events/consent-rules` | `decideConsent` — env / config / default precedence |
| `./events/wire-schema` | Wire record Zod schema (v6) |
| `./events/jsonl-writer` | `JsonlWriter` — append-only JSONL file writer |
| `./research` | Research orchestration + adapters (arxiv, semantic-scholar, github, openalex, crossref, pubmed) |

## Diagnostic logging

Diagnostic logging is OFF by default.

```json
{
  "diagnostics": {
    "log": false,
    "logDir": "/some/path"
  }
}
```

When `diagnostics.log` is `true`, JSONL records are appended to `mma-YYYY-MM-DD.jsonl` under `diagnostics.logDir` (defaults to `~/.mma/logs/`).

```bash
mma serve --log       # persist to JSONL
mma logs --follow     # tail + filter
```

## Full documentation

→ **[github.com/zhixuan312/multi-model-agent](https://github.com/zhixuan312/multi-model-agent)**

## License

[MIT](./LICENSE) — Copyright (c) 2026 Zhang Zhixuan