@groundtrack/hooks 0.1.6 → 0.1.8

package/README.md

@@ -1,56 +1,117 @@
 # @groundtrack/hooks
 
-Lifecycle hook utilities for Groundtrack MCP clients.
+Set up Groundtrack across Claude Code, Codex, Cursor, and OpenCode in one flow.
+Node.js 18 or newer is required.
 
-Install globally so the `groundtrack-hook` command is available to Claude Code,
-Codex, and Cursor hook configurations:
+```sh
+npx --yes --package @groundtrack/hooks@latest groundtrack setup
+```
 
-```bash
-npm install -g @groundtrack/hooks
+Choose the agents you use, review the changes, and finish any sign-in or hook
+approval shown for each agent. The picker detects both machine installations
+and project configuration. Your choices are remembered; adding Codex later
+preserves your working Claude and Cursor connections.
+
+```sh
+groundtrack setup --agent codex
+groundtrack setup --agent claude --agent codex --agent cursor --yes
+groundtrack setup --all-detected --yes
+groundtrack setup --agent codex --dry-run
+groundtrack status
+groundtrack status --json
 ```
 
-## Doctor CLI
+`--agent` is repeatable. `--client` and `claude-code` are accepted aliases.
+Setup configures the current project; it does not activate Groundtrack in every
+repository. Use `--repo PATH` to choose a project and `--url URL` for another
+Groundtrack endpoint. With no explicit targets, an interactive terminal shows
+the picker. An unattended `--yes` run needs a previously saved selection or
+explicit `--agent` / `--all-detected`; it never falls back to all known agents.
+An empty selection or cancellation makes no changes.
+
+The same package provides `groundtrack-hook`. Setup installs this shared runtime
+once if needed for Claude, Codex, or Cursor. OpenCode uses
+`@groundtrack/opencode-plugin` instead. Repeat runs use the installed runtime
+without querying npm for updates on every invocation.
+
+The CLI validates JSON/JSONC and TOML, preserves unrelated settings and comments,
+reuses existing Groundtrack aliases, and backs up changed files before applying
+atomic writes. Backups and selections live under
+`$XDG_CONFIG_HOME/groundtrack` (default `~/.config/groundtrack`). Backups may
+contain existing private configuration, so their directory and files are private.
+A failure rolls back completed writes where possible and reports the backup
+location. Malformed configuration, symbolic links, disabled connections/hooks,
+and endpoint conflicts are reported for the affected agent. Other independent
+selected agents can still be configured. Adding agents does not uninstall others.
+
+## Connection and verification
+
+A local check verifies configuration, not a live authenticated host. Status
+reports `configured` and `activation: unverified`; it never infers a connection
+from a generated file. Each agent must load the connection and its hooks.
+
+Interactive setup checks native sign-in requirements first. Claude Code must
+approve a new project MCP server before OAuth; setup shows that action instead
+of attempting a login that will fail. Codex can authenticate the selected endpoint
+with a one-command configuration override while project and hook trust remain
+explicit user actions. Existing Claude/OpenCode authentication is reused when
+the client reports it, and successful logins are reflected in the final summary.
+Use `--connect` to retry native sign-in for selected clients. Cursor and
+desktop-only installations show their UI steps. In unattended runs, setup prints instructions and never blocks waiting
+for OAuth. `--json` returns structured results without configuration contents or
+credentials; use `--yes` to apply an explicitly selected setup.
+
+Codex requires review and trust of the Groundtrack hook through `/hooks` or its
+hook approval UI. New Codex setups use `.codex/hooks.json`; existing inline
+hooks in `.codex/config.toml` are recognized and repaired without duplicating
+them. Claude's `CLAUDE.md` imports the shared `AGENTS.md` policy. The plugin is
+added to the existing OpenCode JSON/JSONC configuration.
+
+In each selected agent, ask:
+
+> Verify Groundtrack's connection and hook context with search_experiences.
+
+The returned hook-context and instruction-version warnings determine whether
+live activation needs attention. No synthetic engineering event is required.
+
+## Doctor compatibility
+
+`groundtrack doctor` is an alias for `status`; `groundtrack doctor --fix` uses the
+same setup and repair flow. Existing single-client commands continue to work:
+
+```sh
+groundtrack doctor --fix --client codex
+```
 
-The same package installs a deterministic `groundtrack` CLI. Run it from a
-repository root:
+The lower-level `runDoctor` API remains for existing consumers. New setup uses
+client-specific plans for MCP, hooks/plugins, and instructions, so it can preview
+and repair several selected agents safely.
 
-```bash
-groundtrack doctor
-groundtrack doctor --fix --client codex
+`templates/AGENTS.md` is the source of truth for the managed repository policy.
+After changing it, run `pnpm sync:agent-instructions`; tests reject drift between
+the setup guide, this repository's managed `AGENTS.md` block, and the packaged template.
+
+## Development
+
+Agent IDs, names, aliases, event sources, and enrichment kinds are defined once in
+`src/agents.ts`, exported as `@groundtrack/hooks/agents`. The CLI, web UI, hooks,
+and server consume that catalog and its derived types. Keep it dependency-free
+so browser bundles can load it without the Node-only hook runtime.
+
+Build and test the CLI from the repository:
+
+```sh
+pnpm --filter @groundtrack/hooks build
+node packages/hooks/dist/groundtrack.js setup --repo /path/to/test-project
+pnpm --filter @groundtrack/hooks test
 ```
 
