@jr2/orchestrator 0.4.1 → 0.6.0

package/src/agent.ts

@@ -22,57 +22,133 @@
 
 import { open } from "./open.ts";
 
-/** jr2's reasoning-effort scale (ADR-0027) — a strict subset of the runtime's, so every value
- * passes through unmapped; mirrored by `@jr2/harness`'s spec contract. */
+// jr2's reasoning-effort scale (ADR-0027) — a strict subset of the runtime's, so every value
+// passes through unmapped; mirrored by `@jr2/harness`'s spec contract.
+/**
+ * How hard the model thinks before it answers: `"off"`, `"minimal"`, `"low"`, `"medium"`,
+ * `"high"` or `"xhigh"`. Set it on an Agent's definition (`thinkingLevel`), or for one Turn in the
+ * invoke's `input`.
+ *
+ * A model can lack a level. Claude Sonnet 5.5 has no `"off"`, and at `"off"` the Harness's request
+ * then sends effort `"high"`. The Harness does not refuse such a level: it runs the Turn, and the
+ * printed conversation names the level that the model ran at.
+ *
+ * @example
+ * ```ts
+ * import { agent, type ThinkingLevel } from "@jr2/orchestrator";
+ *
+ * const effort: ThinkingLevel = "high";
+ *
+ * export const reviewer = agent({
+ *   model: "anthropic/claude-haiku-5-5",
+ *   instructions: "You review diffs for correctness.",
+ *   thinkingLevel: effort,
+ * });
+ * ```
+ *
+ * @see docs/guides/set-an-agents-access-and-dials.md
+ * @see docs/reference/decisions/0018-instance-agents-are-definitions-jr2-assembles-the-harness.md
+ */
 export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
 
-/** What an Agent may DO to the Workspace (ADR-0028) — and, through `"none"`, where its Turn runs
- * (ADR-0031): the value the Agent actor reads off its own slot's definition to place the Turn. */
+// The value the Agent actor reads off its own slot's definition to place the Turn (ADR-0028,
+// ADR-0031).
+/** What an Agent may do to the Workspace: `"write"`, `"read"` or `"none"`. With `"none"`, its Turn
+ * runs on the Instance Harness, not in a Sandbox. The `workspace` field of {@link AgentDefinition}
+ * tells what each value gives. */
 export type WorkspaceAccess = "write" | "read" | "none";
 
