@stigmer/runner 3.0.1

package/src/workflows/call-agent-orchestrator.ts

@@ -0,0 +1,283 @@
+/**
+ * Workflow-side orchestrator for call:agent tasks.
+ *
+ * Runs inside the Temporal deterministic workflow sandbox. Manages:
+ * 1. Starting the CallAgent activity (async completion)
+ * 2. Listening for `child_execution_started` to get early child execution ID
+ * 3. Listening for `child_approval_required` signals from child agents
+ * 4. Updating workflow approval status via local activities
+ * 5. Returning the agent result when the activity completes
+ *
+ * The kernel's CallAgentTaskBuilder calls `ctx.callAgent()`, which
+ * is wired to `orchestrateAgentCall()` in execute-serverless-workflow.ts.
+ *
+ * SANDBOX RULES: Only @temporalio/workflow imports, type-only imports,
+ * and pure logic. No Node.js built-ins.
+ */
+
+import {
+  defineSignal,
+  setHandler,
+  condition,
+  proxyActivities,
+  proxyLocalActivities,
+  log,
+  CancellationScope,
+  isCancellation,
+} from "@temporalio/workflow";
+
+import type { createCallAgentActivities } from "../activities/call-agent.js";
+import type { createCallAgentStatusActivities, AgentProgressSummary } from "../activities/call-agent-status.js";
+import type { createWorkflowEventActivities } from "../activities/workflow-event-activities.js";
+import type { AgentCallConfig, AgentCallResult, WorkflowEventDescriptor } from "../workflow-engine/types.js";
+import { AgentCallError } from "../workflow-engine/types.js";
+import type { ChildApprovalNotification } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
+
+// ─────────────────────────────────────────────────────────────────────
+// Signal Definitions
+// ─────────────────────────────────────────────────────────────────────
+
+export const childApprovalRequired = defineSignal<[ChildApprovalNotification]>(
+  "child_approval_required",
+);
+
+/** Sent by the platform immediately after the child AgentExecution starts. */
+export const childExecutionStarted = defineSignal<[{ executionId: string }]>(
+  "child_execution_started",
+);
+
+// ─────────────────────────────────────────────────────────────────────
+// Activity Proxies
+// ─────────────────────────────────────────────────────────────────────
+
+type AgentActivities = ReturnType<typeof createCallAgentActivities>;
+type StatusActivities = ReturnType<typeof createCallAgentStatusActivities>;
+type EventActivities = ReturnType<typeof createWorkflowEventActivities>;
+
+const agentProxy = proxyActivities<AgentActivities>({
+  startToCloseTimeout: "1h",
+  retry: {
+    maximumAttempts: 1,
+  },
+});
+
+const statusProxy = proxyLocalActivities<StatusActivities>({
+  startToCloseTimeout: "30s",
+  retry: {
+    maximumAttempts: 3,
+    initialInterval: "2s",
+    backoffCoefficient: 2,
+  },
+});
+
+const eventProxy = proxyLocalActivities<EventActivities>({
+  startToCloseTimeout: "10s",
+  retry: {
+    maximumAttempts: 2,
+    initialInterval: "500ms",
+  },
+});
+
+// ─────────────────────────────────────────────────────────────────────
+// Orchestrator
+// ─────────────────────────────────────────────────────────────────────
+
+export interface AgentCallOrchestrationInput {
+  config: AgentCallConfig;
+  runtimeEnv: Record<string, unknown>;
+  parentWorkflowId: string;
+  taskName: string;
+  workflowExecutionId: string;
+}
+
+/**
+ * Orchestrates a call:agent task from the workflow function.
+ *
+ * Starts the CallAgent activity (async completion), sets up a signal
+ * handler for HITL approval notifications, and waits for the activity
+ * to complete. Returns the agent's result.
+ */
+const PROGRESS_POLL_INTERVAL = "15s";
+
+export async function orchestrateAgentCall(
+  input: AgentCallOrchestrationInput,
+): Promise<AgentCallResult> {
+  let activityDone = false;
+  let activityResult: AgentCallResult = {};
+  let activityError: unknown = undefined;
+  let pendingNotification: ChildApprovalNotification | undefined;
+  let childExecId: string | undefined;
+  let initialProgressEmitted = false;
+
+  setHandler(childApprovalRequired, (notification: ChildApprovalNotification) => {
+    pendingNotification = notification;
+    if (!childExecId && notification.executionId) {
+      childExecId = notification.executionId;
+    }
+  });
+
+  setHandler(childExecutionStarted, (payload: { executionId: string } | string) => {
+    // The Go server sends { executionId: "aex_xxx" } (struct with json tag).
+    // The Java server sends "aex_xxx" (bare string via parentStub.signal(name, id)).
+    // Handle both shapes for cross-implementation resilience.
+    if (typeof payload === "string") {
+      childExecId = payload;
+    } else if (payload && typeof payload === "object" && "executionId" in payload) {
+      childExecId = payload.executionId;
+    }
+  });
+
+  const enrichedConfig = {
+    ...input.config,
+    __taskName: input.taskName,
+    __wfExecId: input.workflowExecutionId,
+  };
+
+  log.info("[CallAgent orchestrator] sending to activity", {
+    taskName: input.taskName,
+    hasOutput: enrichedConfig.output !== undefined,
+    hasOutputSchema: enrichedConfig.output?.schema !== undefined,
+    configKeys: Object.keys(enrichedConfig).join(","),
+    hasTaskName: !!enrichedConfig.__taskName,
+  });
+
+  const activityPromise = agentProxy
+    .CallAgent(enrichedConfig, input.runtimeEnv, input.parentWorkflowId)
+    .then((result) => {
+      if (typeof result === "string") {
+        try {
+          activityResult = JSON.parse(result) as AgentCallResult;
+        } catch {
+          activityResult = {};
+        }
+      } else {
+        activityResult = (result ?? {}) as AgentCallResult;
+      }
+      log.info("[CallAgent callback] activity result received", {
+        taskName: input.taskName,
+        hasStructured: activityResult.structured !== undefined,
+        resultKeys: Object.keys(activityResult).join(","),
+      });
+      activityDone = true;
+    })
+    .catch((err) => {
+      if (isCancellation(err)) {
+        activityDone = true;
+        return;
+      }
+      activityError = err;
+      activityDone = true;
+    });
+
+  while (!activityDone) {
+    // Wait for a signal, activity completion, or periodic timeout for progress polling.
+    // condition() returns false on timeout, true when the predicate became true.
+    const conditionMet = await condition(
+      () => activityDone || pendingNotification !== undefined || (!!childExecId && !initialProgressEmitted),
+      PROGRESS_POLL_INTERVAL,
+    );
+
+    if (activityDone) break;
+
+    // Emit initial progress with childExecutionId as soon as it's known
+    if (childExecId && !initialProgressEmitted) {
+      initialProgressEmitted = true;
+      await emitProgress(input, childExecId, null);
+    }
+
+    // Periodic progress: on timeout, poll the child execution for live data
+    if (!conditionMet && childExecId) {
+      let progress: AgentProgressSummary | null = null;
+      try {
+        progress = await statusProxy.GetAgentExecutionProgress(childExecId);
+      } catch (err) {
+        log.warn("Failed to fetch agent progress (non-fatal)", {
+          error: String(err),
+          taskName: input.taskName,
+        });
+      }
+      if (progress) {
+        await emitProgress(input, childExecId, progress);
+      }
+    }
+
+    // Handle HITL approval notification
+    if (pendingNotification) {
+      const notification = pendingNotification;
+      pendingNotification = undefined;
+
+      try {
+        await statusProxy.UpdateWorkflowTaskApprovalStatus(
+          input.workflowExecutionId,
+          input.taskName,
+          notification,
+        );
+      } catch (statusErr) {
+        log.warn("Failed to update workflow approval status (non-fatal)", {
+          error: String(statusErr),
+          taskName: input.taskName,
+        });
+      }
+    }
+  }
+
+  // Emit a final progress event if the child ID arrived but was never emitted.
+  // This handles the fast-completion race: the activity finishes before the
+  // orchestrator loop has a chance to process the child_execution_started signal.
+  if (childExecId && !initialProgressEmitted) {
+    await emitProgress(input, childExecId, null);
+  }
+
+  try {
+    await statusProxy.ClearWorkflowApprovalStatus(input.workflowExecutionId);
+  } catch (clearErr) {
+    log.warn("Failed to clear workflow approval status (non-fatal)", {
+      error: String(clearErr),
+    });
+  }
+
+  if (activityError) {
+    if (childExecId) {
+      const msg = activityError instanceof Error
+        ? activityError.message
+        : String(activityError);
+      throw new AgentCallError(msg, childExecId);
+    }
+    throw activityError;
+  }
+
+  // Ensure the child execution ID is available on the result for the
+  // agent_call_completed event emitted by CallAgentTaskBuilder.
+  if (childExecId && !activityResult.agent_execution_id) {
+    activityResult = { ...activityResult, agent_execution_id: childExecId };
+  }
+
+  return activityResult;
+}
+
+async function emitProgress(
+  input: AgentCallOrchestrationInput,
+  childExecId: string,
+  progress: AgentProgressSummary | null,
+): Promise<void> {
+  try {
+    const progressEvent: WorkflowEventDescriptor = {
+      type: "agent_call_progress",
+      taskName: input.taskName,
+      occurredAt: new Date().toISOString(),
+      childExecutionId: childExecId,
+      agentSlug: input.config.agent ?? "",
+      agentPhase: progress?.agentPhase ?? 0,
+      currentToolName: progress?.currentToolName ?? "",
+      tokensConsumed: progress?.tokensConsumed ?? 0,
+      messagesCount: progress?.messagesCount ?? 0,
+      toolCallsCount: progress?.toolCallsCount ?? 0,
+    };
+    await eventProxy.EmitWorkflowEvents(input.workflowExecutionId, [progressEvent], []);
+  } catch (emitErr) {
+    log.warn("Failed to emit agent_call_progress (non-fatal)", {
+      error: String(emitErr),
+      taskName: input.taskName,
+    });
+  }
+}