-`doctor` checks the installed package/runtime version, discovers the actual
-Groundtrack MCP server alias, validates Claude/Codex/Cursor hook configuration,
-checks the managed `AGENTS.md` and `CLAUDE.md` instructions, and simulates a
-hook invocation. It exits non-zero when repair is needed.
-
-Pass `--client claude`, `--client codex`, or `--client cursor` when repairing a
-repository. This limits MCP alias discovery and configuration changes to that
-client. If more than one client is detected, `doctor --fix` refuses to guess
-which one to modify.
-
-The Doctor verifies local configuration and enrichment behavior, but it cannot
-observe whether a coding-agent host loaded or trusted a project hook. A
-`search_experiences` MCP response is the authoritative live check: Groundtrack
-returns a `hook_context_missing` warning when hook-injected session context is
-absent. In Codex, use `/hooks` to review and trust the Groundtrack hook when that
-warning appears.
-
-`doctor --fix` previews the diagnosis, asks before changing anything, updates
-only Groundtrack-owned hook entries and versioned managed instruction blocks,
-then repeats the verification. Use `--yes` for an explicitly authorized
-unattended repair. Existing surrounding instructions and unrelated hooks are
-preserved; malformed JSON and symbolic links are reported instead of
-overwritten.
-
-The CLI compares its package version with npm. Canonical hook configuration and
-instruction templates ship inside that versioned package, so repair does not
-depend on an LLM or download arbitrary configuration text.
-
-`templates/AGENTS.md` is the single source of truth for the managed repository
-policy. After changing it, run `pnpm sync:agent-instructions` to regenerate the
-setup-guide example; tests reject drift between the generated copy and the
-packaged template.
+With Claude Code and Codex installed, also run the isolated native-client
+preflight checks (they do not start OAuth or touch your normal agent profiles):
+
+```sh
+GROUNDTRACK_TEST_NATIVE_CLIENTS=1 pnpm --filter @groundtrack/hooks test
+```
 
 The `groundtrack-hook` command reads a pre-tool-use hook payload from standard input and enriches
 Groundtrack `store_event` and `search_experiences` calls with:

package/dist/agent-instructions.d.ts

