@jr2/orchestrator 0.6.0 → 0.7.0

package/src/index.ts

@@ -17,20 +17,25 @@ export { jr2Setup } from "./setup.ts";
 export { sentBy } from "./party.ts";
 export type { HostInjectedInput } from "./vocabulary.ts";
 
+// Gates: a Gate slot hears a Hook (ADR-0011).
+export { gate } from "./gate.ts";
+export type { Delivered, GateLook, GateOutcome, GateReply } from "./gate.ts";
+
 // Failure: the Part a Machine invokes to fail its run, and the guard that tells a Failure from a
 // defect in an `onError` (ADR-0073).
 export { fail, isFailure } from "./fail.ts";
 
 // Agents: an Agent slot and the definition it carries (ADR-0028, ADR-0049).
 export { agent } from "./harness-client.ts";
-export type { AgentDefinition, ThinkingLevel } from "./agent.ts";
+export type { AgentDefinition, AgentMcpServer, ThinkingLevel } from "./agent.ts";
 
 // Workspaces and Repos: a Sandbox and the Repo Slots it binds (ADR-0012, ADR-0051).
 export { workspace } from "./workspace.ts";
 export type { Workspaced } from "./workspace.ts";
 export type { Binding, RepoSlot } from "./parts.ts";
 
-// Effects: work a Machine does outside itself, as an actor slot (ADR-0067, ADR-0068, ADR-0071),
+// Effects: work a Machine does outside itself, as an actor slot (ADR-0067, ADR-0068, ADR-0071,
+// ADR-0079),
 // and what an author writes between a pick and that work.
 export { arg } from "./effect.ts";
 export type { CommandOutput, LaterOutcome } from "./effect.ts";
@@ -54,8 +59,14 @@ export type {
 } from "./worktree.ts";
 export { dispatch } from "./dispatch-effect.ts";
 export type { DispatchOutput } from "./effect.ts";
+export { mcp } from "./mcp-effect.ts";
+export type { McpOptions } from "./mcp-effect.ts";
+export type { McpCallOutput, McpOutput, McpReadOutput } from "./effector-wire.ts";
 export { answer, fromPick, paramsOf } from "./pick.ts";
 
+// Steering: the Machine's free text to one of its Agents, which the Agent hears once (ADR-0002).
+export { steer } from "./steer.ts";
+
 // Composition: a part left Open, a Machine's parts retuned, a Pool over a Source (ADR-0017,
 // ADR-0049, ADR-0054, ADR-0060).
 export { open } from "./parts.ts";
@@ -63,8 +74,8 @@ export { customize } from "./customize.ts";
 export type { Customize } from "./customize.ts";
 export type { EffectBinding } from "./open-effect.ts";
 export type { Size, UserContainer } from "./size.ts";
-export { pool, source } from "./pool.ts";
-export type { PoolNextInput } from "./pool.ts";
+export { carry, pool, reread, skip, source } from "./pool.ts";
+export type { PoolNextInput, SourceReply, SourceVerdict } from "./pool.ts";
 
 // Charts: the Open body a Chart wrapper places in `actors`, and the grammar a planner's pick
 // declares, whole or narrowed to one wrapper (ADR-0070).
@@ -74,4 +85,4 @@ export { chartSchema, chartSchemaFor } from "./chart.ts";
 
 // Config: `jr2.config.ts`, the deployment facts a Machine cannot carry (ADR-0050).
 export { defineConfig } from "./config.ts";
-export type { JR2Config } from "./config.ts";
+export type { JR2Config, McpRemoteServer, McpServer, McpStdioServer, RunsConfig } from "./config.ts";

package/src/instance.ts

@@ -14,7 +14,7 @@
 //   3. `restore()` in-flight runs from the store (reconcile against the live world — ADR-0007),
 //      each inside the Assembly its snapshot names (ADR-0069). With no current Assembly the live
 //      rows wait, untouched, and the first publish restores them. Then sweep finished runs older
