@jr2/orchestrator 0.6.0 → 0.7.0

package/src/harness-client.ts

@@ -83,6 +83,7 @@ import {
   MAX_KILLS_BODY,
   MAX_TOLD,
   type Notice,
+  type SteeringMessage,
   type Settlement,
   type StreamEvent,
   type SubmissionSettledEvent,
@@ -114,6 +115,8 @@ export type HarnessClient = {
       thinkingLevel?: ThinkingLevel;
       /** The pending notices in this admission's scope (ADR-0062). Omitted when there are none. */
       notices?: Notice[];
+      /** The Steering messages held for this Agent slot (ADR-0002). Omitted when there are none. */
+      steering?: SteeringMessage[];
       /** The admission is for a conversation this process was told the Harness keeps (ADR-0062).
        * The Harness that keeps none answers 404 and seats none: this verb throws
        * {@link ConversationNotKept}. */
@@ -393,6 +396,7 @@ export function createHarnessClient(options: HarnessClientOptions): HarnessClien
             // The Briefing's news (ADR-0062): typed data, the Harness writes the words. Omitted
             // when there is none, so an admission without notices is byte-identical to before.
             ...(sendOptions.notices?.length ? { notices: sendOptions.notices } : {}),
+            ...(sendOptions.steering?.length ? { steering: sendOptions.steering } : {}),
             // Omitted when unset, so an admission that is not for a kept conversation is
             // byte-identical to before.
             ...(sendOptions.kept ? { kept: true } : {}),
@@ -613,10 +617,11 @@ export function createHarnessClient(options: HarnessClientOptions): HarnessClien
 
 /** The definition as the ADMISSION carries it (ADR-0057): identity alone. `description` is
  * Console material the Orchestrator strips before admission — the Harness has no use for it and
- * no longer validates it. Every other field travels, so a field added to the definition reaches
- * the Harness without a change here. */
-function admittedDefinition(definition: AgentDefinition): Omit<AgentDefinition, "description"> {
-  const { description: _description, ...identity } = definition;
+ * no longer validates it. `steerable` is the Orchestrator's own (ADR-0002): it refuses Callers,
+ * and the model never reads it. Every other field travels, so a field added to the definition
+ * reaches the Harness without a change here. */
+function admittedDefinition(definition: AgentDefinition): Omit<AgentDefinition, "description" | "steerable"> {
+  const { description: _description, steerable: _steerable, ...identity } = definition;
   return identity;
 }
 
@@ -638,6 +643,7 @@ export function harnessAgentRunPort(client: HarnessClient): AgentRunPort {
         model: input.model,
         thinkingLevel: input.thinkingLevel,
         ...(opts.notices?.length ? { notices: opts.notices } : {}),
+        ...(opts.steering?.length ? { steering: opts.steering } : {}),
         ...(opts.kept ? { kept: true } : {}),
         signal: opts.signal,
       });

package/src/held-secrets.ts

@@ -23,7 +23,7 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { isIP } from "node:net";
-import type { JR2Config, HarnessEnvVar } from "./config.ts";
+import { isStdioServer, type JR2Config, type HarnessEnvVar } from "./config.ts";
 import {
   CREDENTIAL_FILES,
   DOMAIN_WRITABLE_ROOTS,
@@ -280,6 +280,23 @@ export function heldSecretsOf(
     catalogHosts.set(id, target.port === 443 ? target.host : `${target.host}:${target.port}`);
   }
 
+  // R7 for an MCP server (ADR-0079): one with a `secret` needs an https url, because the Custodian
+  // carries TLS only. Its url's host is the default binding of the secret it names (`hostsOf`).
+  const serverHosts = new Map<string, Array<{ server: string; host: string; port: number; path: string }>>();
+  for (const [server, declared] of Object.entries(config.mcp ?? {})) {
+    if (isStdioServer(declared) || declared.secret === undefined || !claimed.has(declared.secret)) continue;
+    const target = httpsTarget(declared.url);
+    if (!target) {
+      throw new Error(
+        `mcp.${server}.url must be an https:// URL — the server has a secret, ${declared.secret}, and the Custodian ` +
+          "carries TLS only (ADR-0059, ADR-0079). Read it from .env: " +
+          `mcp: { "${server}": { url: process.env.${server.toUpperCase().replace(/-/g, "_")}_URL ?? "", secret: "${declared.secret}" } }`,
+      );
+    }
+    const path = new URL(declared.url).pathname || "/";
+    serverHosts.set(declared.secret, [...(serverHosts.get(declared.secret) ?? []), { server, ...target, path }]);
+  }
+
   // jr2's own names (ADR-0076): the Harness's start takes a `JR2_` name from jr2's composition alone,
   // and refuses to start on an envFrom key that starts with `JR2_` (`effector nocore --harness-env`).
   // A user's `JR2_MENU_ONLY` or `JR2_START_ENV` would turn the domain off or replace its env.
@@ -453,8 +470,10 @@ export function heldSecretsOf(
     const source = sourceOf(e, lookups);
     if (source.kind === "literal") values[e.name] = e.value as string;
 
-    // R6
-    const headers = [...(e.headers ?? DEFAULT_CREDENTIAL_HEADERS)];
+    // R6. An MCP server's secret with no binding goes in `authorization` alone (ADR-0079): the
+    // Harness sends `Authorization: Bearer <Stand-in>`.
+    const mcpDefault = e.hosts === undefined && e.headers === undefined && serverHosts.has(e.name);
+    const headers = [...(e.headers ?? (mcpDefault ? ["authorization"] : DEFAULT_CREDENTIAL_HEADERS))];
     const seenHeader = new Set<string>();
     for (const [j, header] of headers.entries()) {
       if (!HEADER_TOKEN.test(header) || FRAMING_HEADERS.has(header) || header.startsWith("proxy-")) {
@@ -467,6 +486,16 @@ export function heldSecretsOf(
       if (seenHeader.has(header)) throw new Error(`${e.at}.headers lists "${header}" twice (ADR-0059)`);
       seenHeader.add(header);
     }
+    // R6 for an MCP server's secret (ADR-0079): the Harness sends its Stand-in in `authorization`
+    // alone, so a binding without that header removes it on each call.
+    for (const s of serverHosts.get(e.name) ?? []) {
+      if (headers.includes("authorization")) break;
+      throw new Error(
+        `${e.at}.headers leaves out "authorization", where the Harness sends the Stand-in of ${e.name} to ` +
+          `mcp.${s.server}.url — each call of that server would arrive with no credential. Add it, or drop headers ` +
+          "to take that default (ADR-0059, ADR-0079)",
+      );
+    }
 
     // R12
     const paths = e.paths === undefined ? undefined : [...e.paths];
@@ -478,9 +507,18 @@ export function heldSecretsOf(
         );
       }
     }
+    // R12 for an MCP server's secret (ADR-0079): every call goes to the url's path, so `paths` must
+    // cover it, by the prefix rule the Custodian applies.
+    for (const s of serverHosts.get(e.name) ?? []) {
+      if (paths === undefined || paths.some((p) => pathCovers(p, s.path))) continue;
+      throw new Error(
+        `${e.at}.paths does not cover ${s.path}, the path of mcp.${s.server}.url, whose secret ${e.name} is — ` +
+          `each call of that server would be refused with 403. Add "${s.path}", or drop paths (ADR-0059, ADR-0079)`,
+      );
+    }
 
     // R5 (+ the §3.4 default and R9)
-    const hosts = hostsOf(e, catalogHosts, lookups.models ?? []);
+    const hosts = hostsOf(e, catalogHosts, lookups.models ?? [], serverHosts.get(e.name) ?? []);
     secrets.push({
       name: e.name,
       source,
@@ -538,24 +576,6 @@ export function heldSecretsOf(
     }
   }
 
-  // R5: one header on one host names one secret.
-  const byTarget = new Map<string, { name: string; headers: string[] }[]>();
-  for (const s of secrets) {
-    for (const h of s.hosts) {
-      const key = `${h.host}:${h.port}`;
-      for (const other of byTarget.get(key) ?? []) {
-        const shared = s.headers.filter((header) => other.headers.includes(header));
-        if (shared.length > 0) {
-          throw new Error(
-            `${s.name} and ${other.name} are both bound to ${key} in header ${shared.join(", ")} — one header on ` +
-              "one host carries one secret; give each its own `headers` (ADR-0059)",
-          );
-        }
-      }
-      byTarget.set(key, [...(byTarget.get(key) ?? []), { name: s.name, headers: s.headers }]);
-    }
-  }
-
   return { manifest: { version: 1, secrets }, values, warnings };
 }
 
@@ -604,16 +624,31 @@ export function sourceOf(
 
 /** R5 and R9: where one secret may go. A known model key with no `hosts` goes where its provider's
  * calls go — the catalog override's host, else the table's — so the key and the calls read one
- * config and cannot drift. */
+ * config and cannot drift. An MCP server's secret with no `hosts` goes to the host of the url of
+ * each server that names it (ADR-0079), for the same reason. */
 function hostsOf(
   e: { at: string; name: string; hosts?: readonly string[] },
   catalogHosts: ReadonlyMap<string, string>,
   models: readonly string[],
+  servers: ReadonlyArray<{ server: string; host: string; port: number }>,
 ): Array<{ host: string; port: number }> {
   const known = MODEL_KEYS[e.name];
   const effective = new Map<string, string | undefined>();
   for (const provider of known?.providers ?? []) effective.set(provider, catalogHosts.get(provider) ?? known?.host);
 
+  if (e.hosts === undefined && servers.length > 0) {
+    const out: Array<{ host: string; port: number }> = [];
+    const add = (t: { host: string; port: number }) => {
+      if (!out.some((o) => o.host === t.host && o.port === t.port)) out.push({ host: t.host, port: t.port });
+    };
+    for (const s of servers) add(s);
+    // A model key that an MCP server also names keeps its provider's host beside the servers'.
+    const defaults = new Set(effective.values());
+    const only = defaults.size === 1 ? [...defaults][0] : undefined;
+    if (only !== undefined) add(parseTarget(`${e.at}.hosts`, only));
+    return out;
+  }
+
   if (e.hosts === undefined || e.hosts.length === 0) {
     const defaults = new Set(effective.values());
     const only = defaults.size === 1 ? [...defaults][0] : undefined;
@@ -636,9 +671,23 @@ function hostsOf(
         `or drop hosts to take that default (ADR-0059)`,
     );
   }
+  for (const s of servers) {
+    if (targets.some((t) => t.host === s.host && t.port === s.port)) continue;
+    throw new Error(
+      `${e.at}.hosts leaves out ${s.host}${s.port === 443 ? "" : `:${s.port}`}, the host of mcp.${s.server}.url, ` +
+        `whose secret ${e.name} is — each call of that server would arrive with the Stand-in and fail with 401. ` +
+        "Add it, or drop hosts to take that default (ADR-0059, ADR-0079)",
+    );
+  }
   return targets;
 }
 
+/** Whether the `paths` entry `prefix` lets a request to `path` through: the Custodian's rule — the
+ * same path, or `prefix` and then a `/` (or `prefix` ends in `/`). */
+function pathCovers(prefix: string, path: string): boolean {
+  return path === prefix || (path.startsWith(prefix) && (prefix.endsWith("/") || path.charAt(prefix.length) === "/"));
+}
+
 /** An `https://` URL's host and port, or undefined for anything else. */
 function httpsTarget(url: string): { host: string; port: number } | undefined {
   let parsed: URL;

package/src/holds.ts

@@ -31,9 +31,9 @@ export type Hold = {
   deliveryId: string;
   /** The pick's event name. */
   pick: string;
-  /** The Agent slot that picked — the Console's "held since" names it. */
+  /** The Agent slot that picked — the Console's "outstanding since" names it. */
   agent: string;
-  /** ISO time the pick was delivered: the Console's "held since". */
+  /** ISO time the pick was delivered: the Console's "outstanding since". */
   since: string;
   /** The Sandbox whose token may read the answer (ADR-0013) — the registration's, kept because the
    * answer outlives a registration that a route out of the Agent's state ends. */

package/src/hook-kinds/discord.ts

@@ -0,0 +1,92 @@
+// `@jr2/orchestrator/hooks/discord`: jr2's Discord kind, for an application's Interactions Endpoint URL.
+
+import { z } from "zod";
+import { at, defineHookKind, json } from "./index.ts";
+
+const user = z.looseObject({ id: z.string() });
+
+/** The schema of each event key. A command's name is part of its key, so `.*` covers them all. */
+export const discordEvents = {
+  "application_command.*": z.looseObject({
+    channel_id: z.string(),
+    /** In a guild. */
+    member: z.looseObject({ user }).optional(),
+    /** In a direct message. */
+    user: user.optional(),
+    data: z.looseObject({
+      name: z.string(),
+      options: z
+        .array(z.looseObject({ name: z.string(), value: z.union([z.string(), z.number(), z.boolean()]).optional() }))
+        .optional(),
+    }),
+  }),
+  message_component: z.looseObject({
+    member: z.looseObject({ user }).optional(),
+    user: user.optional(),
+    data: z.looseObject({ custom_id: z.string() }),
+    message: z.looseObject({ id: z.string() }),
+  }),
+};
+
+const text = (v: unknown): string | undefined => (typeof v === "string" && v !== "" ? v : undefined);
+
+/** The interaction types that this kind reads (Discord's numbers). */
+const PING = 1;
+const APPLICATION_COMMAND = 2;
+const MESSAGE_COMPONENT = 3;
+
+/**
+ * - verifier: `ed25519` over `<X-Signature-Timestamp><raw body>`, `X-Signature-Ed25519` in hex,
+ *   checked against the application's PUBLIC key in the Orchestrator. The signature covers the
+ *   timestamp, so the kind gives it as `at`. Discord states no window; the door's 300 s window
+ *   applies to each signed `at`, so it applies here too.
+ * - handshake: `PING` (type 1) gets `{ type: 1 }` (PONG).
+ * - event keys: `application_command.<data.name>` (type 2), `message_component` (type 3). Another
+ *   type (an autocomplete, a modal) gets the key `interaction.<type>`, which has no schema, so it
+ *   reaches nothing.
+ * - delivery id: the interaction's `id`. `onBehalfOf`: `member.user.id`, or `user.id` in a direct
+ *   message. (Discord's docs do not say that Discord sends an interaction again.)
+ * - who reads the answer: a person, always.
+ * - answer: `{ type: 4, data: { content, flags: 64 } }`, an ephemeral message. Discord shows
+ *   markdown, not HTML, so the text needs no escape. Text limit: 2000 characters.
+ */
+export const discord = defineHookKind({
+  api: 1,
+  id: "discord",
+  events: discordEvents,
+  verify: {
+    ed25519: {
+      signed: (req) => {
+        const ts = req.headers["x-signature-timestamp"];
+        const sig = req.headers["x-signature-ed25519"];
+        if (ts === undefined || !/^\d+$/.test(ts) || sig === undefined) {
+          return { unsigned: "no Discord signature or timestamp" };
+        }
+        return { bytes: [ts, req.body], signature: { hex: sig }, at: Number(ts) };
+      },
+    },
+  },
+  read: (req) => {
+    const p = json(req);
+    const type = at(p, "type");
+    if (type === PING) return { handshake: { body: { type: 1 } } };
+    const id = text(at(p, "id"));
+    if (id === undefined) throw new Error("the interaction has no id");
+    const by = text(at(p, "member.user.id")) ?? text(at(p, "user.id"));
+    const key =
+      type === APPLICATION_COMMAND
+        ? `application_command.${text(at(p, "data.name")) ?? ""}`
+        : type === MESSAGE_COMPONENT
+          ? "message_component"
+          : `interaction.${String(type)}`;
+    return { key, id, payload: p, ...(by ? { onBehalfOf: by } : {}), readBy: "person" };
+  },
+  answer: (t) => ({ body: { type: 4, data: { content: t, flags: 64 } } }),
+  maxText: 2000,
+});
+
+declare module "./index.ts" {
+  interface HookKinds {
+    discord: typeof discord;
+  }
+}

package/src/hook-kinds/door.ts

@@ -0,0 +1,107 @@
+// `hook-kinds/door.ts`: what the Hook's door reads from a Hook and a kind. The package does not
+// export it, because it is NOT part of a kind's interface: a kind imports `@jr2/orchestrator/hooks` only. It is here because
+// `defineHookKind` decides the shape of a Hook, so the code that reads a Hook is beside it.
+
+import type { z } from "zod";
+import { HOOK } from "./hook.ts";
+import { HOOK_KIND_APIS, type Hook, type HookKind, type HookParts, type HookRequest, type Signed } from "./index.ts";
+
+/** True when `value` is a Hook that a kind's constructor made. */
+export function isHook(value: unknown): value is Hook {
+  return typeof value === "object" && value !== null && Object.hasOwn(value, HOOK);
+}
+
+/** The kind, the credential and `may` of a Hook. It throws when `hook` is not a Hook. */
+export function hookParts<K extends HookKind>(hook: Hook<K>): HookParts<K> {
+  if (!isHook(hook)) throw new Error("not a Hook: make it with its kind, such as github({ secret, may })");
+  return hook[HOOK];
+}
+
+/**
+ * The request that the door gives a kind. Header names become lowercase. A header with more than
+ * one value keeps them joined by ", ", as `Headers` does. `strip` names a header that the door
+ * removes (the `token` verifier's header), so no code of the kind can read it.
+ */
+export function hookRequest(
+  headers: Headers | { readonly [name: string]: string | readonly string[] | undefined },
+  body: Uint8Array,
+  strip?: string,
+): HookRequest {
+  const out: { [name: string]: string } = Object.create(null) as { [name: string]: string };
+  const entries: Iterable<[string, string | readonly string[] | undefined]> =
+    headers instanceof Headers ? headers.entries() : Object.entries(headers);
+  for (const [name, value] of entries) {
+    if (value === undefined) continue;
+    const lower = name.toLowerCase();
+    const text = typeof value === "string" ? value : value.join(", ");
+    out[lower] = Object.hasOwn(out, lower) ? `${out[lower]}, ${text}` : text;
+  }
+  if (strip !== undefined) delete out[strip.toLowerCase()];
+  const bytes = new Uint8Array(body);
+  return Object.freeze({
+    headers: Object.freeze(out),
+    body: bytes,
+    text: new TextDecoder("utf-8").decode(bytes),
+  });
+}
+
+/**
+ * The schema of an event key: the exact key, else the longest `prefix.*` key that the event key
+ * starts with (`block_actions.*` for `block_actions.approve`). `undefined` when the kind names no
+ * schema for the key: the door does not parse such a delivery, and it reaches nothing.
+ */
+export function schemaFor(kind: HookKind, key: string): z.ZodType | undefined {
+  if (Object.hasOwn(kind.events, key)) return kind.events[key];
+  let best: { readonly length: number; readonly schema: z.ZodType } | undefined;
+  for (const [k, schema] of Object.entries(kind.events)) {
+    if (!k.endsWith(".*")) continue;
+    const prefix = k.slice(0, -1); // keeps the "."
+    if (key.length > prefix.length && key.startsWith(prefix) && (!best || prefix.length > best.length)) {
+      best = { length: prefix.length, schema };
+    }
+  }
+  return best?.schema;
+}
+
+/** The bytes that the service signed, joined. A string part is UTF-8. */
+export function signedBytes(signed: Signed): Uint8Array {
+  const parts = signed.bytes.map((b) => (typeof b === "string" ? new TextEncoder().encode(b) : b));
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let i = 0;
+  for (const p of parts) {
+    out.set(p, i);
+    i += p.length;
+  }
+  return out;
+}
+
+/** The signature as bytes, or `undefined` when its hex or base64 is not well formed. */
+export function signatureBytes(signed: Signed): Uint8Array | undefined {
+  const s = signed.signature;
+  if ("hex" in s) {
+    if (!/^(?:[0-9a-fA-F]{2})+$/.test(s.hex)) return undefined;
+    return Uint8Array.from(Buffer.from(s.hex, "hex"));
+  }
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(s.base64) || s.base64.length % 4 !== 0) return undefined;
+  return Uint8Array.from(Buffer.from(s.base64, "base64"));
+}
+
+/**
+ * The kinds of one Assembly, by id. It throws when two different kinds give one id, or when a kind
+ * states an `api` that this copy of `@jr2/orchestrator/hooks` does not know. One kind that two Hooks use is one
+ * entry.
+ */
+export function kindsById(kinds: Iterable<HookKind>): ReadonlyMap<string, HookKind> {
+  const out = new Map<string, HookKind>();
+  for (const kind of kinds) {
+    if (!HOOK_KIND_APIS.includes(kind.api)) {
+      throw new Error(`Hook kind ${kind.id} states api ${String(kind.api)}; this jr2 knows api 1 only`);
+    }
+    const had = out.get(kind.id);
+    if (had !== undefined && had !== kind) {
+      throw new Error(`two different Hook kinds have the id ${kind.id}: one id is one kind in an Assembly`);
+    }
+    out.set(kind.id, kind);
+  }
+  return out;
+}

package/src/hook-kinds/github.ts

@@ -0,0 +1,89 @@
+// `@jr2/orchestrator/hooks/github`: jr2's GitHub kind. It imports `@jr2/orchestrator/hooks` and nothing more of jr2, as a
+// kind from another package does.
+
+import { z } from "zod";
+import { defineHookKind, json, type HookRequest } from "./index.ts";
+
+const user = z.looseObject({ login: z.string() });
+
+/**
+ * The schema of each event key. Each names only the fields that handlers read; a loose object keeps
+ * the rest. A value that GitHub can extend (a review's `state`) is a string, not an enum, so a new
+ * value fails no parse.
+ */
+export const githubEvents = {
+  "pull_request_review.submitted": z.looseObject({
+    review: z.looseObject({
+      /** Lowercase in a webhook: `approved`, `changes_requested`, `commented`. */
+      state: z.string(),
+      body: z.string().nullable(),
+      user,
+      commit_id: z.string(),
+    }),
+    pull_request: z.looseObject({ html_url: z.string() }),
+  }),
+  "issue_comment.created": z.looseObject({
+    comment: z.looseObject({ body: z.string(), user, author_association: z.string() }),
+    issue: z.looseObject({
+      /** Only when the issue is a pull request. */
+      pull_request: z.looseObject({ html_url: z.string() }).optional(),
+    }),
+  }),
+  "check_suite.completed": z.looseObject({
+    check_suite: z.looseObject({
+      head_sha: z.string(),
+      /** `success`, `failure`, `neutral`, `cancelled`, `timed_out`, …; `null` while it runs. */
+      conclusion: z.string().nullable(),
+    }),
+  }),
+};
+
+const header = (req: HookRequest, name: string): string => {
+  const v = req.headers[name];
+  if (v === undefined || v === "") throw new Error(`no ${name} header`);
+  return v;
+};
+
+/**
+ * A GitHub repository, organization or App webhook, with the content type `application/json`. (A
+ * webhook with the content type `application/x-www-form-urlencoded` gets 400.)
+ * - verifier: `mac`, HMAC-SHA256 of the raw body, `X-Hub-Signature-256: sha256=<hex>`.
+ * - handshake: the `ping` event (sent when the webhook is made) gets an empty 200.
+ * - event key: `<X-GitHub-Event>.<action>`, or `<X-GitHub-Event>` when the body has no action.
+ * - delivery id: `X-GitHub-Delivery`. `onBehalfOf`: `sender.login`.
+ * - answer: the outcome (the default). No person reads it.
+ */
+export const github = defineHookKind({
+  api: 1,
+  id: "github",
+  events: githubEvents,
+  verify: {
+    mac: {
+      alg: "sha256",
+      signed: (req) => {
+        const sig = req.headers["x-hub-signature-256"];
+        if (!sig?.startsWith("sha256=")) return { unsigned: "no X-Hub-Signature-256 header" };
+        return { bytes: [req.body], signature: { hex: sig.slice("sha256=".length) } };
+      },
+    },
+  },
+  read: (req) => {
+    const event = header(req, "x-github-event");
+    if (event === "ping") return { handshake: { body: null } };
+    const p = json(req) as { readonly action?: unknown; readonly sender?: { readonly login?: unknown } } | null;
+    const action = typeof p?.action === "string" && p.action !== "" ? p.action : undefined;
+    const by = p?.sender?.login;
+    return {
+      key: action ? `${event}.${action}` : event,
+      id: header(req, "x-github-delivery"),
+      payload: p,
+      ...(typeof by === "string" && by !== "" ? { onBehalfOf: by } : {}),
+    };
+  },
+});
+
+declare module "./index.ts" {
+  interface HookKinds {
+    github: typeof github;
+  }
+}

package/src/hook-kinds/gitlab.ts

@@ -0,0 +1,72 @@
+// `@jr2/orchestrator/hooks/gitlab`: jr2's GitLab kind. The `token` verifier: the door compares the digest of the
+// header and removes the header before `read` runs, so this code never sees the token.
+
+import { z } from "zod";
+import { at, defineHookKind, json } from "./index.ts";
+
+const user = z.looseObject({ username: z.string() });
+
+/** The schema of each event key: the fields that handlers read, in loose objects. */
+export const gitlabEvents = {
+  "merge_request.approved": z.looseObject({
+    user,
+    object_attributes: z.looseObject({ url: z.string(), last_commit: z.looseObject({ id: z.string() }) }),
+  }),
+  "note.MergeRequest": z.looseObject({
+    user,
+    object_attributes: z.looseObject({ note: z.string() }),
+    merge_request: z.looseObject({ url: z.string() }),
+  }),
+  "pipeline.success": z.looseObject({
+    object_attributes: z.looseObject({ sha: z.string(), status: z.string() }),
+  }),
+  "pipeline.failed": z.looseObject({
+    object_attributes: z.looseObject({ sha: z.string(), status: z.string() }),
+  }),
+};
+
+const text = (v: unknown): string | undefined => (typeof v === "string" && v !== "" ? v : undefined);
+
+/**
+ * A GitLab project or group webhook.
+ * - verifier: `token`, the secret token in `X-Gitlab-Token`.
+ * - handshake: none. A "Test" delivery from GitLab's settings is an ordinary delivery.
+ * - event key: `<object_kind>.<the second part>`, or `<object_kind>` when it has no second part.
+ *   The second part is `object_attributes.noteable_type` for a `note`, and else
+ *   `object_attributes.action`, then `object_attributes.status`: `merge_request.approved`,
+ *   `note.MergeRequest`, `pipeline.success`.
+ * - delivery id: `Idempotency-Key` (the same on a retry), else `X-Gitlab-Event-UUID`. (From
+ *   GitLab's docs; not checked against a real delivery.)
+ * - `onBehalfOf`: `user.username`.
+ * - answer: the outcome (the default). No person reads it.
+ */
+export const gitlab = defineHookKind({
+  api: 1,
+  id: "gitlab",
+  events: gitlabEvents,
+  verify: { token: { header: "x-gitlab-token" } },
+  read: (req) => {
+    const p = json(req);
+    const kind = text(at(p, "object_kind"));
+    if (kind === undefined) throw new Error("the body has no object_kind");
+    const second =
+      kind === "note"
+        ? text(at(p, "object_attributes.noteable_type"))
+        : (text(at(p, "object_attributes.action")) ?? text(at(p, "object_attributes.status")));
+    const id = text(req.headers["idempotency-key"]) ?? text(req.headers["x-gitlab-event-uuid"]);
+    if (id === undefined) throw new Error("no Idempotency-Key or X-Gitlab-Event-UUID header");
+    const by = text(at(p, "user.username"));
+    return {
+      key: second ? `${kind}.${second}` : kind,
+      id,
+      payload: p,
+      ...(by ? { onBehalfOf: by } : {}),
+    };
+  },
+});
+
+declare module "./index.ts" {
+  interface HookKinds {
+    gitlab: typeof gitlab;
+  }
+}

package/src/hook-kinds/hook.ts

@@ -0,0 +1,7 @@
+// The key that a Hook value keeps its parts under. Internal: `defineHookKind` (./index.ts) writes
+// it and the door (./door.ts) reads it. A kind never imports this module.
+//
+// `Symbol.for`, so that the key is the same in each copy of this module. The Kit image holds one
+// copy of `@jr2/orchestrator` (ADR-0069), so a second copy is a fault, but the key does not depend on it.
+
+export const HOOK: unique symbol = Symbol.for("@jr2/orchestrator/hooks.hook");