@jr2/orchestrator 0.5.1 → 0.7.0

package/src/mcp-effect.ts

@@ -0,0 +1,424 @@
+// The `mcp` Effect (ADR-0067, ADR-0079): call a tool of an MCP server, read one of its resources,
+// or get one of its prompts, from the Instance Effector, with the server's secret that the Agent
+// never reads. It has the shape of `http`, with a server and a tool in place of a url:
+//
+//   post: mcp.call("slack-acme", "post_message", { input: z.object({ channel: z.string(), text: z.string() }) })
+//
+// The server is a name of the `mcp` block of `jr2.config.ts`: its url and its secret are the
+// config's, never a part and never a param. `jr2 up` places the secret in the Instance Effector as
+// an Effect secret and writes the server into `effector.json`; the start names the server alone,
+// so the Effector reads the url and the secret from what `jr2 up` wrote. An Agent's param reaches
+// the tool's arguments only (or a prompt's), through the input.
+//
+// The driver is the Instance Effector's, shared with `http` (`instanceEffectLogic`): the
+// write-ahead intent row, the restore rule (at most once unless the author marks it idempotent;
+// the server's `idempotentHint` is not read), a forged answer, and D1.
+
+import type { z } from "zod";
+import type { Duration, EffectLogic, McpOp, McpParts, OpenMcpParts } from "./effect.ts";
+import {
+  createEffectorClient,
+  MCP_SERVER,
+  nodeEffectorTransport,
+  type McpCallOutput,
+  type McpReadOutput,
+  type McpStartRequest,
+} from "./effector-wire.ts";
+import { instanceEffectLogic, type EffectorPortFactory } from "./http-effect.ts";
+import { open } from "./open.ts";
+import { effectBindingShape, openEffectLogic, openPartsOf, type OpenOf } from "./open-effect.ts";
+
+/** The options of an `mcp` Effect. */
+export type McpOptions<S extends z.ZodObject | undefined = undefined> = {
+  /**
+   * The zod schema of the input of the Effect: what the `input` of the `invoke`, or `fromPick`,
+   * gives it. For `mcp.call` the parsed input is the tool's arguments; for `mcp.prompt`, the
+   * prompt's arguments, each a string. jr2 parses the input with it before the call. When it
+   * starts, input that does not agree with it makes the Effect fail (its `onError` route): `mcp
+   * "<slot>": its input does not match the definition's input schema — <path>: <message>`. With no
+   * schema, the input of the `invoke` is the arguments as it is, and `{}` when it has none.
+   */
+  input?: S;
+  /**
+   * How long jr2 waits for the answer: a number and a unit, such as `"30s"` or `"2m"`. Default:
+   * the server's `timeout` in `jr2.config.ts` (60 seconds when it sets none). With no answer in
+   * that time, the output is `unknown`. It refuses a value that is not a positive duration: `mcp:
+   * timeout "<timeout>" is not a positive duration (like "30s", "2m")`.
+   */
+  timeout?: Duration;
+  /**
+   * The largest number of bytes of `text`, and of `structured` as JSON, that the output keeps.
+   * Default 65536. Past it, jr2 cuts `text`, drops `structured`, and sets `truncated`. It refuses
+   * a value that is not a positive whole number: `mcp({ maxBody }): a positive number of bytes`.
+   */
+  maxBody?: number;
+  // The restore rule (ADR-0067): the author's mark alone. The server's `idempotentHint` is the
+  // server's word, not the author's (ADR-0079).
+  /**
+   * `true` when it is safe to send the request two times: the tool only reads, or it has its own
+   * idempotency key. Default `false`. After an Orchestrator restart, jr2 cannot always tell if the
+   * request went out. Then it sends an idempotent one again, and gives any other the output
+   * `unknown`. jr2 does not read the tool's `idempotentHint`.
+   */
+  idempotent?: boolean;
+};
+
+/** @internal */
+export type McpInput<S> = S extends z.ZodObject ? z.infer<S> : void;
+
+/** Which parts of an `mcp` Effect are Open, by the values the author wrote. @internal */
+export type McpOpenParts<V, T> = (V extends typeof open ? "server" : never) | (T extends typeof open ? "tool" : never);
+
+const DEFAULT_MAX_BODY = 65_536;
+
+/** The definition of one `mcp` Effect, as the three constructors give it. */
+type McpDefinition = {
+  op: McpOp;
+  server: string | typeof open;
+  /** The tool (a call), the resource's uri (a read) or the prompt's name (a prompt). */
+  name: string | typeof open;
+  options: McpOptions<z.ZodObject | undefined>;
+};
+
+const WHAT: Record<McpOp, string> = { call: "tool", read: "uri", prompt: "prompt name" };
+
+/** The definition's plain data, checked: every refusal names what to write instead. */
+function mcpPartsOf(def: McpDefinition): OpenMcpParts {
+  const { op, server, name, options } = def;
+  if (server !== open && (typeof server !== "string" || !MCP_SERVER.test(server) || server === "jr2")) {
+    throw new Error(
+      `mcp.${op}(server): ${JSON.stringify(server)} is not a server name — a name of the mcp block of ` +
+        'jr2.config.ts, lowercase letters, digits and -, not "jr2"; or `open`, which the composer binds (ADR-0079)',
+    );
+  }
+  if (name === open && op !== "call") {
+    throw new Error(`mcp.${op}(): its ${WHAT[op]} is the author's, never Open — only a call's tool is (ADR-0079)`);
+  }
+  if (name !== open && (typeof name !== "string" || name === "")) {
+    throw new Error(`mcp.${op}(): the ${WHAT[op]} is a non-empty string`);
+  }
+  const maxBody = options.maxBody ?? DEFAULT_MAX_BODY;
+  if (!Number.isInteger(maxBody) || maxBody <= 0) throw new Error("mcp({ maxBody }): a positive number of bytes");
+  const timeoutMs = options.timeout === undefined ? undefined : parseDuration(options.timeout);
+  const shape = (options.input as { shape?: unknown } | undefined)?.shape;
+  if (op === "prompt" && shape && typeof shape === "object") {
+    for (const [key, field] of Object.entries(shape)) {
+      if (!isStringSchema(field)) {
+        throw new Error(
+          `mcp.prompt(${JSON.stringify(name)}): the input field "${key}" is not a string schema, and a prompt's ` +
+            "arguments are strings (MCP's prompts/get)",
+        );
+      }
+    }
+  }
+  return {
+    kind: "mcp",
+    op,
+    server,
+    ...(op === "call" ? { tool: name } : op === "read" ? { uri: name as string } : { prompt: name as string }),
+    inputKeys: shape && typeof shape === "object" ? Object.keys(shape) : [],
+    ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+    maxBody,
+    idempotent: options.idempotent === true,
+    secrets: [],
+  };
+}
+
+/**
+ * The wire request for one run: the server, the operation and its arguments.
+ *
+ * @internal
+ */
+export function mcpStartOf(parts: McpParts, args: Record<string, unknown>): McpStartRequest {
+  const request =
+    parts.op === "call"
+      ? { call: { tool: parts.tool!, arguments: args } }
+      : parts.op === "read"
+        ? { read: { uri: parts.uri! } }
+        : { prompt: { name: parts.prompt!, arguments: promptArguments(args) } };
+  return {
+    kind: "mcp",
+    mcp: { server: parts.server, ...request },
+    ...(parts.timeoutMs !== undefined ? { timeoutMs: parts.timeoutMs } : {}),
+    maxBody: parts.maxBody,
+  };
+}
+
+/** The schema types whose value is a string, and the wrappers that leave it one when present. */
+const STRING_TYPES = new Set(["string", "enum", "literal", "template_literal"]);
+const WRAPPERS = new Set(["optional", "default", "prefault", "catch", "readonly", "nonoptional"]);
+
+/** Whether a zod field's value is a string (or absent): what a prompt's argument may be. */
+function isStringSchema(field: unknown): boolean {
+  let def = (field as { _zod?: { def?: { type?: string; innerType?: unknown; values?: unknown[] } } })?._zod?.def;
+  while (def?.type !== undefined && WRAPPERS.has(def.type)) {
+    def = (def.innerType as { _zod?: { def?: typeof def } } | undefined)?._zod?.def;
+  }
+  if (def?.type === undefined || !STRING_TYPES.has(def.type)) return false;
+  return def.values === undefined || def.values.every((v) => typeof v === "string");
+}
+
+/** A prompt's arguments are strings (MCP's `prompts/get`): another value is a defect of the Machine. */
+function promptArguments(args: Record<string, unknown>): Record<string, string> {
+  for (const [key, value] of Object.entries(args)) {
+    if (typeof value !== "string") {
+      throw new Error(`mcp.prompt: the argument "${key}" is ${typeof value}, and a prompt's arguments are strings`);
+    }
+  }
+  return args as Record<string, string>;
+}
+
+/**
+ * The slot logic of an `mcp` Effect over an injected port factory: the seam the constructors and
+ * the unit tests share, as `httpWith` is for an http Effect.
+ *
+ * @internal
+ */
+export function mcpWith<O>(portFactory: EffectorPortFactory, def: McpDefinition): EffectLogic<unknown, O> {
+  const parts = mcpPartsOf(def);
+  const opened = openPartsOf(parts);
+  if (opened.length > 0) {
+    return openEffectLogic(parts, opened, (binding) => {
+      const keys = Object.keys(binding).filter((k) => (binding as Record<string, unknown>)[k] !== undefined);
+      if (keys.some((k) => k !== "server" && k !== "tool")) {
+        throw new Error(
+          `an mcp Effect's Open parts are its server and its tool — bind it with ${effectBindingShape(opened)}`,
+        );
+      }
+      return mcpWith(portFactory, {
+        ...def,
+        ...(binding.server !== undefined ? { server: binding.server } : {}),
+        ...(binding.tool !== undefined ? { name: binding.tool } : {}),
+      }) as EffectLogic<unknown, unknown>;
+    }) as unknown as EffectLogic<unknown, O>;
+  }
+  const bound = parts as McpParts;
+  const target = bound.op === "call" ? `${bound.server}/${bound.tool}` : `${bound.server} ${bound.op}`;
+  return instanceEffectLogic<unknown, O>(
+    bound,
+    {
+      kind: "mcp",
+      idempotent: bound.idempotent,
+      label: `mcp ${target}`,
+      request: (input, slot) => {
+        let args: unknown = input ?? {};
+        const schema = def.options.input;
+        if (schema !== undefined) {
+          const parsed = schema.safeParse(input);
+          if (!parsed.success) {
+            throw new Error(
+              `mcp "${slot}": its input does not match the definition's input schema — ` +
+                parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; "),
+            );
+          }
+          args = parsed.data;
+        }
+        if (typeof args !== "object" || args === null || Array.isArray(args)) {
+          throw new Error(`mcp "${slot}": its input is the request's arguments, an object`);
+        }
+        return mcpStartOf(bound, args as Record<string, unknown>);
+      },
+    },
+    portFactory,
+  );
+}
+
+/** The real port: the Instance Effector's headless Service, over its signed wire. */
+const instancePort: EffectorPortFactory = (target) =>
+  createEffectorClient({ key: target.key, transport: nodeEffectorTransport(target.service) });
+
+/** A duration as milliseconds, a whole number of 1 or more. */
+function parseDuration(d: Duration): number {
+  const m = /^(\d+(?:\.\d+)?)(s|m|h)$/.exec(d);
+  const ms = m === null ? 0 : Math.round(Number(m[1]) * (m[2] === "h" ? 3_600_000 : m[2] === "m" ? 60_000 : 1000));
+  if (!(ms >= 1)) {
+    throw new Error(`mcp: timeout "${d}" is not a positive duration (like "30s", "2m")`);
+  }
+  return ms;
+}
+
+/**
+ * Call a tool of an MCP server: an Effect that the Machine runs, with no model. Put it in
+ * `actors`, and invoke it by its key: `actors: { post: mcp.call("slack-acme", "post_message", {
+ * input }) }`, then `invoke: { src: "post" }`.
+ *
+ * `server` is a name of the `mcp` block of `jr2.config.ts`: a remote server, whose url and secret
+ * are the config's. The Effect runs in the Instance Effector, which holds that secret as an Effect
+ * secret and sends it as `Authorization: Bearer <value>`. The Agent and the Orchestrator never read
+ * it. `jr2 up` refuses a server that the `mcp` block does not declare, and a stdio server: an `mcp`
+ * Effect calls a remote server only.
+ *
+ * `server` and `tool` can each be `open`: a packaged Machine that cannot know them leaves them
+ * Open, and the composer binds them one time with `customize(machine, { effects: { <slot>: {
+ * server, tool } } })`.
+ *
+ * Every outcome is output ({@link McpCallOutput}): `returned`, `refused`, `unreachable`,
+ * `input-required` or `unknown`. A tool's own error is `returned` with `isError: true`. jr2 sends
+ * the call at most one time, unless you mark it `idempotent`. When its state exits while the call
+ * runs, jr2 stops waiting for it. The Effector can still send it.
+ *
+ * This is how an Agent's request gets an approval: the Agent picks, a Gate waits for a person,
+ * and the Effect makes the call. The Effect's output is the pick's answer.
+ *
+ * @param server - A server name of the `mcp` block of `jr2.config.ts`, or `open`.
+ * @param tool - The tool's name, or `open`.
+ * @param options - The input schema, the timeout, the output bound, and `idempotent`.
+ * @returns An Effect, for `actors`.
+ *
+ * @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
+ * @see docs/reference/decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md
+ */
+function call<
+  const V extends string | typeof open,
+  const T extends string | typeof open,
+  S extends z.ZodObject | undefined = undefined,
+>(
+  server: V,
+  tool: T,
+  options: McpOptions<S> = {},
+): EffectLogic<McpInput<S>, McpCallOutput> & OpenOf<McpOpenParts<V, T>> {
+  return mcpWith(instancePort, { op: "call", server, name: tool, options }) as EffectLogic<McpInput<S>, McpCallOutput> &
+    OpenOf<McpOpenParts<V, T>>;
+}
+
+/**
+ * Read a resource of an MCP server: an Effect that the Machine runs, with no model. `server` is
+ * as {@link mcp}`.call` takes it, and can be `open`. `uri` is the author's, never Open and never a
+ * param. The output is {@link McpReadOutput}: `text` joins the text of the resource's contents,
+ * and `structured` is the `contents` list. jr2 sends it at most one time, unless you mark it
+ * `idempotent`.
+ *
+ * @param server - A server name of the `mcp` block of `jr2.config.ts`, or `open`.
+ * @param uri - The resource's uri.
+ * @param options - The timeout, the output bound, and `idempotent`.
+ * @returns An Effect, for `actors`.
+ *
+ * @see docs/concepts/effects.md
+ */
+function read<const V extends string | typeof open>(
+  server: V,
+  uri: string,
+  options: Omit<McpOptions, "input"> = {},
+): EffectLogic<void, McpReadOutput> & OpenOf<McpOpenParts<V, string>> {
+  return mcpWith(instancePort, { op: "read", server, name: uri, options }) as EffectLogic<void, McpReadOutput> &
+    OpenOf<McpOpenParts<V, string>>;
+}
+
+/**
+ * Get a prompt of an MCP server: an Effect that the Machine runs, with no model. `server` is as
+ * {@link mcp}`.call` takes it, and can be `open`. `name` is the author's. The input is the
+ * prompt's arguments, each a string. The output is {@link McpReadOutput}: `text` joins the text of
+ * the prompt's messages, and `structured` is the `messages` list.
+ *
+ * @param server - A server name of the `mcp` block of `jr2.config.ts`, or `open`.
+ * @param name - The prompt's name.
+ * @param options - The input schema, the timeout, the output bound, and `idempotent`.
+ * @returns An Effect, for `actors`.
+ *
+ * @see docs/concepts/effects.md
+ */
+function prompt<const V extends string | typeof open, S extends z.ZodObject | undefined = undefined>(
+  server: V,
+  name: string,
+  options: McpOptions<S> = {},
+): EffectLogic<McpInput<S>, McpReadOutput> & OpenOf<McpOpenParts<V, string>> {
+  return mcpWith(instancePort, { op: "prompt", server, name, options }) as EffectLogic<McpInput<S>, McpReadOutput> &
+    OpenOf<McpOpenParts<V, string>>;
+}
+
+/**
+ * The `mcp` Effects (ADR-0067, ADR-0079): `mcp.call(server, tool, { input })` calls a tool,
+ * `mcp.read(server, uri)` reads a resource, and `mcp.prompt(server, name, { input })` gets a
+ * prompt. Each one is an Effect that the Machine runs, with no model, in the Instance Effector.
+ * Put it in `actors`, and invoke it by its key.
+ *
+ * `server` is a name of the `mcp` block of `jr2.config.ts`: a remote server, whose url and secret
+ * are the config's. The Instance Effector holds that secret as an Effect secret, and sends it as
+ * `Authorization: Bearer <value>`. The Agent and the Orchestrator never read it. `jr2 up` refuses
+ * a server that the `mcp` block does not declare, and a stdio server. `server`, and a call's
+ * `tool`, can each be `open`: the composer binds them one time with `customize(machine, { effects:
+ * { <slot>: { server, tool } } })`.
+ *
+ * Every outcome is output ({@link McpCallOutput}, {@link McpReadOutput}): `returned`, `refused`,
+ * `unreachable`, `input-required` or `unknown`. jr2 sends the request at most one time, unless you
+ * mark it `idempotent`. jr2 does not read the tool's `idempotentHint`.
+ *
+ * An Agent that holds a server's tools (its `mcp` list) calls them with no approval. When a call
+ * needs an approval, the Machine makes it: the Agent picks, a Gate waits for a person, and the
+ * Effect makes the call. The Effect's output is the pick's answer.
+ *
+ * @example
+ * ```ts
+ * import { assign } from "xstate";
+ * import { z } from "zod";
+ * import { agent, defineEvent, fail, gate, jr2Setup, mcp } from "@jr2/orchestrator";
+ *
+ * const postMessage = defineEvent({
+ *   name: "post_message",
+ *   description: "Post one message to the team's channel. A person approves it first.",
+ *   input: z.object({ text: z.string() }),
+ * });
+ * const approve = defineEvent({ name: "approve", input: z.object({ by: z.string() }) });
+ * const reject = defineEvent({ name: "reject", input: z.object({ by: z.string() }) });
+ *
+ * export const machine = jr2Setup({
+ *   types: {} as { context: { text: string } },
+ *   events: [postMessage, approve, reject],
+ *   actors: {
+ *     writer: agent({
+ *       model: "anthropic/claude-haiku-5-5",
+ *       instructions: "You write the release note for the team.",
+ *       workspace: "none",
+ *     }),
+ *     // A person answers it, in the Console or with `jr2 answer`.
+ *     approval: gate({ meta: z.object({ text: z.string() }), delivers: [approve, reject], look: "none" }),
+ *     // "slack-acme" is a remote server of the mcp block of jr2.config.ts.
+ *     post: mcp.call("slack-acme", "post_message", {
+ *       input: z.object({ channel: z.string(), text: z.string() }),
+ *     }),
+ *     fail: fail(),
+ *   },
+ * }).createMachine({
+ *   id: "release-note",
+ *   context: { text: "" },
+ *   on: { "agent.fault": ".failed" },
+ *   initial: "writing",
+ *   states: {
+ *     writing: {
+ *       invoke: { src: "writer", input: { prompt: "Write the release note, then post it." } },
+ *       initial: "ready",
+ *       states: {
+ *         ready: {
+ *           on: {
+ *             post_message: { target: "approving", actions: assign({ text: ({ event }) => event.text }) },
+ *           },
+ *         },
+ *         approving: {
+ *           invoke: { src: "approval", input: ({ context }) => ({ meta: { text: context.text } }) },
+ *           on: { approve: "posting", reject: "ready" },
+ *         },
+ *         posting: {
+ *           invoke: {
+ *             src: "post",
+ *             input: ({ context }) => ({ channel: "#releases", text: context.text }),
+ *             // On another outcome, the Agent reads the output as the answer to its pick.
+ *             onDone: [
+ *               { guard: ({ event }) => event.output.outcome === "returned" && !event.output.isError, target: "#posted" },
+ *               { target: "ready" },
+ *             ],
+ *           },
+ *         },
+ *       },
+ *     },
+ *     posted: { id: "posted", type: "final" },
+ *     failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+ *   },
+ * });
+ * ```
+ *
+ * @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 const mcp: { readonly call: typeof call; readonly read: typeof read; readonly prompt: typeof prompt } =
+  Object.freeze({ call, read, prompt });

package/src/model-keys.ts

@@ -50,3 +50,27 @@ export const SIGNING_CREDENTIALS: readonly string[] = [
   "AWS_PROFILE",
   "GOOGLE_APPLICATION_CREDENTIALS",
 ];
+
+/**
+ * Names whose value is the path of a credential or trust file that the Harness PROCESS reads (the
+ * AWS SDK, Google's library), when `harness.env` or `harness.envFrom` sets one (ADR-0076). The
+ * Harness runs with the control Stand-in in its memory, so such a file must be one that the Agent's
+ * code cannot write: `~/.aws/config` can name a `credential_process`, which the SDK runs. `jr2 up`
+ * refuses a path that the domain writes for certain (`DOMAIN_WRITABLE_ROOTS`), and warns on any
+ * other, because whether the Sandbox's uid can write a path of the image is the image's, which jr2
+ * cannot read. An image's own `ENV` never reaches the Harness process.
+ */
+export const CREDENTIAL_FILES: readonly string[] = [
+  "AWS_CONFIG_FILE",
+  "AWS_SHARED_CREDENTIALS_FILE",
+  "AWS_WEB_IDENTITY_TOKEN_FILE",
+  "AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE",
+  "AWS_CA_BUNDLE",
+  "GOOGLE_APPLICATION_CREDENTIALS",
+  "GOOGLE_API_CERTIFICATE_CONFIG",
+  "CLOUDSDK_CONFIG",
+];
+
+/** Folders of a Sandbox's Harness container that the domain writes in every pod: the Worktree root,
+ * the temporary folders, `/dev/shm`, and the HOME that jr2 gives an image with no `USER`. */
+export const DOMAIN_WRITABLE_ROOTS: readonly string[] = ["/work", "/tmp", "/var/tmp", "/dev/shm", "/home/jr2"];

