@stigmer/runner 3.0.1

package/src/activities/hydrate-workflow-execution.ts

@@ -0,0 +1,306 @@
+/**
+ * Temporal activity that hydrates a workflow execution from slim IDs
+ * into the fully materialized input the CNCF workflow engine expects.
+ *
+ * Bridges the gap between the Java/Go orchestrators (which pass slim
+ * orchestration coordinates via {@link HydrateInput}) and the TS
+ * workflow engine (which expects a parsed {@link ExecuteServerlessWorkflowInput}).
+ *
+ * Hydration chain:
+ *   1. Fetch WorkflowExecution → extract trigger_message
+ *   2. Resolve Workflow → extract pre-validated YAML from status
+ *   3. Fetch ExecutionContext → flatten env data
+ *   4. Parse YAML → WorkflowModel
+ *   5. Assemble ExecuteServerlessWorkflowInput
+ */
+
+import { ApplicationFailure } from "@temporalio/activity";
+import { StigmerClient } from "../client/stigmer-client.js";
+import { loadWorkflowFromYaml } from "../workflow-engine/loader.js";
+import { ValidationState } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/serverless/validation_pb";
+import type { Config } from "../config.js";
+import type { ExecuteServerlessWorkflowInput } from "../workflows/execute-serverless-workflow.js";
+
+export interface HydrateInput {
+  readonly execution_id: string;
+  readonly workflow_instance_id: string;
+  readonly workflow_id: string;
+  readonly org_id: string;
+}
+
+export function createHydrateWorkflowActivities(config: Config) {
+  const client = new StigmerClient({
+    endpoint: config.stigmerBackendEndpoint,
+    token: config.stigmerToken,
+    tokenRef: config.stigmerTokenRef,
+  });
+
+  return {
+    HydrateWorkflowExecution: (input: HydrateInput): Promise<ExecuteServerlessWorkflowInput> =>
+      hydrateWorkflowExecution(input, client),
+  };
+}
+
+/**
+ * Core hydration logic — exported separately for unit testing with
+ * a mock client (same pattern as discover-mcp-server.ts).
+ */
+export async function hydrateWorkflowExecution(
+  input: HydrateInput,
+  client: StigmerClient,
+): Promise<ExecuteServerlessWorkflowInput> {
+  const { execution_id, workflow_instance_id, workflow_id, org_id } = input;
+
+  // 1. Fetch WorkflowExecution for trigger_message and version hash
+  const workflowExecution = await fetchWorkflowExecution(client, execution_id);
+  const triggerMessage = workflowExecution.spec?.triggerMessage ?? "";
+  const versionHash = workflowExecution.status?.workflowVersionHash;
+
+  // 2. Resolve workflow ID — prefer direct workflow_id, fall back to instance lookup
+  const resolvedWorkflowId = await resolveWorkflowId(
+    client, workflow_id, workflow_instance_id,
+  );
+
+  // 3. Fetch workflow YAML — use pinned version if available, otherwise live workflow
+  const yaml = await fetchWorkflowYaml(client, resolvedWorkflowId, versionHash);
+
+  // 4. Parse YAML into WorkflowModel
+  const model = parseWorkflowYaml(yaml, resolvedWorkflowId);
+
+  // 5. Fetch ExecutionContext and flatten env
+  const env = await fetchAndFlattenEnv(client, execution_id);
+
+  // 6. Parse trigger_message as workflow_input
+  const workflow_input = parseTriggerMessage(triggerMessage);
+
+  return {
+    model,
+    workflow_input,
+    env,
+    metadata: {
+      execution_id,
+      workflow_id: resolvedWorkflowId,
+      workflow_instance_id,
+      org_id,
+    },
+  };
+}
+
+async function fetchWorkflowExecution(
+  client: StigmerClient,
+  executionId: string,
+) {
+  try {
+    return await client.getWorkflowExecution(executionId);
+  } catch (err: unknown) {
+    const code = (err as { code?: number | string })?.code;
+    if (code === 5 || code === "not_found" || code === "NOT_FOUND") {
+      throw ApplicationFailure.nonRetryable(
+        `WorkflowExecution '${executionId}' not found`,
+        "WORKFLOW_EXECUTION_NOT_FOUND",
+      );
+    }
+    throw err;
+  }
+}
+
+async function resolveWorkflowId(
+  client: StigmerClient,
+  workflowId: string,
+  workflowInstanceId: string,
+): Promise<string> {
+  if (workflowId) return workflowId;
+
+  if (!workflowInstanceId) {
+    throw ApplicationFailure.nonRetryable(
+      "Neither workflow_id nor workflow_instance_id provided — cannot resolve workflow",
+      "MISSING_WORKFLOW_REFERENCE",
+    );
+  }
+
+  try {
+    const instance = await client.getWorkflowInstance(workflowInstanceId);
+    const resolved = instance.spec?.workflowId;
+    if (!resolved) {
+      throw ApplicationFailure.nonRetryable(
+        `WorkflowInstance '${workflowInstanceId}' has no workflow_id in spec`,
+        "INVALID_WORKFLOW_INSTANCE",
+      );
+    }
+    return resolved;
+  } catch (err: unknown) {
+    if (err instanceof ApplicationFailure) throw err;
+    const code = (err as { code?: number | string })?.code;
+    if (code === 5 || code === "not_found" || code === "NOT_FOUND") {
+      throw ApplicationFailure.nonRetryable(
+        `WorkflowInstance '${workflowInstanceId}' not found`,
+        "WORKFLOW_INSTANCE_NOT_FOUND",
+      );
+    }
+    throw err;
+  }
+}
+
+/**
+ * Fetches the CNCF YAML for a workflow, using version pinning when available.
+ *
+ * Resolution strategy:
+ * 1. If versionHash is provided, fetch the specific version entry's YAML
+ * 2. If version fetch fails or versionHash is absent, fall back to live workflow
+ *
+ * This ensures backward compatibility with pre-versioning executions while
+ * providing correctness for versioned executions.
+ */
+async function fetchWorkflowYaml(
+  client: StigmerClient,
+  workflowId: string,
+  versionHash: string | undefined,
+): Promise<string> {
+  // Path 1: Versioned execution — fetch YAML from the pinned version entry
+  if (versionHash) {
+    try {
+      const versionEntry = await client.getWorkflowVersion(workflowId, versionHash);
+      if (versionEntry?.validatedYaml) {
+        console.log(
+          `[hydrate] Resolved workflow YAML from pinned version: hash=${versionHash.slice(0, 12)}...`,
+        );
+        return versionEntry.validatedYaml;
+      }
+    } catch (err: unknown) {
+      // Version entry not found — fall through to live workflow fetch.
+      // This handles the edge case of data migration (execution created after
+      // versioning enabled, but audit entry not yet backfilled).
+      console.warn(
+        `[hydrate] Failed to fetch workflow version ${versionHash.slice(0, 12)}... ` +
+        `— falling back to live workflow fetch`,
+        err,
+      );
+    }
+  }
+
+  // Path 2: Legacy execution or version fetch failed — use live workflow
+  return fetchAndValidateWorkflowYamlLive(client, workflowId);
+}
+
+async function fetchAndValidateWorkflowYamlLive(
+  client: StigmerClient,
+  workflowId: string,
+): Promise<string> {
+  let workflow;
+  try {
+    workflow = await client.getWorkflow(workflowId);
+  } catch (err: unknown) {
+    const code = (err as { code?: number | string })?.code;
+    if (code === 5 || code === "not_found" || code === "NOT_FOUND") {
+      throw ApplicationFailure.nonRetryable(
+        `Workflow '${workflowId}' not found`,
+        "WORKFLOW_NOT_FOUND",
+      );
+    }
+    throw err;
+  }
+
+  const validation = workflow.status?.serverlessWorkflowValidation;
+  if (!validation) {
+    throw ApplicationFailure.nonRetryable(
+      `Workflow '${workflowId}' has no serverless_workflow_validation in status — ` +
+      `the workflow may not have been validated yet`,
+      "MISSING_VALIDATION",
+    );
+  }
+
+  switch (validation.state) {
+    case ValidationState.VALID:
+      break;
+    case ValidationState.PENDING:
+      throw ApplicationFailure.retryable(
+        `Workflow '${workflowId}' validation is still in progress — retrying`,
+        "VALIDATION_PENDING",
+      );
+    case ValidationState.INVALID:
+      throw ApplicationFailure.nonRetryable(
+        `Workflow '${workflowId}' validation failed: ${validation.errors.join("; ")}`,
+        "VALIDATION_INVALID",
+      );
+    case ValidationState.FAILED:
+      throw ApplicationFailure.nonRetryable(
+        `Workflow '${workflowId}' validation encountered a system error — ` +
+        `retry validation or contact support`,
+        "VALIDATION_FAILED",
+      );
+    default:
+      throw ApplicationFailure.nonRetryable(
+        `Workflow '${workflowId}' has unexpected validation state: ${validation.state}`,
+        "VALIDATION_UNKNOWN_STATE",
+      );
+  }
+
+  const yaml = validation.yaml;
+  if (!yaml) {
+    throw ApplicationFailure.nonRetryable(
+      `Workflow '${workflowId}' has VALID validation state but empty YAML — ` +
+      `the workflow status may not be fully populated (known OSS gap: ` +
+      `PopulateServerlessValidation step is not implemented in the Go server)`,
+      "YAML_EMPTY",
+    );
+  }
+
+  return yaml;
+}
+
+function parseWorkflowYaml(yaml: string, workflowId: string) {
+  try {
+    return loadWorkflowFromYaml(yaml);
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw ApplicationFailure.nonRetryable(
+      `Failed to parse CNCF Serverless Workflow YAML for workflow '${workflowId}': ${message}`,
+      "YAML_PARSE_ERROR",
+    );
+  }
+}
+
+async function fetchAndFlattenEnv(
+  client: StigmerClient,
+  executionId: string,
+): Promise<Record<string, unknown>> {
+  let execCtx;
+  try {
+    execCtx = await client.getExecutionContextByExecutionId(executionId);
+  } catch (err: unknown) {
+    // ConnectError uses numeric Code.NotFound (5); match the pattern
+    // from execute-cursor/env-resolver.ts.
+    const code = (err as { code?: number | string })?.code;
+    if (code === 5 || code === "not_found" || code === "NOT_FOUND") {
+      console.log(
+        `[hydrate] No ExecutionContext found for execution ${executionId} — ` +
+        `proceeding with empty environment`,
+      );
+      return {};
+    }
+    throw err;
+  }
+
+  const env: Record<string, unknown> = {};
+  const data = execCtx.spec?.data;
+  if (data) {
+    for (const [key, execValue] of Object.entries(data)) {
+      env[key] = execValue.value;
+    }
+  }
+
+  console.log(
+    `[hydrate] Resolved environment: env_count=${Object.keys(env).length}`,
+  );
+
+  return env;
+}
+
+function parseTriggerMessage(triggerMessage: string): unknown {
+  if (!triggerMessage) return null;
+  try {
+    return JSON.parse(triggerMessage);
+  } catch {
+    return null;
+  }
+}

