@jam-mcp/server 1.0.0

package/dist/adapters/telemetry/console-telemetry.js

@@ -0,0 +1,31 @@
+/**
+ * One key=value line per tool call on stderr. stdout is reserved for the MCP
+ * stdio protocol, so nothing here may ever write to stdout.
+ *
+ * Only the fields below are emitted - never credentials, headers, JQL bind
+ * values, or issue content.
+ */
+export class ConsoleTelemetry {
+    enabled;
+    constructor(enabled = true) {
+        this.enabled = enabled;
+    }
+    recordTool(m) {
+        if (!this.enabled)
+            return;
+        const parts = [
+            `tool=${m.tool}`,
+            `duration_ms=${Math.round(m.durationMs)}`,
+            `jira_requests=${m.jiraRequests}`,
+            `issues=${m.issues}`,
+            `response_bytes=${m.responseBytes}`,
+        ];
+        if (m.pages !== undefined)
+            parts.push(`pages=${m.pages}`);
+        if (m.complete !== undefined)
+            parts.push(`complete=${m.complete}`);
+        if (m.errorCode)
+            parts.push(`error=${m.errorCode}`);
+        process.stderr.write(`[jam] ${parts.join(" ")}\n`);
+    }
+}

package/dist/application/get-full-issue-context.d.ts

@@ -0,0 +1,18 @@
+import type { JamDeps } from "../deps.js";
+import { type CompletenessMeta } from "../domain/completeness.js";
+import type { FullIssueContext } from "../domain/context.js";
+export type GetFullIssueContextInput = {
+    issueKeys: string[];
+};
+export type GetFullIssueContextResult = {
+    issues: FullIssueContext[];
+    meta: CompletenessMeta;
+};
+/**
+ * Final-judgement path: description plus the complete comment thread.
+ *
+ * Comments are the whole point here - an agreement or approval call made on a
+ * partial thread is exactly the failure this tool exists to prevent, so the
+ * thread is paged to exhaustion and any shortfall is reported.
+ */
+export declare function getFullIssueContext(deps: JamDeps, input: GetFullIssueContextInput): Promise<GetFullIssueContextResult>;

package/dist/application/get-full-issue-context.js

