@jr2/orchestrator 0.6.0 → 0.7.0

package/src/config.ts

@@ -20,8 +20,11 @@ import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { z } from "zod";
+import type { Hook } from "./hook-kinds/index.ts";
+import { hookParts, isHook, kindsById } from "./hook-kinds/door.ts";
 import { repoIdentity } from "./repo-identity.ts";
 import { assertSize, type Size } from "./size.ts";
+import { periodMs } from "./duration.ts";
 
 // ------------------------------------------------------------------------------------------------
 // `git.credentials` (ADR-0051): how the cluster authenticates to a Repo, and the fence.
@@ -360,6 +363,68 @@ export type SecretEntry = {
   paths?: readonly string[];
 };
 
+// One MCP server of the Instance (ADR-0079), by the author's name. A url and a secret are facts of
+// the Instance, never of an Agent's definition, so a packaged Machine names a server and the
+// Instance declares it. The name is the author's: two servers of one service with two secrets are
+// two names.
+/**
+ * A remote MCP server, which the Harness reaches over Streamable HTTP. An Agent that names it in its
+ * `mcp` list gets the tools that its `tools` allowlist names.
+ *
+ * A server with a `secret` needs an `https://` url, because the Custodian puts the value on TLS
+ * only: `mcp.<name>.url must be an https:// URL`. A server with no secret can use `http://`. The
+ * Harness sends `Authorization: Bearer <Stand-in>`, and the Custodian of each pod whose Agents name
+ * the server puts the value in its place. A `secret` that the `secrets` list does not hold is
+ * refused when the config loads: `<file> at mcp.<name>.secret: "<NAME>" is not an entry of secrets`.
+ * Past `timeout`, the Harness cancels the call, and the model reads jr2's text.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from "@jr2/orchestrator";
+ *
+ * export default defineConfig({
+ *   secrets: [{ name: "SLACK_ACME_TOKEN", value: process.env.SLACK_ACME_TOKEN }],
+ *   mcp: { "slack-acme": { url: "https://mcp.slack.example/mcp", secret: "SLACK_ACME_TOKEN" } },
+ * });
+ * ```
+ */
+export type McpRemoteServer = {
+  /** Its Streamable HTTP endpoint: `https://` when it has a `secret`. */
+  url: string;
+  /** A name of the `secrets` list: its bearer token. With no `hosts`, that entry is bound to the
+   * url's host, in `authorization`. Default: none. */
+  secret?: string;
+  /** How long one call can run, such as `"90s"`. Default `"60s"`. */
+  timeout?: `${number}s` | `${number}m` | `${number}h`;
+};
+
+/**
+ * A stdio MCP server: a program of the Sandbox Image that the Harness starts for each Agent
+ * conversation, through jr2's spawner, inside the Agent's confinement. It is Workspace code: its env
+ * holds only the Stand-ins that the `workspace()` grants, so it has no `secret` of its own. A
+ * `"none"` Agent cannot name one, because its Turns run on the Instance Harness, where no Workspace
+ * code runs.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from "@jr2/orchestrator";
+ *
+ * export default defineConfig({ mcp: { notes: { command: "notes-mcp", args: ["--root", "/work"] } } });
+ * ```
+ */
+export type McpStdioServer = {
+  /** A program of the Sandbox Image. */
+  command: string;
+  /** Its arguments. */
+  args?: readonly string[];
+  /** How long one call can run, such as `"90s"`. Default `"60s"`. */
+  timeout?: `${number}s` | `${number}m` | `${number}h`;
+};
+
+/** One MCP server of the Instance: a {@link McpRemoteServer} (`url`) or a {@link McpStdioServer}
+ * (`command`). */
+export type McpServer = McpRemoteServer | McpStdioServer;
+
 // The agent-runtime section (ADR-0018): what the stock Harness image consumes alongside the Agent
 // definition each Turn hands it (ADR-0049). Moved out of `sandbox` deliberately — `sandbox` is pod
 // transport (it still CARRIES this env to the Harness container), but model concerns are Harness
