@jr2/orchestrator 0.4.1 → 0.6.0

package/docs/reference/authoring-surface/file.md

@@ -0,0 +1,142 @@
+---
+title: file
+description: "Make a Worktree file the body of an `http` Effect: `body: file(\"dist/report.pdf\")`."
+---
+
+# `file`
+
+Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+```ts
+function file<S extends z.ZodType | undefined = undefined>(path: FromInput<S, string>, options: {
+  segments?: FromInput<S, readonly string[]>;
+  contentType?: string;
+} = {}): FileBody<S>
+```
+
+Make a Worktree file the body of an `http` Effect: `body: file("dist/report.pdf")`. The Effect
+then runs in the Sandbox Effector of the Workspace whose body invokes it. Under a Workspace with
+Repo Slots, the invoke's input names the Worktree: `input: { worktree: "/work/app/fix" }`. It is a
+Worktree that a cut of this run made. That Effector opens the file in that Worktree and sends it.
+In a Workspace with no Repo Slot, the input names no `worktree`, and the path is relative to
+`/work`, the folder that its steps share. Use it with `PUT`, `POST` or `PATCH`. `path` and
+`segments` can be functions of the input of the Effect.
+
+Some inputs, paths and files give the output `refused`, and then nothing is sent. The `worktree`
+has no cut in this Sandbox: `no cut made <path> in this Sandbox: cut it with worktree(); nothing
+was sent`. Or the input names a `worktree` in a Workspace with no Repo Slot. Or the path has a
+symlink in it, has `..`, or is absolute. Or the file is a FIFO, a directory, or a file with more
+than one link.
+
+It refuses, when you call it:
+- a path that is not a string or a function: `file(path): the path is a string, or a function of
+  the Effect's input that returns one`
+
+And when `http` takes the definition:
+- a method other than `PUT`, `POST` and `PATCH`: `http({ method: "<method>", body: file(...) }):
+  a file body is sent with PUT, POST, PATCH (ADR-0068)`
+- a `request` beside it: ``http({ body: file(...), request }): with a file body the run's part
+  is file()'s — its path, from the input if it must be, and its `segments` — so write no
+  `request` (ADR-0068)``
+- a `content-type` header and `contentType`: `http({ headers, body: file(path, { contentType })
+  }): "content-type" is set by file()'s contentType — write one of them (ADR-0067)`
+
+And at `jr2 up`, an Effect that no `workspace()` invokes: `workflow "<workflow>": the http Effect
+"<slot>" sends a Worktree file as its body, and no workspace() invokes it — outside a Workspace
+there is no Worktree to read; invoke it from a workspace()'s body, or send a json or text body
+(ADR-0068)`.
+
+And when it starts, under a Workspace with Repo Slots, an input with no `worktree`: ``http
+"<slot>" reads a Worktree file, under a Workspace with Repo Slots, and its input names no
+`worktree` ``.
+
+**Parameters**
+
+- `path` ([`FromInput`](type-frominput.md)): The file, relative to the Worktree that `worktree` of the input names, or to
+  `/work` in a Workspace with no Repo Slot: a string, or a function of the input of the Effect
+  that gives one.
+- `options`: Optional. Each field says what it does.
+
+  - `segments` (optional): `FromInput<S, readonly string[]>`
+
+    Path segments that jr2 adds to the end of the url, as `path` does in `request` for a json or
+    text body. A list of strings, or a function of the input of the Effect that gives one.
+  - `contentType` (optional): `string`
+
+    The content type of the body. Default `application/octet-stream`. Do not write it beside a
+    `content-type` header.
+
+**Returns**: The `body` of an `http` Effect.
+
+**Example**
+
+```ts
+import {
+  bearer,
+  command,
+  fail,
+  file,
+  http,
+  isReady,
+  jr2Setup,
+  secret,
+  workspace,
+  worktree,
+  type Workspaced,
+} from "@jr2/orchestrator";
+
+type Input = Workspaced<{}, "app">;
+
+const reportTree = (context: Input) => `${context.workspace.repos.app}/report` as const;
+
+const body = jr2Setup({
+  types: {} as { context: Input; input: Input },
+  actors: {
+    cut: worktree(),
+    build: command(["npm", "run", "report"]),
+    upload: http({
+      method: "PUT",
+      url: "https://files.example.com/reports",
+      auth: bearer(secret("files")),
+      body: file("dist/report.pdf", {
+        segments: ["report.pdf"],
+        contentType: "application/pdf",
+      }),
+    }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "report",
+  context: ({ input }) => input,
+  on: { "workspace.lost": ".lost" },
+  initial: "cutting",
+  states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: reportTree(context), branch: "report" }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "building" }, { target: "notCut" }],
+      },
+    },
+    building: {
+      invoke: { src: "build", input: ({ context }) => ({ worktree: reportTree(context) }), onDone: "uploading" },
+    },
+    uploading: {
+      invoke: { src: "upload", input: ({ context }) => ({ worktree: reportTree(context) }), onDone: "done" },
+    },
+    done: { type: "final" },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
+    lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+  },
+});
+
+export const machine = workspace(body, {
+  repos: { app: { url: "https://github.com/you/app.git" } },
+});
+```
+
+**See also**
+
+- [Run a command or call a URL with an Effect](../../guides/run-a-command-or-call-a-url.md)
+- [Effects](../../concepts/effects.md)
+- [ADR-0067: An Effect is an actor slot, and runs at most once unless marked idempotent](../decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)

