//#region src/types.d.ts declare const version: string; type HarnessId = "antigravity" | "codex" | "gemini" | "grok" | "claude" | "opencode" | "cursor" | "freebuff" | "github-copilot" | "mastracode" | "omp" | "pi" | "prime-agent"; 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; } /** The path lists of a harness descriptor, as named in {@link ResolvedPaths}. */ type PathCategory = "config" | "sessions" | "instructions" | "skills" | "commands" | "promptTemplates" | "hooks" | "temp"; /** * An environment variable the harness reads to move one of its roots. `path` * is the default root, used while the variable is unset or empty. */ interface EnvOverride extends PathCandidate { variable: string; /** Categories with entries under this root, which move with it. */ relocates: PathCategory[]; } /** The user-scope skills directory that skill synchronization links to the source. */ interface SkillsSyncTarget extends PathCandidate { scope: "user"; } /** One stable user-scope destination used by prompt template synchronization. */ interface PromptTemplateSyncTarget extends PathCandidate { scope: "user"; format: "markdown" | "gemini-toml"; } 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[]; /** Lowest CLI version whose read-only enforcement was verified; older or unknown versions reject read-only runs. */ readOnlyMinVersion?: string; /** Per platform, whether read-only child processes reach the network; unlisted is unchecked. */ readOnlyNetwork?: Partial>; /** Arguments appended when a model is selected; every "{model}" is replaced. */ modelArgs?: string[]; /** Arguments appended when a reasoning effort is selected; every "{effort}" is replaced. */ effortArgs?: string[]; /** * Arguments appended to a plain text run so a CLI that holds its answer until * the end reports it as events instead; `invoke` folds them back into that text, * so a stopped run keeps what the model had already written. */ streamArgs?: 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 native search filter; every "{search}" is replaced. * Without it, a search runs `args` and keeps the ids containing the filter, ignoring case. */ searchArgs?: string[]; level: EvidenceLevel; note?: string; } /** One model normalized from a harness's native model-listing output. */ interface AvailableModel { provider: string; id: string; /** Display name, where the adapter reads one from the listing; Codex so far. */ name?: string; /** Absent when the native listing prints only ids, like Grok's. */ contextWindow?: number; maxOutputTokens?: number; thinking?: boolean; images?: boolean; /** Set on the model the harness picks when no model is given, when the listing marks one. */ default?: boolean; } /** Options for querying the models available to one harness. */ interface ListModelsOptions { search?: string; cwd?: string; env?: Record; /** Milliseconds before cleanup starts. Unset or 0 disables the deadline. */ timeoutMs?: number; /** Cancel with the same process cleanup as a timeout. */ signal?: AbortSignal; } interface InvokeOptions { cwd?: string; env?: Record; /** Harness-native model id or selector. */ model?: string; /** Reasoning effort in the harness's own words (`low`, `high`, `max`), passed through as is. */ effort?: 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` when `tools` is omitted; `tools: false` rejects the run. */ readOnly?: boolean; /** Milliseconds before cleanup starts. Unset or 0 disables the deadline. */ timeoutMs?: number; /** Cancel with the same process cleanup as a timeout. */ signal?: AbortSignal; /** 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 terminated by a signal, timeout, or cancellation. */ exitCode: number | null; timedOut: boolean; /** True when caller cancellation wins over the deadline or completion. */ aborted: boolean; /** Milliseconds without output on either stream before a deadline or cancellation stopped the process. */ idleMs?: number; /** Set when an advisor wrote a tool call as text. Nothing ran it, so its output is made up. */ toolCallsAsText?: true; } /** 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[]; /** * 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; url?: string; headers?: Record; /** 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, "prime" is that family with env values as {"env": "NAME"} references, * "mastracode" is that family read by its keys alone, type ignored, and "pi" * is that family without sse that keeps the entry fields it doesn't manage. */ dialect: "standard" | "antigravity" | "mastracode" | "opencode" | "pi" | "prime" | "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; /** Replaces `os.tmpdir()` as the value of `${TMPDIR}`. */ tempDir?: string; } interface ResolvedPaths { config: PathCandidate[]; sessions: PathCandidate[]; instructions: PathCandidate[]; skills: PathCandidate[]; skillsSyncTarget: SkillsSyncTarget | null; commands: PathCandidate[]; promptTemplates: PathCandidate[]; promptTemplateSyncTarget: PromptTemplateSyncTarget | null; hooks: PathCandidate[]; /** Temp roots, moved by a set `temp` override from {@link EnvOverride}. */ temp: PathCandidate[]; } //#endregion //#region src/harness.d.ts type InvocationOptions = Readonly<{ model?: string; effort?: 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[]; /** User-scope skills directory that skill synchronization links; null when none is verified. */ readonly skillsSyncTarget: SkillsSyncTarget | null; abstract readonly commands: PathCandidate[]; /** Reusable prompt files; empty when no CLI template location is verified. */ readonly promptTemplates: PathCandidate[]; /** Stable user-scope destination used by prompt template synchronization. */ readonly promptTemplateSyncTarget: PromptTemplateSyncTarget | null; abstract readonly hooks: PathCandidate[]; /** Where the harness keeps its temp files; empty when not verified. */ readonly temp: PathCandidate[]; /** Environment variables that move a root of this harness; empty when none is verified. */ readonly envOverrides: EnvOverride[]; 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; /** * Whether a read-only run still has network for what it starts, MCP servers included. * * @param platform - Platform to answer for; defaults to this one. * @returns {boolean | null} The checked answer, or null when nobody checked. */ readOnlyNetwork(platform?: string): boolean | null; /** * 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. Inside a harness that `invoke` started, it rejects. * * @param prompt - Prompt sent to the harness. * @param options - Invocation, environment, timeout, and cancellation options. * @returns {Promise} The completed process result. */ invoke(prompt: string, options?: InvokeOptions): Promise; /** * Turns the events a `streamArgs` run printed back into the text the plain * run would have printed. * * @param _stdout - Event output as captured, possibly cut short. * @param _complete - False when a deadline or cancellation stopped the run. * @returns {string} The answer text, or what the model had written so far. */ protected foldStreamOutput(_stdout: string, _complete: boolean): string; /** * Explains why the installed CLI cannot run a read-only recipe that carries a * version floor, or returns null when no floor applies or the installed * version meets it. An unknown version fails closed, like a missing recipe. * * @param options - Requested execution mode. * @returns {string | null} The version incompatibility, or null when the run may proceed. */ private readOnlyVersionError; /** * Expands the native model-listing recipe without spawning anything. * * @param search - Optional model search filter; without native `searchArgs` it is applied * to the parsed output instead, so the command is the unfiltered one. * @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, timeout, and cancellation options. * @returns {Promise} The normalized command and model result. */ listModels(options?: ListModelsOptions): Promise; /** * The value `model` takes for one listed model: `provider/id` unless the * harness overrides it. * * @param model - A model returned by {@link listModels}. * @returns {string} The selector this harness's `modelArgs` accept. */ modelSelector(model: Readonly): string; /** * 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(entries: readonly T[], options?: ResolveOptions): T[]; resolve(options?: ResolveOptions): ResolvedPaths; /** * Temp roots for the platform. A `temp` override set in the environment * replaces its default root, the same move the harness makes itself. * * @param options - Platform and path-resolution overrides. * @returns {PathCandidate[]} Resolved temp roots. */ private resolveTemp; } type HarnessConstructor = new () => Harness; //#endregion //#region src/mcp-servers.d.ts /** 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; } /** Thrown when a server's env cannot be written the way the target dialect requires. */ declare class McpEnvError extends Error { readonly name = "McpEnvError"; } /** Thrown when the target dialect cannot carry a server's transport. */ declare class McpTransportError extends Error { readonly name = "McpTransportError"; } /** * 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" | "kept" | "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 { 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[], keep: Record }} The master list. */ declare function readMasterMcpServers(options?: ResolveOptions): { path: string; servers: McpServerConfig[]; /** Harness ids the master list opts out of syncing. */ excludes: string[]; /** Per harness id, its own server names that sync leaves in place. */ keep: Record; }; /** * 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 unless its `keep` names them for that harness. The * master file is the single source of truth, exceptions included. * * @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; //#endregion //#region src/agents-sync.d.ts /** 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; /** 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; //#endregion //#region src/prompt-sync.d.ts type PromptSyncAction = "linked" | "generated" | "relinked" | "replaced" | "adopted" | "removed" | "unchanged" | "skipped"; /** One prompt template's outcome at a harness destination. */ interface PromptTemplateTargetResult { readonly name: string; readonly source?: string; readonly path: string; readonly action: PromptSyncAction; /** Backup path, skip reason, or a check-mode note. */ readonly detail?: string; } /** One harness's outcome of a prompt template sync run. */ interface PromptSyncTargetResult { readonly id: string; readonly path?: string; readonly format?: PromptTemplateSyncTarget["format"]; /** Outcome for a Markdown destination, which is one link to the whole source directory. */ readonly action?: PromptSyncAction; /** Backup path, skip reason, or a check-mode note. */ readonly detail?: string; readonly templates: readonly PromptTemplateTargetResult[]; } /** Outcome of one prompt template sync run. */ interface PromptSyncReport { readonly source: string; readonly check: boolean; readonly templates: readonly string[]; readonly targets: readonly PromptSyncTargetResult[]; } /** * Synchronizes canonical Markdown prompt templates into each harness's stable * user-scope destination. A Markdown harness's destination becomes one symlink * to the source directory; Gemini's directory holds only TOML commands * generated from it. Anything else found there is backed up first. In check * mode nothing is written. * * @param harnesses - Harnesses to inspect or update. * @param check - Report intended changes without writing them. * @param options - Path-resolution overrides. * @returns {PromptSyncReport} Per-harness synchronization outcomes. */ declare function syncPromptTemplates(harnesses: readonly Harness[], check?: boolean, options?: ResolveOptions): PromptSyncReport; //#endregion //#region src/directory-link.d.ts type DirectoryLinkAction = "linked" | "relinked" | "adopted" | "unchanged" | "skipped"; //#endregion //#region src/skills-sync.d.ts type SkillsSyncAction = DirectoryLinkAction; /** One harness's outcome of a skill sync run. */ interface SkillsSyncTargetResult { readonly id: string; readonly path?: string; readonly action: SkillsSyncAction; /** Backup path, skip reason, or a check-mode note. */ readonly detail?: string; } /** Outcome of one skill sync run. */ interface SkillsSyncReport { readonly source: string; readonly check: boolean; /** Source subdirectories that hold a SKILL.md. */ readonly skills: readonly string[]; readonly targets: readonly SkillsSyncTargetResult[]; } /** * Links each harness's user-scope skills directory to the canonical skills * directory under the agntn XDG data directory, so a skill added or edited * through any harness lands in one place. Per-skill links into the source are * replaced; any other content is backed up first. In check mode nothing is * written. * * @param harnesses - Harnesses to inspect or update. * @param check - Report intended changes without writing them. * @param options - Path-resolution overrides. * @returns {SkillsSyncReport} Per-harness synchronization outcomes. */ declare function syncSkills(harnesses: readonly Harness[], check?: boolean, options?: ResolveOptions): SkillsSyncReport; //#endregion export { StorageDescriptor as $, HarnessConstructor as A, InvokeOptions as B, listMcpServers as C, removeMcpServer as D, readMasterMcpServers as E, HarnessDetection as F, McpServerConfig as G, ListModelsOptions as H, HarnessId as I, Platform as J, PathCandidate as K, HarnessInvocation as L, EnvOverride as M, EvidenceLevel as N, syncMcpServers as O, HarnessCapabilities as P, SkillsSyncTarget as Q, HarnessInvocationModes as R, addMcpServer as S, parseJsonc as T, ListModelsResult as U, InvokeResult as V, McpConfigFile as W, ResolveOptions as X, PromptTemplateSyncTarget as Y, ResolvedPaths as Z, McpConfigListing as _, PromptSyncAction as a, SyncReport as b, PromptTemplateTargetResult as c, AgentsConfig as d, version as et, AgentsSyncAction as f, syncAgentsFiles as g, readAgentsConfig as h, syncSkills as i, AvailableModel as j, Harness as k, syncPromptTemplates as l, AgentsTargetResult as m, SkillsSyncReport as n, PromptSyncReport as o, AgentsSyncReport as p, PathCategory as q, SkillsSyncTargetResult as r, PromptSyncTargetResult as s, SkillsSyncAction as t, AgentsCompanionTargetResult as u, McpEnvError as v, masterMcpPath as w, SyncTargetResult as x, McpTransportError as y, HarnessModelListing as z }; //# sourceMappingURL=skills-sync.d.mts.map