-//      than a week and collect every Assembly no live row holds, and again every hour (ADR-0065,
+//      than `runs.retain` and collect every Assembly no live row holds, and again every hour (ADR-0065,
 //      ADR-0069);
 //   4. serve the hono HTTP surface (`createApp`) so the CLI / humans can push + control + observe.
 //
@@ -26,7 +26,16 @@
 
 import { mkdir, readdir, stat } from "node:fs/promises";
 import type { JR2Config } from "./config.ts";
-import { loadConfig } from "./config.ts";
+import { loadConfig, retainMs, STATE_VOLUME_DEFAULT } from "./config.ts";
+import { statSync } from "node:fs";
+import {
+  bytesUnder,
+  ConversationStore,
+  deleteOrphanConversations,
+  fileSystemBytes,
+  guardSpace,
+  quantityBytes,
+} from "./conversations.ts";
 import {
   assemblyDoor,
   heldAssemblies,
@@ -62,16 +71,28 @@ import { RunHost } from "./run-host.ts";
 import type { RunRecord, WorkflowDef } from "./run-host.ts";
 import { SqliteSnapshotStore } from "./snapshot-store.ts";
 import type { SnapshotStore } from "./snapshot-store.ts";
-import { createAuthenticator, effectorKey, harnessToken, loadSigningKey, mintInstanceToken } from "./tokens.ts";
+import {
+  createAuthenticator,
+  effectorKey,
+  harnessToken,
+  loadSigningKey,
+  mintInstanceToken,
+  namedTokens,
+} from "./tokens.ts";
 import type { SandboxPort } from "./workspace.ts";
+import { jwtAuthenticator } from "./callers.ts";
 import type { EffectorPlacement, EffectorTarget } from "./http-effect.ts";
-import { WORKFLOW_NAME } from "./effector-wire.ts";
+import { WORKFLOW_NAME, createMacClient, nodeEffectorTransport, type HookMac } from "./effector-wire.ts";
+import { createHookPost, hookDoor, type HookPost } from "./hooks.ts";
 
 export type InstanceOptions = {
   /** The instance folder: the state volume `.jr2/` (its `state.db` unless `store` is supplied, and
    * its published Assemblies). Nothing else in it is read: the Workflows are the current
    * Assembly's (ADR-0069). */
   dir: string;
+  /** The size of the state volume claim, as `jr2 up` applied it (`JR2_STATE_VOLUME`, ADR-0065): the
+   * space guard measures against it. Absent (host-booted), the config's `runs.volume` or `5Gi`. */
+  stateVolume?: string;
   /** Which Assembly to load (ADR-0069). Default: `resolveAssembly(dir)`. The entrypoint resolves
    * it first, because it reads the config from the same root before it builds the ports. */
   assembly?: ResolvedAssembly;
@@ -81,8 +102,8 @@ export type InstanceOptions = {
   /** The image map, read when the door checks a publish (ADR-0069). Present only when deployed;
    * absent, the door does not check `file:` image contexts. */
   imageMap?: () => Promise<ImageRefs>;
-  /** The digests of the mounted ConfigMaps, which `GET /assembly` reports (ADR-0069). Present only
-   * when deployed. */
+  /** The digests of the mounted ConfigMaps and of the loaded digests Secrets, which
+   * `GET /assembly` reports (ADR-0069, ADR-0078). Present only when deployed. */
   mounts?: () => Promise<Record<string, string>>;
   /** Called after a publish has landed and the Workflows swapped: the new current Assembly, its
    * config and its Machines, which the entrypoint swaps into the ports (ADR-0069). Synchronous, so
@@ -110,6 +131,9 @@ export type InstanceOptions = {
   hostname?: string;
   /** Override the durable store. Default: sqlite at `<dir>/.jr2/state.db`. */
   store?: SnapshotStore;
+  /** Override the kept conversations (ADR-0023). Default: sqlite at `<dir>/.jr2/conversations.db`,
+   * or in memory when `store` is supplied. The space guard watches only the default file. */
+  conversations?: ConversationStore;
   /** Probe the live world before re-attaching on restore (ADR-0007). Default: always present. */
   reconcile?: (run: RunRecord) => boolean | Promise<boolean>;
   /** The Sandbox backend for `workspace()` workflows (ADR-0012). Composed by the caller — wired
@@ -148,6 +172,23 @@ export type InstanceOptions = {
    * the instance's Secret and the entrypoint passes it here, so a pod restart keeps the credential
    * the CLI reads from that Secret. Default: minted per boot. */
   instanceToken?: string;
+  /** The digests of the named Caller tokens, by name (ADR-0078), read on each request. Deployed, the
+   * entrypoint reads them from the `jr2-caller-digests` mount. The current Assembly's config gives
+   * each name its scopes. Default: none, so only the Instance token is a Caller. */
+  callerDigests?: () => Readonly<Record<string, string>>;
+  /** The digests of the `token` Hooks' secrets, by secret name (ADR-0078), read on each delivery.
+   * Deployed, the entrypoint reads them from the `jr2-hook-digests` mount. Default: none, so a
+   * `token` Hook refuses each delivery. */
+  hookDigests?: () => Readonly<Record<string, string>>;
+  /** The `mac` check of a Hook's delivery (ADR-0068, ADR-0078). Default: over the Instance
+   * Effector's signed wire when `instanceEffector` is set, else none, so a `mac` Hook answers 503.
+   * A test injects its own. */
+  hookMac?: HookMac;
+  /** The follow-up post of a Hook kind's answer, such as the reply to a Slack click (ADR-0011,
+   * ADR-0068). Default: one `http` call over the Instance Effector's signed wire when
+   * `instanceEffector` is set, else none, so a follow-up fails and the hook log says so. A test
+   * injects its own. */
+  hookPost?: HookPost;
 };
 
 /** What one restore did with the runs it found persisted (ADR-0007, ADR-0030). */
@@ -210,13 +251,11 @@ export type RunningInstance = {
   close: () => Promise<void>;
 };
 
-/**
- * How long a finished run's row lives, and how often the sweep looks (ADR-0065). Fixed, not config,
- * like the Sandbox idle timeout: jr2 is not the record of a run's results, and `jr2 status` on an
- * old run is a debugging act. A week is the time a human has to read it.
- */
-const RETAIN_MS = 7 * 24 * 60 * 60 * 1000;
+/** How often the sweep looks (ADR-0065). How long an ended run's row lives is `runs.retain` of the
+ * current config (`retainMs`), read at each sweep, so a publish changes it. */
 const SWEEP_EVERY_MS = 60 * 60 * 1000;
+/** How often the space guard looks at the state volume between two sweeps (ADR-0065). */
+const GUARD_EVERY_MS = 60 * 1000;
 
 /** Boot an instance folder into a running orchestrator (discover → restore → serve). */
 export async function startInstance(opts: InstanceOptions): Promise<RunningInstance> {
@@ -230,6 +269,14 @@ export async function startInstance(opts: InstanceOptions): Promise<RunningInsta
   }
   await store.init();
 
+  // The kept conversations (ADR-0023): a second SQLite file beside `state.db` on the state volume.
+  // A test that supplies its store keeps them in memory, and no guard measures a volume for it.
+  const stateDir = join(opts.dir, ".jr2");
+  const onVolume = !opts.conversations && !opts.store;
+  const conversations =
+    opts.conversations ?? new ConversationStore(onVolume ? join(stateDir, "conversations.db") : ":memory:");
+  conversations.init();
+
   // Resolved BEFORE the host, and the signing key with it: the host derives every Harness bearer
   // from the key (ADR-0058) — admission, stream, abort, echo. The key is loaded from (or minted
   // into) the instance folder, NOT generated per process: live Sandboxes outlive a restart, their
@@ -336,6 +383,9 @@ export async function startInstance(opts: InstanceOptions): Promise<RunningInsta
   // files, as its record lists them. `GET /assembly` answers these; the runtime Charts the host
   // also registers are not part of an Assembly.
   let currentWorkflows: string[] = [];
+  // The config of the current Assembly (ADR-0069), for what the HTTP surface reads per request: the
+  // named Callers' scopes and the `cors` origins (ADR-0078). A publish replaces it.
+  let currentConfig: JR2Config | undefined;
 
   /** Swap the registry to `loaded` and make `next` current, in one synchronous step: nothing in it
    * awaits, so no request sees half of one Assembly and half of another (ADR-0069). The named
@@ -370,6 +420,7 @@ export async function startInstance(opts: InstanceOptions): Promise<RunningInsta
   // by name. No current Assembly → no Workflows, and the process still serves (ADR-0048).
   if (current) {
     const booted = current;
+    currentConfig = await loadConfig(booted.root);
     const loaded = await importAssembly(booted.hash, booted.root);
     swap(loaded, await readChartFiles(booted.root, undefined, contextDirsOf(loaded)), booted);
   } else {
@@ -431,6 +482,7 @@ export async function startInstance(opts: InstanceOptions): Promise<RunningInsta
           // Every named Chart is re-admitted against the new Assembly (ADR-0070): a runtime Chart
           // that fails is marked unrunnable, kept on the volume, and named in the publish's answer.
           unrunnable = swap(workflows, files, next);
+          currentConfig = config;
           // The Machines the walk imported are this hash's, so a run restored inside it later
           // (the next boot is a new process; this is for the same one) needs no second import.
           imported.set(next.hash, Promise.resolve(workflows));
@@ -441,15 +493,20 @@ export async function startInstance(opts: InstanceOptions): Promise<RunningInsta
           // Assembly was published for the old Kit version drifts now, and that is final. The
           // door's collection follows in the same publish, so it removes the Assemblies only those
           // drifted rows named.
-          if (!host.restorePending) return;
-          try {
-            const outcome = await host.restore();
-            opts.onRestore?.({ assembly: next.hash, ...outcome });
-          } catch (err) {
-            // Left pending: the next publish, or the next boot, tries again. The publish itself
-            // landed, so it is not refused for this.
-            console.error(`restore after publish failed: ${err instanceof Error ? err.message : err}`);
+          if (host.restorePending) {
+            try {
+              const outcome = await host.restore();
+              opts.onRestore?.({ assembly: next.hash, ...outcome });
+            } catch (err) {
+              // Left pending: the next publish, or the next boot, tries again. The publish itself
+              // landed, so it is not refused for this.
+              console.error(`restore after publish failed: ${err instanceof Error ? err.message : err}`);
+            }
           }
+          // The standing Workflows (ADR-0017), after the restore: a live run of the Assembly before
+          // is handed over, and a Workflow that this publish adds gets its first run. Not while a
+          // deferred restore is still pending: its rows may hold the live standing runs.
+          if (!host.restorePending) await host.keepStanding("publish");
         },
       };
     },
@@ -475,10 +532,13 @@ export async function startInstance(opts: InstanceOptions): Promise<RunningInsta
   const restored: RestoreOutcome = current
     ? await host.restore()
     : { reattached: [], lost: [], drifted: [], failed: [] };
+  // The standing Workflows (ADR-0017), after the restore, so a restored standing run is kept and not
+  // started a second time. With no current Assembly there is none: the first publish starts them.
+  if (current) await host.keepStanding("boot");
   const waiting = current ? [] : (await store.live()).map((row) => row.runId);
 
   // Right after restore, not before: restore reads live rows only, and a row it marks `lost` or
-  // `drifted` here is written now, so its week starts now (ADR-0065). After the rows, the
+  // `drifted` here is written now, so its `runs.retain` starts now (ADR-0065). After the rows, the
   // Assemblies: restore decided which rows stay live, and so which Assemblies stay held (ADR-0069).
   // A sweep deletes finished rows only, so it never takes a waiting run; and with the restore
   // deferred, every live row is a root, and so is the pointer's target, so the boot collection
@@ -486,11 +546,72 @@ export async function startInstance(opts: InstanceOptions): Promise<RunningInsta
   // A sweep is housekeeping, never a reason to stay up — nor to fail a boot that has already
   // resumed runs: a failed sweep or collection, at boot or on the hour, is logged, and the next
   // hour tries again. The timer holds no process alive.
+  // With no current Assembly, no `runs.retain` is bound, so the rows are not swept: in the Kit bump
+  // window every boot has no current Assembly, and a sweep at the default would delete the history
+  // that a longer `runs.retain` keeps. The first sweep after the publish uses the published value.
+  // The collection still runs. The cutoff is never before the epoch, so a very long `runs.retain`
+  // keeps every row and does not fail the sweep.
+  // The space guard (ADR-0065). It measures the files on the volume against the smaller of the
+  // claim and what `statfs` says, because a hostPath class such as kind's reports the node's disk.
+  // The claim is `runs.volume`, or the default when the config sets none. The files other than the
+  // two databases (the Assemblies, the Charts) are measured at each sweep, and the databases at each
+  // look, so the guard can look every minute and walk the volume only every hour.
+  const dbFiles = ["state.db", "state.db-wal", "conversations.db", "conversations.db-wal"].map((f) =>
+    join(stateDir, f),
+  );
+  const dbBytes = (): number =>
+    dbFiles.reduce((sum, path) => {
+      try {
+        return sum + statSync(path).size;
+      } catch {
+        return sum;
+      }
+    }, 0);
+  let otherBytes = 0;
+  const measureOthers = () => {
+    otherBytes = Math.max(0, bytesUnder(stateDir) - dbBytes());
+  };
+  let guarding = false;
+  const guard = async (): Promise<void> => {
+    if (guarding) return;
+    guarding = true;
+    try {
+      await guardSpace({
+        conversations,
+        used: () => otherBytes + dbBytes(),
+        capacity: () =>
+          Math.min(
+            fileSystemBytes(stateDir),
+            quantityBytes(opts.stateVolume ?? currentConfig?.runs?.volume ?? STATE_VOLUME_DEFAULT) ??
+              Number.POSITIVE_INFINITY,
+          ),
+        isLive: (runId) => host.runIsLive(runId),
+        onSwept: (runId) =>
+          console.log(
+            `space guard: the state volume is more than 80% full — deleted the kept conversations of run ${runId} (ADR-0065)`,
+          ),
+      });
+    } catch (err) {
+      console.error(`space guard failed: ${err instanceof Error ? err.message : err}`);
+    } finally {
+      guarding = false;
+    }
+  };
+  // A run's kept conversations go with its row (ADR-0065), and then the space guard looks.
   const sweep = async (): Promise<string[]> => {
-    await store
-      .sweep(new Date(Date.now() - RETAIN_MS))
-      .catch((err) => console.error(`sweep failed: ${err instanceof Error ? err.message : err}`));
-    return door.collect();
+    if (current) {
+      await store
+        .sweep(new Date(Math.max(0, Date.now() - retainMs(currentConfig?.runs))))
+        .then((swept) => conversations.deleteRuns(swept))
+        .then(() => deleteOrphanConversations(conversations, store))
+        .catch((err) => console.error(`sweep failed: ${err instanceof Error ? err.message : err}`));
+    }
+    const collected = await door.collect();
+    if (onVolume) {
+      measureOthers();
+      await guard();
+    }
+    return collected;
   };
   const collected = await sweep();
   const onCollect =
@@ -506,18 +627,65 @@ export async function startInstance(opts: InstanceOptions): Promise<RunningInsta
       .catch((err) => console.error(`collection announce failed: ${err instanceof Error ? err.message : err}`));
   }, SWEEP_EVERY_MS);
   sweeper.unref();
+  // The guard looks every minute too: a conversation can grow fast between two sweeps.
+  const guarder = onVolume ? setInterval(() => void guard(), GUARD_EVERY_MS) : undefined;
+  guarder?.unref();
 
   // 4. Serve, authenticated (ADR-0013) — the tokens and key resolved above.
-  const auth = createAuthenticator({ instanceToken, signingKey, publishToken });
+  // The named Callers (ADR-0078): the names and scopes of the current config, joined per request with
+  // the digests `jr2 up` gave, so a publish or a rotation applies with no restart.
+  const auth = createAuthenticator({
+    instanceToken,
+    signingKey,
+    publishToken,
+    namedTokens: () => namedTokens(currentConfig?.callers?.tokens, opts.callerDigests?.() ?? {}),
+    // The JWT issuers of the current config, read per request, so a publish changes them.
+    callers: [jwtAuthenticator(() => currentConfig?.callers?.issuers ?? [])],
+  });
+  // The Hook's door (ADR-0011, ADR-0078): the Hooks of the current config, read per delivery, so a
+  // publish changes them; none while no Assembly is current. A `mac` Hook is checked by the
+  // Instance Effector, which holds its secret (ADR-0068).
+  const hookMac =
+    opts.hookMac ??
+    (opts.instanceEffector
+      ? createMacClient({
+          key: effectorKey(signingKey, "instance"),
+          transport: nodeEffectorTransport(opts.instanceEffector),
+        })
+      : undefined);
+  // The follow-up of an answer that a person reads goes out through the same Effector (ADR-0068).
+  const hookPost =
+    opts.hookPost ??
+    (opts.instanceEffector
+      ? createHookPost({
+          key: effectorKey(signingKey, "instance"),
+          transport: nodeEffectorTransport(opts.instanceEffector),
+        })
+      : undefined);
+  const hooks = hookDoor({
+    host,
+    store,
+    hooks: () => (current ? (currentConfig?.hooks ?? {}) : undefined),
+    digests: () => opts.hookDigests?.() ?? {},
+    ...(hookMac ? { mac: hookMac } : {}),
+    ...(hookPost ? { post: hookPost } : {}),
+  });
   // The Repos are read PER REQUEST, never snapshotted here: a cache the agent cloned minutes
   // after boot must show as present the next time anyone asks (ADR-0048/0051).
   const app = createApp(host, auth, {
     charts,
+    conversations,
     dataPlane: opts.dataPlane,
     repos: opts.repos,
     fetchRepo: opts.fetchRepo,
     assembly: door,
     ...(opts.mounts ? { mounts: opts.mounts } : {}),
+    cors: () => currentConfig?.cors ?? [],
+    hooks,
+    consoleLogin: () =>
+      (currentConfig?.callers?.issuers ?? [])
+        .filter((i) => i.login === true)
+        .map((i) => ({ issuer: i.issuer, clientId: i.audience })),
   });
   const server = serve({ fetch: app.fetch, port: opts.port ?? 0, hostname });
   const port = await new Promise<number>((resolve) => {
@@ -562,9 +730,11 @@ export async function startInstance(opts: InstanceOptions): Promise<RunningInsta
       // From that call on, `/agents/*` answers 503 until the listener closes: the Turns are parked
       // for the next boot's restore, not over, so no Harness may read a 404 here (ADR-0026).
       clearInterval(sweeper);
+      if (guarder) clearInterval(guarder);
       await host.close();
       await new Promise<void>((resolve) => server.close(() => resolve()));
       await store.close();
+      conversations.close();
     },
   };
 }

package/src/internal.ts

@@ -18,10 +18,13 @@ export * from "./effect.ts";
 export * from "./http-effect.ts";
 export * from "./sandbox-effect.ts";
 export * from "./dispatch-effect.ts";
+export * from "./mcp-effect.ts";
 export type { EffectBinding, OpenEffect, OpenEffectPart } from "./open-effect.ts";
 export { openPartsText } from "./open-effect.ts";
 export * from "./effector-wire.ts";
 export * from "./pick.ts";
+export * from "./steer.ts";
+export * from "./notices.ts";
 export * from "./chart.ts";
 export * from "./open-body.ts";
 export * from "./charts.ts";
@@ -36,11 +39,15 @@ export * from "./setup.ts";
 export { sentBy } from "./party.ts";
 export * from "./vocabulary.ts";
 export * from "./tokens.ts";
+// What a run records of its Callers (ADR-0078): the CLI's `jr2 status` walks `startedBy`.
+export type { CallerRecord, GateAnswer, RunStarter } from "./callers.ts";
 export * from "./durability.ts";
 export * from "./snapshot-store.ts";
+// The run listing of `GET /runs` (ADR-0009): the CLI reads its summary and its query words.
+export * from "./run-list.ts";
 export * from "./actor.ts";
-// The `gate` actor: jr2Setup pre-registers it and a state invokes it as `src: "gate"`, so no
-// author writes the value (ADR-0015).
+// The `gate` actor: jr2Setup pre-registers it and a state invokes it as `src: "gate"` (ADR-0015).
+// The Authoring surface has `gate({ … })`, a Gate slot that hears a Hook (ADR-0011).
 export * from "./gate.ts";
 // The Failure's brand stays in fail.ts, and so does the logic that throws it: the kit makes a Failure
 // only through `fail()` and `workspace()`, which imports that logic from fail.ts (ADR-0073).
@@ -74,7 +81,19 @@ export * from "./repos.ts";
 export * from "./repo-fetch.ts";
 // Type-only: what a workflow event delivery looks like (the registration TABLE stays internal
 // even here — ADR-0011).
-export type { ChildErrorMarker, DeliveredEvent, PlacingMarker, RunMarker, TurnMarker } from "./registration.ts";
+export type {
+  ChildErrorMarker,
+  DeliveredEvent,
+  GateMarker,
+  HookRefusedMarker,
+  PlacingMarker,
+  PoolMarker,
+  RunMarker,
+  SourceVerdictLine,
+  TurnMarker,
+} from "./registration.ts";
+export type { HookOutcome } from "./hooks.ts";
+export type { HookLogLine } from "./snapshot-store.ts";
 export * from "./machine-doc.ts";
 export * from "./run-host.ts";
 export * from "./http.ts";

package/src/machine-doc.ts

@@ -61,7 +61,19 @@ export type EffectDoc =
   /** A dispatch (ADR-0071): the Workflow it starts a run of, whether it waits, and the other
    * Orchestrator's origin (`<open>` while a package leaves it Open); no target is this Orchestrator.
    * The token's secret is named on the parts, never here: the target is what a reader routes on. */
-  | { kind: "dispatch"; workflow: string; wait: boolean; target?: string; timeoutMs: number };
+  | { kind: "dispatch"; workflow: string; wait: boolean; target?: string; timeoutMs: number }
+  /** An mcp Effect (ADR-0079): what it asks of which server, by the server's name in the `mcp`
+   * block (`<open>` while a package leaves it Open), and the author's timeout, when it set one. */
+  | {
+      kind: "mcp";
+      op: "call" | "read" | "prompt";
+      server: string;
+      tool?: string;
+      uri?: string;
+      prompt?: string;
+      timeoutMs?: number;
+      idempotent: boolean;
+    };
 
 /** One state of the Machine; `states` nests in document order. */
 export type MachineStateDoc = {
@@ -422,6 +434,19 @@ function effectDoc(parts: EffectParts): EffectDoc {
       timeoutMs,
     };
   }
+  if (parts.kind === "mcp") {
+    const { op, server, tool, uri, prompt, timeoutMs, idempotent } = parts;
+    return {
+      kind: "mcp",
+      op,
+      server: server === open ? "<open>" : server,
+      ...(tool !== undefined ? { tool: tool === open ? "<open>" : tool } : {}),
+      ...(uri !== undefined ? { uri } : {}),
+      ...(prompt !== undefined ? { prompt } : {}),
+      ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+      idempotent,
+    };
+  }
   const { argv, timeoutMs, secrets, pin } = parts;
   return {
     kind: "command",