package/src/mount-digest.ts

@@ -1,13 +1,23 @@
-// What a mounted ConfigMap holds, as one digest (ADR-0038, ADR-0069). A publish rolls no pod, so
-// the Orchestrator reads `jr2-images` and `jr2-held` through mounts the kubelet refreshes on its
-// own period. `jr2 up` digests the data it applied, `GET /assembly` reports the digest of what the
-// process reads, and the publish waits until the two agree. Then the door's checks, and the
-// provisions that follow the converge, read the data this converge wrote.
+// What a mounted ConfigMap or digests Secret holds, as one digest (ADR-0038, ADR-0069, ADR-0078). A
+// write to one rolls no pod, so the Orchestrator reads `jr2-images`, `jr2-held` and the two digests
+// Secrets through mounts that the kubelet refreshes on its own period. `jr2 up` digests the data it
+// applied, `GET /assembly` reports the digest of what the process reads, and `jr2 up` waits until
+// the two agree. Then the door's checks and the provisions after the converge read the data that
+// this converge wrote, and a Caller token or a Hook secret that it wrote works.
 
 import { createHash } from "node:crypto";
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { HELD_CONFIGMAP, HELD_MOUNT, IMAGES_CONFIGMAP, IMAGES_MOUNT } from "./names.ts";
+import {
+  CALLER_DIGESTS_KEY,
+  CALLER_DIGESTS_SECRET,
+  HELD_CONFIGMAP,
+  HELD_MOUNT,
+  HOOK_DIGESTS_KEY,
+  HOOK_DIGESTS_SECRET,
+  IMAGES_CONFIGMAP,
+  IMAGES_MOUNT,
+} from "./names.ts";
 
 /** The ConfigMaps the Orchestrator reads through a mount, by name, and where each is mounted. */
 export const MOUNTED_CONFIGMAPS: Readonly<Record<string, string>> = {
@@ -15,7 +25,18 @@ export const MOUNTED_CONFIGMAPS: Readonly<Record<string, string>> = {
   [HELD_CONFIGMAP]: HELD_MOUNT,
 };
 
-/** One digest of a ConfigMap's `data`: the same bytes give the same digest at both ends. */
+/**
+ * The digests Secrets (ADR-0078), by name, and the key of each. For these, `GET /assembly` reports
+ * the digest of the file content that the process LOADED (`watchCallerDigests`), not of the file:
+ * the authenticator and the Hook door use what is loaded, and the poll can be some seconds behind
+ * the file. The content is digests of tokens, never a value.
+ */
+export const DIGEST_SECRETS: Readonly<Record<string, string>> = {
+  [CALLER_DIGESTS_SECRET]: CALLER_DIGESTS_KEY,
+  [HOOK_DIGESTS_SECRET]: HOOK_DIGESTS_KEY,
+};
+
+/** One digest of a mounted object's `data`: the same bytes give the same digest at both ends. */
 export function configMapDigest(data: Readonly<Record<string, string>>): string {
   const entries = Object.keys(data)
     .sort()
@@ -51,3 +72,16 @@ export async function readMountDigests(
   }
   return out;
 }
+
+/** The digest of what each digests Secret's watcher has loaded, by name (ADR-0078). A Secret with
+ * no watcher, or whose file was not read, is left out, as an absent mount is. */
+export function loadedDigests(
+  watched: Readonly<Record<string, { loaded(): string | undefined } | undefined>>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [name, watcher] of Object.entries(watched)) {
+    const digest = watcher?.loaded();
+    if (digest !== undefined) out[name] = digest;
+  }
+  return out;
+}

