@jr2/orchestrator 0.4.1 → 0.6.0

package/docs/reference/authoring-surface/type-workspaced.md

@@ -0,0 +1,115 @@
+---
+title: Workspaced
+description: "The input of a `workspace()` body: the run input, plus `workspace`, the handles that the Workspace adds (`workspace.repos`, the folder of each Repo Slot)."
+---
+
+# `Workspaced`
+
+Type, in `@jr2/orchestrator/src/workspace.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Workspaces and Repos.
+
+```ts
+type Workspaced<TInput, TSlots extends string> = WithoutEmptyIndex<TInput> & {
+  workspace: WorkspaceHandles<TSlots>;
+};
+```
+
+The input of a `workspace()` body: the run input, plus `workspace`, the handles that the
+Workspace adds (`workspace.repos`, the folder of each Repo Slot). Use it as the type of
+the body's input.
+
+The first argument is the run input: the `input` schema of the `workspace()`. The second is the
+Repo Slots that the body reads, by name (`"app"` or `"app" | "docs"`). Under `repos: open`, write
+`string`: the body cannot know the names, so it reads the slots in order. For a `workspace()`
+with no `repos`, write `never`. The second argument has no default.
+
+A body under a root `workspace()` also gets the fields of `HostInjectedInput`. Add them when the
+body reads them: `Workspaced<HostInjectedInput & RunInput, "app">`.
+
+Its fields are the fields of the run input, and `workspace`. The run input can have no fields:
+`Workspaced<z.infer<typeof door>, "app">` for the door `z.object({})` holds only `workspace`.
+
+**Fields**: each field of [`WithoutEmptyIndex`](type-withoutemptyindex.md), and these:
+
+- `workspace`: `WorkspaceHandles<TSlots>`
+
+**Example**
+
+```ts
+import { z } from "zod";
+import {
+  agent,
+  defineEvent,
+  fail,
+  isReady,
+  jr2Setup,
+  workspace,
+  worktree,
+  type Workspaced,
+} from "@jr2/orchestrator";
+
+const done = defineEvent({
+  name: "done",
+  description: "Call this when REVIEW.md is written.",
+  input: z.object({}),
+});
+const runInput = z.object({ sha: z.string() });
+type BodyInput = Workspaced<z.infer<typeof runInput>, "app">;
+
+// A handle is the slot's folder: `/work/app`. A helper returns `as const`, so that the compiler
+// sees the slot.
+const reviewTree = (context: BodyInput) => `${context.workspace.repos.app}/review` as const;
+
+const body = jr2Setup({
+  types: {} as { input: BodyInput; context: BodyInput },
+  events: [done],
+  actors: {
+    reviewer: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You review one commit and write REVIEW.md.",
+      workspace: "read",
+    }),
+    cut: worktree(),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "review",
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".lost", "agent.fault": ".failed" },
+  initial: "cutting",
+  states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: reviewTree(context), detach: context.sha }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "reviewing" }, { target: "notCut" }],
+      },
+    },
+    reviewing: {
+      invoke: {
+        src: "reviewer",
+        input: ({ context }) => ({
+          prompt: `Review commit ${context.sha}.`,
+          cwd: reviewTree(context),
+        }),
+      },
+      on: { done: "finished" },
+    },
+    finished: { 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" } } },
+  },
+});
+
+export const machine = workspace(body, {
+  input: runInput,
+  repos: { app: "https://github.com/you/app.git" },
+});
+```
+
+**See also**
+
+- [Workspaces](../../concepts/workspaces.md)
+- [Write a Workflow](../../guides/write-a-workflow.md)
+- [ADR-0012: `workspace()` wraps a body Machine and owns only Sandbox lifecycle](../decisions/0012-workspace-wrapper-machine.md)
+- [ADR-0051: A Repo is a slot on the `workspace()` and a cache on the node](../decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md)

package/docs/reference/authoring-surface/type-workspacehandles.md

@@ -0,0 +1,22 @@
+---
+title: WorkspaceHandles
+description: "What the body of a `workspace()` gets as `input.workspace`: the folder of each Repo Slot."
+---
+
+# `WorkspaceHandles`
+
+Type, in `@jr2/orchestrator/src/workspace.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type WorkspaceHandles<TSlots extends string> = [TSlots] extends [never]
+  ? { repos: Record<never, string> }
+  : SlotHandles<TSlots>;
+```
+
+What the body of a `workspace()` gets as `input.workspace`: the folder of each Repo Slot. A path
+is correct in each Instance that registers the Machine.
+
+`TSlots` is the names of the Repo Slots that the body reads. `workspace()` refuses a body that
+names a slot that the Workspace does not have. Write `string` for a body that names no slot and
+reads the folders in the order of `repos`, as under `repos: open`. Write `never` for a
+Workspace with no Repo Slot: its handles are `{ repos: {} }`, and its Agents work in `/work`.

package/docs/reference/authoring-surface/type-workspacemachine.md

@@ -0,0 +1,29 @@
+---
+title: WorkspaceMachine
+description: A type that the Authoring surface names.
+---
+
+# `WorkspaceMachine`
+
+Type, in `@jr2/orchestrator/src/workspace.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type WorkspaceMachine<TInput, TOutput, TBody extends AnyStateMachine, TSlots extends string> = StateMachine<
+  any,
+  any,
+  any,
+  WrapperActors<"body", TBody, "place" | "provision" | "attach" | "registrar" | "lease" | "destroy" | "fail">,
+  any,
+  any,
+  any,
+  any,
+  any,
+  TInput,
+  TOutput,
+  any,
+  any,
+  any
+> &
+  JR2Wrapper<TBody> &
+  JR2Repos<TSlots>;
+```

package/docs/reference/authoring-surface/type-workspaceof.md

@@ -0,0 +1,13 @@
+---
+title: WorkspaceOf
+description: A type that the Authoring surface names.
+---
+
+# `WorkspaceOf`
+
+Type, in `@jr2/orchestrator/src/customize.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type WorkspaceOf<M extends AnyStateMachine> =
+  M extends JR2Repos<any> ? M : M extends JR2Wrapper<infer TBody> ? WorkspaceOf<TBody> : never;
+```

package/docs/reference/authoring-surface/type-workspaceoptions.md

@@ -0,0 +1,27 @@
+---
+title: WorkspaceOptions
+description: The options of a `workspace()` that declares the input that starts a run.
+---
+
+# `WorkspaceOptions`
+
+Type, in `@jr2/orchestrator/src/workspace.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type WorkspaceOptions<TSchema extends z.ZodObject, TSlots extends string> = SandboxOptions<
+  TSlots,
+  z.infer<TSchema>
+> & {
+  input: TSchema;
+};
+```
+
+The options of a `workspace()` that declares the input that starts a run.
+
+**Fields**: each field of [`SandboxOptions`](type-sandboxoptions.md), and these:
+
+- `input`: `TSchema`
+
+  The input that starts a run, as a `z.object`. jr2 checks each start against it. It also types
+  the `input` of a per-run Repo Slot, and the body must accept it plus the
+  `workspace` handles. Write it here, not on the body.

package/docs/reference/authoring-surface/type-worktreefound.md

@@ -0,0 +1,16 @@
+---
+title: WorktreeFound
+description: "What a cut found: `held`, a cut made this Worktree earlier, so what is in it is earlier work; `local`, a local branch; `remote`, `origin/<branch>`, now tracked; `none`, a new branch with no upstream; `commit`, a detached cut."
+---
+
+# `WorktreeFound`
+
+Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+type WorktreeFound = "held" | "local" | "remote" | "none" | "commit" | (string & {});
+```
+
+What a cut found: `held`, a cut made this Worktree earlier, so what is in it is earlier work;
+`local`, a local branch; `remote`, `origin/<branch>`, now tracked; `none`, a new branch with no
+upstream; `commit`, a detached cut. Open: a later value does not break an author's code.

