@jr2/orchestrator 0.5.1 → 0.7.0

package/src/effector-wire.ts

@@ -14,6 +14,7 @@
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { lookup } from "node:dns/promises";
 import { z } from "zod";
+import type { LaterOutcome } from "./effect.ts";
 
 // --- The request (POST /effects/<id>) ------------------------------------------------------------
 //
@@ -104,10 +105,10 @@ export const PairShape = z.strictObject({
 });
 export type Pair = z.infer<typeof PairShape>;
 
-/** A `push` start: the Workspace's branch to the Repo Slot's Binding, with the push credential of
+/** A `push` start: a cut Worktree's branch to the Repo Slot's Binding, with the push credential of
  * the `git.credentials` entry the url falls under — the Effector's config holds the entries, and
  * matches the url as the fence does (`credential` names one by its `match` instead). `pin` is the
- * commit; absent, the Effector reads the Agent's branch tip and its answer carries it (`pinned`).
+ * commit; absent, the Effector reads the branch's tip and its answer carries it (`pinned`).
  */
 export const PushStartShape = z.strictObject({
   kind: z.literal("push"),
@@ -181,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
@@ -259,6 +313,8 @@ export const HttpOutputShape = z.union([
  * - `unknown`: the call can have gone out, but no answer came, or jr2 cannot tell after a restart.
  *   `reason` tells why. jr2 does not send it again unless it is marked `idempotent`.
  *
+ * The union is open (`LaterOutcome`): give the rest a last arm with no guard.
+ *
  * @example
  * ```ts
  * import { fail, http, jr2Setup, type HttpOutput } from "@jr2/orchestrator";
@@ -291,7 +347,7 @@ export const HttpOutputShape = z.union([
  * @see docs/guides/run-a-command-or-call-a-url.md
  * @see docs/reference/decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md
  */
-export type HttpOutput = z.infer<typeof HttpOutputShape>;
+export type HttpOutput = z.infer<typeof HttpOutputShape> | LaterOutcome;
 
 /**
  * A `push` Effect's output (ADR-0067). `pushed`: the published commit, its source (the Agent's
@@ -376,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>;
@@ -394,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/fail.ts

@@ -87,24 +87,37 @@ export type FailSlot = PromiseActorLogic<never, FailureInput> & { readonly [FAIL
  * @example
  * ```ts
  * import { z } from "zod";
- * import { command, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+ * import { command, fail, isReady, jr2Setup, workspace, worktree, type Workspaced } from "@jr2/orchestrator";
  *
  * const runInput = z.object({ branch: z.string() });
+ * type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
+ *
+ * const testTree = (context: BodyInput) => `${context.workspace.repos.app}/test` as const;
  *
  * const body = jr2Setup({
- *   types: {} as { input: Workspaced<z.infer<typeof runInput>, "app"> },
+ *   types: {} as { input: BodyInput; context: BodyInput },
  *   actors: {
+ *     cut: worktree(),
  *     tests: command(["npm", "test"], { timeout: "15m" }),
  *     fail: fail(),
  *   },
  * }).createMachine({
  *   id: "check",
+ *   context: ({ input }) => input,
  *   on: { "workspace.lost": ".lost" },
- *   initial: "testing",
+ *   initial: "cutting",
  *   states: {
+ *     cutting: {
+ *       invoke: {
+ *         src: "cut",
+ *         input: ({ context }) => ({ path: testTree(context), branch: context.branch }),
+ *         onDone: [{ guard: ({ event }) => isReady(event.output), target: "testing" }, { target: "notCut" }],
+ *       },
+ *     },
  *     testing: {
  *       invoke: {
  *         src: "tests",
+ *         input: ({ context }) => ({ worktree: testTree(context) }),
  *         onDone: [
  *           {
  *             guard: ({ event }) => event.output.outcome === "exited" && event.output.code === 0,
@@ -117,6 +130,7 @@ export type FailSlot = PromiseActorLogic<never, FailureInput> & { readonly [FAIL
  *     // Not a final state: the run ends `failed`, and the Workspace deletes the Sandbox.
  *     failing: { invoke: { src: "fail", input: { reason: "npm test did not pass" } } },
  *     passed: { type: "final" },
+ *     notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
  *     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
  *   },
  * });
@@ -124,7 +138,6 @@ export type FailSlot = PromiseActorLogic<never, FailureInput> & { readonly [FAIL
  * export const machine = workspace(body, {
  *   input: runInput,
  *   repos: { app: "https://github.com/you/app.git" },
- *   spec: ({ input }) => ({ branch: input.branch }),
  * });
  * ```
  *

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]);
+}