-/** The plain-data Agent definition (ADR-0018): IDENTITY plus one default. A Turn's Frame — what
- * it is about and where it works — is not here and cannot be (ADR-0057): a Worktree path exists
- * only once a run has a branch, so no definition written before the run could name one.
+// The plain-data Agent definition (ADR-0018): IDENTITY plus one default. A Turn's Frame — what it
+// is about and where it works — is not here and cannot be (ADR-0057): a Worktree exists only
+// once a run has cut it, so no definition written before the run could name one.
+//
+// Must stay JSON-serializable: the definition rides the Turn to the Harness (ADR-0049), so
+// anything non-serializable would be silently lost — grow this contract deliberately. ADR-0028
+// added a restriction vocabulary (`workspace`), not an extension one: custom tool implementations
+// stay out of the contract.
+/**
+ * An Agent's definition: which model it runs, its instructions, and what it may do to the
+ * Workspace. Give it to `agent()` to get the Agent's actor slot. It is plain data that can be
+ * written as JSON.
+ *
+ * It holds who the Agent is, not what one Turn does. The prompt of a Turn and the directory it
+ * works in are the Frame. The state that invokes the Agent sets the Frame in the invoke's
+ * `input`. That `input` can also set `model` and `thinkingLevel` for one Turn: the Dials. It
+ * cannot change `instructions` or `workspace`.
  *
- * Must stay JSON-serializable: the definition rides
- * the Turn to the Harness (ADR-0049), so anything non-serializable would be silently lost — grow
- * this contract deliberately. ADR-0028 added a restriction vocabulary (`workspace`), not an
- * extension one: custom tool implementations stay out of the contract. */
+ * @example
+ * ```ts
+ * import { agent, type AgentDefinition } from "@jr2/orchestrator";
+ *
+ * const definition: AgentDefinition = {
+ *   model: "anthropic/claude-haiku-5-5",
+ *   instructions: "You fix the failing test, and you change nothing else.",
+ *   description: "Fixes one failing test",
+ *   thinkingLevel: "medium",
+ *   workspace: "write",
+ * };
+ *
+ * export const coder = agent(definition);
+ * ```
+ *
+ * @see docs/concepts/agents-and-turns.md
+ * @see docs/guides/set-an-agents-access-and-dials.md
+ * @see docs/reference/decisions/0018-instance-agents-are-definitions-jr2-assembles-the-harness.md
+ * @see docs/reference/decisions/0028-what-an-agent-may-do-to-the-workspace-is-part-of-its-definition.md
+ */
 export type AgentDefinition = {
-  /** Model specifier, `<provider>/<modelId>`, e.g. `anthropic/claude-sonnet-4-6`. REQUIRED —
-   * there is no instance-wide default (ADR-0018): `jr2.config.ts`'s `harness` section
-   * declares which providers are REACHABLE, and the definition makes the choice. This is also the
-   * only model `jr2 up` can preflight, since a workflow's is not statically recoverable. An
-   * invocation may override it for one Turn (`AgentTurnInput.model`). */
+  // REQUIRED, with no instance-wide default (ADR-0018): `jr2.config.ts`'s `harness` section
+  // declares which providers are REACHABLE, and the definition makes the choice. This is also the
+  // only model `jr2 up` can preflight, since a workflow's is not statically recoverable. An
+  // invocation may override it for one Turn (`AgentTurnInput.model`).
+  /** The model, as `<provider>/<modelId>`: for example `anthropic/claude-haiku-5-5`. The
+   * provider must be one that `jr2.config.ts` can reach. Here it is always a string: an `open`
+   * model of `agent()` must be bound before a Turn starts. One Turn may set another model in the
+   * invoke's `input`. */
   model: string;
-  /** The Agent's system prompt. */
+  /** The Agent's instructions: the text that tells the model who it is and how to work. The same
+   * on every Turn. */
   instructions: string;
-  /** Optional static description — observability, never sent to the model. */
+  /** A short description, for people who read the Machine. The model never reads it. */
   description?: string;
-  /** Reasoning effort. Omitted → the runtime's default. An invocation may override it for one
-   * Turn (`AgentTurnInput.thinkingLevel`) — effort is a property of the task's difficulty, so the
-   * same persona legitimately runs at different settings in different Machines. */
+  // Effort is a property of the task's difficulty, so the same persona legitimately runs at
+  // different settings in different Machines; an invocation may override it for one Turn
+  // (`AgentTurnInput.thinkingLevel`).
+  /** How hard the model thinks: one of {@link ThinkingLevel}. Absent: `"off"`. A model with no
+   * `"off"` runs at another level, and the printed conversation names it. One Turn may set another
+   * level in the invoke's `input`. */
   thinkingLevel?: ThinkingLevel;
-  /** What this Agent may DO to the Workspace (ADR-0028) — the persona in one word, deliberately
-   * not `tools` (that names the control-plane Menu, what it may SAY). `"read"` withholds the
-   * write/edit Working tools; bash stays, so this states intent and stops the honest path — the
-   * detached review worktree is the containment. `"none"` withholds the ENTIRE Working toolset:
-   * the Menu-only Agent converses and picks from its Menu, nothing else (so its Turn frames no
-   * directory — only Working tools consume one) — and places the Turn on the Instance Harness
-   * (ADR-0031). Default `"write"`. */
+  // The persona in one word (ADR-0028), deliberately not `tools` (that names the control-plane
+  // Menu, what it may SAY). `"read"` states intent and stops the honest path: bash stays, and a
+  // detached Worktree is the containment. `"none"` frames no directory — only Working tools
+  // consume one — and places the Turn on the Instance Harness (ADR-0031).
+  /** What the Agent may do to the Workspace. Default: `"write"`.
+   * - `"write"`: all the Working tools (read, write, edit, bash, grep, glob).
+   * - `"read"`: no write or edit tool. The Agent keeps bash, so `"read"` does not stop a command
+   *   that writes. To keep the Agent from changing the branch, frame its Turn in a detached
+   *   Worktree: cut it with `{ path, detach: sha }`, then give that `path` as `cwd`.
+   * - `"none"`: no Working tools. The Agent only reads its prompt and picks from its Menu. Its Turn
+   *   runs on the Instance Harness, not in a Sandbox, so it needs no `workspace()` around it. */
   workspace?: WorkspaceAccess;
 };
 
