@jr2/orchestrator 0.6.0 → 0.7.0

package/docs/why.md

@@ -47,7 +47,8 @@ cannot be the right one for each of them.
 
 The You band of the diagram holds the clients of jr2. The [Orchestrator](reference/glossary.md#orchestrator) is an HTTP
 API. The [jr2 CLI](reference/glossary.md#jr2-cli) and the [Console](reference/glossary.md#console) are its clients, and
-your own app, such as a webhook, can be one too. For example, a client can start a run with
+your own app, such as a CI job or a bridge to a chat service, can be one too. An outside service, such as a forge, sends
+its deliveries to a [Hook](reference/glossary.md#hook). For example, a client can start a run with
 [`POST /workflows/:name/runs`](reference/http-api.md#post-workflows-name-runs). In the diagram, a
 [Gate](reference/glossary.md#gate) in the state `approval` asks you, and you answer from any of these clients, with
 [`POST /runs/:runId/gates/:gate/events`](reference/http-api.md#post-runs-runid-gates-gate-events).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jr2/orchestrator",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "The jr2 Orchestrator: xstate runtime, HTTP API and Console, and the kit pieces a Workflow imports.",
   "license": "MIT",
   "private": false,
@@ -31,6 +31,12 @@
   "exports": {
     ".": "./src/index.ts",
     "./internal": "./src/internal.ts",
+    "./hooks": "./src/hook-kinds/index.ts",
+    "./hooks/github": "./src/hook-kinds/github.ts",
+    "./hooks/gitlab": "./src/hook-kinds/gitlab.ts",
+    "./hooks/slack": "./src/hook-kinds/slack.ts",
+    "./hooks/discord": "./src/hook-kinds/discord.ts",
+    "./hooks/webhook": "./src/hook-kinds/webhook.ts",
     "./tsconfig.instance.json": "./tsconfig.instance.json"
   },
   "types": "./src/index.ts",
@@ -38,15 +44,16 @@
     "@hono/node-server": "^2.0.6",
     "elkjs": "^0.11.1",
     "hono": "^4.12.27",
+    "jose": "^6.2.3",
     "preact": "^10.29.8",
     "ts-blank-space": "^0.9.0",
     "xstate": "^5.18.0",
     "zod": "^4.4.3",
-    "@jr2/agent-protocol": "0.6.0"
+    "@jr2/agent-protocol": "0.7.0"
   },
   "devDependencies": {
     "@types/node": "^26.0.1",
-    "@jr2/harness": "0.6.0"
+    "@jr2/harness": "0.7.0"
   },
   "files": [
     "bin",

package/src/actor.ts

@@ -56,9 +56,15 @@ import type { HarnessRestarts, MemoryKill } from "./workspace.ts";
 import { INSTANCE_HARNESS_SERVICE } from "./names.ts";
 import { SENDER_KEY } from "@jr2/agent-protocol";
 import { agentAddress, agentSlot, continuedIid, allowedPicks, resolveAccepts, runBindingOf } from "./registration.ts";
-import type { NoticeScope } from "./notices.ts";
+import type { LedgerBody, NoticeScope } from "./notices.ts";
 import { restOf } from "./rest.ts";
-import { SUBMISSION_HARNESS_RESTARTED, SUBMISSION_RUNAWAY, type Notice, type PodMemoryKill } from "./wire.ts";
+import {
+  SUBMISSION_HARNESS_RESTARTED,
+  SUBMISSION_RUNAWAY,
+  type Notice,
+  type PodMemoryKill,
+  type SteeringMessage,
+} from "./wire.ts";
 import type { AbortCause } from "./wire.ts";
 
 /**
@@ -123,6 +129,14 @@ export type AgentAdmission = {
    */
   agent?: string;
   endpoint?: string;
+  /**
+   * The pod and the slot of the conversation (ADR-0076) — stamped by the ACTOR at ledger time, like
+   * `agent`. The kept conversation's route takes entries for this conversation only from this pod's
+   * control token, for this slot (ADR-0023). It reads the ledger and not the live registration,
+   * because the ledger outlives the Turn and the run.
+   */
+  sandbox?: string;
+  slot?: string;
 };
 
 /**
@@ -367,6 +381,8 @@ export type AgentAdmitOptions = {
   /** The pending notices in this admission's scope (ADR-0062), for the Briefing's Turn part. Not
    * on the persisted input either: they are the Orchestrator's, and delivered once. */
   notices?: Notice[];
+  /** The Steering messages held for this Agent slot (ADR-0002), delivered by the rules of a notice. */
+  steering?: SteeringMessage[];
   /** The admission is for a conversation that `holds` said the Harness keeps (ADR-0062): the
    * re-admission after a cut, and a continued Turn. That "kept" can be a timeout's, so a Harness
    * that keeps none refuses it and seats none; `admit` then rejects with an error whose `notKept`
@@ -739,7 +755,10 @@ export function agentActorWith(
     // Per iid, the notices a step boundary's surface read reserved and the Harness has not yet
     // acknowledged (ADR-0062): by the id the read named, every id it stands for — equal notices
     // are said once — and what each was raised as, for `reraiseUnheard`.
-    const boundary = new Map<string, Map<string, Array<{ id: string; raised: { notice: Notice; source?: string } }>>>();
+    const boundary = new Map<
+      string,
+      Map<string, Array<{ id: string; raised: { notice: LedgerBody; source?: string } }>>
+    >();
     const registerSurface = (iid: string) =>
       disposers.push(
         binding.table.register({
@@ -842,6 +861,8 @@ export function agentActorWith(
           instanceId: currentIid,
           agent: input.agentName,
           endpoint,
+          ...(sandbox === undefined ? {} : { sandbox }),
+          slot,
           ...(input.turnId === undefined ? {} : { turnId: input.turnId }),
         },
         delivered,
@@ -994,7 +1015,7 @@ export function agentActorWith(
     // reserved for this Turn until the Harness acknowledges the append. A guard kill's audience
     // leaves out the conversations its `bash` answer told, which only the pod's list says — so when
     // one is among them, the list is read first, and a read that could not tell takes no guard kill.
-    const readBoundary = async (iid: string): Promise<Array<{ id: string; notice: Notice }>> => {
+    const readBoundary = async (iid: string): Promise<Array<{ id: string; notice: LedgerBody }>> => {
       if (stopped || iid !== currentIid || binding.takeNotices === undefined) return [];
       const scope: NoticeScope = { ...noticeScope, taker: iid };
       if (noticeWorkspace !== undefined) {
@@ -1016,7 +1037,7 @@ export function agentActorWith(
       const taken = binding.takeNotices(scope);
       const held = boundary.get(iid) ?? new Map();
       const said = new Map<string, string>();
-      const out: Array<{ id: string; notice: Notice }> = [];
+      const out: Array<{ id: string; notice: LedgerBody }> = [];
       taken.ids.forEach((id, i) => {
         const raised = taken.raised?.[i] ?? { notice: taken.notices[i]! };
         const key = JSON.stringify(raised.notice);
@@ -1078,7 +1099,7 @@ export function agentActorWith(
     // the Harness last read its surface, `heard` before that — and whether an unheard one carried
     // the Turn's task. Collected across the Turn, so a re-admission onto a lost conversation tells
     // the Agent all of them again.
-    type Raised = { notice: Notice; source?: string };
+    type Raised = { notice: LedgerBody; source?: string };
     // `fresh`: a fresh Turn's "this conversation is new", which rides an admission as `extra` and so
     // is kept in no ledger — an unread one is carried again by the next re-admission.
     const carriedBy = new Map<string, { heard: Raised[]; unheard: Raised[]; task: boolean; fresh: Notice[] }>();
@@ -1125,7 +1146,7 @@ export function agentActorWith(
             : unsaid.length > 0
               ? { workspace: noticeWorkspace, taker, only: unsaid }
               : undefined;
-      const none = { ids: [] as string[], notices: [] as Notice[], raised: [] as Raised[] };
+      const none = { ids: [] as string[], notices: [] as LedgerBody[], raised: [] as Raised[] };
       const restored =
         opts.include && opts.include.length > 0
           ? (binding.takeNotices?.({ ...noticeScope, taker, only: opts.include }) ?? none)
@@ -1143,12 +1164,16 @@ export function agentActorWith(
       // cut pick never got (ADR-0031), whose one path to the model is this admission. One "this
       // conversation is new" is enough, whichever path brought it.
       let fresh = false;
-      const notices = [...taken.notices, ...(opts.extra ?? [])].filter((n) => {
+      const bodies = [...taken.notices, ...(opts.extra ?? [])].filter((n) => {
         if (n.kind !== "conversation-new") return true;
         if (fresh) return false;
         fresh = true;
         return true;
       });
+      // The two kinds of body ride the admission apart (ADR-0062): a notice is a fact, and a
+      // Steering message an author's text, which the Harness frames by its author.
+      const notices = bodies.filter((n): n is Notice => n.kind !== "steering");
+      const steering = bodies.filter((n): n is SteeringMessage => n.kind === "steering");
       // `served` is per Instance ID, and a nudge or a wake reuses the Turn's: it must be read again
       // before this admission counts as heard (`reraiseUnheard`). An admission that fails puts the
       // mark back — what an earlier one carried was heard.
@@ -1161,6 +1186,7 @@ export function agentActorWith(
           slot,
           signal: controller.signal,
           ...(notices.length ? { notices } : {}),
+          ...(steering.length ? { steering } : {}),
           ...(opts.kept ? { kept: true } : {}),
         });
       } catch (err) {
@@ -1213,12 +1239,12 @@ export function agentActorWith(
         if (gone) bucket.heard = [];
         if (!read) bucket.unheard = [];
         for (const { notice, source } of again) {
-          const to = notice.scope === "conversation" ? conversation : noticeWorkspace;
+          const to = notice.scope === "conversation" ? conversation : notice.scope === "slot" ? slot : noticeWorkspace;
           if (to === undefined) continue;
           // A Workspace notice is pending again for the conversation that carried it, which did not
           // hear it; the others it reached keep theirs.
           if (binding.restoreNotice) binding.restoreNotice(notice, to, source, iid);
-          else binding.raiseNotice?.(notice, to);
+          else if (notice.kind !== "steering") binding.raiseNotice?.(notice, to);
           if (source !== undefined) restored.push(source);
         }
       }

package/src/agent.ts

@@ -58,6 +58,44 @@ export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhi
  * tells what each value gives. */
 export type WorkspaceAccess = "write" | "read" | "none";
 
+// One entry of an Agent's `mcp` list (ADR-0079): a server of the config's `mcp` block, by its name,
+// and the allowlist. An object, so that `resources` can join `tools` later. The TYPE cannot say
+// which servers take a list: that is the config's (remote or stdio), so `jr2 up` says it.
+/**
+ * One MCP server that an Agent uses, and the tools that it may call there.
+ *
+ * - `server` is a name of the `mcp` block of `jr2.config.ts`. `jr2 up` refuses a name that the
+ *   block does not declare, and prints the `customize()` line that binds the Agent to one it does.
+ * - `tools` is the allowlist. A remote server needs it: a list of tool names, or `"*"` for every
+ *   tool. The Harness offers and runs only those tools. When Workspace code in the Agent's Sandbox
+ *   can spend the server's secret, `jr2 up` takes only `"*"`, because a list would then not be a
+ *   limit. A stdio server takes no `tools`: the Agent gets every tool of the server.
+ *
+ * The model reads each tool as `mcp__<server>__<tool>`. A tool name in the list must keep that name
+ * within `[A-Za-z0-9_-]` and 128 characters.
+ *
+ * @example
+ * ```ts
+ * import { agent } from "@jr2/orchestrator";
+ *
+ * export const triage = agent({
+ *   model: "anthropic/claude-haiku-5-5",
+ *   instructions: "You read the ticket and post a summary to the channel.",
+ *   workspace: "none",
+ *   mcp: [{ server: "slack-acme", tools: ["post_message", "read_channel"] }],
+ * });
+ * ```
+ *
+ * @see docs/reference/decisions/0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md
+ */
+export type AgentMcpServer = {
+  /** A server name of the `mcp` block of `jr2.config.ts`. */
+  server: string;
+  /** The allowlist: tool names of the server, or `"*"` for every tool. Required for a remote
+   * server; absent for a stdio server. */
+  tools?: readonly string[] | "*";
+};
+
 // The plain-data Agent definition (ADR-0018): IDENTITY plus one default. A Turn's Frame — what it
 // is about and where it works — is not here and cannot be (ADR-0057): a Worktree exists only
 // once a run has cut it, so no definition written before the run could name one.
@@ -130,6 +168,18 @@ export type AgentDefinition = {
    * - `"none"`: no Working tools. The Agent only reads its prompt and picks from its Menu. Its Turn
    *   runs on the Instance Harness, not in a Sandbox, so it needs no `workspace()` around it. */
   workspace?: WorkspaceAccess;
+  // Reach for tools (ADR-0079): names only. The url and the secret are the Instance's, in the
+  // config's `mcp` block, so a packaged Machine ships no credential and a composer rebinds the list.
+  /** The MCP servers whose tools the Agent gets, each with its allowlist: see
+   * {@link AgentMcpServer}. The tools join the Agent's tools, after its Working tools and before
+   * its Menu. A call to one is not a pick, and the Turn goes on after it. Default: none. A composer
+   * replaces the whole list with `customize(machine, { agents: { <slot>: { mcp: [...] } } })`. */
+  mcp?: readonly AgentMcpServer[];
+  // Read by the Orchestrator alone (ADR-0002): the admission strips it, and the model never reads it.
+  /** May a Caller send this Agent a Steering message? Default: `true`. With `false`,
+   * `POST /runs/:runId/steering` and `jr2 steer` refuse it, and `GET /runs/:runId/agents` says
+   * `steerable: false`. The Machine can still steer the Agent with the `steer` action. */
+  steerable?: boolean;
 };
 
 // The Agent as an author DECLARES it (ADR-0054): the definition, except that `model` may be Open —