@jr2/orchestrator 0.3.0 → 0.5.1

package/src/held-secrets.ts

@@ -1,4 +1,6 @@
-// Held secrets (ADR-0059): credentials the Harness uses and never holds.
+// Held secrets (ADR-0059): credentials the Harness uses and never holds — the entries of the
+// `secrets` list that a Harness pod claims: a `workspace()` lists it under `secrets`, or a provider
+// an Agent there names reads it (secret-placement.ts places each one, ADR-0068).
 //
 // The Agent executes code in the Harness container (ADR-0005), so a key in that container's env is
 // a key it can take out of the pod. A held secret is not there: the Harness's env carries a
@@ -8,8 +10,9 @@
 // This module is the pure half, shared by every seat that needs it:
 //
 //   standIn(name)        the value the Harness sees — deterministic and public
-//   heldSecretsOf(...)   `jr2 up`'s normalization: every refusal (R1–R13), every warning, and the
-//                        engine-neutral manifest (`held.json`) every composition reads
+//   heldSecretsOf(...)   `jr2 up`'s normalization of the claimed entries: every refusal (R1–R13),
+//                        every warning, and the engine-neutral bindings each pod's manifest
+//                        (`held-<pod>.json`) takes its own from
 //
 // It runs HOST-SIDE, in `jr2 up`, because only there does the config carry values: in-cluster,
 // `process.env` has no `.env`, so a `value` reads `undefined` and a `hosts` entry built from `.env`
@@ -21,11 +24,50 @@ import { readFile } from "node:fs/promises";
 import { isIP } from "node:net";
 import type { JR2Config, HarnessEnvVar } from "./config.ts";
 import { MODEL_KEYS, MODEL_KEY_PROVIDERS, SIGNING_CREDENTIALS } from "./model-keys.ts";
-import { HELD_CA_SECRET, HELD_SECRETS_SECRET, HELD_TLS_SECRET, INSTANCE_SECRET } from "./names.ts";
+import { HELD_CA_SECRET, HELD_SECRETS_SECRET, HELD_TLS_SECRET, INSTANCE_EFFECTOR, INSTANCE_SECRET } from "./names.ts";
+import type { PlacementRoute } from "./parts.ts";
+
+/** The kit's Secrets no Harness container may read (R13): the Instance token and signing key, each
+ * pod's literal held values, the leaves, the CA, and every Effector's (ADR-0068) — the Instance
+ * Effector's Effect secrets and key, each Workspace's Sandbox Effector Secret (`jr2-effector-<pod>`),
+ * each Sandbox's Effector key (`<sandbox>-effector`), and each `git.credentials` entry's clone and
+ * push Secrets (`jr2-git-<hash>`, `jr2-git-push-<hash>`, ADR-0051). */
+const KIT_SECRETS: readonly string[] = [INSTANCE_SECRET, HELD_TLS_SECRET, HELD_CA_SECRET, INSTANCE_EFFECTOR];
+const KIT_SECRET_PREFIXES: readonly string[] = [`${HELD_SECRETS_SECRET}-`, "jr2-effector-", "jr2-git-"];
+const isKitSecret = (name: string): boolean =>
+  KIT_SECRETS.includes(name) ||
+  name === HELD_SECRETS_SECRET ||
+  KIT_SECRET_PREFIXES.some((p) => name.startsWith(p)) ||
+  // A Sandbox's own Effector key: every Sandbox's name starts `ws-` (`workspaceName`).
+  (name.startsWith("ws-") && name.endsWith("-effector"));
 
