harness-dispatch 0.4.0

package/dist/mcp/tools.js

@@ -0,0 +1,658 @@
+/**
+ * MCP tool registry for harness-dispatch.
+ *
+ * The public MCP surface is three tools, each doing exactly one thing:
+ * `dispatch` starts routed work (single or fanout) and only ever starts —
+ * `job_status` checks or lists it, `usage` reads route/quota state. Every
+ * dispatch is job-backed from the first moment — dispatch races an inline
+ * grace window against the background run, so a fast task returns its full
+ * result in-call and a slow one degrades to a pollable jobId with NOTHING
+ * lost to a timeout; job_status is how that jobId gets checked on later.
+ * Status is also exposed as resources so clients can inspect state without
+ * a tool call.
+ */
+import { z } from "zod";
+import { setTimeout as delay } from "node:timers/promises";
+import { withMcpToolSpan } from "../observability/spans.js";
+import { evaluateRoutePolicy } from "../route-policy.js";
+import { getAsyncJob, listAsyncJobs, startAsyncJobTracked } from "../jobs.js";
+import { isIsolatedWorkspacePolicy } from "../workspaces.js";
+import { buildStatus, buildUsage } from "../status.js";
+import { endpointUrl } from "../dispatchers/openai-compatible.js";
+const taskTypeSchema = z.enum(["execute", "plan", "review", "local"]);
+const safetyProfileSchema = z.enum(["read_only", "workspace_edit", "full_auto"]);
+const workspacePolicySchema = z.enum(["shared", "shared_locked", "copy", "git_worktree"]);
+const routePolicySchema = z.enum(["standard", "local_only", "approval_required", "blocked"]);
+const publicHintsSchema = z
+    .object({
+    model: z
+        .string()
+        .optional()
+        .describe("Preferred route or model name (e.g. a route id like 'codex' or a model like " +
+        "'gpt-5.6-sol'). Routes that statically declare this model get a scoring " +
+        "boost; the model is ALWAYS passed to the harness as an override either way, " +
+        "even on a route that doesn't recognize it — NOT validated, so an unfamiliar " +
+        "or misspelled name can still fail at dispatch time if the harness doesn't " +
+        "support it. Check the response's routing.modelHintMatched: true means the " +
+        "picked route actually declares this model; false means it was forwarded " +
+        "blind and you should treat the result with more suspicion (or check why). " +
+        "Call the `usage` tool first to see valid route ids, their default models, " +
+        "and a modelHint per route pointing to where that harness's real model " +
+        "catalog is documented (or how to list it) — use it to pick correctly up " +
+        "front or self-correct after an unfamiliar-model failure. In fanout mode " +
+        "this field is ignored entirely — use `models` (top-level, not under " +
+        "hints) to select fanout candidates instead."),
+    taskType: taskTypeSchema
+        .optional()
+        .describe("Kind of work: 'execute' (write/modify code, run commands), 'plan' " +
+        "(architecture/design, no edits), 'review' (critique code, no edits), 'local' " +
+        "(trivial/mechanical — prefers free local endpoints). ALWAYS set this: when " +
+        "omitted, per-task capability weighting and model escalation are disabled and " +
+        "routing quality degrades."),
+    preferLargeContext: z
+        .boolean()
+        .optional()
+        .describe("Boost routes with very large context windows (for huge-codebase reads)."),
+    safetyProfile: safetyProfileSchema
+        .optional()
+        .describe("Maximum permission the routed harness may use: 'read_only' (inspect only — use " +
+        "for review/plan), 'workspace_edit' (default; may edit files in workingDir), " +
+        "'full_auto' (unrestricted shell — only when explicitly needed). Routes that " +
+        "cannot honor the requested profile are skipped."),
+    workspacePolicy: workspacePolicySchema.optional().describe("Workspace execution policy."),
+    routePolicy: routePolicySchema
+        .optional()
+        .describe("Operational routing policy: 'standard' (default), 'local_only' (never leave the " +
+        "machine), 'approval_required' (BLOCKS non-local routes — it is a restriction, " +
+        "not an approval grant), 'blocked' (dry-run: block everything)."),
+    timeoutMs: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Override the background run's hard ceiling (milliseconds). Every dispatch " +
+        "runs as a background job with a generous 60-minute default meant to catch a " +
+        "genuinely hung process, not to cap a slow-but-healthy run — raise this for " +
+        "a task you expect to run past an hour. This changes when the harness itself " +
+        "gives up, not how long the inline grace window waits (that's `graceSeconds`)."),
+})
+    .describe("Public routing hints.");
+const workingDirDescription = "Absolute path to the project the task is about. EFFECTIVELY REQUIRED: when omitted, " +
+    "the task runs in the router server's own working directory — almost never the " +
+    "project you mean. Always pass the caller's project root.";
+/** Inline grace window: how long `dispatch` waits for the background run before returning a pollable jobId instead of the full result. */
+const DEFAULT_GRACE_SECONDS = 25;
+const dispatchInputShape = {
+    prompt: z
+        .string()
+        .describe("The coding task or question. Every dispatch starts as a background job " +
+        "immediately; if it finishes within the grace window you get the full result " +
+        "inline, otherwise you get a jobId — check on it with the `job_status` tool. " +
+        "Either way nothing is ever lost to a timeout."),
+    mode: z
+        .enum(["single", "fanout"])
+        .optional()
+        .default("single")
+        .describe("'single' routes to the one best-fit harness. 'fanout' runs the prompt on " +
+        "MULTIPLE routes in parallel for independent perspectives — without `models` it " +
+        "hits every eligible route and consumes quota on each; prefer passing an " +
+        "explicit `models` list. Write-capable fanout requires workspacePolicy 'copy' " +
+        "or 'git_worktree'. Fanout results that outlive the grace window each return " +
+        "their own jobId to poll individually."),
+    files: z
+        .array(z.string())
+        .optional()
+        .describe("Absolute file paths to snapshot and include as context."),
+    workingDir: z.string().optional().describe(workingDirDescription),
+    workspacePolicy: workspacePolicySchema.optional().describe("Workspace execution policy."),
+    hints: publicHintsSchema.optional(),
+    models: z
+        .array(z.string())
+        .optional()
+        .describe("Route ids or model names to fan out to (fanout mode only). This is the ONLY " +
+        "field that narrows which routes fanout hits — `hints.model` is ignored " +
+        "entirely in fanout mode (not used for selection, not forwarded to any " +
+        "dispatch); it only does anything in single mode. Get valid ids from the " +
+        "`usage` tool."),
+    service: z
+        .string()
+        .optional()
+        .describe("Optional explicit route id to run (e.g. 'codex', 'cursor', 'local_inference' — " +
+        "see the `usage` tool for valid ids). Omit to let the router pick. Single " +
+        "mode only — incompatible with mode='fanout' (use `models` there)."),
+    graceSeconds: z
+        .number()
+        .int()
+        .min(0)
+        .max(600)
+        .optional()
+        .describe(`Seconds to wait for the run inline before returning a pollable jobId (default ` +
+        `${DEFAULT_GRACE_SECONDS}). 0 returns the jobId immediately (pure async). ` +
+        `Raising it past your MCP client's own request timeout buys nothing — the run ` +
+        `continues in the background either way and the result stays collectible via ` +
+        `\`job_status\`, so a client timeout on this call loses nothing but the inline reply.`),
+};
+const jobStatusInputShape = {
+    jobId: z
+        .string()
+        .optional()
+        .describe("Check a previously started dispatch: returns partialOutput while running and " +
+        "the full result once completed or failed. Omit to list every known background " +
+        "dispatch instead."),
+};
+export const TOOL_NAMES = ["dispatch", "job_status", "usage"];
+function jsonText(value) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+    };
+}
+function toHints(h) {
+    if (!h)
+        return {};
+    const out = {};
+    if (h.model !== undefined)
+        out.model = h.model;
+    if (h.taskType !== undefined)
+        out.taskType = h.taskType;
+    if (h.preferLargeContext !== undefined)
+        out.preferLargeContext = h.preferLargeContext;
+    if (h.safetyProfile !== undefined)
+        out.safetyProfile = h.safetyProfile;
+    if (h.workspacePolicy !== undefined)
+        out.workspacePolicy = h.workspacePolicy;
+    if (h.routePolicy !== undefined)
+        out.routePolicy = h.routePolicy;
+    if (h.timeoutMs !== undefined)
+        out.timeoutMs = h.timeoutMs;
+    return out;
+}
+function workspacePolicyFromInput(input) {
+    return input.workspacePolicy ?? input.hints?.workspacePolicy;
+}
+async function ensureFreshConfig(reloader) {
+    if (reloader)
+        await reloader.maybeReload();
+}
+async function emitProgress(extra, progressToken, counter, event, route) {
+    if (!extra?.sendNotification || progressToken === undefined)
+        return;
+    counter.value += 1;
+    try {
+        await extra.sendNotification({
+            method: "notifications/progress",
+            params: {
+                progressToken,
+                progress: counter.value,
+                message: summarizeEvent(event, route),
+                _meta: { event, route },
+            },
+        });
+    }
+    catch {
+        // Best effort only. A progress delivery failure should not fail the tool.
+    }
+}
+function summarizeEvent(event, route) {
+    const prefix = route ? `[${route}] ` : "";
+    switch (event.type) {
+        case "stdout":
+            return `${prefix}stdout: ${truncate(event.chunk, 60)}`;
+        case "stderr":
+            return `${prefix}stderr: ${truncate(event.chunk, 60)}`;
+        case "tool_use":
+            return `${prefix}tool_use: ${event.name}`;
+        case "thinking":
+            return `${prefix}thinking: ${truncate(event.chunk, 60)}`;
+        case "completion":
+            return `${prefix}completion: ${event.result.success ? "ok" : "fail"}`;
+        case "error":
+            return `${prefix}error: ${event.error}`;
+    }
+}
+function truncate(s, n) {
+    return s.length <= n ? s : `${s.slice(0, n - 3)}...`;
+}
+function routeResponse(result, decision, workingDirWarningMessage) {
+    const response = {
+        success: result.success,
+        output: result.output,
+        route: result.service,
+    };
+    if (workingDirWarningMessage !== undefined)
+        response.warning = workingDirWarningMessage;
+    if (result.error !== undefined)
+        response.error = result.error;
+    if (result.durationMs !== undefined)
+        response.durationMs = result.durationMs;
+    if (result.tokensUsed !== undefined)
+        response.tokensUsed = result.tokensUsed;
+    if (result.skippedRoutes !== undefined)
+        response.skippedRoutes = result.skippedRoutes;
+    if (result.workspace !== undefined)
+        response.workspace = result.workspace;
+    if (decision) {
+        if (decision.model !== undefined)
+            response.model = decision.model;
+        response.routing = {
+            tier: decision.tier,
+            quotaScore: decision.quotaScore,
+            qualityScore: decision.qualityScore,
+            cliCapability: decision.cliCapability,
+            capabilityScore: decision.capabilityScore,
+            taskType: decision.taskType,
+            finalScore: decision.finalScore,
+            reason: decision.reason,
+        };
+        if (decision.elo !== undefined)
+            response.routing.elo = decision.elo;
+        if (decision.modelHintMatched !== undefined) {
+            response.routing.modelHintMatched = decision.modelHintMatched;
+        }
+        if (decision.skippedRoutes !== undefined && decision.skippedRoutes.length > 0) {
+            response.skippedRoutes = decision.skippedRoutes;
+        }
+    }
+    return response;
+}
+/**
+ * Wait up to `graceMs` for the background run, then report disk truth. The
+ * race only decides when we STOP waiting — completion state is always read
+ * back from the job artifacts, so the inline path and a later poll can
+ * never disagree about the same run. The grace timer is unref'd so a
+ * short-lived process (tests, one-shot CLI) never hangs on it.
+ */
+async function waitGrace(completion, graceMs) {
+    if (graceMs <= 0)
+        return;
+    await Promise.race([completion, delay(graceMs, undefined, { ref: false })]);
+}
+function jobCompleted(job) {
+    return (job.result !== undefined ||
+        job.status.status === "completed" ||
+        job.status.status === "failed" ||
+        // Orphaned (owner process died mid-run) is terminal: it will never
+        // complete, so callers must stop polling and re-dispatch.
+        job.status.status === "orphaned");
+}
+/**
+ * Build the RouteResponse view of a finished job. Covers the crash path
+ * too: a runJob failure writes a final "failed" status but no result.json,
+ * which must still surface as a completed-and-failed dispatch, not as
+ * something to keep polling.
+ */
+function jobRouteResponse(job) {
+    if (job.result) {
+        return routeResponse(job.result.result, job.result.decision, job.status.warning);
+    }
+    const response = {
+        success: false,
+        output: "",
+        route: job.status.route ?? job.status.service ?? "none",
+    };
+    if (job.status.error !== undefined)
+        response.error = job.status.error;
+    if (job.status.warning !== undefined)
+        response.warning = job.status.warning;
+    if (job.status.durationMs !== undefined)
+        response.durationMs = job.status.durationMs;
+    return response;
+}
+/** Progress forwarder for the inline grace window — goes quiet once the MCP call has returned. */
+function makeProgressTap(extra, live, counter, route) {
+    const progressToken = extra?._meta?.progressToken;
+    if (progressToken === undefined || !extra?.sendNotification)
+        return undefined;
+    return (event) => {
+        if (!live.value)
+            return;
+        void emitProgress(extra, progressToken, counter, event, route);
+    };
+}
+async function startSingle(deps, input, extra) {
+    await ensureFreshConfig(deps.reloader);
+    const hints = toHints(input.hints);
+    const workspacePolicy = workspacePolicyFromInput(input);
+    if (workspacePolicy !== undefined)
+        hints.workspacePolicy = workspacePolicy;
+    const live = { value: true };
+    const counter = { value: 0 };
+    const onEvent = makeProgressTap(extra, live, counter, input.service);
+    const { status, completion } = await startAsyncJobTracked({ holder: deps.holder }, {
+        prompt: input.prompt,
+        files: input.files ?? [],
+        ...(input.workingDir !== undefined ? { workingDir: input.workingDir } : {}),
+        hints,
+        ...(input.workspacePolicy !== undefined ? { workspacePolicy: input.workspacePolicy } : {}),
+        ...(input.service !== undefined ? { service: input.service } : {}),
+        ...(onEvent !== undefined ? { onEvent } : {}),
+    });
+    const graceMs = (input.graceSeconds ?? DEFAULT_GRACE_SECONDS) * 1000;
+    await waitGrace(completion, graceMs);
+    live.value = false;
+    const job = await getAsyncJob(status.jobId);
+    if (jobCompleted(job)) {
+        return { mode: "single", jobId: status.jobId, completed: true, ...jobRouteResponse(job) };
+    }
+    const pending = {
+        mode: "single",
+        jobId: status.jobId,
+        completed: false,
+    };
+    if (job.partialOutput !== undefined)
+        pending.partialOutput = job.partialOutput;
+    if (job.status.nextPollSeconds !== undefined)
+        pending.nextPollSeconds = job.status.nextPollSeconds;
+    if (job.status.instructions !== undefined)
+        pending.instructions = job.status.instructions;
+    if (job.status.warning !== undefined)
+        pending.warning = job.status.warning;
+    return pending;
+}
+function matchesRequestedModel(routeName, svc, requested) {
+    if (requested.size === 0)
+        return true;
+    const lower = new Set([...requested].map((s) => s.toLowerCase()));
+    return [routeName, svc.model, svc.leaderboardModel]
+        .filter((v) => typeof v === "string" && v.length > 0)
+        .some((v) => lower.has(v.toLowerCase()));
+}
+async function startFanout(deps, input, extra) {
+    await ensureFreshConfig(deps.reloader);
+    const state = deps.holder.state;
+    const hints = toHints(input.hints);
+    const workspacePolicy = workspacePolicyFromInput(input);
+    if (workspacePolicy !== undefined)
+        hints.workspacePolicy = workspacePolicy;
+    const fanoutSafetyProfile = hints.safetyProfile ?? "read_only";
+    if (fanoutSafetyProfile !== "read_only" &&
+        (hints.workspacePolicy === undefined || !isIsolatedWorkspacePolicy(hints.workspacePolicy))) {
+        return {
+            mode: "fanout",
+            completed: true,
+            results: [],
+            skippedRoutes: [
+                {
+                    route: "fanout",
+                    code: "workspace_isolation_required",
+                    message: "write-capable fanout requires workspacePolicy=copy or workspacePolicy=git_worktree; use read_only fanout or run single-route workspace_edit",
+                },
+            ],
+        };
+    }
+    hints.safetyProfile = fanoutSafetyProfile;
+    // Contract: hints.model is ignored entirely in fanout mode — `models` is
+    // the only selection mechanism. The job runner would forward it to every
+    // arm otherwise.
+    delete hints.model;
+    const taskType = hints.taskType ?? "plan";
+    const requested = new Set(input.models ?? []);
+    const counter = { value: 0 };
+    const skippedRoutes = [];
+    const candidates = [];
+    for (const [routeName, svc] of Object.entries(state.config.services)) {
+        if (!matchesRequestedModel(routeName, svc, requested))
+            continue;
+        const breaker = state.router.getBreaker(routeName);
+        const dispatcher = state.dispatchers[routeName];
+        const policy = evaluateRoutePolicy(routeName, svc, {
+            ...(dispatcher !== undefined ? { dispatcher } : {}),
+            circuitBroken: Boolean(breaker?.isTripped),
+            ...(hints.safetyProfile !== undefined ? { requestedSafetyProfile: hints.safetyProfile } : {}),
+            ...(hints.routePolicy !== undefined ? { routePolicy: hints.routePolicy } : {}),
+        });
+        if (policy.skipped)
+            skippedRoutes.push(policy.skipped);
+        if (policy.blocked)
+            continue;
+        candidates.push(routeName);
+    }
+    const prompt = input.prompt;
+    const files = input.files ?? [];
+    const live = { value: true };
+    // Start every candidate as its own background job up front, then wait ONE
+    // shared grace window for all of them — a route that beats the deadline
+    // reports inline, the rest hand back their jobIds. Per-route job dirs also
+    // give each fanout arm its own artifacts, which the blocking version never
+    // had.
+    const started = await Promise.all(candidates.map(async (routeName) => {
+        const svc = state.config.services[routeName];
+        const cap = svc.capabilities[taskType] ?? 1.0;
+        const quality = await state.leaderboard.getQualityScore(svc.leaderboardModel, svc.thinkingLevel);
+        const onEvent = makeProgressTap(extra, live, counter, routeName);
+        const job = await startAsyncJobTracked({ holder: deps.holder }, {
+            prompt,
+            files,
+            ...(input.workingDir !== undefined ? { workingDir: input.workingDir } : {}),
+            hints,
+            service: routeName,
+            ...(onEvent !== undefined ? { onEvent } : {}),
+        });
+        return { routeName, cap, quality, job };
+    }));
+    const graceMs = (input.graceSeconds ?? DEFAULT_GRACE_SECONDS) * 1000;
+    await waitGrace(Promise.all(started.map((s) => s.job.completion)).then(() => undefined), graceMs);
+    live.value = false;
+    let warning;
+    const results = await Promise.all(started.map(async ({ routeName, cap, quality, job }) => {
+        const current = await getAsyncJob(job.status.jobId);
+        if (current.status.warning !== undefined)
+            warning = current.status.warning;
+        const item = {
+            route: routeName,
+            jobId: job.status.jobId,
+            completed: jobCompleted(current),
+            capabilityScore: cap,
+            qualityScore: quality.qualityScore,
+        };
+        if (quality.elo !== null)
+            item.elo = quality.elo;
+        if (item.completed) {
+            const response = jobRouteResponse(current);
+            item.success = response.success;
+            item.output = response.output;
+            if (response.error !== undefined)
+                item.error = response.error;
+            if (response.durationMs !== undefined)
+                item.durationMs = response.durationMs;
+            if (response.workspace !== undefined)
+                item.workspace = response.workspace;
+        }
+        else if (current.partialOutput !== undefined) {
+            item.partialOutput = current.partialOutput;
+        }
+        return item;
+    }));
+    results.sort((a, b) => {
+        if (a.completed !== b.completed)
+            return a.completed ? -1 : 1;
+        if (a.success !== b.success)
+            return a.success ? -1 : 1;
+        return b.capabilityScore - a.capabilityScore;
+    });
+    const response = {
+        mode: "fanout",
+        completed: results.every((r) => r.completed),
+        results,
+    };
+    if (skippedRoutes.length > 0)
+        response.skippedRoutes = skippedRoutes;
+    if (warning !== undefined)
+        response.warning = warning;
+    return response;
+}
+async function pollDispatch(jobId) {
+    const job = await getAsyncJob(jobId);
+    const completed = jobCompleted(job);
+    const response = { jobId, completed, status: job.status };
+    if (completed) {
+        response.result = jobRouteResponse(job);
+    }
+    else if (job.partialOutput !== undefined) {
+        response.partialOutput = job.partialOutput;
+    }
+    return response;
+}
+export async function handleDispatch(deps, input, extra) {
+    return withMcpToolSpan({ "tool.name": "dispatch" }, async () => {
+        if ((input.mode ?? "single") === "fanout") {
+            if (input.service !== undefined) {
+                throw new Error("dispatch: `service` forces a single route and is incompatible with mode='fanout' — use `models` to select fanout routes");
+            }
+            return startFanout(deps, input, extra);
+        }
+        return startSingle(deps, input, extra);
+    });
+}
+/** Most-recent jobs returned by the list view. */
+const LIST_LIMIT = 20;
+export async function handleJobStatus(input) {
+    return withMcpToolSpan({ "tool.name": "job_status" }, async () => {
+        if (input.jobId !== undefined)
+            return pollDispatch(input.jobId);
+        // Compact list: full detail (jobDir, warnings, instructions, errors)
+        // lives behind a per-job check — dumping it for every job ever was a
+        // several-KB token tax on each list call.
+        const all = await listAsyncJobs();
+        const jobs = all.slice(0, LIST_LIMIT).map((j) => ({
+            jobId: j.jobId,
+            status: j.status,
+            createdAt: j.createdAt,
+            ...(j.route !== undefined ? { route: j.route } : {}),
+            ...(j.service !== undefined && j.service !== j.route ? { service: j.service } : {}),
+            ...(j.success !== undefined ? { success: j.success } : {}),
+            ...(j.durationMs !== undefined ? { durationMs: j.durationMs } : {}),
+        }));
+        return {
+            jobs,
+            ...(all.length > LIST_LIMIT ? { omitted: all.length - LIST_LIMIT } : {}),
+        };
+    });
+}
+const usageInputShape = {
+    listModels: z
+        .string()
+        .optional()
+        .describe("Route id of an OpenAI-compatible endpoint (e.g. an entry from `endpoints:` " +
+        "like nvidia_nim or ollama). If the route declares a `models:` list in " +
+        "config, that operator-curated list is returned as-is — declaring it is " +
+        "how you override live discovery (e.g. to pin specific ids, or the " +
+        "endpoint's /models listing is noisy/untrustworthy). Otherwise fetches the " +
+        "endpoint's live GET /models catalog server-side — the API key never " +
+        "leaves the router. Either way, results come back under `liveModels`. CLI " +
+        "harness routes don't support this; use their modelHint instead."),
+};
+/**
+ * Model catalog for one OpenAI-compatible route. An operator-declared
+ * `models:` list is an override, not a supplement — if present it's
+ * returned as-is with NO network call, so a curated/pinned list stays
+ * authoritative even if the endpoint's live /models changes or is noisy.
+ * `source` distinguishes the two so a caller can tell which happened.
+ */
+async function fetchEndpointModels(route, svc) {
+    if (!svc) {
+        return { route, error: `unknown route '${route}' — call usage without listModels to see valid route ids` };
+    }
+    if (svc.models && svc.models.length > 0) {
+        return { route, models: svc.models, source: "declared" };
+    }
+    if (svc.type !== "openai_compatible" || !svc.baseUrl) {
+        return {
+            route,
+            error: "listModels only works for openai_compatible endpoint routes (or any route " +
+                "with a declared models: list) — CLI harnesses publish their catalog via " +
+                "this route's modelHint instead",
+        };
+    }
+    const url = endpointUrl(svc.baseUrl, "/models");
+    const headers = {};
+    if (svc.apiKey)
+        headers["Authorization"] = `Bearer ${svc.apiKey}`;
+    try {
+        const res = await fetch(url, { headers, signal: AbortSignal.timeout(10_000) });
+        if (!res.ok) {
+            return { route, error: `GET ${url} -> HTTP ${res.status}` };
+        }
+        const body = (await res.json());
+        const models = (body.data ?? [])
+            .map((m) => m.id)
+            .filter((id) => typeof id === "string");
+        return { route, models, source: "live" };
+    }
+    catch (err) {
+        return { route, error: `GET ${url} failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+async function handleUsage(deps, args = {}) {
+    await ensureFreshConfig(deps.reloader);
+    const state = deps.holder.state;
+    const status = await buildStatus(state.config, state.dispatchers, state.quota, state.router, state.leaderboard);
+    const usage = buildUsage(status);
+    if (args.listModels) {
+        const svc = state.config.services[args.listModels];
+        return { ...usage, liveModels: await fetchEndpointModels(args.listModels, svc) };
+    }
+    return usage;
+}
+export function registerTools(server, deps) {
+    server.registerTool("dispatch", {
+        title: "Dispatch a coding task",
+        description: "Delegate a bounded coding task (implement, fix, review, plan, or investigate — " +
+            "not general Q&A) to the best-fit harness (Claude Code, Codex, Cursor, " +
+            "Antigravity, or a configured endpoint), or fan out to several for independent " +
+            "opinions. Always starts new work — every dispatch runs as a background job " +
+            "from the first moment: if it finishes within the grace window (default " +
+            `${DEFAULT_GRACE_SECONDS}s, see graceSeconds) you get the full result inline ` +
+            "(completed: true); otherwise you get completed: false plus a jobId — check on " +
+            "it with the `job_status` tool, which returns partialOutput while it runs and " +
+            "the full result once done. NOTHING is ever lost to a timeout, including this " +
+            "MCP call's own: the run executes in a detached process that survives even a " +
+            "server restart, and results " +
+            "persist on disk — if THIS call times out client-side, the jobId was lost with " +
+            "the reply, so call `job_status` with no arguments and pick the newest running " +
+            "entry (it is yours). Keep graceSeconds under your MCP client's own request " +
+            "timeout, or skip the inline wait entirely with graceSeconds: 0. Always pass " +
+            "`workingDir` (the caller's project root) and `hints.taskType`.",
+        inputSchema: dispatchInputShape,
+    }, async (args, extra) => jsonText(await handleDispatch(deps, args, extra)));
+    server.registerTool("job_status", {
+        title: "Check or list background dispatches",
+        description: "Check on work started by `dispatch`. Pass the `jobId` it returned: while " +
+            "running you get `partialOutput` (a live tail), and once `completed` is true " +
+            "you get the full `result` — same shape as an inline dispatch reply. Omit " +
+            "`jobId` to list recent background dispatches instead (compact, newest first). "
+            + "Nothing is lost by " +
+            "checking late; results persist on disk.",
+        inputSchema: jobStatusInputShape,
+    }, async (args) => jsonText(await handleJobStatus(args)));
+    server.registerTool("usage", {
+        title: "Check current usage",
+        description: "Per-route call counts (success/failure), quota remaining, billing kind, and " +
+            "circuit-breaker state for this session. Call this before using an unfamiliar " +
+            "`hints.model`/`service`/`models` value to see valid route ids and their " +
+            "current models — those fields are not validated and silently ignore unknown names. " +
+            "Each route also includes modelHint (where that harness's real model catalog " +
+            "is documented or listed live) and, when the operator declared one, models: " +
+            "a list of known-good ids. For OpenAI-compatible endpoint routes, pass " +
+            "listModels: <route id> to fetch the endpoint's live GET /models catalog " +
+            "server-side and get the real ids back under liveModels — use these to pick " +
+            "a real model up front or self-correct after a dispatch failure caused by an " +
+            "unsupported model name.",
+        inputSchema: usageInputShape,
+    }, async (args) => jsonText(await handleUsage(deps, args)));
+}
+export async function invokeTool(name, args, deps) {
+    if (name === "dispatch") {
+        const parsed = z.object(dispatchInputShape).parse(args);
+        return { kind: "json", data: await handleDispatch(deps, parsed) };
+    }
+    if (name === "job_status") {
+        const parsed = z.object(jobStatusInputShape).parse(args ?? {});
+        return { kind: "json", data: await handleJobStatus(parsed) };
+    }
+    if (name === "usage") {
+        const parsed = z.object(usageInputShape).parse(args ?? {});
+        return { kind: "json", data: await handleUsage(deps, parsed) };
+    }
+    throw new Error(`Unknown tool: ${name} (valid: ${TOOL_NAMES.join(", ")})`);
+}
+//# sourceMappingURL=tools.js.map