@jr2/orchestrator 0.6.0 → 0.7.0

package/docs/reference/config.md

@@ -15,7 +15,7 @@ Sandbox Image: a Machine names those itself.
 Every field is optional, and an Instance can run with no `jr2.config.ts`. Write the file as
 `export default defineConfig({ … })`. When the config loads, a file with no default export is
 refused: `` <file> has no default export (use `export default defineConfig({…})`) ``. The load also
-checks the shape of `git.credentials`, `secrets`, `harness.catalog` and `priorityClasses`. It
+checks the shape of `git.credentials`, `secrets`, `harness.catalog`, `priorityClasses` and `mcp`. It
 checks that `sandbox` is an object, and checks its `resources`. Each refusal names the field.
 `jr2 up` checks the rest.
 
@@ -42,7 +42,7 @@ export default defineConfig({ name: "my-instance", harness });
 - [Secrets and trust](../concepts/secrets-and-trust.md)
 - [ADR-0050: What code names, config declares; what the CLI names, discovery finds](decisions/0050-what-code-names-config-declares-what-the-cli-names-discovery-finds.md)
 
-Fields: [`name`](#name), [`secrets`](#secrets), [`git`](#git), [`harness`](#harness), [`sandbox`](#sandbox), [`priorityClasses`](#priorityclasses), [`registry`](#registry), [`kitRegistry`](#kitregistry), [`platforms`](#platforms), [`operator`](#operator).
+Fields: [`name`](#name), [`secrets`](#secrets), [`git`](#git), [`harness`](#harness), [`sandbox`](#sandbox), [`priorityClasses`](#priorityclasses), [`callers`](#callers), [`cors`](#cors), [`hooks`](#hooks), [`mcp`](#mcp), [`runs`](#runs), [`registry`](#registry), [`kitRegistry`](#kitregistry), [`platforms`](#platforms), [`operator`](#operator).
 
 <a id="name"></a>
 
@@ -701,6 +701,239 @@ An existing PriorityClass for the Orchestrator, the operator and the Repo cache
 
 An existing PriorityClass for the Sandboxes and the Instance Harness.
 
+<a id="callers"></a>
+
+## `callers`
+
+- Type: `CallersConfig`
+- Required: no
+- Default: none; only the Instance token acts
+
+The Callers that act on the Instance with a credential of their own, and what each may do.
+See `CallersConfig`.
+
+<a id="callers-tokens"></a>
+
+### `callers.tokens`
+
+- Type: `Readonly<Record<string, CallerToken>>`
+- Required: no
+
+The named Caller tokens, by name. A name is lowercase letters, digits and `-`, at most 40
+characters, from a letter to a letter or digit. The config load refuses `instance`, the
+Instance token's name. A name that the config no longer declares stops working at the next
+`jr2 up`.
+
+<a id="callers-tokens-name-may"></a>
+
+### `callers.tokens.<name>.may`
+
+- Type: `Scopes`
+- Required: yes
+
+What the token may do. See `Scopes`.
+
+<a id="callers-tokens-name-may-start"></a>
+
+### `callers.tokens.<name>.may.start`
+
+- Type: `ScopeGrant`
+- Required: no
+
+Start a run.
+
+<a id="callers-tokens-name-may-answer"></a>
+
+### `callers.tokens.<name>.may.answer`
+
+- Type: `AnswerGrant`
+- Required: no
+
+Answer a Gate, and read a run's open Gates without its context. A list item
+`{ workflow, gates }` opens only the Gates that it names, by invoke id (see `GateGrant`).
+
+<a id="callers-tokens-name-may-cancel"></a>
+
+### `callers.tokens.<name>.may.cancel`
+
+- Type: `ScopeGrant`
+- Required: no
+
+Cancel a run.
+
+<a id="callers-tokens-name-may-read"></a>
+
+### `callers.tokens.<name>.may.read`
+
+- Type: `ScopeGrant`
+- Required: no
+
+Read a run's state: its status, its context and its feed.
+
+<a id="callers-tokens-name-may-steer"></a>
+
+### `callers.tokens.<name>.may.steer`
+
+- Type: `ScopeGrant`
+- Required: no
+
+Send a Steering message to an Agent of a run.
+
+<a id="callers-issuers"></a>
+
+### `callers.issuers`
+
+- Type: `readonly JwtIssuer[]`
+- Required: no
+
+The identity providers whose JWTs are Callers. See `JwtIssuer`. Two entries with one
+`issuer` are refused.
+
+<a id="callers-issuers-issuer"></a>
+
+### `callers.issuers[].issuer`
+
+- Type: `string`
+- Required: yes
+
+The issuer's URL, exactly as the `iss` claim gives it, such as `https://dex.example.com`.
+
+<a id="callers-issuers-audience"></a>
+
+### `callers.issuers[].audience`
+
+- Type: `string`
+- Required: yes
+
+The audience that a JWT must name in its `aud` claim: for a login, the client id.
+
+<a id="callers-issuers-jwks"></a>
+
+### `callers.issuers[].jwks`
+
+- Type: `string`
+- Required: no
+- Default: the `jwks_uri` of the issuer's `/.well-known/openid-configuration`
+
+The URL of the issuer's public keys (a JWKS).
+
+<a id="callers-issuers-claims"></a>
+
+### `callers.issuers[].claims`
+
+- Type: `object`
+- Required: no
+- Default: `{ name: "sub", shown: "email", groups: "groups" }`
+
+The claims to read.
+
+<a id="callers-issuers-claims-name"></a>
+
+### `callers.issuers[].claims.name`
+
+- Type: `string`
+- Required: no
+
+The claim that is the Caller's name. Use a claim that the provider never reassigns.
+
+<a id="callers-issuers-claims-shown"></a>
+
+### `callers.issuers[].claims.shown`
+
+- Type: `string`
+- Required: no
+
+The claim that is the name that jr2 shows.
+
+<a id="callers-issuers-claims-groups"></a>
+
+### `callers.issuers[].claims.groups`
+
+- Type: `string`
+- Required: no
+
+The claim that holds the list of groups or roles that `groups` maps to scopes.
+
+<a id="callers-issuers-groups"></a>
+
+### `callers.issuers[].groups`
+
+- Type: `Readonly<Record<string, Scopes>>`
+- Required: yes
+
+The scopes that each value of the groups claim gives, such as
+`{ "jr2-ops": { start: "all", answer: "all" } }`. A JWT with more than one value gets the scopes
+of each, joined. A value that is not here gives nothing.
+
+<a id="callers-issuers-login"></a>
+
+### `callers.issuers[].login`
+
+- Type: `boolean`
+- Required: no
+- Default: `false`, because an issuer for machines (a CI provider's tokens) has no login page
+
+The Console offers a login against this issuer ([ADR-0032](decisions/0032-the-console-unlocks-with-a-callers-credential.md)): OIDC, the authorization code flow
+with PKCE, as a public client, with `audience` as the client id. Register the client as public
+(no secret), with the Console's root (`https://<console>/`) as its redirect URI. The Console
+reads the issuer and the client id before the login, from the open route
+`GET /console/config`: both are public values. A login needs the Console on https or on
+localhost, and the issuer must let the Console's origin call its discovery document and its
+token endpoint (CORS).
+
+<a id="cors"></a>
+
+## `cors`
+
+- Type: `readonly string[]`
+- Required: no
+- Default: none
+
+The origins from which a browser app may call the Instance's HTTP API, such as
+`https://ops.example.com`. Each entry is an origin alone: a scheme, a host and an optional port,
+with no path. The Console is served from the Orchestrator's own origin, so it
+needs no entry. The config load refuses an entry that is not an origin:
+`<file> at cors[<i>]: <entry> is not an origin — scheme://host[:port], with no path`.
+
+<a id="hooks"></a>
+
+## `hooks`
+
+- Type: `Readonly<Record<string, Hook>>`
+- Required: no
+- Default: none
+
+The Hooks of the Instance, by name: each one is a door, `POST /hooks/<name>`, for one outside
+service. A Hook's value comes from its kind's constructor, which the config imports:
+`github({ secret: secret("GH_HOOK") })`, `gitlab({ secret: secret("GL_HOOK"), may })`,
+`discord({ publicKey: "…" })`. `may.answer` names the Workflows whose Gates the Hook may answer,
+every Workflow by default. A Hook never starts a run. A name has the rule of a Caller token's
+name. When the config loads, a bad entry is refused: `<file> at hooks.<name>: <problem>`.
+
+<a id="mcp"></a>
+
+## `mcp`
+
+- Type: `Readonly<Record<string, McpServer>>`
+- Required: no
+- Default: none
+
+The MCP servers, by a name of yours: `[a-z][a-z0-9-]*`, not `jr2`. A remote server has a
+`url` (`https://` with a secret), a `secret` (a name of the `secrets` list; with no `hosts`, it
+is bound to the url's host) and a `timeout` (default `"60s"`). A stdio server has a `command`
+of the Sandbox Image, its `args` and a `timeout`. An Agent names a server in its `mcp` list.
+See [`McpServer`](authoring-surface/type-mcpserver.md).
+
+<a id="runs"></a>
+
+## `runs`
+
+- Type: [`RunsConfig`](authoring-surface/type-runsconfig.md)
+- Required: no
+- Default: `{ retain: "30d", volume: "5Gi" }`
+
+How long ended runs are kept, and the volume size.
+
 <a id="registry"></a>
 
 ## `registry`

package/docs/reference/decisions/0002-duplex-streaming-actor.md

@@ -23,21 +23,81 @@ The split-channel model:
 | down      | the next turn's prompt (feedback, steering at a boundary)      | a new submission on the same iid              |
 | down      | the Turn part, restated (the Allowed picks changed)            | the Harness's read at each step boundary      |
 | down      | a jr2 notice (a memory kill, ADR-0062), typed, to its audience | the same step-boundary read, per conversation |
+| down      | a Steering message (a Caller's or the Machine's free text)     | the same step-boundary read, per Agent slot   |
 | down      | interrupts (deliberate terminal cancel)                        | `abort` on the wire                           |
 
-Tool calls are Agent-initiated, so the Machine speaks inside a Turn only as an answer. The one exception is the
-**restated Turn part**: when something other than the Agent's own pick changes its Allowed picks — a Gate's answer, an
-outside event — the Harness learns it by reading the surface at each step boundary and appends the new list
+Tool calls are Agent-initiated, so the Machine answers a pick only when the Agent makes one. Inside a Turn, three other
+things reach the Agent, and each one at a step boundary. The first is the **restated Turn part**: when something other
+than the Agent's own pick changes its Allowed picks — a Gate's answer, an outside event — the Harness learns it by
+reading the surface at each step boundary and appends the new list
 ([ADR-0029](0029-a-menu-is-fixed-for-a-conversation-and-a-turn-is-told-its-allowed-picks.md)). It is a pull, not a push:
 the Harness asks at a step boundary, and nothing reaches it that it did not ask for. What is restated is fixed text plus
-Menu names. jr2's own **typed notices** ride that same step-boundary read: the read of an open Turn returns its
-conversation's pending notices, the Harness appends them, and its acknowledgment of the append delivers them. So a
-running Agent hears a fact the mechanism knows — a memory kill above all — without an interrupt. A notice is typed data,
-and the Harness words it ([ADR-0062](0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md)). The residual case is
-**free-text human steering** — arbitrary text from a human Caller to an Agent that has not asked. jr2 reserves it for v1
-on this same channel, authenticated as a Caller ([ADR-0011](0011-workflow-defined-events.md)) rather than by a
-Sandbox-scoped credential; its sender and authorization are designed with the Caller. It is one behavior, not a
-dependency of the whole control plane.
+Menu names. The second is jr2's own **typed notices**, which ride that same step-boundary read: the read of an open Turn
+returns its conversation's pending notices, the Harness appends them, and its acknowledgment of the append delivers
+them. So a running Agent hears a fact the mechanism knows — a memory kill above all — without an interrupt. A notice is
+typed data, and the Harness words it ([ADR-0062](0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md)). The third
+is a **Steering message**: free text to an Agent that has not asked for it, on the same read (below). Each is a pull at
+a step boundary, never an interrupt.
+
+## Steering messages
+
+- **Two senders.** A Caller ([ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md))
+  sends one with `POST /runs/:runId/steering { agent, text }` or `jr2 steer <run> <agent> "<text>"`, and needs the
+  `steer` scope for the run's Workflow. A text above 16 KiB of UTF-8 is 413, and an empty one 400. The route answers 202
+  `{ id, agent, open }`: `open` says whether a Turn of the slot was open when the message came. The message names the
+  Caller by the name that jr2 shows (a JWT's `email`, else its name), with its `via` and its `onBehalfOf` claim. The
+  Machine sends one with the authoring action `steer(<agent>, text, { from? })` in a transition, to an Agent of the
+  Machine that runs the action; `from` is the Sender whose words it carries. The action cuts a text above 16 KiB and
+  says so in the text, because a relayed payload is not the author's to bound, and a refusal there would fail the
+  transition.
+- **Addressed by Agent slot.** `agent` names an Agent slot of the run, as the run's slot list names it. The list,
+  `{ agent, open, steerable }` for each slot at `GET /runs/:runId/agents`, is open to a Caller with `steer`, so a Caller
+  can see where a message would go. It lists each Agent that each live Machine instance carries in its `actors`, with or
+  without an open Turn, and `jr2 steer <run>` prints it. An Instance ID is not the address: jr2 computes it, a Caller
+  cannot know it, and a fresh Turn gets a new one. A slot is the name that the author gave, and the walk lets at most
+  one state of a Machine instance hold it at a time ([ADR-0015](0015-authoring-surface-absorbs-the-mechanism.md)), so it
+  names one conversation at a time.
+- **Delivery.** When the slot has an open Turn, its Harness appends the message at the Turn's next step boundary, on the
+  same read as a notice. A pick that ends the Turn skips that read. Thus a message that comes while the Turn's last
+  model request runs is held for the slot's next Turn, as when no Turn is open, and `jr2 steer` says that both can
+  occur. Otherwise the message is held for the slot's next Turn of the same Machine instance, and that Turn's admission
+  carries it. A held message belongs to the Machine instance that was live when it was sent: when that instance ends,
+  the message retires, and the run records it "not delivered". A Machine instance ends when it leaves its parent's
+  children, when it reaches `done` or `error`, and when the run ends; a host that stops parks the run, and ends nothing.
+  An instance below one that ended ends with it. When no live Machine instance holds the slot — it has ended, or it
+  never was — the route answers 409 with the run's slots, because the Orchestrator cannot tell a slot that ended from
+  one that never was; an unknown run is 404, and a run that is not live is 409. The Agent hears each message once, by
+  the rules of a notice (ADR-0062). The run records each message with its author, its text, when it was sent and its
+  outcome (`held`, `heard`, `not-delivered`), in the run's persisted state; the record keeps the newest 100 and each one
+  still held. The run's status carries it as `steering`, behind `read` like `context` (ADR-0014): a message is a
+  Caller's working text, never the open band's.
+- **Never a Machine event.** A Steering message is in no Vocabulary, no Gate takes it, and no guard reads it. The Agent
+  decides what to do with it, and acts on the workflow only by its picks.
+- **Agents message each other only through the Machine.** An Agent's Menu offers a pick that the author declared; the
+  Machine's transition relays its payload with `steer(<agent>, …)`. jr2 gives no built-in message tool.
+- **The Harness frames the message by its author** (ADR-0062). A Caller's message is an instruction from outside the
+  run, with the Caller's name. A message that the Machine relays from another Agent is information from a peer, and the
+  frame says that it is not an instruction. A Machine's message that relays no one is the workflow's own text.
+- **`steerable: false` on an Agent definition refuses Callers only** (403). The Machine can still steer that Agent: the
+  author wrote both. The admission strips it from the definition, because the model never reads it.
+- **What a model reads changes, so two `@model` claims are owed**
+  ([ADR-0066](0066-a-model-tier-runs-a-real-model-and-a-change-to-what-it-reads-runs-the-tier.md)): `steer-follow`, an
+  Agent follows a Caller's Steering message that comes in its open Turn, and `peer-not-order`, an Agent does not obey a
+  peer's relayed word as an order. Their floors were set before a measured run, as `chart-refusal`'s was: `steer-follow`
+  9 of 10, a list read last's floor, because the message is the newest text that the model read; and `peer-not-order` 7
+  of 10, because there the peer's word comes after the workflow's text, and ADR-0029 measured how much the text read
+  last pulls.
+
+Considered and rejected: address a message by conversation (an Instance ID), which a Caller cannot know and which
+changes at a fresh Turn; a built-in tool with which an Agent messages another Agent, which goes around the Machine that
+the author wrote; and a Steering message as a Machine event, which makes free text control.
+
+Considered and not chosen now: a held message turns back a pick that ends the Turn. The Harness would refuse that pick
+while a message waits for the slot, and the model would read the message and pick again, so a message always reaches the
+Turn that was open when it came. It costs a new refusal that the model reads (an `@model` claim), one more model request
+in that case, and a pick that a Caller's message can undo, where today a pick is final. The case is one model request
+wide, and a Gate or the Machine can still send the Agent back. Look at it again if Callers need a message to reach the
+Turn that was open.
 
 ## Durability: the admission is the handle
 

package/docs/reference/decisions/0005-sandbox-pod-composition.md

@@ -6,10 +6,11 @@ A Sandbox pod composes up to four containers around one shared worktree volume (
   [ADR-0037](0037-an-instance-builds-its-sandbox-images-jr2-injects-the-harness.md)) with jr2's runtime mounted at
   `/opt/jr2` and the command overridden to start the Harness. The Agent's toolchain lives here because the Working tools
   (read/write/edit/bash) execute here — the tools the Agent can reach are this image's. It is also where a human
-  `kubectl exec`s to inspect a run with the agent's exact tools, worktrees, and filesystem. One Harness container serves
-  every workspace-ful Agent of the Sandbox. Each process that the Harness starts in `/work` — a Working tool's shell, a
-  test, git, a `command` Effect — runs as a confined child of the Harness process, so no code from `/work` reaches the
-  control credential that the Harness process holds
+  inspects a run with the agent's exact tools, worktrees, and filesystem: `jr2 workspace shell` starts its shell through
+  the spawner, as an Agent's `bash` starts ([ADR-0009](0009-cli-and-instance-interface.md)), so the shell does not reach
+  the control Stand-in. One Harness container serves every workspace-ful Agent of the Sandbox. Each process that the
+  Harness starts in `/work` — a Working tool's shell, a test, git, a `command` Effect — runs as a confined child of the
+  Harness process, so no code from `/work` reaches the control credential that the Harness process holds
   ([ADR-0076](0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md)).
 - **Custodian container** — jr2-composed sidecar, upstream Envoy configured at provision by the Orchestrator
   ([ADR-0013](0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md),
@@ -28,10 +29,11 @@ A Sandbox pod composes up to four containers around one shared worktree volume (
   Size ([ADR-0060](0060-a-workspace-states-its-size-and-jr2-reserves-all-of-it.md)): a budget is the pod's business, not
   the process's, so it puts nothing in the container. Env and ports are not forwarded, because every key jr2 forwarded
   into the process would be a crack in "jr2 puts nothing in it"; a routable port (the follow-up below) is the known
-  candidate for the next key. In the pod it is the container named `user` (`kubectl exec -c user`). It runs its **own
-  entrypoint, untouched**: jr2 injects nothing into its process — no env, no command, no probe — and overrides nothing;
-  it mounts only what the checkouts need to be checkouts (below). The zero-contract seat, which is exactly why it
-  exists. Two jobs no other seat can do:
+  candidate for the next key. In the pod it is the container named `user`: `jr2 workspace shell <ws> --user` is
+  `kubectl exec -c user`, and `jr2 workspace forward <ws> <port> [--stdio]` reaches its sshd or any of its listeners by
+  port-forward ([ADR-0009](0009-cli-and-instance-interface.md)). It runs its **own entrypoint, untouched**: jr2 injects
+  nothing into its process — no env, no command, no probe — and overrides nothing; it mounts only what the checkouts
+  need to be checkouts (below). The zero-contract seat, which is exactly why it exists. Two jobs no other seat can do:
   - **Unattended services.** A container's one command belongs to the Harness in the primary seat (ADR-0037), so an
     image's own services — an sshd for managed access, an IDE server, a metrics agent — need a container whose command
     jr2 deliberately does not own. A system built _on_ jr2 that hands people access to their Sandboxes automates through
@@ -235,6 +237,8 @@ plainly:
 - The Harness container's `/work` writes being group-writable widens nothing: every process that could abuse group
   access already runs in the same trust domain, and the work group exists only inside this pod.
 - **Routable access is a follow-up, deliberately untaken**: the operator's Service serves the Harness at `:8080`, and a
-  managed system wanting cluster-routed ssh to the User Container needs a declared port there. `kubectl port-forward`
-  reaches any listener in the pod without one, which covers the human case day one.
+  managed system wanting cluster-routed ssh to the User Container needs a declared port there. A person reaches the User
+  Container through the kube API: `jr2 workspace shell --user` by exec, and `jr2 workspace forward` by port-forward,
+  which reaches any listener in the pod with no Service. `forward --stdio` is an ssh `ProxyCommand`, so
+  `ssh <sandbox>.jr2` with agent forwarding reaches the User Container's sshd (ADR-0009).
 - **GLOSSARY.md**: **User Container** is a glossary term.

package/docs/reference/decisions/0006-agent-control-surface.md

@@ -44,7 +44,7 @@ is the only structured channel. Consequences:
 
 jr2's own typed notices now reach a running Agent through the step-boundary read (ADR-0002,
 [ADR-0062](0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md)); the Menu still opens only when the Agent
-reaches a checkpoint or a turn boundary. Free-text human steering is the remaining case, reserved for v1 as a
-Caller-authenticated message on the same channel (ADR-0002, [ADR-0011](0011-workflow-defined-events.md)). Evidence for
-the findings above: `poc/actor/POC-5B-FINDINGS.md`, `poc/actor/POC-5C-FINDINGS.md` (`poc/` is gitignored; conclusions
-live here).
+reaches a checkpoint or a turn boundary. Free text from a Caller, or from the Machine, is a Steering message on the same
+channel (ADR-0002, [ADR-0078](0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)): the Agent
+hears it once, and it is never a pick or a workflow event. Evidence for the findings above:
+`poc/actor/POC-5B-FINDINGS.md`, `poc/actor/POC-5C-FINDINGS.md` (`poc/` is gitignored; conclusions live here).

package/docs/reference/decisions/0007-durable-machine-state.md

@@ -15,7 +15,7 @@ it from the start (the top Machine keeps only counts + ids, children report comp
 snapshot/restore possible.
 
 The store's own durability — what a persist survives, and how long a finished run's row lives — is
-[ADR-0065](0065-a-persist-survives-a-crash-and-history-is-a-week.md).
+[ADR-0065](0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md).
 
 Durable **agent handles** do not ride Machine context at all: the host persists an `iid → admission` ledger beside the
 snapshot in the same save (ADR-0016). Iids are globally unique, so restore needs no context-tree walking to find them.