@stigmer/runner 3.0.1

package/src/workflow-engine/task-status-accumulator.ts

@@ -0,0 +1,204 @@
+/**
+ * Tracks per-task execution status across a workflow run.
+ *
+ * SANDBOX-SAFE: This class runs inside the Temporal deterministic V8
+ * isolate. No Node.js built-ins, no crypto, no non-deterministic ops.
+ * All data is plain objects suitable for serialization across the
+ * sandbox boundary via Temporal local-activity arguments.
+ */
+
+/** Maximum serialized size (bytes) for input/output payloads stored per task. */
+const MAX_PAYLOAD_BYTES = 65_536;
+
+export interface TaskStatusEntry {
+  readonly taskId: string;
+  readonly taskName: string;
+  readonly taskKind: string;
+  readonly status: "started" | "completed" | "failed" | "skipped" | "waiting_approval";
+  readonly startedAt?: string;
+  readonly completedAt?: string;
+  readonly error?: string;
+  readonly durationMs?: number;
+  readonly input?: unknown;
+  readonly output?: unknown;
+  readonly metadata?: Record<string, unknown>;
+  readonly costMicros?: number;
+  readonly inputTokens?: number;
+  readonly outputTokens?: number;
+}
+
+/**
+ * Truncates a payload to fit within the configured size limit.
+ *
+ * SANDBOX-SAFE: uses only JSON.stringify (deterministic for plain objects)
+ * and string slicing. No crypto, no Buffer, no Node.js APIs.
+ *
+ * Returns the value unchanged if it fits. Returns a summary object with
+ * a truncation marker and preview if it exceeds the limit.
+ */
+export function truncatePayload(value: unknown, maxBytes = MAX_PAYLOAD_BYTES): unknown {
+  if (value === undefined || value === null) return value;
+
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(value);
+  } catch {
+    return { _truncated: true, _reason: "unserializable" };
+  }
+
+  if (serialized.length <= maxBytes) return value;
+
+  const preview = serialized.slice(0, 2048);
+  return {
+    _truncated: true,
+    _original_bytes: serialized.length,
+    _preview: preview,
+  };
+}
+
+export class TaskStatusAccumulator {
+  private readonly entries = new Map<string, TaskStatusEntry>();
+  private readonly attemptCounts = new Map<string, number>();
+
+  private nextAttempt(name: string): number {
+    const current = this.attemptCounts.get(name) ?? 0;
+    const next = current + 1;
+    this.attemptCounts.set(name, next);
+    return next;
+  }
+
+  private currentAttempt(name: string): number {
+    return this.attemptCounts.get(name) ?? 1;
+  }
+
+  /** Returns the current attempt number for a task (1-based). */
+  getAttempt(name: string): number {
+    return this.attemptCounts.get(name) ?? 1;
+  }
+
+  taskStarted(name: string, kind: string): void {
+    const attempt = this.nextAttempt(name);
+    this.entries.set(name, {
+      taskId: `${name}:${attempt}`,
+      taskName: name,
+      taskKind: kind,
+      status: "started",
+      startedAt: new Date().toISOString(),
+    });
+  }
+
+  taskStartedWithInput(name: string, kind: string, input: unknown): void {
+    const attempt = this.currentAttempt(name);
+    this.entries.set(name, {
+      taskId: `${name}:${attempt}`,
+      taskName: name,
+      taskKind: kind,
+      status: "started",
+      startedAt: new Date().toISOString(),
+      input: truncatePayload(input),
+    });
+  }
+
+  taskCompleted(name: string, durationMs: number): void {
+    const existing = this.entries.get(name);
+    this.entries.set(name, {
+      ...existing,
+      taskId: existing?.taskId ?? `${name}:${this.currentAttempt(name)}`,
+      taskName: name,
+      taskKind: existing?.taskKind ?? "",
+      status: "completed",
+      startedAt: existing?.startedAt,
+      completedAt: new Date().toISOString(),
+      durationMs,
+    });
+  }
+
+  taskCompletedWithResult(
+    name: string,
+    durationMs: number,
+    output: unknown,
+    cost?: { costMicros: number; inputTokens: number; outputTokens: number },
+  ): void {
+    const existing = this.entries.get(name);
+    this.entries.set(name, {
+      ...existing,
+      taskId: existing?.taskId ?? `${name}:${this.currentAttempt(name)}`,
+      taskName: name,
+      taskKind: existing?.taskKind ?? "",
+      status: "completed",
+      startedAt: existing?.startedAt,
+      completedAt: new Date().toISOString(),
+      durationMs,
+      output: truncatePayload(output),
+      costMicros: cost?.costMicros ?? existing?.costMicros,
+      inputTokens: cost?.inputTokens ?? existing?.inputTokens,
+      outputTokens: cost?.outputTokens ?? existing?.outputTokens,
+    });
+  }
+
+  taskFailed(name: string, error: string, structuredError?: {
+    category: string;
+    detail: string;
+    retryable: boolean;
+  }, durationMs?: number): void {
+    const existing = this.entries.get(name);
+    const metadata = structuredError
+      ? {
+          ...existing?.metadata,
+          error_category: structuredError.category,
+          error_detail: structuredError.detail,
+          error_retryable: structuredError.retryable,
+        }
+      : existing?.metadata;
+
+    this.entries.set(name, {
+      ...existing,
+      taskId: existing?.taskId ?? `${name}:${this.currentAttempt(name)}`,
+      taskName: name,
+      taskKind: existing?.taskKind ?? "",
+      status: "failed",
+      startedAt: existing?.startedAt,
+      completedAt: new Date().toISOString(),
+      error,
+      durationMs,
+      metadata,
+    });
+  }
+
+  taskSkipped(name: string, reason: string): void {
+    const existing = this.entries.get(name);
+    this.entries.set(name, {
+      taskId: `${name}:${this.currentAttempt(name)}`,
+      taskName: name,
+      taskKind: existing?.taskKind ?? "",
+      status: "skipped",
+      completedAt: new Date().toISOString(),
+      error: reason,
+    });
+  }
+
+  taskWaitingApproval(name: string): void {
+    const existing = this.entries.get(name);
+    this.entries.set(name, {
+      ...existing,
+      taskId: existing?.taskId ?? `${name}:${this.currentAttempt(name)}`,
+      taskName: name,
+      taskKind: existing?.taskKind ?? "",
+      status: "waiting_approval",
+      startedAt: existing?.startedAt,
+    });
+  }
+
+  setTaskMetadata(name: string, metadata: Record<string, unknown>): void {
+    const existing = this.entries.get(name);
+    if (!existing) return;
+    this.entries.set(name, {
+      ...existing,
+      metadata: { ...existing.metadata, ...metadata },
+    });
+  }
+
+  toArray(): TaskStatusEntry[] {
+    return Array.from(this.entries.values());
+  }
+}

