@jr2/orchestrator 0.6.0 → 0.7.0

package/src/effect.ts

@@ -39,7 +39,7 @@ import { randomUUID } from "node:crypto";
 import type { ActorLogic, AnyActorRef, EventObject, Snapshot } from "xstate";
 import { ambientHandlesFor, type AmbientHandles } from "./ambient.ts";
 import { boundRun, type AnyActorSystem } from "./registration.ts";
-import type { HttpMethod, HttpOutput, TextPart, WireAuth } from "./effector-wire.ts";
+import type { HttpMethod, HttpOutput, McpOutput, TextPart, WireAuth } from "./effector-wire.ts";
 import type { ExecOutcome, ExecRead, ExecRequest, SyncAnswer } from "./wire.ts";
 import { bindOpenSecretIn, type EffectorPortFactory, type OpenSecretIn } from "./http-effect.ts";
 import { commandEnvParts, credentialedCommandWith, sandboxEffectorPort, type CommandEnv } from "./sandbox-effect.ts";
@@ -240,6 +240,51 @@ export type DispatchParts = {
   readonly openSecret: boolean;
 };
 
+/** What an `mcp` Effect asks of its server (ADR-0079): call a tool, read a resource, or get a
+ * prompt. */
+export type McpOp = "call" | "read" | "prompt";
+
+/**
+ * An `mcp` Effect's plain data (ADR-0067, ADR-0079): what `jr2 up` and the Machine doc read — the
+ * operation, the server by its name in the `mcp` block of `jr2.config.ts`, the tool (a call), the
+ * resource's uri (a read) or the prompt's name (a prompt), the input's keys, the author's timeout,
+ * the bound on the output, and whether a restore may send it again. The server's url and secret
+ * are the config's, never a part: `jr2 up` reads them from there, and the Instance Effector holds
+ * them in its `effector.json` and its secrets.
+ */
+export type McpParts = {
+  readonly kind: "mcp";
+  readonly op: McpOp;
+  readonly server: string;
+  /** `mcp.call`'s tool. */
+  readonly tool?: string;
+  /** `mcp.read`'s resource uri. */
+  readonly uri?: string;
+  /** `mcp.prompt`'s prompt name. */
+  readonly prompt?: string;
+  /** The keys of the input schema: what a pick param may fill (ADR-0067's load walk reads them). */
+  readonly inputKeys: readonly string[];
+  /** The author's timeout, in milliseconds. Absent: the server's `timeout` in `jr2.config.ts`. */
+  readonly timeoutMs?: number;
+  /** The most bytes of `text`, and of `structured` as JSON, in the output. */
+  readonly maxBody: number;
+  /** Marked by the author: a restore that cannot find the Effect sends it again. The server's
+   * `idempotentHint` is not read (ADR-0079). */
+  readonly idempotent: boolean;
+  /** Always empty: an `mcp` Effect names no secret of its own. Its server's secret is placed in
+   * the Instance Effector by `jr2 up`, from the config (ADR-0079). */
+  readonly secrets: readonly string[];
+  /** Never: the server, not a `secret(open)`, is what a package leaves Open (ADR-0054). */
+  readonly openSecret?: never;
+};
+
+/** An `mcp` Effect whose server or tool a package left Open (ADR-0054, ADR-0079): the sentinel in
+ * that place, until the composer binds it with `customize()`. */
+export type OpenMcpParts = Omit<McpParts, "server" | "tool"> & {
+  readonly server: string | typeof open;
+  readonly tool?: string | typeof open;
+};
+
 /**
  * An Effect whose url or argv a package left Open (ADR-0054): the same parts with the sentinel in
  * that one place. The kind, the placement, the timeout and the secrets the other parts name are
@@ -264,10 +309,12 @@ export type EffectParts =
   | OpenCommandParts
   | OpenHttpParts
   | DispatchParts
-  | OpenDispatchParts;
+  | OpenDispatchParts
+  | McpParts
+  | OpenMcpParts;
 
 /** The kinds, as their parts name them. */