@@ -0,0 +1,120 @@
+import { JIRA_EVIDENCE, nowIso } from "../domain/completeness.js";
+import { fieldsFor } from "../policy/field-policy.js";
+import { applyOutputBudget } from "../policy/output-budget-policy.js";
+import { normalizeKeys, toContext, MAX_KEYS_PER_CALL } from "./get-issue-context.js";
+const COMMENT_PAGE_SIZE = 100;
+/** Safety stop for pathological threads; hitting it is reported, never silent. */
+const MAX_COMMENT_PAGES = 20;
+/**
+ * Final-judgement path: description plus the complete comment thread.
+ *
+ * Comments are the whole point here - an agreement or approval call made on a
+ * partial thread is exactly the failure this tool exists to prevent, so the
+ * thread is paged to exhaustion and any shortfall is reported.
+ */
+export async function getFullIssueContext(deps, input) {
+    const started = performance.now();
+    const keys = normalizeKeys(input.issueKeys);
+    const fields = fieldsFor("full", deps.config);
+    const fetched = await deps.jira.getIssues({ keys, fields });
+    let jiraRequests = Math.ceil(keys.length / MAX_KEYS_PER_CALL) || 1;
+    let responseBytes = fetched.responseBytes;
+    const partialThreads = [];
+    for (const issue of fetched.issues) {
+        const total = fetched.commentTotals[issue.key] ?? issue.comments.length;
+        let pages = 0;
+        while (issue.comments.length < total && pages < MAX_COMMENT_PAGES) {
+            const page = await deps.jira.getComments({
+                key: issue.key,
+                startAt: issue.comments.length,
+                maxResults: COMMENT_PAGE_SIZE,
+            });
+            jiraRequests++;
+            responseBytes += page.responseBytes;
+            pages++;
+            if (page.comments.length === 0)
+                break;
+            issue.comments.push(...page.comments);
+        }
+        if (issue.comments.length < total)
+            partialThreads.push(issue.key);
+    }
+    const budget = applyOutputBudget(fetched.issues, deps.config.output.fullTokens);
+    const issues = budget.issues.map((issue) => toFull(issue));
+    const commentsComplete = budget.commentsComplete && partialThreads.length === 0;
+    const meta = {
+        ...JIRA_EVIDENCE,
+        level: "full",
+        complete: budget.complete && fetched.missingKeys.length === 0 && partialThreads.length === 0,
+        fetchedAt: nowIso(),
+        fieldsLoaded: fields,
+        commentsComplete,
+        linksComplete: budget.linksComplete,
+    };
+    const notes = [];
+    if (fetched.missingKeys.length > 0) {
+        meta.missingKeys = fetched.missingKeys;
+        meta.reason = "PARTIAL_API_RESPONSE";
+        notes.push(`${fetched.missingKeys.length} issue(s) could not be read - they may not exist or may not be visible to this account.`);
+    }
+    if (partialThreads.length > 0) {
+        meta.reason ??= "PARTIAL_API_RESPONSE";
+        meta.overflow = [...(meta.overflow ?? []), "comments"];
+        notes.push(`Comment thread not fully retrieved for: ${partialThreads.join(", ")}. Do not treat the discussion as settled.`);
+    }
+    if (budget.overflow.length > 0) {
+        meta.overflow = [...new Set([...(meta.overflow ?? []), ...budget.overflow])];
+        meta.reason ??= "OUTPUT_BUDGET";
+        notes.push(`Dropped ${budget.overflow.join(", ")}${budget.droppedComments > 0 ? ` (${budget.droppedComments} oldest comment(s))` : ""} to stay within the ${deps.config.output.fullTokens}-token full budget. Request a single issue key for the complete record.`);
+    }
+    if (notes.length > 0)
+        meta.notes = notes;
+    deps.telemetry.recordTool({
+        tool: "jira_full",
+        durationMs: performance.now() - started,
+        jiraRequests,
+        issues: issues.length,
+        responseBytes,
+        complete: meta.complete,
+    });
+    return { issues, meta };
+}
+function toFull(issue) {
+    const full = {
+        ...toContext(issue),
+        comments: issue.comments,
+    };
+    if (issue.description)
+        full.description = issue.description;
+    if (issue.history?.length)
+        full.history = issue.history;
+    const latest = latestCommentAt(issue.comments);
+    if (latest)
+        full.latestCommentAt = latest;
+    return full;
+}
+/**
+ * Max, not last: the first page arrives embedded in the bulk fetch in
+ * whatever order Jira returned it, and the output budget drops from the front,
+ * so position says nothing about recency. An edit counts - `updated` is only
+ * present when it differs from `created`.
+ */
+function latestCommentAt(comments) {
+    let latest;
+    let latestMs = Number.NEGATIVE_INFINITY;
+    for (const comment of comments) {
+        const at = comment.updated ?? comment.created;
+        if (!at)
+            continue;
+        // Parsed rather than compared as text: Jira stamps an offset, and
+        // "...+0900" sorts below "...Z" as a string while being later in time.
+        const ms = Date.parse(at);
+        if (Number.isNaN(ms))
+            continue;
+        if (ms > latestMs) {
+            latestMs = ms;
+            latest = at;
+        }
+    }
+    return latest;
+}

package/dist/application/get-issue-context.d.ts