@@ -489,6 +554,184 @@ export type PriorityClasses = {
   sandbox?: string;
 };
 
+/**
+ * The Workflows that one scope of a Caller opens (ADR-0078): `"all"` for every Workflow, or a list
+ * of Workflow names. A Chart wrapper's name in the list also opens each named Chart of that wrapper
+ * (`plan` opens `plan/weekly`), because a named Chart runs its wrapper's Machine. A named Chart's
+ * own name (`plan/weekly`) opens that Chart alone.
+ */
+export type ScopeGrant = "all" | readonly string[];
+
+/**
+ * What a Caller may do: five scopes, each one for the Workflows that it names (ADR-0078). A scope
+ * that is absent opens nothing. Which scope opens which route is in the HTTP API Reference.
+ *
+ * A Caller's scope does not limit what its run dispatches: a Caller with `start` on `triage` starts
+ * a run whose Machine can dispatch `deploy`. The Machine is the author's, and it is the boundary of
+ * what its run does.
+ */
+export type Scopes = {
+  /** Start a run. */
+  start?: ScopeGrant;
+  /** Answer a Gate, and read a run's open Gates without its context. A list item
+   * `{ workflow, gates }` opens only the Gates that it names, by invoke id (see {@link GateGrant}). */
+  answer?: AnswerGrant;
+  /** Cancel a run. */
+  cancel?: ScopeGrant;
+  /** Read a run's state: its status, its context and its feed. */
+  read?: ScopeGrant;
+  /** Send a Steering message to an Agent of a run. */
+  steer?: ScopeGrant;
+};
+
+/**
+ * The Gates that the `answer` scope opens (ADR-0078): `"all"`, or a list in which each item is a
+ * Workflow name, which opens every Gate of that Workflow, or a {@link GateGrant}, which opens only
+ * the Gates that it names: `["triage", { workflow: "deploy", gates: ["approve"] }]`.
+ */
+export type AnswerGrant = "all" | readonly (string | GateGrant)[];
+
+/**
+ * Some Gates of one Workflow, in the `answer` scope (ADR-0078). A Gate's name is its invoke id: the
+ * static name that it has in the Machine that invokes it, and the id that its events carry as their
+ * sender (ADR-0011). That is the invoke `id` that the author wrote, or else the key path of its
+ * gated state below the root of that Machine (`body.humanReview`). One name opens every Gate of the
+ * Workflow with that id, in each child of a Pool too.
+ *
+ * `jr2 up` refuses an item for a Workflow that the Assembly does not have, a name that no Machine
+ * of the Workflow has, and a name that Gates in more than one Machine of the Workflow have. A Chart
+ * wrapper's item (`{ workflow: "plan", gates }`) opens those Gates in each Chart of `plan` too, and
+ * `jr2 up` checks its names against the wrapper's Machines and its Chart files. A runtime Chart is
+ * not in the Assembly, so `jr2 up` cannot check its Gates: a name that no Machine and no Chart file
+ * of the wrapper has, and an item for a runtime Chart (`plan/weekly` with no Chart file), are
+ * warnings, not refusals.
+ */
+export type GateGrant = {
+  /** The Workflow, as a bare name in the list names it. */
+  workflow: string;
+  /** The Gates' names. */
+  gates: readonly string[];
+};
+
+/** The name of one scope of a Caller (ADR-0078). */
+export type Scope = keyof Scopes;
+
+/** Every scope, in the order a reader meets them. */
+export const SCOPES: readonly Scope[] = ["start", "answer", "cancel", "read", "steer"];
+
+/**
+ * One named Caller token (ADR-0078). `jr2 up` makes its value once, in a Secret of its own, and
+ * gives the Orchestrator only the sha-256 of the value. `jr2 caller token <name>` prints the value,
+ * and `jr2 caller rotate <name>` makes a new one.
+ */
+export type CallerToken = {
+  /** What the token may do. See {@link Scopes}. */
+  may: Scopes;
+};
+
+/**
+ * The Callers of an Instance that do not hold the Instance token (ADR-0078). The CLI on a kube
+ * context is the Caller `token/instance`, which needs no entry. When the config loads, a bad entry
+ * is refused: `<file> at callers<path>: <problem>`, followed by the shape of the block.
+ */
+export type CallersConfig = {
+  // The name is part of a Secret's name (`jr2 up`), so it is a DNS label. `instance` is the
+  // Instance token's Caller name, so no named token takes it.
+  /** The named Caller tokens, by name. A name is lowercase letters, digits and `-`, at most 40
+   * characters, from a letter to a letter or digit. The config load refuses `instance`, the
+   * Instance token's name. A name that the config no longer declares stops working at the next
+   * `jr2 up`. */
+  tokens?: Readonly<Record<string, CallerToken>>;
+  /** The identity providers whose JWTs are Callers. See {@link JwtIssuer}. Two entries with one
+   * `issuer` are refused. */
+  issuers?: readonly JwtIssuer[];
+};
+
+/**
+ * One identity provider whose JWTs are Callers (ADR-0078). For each bearer that is a JWT with this
+ * `issuer` in its `iss` claim, jr2 checks the signature against the issuer's published keys, and the
+ * issuer, the audience and the expiry. A JWT that fails a check is 401.
+ *
+ * The Caller's name is the `sub` claim, and the name that jr2 shows is the `email` claim; `claims`
+ * names other claims. Its scopes come from the values of one claim, a list of groups or roles,
+ * through `groups`: each value that `groups` names adds its scopes. A JWT that gets no scope is 403
+ * on every route that needs a scope. jr2 never treats it as read-only.
+ *
+ * The Orchestrator fetches the keys from the issuer: this is its one call out of the Instance, and
+ * it spends no secret (ADR-0068). It keeps the keys for 10 minutes, and fetches them again at once
+ * for a JWT whose key it does not know, at most once each 30 seconds, so a key that the issuer
+ * rotated works with no restart.
+ */
+export type JwtIssuer = {
+  /** The issuer's URL, exactly as the `iss` claim gives it, such as `https://dex.example.com`. */
+  issuer: string;
+  /** The audience that a JWT must name in its `aud` claim: for a login, the client id. */
+  audience: string;
+  /** The URL of the issuer's public keys (a JWKS). Default: the `jwks_uri` of the issuer's
+   * `/.well-known/openid-configuration`. */
+  jwks?: string;
+  /** The claims to read. Default: `{ name: "sub", shown: "email", groups: "groups" }`. */
+  claims?: {
+    /** The claim that is the Caller's name. Use a claim that the provider never reassigns. */
+    name?: string;
+    /** The claim that is the name that jr2 shows. */
+    shown?: string;
+    /** The claim that holds the list of groups or roles that `groups` maps to scopes. */
+    groups?: string;
+  };
+  /** The scopes that each value of the groups claim gives, such as
+   * `{ "jr2-ops": { start: "all", answer: "all" } }`. A JWT with more than one value gets the scopes
+   * of each, joined. A value that is not here gives nothing. */
+  groups: Readonly<Record<string, Scopes>>;
+  /** The Console offers a login against this issuer (ADR-0032): OIDC, the authorization code flow
+   * with PKCE, as a public client, with `audience` as the client id. Register the client as public
+   * (no secret), with the Console's root (`https://<console>/`) as its redirect URI. The Console
+   * reads the issuer and the client id before the login, from the open route
+   * `GET /console/config`: both are public values. A login needs the Console on https or on
+   * localhost, and the issuer must let the Console's origin call its discovery document and its
+   * token endpoint (CORS). Default: `false`, because an issuer for machines (a CI provider's
+   * tokens) has no login page. */
+  login?: boolean;
+};
+
+/**
+ * How long jr2 keeps an ended run, and the volume that keeps it (ADR-0065). When the config loads,
+ * a bad field is refused: `<file> at runs.<field>: <problem>`.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from "@jr2/orchestrator";
+ *
+ * export default defineConfig({ runs: { retain: "90d", volume: "20Gi" } });
+ * ```
+ */
+export type RunsConfig = {
+  /** How long jr2 keeps an ended run: its row, its conversations and the hook log. A number and
+   * `m`, `h`, `d` or `w`, such as `"90d"`. At least `"1h"`, with no upper limit. A live run is
+   * never removed. Default: `"30d"`. */
+  retain?: `${number}${"m" | "h" | "d" | "w"}`;
+  /** The size of the Orchestrator's state volume claim: a number and a unit, such as `"5Gi"` or
+   * `"500Mi"` (a number with no unit is refused). Default: `"5Gi"` for a
+   * new claim; unset, `jr2 up` keeps the size of a claim that exists. A larger size grows the
+   * claim where its StorageClass allows expansion, else `jr2 up` refuses it. A smaller size is
+   * refused: Kubernetes never makes a claim smaller. */
+  volume?: string;
+};
+
+/** `runs.retain` when the config sets none (ADR-0065). */
+export const RUNS_RETAIN_DEFAULT = "30d";
+/** The shortest `runs.retain` (ADR-0065). */
+export const RUNS_RETAIN_MIN_MS = 3_600_000;
+/** The size of a new state volume claim when the config sets no `runs.volume` (ADR-0065). */
+export const STATE_VOLUME_DEFAULT = "5Gi";
+
+/** How long an ended run is kept, in milliseconds: `runs.retain`, or the default. The config load
+ * refuses a bad value, so here a bad one reads as the default. */
+export function retainMs(runs: RunsConfig | undefined): number {
+  const ms = runs?.retain === undefined ? undefined : periodMs(runs.retain);
+  return ms !== undefined && ms >= RUNS_RETAIN_MIN_MS ? ms : periodMs(RUNS_RETAIN_DEFAULT)!;
+}
+
 /**
  * The shape of `jr2.config.ts`: the deployment facts of an Instance, which a Machine cannot carry.
  * It holds the Instance's name, its secrets, how the cluster authenticates to Repos, what the
@@ -498,7 +741,7 @@ export type PriorityClasses = {
  * Every field is optional, and an Instance can run with no `jr2.config.ts`. Write the file as
  * `export default defineConfig({ … })`. When the config loads, a file with no default export is
  * refused: `` <file> has no default export (use `export default defineConfig({…})`) ``. The load also
- * checks the shape of `git.credentials`, `secrets`, `harness.catalog` and `priorityClasses`. It
+ * checks the shape of `git.credentials`, `secrets`, `harness.catalog`, `priorityClasses` and `mcp`. It
  * checks that `sandbox` is an object, and checks its `resources`. Each refusal names the field.
  * `jr2 up` checks the rest.
  *
@@ -554,6 +797,37 @@ export type JR2Config = {
   /** Existing PriorityClasses to use in place of the two that `jr2 up` creates. See
    * {@link PriorityClasses}. */
   priorityClasses?: PriorityClasses;