package/src/names.ts

@@ -18,18 +18,27 @@ export const INSTANCE_HARNESS_SERVICE = "jr2-instance-harness";
 export const INSTANCE_HARNESS_PORT = 8080;
 
 /** The Instance Effector (ADR-0068): its Deployment, headless Service, NetworkPolicy and Secret all
- * carry this name. `jr2 up` converges them when a registered Machine places an Effect there. The
+ * carry this name. `jr2 up` converges them when a registered Machine places an Effect there, or a
+ * Hook needs it (a `mac` verifier, or a kind that declares `posts`). The
  * port is the Effector's own (`JR2_EFFECTOR_PORT` default) — none of the Harness pod's ports. */
 export const INSTANCE_EFFECTOR = "jr2-instance-effector";
 export const EFFECTOR_PORT = 8082;
 
 /** Where a Harness persists its conversations, and the env var that tells it so (ADR-0031): one
  * fixed path in both placements — the Instance Harness's PersistentVolumeClaim (deploy.ts) and a
- * Sandbox's emptyDir (sandbox-kube.ts), each mounted into the Harness container alone. */
-export const CONVERSATIONS_DIR = "/conversations";
+ * Sandbox's emptyDir (sandbox-kube.ts), each mounted into the Harness container alone. It is under
+ * `/run/jr2`, as each path that the Harness holds alone is, so no process that the Harness confines
+ * can read an Agent's history or write into it (ADR-0076). */
+export const CONVERSATIONS_DIR = "/run/jr2/conversations";
 export const CONVERSATIONS_DIR_ENV = "JR2_CONVERSATIONS_DIR";
 export const CONVERSATIONS_VOLUME = "conversations";
 
