@jr2/orchestrator 0.5.1 → 0.7.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,11 +46,13 @@ 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 { isGateSlot } from "./gate.ts";
+import { open } from "./open.ts";
 import { actorPath, boundRun } from "./registration.ts";
 import { COMPILED_CHART, jr2Setup } from "./setup.ts";
 import { attachBoundMachine, boundMachineFor } from "./vocabulary.ts";
@@ -111,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. */
@@ -119,6 +126,7 @@ export type Lends = {
   agents?: string[];
   effects?: string[];
   machines?: string[];
+  gates?: string[];
   guards?: string[];
   actions?: string[];
   delays?: string[];
@@ -157,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)$/;
@@ -166,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`;
@@ -516,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 ?? [])],
@@ -573,9 +586,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) {
@@ -627,11 +643,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
@@ -648,7 +676,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)));
@@ -675,7 +706,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 {}
 
 /**
@@ -839,6 +870,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)]));
 
@@ -847,15 +882,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>();
@@ -867,13 +904,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",
@@ -885,9 +924,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
@@ -918,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) {
@@ -926,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);
   }
@@ -935,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);
@@ -964,7 +1034,7 @@ 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, 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
+ * 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",
@@ -984,7 +1054,7 @@ 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.
@@ -992,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",
@@ -1000,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",
@@ -1018,7 +1091,11 @@ export function compileChart(
     events: admitted.events,
     actors,
     // `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,
+    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;
@@ -1382,7 +1459,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,

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,17 +14,30 @@
  * - 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
  * import { z } from "zod";
- * import { agent, customize, defineEvent, fail, jr2Setup, open, workspace } from "@jr2/orchestrator";
+ * import {
+ *   agent,
+ *   customize,
+ *   defineEvent,
+ *   fail,
+ *   isReady,
+ *   jr2Setup,
+ *   open,
+ *   workspace,
+ *   worktree,
+ *   type Workspaced,
+ * } from "@jr2/orchestrator";
  *
  * const finish = defineEvent({
  *   name: "finish",
@@ -32,19 +45,40 @@
  *   input: z.object({}),
  * });
  *
+ * type Input = Workspaced<{}, "app">;
+ *
+ * const fixTree = (context: Input) => `${context.workspace.repos.app}/fix` as const;
+ *
  * const body = jr2Setup({
+ *   types: {} as { context: Input; input: Input },
  *   events: [finish],
- *   actors: { coder: agent({ model: open, instructions: "You fix the failing test." }), fail: fail() },
+ *   actors: {
+ *     coder: agent({ model: open, instructions: "You fix the failing test." }),
+ *     cut: worktree(),
+ *     fail: fail(),
+ *   },
  * }).createMachine({
  *   id: "fix",
+ *   context: ({ input }) => input,
  *   on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
- *   initial: "coding",
+ *   initial: "cutting",
  *   states: {
+ *     cutting: {
+ *       invoke: {
+ *         src: "cut",
+ *         input: ({ context }) => ({ path: fixTree(context), branch: "jr2/fix" }),
+ *         onDone: [{ guard: ({ event }) => isReady(event.output), target: "coding" }, { target: "notCut" }],
+ *       },
+ *     },
  *     coding: {
- *       invoke: { src: "coder", input: { prompt: "Make `node --test` pass." } },
+ *       invoke: {
+ *         src: "coder",
+ *         input: ({ context }) => ({ prompt: "Make `node --test` pass.", cwd: fixTree(context) }),
+ *       },
  *       on: { finish: "done" },
  *     },
  *     done: { type: "final" },
+ *     notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
  *     failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
  *     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
  *   },
@@ -53,7 +87,6 @@
  * // 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.