@jr2/orchestrator 0.4.1 → 0.5.1

package/src/notices.ts

@@ -13,8 +13,17 @@ import type { Notice } from "./wire.ts";
 
 /** Where an admission 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 conversation to be
- * told about, and a Menu-only Agent works in no Workspace. */
-export type NoticeScope = { conversation?: string; workspace?: string };
+ * told about, and a Menu-only Agent works in no Workspace. `only`, when set, narrows the take to
+ * the notices raised by these sources: what a nudge or a wake carries (ADR-0062). `except` leaves
+ * out the notices raised by these: what a re-admission of the same Turn was told already;
+ * `exceptPrefix` every notice whose source starts so — all guard kills, when that is not known. */
+export type NoticeScope = {
+  conversation?: string;
+  workspace?: string;
+  only?: readonly string[];
+  except?: readonly string[];
+  exceptPrefix?: string;
+};
 
 /** One pending notice: the notice, and the conversation or Workspace it goes to. `source` names
  * the event that raised it, so the same event raised twice — two Turns lost to one kernel kill, a
@@ -26,7 +35,13 @@ export type PendingNotice = { id: string; notice: Notice; to: string; source?: s
 export type NoticeLedgerState = { pending: PendingNotice[]; seen: string[] };
 
 /** What one admission takes: the notices it carries, and their ids for the ledger write. */