@@ -0,0 +1,8 @@
+import type { Agent } from "./agents.js";
+/** Canonical managed Groundtrack policy, packaged with the CLI. */
+export declare const AGENT_INSTRUCTION_BODY: string;
+/** Version is derived from the canonical template marker; never define it separately. */
+export declare const AGENT_INSTRUCTION_TEMPLATE_VERSION: number;
+export type AgentInstructionsClient = Agent;
+/** Detect the managed policy version available to a client in one repository. */
+export declare function detectAgentInstructionsVersion(repoDir: string, client: AgentInstructionsClient): number | null;

package/dist/agents.d.ts

@@ -0,0 +1,36 @@
+/** Shared by the CLI, browser UI, hooks, and server. Keep this module dependency-free. */
+export declare const AGENTS: readonly [{
+    readonly id: "claude";
+    readonly name: "Claude Code";
+    readonly aliases: readonly ["claude-code"];
+    readonly source: "claude_code";
+    readonly enrichment: "command";
+}, {
+    readonly id: "codex";
+    readonly name: "Codex";
+    readonly aliases: readonly [];
+    readonly source: "codex";
+    readonly enrichment: "command";
+}, {
+    readonly id: "cursor";
+    readonly name: "Cursor";
+    readonly aliases: readonly [];
+    readonly source: "cursor";
+    readonly enrichment: "command";
+}, {
+    readonly id: "opencode";
+    readonly name: "OpenCode";
+    readonly aliases: readonly [];
+    readonly source: "opencode";
+    readonly enrichment: "plugin";
+}];
+export type AgentDefinition = (typeof AGENTS)[number];
+export type Agent = AgentDefinition["id"];
+export type CommandHookAgent = Extract<AgentDefinition, {
+    enrichment: "command";
+}>["id"];
+export declare const AGENT_IDS: ("claude" | "codex" | "cursor" | "opencode")[];
+export declare function isAgent(value: unknown): value is Agent;
+export declare function resolveAgent(value: string): AgentDefinition | undefined;
+export declare function agentFromClientName(value: string | null | undefined): AgentDefinition | undefined;
+export declare function requiresHookRuntime(id: Agent): boolean;

package/dist/agents.js

@@ -0,0 +1,27 @@
+/** Shared by the CLI, browser UI, hooks, and server. Keep this module dependency-free. */
+export const AGENTS = [
+    {
+        id: "claude",
+        name: "Claude Code",
+        aliases: ["claude-code"],
+        source: "claude_code",
+        enrichment: "command",
+    },
+    { id: "codex", name: "Codex", aliases: [], source: "codex", enrichment: "command" },
+    { id: "cursor", name: "Cursor", aliases: [], source: "cursor", enrichment: "command" },
+    { id: "opencode", name: "OpenCode", aliases: [], source: "opencode", enrichment: "plugin" },
+];
+export const AGENT_IDS = AGENTS.map((agent) => agent.id);
+export function isAgent(value) {
+    return AGENTS.some((agent) => agent.id === value);
+}
+export function resolveAgent(value) {
+    return AGENTS.find((agent) => agent.id === value || agent.aliases.some((alias) => alias === value));
+}
+export function agentFromClientName(value) {
+    const normalized = value?.trim().toLowerCase() ?? "";
+    return AGENTS.find((agent) => normalized.includes(agent.id));
+}
+export function requiresHookRuntime(id) {
+    return AGENTS.some((agent) => agent.id === id && agent.enrichment === "command");
+}

package/dist/doctor.d.ts

