@stigmer/runner 3.0.1

package/src/activities/call-http.ts

@@ -0,0 +1,185 @@
+/**
+ * CallHTTP Temporal activity — executes HTTP requests for workflow
+ * `call: http` tasks.
+ *
+ * Runs OUTSIDE the Temporal workflow sandbox. Performs network I/O
+ * using Node.js built-in `fetch()`.
+ *
+ * Error classification drives Temporal retry behavior:
+ * - 4xx / 3xx → non-retryable (client error, won't fix itself)
+ * - 5xx → retryable (server error, may recover)
+ * - Network errors → retryable (transient)
+ *
+ * Activity contract:
+ *   Name:   "CallHttp"
+ *   Input:  (config: HttpCallConfig, runtimeEnv: Record<string, unknown>)
+ *   Output: unknown (parsed response content, full response, or raw bytes)
+ */
+
+import { ApplicationFailure } from "@temporalio/activity";
+import type { HttpCallConfig, EndpointDef } from "../workflow-engine/types.js";
+import {
+  resolveObjectPlaceholders,
+} from "../workflow-engine/resolve.js";
+import { startHeartbeat } from "../shared/heartbeat.js";
+
+export interface HttpResponse {
+  readonly request: {
+    readonly method: string;
+    readonly uri: string;
+    readonly headers: Record<string, string>;
+  };
+  readonly statusCode: number;
+  readonly headers: Record<string, string>;
+  readonly content: unknown;
+}
+
+function injectBaggageHeaders(
+  headers: Record<string, string>,
+  env: Record<string, unknown>,
+): void {
+  const parts: string[] = [];
+  const execId = env["__stigmer_execution_id"];
+  const orgId = env["__stigmer_org_id"];
+  if (execId) parts.push(`stigmer.execution_id=${execId}`);
+  if (orgId) parts.push(`stigmer.org_id=${orgId}`);
+  if (parts.length > 0 && !headers["baggage"]) {
+    headers["baggage"] = parts.join(",");
+  }
+}
+
+function resolveEndpointUri(endpoint: EndpointDef): string {
+  if (typeof endpoint === "string") return endpoint;
+  return endpoint.uri;
+}
+
+function buildQueryString(query: Record<string, string>): string {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    params.append(key, value);
+  }
+  return params.toString();
+}
+
+export async function callHttpAction(
+  config: HttpCallConfig,
+  runtimeEnv: Record<string, unknown>,
+): Promise<unknown> {
+  const resolved = resolveObjectPlaceholders(config, runtimeEnv) as HttpCallConfig;
+
+  const method = resolved.method.toUpperCase();
+  let uri = resolveEndpointUri(resolved.endpoint);
+
+  if (resolved.query && Object.keys(resolved.query).length > 0) {
+    const qs = buildQueryString(resolved.query);
+    uri += (uri.includes("?") ? "&" : "?") + qs;
+  }
+
+  const headers: Record<string, string> = { ...resolved.headers };
+
+  injectBaggageHeaders(headers, runtimeEnv);
+
+  let body: string | undefined;
+  if (resolved.body !== undefined && resolved.body !== null) {
+    if (typeof resolved.body === "string") {
+      body = resolved.body;
+    } else {
+      body = JSON.stringify(resolved.body);
+      if (!headers["Content-Type"] && !headers["content-type"]) {
+        headers["Content-Type"] = "application/json";
+      }
+    }
+  }
+
+  const fetchOptions: RequestInit = {
+    method,
+    headers,
+    body,
+  };
+
+  if (resolved.redirect === "false" || resolved.redirect === false as unknown) {
+    fetchOptions.redirect = "manual";
+  }
+
+  let response: Response;
+  try {
+    response = await fetch(uri, fetchOptions);
+  } catch (err: unknown) {
+    throw new Error(
+      `HTTP ${method} ${uri} failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  const statusCode = response.status;
+
+  if (statusCode >= 300 && statusCode < 400) {
+    throw ApplicationFailure.nonRetryable(
+      `HTTP ${method} ${uri} returned redirect ${statusCode}`,
+      "HTTP_REDIRECT",
+      { statusCode },
+    );
+  }
+
+  if (statusCode >= 400 && statusCode < 500) {
+    const errorBody = await response.text().catch(() => "");
+    throw ApplicationFailure.nonRetryable(
+      `HTTP ${method} ${uri} returned ${statusCode}: ${errorBody.slice(0, 500)}`,
+      "HTTP_CLIENT_ERROR",
+      { statusCode, body: errorBody.slice(0, 2000) },
+    );
+  }
+
+  if (statusCode >= 500) {
+    const errorBody = await response.text().catch(() => "");
+    throw new Error(
+      `HTTP ${method} ${uri} returned ${statusCode}: ${errorBody.slice(0, 500)}`,
+    );
+  }
+
+  const outputMode = resolved.output ?? "content";
+
+  if (outputMode === "raw") {
+    const buffer = await response.arrayBuffer();
+    return Buffer.from(buffer).toString("base64");
+  }
+
+  const responseText = await response.text();
+  let content: unknown;
+  try {
+    content = JSON.parse(responseText);
+  } catch {
+    content = responseText;
+  }
+
+  if (outputMode === "response") {
+    const responseHeaders: Record<string, string> = {};
+    response.headers.forEach((value, key) => {
+      responseHeaders[key] = value;
+    });
+
+    return {
+      request: { method, uri, headers },
+      statusCode,
+      headers: responseHeaders,
+      content,
+    } satisfies HttpResponse;
+  }
+
+  return content;
+}
+
+export function createCallHttpActivities() {
+  return {
+    CallHttp: async (
+      config: HttpCallConfig,
+      runtimeEnv: Record<string, unknown>,
+    ): Promise<unknown> => {
+      const hb = startHeartbeat(10_000, () => ({ phase: "http_call" }));
+      try {
+        return await callHttpAction(config, runtimeEnv);
+      } finally {
+        hb.stop();
+      }
+    },
+  };
+}

package/src/activities/call-llm.ts

@@ -0,0 +1,379 @@
+/**
+ * CallLLM Temporal activity — executes LLM API calls for workflow
+ * `call: llm` tasks.
+ *
+ * Uses LangChain ChatModel with streaming for proxy metering compatibility.
+ * Supports structured output via `withStructuredOutput()` when a
+ * `response_schema` is provided.
+ *
+ * Supports two modes:
+ * 1. Proxy mode (cloud): routes through Stigmer's LLM proxy
+ * 2. Direct mode (OSS): uses API keys from environment
+ *
+ * Activity contract:
+ *   Name:   "CallLlm"
+ *   Input:  (config: LlmCallConfig, runtimeEnv: Record<string, unknown>, executionId: string)
+ *   Output: LlmCallResult
+ */
+
+import { ChatAnthropic } from "@langchain/anthropic";
+import { ChatOpenAI } from "@langchain/openai";
+import { HumanMessage, SystemMessage } from "@langchain/core/messages";
+import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
+import type { BaseMessageChunk } from "@langchain/core/messages";
+import { z } from "zod";
+import { ApplicationFailure } from "@temporalio/activity";
+import { jsonSchemaToZod } from "../shared/json-schema-to-zod.js";
+
+import {
+  inferProvider,
+  stripProviderPrefix,
+  resolveProxyBaseUrl,
+  buildProxyHeaders,
+  type LlmProvider,
+} from "../shared/llm-proxy.js";
+import { computeLlmCostMicros, ensureLoaded as ensurePricingLoaded } from "../shared/model-pricing.js";
+import { resolveToApiModelId } from "../shared/model-registry.js";
+
+export interface LlmCallConfig {
+  readonly model: string;
+  readonly prompt: string;
+  readonly system_prompt?: string;
+  readonly response_schema?: Record<string, unknown>;
+  readonly temperature?: number;
+  readonly max_tokens?: number;
+  readonly timeout?: number;
+}
+
+export interface LlmCallResult {
+  readonly input_tokens: number;
+  readonly output_tokens: number;
+  readonly result: unknown;
+  readonly model: string;
+  readonly provider: LlmProvider;
+  readonly parse_error?: string;
+}
+
+function constructModel(
+  provider: LlmProvider,
+  modelId: string,
+  config: LlmCallConfig,
+  baseUrl?: string,
+  headers?: Record<string, string>,
+): BaseChatModel {
+  if (provider === "openai") {
+    const apiKey = baseUrl
+      ? (headers?.Authorization?.replace("Bearer ", "") ?? "proxy-managed")
+      : (process.env.OPENAI_API_KEY ?? "");
+
+    return new ChatOpenAI({
+      model: modelId,
+      temperature: config.temperature ?? 0,
+      maxTokens: config.max_tokens,
+      ...(baseUrl || headers
+        ? {
+            configuration: {
+              ...(baseUrl ? { baseURL: baseUrl } : {}),
+              ...(headers ? { defaultHeaders: headers } : {}),
+            },
+          }
+        : {}),
+      apiKey,
+    });
+  }
+
+  const apiKey = baseUrl
+    ? (headers?.Authorization?.replace("Bearer ", "") ?? "proxy-managed")
+    : (process.env.ANTHROPIC_API_KEY ?? "");
+
+  return new ChatAnthropic({
+    model: modelId,
+    temperature: config.temperature ?? 0,
+    maxTokens: config.max_tokens ?? 4096,
+    ...(baseUrl || headers
+      ? {
+          clientOptions: {
+            ...(baseUrl ? { baseURL: baseUrl } : {}),
+            ...(headers ? { defaultHeaders: headers } : {}),
+          },
+        }
+      : {}),
+    apiKey,
+  });
+}
+
+/**
+ * Stream a chat model invocation and collect the response.
+ *
+ * Streaming ensures the proxy's SSE usage extractors can meter the
+ * request properly. The full response is collected from chunks.
+ */
+async function streamAndCollect(
+  model: BaseChatModel,
+  messages: (HumanMessage | SystemMessage)[],
+): Promise<{ content: string; inputTokens: number; outputTokens: number }> {
+  const stream = await model.stream(messages);
+
+  let content = "";
+  let inputTokens = 0;
+  let outputTokens = 0;
+
+  for await (const chunk of stream) {
+    const messageChunk = chunk as BaseMessageChunk;
+    if (typeof messageChunk.content === "string") {
+      content += messageChunk.content;
+    }
+
+    // Usage is split across stream chunks: Anthropic reports input_tokens in
+    // the message_start chunk and the (cumulative) output_tokens in the
+    // message_delta chunk — which also carries input_tokens: 0. Take the max
+    // per field so a later zero never clobbers an earlier non-zero count, and
+    // so cumulative output totals are preserved. (OpenAI reports both in a
+    // single final chunk, where max is equivalent.)
+    const usage = (messageChunk as unknown as { usage_metadata?: { input_tokens?: number; output_tokens?: number } }).usage_metadata;
+    if (usage) {
+      if (typeof usage.input_tokens === "number") {
+        inputTokens = Math.max(inputTokens, usage.input_tokens);
+      }
+      if (typeof usage.output_tokens === "number") {
+        outputTokens = Math.max(outputTokens, usage.output_tokens);
+      }
+    }
+  }
+
+  return { content, inputTokens, outputTokens };
+}
+
+/**
+ * Classify an LLM call error and re-throw as a Temporal ApplicationFailure
+ * with correct retryability semantics and a user-facing message.
+ *
+ * Both OpenAI and Anthropic SDKs throw typed error subclasses of APIError
+ * with a `.status` property. We duck-type on `.status` to avoid importing
+ * either SDK's error classes directly.
+ *
+ * Retryability policy:
+ *   - 4xx (except 429): nonRetryable — client/config errors won't self-heal
+ *   - 429: nonRetryable at Temporal level — the SDK already retries internally
+ *          with exponential backoff; Temporal retrying on top causes duplicates
+ *   - 5xx: retryable — transient provider outages
+ *   - Connection/timeout: retryable — transient network issues
+ *   - ZodError: nonRetryable — schema mismatch won't self-heal
+ */
+function classifyAndThrowLlmError(
+  err: unknown,
+  modelId: string,
+  provider: LlmProvider,
+): never {
+  const status = typeof (err as { status?: unknown }).status === "number"
+    ? (err as { status: number }).status
+    : undefined;
+
+  const rawMessage = err instanceof Error ? err.message : String(err);
+  const providerLabel = provider === "anthropic" ? "Anthropic" : "OpenAI";
+
+  if (err instanceof z.ZodError) {
+    throw ApplicationFailure.nonRetryable(
+      `Structured output from model "${modelId}" (${providerLabel}) did not match the expected schema. ` +
+      `Validation errors: ${err.errors.map(e => `${e.path.join(".")}: ${e.message}`).join("; ")}`,
+      "LLM_SCHEMA_VALIDATION",
+    );
+  }
+
+  if (status !== undefined) {
+    const context = `model "${modelId}" (${providerLabel})`;
+
+    switch (status) {
+      case 401:
+        throw ApplicationFailure.nonRetryable(
+          `Authentication failed for ${context}. Check that your API key is valid and not expired.`,
+          "LLM_AUTHENTICATION_ERROR",
+        );
+      case 403:
+        throw ApplicationFailure.nonRetryable(
+          `Access denied for ${context}. Verify that your API key has permission to use this model.`,
+          "LLM_PERMISSION_DENIED",
+        );
+      case 404:
+        throw ApplicationFailure.nonRetryable(
+          `Model not found: ${context}. Verify the model name is correct and available in your account.`,
+          "LLM_MODEL_NOT_FOUND",
+        );
+      case 400:
+        throw ApplicationFailure.nonRetryable(
+          `Invalid request to ${context}: ${rawMessage}`,
+          "LLM_BAD_REQUEST",
+        );
+      case 422:
+        throw ApplicationFailure.nonRetryable(
+          `Unprocessable request to ${context}: ${rawMessage}`,
+          "LLM_UNPROCESSABLE_REQUEST",
+        );
+      case 429:
+        throw ApplicationFailure.nonRetryable(
+          `Rate limit exceeded for ${context}. The provider's built-in retry was exhausted. ` +
+          `Try again later or reduce request frequency.`,
+          "LLM_RATE_LIMIT",
+        );
+      default:
+        if (status >= 500) {
+          throw new Error(
+            `${providerLabel} provider error (HTTP ${status}) for ${context}: ${rawMessage}`,
+          );
+        }
+        throw ApplicationFailure.nonRetryable(
+          `${providerLabel} API error (HTTP ${status}) for ${context}: ${rawMessage}`,
+          "LLM_API_ERROR",
+        );
+    }
+  }
+
+  const errName = err instanceof Error ? err.constructor.name : "";
+  if (errName.includes("Timeout") || errName.includes("ConnectionTimeout")) {
+    throw new Error(
+      `Connection timed out for model "${modelId}" (${providerLabel}): ${rawMessage}`,
+    );
+  }
+  if (errName.includes("Connection")) {
+    throw new Error(
+      `Connection failed for model "${modelId}" (${providerLabel}): ${rawMessage}`,
+    );
+  }
+
+  throw ApplicationFailure.nonRetryable(
+    `LLM call failed for model "${modelId}" (${providerLabel}): ${rawMessage}`,
+    "LLM_UNKNOWN_ERROR",
+  );
+}
+
+export async function callLlmAction(
+  config: LlmCallConfig,
+  runtimeEnv: Record<string, unknown>,
+  executionId: string,
+): Promise<LlmCallResult> {
+  if (!config.model) {
+    throw new Error("LLM call requires 'model' in config");
+  }
+  if (!config.prompt) {
+    throw new Error("LLM call requires 'prompt' in config");
+  }
+
+  const resolvedModel = await resolveToApiModelId(config.model);
+  const provider = inferProvider(resolvedModel);
+  const modelId = stripProviderPrefix(resolvedModel);
+  const callStart = Date.now();
+
+  await ensurePricingLoaded().catch(() => {});
+
+  const proxyEndpoint = process.env.STIGMER_PROXY_ENDPOINT;
+  const stigmerToken = process.env.STIGMER_TOKEN;
+  const proxyActive = !!(proxyEndpoint && stigmerToken);
+
+  console.log(
+    `[call-llm] model=${modelId} provider=${provider} proxy=${proxyActive} ` +
+    `structured=${!!config.response_schema} execution=${executionId}`,
+  );
+
+  let baseUrl: string | undefined;
+  let headers: Record<string, string> | undefined;
+
+  if (proxyActive) {
+    baseUrl = resolveProxyBaseUrl(proxyEndpoint!, provider);
+    headers = buildProxyHeaders(stigmerToken!, { workflowExecutionId: executionId });
+  } else if (provider === "openai") {
+    if (!process.env.OPENAI_API_KEY) {
+      throw ApplicationFailure.nonRetryable(
+        `OPENAI_API_KEY is not set and no proxy is configured. ` +
+        `Set the API key in your environment or connect to a Stigmer Cloud deployment.`,
+        "LLM_MISSING_API_KEY",
+      );
+    }
+  } else {
+    if (!process.env.ANTHROPIC_API_KEY) {
+      throw ApplicationFailure.nonRetryable(
+        `ANTHROPIC_API_KEY is not set and no proxy is configured. ` +
+        `Set the API key in your environment or connect to a Stigmer Cloud deployment.`,
+        "LLM_MISSING_API_KEY",
+      );
+    }
+  }
+
+  const model = constructModel(provider, modelId, config, baseUrl, headers);
+
+  const messages: (HumanMessage | SystemMessage)[] = [];
+  if (config.system_prompt) {
+    messages.push(new SystemMessage(config.system_prompt));
+  }
+  messages.push(new HumanMessage(config.prompt));
+
+  let result: LlmCallResult;
+
+  try {
+    if (config.response_schema) {
+      const zodSchema = jsonSchemaToZod(config.response_schema);
+      const structured = model.withStructuredOutput(zodSchema, { includeRaw: true });
+      const response = await structured.invoke(messages);
+
+      const rawUsage = (response.raw as unknown as {
+        usage_metadata?: { input_tokens?: number; output_tokens?: number };
+      }).usage_metadata;
+
+      result = {
+        input_tokens: rawUsage?.input_tokens ?? 0,
+        output_tokens: rawUsage?.output_tokens ?? 0,
+        result: response.parsed,
+        model: modelId,
+        provider,
+      };
+    } else {
+      const { content, inputTokens, outputTokens } = await streamAndCollect(model, messages);
+
+      result = {
+        input_tokens: inputTokens,
+        output_tokens: outputTokens,
+        result: content,
+        model: modelId,
+        provider,
+      };
+    }
+  } catch (err) {
+    classifyAndThrowLlmError(err, modelId, provider);
+  }
+
+  const costMicros = computeLlmCostMicros(config.model, result.input_tokens, result.output_tokens);
+  const enrichedResult = costMicros > 0
+    ? { ...result, __stigmer_cost_micros: costMicros }
+    : result;
+
+  recordLlmMetrics(Date.now() - callStart, result);
+  return enrichedResult as LlmCallResult;
+}
+
+async function recordLlmMetrics(durationMs: number, result: LlmCallResult): Promise<void> {
+  try {
+    const { getInstruments } = await import("../otel-metrics.js");
+    const mi = await getInstruments();
+    const attrs = {
+      "stigmer.llm.provider": result.provider,
+      "stigmer.llm.model": result.model,
+    };
+    mi.llmCallDuration.record(durationMs, attrs);
+    mi.llmCallCount.add(1, attrs);
+    if (result.input_tokens) mi.llmTokensInput.add(result.input_tokens, attrs);
+    if (result.output_tokens) mi.llmTokensOutput.add(result.output_tokens, attrs);
+  } catch {
+    // OTel not initialized — silently skip
+  }
+}
+
+export function createCallLlmActivities() {
+  return {
+    CallLlm: async (
+      config: LlmCallConfig,
+      runtimeEnv: Record<string, unknown>,
+      executionId: string,
+    ): Promise<LlmCallResult> => {
+      return callLlmAction(config, runtimeEnv, executionId);
+    },
+  };
+}

