@agntn/harnesses 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 oritwoen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# @agntn/harnesses
+
+[![npm version](https://img.shields.io/npm/v/%40agntn%2Fharnesses?style=flat&colorA=130f40&colorB=474787)](https://npmjs.com/package/@agntn/harnesses)
+[![npm downloads](https://img.shields.io/npm/dm/%40agntn%2Fharnesses?style=flat&colorA=130f40&colorB=474787)](https://npm.chart.dev/@agntn/harnesses)
+[![license](https://img.shields.io/github/license/agntn/harnesses?style=flat&colorA=130f40&colorB=474787)](https://github.com/agntn/harnesses/blob/main/LICENSE)
+[![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.
+
+## Install
+
+```bash
+pnpm add @agntn/harnesses
+```
+
+## Usage
+
+```ts
+import { getHarness, detectHarness, detectProjectHarnesses } from "@agntn/harnesses";
+
+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
+
+const codex = getHarness("codex");
+await codex.invoke("Review this patch", { readOnly: true });
+
+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" });
+
+// Resolve to absolute paths for current platform
+const paths = claude.resolve({ platform: "linux", homeDir: "/home/dev" });
+console.log(paths.config); // [{ path: "/home/dev/.claude/settings.json", ... }, ...]
+
+// Detect which agent is running (env vars first, then project markers)
+const active = detectHarness();
+if (active) {
+  console.log(`Running inside ${active.name}`);
+}
+
+// Find all agents configured in a project directory
+const harnesses = detectProjectHarnesses("/path/to/project");
+```
+
+Session schemas are typed per agent, so you get structure when parsing JSONL/SQLite/JSON files:
+
+```ts
+import type { ClaudeSessionEntry, CodexThread, GeminiConversationRecord } from "@agntn/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).
+
+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.
+
+```jsonc
+{
+  "source": "bundle/AGENTS.md",
+  "companions": ["RULES.md"],
+  "excludes": ["codex"],
+}
+```
+
+All paths carry `scope` (user/project/system/data), `level` (official/community/inferred), and optional `platforms` tags.
+
+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.
+
+## CLI
+
+```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. 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.
+
+## How harnesses compares to unagent
+
+[unagent](https://github.com/onmax/unagent) covers similar ground but makes different tradeoffs.
+
+**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.
+
+**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.
+
+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.
+
+## License
+
+[MIT](./LICENSE)

package/dist/THIRD-PARTY-LICENSES.md

@@ -0,0 +1,36 @@
+# Licenses of Bundled Dependencies
+
+The published artifact additionally contains code with the following licenses:
+MIT
+
+# Bundled Dependencies
+
+## typebox
+
+License: MIT
+By: sinclairzx81
+Repository: https://github.com/sinclairzx81/typebox
+
+> TypeBox
+> 
+> The MIT License (MIT)
+> 
+> Copyright (c) 2017-2026 Haydn Paterson
+> 
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+> 
+> The above copyright notice and this permission notice shall be included in
+> all copies or substantial portions of the Software.
+> 
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+> THE SOFTWARE.

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

@@ -0,0 +1,417 @@
+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 {
+  path: string;
+  scope: "user" | "project" | "system" | "data";
+  level: EvidenceLevel;
+  platforms?: Platform[];
+  note?: string;
+}
+interface StorageDescriptor {
+  format: string;
+  level: EvidenceLevel;
+  note?: string;
+}
+interface HarnessCapabilities {
+  mcp: boolean;
+  vision: boolean;
+  /** Audio reaches the model without conversion or MCP. */
+  audio: boolean;
+  /** Video reaches the model without conversion or MCP. */
+  video: boolean;
+  tools: boolean;
+  streaming: boolean;
+}
+/** How to run one prompt through the harness non-interactively. */
+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. */
+  args: string[];
+  /** Structured full agent argument template. */
+  jsonArgs?: string[];
+  /** Advisor argument template without tools; absent when the CLI cannot disable tools. */
+  noToolsArgs?: string[];
+  /** Structured advisor argument template without tools. */
+  noToolsJsonArgs?: string[];
+  /** Agent argument template whose native sandbox enforces read-only tool access. */
+  readOnlyArgs?: string[];
+  /** Structured agent argument template with read-only tool access. */
+  readOnlyJsonArgs?: string[];
+  /** Arguments appended when a model is selected; every "{model}" is replaced. */
+  modelArgs?: string[];
+  level: EvidenceLevel;
+  note?: string;
+}
+/** Invocation modes a harness supports without fallback or prompt-only restrictions. */
+interface HarnessInvocationModes {
+  advisor: boolean;
+  advisorStructured: boolean;
+  readOnly: boolean;
+  readOnlyStructured: boolean;
+  agent: boolean;
+  agentStructured: boolean;
+}
+/** How to ask one harness CLI for the models currently available to it. */
+interface HarnessModelListing {
+  /** Arguments used when no search filter is supplied. */
+  args: string[];
+  /** Optional argument template for a search filter; every "{search}" is replaced. */
+  searchArgs?: string[];
+  level: EvidenceLevel;
+  note?: string;
+}
+/** One model normalized from a harness's native model-listing output. */
+interface AvailableModel {
+  provider: string;
+  id: string;
+  contextWindow: number;
+  maxOutputTokens: number;
+  thinking: boolean;
+  images: boolean;
+}
+/** Options for querying the models available to one harness. */
+interface ListModelsOptions {
+  search?: string;
+  cwd?: string;
+  env?: Record<string, string>;
+  /** Kill the model-listing command after this many milliseconds; unset means no timeout. */
+  timeoutMs?: number;
+}
+interface InvokeOptions {
+  cwd?: string;
+  env?: Record<string, string>;
+  /** Harness-native model id or selector. */
+  model?: string;
+  /** Enable the spawned harness's tools; defaults to advisor without tools mode. */
+  tools?: boolean;
+  /** Require native enforcement of read-only tool access. Implies `tools: true`. */
+  readOnly?: boolean;
+  /** Kill the harness after this many milliseconds; unset means no timeout. */
+  timeoutMs?: number;
+  /** Use the harness's structured (JSON) output mode instead of plain text. */
+  structured?: boolean;
+}
+interface InvokeResult {
+  command: string;
+  args: string[];
+  stdout: string;
+  stderr: string;
+  /** Process exit code; null when the run hit `timeoutMs` and was killed. */
+  exitCode: number | null;
+  timedOut: boolean;
+}
+/** Result of one native model-listing command. */
+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 {
+  name: string;
+  transport: "stdio" | "http" | "sse";
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  url?: string;
+  headers?: Record<string, string>;
+  /** Present only when the harness tracks an on/off state per server. */
+  enabled?: boolean;
+}
+/** How one harness config file stores its MCP servers. */
+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";
+}
+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 {
+  homeDir?: string;
+  projectRoot?: string;
+  platform?: Platform;
+}
+interface ResolvedPaths {
+  config: PathCandidate[];
+  sessions: PathCandidate[];
+  instructions: PathCandidate[];
+  skills: PathCandidate[];
+  commands: PathCandidate[];
+  hooks: PathCandidate[];
+}
+type InvocationOptions = Readonly<{
+  model?: string;
+  structured?: boolean;
+  tools?: boolean;
+  readOnly?: boolean;
+}>;
+declare abstract class Harness {
+  abstract readonly id: HarnessId;
+  abstract readonly name: string;
+  abstract readonly binaries: string[];
+  abstract readonly config: PathCandidate[];
+  abstract readonly sessions: PathCandidate[];
+  abstract readonly persistence: StorageDescriptor[];
+  abstract readonly instructions: PathCandidate[];
+  abstract readonly skills: PathCandidate[];
+  abstract readonly commands: PathCandidate[];
+  abstract readonly hooks: PathCandidate[];
+  abstract readonly capabilities: HarnessCapabilities;
+  abstract readonly detection: HarnessDetection;
+  /** Non-interactive invocation recipe; null when the harness has no headless mode. */
+  abstract readonly invocation: HarnessInvocation | null;
+  /** Native model-listing recipe; null when the harness cannot enumerate available models. */
+  readonly modelListing: HarnessModelListing | null;
+  /** Config files that hold MCP server definitions; empty when unknown or unsupported. */
+  readonly mcpConfigs: McpConfigFile[];
+  /**
+   * The user-scope global instructions file this harness reads, as a path
+   * template; null when there is no stable file (or another harness's file
+   * covers it via vendor compatibility).
+   */
+  readonly agentsFile: string | null;
+  isInstalled(): boolean;
+  detectEnv(): boolean;
+  detectProject(cwd?: string): boolean;
+  get version(): string | null;
+  /**
+   * Invocation modes available without fallback or prompt-only restrictions.
+   *
+   * @returns {HarnessInvocationModes} The exact supported invocation modes.
+   */
+  get invocationModes(): HarnessInvocationModes;
+  /**
+   * Expands the invocation template for one prompt, without spawning anything.
+   * Returns null when the harness has no headless mode, or no structured mode
+   * when `structured` is requested.
+   *
+   * @param prompt - Prompt inserted into the invocation template.
+   * @param options - Requested model and execution mode.
+   * @returns {{ command: string, args: string[] } | null} The executable invocation, or null.
+   */
+  buildInvocation(prompt: string, options?: InvocationOptions): {
+    command: string;
+    args: string[];
+  } | null;
+  /**
+   * Explains why an invocation option set cannot be built, or returns null when supported.
+   *
+   * @param options - Requested model and execution mode.
+   * @returns {string | null} The incompatibility reason, or null when supported.
+   */
+  invocationError(options?: InvocationOptions): string | null;
+  /**
+   * Runs one prompt through the harness non-interactively and collects the
+   * output. stdin is closed so a harness that falls back to interactive mode
+   * exits instead of waiting forever.
+   *
+   * @param prompt - Prompt sent to the harness.
+   * @param options - Invocation, environment, and timeout options.
+   * @returns {Promise<InvokeResult>} The completed process result.
+   */
+  invoke(prompt: string, options?: InvokeOptions): Promise<InvokeResult>;
+  /**
+   * Expands the native model-listing recipe without spawning anything.
+   *
+   * @param search - Optional native model search filter.
+   * @returns {{ command: string, args: string[] } | null} The command, or null when unsupported.
+   */
+  buildModelListInvocation(search?: string): {
+    command: string;
+    args: string[];
+  } | null;
+  /**
+   * Runs the harness's native model-listing command and normalizes its output.
+   * stdin is closed for the same reason as {@link invoke}.
+   *
+   * @param options - Search, environment, and timeout options.
+   * @returns {Promise<ListModelsResult>} The normalized command and model result.
+   */
+  listModels(options?: ListModelsOptions): Promise<ListModelsResult>;
+  /**
+   * Converts a successful native model-listing response to the shared shape.
+   *
+   * @param _stdout - Native command output to parse.
+   */
+  protected parseModelListingOutput(_stdout: string): AvailableModel[];
+  /**
+   * Filters one candidate list to the platform and expands its path
+   * templates: the shared pipeline behind {@link resolve} and the MCP
+   * config surface.
+   *
+   * @param entries - Candidate paths to filter and resolve.
+   * @param options - Platform and path-resolution overrides.
+   * @returns {T[]} Resolved candidates supported on the selected platform.
+   */
+  resolveCandidates<T extends PathCandidate>(entries: readonly T[], options?: ResolveOptions): T[];
+  resolve(options?: ResolveOptions): ResolvedPaths;
+}
+type HarnessConstructor = new () => Harness;
+/** One resolved config file together with the servers it declares. */
+interface McpConfigListing {
+  path: string;
+  scope: McpConfigFile["scope"];
+  format: McpConfigFile["format"];
+  level: EvidenceLevel;
+  note?: string;
+  exists: boolean;
+  servers: McpServerConfig[];
+  /** Set when the file exists but could not be parsed. */
+  error?: string;
+}
+/**
+ * Lists the MCP servers a harness has configured, per declared config file.
+ * Missing files come back with `exists: false`; unparsable ones carry `error`.
+ *
+ * @param harness - Harness whose configs should be read.
+ * @param options - Platform and path-resolution overrides.
+ * @returns {McpConfigListing[]} One listing per declared config file.
+ */
+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
+ * normalizes to two-space indentation), TOML through a surgical line edit.
+ *
+ * @param harness - Target harness.
+ * @param server - Normalized server configuration to write.
+ * @param scope - User or project config scope.
+ * @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): {
+  path: string;
+  replaced: boolean;
+};
+/**
+ * Removes one MCP server from a harness's config.
+ *
+ * @param harness - Target harness.
+ * @param name - Server name to remove.
+ * @param scope - User or project config 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): {
+  path: string;
+  removed: boolean;
+};
+/**
+ * Strips JSONC extensions (comments and trailing commas) so the master sync
+ * file can be read with JSON.parse. String contents are left untouched.
+ *
+ * @param text - JSONC source text.
+ * @returns {unknown} The parsed JSON value.
+ */
+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;
+/** One harness's outcome of a sync run. */
+interface SyncTargetResult {
+  id: string;
+  path?: string;
+  /** Reason this harness could not be targeted; `results` is empty then. */
+  skipped?: string;
+  /** Set when the master list excludes this harness; master-listed names are withdrawn. */
+  excluded?: true;
+  results: Array<{
+    name: string;
+    action: "added" | "replaced" | "removed" | "unchanged";
+  }>;
+}
+/** Outcome of resetting the harness configs to the master list. */
+interface SyncReport {
+  source: string;
+  servers: string[];
+  targets: SyncTargetResult[];
+}
+/**
+ * Reads and normalizes the master list; throws when the file is missing or invalid.
+ *
+ * @param options - Path-resolution overrides.
+ * @returns {{ path: string, servers: McpServerConfig[], excludes: string[] }} The master list.
+ */
+declare function readMasterMcpServers(options?: ResolveOptions): {
+  path: string;
+  servers: McpServerConfig[];
+  /** Harness ids the master list opts out of syncing. */
+  excludes: string[];
+};
+/**
+ * Resets each harness's user-scope MCP config to exactly the master list:
+ * missing servers are added, drifted ones replaced, and servers absent from
+ * the master are removed. The master file is the single source of truth.
+ *
+ * @param harnesses - Harnesses to synchronize.
+ * @param options - Platform and path-resolution overrides.
+ * @returns {SyncReport} Per-harness synchronization outcomes.
+ */
+declare function syncMcpServers(harnesses: readonly Harness[], options?: ResolveOptions): SyncReport;
+/** Configuration read from agents.jsonc. */
+interface AgentsConfig {
+  /** The master instructions file every harness links to. */
+  source: string;
+  /** Relative files to link beside every harness instructions target. */
+  companions: string[];
+  /** Harness ids the sync leaves untouched. */
+  excludes: string[];
+  /** Path the config was read from; absent when defaults were used. */
+  configPath?: string;
+}
+type AgentsSyncAction = "linked" | "relinked" | "adopted" | "unchanged" | "skipped";
+/** One companion file's outcome for a harness target. */
+interface AgentsCompanionTargetResult {
+  readonly source: string;
+  readonly path: string;
+  readonly action: Exclude<AgentsSyncAction, "skipped">;
+  /** Backup path for an adopted file, or a check-mode note. */
+  readonly detail?: string;
+}
+/** One harness's outcome of an agents sync run. */
+interface AgentsTargetResult {
+  id: string;
+  path?: string;
+  action: AgentsSyncAction;
+  /** Reason for a skip, or the backup path for an adopted diverged file. */
+  detail?: string;
+  /** Companion outcomes, present when companions are configured. */
+  companions?: readonly AgentsCompanionTargetResult[];
+}
+/** Outcome of one agents sync/doctor run. */
+interface AgentsSyncReport {
+  source: string;
+  check: boolean;
+  targets: AgentsTargetResult[];
+}
+/**
+ * Reads agents.jsonc; missing file falls back to defaults.
+ *
+ * @param options - Path-resolution overrides.
+ * @returns {AgentsConfig} The normalized sync configuration.
+ */
+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.
+ *
+ * @param harnesses - Harnesses to inspect or update.
+ * @param check - Report intended changes without writing them.
+ * @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 };
+//# sourceMappingURL=agents-sync.d.mts.map

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

@@ -0,0 +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;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;;UAGe;EACf;EACA,MAAM;;EAEN;;EAEA;;EAEA;;EAEA;;EAEA;;UAGe;EACf;EACA;EACA;EACA;;EAEA;EACA;;;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;;KC9IJ,oBAAoB;EACvB;EACA;EACA;EACA;;uBAqHoB;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;;;;;;;;;;EAwBzB,OAAO,gBAAgB,UAAS,gBAAqB,QAAQ;;;;;;;EAuB7D,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;;UC9X1B;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;;;;;;;;iBAkFK,iBAAiB,UAAS,iBAAsB;;;;;;;;;;iBAiMhD,gBACd,oBAAoB,WACpB,iBACA,UAAS,iBACR"}