@@ -0,0 +1,19 @@
+import type { JamDeps } from "../deps.js";
+import { type CompletenessMeta } from "../domain/completeness.js";
+import type { FullIssueContext, IssueContext } from "../domain/context.js";
+export type GetIssueContextInput = {
+    issueKeys: string[];
+};
+export type GetIssueContextResult = {
+    issues: IssueContext[];
+    meta: CompletenessMeta;
+};
+export declare const MAX_KEYS_PER_CALL = 100;
+/**
+ * Readiness path. One batched round trip for every requested key, plus the
+ * dependency structure needed to answer "can this start yet".
+ */
+export declare function getIssueContext(deps: JamDeps, input: GetIssueContextInput): Promise<GetIssueContextResult>;
+/** CONTEXT projection: everything but description/comments/history. */
+export declare function toContext(issue: FullIssueContext): IssueContext;
+export declare function normalizeKeys(raw: string[]): string[];

package/dist/application/get-issue-context.js

@@ -0,0 +1,79 @@
+import { JIRA_EVIDENCE, nowIso } from "../domain/completeness.js";
+import { JamError } from "../domain/errors.js";
+import { fieldsFor } from "../policy/field-policy.js";
+import { applyOutputBudget } from "../policy/output-budget-policy.js";
+import { toSummary } from "./search-issues.js";
+export const MAX_KEYS_PER_CALL = 100;
+/**
+ * Readiness path. One batched round trip for every requested key, plus the
+ * dependency structure needed to answer "can this start yet".
+ */
+export async function getIssueContext(deps, input) {
+    const started = performance.now();
+    const keys = normalizeKeys(input.issueKeys);
+    const fields = fieldsFor("context", deps.config);
+    const fetched = await deps.jira.getIssues({ keys, fields });
+    const budget = applyOutputBudget(fetched.issues, deps.config.output.contextTokens);
+    const issues = budget.issues.map(toContext);
+    const meta = {
+        ...JIRA_EVIDENCE,
+        level: "context",
+        complete: budget.complete && fetched.missingKeys.length === 0,
+        fetchedAt: nowIso(),
+        fieldsLoaded: fields,
+        linksComplete: budget.linksComplete,
+    };
+    const overflow = [...budget.overflow];
+    if (fetched.missingKeys.length > 0) {
+        meta.missingKeys = fetched.missingKeys;
+        meta.reason = "PARTIAL_API_RESPONSE";
+        meta.notes = [
+            `${fetched.missingKeys.length} issue(s) could not be read - they may not exist or may not be visible to this account.`,
+        ];
+    }
+    if (overflow.length > 0) {
+        meta.overflow = overflow;
+        meta.reason ??= "OUTPUT_BUDGET";
+        meta.notes = [
+            ...(meta.notes ?? []),
+            `Dropped ${overflow.join(", ")} to stay within the ${deps.config.output.contextTokens}-token context budget. Request fewer keys for the full picture.`,
+        ];
+    }
+    deps.telemetry.recordTool({
+        tool: "jira_context",
+        durationMs: performance.now() - started,
+        jiraRequests: Math.ceil(keys.length / MAX_KEYS_PER_CALL) || 1,
+        issues: issues.length,
+        responseBytes: fetched.responseBytes,
+        complete: meta.complete,
+    });
+    return { issues, meta };
+}
+/** CONTEXT projection: everything but description/comments/history. */
+export function toContext(issue) {
+    const context = {
+        ...toSummary(issue),
+        subtasks: issue.subtasks,
+        links: issue.links,
+        customFields: issue.customFields,
+    };
+    if (issue.issueType)
+        context.issueType = issue.issueType;
+    if (issue.parent)
+        context.parent = issue.parent;
+    return context;
+}
+export function normalizeKeys(raw) {
+    const keys = [...new Set(raw.map((k) => k.trim().toUpperCase()).filter(Boolean))];
+    if (keys.length === 0) {
+        throw new JamError("CONFIG_INVALID", "issueKeys must contain at least one issue key.");
+    }
+    if (keys.length > MAX_KEYS_PER_CALL * 5) {
+        throw new JamError("CONTEXT_TOO_LARGE", `Too many issue keys in one call (${keys.length}). Split the request.`);
+    }
+    const malformed = keys.filter((k) => !/^[A-Z][A-Z0-9_]*-\d+$/.test(k));
+    if (malformed.length > 0) {
+        throw new JamError("CONFIG_INVALID", `Not valid Jira issue keys: ${malformed.join(", ")}`, { malformed });
+    }
+    return keys;
+}

