@agntn/harnesses 0.1.0 → 0.2.0

package/README.md

@@ -5,158 +5,172 @@
 [![license](https://npmx.dev/api/registry/badge/license/@agntn/harnesses)](https://npmx.dev/package/@agntn/harnesses)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/agntn/harnesses)
 
-Metadata toolkit for AI coding harnesses. One registry of paths, formats, and detection rules for every major CLI.
+🧭 Thirteen coding CLIs, one map. You ask where Claude keeps skills, you get the path.
 
-Docs: [harnesses.agntn.dev](https://harnesses.agntn.dev)
+> [!WARNING]
+> **@agntn/harnesses is pre-1.0.** Paths follow upstream CLIs that still move. Building on it now means pinning the version.
 
-## Install
+## Why?
+
+Claude stores transcripts under a mangled copy of your cwd. Codex keeps TOML with comments you wanted to keep. Ask a model where Codex lives and it invents `.claude/`. So this is one registry: thirteen harnesses, same object, paths for your machine.
+
+The rest of it sits on [harnesses.agntn.dev](https://harnesses.agntn.dev).
+
+## ✨ Features
+
+- 🧩 **Thirteen harnesses, one class.** Same fields on Claude, Codex, Pi and the rest.
+- 📂 **Every path has a receipt.** Scope, evidence level, and a platform tag when the OS actually differs.
+- 🔎 **Detects which CLI you're inside.** Environment variables first. Two project markers in one directory is `null`, not a guess.
+- ▶️ **Headless runs with real modes.** Advisor without tools, full agent, or a native read-only sandbox. A mode the CLI cannot enforce is rejected.
+- 🔌 **MCP across the dialects.** One master list at `~/.config/agntn/mcp.jsonc`. TOML edits keep the comments.
+- 🔗 **One AGENTS.md behind the global files.** Symlinks, so an edit through Claude or Gemini is the same bytes.
+- 📜 **Session types when the format is stable.** JSONL, SQLite, JSON. Unstable shapes stay `unknown`.
+- 🤖 **Nine tools, three doors.** MCP, Pi and OMP call the same executors.
+
+## 📦 Install
 
 ```bash
 pnpm add @agntn/harnesses
 ```
 
-## Usage
+Node.js 24 or newer.
 
-```ts
-import { getHarness, detectHarness, detectProjectHarnesses } from "@agntn/harnesses";
+## 🚀 First call
 
-const claude = getHarness("claude");
-console.log(claude.skills); // [{ path: ".claude/skills/", scope: "project", ... }, ...]
-console.log(claude.hooks); // [{ path: ".claude/hooks/", scope: "project", ... }, ...]
-console.log(claude.invocationModes); // advisor and full agent modes, no read-only mode
+```bash
+npx @agntn/harnesses detect
+```
+
+```
+  System Scan
+
+    ● antigravity     Google Antigravity CLI  v1.2.5
+    ● claude          Anthropic Claude Code  v2.1.276
+    ● codex           OpenAI Codex CLI  v0.154.0
+    ○ cursor          Cursor
+    ● freebuff        Freebuff
+    ○ gemini          Google Gemini CLI
+    ○ github-copilot  GitHub Copilot
+    ● grok            xAI Grok CLI  v1.0.34
+    ● mastracode      Mastra Code
+    ● omp             OMP (oh-my-pi)  v18.2.4
+    ● opencode        OpenCode CLI  v2.0.5
+    ● prime-agent     Prime Agent  v0.9.5
+    ● pi              Pi Coding Agent  v0.85.1
+```
+
+No key, no config. No network either. `detect` looks at `PATH`. Filled dot is installed, hollow is not. After `pnpm add`, the same command is `pnpm exec harnesses`, or install it once with `pnpm add -g @agntn/harnesses`.
+
+Same binary, more commands:
+
+```bash
+harnesses list
+harnesses info claude
+harnesses paths pi
+harnesses models pi gpt-5.4 --json
+harnesses run claude "review this design"
+harnesses run codex --read-only "review this"
+harnesses mcp-servers list
+harnesses agents sync --check
+```
+
+`run` without `--tools` is the advisor. `--tools` is the full agent. `--read-only` asks the CLI for a sandbox and implies tools. Timeouts, `--cwd` and `--model` sit in the [CLI guide](https://harnesses.agntn.dev/guide/cli).
 
-const codex = getHarness("codex");
-await codex.invoke("Review this patch", { readOnly: true, timeoutMs: 60_000 });
+### Commands
 
-const pi = getHarness("pi");
-const { models } = await pi.listModels({ search: "gpt-5.4" });
-console.log(models); // [{ provider: "openai-codex", id: "gpt-5.4", ... }]
-await pi.invoke("Review this patch", { model: "openai-codex/gpt-5.4", readOnly: true });
+| Command       | What it does                                           | Example                                     |
+| ------------- | ------------------------------------------------------ | ------------------------------------------- |
+| `list`        | Every known harness, id and name                       | `harnesses list`                            |
+| `detect`      | Which ones are installed, with versions                | `harnesses detect`                          |
+| `info`        | Registry entry: modes, capabilities, path templates    | `harnesses info claude`                     |
+| `paths`       | Those templates expanded for this machine              | `harnesses paths pi`                        |
+| `models`      | Models the harness can use, through its native listing | `harnesses models pi`                       |
+| `run`         | One prompt through headless mode                       | `harnesses run claude "review this design"` |
+| `mcp-servers` | MCP servers across the config dialects                 | `harnesses mcp-servers list`                |
+| `agents sync` | Link global instructions files to one master           | `harnesses agents sync --check`             |
+| `mcp`         | The MCP server on stdio                                | `harnesses mcp`                             |
 
-// Resolve to absolute paths for current platform
+`list`, `detect`, `info`, `paths` and `models` take `--json` or `--toon`. `run --json` is different: that one is the harness's own structured output.
+
+## 🧠 Library
+
+```ts
+import { getHarness, detectHarness } from "@agntn/harnesses";
+
+const claude = getHarness("claude");
 const paths = claude.resolve({ platform: "linux", homeDir: "/home/dev" });
-console.log(paths.config); // [{ path: "/home/dev/.claude/settings.json", ... }, ...]
+console.log(paths.skills);
 
-// Detect which agent is running (env vars first, then project markers)
 const active = detectHarness();
-if (active) {
-  console.log(`Running inside ${active.name}`);
-}
+if (active) console.log(active.id);
 
-// Find all agents configured in a project directory
-const harnesses = detectProjectHarnesses("/path/to/project");
+await getHarness("codex").invoke("Review this patch", { readOnly: true });
 ```
 
-Session schemas are typed per agent, so you get structure when parsing JSONL/SQLite/JSON files:
+That's most of it, really. `getHarness` wants an exact id. `detectHarness` uses env vars first, then a single project marker. `invoke()` talks to the CLI. A mode the CLI cannot run comes back as an error, not a quieter one. The rest: [Registry](https://harnesses.agntn.dev/guide/registry), [Invoke](https://harnesses.agntn.dev/guide/invoke), [MCP servers](https://harnesses.agntn.dev/guide/mcp-servers), [Instructions files](https://harnesses.agntn.dev/guide/agents-sync).
 
-```ts
-import type { ClaudeSessionEntry, CodexThread, GeminiConversationRecord } from "@agntn/harnesses";
-```
+## 🗺️ Harnesses
 
-## Supported agents
-
-| Agent           | ID               | Detection     | Skills                | Hooks                    | Sessions       |
-| --------------- | ---------------- | ------------- | --------------------- | ------------------------ | -------------- |
-| Antigravity CLI | `antigravity`    | project       | `.agents/skills/`     | -                        | JSONL + SQLite |
-| Claude Code     | `claude`         | env + project | `.claude/skills/`     | `.claude/hooks/`         | JSONL          |
-| Codex CLI       | `codex`          | project       | `.agents/skills/`     | -                        | SQLite + JSONL |
-| Gemini CLI      | `gemini`         | env + project | `.gemini/skills/`     | -                        | JSON           |
-| Grok CLI        | `grok`           | env + project | `.grok/skills/`       | `.grok/hooks/`           | TOML + JSONL   |
-| OpenCode        | `opencode`       | project       | `.opencode/skills/`   | -                        | SQLite         |
-| Cursor          | `cursor`         | env + project | `.cursor/skills/`     | -                        | -              |
-| GitHub Copilot  | `github-copilot` | env + project | `.github/skills/`     | -                        | -              |
-| Mastra Code     | `mastracode`     | project       | `.mastracode/skills/` | `.mastracode/hooks.json` | SQLite         |
-| OMP (oh-my-pi)  | `omp`            | env + project | `.omp/skills/`        | -                        | JSONL + SQLite |
-| Pi Coding Agent | `pi`             | env + project | `.pi/skills/`         | -                        | JSON + JSONL   |
-| Freebuff        | `freebuff`       | project       | `.agents/skills/`     | -                        | JSON + JSONL   |
-
-### Native audio and video input
-
-`audio` and `video` report whether the harness has a verified native route that puts that medium into model context. External conversion, MCP tools, and voice dictation that becomes text do not count. `false` means no native route was verified, not that every possible provider or extension was disproved.
-
-| Agent           | Audio | Video | Evidence boundary                                                           |
-| --------------- | :---: | :---: | --------------------------------------------------------------------------- |
-| Antigravity CLI |  Yes  |  Yes  | Native attachments; documented audio formats and direct video pasting       |
-| Gemini CLI      |  Yes  |  No   | The `read_file` tool supports audio; native video support is not documented |
-| Claude Code     |  No   |  No   | No verified native route                                                    |
-| Codex CLI       |  No   |  No   | No verified native route                                                    |
-| Grok CLI        |  No   |  No   | Its ACP parser recognizes audio blocks, but the runtime rejects them        |
-| OpenCode        |  No   |  No   | Its attachment documentation explicitly excludes audio and video            |
-| Cursor          |  No   |  No   | Voice input is transcribed to text                                          |
-| GitHub Copilot  |  No   |  No   | Voice input is transcribed locally to text                                  |
-| Mastra Code     |  No   |  No   | No verified native route                                                    |
-| OMP (oh-my-pi)  |  No   |  No   | No verified native route                                                    |
-| Pi Coding Agent |  No   |  No   | No verified native route                                                    |
-| Freebuff        |  No   |  No   | No verified native route                                                    |
-
-Primary references: [Antigravity prompting](https://antigravity.google/docs/cli/prompting/), [Antigravity changelog](https://github.com/google-antigravity/antigravity-cli/blob/main/CHANGELOG.md), [Gemini CLI tools](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/tools.md), [Gemini CLI video request](https://github.com/google-gemini/gemini-cli/issues/27194), [OpenCode attachments](https://opencode.ai/v2/docs/attachments/), [Cursor prompting](https://cursor.com/docs/agent/prompting), and [Copilot CLI voice input](https://docs.github.com/en/copilot/how-tos/copilot-cli/use-copilot-cli/voice-input).
-
-`invoke()` and `listModels()` accept `timeoutMs` and `signal?: AbortSignal`. Unset or `0` means no deadline. An already aborted signal skips spawning. Otherwise, the first cancellation or deadline starts cleanup: Linux and macOS use a dedicated process group, with `SIGTERM` followed by `SIGKILL` after 500 ms even if the root has exited. Windows uses `taskkill /T /F` immediately, with a 2 s budget for that command. Cleanup failures reject the call.
-
-Stopped results retain captured output and set `exitCode: null`. Caller cancellation sets `aborted: true`, a deadline sets `timedOut: true`, and the first reason wins. Both flags are false on normal completion. Later aborts do nothing, and cancelled model listings return no parsed models. Pi, OMP, and MCP tools forward their host request signal, not a JSON argument supplied by the model.
+| ID               | Name                   | Project skills         |
+| ---------------- | ---------------------- | ---------------------- |
+| `antigravity`    | Google Antigravity CLI | `.agents/skills/`      |
+| `claude`         | Anthropic Claude Code  | `.claude/skills/`      |
+| `codex`          | OpenAI Codex CLI       | `.codex/skills/`       |
+| `cursor`         | Cursor                 | `.cursor/skills/`      |
+| `freebuff`       | Freebuff               | `.agents/skills/`      |
+| `gemini`         | Google Gemini CLI      | `.gemini/skills/`      |
+| `github-copilot` | GitHub Copilot         | `.github/skills/`      |
+| `grok`           | xAI Grok CLI           | `.grok/skills/`        |
+| `mastracode`     | Mastra Code            | `.mastracode/skills/`  |
+| `omp`            | OMP (oh-my-pi)         | `.omp/skills/`         |
+| `opencode`       | OpenCode CLI           | `.opencode/skills/`    |
+| `prime-agent`    | Prime Agent            | `.prime/agent/skills/` |
+| `pi`             | Pi Coding Agent        | `.pi/skills/`          |
 
-```ts
-const controller = new AbortController();
-const pending = getHarness("pi").invoke("Review this change", {
-  tools: true,
-  readOnly: true,
-  signal: controller.signal,
-});
-controller.abort();
-const result = await pending;
-console.log(result.aborted);
-```
+That's the project directory. Most of them also keep a copy under your home directory, and a few read someone else's skills folder on purpose. Sessions, hooks, audio, video, the whole sheet: [Harnesses](https://harnesses.agntn.dev/harnesses).
 
-This is command cleanup, not a sandbox. Descendants that leave the POSIX process group, or outlive an already exited root on Windows, cannot be reliably reached by these mechanisms. Inherited output pipes do not extend the wait after cleanup. Scheduling and OS delays can exceed the stated budgets.
+## 🤖 Agents
 
-Each agent is a concrete subclass of the abstract `Harness` class. Custom subclasses can be added with `registerHarness`. Every harness exposes config paths, session locations, instruction files, skills dirs, hooks, commands, persistence formats, capabilities (MCP, vision, audio, video, tools, streaming), detection rules, a normalized non-interactive invocation (`harness.invoke(prompt, { model })`) where the CLI has a headless mode, native model listing (`harness.listModels()`) where the CLI supports it, and its MCP server config files (`listMcpServers`/`addMcpServer`/`removeMcpServer` normalize the dialects; writes rewrite JSON and surgically edit TOML with comments preserved). `syncMcpServers` treats `~/.config/agntn/mcp.jsonc` (JSONC, XDG-aware) as the single source of truth and resets every harness's user-scope MCP config to exactly that list; a top-level `"excludes": ["codex"]` array opts individual harnesses out of the sync (their own servers stay, master-listed names are withdrawn), and `~`/`${HOME}` in commands, args, and env values expand to absolute paths at sync time (harnesses spawn MCP servers without a shell). `syncAgentsFiles` links every harness's global instructions file (CLAUDE.md/AGENTS.md/GEMINI.md) to one master file as symlinks, so an edit made through any harness lands in the single physical copy; `~/.config/agntn/agents.jsonc` sets the `source`, `companions`, and `excludes`, diverged regular files are backed up and relinked, and check mode reports without writing. Companion paths are relative to the source directory and are linked at the same relative path beside each harness target.
+```bash
+harnesses mcp
+pi install npm:@agntn/harnesses
+omp install @agntn/harnesses
+```
 
-```jsonc
+```json
 {
-  "source": "bundle/AGENTS.md",
-  "companions": ["RULES.md"],
-  "excludes": ["codex"],
+  "mcpServers": {
+    "harnesses": { "command": "npx", "args": ["-y", "@agntn/harnesses", "mcp"] }
+  }
 }
 ```
 
-All paths carry `scope` (user/project/system/data), `level` (official/community/inferred), and optional `platforms` tags.
+Nine tools, the same nine on MCP, Pi and OMP. `harnesses_detect`, `harnesses_info` and `harnesses_mcp_list` only read. `harnesses_run` is the one that can spend tokens. `tools` is required, so the model has to pick advisor or agent. What each call returns is on the [Agents page](https://harnesses.agntn.dev/guide/agents).
 
-The `harnesses_info` agent tool accepts one harness id or a batch of up to 20 ids. Batch results keep the input order and include errors for unknown ids beside successful metadata.
+## 🚫 What this does not do
 
-## CLI
+It does not install skills, drive a browser, or run a sandbox of its own. `invoke()` is the harness CLI plus process cleanup. The wide, thin agent list is [unagent](https://github.com/onmax/unagent).
 
-```bash
-harnesses list                  # all known harnesses
-harnesses detect                # which ones are installed + versions
-harnesses info claude           # metadata, including supported invocation modes
-harnesses paths claude          # resolved paths for current platform
-harnesses info codex --json     # machine-readable output
-harnesses models pi             # models available to Pi
-harnesses models pi gpt-5.4 --json
-harnesses run claude "review this design"       # advisor without tools mode (default)
-harnesses run pi --model openai-codex/gpt-5.4 "review this design"
-harnesses run claude --tools "fix lint"         # full agent with tools enabled
-harnesses run codex --read-only "review this"   # tools inside a native read-only sandbox
-harnesses mcp-servers list      # MCP servers configured across all harnesses
-harnesses mcp-servers add omp probe --command node --args "srv.mjs mcp"
-harnesses mcp-servers remove omp probe
-harnesses mcp-servers sync      # reset all harnesses to ~/.config/agntn/mcp.jsonc
-harnesses agents sync --check   # doctor: link global AGENTS.md files to one master
-harnesses mcp                   # run the MCP server over stdio
-```
-
-`tools` defaults to `false` in the library and CLI. The MCP, Pi, and OMP tools require agents to choose it explicitly. `false` must use a native CLI flag that removes tools from the model context; it is a lightweight advisor, not an agent constrained only by prompt wording. Set `tools: true` (or CLI `--tools`) whenever the task needs harness tools, including Grok's native X search. Add `readOnly: true` when those tools must stay inside a sandbox enforced by the harness CLI; the agent tools pass it beside `tools: true`, while the library and CLI let it imply tools. Read-only mode is rejected when a harness has no verified native recipe, so it never falls back to broader access. A recipe can also carry the lowest CLI version whose enforcement was verified, and `invoke()` rejects read-only runs on older or unknown versions: Grok runs `--sandbox read-only` from 1.0.13, and Claude Code keeps read-only runs on `Read`, `Glob` and `Grep` with `--strict-mcp-config` from 2.1.175. Harnesses whose CLI cannot disable tools reject advisor mode instead of silently running an agent and return an explicit `tools` retry when their full agent mode can handle the request.
+## 🧩 Adding a harness
 
-## How harnesses compares to unagent
+Want a fourteenth? One class extending `Harness`, then `registerHarness`. `getHarness`, the CLI and the tools pick it up. How to write that class: [Custom harnesses](https://harnesses.agntn.dev/guide/custom).
 
-[unagent](https://github.com/onmax/unagent) covers similar ground but makes different tradeoffs.
+## 🛠️ Development
 
-**harnesses is deep and narrow.** Each harness gets verified, platform-specific paths with scope, evidence level, and platform tags. Session formats are typed per harness. Twelve harnesses, each fully mapped.
+```bash
+pnpm install
+pnpm lint        # builds first, then oxlint and oxfmt --check
+pnpm lint:fix
+pnpm typecheck
+pnpm test:run
+pnpm build       # obuild
+pnpm docs        # the Docus site, bundles src/ itself
+```
 
-**unagent is wide and shallow.** 40+ agents detected by env vars, but each definition is just `configDir` + `rulesFile` + `skillsDir`. No platform-specific paths, no session schemas. In exchange, it ships runtime primitives harnesses doesn't touch yet: skill install/uninstall, vector stores, browser automation, sandboxes, queues, workflows.
+## 💛 Thanks
 
-harnesses tells you _where coding harnesses live and what format their data uses_. unagent tells you _which agent is running_ and gives you tools to _do things_ with skills. They could use each other.
+Anthropic and OpenAI both run programs this package was built with. [Claude for Open Source](https://claude.com/contact-sales/claude-for-oss) and [Codex for Open Source](https://developers.openai.com/community/codex-for-oss). Thank you <3
 
-## License
+## 📄 License
 
 [MIT](./LICENSE)

package/dist/_chunks/agents-sync.d.mts

@@ -1,20 +1,20 @@
-declare const version: string;
-type HarnessId = "antigravity" | "codex" | "gemini" | "grok" | "claude" | "opencode" | "cursor" | "freebuff" | "github-copilot" | "mastracode" | "omp" | "pi";
-type EvidenceLevel = "official" | "community" | "inferred";
-type Platform = "linux" | "darwin" | "win32";
-interface PathCandidate {
+export declare const version: string;
+export type HarnessId = "antigravity" | "codex" | "gemini" | "grok" | "claude" | "opencode" | "cursor" | "freebuff" | "github-copilot" | "mastracode" | "omp" | "pi" | "prime-agent";
+export type EvidenceLevel = "official" | "community" | "inferred";
+export type Platform = "linux" | "darwin" | "win32";
+export interface PathCandidate {
   path: string;
   scope: "user" | "project" | "system" | "data";
   level: EvidenceLevel;
   platforms?: Platform[];
   note?: string;
 }
-interface StorageDescriptor {
+export interface StorageDescriptor {
   format: string;
   level: EvidenceLevel;
   note?: string;
 }
-interface HarnessCapabilities {
+export interface HarnessCapabilities {
   mcp: boolean;
   vision: boolean;
   /** Audio reaches the model without conversion or MCP. */
@@ -25,7 +25,7 @@ interface HarnessCapabilities {
   streaming: boolean;
 }
 /** How to run one prompt through the harness non-interactively. */
-interface HarnessInvocation {
+export interface HarnessInvocation {
   /** Binary to spawn; defaults to the harness's first `binaries` entry. */
   binary?: string;
   /** Full agent argument template; every "{prompt}" is replaced with the prompt text. */
@@ -48,7 +48,7 @@ interface HarnessInvocation {
   note?: string;
 }
 /** Invocation modes a harness supports without fallback or prompt-only restrictions. */
-interface HarnessInvocationModes {
+export interface HarnessInvocationModes {
   advisor: boolean;
   advisorStructured: boolean;
   readOnly: boolean;
@@ -57,7 +57,7 @@ interface HarnessInvocationModes {
   agentStructured: boolean;
 }
 /** How to ask one harness CLI for the models currently available to it. */
-interface HarnessModelListing {
+export interface HarnessModelListing {
   /** Arguments used when no search filter is supplied. */
   args: string[];
   /** Optional argument template for a search filter; every "{search}" is replaced. */
@@ -66,7 +66,7 @@ interface HarnessModelListing {
   note?: string;
 }
 /** One model normalized from a harness's native model-listing output. */
-interface AvailableModel {
+export interface AvailableModel {
   provider: string;
   id: string;
   contextWindow: number;
@@ -75,7 +75,7 @@ interface AvailableModel {
   images: boolean;
 }
 /** Options for querying the models available to one harness. */
-interface ListModelsOptions {
+export interface ListModelsOptions {
   search?: string;
   cwd?: string;
   env?: Record<string, string>;
@@ -84,7 +84,7 @@ interface ListModelsOptions {
   /** Cancel with the same process cleanup as a timeout. */
   signal?: AbortSignal;
 }
-interface InvokeOptions {
+export interface InvokeOptions {
   cwd?: string;
   env?: Record<string, string>;
   /** Harness-native model id or selector. */
@@ -100,7 +100,7 @@ interface InvokeOptions {
   /** Use the harness's structured (JSON) output mode instead of plain text. */
   structured?: boolean;
 }
-interface InvokeResult {
+export interface InvokeResult {
   command: string;
   args: string[];
   stdout: string;
@@ -112,16 +112,21 @@ interface InvokeResult {
   aborted: boolean;
 }
 /** Result of one native model-listing command. */
-interface ListModelsResult extends InvokeResult {
+export interface ListModelsResult extends InvokeResult {
   /** Empty on a successful no-match response or when the command itself failed. */
   models: AvailableModel[];
 }
 /** Normalized MCP server entry, shared across every harness dialect. */
-interface McpServerConfig {
+export interface McpServerConfig {
   name: string;
   transport: "stdio" | "http" | "sse";
   command?: string;
   args?: string[];
+  /**
+   * Environment for stdio servers. A value that is exactly "${NAME}" refers to
+   * the variable NAME of the harness environment: dialects with native
+   * references keep it, the others resolve it when the entry is written.
+   */
   env?: Record<string, string>;
   url?: string;
   headers?: Record<string, string>;
@@ -129,25 +134,28 @@ interface McpServerConfig {
   enabled?: boolean;
 }
 /** How one harness config file stores its MCP servers. */
-interface McpConfigFile extends PathCandidate {
+export interface McpConfigFile extends PathCandidate {
   format: "json" | "toml";
   /** Object path to the server map inside the file, e.g. ["mcpServers"]. */
   key: string[];
-  /** Shape of individual entries; "standard" is the {command, args, env, url} family. */
-  dialect: "standard" | "antigravity" | "opencode" | "vscode";
+  /**
+   * Shape of individual entries; "standard" is the {command, args, env, url}
+   * family and "prime" is that family with env values as {"env": "NAME"} references.
+   */
+  dialect: "standard" | "antigravity" | "opencode" | "prime" | "vscode";
 }
-interface HarnessDetection {
+export interface HarnessDetection {
   /** Environment variables that indicate running inside this agent. */
   envVars: string[];
   /** Project-level files or directories whose presence indicates this agent. */
   projectMarkers: string[];
 }
-interface ResolveOptions {
+export interface ResolveOptions {
   homeDir?: string;
   projectRoot?: string;
   platform?: Platform;
 }
-interface ResolvedPaths {
+export interface ResolvedPaths {
   config: PathCandidate[];
   sessions: PathCandidate[];
   instructions: PathCandidate[];
@@ -161,7 +169,7 @@ type InvocationOptions = Readonly<{
   tools?: boolean;
   readOnly?: boolean;
 }>;
-declare abstract class Harness {
+export declare abstract class Harness {
   abstract readonly id: HarnessId;
   abstract readonly name: string;
   abstract readonly binaries: string[];
@@ -271,9 +279,9 @@ declare abstract class Harness {
   resolveCandidates<T extends PathCandidate>(entries: readonly T[], options?: ResolveOptions): T[];
   resolve(options?: ResolveOptions): ResolvedPaths;
 }
-type HarnessConstructor = new () => Harness;
+export type HarnessConstructor = new () => Harness;
 /** One resolved config file together with the servers it declares. */
-interface McpConfigListing {
+export interface McpConfigListing {
   path: string;
   scope: McpConfigFile["scope"];
   format: McpConfigFile["format"];
@@ -284,6 +292,10 @@ interface McpConfigListing {
   /** Set when the file exists but could not be parsed. */
   error?: string;
 }
+/** Thrown when a server's env cannot be written the way the target dialect requires. */
+export declare class McpEnvError extends Error {
+  readonly name = "McpEnvError";
+}
 /**
  * Lists the MCP servers a harness has configured, per declared config file.
  * Missing files come back with `exists: false`; unparsable ones carry `error`.
@@ -292,7 +304,7 @@ interface McpConfigListing {
  * @param options - Platform and path-resolution overrides.
  * @returns {McpConfigListing[]} One listing per declared config file.
  */
-declare function listMcpServers(harness: Harness, options?: ResolveOptions): McpConfigListing[];
+export declare function listMcpServers(harness: Harness, options?: ResolveOptions): McpConfigListing[];
 /**
  * Adds (or replaces) one MCP server in a harness's config. The rest of the
  * file is preserved: JSON through a parse/serialize round trip (formatting
@@ -304,7 +316,7 @@ declare function listMcpServers(harness: Harness, options?: ResolveOptions): Mcp
  * @param options - Platform and path-resolution overrides.
  * @returns {{ path: string, replaced: boolean }} The written path and replacement status.
  */
-declare function addMcpServer(harness: Harness, server: McpServerConfig, scope?: "user" | "project", options?: ResolveOptions): {
+export declare function addMcpServer(harness: Harness, server: McpServerConfig, scope?: "user" | "project", options?: ResolveOptions): {
   path: string;
   replaced: boolean;
 };
@@ -317,7 +329,7 @@ declare function addMcpServer(harness: Harness, server: McpServerConfig, scope?:
  * @param options - Platform and path-resolution overrides.
  * @returns {{ path: string, removed: boolean }} The targeted path and removal status.
  */
-declare function removeMcpServer(harness: Harness, name: string, scope?: "user" | "project", options?: ResolveOptions): {
+export declare function removeMcpServer(harness: Harness, name: string, scope?: "user" | "project", options?: ResolveOptions): {
   path: string;
   removed: boolean;
 };
@@ -328,16 +340,16 @@ declare function removeMcpServer(harness: Harness, name: string, scope?: "user"
  * @param text - JSONC source text.
  * @returns {unknown} The parsed JSON value.
  */
-declare function parseJsonc(text: string): unknown;
+export declare function parseJsonc(text: string): unknown;
 /**
  * Resolves the master sync file path: $XDG_CONFIG_HOME or ~/.config.
  *
  * @param options - Path-resolution overrides.
  * @returns {string} The resolved master MCP config path.
  */
-declare function masterMcpPath(options?: ResolveOptions): string;
+export declare function masterMcpPath(options?: ResolveOptions): string;
 /** One harness's outcome of a sync run. */
-interface SyncTargetResult {
+export interface SyncTargetResult {
   id: string;
   path?: string;
   /** Reason this harness could not be targeted; `results` is empty then. */
@@ -346,11 +358,13 @@ interface SyncTargetResult {
   excluded?: true;
   results: Array<{
     name: string;
-    action: "added" | "replaced" | "removed" | "unchanged";
+    action: "added" | "replaced" | "removed" | "unchanged" | "skipped";
+    /** Why a master server could not be written to this harness. */
+    reason?: string;
   }>;
 }
 /** Outcome of resetting the harness configs to the master list. */
-interface SyncReport {
+export interface SyncReport {
   source: string;
   servers: string[];
   targets: SyncTargetResult[];
@@ -361,7 +375,7 @@ interface SyncReport {
  * @param options - Path-resolution overrides.
  * @returns {{ path: string, servers: McpServerConfig[], excludes: string[] }} The master list.
  */
-declare function readMasterMcpServers(options?: ResolveOptions): {
+export declare function readMasterMcpServers(options?: ResolveOptions): {
   path: string;
   servers: McpServerConfig[];
   /** Harness ids the master list opts out of syncing. */
@@ -376,9 +390,9 @@ declare function readMasterMcpServers(options?: ResolveOptions): {
  * @param options - Platform and path-resolution overrides.
  * @returns {SyncReport} Per-harness synchronization outcomes.
  */
-declare function syncMcpServers(harnesses: readonly Harness[], options?: ResolveOptions): SyncReport;
+export declare function syncMcpServers(harnesses: readonly Harness[], options?: ResolveOptions): SyncReport;
 /** Configuration read from agents.jsonc. */
-interface AgentsConfig {
+export interface AgentsConfig {
   /** The master instructions file every harness links to. */
   source: string;
   /** Relative files to link beside every harness instructions target. */
@@ -388,9 +402,9 @@ interface AgentsConfig {
   /** Path the config was read from; absent when defaults were used. */
   configPath?: string;
 }
-type AgentsSyncAction = "linked" | "relinked" | "adopted" | "unchanged" | "skipped";
+export type AgentsSyncAction = "linked" | "relinked" | "adopted" | "unchanged" | "skipped";
 /** One companion file's outcome for a harness target. */
-interface AgentsCompanionTargetResult {
+export interface AgentsCompanionTargetResult {
   readonly source: string;
   readonly path: string;
   readonly action: Exclude<AgentsSyncAction, "skipped">;
@@ -398,7 +412,7 @@ interface AgentsCompanionTargetResult {
   readonly detail?: string;
 }
 /** One harness's outcome of an agents sync run. */
-interface AgentsTargetResult {
+export interface AgentsTargetResult {
   id: string;
   path?: string;
   action: AgentsSyncAction;
@@ -408,7 +422,7 @@ interface AgentsTargetResult {
   companions?: readonly AgentsCompanionTargetResult[];
 }
 /** Outcome of one agents sync/doctor run. */
-interface AgentsSyncReport {
+export interface AgentsSyncReport {
   source: string;
   check: boolean;
   targets: AgentsTargetResult[];
@@ -419,7 +433,7 @@ interface AgentsSyncReport {
  * @param options - Path-resolution overrides.
  * @returns {AgentsConfig} The normalized sync configuration.
  */
-declare function readAgentsConfig(options?: ResolveOptions): AgentsConfig;
+export declare function readAgentsConfig(options?: ResolveOptions): AgentsConfig;
 /**
  * Links every harness's user-scope instructions file to the master. In check
  * mode nothing is written; the report shows what a real run would do.
@@ -429,6 +443,5 @@ declare function readAgentsConfig(options?: ResolveOptions): AgentsConfig;
  * @param options - Path-resolution overrides.
  * @returns {AgentsSyncReport} Per-harness synchronization outcomes.
  */
-declare function syncAgentsFiles(harnesses: readonly Harness[], check?: boolean, options?: ResolveOptions): AgentsSyncReport;
-export { AgentsCompanionTargetResult, AgentsConfig, AgentsSyncAction, AgentsSyncReport, AgentsTargetResult, AvailableModel, EvidenceLevel, Harness, HarnessCapabilities, HarnessConstructor, HarnessDetection, HarnessId, HarnessInvocation, HarnessInvocationModes, HarnessModelListing, InvokeOptions, InvokeResult, ListModelsOptions, ListModelsResult, McpConfigFile, McpConfigListing, McpServerConfig, PathCandidate, Platform, ResolveOptions, ResolvedPaths, StorageDescriptor, SyncReport, SyncTargetResult, addMcpServer, listMcpServers, masterMcpPath, parseJsonc, readAgentsConfig, readMasterMcpServers, removeMcpServer, syncAgentsFiles, syncMcpServers, version };
+export declare function syncAgentsFiles(harnesses: readonly Harness[], check?: boolean, options?: ResolveOptions): AgentsSyncReport;
 //# sourceMappingURL=agents-sync.d.mts.map

package/dist/_chunks/agents-sync.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"agents-sync.d.mts","names":[],"sources":["../../src/types.ts","../../src/harness.ts","../../src/mcp-servers.ts","../../src/agents-sync.ts"],"mappings":"AAEA,cAAa;KAED;KAaA;KACA;UAEK;EACf;EACA;EACA,OAAO;EACP,YAAY;EACZ;;UAGe;EACf;EACA,OAAO;EACP;;UAGe;EACf;EACA;;EAEA;;EAEA;EACA;EACA;;;UAIe;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;EACA,OAAO;EACP;;;UAIe;EACf;EACA;EACA;EACA;EACA;EACA;;;UAIe;;EAEf;;EAEA;EACA,OAAO;EACP;;;UAIe;EACf;EACA;EACA;EACA;EACA;EACA;;;UAIe;EACf;EACA;EACA,MAAM;;EAEN;;EAEA,SAAS;;UAGM;EACf;EACA,MAAM;;EAEN;;EAEA;;EAEA;;EAEA;;EAEA,SAAS;;EAET;;UAGe;EACf;EACA;EACA;EACA;;EAEA;EACA;;EAEA;;;UAIe,yBAAyB;;EAExC,QAAQ;;;UAIO;EACf;EACA;EACA;EACA;EACA,MAAM;EACN;EACA,UAAU;;EAEV;;;UAIe,sBAAsB;EACrC;;EAEA;;EAEA;;UAGe;;EAEf;;EAEA;;UAGe;EACf;EACA;EACA,WAAW;;UAGI;EACf,QAAQ;EACR,UAAU;EACV,cAAc;EACd,QAAQ;EACR,UAAU;EACV,OAAO;;KCnJJ,oBAAoB;EACvB;EACA;EACA;EACA;;uBA2OoB;oBACF,IAAI;oBACJ;oBACA;oBACA,QAAQ;oBACR,UAAU;oBACV,aAAa;oBACb,cAAc;oBACd,QAAQ;oBACR,UAAU;oBACV,OAAO;oBACP,cAAc;oBACd,WAAW;;oBAEX,YAAY;;WAErB,cAAc;;WAEd,YAAY;;;;;;WAMZ;EAET;EAYA;EAIA,cAAc;MAKV;;;;;;MAsBA,mBAAmB;;;;;;;;;;EAoBvB,gBACE,gBACA,UAAS;IACN;IAAiB;;;;;;;;EAmBtB,gBAAgB,UAAS;;;;;;;;;;EAqBzB,OAAO,gBAAgB,UAAS,gBAAqB,QAAQ;;;;;;;;;UA2BrD;;;;;;;EAgBR,yBAAyB;IAAoB;IAAiB;;;;;;;;;EAmBxD,WAAW,UAAS,oBAAyB,QAAQ;;;;;;YAyBjD,wBAAwB,kBAAkB;;;;;;;;;;EAapD,kBAAkB,UAAU,eAC1B,kBAAkB,KAClB,UAAS,iBACR;EAcH,QAAQ,UAAS,iBAAsB;;KAY7B,+BAA+B;;UCxgB1B;EACf;EACA,OAAO;EACP,QAAQ;EACR,OAAO;EACP;EACA;EACA,SAAS;;EAET;;;;;;;;;;iBAmRc,eAAe,SAAS,SAAS,UAAS,iBAAsB;;;;;;;;;;;;iBAiLhE,aACd,SAAS,SACT,QAAQ,iBACR,4BACA,UAAS;EACN;EAAc;;;;;;;;;;;iBA0BH,gBACd,SAAS,SACT,cACA,4BACA,UAAS;EACN;EAAc;;;;;;;;;iBA8FH,WAAW;;;;;;;iBAwBX,cAAc,UAAS;;UAKtB;EACf;EACA;;EAEA;;EAEA;EACA,SAAS;IAAQ;IAAc;;;;UAIhB;EACf;EACA;EACA,SAAS;;;;;;;;iBAuEK,qBAAqB,UAAS;EAC5C;EACA,SAAS;;EAET;;;;;;;;;;;iBA2Hc,eACd,oBAAoB,WACpB,UAAS,iBACR;;UC1zBc;;EAEf;;EAEA;;EAEA;;EAEA;;KAGU;;UAGK;WACN;WACA;WACA,QAAQ,QAAQ;;WAEhB;;;UAIM;EACf;EACA;EACA,QAAQ;;EAER;;EAEA,sBAAsB;;;UAIP;EACf;EACA;EACA,SAAS;;;;;;;;iBA2FK,iBAAiB,UAAS,iBAAsB;;;;;;;;;;iBAiMhD,gBACd,oBAAoB,WACpB,iBACA,UAAS,iBACR"}
+{"version":3,"file":"agents-sync.d.mts","names":[],"sources":["../../src/types.ts","../../src/harness.ts","../../src/mcp-servers.ts","../../src/agents-sync.ts"],"mappings":"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"}