@@ -0,0 +1,34 @@
+import type { CommandHookAgent } from "./agents.js";
+export declare const CLAUDE_INSTRUCTION_BODY: string;
+export type Client = CommandHookAgent;
+type CheckStatus = "ok" | "advisory" | "issue" | "fixed" | "blocked";
+export type DoctorCheck = {
+    id: string;
+    label: string;
+    status: CheckStatus;
+    detail: string;
+    file?: string;
+};
+export type DoctorOptions = {
+    repoDir: string;
+    homeDir: string;
+    fix?: boolean;
+    clients?: Client[];
+    installedHookVersion?: string | null;
+    latestVersion?: string | null;
+    skipPackageInstall?: boolean;
+};
+export type DoctorResult = {
+    version: string;
+    clients: Client[];
+    aliases: string[];
+    checks: DoctorCheck[];
+    changedFiles: string[];
+    healthy: boolean;
+};
+export declare function claudeInstructionsAreCurrent(content: string | null): boolean;
+export declare function claudeUsesInlineGroundtrackInstructions(content: string | null): boolean;
+export declare function upsertManagedContent(content: string | null, desired: string, migrateLegacyAgentInstructions?: boolean): string;
+export declare function compareVersions(left: string, right: string): number;
+export declare function runDoctor(options: DoctorOptions): DoctorResult;
+export {};

package/dist/doctor.js

@@ -7,7 +7,7 @@ import { packageVersion } from "./version.js";
 const HOOK_TEMPLATE_VERSION = 1;
 const MANAGED_START = `<!-- groundtrack:start version=${AGENT_INSTRUCTION_TEMPLATE_VERSION} -->`;
 const MANAGED_END = "<!-- groundtrack:end -->";
