@jr2/orchestrator 0.6.0 → 0.7.0

package/src/notices.ts

@@ -27,8 +27,51 @@
 // a second read in the same conversation cannot carry it too — and a restart forgets reservations
 // along with everything else in memory. jr2 keeps no "handled" state: whether an Agent acted on a
 // notice is not the ledger's concern.
+//
+// The same ledger keeps Steering messages (ADR-0002): one transport, two kinds of body. Each entry is
+// an ENVELOPE — the address, the source, the audience, what is reserved and heard — and a BODY: a
+// Notice, or a Steering message with its author. The address is a tagged value: the body's `scope`
+// names its kind and `to` its value — `conversation` (a continued conversation's base id),
+// `workspace` (a Sandbox name), or `slot` (an Agent slot of one Machine instance, ADR-0076). A
+// message to a slot has one taker, like a conversation notice: the slot's open Turn at a step
+// boundary, or else its next Turn's admission, whose conversation does not exist yet when it is
+// sent. It RETIRES, recorded "not delivered", when its Machine instance ends (`retire`). The ledger
+// also keeps the record of each message (`steering`): its author and its outcome.
+
+import type { Notice, SteeringAuthor, SteeringMessage } from "./wire.ts";
+
+/** One body of the ledger: a Notice (a fact with no author) or a Steering message (an author's
+ * text). The body's `scope` is the kind of its address. */
+export type LedgerBody = Notice | SteeringMessage;
+
+/** What became of one Steering message (ADR-0002): `held` until a Turn of its slot hears it,
+ * `heard` once one did, `not-delivered` when its Machine instance ended first. */
+export type SteeringOutcome = "held" | "heard" | "not-delivered";
+
+/** The run's record of one Steering message: the slot it went to, its author, its text, when it was
+ * sent, and what became of it. */
+export type SteeringRecord = {
+  id: string;
+  agent: string;
+  author: SteeringAuthor;
+  text: string;
+  at: string;
+  outcome: SteeringOutcome;
+};
+
+/** How many Steering messages a run's record keeps: the newest, and every held one. A message is at
+ * most 16 KiB, so the record stays under about 1.6 MiB of a run's blob. */
+export const STEERING_RECORD_MAX = 100;
 