+  // See `CallersConfig` (ADR-0078).
+  /** The Callers that act on the Instance with a credential of their own, and what each may do.
+   * Default: none; only the Instance token acts. See {@link CallersConfig}. */
+  callers?: CallersConfig;
+  // An allowlist, never a pattern (ADR-0078): the Console needs no entry.
+  /** The origins from which a browser app may call the Instance's HTTP API, such as
+   * `https://ops.example.com`. Each entry is an origin alone: a scheme, a host and an optional port,
+   * with no path. Default: none. The Console is served from the Orchestrator's own origin, so it
+   * needs no entry. The config load refuses an entry that is not an origin:
+   * `<file> at cors[<i>]: <entry> is not an origin — scheme://host[:port], with no path`. */
+  cors?: readonly string[];
+  // A Hook is a Caller with `answer` alone (ADR-0078); its door is `POST /hooks/:name` (ADR-0011).
+  /** The Hooks of the Instance, by name: each one is a door, `POST /hooks/<name>`, for one outside
+   * service. A Hook's value comes from its kind's constructor, which the config imports:
+   * `github({ secret: secret("GH_HOOK") })`, `gitlab({ secret: secret("GL_HOOK"), may })`,
+   * `discord({ publicKey: "…" })`. `may.answer` names the Workflows whose Gates the Hook may answer,
+   * every Workflow by default. A Hook never starts a run. A name has the rule of a Caller token's
+   * name. When the config loads, a bad entry is refused: `<file> at hooks.<name>: <problem>`.
+   * Default: none. */
+  hooks?: Readonly<Record<string, Hook>>;
+  // Reach for tools (ADR-0079): a name of the author's, so an Agent's definition and an Effect name
+  // a server without its url or its secret.
+  /** The MCP servers, by a name of yours: `[a-z][a-z0-9-]*`, not `jr2`. A remote server has a
+   * `url` (`https://` with a secret), a `secret` (a name of the `secrets` list; with no `hosts`, it
+   * is bound to the url's host) and a `timeout` (default `"60s"`). A stdio server has a `command`
+   * of the Sandbox Image, its `args` and a `timeout`. An Agent names a server in its `mcp` list.
+   * Default: none. See {@link McpServer}. */
+  mcp?: Readonly<Record<string, McpServer>>;
+  // The history (ADR-0065): how long an ended run is kept, and the volume that keeps it.
+  /** How long ended runs are kept, and the volume size. Default: `{ retain: "30d", volume: "5Gi" }`. */
+  runs?: RunsConfig;
   // Deployment-varying — resolve from env (ADR-0019).
   /** The image registry prefix to which `jr2 up` pushes the images that it builds, such as
    * `registry.example.com/team`. It changes between deployments, so read it from `process.env`
@@ -650,9 +924,284 @@ export async function loadConfig(dir: string): Promise<JR2Config | undefined> {
   if (mod.default.harness !== undefined) checkHarness(mod.default.harness, file);
   if (mod.default.sandbox !== undefined) checkSandbox(mod.default.sandbox, file);
   if (mod.default.priorityClasses !== undefined) checkPriorityClasses(mod.default.priorityClasses, file);
+  if (mod.default.callers !== undefined) checkCallers(mod.default.callers, file);
+  if (mod.default.cors !== undefined) checkCors(mod.default.cors, file);
+  if (mod.default.hooks !== undefined) checkHooks(mod.default.hooks, file);
+  if (mod.default.mcp !== undefined) checkMcp(mod.default.mcp, mod.default.secrets ?? [], file);
+  if (mod.default.runs !== undefined) checkRuns(mod.default.runs, file);
   return mod.default;
 }
 
+const RUNS_HINT = 'runs is { retain?, volume? }, such as { retain: "30d", volume: "5Gi" } (ADR-0065)';
+const RETAIN_FORM = /^\d+(\.\d+)?[mhdw]$/;
+// A unit is required: a bare number is bytes to Kubernetes, so "5" for "5Gi" is a claim of 5 bytes.
+const VOLUME_FORM = /^\d+(\.\d+)?(Ki|Mi|Gi|Ti|Pi|Ei|k|M|G|T|P|E)$/;
+
+/** `runs`' SHAPE (ADR-0065): `retain` a duration of at least 1h, `volume` a storage quantity. */
+export function checkRuns(runs: unknown, where: string): void {
+  if (typeof runs !== "object" || runs === null || Array.isArray(runs)) {
+    throw new Error(`${where} at runs: expected an object — ${RUNS_HINT}`);
+  }
+  for (const key of Object.keys(runs)) {
+    if (key !== "retain" && key !== "volume") throw new Error(`${where} at runs.${key}: not a field — ${RUNS_HINT}`);
+  }
+  const { retain, volume } = runs as { retain?: unknown; volume?: unknown };
+  if (retain !== undefined) {
+    const ms = typeof retain === "string" && RETAIN_FORM.test(retain) ? periodMs(retain) : undefined;
+    if (ms === undefined) {
+      throw new Error(
+        `${where} at runs.retain: ${JSON.stringify(retain)} is not a duration — a number and m, h, d or w, such as "30d" (ADR-0065)`,
+      );
+    }
+    if (ms < RUNS_RETAIN_MIN_MS) {
+      throw new Error(
+        `${where} at runs.retain: ${JSON.stringify(retain)} is shorter than 1h — jr2 keeps an ended run for at least 1h (ADR-0065)`,
+      );
+    }
+  }
+  if (
+    volume !== undefined &&
+    (typeof volume !== "string" || !VOLUME_FORM.test(volume) || !(Number.parseFloat(volume) > 0))
+  ) {
+    throw new Error(
+      `${where} at runs.volume: ${JSON.stringify(volume)} is not a storage quantity — a number and a unit, such as "5Gi" or "500Mi" (ADR-0065)`,
+    );
+  }
+}
+
+/** A list item of a scope other than `answer`: a Workflow name. An item that names Gates is refused
+ * with the reason: only `answer` acts on one Gate, and the other scopes act on a whole run. */
+const workflowItem = (scope: Scope) =>
+  z.unknown().superRefine((item, ctx) => {
+    if (typeof item === "string" && item !== "") return;
+    ctx.addIssue({
+      code: "custom",
+      message:
+        typeof item === "object" && item !== null && "gates" in item
+          ? `only "answer" can name single Gates; "${scope}" names whole Workflows, because it acts on a whole run`
+          : "a Workflow name is a string that is not empty",
+    });
+  });
+const ScopeGrantShape = (scope: Scope) => z.union([z.literal("all"), z.array(workflowItem(scope)).min(1)]);
+const GateGrantShape = z
+  .object({
+    workflow: z.string().min(1, "a Workflow name is a string that is not empty"),
+    gates: z
+      .array(z.string().min(1, "a Gate name is a string that is not empty"))
+      .min(1, "gates names at least one Gate"),
+  })
+  .strict();
+const AnswerGrantShape = z.union([z.literal("all"), z.array(z.union([z.string().min(1), GateGrantShape])).min(1)]);
+const ScopesShape = z
+  .object({
+    start: ScopeGrantShape("start").optional(),
+    answer: AnswerGrantShape.optional(),
+    cancel: ScopeGrantShape("cancel").optional(),
+    read: ScopeGrantShape("read").optional(),
+    steer: ScopeGrantShape("steer").optional(),
+  })
+  .strict();
+const CallersShape = z
+  .object({
+    tokens: z
+      .record(
+        z
+          .string()
+          .regex(
+            /^[a-z]([a-z0-9-]{0,38}[a-z0-9])?$/,
+            "a token name is lowercase letters, digits and -, at most 40, starts with a letter and ends with a letter or digit",
+          )
+          .refine((name) => name !== "instance", "the name instance is the Instance token's"),
+        z.object({ may: ScopesShape }).strict(),
+      )
+      .optional(),
+    issuers: z
+      .array(
+        z
+          .object({
+            issuer: z.string().refine(isHttpUrl, "the issuer is an http or https URL"),
+            audience: z.string().min(1),
+            jwks: z.string().refine(isHttpUrl, "jwks is an http or https URL").optional(),
+            claims: z
+              .object({
+                name: z.string().min(1).optional(),
+                shown: z.string().min(1).optional(),
+                groups: z.string().min(1).optional(),
+              })
+              .strict()
+              .optional(),
+            groups: z.record(z.string().min(1), ScopesShape),
+            login: z.boolean().optional(),
+          })
+          .strict(),
+      )
+      .refine(
+        (list) => new Set(list.map((i) => i.issuer)).size === list.length,
+        "two issuers have one issuer URL; each issuer is one entry",
+      )
+      .optional(),
+  })
+  .strict();
+
+/** Whether `text` is an http or https URL. */
+function isHttpUrl(text: string): boolean {
+  try {
+    const url = new URL(text);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+/** `callers`' SHAPE (ADR-0078), the `checkGit` style: a bad entry names its path. */
+function checkCallers(callers: unknown, where: string): void {
+  const parsed = CallersShape.safeParse(callers);
+  if (parsed.success) return;
+  const issue = parsed.error.issues[0];
+  const at = ["", ...(issue?.path ?? [])].map(String).join(".");
+  // A bad token NAME is an issue about the key, whose own issues say why.
+  const inner = issue?.code === "invalid_key" ? issue.issues[0]?.message : undefined;
+  throw new Error(`${where} at callers${at}: ${inner ?? issue?.message ?? "invalid"} — ${CALLERS_HINT}`);
+}
+
+const CALLERS_HINT =
+  "callers is { tokens?: { <name>: { may: <scopes> } }, issuers?: [{ issuer, audience, jwks?, " +
+  "claims?: { name?, shown?, groups? }, groups: { <value>: <scopes> }, login? }] }, where <scopes> is " +
+  '{ start?, answer?, cancel?, read?, steer? }, each scope "all" or a list of Workflow names, and an answer ' +
+  "item may be { workflow, gates: [<Gate name>] } (ADR-0078)";
+
+/** The name of a Hook (ADR-0078): the last segment of `POST /hooks/:name`, the rule of a Caller
+ * token's name. */
+export const HOOK_NAME = /^[a-z]([a-z0-9-]{0,38}[a-z0-9])?$/;
+
+/** `hooks`' SHAPE (ADR-0078): each entry is a Hook that a kind's constructor made, under a name of
+ * the Caller name's form, and one kind id is one kind (`kindsById`). */
+function checkHooks(hooks: unknown, where: string): void {
+  if (typeof hooks !== "object" || hooks === null || Array.isArray(hooks)) {
+    throw new Error(`${where} at hooks: expected { <name>: <Hook> }, such as { forge: github({ secret }) } (ADR-0078)`);
+  }
+  const kinds = [];
+  for (const [name, hook] of Object.entries(hooks)) {
+    if (!HOOK_NAME.test(name)) {
+      throw new Error(
+        `${where} at hooks.${name}: a Hook's name is lowercase letters, digits and -, at most 40, starts with a ` +
+          "letter and ends with a letter or digit (ADR-0078)",
+      );
+    }
+    if (!isHook(hook)) {
+      throw new Error(
+        `${where} at hooks.${name}: not a Hook — make it with its kind, such as github({ secret: secret("GH_HOOK") }) (ADR-0078)`,
+      );
+    }
+    kinds.push(hookParts(hook).kind);
+  }
+  try {
+    kindsById(kinds);
+  } catch (err) {
+    throw new Error(`${where} at hooks: ${err instanceof Error ? err.message : String(err)} (ADR-0078)`);
+  }
+}
+
+/** `cors`' SHAPE (ADR-0078): a list of origins, each one exactly what a browser sends as `Origin`. */
+function checkCors(cors: unknown, where: string): void {
+  if (!Array.isArray(cors)) throw new Error(`${where} at cors: expected an array of origins (ADR-0078)`);
+  for (const [i, entry] of cors.entries()) {
+    if (typeof entry !== "string" || !isOrigin(entry)) {
+      throw new Error(
+        `${where} at cors[${i}]: ${JSON.stringify(entry)} is not an origin — scheme://host[:port], with no path (ADR-0078)`,
+      );
+    }
+  }
+}
+
+/** Whether `text` is an origin as a browser sends it: `URL` gives back the same text as its origin. */
+function isOrigin(text: string): boolean {
+  try {
+    const url = new URL(text);
+    return (url.protocol === "http:" || url.protocol === "https:") && url.origin === text;
+  } catch {
+    return false;
+  }
+}
+
+/** An MCP server's name (ADR-0079): the `<server>` of `mcp__<server>__<tool>`. It has no `_`, so
+ * the prefix of a tool name is never ambiguous. */
+export const MCP_SERVER_NAME = /^[a-z][a-z0-9-]*$/;
+
+/** The default `timeout` of one MCP call (ADR-0079). */
+export const MCP_DEFAULT_TIMEOUT_MS = 60_000;
+
+/** One MCP server's `timeout` in milliseconds, or undefined when it is not a duration of 1 ms or
+ * more (a shorter one rounds to 0 ms, which no Harness can wait). */
+export function mcpTimeoutMs(timeout: string | undefined): number | undefined {
+  if (timeout === undefined) return MCP_DEFAULT_TIMEOUT_MS;
+  const m = /^(\d+(?:\.\d+)?)(s|m|h)$/.exec(timeout);
+  const n = m ? Number(m[1]) : NaN;
+  if (!(n > 0)) return undefined;
+  const ms = Math.round(m![2] === "h" ? n * 3_600_000 : m![2] === "m" ? n * 60_000 : n * 1000);
+  return ms >= 1 ? ms : undefined;
+}
+
+/** Is this MCP server a stdio one (`command`), not a remote one (`url`)? */
+export function isStdioServer(server: McpServer): server is McpStdioServer {
+  return "command" in server;
+}
+
+const McpTimeoutShape = z
+  .string()
+  .refine((t) => mcpTimeoutMs(t) !== undefined, 'a timeout is a positive duration, such as "90s", "5m" or "1h"');
+const McpServerShape = z.union([
+  z.object({ url: z.string(), secret: z.string().min(1).optional(), timeout: McpTimeoutShape.optional() }).strict(),
+  z
+    .object({
+      command: z.string().min(1),
+      args: z.array(z.string()).optional(),
+      timeout: McpTimeoutShape.optional(),
+    })
+    .strict(),
+]);
+
+const MCP_HINT =
+  "an entry is <name>: { url, secret?, timeout? } for a remote server, or <name>: { command, args?, timeout? } for a stdio server (ADR-0079)";
+
+/** `mcp`'s SHAPE (ADR-0079), the `checkGit` style: a bad entry names its path. The url is not
+ * checked here: in-cluster it reads `.env`, which is absent, so `jr2 up` checks it host-side. */
+function checkMcp(mcp: unknown, secrets: readonly SecretEntry[], where: string): void {
+  if (typeof mcp !== "object" || mcp === null || Array.isArray(mcp)) {
+    throw new Error(`${where} at mcp: expected an object keyed by server name — ${MCP_HINT}`);
+  }
+  for (const [name, server] of Object.entries(mcp)) {
+    if (name === "jr2") {
+      throw new Error(
+        `${where} at mcp.jr2: the server name jr2 is reserved — the Menu's tools are named mcp__jr2__<event>; ` +
+          "give the server another name (ADR-0079)",
+      );
+    }
+    if (!MCP_SERVER_NAME.test(name)) {
+      throw new Error(
+        `${where} at mcp.${name}: a server name is lowercase letters, digits and -, and starts with a letter ` +
+          "([a-z][a-z0-9-]*) — it is the <server> of the tool names mcp__<server>__<tool> (ADR-0079)",
+      );
+    }
+    const parsed = McpServerShape.safeParse(server);
+    if (!parsed.success) {
+      // A union's issue says only "invalid input": name the branch the entry meant.
+      const meant = typeof server === "object" && server !== null && "command" in server ? 1 : 0;
+      const issues = parsed.error.issues[0];
+      const inner = issues?.code === "invalid_union" ? (issues.errors[meant]?.[0] ?? issues.errors[0]?.[0]) : issues;
+      const at = ["", ...(inner?.path ?? [])].map(String).join(".");
+      throw new Error(`${where} at mcp.${name}${at}: ${inner?.message ?? "invalid"} — ${MCP_HINT}`);
+    }
+    const secret = (server as { secret?: string }).secret;
+    if (secret !== undefined && !secrets.some((s) => s.name === secret)) {
+      throw new Error(
+        `${where} at mcp.${name}.secret: "${secret}" is not an entry of secrets — add it: ` +
+          `secrets: [{ name: "${secret}", value: process.env.${secret} }] (ADR-0079)`,
+      );
+    }
+  }
+}
+
 const NonEmpty = z.string().min(1);
 const Credential = z
   .object({