package/src/activities/notification.ts

@@ -0,0 +1,71 @@
+/**
+ * Notification Temporal activity — sends fire-and-forget notifications
+ * through channel providers (webhook, etc.).
+ *
+ * Resolves JIT placeholders in body, subject, recipients, and metadata
+ * values before dispatching to the provider. Delivery is non-fatal:
+ * errors produce a result with delivered=false rather than failing
+ * the activity.
+ */
+
+import { getProvider, type NotificationResult } from "../notification/index.js";
+import { resolveObjectPlaceholders } from "../workflow-engine/resolve.js";
+
+export interface NotificationConfig {
+  readonly channel: string;
+  readonly recipients: readonly string[];
+  readonly subject?: string;
+  readonly body: string;
+  readonly template?: string;
+  readonly metadata?: Readonly<Record<string, string>>;
+}
+
+function resolveStringPlaceholder(
+  value: string,
+  env: Record<string, unknown>,
+): string {
+  const resolved = resolveObjectPlaceholders({ __v: value }, env) as Record<string, unknown>;
+  return String(resolved.__v ?? value);
+}
+
+export async function notificationAction(
+  config: NotificationConfig,
+  runtimeEnv: Record<string, unknown>,
+): Promise<NotificationResult> {
+  if (!config.channel) {
+    throw new Error("notification: 'channel' field is required");
+  }
+  if (!config.body) {
+    throw new Error("notification: 'body' field is required");
+  }
+  if (!config.recipients || config.recipients.length === 0) {
+    throw new Error("notification: at least one recipient is required");
+  }
+
+  const resolvedBody = resolveStringPlaceholder(config.body, runtimeEnv);
+  const resolvedSubject = config.subject
+    ? resolveStringPlaceholder(config.subject, runtimeEnv)
+    : "";
+
+  const resolvedRecipients = config.recipients.map(
+    r => resolveStringPlaceholder(r, runtimeEnv),
+  );
+
+  const resolvedMetadata: Record<string, string> = {};
+  if (config.metadata) {
+    for (const [k, v] of Object.entries(config.metadata)) {
+      resolvedMetadata[k] = resolveStringPlaceholder(v, runtimeEnv);
+    }
+  }
+
+  const provider = getProvider(config.channel);
+
+  return provider.send({
+    channel: config.channel,
+    recipients: resolvedRecipients,
+    subject: resolvedSubject,
+    body: resolvedBody,
+    template: config.template,
+    metadata: resolvedMetadata,
+  });
+}

