@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/reference/glossary.md

@@ -70,8 +70,8 @@ _Avoid_: agent (unqualified), coding agent (a `coder` Agent codes too), copilot,
 
 **Console**:
 The browser surface that the Orchestrator serves, where a person sees the Workflows, their runs and their Machines.
-Observation needs no token; the Instance token unlocks control, so that a person can start runs and see and answer the
-open Gates.
+Observation needs no token; a Caller's credential unlocks the control that its scopes allow, so that a person can start
+runs and see and answer the open Gates.
 _Avoid_: visualizer (only one panel of it), dashboard, UI (unqualified), viz
 
 <a id="kit-image"></a>
@@ -147,9 +147,9 @@ _Avoid_: agent actor
 <a id="agent"></a>
 
 **Agent**:
-A configured worker, such as a coder or a reviewer: a model, instructions, Working tools and access to the Workspace.
-It is a data definition that a Machine carries in a named Actor slot, so its name is the slot's name and its scope is
-that Machine; a Turn can set its Dials but never its identity.
+A configured worker, such as a coder or a reviewer: a model, instructions, Working tools, MCP tools and access to the
+Workspace. It is a data definition that a Machine carries in a named Actor slot, so its name is the slot's name and its
+scope is that Machine; a Turn can set its Dials but never its identity.
 _Avoid_: role, persona, roster entry
 
 <a id="dials"></a>