+/** Where the Harness of a Sandbox listens for a person's shell (`jr2 workspace shell`, ADR-0076):
+ * a folder under `/run/jr2`, an emptyDir mounted into the Harness container alone. No process that
+ * the Harness confines can make a file there, so none can listen in the Harness's place. */
+export const SHELL_DIR = "/run/jr2/shell";
+export const SHELL_VOLUME = "shell";
+
 /** The harness config ConfigMap the stock Harness boots from (ADR-0018): what this instance can
  * REACH — the custom model provider minus its key, and the catalog providers' gateways (ADR-0059). No Agents ride it: a Machine carries its own
  * (ADR-0049), and the definition rides each admission, so this holds deployment facts alone
@@ -51,6 +60,33 @@ export const IMAGES_MOUNT = "/etc/jr2/images";
 /** The ConfigMap key, hence the filename under the mount — the two-sided contract's other half. */
 export const IMAGES_KEY = "images.json";
 
+/** The digests of the named Caller tokens (ADR-0078): one key, `CALLER_DIGESTS_KEY`, a JSON object
+ * `{ "<name>": "<sha-256 hex of the value>" }`. `jr2 up` writes it, and the Orchestrator reads it
+ * through a MOUNT and reads it again when it changes, so a rotation rolls no pod. Until the kubelet
+ * updates the mount, about a minute, the old value still works, so `jr2 up` and `jr2 caller rotate`
+ * wait until `GET /assembly` reports the new content as loaded. No value is here: each value is in
+ * its own Secret (`callerTokenSecret`), which no pod mounts. */
+export const CALLER_DIGESTS_SECRET = "jr2-caller-digests";
+/** Where the Orchestrator reads the digests. */
+export const CALLER_DIGESTS_MOUNT = "/etc/jr2/callers";
+/** The Secret's key, hence the filename under the mount. */
+export const CALLER_DIGESTS_KEY = "digests.json";
+/** The digests of the `token` Hooks' secrets (ADR-0078): one key, `HOOK_DIGESTS_KEY`, a JSON object
+ * `{ "<secret name>": "<sha-256 hex of the value>" }`. The door compares the sha-256 of a delivery's
+ * token with it, so the Orchestrator holds no Hook secret. Its own Secret, not the Caller digests':
+ * `jr2 caller rotate` writes that one whole. The Orchestrator reads it through a mount, again when
+ * it changes. */
+export const HOOK_DIGESTS_SECRET = "jr2-hook-digests";
+/** Where the Orchestrator reads the Hook digests. */
+export const HOOK_DIGESTS_MOUNT = "/etc/jr2/hooks";
+/** The Secret's key, hence the filename under the mount. */
+export const HOOK_DIGESTS_KEY = "digests.json";
+/** The Secret that holds one named Caller token's value (ADR-0078), which `jr2 caller token <name>`
+ * reads over the kube API. */
+export function callerTokenSecret(name: string): string {
+  return `jr2-caller-${name}`;
+}
+
 /** The HARNESS containers' env Secret — the literal `harness.env` values, never the Instance token
  * (ADR-0013) and never a model key (ADR-0059: those are held). */
 export const HARNESS_ENV_SECRET = "jr2-harness-env";