-import type { Notice } from "./wire.ts";
+/** The Machine path of a slot (`<machine path>/<agent>`): what ends with its Machine instance. */
+export const slotMachine = (slot: string): string => slot.slice(0, Math.max(0, slot.lastIndexOf("/")));
+
+const isSteering = (body: LedgerBody): body is SteeringMessage => body.kind === "steering";
+
+/** Whether a record is the record of this message to this slot: a message that an unheard
+ * admission carried is put back as a new entry, and its record stays the same. */
+const recordOf = (r: SteeringRecord, body: SteeringMessage, slot: string): boolean =>
+  r.agent === slot && r.at === body.at && r.text === body.text;
 
 /** Where an admission, or a step boundary, may hear notices: its continued conversation's base
  * Instance ID (ADR-0057) and its Workspace's Sandbox name. Either may be absent — a fresh Turn has no
@@ -70,7 +113,8 @@ export const AUDIENCE_SKEW_MS = 2_000;
  * own `bash` answer told them. */
 export type PendingNotice = {
   id: string;
-  notice: Notice;
+  /** The body: a Notice or a Steering message. */
+  notice: LedgerBody;
   to: string;
   source?: string;
   audience?: string[];
@@ -93,15 +137,17 @@ export type NoticeLedgerState = {
   /** Each retry ever recorded, by source and slot: a replayed raise records it once. */
   retriesSeen?: string[];
   members?: Record<string, NoticeMember[]>;
+  /** The record of the run's Steering messages, oldest first (ADR-0002). */
+  steering?: SteeringRecord[];
 };
 
 /** What one admission takes: the notices it carries, and their ids for the ledger write. */
 export type TakenNotices = {
   ids: string[];
-  notices: Notice[];
+  notices: LedgerBody[];
   /** Every notice taken, in the order of `ids`, with the source it was raised with — what `restore`
    * puts back when no model heard the admission. */
-  raised?: Array<{ notice: Notice; source?: string }>;
+  raised?: Array<{ notice: LedgerBody; source?: string }>;
 };
 
 /** What a Workspace notice's raise knows of its kill: the cut Turn's retry, the conversations its
@@ -129,6 +175,7 @@ export class NoticeLedger {
    * retry `retried`. */
   readonly #asRetry = new Map<string, string>();
   readonly #newId: () => string;
+  readonly #steering: SteeringRecord[];
 
   constructor(state: NoticeLedgerState | undefined, newId: () => string) {
     this.#pending = (state?.pending ?? []).map((p) => ({
@@ -142,6 +189,71 @@ export class NoticeLedger {
     this.#retriesSeen = new Set(state?.retriesSeen ?? []);
     this.#members = new Map(Object.entries(state?.members ?? {}).map(([ws, ms]) => [ws, ms.map((m) => ({ ...m }))]));
     this.#newId = newId;
+    this.#steering = (state?.steering ?? []).map((r) => ({ ...r }));
+  }
+
+  /** Hold a Steering message for `slot` (ADR-0002): its open Turn hears it at a step boundary, or
+   * else its next Turn's admission carries it. Recorded `held`. Answers its id. */
+  steer(message: SteeringMessage, slot: string): string {
+    const id = this.#newId();
+    this.#pending.push({ id, notice: message, to: slot });
+    this.#steering.push({
+      id,
+      agent: slot,
+      author: message.author,
+      text: message.text,
+      at: message.at,
+      outcome: "held",
+    });
+    this.#trimRecord();
+    return id;
+  }
+
+  /** The Machine instance at `machine` (a slot's Machine path) ended (ADR-0002): every message held
+   * for a slot of it, or of a Machine below it, retires, recorded `not-delivered`. With no
+   * `machine`, the run ended, and every held message retires. Answers whether anything changed. */
+  retire(machine?: string): boolean {
+    let changed = false;
+    for (const p of [...this.#pending]) {
+      if (!isSteering(p.notice)) continue;
+      const at = slotMachine(p.to);
+      if (machine !== undefined && at !== machine && !at.startsWith(`${machine}.`)) continue;
+      this.#pending.splice(this.#pending.indexOf(p), 1);
+      this.#reserved.delete(p.id);
+      this.#outcome(p.notice, p.to, "not-delivered");
+      changed = true;
+    }
+    return changed;
+  }
+
+  /** The run's record of its Steering messages, oldest first. */
+  steeringRecord(): SteeringRecord[] {
+    return this.#steering.map((r) => ({ ...r }));
+  }
+
+  /** The outcome of a message, on its record. */
+  #outcome(body: SteeringMessage, slot: string, outcome: SteeringOutcome): void {
+    const record = this.#steering.find((r) => recordOf(r, body, slot));
+    if (record !== undefined) record.outcome = outcome;
+  }
+
+  /** Whether a message's record says that it retired: one put back after its Machine ended stays
+   * retired. */
+  #retired(body: SteeringMessage, slot: string): boolean {
+    return this.#steering.some((r) => r.outcome === "not-delivered" && recordOf(r, body, slot));
+  }
+
+  /** Keep the newest {@link STEERING_RECORD_MAX} records, and every held one. */
+  #trimRecord(): void {
+    let over = this.#steering.length - STEERING_RECORD_MAX;
+    for (let i = 0; over > 0 && i < this.#steering.length; ) {
+      if (this.#steering[i]!.outcome === "held") {
+        i++;
+        continue;
+      }
+      this.#steering.splice(i, 1);
+      over--;
+    }
   }
 
   /** Raise a notice for `to` (a conversation's base id, or a Sandbox name — the notice's own
@@ -240,7 +352,7 @@ export class NoticeLedger {
 
   /** What {@link take} would reserve in this scope, reserving nothing: a step boundary asks first
    * whether a guard kill is among them, and so whether it must learn who was told. */