-/**
- * The Agent as an author DECLARES it (ADR-0054): the definition, except that `model` may be Open —
- * the one part a packaged Machine cannot honestly fill, since the package cannot pay for it. Every
- * other field is the wire's, because every other field a package CAN state.
- *
- * This is what `agent()` takes and what the slot's brand carries, so the walk and `customize()`
- * read the author's own answer, Open included. Nothing sends this: the wire takes an
- * {@link AgentDefinition}, and {@link requireBoundAgent} is the one door between the two.
- */
-export type AgentDeclaration = Omit<AgentDefinition, "model"> & { model: string | typeof open };
+// The Agent as an author DECLARES it (ADR-0054): the definition, except that `model` may be Open —
+// the one part a packaged Machine cannot honestly fill, since the package cannot pay for it. Every
+// other field is the wire's, because every other field a package CAN state.
+//
+// This is what `agent()` takes and what the slot's brand carries, so the walk and `customize()`
+// read the author's own answer, Open included. Nothing sends this: the wire takes an
+// AgentDefinition, and `requireBoundAgent` is the one door between the two.
+/** What `agent()` takes: an {@link AgentDefinition}, except that `model` can also be `open`. */
+export type AgentDeclaration = Omit<AgentDefinition, "model"> & {
+  /** The model, as `<provider>/<modelId>`: for example `anthropic/claude-haiku-5-5`. Required:
+   * there is no default model. The provider must be one that `jr2.config.ts` can reach.
+   *
+   * Or `open`, in a Machine that you publish as a package. Then the Instance that registers the
+   * Machine binds the model with `customize()`. One Turn may set another model in the invoke's
+   * `input`. */
+  model: string | typeof open;
+};
 
 /** The brand `agent(declaration)` stamps on its logic (ADR-0049): the declaration itself, readable
  * off the logic object. Everything that must recognize an Agent slot reads THIS — never a name

package/src/ambient.ts

@@ -21,13 +21,12 @@ import type { AnyActorRef } from "xstate";
 export type AmbientHandles = {
   endpoint: string;
   sandbox: string;
-  /** Every Repo Slot's branch-worktree path, by slot (ADR-0051). */
+  /** Every Repo Slot's folder, `/work/<slot>`, by slot (ADR-0051). */
   repos: Record<string, string>;
   /** Every Repo Slot's Binding url, by slot (ADR-0051): where a push goes. */
   bindings?: Record<string, string>;
-  branch: string;
-  /** Detached review-worktree paths, when the spec carried `reviewSha` (ADR-0028). */
-  review?: Record<string, string>;
+  /** Each Repo Slot's Binding base, where the Binding names one: a cut with no `from` starts here. */
+  bases?: Record<string, string>;
 };
 
 const byRef = new WeakMap<AnyActorRef, AmbientHandles>();

package/src/assembly-checks.ts

@@ -6,16 +6,55 @@
 
 import { isAbsolute, relative, sep } from "node:path";
 import type { AnyStateMachine } from "xstate";
+import { z } from "zod";
 import type { JR2Config } from "./config.ts";
 import { imageContextDigest, type ImageRefs } from "./images.ts";
 import { openPartsText } from "./open-effect.ts";
 import { customizeLine, partsOf, placedEffectsOf, workspacePodsOf } from "./parts.ts";
 import { refuseEffectSecrets, type PlacementWalk } from "./secret-placement.ts";