package/src/activities/promote-task-output.ts

@@ -0,0 +1,126 @@
+/**
+ * Activity: Promote large task outputs to the Artifact store (T07).
+ *
+ * When a task's serialized output exceeds the promotion threshold (256KB),
+ * this activity calls ArtifactCommandController.create() to persist the
+ * content as a first-class Artifact resource, then replaces the inline
+ * output with an artifact reference.
+ *
+ * This runs as a Temporal LOCAL activity (short-lived, in-process I/O)
+ * because the gRPC call to the Stigmer server is fast and the data is
+ * already in memory.
+ *
+ * Called from the workflow sandbox via proxyLocalActivities.
+ */
+
+import { StigmerClient } from "../client/stigmer-client.js";
+import { loadConfig } from "../config.js";
+import { create } from "@bufbuild/protobuf";
+import {
+  CreateArtifactInputSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/io_pb";
+import {
+  ArtifactSpecSchema,
+  ArtifactSourceSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/spec_pb";
+
+const PROMOTION_THRESHOLD_BYTES = 256 * 1024; // 256 KB
+
+export interface PromoteTaskOutputResult {
+  /** The output to use (original if small, artifact reference if promoted). */
+  output: unknown;
+  /** Artifact IDs created during promotion (empty if no promotion). */
+  artifactIds: string[];
+  /** Event descriptors for artifact_created events (empty if no promotion). */
+  artifactCreatedEvents: ArtifactCreatedEventDescriptor[];
+}
+
+export interface ArtifactCreatedEventDescriptor {
+  type: "artifact_created";
+  artifactId: string;
+  displayName: string;
+  contentType: string;
+  sizeBytes: number;
+  occurredAt: string;
+}
+
+let cachedClient: StigmerClient | null = null;
+
+function getClient(): StigmerClient {
+  if (!cachedClient) {
+    const config = loadConfig();
+    cachedClient = new StigmerClient({
+      endpoint: config.stigmerBackendEndpoint,
+      token: config.stigmerToken,
+    });
+  }
+  return cachedClient;
+}
+
+export function createPromoteTaskOutputActivities() {
+  return {
+    /**
+     * Check if a task output should be promoted to an artifact. If the
+     * serialized JSON exceeds the threshold, create an artifact via gRPC
+     * and return a reference.
+     */
+    async PromoteTaskOutput(
+      taskOutput: unknown,
+      workflowExecutionId: string,
+      taskName: string,
+    ): Promise<PromoteTaskOutputResult> {
+      if (taskOutput === undefined || taskOutput === null) {
+        return { output: taskOutput, artifactIds: [], artifactCreatedEvents: [] };
+      }
+
+      let serialized: string;
+      try {
+        serialized = JSON.stringify(taskOutput);
+      } catch {
+        return { output: taskOutput, artifactIds: [], artifactCreatedEvents: [] };
+      }
+
+      const byteLength = Buffer.byteLength(serialized, "utf-8");
+      if (byteLength < PROMOTION_THRESHOLD_BYTES) {
+        return { output: taskOutput, artifactIds: [], artifactCreatedEvents: [] };
+      }
+
+      const displayName = `${taskName} — output.json`;
+      const contentType = "application/json";
+      const contentBytes = Buffer.from(serialized, "utf-8");
+
+      const input = create(CreateArtifactInputSchema, {
+        spec: create(ArtifactSpecSchema, {
+          contentType,
+          displayName,
+          source: create(ArtifactSourceSchema, {
+            workflowExecutionId,
+            taskName,
+          }),
+        }),
+        content: new Uint8Array(contentBytes),
+      });
+
+      const artifact = await getClient().createArtifact(input);
+      const artifactId = artifact.metadata?.id ?? "";
+
+      return {
+        output: {
+          _artifact_ref: artifactId,
+          display_name: displayName,
+          content_type: contentType,
+          size_bytes: byteLength,
+        },
+        artifactIds: [artifactId],
+        artifactCreatedEvents: [{
+          type: "artifact_created" as const,
+          artifactId,
+          displayName,
+          contentType,
+          sizeBytes: byteLength,
+          occurredAt: new Date().toISOString(),
+        }],
+      };
+    },
+  };
+}

package/src/activities/run-command.ts

@@ -0,0 +1,148 @@
+/**
+ * Run command activities — executes scripts and shell commands.
+ *
+ * Two activity functions:
+ * - RunScript: writes inline code to a temp file, executes via node/python
+ * - RunShell: executes a shell command directly
+ *
+ * Both resolve runtime placeholders (JIT secrets) before execution
+ * and capture stdout as the activity result.
+ */
+
+import { execFile, exec } from "node:child_process";
+import { writeFile, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { ApplicationFailure } from "@temporalio/activity";
+import type { RunCommandConfig } from "../workflow-engine/types.js";
+import { startHeartbeat } from "../shared/heartbeat.js";
+
+const execFileAsync = promisify(execFile);
+const execAsync = promisify(exec);
+
+export function createRunCommandActivities() {
+  return {
+    async RunScript(config: RunCommandConfig): Promise<unknown> {
+      const hb = startHeartbeat(10_000, () => ({ phase: "running_script" }));
+      try {
+        return await runScriptImpl(config);
+      } finally {
+        hb.stop();
+      }
+    },
+    async RunShell(config: RunCommandConfig): Promise<unknown> {
+      const hb = startHeartbeat(10_000, () => ({ phase: "running_shell" }));
+      try {
+        return await runShellImpl(config);
+      } finally {
+        hb.stop();
+      }
+    },
+  };
+}
+
+async function runScriptImpl(config: RunCommandConfig): Promise<unknown> {
+  if (config.mode !== "script") {
+    throw ApplicationFailure.nonRetryable("RunScript called with non-script config");
+  }
+
+  const language = config.language!;
+  const code = config.code!;
+  const env = buildEnv(config.environment);
+
+  const ext = language === "js" ? ".js" : ".py";
+  const interpreter = language === "js" ? "node" : "python3";
+
+  let tempDir: string | undefined;
+  try {
+    tempDir = await mkdtemp(join(tmpdir(), "stigmer-run-"));
+    const scriptPath = join(tempDir, `script${ext}`);
+    await writeFile(scriptPath, code, { mode: 0o600 });
+
+    const args = buildArgsList(config.arguments);
+    const { stdout } = await execFileAsync(interpreter, [scriptPath, ...args], {
+      env,
+      timeout: 300_000,
+      maxBuffer: 10 * 1024 * 1024,
+    });
+
+    return stdout.trim();
+  } catch (err: unknown) {
+    if (isExecError(err)) {
+      throw ApplicationFailure.nonRetryable(
+        `Script execution failed (exit code ${err.code})`,
+        "SCRIPT_EXECUTION_FAILED",
+        { stderr: err.stderr, stdout: err.stdout, code: err.code },
+      );
+    }
+    throw err;
+  } finally {
+    if (tempDir) {
+      await rm(tempDir, { recursive: true, force: true }).catch(() => {});
+    }
+  }
+}
+
+async function runShellImpl(config: RunCommandConfig): Promise<unknown> {
+  if (config.mode !== "shell") {
+    throw ApplicationFailure.nonRetryable("RunShell called with non-shell config");
+  }
+
+  const command = config.command!;
+  const args = buildArgsList(config.arguments);
+  const fullCommand = args.length > 0
+    ? `${command} ${args.join(" ")}`
+    : command;
+  const env = buildEnv(config.environment);
+
+  try {
+    const { stdout } = await execAsync(fullCommand, {
+      env,
+      timeout: 300_000,
+      maxBuffer: 10 * 1024 * 1024,
+    });
+
+    return stdout.trim();
+  } catch (err: unknown) {
+    if (isExecError(err)) {
+      throw ApplicationFailure.nonRetryable(
+        `Shell command failed (exit code ${err.code})`,
+        "SHELL_EXECUTION_FAILED",
+        { stderr: err.stderr, stdout: err.stdout, code: err.code },
+      );
+    }
+    throw err;
+  }
+}
+
+function buildEnv(
+  taskEnv?: Record<string, string>,
+): Record<string, string | undefined> {
+  const base = { ...process.env };
+  if (taskEnv) {
+    for (const [k, v] of Object.entries(taskEnv)) {
+      base[k] = v;
+    }
+  }
+  return base;
+}
+
+function buildArgsList(args: unknown): string[] {
+  if (!args) return [];
+  if (Array.isArray(args)) return args.map(String);
+  if (typeof args === "object" && args !== null) {
+    return Object.values(args).map(String);
+  }
+  return [String(args)];
+}
+
+interface ExecError {
+  code?: number;
+  stderr?: string;
+  stdout?: string;
+}
+
+function isExecError(err: unknown): err is ExecError & Error {
+  return err instanceof Error && "code" in err;
+}