feat(contract): add @loopover/contract, the single zod source for tool and API schemas

LoopOver declares the same contracts in four unshared places: src/openapi/schemas.ts
(responses, spec-only), src/api/routes.ts (request bodies), src/mcp/server.ts (tool
shapes), and packages/loopover-mcp/bin/loopover-mcp.ts (~85 shapes whose own comments
say they mirror the remote server's). This package is the one place they can live.

It is a zod-only leaf with no node builtins, which is the property that lets the
Worker, both published stdio bins, the miner, and the UI depend on it. Sharing these
through @loopover/engine was rejected once already (#6153): @loopover/mcp resolves the
engine through its published export map, which never surfaced the enums, so importing
them would have meant widening the engine's public API.

The model carries schemas ON each entry rather than in a name-keyed side map, so a
tool without an output schema is a type error rather than a silently dropped lookup,
and projectToolDefinitions is the single point every consumer derives from -- MCP
registration, the OpenAI/Anthropic spec builders that #9183/#9184 need, and the
generated docs to come. Each entry declares auth, locality, and availability;
locality is what makes explicit why LoopOver cannot collapse to one MCP process.

Six pilot contracts, modelled from the engine types the handlers actually return
rather than from the placeholder schemas they advertise today -- the remote server
declared six of get_repo_context's eight fields, and all of predict_gate's blockers,
warnings, and funnel, as bare z.unknown(). Writing them surfaced two divergences that
are modelled honestly as unions and left for #9518 to converge: get_repo_context and
get_pr_reviewability return DIFFERENT payloads from the remote and stdio servers.

Input bounds take the wider of the two servers' historical limits where they
disagreed, since a shared contract may widen an input but never tighten one.

Refs #9517

Author: JSONbored

package-lock.json

@@ -0,0 +1,87 @@
+# @loopover/contract
+
+The single zod source of truth for LoopOver's MCP tool and API contracts.
+
+LoopOver runs three MCP servers — the hosted/self-host remote server (`src/mcp/server.ts`), the
+stdio contributor wrapper (`@loopover/mcp`), and the AMS miner server (`@loopover/miner`) — plus a
+REST API and a UI that all describe the same data. Before this package, each of those declared its
+own zod shapes, and the copies drifted: the stdio server's shapes were hand-mirrored from the remote
+server's (their own comments said so), enum literals were hand-copied out of the engine, and
+responses were consumed as `any`.
+
+This package is the one place those contracts live. **A shape declared here is never restated
+elsewhere.**
+
+## Why a separate package
+
+It is a **leaf**: its only runtime dependency is `zod`, and it imports no node builtins, so it is
+safe in the Cloudflare Workers bundle. That is what lets every surface depend on it — the Worker,
+both published stdio bins, the miner, the control plane, and the UI — without dragging the engine
+along behind it. Sharing these schemas through `@loopover/engine` was considered and rejected:
+`@loopover/mcp` resolves the engine through its *published* export map, which never surfaced the
+enums, so importing them would have meant widening the engine's public API (#6153).
+
+## Layout
+
+| Path | Holds |
+|---|---|
+| `src/tool-definition.ts` | The `ToolContract` model, `defineTool`, and `projectToolDefinitions` — the single projection point |
+| `src/tools/*.ts` | One file per tool family; the contracts themselves |
+| `src/tools/index.ts` | `TOOL_CONTRACTS`, `listToolDefinitions()`, `getToolContract()` |
+| `src/enums.ts` | Shared enum vocabularies (autonomy levels, action classes, …) |
+| `src/shared.ts` | Shapes reused by **three or more** contracts |
+| `src/agent-specs.ts` | OpenAI / Anthropic / agent-index projections |
+
+## Conventions
+
+These are enforced by meta-tests in `test/unit/contract-registry.test.ts`, not just documented.
+
+**Naming.** One file per tool family. Within it, export `<ToolNamePascal>Input` and
+`<ToolNamePascal>Output` schemas plus the `defineTool(...)` contract. Derive types with
+`z.infer<typeof X>` — never hand-write an interface that mirrors a schema.
+
+**Inputs are closed; outputs are open.** Input schemas use `z.object`, which emits
+`additionalProperties: false`. Output schemas use `z.looseObject`, which emits open
+`additionalProperties`. An MCP output schema is a *floor*, not a fence: a server that starts
+returning an extra field must not retroactively invalidate a client validating against the older
+schema.
+
+> **Known gap:** zod's `z.object` *strips* unknown keys at runtime rather than rejecting them, so a
+> typo'd argument is silently dropped even though the advertised JSON Schema says it should be
+> refused. Switching to `z.strictObject` would close the gap but is a wire-visible tightening, so it
+> is a recorded decision on #9518 rather than a drive-by change. A meta-test pins the current
+> behavior so the switch cannot happen by accident.
+
+**Output schemas may be shallower than their REST counterparts, and that is deliberate.** Reusing a
+strict REST response schema for an MCP tool *tightens* the wire contract and is a regression — the
+exact constraint metagraphed hit during its own migration. Reuse a REST schema only when it is
+field-for-field equal to what the tool actually returns. What is never acceptable is a top-level
+`z.unknown()` standing in for a real object.
+
+**Hoist to `shared.ts` at the third consumer, not the second.** Two contracts sharing fields today
+is usually coincidence; coupling them early means a later divergence has to be un-shared under
+pressure.
+
+**Metadata is a declaration, not a hint.** Every contract states its `auth`, `locality`, and
+`availability`, and runtimes enforce them:
+
+- `locality` — where the state physically lives (`remote`, `local-git`, `miner`). This is why
+  LoopOver cannot collapse to one MCP process: `local-git` tools read the caller's uncommitted
+  working tree and `miner` tools read the miner box's stores, neither reachable from a Worker.
+- `availability` — `cloud`, `selfhost`, or `both`. Self-host-only tools depend on capabilities the
+  Workers bundle cannot provide (fs-backed config, a redeploy socket).
+- `auth` — the identity kind `src/auth/security.ts` must authenticate before the tool runs.
+
+**Nothing reads `TOOL_CONTRACTS` directly.** Consumers call `listToolDefinitions()` (optionally
+filtered), so cross-cutting concerns are applied exactly once.
+
+## Adding a tool
+
+1. Add `src/tools/<family>.ts` with input + output schemas and a `defineTool(...)` entry.
+2. Export it from `src/tools/index.ts`.
+3. Register it in whichever runtimes can serve its locality, using `contract.input.shape` /
+   `contract.output.shape` for the MCP SDK.
+4. The contract validator (#9520) requires a smoke call per tool — a tool with no call fails CI.
+
+Generated docs, agent tool specs, and the tool-reference tables pick it up automatically. If you
+find yourself hand-editing a tool table, that table is a bug.

packages/loopover-contract/README.md

@@ -0,0 +1,64 @@
+{
+  "name": "@loopover/contract",
+  "version": "0.1.0",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "description": "Single zod source of truth for LoopOver's MCP tool and API contracts — schemas, tool metadata, and the projections every server and client derives from.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JSONbored/loopover.git",
+    "directory": "packages/loopover-contract"
+  },
+  "homepage": "https://github.com/JSONbored/loopover#readme",
+  "bugs": {
+    "url": "https://github.com/JSONbored/loopover/issues"
+  },
+  "keywords": [
+    "loopover",
+    "mcp",
+    "model-context-protocol",
+    "zod",
+    "openapi",
+    "schema"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./enums": {
+      "types": "./dist/enums.d.ts",
+      "default": "./dist/enums.js"
+    },
+    "./tools": {
+      "types": "./dist/tools/index.d.ts",
+      "default": "./dist/tools/index.js"
+    },
+    "./agent-specs": {
+      "types": "./dist/agent-specs.d.ts",
+      "default": "./dist/agent-specs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=22.0.0 <23.0.0"
+  }
+}

packages/loopover-contract/package.json

@@ -0,0 +1,80 @@
+// Non-MCP projections of the same tool registry (#9517).
+//
+// The hosted maintainer chat (#9183) and hosted AMS chat (#9184) both need a "grounding tool
+// catalog" to hand an LLM. That catalog is this registry in a different envelope -- not a second
+// list to maintain. Each builder is a pure function over already-projected definitions, so a tool
+// added to the contract appears in every surface at once, and a validator can assert the served
+// bytes equal a fresh build.
+import type { JsonSchemaLike, McpToolDefinition } from "./tool-definition.js";
+
+export type OpenAIToolSpec = {
+  type: "function";
+  function: {
+    name: string;
+    description: string;
+    parameters: JsonSchemaLike;
+  };
+};
+
+export type AnthropicToolSpec = {
+  name: string;
+  description: string;
+  input_schema: JsonSchemaLike;
+};
+
+export function buildOpenAIToolSpecs(tools: readonly McpToolDefinition[]): OpenAIToolSpec[] {
+  return tools.map((tool) => ({
+    type: "function",
+    function: {
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.inputSchema,
+    },
+  }));
+}
+
+export function buildAnthropicToolSpecs(tools: readonly McpToolDefinition[]): AnthropicToolSpec[] {
+  return tools.map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    input_schema: tool.inputSchema,
+  }));
+}
+
+export type AgentToolsIndex = {
+  schema_version: number;
+  title: string;
+  description: string;
+  executor: {
+    transport: "mcp-streamable-http";
+    endpoint: string;
+    jsonrpc_method: "tools/call";
+  };
+  specs: {
+    openai: OpenAIToolSpec[];
+    anthropic: AnthropicToolSpec[];
+  };
+  tools: string[];
+};
+
+/** Bumped only when the index's own envelope changes shape -- not when tools are added. */
+export const AGENT_TOOLS_INDEX_SCHEMA_VERSION = 1;
+
+export function buildAgentToolsIndex(tools: readonly McpToolDefinition[], options: { endpoint: string }): AgentToolsIndex {
+  return {
+    schema_version: AGENT_TOOLS_INDEX_SCHEMA_VERSION,
+    title: "LoopOver agent tools",
+    description:
+      "Tool specifications for LoopOver's MCP server, projected for OpenAI- and Anthropic-shaped tool-calling clients. Every tool is executed through the same MCP endpoint via tools/call.",
+    executor: {
+      transport: "mcp-streamable-http",
+      endpoint: options.endpoint,
+      jsonrpc_method: "tools/call",
+    },
+    specs: {
+      openai: buildOpenAIToolSpecs(tools),
+      anthropic: buildAnthropicToolSpecs(tools),
+    },
+    tools: tools.map((tool) => tool.name),
+  };
+}