package/src/workflow-engine/tasks/call-agent-output.ts

@@ -0,0 +1,132 @@
+/**
+ * Structured output validation for call:agent results.
+ *
+ * When a call:agent task defines `output.schema`, the agent's
+ * response is validated against the JSON Schema. The `on_invalid`
+ * policy determines behavior on validation failure:
+ *
+ * - ON_INVALID_FAIL: task fails immediately
+ * - ON_INVALID_RETRY: re-prompt with validation errors (up to max_retries)
+ * - ON_INVALID_FALLBACK: branch to fallback_task
+ *
+ * Uses Ajv for JSON Schema Draft 2020-12 validation.
+ *
+ * This module is sandbox-safe — no Node.js built-ins, no I/O.
+ */
+
+import type { AgentCallResult } from "../types.js";
+
+export interface ValidationResult {
+  readonly valid: boolean;
+  readonly errors: string[];
+}
+
+/**
+ * Validates an agent call result against a JSON Schema.
+ * Reads from `result.structured` — the agent domain owns extraction
+ * and this function only validates the already-extracted data.
+ */
+export function validateAgentCallOutput(
+  result: AgentCallResult,
+  schema: Record<string, unknown>,
+): ValidationResult {
+  const data = extractValidationTarget(result);
+
+  if (data === undefined) {
+    return {
+      valid: false,
+      errors: ["Agent did not return structured output"],
+    };
+  }
+
+  return validateJsonSchema(data, schema);
+}
+
+function extractValidationTarget(result: AgentCallResult): unknown | undefined {
+  if (result.structured !== undefined && result.structured !== null) {
+    return result.structured;
+  }
+  return undefined;
+}
+
+/**
+ * Lightweight JSON Schema validation. Checks `type`, `required`,
+ * `properties`, and `enum` constraints — the subset used by agent
+ * output schemas. Full Ajv integration is deferred to the activity
+ * layer if deeper schema support (Draft 2020-12 features like
+ * $ref, if/then/else, etc.) is needed.
+ *
+ * This keeps the workflow sandbox free of heavy dependencies.
+ */
+function validateJsonSchema(
+  data: unknown,
+  schema: Record<string, unknown>,
+): ValidationResult {
+  const errors: string[] = [];
+
+  if (schema.type === "object") {
+    if (typeof data !== "object" || data === null || Array.isArray(data)) {
+      return { valid: false, errors: ["Expected object, got " + typeof data] };
+    }
+
+    const obj = data as Record<string, unknown>;
+    const required = schema.required as string[] | undefined;
+    if (required) {
+      for (const field of required) {
+        if (!(field in obj)) {
+          errors.push(`Missing required field '${field}'`);
+        }
+      }
+    }
+
+    const properties = schema.properties as Record<string, Record<string, unknown>> | undefined;
+    if (properties) {
+      for (const [field, propSchema] of Object.entries(properties)) {
+        if (!(field in obj)) continue;
+        const value = obj[field];
+
+        if (propSchema.type && !matchesType(value, propSchema.type as string)) {
+          errors.push(`Field '${field}' expected type '${propSchema.type}', got '${typeof value}'`);
+        }
+
+        if (propSchema.enum && Array.isArray(propSchema.enum)) {
+          if (!propSchema.enum.includes(value)) {
+            errors.push(
+              `Field '${field}' must be one of [${propSchema.enum.join(", ")}], got '${value}'`,
+            );
+          }
+        }
+      }
+    }
+  } else if (schema.type === "array") {
+    if (!Array.isArray(data)) {
+      return { valid: false, errors: ["Expected array, got " + typeof data] };
+    }
+  } else if (schema.type) {
+    if (!matchesType(data, schema.type as string)) {
+      return { valid: false, errors: [`Expected type '${schema.type}', got '${typeof data}'`] };
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+function matchesType(value: unknown, expectedType: string): boolean {
+  switch (expectedType) {
+    case "string":
+      return typeof value === "string";
+    case "number":
+    case "integer":
+      return typeof value === "number";
+    case "boolean":
+      return typeof value === "boolean";
+    case "object":
+      return typeof value === "object" && value !== null && !Array.isArray(value);
+    case "array":
+      return Array.isArray(value);
+    case "null":
+      return value === null;
+    default:
+      return true;
+  }
+}

package/src/workflow-engine/tasks/call-agent.ts

@@ -0,0 +1,221 @@
+/**
+ * CallAgent task builder — invokes a Stigmer agent from a workflow.
+ *
+ * Unlike call:llm (synchronous activity), call:agent uses Temporal
+ * async completion: the activity creates an AgentExecution with a
+ * callback token and returns pending. The platform completes the
+ * activity when the agent finishes. While pending, the workflow
+ * listens for `child_approval_required` signals for HITL propagation.
+ *
+ * This builder is sandbox-safe — it evaluates jq expressions and
+ * delegates to `ctx.callAgent()`. The async completion and signal
+ * logic live in the workflow-side orchestrator, not here.
+ *
+ * Mirrors Go's `CallAgentTaskBuilder` in `task_builder_call_agent.go`.
+ */
+
+import type {
+  CallAgentTaskDef,
+  TaskBuilder,
+  TaskExecutorFn,
+  TaskExecutionContext,
+  AgentCallConfig,
+  AgentCallResult,
+  CallAgentMetadata,
+} from "../types.js";
+import { AgentCallError } from "../types.js";
+import { resolveConfigExpressions } from "../resolve.js";
+import { validateAgentCallOutput } from "./call-agent-output.js";
+
+/**
+ * Enriches an AgentCallResult with __stigmer_* keys so that
+ * extractCostFromOutput (in do-executor) can pick up cost/token data.
+ *
+ * Agent usage_summary only provides total_tokens (no input/output split).
+ * We map total_tokens to input_tokens and leave output_tokens at 0.
+ * The do-executor sets metadata `token_attribution: "total_only"` so
+ * the frontend can avoid displaying a misleading split.
+ */
+function enrichResultWithCost(result: AgentCallResult): AgentCallResult {
+  const usage = result.usage_summary;
+  if (!usage) return result;
+
+  return {
+    ...result,
+    __stigmer_cost_micros: Math.round((usage.estimated_cost_usd ?? 0) * 1_000_000),
+    input_tokens: usage.total_tokens ?? 0,
+    output_tokens: 0,
+  } as AgentCallResult;
+}
+
+export class CallAgentTaskBuilder implements TaskBuilder {
+  readonly taskName: string;
+  readonly taskDef: CallAgentTaskDef;
+
+  constructor(taskName: string, taskDef: CallAgentTaskDef) {
+    this.taskName = taskName;
+    this.taskDef = taskDef;
+  }
+
+  build(): TaskExecutorFn {
+    return async (input, state, ctx) => {
+      const withConfig = this.taskDef.with;
+
+      const resolved = await resolveConfigExpressions(
+        withConfig as unknown as Record<string, unknown>,
+        input,
+        state,
+        ctx.evaluateExpressions,
+      );
+
+      const config = resolved as unknown as AgentCallConfig;
+
+      const executionId =
+        (state.data["__stigmer_execution_id"] as string | undefined) ?? "";
+
+      const metadata = {
+        parentWorkflowId:
+          (state.data["__stigmer_parent_workflow_id"] as string | undefined) ?? "",
+        taskName: this.taskName,
+        workflowExecutionId: executionId,
+      };
+
+      const outputContract = withConfig.output;
+      const maxRetries = outputContract?.max_retries ?? 2;
+      let attempts = 0;
+      let lastResult: AgentCallResult;
+
+      do {
+        const effectiveConfig =
+          attempts === 0
+            ? config
+            : augmentMessageWithValidationError(config, lastResult!);
+
+        lastResult = await this.executeAgentCall(
+          effectiveConfig, state.env, metadata, ctx,
+        );
+        attempts++;
+
+        if (!outputContract?.schema) {
+          return enrichResultWithCost(lastResult);
+        }
+
+        const validation = validateAgentCallOutput(
+          lastResult,
+          outputContract.schema,
+        );
+
+        if (validation.valid) {
+          return enrichResultWithCost(lastResult);
+        }
+
+        const onInvalid = outputContract.on_invalid ?? "ON_INVALID_FAIL";
+
+        if (onInvalid === "ON_INVALID_FAIL") {
+          throw new Error(
+            `Agent output validation failed for task '${this.taskName}': ` +
+            `${validation.errors.join("; ")}`,
+          );
+        }
+
+        if (onInvalid === "ON_INVALID_FALLBACK") {
+          return {
+            __flow_directive__: outputContract.fallback_task ?? "continue",
+            validation_errors: validation.errors,
+            original_output: lastResult,
+          };
+        }
+      } while (attempts <= maxRetries);
+
+      throw new Error(
+        `Agent output validation failed after ${attempts} attempts ` +
+        `for task '${this.taskName}'. Schema validation did not pass.`,
+      );
+    };
+  }
+
+  /**
+   * Executes a single agent call with event emission bracketing.
+   *
+   * Emits `agent_call_started` before dispatching and
+   * `agent_call_completed` after completion (success or failure).
+   * These events drive the waterfall timeline's nested sub-span bars.
+   */
+  private async executeAgentCall(
+    config: AgentCallConfig,
+    env: Record<string, unknown>,
+    metadata: CallAgentMetadata,
+    ctx: TaskExecutionContext,
+  ): Promise<AgentCallResult> {
+    const callStartMs = Date.now();
+    const messageSummary = (config.message ?? "").slice(0, 200);
+
+    if (ctx.emitEvents) {
+      await ctx.emitEvents([{
+        type: "agent_call_started",
+        taskName: this.taskName,
+        occurredAt: new Date().toISOString(),
+        childExecutionId: "",
+        agentSlug: config.agent ?? "",
+        messageSummary,
+      }]);
+    }
+
+    let result: AgentCallResult;
+    try {
+      result = await ctx.callAgent(config, env, metadata);
+    } catch (err) {
+      const errorChildExecId = err instanceof AgentCallError
+        ? err.childExecutionId
+        : "";
+      if (ctx.emitEvents) {
+        await ctx.emitEvents([{
+          type: "agent_call_completed",
+          taskName: this.taskName,
+          occurredAt: new Date().toISOString(),
+          childExecutionId: errorChildExecId,
+          durationMs: Date.now() - callStartMs,
+          tokensConsumed: 0,
+          costMicros: 0,
+          error: err instanceof Error ? err.message : String(err),
+        }]);
+      }
+      throw err;
+    }
+
+    if (ctx.emitEvents) {
+      const usage = result.usage_summary;
+      await ctx.emitEvents([{
+        type: "agent_call_completed",
+        taskName: this.taskName,
+        occurredAt: new Date().toISOString(),
+        childExecutionId: result.agent_execution_id ?? "",
+        durationMs: Date.now() - callStartMs,
+        tokensConsumed: usage?.total_tokens ?? 0,
+        costMicros: Math.round((usage?.estimated_cost_usd ?? 0) * 1_000_000),
+        error: "",
+      }]);
+    }
+
+    return result;
+  }
+
+  async shouldRun(): Promise<boolean> {
+    return true;
+  }
+}
+
+function augmentMessageWithValidationError(
+  config: AgentCallConfig,
+  previousResult: AgentCallResult,
+): AgentCallConfig {
+  const validationContext =
+    `\n\n[RETRY — Your previous response did not match the required output schema. ` +
+    `Previous response: ${JSON.stringify(previousResult.structured ?? previousResult.final_text)}. ` +
+    `Please ensure your response strictly matches the JSON schema provided.]`;
+
+  return {
+    ...config,
+    message: config.message + validationContext,
+  };
+}

package/src/workflow-engine/tasks/call-function.ts

@@ -0,0 +1,107 @@
+/**
+ * CallFunction task builder — handles Stigmer extension call types:
+ * `call: llm`, `call: agent`, `call: transform`, etc.
+ *
+ * The CNCF DSL uses `call: <string>` for custom function calls.
+ * This builder evaluates expressions in the `with` config, then
+ * delegates to the `ctx.callFunction` callback which routes to
+ * the appropriate Temporal activity based on the `call` value.
+ *
+ * Mirrors Go's custom call function dispatch in `task_builder.go`.
+ */
+
+import type {
+  CallFunctionTaskDef,
+  TaskBuilder,
+  TaskExecutorFn,
+} from "../types.js";
+import { resolveConfigExpressions } from "../resolve.js";
+
+interface LlmActivityResult {
+  readonly result: unknown;
+  readonly model: string;
+  readonly provider: string;
+  readonly input_tokens: number;
+  readonly output_tokens: number;
+  readonly parse_error?: string;
+  readonly __stigmer_cost_micros?: number;
+}
+
+/**
+ * Normalizes the raw LlmCallResult from the activity into the documented
+ * task output contract: { text, structured, model, usage }.
+ *
+ * When response_schema is set, the parsed JSON goes into `.structured`.
+ * When no schema is used, the raw text goes into `.text`.
+ */
+function normalizeLlmOutput(
+  raw: LlmActivityResult,
+  hasResponseSchema: boolean,
+): Record<string, unknown> {
+  return {
+    text: hasResponseSchema ? undefined : raw.result,
+    structured: hasResponseSchema ? raw.result : undefined,
+    model: raw.model,
+    usage: {
+      input_tokens: raw.input_tokens,
+      output_tokens: raw.output_tokens,
+    },
+    ...(raw.__stigmer_cost_micros !== undefined
+      ? { __stigmer_cost_micros: raw.__stigmer_cost_micros }
+      : {}),
+  };
+}
+
+export class CallFunctionTaskBuilder implements TaskBuilder {
+  readonly taskName: string;
+  readonly taskDef: CallFunctionTaskDef;
+
+  constructor(taskName: string, taskDef: CallFunctionTaskDef) {
+    this.taskName = taskName;
+    this.taskDef = taskDef;
+  }
+
+  build(): TaskExecutorFn {
+    return async (input, state, ctx) => {
+      const withConfig = this.taskDef.with ?? {};
+
+      const resolved = await resolveConfigExpressions(
+        withConfig as Record<string, unknown>,
+        input,
+        state,
+        ctx.evaluateExpressions,
+      );
+
+      const callType = this.taskDef.call;
+      if ((callType === "transform" || callType === "validate") &&
+          !("input" in resolved) || resolved.input === undefined) {
+        resolved.input = input;
+      }
+
+      const executionId =
+        (state.env.__stigmer_execution_id as string | undefined) || undefined;
+
+      const result = await ctx.callFunction(
+        callType,
+        resolved,
+        state.env,
+        {
+          workflowExecutionId: executionId,
+        },
+      );
+
+      if (callType === "llm") {
+        return normalizeLlmOutput(
+          result as LlmActivityResult,
+          !!resolved.response_schema,
+        );
+      }
+
+      return result;
+    };
+  }
+
+  async shouldRun(): Promise<boolean> {
+    return true;
+  }
+}

package/src/workflow-engine/tasks/call-grpc.ts

@@ -0,0 +1,47 @@
+/**
+ * CallGRPC task builder — evaluates expressions in the gRPC call
+ * config, then delegates the actual RPC to a Temporal activity
+ * via the `ctx.callGrpc` callback.
+ *
+ * Mirrors Go's `task_builder_call_grpc.go` workflow-side logic.
+ */
+
+import type {
+  CallGrpcTaskDef,
+  GrpcCallConfig,
+  TaskBuilder,
+  TaskExecutorFn,
+} from "../types.js";
+import { resolveConfigExpressions } from "../resolve.js";
+
+export class CallGrpcTaskBuilder implements TaskBuilder {
+  readonly taskName: string;
+  readonly taskDef: CallGrpcTaskDef;
+
+  constructor(taskName: string, taskDef: CallGrpcTaskDef) {
+    this.taskName = taskName;
+    this.taskDef = taskDef;
+  }
+
+  build(): TaskExecutorFn {
+    return async (input, state, ctx) => {
+      const resolved = await resolveConfigExpressions(
+        this.taskDef.with as unknown as Record<string, unknown>,
+        input,
+        state,
+        ctx.evaluateExpressions,
+      );
+
+      const result = await ctx.callGrpc(
+        resolved as unknown as GrpcCallConfig,
+        state.env,
+      );
+
+      return result;
+    };
+  }
+
+  async shouldRun(): Promise<boolean> {
+    return true;
+  }
+}