@jr2/orchestrator 0.3.0 → 0.5.1

package/docs/guides/publish-a-machine-as-an-npm-package.md

@@ -0,0 +1,350 @@
+---
+title: Publish a Machine as an npm package
+description: Ship a Machine in an npm package that names the Kit as a peer, and register it in an Instance.
+---
+
+# Publish a Machine as an npm package
+
+Publish a [Machine](../reference/glossary.md#machine) as an npm package, so that each
+[Instance](../reference/glossary.md#instance) can install it and register it as a
+[Workflow](../reference/glossary.md#workflow).
+
+The example package is `@you/labeler`. It exports one Machine, `labeler`: an [Agent](../reference/glossary.md#agent)
+reads an issue and chooses one label for it. The Machine gives the label as its output. The package leaves the model of
+the Agent [Open](../reference/glossary.md#open), because it cannot know which model each Instance uses. `@jr2/machines`
+has the same shape.
+
+Replace `@you` with your npm scope in each file and each command on this page.
+
+## The package
+
+The package has three files:
+
+```text
+labeler/
+├── package.json
+├── tsconfig.json
+└── src/
+    └── index.ts
+```
+
+`package.json`:
+
+```json
+{
+  "name": "@you/labeler",
+  "version": "1.0.0",
+  "description": "A jr2 Machine that gives an issue one label.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "types": "./src/index.ts",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@jr2/orchestrator": "<version>",
+    "xstate": "^5.18.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@jr2/orchestrator": "<version>",
+    "@types/node": "^26.0.1",
+    "typescript": "^5.6.0",
+    "xstate": "^5.18.0",
+    "zod": "^4.4.3"
+  }
+}
+```
+
+- `peerDependencies` names `@jr2/orchestrator`, `xstate` and `zod`. The package has no `dependencies`. Replace
+  `<version>` with the [Kit version](../reference/glossary.md#kit-version) that the package is for, such as `0.4.1`.
+  Write the exact version, with no `^` and no `~`.
+- `devDependencies` also names the three packages, at the same versions, and `typescript` and `@types/node`. With them,
+  you can typecheck the package.
+- `exports` gives the `.ts` files, and `files` ships `src`. The package has no build step. jr2 loads `.ts` files from
+  `node_modules`, the same as it loads `@jr2/orchestrator` and `@jr2/machines`.
+
+`tsconfig.json` uses the options of an Instance. The typecheck of an Instance also checks the `.ts` files of each
+package that it imports, so the package must pass the same options:
+
+```json
+{
+  "extends": "@jr2/orchestrator/tsconfig.instance.json",
+  "include": ["src/**/*.ts"]
+}
+```
+
+`src/index.ts` exports the Machine, and the type of its output:
+
+```ts
+import { assign } from "xstate";
+import { z } from "zod";
+import { agent, defineEvent, fail, jr2Setup, open } from "@jr2/orchestrator";
+
+// The Agent's one pick.
+const label = defineEvent({
+  name: "label",
+  description: "Give the issue one label. Call this once, then stop.",
+  audience: "agent",
+  input: z.object({
+    kind: z
+      .enum(["bug", "feature", "question"])
+      .describe(
+        "bug: something does not work. feature: a request. question: the author asks for help or for information.",
+      ),
+    reason: z.string().describe("Why, in one sentence."),
+  }),
+});
+
+const door = z.object({
+  title: z.string().describe("The title of the issue."),
+  body: z.string().describe("The text of the issue."),
+});
+
+type Input = z.infer<typeof door>;
+export type LabelerOutput = { kind: "bug" | "feature" | "question"; reason: string };
+
+/**
+ * A Machine that gives an issue one label.
+ *
+ * Open part: `agents.labeler.model`. Bind it with `customize()` where you register the Machine.
+ *
+ * Run input: `{ title, body }`, the title and the text of the issue.
+ *
+ * Output: `{ kind, reason }`. `kind` is `bug`, `feature` or `question`.
+ *
+ * Fails the run when the Turn of the Agent fails: the reason of the Failure is `no label: ` and the
+ * reason of the fault.
+ */
+export const labeler = jr2Setup({
+  types: {} as { input: Input; context: Input & { result?: LabelerOutput; fault?: string }; output: LabelerOutput },
+  events: [label],
+  actors: {
+    labeler: agent({
+      // Open: the Instance that registers this Machine binds the model with customize().
+      model: open,
+      workspace: "none",
+      instructions: "You read one issue and give it one label. Call label once.",
+    }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "labeler",
+  input: door,
+  context: ({ input }) => input,
+  initial: "labeling",
+  states: {
+    labeling: {
+      invoke: {
+        src: "labeler",
+        input: ({ context }) => ({ prompt: `Title: ${context.title}\n\n${context.body}` }),
+      },
+      on: {
+        label: {
+          target: "done",
+          actions: assign({ result: ({ event }) => ({ kind: event.kind, reason: event.reason }) }),
+        },
+        // jr2 sends this when the Agent's Turn fails for good.
+        "agent.fault": { target: "failed", actions: assign({ fault: ({ event }) => event.reason }) },
+      },
+    },
+    done: { type: "final" },
+    // Not a final state: the run ends `failed`. The reason of the Failure is `no label: ` and the reason of the fault.
+    failed: { invoke: { src: "fail", input: ({ context }) => ({ reason: `no label: ${context.fault}` }) } },
+  },
+  output: ({ context }) => context.result!,
+});
+```
+
+The Machine carries all of its parts: its run input, its [Vocabulary](../reference/glossary.md#vocabulary) and its
+Agent. The model is [`open`](../reference/authoring-surface/open.md), so the Instance binds it with
+[`customize()`](../reference/authoring-surface/customize.md). On the export, write TSDoc that gives its Open parts and
+its run input, as [`task`](../reference/machines.md#task) does. An [Assistant](../reference/glossary.md#assistant) that
+reads `node_modules` reads that text.
+
+## Check the package
+
+In the folder of the package, install the `devDependencies`. Then typecheck the package:
+
+```sh
+npm install
+npm run typecheck
+```
+
+Then see what the package ships:
+
+```sh
+npm pack --dry-run
+```
+
+```text
+npm notice
+npm notice 📦  @you/labeler@1.0.0
+npm notice Tarball Contents
+npm notice 623B package.json
+npm notice 2.4kB src/index.ts
+npm notice Tarball Details
+npm notice name: @you/labeler
+npm notice version: 1.0.0
+npm notice filename: you-labeler-1.0.0.tgz
+npm notice package size: 1.4 kB
+npm notice unpacked size: 3.0 kB
+npm notice shasum: b4b5fd9c9ddff44b1be2e852e89969bdbe76750c
+npm notice integrity: sha512-5CXrYzHDj/Qy8[...]70mtq84+C6+6w==
+npm notice total files: 2
+npm notice
+you-labeler-1.0.0.tgz
+```
+
+The list holds `package.json` and the files of `src`. Your sizes and sums are different.
+
+## Publish the package
+
+Log in to your registry with `npm login`. Then publish the package. npm publishes a package with a scope, such as
+`@you`, as restricted, unless you give `--access public`:
+
+```sh
+npm publish --access public
+```
+
+## Register the Machine in an Instance
+
+In the Instance folder, install the package. Use npm's `--save-exact`, so that `package.json` names one version:
+
+```sh
+npm install --save-exact @you/labeler@1.0.0
+```
+
+Make sure that the Instance has one copy of `@jr2/orchestrator`:
+
+```sh
+npm ls @jr2/orchestrator
+```
+
+```text
+my-instance@0.0.0 <path>
+├─┬ @jr2/cli@0.4.1
+│ └── @jr2/orchestrator@0.4.1 deduped
+├── @jr2/orchestrator@0.4.1
+└─┬ @you/labeler@1.0.0
+  └── @jr2/orchestrator@0.4.1 deduped
+```
+
+`<path>` is the path of your Instance folder, and the version is your Kit version. Each line names the same version.
+Each `deduped` line tells you that the package uses the copy of the Instance.
+
+Save this file as `workflows/label.ts`. It binds the Open model of the Agent `labeler` to the model of the tab:
+
+**Anthropic**
+
+```ts
+import { customize } from "@jr2/orchestrator";
+import { labeler } from "@you/labeler";
+
+export const machine = customize(labeler, {
+  agents: { labeler: { model: "anthropic/claude-haiku-5-5" } },
+});
+```
+
+**Local**
+
+```ts
+import { customize } from "@jr2/orchestrator";
+import { labeler } from "@you/labeler";
+
+export const machine = customize(labeler, {
+  agents: { labeler: { model: "local/qwen3.6-35b-a3b" } },
+});
+```
+
+Run [`jr2 up`](../reference/cli.md#up):
+
+```sh
+jr2 up
+```
+
+```text
+…
+jr2 up — instance "my-instance" → context <context> / namespace my-instance
+typecheck: tsc --noEmit (the instance's own compiler)
+failures: workflow "label" — the states that fail the run (ADR-0073)
+  labeler.failed: invokes fail
+seats: workflow "label" — who may send what, per state (ADR-0015)
+  labeler.labeling agent:labeler: [label]
+…
+```
+
+The first line (`…`) is the `.env` line, when `.env` sets a variable that your shell does not set. `<context>` is your
+kubectl context. The `seats:` lines show that jr2 reads the Vocabulary of the Machine. [Start a run](start-a-run.md)
+tells how to run the Workflow `label`.
+
+## Rules
+
+- Name `@jr2/orchestrator`, `xstate` and `zod` in `peerDependencies`, never in `dependencies`.
+- When the package names `@jr2/orchestrator` in `dependencies` at a different version, npm installs a second copy under
+  the package, with no error. A Machine that loads a second copy has empty [Menus](../reference/glossary.md#menu). Thus
+  `jr2 up` refuses the Instance before it applies anything. It gives one line for each Kit package that has a second
+  copy, such as `@jr2/orchestrator` and `@jr2/agent-protocol`:
+
+  ```text
+  error: cannot stage the Assembly: it would carry a second copy of a Kit package (ADR-0069)
+    <path> is a second copy of <name>, nested by <package>@<package version> (<package path>): the Orchestrator's image ships <name> for @jr2/orchestrator <version>, and an Assembly that carries its own copy loads Machines whose Menus are empty (ADR-0054) — align that dependency with the <name> @jr2/orchestrator uses, or remove it, and reinstall
+  ```
+
+  Run `npm ls @jr2/orchestrator` to find the second copy.
+
+- Name `@jr2/orchestrator` at the exact Kit version. When the Instance has a different Kit version, npm refuses to
+  install the package:
+
+  ```text
+  npm error code ERESOLVE
+  npm error ERESOLVE unable to resolve dependency tree
+  …
+  npm error Could not resolve dependency:
+  npm error peer @jr2/orchestrator@"<version>" from <package>@<package version>
+  …
+  ```
+
+  `<package>@<package version>` is the package and the version that you install.
+
+  Do not install with `--force` or `--legacy-peer-deps`. Publish a version of the package for the Kit version of the
+  Instance. Thus each [upgrade of the Kit version](upgrade-the-kit-version.md) needs a new version of the package.
+
+- In the Instance, the package must be in `dependencies`, not in `devDependencies`. The
+  [Assembly](../reference/glossary.md#assembly) holds only `dependencies`. Without the package, the
+  [Orchestrator](../reference/glossary.md#orchestrator) cannot load the Workflow, and it refuses the Assembly.
+- The typecheck of `jr2 up` includes the `.ts` files of the package. A type error in it stops the converge:
+  `refusing: this instance does not typecheck — nothing was built and nothing was applied`.
+- Use only TypeScript that jr2 can erase: no `enum`, no `namespace`, and no parameter properties in a constructor. The
+  typecheck accepts them, but `jr2 up` cannot load the Workflow. It stops with a JavaScript syntax error, such as
+  `error: Unexpected token 'export'`.
+- Write each relative import in the package with the `.ts` extension, as `./util.ts`. With `.js`, the typecheck passes,
+  but `jr2 up` stops: `error: Cannot find module '<path>/util.js' imported from <path>/index.ts`.
+- A package exports Machines, never Workflows. A Workflow is a file in the `workflows/` folder of an Instance.
+- `jr2 up` refuses a Workflow that leaves a part Open. It prints the `customize()` line that binds it:
+  `refusing: workflow "<workflow>" leaves Agent "<slot>" open — bind it where the Machine is registered: export const machine = customize(<import>, { agents: { <slot>: { model: "<provider>/<model>" } } })  (ADR-0054)`.
+  [Bind a shipped Machine's Open parts](bind-open-parts.md) gives the refusals for the other Open parts.
+- A new version of the package can change the [Machine shape](../reference/glossary.md#machine-shape): its states, its
+  invokes or its transitions. Then the Orchestrator does not continue a run that the old version started. Its status is
+  `drifted`. See [Machine shape and drift](../concepts/durable-runs.md#machine-shape-and-drift).
+
+## Read next
+
+- [Composition](../concepts/composition.md)
+- [Bind a shipped Machine's Open parts](bind-open-parts.md)
+- [Durable runs](../concepts/durable-runs.md)
+- Reference: [`customize()`](../reference/authoring-surface/customize.md),
+  [`open`](../reference/authoring-surface/open.md), [`@jr2/machines`](../reference/machines.md)
+- [ADR-0054](../reference/decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md): the kit
+  ships Machines, and a shipped Machine leaves its parts Open
+- [ADR-0049](../reference/decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md): a Machine carries its
+  parts and composes by invoke