package/docs/reference/authoring-surface/frompick.md

@@ -0,0 +1,277 @@
+---
+title: fromPick
+description: "Make the `input` of the invoke of a state that a pick enters: the params of the pick go to the input of the invoked actor by name."
+---
+
+# `fromPick`
+
+Function, in `@jr2/orchestrator/src/pick.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+## Overload 1
+
+```ts
+function fromPick<
+  N extends string,
+  I extends z.ZodObject,
+  C,
+  E extends EventObject,
+>(
+  def: EventDef<N, I>,
+): (args: { context: C; event: E; self: AnyActorRef }) => z.infer<I>
+```
+
+Make the `input` of the invoke of a state that a pick enters: the params of the pick go to the
+input of the invoked actor by name. With `fill`, the Machine adds the keys that the Agent must
+not choose. So one expression shows the security boundary: the pick is what the Agent gives, and
+`fill` is what the Machine adds.
+
+TypeScript checks the params and the keys of `fill` together against the input type of the
+invoked actor. It finds a missing key or a key of the wrong type, but it accepts an extra key.
+
+So `createMachine` refuses:
+- a param that is no key of the input of the Effect, and that nothing else reads: ``machine
+  "<id>": pick "<pick>" enters state "<state>" (Effect "<slot>") with fromPick: "<param>" is no
+  key of the Effect's input (<keys>), and nothing else reads it — the Agent supplies it and it
+  reaches nothing; name an argv slot for it, read it in `fill`, store it with assign, or drop it
+  from the def``
+- a key that `fill` sets and that is also a param: ``machine "<id>": pick "<pick>" enters state
+  "<state>" (Effect "<slot>"): `fill` sets "<param>", which is also a param of the pick — the
+  Machine's value wins and the Agent's is dropped; rename one, or drop it from the def``
+- a `fromPick` in a state that another event enters: `machine "<id>": state "<state>" (Effect
+  "<slot>") reads the params of pick "<pick>" but is entered on "<event>" — that event does not
+  carry them`
+
+The input of an Open argv is one string for each key, so TypeScript checks no key for it. A key
+that the bound argv names and the input does not give stops the Effect when it starts.
+
+The state that the pick enters has one of two places:
+- A child state of the Agent's state, as in the first example. The Turn stays open, and the
+  pick is outstanding until the Effect ends. Use this shape when the Agent must see the result.
+  The Agent reads the Effect's output as the answer only when the route after the Effect stays
+  in the Agent's state, as `onDone: "ready"` does. Then the Agent can pick again. A route that
+  leaves the Agent's state ends the Turn when the Effect ends, and no Agent reads the output.
+- A sibling state of the Agent's state, as in the second example. The pick leaves the Agent's
+  state, so the Turn ends before the Effect runs, and the Agent does not see the output. Use
+  this shape for a pick that ends the work of the Agent.
+
+**Parameters**
+
+- `def` ([`EventDef`](type-eventdef.md)): The pick, as `defineEvent` made it.
+
+**Returns**: An `input` mapper for the `invoke` of the state.
+
+**Example**
+
+```ts
+import { z } from "zod";
+import { agent, defineEvent, fail, fromPick, http, jr2Setup } from "@jr2/orchestrator";
+
+const postNote = defineEvent({
+  name: "post_note",
+  description: "Post a note to the team channel.",
+  input: z.object({ text: z.string() }),
+});
+
+const finish = defineEvent({
+  name: "finish",
+  description: "The note is posted. This ends your work.",
+  input: z.object({}),
+});
+
+export const machine = jr2Setup({
+  types: {} as { context: {}; input: {} },
+  events: [postNote, finish],
+  actors: {
+    writer: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You write one short note for the team.",
+      workspace: "none",
+    }),
+    note: http({
+      method: "POST",
+      url: "https://hooks.example.com/notes",
+      input: z.object({ text: z.string() }),
+      request: ({ text }) => ({ json: { text } }),
+    }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "note",
+  on: { "agent.fault": ".failed" },
+  initial: "writing",
+  states: {
+    writing: {
+      invoke: {
+        src: "writer",
+        input: {
+          prompt: "Write a note that says the release is out, post it, and check the reply.",
+        },
+      },
+      initial: "ready",
+      states: {
+        ready: { on: { post_note: "posting", finish: "#done" } },
+        posting: {
+          // The `text` of the pick goes to the input of `note` as it is. The route goes back
+          // to `ready`, in `writing`: the writer reads the output and picks again.
+          invoke: { src: "note", input: fromPick(postNote), onDone: "ready" },
+        },
+      },
+    },
+    done: { id: "done", type: "final" },
+    failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+  },
+});
+```
+
+**Example**
+
+```ts
+import { z } from "zod";
+import { agent, defineEvent, fail, fromPick, http, jr2Setup } from "@jr2/orchestrator";
+
+const postNote = defineEvent({
+  name: "post_note",
+  description: "Post the note to the team channel. This ends your work.",
+  input: z.object({ text: z.string() }),
+});
+
+export const machine = jr2Setup({
+  types: {} as { context: {}; input: {} },
+  events: [postNote],
+  actors: {
+    writer: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You write one short note for the team.",
+      workspace: "none",
+    }),
+    note: http({
+      method: "POST",
+      url: "https://hooks.example.com/notes",
+      input: z.object({ text: z.string() }),
+      request: ({ text }) => ({ json: { text } }),
+    }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "note",
+  on: { "agent.fault": ".failed" },
+  initial: "writing",
+  states: {
+    // The pick leaves this state, so it ends the Turn of the writer.
+    writing: {
+      invoke: {
+        src: "writer",
+        input: { prompt: "Write a note that says the release is out, and post it." },
+      },
+      on: { post_note: "posting" },
+    },
+    // A sibling of `writing`: the Effect runs after the Turn, and no Agent reads its output.
+    posting: {
+      invoke: { src: "note", input: fromPick(postNote), onDone: "done" },
+    },
+    done: { type: "final" },
+    failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+  },
+});
+```
+
+**See also**
+
+- [Effects](../../concepts/effects.md)
+- [Run a command or call a URL with an Effect](../../guides/run-a-command-or-call-a-url.md)
+- [ADR-0067: An Effect is an actor slot, and runs at most once unless marked idempotent](../decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)
+
+## Overload 2
+
+```ts
+function fromPick<
+  N extends string,
+  I extends z.ZodObject,
+  C,
+  E extends EventObject,
+  R extends object,
+>(
+  def: EventDef<N, I>,
+  fill: (args: { context: C; params: z.infer<I> }) => R,
+): (args: { context: C; event: E; self: AnyActorRef }) => z.infer<I> & R
+```
+
+Make the `input` from the params of the pick and the keys that `fill` adds. `fromPick`
+tells the rest, and what `createMachine` refuses.
+
+**Parameters**
+
+- `def` ([`EventDef`](type-eventdef.md)): The pick, as `defineEvent` made it.
+- `fill`: Gets `{ context, params }` and gives back only the keys that the Machine adds. Do
+  not set a key that is also a param.
+
+**Returns**: An `input` mapper for the `invoke` of the state.
+
+**Example**
+
+```ts
+import { z } from "zod";
+import { agent, bearer, defineEvent, fail, fromPick, http, jr2Setup, secret } from "@jr2/orchestrator";
+
+const postComment = defineEvent({
+  name: "post_comment",
+  description: "Post a comment on the ticket.",
+  input: z.object({ body: z.string() }),
+});
+
+export const machine = jr2Setup({
+  types: {} as { context: { ticket: string }; input: { ticket: string } },
+  events: [postComment],
+  actors: {
+    triager: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You triage tickets.",
+      workspace: "none",
+    }),
+    comment: http({
+      method: "POST",
+      url: "https://jira.example.com/rest/api/2/issue",
+      auth: bearer(secret("jira")),
+      input: z.object({ ticket: z.string(), body: z.string() }),
+      request: ({ ticket, body }) => ({ path: [ticket, "comment"], json: { body } }),
+    }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "triage",
+  context: ({ input }) => input,
+  on: { "agent.fault": ".failed" },
+  initial: "triaging",
+  states: {
+    triaging: {
+      invoke: {
+        src: "triager",
+        input: ({ context }) => ({
+          prompt: `Read ticket ${context.ticket}, then post one comment on it.`,
+        }),
+      },
+      initial: "ready",
+      states: {
+        ready: { on: { post_comment: "posting" } },
+        posting: {
+          invoke: {
+            src: "comment",
+            // The Agent gives `body`. The Machine gives `ticket`, so the Agent cannot post on
+            // another ticket.
+            input: fromPick(postComment, ({ context }) => ({ ticket: context.ticket })),
+            onDone: "#done",
+          },
+        },
+      },
+    },
+    done: { id: "done", type: "final" },
+    failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+  },
+});
+```
+
+**See also**
+
+- [Effects](../../concepts/effects.md)
+- [Run a command or call a URL with an Effect](../../guides/run-a-command-or-call-a-url.md)
+- [ADR-0067: An Effect is an actor slot, and runs at most once unless marked idempotent](../decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)

package/docs/reference/authoring-surface/http.md

@@ -0,0 +1,259 @@
+---
+title: http
+description: "Make an `http` Effect: a call to a URL, with Effect secrets that the Agent never reads."
+---
+
+# `http`
+
+Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+
+## Overload 1
+
+```ts
+function http<
+  S extends z.ZodType | undefined = undefined,
+  const U extends HttpDefinition<S>["url"] = string,
+  const A extends HttpDefinition<S>["auth"] = undefined,
+  const H extends HttpDefinition<S>["headers"] = undefined,
+>(
+  def: HttpDefinition<S> & { url: U; auth?: A; headers?: H; body: FileBody<S> },
+): EffectLogic<HttpFileInput<S>, HttpOutput> & OpenOf<HttpOpenParts<U, A, H>>
+```
+
+Make an `http` Effect: a call to a URL, with Effect secrets that the Agent never reads. Put it
+in `actors`, and invoke it by its key: `actors: { comment: http({ ... }) }`, then `invoke: {
+src: "comment" }`.
+
+It runs in the Instance Effector, which `jr2 up` deploys when a Machine has an `http` Effect.
+With `body: file(...)`, it runs in the Sandbox Effector of the Workspace whose body invokes it,
+and under Repo Slots its input names the Worktree in `worktree`. The Effector makes the call. The
+Orchestrator holds no secret.
+
+Every outcome is output (`HttpOutput`): `response`, `unreachable`, `refused` or `unknown`. A 4xx
+or 5xx status is output too. jr2 sends the call at most one time, unless you mark it
+`idempotent`. When its state exits while the call runs, jr2 stops waiting for it. The Effector
+can still send it.
+
+Each field of [`HttpDefinition`](type-httpdefinition.md) tells what it refuses. `createMachine` also refuses an
+Effect written directly in an `invoke`: `machine "<id>": state "<state>" invokes an Effect
+inline — a Part is a key of actors, so it has a name that the ledger, the report and
+customize() share: actors: { <name>: http(...) }, then invoke: { src: "<name>" }`.
+
+**Parameters**
+
+- `def`: The definition. Each field tells what it does.
+
+  - `method`: [`HttpMethod`](type-httpmethod.md)
+
+    The HTTP method: `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` or `OPTIONS`. It refuses
+    another: `http({ method: "<method>" }): the method is one of GET, HEAD, POST, PUT, PATCH,
+    DELETE, OPTIONS`.
+  - `url`: `string | Text | typeof open`
+
+    The url: `http://` or `https://`, then a literal host. No input, param or Effect secret can
+    change where the call goes. An Effect secret can be only in the path:
+    `` text`https://api.telegram.org/bot${secret("tg")}/sendMessage` ``.
+
+    Or `open`: a packaged Machine that cannot know the host leaves the url Open, and the composer
+    binds it one time with `customize(machine, { effects: { <slot>: { url } } })`.
+
+    It refuses:
+    - a scheme or host that is not literal: `` http({ url }): the url is an http:// or https:// url
+      whose scheme and host are literal — a secret may sit only in its path, after a "/":
+      text`https://api.example.com/bot${secret("tg")}/send` (ADR-0068) ``
+    - an Effect secret after `?` or `#`: `` http({ url }): secret("<name>") sits in the url's query
+      or fragment — a secret may sit only in its path; send it in `auth` or a header instead:
+      headers: { "x-api-key": text`${secret("...")}` } (ADR-0068) ``
+    - a host that is not a host: `http({ url }): "<scheme>://<host>" is not a host`
+    - a user name or password in the url: ``http({ url }): the url carries userinfo — use `auth` ``
+  - `headers` (optional): `Readonly<Record<string, string | Text>>`
+
+    Headers that are the same for each run. Each name is lowercase. A value is a string, or a
+    `text` with an Effect secret.
+
+    It refuses:
+    - a name that is not lowercase, or that frames or routes the request (`host`,
+      `content-length`, `transfer-encoding`, `connection`, `upgrade`, `te`, `trailer`,
+      `keep-alive`, `proxy-*`): `http({ headers }): "<name>" is not a header an Effect sets — a
+      lowercase name that does not frame or route the request (ADR-0068)`
+    - an `authorization` header beside `auth`: ``http({ headers }): "authorization" is set by
+      `auth` — write one of them``
+  - `auth` (optional): `{ readonly bearer: Secret; } | { readonly basic: { user: Text; password: Text; }; } | Text`
+
+    The `Authorization` header: `bearer(secret("x"))`, `basic(user, password)`, or a `text` that
+    is the whole value.
+  - `input` (optional): `S`
+
+    The zod schema of the input of the Effect: what the `input` of the `invoke`, or `fromPick`,
+    gives it. jr2 parses the input with it before the call. When it starts, input that does not
+    agree with it makes the Effect fail (its `onError` route): `http "<slot>": its input does not
+    match the definition's input schema — <path>: <message>`, one `<path>: <message>` for each
+    problem, joined by `; `.
+  - `request` (optional): `(input: S extends z.ZodType ? z.infer<S> : void) => HttpRequestParts`
+
+    A function that makes the part of the request that changes for each run, from the input:
+    `path` segments, and a `json` or `text` body. It cannot change the host, a header or an
+    Effect secret. Do not write it beside `body`.
+  - `body`: `FileBody<S>`
+
+    A Worktree file as the body: `file(path, { segments?, contentType? })`. The Effect then
+    runs in the Sandbox Effector of its Workspace. Under a Workspace with Repo Slots, the invoke's
+    input names a Worktree that a cut of this run made, in `worktree`; with none, it refuses when
+    it starts: ``http "<slot>" reads a Worktree file, under a Workspace with Repo Slots, and its
+    input names no `worktree` ``. Do not write `request` beside it: the `segments`
+    of `file` are the path. It refuses another body: ``http({ body }): a body is file(path, {
+    segments?, contentType? }) — json and text come from `request` ``.
+  - `timeout` (optional): [`Duration`](type-duration.md)
+
+    How long jr2 waits for the answer: a number and a unit, such as `"30s"` or `"2m"`. Default
+    `"30s"`. With no answer in that time, the output is `unknown`. It refuses a value that is not
+    a positive duration: `http: timeout "<timeout>" is not a positive duration (like "30s",
+    "2m")`.
+  - `maxBody` (optional): `number`
+
+    The largest number of bytes of a text response body that the output keeps. Default 65536.
+    When jr2 cuts the body, `truncated` is `true`. It refuses a value that is not a positive whole
+    number: `http({ maxBody }): a positive number of bytes`.
+  - `idempotent` (optional): `boolean`
+
+    `true` when it is safe to send the call two times: it has its own idempotency key, or it only
+    reads. Default `false`. After an Orchestrator restart, jr2 cannot always tell if the call went
+    out. Then it sends an idempotent call again, and gives any other call the output `unknown`.
+
+**Returns**: An Effect, for `actors`.
+
+**Example**
+
+```ts
+import { z } from "zod";
+import { bearer, http, jr2Setup, secret } from "@jr2/orchestrator";
+
+const comment = http({
+  method: "POST",
+  url: "https://jira.example.com/rest/api/2/issue",
+  auth: bearer(secret("jira")),
+  input: z.object({ key: z.string(), body: z.string() }),
+  request: ({ key, body }) => ({ path: [key, "comment"], json: { body } }),
+});
+
+export const machine = jr2Setup({
+  types: {} as { context: { key: string }; input: { key: string } },
+  actors: { comment },
+}).createMachine({
+  id: "comment",
+  context: ({ input }) => input,
+  initial: "commenting",
+  states: {
+    commenting: {
+      invoke: {
+        src: "comment",
+        input: ({ context }) => ({ key: context.key, body: "The build passed." }),
+        onDone: "done",
+      },
+    },
+    done: { type: "final" },
+  },
+});
+```
+
+**See also**
+
+- [Effects](../../concepts/effects.md)
+- [Run a command or call a URL with an Effect](../../guides/run-a-command-or-call-a-url.md)
+- [Secrets and trust](../../concepts/secrets-and-trust.md)
+- [ADR-0068: An Effector holds an Effect's secrets and signs its wire](../decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)
+- [ADR-0067: An Effect is an actor slot, and runs at most once unless marked idempotent](../decisions/0067-an-effect-is-an-actor-slot-and-runs-at-most-once-unless-marked-idempotent.md)
+
+## Overload 2
+
+```ts
+function http<
+  S extends z.ZodType | undefined = undefined,
+  const U extends HttpDefinition<S>["url"] = string,
+  const A extends HttpDefinition<S>["auth"] = undefined,
+  const H extends HttpDefinition<S>["headers"] = undefined,
+>(
+  def: HttpDefinition<S> & { url: U; auth?: A; headers?: H },
+): EffectLogic<HttpInput<S>, HttpOutput> & OpenOf<HttpOpenParts<U, A, H>>
+```
+
+**Parameters**
+
+- `def`
+
+  - `method`: [`HttpMethod`](type-httpmethod.md)
+
+    The HTTP method: `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` or `OPTIONS`. It refuses
+    another: `http({ method: "<method>" }): the method is one of GET, HEAD, POST, PUT, PATCH,
+    DELETE, OPTIONS`.
+  - `url`: `string | Text | typeof open`
+
+    The url: `http://` or `https://`, then a literal host. No input, param or Effect secret can
+    change where the call goes. An Effect secret can be only in the path:
+    `` text`https://api.telegram.org/bot${secret("tg")}/sendMessage` ``.
+
+    Or `open`: a packaged Machine that cannot know the host leaves the url Open, and the composer
+    binds it one time with `customize(machine, { effects: { <slot>: { url } } })`.
+
+    It refuses:
+    - a scheme or host that is not literal: `` http({ url }): the url is an http:// or https:// url
+      whose scheme and host are literal — a secret may sit only in its path, after a "/":
+      text`https://api.example.com/bot${secret("tg")}/send` (ADR-0068) ``
+    - an Effect secret after `?` or `#`: `` http({ url }): secret("<name>") sits in the url's query
+      or fragment — a secret may sit only in its path; send it in `auth` or a header instead:
+      headers: { "x-api-key": text`${secret("...")}` } (ADR-0068) ``
+    - a host that is not a host: `http({ url }): "<scheme>://<host>" is not a host`
+    - a user name or password in the url: ``http({ url }): the url carries userinfo — use `auth` ``
+  - `headers` (optional): `Readonly<Record<string, string | Text>>`
+
+    Headers that are the same for each run. Each name is lowercase. A value is a string, or a
+    `text` with an Effect secret.
+
+    It refuses:
+    - a name that is not lowercase, or that frames or routes the request (`host`,
+      `content-length`, `transfer-encoding`, `connection`, `upgrade`, `te`, `trailer`,
+      `keep-alive`, `proxy-*`): `http({ headers }): "<name>" is not a header an Effect sets — a
+      lowercase name that does not frame or route the request (ADR-0068)`
+    - an `authorization` header beside `auth`: ``http({ headers }): "authorization" is set by
+      `auth` — write one of them``
+  - `auth` (optional): `{ readonly bearer: Secret; } | { readonly basic: { user: Text; password: Text; }; } | Text`
+
+    The `Authorization` header: `bearer(secret("x"))`, `basic(user, password)`, or a `text` that
+    is the whole value.
+  - `input` (optional): `S`
+
+    The zod schema of the input of the Effect: what the `input` of the `invoke`, or `fromPick`,
+    gives it. jr2 parses the input with it before the call. When it starts, input that does not
+    agree with it makes the Effect fail (its `onError` route): `http "<slot>": its input does not
+    match the definition's input schema — <path>: <message>`, one `<path>: <message>` for each
+    problem, joined by `; `.
+  - `request` (optional): `(input: S extends z.ZodType ? z.infer<S> : void) => HttpRequestParts`
+
+    A function that makes the part of the request that changes for each run, from the input:
+    `path` segments, and a `json` or `text` body. It cannot change the host, a header or an
+    Effect secret. Do not write it beside `body`.
+  - `body` (optional): `FileBody<S>`
+
+    A Worktree file as the body: `file(path, { segments?, contentType? })`. The Effect then
+    runs in the Sandbox Effector of its Workspace. Under a Workspace with Repo Slots, the invoke's
+    input names a Worktree that a cut of this run made, in `worktree`; with none, it refuses when
+    it starts: ``http "<slot>" reads a Worktree file, under a Workspace with Repo Slots, and its
+    input names no `worktree` ``. Do not write `request` beside it: the `segments`
+    of `file` are the path. It refuses another body: ``http({ body }): a body is file(path, {
+    segments?, contentType? }) — json and text come from `request` ``.
+  - `timeout` (optional): [`Duration`](type-duration.md)
+
+    How long jr2 waits for the answer: a number and a unit, such as `"30s"` or `"2m"`. Default
+    `"30s"`. With no answer in that time, the output is `unknown`. It refuses a value that is not
+    a positive duration: `http: timeout "<timeout>" is not a positive duration (like "30s",
+    "2m")`.
+  - `maxBody` (optional): `number`
+
+    The largest number of bytes of a text response body that the output keeps. Default 65536.
+    When jr2 cuts the body, `truncated` is `true`. It refuses a value that is not a positive whole
+    number: `http({ maxBody }): a positive number of bytes`.
+  - `idempotent` (optional): `boolean`
+
+    `true` when it is safe to send the call two times: it has its own idempotency key, or it only
+    reads. Default `false`. After an Orchestrator restart, jr2 cannot always tell if the call went
+    out. Then it sends an idempotent call again, and gives any other call the output `unknown`.