@stigmer/runner 3.0.1

package/src/activities/workflow-event-activities.ts

@@ -0,0 +1,481 @@
+/**
+ * Local activities for emitting workflow execution events.
+ *
+ * Converts plain event descriptors (safe for the Temporal deterministic
+ * sandbox) into WorkflowExecutionEvent proto objects and sends them
+ * alongside a status update via gRPC. Best-effort — failures are logged
+ * but do not fail the activity.
+ *
+ * Registered as proxyLocalActivities in engine-core.ts so the workflow
+ * sandbox can emit events at task boundaries and approval gates.
+ */
+
+import { StigmerClient } from "../client/stigmer-client.js";
+import { loadConfig } from "../config.js";
+import { create } from "@bufbuild/protobuf";
+import {
+  WorkflowExecutionEventSchema,
+  type WorkflowExecutionEvent,
+  WorkflowEventType,
+  ExecutionStartedPayloadSchema,
+  ExecutionCompletedPayloadSchema,
+  ExecutionFailedPayloadSchema,
+  TaskStartedPayloadSchema,
+  TaskCompletedPayloadSchema,
+  TaskFailedPayloadSchema,
+  TaskSkippedPayloadSchema,
+  TaskRetryingPayloadSchema,
+  ApprovalRequestedPayloadSchema,
+  ApprovalResolvedPayloadSchema,
+  AgentCallStartedPayloadSchema,
+  AgentCallProgressPayloadSchema,
+  AgentCallCompletedPayloadSchema,
+  ArtifactCreatedPayloadSchema,
+  HumanInputOutcomeInfoSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/event_pb";
+import { WorkflowExecutionStatusSchema, WorkflowTaskSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import {
+  WorkflowExecutionUpdateStatusInputSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import { ExecutionPhase, WorkflowTaskStatus, WorkflowTaskType } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+import { ExecutionPhase as AgentExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { WorkflowTaskKind } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/enum_pb";
+import type { JsonObject } from "@bufbuild/protobuf";
+import type { WorkflowEventDescriptor } from "../workflow-engine/types.js";
+import type { TaskStatusEntry } from "../workflow-engine/task-status-accumulator.js";
+import type { RecoveryTaskData } from "../workflow-engine/recovery.js";
+
+const TASK_STATUS_MAP: Record<TaskStatusEntry["status"], WorkflowTaskStatus> = {
+  started: WorkflowTaskStatus.WORKFLOW_TASK_IN_PROGRESS,
+  completed: WorkflowTaskStatus.WORKFLOW_TASK_COMPLETED,
+  failed: WorkflowTaskStatus.WORKFLOW_TASK_FAILED,
+  skipped: WorkflowTaskStatus.WORKFLOW_TASK_SKIPPED,
+  waiting_approval: WorkflowTaskStatus.WORKFLOW_TASK_WAITING_APPROVAL,
+};
+
+/**
+ * Maps internal DSL task kind strings to proto WorkflowTaskKind enum values.
+ *
+ * IMPORTANT: Values must match the proto enum in
+ * apis/ai/stigmer/agentic/workflow/v1/enum.proto — use the imported
+ * WorkflowTaskKind enum to prevent drift.
+ *
+ * The "call:function:<sub>" entries handle call:function sub-types.
+ * The do-executor emits these composite strings so the event carries
+ * the specific proto kind (llm_call, eval, etc.) instead of the
+ * generic activity_call fallback.
+ */
+const TASK_KIND_MAP: Record<string, number> = {
+  "set": WorkflowTaskKind.set_vars,
+  "call:http": WorkflowTaskKind.http_call,
+  "call:grpc": WorkflowTaskKind.grpc_call,
+  "call:function": WorkflowTaskKind.activity_call,
+  "call:function:llm": WorkflowTaskKind.llm_call,
+  "call:function:transform": WorkflowTaskKind.transform,
+  "call:function:validate": WorkflowTaskKind.validate,
+  "call:function:emit_event": WorkflowTaskKind.emit_event,
+  "call:function:notification": WorkflowTaskKind.notification,
+  "call:function:eval": WorkflowTaskKind.eval,
+  "switch": WorkflowTaskKind.switch_case,
+  "for": WorkflowTaskKind.for_each,
+  "fork": WorkflowTaskKind.fork,
+  "try": WorkflowTaskKind.try_catch,
+  "listen": WorkflowTaskKind.listen,
+  "wait": WorkflowTaskKind.wait,
+  "raise": WorkflowTaskKind.raise_error,
+  "run": WorkflowTaskKind.run_workflow,
+  "call:function:cursor": WorkflowTaskKind.agent_call,
+  "call:agent": WorkflowTaskKind.agent_call,
+  "human_input": WorkflowTaskKind.human_input,
+};
+
+/**
+ * Maps DSL task kind strings to the runtime WorkflowTaskType enum
+ * for the per-task status snapshot on WorkflowExecutionStatus.tasks[].
+ */
+const TASK_KIND_TO_TYPE_MAP: Record<string, WorkflowTaskType> = {
+  "call:agent": WorkflowTaskType.WORKFLOW_TASK_AGENT_INVOCATION,
+  "call:function:llm": WorkflowTaskType.WORKFLOW_TASK_API_CALL,
+  "call:function:eval": WorkflowTaskType.WORKFLOW_TASK_API_CALL,
+  "call:function:cursor": WorkflowTaskType.WORKFLOW_TASK_AGENT_INVOCATION,
+  "call:http": WorkflowTaskType.WORKFLOW_TASK_API_CALL,
+  "call:grpc": WorkflowTaskType.WORKFLOW_TASK_API_CALL,
+  "call:function": WorkflowTaskType.WORKFLOW_TASK_API_CALL,
+  "human_input": WorkflowTaskType.WORKFLOW_TASK_APPROVAL,
+  "switch": WorkflowTaskType.WORKFLOW_TASK_CONDITIONAL,
+  "fork": WorkflowTaskType.WORKFLOW_TASK_PARALLEL,
+  "for": WorkflowTaskType.WORKFLOW_TASK_PARALLEL,
+  "set": WorkflowTaskType.WORKFLOW_TASK_TRANSFORM,
+  "call:function:transform": WorkflowTaskType.WORKFLOW_TASK_TRANSFORM,
+  "call:function:validate": WorkflowTaskType.WORKFLOW_TASK_TRANSFORM,
+  "try": WorkflowTaskType.WORKFLOW_TASK_CUSTOM,
+  "listen": WorkflowTaskType.WORKFLOW_TASK_CUSTOM,
+  "do": WorkflowTaskType.WORKFLOW_TASK_CUSTOM,
+  "wait": WorkflowTaskType.WORKFLOW_TASK_CUSTOM,
+  "raise": WorkflowTaskType.WORKFLOW_TASK_CUSTOM,
+  "run": WorkflowTaskType.WORKFLOW_TASK_CUSTOM,
+};
+
+/**
+ * Converts a plain JS value to a JsonObject suitable for proto Struct fields.
+ * Returns undefined if the value is not a valid JSON-serializable object.
+ */
+function toJsonObject(value: unknown): JsonObject | undefined {
+  if (value === null || value === undefined) return undefined;
+  if (typeof value !== "object" || Array.isArray(value)) return undefined;
+  try {
+    return JSON.parse(JSON.stringify(value)) as JsonObject;
+  } catch {
+    return undefined;
+  }
+}
+
+function buildClient(): StigmerClient {
+  const config = loadConfig();
+  return new StigmerClient({
+    endpoint: config.stigmerBackendEndpoint,
+    token: config.stigmerToken,
+  });
+}
+
+let sequenceCounter = 0;
+
+function nextSequence(): bigint {
+  sequenceCounter += 1;
+  return BigInt(sequenceCounter);
+}
+
+/**
+ * Initialize the event sequence counter from the persisted high-water mark.
+ *
+ * On first run (no prior events), the counter stays at 0 and the first
+ * event gets sequence_number = 1 — identical to the original behavior.
+ *
+ * On recovery (events already persisted from a failed run), the counter
+ * is set to the highest persisted sequence_number so that new events
+ * continue from N+1, avoiding duplicate-key collisions in storage.
+ *
+ * When executionId is empty (direct executeServerlessWorkflow without a
+ * persisted execution), the counter resets to 0 as a safe fallback.
+ */
+export async function initSequenceFromEventLog(executionId: string): Promise<void> {
+  if (!executionId) {
+    sequenceCounter = 0;
+    return;
+  }
+  const client = buildClient();
+  const highWaterMark = await client.getEventLogHighWaterMark(executionId);
+  sequenceCounter = Number(highWaterMark);
+}
+
+/** @internal Exported for unit testing only. */
+export function toProtoEvent(desc: WorkflowEventDescriptor): WorkflowExecutionEvent {
+  const base = create(WorkflowExecutionEventSchema, {
+    eventId: crypto.randomUUID(),
+    sequenceNumber: nextSequence(),
+    occurredAt: desc.occurredAt,
+    taskName: desc.taskName ?? "",
+  });
+
+  switch (desc.type) {
+    case "execution_started":
+      base.eventType = WorkflowEventType.execution_started;
+      base.payload = {
+        case: "executionStarted",
+        value: create(ExecutionStartedPayloadSchema, {
+          totalTasks: desc.totalTasks,
+          workflowId: desc.workflowId,
+          workflowInstanceId: desc.workflowInstanceId,
+        }),
+      };
+      break;
+
+    case "execution_completed":
+      base.eventType = WorkflowEventType.execution_completed;
+      base.payload = {
+        case: "executionCompleted",
+        value: create(ExecutionCompletedPayloadSchema, {
+          durationMs: BigInt(desc.durationMs),
+          totalCostMicros: BigInt(desc.totalCostMicros),
+          totalTokens: BigInt(desc.totalTokens),
+        }),
+      };
+      break;
+
+    case "execution_failed":
+      base.eventType = WorkflowEventType.execution_failed;
+      base.payload = {
+        case: "executionFailed",
+        value: create(ExecutionFailedPayloadSchema, {
+          error: desc.error,
+          failedTaskName: desc.failedTaskName,
+          durationMs: BigInt(desc.durationMs),
+        }),
+      };
+      break;
+
+    case "task_started":
+      base.eventType = WorkflowEventType.task_started;
+      base.payload = {
+        case: "taskStarted",
+        value: create(TaskStartedPayloadSchema, {
+          taskKind: TASK_KIND_MAP[desc.taskKind] ?? 0,
+          attemptNumber: desc.attemptNumber,
+        }),
+      };
+      break;
+
+    case "task_completed":
+      base.eventType = WorkflowEventType.task_completed;
+      base.payload = {
+        case: "taskCompleted",
+        value: create(TaskCompletedPayloadSchema, {
+          taskKind: TASK_KIND_MAP[desc.taskKind] ?? 0,
+          durationMs: BigInt(desc.durationMs),
+          costMicros: BigInt(desc.costMicros),
+          tokensUsed: BigInt(desc.tokensUsed),
+        }),
+      };
+      break;
+
+    case "task_failed":
+      base.eventType = WorkflowEventType.task_failed;
+      base.payload = {
+        case: "taskFailed",
+        value: create(TaskFailedPayloadSchema, {
+          taskKind: TASK_KIND_MAP[desc.taskKind] ?? 0,
+          error: desc.error,
+          attemptNumber: desc.attemptNumber,
+          willRetry: desc.willRetry,
+          durationMs: BigInt(desc.durationMs),
+        }),
+      };
+      break;
+
+    case "task_skipped":
+      base.eventType = WorkflowEventType.task_skipped;
+      base.payload = {
+        case: "taskSkipped",
+        value: create(TaskSkippedPayloadSchema, {
+          taskKind: TASK_KIND_MAP[desc.taskKind] ?? 0,
+          reason: desc.reason,
+        }),
+      };
+      break;
+
+    case "task_retrying":
+      base.eventType = WorkflowEventType.task_retrying;
+      base.payload = {
+        case: "taskRetrying",
+        value: create(TaskRetryingPayloadSchema, {
+          failedAttempt: desc.failedAttempt,
+          nextAttempt: desc.nextAttempt,
+          delayMs: BigInt(desc.delayMs),
+        }),
+      };
+      break;
+
+    case "approval_requested":
+      base.eventType = WorkflowEventType.approval_requested;
+      base.payload = {
+        case: "approvalRequested",
+        value: create(ApprovalRequestedPayloadSchema, {
+          prompt: desc.prompt,
+          approvers: [...desc.approvers],
+          timeoutSeconds: desc.timeoutSeconds,
+          outcomes: desc.outcomes.map((o) =>
+            create(HumanInputOutcomeInfoSchema, { name: o.name, label: o.label }),
+          ),
+          formSchema: desc.formSchema
+            ? (desc.formSchema as JsonObject)
+            : undefined,
+        }),
+      };
+      break;
+
+    case "approval_resolved":
+      base.eventType = WorkflowEventType.approval_resolved;
+      base.payload = {
+        case: "approvalResolved",
+        value: create(ApprovalResolvedPayloadSchema, {
+          resolvedBy: desc.resolvedBy,
+          comment: desc.comment,
+          waitDurationMs: BigInt(desc.waitDurationMs),
+        }),
+      };
+      break;
+
+    case "agent_call_started":
+      base.eventType = WorkflowEventType.agent_call_started;
+      base.payload = {
+        case: "agentCallStarted",
+        value: create(AgentCallStartedPayloadSchema, {
+          childExecutionId: desc.childExecutionId,
+          agentSlug: desc.agentSlug,
+          messageSummary: desc.messageSummary,
+        }),
+      };
+      break;
+
+    case "agent_call_progress":
+      base.eventType = WorkflowEventType.agent_call_progress;
+      base.payload = {
+        case: "agentCallProgress",
+        value: create(AgentCallProgressPayloadSchema, {
+          childExecutionId: desc.childExecutionId,
+          agentPhase: desc.agentPhase as AgentExecutionPhase,
+          currentToolName: desc.currentToolName,
+          tokensConsumed: BigInt(desc.tokensConsumed),
+          messagesCount: desc.messagesCount,
+          toolCallsCount: desc.toolCallsCount,
+        }),
+      };
+      break;
+
+    case "agent_call_completed":
+      base.eventType = WorkflowEventType.agent_call_completed;
+      base.payload = {
+        case: "agentCallCompleted",
+        value: create(AgentCallCompletedPayloadSchema, {
+          childExecutionId: desc.childExecutionId,
+          durationMs: BigInt(desc.durationMs),
+          tokensConsumed: BigInt(desc.tokensConsumed),
+          costMicros: BigInt(desc.costMicros),
+          error: desc.error,
+        }),
+      };
+      break;
+
+    case "artifact_created":
+      base.eventType = WorkflowEventType.artifact_created;
+      base.payload = {
+        case: "artifactCreated",
+        value: create(ArtifactCreatedPayloadSchema, {
+          artifactId: desc.artifactId,
+          displayName: desc.displayName,
+          contentType: desc.contentType,
+          sizeBytes: BigInt(desc.sizeBytes),
+        }),
+      };
+      break;
+  }
+
+  return base;
+}
+
+export async function emitWorkflowEvents(
+  executionId: string,
+  events: WorkflowEventDescriptor[],
+  taskStatuses?: TaskStatusEntry[],
+): Promise<void> {
+  if (!executionId || events.length === 0) return;
+
+  try {
+    const client = buildClient();
+    const protoEvents = events.map(toProtoEvent);
+
+    const protoTasks = (taskStatuses ?? []).map(ts =>
+      create(WorkflowTaskSchema, {
+        taskId: ts.taskId ?? "",
+        taskName: ts.taskName,
+        taskType: TASK_KIND_TO_TYPE_MAP[ts.taskKind] ?? WorkflowTaskType.WORKFLOW_TASK_TYPE_UNSPECIFIED,
+        status: TASK_STATUS_MAP[ts.status],
+        startedAt: ts.startedAt ?? "",
+        completedAt: ts.completedAt ?? "",
+        error: ts.error ?? "",
+        input: toJsonObject(ts.input),
+        output: toJsonObject(ts.output),
+        metadata: toJsonObject(ts.metadata),
+        costMicros: BigInt(ts.costMicros ?? 0),
+        inputTokens: BigInt(ts.inputTokens ?? 0),
+        outputTokens: BigInt(ts.outputTokens ?? 0),
+      }),
+    );
+
+    const startedEvent = events.find(e => e.type === "execution_started");
+    const completedEvent = events.find(e => e.type === "execution_completed");
+    const failedEvent = events.find(e => e.type === "execution_failed");
+
+    const statusFields: Record<string, unknown> = { tasks: protoTasks };
+
+    if (startedEvent) {
+      statusFields.phase = ExecutionPhase.EXECUTION_IN_PROGRESS;
+      statusFields.startedAt = startedEvent.occurredAt;
+    }
+    if (completedEvent && completedEvent.type === "execution_completed") {
+      statusFields.phase = ExecutionPhase.EXECUTION_COMPLETED;
+      statusFields.completedAt = completedEvent.occurredAt;
+      statusFields.totalCostMicros = BigInt(completedEvent.totalCostMicros);
+      statusFields.totalInputTokens = BigInt(completedEvent.totalInputTokens ?? 0);
+      statusFields.totalOutputTokens = BigInt(completedEvent.totalOutputTokens ?? 0);
+    }
+    if (failedEvent && failedEvent.type === "execution_failed") {
+      statusFields.phase = ExecutionPhase.EXECUTION_FAILED;
+      statusFields.completedAt = failedEvent.occurredAt;
+      statusFields.error = failedEvent.error;
+    }
+
+    const input = create(WorkflowExecutionUpdateStatusInputSchema, {
+      executionId,
+      status: create(WorkflowExecutionStatusSchema, statusFields as Parameters<typeof create>[1]),
+      events: protoEvents,
+    });
+    await client.workflowExecutionCommand.updateStatus(input);
+  } catch (err) {
+    console.error(
+      `Failed to emit ${events.length} workflow event(s) for ${executionId}:`,
+      err,
+    );
+  }
+}
+
+const PROTO_STATUS_TO_STRING: Record<number, string> = {
+  [WorkflowTaskStatus.WORKFLOW_TASK_IN_PROGRESS]: "started",
+  [WorkflowTaskStatus.WORKFLOW_TASK_COMPLETED]: "completed",
+  [WorkflowTaskStatus.WORKFLOW_TASK_FAILED]: "failed",
+  [WorkflowTaskStatus.WORKFLOW_TASK_SKIPPED]: "skipped",
+  [WorkflowTaskStatus.WORKFLOW_TASK_WAITING_APPROVAL]: "waiting_approval",
+};
+
+/**
+ * Converts a proto Struct field to a plain JS object safe for Temporal
+ * serialization. Returns undefined when the field is not set.
+ */
+function structToPlain(value: JsonObject | undefined): unknown {
+  if (value === undefined) return undefined;
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Loads recovery context data from the previous run's status snapshot.
+ *
+ * Fetches the WorkflowExecution and extracts status.tasks[] as plain
+ * serializable objects. The workflow sandbox builds the RecoveryContext
+ * from this data via buildRecoveryContext().
+ *
+ * Unlike emitWorkflowEvents (best-effort), this activity propagates
+ * errors — recovery context loading is required for correctness.
+ */
+export async function loadRecoveryContext(executionId: string): Promise<RecoveryTaskData[]> {
+  const client = buildClient();
+  const execution = await client.getWorkflowExecution(executionId);
+  const tasks = execution.status?.tasks ?? [];
+
+  return tasks.map(t => ({
+    taskName: t.taskName,
+    status: PROTO_STATUS_TO_STRING[t.status] ?? "unknown",
+    output: structToPlain(t.output),
+  }));
+}
+
+export function createWorkflowEventActivities() {
+  return {
+    EmitWorkflowEvents: emitWorkflowEvents,
+    ResetEventSequence: initSequenceFromEventLog,
+    LoadRecoveryContext: loadRecoveryContext,
+  };
+}

package/src/bootstrap.ts

@@ -0,0 +1,173 @@
+/**
+ * Runner self-bootstrap for embedded runners.
+ *
+ * A cloud embedder's contract should be one endpoint plus one token. From that
+ * the runner needs two things it should not have to know or hold ahead of time:
+ * the Temporal frontend coordinates to poll for work, and (on cloud) a minted
+ * iss=stigmer access token for its Cursor-proxy traffic. This module resolves
+ * both at boot from a single control-plane call:
+ *
+ *   1. Explicit address wins. If TEMPORAL_SERVICE_ADDRESS (or the equivalent
+ *      option) is set, use it verbatim — preserves local dev and any caller that
+ *      already passes coordinates. Note: this branch does NOT call the control
+ *      plane, so no runner token is minted; pinning the address against cloud
+ *      means the runner keeps using its existing proxy token. Production desktop
+ *      does not pin the address, so this is a dev-only edge.
+ *   2. Otherwise discover. With only a token + backend endpoint, ask the control
+ *      plane (getRunnerBootstrapConfig). The token presence is the trigger: a
+ *      desktop runs MODE=local with a token + proxy, and must still discover the
+ *      cloud Temporal it cannot be expected to hardcode. The same response
+ *      carries the minted runner token (when the server mints one).
+ *   3. Otherwise localhost. A tokenless local runner (OSS, no auth) falls back
+ *      to the standard local Temporal.
+ *
+ * Two distinct failure semantics: the Temporal coordinates are load-bearing, so
+ * discovery failure throws — there is no silent localhost fallback once we have
+ * committed to discovery, because in a cloud deployment a wrong address fails
+ * later in a far more confusing way. The runner token is best-effort: a response
+ * that omits it is normal (OSS, or no signing key) and never throws — the runner
+ * just keeps its existing token.
+ */
+
+// StigmerClient is intentionally NOT statically imported here. It transitively
+// pulls in @connectrpc/connect-node, which does `import * as http2 from
+// "node:http2"` and snapshots the http2 ESM facade on first import. The Cursor
+// SDK HTTP/2 auth interceptor (http2-interceptor.ts) patches `http2.connect`
+// via require() and only propagates to that facade if it runs BEFORE the
+// snapshot. A static import here would drag connect-node into the runner's
+// pre-install module graph (this module is statically imported by runner.ts /
+// runner-manager.ts), freezing the facade to the unpatched connect and silently
+// breaking BiDi auth. Loading the client dynamically keeps connect-node out of
+// the pre-install graph, consistent with the runner's dynamic-import-for-order
+// convention. See assertHttp2ConnectPatched() for the boot-time guard.
+import type { RunnerBootstrapConfig } from "./client/stigmer-client.js";
+
+const LOCAL_TEMPORAL_ADDRESS = "localhost:7233";
+const DEFAULT_TEMPORAL_NAMESPACE = "default";
+
+export interface ResolveTemporalOptions {
+  /** Explicit Temporal address from env/options. When non-empty it always wins. */
+  readonly explicitAddress?: string | null;
+  /** Explicit Temporal namespace, applied alongside an explicit/local address. */
+  readonly explicitNamespace?: string | null;
+  /** Auth token. Its presence (with no explicit address) triggers discovery. */
+  readonly token?: string | null;
+  /** Stigmer backend endpoint the runner authenticates against for discovery. */
+  readonly stigmerEndpoint: string;
+}
+
+/**
+ * A minimal discovery client seam, so the resolver can be unit-tested without a
+ * live control plane. Defaults to a real {@link StigmerClient}.
+ *
+ * Async because the default factory loads StigmerClient via dynamic import to
+ * keep @connectrpc/connect-node out of the pre-install module graph (see the
+ * note on the omitted static import at the top of this file).
+ */
+export type BootstrapClientFactory = (
+  endpoint: string,
+  token: string,
+) => Promise<{ getRunnerBootstrapConfig(): Promise<RunnerBootstrapConfig> }>;
+
+const defaultClientFactory: BootstrapClientFactory = async (endpoint, token) => {
+  const { StigmerClient } = await import("./client/stigmer-client.js");
+  return new StigmerClient({ endpoint, token });
+};
+
+export async function resolveRunnerBootstrap(
+  options: ResolveTemporalOptions,
+  clientFactory: BootstrapClientFactory = defaultClientFactory,
+): Promise<RunnerBootstrapConfig> {
+  const explicit = options.explicitAddress?.trim();
+  const namespace = options.explicitNamespace?.trim() || DEFAULT_TEMPORAL_NAMESPACE;
+
+  if (explicit) {
+    return { temporalAddress: explicit, temporalNamespace: namespace };
+  }
+
+  const token = options.token?.trim();
+  if (!token) {
+    return {
+      temporalAddress: LOCAL_TEMPORAL_ADDRESS,
+      temporalNamespace: namespace,
+    };
+  }
+
+  let discovered: RunnerBootstrapConfig;
+  try {
+    const client = await clientFactory(options.stigmerEndpoint, token);
+    discovered = await client.getRunnerBootstrapConfig();
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `Failed to discover Temporal coordinates from ${options.stigmerEndpoint}: ${reason}. ` +
+        "Set TEMPORAL_SERVICE_ADDRESS explicitly, or upgrade the Stigmer server to one that " +
+        "supports runner bootstrap (getRunnerBootstrapConfig).",
+    );
+  }
+
+  if (!discovered.temporalAddress?.trim()) {
+    throw new Error(
+      `Runner bootstrap from ${options.stigmerEndpoint} returned an empty Temporal address. ` +
+        "Set TEMPORAL_SERVICE_ADDRESS explicitly or check the server's runner-bootstrap configuration.",
+    );
+  }
+
+  return {
+    temporalAddress: discovered.temporalAddress.trim(),
+    temporalNamespace: discovered.temporalNamespace?.trim() || DEFAULT_TEMPORAL_NAMESPACE,
+    // Best-effort: pass the minted token through when present. Absence is normal
+    // (OSS / no signing key) and is handled by the runner, not treated as fatal.
+    runnerAccessToken: discovered.runnerAccessToken,
+    runnerAccessTokenExpiresInSeconds: discovered.runnerAccessTokenExpiresInSeconds,
+  };
+}
+
+/** A freshly minted runner proxy token and its remaining lifetime. */
+export interface RefreshedRunnerToken {
+  token: string;
+  expiresInSeconds?: number;
+}
+
+/**
+ * Re-mint the runner's proxy token from the control plane (best-effort).
+ *
+ * A long-lived embedded runner holds a minted iss=stigmer token with a TTL and
+ * must refresh it before expiry. Unlike {@link resolveRunnerBootstrap}, this:
+ *
+ *   - ignores the Temporal coordinates — they are resolved once at boot and do
+ *     not change for the life of the runner;
+ *   - never throws — a transient failure should trigger a retry, not crash a
+ *     running runner;
+ *   - authenticates with the caller's current control-plane token, which the
+ *     host keeps fresh independently, so re-minting works even after the
+ *     previous proxy token has fully expired (the chicken-and-egg a self-signed
+ *     refresh would hit).
+ *
+ * Returns undefined when there is no token to authenticate with, the server
+ * mints no token, or the call fails — the caller retries.
+ */
+export async function refreshRunnerAccessToken(
+  options: { token: string | null; stigmerEndpoint: string },
+  clientFactory: BootstrapClientFactory = defaultClientFactory,
+): Promise<RefreshedRunnerToken | undefined> {
+  const token = options.token?.trim();
+  if (!token) {
+    return undefined;
+  }
+  try {
+    const client = await clientFactory(options.stigmerEndpoint, token);
+    const config = await client.getRunnerBootstrapConfig();
+    if (!config.runnerAccessToken) {
+      return undefined;
+    }
+    return {
+      token: config.runnerAccessToken,
+      expiresInSeconds: config.runnerAccessTokenExpiresInSeconds,
+    };
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    console.warn(`[runner] Failed to refresh runner access token: ${reason}`);
+    return undefined;
+  }
+}