package/docs/reference/authoring-surface/type-worktreeinput.md

@@ -0,0 +1,56 @@
+---
+title: WorktreeInput
+description: "The input of a `worktree()`: a branch Worktree, or a detached one."
+---
+
+# `WorktreeInput`
+
+Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+type WorktreeInput =
+  | {
+      path: AnyWorktreePath;
+      branch: string;
+      from?: string;
+      detach?: never;
+      expect?: never;
+    }
+  | {
+      path: AnyWorktreePath;
+      detach: string;
+      branch?: never;
+      from?: never;
+      expect?: never;
+    };
+```
+
+The input of a `worktree()`: a branch Worktree, or a detached one.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `path`, `branch`, `from`, `detach`, `expect`
+
+  - `path`: [`AnyWorktreePath`](type-anyworktreepath.md)
+
+    The root of the Worktree: `${context.workspace.repos.app}/<name>`, a constant word.
+  - `branch`: `string`
+
+    The branch. It resolves as a local branch, then `origin/<branch>` (tracked), then a new
+    branch.
+  - `from` (optional): `string`
+
+    Where a new branch starts. Default: the Binding's base. On a branch that exists, it must
+    be that branch's tip, or the cut is `refused`.
+  - `detach` (optional): `never`
+  - `expect` (optional): `never`
+- Form 2: `path`, `detach`, `branch`, `from`, `expect`
+
+  - `path`: [`AnyWorktreePath`](type-anyworktreepath.md)
+  - `detach`: `string`
+
+    The commit to check out, with no branch. The Worktree is forced to it and cleaned on each
+    cut. Ignored files stay, so that a reviewer can run the tests.
+  - `branch` (optional): `never`
+  - `from` (optional): `never`
+  - `expect` (optional): `never`

package/docs/reference/authoring-surface/type-worktreekey.md

@@ -0,0 +1,14 @@
+---
+title: WorktreeKey
+description: A type that the Authoring surface names.
+---
+
+# `WorktreeKey`
+
+Type, in `@jr2/orchestrator/src/effect.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type WorktreeKey<Opt> = [Opt] extends [{ readonly env: object }]
+  ? { worktree: AnyWorktreePath }
+  : { worktree?: AnyWorktreePath };
+```

package/docs/reference/authoring-surface/type-worktreeoptions.md

@@ -0,0 +1,29 @@
+---
+title: WorktreeOptions
+description: The options of `worktree()`.
+---
+
+# `WorktreeOptions`
+
+Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+type WorktreeOptions = {
+  expect?: "new" | "existing";
+  timeout?: Duration;
+};
+```
+
+The options of `worktree()`.
+
+**Fields**
+
+- `expect` (optional): `"new" | "existing"`
+
+  `"new"`: refuse a branch that exists, local or on the remote. For a name that a planner or a
+  door chose for new work: a collision is a refusal, not someone else's branch. `"existing"`:
+  refuse a branch that does not exist, and make nothing. For a run that must continue a branch.
+  A Chart cannot change it, and a cut lent to a Chart must state it.
+- `timeout` (optional): [`Duration`](type-duration.md)
+
+  How long the fetch and the cut can take. Default `"10m"`.