@@ -213,7 +213,43 @@ _Avoid_: humanGate (humans are one caller among many), approval (one possible ev
 **Sender**:
 The party that delivered an event: an Agent or a Gate. Only the Orchestrator writes the Sender, on each event that a
 party delivers, and the Machine's own events have none.
-_Avoid_: origin, caller (the human or system behind a Gate)
+_Avoid_: origin, Caller (the holder of the credential behind a Gate's answer)
+
+<a id="caller"></a>
+
+**Caller**:
+The holder of a credential that acts on an Instance from outside its Machines, such as a person, a CI job or a bridge
+to a chat service: it starts a run, answers a Gate, sends a **Steering message** or cancels a run. A Caller can act
+**on behalf of** another party, but that is the Caller's claim, which jr2 does not check, except where a **Hook**'s
+signature covers it.
+_Avoid_: principal (it brings policies and roles that an Instance does not have), user (a CI job is a Caller), actor
+(xstate's word), Sender (a party inside the run)
+
+<a id="steering-message"></a>
+
+**Steering message**:
+Free text that a Caller, or the Machine, sends to one Agent of a run, named by its slot, which the Agent hears once,
+without an interrupt. A Caller's is an instruction from outside the run; the Machine's can carry what another Agent said, which is
+a peer's word, not an instruction. It is not a fact from jr2, and it is not a pick.
+_Avoid_: steer (as a noun), notice (a fact that jr2 knows and the Agent cannot find), prompt (the Turn's, from the
+Machine), interrupt (`abort` is the terminal act)
+
+<a id="hook"></a>
+
+**Hook**:
+An Instance's door, at a stable address, for one outside service that sends it deliveries, such as a forge or an alert
+service. A Hook checks that a delivery is the service's and decides nothing: it is a Caller that can only answer a Gate
+or bring items to a Source. Its Hook kind, such as `github` or `slack`, is the service's protocol.
+_Avoid_: webhook (the service's request, not the door), endpoint, trigger, listener, subscription, intake; not an engine
+hook or a git hook
+
+<a id="hook-kind"></a>
+
+**Hook kind**:
+One outside service's protocol, as code that an Instance imports: what the service signed, how to read a delivery and
+its payloads, the service's handshake, and the envelope of an answer that a person reads. It never holds a secret, and
+one kind serves every Hook of that service.
+_Avoid_: plugin, adapter (a Source's word), integration, driver
 
 <a id="emit"></a>
 
@@ -225,9 +261,9 @@ _Avoid_: event (what a Gate or an Agent delivers), log (not a diagnostic)
 <a id="effect"></a>
 
 **Effect**:
-Work that a Machine does outside itself: it runs a command, calls a URL, pushes a branch or starts a run. A run that
-an Effect started is **dispatched by** the run that started it, and the two are independent: an in-run child is a
-nested Machine, never a dispatched run.
+Work that a Machine does outside itself: it runs a command, calls a URL, calls an MCP server, pushes a branch
+or starts a run. A run that an Effect started is **dispatched by** the run that started it, and the two are independent:
+an in-run child is a nested Machine, never a dispatched run.
 _Avoid_: action (xstate's word), side effect, job, task, step, operation, errand, tool; sub-run, child run, nested run,
 spawned run (a dispatched run is a run of its own)
 
@@ -235,8 +271,9 @@ spawned run (a dispatched run is a run of its own)
 
 **Open**:
 A part that a Machine declares but does not bind, so that its composer binds it: for example, a Repo Slot with no url,
-an Agent with no model, or an Effect with no url, program or secret. It is the shape that a packaged Machine ships in,
-`jr2 up` refuses an Open part that nobody bound, and a run never sees one, except an Open body, which a run binds.
+an Agent with no model, or an Effect with no url, program, MCP server or tool, or secret. It is the shape that a
+packaged Machine ships in, `jr2 up` refuses an Open part that nobody bound, and a run never sees one, except an Open
+body, which a run binds, and a Gate's Open look, about which `jr2 up` only warns.
 _Avoid_: unset, default (an Open part has none), placeholder
 
 <a id="open-body"></a>
@@ -274,6 +311,13 @@ _Avoid_: template, expression, interpolation, variable, placeholder (the `{{ }}`
 
 ### Turns and conversations
 
+<a id="conversation"></a>
+
+**Conversation**:
+One Agent's exchange with its model, from its first Turn to its end: the prompts, the model's words, its tool calls and
+their results. An Instance ID names it, and one conversation spans one or more Turns.
+_Avoid_: session, transcript, chat, log
+
 <a id="turn"></a>
 
 **Turn**:
@@ -327,8 +371,9 @@ _Avoid_: result, status
 **Sweep**:
 The Turn's sweep: the Orchestrator's end of an Agent's Submissions when the state that asked for the Turn stops
 waiting. It settles the running Submission and every one queued behind it. It says how the Turn ended: by the Turn's
-own pick, or by something else. Two other sweeps are not this one: the image sweep of `jr2 up` (ADR-0039,
-"swept N image(s)"), and the Repo sweep of `jr2 gc` (ADR-0051).
+own pick, or by something else. Other sweeps are not this one: the image sweep of `jr2 up` (ADR-0039,
+"swept N image(s)"), the Repo sweep of `jr2 gc` (ADR-0051), and the run sweep of the Orchestrator, which deletes the
+ended runs older than `runs.retain` and, when the state volume is more than 80% full, the oldest kept conversations (ADR-0065).
 _Avoid_: abort (the wire's route, not the act), cancel (the end of a run)
 
 <a id="runaway"></a>
@@ -342,7 +387,7 @@ _Avoid_: degeneration (the model behavior, not the fault class), loop, hang, sta
 
 **step**:
 One tool call of a model answer that the engine starts while a Turn is live, whether or not it runs: a call of a
-Working tool or a pick, a call of an unknown tool or with invalid arguments, a pick that the Harness blocks as the
+Working tool, of an MCP tool or a pick, a call of an unknown tool or with invalid arguments, a pick that the Harness blocks as the
 second pick of its model answer, each call of a model answer that hit the output limit, and the call that trips the
 Runaway watch. A call after a pick that ended the Turn is not a step. The Harness counts steps to find a Runaway. A
 **step boundary** is the point after a model answer and the results of all its calls, and before the next model
@@ -414,9 +459,20 @@ re-prompt of an open Turn)
 
 **Working tools**:
 The file and shell tools that the Harness runs in its own container: what an Agent may do, as its Menu is what it may
-say. The Agent's access to the Workspace decides which of them it gets, and a Menu-only Agent gets none.
+say. Every program that they run, and their file I/O, is confined, so it cannot reach what the Harness itself holds. The
+Agent's access to the Workspace decides which of them it gets, and a Menu-only Agent gets none.
 _Avoid_: tools (unqualified), sandbox tools
 
+<a id="mcp-tools"></a>
+
+**MCP tools**:
+The tools of the MCP servers that an Agent's definition names: what an Agent may do through a service, beside its
+Working tools and its Menu. The Instance's config declares each server by a name of the author's, and the Agent names
+the servers and, for a remote server, the tools that it may call. They are fixed for a conversation, and a call to one
+is never a pick. A call that needs a person's approval is not made with an MCP tool: the Machine makes it as an Effect,
+after a Gate.
+_Avoid_: connector, plugin, integration, extension, tools (unqualified)
+
 ### Sandboxes, Harnesses and secrets
 
 <a id="sandbox"></a>
@@ -429,9 +485,9 @@ _Avoid_: worker pod, container
 <a id="harness"></a>
 
 **Harness**:
-jr2's own long-running server that hosts the conversations of Agents and executes their Working tools, in every Sandbox
-and once per Instance as the Instance Harness. It holds no Agent of its own: each Submission carries the definition
-that it runs.
+jr2's own long-running server that hosts the conversations of Agents and executes their Working tools and calls their
+MCP tools, in every Sandbox and once per Instance as the Instance Harness. It holds no Agent of its own: each Submission
+carries the definition that it runs.
 _Avoid_: flue agent, server, `local()`
 
 <a id="engine"></a>
@@ -462,36 +518,60 @@ firewall
 <a id="held-secret"></a>
 
 **Held secret**:
-A credential that the Harness uses through its pod's Custodian but never holds: a model API key above all, and the
-Sandbox token. The Harness holds only its Stand-in, so the Agent cannot take the secret out of the pod, but it can spend
-it through the Custodian while the pod lives.
+A credential that the Harness uses through its pod's Custodian but never holds: a model API key above all, the token of
+an MCP server that an Agent names, and the Sandbox tokens. The Harness holds only its Stand-in, so no Agent can take the
+secret out of the pod. Workspace code can spend it through the Custodian, while the pod lives, only when its Workspace
+grants that secret.
 _Avoid_: masked secret, injected secret, proxied key, secret (unqualified)
 
 <a id="stand-in"></a>
 
 **Stand-in**:
-The public value that the Harness holds in place of a Held secret. It means something only to the Custodian, and only
-toward a host that the secret is bound to; sent anywhere else, it arrives as it left.
+The value that the Harness holds in place of a Held secret. It means something only to the Custodian, and only toward a
+host or a route that the secret is bound to; sent anywhere else, it arrives as it left. It is secret, and only the
+Harness itself holds it: Workspace code gets a Stand-in only for a secret that its Workspace grants, and never the one
+for the control token. The one public Stand-in is the fetch token's, which can only ask for a fetch.
 _Avoid_: placeholder (an Open part's word), dummy key, fake key, token, mask
 
+<a id="sandbox-token"></a>
+
+**Sandbox token**:
+A credential that jr2 makes for one Sandbox, which its Custodian alone holds. There are two. The **control token** lets
+the Harness read each Agent's Menu and deliver its picks, for the Agent that the Harness names. The **fetch token** lets
+a process in the pod ask for a fetch of a Repo that the Sandbox holds. Each one is good only for its own work and in its
+own Sandbox, and neither one reaches a Gate.
+_Avoid_: pod token, agent token, slot token, Instance token (the Caller's credential)
+
+<a id="workspace-code"></a>
+
+**Workspace code**:
+Each process in a Sandbox whose program or input comes from the Workspace's shared files: what an Agent's Working tools
+run, tests and builds, git and what a repository's own config makes it run, a stdio MCP server, and a command that a
+Machine runs there. Any Agent can run what another Agent wrote, so jr2 trusts none of it, and no credential that acts
+for an Agent is where Workspace code runs.
+_Avoid_: agent code (any Agent can run another's), user code, untrusted code (unqualified), tool process
+
 <a id="check-pod"></a>
 
 **Check pod**:
-The one-shot pod in which the provider preflight of `jr2 up` checks the models of one class of Harness pod, before the
-converge writes an object that the Instance reads. It has a Custodian, its own copies of the objects that it reads, and
-labels that no Harness pod has. Its check container calls each model as a Turn calls it. The preflight is the step of
-`jr2 up`, and a check is what the check container does for one model: one call, and at most a second one after an
-answer in text. `jr2 check` is not this check: it runs the typecheck and the Machine walk of `jr2 up`, with no pod and no
-cluster.
+The one-shot pod in which the provider preflight of `jr2 up` checks the models of one class of Harness pod, and the tool
+list of each remote MCP server that an Agent of the class names, before the converge writes an object that the Instance
+reads. It has a Custodian, its own copies of the objects that it reads, and labels that no Harness pod has. Its check
+container calls each model as a Turn calls it. The preflight is the step of `jr2 up`, and a check is what the check
+container does for one model: one call, and at most a second one after an answer in text; for an MCP server, it reads
+its tool list once through the Custodian. `jr2 check` is not this check: it runs the typecheck and the Machine walk of
+`jr2 up`, with no pod and no cluster.
 _Avoid_: probe, probe pod, preflight pod, test pod, Harness (it runs none)
 
 <a id="effector"></a>
 
 **Effector**:
-The container where jr2's own process runs a Machine's Effects and holds their secrets, and where the Agent executes
-nothing: a Sandbox Effector or the Instance Effector. Every Effect runs in it except a command that names no secret,
-which runs beside the Agent, and a dispatch that names no target, which runs in the Orchestrator's own process; a
-command that runs in it sees a pinned commit, never the live Worktree.
+The container where jr2's own process holds the secrets that the Orchestrator must not hold and makes the calls to the
+outside that jr2 makes for a Machine or a Hook, and where the Agent executes nothing: a Sandbox Effector or the Instance
+Effector. It serves a Machine's Effects and, in the Instance Effector, the Hook door, and it knows no Hook kind or
+service. Every Effect runs in it except a command that names no secret, which runs beside the Agent, and a dispatch that
+names no target, which runs in the Orchestrator's own process; a command that runs in it sees a pinned commit, never the
+live Worktree.
 _Avoid_: Courier, Actuator, Clerk, machine container, tool image
 
 <a id="sandbox-effector"></a>
@@ -506,7 +586,9 @@ _Avoid_: sidecar, worker, runner
 
 **Instance Effector**:
 The Effector as a stateless pod of its own, one per Instance, for an Effect that calls a URL and reads no Worktree file,
-and for a dispatch that starts a run on another Orchestrator.
+for an Effect that calls an MCP server, for a dispatch that starts a run on another Orchestrator, and for the Hook
+door's two operations: it checks an HMAC with a Hook's secret, which the Orchestrator never holds, and makes the door's
+one call out.
 _Avoid_: sidecar, worker, runner
 
 <a id="effect-secret"></a>
@@ -519,7 +601,7 @@ _Avoid_: secret (unqualified), injected secret
 <a id="sandbox-image"></a>
 
 **Sandbox Image**:
-The user-owned image that a Sandbox's Harness runs in: the tools that the Agent's Working tools can reach, and the shell
+The user-owned image that a Sandbox's Harness runs in: the tools that the Agent's Working tools can reach, the program of each stdio MCP server, and the shell
 that a human gets where the Harness runs. A Workspace names it as a fact of its Machine, built by `jr2 up` or brought
 from a registry, and it carries no part of jr2.
 _Avoid_: workspace image (a Workspace is a Machine; the image is the pod's), agent image, harness image (the kit's own),
@@ -558,15 +640,17 @@ _Avoid_: sidecar (its deployment shape), debug container (a one-off attach, not
 
 **Source**:
 The port from which a Pool gets its work items. A queue, a generator or a re-queried set can be a Source, and a Work
-Source is one Source adapter.
+Source is one Source adapter. A Source can pull (read its set again) and be pushed (hear a Hook, which either tells it to
+read again or carries an item to it); when it can read, the read is the truth.
 _Avoid_: queue (one possible backing, and not FIFO), feed
 
 <a id="pool"></a>
 
 **Pool**:
-The Machine that the kit supplies to run one worker Machine for each Source item, with a limit on how many run at the
-same time.
-_Avoid_: scheduler, work loop
+The Machine that the kit supplies to run one worker for each Source item, with a limit on how many run at the same
+time. A worker is a child Machine inside the Pool's run, or a run of another Workflow that the Pool dispatches. A Pool
+of runs can be **standing**: jr2 keeps it live for the Instance, and it parks when it has no work instead of ending.
+_Avoid_: scheduler, work loop, intake, router
 
 <a id="work-source"></a>
 
@@ -629,20 +713,29 @@ _Avoid_: role, alias, repo name, workdir, primary repo
 <a id="binding"></a>
 
 **Binding**:
-What a Repo Slot resolves to: a Repo's url and an optional base from which the Worktree is cut. With no base, the
-Worktree is cut from the Repo's own default branch.
+What a Repo Slot resolves to: a Repo's url and an optional base. The Sandbox's own clone stays on that base, and a new
+branch starts from it. With no base, both use the Repo's own default branch.
 _Avoid_: config, catalog entry
 
 <a id="project-layout"></a>
 
 **Project layout**:
 The convention for the checkouts in a Sandbox: under each Repo Slot, the Sandbox's own clone of the Repo, with the
-Worktrees beside it. The node's cache of the Repo is not part of the layout.
+Worktrees beside it. An Agent reads the clone and works in a Worktree. The node's cache of the Repo is not part of the
+layout.
 _Avoid_: directory structure, repo tree
 
 <a id="worktree"></a>
 
 **Worktree**:
-A git worktree of a Repo Slot for the one branch that its Workspace works on, beside the Sandbox's own clone. Its work
-is sequential commits on that branch, not separate worktrees; the Machine, not jr2, chooses the branch and its scope.
-_Avoid_: per-task worktree, task branch
+A git worktree of a Repo Slot, in a folder that a Machine names, beside the Sandbox's own clone. It holds one branch, or
+one commit with no branch. The Machine, not jr2, chooses how many Worktrees it cuts, their branches, and which Agents
+work in them.
+_Avoid_: checkout, task branch
+
+<a id="cut"></a>
+
+**Cut**:
+An Effect's act that makes a Worktree, or reads the one that a cut already made at that path. A cut that cannot happen
+changes nothing.
+_Avoid_: attach (the Workspace's step, which only clones), provision