@stigmer/runner 3.0.1

package/src/client/stigmer-client.ts

@@ -0,0 +1,339 @@
+/**
+ * Connect-RPC client for communicating with the Stigmer server.
+ *
+ * Provides typed wrappers around generated service stubs for RPCs the
+ * runner needs: execution queries, status updates, session reads/writes,
+ * and blueprint resolution (agent, skill, MCP server).
+ *
+ * Shared by all activities in the unified runner.
+ */
+
+import { createClient, type Client, type Transport } from "@connectrpc/connect";
+import { createGrpcTransport } from "@connectrpc/connect-node";
+import { AgentExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/command_pb";
+import { AgentExecutionQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/query_pb";
+import { ExecutionContextQueryController } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/query_pb";
+import { SessionCommandController } from "@stigmer/protos/ai/stigmer/agentic/session/v1/command_pb";
+import { SessionQueryController } from "@stigmer/protos/ai/stigmer/agentic/session/v1/query_pb";
+import { AgentQueryController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/query_pb";
+import { AgentInstanceQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/query_pb";
+import { McpServerQueryController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/query_pb";
+import { McpServerCommandController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/command_pb";
+import { ArtifactCommandController } from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/command_pb";
+import type { Artifact } from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/api_pb";
+import type { CreateArtifactInput } from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/io_pb";
+import { SkillQueryController } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/query_pb";
+import { BillingCommandController } from "@stigmer/protos/ai/stigmer/billing/v1/command_pb";
+import type { RecordLlmCallUsageInput, RecordLlmCallUsageResponse } from "@stigmer/protos/ai/stigmer/billing/v1/io_pb";
+import type { AgentExecution, AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { ExecutionContext } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/api_pb";
+import { ExecutionContextExecutionIdInputSchema } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/io_pb";
+import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import type { AgentInstance } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
+import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import type { GetArtifactResponse } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
+import { create } from "@bufbuild/protobuf";
+import { ConnectInputSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
+import { ExecutionValueSchema } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/spec_pb";
+import { AgentExecutionUpdateStatusInputSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import type { UpdateStatusResponse } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { WorkflowExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/command_pb";
+import { WorkflowExecutionQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/query_pb";
+import type { WorkflowExecution, WorkflowExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { WorkflowExecutionUpdateStatusInputSchema, GetEventLogRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import { WorkflowQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/query_pb";
+import type { Workflow } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { WorkflowInstanceQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/query_pb";
+import type { WorkflowInstance } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/api_pb";
+import { PlatformQueryController } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
+import { assertCreateRequirements, assertReferenceRequirements } from "./server-contracts.js";
+
+/**
+ * Everything an embedded runner needs to bootstrap: Temporal coordinates plus
+ * its own minted access token.
+ *
+ * The Temporal coordinates are always present. The access token is optional: the
+ * server only mints one when it has a Cursor proxy to authenticate against
+ * (cloud) and a signing key configured — OSS and misconfigured servers omit it,
+ * and the runner keeps using its existing token in that case.
+ */
+export interface RunnerBootstrapConfig {
+  temporalAddress: string;
+  temporalNamespace: string;
+  /** Minted iss=stigmer token for the runner's proxy traffic; absent when not minted. */
+  runnerAccessToken?: string;
+  /** Lifetime of {@link runnerAccessToken} in seconds; absent/0 when no token. */
+  runnerAccessTokenExpiresInSeconds?: number;
+}
+
+/**
+ * A shared mutable token reference. When provided, the interceptor
+ * reads from this on every request, enabling token updates to
+ * propagate to all clients sharing the same ref.
+ */
+export interface TokenRef {
+  current: string | null;
+}
+
+export interface StigmerClientOptions {
+  endpoint: string;
+  token: string | null;
+  tokenRef?: TokenRef;
+}
+
+export class StigmerClient {
+  readonly transport: Transport;
+  private currentToken: string | null;
+  private readonly executionQuery: Client<typeof AgentExecutionQueryController>;
+  private readonly executionCommand: Client<typeof AgentExecutionCommandController>;
+  private readonly executionContextQuery: Client<typeof ExecutionContextQueryController>;
+  private readonly sessionQuery: Client<typeof SessionQueryController>;
+  private readonly sessionCommand: Client<typeof SessionCommandController>;
+  private readonly agentQuery: Client<typeof AgentQueryController>;
+  private readonly agentInstanceQuery: Client<typeof AgentInstanceQueryController>;
+  private readonly mcpServerQuery: Client<typeof McpServerQueryController>;
+  private readonly mcpServerCommand: Client<typeof McpServerCommandController>;
+  private readonly skillQuery: Client<typeof SkillQueryController>;
+  private readonly billingCommand: Client<typeof BillingCommandController>;
+  private readonly artifactCommand: Client<typeof ArtifactCommandController>;
+  readonly workflowExecutionCommand: Client<typeof WorkflowExecutionCommandController>;
+  private readonly workflowExecutionQuery: Client<typeof WorkflowExecutionQueryController>;
+  private readonly workflowQuery: Client<typeof WorkflowQueryController>;
+  private readonly workflowInstanceQuery: Client<typeof WorkflowInstanceQueryController>;
+  private readonly platformQuery: Client<typeof PlatformQueryController>;
+
+  private readonly tokenRef: TokenRef | null;
+
+  constructor(options: StigmerClientOptions) {
+    this.currentToken = options.token;
+    this.tokenRef = options.tokenRef ?? null;
+    this.transport = createGrpcTransport({
+      baseUrl: options.endpoint,
+      interceptors: [
+        (next) => async (req) => {
+          const token = this.tokenRef?.current ?? this.currentToken;
+          if (token) {
+            req.header.set("authorization", `Bearer ${token}`);
+          }
+          return next(req);
+        },
+      ],
+    });
+
+    this.executionQuery = createClient(AgentExecutionQueryController, this.transport);
+    this.executionCommand = createClient(AgentExecutionCommandController, this.transport);
+    this.executionContextQuery = createClient(ExecutionContextQueryController, this.transport);
+    this.sessionQuery = createClient(SessionQueryController, this.transport);
+    this.sessionCommand = createClient(SessionCommandController, this.transport);
+    this.agentQuery = createClient(AgentQueryController, this.transport);
+    this.agentInstanceQuery = createClient(AgentInstanceQueryController, this.transport);
+    this.mcpServerQuery = createClient(McpServerQueryController, this.transport);
+    this.mcpServerCommand = createClient(McpServerCommandController, this.transport);
+    this.skillQuery = createClient(SkillQueryController, this.transport);
+    this.billingCommand = createClient(BillingCommandController, this.transport);
+    this.artifactCommand = createClient(ArtifactCommandController, this.transport);
+    this.workflowExecutionCommand = createClient(WorkflowExecutionCommandController, this.transport);
+    this.workflowExecutionQuery = createClient(WorkflowExecutionQueryController, this.transport);
+    this.workflowQuery = createClient(WorkflowQueryController, this.transport);
+    this.workflowInstanceQuery = createClient(WorkflowInstanceQueryController, this.transport);
+    this.platformQuery = createClient(PlatformQueryController, this.transport);
+  }
+
+  /**
+   * Fetch this runner's bootstrap config from the control plane.
+   *
+   * Lets an embedded runner self-bootstrap from a token alone: the control
+   * plane returns the Temporal frontend address and namespace for the
+   * environment the token belongs to (so integrators never hardcode
+   * infrastructure addresses) and, on cloud, a minted iss=stigmer access token
+   * the runner uses for its proxy traffic. The token fields are absent when the
+   * server does not mint one (OSS, or no signing key configured).
+   */
+  async getRunnerBootstrapConfig(): Promise<RunnerBootstrapConfig> {
+    const res = await this.platformQuery.getRunnerBootstrapConfig({});
+    return {
+      temporalAddress: res.temporalAddress,
+      temporalNamespace: res.temporalNamespace,
+      // Empty proto string/0 means "not minted" — normalize to undefined so
+      // callers branch on presence rather than emptiness.
+      runnerAccessToken: res.runnerAccessToken || undefined,
+      runnerAccessTokenExpiresInSeconds:
+        res.runnerAccessTokenExpiresInSeconds || undefined,
+    };
+  }
+
+  async getExecution(executionId: string): Promise<AgentExecution> {
+    return this.executionQuery.get({ value: executionId });
+  }
+
+  async updateStatus(
+    executionId: string,
+    status: AgentExecutionStatus,
+  ): Promise<UpdateStatusResponse> {
+    const input = create(AgentExecutionUpdateStatusInputSchema, {
+      executionId,
+      status,
+    });
+    return this.executionCommand.updateStatus(input);
+  }
+
+  async getExecutionContextByExecutionId(executionId: string): Promise<ExecutionContext> {
+    return this.executionContextQuery.getByExecutionId(
+      create(ExecutionContextExecutionIdInputSchema, { executionId }),
+    );
+  }
+
+  async getSession(sessionId: string): Promise<Session> {
+    return this.sessionQuery.get({ value: sessionId });
+  }
+
+  async updateSession(session: Session): Promise<Session> {
+    return this.sessionCommand.update(session);
+  }
+
+  async getAgent(agentId: string): Promise<Agent> {
+    return this.agentQuery.get({ value: agentId });
+  }
+
+  async getAgentInstance(instanceId: string): Promise<AgentInstance> {
+    return this.agentInstanceQuery.get({ value: instanceId });
+  }
+
+  async getMcpServer(serverId: string): Promise<McpServer> {
+    return this.mcpServerQuery.get({ value: serverId });
+  }
+
+  async getMcpServerByReference(ref: ApiResourceReference): Promise<McpServer> {
+    return this.mcpServerQuery.getByReference(ref);
+  }
+
+  async connectMcpServer(
+    mcpServerId: string,
+    org: string,
+    runtimeEnv?: Record<string, { value: string; isSecret: boolean }>,
+  ): Promise<McpServer> {
+    const input = create(ConnectInputSchema, {
+      mcpServerId,
+      org,
+    });
+    if (runtimeEnv) {
+      for (const [key, entry] of Object.entries(runtimeEnv)) {
+        input.runtimeEnv[key] = create(ExecutionValueSchema, {
+          value: entry.value,
+          isSecret: entry.isSecret,
+        });
+      }
+    }
+    return this.mcpServerCommand.connect(input);
+  }
+
+  async getSkill(skillId: string): Promise<Skill> {
+    return this.skillQuery.get({ value: skillId });
+  }
+
+  async getSkillByReference(ref: ApiResourceReference): Promise<Skill> {
+    return this.skillQuery.getByReference(ref);
+  }
+
+  async getSkillArtifact(artifactStorageKey: string): Promise<GetArtifactResponse> {
+    return this.skillQuery.getArtifact({ artifactStorageKey });
+  }
+
+  async createArtifact(input: CreateArtifactInput): Promise<Artifact> {
+    return this.artifactCommand.create(input);
+  }
+
+  async recordLlmCallUsage(input: RecordLlmCallUsageInput): Promise<RecordLlmCallUsageResponse> {
+    return this.billingCommand.recordLlmCallUsage(input);
+  }
+
+  async getAgentByReference(ref: ApiResourceReference): Promise<Agent> {
+    assertReferenceRequirements(ref, "Agent", "getAgentByReference");
+    return this.agentQuery.getByReference(ref);
+  }
+
+  async createSession(session: Session): Promise<Session> {
+    assertCreateRequirements(session, "Session", "createSession");
+    return this.sessionCommand.create(session);
+  }
+
+  async applySession(session: Session): Promise<Session> {
+    assertCreateRequirements(session, "Session", "applySession");
+    return this.sessionCommand.apply(session);
+  }
+
+  async createAgentExecution(execution: AgentExecution): Promise<AgentExecution> {
+    assertCreateRequirements(execution, "AgentExecution", "createAgentExecution");
+    return this.executionCommand.create(execution);
+  }
+
+  async updateWorkflowExecutionStatus(
+    executionId: string,
+    status: WorkflowExecutionStatus,
+    options?: { updatePendingApprovals?: boolean },
+  ): Promise<WorkflowExecution> {
+    const input = create(WorkflowExecutionUpdateStatusInputSchema, {
+      executionId,
+      status,
+      updatePendingApprovals: options?.updatePendingApprovals ?? false,
+    });
+    return this.workflowExecutionCommand.updateStatus(input);
+  }
+
+  async getWorkflowExecution(executionId: string): Promise<WorkflowExecution> {
+    return this.workflowExecutionQuery.get({ value: executionId });
+  }
+
+  /**
+   * Return the highest persisted event sequence_number for a workflow execution.
+   *
+   * Paginates through getEventLog with the maximum page size (500) and
+   * follows the cursor until has_more is false. The final page's
+   * latest_sequence is the global high-water mark.
+   *
+   * Returns 0 when no events have been persisted yet (new execution).
+   */
+  async getEventLogHighWaterMark(executionId: string): Promise<bigint> {
+    let afterSequence = BigInt(0);
+    let highWaterMark = BigInt(0);
+
+    for (;;) {
+      const resp = await this.workflowExecutionQuery.getEventLog(
+        create(GetEventLogRequestSchema, {
+          executionId,
+          afterSequence,
+          pageSize: 500,
+        }),
+      );
+
+      if (resp.latestSequence > highWaterMark) {
+        highWaterMark = resp.latestSequence;
+      }
+
+      if (!resp.hasMore) {
+        return highWaterMark;
+      }
+
+      afterSequence = resp.latestSequence;
+    }
+  }
+
+  async getWorkflow(workflowId: string): Promise<Workflow> {
+    return this.workflowQuery.get({ value: workflowId });
+  }
+
+  async getWorkflowVersion(workflowId: string, versionHash: string) {
+    return this.workflowQuery.getVersion({ workflowId, versionHash });
+  }
+
+  async getWorkflowInstance(instanceId: string): Promise<WorkflowInstance> {
+    return this.workflowInstanceQuery.get({ value: instanceId });
+  }
+
+  updateToken(token: string | null): void {
+    this.currentToken = token;
+  }
+}

package/src/config.ts

@@ -0,0 +1,185 @@
+/**
+ * Environment-based configuration for the unified runner service.
+ *
+ * Supports both ExecuteCursor and ExecuteDeepAgent activities from a single
+ * process. All values come from environment variables set by the CLI daemon,
+ * Kubernetes pod spec, or Daytona sandbox launcher.
+ *
+ * Credential modes:
+ *
+ * 1. Direct mode (local / OSS):
+ *    - CURSOR_API_KEY provided directly by the user (for Cursor harness).
+ *    - STIGMER_TOKEN is optional (local stigmer-server has no auth).
+ *    - STIGMER_PROXY_ENDPOINT is NOT set.
+ *
+ * 2. Proxy mode (cloud / managed runners):
+ *    - STIGMER_PROXY_ENDPOINT + STIGMER_TOKEN are required.
+ *    - CURSOR_API_KEY is NOT required — the proxy injects it.
+ *    - The fetch interceptor rewrites outbound Cursor SDK requests.
+ *
+ * Workspace isolation:
+ *
+ * WORKSPACE_ROOT_DIR must always resolve to a directory that is NOT the
+ * runner's own app directory. Falling back to process.cwd() would expose
+ * runner internals to agents. The fallback creates an isolated directory.
+ */
+
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir, tmpdir } from "node:os";
+
+export interface Config {
+  readonly taskQueue: string;
+  readonly temporalAddress: string;
+  readonly temporalNamespace: string;
+  readonly stigmerBackendEndpoint: string;
+  readonly stigmerToken: string | null;
+  /**
+   * Bearer credential for the Cursor SDK's Connect RPC transport.
+   *
+   * - Direct mode: the real Cursor API key (authenticates with Cursor directly).
+   * - Proxy mode: the STIGMER_TOKEN JWT (authenticates with our BiDi proxy,
+   *   which validates it and injects the real Cursor key upstream).
+   *
+   * Named after the CURSOR_API_KEY env var the SDK reads, though in proxy mode
+   * the credential authenticates with the proxy endpoint, not with Cursor.
+   */
+  readonly cursorApiKey: string;
+  readonly workspaceRootDir: string;
+  /**
+   * Execution location: where the agent runs and whose filesystem it sees.
+   * "local" allows local-path workspaces (host filesystem); "cloud" runs in a
+   * server-provisioned sandbox (git-only). Independent of {@link proxyEndpoint},
+   * which controls credential/artifact transport — the desktop runner executes
+   * locally yet still proxies its Cursor traffic.
+   */
+  readonly mode: "local" | "cloud";
+  readonly proxyEndpoint: string | null;
+  readonly maxConcurrentActivities: number;
+  readonly idleTimeoutSeconds: number | null;
+  readonly cloudModeEnabled: boolean;
+  readonly checkpointerType: "memory" | "http";
+  readonly checkpointerProxyEndpoint: string | null;
+  readonly primaryModel: string;
+  /** Shared mutable token reference for dynamic token updates (manager mode). */
+  readonly stigmerTokenRef?: { current: string | null };
+}
+
+export function loadConfig(): Config {
+  const mode = (process.env.MODE ?? "local") as "local" | "cloud";
+  const proxyEndpoint = process.env.STIGMER_PROXY_ENDPOINT ?? null;
+  const proxyActive = !!proxyEndpoint;
+
+  const taskQueue = process.env.STIGMER_TASK_QUEUE
+    ?? process.env.TEMPORAL_AGENT_EXECUTION_RUNNER_TASK_QUEUE
+    ?? "stigmer_runner";
+
+  // Temporal address is no longer required up front. When unset, the runner
+  // self-discovers it from the control plane during boot (see bootstrap.ts):
+  // an explicit value always wins, a token triggers discovery, and a tokenless
+  // local runner falls back to localhost. An empty string here means "resolve
+  // later" — the factory fills it in before connecting to Temporal.
+  const temporalAddress = process.env.TEMPORAL_SERVICE_ADDRESS ?? "";
+
+  const temporalNamespace = process.env.TEMPORAL_NAMESPACE ?? "default";
+
+  const stigmerBackendEndpoint = normalizeEndpoint(
+    mode === "local"
+      ? (process.env.STIGMER_BACKEND_ENDPOINT ?? "http://localhost:7234")
+      : requireEnv("STIGMER_BACKEND_ENDPOINT"),
+  );
+
+  const stigmerToken = (mode === "cloud" || proxyActive)
+    ? requireEnv("STIGMER_TOKEN")
+    : (process.env.STIGMER_TOKEN ?? null);
+
+  // In proxy mode, pass STIGMER_TOKEN as the SDK's API key. The SDK exchanges
+  // it (via REST proxy → Tomcat → Cursor) for an access token. The HTTP/2
+  // interceptor injects x-stigmer-auth for BiDi proxy authentication while
+  // the SDK's authorization header (Cursor access token) passes through to
+  // api2.cursor.sh unchanged.
+  const cursorApiKey = proxyActive
+    ? (process.env.CURSOR_API_KEY ?? stigmerToken ?? "proxy-managed")
+    : (process.env.CURSOR_API_KEY ?? "");
+
+  const workspaceRootDir = resolveWorkspaceRootDir();
+
+  const maxConcurrentActivities = parseInt(
+    process.env.TEMPORAL_MAX_CONCURRENCY ?? "5",
+    10,
+  );
+
+  const idleTimeoutRaw = process.env.STIGMER_IDLE_TIMEOUT_SECONDS;
+  const idleTimeoutSeconds = idleTimeoutRaw ? parseInt(idleTimeoutRaw, 10) : null;
+
+  const checkpointerType = (process.env.STIGMER_CHECKPOINTER_TYPE as "memory" | "http" | undefined)
+    ?? (mode === "cloud" ? "http" : "memory");
+  const checkpointerProxyEndpoint = process.env.STIGMER_CHECKPOINTER_PROXY_ENDPOINT
+    ?? proxyEndpoint;
+
+  const primaryModel = process.env.STIGMER_PRIMARY_MODEL ?? "gpt-4.1";
+
+  return {
+    taskQueue,
+    temporalAddress,
+    temporalNamespace,
+    stigmerBackendEndpoint,
+    stigmerToken,
+    cursorApiKey,
+    workspaceRootDir,
+    mode,
+    proxyEndpoint,
+    maxConcurrentActivities,
+    idleTimeoutSeconds,
+    cloudModeEnabled: process.env.STIGMER_CURSOR_CLOUD_MODE_ENABLED === "true",
+    checkpointerType,
+    checkpointerProxyEndpoint,
+    primaryModel,
+  };
+}
+
+function resolveWorkspaceRootDir(): string {
+  const explicit = process.env.WORKSPACE_ROOT_DIR;
+  if (explicit) {
+    return explicit;
+  }
+
+  console.warn(
+    "WORKSPACE_ROOT_DIR is not set — creating isolated fallback workspace. " +
+    "This likely means the runner was started outside the CLI daemon.",
+  );
+
+  const fallbackDir = safeWorkspaceFallback();
+  mkdirSync(fallbackDir, { recursive: true });
+  return fallbackDir;
+}
+
+function safeWorkspaceFallback(): string {
+  try {
+    return join(homedir(), ".stigmer", "workspaces", "runner");
+  } catch {
+    return join(tmpdir(), "stigmer-runner-workspace");
+  }
+}
+
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`Required environment variable ${name} is not set`);
+  }
+  return value;
+}
+
+/**
+ * Ensures the endpoint has an HTTP(S) scheme. Port 443 implies TLS;
+ * all other bare host:port endpoints get http://.
+ */
+function normalizeEndpoint(endpoint: string): string {
+  if (endpoint.startsWith("http://") || endpoint.startsWith("https://")) {
+    return endpoint;
+  }
+  if (endpoint.endsWith(":443")) {
+    return `https://${endpoint}`;
+  }
+  return `http://${endpoint}`;
+}

package/src/idle-watchdog.ts

@@ -0,0 +1,28 @@
+/**
+ * Activity execution tracking for the execution worker.
+ *
+ * Tracks the number of concurrently executing Temporal activities and the
+ * timestamp of the last activity event. Used by activities for diagnostics
+ * and concurrency-aware behavior.
+ */
+
+let lastActivityAt = Date.now();
+let activeCount = 0;
+
+export function activityStarted(): void {
+  activeCount++;
+  lastActivityAt = Date.now();
+}
+
+export function activityFinished(): void {
+  activeCount = Math.max(0, activeCount - 1);
+  lastActivityAt = Date.now();
+}
+
+export function getActiveCount(): number {
+  return activeCount;
+}
+
+export function getLastActivityAt(): number {
+  return lastActivityAt;
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+/**
+ * @stigmer/runner — public API.
+ *
+ * Two modes of operation:
+ *
+ * 1. Static (CLI, single-queue polling):
+ *    {@link createStigmerRunner} — one Worker, one task queue, blocks until shutdown.
+ *
+ * 2. Dynamic (desktop, multi-session):
+ *    {@link createStigmerRunnerManager} — shared Temporal connection, per-session Workers.
+ *
+ * @example Static mode
+ * ```ts
+ * import { createStigmerRunner } from '@stigmer/runner';
+ *
+ * const runner = await createStigmerRunner({
+ *   taskQueue: 'agent_execution_runner',
+ *   temporalAddress: 'localhost:7233',
+ *   stigmerEndpoint: 'http://localhost:7234',
+ * });
+ *
+ * process.on('SIGTERM', () => runner.shutdown());
+ * await runner.start();
+ * ```
+ *
+ * @example Dynamic mode
+ * ```ts
+ * import { createStigmerRunnerManager } from '@stigmer/runner';
+ *
+ * const manager = await createStigmerRunnerManager({
+ *   temporalAddress: 'localhost:7233',
+ *   stigmerEndpoint: 'http://localhost:7234',
+ * });
+ *
+ * await manager.addSession('ses_abc123');
+ * // ... later
+ * await manager.shutdown();
+ * ```
+ */
+
+export { createStigmerRunner } from "./runner.js";
+export type { StigmerRunnerOptions, StigmerRunner } from "./runner.js";
+
+export { createStigmerRunnerManager } from "./runner-manager.js";
+export type {
+  RunnerManagerOptions,
+  StigmerRunnerManager,
+} from "./runner-manager.js";

package/src/interceptors/workflow-metrics-sink.ts

@@ -0,0 +1,56 @@
+/**
+ * Worker-side implementation of the workflow metrics sink.
+ *
+ * Receives timing data pushed from within the Temporal workflow sandbox
+ * and records it using the OTel metrics registry. This is the bridge
+ * between the deterministic workflow code and the non-deterministic
+ * observability infrastructure.
+ */
+
+import type { InjectedSinks } from "@temporalio/worker";
+import type { WorkflowMetricsSinks } from "../workflows/metrics-sink.js";
+import { getInstruments } from "../otel-metrics.js";
+
+let instrumentsPromise: ReturnType<typeof getInstruments> | null = null;
+
+function ensureInstruments() {
+  if (!instrumentsPromise) {
+    instrumentsPromise = getInstruments();
+  }
+  return instrumentsPromise;
+}
+
+export function createWorkflowMetricsSinks(): InjectedSinks<WorkflowMetricsSinks> {
+  return {
+    metrics: {
+      recordTaskDuration: {
+        fn(_workflowInfo, info) {
+          ensureInstruments().then((instruments) => {
+            const attrs = {
+              "task.name": info.taskName,
+              "task.kind": info.taskKind,
+              "task.success": String(info.success),
+            };
+            instruments.workflowTaskDuration.record(info.durationMs, attrs);
+            instruments.workflowTaskCount.add(1, attrs);
+          });
+        },
+      },
+      recordExecutionStart: {
+        fn(_workflowInfo, info) {
+          ensureInstruments().then((instruments) => {
+            instruments.executionCount.add(1, { "workflow.name": info.workflowName });
+            instruments.executionActive.add(1, { "workflow.name": info.workflowName });
+          });
+        },
+      },
+      recordExecutionEnd: {
+        fn(_workflowInfo, info) {
+          ensureInstruments().then((instruments) => {
+            instruments.executionActive.add(-1, { "workflow.name": info.workflowName });
+          });
+        },
+      },
+    },
+  };
+}