-const CLAUDE_INSTRUCTION_BODY = `${MANAGED_START}
+export const CLAUDE_INSTRUCTION_BODY = `${MANAGED_START}
 @AGENTS.md
 ${MANAGED_END}`;
 const UNMARKED_AGENT_INSTRUCTION_BODY = AGENT_INSTRUCTION_BODY.replace(MANAGED_START, "")
@@ -232,14 +232,17 @@ function managedContentIsCurrent(content, desired) {
     const end = content.indexOf(MANAGED_END, start);
     return start >= 0 && end >= 0 && content.slice(start, end + MANAGED_END.length) === desired;
 }
-function claudeInstructionsAreCurrent(content) {
+export function claudeInstructionsAreCurrent(content) {
     if (!content)
         return false;
-    return (/^@AGENTS\.md$/m.test(content) ||
-        managedContentIsCurrent(content, AGENT_INSTRUCTION_BODY) ||
+    if (/^@AGENTS\.md\s*$/m.test(content)) {
+        const bridgeVersion = /<!-- groundtrack:start version=(\d+) -->/.exec(content)?.[1];
+        return (bridgeVersion === undefined || Number(bridgeVersion) >= AGENT_INSTRUCTION_TEMPLATE_VERSION);
+    }
+    return (managedContentIsCurrent(content, AGENT_INSTRUCTION_BODY) ||
         content.includes(UNMARKED_AGENT_INSTRUCTION_BODY));
 }
-function claudeUsesInlineGroundtrackInstructions(content) {
+export function claudeUsesInlineGroundtrackInstructions(content) {
     return content?.includes(LEGACY_AGENT_SIGNATURE) ?? false;
 }
 function removeLegacyAgentInstructions(content) {
@@ -266,7 +269,7 @@ function removeLegacyAgentInstructions(content) {
     }
     return lines.join("\n");
 }
-function upsertManagedContent(content, desired, migrateLegacyAgentInstructions = false) {
+export function upsertManagedContent(content, desired, migrateLegacyAgentInstructions = false) {
     const existing = content ?? "";
     const managed = /<!-- groundtrack:start version=\d+ -->[\s\S]*?<!-- groundtrack:end -->/;
     if (managed.test(existing)) {

package/dist/enrich-store-event.d.ts

@@ -0,0 +1,18 @@
+type HookInput = {
+    conversation_id?: unknown;
+    cwd?: unknown;
+    generation_id?: unknown;
+    model?: unknown;
+    model_id?: unknown;
+    session_id?: unknown;
+    transcript_path?: unknown;
+    tool_input?: unknown;
+    tool_name?: unknown;
+    tool_use_id?: unknown;
+    workspace_roots?: unknown;
+};
+export type GroundtrackContextTool = "store_event" | "search_experiences";
+export declare function groundtrackContextTool(toolName: unknown): GroundtrackContextTool | null;
+export declare function enrichInput(hookInput: HookInput, clientOverride?: string, tool?: GroundtrackContextTool): Record<string, unknown>;
+export declare function hookOutput(hookInput: HookInput, clientOverride?: string): Record<string, unknown>;
+export {};

package/dist/enrich-store-event.js

@@ -1,3 +1,4 @@
+import { isAgent } from "./agents.js";
 import { execFileSync } from "node:child_process";
 import { closeSync, fstatSync, openSync, readSync } from "node:fs";
 import { detectAgentInstructionsVersion, } from "./agent-instructions.js";
@@ -73,7 +74,7 @@ function transcriptModel(transcriptPath) {
     }
     return null;
 }
-function groundtrackContextTool(toolName) {
+export function groundtrackContextTool(toolName) {
     const normalized = nonEmptyString(toolName)?.toLowerCase();
     if (!normalized)
         return null;
@@ -149,7 +150,7 @@ export function enrichInput(hookInput, clientOverride, tool = "store_event") {
         toolInput.clientEventId = [host, hostSessionId, invocationId].filter(Boolean).join(":");
     }
     if (tool === "search_experiences") {
-        const client = host === "claude" || host === "cursor" ? host : "codex";
+        const client = isAgent(host) ? host : "codex";
         const root = repositoryRoot(cwd);
         toolInput.agentInstructionsVersion = root ? detectAgentInstructionsVersion(root, client) : null;
     }

package/dist/groundtrack-hook.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/groundtrack.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/groundtrack.js

@@ -1,199 +1,10 @@
 #!/usr/bin/env node
-import { createInterface } from "node:readline/promises";
-import { spawnSync } from "node:child_process";
-import { homedir } from "node:os";
-import { resolve } from "node:path";
-import { stdin, stdout } from "node:process";
-import { compareVersions, runDoctor } from "./doctor.js";
-import { packageVersion } from "./version.js";
-function usage() {
-    return `Groundtrack CLI
-
-Usage:
-  groundtrack doctor [--fix] [--yes] [--json] [--client CLIENT] [--repo PATH]
-  groundtrack version [--json]
-
-Commands:
-  doctor       Diagnose Groundtrack hooks and managed agent instructions
-  doctor --fix Repair deterministic configuration drift
-  version      Print the installed CLI/runtime version
-
-Options:
-  --client     Limit diagnosis and repair to claude, codex, or cursor
-`;
-}
-function parseArguments(argv) {
-    if (argv[0] &&
-        !["doctor", "version", "--version"].includes(argv[0]) &&
-        !argv[0].startsWith("-")) {
-        throw new Error(`Unknown command: ${argv[0]}\n\n${usage()}`);
-    }
-    const command = argv[0] === "version" || argv[0] === "--version" ? "version" : "doctor";
-    let repoDir = process.cwd();
-    let homeDir = homedir();
-    let client;
-    for (let index = 0; index < argv.length; index += 1) {
-        if (argv[index] === "--repo" && argv[index + 1])
-            repoDir = resolve(argv[++index]);
-        if (argv[index] === "--home" && argv[index + 1])
-            homeDir = resolve(argv[++index]);
-        if (argv[index] === "--client") {
-            const value = argv[++index];
-            if (value !== "claude" && value !== "codex" && value !== "cursor") {
-                throw new Error("--client must be one of: claude, codex, cursor");
-            }
-            client = value;
-        }
-    }
-    return {
-        command,
-        fix: argv.includes("--fix"),
-        yes: argv.includes("--yes") || argv.includes("-y"),
-        json: argv.includes("--json"),
-        client,
-        repoDir,
-        homeDir,
-    };
-}
-function printResult(result, options = {}) {
-    const selectedClient = options.client ?? (result.clients.length === 1 ? result.clients[0] : null);
-    const fixHint = !options.showFixHint
-        ? ""
-        : selectedClient
-            ? ` Run: groundtrack doctor --fix --client ${selectedClient}`
-            : " Re-run with --client claude, --client codex, or --client cursor.";
-    stdout.write(`Groundtrack doctor ${result.version}\n`);
-    stdout.write(`Clients: ${result.clients.join(", ")}\n`);
-    stdout.write(`MCP aliases: ${result.aliases.join(", ")}\n\n`);
-    for (const check of result.checks) {
-        const icon = check.status === "ok"
-            ? "✓"
-            : check.status === "advisory"
-                ? "i"
-                : check.status === "fixed"
-                    ? "◆"
-                    : check.status === "blocked"
-                        ? "×"
-                        : "!";
-        stdout.write(`${icon} ${check.label}: ${check.detail}${check.file ? ` (${check.file})` : ""}\n`);
-    }
-    if (result.changedFiles.length > 0) {
-        stdout.write(`\nUpdated ${result.changedFiles.length} file(s).\n`);
-    }
-    stdout.write(result.healthy
-        ? "\nGroundtrack local configuration is healthy. Live hook activation is verified by Groundtrack MCP calls.\n"
-        : `\nGroundtrack local configuration needs attention.${fixHint}\n`);
-}
-async function confirmFix() {
-    const prompt = createInterface({ input: stdin, output: stdout });
-    try {
-        const answer = await prompt.question("Apply deterministic Groundtrack repairs? [y/N] ");
-        return /^y(?:es)?$/i.test(answer.trim());
-    }
-    finally {
-        prompt.close();
-    }
-}
-async function latestPackageVersion() {
-    const override = process.env.GROUNDTRACK_DOCTOR_LATEST_VERSION;
-    if (override)
-        return override;
-    if (process.env.GROUNDTRACK_DOCTOR_OFFLINE === "1")
-        return null;
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), 2_000);
-    try {
-        const response = await fetch("https://registry.npmjs.org/@groundtrack%2Fhooks/latest", {
-            signal: controller.signal,
-            headers: { accept: "application/json" },
-        });
-        if (!response.ok)
-            return null;
-        const payload = (await response.json());
-        return typeof payload.version === "string" ? payload.version : null;
-    }
-    catch {
-        return null;
-    }
-    finally {
-        clearTimeout(timeout);
-    }
-}
-function updatePackageAndRerun(version) {
-    const install = spawnSync("npm", ["install", "-g", `@groundtrack/hooks@${version}`], {
-        stdio: "inherit",
-        timeout: 120_000,
-    });
-    if (install.status !== 0)
-        return install.status ?? 1;
-    const rerun = spawnSync("groundtrack", process.argv.slice(2), {
-        stdio: "inherit",
-        env: {
-            ...process.env,
-            GROUNDTRACK_DOCTOR_REEXEC: "1",
-            GROUNDTRACK_DOCTOR_LATEST_VERSION: version,
-        },
-    });
-    return rerun.status ?? 1;
-}
-async function main() {
-    const args = parseArguments(process.argv.slice(2));
-    if (process.argv.includes("--help") || process.argv.includes("-h")) {
-        stdout.write(usage());
-        return;
-    }
-    if (args.command === "version") {
-        const version = packageVersion();
-        stdout.write(args.json ? `${JSON.stringify({ version })}\n` : `${version}\n`);
-        return;
-    }
-    const base = {
-        repoDir: args.repoDir,
-        homeDir: args.homeDir,
-        clients: args.client ? [args.client] : undefined,
-        skipPackageInstall: process.env.GROUNDTRACK_DOCTOR_SKIP_INSTALL === "1",
-        latestVersion: await latestPackageVersion(),
-    };
-    const diagnosis = runDoctor(base);
-    if (!args.fix) {
-        if (args.json)
-            stdout.write(`${JSON.stringify(diagnosis, null, 2)}\n`);
-        else
-            printResult(diagnosis, { showFixHint: true, client: args.client });
-        process.exitCode = diagnosis.healthy ? 0 : 1;
-        return;
-    }
-    if (!args.client && diagnosis.clients.length > 1) {
-        throw new Error(`Multiple coding-agent clients detected: ${diagnosis.clients.join(", ")}. Re-run with --client claude, --client codex, or --client cursor so Doctor does not modify unrelated client configuration.`);
-    }
-    if (diagnosis.healthy) {
-        if (args.json)
-            stdout.write(`${JSON.stringify(diagnosis, null, 2)}\n`);
-        else
-            printResult(diagnosis);
-        return;
-    }
-    if (!args.json)
-        printResult(diagnosis);
-    if (!args.yes && !(await confirmFix())) {
-        stdout.write("No changes made.\n");
-        process.exitCode = 1;
-        return;
-    }
-    if (base.latestVersion &&
-        compareVersions(base.latestVersion, diagnosis.version) > 0 &&
-        process.env.GROUNDTRACK_DOCTOR_REEXEC !== "1") {
-        process.exitCode = updatePackageAndRerun(base.latestVersion);
-        return;
-    }
-    const repaired = runDoctor({ ...base, fix: true });
-    if (args.json)
-        stdout.write(`${JSON.stringify(repaired, null, 2)}\n`);
+import { runCli } from "./setup/cli.js";
+runCli(process.argv.slice(2)).catch((error) => {
+    const message = error instanceof Error ? error.message : "Groundtrack setup failed.";
+    if (process.argv.includes("--json"))
+        process.stdout.write(`${JSON.stringify({ error: message, applied: false })}\n`);
     else
-        printResult(repaired);
-    process.exitCode = repaired.healthy ? 0 : 1;
-}
-main().catch((error) => {
-    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        process.stderr.write(`${message}\n`);
     process.exitCode = 1;
 });

package/dist/setup/agents.d.ts

@@ -0,0 +1,59 @@
+import { type Agent } from "../agents.js";
+export declare const MCP_URL = "https://app.groundtrack.dev/api/mcp";
+export type SetupEnvironment = {
+    repoDir: string;
+    homeDir: string;
+    env: NodeJS.ProcessEnv;
+    platform: NodeJS.Platform;
+};
+export declare function environment(options?: Partial<SetupEnvironment>): SetupEnvironment;
+export declare function agentId(value: string): Agent;
+export declare function executable(name: string, context: SetupEnvironment): string | null;
+export declare function stateDir(context: SetupEnvironment): string;
+export declare function configPaths(agent: Agent, context: SetupEnvironment): {
+    project: string;
+    user: string;
+    presence: string[];
+};
+export declare function serverPath(agent: Agent, config: Record<string, unknown>): string[];
+export declare function readConfig(agent: Agent, text: string): Record<string, unknown>;
+export declare function serverMap(agent: Agent, config: Record<string, unknown>): Record<string, unknown>;
+export declare function isGroundtrack(alias: string, value: unknown, url: string): boolean;
+export declare function discoverAgents(context: SetupEnvironment, url?: string): ({
+    id: "claude";
+    name: "Claude Code";
+    aliases: readonly ["claude-code"];
+    source: "claude_code";
+    enrichment: "command";
+    detected: boolean;
+    configured: boolean;
+    issue: string | null;
+} | {
+    id: "codex";
+    name: "Codex";
+    aliases: readonly [];
+    source: "codex";
+    enrichment: "command";
+    detected: boolean;
+    configured: boolean;
+    issue: string | null;
+} | {
+    id: "cursor";
+    name: "Cursor";
+    aliases: readonly [];
+    source: "cursor";
+    enrichment: "command";
+    detected: boolean;
+    configured: boolean;
+    issue: string | null;
+} | {
+    id: "opencode";
+    name: "OpenCode";
+    aliases: readonly [];
+    source: "opencode";
+    enrichment: "plugin";
+    detected: boolean;
+    configured: boolean;
+    issue: string | null;
+})[];
+export declare function savedAgents(context: SetupEnvironment): Agent[] | null;