-/** The kit's Secrets no Harness container may read (R13): the Instance token and signing key, the
- * literal held values, the leaves, and the CA. */
-const KIT_SECRETS: readonly string[] = [INSTANCE_SECRET, HELD_SECRETS_SECRET, HELD_TLS_SECRET, HELD_CA_SECRET];
+/**
+ * The pod key of one Workspace (ADR-0059): its registered workflow and the placement route to its
+ * `workspace()` (`PlacementRoute`) — what `jr2 up` reads off the walk and the run host off the live
+ * actor (`actorRoute`), so both name one pod alike. Every Workspace has a route of its own, an
+ * inline-invoked one included, so two Workspaces never share a key. A digest, so it is a name a
+ * Secret and a ConfigMap key can carry; `ws-` keeps it apart from the Instance Harness's.
+ */
+export function workspaceHeldPod(at: { workflow: string; route: PlacementRoute }): string {
+  const key = JSON.stringify([at.workflow, at.route]);
+  return `ws-${createHash("sha256").update(key).digest("hex").slice(0, 16)}`;
+}
+
+/**
+ * The names a provider claims for a pod (ADR-0059): the `secrets` entries that are a known model key
+ * the provider of one of `models` reads, and the custom provider's key when an Agent there names
+ * that provider. A model key is claimed by the PROVIDER — the Agent names its model, jr2 knows which
+ * key that provider reads — so it is not listed under a `workspace()`'s `secrets`.
+ */
+export function providerClaims(config: JR2Config, models: readonly string[]): string[] {
+  const providers = new Set(models.map((m) => m.split("/")[0] ?? ""));
+  const claims = (config.secrets ?? [])
+    .filter((s) => MODEL_KEYS[s.name]?.providers.some((p) => providers.has(p)))
+    .map((s) => s.name);
+  const custom = config.harness?.provider;
+  if (custom?.apiKey && providers.has(custom.id)) claims.push(PROVIDER_KEY_NAME);
+  return claims;
+}
 
 /**
  * The Stand-in for one held secret: what its env var holds in the Harness container.
@@ -79,7 +121,7 @@ export const MECHANISM_ENV: readonly string[] = [
   "GIT_SSL_CAINFO",
 ];
 
-/** What `jr2 up` resolved; what every composition reads (`held.json` in the `jr2-held`
+/** What `jr2 up` placed in one pod; what its composition reads (`held-<pod>.json` in the `jr2-held`
  * ConfigMap). Values never appear here. */
 export type HeldManifest = { version: 1; secrets: HeldBinding[] };
 