package/dist/application/search-issues.d.ts

@@ -0,0 +1,22 @@
+import type { JamDeps } from "../deps.js";
+import type { FullIssueContext } from "../domain/context.js";
+import { type CompletenessMeta } from "../domain/completeness.js";
+import type { IssueSummary } from "../domain/issue.js";
+import { type SearchScope } from "../policy/pagination-policy.js";
+export type SearchIssuesInput = {
+    jql: string;
+    scope?: SearchScope;
+};
+export type SearchIssuesResult = {
+    issues: IssueSummary[];
+    meta: CompletenessMeta;
+};
+/**
+ * Discovery path. Lite fields only, pagination owned by JAM.
+ *
+ * A `complete` search walks nextPageToken to exhaustion; if it hits the page
+ * cap it says so instead of presenting a partial list as the whole set.
+ */
+export declare function searchIssues(deps: JamDeps, input: SearchIssuesInput): Promise<SearchIssuesResult>;
+/** Project down to lite fields so heavy data cannot leak through this path. */
+export declare function toSummary(issue: FullIssueContext): IssueSummary;

package/dist/application/search-issues.js

@@ -0,0 +1,93 @@
+import { JIRA_EVIDENCE, nowIso } from "../domain/completeness.js";
+import { fieldsFor } from "../policy/field-policy.js";
+import { paginationFor } from "../policy/pagination-policy.js";
+import { estimateTokens } from "../policy/output-budget-policy.js";
+/**
+ * Discovery path. Lite fields only, pagination owned by JAM.
+ *
+ * A `complete` search walks nextPageToken to exhaustion; if it hits the page
+ * cap it says so instead of presenting a partial list as the whole set.
+ */
+export async function searchIssues(deps, input) {
+    const started = performance.now();
+    const scope = input.scope ?? "preview";
+    const fields = fieldsFor("search", deps.config);
+    const plan = paginationFor(scope, deps.config);
+    const collected = [];
+    let pageToken;
+    let pagesFetched = 0;
+    let responseBytes = 0;
+    let truncatedByPageCap = false;
+    for (;;) {
+        const page = await deps.jira.searchPage({
+            jql: input.jql,
+            fields,
+            pageSize: plan.pageSize,
+            ...(pageToken ? { pageToken } : {}),
+        });
+        pagesFetched++;
+        responseBytes += page.responseBytes;
+        collected.push(...page.issues);
+        pageToken = page.nextPageToken;
+        if (!pageToken)
+            break;
+        if (pagesFetched >= plan.maxPages) {
+            // preview stops here by design; complete hitting the cap is an overflow.
+            truncatedByPageCap = scope === "complete";
+            break;
+        }
+    }
+    const issues = collected.map(toSummary);
+    const morePagesAvailable = Boolean(pageToken);
+    const meta = {
+        ...JIRA_EVIDENCE,
+        level: "search",
+        complete: !morePagesAvailable,
+        fetchedAt: nowIso(),
+        pagesFetched,
+        fieldsLoaded: fields,
+    };
+    if (morePagesAvailable) {
+        meta.reason = truncatedByPageCap ? "OUTPUT_BUDGET" : "PARTIAL_API_RESPONSE";
+        meta.overflow = ["pages"];
+        meta.notes = [
+            scope === "preview"
+                ? "Preview scope returns the first page only. Re-run with scope=\"complete\" to enumerate every match."
+                : `Stopped at the ${plan.maxPages}-page safety cap. Narrow the JQL or raise search.maxPages in project.yaml.`,
+        ];
+    }
+    const budget = deps.config.output.searchTokens;
+    const estimated = estimateTokens(issues);
+    if (estimated > budget) {
+        meta.notes = [
+            ...(meta.notes ?? []),
+            `Result is larger than the ${budget}-token search budget (~${estimated}). Narrow the JQL.`,
+        ];
+    }
+    deps.telemetry.recordTool({
+        tool: "jira_search",
+        durationMs: performance.now() - started,
+        jiraRequests: pagesFetched,
+        issues: issues.length,
+        responseBytes,
+        pages: pagesFetched,
+        complete: meta.complete,
+    });
+    return { issues, meta };
+}
+/** Project down to lite fields so heavy data cannot leak through this path. */
+export function toSummary(issue) {
+    const summary = {
+        key: issue.key,
+        summary: issue.summary,
+        status: issue.status,
+        updated: issue.updated,
+        labels: issue.labels,
+        components: issue.components,
+    };
+    if (issue.assignee)
+        summary.assignee = issue.assignee;
+    if (issue.priority)
+        summary.priority = issue.priority;
+    return summary;
+}

