@jr2/orchestrator 0.4.1 → 0.6.0

package/src/open-body.ts

@@ -24,6 +24,7 @@ import {
   type UnknownActorLogic,
 } from "xstate";
 import { isAgent, type AgentDefinition, type WorkspaceAccess } from "./agent.ts";
+import { ambientHandlesFor } from "./ambient.ts";
 import {
   admitChart,
   chartDigest,
@@ -31,8 +32,10 @@ import {
   ChartRefusal,
   GENERIC_ACTIONS,
   pathSegments,
+  READY_GUARD,
   resolveSource,
   resolveReferences,
+  slotFolderFault,
   type AdmittedChart,
   type ChartAction,
   type ChartGuard,
@@ -43,28 +46,33 @@ import {
   type ChartTransition,
   type ChartTransitions,
 } from "./chart.ts";
-import { inputKeysOf, isEffect, type Duration } from "./effect.ts";
+import { inputShapeOf, isEffect, type Duration, type InputShape } from "./effect.ts";
+import { fail, FAILURE_GUARD, failureGuard } from "./fail.ts";
 import { agent } from "./harness-client.ts";
 import { SENT_BY } from "./party.ts";
-import { wrapperBodyOf } from "./parts.ts";
+import { composesSandbox, sandboxPartsOf, wrapperBodyOf } from "./parts.ts";
+import { open } from "./open.ts";
 import { actorPath, boundRun } from "./registration.ts";
-import { jr2Setup } from "./setup.ts";
+import { COMPILED_CHART, jr2Setup } from "./setup.ts";
 import { attachBoundMachine, boundMachineFor } from "./vocabulary.ts";
 
+// ADR-0070: "counters are the Open body's".
 /**
- * The ceilings an Open body sets on the Chart that binds it (ADR-0070: "counters are the Open
- * body's"). Each is a positive bound; reaching one settles the body with a `ceiling` output.
+ * The limits that an Open body sets on its Chart. Each one is a positive bound. When the Chart gets
+ * to one, the Open body stops it and ends with `{ outcome: "ceiling", ceiling, detail }`.
  */
 export type Ceilings = {
-  /** The Agent Turns started under the body, at any depth: a lent Machine's Turns count too. */
+  /** The Agent Turns that start under the Open body, at all levels. The Turns of a lent Machine
+   * count too. */
   turns: number;
-  /** The wall clock from the body's start. */
+  /** The time from the start of the Open body, such as `"30m"`. At most about 596 hours. */
   wallClock: Duration;
-  /** The microsteps the body takes, over the whole run: a budget, since xstate has no loop guard. */
+  /** The transitions of the Chart in the whole run. xstate has no guard against a loop, so this is
+   * the guard. */
   transitions: number;
-  /** The children live under the body at once. */
+  /** The children that run under the Open body at one time. */
   fanOut: number;
-  /** The Chart's canonical JSON, in bytes: the door's own limit. At most {@link MAX_CHART_SIZE}. */
+  /** The size of the Chart, as JSON, in bytes. At most 1048576 (1 MiB). */
   size: number;
 };
 
@@ -106,8 +114,11 @@ export function jsonOver(value: unknown, cap: number): boolean {
   return false;
 }
 
-/** The kinds of part an Open body lends, each as a list of the wrapper's own slot names; and the
- * kit's Gate, lent whole (`gate: true`), since there is one and it has no name to list. */
+/** 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
+ * 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. */
 export type Lends = {
   agents?: string[];
   effects?: string[];
@@ -116,13 +127,23 @@ export type Lends = {
   actions?: string[];
   delays?: string[];
   gate?: boolean;
+  fail?: boolean;
 };
 
-/** What an Open body states (ADR-0070): the parts it lends, what a Chart may define, the ceilings. */
+/**
+ * What an Open body declares: the parts that it lends a Chart, what the Agents of a Chart can
+ * have, and the limits of a Chart. Give it to {@link openBody}, and to `chartSchemaFor` for the
+ * pick of a planner.
+ *
+ * @see docs/concepts/charts.md
+ */
 export type OpenBodyDeclaration = {
+  /** The parts that a Chart can use. */
   lends: Lends;
-  /** What a Chart's own Agents may have: a model from `models`, a Workspace access from `workspace`. */
+  /** What the Agents that a Chart adds can have: a model from `models`, and a Workspace access
+   * from `workspace`. With no model, a Chart cannot add an Agent. */
   allows: { models: string[]; workspace: WorkspaceAccess[] };
+  /** The limits of one Chart. */
   ceilings: Ceilings;
 };
 
@@ -151,6 +172,8 @@ const reservedName = (kind: (typeof LEND_KINDS)[number], v: string): string | un
   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")
     return `"gate" is the kit's Gate; lend a slot of another name`;
+  if ((kind === "agents" || kind === "effects" || kind === "machines") && 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`;
   if (kind === "delays" && /^(0|[1-9][0-9]*)$/.test(v))
@@ -201,8 +224,12 @@ export function declarationFaults(decl: unknown): string[] {
         if (typeof (lends as { gate?: unknown }).gate !== "boolean") {
           faults.push("lends.gate: the kit's Gate is lent whole: true or false");
         }
+      } else if (key === "fail") {
+        if (typeof (lends as { fail?: unknown }).fail !== "boolean") {
+          faults.push("lends.fail: the kit's Part that fails the run is lent whole: true or false");
+        }
       } else if (!(LEND_KINDS as readonly string[]).includes(key)) {
-        faults.push(`lends.${key}: an Open body lends ${LEND_KINDS.join(", ")} and gate only`);
+        faults.push(`lends.${key}: an Open body lends ${LEND_KINDS.join(", ")}, gate and fail only`);
       }
     }
     for (const kind of LEND_KINDS) {
@@ -261,6 +288,7 @@ function frozen(decl: OpenBodyDeclaration): OpenBodyDeclaration {
     if (v !== undefined) lends[kind] = Object.freeze([...v]) as string[];
   }
   if (decl.lends.gate !== undefined) lends.gate = decl.lends.gate;
+  if (decl.lends.fail !== undefined) lends.fail = decl.lends.fail;
   return Object.freeze({
     lends: Object.freeze(lends),
     allows: Object.freeze({
@@ -271,11 +299,78 @@ function frozen(decl: OpenBodyDeclaration): OpenBodyDeclaration {
   });
 }
 
+// It validates the declaration now, so a bad one fails where the Machine is written, and returns
+// actor logic branded with it. `jr2Setup` resolves every lent name against its own `actors`,
+// `guards`, `actions` and `delays` at createMachine, and stamps the result with `attachLent`
+// (ADR-0070).
 /**
- * Declare an Open body (ADR-0070). It validates the declaration now, so a bad one fails where the
- * Machine is written, and returns actor logic branded with it. `jr2Setup` resolves every lent name
- * against its own `actors`, `guards`, `actions` and `delays` at createMachine, and stamps the
- * result with {@link attachLent}.
+ * Make an Open body: the actor slot that a Chart binds. Put it in `actors`, and invoke it from a
+ * state with `{ chart, ...input }`. `chart` is the text of a Chart, or `{ name }` for a named
+ * Chart of this wrapper. The other keys are the input of the Chart, which it reads as
+ * `{{input.<key>}}`. A Machine with an Open body is a Chart wrapper.
+ *
+ * Each Agent Turn of the Chart runs where the Open body runs: in the Sandbox of its `workspace()`,
+ * or on the Instance Harness. The Open body ends with an {@link OpenBodyOutput}.
+ *
+ * It refuses a declaration that is not correct: `openBody: <problem>; <problem>`, for example
+ * `ceilings.turns: missing; an Open body states every ceiling`. `createMachine` refuses a lent
+ * name that the Machine does not have: `machine "<id>": Open body "<slot>": lends.agents: "<name>"
+ * is no actor slot of this Machine; its actors: <slots>`.
+ *
+ * @param decl - What a Chart can use, and its limits (see {@link OpenBodyDeclaration}).
+ * @returns The actor logic of the slot.
+ *
+ * @example
+ * ```ts
+ * import { assign } from "xstate";
+ * import { z } from "zod";
+ * import { agent, chartSchema, fail, jr2Setup, openBody, type OpenBodyOutput } from "@jr2/orchestrator";
+ *
+ * // `chart` is a Chart, so a run input can carry one, and Charts can have names.
+ * const door = z.object({ topic: z.string(), chart: chartSchema });
+ * type Input = z.infer<typeof door>;
+ * type Context = Input & { result?: OpenBodyOutput };
+ *
+ * export const machine = jr2Setup({
+ *   types: {} as { context: Context; input: Input },
+ *   actors: {
+ *     writer: agent({
+ *       model: "anthropic/claude-haiku-5-5",
+ *       workspace: "none",
+ *       instructions: "You write clear, short text for engineers.",
+ *     }),
+ *     body: openBody({
+ *       lends: { agents: ["writer"] },
+ *       allows: { models: [], workspace: [] },
+ *       ceilings: { turns: 6, wallClock: "15m", transitions: 200, fanOut: 1, size: 65536 },
+ *     }),
+ *     fail: fail(),
+ *   },
+ * }).createMachine({
+ *   id: "notes",
+ *   input: door,
+ *   context: ({ input }) => ({ ...input }),
+ *   // The fault of `writer` when a Chart does not route it: the Open body sends it here.
+ *   on: { "agent.fault": ".failed" },
+ *   initial: "running",
+ *   states: {
+ *     running: {
+ *       invoke: {
+ *         src: "body",
+ *         input: ({ context }: { context: Context }) => ({ chart: context.chart, topic: context.topic }),
+ *         onDone: { target: "done", actions: assign({ result: ({ event }) => event.output as OpenBodyOutput }) },
+ *       },
+ *     },
+ *     done: { type: "final" },
+ *     failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+ *   },
+ * });
+ * ```
+ *
+ * @see docs/concepts/charts.md
+ * @see docs/guides/run-a-chart-by-name.md
+ * @see docs/guides/let-an-agent-write-a-chart.md
+ * @see docs/reference/decisions/0070-a-machine-lends-its-parts-to-a-chart.md
  */
 export function openBody(decl: OpenBodyDeclaration): OpenBodyLogic {
   return openBodyWith(decl);
@@ -358,7 +453,16 @@ export function lentOf(logic: OpenBodyLogic): LentParts | undefined {
 /** What an Open body is invoked with: the Chart, by text or by name, and its `input` (the rest). */
 export type OpenBodyInput = { chart: ChartText | { name: string } } & Record<string, unknown>;
 
-/** How an Open body settles: the Chart's output, the door's refusal, or the ceiling it reached. */
+/**
+ * The output of an Open body. Route on `outcome` in the `onDone` of the state that invokes it:
+ *
+ * - `done`: the Chart got to a final state. `output` is the output of the Chart.
+ * - `refused`: the door refused the Chart. `report` has one line for each problem. Give it to the
+ *   Agent that wrote the Chart, so that it can send a corrected one.
+ * - `ceiling`: the Chart got to a ceiling, and the Open body stopped it. `ceiling` names it.
+ *
+ * @see docs/concepts/charts.md
+ */
 export type OpenBodyOutput =
   | { outcome: "done"; output: unknown }
   | { outcome: "refused"; report: string[] }
@@ -473,9 +577,12 @@ export function admitBodyChart(
   text: unknown,
   decl: OpenBodyDeclaration,
   lent: LentParts,
-  options: { inputKeys?: readonly string[] } = {},
+  options: { inputKeys?: readonly string[]; repoSlots?: readonly string[] } = {},
 ): AdmittedChart {
-  const admitted = admitChart(text, decl, lent, options.inputKeys ? { inputKeys: options.inputKeys } : {});
+  const admitted = admitChart(text, decl, lent, {
+    ...(options.inputKeys ? { inputKeys: options.inputKeys } : {}),
+    ...(options.repoSlots ? { repoSlots: options.repoSlots } : {}),
+  });
   try {
     compileChart(admitted, lent, decl);
   } catch (err) {
@@ -527,11 +634,23 @@ export function admitOpenBodyChart(
   const logic = (inner.implementations.actors as Record<string, unknown>)[slot];
   if (!isOpenBody(logic)) throw new Error(`machine "${machine.id}" has no Open body "${slot}"`);
   const decl = openBodyDeclarationOf(logic);
+  const repoSlots = repoSlotsAround(machine);
   return admitBodyChart(text, decl, lentIn(inner.implementations as Implementations, decl), {
     ...(inputKeys ? { inputKeys } : {}),
+    ...(repoSlots ? { repoSlots } : {}),
   });
 }
 
+/** The Repo Slots of the `workspace()` around a Chart wrapper, where the door can see one: the
+ * wrapper IS the `workspace()`. Undefined: an Open map, or a Workspace that a parent state invokes,
+ * whose slots this door cannot read. Then the Open body's own door reads them off the running
+ * Workspace, and a Turn's or an Effect's start refuses what no door could see. */
+export function repoSlotsAround(machine: AnyStateMachine): readonly string[] | undefined {
+  if (!composesSandbox(machine)) return undefined;
+  const { repos } = sandboxPartsOf(machine);
+  return repos === open ? undefined : Object.keys(repos);
+}
+
 /**
  * Admit a Chart field of a Chart wrapper's door (ADR-0070), the door a run's start runs before the
  * run exists. The door cannot tell which Open body a field feeds, so the Chart is admitted against
@@ -548,7 +667,10 @@ export function admitWrapperChart(machine: AnyStateMachine, text: unknown): Admi
   for (const { slot, logic } of bodies) {
     const decl = openBodyDeclarationOf(logic);
     try {
-      return admitBodyChart(text, decl, lentIn(inner.implementations as Implementations, decl));
+      const repoSlots = repoSlotsAround(machine);
+      return admitBodyChart(text, decl, lentIn(inner.implementations as Implementations, decl), {
+        ...(repoSlots ? { repoSlots } : {}),
+      });
     } catch (err) {
       if (!(err instanceof ChartRefusal)) throw err;
       report.push(...err.report.map((line) => (bodies.length > 1 ? `body "${slot}": ${line}` : line)));
@@ -575,7 +697,7 @@ const scopeOf = (args: Args) => ({
   input: chartInputOf((args.context?.[CHART_INPUT_KEY] as Record<string, unknown> | undefined) ?? {}),
 });
 
-/** An invoke's error whose message jr2 wrote for a Chart to read: a lent Effect's input fault. */
+/** An invoke's error whose message jr2 wrote for a Chart to read: a fault in an input the door could not see. */
 class ChartInvokeFault extends Error {}
 
 /**
@@ -739,6 +861,10 @@ function transitionsOf(ts: ChartTransitions): unknown {
   return Array.isArray(ts) ? ts.map(transitionOf) : transitionOf(ts);
 }
 
+/** `jr2.ready`: is this cut's output `ready`? On an `onDone`. */
+const readyGuard = ({ event }: { event: unknown }): boolean =>
+  (event as { output?: { outcome?: unknown } } | undefined)?.output?.outcome === "ready";
+
 const mapValues = <T, U>(o: Record<string, T>, fn: (v: T) => U): Record<string, U> =>
   Object.fromEntries(Object.entries(o).map(([k, v]) => [k, fn(v)]));
 
@@ -747,15 +873,17 @@ const mapValues = <T, U>(o: Record<string, T>, fn: (v: T) => U): Record<string,
  * resolved object again at invoke time"), or undefined when it is. The door checked the literal
  * parts; a reference may still resolve to a value that is no string.
  */
-function effectInputFault(keys: readonly string[], value: unknown): string | undefined {
+function effectInputFault(shape: InputShape, value: unknown): string | undefined {
   const given = typeof value === "object" && value !== null && !Array.isArray(value) ? Object.keys(value) : undefined;
+  const known = [...shape.required, ...shape.optional, ...(shape.oneOf ?? [])];
   const ok =
     given !== undefined &&
-    given.length === keys.length &&
-    keys.every((k) => typeof (value as Record<string, unknown>)[k] === "string");
+    shape.required.every((k) => given.includes(k)) &&
+    given.every((k) => known.includes(k) && typeof (value as Record<string, unknown>)[k] === "string") &&
+    (shape.oneOf === undefined || shape.oneOf.filter((k) => given.includes(k)).length === 1);
   return ok
     ? undefined
-    : `its input resolved to ${JSON.stringify(value)}; it takes exactly ${keys.join(", ") || "nothing"}, each a string (ADR-0070)`;
+    : `its input resolved to ${JSON.stringify(value)}; it takes ${known.join(", ") || "nothing"}, each a string (ADR-0070)`;
 }
 
 const checkedEffects = new WeakMap<object, UnknownActorLogic>();
@@ -767,13 +895,15 @@ const checkedEffects = new WeakMap<object, UnknownActorLogic>();
  */
 function checkedEffect(slot: string, logic: UnknownActorLogic): UnknownActorLogic {
   if (!isEffect(logic)) return logic;
-  const keys = inputKeysOf(logic.effect);
-  if (keys === undefined) return logic;
+  const shape = inputShapeOf(logic.effect);
+  if (shape === undefined) return logic;
   const hit = checkedEffects.get(logic);
   if (hit) return hit;
   const checked = Object.create(logic) as UnknownActorLogic;
   checked.getInitialSnapshot = (scope, input) => {
-    const fault = effectInputFault(keys, input);
+    // An Effect that takes nothing, invoked with no input, is a whole input: the door let it through.
+    const fault =
+      input === undefined && shape.required.length === 0 && !shape.oneOf ? undefined : effectInputFault(shape, input);
     if (fault === undefined) return logic.getInitialSnapshot(scope, input);
     return {
       status: "error",
@@ -785,9 +915,38 @@ function checkedEffect(slot: string, logic: UnknownActorLogic): UnknownActorLogi
   return checked;
 }
 
-/** The lent actors as a Chart invokes them: each Effect checked at its start (see {@link checkedEffect}). */
+const checkedAgents = new WeakMap<object, UnknownActorLogic>();
+
+/**
+ * An Agent as a Chart invokes it: the Agent itself, whose start refuses a resolved `cwd` that is a
+ * Repo Slot's folder. A reference hides that value from the door. The check is in `start`, because
+ * the Workspace's handles are registered at a start, and a Chart's first invoke resolves before
+ * that. The refusal is THAT invoke's error, as in {@link checkedEffect}.
+ */
+function checkedAgent(slot: string, logic: UnknownActorLogic): UnknownActorLogic {
+  const hit = checkedAgents.get(logic);
+  if (hit) return hit;
+  const checked = Object.create(logic) as UnknownActorLogic;
+  checked.start = (snapshot, scope) => {
+    const cwd = ((snapshot as { input?: unknown }).input as { cwd?: unknown } | undefined)?.cwd;
+    const reads = (logic as { definition?: { workspace?: unknown } }).definition?.workspace !== "none";
+    const repos = reads && typeof cwd === "string" ? ambientHandlesFor(scope.self)?.repos : undefined;
+    const fault = repos ? slotFolderFault(cwd as string, Object.keys(repos)) : undefined;
+    if (fault !== undefined) throw new ChartInvokeFault(`the Agent "${slot}": ${fault}`);
+    logic.start?.(snapshot, scope);
+  };
+  checkedAgents.set(logic, checked);
+  return checked;
+}
+
+/** The lent actors as a Chart invokes them: each Effect and Agent checked at its start. */
 function chartActors(actors: Record<string, UnknownActorLogic>): Record<string, UnknownActorLogic> {
-  return Object.fromEntries(Object.entries(actors).map(([slot, logic]) => [slot, checkedEffect(slot, logic)]));
+  return Object.fromEntries(
+    Object.entries(actors).map(([slot, logic]) => [
+      slot,
+      isAgent(logic) ? checkedAgent(slot, logic) : checkedEffect(slot, logic),
+    ]),
+  );
 }
 
 /** An Agent Turn's input with `prompt` and `cwd` as strings: a whole placeholder may resolve to
@@ -863,13 +1022,16 @@ export type CompileOptions = OpenBodyOptions & {
 
 /**
  * Build the Machine a Chart describes (ADR-0070), with `jr2Setup` over: the lent actors by their
- * slot names, `agent(def)` for each Agent the Chart mints, and the kit's `gate`; the lent guards
- * and `jr2.sentBy`; the lent actions and the four generic ones; the lent delays. Every reference
- * resolves at invoke time, so the Machine holds the text's shape and no run's data. The Chart's
+ * slot names, `agent(def)` for each Agent the Chart mints, the kit's `gate`, and `fail()` where the
+ * body lends it; the lent guards, `jr2.sentBy`, `jr2.failure` and `jr2.ready`; the lent actions and the four
+ * generic ones; the lent delays. Every reference resolves at invoke time, so the Machine holds the
+ * text's shape and no run's data. The Chart's
  * input is the context key {@link CHART_INPUT_KEY}; a done Chart outputs `{ outcome: "done",
  * output }`, its `output` resolved (or, without one, its final state's). The transitions ceiling
  * is xstate's `maxIterations` as well, so a guarded `always` loop that never ends in one macrostep
- * still ends. `jr2Setup`'s own refusals (a parallel state below an Agent's) throw here.
+ * still ends. `jr2Setup`'s own refusals (a parallel state below an Agent's) throw here, but not its
+ * `agent.fault` refusal: in a Chart that route is optional, and the body sends an `agent.fault` that
+ * no transition of the Chart takes to the Machine that invoked it (ADR-0074).
  */
 export function compileChart(
   admitted: AdmittedChart,
@@ -881,7 +1043,9 @@ export function compileChart(
   const mint = options.mintAgent ?? ((_slot: string, definition: AgentDefinition) => agent(definition));
   const minted = mapValues(admitted.agents, (def) => def);
   const actors: Record<string, UnknownActorLogic> = chartActors(lent.actors);
-  for (const [slot, def] of Object.entries(minted)) actors[slot] = mint(slot, def);
+  for (const [slot, def] of Object.entries(minted)) actors[slot] = checkedAgent(slot, mint(slot, def));
+  // The kit's Part that fails the run, where the body lends it (ADR-0073): no slot of the wrapper's.
+  if (decl.lends.fail === true) actors.fail = fail();
   // The slots an invoke runs an Agent Turn in: the lent Agents and the Chart's own.
   const agentSlots = new Set([
     ...Object.keys(lent.actors).filter((slot) => isAgent(lent.actors[slot])),
@@ -905,11 +1069,19 @@ export function compileChart(
             : (event as { output?: unknown } | undefined)?.output,
       }) satisfies OpenBodyOutput,
     options: { maxIterations: decl.ceilings.transitions },
+    // In a Chart the `agent.fault` route is optional (ADR-0070): the Open body sends an `agent.fault`
+    // that no transition takes to its parent, so `createMachine` does not refuse a state with none.
+    [COMPILED_CHART]: true,
   };
   return jr2Setup({
     events: admitted.events,
     actors,
-    guards: lent.guards as never,
+    // `jr2.failure` is in every Chart, as `jr2.sentBy` is: a predicate, with no capability (ADR-0073).
+    guards: {
+      ...(lent.guards as Record<string, unknown>),
+      [FAILURE_GUARD]: failureGuard,
+      [READY_GUARD]: readyGuard,
+    } as never,
     actions: { ...(lent.actions as Record<string, unknown>), ...GENERIC } as never,
     delays: lent.delays as never,
   }).createMachine(config as never) as unknown as AnyStateMachine;
@@ -1097,6 +1269,20 @@ function watchTurns(self: AnyActorRef, turns: number, ceiling: number): TurnWatc
   return watch;
 }
 
+/**
+ * Does a transition of the Chart take this event now? xstate's own selection, guards and all. A
+ * guard that throws (a reference that resolved to nothing) counts as a take: the step then runs
+ * the guard again, and settles the body `refused` with the reference named.
+ */
+function takes(machine: AnyStateMachine, snapshot: BodySnapshot, event: AnyEventObject): boolean {
+  try {
+    return machine.getTransitionData(snapshot as never, event as never).length > 0;
+  } catch {
+    runFault = undefined;
+    return true;
+  }
+}
+
 /** The actor logic of an Open body: a custom ActorLogic that delegates to the compiled Chart. */
 export function openBodyLogic(decl: OpenBodyDeclaration, options: OpenBodyOptions = {}): UnknownActorLogic {
   const wallMs = durationMs(decl.ceilings.wallClock) ?? Number.POSITIVE_INFINITY;
@@ -1259,7 +1445,10 @@ export function openBodyLogic(decl: OpenBodyDeclaration, options: OpenBodyOption
   /** Admit and compile a Chart text, and record the Machine the actor runs. Throws ChartRefusal. */
   const bind = (self: AnyActorRef, text: unknown, inputKeys: readonly string[]) => {
     const lent = liveLentOf(self, logic);
-    const admitted = admitChart(text, decl, lent, { inputKeys });
+    // A Chart that comes after the Workspace started finds its slots here. A Chart in the step that
+    // starts the Workspace comes before them, and the wrapper's door or the Turn's start saw it.
+    const repos = ambientHandlesFor(self)?.repos;
+    const admitted = admitChart(text, decl, lent, { inputKeys, ...(repos ? { repoSlots: Object.keys(repos) } : {}) });
     const src = (self as { src?: unknown }).src;
     const machine = compiledFor(admitted, lent, decl, {
       ...options,
@@ -1392,6 +1581,19 @@ export function openBodyLogic(decl: OpenBodyDeclaration, options: OpenBodyOption
           ceiling("transitions", transitionsDetail(fields.counters.transitions), snapshot, fields, scope),
         );
       }
+      // An `agent.fault` that no transition of the Chart takes goes to the Machine that invoked the
+      // body, unchanged (ADR-0074): in a Chart the route is optional, and the parent's `agent.fault`
+      // route is the route for a Chart's Agents too. The body does not step the Chart: the parent's
+      // route decides, and its exit stops the body. With no parent route that takes it, the run
+      // host faults the run, as for any `agent.fault` that no transition took.
+      if (event.type === "agent.fault" && !takes(machine, snapshot, event)) {
+        // Relayed from the body, as `sendBack` relays from an Agent: the run host reads a relayed
+        // event's source, so a pick held in the parent is answered as for an Agent of its own.
+        const parent = scope.self._parent;
+        const system = scope.system as unknown as { _relay(from: unknown, to: unknown, e: AnyEventObject): void };
+        if (parent) scope.defer(() => system._relay(scope.self, parent, event));
+        return snapshot;
+      }
       return release(
         scope.self,
         step(

package/src/open-effect.ts

@@ -25,18 +25,82 @@
 import type { ActorLogic, AnyActorRef, EventObject } from "xstate";
 import { open } from "./open.ts";
 import type { Arg, EffectLogic, EffectParts, EffectSnapshot } from "./effect.ts";
-import type { Text } from "./http-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. */
-export type OpenEffectPart = "url" | "argv" | "secret";
+/** 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";
 
-/** What a composer binds an Effect's Open parts to, each key one part: a url (a string, or a `text`
- * with a secret in its path), an argv (each entry one argument, never shell text), a secret's name
- * (its file in the Effector's mount, ADR-0068). One object for an Effect with two Open parts. */
+// 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
+// Effect with two Open parts. `customize()` reads each Effect's own binding type off its logic
+// (`BindingOf`, customize.ts), so this loose shape is what the implementation walks.
+/**
+ * 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
+ * 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.
+ *
+ * The binding is a value, never a function of the run: no run chooses an Effect's url, argv or
+ * secret. `customize()` builds the Effect again with the bound parts, so a bound part gets every
+ * check that a part written in the definition gets.
+ *
+ * `customize()` refuses:
+ * - an empty binding, or a key for a part that is not Open: `customize(): the <kind> Effect
+ *   "<slot>" leaves its <parts> Open — bind it with <binding> (ADR-0054)`
+ * - an Effect with no Open part: ``customize(): the <kind> Effect "<slot>" of machine "<id>"
+ *   leaves nothing Open — its parts are fixed in its definition, and only a part a package left
+ *   `open` is bound, once (ADR-0054).``
+ * - `open` as a value: ``customize(): the <kind> Effect "<slot>"'s <part> is bound once, to a
+ *   value — not `open` again: no run chooses an Effect's <part> (ADR-0054)``. A function as a
+ *   value gives the same text, with `a function of the run` for `` `open` again ``.
+ * - a secret that is not a string: `customize(): the <kind> Effect "<slot>"'s secret is bound to
+ *   a secret's name, a string — the file the Effector reads it from: { secret: "<name>" }
+ *   (ADR-0054, ADR-0068)`
+ *
+ * `jr2 up` refuses a registered Machine with an Open part that nobody bound, and prints the
+ * `customize` line that binds it.
+ *
+ * @example
+ * ```ts
+ * import { customize, http, jr2Setup, open, type EffectBinding } from "@jr2/orchestrator";
+ *
+ * const notifier = jr2Setup({
+ *   actors: { notify: http({ method: "POST", url: open }) },
+ * }).createMachine({
+ *   id: "notifier",
+ *   initial: "sending",
+ *   states: {
+ *     sending: { invoke: { src: "notify", onDone: "done" } },
+ *     done: { type: "final" },
+ *   },
+ * });
+ *
+ * const notify = { url: "https://hooks.example.com/build" } satisfies EffectBinding;
+ *
+ * export const machine = customize(notifier, { effects: { notify } });
+ * ```
+ *
+ * @see docs/guides/bind-open-parts.md
+ * @see docs/concepts/effects.md
+ * @see docs/reference/decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md
+ * @see docs/reference/decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md
+ */
 export type EffectBinding = {
+  /** The url of an `http` Effect whose url is Open: a string, or a `text` template with a secret
+   * in its path, such as `` text`https://hooks.example.com/services/${secret("hook")}` ``. Its
+   * scheme and host must be literal. */
   readonly url?: string | Text;
+  /** The argv of a `command` whose argv is Open: one entry for each argument, never shell text.
+   * An entry is a string or an `arg("<param>")` that the invoke's input fills. It must not be
+   * empty. */
   readonly argv?: readonly (string | Arg)[];
+  /** The name of the secret that `secret(open)` stands for: an entry of `secrets` in
+   * `jr2.config.ts`. The Effector reads it from a file of that name. */
   readonly secret?: string;
+  readonly target?: { readonly url: string; readonly token: Secret };
 };
 
 declare const openPart: unique symbol;
@@ -46,10 +110,16 @@ declare const openPart: unique symbol;
  * `effects` offers exactly the Open slots, each with the binding its parts take — the intersection
  * of each part's, for an Effect with two. Phantom, like `JR2Wrapper`: the property exists in the
  * type alone.
+ *
+ * @internal
  */
 export type OpenEffect<P extends OpenEffectPart> = { readonly [openPart]: P };
 
-/** The phantom for these Open parts, or nothing for none: what a constructor's type adds. */
+/**
+ * The phantom for these Open parts, or nothing for none: what a constructor's type adds.
+ *
+ * @internal
+ */
 export type OpenOf<P extends OpenEffectPart> = [P] extends [never] ? unknown : OpenEffect<P>;
 
 /** The binder an Open Effect carries, under a `Symbol.for` key so a second copy of this module (an
@@ -58,11 +128,13 @@ const BIND: unique symbol = Symbol.for("jr2.effect.bind");
 
 type Binder = (binding: EffectBinding) => EffectLogic<unknown, unknown>;
 
-/** Which parts of these parts are Open, in binding order: the url or the argv, then the secret. */
+/** Which parts of these parts are Open, in binding order: the url, the argv or the target, then the
+ * secret. A dispatch's target is one part: its token is never `secret(open)` (ADR-0071). */
 export function openPartsOf(parts: EffectParts): OpenEffectPart[] {
   const out: 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");
   return out;
 }
@@ -78,6 +150,7 @@ const BINDING_SAMPLE: Record<OpenEffectPart, string> = {
   url: 'url: "https://<host>/<path>"',
   argv: 'argv: ["<program>", "<arg>"]',
   secret: 'secret: "<name>"',
+  target: 'target: { url: "https://<host>", token: secret("<name>") }',
 };
 
 /** One binding object for these Open parts — `{ url: "…", secret: "<name>" }` for two. */