@@ -87,7 +129,7 @@ export type HeldManifest = { version: 1; secrets: HeldBinding[] };
 export type HeldBinding = {
   /** The env var; the Harness sees `standIn(name)`. */
   name: string;
-  /** A literal lands in the `jr2-held-secrets` Secret under `name`; a `secret` is the user's own
+  /** A literal lands in its pod's `jr2-held-secrets-<pod>` Secret under `name`; a `secret` is the user's own
    * Secret, mounted by reference so a rotation reaches new pods without a `jr2 up`. */
   source: { kind: "literal" } | { kind: "secret"; secret: string; key: string };
   /** `leaf` is the file stem of this host's certificate in `jr2-held-tls` (`leafStem`). */
@@ -118,13 +160,18 @@ export type HeldLookups = {
   /** The key names of a Secret a `valueFrom.secretKeyRef` names, or undefined when it does not
    * exist in the namespace (R10). */
   secretKeys?: (name: string) => readonly string[] | undefined;
+  /** The length in characters of one key's value in a Secret a `valueFrom.secretKeyRef` names —
+   * never the value — or undefined when it is not known. An Effect secret shorter than 8 characters
+   * is refused by it as a literal is (ADR-0068). */
+  valueLength?: (name: string, key: string) => number | undefined;
   /** Every model specifier a carried Agent definition names (`anthropic/claude-sonnet-4-6`) — R9's
    * evidence that a provider's turns will reach its host. */
   models?: readonly string[];
 };
 
-/** `heldSecretsOf`'s answer: the manifest, the literal values (host-side only — they go into the
- * `jr2-held-secrets` Secret and nowhere else), and what `jr2 up` should warn about. */
+/** `heldSecretsOf`'s answer: every claimed binding, the literal values (host-side only — each goes
+ * into the `jr2-held-secrets-<pod>` Secret of a pod that claims it and nowhere else), and what
+ * `jr2 up` should warn about. */
 export type HeldResolution = {
   manifest: HeldManifest;
   values: Record<string, string>;
@@ -146,11 +193,17 @@ const FRAMING_HEADERS = new Set([
 ]);
 
 /**
- * Normalize `harness.heldSecrets` (plus the implicit `JR2_PROVIDER_API_KEY`) into the manifest,
- * or throw the FIRST refusal. Every message names the config path and never a value, and says
- * what to write instead — the `checkGit` style.
+ * Normalize the Held secrets — the entries of the `secrets` list some pod claims, and the implicit
+ * `JR2_PROVIDER_API_KEY` when one claims it (`claimed`, from secret-placement.ts) — into bindings, or
+ * throw the FIRST refusal. Every message names the config path and never a value, and says what to
+ * write instead — the `checkGit` style. An entry no pod claims is not this function's: `hosts`,
+ * `headers` and `paths` are the binding, never the placement, so R5 fires only for a claimed one.
  */
-export function heldSecretsOf(config: JR2Config, lookups: HeldLookups = {}): HeldResolution {
+export function heldSecretsOf(
+  config: JR2Config,
+  claimed: ReadonlySet<string>,
+  lookups: HeldLookups = {},
+): HeldResolution {
   const harness = config.harness ?? {};
   const warnings: string[] = [];
   const env = harness.env ?? [];
@@ -185,7 +238,7 @@ export function heldSecretsOf(config: JR2Config, lookups: HeldLookups = {}): Hel
     if (!(v.name in MODEL_KEYS)) continue;
     throw new Error(
       `harness.env[${i}] sets ${v.name}, a model key the Agent could read and take out of the pod — hold it ` +
-        `instead: heldSecrets: [${heldLine(v)}] (ADR-0059)`,
+        `instead: secrets: [${heldLine(v)}] (ADR-0059)`,
     );
   }
   for (const [i, ref] of (harness.envFrom ?? []).entries()) {
@@ -201,7 +254,7 @@ export function heldSecretsOf(config: JR2Config, lookups: HeldLookups = {}): Hel
     const where = ref.secretRef ? `Secret "${ref.secretRef.name}"` : `ConfigMap "${ref.configMapRef?.name}"`;
     throw new Error(
       `harness.envFrom[${i}] loads ${where}, which carries ${known} — a model key the Agent could read. Hold it ` +
-        `instead: heldSecrets: [{ name: "${known}", valueFrom: { secretKeyRef: { name: "${ref.secretRef?.name ?? "<secret>"}", key: "${known}" } } }], ` +
+        `instead: secrets: [{ name: "${known}", valueFrom: { secretKeyRef: { name: "${ref.secretRef?.name ?? "<secret>"}", key: "${known}" } } }], ` +
         `and drop the key from that ${ref.secretRef ? "Secret" : "ConfigMap"} (ADR-0059)`,
     );
   }
@@ -224,7 +277,9 @@ export function heldSecretsOf(config: JR2Config, lookups: HeldLookups = {}): Hel
     headers?: readonly string[];
     paths?: readonly string[];
   };
-  const entries: Entry[] = (harness.heldSecrets ?? []).map((s, i) => ({ at: `harness.heldSecrets[${i}]`, ...s }));
+  const entries: Entry[] = (config.secrets ?? []).flatMap((s, i) =>
+    claimed.has(s.name) ? [{ at: `secrets[${i}]`, ...s }] : [],
+  );
 
   // R2, for the user's own entries — before the implicit one joins them.
   for (const e of entries) {
@@ -241,7 +296,7 @@ export function heldSecretsOf(config: JR2Config, lookups: HeldLookups = {}): Hel
 
   // The custom provider's key: held since ADR-0059, bound to its own endpoint.
   const provider = harness.provider;
-  if (provider?.apiKey) {
+  if (provider?.apiKey && claimed.has(PROVIDER_KEY_NAME)) {
     const target = httpsTarget(provider.baseUrl);
     if (!target) {
       throw new Error(
@@ -335,7 +390,7 @@ export function heldSecretsOf(config: JR2Config, lookups: HeldLookups = {}): Hel
     )?.name;
   for (const [i, v] of env.entries()) {
     const ref = (v.valueFrom as { secretKeyRef?: { name?: string; key?: string } } | undefined)?.secretKeyRef;
-    if (ref?.name !== undefined && KIT_SECRETS.includes(ref.name)) {
+    if (ref?.name !== undefined && isKitSecret(ref.name)) {
       throw new Error(
         `harness.env[${i}] (${v.name}) reads Secret "${ref.name}", which is the kit's and never the Harness's — the ` +
           "Agent would read it. Drop the entry (ADR-0059)",
@@ -359,7 +414,7 @@ export function heldSecretsOf(config: JR2Config, lookups: HeldLookups = {}): Hel
   for (const [i, ref] of (harness.envFrom ?? []).entries()) {
     const secret = ref.secretRef?.name;
     if (secret === undefined) continue;
-    if (KIT_SECRETS.includes(secret)) {
+    if (isKitSecret(secret)) {
       throw new Error(
         `harness.envFrom[${i}] loads Secret "${secret}", which is the kit's and never the Harness's — the Agent ` +
           "would read every key of it. Drop the entry (ADR-0059)",
@@ -396,7 +451,7 @@ export function heldSecretsOf(config: JR2Config, lookups: HeldLookups = {}): Hel
 }
 
 /** R4 and R10: exactly one source, and a literal that can ride a header. */
-function sourceOf(
+export function sourceOf(
   e: { at: string; name: string; value?: string; valueFrom?: { secretKeyRef: { name: string; key: string } } },
   lookups: HeldLookups,
 ): HeldBinding["source"] {
@@ -539,7 +594,7 @@ export function normalHost(raw: string): string {
   return bare;
 }
 
-/** The `heldSecrets` line R1 hands back, built from the entry it refuses. */
+/** The `secrets` line R1 hands back, built from the entry it refuses. */
 function heldLine(v: HarnessEnvVar): string {
   const ref = (v.valueFrom as { secretKeyRef?: { name?: string; key?: string } } | undefined)?.secretKeyRef;
   if (ref?.name && ref.key) {
@@ -549,7 +604,8 @@ function heldLine(v: HarnessEnvVar): string {
 }
 
 /**
- * Read the manifest `jr2 up` wrote (`held.json`, mounted from the `jr2-held` ConfigMap), per call —
+ * Read the manifest `jr2 up` wrote for one pod (`held-<pod>.json`, mounted from the `jr2-held`
+ * ConfigMap), per call —
  * the `readImageRefs` stance (ADR-0038): no cache, so a `jr2 up` that changes a held secret reaches
  * the next provision without rolling the Orchestrator. Absent or malformed is a pointed error naming
  * `jr2 up`, never "nothing held": a Sandbox composed on a guess would put a key where the converge
@@ -562,8 +618,8 @@ export async function readHeldManifest(path: string): Promise<HeldManifest> {
   } catch (err) {
     throw new Error(
       `no held-secret manifest at ${path} (${(err as NodeJS.ErrnoException).code ?? "read failed"}) — every ` +
-        "Harness pod's Custodian is composed from the `jr2-held` ConfigMap, which `jr2 up` writes (ADR-0059). " +
-        "Converge this instance with `jr2 up`.",
+        "Harness pod's Custodian is composed from its own manifest in the `jr2-held` ConfigMap, which `jr2 up` " +
+        "writes for each Workspace it walked (ADR-0059). Converge this instance with `jr2 up`.",
     );
   }
   const bad = (why: string): never => {

package/src/holds.ts

@@ -0,0 +1,156 @@
+// The held answer (ADR-0024, ADR-0013): a pick that moves the workflow to a state inside the Agent's
+// state is answered when the workflow is back at Rest there (rest.ts). Until then the pick is
+// OUTSTANDING: its POST answered at once with a delivery id, and the Harness long-polls
+// `GET /agents/:iid/deliveries/:id` for the answer, inside the one tool call.
+//
+// A hold is plain data on the run (`RunBlob.holds`), saved with the snapshot, so a park or an
+// Orchestrator restart is a longer wait in the same Turn: the restored host reads the same Rest off
+// the restored Machine, and answers the same poll. What a hold keeps beside the delivery id is EVERY
+// reply from below the Agent's state since the pick (`chain`) — the last is the answer's default —
+// because the events that carried them are gone after a restart.
+//
+// The answer is the last reply since the pick, rendered by the Harness: a party's event (a Gate's
+// answer, a nested Agent's pick) with its payload, or a child's output (a child Machine, an Effect
+// stand-in). A chain link is a reply from below the Agent's state — from the set of active states
+// under it, never from a sibling region or the root; the events the Machine sent itself (`raise`,
+// `sendTo(self)`, a timer) are skipped, and so is a child's error: every outcome of work is its
+// output, and an error is a jr2 or config defect, never an answer. With no link, the answer carries
+// no reply — it does not say whether work ran.
+
+import type { AnyActorRef, AnyEventObject, AnyMachineSnapshot, AnyStateMachine } from "xstate";
+import { SENDER_KEY, type Sender } from "@jr2/agent-protocol";
+import { activeBelow } from "./rest.ts";
+import type { PickAnswer } from "./wire.ts";
+
+type Node = AnyStateMachine["root"];
+
+/** One outstanding pick, or its answer not yet superseded. JSON-safe: it rides the run blob. */
+export type Hold = {
+  /** The Agent address the pick was posted to. */
+  instanceId: string;
+  deliveryId: string;
+  /** The pick's event name. */
+  pick: string;
+  /** The Agent slot that picked — the Console's "held since" names it. */
+  agent: string;
+  /** ISO time the pick was delivered: the Console's "held since". */
+  since: string;
+  /** The Sandbox whose token may read the answer (ADR-0013) — the registration's, kept because the
+   * answer outlives a registration that a route out of the Agent's state ends. */
+  sandbox?: string;
+  /** The invoke id of the Agent's state when the pick was made: a re-registration of the same
+   * address by another state is another Turn. */
+  invokeId?: string;
+  /** The continued conversation (ADR-0057) the picking Turn is part of: where a route out of its
+   * state leaves the answer as a notice for its next Turn. Absent for a fresh Turn: no notice. */
+  conversation?: string;
+  /** Every reply since the pick, oldest first (ADR-0024): the last is the answer's default, and
+   * the whole is the `chain` an `answer` action reads (ADR-0067). Each link whole, a command's tail
+   * included, because the `answer` action may read it after a restore; dropped once `answer` is
+   * set. So a loop below the Agent's state grows the blob by one tail per pass while the pick is
+   * outstanding. */
+  chain?: PickAnswer[];
+  /** What the Machine's `answer` action set since the pick (ADR-0067): it replaces the default.
+   * Wrapped, so an answer of `null` is still one. */
+  shaped?: { value: unknown };
+  /** The last event the Machine took while the Agent's state was the hold's, with work still running
+   * below it, was no reply from below and no event a Machine sent itself at once: a timer the Machine
+   * set, an event from outside the states below, a party's event, the Agent's own end. If the Machine
+   * then left the Agent's state, the pick's route did not take it out: the exit stopped the work
+   * below (`HeldAnswer.stopped`). An event a Machine sends itself at once (`sendTo(self)`; a `raise`
+   * is never relayed) is part of the route of the event whose actions sent it and changes nothing
+   * here; a reply clears it. */
+  cutShort?: true;
+  /** The answer, once the Machine is back at Rest or has left the Agent's state. */
+  answer?: HeldAnswer;
+  /** The answer reached the model: the poll read it, or a re-admission carried it (ADR-0031). */
+  fetched?: boolean;
+};
+
+/** A pick's answer from what the Machine did since it: the author's `answer` when one ran, else the
+ * last reply; undefined when neither — the answer then carries no reply. */
+export function answerOf(record: {
+  chain?: readonly PickAnswer[];
+  shaped?: { value: unknown };
+}): PickAnswer | undefined {
+  if (record.shaped !== undefined) return { kind: "answer", value: record.shaped.value };
+  return record.chain?.at(-1);
+}
+
+/** The answer to an outstanding pick: the receipt's facts at the moment of Rest (ADR-0024). */
+export type HeldAnswer = {
+  /** The Machine left the Agent's state: the Turn is over. */
+  turnComplete: boolean;
+  /** The Allowed picks read AFTER the route (ADR-0029); empty once the Turn is over. */
+  allowed: string[];
+  /** The last reply since the pick — kept when the work was stopped after an earlier link replied. */
+  answer?: PickAnswer;
+  /** With `turnComplete`: something other than the pick's route left the Agent's state while the
+   * pick's work ran, and that exit stopped the work before it finished (`Hold.cutShort`). */
+  stopped?: true;
+};
+
+/**
+ * The reply one event is, when the invoking Machine receives it during a hold — or undefined when it
+ * is no reply. Rest, the answer and the ledger are computed over the SET of active states below the
+ * Agent's state (`seat`), so a reply comes from below it:
+ *
+ *   - from a child invoked on an active state below the seat (`source` is that child: its end, or an
+ *     event it sends its parent), or
+ *   - from a party seated below it: a Gate whose invoke id, or an Agent whose slot, is invoked on an
+ *     active state below the seat (the event's `sender`, ADR-0015).
+ *
+ * Everything else is skipped: the Machine's own events (`source` is the Machine itself: a `raise`, a
+ * `sendTo(self)`, a timer), an xstate event other than a child's output — a child's error
+ * (`xstate.error.actor.*`) is a defect, never a reply, so its message never reaches the model — and
+ * an event from outside the set: a Gate in a sibling region, a root Gate, an outside `jr2 send`.
+ * Read it as the event is relayed, before the Machine processes it: the states the reply came from are still active. A
+ * child is named by its slot (`src`) where it has one, else by its invoke id.
+ */
+export function replyOf(
+  event: AnyEventObject,
+  source: AnyActorRef | undefined,
+  machine: AnyActorRef,
+  seat: Node,
+): PickAnswer | undefined {
+  if (source === machine) return undefined;
+  const below = activeBelow(machine.getSnapshot() as AnyMachineSnapshot, seat).flatMap((node) => node.invoke);
+  const sender = (event as { [SENDER_KEY]?: Sender })[SENDER_KEY];
+  const fromChild = source !== undefined && below.some((inv) => inv.id === source.id);
+  const fromParty =
+    sender !== undefined &&
+    below.some((inv) => (sender.party === "gate" ? inv.id === sender.id : inv.src === sender.id));
+  if (!fromChild && !fromParty) return undefined;
+  const done = /^xstate\.done\.actor\.(.+)$/.exec(event.type);
+  if (done) {
+    const src = (source as { src?: unknown } | undefined)?.src;
+    const actor = typeof src === "string" ? src : done[1]!;
+    return { kind: "output", actor, output: (event as { output?: unknown }).output };
+  }
+  if (event.type.startsWith("xstate.")) return undefined;
+  const payload = Object.fromEntries(Object.entries(event).filter(([key]) => key !== "type" && key !== SENDER_KEY));
+  return { kind: "event", event: event.type, ...(sender ? { sender: { ...sender } } : {}), payload };
+}
+
+/**
+ * The error one event is, when it is a child's error from below the Agent's state (`seat`) — or
+ * undefined. It is no reply (`replyOf`): the Agent is not told by default, and the operator reads it
+ * on the run's feed (ADR-0024). The child is named as `replyOf` names it.
+ */
+export function childErrorOf(
+  event: AnyEventObject,
+  source: AnyActorRef | undefined,
+  machine: AnyActorRef,
+  seat: Node,
+): { child: string; error: string } | undefined {
+  const failed = /^xstate\.error\.actor\.(.+)$/.exec(event.type);
+  if (!failed || source === undefined || source === machine) return undefined;
+  const below = activeBelow(machine.getSnapshot() as AnyMachineSnapshot, seat).flatMap((node) => node.invoke);
+  if (!below.some((inv) => inv.id === source.id)) return undefined;
+  const src = (source as { src?: unknown }).src;
+  const error = (event as { error?: unknown }).error;
+  return {
+    child: typeof src === "string" ? src : failed[1]!,
+    error: error instanceof Error ? error.message : String(error),
+  };
+}