package/dist/bootstrap/boot-health-gate.d.ts

@@ -0,0 +1,25 @@
+import type { JamDeps } from "../deps.js";
+export type HealthCheck = {
+    name: string;
+    ok: boolean;
+    /** A failed fatal check blocks MCP startup; a non-fatal one is a warning. */
+    fatal: boolean;
+    detail?: string;
+};
+export type GateMode = "boot" | "full";
+export type GateResult = {
+    mode: GateMode;
+    checks: HealthCheck[];
+    passed: boolean;
+};
+/**
+ * One health-check core shared by `jam doctor`, `jam setup` and `jam serve`.
+ *
+ * "boot" mode is what `jam serve` runs on every startup: local checks only
+ * (Node version, config, credentials, base URL shape, MCP wiring) - no network
+ * round trip, so it never adds Jira's latency to Claude Code's own startup.
+ * "full" mode adds live Jira connectivity checks and is what `jam doctor` and
+ * `jam setup` run, since those are explicit, occasional diagnostics rather
+ * than something on the hot path of every session.
+ */
+export declare function runHealthGate(deps: JamDeps, mode: GateMode): Promise<GateResult>;

package/dist/bootstrap/boot-health-gate.js

@@ -0,0 +1,137 @@
+import { toJamError } from "../domain/errors.js";
+import { createServer } from "../mcp/create-server.js";
+/**
+ * One health-check core shared by `jam doctor`, `jam setup` and `jam serve`.
+ *
+ * "boot" mode is what `jam serve` runs on every startup: local checks only
+ * (Node version, config, credentials, base URL shape, MCP wiring) - no network
+ * round trip, so it never adds Jira's latency to Claude Code's own startup.
+ * "full" mode adds live Jira connectivity checks and is what `jam doctor` and
+ * `jam setup` run, since those are explicit, occasional diagnostics rather
+ * than something on the hot path of every session.
+ */
+export async function runHealthGate(deps, mode) {
+    const checks = [];
+    const add = (c) => checks.push(c);
+    const major = Number(process.versions.node.split(".")[0]);
+    add({
+        name: "Node runtime",
+        ok: major >= 20,
+        fatal: true,
+        detail: major >= 20 ? `v${process.versions.node}` : `v${process.versions.node} (need >= 20)`,
+    });
+    add({
+        name: "Project config",
+        ok: true,
+        fatal: true,
+        // Three states, not two: a project with no config file may still have a
+        // key, supplied for this run only. Saying "using defaults" there would
+        // report the opposite of what JAM is about to do.
+        detail: deps.configPath
+            ? `${deps.configPath} (project=${deps.config.project.key || "unset"})`
+            : deps.keySource
+                ? `no project.yaml - project=${deps.config.project.key} from ${deps.keySource}`
+                : "using defaults (no .jira-agent/project.yaml found)",
+    });
+    const hasKey = Boolean(deps.config.project.key);
+    add({
+        name: "Jira project key",
+        ok: hasKey,
+        fatal: true,
+        detail: hasKey ? deps.config.project.key : "not set - run `jam setup --project <KEY>`",
+    });
+    const creds = deps.credentials.describe();
+    const credsOk = Boolean(creds.baseUrl && creds.email && creds.hasToken);
+    add({
+        name: "Credentials present",
+        ok: credsOk,
+        fatal: true,
+        // Never print the token itself - presence and source only.
+        detail: credsOk
+            ? `${creds.email} @ ${creds.baseUrl} (${creds.source})`
+            : "run `jam auth login`, or set JIRA_BASE_URL, JIRA_EMAIL and JIRA_API_TOKEN",
+    });
+    const baseUrlOk = Boolean(creds.baseUrl && /^https?:\/\//.test(creds.baseUrl));
+    add({
+        name: "Jira base URL",
+        ok: baseUrlOk,
+        fatal: true,
+        detail: baseUrlOk ? creds.baseUrl : "must start with http:// or https://",
+    });
+    try {
+        createServer(deps);
+        add({ name: "MCP server startup", ok: true, fatal: true, detail: "3 tools registered" });
+    }
+    catch (err) {
+        add({ name: "MCP server startup", ok: false, fatal: true, detail: toJamError(err).message });
+    }
+    const bootFatalFailed = checks.some((c) => c.fatal && !c.ok);
+    if (mode === "boot" || bootFatalFailed) {
+        return { mode, checks, passed: !bootFatalFailed };
+    }
+    // full mode: live Jira connectivity, only reached once every boot-level check passed.
+    try {
+        const me = await deps.jira.getCurrentUser();
+        add({
+            name: "Jira authentication",
+            ok: true,
+            fatal: true,
+            detail: me.displayName ?? me.emailAddress ?? me.accountId,
+        });
+    }
+    catch (err) {
+        add({ name: "Jira authentication", ok: false, fatal: true, detail: describeErr(err) });
+        return { mode, checks, passed: false };
+    }
+    const projectKey = deps.config.project.key;
+    let sampleKey;
+    try {
+        const page = await deps.jira.searchPage({
+            jql: `project = "${projectKey}" ORDER BY updated DESC`,
+            fields: ["summary", "status"],
+            pageSize: 1,
+        });
+        sampleKey = page.issues[0]?.key;
+        add({
+            name: `JQL search / ${projectKey} access`,
+            ok: true,
+            fatal: true,
+            detail: sampleKey ? `reachable (sample ${sampleKey})` : "reachable (project has no issues)",
+        });
+    }
+    catch (err) {
+        add({ name: `JQL search / ${projectKey} access`, ok: false, fatal: true, detail: describeErr(err) });
+        return { mode, checks, passed: false };
+    }
+    if (sampleKey) {
+        try {
+            const batch = await deps.jira.getIssues({
+                keys: [sampleKey],
+                fields: ["summary", "status", "issuelinks"],
+            });
+            add({
+                name: "Issue detail endpoint",
+                ok: batch.issues.length === 1,
+                fatal: false,
+                detail: batch.issues.length === 1 ? `read ${sampleKey}` : `could not read ${sampleKey}`,
+            });
+        }
+        catch (err) {
+            add({ name: "Issue detail endpoint", ok: false, fatal: false, detail: describeErr(err) });
+        }
+    }
+    else {
+        add({
+            name: "Issue detail endpoint",
+            ok: true,
+            fatal: false,
+            detail: "skipped - no issue available to sample",
+        });
+    }
+    const anyFatalFailed = checks.some((c) => c.fatal && !c.ok);
+    return { mode, checks, passed: !anyFatalFailed };
+}
+function describeErr(err) {
+    const e = toJamError(err);
+    return `${e.code}: ${e.message}`;
+}

package/dist/bootstrap/bootstrap-orchestrator.d.ts

@@ -0,0 +1,15 @@
+import { type BuildDepsOptions, type JamDeps } from "../deps.js";
+import { type GateResult } from "./boot-health-gate.js";
+export type BootstrapResult = {
+    deps: JamDeps;
+    gate: GateResult;
+};
+export type BootstrapForServeOptions = Pick<BuildDepsOptions, "cwd" | "jira" | "credentials" | "env" | "presetsPath" | "home" | "git">;
+/**
+ * `jam serve`'s boot path: resolve the project config - reading a file if the
+ * project has one, otherwise falling back to an explicitly supplied key - then
+ * run the local-only "boot" gate. Nothing here writes to the repository, and
+ * no live Jira call happens either, so every `claude` startup stays fast even
+ * when Jira is slow or briefly unreachable.
+ */
+export declare function bootstrapForServe(options?: BootstrapForServeOptions): Promise<BootstrapResult>;

package/dist/bootstrap/bootstrap-orchestrator.js

@@ -0,0 +1,14 @@
+import { buildDeps } from "../deps.js";
+import { runHealthGate } from "./boot-health-gate.js";
+/**
+ * `jam serve`'s boot path: resolve the project config - reading a file if the
+ * project has one, otherwise falling back to an explicitly supplied key - then
+ * run the local-only "boot" gate. Nothing here writes to the repository, and
+ * no live Jira call happens either, so every `claude` startup stays fast even
+ * when Jira is slow or briefly unreachable.
+ */
+export async function bootstrapForServe(options = {}) {
+    const deps = await buildDeps({ ...options, keyFallback: "required" });
+    const gate = await runHealthGate(deps, "boot");
+    return { deps, gate };
+}

package/dist/bootstrap/host-mcp.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The coding agents JAM knows how to register itself with, for this user
+ * rather than for a repository.
+ *
+ * Both keep user-level MCP registration in a file of their own - Claude Code
+ * in `~/.claude.json`, Codex in `~/.codex/config.toml` - and JAM parses
+ * neither. Editing another program's live state file is how you corrupt it;
+ * each of these ships a command for exactly this, so JAM uses it.
+ */
+export type HostId = "claude-code" | "codex";
+export type HostCommand = {
+    command: string;
+    args: string[];
+};
+export type HostState = {
+    id: HostId;
+    /** Whether the host's own CLI is on PATH and answering. */
+    cliAvailable: boolean;
+    /** Whether it already has a `jam` entry registered for this user. */
+    hasJamEntry: boolean;
+};
+export type HostRunResult = {
+    status: number | null;
+    /** True when the command could not be run at all. */
+    failed: boolean;
+    stdout: string;
+};
+/** Injected by tests. Nothing in this module may reach a real CLI unasked. */
+export type HostRunner = (command: HostCommand) => HostRunResult;
+export declare const defaultHostRunner: HostRunner;
+export declare function hostRegistration(id: HostId): HostCommand | undefined;
+/**
+ * Is `jam` in this listing?
+ *
+ * Both CLIs exit 0 whether or not a server exists, so the exit code says
+ * nothing and the name column is the only signal available. Matched as the
+ * first token of a line so a server called `jam-something`, or the word
+ * appearing in a URL, cannot be mistaken for it.
+ *
+ * ponytail: this reads another program's table. If either changes its listing
+ * format the effect is a redundant registration attempt, not a wrong one -
+ * `mcp add` on an existing entry writes the same launcher line back.
+ */
+export declare function listsJamEntry(stdout: string): boolean;
+/**
+ * Ask each host what it has, and whether it is there at all.
+ *
+ * Read-only by construction: `mcp list` reports. A host that cannot be reached
+ * is recorded as unavailable rather than assumed empty - so planning has
+ * something to refuse rather than something to guess.
+ */
+export declare function detectHosts(run?: HostRunner): HostState[];
+/** How a person would do it by hand, for the hosts JAM could not reach. */
+export declare function describeHostCommand({ command, args }: HostCommand): string;