package/src/workflows/connect-mcp-server.ts

@@ -0,0 +1,152 @@
+/**
+ * Temporal workflows for the MCP server connect flow.
+ *
+ * ConnectMcpServerWorkflow ("stigmer/mcp-server/connect"):
+ *   Two-stage pipeline — discover tools, then classify approval policies.
+ *   Short-circuits classification when the tools fingerprint is unchanged
+ *   and previous approvals exist.
+ *
+ * DiscoverMcpServerWorkflow ("stigmer/mcp-server/discover"):
+ *   Legacy single-stage wrapper retained for in-flight backward
+ *   compatibility during deployment transitions.
+ *
+ * SANDBOX RULES: This file runs inside the Temporal deterministic V8
+ * isolate. No Node.js built-ins (crypto, fs, net), no non-deterministic
+ * operations, no side-effecting imports. Only @temporalio/workflow APIs,
+ * type-only imports, and pure JS/TS logic.
+ */
+
+import { proxyActivities, log } from "@temporalio/workflow";
+
+import type { createDiscoverMcpServerActivities } from "../activities/discover-mcp-server.js";
+import type { createClassifyToolApprovalsActivities } from "../activities/classify-tool-approvals.js";
+
+import type {
+  ConnectMcpServerWorkflowInput,
+  ConnectMcpServerWorkflowOutput,
+  DiscoverMcpServerWorkflowOutput,
+} from "./types.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Activity Proxies
+// ─────────────────────────────────────────────────────────────────────────────
+
+type DiscoverActivities = ReturnType<typeof createDiscoverMcpServerActivities>;
+type ClassifyActivities = ReturnType<typeof createClassifyToolApprovalsActivities>;
+
+const discover = proxyActivities<DiscoverActivities>({
+  startToCloseTimeout: "600s",
+  heartbeatTimeout: "60s",
+  retry: { maximumAttempts: 1 },
+});
+
+function classifyWithTimeout(numTools: number) {
+  const timeoutSec = Math.max(120, (Math.floor(numTools / 40) + 1) * 60);
+  return proxyActivities<ClassifyActivities>({
+    startToCloseTimeout: `${timeoutSec}s`,
+    retry: { maximumAttempts: 2 },
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ConnectMcpServerWorkflow — primary connect flow
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function connectMcpServer(
+  input: ConnectMcpServerWorkflowInput,
+): Promise<ConnectMcpServerWorkflowOutput> {
+  const discovery = await discover.DiscoverMcpServerCapabilities({
+    mcpServerId: input.mcp_server_id,
+    executionContextId: input.execution_context_id ?? null,
+    invokerIdentityAccountId: input.invoker_identity_account_id ?? null,
+  });
+
+  const canReusePreviousApprovals =
+    discovery.newToolsFingerprint !== "" &&
+    discovery.newToolsFingerprint === discovery.previousToolsFingerprint &&
+    discovery.previousToolApprovals.length > 0;
+
+  let toolApprovals: Array<{
+    tool_name: string;
+    requires_approval: boolean;
+    message: string;
+  }>;
+
+  if (canReusePreviousApprovals) {
+    log.info(
+      `Tools unchanged for '${input.mcp_server_id}' ` +
+        `(fingerprint ${discovery.newToolsFingerprint.slice(0, 12)}) — ` +
+        `reusing ${discovery.previousToolApprovals.length} previous approval(s)`,
+    );
+
+    toolApprovals = discovery.previousToolApprovals.map((a) => ({
+      tool_name: a.toolName,
+      requires_approval: a.requiresApproval,
+      message: a.message,
+    }));
+  } else {
+    const classifyInput = {
+      tools: discovery.tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        input_schema: t.inputSchema ?? null,
+      })),
+      serverName: input.mcp_server_id,
+      serverDescription: "",
+      mcpServerId: input.mcp_server_id,
+    };
+
+    const classify = classifyWithTimeout(discovery.tools.length);
+    toolApprovals = await classify.ClassifyToolApprovals(classifyInput);
+  }
+
+  return {
+    tools: discovery.tools.map((t) => ({
+      name: t.name,
+      description: t.description,
+      input_schema: t.inputSchema ?? null,
+    })),
+    resource_templates: discovery.resourceTemplates.map((rt) => ({
+      uri_template: rt.uriTemplate,
+      name: rt.name,
+      description: rt.description,
+      mime_type: rt.mimeType,
+    })),
+    tool_approvals: toolApprovals,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// DiscoverMcpServerWorkflow — legacy backward-compatible wrapper
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function discoverMcpServerLegacy(
+  input: ConnectMcpServerWorkflowInput,
+): Promise<DiscoverMcpServerWorkflowOutput> {
+  const discovery = await discover.DiscoverMcpServerCapabilities({
+    mcpServerId: input.mcp_server_id,
+    executionContextId: input.execution_context_id ?? null,
+    invokerIdentityAccountId: input.invoker_identity_account_id ?? null,
+  });
+
+  return {
+    tools: discovery.tools.map((t) => ({
+      name: t.name,
+      description: t.description,
+      input_schema: t.inputSchema ?? null,
+    })),
+    resource_templates: discovery.resourceTemplates.map((rt) => ({
+      uri_template: rt.uriTemplate,
+      name: rt.name,
+      description: rt.description,
+      mime_type: rt.mimeType,
+    })),
+    previous_tools_fingerprint: discovery.previousToolsFingerprint,
+    previous_tool_approvals: discovery.previousToolApprovals.map((a) => ({
+      tool_name: a.toolName,
+      requires_approval: a.requiresApproval,
+      message: a.message,
+    })),
+    new_tools_fingerprint: discovery.newToolsFingerprint,
+  };
+}