-  peek(scope: NoticeScope): Array<{ id: string; notice: Notice; source?: string }> {
+  peek(scope: NoticeScope): Array<{ id: string; notice: LedgerBody; source?: string }> {
     return this.#eligible(scope, scope.taker ?? scope.conversation).map((p) => ({
       id: p.id,
       notice: p.notice,
@@ -253,7 +365,17 @@ export class NoticeLedger {
    * for the other conversations: it is pending again for `taker`, the conversation that did not hear
    * it, which is a member of its audience again. Nothing changes when the notice is pending for that
    * conversation already. Answers whether anything changed. */
-  restore(notice: Notice, to: string, source?: string, taker?: string): boolean {
+  restore(notice: LedgerBody, to: string, source?: string, taker?: string): boolean {
+    // A Steering message has one taker: pending again for its slot, unless its Machine instance
+    // ended while the admission that carried it was unheard.
+    if (isSteering(notice)) {
+      const same = (p: PendingNotice) =>
+        p.to === to && isSteering(p.notice) && p.notice.at === notice.at && p.notice.text === notice.text;
+      if (this.#retired(notice, to) || this.#pending.some(same)) return false;
+      this.#pending.push({ id: this.#newId(), notice, to });
+      this.#outcome(notice, to, "held");
+      return true;
+    }
     const pending =
       source === undefined
         ? notice.scope === "workspace" && taker !== undefined
@@ -303,6 +425,7 @@ export class NoticeLedger {
       this.#reserved.delete(key);
       if (p.notice.scope !== "workspace") {
         this.#pending.splice(at, 1);
+        if (isSteering(p.notice)) this.#outcome(p.notice, p.to, "heard");
         continue;
       }
       const slot = this.#asRetry.get(key);
@@ -421,6 +544,7 @@ export class NoticeLedger {
       ...(this.#members.size === 0
         ? {}
         : { members: Object.fromEntries([...this.#members].map(([ws, ms]) => [ws, ms.map((m) => ({ ...m }))])) }),
+      ...(this.#steering.length === 0 ? {} : { steering: this.#steering.map((r) => ({ ...r })) }),
     };
   }
 
@@ -434,10 +558,14 @@ export class NoticeLedger {
         (scope.exceptPrefix === undefined || p.source === undefined || !p.source.startsWith(scope.exceptPrefix)) &&
         (p.notice.scope === "conversation"
           ? p.to === scope.conversation
-          : taker !== undefined &&
-            p.to === scope.workspace &&
-            !(p.heardBy ?? []).includes(taker) &&
-            (p.audience === undefined || p.audience.includes(taker) || this.#retryFor(p, scope, taker) !== undefined)),
+          : p.notice.scope === "slot"
+            ? p.to === scope.slot
+            : taker !== undefined &&
+              p.to === scope.workspace &&
+              !(p.heardBy ?? []).includes(taker) &&
+              (p.audience === undefined ||
+                p.audience.includes(taker) ||
+                this.#retryFor(p, scope, taker) !== undefined)),
     );
   }
 

package/src/open-body.ts

@@ -51,6 +51,7 @@ import { fail, FAILURE_GUARD, failureGuard } from "./fail.ts";
 import { agent } from "./harness-client.ts";
 import { SENT_BY } from "./party.ts";
 import { composesSandbox, sandboxPartsOf, wrapperBodyOf } from "./parts.ts";
+import { isGateSlot } from "./gate.ts";
 import { open } from "./open.ts";
 import { actorPath, boundRun } from "./registration.ts";
 import { COMPILED_CHART, jr2Setup } from "./setup.ts";
@@ -115,7 +116,9 @@ export function jsonOver(value: unknown, cap: number): boolean {
 }
 
 /** The parts of the Chart wrapper that a Chart can use, by their keys in `actors`, `guards`,
- * `actions` and `delays`. `gate: true` lends the Gate, so that a Chart can wait for an answer from
+ * `actions` and `delays`. `gates` lends Gate slots (`gate({ … })`) that hear a Hook, by slot name:
+ * the door refuses a Chart that invokes one whose `delivers` names an event that is not in the
+ * Chart's `events`. `gate: true` lends the Gate, so that a Chart can wait for an answer from
  * outside the run. `fail: true` lends the Part that fails the run, so that a Chart can end its run
  * as a Failure (ADR-0073): the Machine decides which ends a Chart can choose. A Chart can use no
  * other part. */
@@ -123,6 +126,7 @@ export type Lends = {
   agents?: string[];
   effects?: string[];
   machines?: string[];
+  gates?: string[];
   guards?: string[];
   actions?: string[];
   delays?: string[];
@@ -161,7 +165,7 @@ export type OpenBodySlot = { readonly openBody: OpenBodyDeclaration };
 /** The logic `openBody()` returns: actor logic that carries the brand. */
 export type OpenBodyLogic = UnknownActorLogic & OpenBodySlot;
 
-const LEND_KINDS = ["agents", "effects", "machines", "guards", "actions", "delays"] as const;
+const LEND_KINDS = ["agents", "effects", "machines", "gates", "guards", "actions", "delays"] as const;
 const WORKSPACE: readonly WorkspaceAccess[] = ["write", "read", "none"];
 const CEILING_KEYS = ["turns", "wallClock", "transitions", "fanOut", "size"] as const;
 const DURATION = /^(\d+(\.\d+)?)(s|m|h)$/;
@@ -170,9 +174,9 @@ const MAX_WALL_CLOCK_MS = 2_147_483_647;
 /** A name a Chart's grammar reads as its own, so a lent part by that name would be shadowed. */
 const reservedName = (kind: (typeof LEND_KINDS)[number], v: string): string | undefined => {
   if (v.includes(".")) return `"${v}" holds a dot; a lent name is a slot key, and dotted names are jr2's and xstate's`;
-  if ((kind === "agents" || kind === "effects" || kind === "machines") && v === "gate")
+  if ((kind === "agents" || kind === "effects" || kind === "machines" || kind === "gates") && v === "gate")
     return `"gate" is the kit's Gate; lend a slot of another name`;
-  if ((kind === "agents" || kind === "effects" || kind === "machines") && v === "fail")
+  if ((kind === "agents" || kind === "effects" || kind === "machines" || kind === "gates") && v === "fail")
     return `"fail" is the kit's Part that fails the run, lent as \`fail: true\`; lend a slot of another name`;
   if (kind === "actions" && (GENERIC_ACTIONS as readonly string[]).includes(v))
     return `"${v}" is a generic action every Chart has; lend an action of another name`;
@@ -520,7 +524,12 @@ const EMPTY_LENT: LentParts = { actors: {}, guards: {}, actions: {}, delays: {}
 /** The lent names of a declaration, by the implementation map each resolves in. */
 function lentNames(decl: OpenBodyDeclaration) {
   return {
-    actors: [...(decl.lends.agents ?? []), ...(decl.lends.effects ?? []), ...(decl.lends.machines ?? [])],
+    actors: [
+      ...(decl.lends.agents ?? []),
+      ...(decl.lends.effects ?? []),
+      ...(decl.lends.machines ?? []),
+      ...(decl.lends.gates ?? []),
+    ],
     guards: [...(decl.lends.guards ?? [])],
     actions: [...(decl.lends.actions ?? [])],
     delays: [...(decl.lends.delays ?? [])],
@@ -977,7 +986,7 @@ function gateInput(value: unknown, self: AnyActorRef): unknown {
   return { ...(value as Record<string, unknown>), gate: [...actorPath(self), id].join(".") };
 }
 
-function invokeOf(inv: ChartInvoke, agents: ReadonlySet<string>): unknown {
+function invokeOf(inv: ChartInvoke, agents: ReadonlySet<string>, gates: ReadonlySet<string>): unknown {
   const out: Record<string, unknown> = { src: inv.src };
   if (inv.id !== undefined) out.id = inv.id;
   if (inv.input !== undefined) {
@@ -985,7 +994,7 @@ function invokeOf(inv: ChartInvoke, agents: ReadonlySet<string>): unknown {
     // Resolved at invoke time, with `{ context, event, input }` (ADR-0070).
     out.input = agents.has(inv.src)
       ? (args: Args) => turnInput(resolveAt(template, args), placementOf(args.context?.[CHART_INPUT_KEY]))
-      : inv.src === "gate"
+      : inv.src === "gate" || gates.has(inv.src)
         ? (args: Args & { self: AnyActorRef }) => gateInput(resolveAt(template, args), args.self)
         : (args: Args) => resolveAt(template, args);
   }
@@ -994,14 +1003,16 @@ function invokeOf(inv: ChartInvoke, agents: ReadonlySet<string>): unknown {
   return out;
 }
 
-function stateOf(st: ChartState, agents: ReadonlySet<string>): Record<string, unknown> {
+function stateOf(st: ChartState, agents: ReadonlySet<string>, gates: ReadonlySet<string>): Record<string, unknown> {
   const out: Record<string, unknown> = {};
   if (st.type !== undefined) out.type = st.type;
   if (st.initial !== undefined) out.initial = st.initial;
   if (st.history !== undefined) out.history = st.history;
-  if (st.states !== undefined) out.states = mapValues(st.states, (child) => stateOf(child, agents));
+  if (st.states !== undefined) out.states = mapValues(st.states, (child) => stateOf(child, agents, gates));
   if (st.invoke !== undefined)
-    out.invoke = Array.isArray(st.invoke) ? st.invoke.map((inv) => invokeOf(inv, agents)) : invokeOf(st.invoke, agents);
+    out.invoke = Array.isArray(st.invoke)
+      ? st.invoke.map((inv) => invokeOf(inv, agents, gates))
+      : invokeOf(st.invoke, agents, gates);
   if (st.on !== undefined) out.on = mapValues(st.on, transitionsOf);
   if (st.always !== undefined) out.always = transitionsOf(st.always);
   if (st.after !== undefined) out.after = mapValues(st.after, transitionsOf);
@@ -1051,6 +1062,9 @@ export function compileChart(
     ...Object.keys(lent.actors).filter((slot) => isAgent(lent.actors[slot])),
     ...Object.keys(minted),
   ]);
+  // The lent Gate slots (ADR-0011): an authored gate id sits below the body's actor path, as the kit
+  // Gate's does.
+  const gateSlots = new Set(Object.keys(lent.actors).filter((slot) => isGateSlot(lent.actors[slot])));
   const initialContext = text.context ?? {};
   const config = {
     id: text.id ?? options.id ?? "chart",
@@ -1059,7 +1073,7 @@ export function compileChart(
       [CHART_INPUT_KEY]: input ?? {},
     }),
     initial: text.initial,
-    states: mapValues(text.states, (st) => stateOf(st, agentSlots)),
+    states: mapValues(text.states, (st) => stateOf(st, agentSlots, gateSlots)),
     output: ({ context, event }: Args) =>
       ({
         outcome: "done",

package/src/open-effect.ts

@@ -28,8 +28,9 @@ import type { Arg, EffectLogic, EffectParts, EffectSnapshot } from "./effect.ts"
 import type { Secret, Text } from "./http-effect.ts";
 
 /** The parts of an Effect a package may leave Open: an http url, a command's argv, a secret's name,
- * a dispatch's target (its url and token together, ADR-0071). */
-export type OpenEffectPart = "url" | "argv" | "secret" | "target";
+ * a dispatch's target (its url and token together, ADR-0071), an `mcp` Effect's server and tool
+ * (ADR-0079). */
+export type OpenEffectPart = "url" | "argv" | "secret" | "target" | "server" | "tool";
 
 // What a composer binds an Effect's Open parts to, each key one part (ADR-0054); a dispatch's
 // target is its url and token, bound as one (ADR-0071). One object for an
@@ -39,7 +40,8 @@ export type OpenEffectPart = "url" | "argv" | "secret" | "target";
  * The values that bind the Open parts of one Effect. A packaged Machine leaves a part of an Effect
  * Open when it cannot know it. That part is the url of an `http` Effect, the argv of a `command`,
  * the name of a secret, written `secret(open)`, or the target of a `dispatch`: the url of another
- * Orchestrator and the secret that holds its Instance token, bound as one. You bind it once, where you register the
+ * Orchestrator and the secret that holds its Instance token, bound as one, or the server or the tool
+ * of an `mcp` Effect. You bind it once, where you register the
  * Machine, with `customize(machine, { effects: { <slot>: binding } })`. Each key binds one Open
  * part. For an Effect with two Open parts, one object holds both keys.
  *
@@ -101,6 +103,11 @@ export type EffectBinding = {
    * `jr2.config.ts`. The Effector reads it from a file of that name. */
   readonly secret?: string;
   readonly target?: { readonly url: string; readonly token: Secret };
+  /** The server of an `mcp` Effect whose server is Open: a name of the `mcp` block of
+   * `jr2.config.ts`. The server's url and its secret are the config's. */
+  readonly server?: string;
+  /** The tool of an `mcp.call` Effect whose tool is Open: a tool name of the server. */
+  readonly tool?: string;
 };
 
 declare const openPart: unique symbol;
@@ -135,7 +142,11 @@ export function openPartsOf(parts: EffectParts): OpenEffectPart[] {
   if (parts.kind === "http" && parts.url === open) out.push("url");
   if (parts.kind === "command" && parts.argv === open) out.push("argv");
   if (parts.kind === "dispatch" && parts.target === open) out.push("target");
-  if (parts.kind !== "push" && parts.openSecret) out.push("secret");
+  if (parts.kind === "mcp") {
+    if (parts.server === open) out.push("server");
+    if (parts.tool === open) out.push("tool");
+  }
+  if (parts.kind !== "push" && parts.kind !== "mcp" && parts.openSecret) out.push("secret");
   return out;
 }
 
@@ -151,6 +162,8 @@ const BINDING_SAMPLE: Record<OpenEffectPart, string> = {
   argv: 'argv: ["<program>", "<arg>"]',
   secret: 'secret: "<name>"',
   target: 'target: { url: "https://<host>", token: secret("<name>") }',
+  server: 'server: "<name>"',
+  tool: 'tool: "<tool>"',
 };
 
 /** One binding object for these Open parts — `{ url: "…", secret: "<name>" }` for two. */

package/src/open.ts

@@ -14,12 +14,14 @@
  * - a Repo Slot: `repos: { app: open }`, or the whole map: `repos: open`;
  * - an Agent's model: `agent({ model: open, … })`;
  * - an Effect's url or argv: `http({ url: open, … })`, `command(open)`;
- * - the secret of an Effect's auth, of a header, or of a command's `env`: `secret(open)`.
+ * - the secret of an Effect's auth, of a header, or of a command's `env`: `secret(open)`;
+ * - the look of a Gate slot: `gate({ …, look: open })`.
  *
  * `jr2 up` refuses a Workflow with an Open part that nobody bound, and prints the `customize()`
  * line that binds it: ``refusing: workflow "<name>" leaves <part> open — bind it where the Machine
  * is registered: export const machine = customize(<import>, …)  (<adr>)``. A run never sees an
- * Open part.
+ * Open part. An Open look is the one exception: `jr2 up` warns about it and does not refuse,
+ * because a person can still answer the Gate with `jr2 send`.
  *
  * @example
  * ```ts

package/src/parts.ts

@@ -48,8 +48,9 @@
 import { basename } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { AnyActorRef, AnyStateMachine, StateNode, UnknownActorLogic } from "xstate";
-import { isAgent, isOpenAgent, type AgentDeclaration } from "./agent.ts";
-import { argvText, isEffect, placementOf, type EffectParts, type Placement } from "./effect.ts";
+import { isAgent, isOpenAgent, type AgentDeclaration, type AgentMcpServer, type WorkspaceAccess } from "./agent.ts";
+import { argvText, isEffect, placementOf, type EffectParts, type EffectSlot, type Placement } from "./effect.ts";
+import { isGateSlot } from "./gate.ts";
 import { effectBindingLine, openPartsOf, type OpenEffectPart } from "./open-effect.ts";
 import { isFailSlot } from "./fail.ts";
 import { isImageContext } from "./images.ts";
@@ -601,6 +602,20 @@ export type CarriedEffect = {
         input?: Record<string, unknown>;
         open?: Array<"target">;
       }
+    /** An mcp Effect (ADR-0079): what it asks of which server, by the server's name in the `mcp`
+     * block of `jr2.config.ts`. It names no secret of its own: `jr2 up` reads the server's url and
+     * secret from the config and places them in the Instance Effector. An Open server or tool is
+     * absent until bound. `timeoutMs` is the author's; 0 when the author set none, and the server's
+     * `timeout` then applies. */
+    | {
+        kind: "mcp";
+        op: "call" | "read" | "prompt";
+        server?: string;
+        tool?: string;
+        secrets: string[];
+        idempotent: boolean;
+        open?: Array<"server" | "tool">;
+      }
   );
 
 /** One state that can fail the run (ADR-0073): it invokes a `fail()` slot. `state` is the state's
@@ -649,9 +664,22 @@ export type CarriedParts = {
   /**
    * The Instance Harness is needed (ADR-0031): an Agent declares `workspace: "none"`, or an Open
    * body allows it. `models` are the models its Turns may run: those Agents', and those Open bodies'
-   * allowed ones. Absent when nothing needs it.
+   * allowed ones. `servers` are the MCP servers those Agents name (ADR-0079), sorted, deduped.
+   * Absent when nothing needs it.
    */
-  instanceHarness?: { models: string[] };
+  instanceHarness?: { models: string[]; servers: string[] };
+  /** Every Agent slot whose definition names an MCP server (ADR-0079), at each `customize()` route
+   * the walk reached it by, in walk order: what `jr2 up` checks against the config's `mcp` block. */
+  mcpAgents: CarriedMcpAgent[];
+};
+
+/** An Agent that names MCP servers (ADR-0079): its slot, the `customize()` route to its Machine,
+ * where its Turns run, and its `mcp` list as written. */
+export type CarriedMcpAgent = {
+  slot: string;
+  path: OpenSlot["path"];
+  workspace: WorkspaceAccess;
+  mcp: readonly AgentMcpServer[];
 };
 
 /** A machine actor, told apart from a promise/callback/observable one by having a state tree.
@@ -742,6 +770,7 @@ export function partsOf(machines: Iterable<AnyStateMachine>): CarriedParts {
   const openEffects: CarriedParts["openEffects"] = [];
   const sizes: CarriedSize[] = [];
   const openBodies: CarriedParts["openBodies"] = [];
+  const mcpAgents: CarriedMcpAgent[] = [];
   // The Machine that declares each Open body: where its lent Agents are read (not carried data).
   const bodyWrappers = new Map<CarriedParts["openBodies"][number], AnyStateMachine>();
   let sandboxed = false;
@@ -832,8 +861,11 @@ export function partsOf(machines: Iterable<AnyStateMachine>): CarriedParts {
     const body = wrapperBodyOf(machine);
     for (const { state, slot } of failingStatesOf(machine)) failures.push({ machine: machine.id, state, slot, path });
     for (const [name, logic] of Object.entries(machine.implementations.actors as Record<string, unknown>)) {
-      if (isAgent(logic)) collectAgent(path, name, logic.definition);
-      else if (isOpenBody(logic)) {
+      if (isAgent(logic)) {
+        collectAgent(path, name, logic.definition);
+        const { mcp, workspace } = logic.definition;
+        if (mcp?.length) mcpAgents.push({ slot: name, path, workspace: workspace ?? "write", mcp });
+      } else if (isOpenBody(logic)) {
         const body = { slot: name, declaration: openBodyDeclarationOf(logic), path };
         openBodies.push(body);
         bodyWrappers.set(body, machine);
@@ -842,6 +874,10 @@ export function partsOf(machines: Iterable<AnyStateMachine>): CarriedParts {
         effects.push(effect);
         if (effect.kind !== "push" && effect.open !== undefined)
           openEffects.push({ slot: name, path, parts: [...effect.open] });
+      } else if (lookReadOf(logic)) {
+        // A Gate slot's look reads with an http Effect (ADR-0011): the Instance Effector runs it, so
+        // `jr2 up` converges the Effector and places its secrets as for any Effect slot.
+        effects.push(carriedEffectOf(`${name}.look`, path, route, lookReadOf(logic)!.effect));
       } else {
         const child = asMachine(logic);
         if (child) walk(child, slotPath(path, name, body), name === body ? route : [...route, name]);
@@ -858,6 +894,7 @@ export function partsOf(machines: Iterable<AnyStateMachine>): CarriedParts {
   const noneBodies = openBodies.filter((b) => bodyTurnsRunIn(bodyWrappers.get(b)!, b.declaration, "instance"));
   const harnessModels = new Set<string>(menuOnly.map((a) => a.definition.model).filter(bound));
   for (const body of noneBodies) for (const m of body.declaration.allows.models) harnessModels.add(m);
+  const harnessServers = new Set(menuOnly.flatMap((a) => (a.definition.mcp ?? []).map((e) => e.server)));
   return {
     agents,
     failures,
@@ -871,7 +908,10 @@ export function partsOf(machines: Iterable<AnyStateMachine>): CarriedParts {
     composesSandbox: sandboxed,
     openBodies,
     models: [...models].sort(),
-    ...(menuOnly.length || noneBodies.length ? { instanceHarness: { models: [...harnessModels].sort() } } : {}),
+    ...(menuOnly.length || noneBodies.length
+      ? { instanceHarness: { models: [...harnessModels].sort(), servers: [...harnessServers].sort() } }
+      : {}),
+    mcpAgents,
   };
 }
 
@@ -924,6 +964,11 @@ export function placedEffectsOf(root: AnyStateMachine): CarriedEffect[] {
         effects.push(carriedEffectOf(name, path, route, logic.effect));
         continue;
       }
+      const look = lookReadOf(logic);
+      if (look) {
+        effects.push(carriedEffectOf(`${name}.look`, path, route, look.effect));
+        continue;
+      }
       const child = asMachine(logic);
       if (child) walk(child, slotPath(path, name, body), name === body ? route : [...route, name], on);
     }
@@ -976,6 +1021,22 @@ export function carriedEffectOf(
       ...(parts.file ? { file: true as const } : {}),
     };
   }
+  if (parts.kind === "mcp") {
+    return {
+      name,
+      path,
+      route,
+      kind: "mcp",
+      placement,
+      op: parts.op,
+      ...(parts.server === open ? {} : { server: parts.server }),
+      ...(parts.tool === undefined || parts.tool === open ? {} : { tool: parts.tool }),
+      secrets: [],
+      idempotent: parts.idempotent,
+      timeoutMs: parts.timeoutMs ?? 0,
+      ...(openParts.length ? { open: openParts as Array<"server" | "tool"> } : {}),
+    };
+  }
   if (parts.kind === "push") {
     const { sign, squash, force, pin, timeoutMs, slot } = parts;
     return {
@@ -1040,6 +1101,10 @@ export type WorkspacePod = {
    * down to the next `workspace()`, which is a pod of its own, and every model an Open body below
    * it allows a Chart's own Agents when it allows "write" or "read" (ADR-0070). Sorted, deduped. */
   models: string[];
+  /** The MCP servers that the Agents whose Turns run in this pod name (ADR-0079), with the Agent
+   * that names each and its allowlist: what places each server's secret in this pod, and what the
+   * allowlist rule reads. Absent when none names one. */
+  mcp?: Array<{ slot: string; path: OpenSlot["path"]; entry: AgentMcpServer }>;
   /** The Effects placed in this pod's Sandbox Effector (ADR-0068): every `push`, file-body `http` and
    * credentialed `command` slot below the `workspace()`, down to the next `workspace()` — read off
    * their plain data, statically. Empty → the pod gets no Sandbox Effector and no Secret. */
@@ -1076,6 +1141,7 @@ export function workspacePodsOf(root: AnyStateMachine): WorkspacePod[] {
     on: Set<AnyStateMachine>,
     effects: Map<string, CarriedEffect>,
     cuts: Set<string>,
+    mcp: NonNullable<WorkspacePod["mcp"]>,
     path: OpenSlot["path"],
     route: PlacementRoute,
   ): void => {
@@ -1083,12 +1149,14 @@ export function workspacePodsOf(root: AnyStateMachine): WorkspacePod[] {
     on.add(machine);
     const body = wrapperBodyOf(machine);
     const visit = (child: AnyStateMachine, at: OpenSlot["path"], to: PlacementRoute) => {
-      if (!composesSandbox(child)) modelsIn(child, models, on, effects, cuts, at, to);
+      if (!composesSandbox(child)) modelsIn(child, models, on, effects, cuts, mcp, at, to);
     };
     for (const [name, logic] of Object.entries(machine.implementations.actors as Record<string, unknown>)) {
       if (isAgent(logic)) {
         const { model, workspace } = logic.definition;
         if (workspace !== "none" && typeof model === "string") models.add(model);
+        // A "none" Agent's servers are the Instance Harness's (ADR-0079), never this pod's.
+        if (workspace !== "none") for (const entry of logic.definition.mcp ?? []) mcp.push({ slot: name, path, entry });
         continue;
       }
       // A Turn under an Open body may run in this pod with any model the body allows (ADR-0070):
@@ -1123,7 +1191,8 @@ export function workspacePodsOf(root: AnyStateMachine): WorkspacePod[] {
       const models = new Set<string>();
       const effects = new Map<string, CarriedEffect>();
       const cuts = new Set<string>();
-      modelsIn(machine, models, new Set(), effects, cuts, path, route);
+      const mcp: NonNullable<WorkspacePod["mcp"]> = [];
+      modelsIn(machine, models, new Set(), effects, cuts, mcp, path, route);
       const parts = sandboxPartsOf(machine);
       const bindings: Record<string, string | undefined> = {};
       if (parts.repos !== open) {
@@ -1139,6 +1208,7 @@ export function workspacePodsOf(root: AnyStateMachine): WorkspacePod[] {
         models: [...models].sort(),
         effects: [...effects.values()],
         ...(cuts.size ? { cuts: [...cuts] } : {}),
+        ...(mcp.length ? { mcp } : {}),
         ...(parts.effector ? { effector: { ...parts.effector } } : {}),
         ...(parts.image !== undefined ? { image: parts.image } : {}),
         bindings,
@@ -1157,6 +1227,14 @@ export function workspacePodsOf(root: AnyStateMachine): WorkspacePod[] {
   return pods;
 }
 
+/** The read of a Gate slot's bound look, when it is an Effect (ADR-0011); undefined otherwise. */
+function lookReadOf(logic: unknown): EffectSlot | undefined {
+  if (!isGateSlot(logic)) return undefined;
+  const look = logic.gateSlot.look;
+  if (typeof look !== "object" || look === null) return undefined;
+  return isEffect(look.read) ? look.read : undefined;
+}
+
 /** Every state of `machine`'s own tree that invokes a `fail()` slot (ADR-0073), in document order,
  * with the slot key: a state that can fail the run. A child Machine's states are its own walk's. */
 export function failingStatesOf(machine: AnyStateMachine): Array<{ state: string; slot: string }> {

package/src/party.ts

@@ -19,6 +19,7 @@
 import type { AnyActorRef, AnyEventObject, AnyMachineSnapshot, AnyStateMachine } from "xstate";
 import { SENDER_KEY, type Sender } from "@jr2/agent-protocol";
 import { isAgent } from "./agent.ts";
+import { isGateInvoke } from "./gate-brand.ts";
 import { vocabularyOf } from "./vocabulary.ts";
 
 /** The guard type `sentBy` names: dotted, so no author guard can take the name. */
@@ -138,7 +139,7 @@ export function partiesAt(node: Node, machine: AnyStateMachine): Sender[] {
   const out: Sender[] = [];
   for (const inv of node.invoke) {
     if (typeof inv.src !== "string") continue;
-    if (inv.src === "gate") out.push({ party: "gate", id: inv.id });
+    if (isGateInvoke(inv, actors)) out.push({ party: "gate", id: inv.id });
     else if (isAgent(actors[inv.src])) out.push({ party: "agent", id: inv.src });
   }
   return out;

package/src/pick.ts

@@ -424,8 +424,8 @@ export function fromPick<N extends string, I extends z.ZodObject, C, E extends E
 }
 
 /**
- * One reply since the pick, as the author reads it: an invoked actor's output, typed by its slot
- * (`src`); or an event that answered a state below the Agent's — a Gate's answer, a nested Agent's
+ * One reply since the pick, as the author reads it. It is an invoked actor's output, typed by its
+ * slot (`src`); or an event that answered a state below the Agent's — a Gate's answer, a nested Agent's
  * pick — typed by the Machine's events. A reply is from outside the Machine: the events it sends
  * itself are not links.
  */