@stigmer/runner 3.0.1

package/src/activities/discover-mcp-server.ts

@@ -0,0 +1,411 @@
+/**
+ * DiscoverMcpServerCapabilities Temporal activity — connects to an MCP server,
+ * enumerates its tools and resource templates, and returns a serializable
+ * result for the connect workflow.
+ *
+ * Part of the `stigmer/mcp-server/connect` workflow: runs as step 1 before
+ * ClassifyToolApprovals. The activity hydrates the MCP server spec via gRPC,
+ * resolves environment variables from a pre-created ExecutionContext, and
+ * connects using MultiServerMCPClient for transport management.
+ *
+ * Security: Temporal input carries only IDs (mcp_server_id,
+ * execution_context_id) — no secret values ever appear in workflow history.
+ * The activity resolves secrets from the backend-created ExecutionContext.
+ *
+ * Activity contract:
+ *   Name:   "DiscoverMcpServerCapabilities"
+ *   Input:  DiscoverMcpServerInput
+ *   Output: DiscoverMcpServerOutput
+ */
+
+import { createHash } from "node:crypto";
+import { MultiServerMCPClient } from "@langchain/mcp-adapters";
+import { activityStarted, activityFinished } from "../idle-watchdog.js";
+import { StigmerClient } from "../client/stigmer-client.js";
+import { mcpServerToResolved } from "../shared/mcp-resolver.js";
+import { toMcpClientConfig } from "../shared/mcp-manager.js";
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import type { Config } from "../config.js";
+
+const SESSION_INIT_TIMEOUT_MS = 270_000;
+
+const PLATFORM_INJECTABLE_MAP: Record<string, string> = {
+  STIGMER_SERVER_ADDRESS: "STIGMER_MCP_PUBLIC_ENDPOINT",
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface DiscoverMcpServerInput {
+  mcpServerId: string;
+  executionContextId?: string | null;
+  invokerIdentityAccountId?: string | null;
+}
+
+export interface DiscoveredToolResult {
+  name: string;
+  description: string;
+  inputSchema?: Record<string, unknown> | null;
+}
+
+export interface DiscoveredResourceTemplateResult {
+  uriTemplate: string;
+  name: string;
+  description: string;
+  mimeType: string;
+}
+
+export interface DiscoverMcpServerOutput {
+  tools: DiscoveredToolResult[];
+  resourceTemplates: DiscoveredResourceTemplateResult[];
+  previousToolsFingerprint: string;
+  previousToolApprovals: ToolApprovalDict[];
+  newToolsFingerprint: string;
+}
+
+export interface ToolApprovalDict {
+  toolName: string;
+  requiresApproval: boolean;
+  message: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tools Fingerprint (pure, deterministic, safe in workflow code)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function toolsFingerprint(tools: DiscoveredToolResult[]): string {
+  if (tools.length === 0) return "";
+
+  const canonical = tools
+    .map((t) => ({
+      name: t.name,
+      description: t.description,
+      input_schema: t.inputSchema ?? null,
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  return createHash("sha256")
+    .update(JSON.stringify(canonical))
+    .digest("hex");
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Previous State Extraction
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface PreviousState {
+  fingerprint: string;
+  toolApprovals: ToolApprovalDict[];
+}
+
+export function extractPreviousState(mcpServer: McpServer): PreviousState {
+  const status = mcpServer.status;
+  if (!status) return { fingerprint: "", toolApprovals: [] };
+
+  const caps = status.discoveredCapabilities;
+  const prevTools: DiscoveredToolResult[] = [];
+  if (caps) {
+    for (const tool of caps.tools) {
+      let schema: Record<string, unknown> | null = null;
+      if (tool.inputSchema) {
+        schema = structToPlainObject(tool.inputSchema);
+      }
+      prevTools.push({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: schema,
+      });
+    }
+  }
+
+  const toolApprovals: ToolApprovalDict[] = [];
+  for (const approval of status.toolApprovals) {
+    toolApprovals.push({
+      toolName: approval.toolName,
+      requiresApproval: true,
+      message: approval.message,
+    });
+  }
+
+  return {
+    fingerprint: toolsFingerprint(prevTools),
+    toolApprovals,
+  };
+}
+
+/**
+ * Convert a protobuf Struct to a plain JS object. The @bufbuild/protobuf
+ * Struct type uses `fields` as a Record<string, Value>; we need a plain
+ * JSON-compatible object for fingerprinting and serialization.
+ */
+function structToPlainObject(struct: unknown): Record<string, unknown> | null {
+  if (!struct || typeof struct !== "object") return null;
+  try {
+    return JSON.parse(JSON.stringify(struct));
+  } catch {
+    return null;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Platform Env Injection
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function injectPlatformEnv(
+  declaredEnvKeys: Set<string>,
+  envVars: Record<string, string>,
+): Record<string, string> {
+  if (declaredEnvKeys.size === 0) return envVars;
+
+  let result: Record<string, string> | undefined;
+
+  for (const [targetKey, sourceKey] of Object.entries(PLATFORM_INJECTABLE_MAP)) {
+    if (!declaredEnvKeys.has(targetKey)) continue;
+    const value = process.env[sourceKey];
+    if (!value) continue;
+
+    if (!result) result = { ...envVars };
+    if (targetKey in result && result[targetKey] !== value) {
+      console.info(
+        `Platform env var '${targetKey}' overrides value from ExecutionContext ` +
+        `(platform infra vars are authoritative)`,
+      );
+    }
+    result[targetKey] = value;
+  }
+
+  return result ?? envVars;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Core Discovery Logic (no Temporal coupling)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface DiscoverDeps {
+  stigmerClient: StigmerClient;
+}
+
+export async function discoverMcpServer(
+  input: DiscoverMcpServerInput,
+  deps: DiscoverDeps,
+): Promise<DiscoverMcpServerOutput> {
+  const { mcpServerId, executionContextId } = input;
+  const { stigmerClient } = deps;
+
+  console.log(
+    `[DiscoverMcpServer] Discovery started for mcp_server_id=${mcpServerId}`,
+  );
+
+  const mcpServer = await stigmerClient.getMcpServer(mcpServerId);
+  if (!mcpServer?.spec) {
+    throw new Error(
+      `MCP server '${mcpServerId}' not found or has no spec`,
+    );
+  }
+
+  const slug = mcpServer.metadata?.slug || mcpServerId;
+  const previousState = extractPreviousState(mcpServer);
+
+  const envVars = await resolveEnvVarsForDiscovery(
+    stigmerClient,
+    executionContextId ?? null,
+  );
+
+  const declaredEnvKeys = mcpServer.spec.env
+    ? new Set(Object.keys(mcpServer.spec.env))
+    : new Set<string>();
+  const finalEnv = injectPlatformEnv(declaredEnvKeys, envVars);
+
+  const resolved = mcpServerToResolved(mcpServer, slug, finalEnv);
+  if (!resolved) {
+    throw new Error(
+      `MCP server '${slug}' has no valid server type configured ` +
+      `(must specify either 'stdio' or 'http' in the spec)`,
+    );
+  }
+
+  const connectionConfig = toMcpClientConfig([resolved]);
+  const { tools, resourceTemplates } = await connectAndDiscover(
+    slug,
+    connectionConfig,
+  );
+
+  const newFp = toolsFingerprint(tools);
+
+  console.log(
+    `[DiscoverMcpServer] Discovery complete for '${slug}': ` +
+    `${tools.length} tool(s), ${resourceTemplates.length} resource template(s)`,
+  );
+
+  return {
+    tools,
+    resourceTemplates,
+    previousToolsFingerprint: previousState.fingerprint,
+    previousToolApprovals: previousState.toolApprovals,
+    newToolsFingerprint: newFp,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Env Var Resolution
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function resolveEnvVarsForDiscovery(
+  client: StigmerClient,
+  executionContextId: string | null,
+): Promise<Record<string, string>> {
+  if (!executionContextId) return {};
+
+  try {
+    const execCtx = await client.getExecutionContextByExecutionId(
+      executionContextId,
+    );
+
+    if (!execCtx?.spec?.data || Object.keys(execCtx.spec.data).length === 0) {
+      console.warn(
+        `[DiscoverMcpServer] ExecutionContext '${executionContextId}' not found ` +
+        `or empty — MCP server may not require environment variables`,
+      );
+      return {};
+    }
+
+    const envVars: Record<string, string> = {};
+    for (const [key, execValue] of Object.entries(execCtx.spec.data)) {
+      envVars[key] = execValue.value;
+    }
+
+    console.log(
+      `[DiscoverMcpServer] Resolved ${Object.keys(envVars).length} env var(s) ` +
+      `from ExecutionContext '${executionContextId}'`,
+    );
+    return envVars;
+  } catch (err) {
+    console.warn(
+      `[DiscoverMcpServer] Failed to resolve ExecutionContext '${executionContextId}': ` +
+      `${err instanceof Error ? err.message : err}`,
+    );
+    return {};
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MCP Connection + Enumeration
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function connectAndDiscover(
+  slug: string,
+  connectionConfig: ReturnType<typeof toMcpClientConfig>,
+): Promise<{
+  tools: DiscoveredToolResult[];
+  resourceTemplates: DiscoveredResourceTemplateResult[];
+}> {
+  const client = new MultiServerMCPClient(connectionConfig);
+  const tools: DiscoveredToolResult[] = [];
+  const resourceTemplates: DiscoveredResourceTemplateResult[] = [];
+
+  try {
+    await withTimeout(SESSION_INIT_TIMEOUT_MS, slug, async () => {
+      await client.initializeConnections();
+
+      const mcpClient = await client.getClient(slug);
+      if (!mcpClient) {
+        throw new Error(
+          `Failed to get MCP client for server '${slug}' after initialization`,
+        );
+      }
+
+      const toolsResult = await mcpClient.listTools();
+      for (const tool of toolsResult.tools) {
+        tools.push({
+          name: tool.name,
+          description: tool.description ?? "",
+          inputSchema: tool.inputSchema
+            ? (tool.inputSchema as Record<string, unknown>)
+            : null,
+        });
+      }
+
+      try {
+        const capabilities = mcpClient.getServerCapabilities();
+        if (capabilities?.resources) {
+          const templatesResult = await mcpClient.listResourceTemplates();
+          for (const tpl of templatesResult.resourceTemplates) {
+            resourceTemplates.push({
+              uriTemplate: tpl.uriTemplate,
+              name: tpl.name,
+              description: tpl.description ?? "",
+              mimeType: tpl.mimeType ?? "",
+            });
+          }
+        }
+      } catch (err) {
+        console.warn(
+          `[DiscoverMcpServer] Server '${slug}' does not support ` +
+          `resource templates: ${err instanceof Error ? err.message : err}`,
+        );
+      }
+    });
+  } finally {
+    await client.close().catch((err: unknown) => {
+      console.warn(
+        `[DiscoverMcpServer] Error closing MCP client for '${slug}': ` +
+        `${err instanceof Error ? err.message : err}`,
+      );
+    });
+  }
+
+  return { tools, resourceTemplates };
+}
+
+async function withTimeout<T>(
+  ms: number,
+  serverSlug: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(
+        `MCP server '${serverSlug}' did not respond within ` +
+        `${Math.round(ms / 1000)}s. If this server requires compilation or ` +
+        `package installation on first run (e.g. go run, npx), the cold ` +
+        `start may have exceeded the discovery timeout.`,
+      ));
+    }, ms);
+
+    fn()
+      .then((result) => {
+        clearTimeout(timer);
+        resolve(result);
+      })
+      .catch((err) => {
+        clearTimeout(timer);
+        reject(err);
+      });
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Temporal Activity Factory
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function createDiscoverMcpServerActivities(config: Config) {
+  const stigmerClient = new StigmerClient({
+    endpoint: config.stigmerBackendEndpoint,
+    token: config.stigmerToken,
+    tokenRef: config.stigmerTokenRef,
+  });
+
+  return {
+    DiscoverMcpServerCapabilities: async (
+      input: DiscoverMcpServerInput,
+    ): Promise<DiscoverMcpServerOutput> => {
+      activityStarted();
+      try {
+        return await discoverMcpServer(input, { stigmerClient });
+      } finally {
+        activityFinished();
+      }
+    },
+  };
+}

package/src/activities/emit-event.ts

@@ -0,0 +1,195 @@
+/**
+ * Emit event action — constructs a CloudEvents 1.0 envelope and
+ * optionally delivers it to external targets.
+ *
+ * Delivery targets are optional. When absent, the envelope is returned
+ * as task output only (backward compatible). When present, the envelope
+ * is delivered to each target. Delivery is non-fatal: failures are
+ * collected in the result but do not fail the task.
+ *
+ * Supported delivery targets:
+ * - webhook: HTTP POST with Content-Type: application/cloudevents+json
+ * - signal:  Temporal signal to another running workflow's listen task
+ *
+ * CloudEvents spec: https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md
+ */
+
+import { randomUUID } from "node:crypto";
+import { loadConfig } from "../config.js";
+import { resolveRuntimePlaceholders } from "../workflow-engine/resolve.js";
+
+export interface WebhookDeliveryTarget {
+  readonly url: string;
+  readonly headers?: Readonly<Record<string, string>>;
+}
+
+export interface SignalDeliveryTarget {
+  readonly workflow_id: string;
+  readonly signal_name: string;
+}
+
+export type DeliveryTarget =
+  | { readonly webhook: WebhookDeliveryTarget }
+  | { readonly signal: SignalDeliveryTarget };
+
+export interface EmitEventConfig {
+  readonly event: {
+    readonly type: string;
+    readonly source?: string;
+    readonly subject?: string;
+    readonly data?: Record<string, unknown>;
+  };
+  readonly delivery?: readonly DeliveryTarget[];
+}
+
+export interface DeliveryError {
+  readonly target: string;
+  readonly error: string;
+}
+
+export interface EmitEventResult {
+  readonly envelope: Record<string, unknown>;
+  readonly delivery_errors?: readonly DeliveryError[];
+}
+
+const WEBHOOK_TIMEOUT_MS = 30_000;
+
+function buildEnvelope(
+  config: EmitEventConfig,
+  executionId: string,
+): Record<string, unknown> {
+  const source = config.event.source || `/workflows/executions/${executionId}`;
+
+  const envelope: Record<string, unknown> = {
+    id: randomUUID(),
+    specversion: "1.0",
+    type: config.event.type,
+    source,
+    time: new Date().toISOString(),
+    datacontenttype: "application/json",
+  };
+
+  if (config.event.subject) {
+    envelope.subject = config.event.subject;
+  }
+
+  if (config.event.data && Object.keys(config.event.data).length > 0) {
+    envelope.data = config.event.data;
+  }
+
+  return envelope;
+}
+
+async function deliverWebhook(
+  envelope: Record<string, unknown>,
+  target: WebhookDeliveryTarget,
+  runtimeEnv: Record<string, unknown>,
+): Promise<DeliveryError | null> {
+  const resolvedHeaders: Record<string, string> = {
+    "Content-Type": "application/cloudevents+json",
+  };
+
+  if (target.headers) {
+    for (const [k, v] of Object.entries(target.headers)) {
+      resolvedHeaders[k] = resolveRuntimePlaceholders(v, runtimeEnv);
+    }
+  }
+
+  try {
+    const response = await fetch(target.url, {
+      method: "POST",
+      headers: resolvedHeaders,
+      body: JSON.stringify(envelope),
+      signal: AbortSignal.timeout(WEBHOOK_TIMEOUT_MS),
+    });
+
+    if (response.status >= 400) {
+      return {
+        target: `webhook:${target.url}`,
+        error: `HTTP ${response.status}`,
+      };
+    }
+
+    return null;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      target: `webhook:${target.url}`,
+      error: message,
+    };
+  }
+}
+
+async function deliverSignal(
+  envelope: Record<string, unknown>,
+  target: SignalDeliveryTarget,
+): Promise<DeliveryError | null> {
+  try {
+    const { Connection, Client } = await import("@temporalio/client");
+
+    // Resolve Temporal coordinates through the central config layer rather than
+    // reading env directly: signal delivery must dial the SAME cluster/namespace
+    // the worker connected with. config.ts is the single source of truth for the
+    // canonical TEMPORAL_SERVICE_ADDRESS / TEMPORAL_NAMESPACE resolution — reading
+    // env here would diverge (and previously dialed localhost via a stale name).
+    const config = loadConfig();
+    const temporalAddress = config.temporalAddress;
+    const temporalNamespace = config.temporalNamespace;
+
+    const connection = await Connection.connect({ address: temporalAddress });
+    const client = new Client({ connection, namespace: temporalNamespace });
+
+    const handle = client.workflow.getHandle(target.workflow_id);
+    await handle.signal(target.signal_name, envelope);
+
+    return null;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      target: `signal:${target.workflow_id}/${target.signal_name}`,
+      error: message,
+    };
+  }
+}
+
+export async function emitEventAction(
+  config: EmitEventConfig,
+  executionId: string,
+  runtimeEnv?: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  if (!config.event) {
+    throw new Error("emit_event: 'event' field is required");
+  }
+  if (!config.event.type) {
+    throw new Error("emit_event: 'event.type' field is required");
+  }
+
+  const envelope = buildEnvelope(config, executionId);
+
+  if (!config.delivery || config.delivery.length === 0) {
+    return envelope;
+  }
+
+  const errors: DeliveryError[] = [];
+  const env = runtimeEnv ?? {};
+
+  for (const target of config.delivery) {
+    let err: DeliveryError | null = null;
+
+    if ("webhook" in target) {
+      err = await deliverWebhook(envelope, target.webhook, env);
+    } else if ("signal" in target) {
+      err = await deliverSignal(envelope, target.signal);
+    }
+
+    if (err) {
+      errors.push(err);
+    }
+  }
+
+  if (errors.length > 0) {
+    return { ...envelope, delivery_errors: errors };
+  }
+
+  return envelope;
+}

package/src/activities/ensure-thread.ts

@@ -0,0 +1,45 @@
+/**
+ * EnsureThread Temporal activity — resolves a LangGraph thread ID for an
+ * agent execution.
+ *
+ * Called by the Java/Go InvokeAgentExecutionWorkflow as Step 1 of the
+ * native (deep-agent) harness flow, before ExecuteDeepAgent. The returned
+ * thread ID keys the LangGraph checkpointer for conversation continuity.
+ *
+ * Thread ID conventions (load-bearing for proxy authorization):
+ *   - Session-based:  "thread-{sessionId}"   — deterministic, no DB call
+ *   - Ephemeral:      "ephemeral-{agentId}-{8hex}" — single-use
+ *
+ * The "thread-{sessionId}" prefix is parsed by ProxyAuthorizationService
+ * (stigmer-cloud) to extract the session ID for checkpoint access control.
+ * Changing the format requires a coordinated update.
+ *
+ * Activity contract:
+ *   Name:   "EnsureThread"
+ *   Input:  (sessionId: string, agentId: string)
+ *   Output: string (thread ID)
+ */
+
+import { randomUUID } from "node:crypto";
+import { activityStarted, activityFinished } from "../idle-watchdog.js";
+
+export function createEnsureThreadActivities() {
+  return {
+    EnsureThread: async (sessionId: string, agentId: string): Promise<string> => {
+      activityStarted();
+      try {
+        if (sessionId) {
+          const threadId = `thread-${sessionId}`;
+          console.log(`[EnsureThread] Session-based thread: ${threadId}`);
+          return threadId;
+        }
+
+        const threadId = `ephemeral-${agentId}-${randomUUID().replace(/-/g, "").slice(0, 8)}`;
+        console.log(`[EnsureThread] Ephemeral thread: ${threadId}`);
+        return threadId;
+      } finally {
+        activityFinished();
+      }
+    },
+  };
+}

package/src/activities/evaluate-expressions.ts

@@ -0,0 +1,47 @@
+/**
+ * EvaluateExpressions Temporal local activity — evaluates batched jq
+ * expressions using jq-wasm.
+ *
+ * Runs OUTSIDE the Temporal workflow sandbox (local activity on the
+ * worker) because jq-wasm's Emscripten loader requires Node.js
+ * built-ins (fs, path, crypto) that are blocked in the deterministic
+ * V8 isolate.
+ *
+ * Local activity results are recorded in workflow history, providing
+ * deterministic replay for all expression evaluation — including
+ * non-deterministic operations like uuid generation.
+ *
+ * Activity contract:
+ *   Name:   "EvaluateExpressions"
+ *   Input:  (expressions: Record<string, string>, input: unknown, stateVars: Record<string, unknown>)
+ *   Output: Record<string, unknown>
+ */
+
+import { ApplicationFailure } from "@temporalio/activity";
+
+import { evaluateExpressionBatch } from "../workflow-engine/expression.js";
+
+export function createEvaluateExpressionsActivities() {
+  return {
+    EvaluateExpressions: async (
+      expressions: Record<string, string>,
+      input: unknown,
+      stateVars: Record<string, unknown>,
+    ): Promise<Record<string, unknown>> => {
+      try {
+        return await evaluateExpressionBatch(expressions, input, stateVars);
+      } catch (err) {
+        // jq expression evaluation is deterministic and side-effect free:
+        // a failure (parse/compile/syntax/runtime error) is a property of the
+        // expression + input and will never succeed on retry. Surface it as a
+        // non-retryable failure so the workflow reaches a terminal FAILED phase
+        // instead of being retried forever by the local-activity retry policy.
+        const message = err instanceof Error ? err.message : String(err);
+        throw ApplicationFailure.nonRetryable(
+          `Expression evaluation failed: ${message}`,
+          "EXPRESSION_EVALUATION_FAILED",
+        );
+      }
+    },
+  };
+}