feat(workflow): expose read-only app snapshots

Waishnav · Waishnav · commit d3643e8b40c3 · 2026-07-25T20:43:46.000Z
diff --git a/src/server.ts b/src/server.ts
@@ -48,6 +48,8 @@ import { createWorkspaceStore } from "./workspace-store.js";
 import { formatAgentsPath, WorkspaceRegistry } from "./workspaces.js";
 import { summarizeLocalAgentProfile } from "./local-agent-profiles.js";
 import { registerWorkflowTools } from "./workflow-tools.js";
+import { createWorkflowStore } from "./workflow-store.js";
+import { loadActiveWorkflowSummaries } from "./workflow-ui.js";
 import {
   formatLocalAgentProviderAvailabilitySummary,
   getLocalAgentProviderAvailabilitySnapshot,
@@ -264,6 +266,24 @@ const workspaceAvailableAgentsFileOutputSchema = z.object({
   path: z.string(),
 });
 
+const workflowCallCountsOutputSchema = z.object({
+  running: z.number(),
+  completed: z.number(),
+  cached: z.number(),
+  failed: z.number(),
+  cancelled: z.number(),
+  observed: z.number(),
+});
+
+const workflowRunSummaryOutputSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  status: z.enum(["starting", "running", "completed", "failed", "cancelled"]),
+  currentPhase: z.string().optional(),
+  calls: workflowCallCountsOutputSchema,
+  updatedAt: z.string(),
+});
+
 const reviewFileOutputSchema = z.object({
   path: z.string(),
   previousPath: z.string().optional(),
@@ -779,6 +799,7 @@ function createMcpServer(
         agentProviders: z.array(workspaceLocalAgentProviderOutputSchema),
         agents: z.array(workspaceLocalAgentOutputSchema),
         skillDiagnostics: z.array(z.unknown()),
+        activeWorkflows: z.array(workflowRunSummaryOutputSchema),
         instruction: z.string(),
       },
       ...toolWidgetDescriptorMeta(config, "workspace"),
@@ -817,6 +838,16 @@ function createMcpServer(
       const availableAgentsFileOutputs = availableAgentsFiles.map((file) => ({
         path: formatAgentsPath(file.path, workspace.root),
       }));
+      const activeWorkflows = config.subagents
+        ? (() => {
+            const workflowStore = createWorkflowStore(config);
+            try {
+              return loadActiveWorkflowSummaries(workflowStore, workspace.root);
+            } finally {
+              workflowStore.close();
+            }
+          })()
+        : [];
       const instruction = config.skillsEnabled
         ? "Use this workspaceId in all subsequent tool calls for this project. Do not call open_workspace again for this same folder unless this workspaceId stops working, the user asks to reopen, or you switch to a different folder/worktree. Follow loaded agentsFiles instructions. Before working under a path listed in availableAgentsFiles, read that instruction file. When a task matches an available skill in skills, read its path before proceeding."
         : "Use this workspaceId in all subsequent tool calls for this project. Do not call open_workspace again for this same folder unless this workspaceId stops working, the user asks to reopen, or you switch to a different folder/worktree. Follow loaded agentsFiles instructions. Before working under a path listed in availableAgentsFiles, read that instruction file.";
@@ -870,6 +901,7 @@ function createMcpServer(
               agentsFiles: loadedAgentsFiles.length,
               availableAgentsFiles: availableAgentsFileOutputs.length,
               skills: visibleSkills.length,
+              activeWorkflows: activeWorkflows.length,
               agentProviders: visibleAgentProviders.length,
               agents: visibleAgents.length,
               skillDiagnostics: workspace.skillDiagnostics.length,
@@ -885,6 +917,7 @@ function createMcpServer(
           agentsFiles: loadedAgentsFiles,
           availableAgentsFiles: availableAgentsFileOutputs,
           skills: visibleSkills,
+          activeWorkflows,
           agentProviders: visibleAgentProviders,
           agents: visibleAgents,
           skillDiagnostics: workspace.skillDiagnostics,
diff --git a/src/workflow-tools.ts b/src/workflow-tools.ts
@@ -34,6 +34,14 @@ import {
   WorkflowNotFoundError,
   WorkflowStoredDataError,
 } from "./workflow-errors.js";
+import {
+  loadWorkflowUiCallDetail,
+  loadWorkflowUiProject,
+  loadWorkflowUiRun,
+} from "./workflow-ui.js";
+
+const WORKSPACE_APP_URI = "ui://devspace/workspace-app.html";
+const WORKFLOW_UI_WAIT_MAX_MS = 30_000;
 
 const WORKFLOW_API_CHEATSHEET = `
 Workflow scripts (JS only):
@@ -84,7 +92,7 @@ export function registerWorkflowTools(
           .describe(`Ms to wait for early completion (default 2000, max ${WORKFLOW_MCP_YIELD_MS}).`),
       },
       annotations: { readOnlyHint: false },
-      _meta: {},
+      _meta: workflowWidgetMeta(config),
     },
     async ({ workspaceId, script, name, scriptPath, resumeFromRunId, args, yieldTimeMs }) => {
       const workspace = workspaces.getWorkspace(workspaceId);
@@ -200,7 +208,7 @@ export function registerWorkflowTools(
 
         const yieldMs = yieldTimeMs ?? 2_000;
         const page = await yieldEvents(store, run.id, 0, yieldMs);
-        return toolResult(page);
+        return toolResult(page, "run_workflow");
       } catch (error) {
         if (isWorkflowOperationError(error)) return workflowToolError(error);
         throw error;
@@ -228,14 +236,14 @@ export function registerWorkflowTools(
           .describe(`Long-poll ms (default 0, max ${WORKFLOW_MCP_YIELD_MS}).`),
       },
       annotations: { readOnlyHint: true },
-      _meta: {},
+      _meta: workflowWidgetMeta(config),
     },
     async ({ runId, sinceSeq, yieldTimeMs }) => {
       const store = createWorkflowStore(config);
       try {
         if (!store.getRun(runId)) throw new WorkflowNotFoundError(runId);
         const page = await yieldEvents(store, runId, sinceSeq ?? 0, yieldTimeMs ?? 0);
-        return toolResult(page);
+        return toolResult(page, "workflow_status");
       } catch (error) {
         if (isWorkflowOperationError(error)) return workflowToolError(error);
         throw error;
@@ -284,7 +292,104 @@ export function registerWorkflowTools(
     },
   );
 
+  if (config.widgets !== "off") {
+    registerWorkflowUiTools(server, config, workspaces);
   }
+}
+
+function registerWorkflowUiTools(
+  server: McpServer,
+  config: ServerConfig,
+  workspaces: WorkspaceRegistry,
+): void {
+  registerAppTool(
+    server,
+    "workspace_workflow_activity",
+    {
+      title: "Workspace workflow activity",
+      description: "Read-only workflow activity for the DevSpace app.",
+      inputSchema: {
+        workspaceId: z.string(),
+        knownVersion: z.string().optional(),
+        waitMs: z.number().int().min(0).max(WORKFLOW_UI_WAIT_MAX_MS).optional(),
+      },
+      annotations: { readOnlyHint: true },
+      _meta: appOnlyToolMeta(),
+    },
+    async ({ workspaceId, knownVersion, waitMs }) => {
+      const workspace = workspaces.getWorkspace(workspaceId);
+      const store = createWorkflowStore(config);
+      try {
+        const project = await waitForProjectSnapshot(
+          store,
+          workspace.root,
+          knownVersion,
+          waitMs ?? 0,
+        );
+        return appToolResult({ workspaceId, project });
+      } finally {
+        store.close();
+      }
+    },
+  );
+
+  registerAppTool(
+    server,
+    "workflow_ui_snapshot",
+    {
+      title: "Workflow UI snapshot",
+      description: "Read-only workflow snapshot for the DevSpace app.",
+      inputSchema: {
+        runId: z.string(),
+        knownVersion: z.string().optional(),
+        waitMs: z.number().int().min(0).max(WORKFLOW_UI_WAIT_MAX_MS).optional(),
+      },
+      annotations: { readOnlyHint: true },
+      _meta: appOnlyToolMeta(),
+    },
+    async ({ runId, knownVersion, waitMs }) => {
+      const store = createWorkflowStore(config);
+      try {
+        const run = await waitForRunSnapshot(store, runId, knownVersion, waitMs ?? 0);
+        if (!run) throw new WorkflowNotFoundError(runId);
+        return appToolResult({ run });
+      } finally {
+        store.close();
+      }
+    },
+  );
+
+  registerAppTool(
+    server,
+    "workflow_ui_call_detail",
+    {
+      title: "Workflow call detail",
+      description: "Read-only workflow call detail for the DevSpace app.",
+      inputSchema: {
+        runId: z.string(),
+        callIndex: z.number().int().min(0),
+      },
+      annotations: { readOnlyHint: true },
+      _meta: appOnlyToolMeta(),
+    },
+    async ({ runId, callIndex }) => {
+      const store = createWorkflowStore(config);
+      try {
+        if (!store.getRun(runId)) throw new WorkflowNotFoundError(runId);
+        const call = loadWorkflowUiCallDetail(store, runId, callIndex);
+        if (!call) {
+          throw new InvalidWorkflowInputError({
+            code: "invalid_argument",
+            message: `Unknown workflow agent call: ${runId}#${callIndex}`,
+          });
+        }
+        return appToolResult({ call });
+      } finally {
+        store.close();
+      }
+    },
+  );
+}
 
 async function yieldEvents(
   store: ReturnType<typeof createWorkflowStore>,
@@ -329,7 +434,7 @@ function toolResult(page: {
   nextSeq: number;
   terminal: boolean;
   callSummary: ReturnType<typeof summarizeCalls>;
-}) {
+}, tool: "run_workflow" | "workflow_status") {
   const payload = {
     runId: page.run.id,
     status: page.run.status,
@@ -354,9 +459,74 @@ function toolResult(page: {
   return {
     content: [{ type: "text" as const, text: JSON.stringify(payload, null, 2) }],
     structuredContent: payload,
+    _meta: {
+      tool,
+      card: {
+        runId: page.run.id,
+        status: page.run.status,
+        name: page.run.name,
+      },
+    },
+  };
+}
+
+function workflowWidgetMeta(config: ServerConfig) {
+  if (config.widgets !== "full") return {};
+  return {
+    ui: {
+      resourceUri: WORKSPACE_APP_URI,
+      visibility: ["model"] as const,
+    },
+  };
+}
+
+function appOnlyToolMeta() {
+  return {
+    ui: {
+      visibility: ["app"] as const,
+    },
   };
 }
 
+function appToolResult(structuredContent: Record<string, unknown>) {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(structuredContent) }],
+    structuredContent,
+  };
+}
+
+async function waitForProjectSnapshot(
+  store: ReturnType<typeof createWorkflowStore>,
+  workspaceRoot: string,
+  knownVersion: string | undefined,
+  waitMs: number,
+) {
+  const deadline = Date.now() + Math.min(waitMs, WORKFLOW_UI_WAIT_MAX_MS);
+  for (;;) {
+    const project = loadWorkflowUiProject(store, workspaceRoot);
+    if (!knownVersion || project.version !== knownVersion || Date.now() >= deadline) {
+      return project;
+    }
+    await sleep(250);
+  }
+}
+
+async function waitForRunSnapshot(
+  store: ReturnType<typeof createWorkflowStore>,
+  runId: string,
+  knownVersion: string | undefined,
+  waitMs: number,
+) {
+  const deadline = Date.now() + Math.min(waitMs, WORKFLOW_UI_WAIT_MAX_MS);
+  for (;;) {
+    const run = loadWorkflowUiRun(store, runId);
+    if (!run || !knownVersion || run.version !== knownVersion || Date.now() >= deadline) {
+      return run;
+    }
+    await sleep(250);
+  }
+}
+
 function summarizeCalls(calls: ReturnType<ReturnType<typeof createWorkflowStore>["listAgentCalls"]>) {
   return {
     reused: calls.filter((call) => call.fromCache).length,