-import { chartFileRefusals, type ChartFile } from "./charts.ts";
+import {
+  chartFileRefusals,
+  chartName,
+  chartWrapperOf,
+  splitChartName,
+  wrapperFault,
+  type ChartFile,
+} from "./charts.ts";
+import { doorCompat } from "./door-compat.ts";
+
+// The comparison is the same one `jr2 up`'s foreign preflight makes, so it is exported beside the
+// walk the CLI already imports (ADR-0071).
+export { doorCompat, type DoorCompat } from "./door-compat.ts";
+import { inputSchemaOf, isZodSchema } from "./vocabulary.ts";
 
 /** One registered Workflow, as `loadWorkflows` gives it. */
 export type LoadedWorkflow = { name: string; machine: AnyStateMachine };
 
+/**
+ * Every registered Machine that has a zod `input` on its `createMachine` config and that `jr2Setup`
+ * did not make (ADR-0033). The `setup()` of xstate keeps that `input` in the config but does not read it,
+ * so the Machine has no door: a start with any input passes, and the Console start form is only a
+ * field for JSON. TypeScript accepts the config, so only this walk finds it. One line per Workflow,
+ * naming the fix.
+ * A Machine with no `input`, or with an `input` that is not zod, can still use `setup()`.
+ *
+ * The line text follows `refusing: ` in `jr2 up`'s output; the prefix is the caller's.
+ */
+export function doorRefusals(workflows: readonly LoadedWorkflow[]): string[] {
+  const lines: string[] = [];
+  for (const w of workflows) {
+    const declared = (w.machine.config as { input?: unknown }).input;
+    if (!isZodSchema(declared) || inputSchemaOf(w.machine)) continue;
+    lines.push(
+      `workflow "${w.name}": machine "${w.machine.id}" has a zod \`input\` on createMachine, but jr2Setup did not ` +
+        "make this Machine, so no door reads that input: a run starts with any input, and the Console start form " +
+        "is only a field for JSON — make the Machine with jr2Setup in place of setup() or createMachine() (leave " +
+        "out `events` if it takes no workflow event) (ADR-0033)",
+    );
+  }
+  return lines;
+}
+
 /**
  * Every part a registered Machine leaves Open (ADR-0051, ADR-0054): a Repo Slot with no url, an
  * Agent with no model, an Effect's url, argv or secret. One line per part, in walk order within
@@ -89,6 +128,139 @@ export function placementWalkOf(workflows: readonly LoadedWorkflow[]): Placement
   };
 }
 
+/**
+ * What a `dispatch` names, checked against what the walk can see (ADR-0071). Each dispatch with no
+ * target — a same-Instance one; a foreign target is `jr2 up`'s preflight, a warning — must name a
+ * Workflow the Assembly has: a Machine (`workflows/<name>.ts`), or `<wrapper>/<name>`, a named Chart
+ * under a Chart wrapper the Assembly registers, from a Chart file or (when `runtime` is given) a
+ * runtime Chart. A miss is an error. Without `runtime` — on the host, which cannot see the
+ * Orchestrator's volume — a slashed name under a known wrapper with no Chart file is a warning.
+ * Then the slot's input schema, when it has one, is compared with the callee's door
+ * (`doorCompat`): a fault is an error, naming the field; a schema outside the compared subset is a
+ * warning, "not compared".
+ *
+ * A dispatch resolves at RUN time against the current Assembly (ADR-0069); this check is of the
+ * Assembly being published, so a later publish that drops the callee answers `refused` with the
+ * door's 404 then, and is not refused for it here.
+ */
+export function dispatchRefusals(
+  workflows: readonly LoadedWorkflow[],
+  charts: readonly ChartFile[],
+  runtime?: readonly { name: string }[],
+): { errors: string[]; warnings: string[] } {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  const seen = new Set<string>();
+  for (const w of workflows) {
+    for (const effect of partsOf([w.machine]).effects) {
+      // A target, bound or Open, is another Orchestrator's: its door is not in this Assembly.
+      if (effect.kind !== "dispatch" || effect.target !== undefined || effect.open !== undefined) continue;
+      const name = effect.workflow;
+      const at = `workflow "${w.name}" dispatches "${name}"`;
+      const once = JSON.stringify([w.name, effect.name, name]);
+      if (seen.has(once)) continue;
+      seen.add(once);
+      const callee = calleeOf(workflows, charts, runtime, name);
+      if ("error" in callee) {
+        errors.push(`${at} ${callee.error} (ADR-0071)`);
+        continue;
+      }
+      // A slashed name with no Chart the host can see still has a known door: the wrapper's minus
+      // its Chart fields, the same for every Chart under it. So it is warned AND compared.
+      if (callee.warning) warnings.push(`${at}: ${callee.warning} (ADR-0071)`);
+      if (effect.input === undefined) continue;
+      if ("notDrawn" in callee.door) {
+        warnings.push(`${at}: its input schema and the door are not compared — ${callee.door.notDrawn} (ADR-0071)`);
+        continue;
+      }
+      const compared = doorCompat(effect.input, callee.door.schema);
+      if (compared.ok === "not-compared") {
+        warnings.push(`${at}: its input schema and the door are not compared — ${compared.why} (ADR-0071)`);
+      } else if (compared.ok === false) {
+        for (const fault of compared.faults) {
+          errors.push(
+            `${at} with input its door does not take: ${fault} — align the slot's \`input\` with the door ` +
+              "(derive it from the door's schema, `door.pick({ ... })`) (ADR-0071)",
+          );
+        }
+      }
+    }
+  }
+  return { errors, warnings };
+}
+
+/** The door a dispatch's name resolves to in these Workflows, or why it does not. */
+function calleeOf(
+  workflows: readonly LoadedWorkflow[],
+  charts: readonly ChartFile[],
+  runtime: readonly { name: string }[] | undefined,
+  name: string,
+): { door: Door; warning?: string } | { error: string } {
+  const split = splitChartName(name);
+  if (!split) {
+    const found = workflows.find((w) => w.name === name);
+    if (!found) {
+      return {
+        error:
+          `which no Workflow in the Assembly has — add workflows/${name}.ts, or name one it registers` +
+          (workflows.length ? `: ${workflows.map((w) => `"${w.name}"`).join(", ")}` : ""),
+      };
+    }
+    return { door: doorOf(found.machine, []) };
+  }
+  const { wrapper, name: short } = split;
+  const fault = wrapperFault(workflows, wrapper);
+  if (fault) {
+    return {
+      error:
+        fault.status === 404
+          ? `which no Workflow in the Assembly has — no workflows/${wrapper}.ts registers the Chart wrapper "${wrapper}"`
+          : `which no Workflow in the Assembly can be: ${fault.error}`,
+    };
+  }
+  const machine = workflows.find((w) => w.name === wrapper)!.machine;
+  const door = doorOf(machine, chartWrapperOf(machine)?.chartFields ?? []);
+  const file = `workflows/${wrapper}/${short}.chart.json`;
+  if (charts.some((c) => chartName(c.wrapper, c.name) === name)) return { door };
+  if (runtime === undefined) {
+    return {
+      door,
+      warning:
+        `the Assembly has no Chart file ${file}, and a runtime Chart lives on the Orchestrator's volume alone, ` +
+        "which jr2 up cannot see — the publish door checks it, and a run of the dispatch is refused with the door's " +
+        "404 if it is not there",
+    };
+  }
+  if (runtime.some((c) => c.name === name)) return { door };
+  return {
+    error:
+      `which no Workflow in the Assembly has — add the Chart file ${file}; or, for a runtime Chart, PUT ` +
+      `/workflows/${wrapper}/charts/${short} before this publish (a PUT needs "${wrapper}" in the current ` +
+      `Assembly: when this publish adds it, publish "${wrapper}" first, then PUT the Chart, then publish the dispatch)`,
+  };
+}
+
+/** A door as the comparison reads it: its JSON Schema (null: it declares no input), or why zod
+ * could not draw one. */
+type Door = { schema: Record<string, unknown> | null } | { notDrawn: string };
+
+/** A Workflow's door as JSON Schema, exactly as `GET /workflows/<name>` serves it (run-host.ts
+ * `inputSchema`): null for a Machine that declares none; for a named Chart the wrapper's minus its
+ * Chart fields, which the Chart supplies (ADR-0070). A door zod cannot draw (`z.date()`,
+ * `z.custom()`) is not drawn as "any", which would guess "compatible": it is not compared. */
+function doorOf(machine: AnyStateMachine, chartFields: readonly string[]): Door {
+  let schema = inputSchemaOf(machine);
+  if (!schema) return { schema: null };
+  if (chartFields.length) schema = schema.omit(Object.fromEntries(chartFields.map((f) => [f, true])) as never);
+  try {
+    return { schema: z.toJSONSchema(schema, { io: "input" }) as Record<string, unknown> };
+  } catch (err) {
+    return {
+      notDrawn: `the door has a part JSON Schema cannot state (${err instanceof Error ? err.message : String(err)})`,
+    };
+  }
+}
+
 export type AssemblyRefusalInput = {
   /** The Assembly's `jr2.config.ts`, loaded; `undefined` when it ships none. */
   config: JR2Config | undefined;
@@ -99,6 +271,12 @@ export type AssemblyRefusalInput = {
    * admitted against its wrapper's Open body by the same door a run's Chart passes. Absent, none.
    */
   charts?: readonly ChartFile[];
+  /**
+   * The runtime Charts on the Orchestrator's volume (ADR-0070), by Workflow name
+   * (`<wrapper>/<name>`): what a dispatch of a named Chart may resolve to beside the Chart files
+   * (ADR-0071). The door can see them; absent, none.
+   */
+  runtimeCharts?: readonly { name: string }[];
   /**
    * The image map the Orchestrator reads per provision (ADR-0038), or a reader of it. Present
    * only when deployed: a host-booted process has no map, and no Sandbox to provision. When
@@ -116,16 +294,20 @@ export type AssemblyRefusalInput = {
 /**
  * The door's walk (ADR-0069): the refusals the Orchestrator can see in an Assembly it has already
  * imported. An import error, a missing `export const machine` and a Vocabulary error are the
- * caller's: they throw at import, before this runs. Here: every Open part, a secret the config does
- * not declare (or a literal one too short to scrub), a `file:` image context whose digest the
- * mounted image map does not hold, and a Chart file that does not admit under its wrapper
- * (ADR-0070), each line naming the file. The door runs this after `jr2 up` did its cluster work, so each
- * check is true when the Assembly lands.
+ * caller's: they throw at import, before this runs. Here: a zod `input` that no door reads, every
+ * Open part, a secret the config does not declare (or a literal one too short to scrub), a `file:`
+ * image context whose digest the mounted image map does not hold, and a Chart file that does not
+ * admit under its wrapper (ADR-0070), each line naming the file. The door runs this after `jr2 up`
+ * did its cluster work, so each check is true when the Assembly lands.
  */
 export async function assemblyRefusals(input: AssemblyRefusalInput): Promise<string[]> {
-  const lines = openPartRefusals(input.workflows);
+  const lines = [...doorRefusals(input.workflows), ...openPartRefusals(input.workflows)];
   // A Chart file is the Instance's own (ADR-0070): one that fails refuses the publish.
   if (input.charts?.length) lines.push(...chartFileRefusals(input.charts, input.workflows));
+  // A same-Instance dispatch names a Workflow this Assembly has (ADR-0071). The door sees the
+  // runtime Charts, so a miss is an error here. Its warnings (a schema "not compared") have no
+  // channel in the publish's answer, and are dropped: `jr2 up` printed them before the publish.
+  lines.push(...dispatchRefusals(input.workflows, input.charts ?? [], input.runtimeCharts ?? []).errors);
   try {
     refuseEffectSecrets(input.config ?? {}, placementWalkOf(input.workflows));
   } catch (err) {