@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/src/harness/registry.ts

@@ -0,0 +1,203 @@
+/**
+ * The harness registry — the lifecycle fan-out over the adapters a worker
+ * runs, and the byte-pinned binding from harness to Temporal activity name.
+ *
+ * Plain functions over an `adapters` argument, no module state and no DI
+ * (the composition roots are staged plain functions; a missing adapter is a
+ * compile error or a loud boot throw, never a silent no-op). ORDER IS
+ * LOAD-BEARING: `bootHarnesses` runs adapters in declaration order because
+ * the Cursor harness's interceptors must patch `node:http2` before anything
+ * dials the control plane, and `shutdownHarnesses` runs them in reverse so
+ * what was set up last is torn down first.
+ *
+ * Error posture (fixed in #1064):
+ *  - Boot validates the whole table BEFORE booting anything (a duplicate name
+ *    is a configuration defect, and a half-booted worker is the worst state to
+ *    discover it in), then fails fast at the first adapter that rejects. A
+ *    worker that cannot boot a harness must not start.
+ *  - Shutdown and session release CONTINUE past a failing adapter and throw
+ *    one `AggregateError` at the end naming each failure, so one bad teardown
+ *    never leaks the others' resources.
+ *
+ * `createHarnessActivities` binds each row to its Temporal activity over the
+ * turn runtime (`run-turn.ts`). The table of real rows is NOT here: it lives
+ * at the source root (`src/harness-adapters.ts`), because a row imports its
+ * adapter from `activities/` and nothing under `src/harness/` may
+ * (`__tests__/import-direction.test.ts`). The registry knows rows,
+ * never which adapters exist.
+ *
+ * `HarnessName` lives here and not in `types.ts` on purpose: the wire
+ * vocabulary is the registry's concern. An adapter never declares the
+ * activity it is bound to (its `name` is a diagnostic identity); the registry
+ * row does.
+ *
+ * THIS MODULE'S STATIC GRAPH MUST STAY CONNECT-FREE. Both composition roots
+ * import it BEFORE they boot the harnesses, and the Cursor adapter's boot
+ * patches `node:http2` (its HTTP/2 auth interceptor); a static import of
+ * anything that loads `@connectrpc/connect-node` here would snapshot the
+ * `node:http2` ESM facade to the unpatched `connect` before that boot ran,
+ * and every BiDi stream would silently 401. So `StigmerClient` is loaded
+ * with a dynamic import inside `createHarnessActivities`, the runner's
+ * dynamic-import-for-order convention (`bootstrap.ts` documents the same
+ * omission for the same reason). `__tests__/harness-boot-order.test.ts`
+ * boots a fresh process through this module and fails if the facade froze.
+ */
+
+import type { Config } from "../config.js";
+import type { StigmerClient } from "../client/stigmer-client.js";
+import { activityFinished, activityStarted } from "../idle-watchdog.js";
+import { normalizeActivityInput, type ExecuteActivityInput } from "../shared/activity-input.js";
+import { runTurnActivity } from "./run-turn.js";
+import type { HarnessAdapter } from "./types.js";
+
+/** The harnesses the control plane can dispatch to, as the registry knows them. */
+export type HarnessName = "cursor" | "deep-agent";
+
+/**
+ * Byte-pinned Temporal activity names, one per harness. The server side of
+ * the pin is `stigmer-server/src/temporal/agentexecution/names.ts`
+ * (`EXECUTE_CURSOR_ACTIVITY_NAME`, `EXECUTE_DEEP_AGENT_ACTIVITY_NAME`); the
+ * two must stay byte-identical or the workflow schedules an activity no
+ * worker registers. Never "cleaned up".
+ */
+export const HARNESS_ACTIVITY_NAMES = {
+  cursor: "ExecuteCursor",
+  "deep-agent": "ExecuteDeepAgent",
+} as const satisfies Record<HarnessName, string>;
+
+export type HarnessActivityName = (typeof HARNESS_ACTIVITY_NAMES)[HarnessName];
+
+/** One harness the worker serves: the wire name it answers to and the adapter that runs its turns. */
+export interface HarnessRow {
+  readonly harness: HarnessName;
+  readonly adapter: HarnessAdapter;
+}
+
+/**
+ * The legacy positional activity signature, kept as the wire shape both
+ * control planes send until they both send the typed object
+ * (`shared/activity-input.ts`). Every harness's activity has it.
+ */
+export type HarnessActivity = (arg0: ExecuteActivityInput | string, arg1?: string) => Promise<unknown>;
+
+/** The row serving `harness`; a harness the table lacks is a wiring defect, so it throws. */
+export function harnessRowFor(rows: readonly HarnessRow[], harness: HarnessName): HarnessRow {
+  const row = rows.find((r) => r.harness === harness);
+  if (!row) throw new Error(`harness registry: no adapter serves '${harness}'`);
+  return row;
+}
+
+/** The adapters of a row list, for the lifecycle functions below. */
+export function adaptersOf(rows: readonly HarnessRow[]): HarnessAdapter[] {
+  return rows.map((row) => row.adapter);
+}
+
+/**
+ * One Temporal activity per row, under the row's byte-pinned name, over ONE
+ * `StigmerClient` for all of them (each harness used to build its own). The
+ * activity normalizes the wire input, brackets the turn with the idle
+ * watchdog, and hands the turn runtime the adapter. The roots spread the
+ * result into the worker's activity map beside the activities the runtime
+ * does not own.
+ *
+ * Async because the client is loaded here, not at the top of the module (see
+ * the header): the roots call this after the harnesses have booted, when
+ * connect-node may load.
+ */
+export async function createHarnessActivities(
+  rows: readonly HarnessRow[],
+  config: Config,
+): Promise<Partial<Record<HarnessActivityName, HarnessActivity>>> {
+  const { StigmerClient } = await import("../client/stigmer-client.js");
+  const client: StigmerClient = new StigmerClient({
+    endpoint: config.stigmerBackendEndpoint,
+    tokenRef: config.stigmerTokenRef,
+    runnerTokenRef: config.stigmerRunnerTokenRef,
+  });
+  const activities: Partial<Record<HarnessActivityName, HarnessActivity>> = {};
+  for (const row of rows) {
+    const activityName = HARNESS_ACTIVITY_NAMES[row.harness];
+    const deps = { adapter: row.adapter, activityName, client, config };
+    activities[activityName] = async (arg0, arg1) => {
+      const input = normalizeActivityInput(arg0, arg1);
+      activityStarted();
+      try {
+        return await runTurnActivity(deps, input);
+      } finally {
+        activityFinished();
+      }
+    };
+  }
+  return activities;
+}
+
+/**
+ * Refuse a table two of whose adapters share a name. Names are the registry's
+ * identity for diagnostics and for this check; a duplicate means two adapters
+ * would be indistinguishable in every log line and kit message.
+ */
+function assertUniqueNames(adapters: readonly HarnessAdapter[]): void {
+  const seen = new Set<string>();
+  for (const adapter of adapters) {
+    if (seen.has(adapter.name)) {
+      throw new Error(`harness registry: duplicate adapter name '${adapter.name}'; every adapter must have a unique name`);
+    }
+    seen.add(adapter.name);
+  }
+}
+
+/**
+ * Boot every adapter in declaration order, one at a time, awaiting each. The
+ * table is validated first; the first rejection stops the boot and propagates
+ * (adapters after it are never booted; adapters before it stay booted for the
+ * caller's shutdown path to release).
+ */
+export async function bootHarnesses(adapters: readonly HarnessAdapter[], config: Config): Promise<void> {
+  assertUniqueNames(adapters);
+  for (const adapter of adapters) {
+    await adapter.boot(config);
+  }
+}
+
+/**
+ * Shut every adapter down in reverse declaration order, continuing past
+ * failures. Rejects with one `AggregateError` carrying every failure once all
+ * adapters have been given their chance.
+ */
+export async function shutdownHarnesses(adapters: readonly HarnessAdapter[]): Promise<void> {
+  const failures: Error[] = [];
+  for (const adapter of [...adapters].reverse()) {
+    try {
+      await adapter.shutdown();
+    } catch (err) {
+      failures.push(describeFailure(adapter, "shutdown", err));
+    }
+  }
+  throwIfAny(failures, "harness registry: shutdown failed for one or more adapters");
+}
+
+/**
+ * Tell every adapter the session is done on this host, in declaration order,
+ * continuing past failures. An adapter that parks nothing per session
+ * resolves as a no-op; the registry does not know which do.
+ */
+export async function releaseHarnessSession(adapters: readonly HarnessAdapter[], sessionId: string): Promise<void> {
+  const failures: Error[] = [];
+  for (const adapter of adapters) {
+    try {
+      await adapter.releaseSession(sessionId);
+    } catch (err) {
+      failures.push(describeFailure(adapter, `releaseSession('${sessionId}')`, err));
+    }
+  }
+  throwIfAny(failures, `harness registry: releaseSession('${sessionId}') failed for one or more adapters`);
+}
+
+function describeFailure(adapter: HarnessAdapter, call: string, err: unknown): Error {
+  const cause = err instanceof Error ? err : new Error(String(err));
+  return new Error(`${adapter.name}: ${call} rejected: ${cause.message}`, { cause });
+}
+
+function throwIfAny(failures: readonly Error[], message: string): void {
+  if (failures.length > 0) throw new AggregateError(failures, `${message}: ${failures.map((f) => f.message).join("; ")}`);
+}