-export type TakenNotices = { ids: string[]; notices: Notice[] };
+export type TakenNotices = {
+  ids: string[];
+  notices: Notice[];
+  /** Every notice taken, with the source it was raised with — what `restore` puts back when no
+   * model heard the admission. */
+  raised?: Array<{ notice: Notice; source?: string }>;
+};
 
 export class NoticeLedger {
   readonly #pending: PendingNotice[];
@@ -41,30 +56,68 @@ export class NoticeLedger {
   }
 
   /** Raise a notice for `to` (a conversation's base id, or a Sandbox name — the notice's own
-   * `scope` says which). False when `source` was already raised, or the same notice is already
-   * pending for `to`. */
-  raise(notice: Notice, to: string, source?: string): boolean {
+   * `scope` says which). `older` are the sources of earlier events that this one tells the same as —
+   * a burst of guard kills, read at once: they are marked raised and give no notice of their own.
+   * Answers whether anything changed — a notice pending, or a source marked — so the caller saves
+   * only then. */
+  raise(notice: Notice, to: string, source?: string, older: readonly string[] = []): boolean {
+    let changed = false;
+    for (const seen of older) {
+      if (this.#seen.has(seen)) continue;
+      this.#seen.add(seen);
+      changed = true;
+    }
     if (source !== undefined) {
-      if (this.#seen.has(source)) return false;
+      if (this.#seen.has(source)) return changed;
       this.#seen.add(source);
+    } else {
+      // A notice with no source is one notice with a pending twin that has none either. A notice
+      // WITH a source keeps its own entry, so a take by source (`only`, `except`) finds it; equal
+      // ones are one notice in the admission (`take`).
+      const same = JSON.stringify(notice);
+      if (this.#pending.some((p) => p.source === undefined && p.to === to && JSON.stringify(p.notice) === same)) {
+        return changed;
+      }
     }
-    // The same news, still unheard, is one notice: the guard writes one kill to the stream of
-    // every conversation running in the pod, and each Turn following one reads it.
-    const same = JSON.stringify(notice);
-    if (this.#pending.some((p) => p.to === to && JSON.stringify(p.notice) === same)) return false;
     this.#pending.push({ id: this.#newId(), notice, to, ...(source === undefined ? {} : { source }) });
     return true;
   }
 
-  /** Reserve every unreserved notice in this admission's scope, in the order raised. */
+  /** Reserve every unreserved notice in this admission's scope, in the order raised. Equal notices —
+   * two kills that tell the same thing — are said once, and every id is reserved. */
   take(scope: NoticeScope): TakenNotices {
     const taken = this.#pending.filter(
       (p) =>
         !this.#reserved.has(p.id) &&
+        (scope.only === undefined || (p.source !== undefined && scope.only.includes(p.source))) &&
+        (scope.except === undefined || p.source === undefined || !scope.except.includes(p.source)) &&
+        (scope.exceptPrefix === undefined || p.source === undefined || !p.source.startsWith(scope.exceptPrefix)) &&
         (p.notice.scope === "conversation" ? p.to === scope.conversation : p.to === scope.workspace),
     );
     for (const p of taken) this.#reserved.add(p.id);
-    return { ids: taken.map((p) => p.id), notices: taken.map((p) => p.notice) };
+    const said = new Set<string>();
+    const notices = taken.flatMap((p) => {
+      const key = JSON.stringify(p.notice);
+      if (said.has(key)) return [];
+      said.add(key);
+      return [p.notice];
+    });
+    return {
+      ids: taken.map((p) => p.id),
+      notices,
+      raised: taken.map((p) => ({ notice: p.notice, ...(p.source === undefined ? {} : { source: p.source }) })),
+    };
+  }
+
+  /** Put back a notice an admission carried that no model heard, with the source it was raised
+   * with — `seen` already holds it, so a raise would drop it. Nothing changes when a notice with
+   * that source is pending already. Answers whether anything changed. */
+  restore(notice: Notice, to: string, source?: string): boolean {
+    if (source === undefined) return this.raise(notice, to);
+    if (this.#pending.some((p) => p.source === source && p.to === to)) return false;
+    this.#seen.add(source);
+    this.#pending.push({ id: this.#newId(), notice, to, source });
+    return true;
   }
 
   /** The admission that carried them was ledgered: they are delivered. */

package/src/open-body.ts

@@ -44,27 +44,31 @@ import {
   type ChartTransitions,
 } from "./chart.ts";
 import { inputKeysOf, isEffect, type Duration } 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 { 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 +110,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 +123,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 +168,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 +220,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 +284,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 +295,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 +449,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[] }
@@ -863,13 +963,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` and `jr2.failure`; 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,
@@ -882,6 +985,8 @@ export function compileChart(
   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);
+  // 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 +1010,15 @@ 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 } 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 +1206,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;
@@ -1392,6 +1515,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. */

package/src/open.ts

@@ -5,13 +5,66 @@
 // and a `workspace()`'s Repo Slots (parts.ts, which already imports agent.ts). A module with
 // nothing but the sentinel in it is what lets both import it and neither import the other.
 
+// `Symbol.for`, so an Instance's own copy of this module and the CLI's walk agree on it — a
+// packaged Machine may be built against one and walked by the other.
 /**
- * Open (GLOSSARY.md, ADR-0054): this part is a composer's to bind, with `customize()` — a Repo
- * Slot with no url, an Agent with no model. The shape a packaged Machine ships in, because a
- * package cannot know the repository or pay for the model. `jr2 up` refuses an Open part nobody
- * bound and names the line that binds it; a run never sees one.
+ * Leave a part of a Machine Open: for the Instance that registers the Machine to bind with
+ * `customize()`. Write it where a value goes, in a Machine that you publish as a package, for a
+ * part that the package cannot know or pay for:
+ * - 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)`.
  *
- * `Symbol.for`, so an Instance's own copy of this module and the CLI's walk agree on it — a
- * packaged Machine may be built against one and walked by the other.
+ * `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.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { agent, customize, defineEvent, fail, jr2Setup, open, workspace } from "@jr2/orchestrator";
+ *
+ * const finish = defineEvent({
+ *   name: "finish",
+ *   description: "Call this when `node --test` passes.",
+ *   input: z.object({}),
+ * });
+ *
+ * const body = jr2Setup({
+ *   events: [finish],
+ *   actors: { coder: agent({ model: open, instructions: "You fix the failing test." }), fail: fail() },
+ * }).createMachine({
+ *   id: "fix",
+ *   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
+ *   initial: "coding",
+ *   states: {
+ *     coding: {
+ *       invoke: { src: "coder", input: { prompt: "Make `node --test` pass." } },
+ *       on: { finish: "done" },
+ *     },
+ *     done: { type: "final" },
+ *     failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+ *     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+ *   },
+ * });
+ *
+ * // What a package exports: the repository and the model are Open.
+ * export const fix = workspace(body, {
+ *   repos: { app: open },
+ *   spec: () => ({ branch: "jr2/fix" }),
+ * });
+ *
+ * // What an Instance's `workflows/fix.ts` exports: the same Machine, its Open parts bound.
+ * export const machine = customize(fix, {
+ *   repos: { app: { url: "https://github.com/you/app.git" } },
+ *   agents: { coder: { model: "anthropic/claude-haiku-5-5" } },
+ * });
+ * ```
+ *
+ * @see docs/guides/bind-open-parts.md
+ * @see docs/concepts/composition.md
+ * @see docs/reference/decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md
  */
 export const open: unique symbol = Symbol.for("jr2.open");