package/src/activities/call-transform.ts

@@ -0,0 +1,54 @@
+/**
+ * Transform action — evaluates a JQ expression against input data.
+ *
+ * Called by `call: transform` tasks in the CNCF workflow DSL. The Go
+ * converter emits:
+ *   call: transform
+ *   with:
+ *     engine: TRANSFORM_ENGINE_JQ
+ *     expression: '{full_name: (.first_name + " " + .last_name)}'
+ *     input: "${ $context.triage }"  (optional, already resolved)
+ *
+ * Currently only JQ is supported. JSONATA and TEMPLATE engines will
+ * throw a non-retryable error until implemented.
+ */
+
+import { ApplicationFailure } from "@temporalio/activity";
+import { evaluateExpression } from "../workflow-engine/expression.js";
+
+export interface TransformConfig {
+  readonly engine: string;
+  readonly expression: string;
+  readonly input?: unknown;
+}
+
+function normalizeEngine(raw: string): string {
+  return raw
+    .toUpperCase()
+    .replace(/^TRANSFORM_ENGINE_/, "");
+}
+
+export async function transformAction(
+  config: TransformConfig,
+  taskInput?: unknown,
+): Promise<unknown> {
+  if (!config.expression) {
+    throw ApplicationFailure.nonRetryable(
+      "transform: 'expression' is required",
+      "TRANSFORM_MISSING_EXPRESSION",
+    );
+  }
+
+  const engine = normalizeEngine(config.engine || "JQ");
+
+  if (engine !== "JQ") {
+    throw ApplicationFailure.nonRetryable(
+      `transform: engine '${config.engine}' is not yet supported. Only JQ is currently implemented.`,
+      "TRANSFORM_UNSUPPORTED_ENGINE",
+    );
+  }
+
+  const data = config.input !== undefined ? config.input : taskInput;
+
+  return evaluateExpression(config.expression, data, {});
+}