@jr2/orchestrator 0.2.0 → 0.3.0

package/src/harness-client.ts

@@ -10,7 +10,7 @@
 // socket-free through an injected `fetch`.
 //
 // Channel split (ADR-0002, refined by ADR-0016): the Harness wire carries **lifecycle only** —
-// domain events go up the MCP channel via the Adapter. The client's `send`/`wait` pair is exactly
+// domain events go up the Menu, through the pod's Custodian. The client's `send`/`wait` pair is exactly
 // that lifecycle surface: `send` answers with a serializable Admission
 // (`{ streamUrl, offset, submissionId }` — jr2's durable re-attach handle, stored in the host
 // ledger), and `wait(admission)` follows the durable stream from the admission offset to the
@@ -80,6 +80,10 @@ export type HarnessClient = {
 export type HarnessClientOptions = {
   /** The Harness base URL — what a workspace publishes, or a stub's `url`. */
   baseUrl: string;
+  /** The Harness bearer for this placement (ADR-0058; `harnessToken` in tokens.ts) — sent on
+   * every call, the long-poll included. Absent only where no placement exists: an explicit-
+   * `endpoint` run against the stub Harness, which checks nothing. */
+  token?: string;
   /** Injectable for socket-free tests. Default: global `fetch`. */
   fetch?: typeof fetch;
   /** Reconnect backoff floor/ceiling (capped exponential, jittered per rung — see `jittered`;
@@ -125,6 +129,7 @@ export function createHarnessClient(options: HarnessClientOptions): HarnessClien
   const backoffMaxMs = options.backoffMaxMs ?? 5_000;
   const admitWindowMs = options.admitWindowMs ?? 90_000;
   const log = options.log ?? ((line: string) => console.warn(line));
+  const authorization: Record<string, string> = options.token ? { authorization: `Bearer ${options.token}` } : {};
 
   const conversationUrl = (agentName: string, instanceId: string) =>
     new URL(`/agents/${encodeURIComponent(agentName)}/${encodeURIComponent(instanceId)}`, baseUrl).toString();
@@ -192,7 +197,7 @@ export function createHarnessClient(options: HarnessClientOptions): HarnessClien
         url,
         {
           method: "POST",
-          headers: { "content-type": "application/json" },
+          headers: { "content-type": "application/json", ...authorization },
           body: JSON.stringify({
             message: sendOptions.message,
             // The other half of the Frame (ADR-0057): where this Turn works. Omitted only when
@@ -238,13 +243,21 @@ export function createHarnessClient(options: HarnessClientOptions): HarnessClien
         let events: StreamEvent[];
         let nextOffset: string | null;
         try {
-          const res = await fetchImpl(url.toString(), { signal });
+          const res = await fetchImpl(url.toString(), { headers: authorization, signal });
           if (res.status === 404) {
             throw new SettlementFault(
               `conversation lost: the harness answered 404 for submission "${admission.submissionId}" — ` +
                 `a conversation lives as long as its Harness process (ADR-0027)`,
             );
           }
+          // Refused, not unreachable: the bearer is derived, so a Harness that rejects it now
+          // rejects it on every retry — reconnecting would park the Turn forever, silently.
+          if (res.status === 401 || res.status === 403) {
+            throw new SettlementFault(
+              `harness refused the stream read (${res.status}) for submission "${admission.submissionId}": ` +
+                `${await errorDetail(res)} — the bearer is not this placement's (ADR-0058)`,
+            );
+          }
           if (!res.ok && res.status !== 204) {
             throw new ReconnectableError(`harness stream read failed (${res.status})`);
           }
@@ -274,6 +287,7 @@ export function createHarnessClient(options: HarnessClientOptions): HarnessClien
     async abort(agentName, instanceId, opts) {
       const res = await fetchImpl(`${conversationUrl(agentName, instanceId)}/abort`, {
         method: "POST",
+        headers: authorization,
         signal: opts?.signal,
       });
       if (!res.ok) {
@@ -334,16 +348,16 @@ export function createHarnessAgentRunClient(options: HarnessClientOptions): Agen
 
 /**
  * The run-narrative echo push (ADR-0023): `POST /echo { events }` against one Workspace Harness,
- * bearing the Instance token (the endpoint is instance-token-gated — the Harness verifies the
- * bearer against the token's sha-256, never holding the token itself). The payload is the
+ * bearing that placement's Harness bearer (ADR-0058 — the Harness verifies it against a sha-256,
+ * never holding it at rest). The payload is the
  * STRUCTURED feed events; the Harness renders. A non-OK answer rejects, and the CALLER treats
  * that as log-and-continue — fire-and-forget lives in the tee (run-host.ts), not here, so a test
  * can still assert a push failed.
  */
 export function createEchoPush(options: {
   baseUrl: string;
-  /** The Instance token — the echo bearer. */
-  token: string;
+  /** The Workspace's Harness bearer (ADR-0058). Absent only against the stub Harness. */
+  token?: string;
   /** Injectable for socket-free tests. Default: global `fetch`. */
   fetch?: typeof fetch;
 }): (events: EchoEvent[]) => Promise<void> {
@@ -356,7 +370,10 @@ export function createEchoPush(options: {
     // `fetch failed` in the pod log is what let that condition hide.
     const res = await fetchImpl(url, {
       method: "POST",
-      headers: { "content-type": "application/json", authorization: `Bearer ${options.token}` },
+      headers: {
+        "content-type": "application/json",
+        ...(options.token ? { authorization: `Bearer ${options.token}` } : {}),
+      },
       body: JSON.stringify({ events }),
     }).catch((err: unknown) => {
       throw new Error(`harness echo to ${url} failed: ${transportDetail(err)}`, { cause: err });
@@ -386,7 +403,10 @@ export function createEchoPush(options: {
  * still an `AgentDefinition`: the actor narrows on start and refuses an Open one there.
  */
 export function agent(declaration: AgentDeclaration): AgentLogic {
-  return agentActorWith((endpoint) => createHarnessAgentRunClient({ baseUrl: endpoint }), declaration);
+  return agentActorWith(
+    (endpoint, bearer) => createHarnessAgentRunClient({ baseUrl: endpoint, ...(bearer ? { token: bearer } : {}) }),
+    declaration,
+  );
 }
 
 /** A stream read worth retrying (server hiccup) — internal to the reconnect loop, never thrown out. */
@@ -457,7 +477,7 @@ async function errorDetail(res: Response): Promise<string> {
 
 /**
  * The marker the `@kind` tier greps for, and therefore a CONTRACT — duplicated verbatim in
- * `@jr2/adapter` (the two packages share no runtime dependency) and matched in
+ * `@jr2/harness`'s Menu (the two packages share no runtime dependency) and matched in
  * `features/steps/kind.steps.ts`. Renaming it on one side does not break a build; it silently turns
  * the tier's routability budget into a check that passes because it matches nothing.
  */