packages/loopover-contract/src/agent-specs.ts

@@ -0,0 +1,74 @@
+// Shared enum vocabularies (#9517).
+//
+// These existed as hand-copied literals in packages/loopover-mcp/bin/loopover-mcp.ts because that
+// package resolves @loopover/engine through the PUBLISHED package, whose export map never surfaced
+// them -- so importing the canonical list would have meant widening the engine's public API
+// (#6153). The comment on those copies noted the drift it invited "has bitten once already": the
+// stdio list carried "suggest"/"propose" for the whole life of #4620 after the server dropped
+// them, turning a clear client-side error into a confusing 400 from the API.
+//
+// This package is the answer that was missing: a zod-only leaf with no dependencies, so every
+// surface (Worker, both stdio bins, miner, UI) can import the same values without pulling the
+// engine in behind them.
+//
+// SCOPE NOTE: packages/loopover-engine/src/settings/autonomy.ts still declares its own
+// AUTONOMY_LEVELS / AGENT_ACTION_CLASSES, because it is an engine-parity twin of
+// src/settings/autonomy.ts and inverting that pair to import from here is #9518's batch work, not
+// the keystone's. Until then the values below are pinned against the engine's by a meta-test, so
+// the two cannot silently disagree.
+
+/**
+ * Per-action-class autonomy levels. Mirrors the engine's `AUTONOMY_LEVELS`.
+ *
+ * `observe` records what it would have done; `auto_with_approval` stages an action for a human
+ * decision; `auto` acts directly.
+ */
+export const AUTONOMY_LEVELS = ["observe", "auto_with_approval", "auto"] as const;
+export type AutonomyLevel = (typeof AUTONOMY_LEVELS)[number];
+
+/**
+ * The action classes an operator may configure autonomy for.
+ *
+ * Deliberately NOT the engine's full `AGENT_ACTION_CLASSES` -- it is the operator-settable subset
+ * the maintain surface exposes, matching `MAINTAIN_AUTONOMY_ACTION_CLASSES` in src/mcp/server.ts.
+ * Do not "sync" this to the engine's list; the difference is the point.
+ */
+export const MAINTAIN_ACTION_CLASSES = ["review", "request_changes", "approve", "merge", "close", "label"] as const;
+export type MaintainActionClass = (typeof MAINTAIN_ACTION_CLASSES)[number];
+
+/**
+ * Action classes accepted when proposing an action into the approval queue (#6744).
+ *
+ * Derived rather than restated: it is exactly the operator-settable set plus `review_state_label`,
+ * and expressing that as code means the two can never drift apart the way three independent
+ * literal lists did.
+ */
+export const PROPOSE_ACTION_CLASSES = [...MAINTAIN_ACTION_CLASSES, "review_state_label"] as const;
+export type ProposeActionClass = (typeof PROPOSE_ACTION_CLASSES)[number];
+
+/** Test frameworks the boundary-test and test-evidence surfaces recognize by name. */
+export const TEST_FRAMEWORKS = ["vitest", "jest", "pytest", "go-test", "rspec", "cargo-test"] as const;
+export type TestFramework = (typeof TEST_FRAMEWORKS)[number];
+
+/** Lifecycle states of a plan step in the stateless plan-DAG tools. */
+export const PLAN_STEP_STATUSES = ["pending", "in_progress", "completed", "skipped", "failed"] as const;
+export type PlanStepStatus = (typeof PLAN_STEP_STATUSES)[number];
+
+/** Verdicts the pre-start feasibility surfaces return. */
+export const FEASIBILITY_VERDICTS = ["go", "raise", "avoid"] as const;
+export type FeasibilityVerdict = (typeof FEASIBILITY_VERDICTS)[number];
+
+/**
+ * Scope selector for WRITING the self-hosted private config: the deployment-wide default layer, or
+ * one repository's override layer. Only real files are writable.
+ */
+export const CONFIG_ADMIN_WRITE_SCOPES = ["global", "repo"] as const;
+export type ConfigAdminWriteScope = (typeof CONFIG_ADMIN_WRITE_SCOPES)[number];
+
+/**
+ * Scope selector for READING it. A superset of the write scopes: `effective` is the merged view
+ * (shared base + global default + per-repo override) that no single file corresponds to, which is
+ * exactly why it can be read but never written.
+ */
+export const CONFIG_ADMIN_READ_SCOPES = ["effective", ...CONFIG_ADMIN_WRITE_SCOPES] as const;
+export type ConfigAdminReadScope = (typeof CONFIG_ADMIN_READ_SCOPES)[number];