@@ -98,12 +134,23 @@ export const sandboxCustodianConfigMap = (sandbox: string): string => `${sandbox
  * (`workspaceHeldPod`), so the two cannot collide. */
 export const INSTANCE_HARNESS_HELD_POD = "instance";
 
-/** The Custodian's listeners (ADR-0059), all taken on every Harness pod (ADR-0005): the Harness's
- * HTTPS proxy on loopback, the kubelet's probe, and the control listener the Menu and the ask ride
- * to the Orchestrator, at the address `jr2-upload-pack` defaults to (ADR-0053). */
+/** The Custodian's ports (ADR-0059), all taken on every Harness pod (ADR-0005): the Harness's
+ * HTTPS proxy on loopback, the kubelet's probe, and the fetch listener that the ask rides to the
+ * Orchestrator, at the address `jr2-upload-pack` defaults to (ADR-0053). The agent routes are not
+ * on a port: they are on the control socket ({@link CUSTODIAN_CONTROL_SOCKET}, ADR-0076). */
 export const CUSTODIAN_PORT = 15001;
 export const CUSTODIAN_HEALTH_PORT = 15021;
-export const CUSTODIAN_CONTROL_PORT = 8081;
+export const CUSTODIAN_FETCH_PORT = 8081;
+
+/** The folder of the Custodian's control socket (ADR-0076): an emptyDir that the Harness container
+ * and the Custodian container alone mount, at this path in both. It is under `/run/jr2`, so no
+ * process that the Harness confines can make a socket here, and none can take the control
+ * listener's place while the Custodian restarts. The Custodian writes it; the Harness mounts it
+ * read-only, which still lets it connect to the socket. */
+export const CUSTODIAN_SOCKET_DIR = "/run/jr2/custodian";
+/** The control socket: the Custodian's listener for the five agent routes, which carry the control
+ * Stand-in (ADR-0059, ADR-0076). */
+export const CUSTODIAN_CONTROL_SOCKET = `${CUSTODIAN_SOCKET_DIR}/control.sock`;
 
 /** The scaffold's default deploy-key Secret name (ADR-0047/0051): what `jr2 init`'s wildcard
  * `git.credentials` entry names as its `sshKey`, and what `jr2 up`'s ssh offer generates into when
@@ -130,6 +177,34 @@ export const LABEL_REPO_BOUND = "jr2.dev/bound";
 export const ANNOTATION_REPO_IDENTITY = "jr2.dev/identity";
 export const ANNOTATION_REPO_LAST_ATTACHED = "jr2.dev/last-attached";
 
+/** What a Workspace writes on its Sandbox CR (ADR-0012, ADR-0021). The labels carry its run, its
+ * Workflow and a selector form of its path; the annotation carries the exact path, which the
+ * `jr2 workspace` verbs compare a handle with (ADR-0009). The keepalive is the Lease's stamp, and
+ * the hold mark says whether a run still holds the Sandbox: `held` from the Lease's first write,
+ * `released` when the Lease stops for the body's final state, a fault, a cancel or a parent that
+ * leaves the Workspace's state. */
+export const LABEL_SANDBOX_RUN = "jr2.dev/run";
+export const LABEL_SANDBOX_WORKFLOW = "jr2.dev/workflow";
+export const LABEL_SANDBOX_WORKSPACE = "jr2.dev/workspace";
+export const ANNOTATION_WORKSPACE_PATH = "jr2.dev/workspace-path";
+export const ANNOTATION_KEEPALIVE = "jr2.dev/keepalive";
+export const ANNOTATION_HOLD = "jr2.dev/hold";
+export const HOLD_HELD = "held";
+export const HOLD_RELEASED = "released";
+
+/** The selector form of a Workspace path for the `jr2.dev/workspace` label (ADR-0012): a label
+ * value holds at most 63 characters from `[A-Za-z0-9._-]` and starts and ends with an alphanumeric.
+ * Each other character becomes `-`; a value above 63 characters is cut and ends with a hash of the
+ * whole path. For `kubectl -l` alone: no jr2 reader selects by it. */
+export function workspaceLabel(path: string): string {
+  const form = path.replace(/[^A-Za-z0-9._-]/g, "-").replace(/^[^A-Za-z0-9]+|[^A-Za-z0-9]+$/g, "");
+  if (form.length <= 63) return form;
+  let h = 0;
+  for (const ch of path) h = (h * 31 + ch.charCodeAt(0)) | 0;
+  const hash = (h >>> 0).toString(36);
+  return `${form.slice(0, 62 - hash.length).replace(/[^A-Za-z0-9]+$/, "")}-${hash}`;
+}
+
 /** The mark one ask leaves on a Sandbox CR, per Repo key (ADR-0053): a timestamp the Orchestrator
  * writes when something inside the pod asks for a fetch. The operator copies it onto the pod, and
  * the node's cache agent takes `asked` as the later of the pod's creation and this — so a fetch