@stigmer/runner 3.0.1

package/src/activities/call-agent-status.ts

@@ -0,0 +1,130 @@
+/**
+ * Local activities for surfacing child agent HITL approval state
+ * on the parent WorkflowExecution.
+ *
+ * These run as Temporal local activities (proxyLocalActivities) with
+ * short timeouts. Failures are best-effort — they update the platform
+ * UI but do not block the workflow.
+ *
+ * - UpdateWorkflowTaskApprovalStatus: sets pending_approvals on the
+ *   WorkflowExecution when a child agent enters a tool-approval gate.
+ * - ClearWorkflowApprovalStatus: clears pending_approvals when the
+ *   child agent activity completes (approvals resolved).
+ */
+
+import { StigmerClient } from "../client/stigmer-client.js";
+import { loadConfig } from "../config.js";
+import { create } from "@bufbuild/protobuf";
+import { WorkflowExecutionStatusSchema, WorkflowPendingApprovalSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import type { ChildApprovalNotification } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
+import { ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+function buildClient(): StigmerClient {
+  const config = loadConfig();
+  return new StigmerClient({
+    endpoint: config.stigmerBackendEndpoint,
+    token: config.stigmerToken,
+  });
+}
+
+export async function updateWorkflowTaskApprovalStatus(
+  executionId: string,
+  _taskName: string,
+  notification: ChildApprovalNotification,
+): Promise<void> {
+  if (!executionId) return;
+
+  const client = buildClient();
+  const pendingApprovals = (notification.pendingApprovals ?? []).map(
+    (approval) =>
+      create(WorkflowPendingApprovalSchema, {
+        approval,
+        childAgentExecutionId: notification.executionId,
+      }),
+  );
+
+  const status = create(WorkflowExecutionStatusSchema, {
+    pendingApprovals,
+  });
+
+  await client.updateWorkflowExecutionStatus(executionId, status, {
+    updatePendingApprovals: true,
+  });
+}
+
+export async function clearWorkflowApprovalStatus(
+  executionId: string,
+): Promise<void> {
+  if (!executionId) return;
+
+  const client = buildClient();
+  const status = create(WorkflowExecutionStatusSchema, {
+    pendingApprovals: [],
+  });
+
+  await client.updateWorkflowExecutionStatus(executionId, status, {
+    updatePendingApprovals: true,
+  });
+}
+
+/**
+ * Queries the child AgentExecution for progress data that can be
+ * emitted as an `agent_call_progress` event on the parent workflow.
+ *
+ * Returns a lightweight summary derived from the agent's status:
+ * message count, last active tool, token consumption. Returns null
+ * if the execution cannot be fetched (best-effort).
+ */
+export interface AgentProgressSummary {
+  messagesCount: number;
+  toolCallsCount: number;
+  currentToolName: string;
+  tokensConsumed: number;
+  agentPhase: number;
+}
+
+export async function getAgentExecutionProgress(
+  childExecutionId: string,
+): Promise<AgentProgressSummary | null> {
+  if (!childExecutionId) return null;
+
+  try {
+    const client = buildClient();
+    const execution = await client.getExecution(childExecutionId);
+    const status = execution?.status;
+    if (!status) return null;
+
+    const messages = status.messages ?? [];
+    const messagesCount = messages.length;
+
+    let toolCallsCount = 0;
+    let currentToolName = "";
+    for (const msg of messages) {
+      const tools = msg.toolCalls ?? [];
+      toolCallsCount += tools.length;
+      for (const tc of tools) {
+        if (tc.name && tc.status === ToolCallStatus.TOOL_CALL_RUNNING) {
+          currentToolName = tc.name;
+        }
+      }
+    }
+
+    const usage = status.streamingUsage;
+    const tokensConsumed = Number(usage?.totalTokens ?? 0);
+
+    const phase = status.phase ?? 0;
+
+    return { messagesCount, toolCallsCount, currentToolName, tokensConsumed, agentPhase: phase };
+  } catch (err) {
+    console.warn("Failed to fetch agent execution progress (non-fatal):", String(err));
+    return null;
+  }
+}
+
+export function createCallAgentStatusActivities() {
+  return {
+    UpdateWorkflowTaskApprovalStatus: updateWorkflowTaskApprovalStatus,
+    ClearWorkflowApprovalStatus: clearWorkflowApprovalStatus,
+    GetAgentExecutionProgress: getAgentExecutionProgress,
+  };
+}

package/src/activities/call-agent.ts

@@ -0,0 +1,302 @@
+/**
+ * CallAgent Temporal activity — creates a Stigmer AgentExecution via
+ * the platform gRPC API and uses Temporal async completion.
+ *
+ * Flow:
+ * 1. Extract Temporal task token (for async completion callback)
+ * 2. Resolve runtime placeholders (${.secrets.*}, ${.env_vars.*})
+ * 3. Resolve agent by slug → get agent ID and default instance
+ * 4. Apply Session (idempotent get-or-create by slug)
+ * 5. Create AgentExecution (callback token, parent workflow ID)
+ * 6. Throw CompleteAsyncError — worker thread released
+ *
+ * The platform completes this activity asynchronously via the token
+ * when the agent execution workflow finishes.
+ *
+ * Activity contract:
+ *   Name:   "CallAgent"
+ *   Input:  (config, runtimeEnv, parentWorkflowId)
+ *   Output: (completed asynchronously by platform)
+ */
+
+import { randomUUID } from "node:crypto";
+import { Context, CompleteAsyncError } from "@temporalio/activity";
+import { StigmerClient } from "../client/stigmer-client.js";
+import { loadConfig } from "../config.js";
+import { resolveObjectPlaceholders } from "../workflow-engine/resolve.js";
+import type { AgentCallConfig } from "../workflow-engine/types.js";
+import { startHeartbeat } from "../shared/heartbeat.js";
+import { create, type JsonObject } from "@bufbuild/protobuf";
+import { AgentExecutionSpecSchema, ExecutionConfigSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import { SessionSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import { SessionSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/spec_pb";
+import { Harness, ExecutionTarget } from "@stigmer/protos/ai/stigmer/agentic/session/v1/enum_pb";
+import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionValueSchema } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/spec_pb";
+import type { ExecutionValue } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/spec_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+export async function callAgentAction(
+  config: AgentCallConfig,
+  runtimeEnv: Record<string, unknown>,
+  parentWorkflowId: string,
+): Promise<void> {
+  const taskToken = Context.current().info.taskToken;
+
+  const resolved = resolveObjectPlaceholders(config, runtimeEnv) as AgentCallConfig;
+
+  if (!resolved.agent) {
+    throw new Error(
+      "call:agent: 'agent' resolved to empty after placeholder substitution. " +
+      "If using ${.secrets.X} or ${.env_vars.X}, ensure the referenced key " +
+      "exists in the workflow's env block and is provisioned in the environment.",
+    );
+  }
+
+  if (!resolved.message) {
+    throw new Error(
+      "call:agent: 'message' resolved to empty after placeholder substitution. " +
+      "The agent requires a non-empty prompt message.",
+    );
+  }
+
+  const orgId = resolved.org
+    ?? (runtimeEnv["__stigmer_org_id"] as string | undefined)
+    ?? "";
+
+  if (!orgId) {
+    throw new Error(
+      "call:agent requires an organization context. " +
+      "Set 'org' in the task config or ensure '__stigmer_org_id' is in the workflow environment.",
+    );
+  }
+
+  const appConfig = loadConfig();
+  const client = new StigmerClient({
+    endpoint: appConfig.stigmerBackendEndpoint,
+    token: appConfig.stigmerToken,
+  });
+
+  const agentRef = parseAgentReference(resolved.agent, orgId);
+  const agent = await client.getAgentByReference(
+    create(ApiResourceReferenceSchema, agentRef),
+  );
+
+  const agentId = agent.metadata?.id ?? "";
+  const defaultInstanceId = agent.status?.defaultInstanceId ?? "";
+  const agentEnvKeys = Object.keys(agent.spec?.env ?? {});
+  const workflowEnvKeys = Object.keys(runtimeEnv).filter(k => !k.startsWith("__stigmer_"));
+  console.log(
+    `[CallAgent] agent=${resolved.agent} agentId=${agentId} ` +
+    `agentEnvDecls=[${agentEnvKeys.join(",")}] ` +
+    `workflowEnvKeys=[${workflowEnvKeys.join(",")}]`,
+  );
+
+  if (!agentId) {
+    throw new Error(`Agent '${resolved.agent}' resolved but has no metadata.id`);
+  }
+
+  const wfExecId = (resolved as unknown as Record<string, unknown>).__wfExecId as string | undefined
+    ?? runtimeEnv["__stigmer_execution_id"] as string | undefined;
+  const taskName = (resolved as unknown as Record<string, unknown>).__taskName as string | undefined;
+
+  let sessionName: string;
+  let executionName: string;
+
+  if (wfExecId && taskName) {
+    const taskKey = `${wfExecId}-${taskName}`;
+    sessionName = `ses-wf-${taskKey}`;
+    executionName = `aex-wf-${taskKey}-${shortUniqueId()}`;
+  } else {
+    console.warn(
+      `[CallAgent] Missing workflow context for session naming: ` +
+      `wfExecId=${wfExecId ?? "(missing)"}, taskName=${taskName ?? "(missing)"}. ` +
+      `Using timestamp-based names — session will NOT be reused on retry.`,
+    );
+    sessionName = `wf-${extractSlug(resolved.agent)}-${Math.floor(Date.now() / 1000)}`;
+    executionName = `aex-wf-${extractSlug(resolved.agent)}-${Date.now()}`;
+  }
+
+  console.log(
+    `[CallAgent] session=${sessionName}, execution=${executionName}, ` +
+    `wfExecId=${wfExecId ?? "(none)"}, task=${taskName ?? "(none)"}`,
+  );
+
+  const harness = resolveHarness(resolved.harness);
+  const executionTarget = resolveExecutionTarget(
+    runtimeEnv["__stigmer_execution_target"] as number | undefined,
+  );
+
+  const session = await client.applySession(
+    create(SessionSchema, {
+      apiVersion: "agentic.stigmer.ai/v1",
+      kind: "Session",
+      metadata: create(ApiResourceMetadataSchema, {
+        name: sessionName,
+        org: orgId,
+      }),
+      spec: create(SessionSpecSchema, {
+        agentInstanceId: defaultInstanceId,
+        harness,
+        executionTarget,
+        subject: "Auto-created session",
+      }),
+    }),
+  );
+  const sessionId = session?.metadata?.id ?? "";
+
+  const executionRuntimeEnv: Record<string, { value: string; isSecret: boolean }> = {};
+
+  // Automatic intersection forwarding: forward workflow env vars that match the
+  // child agent's declared spec.env keys. This avoids requiring workflow authors
+  // to manually re-declare every env var on every agent_call task.
+  const agentEnvDecls = agent.spec?.env ?? {};
+  for (const [key, decl] of Object.entries(agentEnvDecls)) {
+    if (key in runtimeEnv && runtimeEnv[key] != null) {
+      executionRuntimeEnv[key] = {
+        value: String(runtimeEnv[key]),
+        isSecret: decl.isSecret ?? false,
+      };
+    }
+  }
+
+  const intersectionKeys = Object.keys(executionRuntimeEnv);
+  const skippedKeys = agentEnvKeys.filter(k => !(k in executionRuntimeEnv));
+  if (skippedKeys.length > 0) {
+    console.warn(
+      `[CallAgent] agent declares env keys not present in workflow env: [${skippedKeys.join(",")}]`,
+    );
+  }
+
+  // Task-config-level env takes precedence over auto-forwarded values
+  if (resolved.env) {
+    for (const [key, value] of Object.entries(resolved.env)) {
+      executionRuntimeEnv[key] = { value: String(value), isSecret: false };
+    }
+  }
+
+  const finalKeys = Object.keys(executionRuntimeEnv);
+  const overrideKeys = finalKeys.filter(k => !intersectionKeys.includes(k));
+  console.log(
+    `[CallAgent] env forwarding: intersection=${intersectionKeys.length} ` +
+    `taskOverrides=${overrideKeys.length} total=${finalKeys.length} ` +
+    `keys=[${finalKeys.join(",")}]`,
+  );
+
+  const runtimeEnvProto: Record<string, ExecutionValue> = {};
+  for (const [key, val] of Object.entries(executionRuntimeEnv)) {
+    runtimeEnvProto[key] = create(ExecutionValueSchema, {
+      value: val.value,
+      isSecret: val.isSecret,
+    });
+  }
+
+  const parentQueue = runtimeEnv["__stigmer_activity_task_queue"] as string | undefined;
+  const activityTaskQueue = parentQueue?.startsWith("wfexec:") ? parentQueue : "";
+
+  const hasModel = !!resolved.config?.model;
+  const hasOutputSchema = !!resolved.output?.schema;
+
+  console.log(
+    `[CallAgent] schema propagation diagnostic: ` +
+    `hasOutputSchema=${hasOutputSchema}, ` +
+    `hasModel=${hasModel}, ` +
+    `configKeys=[${Object.keys(resolved).join(",")}], ` +
+    `hasOutput=${resolved.output !== undefined}, ` +
+    `outputKeys=${resolved.output ? JSON.stringify(Object.keys(resolved.output)) : "N/A"}, ` +
+    `__taskName=${(resolved as any).__taskName ?? "MISSING"}, ` +
+    `wfExecId=${wfExecId ?? "MISSING"}`,
+  );
+
+  const executionSpec = create(AgentExecutionSpecSchema, {
+    sessionId,
+    agentId,
+    message: resolved.message,
+    callbackToken: taskToken,
+    parentWorkflowId,
+    activityTaskQueue,
+    runtimeEnv: runtimeEnvProto,
+  });
+
+  if (hasModel || hasOutputSchema) {
+    const execConfig = create(ExecutionConfigSchema, {});
+    if (hasModel) execConfig.modelName = resolved.config!.model!;
+    if (hasOutputSchema) {
+      execConfig.structuredOutputSchema = resolved.output!.schema as JsonObject;
+    }
+    executionSpec.executionConfig = execConfig;
+  }
+
+  await client.createAgentExecution(
+    create(AgentExecutionSchema, {
+      apiVersion: "agentic.stigmer.ai/v1",
+      kind: "AgentExecution",
+      metadata: create(ApiResourceMetadataSchema, {
+        name: executionName,
+        org: orgId,
+      }),
+      spec: executionSpec,
+    }),
+  );
+
+  throw new CompleteAsyncError();
+}
+
+function parseAgentReference(
+  agentStr: string,
+  defaultOrg: string,
+): { org: string; slug: string; kind: ApiResourceKind } {
+  if (agentStr.includes("/")) {
+    const [org, slug] = agentStr.split("/", 2);
+    return { org, slug, kind: ApiResourceKind.agent };
+  }
+  return { org: defaultOrg, slug: agentStr, kind: ApiResourceKind.agent };
+}
+
+function extractSlug(agentStr: string): string {
+  return agentStr.includes("/") ? agentStr.split("/", 2)[1] : agentStr;
+}
+
+function shortUniqueId(): string {
+  return randomUUID().replace(/-/g, "").slice(0, 8);
+}
+
+function resolveHarness(harnessStr?: string): Harness {
+  if (!harnessStr) return Harness.NATIVE;
+
+  switch (harnessStr.toUpperCase()) {
+    case "HARNESS_NATIVE":
+    case "NATIVE":
+      return Harness.NATIVE;
+    case "HARNESS_CURSOR":
+    case "CURSOR":
+      return Harness.CURSOR;
+    default:
+      return Harness.NATIVE;
+  }
+}
+
+function resolveExecutionTarget(target?: number): ExecutionTarget {
+  if (target === 1) return ExecutionTarget.LOCAL;
+  if (target === 2) return ExecutionTarget.CLOUD;
+  return ExecutionTarget.UNSPECIFIED;
+}
+
+export function createCallAgentActivities() {
+  return {
+    CallAgent: async (
+      config: AgentCallConfig,
+      runtimeEnv: Record<string, unknown>,
+      parentWorkflowId: string,
+    ): Promise<void> => {
+      const hb = startHeartbeat(15_000, () => ({ phase: "creating_agent_execution" }));
+      try {
+        return await callAgentAction(config, runtimeEnv, parentWorkflowId);
+      } finally {
+        hb.stop();
+      }
+    },
+  };
+}