package/docs/reference/authoring-surface/type-worktreeoutput.md

@@ -0,0 +1,45 @@
+---
+title: WorktreeOutput
+description: The output of a `worktree()`.
+---
+
+# `WorktreeOutput`
+
+Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+type WorktreeOutput<S extends string = string> = WorktreeReady<S> | WorktreeRefused | Unknown | LaterOutcome;
+```
+
+The output of a `worktree()`. `unknown`: its state exited while it ran, or the cut did not end.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `outcome`, `reason`
+
+  - `outcome`: `"unknown"`
+  - `reason`: `string`
+- Form 2: `outcome`, `slot`, `path`, `branch`, `head`, `found`, `stale`
+
+  - `outcome`: `"ready"`
+  - `slot`: `S`
+  - `path`: `WorktreePath<S>`
+  - `branch`: `string | null`
+
+    The branch of the cut, from git and the cut's record, never from the folder or HEAD. `null`
+    when the Worktree is detached.
+  - `head`: `string`
+
+    The tip of `branch` (of the commit, when detached). Never HEAD.
+  - `found`: [`WorktreeFound`](type-worktreefound.md)
+  - `stale` (optional): `string`
+
+    [ADR-0053](../decisions/0053-a-fetch-inside-the-pod-asks-the-node-cache-and-the-cache-asks-the-remote.md)'s words when the remote did not answer. The cut used what the clone holds.
+- Form 3: `outcome`, `reason`
+
+  - `outcome`: `"refused"`
+  - `reason`: `string`
+- Form 4: `outcome`, `reason`
+
+  - `outcome`: `"(a later outcome)"`
+  - `reason` (optional): `string`

package/docs/reference/authoring-surface/type-worktreepath.md

@@ -0,0 +1,16 @@
+---
+title: WorktreePath
+description: A Worktree of the Repo Slots `S`.
+---
+
+# `WorktreePath`
+
+Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+type WorktreePath<S extends string> = `/work/${S}/${NameStart}${string}`;
+```
+
+A Worktree of the Repo Slots `S`. One segment below the slot, that starts with a letter, a
+digit or `_`: `${context.workspace.repos.app}/run`. The compiler sees the start of the name; a
+`/` further on is the Effect's own refusal.

package/docs/reference/authoring-surface/type-worktreeready.md

@@ -0,0 +1,37 @@
+---
+title: WorktreeReady
+description: Type, an export of @jr2/orchestrator.
+---
+
+# `WorktreeReady`
+
+Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+type WorktreeReady<S extends string = string> = {
+  outcome: "ready";
+  slot: S;
+  path: WorktreePath<S>;
+  branch: string | null;
+  head: string;
+  found: WorktreeFound;
+  stale?: string;
+};
+```
+
+**Fields**
+
+- `outcome`: `"ready"`
+- `slot`: `S`
+- `path`: `WorktreePath<S>`
+- `branch`: `string | null`
+
+  The branch of the cut, from git and the cut's record, never from the folder or HEAD. `null`
+  when the Worktree is detached.
+- `head`: `string`
+
+  The tip of `branch` (of the commit, when detached). Never HEAD.
+- `found`: [`WorktreeFound`](type-worktreefound.md)
+- `stale` (optional): `string`
+
+  [ADR-0053](../decisions/0053-a-fetch-inside-the-pod-asks-the-node-cache-and-the-cache-asks-the-remote.md)'s words when the remote did not answer. The cut used what the clone holds.

package/docs/reference/authoring-surface/type-worktreerefused.md

@@ -0,0 +1,21 @@
+---
+title: WorktreeRefused
+description: "No Worktree, and nothing changed: a bad path, a name git or the push refuses, a re-cut that does not agree with the first, a branch that another Worktree holds, an `expect` that does not hold, or a name that the remote cannot confirm."
+---
+
+# `WorktreeRefused`
+
+Type, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+type WorktreeRefused = { outcome: "refused"; reason: string };
+```
+
+No Worktree, and nothing changed: a bad path, a name git or the push refuses, a re-cut that does
+not agree with the first, a branch that another Worktree holds, an `expect` that does not hold, or a
+name that the remote cannot confirm.
+
+**Fields**
+
+- `outcome`: `"refused"`
+- `reason`: `string`