package/src/harness/run-span.ts

@@ -0,0 +1,184 @@
+/**
+ * A turn's `invoke_agent {agent}` span: what a tracing tool lists as the
+ * run, for every harness alike, started by the turn runtime
+ * (`run-turn.ts`) around the whole activity.
+ *
+ * Root, never a child. The run workflow lives in the server, which has no
+ * tracer, so the runner's Temporal activity span would otherwise be the
+ * trace's root and every run would be listed as `RunActivity:...`. Each
+ * turn's span is a root instead, named after the agent, with a link to the
+ * activity span when one is active, so the operational spans stay one click
+ * away. Started inside the run's execution context, it takes the run's
+ * trace id (`run-trace-id.ts`): a run that waits for an approval and
+ * resumes stays one trace, each turn a root span in it.
+ *
+ * The whole turn runs in its context, so the runtime's own RPCs carry it
+ * to the server (`client/stigmer-client.ts` injects the active context),
+ * the agent's hooks join it, and the agent host runs the engine under it
+ * (`shared/trace-context.ts`), where the engines' `chat` and
+ * `execute_tool` spans nest (`middleware/otel-spans.ts`,
+ * `activities/execute-cursor/run-telemetry.ts`).
+ *
+ * Its facts arrive as resolution learns them: the run and its session
+ * ({@link RunSpan.identify}, which also names the span), the model, the
+ * answer, and how the turn ended ({@link RunSpan.settle}, from the status
+ * the terminal table wrote). No usage is set here: the `chat` spans carry
+ * it, and a tool that sums both would count it twice. With content on
+ * (`otel-export.ts`), the turn's request and answer, and who asked
+ * (`user.id`, which can be an email, so never without content).
+ *
+ * `stigmer.run.kind` tells what started the run, read from the labels the
+ * server sets: a judge's grade, an eval run's try, a schedule's run, or a
+ * conversation, so a tool can filter each.
+ */
+
+import { SpanKind, context, trace, type Span } from "@opentelemetry/api";
+import type { Run } from "@stigmer/apis/ai/stigmer/agentic/run/v1/api_pb";
+import { RunPhase } from "@stigmer/apis/ai/stigmer/agentic/run/v1/enum_pb";
+import type { RunStatus } from "@stigmer/apis/ai/stigmer/agentic/run/v1/api_pb";
+import type { Session } from "@stigmer/apis/ai/stigmer/agentic/session/v1/api_pb";
+
+import {
+  GEN_AI_AGENT_ID,
+  GEN_AI_AGENT_NAME,
+  GEN_AI_AGENT_VERSION,
+  GEN_AI_CONVERSATION_ID,
+  GEN_AI_INPUT_MESSAGES,
+  GEN_AI_OPERATION_NAME,
+  GEN_AI_OUTPUT_MESSAGES,
+  GEN_AI_REQUEST_MODEL,
+  OP_INVOKE_AGENT,
+  STIGMER_HARNESS,
+  STIGMER_ORGANIZATION,
+  STIGMER_RUN_ID,
+  STIGMER_RUN_KIND,
+  STIGMER_RUN_TURN,
+  TRACER_NAME,
+  USER_ID,
+  type RunKind,
+} from "../gen-ai-conventions.js";
+import { telemetrySettings } from "../otel-export.js";
+import type { ResolvedBlueprint } from "../shared/blueprint-resolver.js";
+import { GRADES_RUN_LABEL } from "../shared/builtin-judge.js";
+import { markFailed, turnContent } from "../shared/telemetry-content.js";
+
+/** The label the server sets on an eval run's try (the server's `domain/eval-run/constants.ts`). Wire contract. */
+export const EVAL_RUN_LABEL = "stigmer.ai/eval-run";
+/** The label the server sets on a schedule's run (the server's `domain/schedule/labels.ts`). Wire contract. */
+export const SCHEDULE_ID_LABEL = "stigmer.ai/schedule-id";
+
+/** The agent name of a turn that runs no saved agent. */
+export const ASSISTANT_AGENT_NAME = "assistant";
+/** The agent name of a judge's grade. */
+export const JUDGE_AGENT_NAME = "judge";
+
+/** What resolution knows once it has the run and its session. */
+export interface RunFacts {
+  readonly execution: Run;
+  readonly session: Session;
+  readonly sessionId: string;
+  readonly blueprint: ResolvedBlueprint;
+}
+
+/** The turn's span, as the runtime feeds it. Every method is a no-op when tracing is off. */
+export interface RunSpan {
+  /** Name and stamp the span: the agent, the conversation, the organization, what started the run. */
+  identify(facts: RunFacts): void;
+  /** The model the turn asked for. */
+  model(requested: string): void;
+  /** The turn's final answer, the span's output when content is on. */
+  answer(text: string | undefined): void;
+  /** How the turn ended, from the status the terminal table wrote. */
+  settle(status: RunStatus): void;
+}
+
+/** What started a run, from the labels the server sets on it. */
+export function runKindOf(labels: Readonly<Record<string, string>> | undefined): RunKind {
+  if ((labels?.[GRADES_RUN_LABEL] ?? "") !== "") return "judge";
+  if ((labels?.[EVAL_RUN_LABEL] ?? "") !== "") return "eval-try";
+  if ((labels?.[SCHEDULE_ID_LABEL] ?? "") !== "") return "schedule";
+  return "conversation";
+}
+
+/** The agent a run's span is named after: the session's agent by its slug, else the assistant, the judge for a grade. */
+export function agentNameOf(execution: Run, session: Session): string {
+  if (runKindOf(execution.metadata?.labels) === "judge") return JUDGE_AGENT_NAME;
+  return session.spec?.agentRef?.slug || ASSISTANT_AGENT_NAME;
+}
+
+/** The phases a turn that ended badly settles in, which mark the span as an error. */
+const FAILED_PHASES: ReadonlySet<RunPhase> = new Set([RunPhase.RUN_FAILED]);
+
+class RecordingRunSpan implements RunSpan {
+  private readonly content = telemetrySettings().content;
+
+  constructor(private readonly span: Span) {}
+
+  identify({ execution, session, sessionId, blueprint }: RunFacts): void {
+    const name = agentNameOf(execution, session);
+    this.span.updateName(`${OP_INVOKE_AGENT} ${name}`);
+    this.span.setAttributes({
+      [GEN_AI_AGENT_NAME]: name,
+      [GEN_AI_CONVERSATION_ID]: sessionId,
+      [STIGMER_ORGANIZATION]: session.metadata?.org ?? "",
+      [STIGMER_RUN_KIND]: runKindOf(execution.metadata?.labels),
+      ...(blueprint.agent?.id ? { [GEN_AI_AGENT_ID]: blueprint.agent.id } : {}),
+      ...(blueprint.agent?.versionHash ? { [GEN_AI_AGENT_VERSION]: blueprint.agent.versionHash } : {}),
+    });
+    if (!this.content) return;
+    const asker = execution.status?.audit?.specAudit?.createdBy?.id;
+    if (asker) this.span.setAttribute(USER_ID, asker);
+    this.span.setAttribute(GEN_AI_INPUT_MESSAGES, turnContent(execution.spec?.message ?? "", undefined).input);
+  }
+
+  model(requested: string): void {
+    if (requested) this.span.setAttribute(GEN_AI_REQUEST_MODEL, requested);
+  }
+
+  answer(text: string | undefined): void {
+    if (!this.content || text === undefined) return;
+    const { output } = turnContent("", text);
+    if (output !== undefined) this.span.setAttribute(GEN_AI_OUTPUT_MESSAGES, output);
+  }
+
+  settle(status: RunStatus): void {
+    if (!FAILED_PHASES.has(status.phase)) return;
+    markFailed(this.span, RunPhase[status.phase] ?? "RUN_FAILED", { message: status.error }, this.content);
+  }
+}
+
+const NO_SPAN: RunSpan = {
+  identify() {},
+  model() {},
+  answer() {},
+  settle() {},
+};
+
+/**
+ * Run one turn inside its `invoke_agent` span. Call inside the run's
+ * execution context (`shared/execution-context.ts`), so the span takes the
+ * run's trace id.
+ */
+export async function withRunSpan<T>(
+  turn: { readonly executionId: string; readonly turnSeq: number; readonly harness: string },
+  body: (span: RunSpan) => Promise<T>,
+): Promise<T> {
+  const activity = trace.getSpan(context.active());
+  const span = trace.getTracer(TRACER_NAME).startSpan(OP_INVOKE_AGENT, {
+    root: true,
+    kind: SpanKind.INTERNAL,
+    ...(activity?.isRecording() ? { links: [{ context: activity.spanContext() }] } : {}),
+    attributes: {
+      [GEN_AI_OPERATION_NAME]: OP_INVOKE_AGENT,
+      [STIGMER_RUN_ID]: turn.executionId,
+      [STIGMER_RUN_TURN]: turn.turnSeq,
+      [STIGMER_HARNESS]: turn.harness,
+    },
+  });
+  const runSpan = span.isRecording() ? new RecordingRunSpan(span) : NO_SPAN;
+  try {
+    return await context.with(trace.setSpan(context.active(), span), () => body(runSpan));
+  } finally {
+    span.end();
+  }
+}