-export const EFFECT_KINDS: ReadonlySet<string> = new Set(["command", "http", "push", "dispatch"]);
+export const EFFECT_KINDS: ReadonlySet<string> = new Set(["command", "http", "push", "dispatch", "mcp"]);
 
 /**
  * Where an Effect runs, derived from its kind and what it names, never authored (ADR-0067,
@@ -275,7 +322,8 @@ export const EFFECT_KINDS: ReadonlySet<string> = new Set(["command", "http", "pu
  * `http` Effect with no Worktree file in the Instance Effector; an `http` whose body is a Worktree
  * file, a `push` and a `command` that names a secret in the Sandbox Effector of its Workspace; a
  * `dispatch` with no target in the Orchestrator's own process, and one with a target (an Open one
- * included: it has one once bound) in the Instance Effector (ADR-0071).
+ * included: it has one once bound) in the Instance Effector (ADR-0071); an `mcp` Effect in the
+ * Instance Effector, which calls remote servers only (ADR-0079).
  */
 export type Placement = "harness" | "instance" | "sandbox" | "orchestrator";
 export function placementOf(parts: EffectParts): Placement {
@@ -286,6 +334,8 @@ export function placementOf(parts: EffectParts): Placement {
       return parts.file ? "sandbox" : "instance";
     case "push":
       return "sandbox";
+    case "mcp":
+      return "instance";
     case "command":
       return (parts.secrets?.length ?? 0) > 0 || parts.openSecret ? "sandbox" : "harness";
   }
@@ -338,7 +388,7 @@ export function inputShapeOf(parts: EffectParts): InputShape | undefined {
   if (parts.kind === "dispatch") {
     return parts.inputKeys === undefined ? undefined : { required: [...parts.inputKeys], optional: [] };
   }
-  if (parts.kind === "push") return { required: [...parts.inputKeys], optional: [] };
+  if (parts.kind === "push" || parts.kind === "mcp") return { required: [...parts.inputKeys], optional: [] };
   if (parts.kind === "http") {
     return { required: [...parts.inputKeys], optional: parts.file ? ["worktree"] : [] };
   }
@@ -492,7 +542,7 @@ export type EffectRow =
   | { state: "intent"; kind: "command"; slot: string; endpoint: string; placement: string; at: string }
   /** An http Effect's intent names its placement and no replica (ADR-0068): a restore asks every
    * replica. `idempotent` is the author's mark, which the restore rule reads. */
-  | { state: "intent"; kind: "http"; slot: string; placement: "instance"; idempotent: boolean; at: string }
+  | { state: "intent"; kind: "http" | "mcp"; slot: string; placement: "instance"; idempotent: boolean; at: string }
   /** An Effect of the Sandbox Effector (ADR-0067): its Sandbox, and — for a push or a credentialed
    * command — the commit it runs against, written once the start's answer names it. A restore
    * re-attaches by id, or sends a push or a credentialed command again with only that commit, and
@@ -590,6 +640,9 @@ const TAILS: Record<EffectRow["kind"], readonly string[]> = {
   // settled marker carries both whole. The row keeps the outcome, the run id, its status and the
   // door's HTTP status (ADR-0071).
   dispatch: ["output", "report"],
+  // An mcp answer's text and its structured value: the feed's settled marker carries both whole.
+  // The row keeps the outcome, `isError` and `truncated` (ADR-0079).
+  mcp: ["text", "structured"],
 };
 
 /** A kind's tail for one output. The NEWEST push of its Repo Slot whose sync did not finish (`busy`,
@@ -702,7 +755,7 @@ export type EffectMarker = {
   effect: string;
   stage: "started" | "output" | "settled" | "aborted";
   text?: string;
-  output?: CommandOutput | WorktreeOutput | HttpOutput | DispatchOutput;
+  output?: CommandOutput | WorktreeOutput | HttpOutput | DispatchOutput | McpOutput;
 };
 
 // --- The port -----------------------------------------------------------------------------------

package/src/effector-wire.ts

@@ -182,37 +182,90 @@ export const DispatchedByShape = z.strictObject({
  * A `dispatch` start (ADR-0071), which only the Instance Effector serves: a run of `workflow` on the
  * Orchestrator at `url` (its origin, one text part), the body `input` whole, the Instance token as a
  * bearer by name, `dispatchedBy` as the `jr2-dispatched-by` header — `instance` set, since the
- * caller is foreign by construction — and, with `wait`, a poll of `GET /runs/<id>` until the run
+ * caller is foreign by construction — `onBehalfOf` as the `jr2-on-behalf-of` header, and, with
+ * `wait`, a poll of `GET /runs/<id>` until the run
  * ends or `timeoutMs` passes.
+ *
+ * `keyOnly` in place of `input`: a key-only ask, sent when the slot's schema refuses the body. The
+ * Effector sends the `jr2-key-only` header and no body; the door answers the run under the key, or
+ * `{ existing: false }`, which the Effector settles as `absent`. One of the two is set, never both.
  */
-export const DispatchStartShape = z.strictObject({
-  kind: z.literal("dispatch"),
-  url: TextShape.refine(
-    (parts) => parts.length === 1 && "text" in parts[0]! && ORIGIN.test(parts[0].text),
-    "a dispatch url is one text part, an origin: http(s)://host[:port]",
-  ),
-  workflow: z.string().regex(WORKFLOW_NAME),
-  input: z.record(z.string(), z.unknown()),
-  auth: z.strictObject({ bearer: SecretRefShape }),
-  // Every id non-empty, as the door's header shape requires (http.ts): an empty one would be the
-  // door's 400, which reads as a defect of the input. The effect is a ledger row id, the key. The Go
-  // side's `validateDispatch` holds the same rule.
-  dispatchedBy: DispatchedByShape.extend({
-    run: z.string().min(1),
-    slot: z.string().min(1),
-    effect: z
+export const DispatchStartShape = z
+  .strictObject({
+    kind: z.literal("dispatch"),
+    url: TextShape.refine(
+      (parts) => parts.length === 1 && "text" in parts[0]! && ORIGIN.test(parts[0].text),
+      "a dispatch url is one text part, an origin: http(s)://host[:port]",
+    ),
+    workflow: z.string().regex(WORKFLOW_NAME),
+    input: z.record(z.string(), z.unknown()).optional(),
+    keyOnly: z.literal(true).optional(),
+    auth: z.strictObject({ bearer: SecretRefShape }),
+    // Every id non-empty, as the door's header shape requires (http.ts): an empty one would be the
+    // door's 400, which reads as a defect of the input. The effect is a ledger row id, the key. The Go
+    // side's `validateDispatch` holds the same rule.
+    dispatchedBy: DispatchedByShape.extend({
+      run: z.string().min(1),
+      slot: z.string().min(1),
+      effect: z
+        .string()
+        .regex(/^[A-Za-z0-9._-]{1,128}$/)
+        .refine((id) => id !== "." && id !== ".."),
+      instance: z.string().min(1),
+    }),
+    wait: z.boolean(),
+    timeoutMs: z.number().int().positive(),
+    // The first Caller of the calling run's chain (ADR-0071, ADR-0078), sent as the
+    // `jr2-on-behalf-of` header: printable ASCII, as a header value is, and at most what the door
+    // takes. The other Instance records it and does not check it.
+    onBehalfOf: z
       .string()
-      .regex(/^[A-Za-z0-9._-]{1,128}$/)
-      .refine((id) => id !== "." && id !== ".."),
-    instance: z.string().min(1),
-  }),
-  wait: z.boolean(),
-  timeoutMs: z.number().int().positive(),
-});
+      .regex(/^[\x20-\x7e]{1,256}$/)
+      .optional(),
+  })
+  .refine(
+    (req) => (req.input === undefined) !== (req.keyOnly === undefined),
+    "a dispatch start carries its input, or keyOnly and no input",
+  );
 export type DispatchStartRequest = z.infer<typeof DispatchStartShape>;
 
-/** Every start: the http kinds, a push, a credentialed command, a dispatch. */
-export const StartRequestShape = z.union([HttpStartShape, PushStartShape, CommandStartShape, DispatchStartShape]);
+/** An MCP server's name (ADR-0079), as the `mcp` block of `jr2.config.ts` keys it. The Go side's
+ * `mcpServer` is the same rule. */
+export const MCP_SERVER = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * An `mcp` start (ADR-0067, ADR-0079), which only the Instance Effector serves: the server by its
+ * name — the Effector reads its url and the name of its secret from `effector.json`, so neither is
+ * on the wire — and one request: `call` a tool with its arguments, `read` a resource, or get a
+ * `prompt` with its arguments. `timeoutMs` is the author's; absent, the server's `timeout` from
+ * `effector.json` applies. `maxBody` bounds the answer's `text` and its `structured` value.
+ */
+export const McpStartShape = z.strictObject({
+  kind: z.literal("mcp"),
+  mcp: z
+    .strictObject({
+      server: z.string().regex(MCP_SERVER),
+      call: z.strictObject({ tool: z.string().min(1), arguments: z.record(z.string(), z.unknown()) }).optional(),
+      read: z.strictObject({ uri: z.string().min(1) }).optional(),
+      prompt: z.strictObject({ name: z.string().min(1), arguments: z.record(z.string(), z.string()) }).optional(),
+    })
+    .refine(
+      (m) => [m.call, m.read, m.prompt].filter((x) => x !== undefined).length === 1,
+      "an mcp start carries exactly one of call, read, prompt",
+    ),
+  timeoutMs: z.number().int().positive().optional(),
+  maxBody: z.number().int().positive(),
+});
+export type McpStartRequest = z.infer<typeof McpStartShape>;
+
+/** Every start: the http kinds, a push, a credentialed command, a dispatch, an mcp request. */
+export const StartRequestShape = z.union([
+  HttpStartShape,
+  PushStartShape,
+  CommandStartShape,
+  DispatchStartShape,
+  McpStartShape,
+]);
 export type StartRequest = z.infer<typeof StartRequestShape>;
 
 /** The most bytes of a start's body the Effector reads (its `maxRequestBody`). A longer body
@@ -379,9 +432,92 @@ export const DispatchOutputShape = z.discriminatedUnion("outcome", [
   z.strictObject({ outcome: z.literal("refused"), status: z.number().int(), report: z.array(z.string()) }),
   z.strictObject({ outcome: z.literal("unreachable"), reason: z.string() }),
   z.strictObject({ outcome: z.literal("unknown"), reason: z.string() }),
+  // The answer to a key-only ask when no run has the key (ADR-0071): nothing was started. Wire
+  // only: the driver makes it the invoke's error, the slot's schema refusal, and the Machine never
+  // reads it.
+  z.strictObject({ outcome: z.literal("absent") }),
 ]);
 export type DispatchWireOutput = z.infer<typeof DispatchOutputShape>;
 
+/**
+ * An `mcp` Effect's output on the wire (ADR-0067, ADR-0079): `returned`, with `isError` for a call
+ * alone; or a reason for `refused`, `unreachable`, `input-required` and `unknown`.
+ */
+export const McpOutputShape = z.union([
+  z.strictObject({
+    outcome: z.literal("returned"),
+    isError: z.boolean().optional(),
+    text: z.string(),
+    structured: z.unknown().optional(),
+    truncated: z.boolean().optional(),
+  }),
+  z.strictObject({
+    outcome: z.enum(["refused", "unreachable", "input-required", "unknown"]),
+    reason: z.string(),
+  }),
+]);
+
+/** The outcomes that an `mcp` Effect gives besides `returned`. Each one has a `reason` in words. */
+type McpNotReturned =
+  | { outcome: "refused"; reason: string }
+  | { outcome: "unreachable"; reason: string }
+  | { outcome: "input-required"; reason: string }
+  | { outcome: "unknown"; reason: string }
+  | LaterOutcome;
+
+/**
+ * The output of an `mcp.call` Effect: what the `onDone` of its state gets as `event.output`. Every
+ * outcome is output. Route on `outcome`:
+ *
+ * - `returned`: the server answered the call. `isError` is the tool's own `isError`: the tool ran
+ *   and says that it failed. `text` joins the text of the result's content; a part that is not text
+ *   is one line that names its type. `structured` is the result's `structuredContent`, when it has
+ *   one. `text` and `structured` each have the byte bound of the Effect's `maxBody`: past it, jr2
+ *   cuts `text`, drops `structured`, and sets `truncated`.
+ * - `refused`: the request did not run. The server answered an HTTP 3xx or 4xx status (a 401 or a
+ *   403 included) at any step, the handshake too; it refused the handshake; or it answered the
+ *   request with the JSON-RPC error `-32700`, `-32600`, `-32601` or `-32602`: a request that it
+ *   could not read, an unknown method, an unknown tool, or bad arguments; or it answered a read with
+ *   `-32002`: the resource does not exist. It is also the Effector's
+ *   own refusal, with nothing sent: the server or its secret is not in its `effector.json`.
+ * - `unreachable`: nothing of the request was sent: the name did not resolve, or the connection,
+ *   TLS or the handshake failed otherwise (a 5xx, the timeout, an answer that is not MCP's, a
+ *   revision of MCP that jr2 does not speak).
+ * - `input-required`: the server asked for input, which jr2 does not give. After the error
+ *   `-32042`, the tool did not run. After an `elicitation/create` request, which comes while the
+ *   tool runs, the tool may have begun. jr2 does not send the request again: a Machine that
+ *   invokes the Effect again after a Gate can run a part of the tool two times.
+ * - `unknown`: the request was sent and no answer came (the timeout, a reset, a stream that ended
+ *   first), or the server answered with a 5xx or another JSON-RPC error. The tool may have acted.
+ *   jr2 does not send it again unless it is marked `idempotent`.
+ *
+ * jr2 replaces each value of an Effect secret that the Effector holds with `[secret:<name>]`, in
+ * every string of the output. The union is open ({@link LaterOutcome}): give the rest a last arm
+ * with no guard.
+ *
+ * @see docs/concepts/effects.md
+ * @see docs/reference/decisions/0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md
+ */
+export type McpCallOutput =
+  | { outcome: "returned"; isError: boolean; text: string; structured?: unknown; truncated?: boolean }
+  | McpNotReturned;
+
+/**
+ * The output of an `mcp.read` or an `mcp.prompt` Effect. Its outcomes are those of
+ * {@link McpCallOutput}, with no `isError`. For a read, `text` joins the text of the resource's
+ * contents, and `structured` is the `contents` list: a blob is given only as its `mimeType` and its
+ * size. For a prompt, `text` joins the text of the prompt's messages, and `structured` is the
+ * `messages` list. Past the bound, `structured` is dropped and `truncated` is set.
+ *
+ * @see docs/concepts/effects.md
+ */
+export type McpReadOutput =
+  | { outcome: "returned"; text: string; structured?: unknown; truncated?: boolean }
+  | McpNotReturned;
+
+/** The output of any `mcp` Effect: a call's, a read's or a prompt's. */
+export type McpOutput = McpCallOutput | McpReadOutput;
+
 /** The replica that holds an Effect, and where to poll it. */
 export const ReplicaShape = z.strictObject({ name: z.string(), address: z.string() });
 export type Replica = z.infer<typeof ReplicaShape>;
@@ -397,13 +533,122 @@ export const EffectStateShape = z.strictObject({
   /** The run a dispatch started, once the door answered and while its wait runs: the Orchestrator
    * writes it to the ledger's intent row, so the caller names its callee during the wait (ADR-0071). */
   run: z.string().optional(),
-  output: z.union([HttpOutputShape, PushOutputShape, CommandOutputShape, DispatchOutputShape]).optional(),
+  output: z
+    .union([HttpOutputShape, PushOutputShape, CommandOutputShape, DispatchOutputShape, McpOutputShape])
+    .optional(),
 });
 export type EffectState = z.infer<typeof EffectStateShape>;
 
 /** A refusal's body: the reason, and the replica when it names one. */
 export const RefusalShape = z.strictObject({ error: z.string(), replica: ReplicaShape.optional() });
 
+// --- The `mac` check (POST /mac, ADR-0068, ADR-0078) ---------------------------------------------
+//
+// A Hook's `mac` verifier: the Orchestrator builds the bytes that the service signed, and the
+// Instance Effector, which holds the secret, computes the HMAC over them and compares it with the
+// signature in constant time. The answer is "match" or "no match", and nothing more: no HMAC and no
+// secret ever comes back. The Orchestrator makes every check that needs no secret (the window)
+// before it asks.
+
+/** The HMAC algorithms of a `mac` check. */
+export const MAC_ALGS = ["sha256", "sha1", "sha512"] as const;
+
+/** A `mac` check: the NAME of the secret, the algorithm, the signed bytes and the signature, each
+ * in base64. */
+export const MacRequestShape = z.strictObject({
+  // A secret's name, as the Effector reads it: a file under its secrets mount.
+  secret: z
+    .string()
+    .regex(/^[A-Za-z0-9._-]{1,253}$/)
+    .refine((name) => !name.startsWith("."), "a secret's name does not start with ."),
+  alg: z.enum(MAC_ALGS),
+  bytes: z.base64(),
+  signature: z.base64(),
+});
+export type MacRequest = z.infer<typeof MacRequestShape>;
+
+/** The answer to a `mac` check: whether the HMAC of the bytes with the secret is the signature. */
+export const MacAnswerShape = z.strictObject({ match: z.boolean() });
+export type MacAnswer = z.infer<typeof MacAnswerShape>;
+
+/** The path of a `mac` check on the Instance Effector. */
+export const MAC_PATH = "/mac";
+
+/** The `mac` check, as the Hook's door asks it: `true` for a match. It rejects when no Effector can
+ * answer, and the door then answers 503. */
+export type HookMac = (req: {
+  secret: string;
+  alg: (typeof MAC_ALGS)[number];
+  bytes: Uint8Array;
+  signature: Uint8Array;
+}) => Promise<boolean>;
+
+/**
+ * The `mac` check over the Instance Effector's signed wire (ADR-0068): one replica, any one, since
+ * each holds the same secrets. A replica that was never reached is passed over for the next. An
+ * answer is trusted only with the Effector's signature, as an Effect's is.
+ */
+export function createMacClient(opts: {
+  key: Buffer | string;
+  transport: EffectorTransport;
+  now?: () => number;
+}): HookMac {
+  const now = opts.now ?? Date.now;
+  return async ({ secret, alg, bytes, signature }) => {
+    const body = JSON.stringify({
+      secret,
+      alg,
+      bytes: Buffer.from(bytes).toString("base64"),
+      signature: Buffer.from(signature).toString("base64"),
+    } satisfies MacRequest);
+    const addresses = shuffle(await opts.transport.replicas().catch(notSent));
+    if (addresses.length === 0) throw new EffectorNotSent("no Effector replica is serving");
+    let last: unknown;
+    for (const address of addresses) {
+      const time = String(now());
+      const nonce = randomBytes(16).toString("hex");
+      const headers = {
+        "content-type": "application/json",
+        [HEADER_TIME]: time,
+        [HEADER_NONCE]: nonce,
+        [HEADER_SIGNATURE]: requestMac(opts.key, "POST", address, MAC_PATH, time, nonce, body),
+      };
+      let answer: RawAnswer;
+      try {
+        answer = await opts.transport.send(address, "POST", MAC_PATH, headers, body);
+      } catch (err) {
+        if (neverReached(err)) {
+          last = err;
+          continue;
+        }
+        throw err;
+      }
+      const want = responseMac(opts.key, answer.status, "POST", MAC_PATH, nonce, answer.body);
+      if (!sameString(answer.headers[HEADER_SIGNATURE] ?? "", want)) {
+        throw new EffectorForged(
+          `the answer to POST ${MAC_PATH} from ${address} does not carry the Effector's signature`,
+        );
+      }
+      if (answer.status === 503) {
+        last = new EffectorNotSent(`the Effector replica at ${address} is stopping`);
+        continue;
+      }
+      if (answer.status !== 200) {
+        const refusal = RefusalShape.safeParse(parseJson(answer.body));
+        throw new Error(
+          `the Effector answered a mac check with ${answer.status}: ${refusal.success ? refusal.data.error : "no reason"}`,
+        );
+      }
+      const parsed = MacAnswerShape.safeParse(parseJson(answer.body));
+      if (!parsed.success) throw new EffectorMalformed("the Effector's answer to a mac check is not the wire's shape");
+      return parsed.data.match;
+    }
+    throw last instanceof EffectorNotSent
+      ? last
+      : new EffectorNotSent(`no Effector replica answered: ${(last as Error | undefined)?.message ?? "none"}`);
+  };
+}
+
 // --- Signatures ----------------------------------------------------------------------------------
 
 export const HEADER_TIME = "x-jr2-time";

package/src/gate-brand.ts

@@ -0,0 +1,16 @@
+// The brand of a Gate slot (ADR-0011), alone in its module: the walk (setup.ts, party.ts,
+// effect-checks.ts) and the Chart door read it, and gate.ts imports the registration table, which
+// imports party.ts. A leaf with no imports lets each of them ask without a cycle.
+
+/** Is this actor logic a Gate slot (`gate({ … })`)? A duck test on the brand, as `isAgent` is. */
+export function isGateSlotLogic(logic: unknown): boolean {
+  if (typeof logic !== "object" || logic === null) return false;
+  const parts = (logic as { gateSlot?: { delivers?: unknown } }).gateSlot;
+  return typeof parts === "object" && parts !== null && Array.isArray(parts.delivers);
+}
+
+/** Does this invoke run a Gate: the plain `gate`, or a Gate slot? */
+export function isGateInvoke(inv: { src?: unknown } | undefined, actors: Record<string, unknown>): boolean {
+  if (inv?.src === "gate") return true;
+  return typeof inv?.src === "string" && isGateSlotLogic(actors[inv.src]);
+}