feat(canvas): workflows attached to canvases

A workflow canvas = a canvas artifact + a PostHog workflow (HogFlow) + the
link between them. The unified canvas generation prompt gains a workflow
intent branch: describing an ongoing action ("Send an email after signup")
makes the build agent draft a workflow over the PostHog MCP workflows-*
tools, author email templates with neutral branding, test every branch,
and publish an observability canvas from a baked-in starter board (health
or engagement) instead of authoring React from scratch.

- Workflow link primitive: the agent-side hooks pair a workflows-create/get
  result with the canvas publish and emit _posthog/workflow_built; the app
  writes the link into the dashboard row meta (setWorkflow) and stamps
  templateId "workflow" (lightning icon in Artifacts, workflow badge in the
  canvas header, edit-time prompt resolution).
- Go-live gating: workflows-enable / run-batch / schedule-create /
  update-schedule always raise an "Approve & publish" card - even in auto
  mode, with no always-allow, never persisted - and the cloud agent-server
  parks (never auto-approves) such requests when no client is reachable.
- Generating state now mirrors the agent's live to-do list (StepList) and
  flips optimistically on submit; a terminal cloud run now clears
  "Generating" even while the chat session lingers connected.
- Hero suggestions gain workflow ideas; repo-less tasks hide the diff chip.

Generated-By: PostHog Code
Task-Id: 3b50883f-cab5-443a-8b92-3d0c948688da

Author: mayteio

packages/agent/src/acp-extensions.ts

@@ -75,6 +75,11 @@ export const POSTHOG_NOTIFICATIONS = {
   /** PostHog products used during a turn (derived from MCP exec calls) */
   RESOURCES_USED: "_posthog/resources_used",
 
+  /** A workflow build linked a PostHog workflow to its canvas (derived from the
+   *  workflows-create result + the canvas publish call). The host writes the
+   *  link onto the dashboard row (the agent can't persist it itself). */
+  WORKFLOW_BUILT: "_posthog/workflow_built",
+
   /** Response to a relayed permission request (plan approval, question) */
   PERMISSION_RESPONSE: "_posthog/permission_response",
 
@@ -93,6 +98,19 @@ export const POSTHOG_NOTIFICATIONS = {
   MCP_RESPONSE: "_posthog/mcp_response",
 } as const;
 
+/**
+ * Payload of a `_posthog/workflow_built` notification: the PostHog workflow a
+ * build attached to its canvas. `dashboardId` is the canvas the workflow
+ * tracks; the host writes the rest onto that row's meta.
+ */
+export interface WorkflowBuiltPayload {
+  dashboardId: string;
+  workflowId: string;
+  workflowStatus?: string;
+  workflowName?: string;
+  workflowType?: string;
+}
+
 export type NativeGoalState = {
   objective: string;
   status:

packages/agent/src/adapters/claude/claude-agent.ts

@@ -96,7 +96,7 @@ import {
   type TaskState,
   taskStateToPlanEntries,
 } from "./conversion/task-state";
-import type { EnrichedReadCache } from "./hooks";
+import type { EnrichedReadCache, WorkflowBuiltSignal } from "./hooks";
 import { createLocalToolsMcpServer } from "./mcp/local-tools";
 import {
   clearMcpToolMetadataCache,
@@ -1975,6 +1975,7 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
       settingsManager,
       onModeChange: this.createOnModeChange(),
       onPostHogResourceUsed: this.createOnPostHogResourceUsed(),
+      onWorkflowBuilt: this.createOnWorkflowBuilt(),
       onProcessSpawned: this.options?.onProcessSpawned,
       onProcessExited: this.options?.onProcessExited,
       effort,
@@ -2277,6 +2278,19 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
     };
   }
 
+  /** Emits the workflow link (workflow ↔ canvas) the moment a build forms it,
+   *  so the host can persist it onto the dashboard row (the agent has no MCP
+   *  tool to write it itself). Deterministic - derived from the build's tool
+   *  calls, no model cooperation required. */
+  private createOnWorkflowBuilt() {
+    return (signal: WorkflowBuiltSignal) => {
+      void this.client.extNotification(POSTHOG_NOTIFICATIONS.WORKFLOW_BUILT, {
+        sessionId: this.sessionId,
+        ...signal,
+      });
+    };
+  }
+
   /** Adds products to the session-wide set and emits any newly-seen ones.
    *  Session-wide dedup: only the first use of a product emits, so the client's
    *  persistent list shows each chip once across all turns. */

packages/agent/src/adapters/claude/hooks.test.ts

@@ -10,12 +10,14 @@ vi.mock("../../enrichment/file-enricher", () => ({
 import { Logger } from "../../utils/logger";
 import type { TaskState } from "./conversion/task-state";
 import {
+  createPostToolUseHook,
   createPreToolUseHook,
   createReadEnrichmentHook,
   createReadImageGuardHook,
   createSignedCommitGuardHook,
   createTaskHook,
   type EnrichedReadCache,
+  type WorkflowBuiltSignal,
 } from "./hooks";
 import type {
   PermissionCheckResult,
@@ -694,3 +696,105 @@ describe("createTaskHook", () => {
     expect(state.get("t1")?.subject).toBe("Fix bug");
   });
 });
+
+describe("createPostToolUseHook workflow link", () => {
+  function execInput(command: string, tool_response?: unknown): HookInput {
+    return {
+      hook_event_name: "PostToolUse",
+      tool_name: "mcp__posthog__exec",
+      tool_input: { command },
+      tool_response,
+    } as unknown as HookInput;
+  }
+
+  test("pairs a workflows-create result with the canvas publish it precedes", async () => {
+    const signals: WorkflowBuiltSignal[] = [];
+    const hook = createPostToolUseHook({
+      onWorkflowBuilt: (s) => signals.push(s),
+    });
+
+    await hook(
+      execInput(
+        "call --json workflows-create {}",
+        JSON.stringify({
+          id: "wf-42",
+          status: "draft",
+          name: "Welcome sequence",
+        }),
+      ),
+      "tu1",
+      { signal: new AbortController().signal },
+    );
+    await hook(
+      execInput(
+        'call --json desktop-file-system-canvas-partial-update {"id":"dash-7","code":"export default () => null;"}',
+      ),
+      "tu2",
+      { signal: new AbortController().signal },
+    );
+
+    expect(signals).toEqual([
+      {
+        dashboardId: "dash-7",
+        workflowId: "wf-42",
+        workflowStatus: "draft",
+        workflowName: "Welcome sequence",
+      },
+    ]);
+  });
+
+  test("links an existing workflow fetched with workflows-get", async () => {
+    const signals: WorkflowBuiltSignal[] = [];
+    const hook = createPostToolUseHook({
+      onWorkflowBuilt: (s) => signals.push(s),
+    });
+
+    // Attach-existing flow: no workflows-create, just a workflows-get on the
+    // target, then the canvas publish.
+    await hook(
+      execInput(
+        "call --json workflows-get {}",
+        JSON.stringify({
+          id: "wf-existing",
+          status: "active",
+          name: "Welcome sequence",
+        }),
+      ),
+      "tu1",
+      { signal: new AbortController().signal },
+    );
+    await hook(
+      execInput(
+        'call --json desktop-file-system-canvas-partial-update {"id":"dash-9","code":"x"}',
+      ),
+      "tu2",
+      { signal: new AbortController().signal },
+    );
+
+    expect(signals).toEqual([
+      {
+        dashboardId: "dash-9",
+        workflowId: "wf-existing",
+        workflowStatus: "active",
+        workflowName: "Welcome sequence",
+      },
+    ]);
+  });
+
+  test("does not fire on a canvas publish with no workflow created first", async () => {
+    const signals: WorkflowBuiltSignal[] = [];
+    const hook = createPostToolUseHook({
+      onWorkflowBuilt: (s) => signals.push(s),
+    });
+
+    await hook(
+      execInput(
+        'call --json desktop-file-system-canvas-partial-update {"id":"dash-7","code":"x"}',
+      ),
+      "tu1",
+      { signal: new AbortController().signal },
+    );
+
+    expect(signals).toEqual([]);
+  });
+});

packages/agent/src/adapters/claude/hooks.ts

@@ -11,6 +11,7 @@ import { gitSubcommand } from "./git-command";
 import { neutralizeUnprocessableImages } from "./image-sanitization";
 import {
   extractPostHogSubTool,
+  isPostHogAlwaysGatedSubTool,
   isPostHogDestructiveSubTool,
   isPostHogExecTool,
 } from "./permissions/posthog-exec-gate";
@@ -55,6 +56,66 @@ function extractTextFromToolResponse(response: unknown): string | null {
   return null;
 }
 
+// Parse the first JSON object embedded in a string (e.g. the `{...}` arg of a
+// PostHog `call --json <tool> {...}` command, or a JSON tool result). Returns
+// null when there's no parseable object.
+function parseEmbeddedJsonObject(text: string): Record<string, unknown> | null {
+  const start = text.indexOf("{");
+  if (start === -1) return null;
+  try {
+    const parsed = JSON.parse(text.slice(start));
+    return parsed && typeof parsed === "object"
+      ? (parsed as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+// The `id` (dashboard id) a workflow build's canvas publish targets, read from
+// the `desktop-file-system-canvas-partial-update` command's JSON arg.
+function parseCanvasPublishDashboardId(toolInput: unknown): string | null {
+  const command = (toolInput as { command?: unknown })?.command;
+  if (typeof command !== "string") return null;
+  const arg = parseEmbeddedJsonObject(command);
+  return arg && typeof arg.id === "string" ? arg.id : null;
+}
+
+// The workflow id + status from a `workflows-create` result. The result JSON may
+// be the workflow itself or wrapped, so look under common envelopes too. Best
+// effort - returns null if no workflow id is present.
+function parseWorkflowFromResponse(response: unknown): {
+  workflowId: string;
+  workflowStatus?: string;
+  workflowName?: string;
+} | null {
+  const text = extractTextFromToolResponse(response);
+  if (!text) return null;
+  const root = parseEmbeddedJsonObject(text);
+  if (!root) return null;
+  for (const candidate of [
+    root,
+    root.workflow,
+    root.result,
+    root.data,
+  ] as Record<string, unknown>[]) {
+    if (candidate && typeof candidate === "object") {
+      const id = (candidate as { id?: unknown }).id;
+      if (typeof id === "string" && id) {
+        const status = (candidate as { status?: unknown }).status;
+        const name = (candidate as { name?: unknown }).name;
+        return {
+          workflowId: id,
+          workflowStatus: typeof status === "string" ? status : undefined,
+          workflowName:
+            typeof name === "string" && name.trim() ? name : undefined,
+        };
+      }
+    }
+  }
+  return null;
+}
+
 /**
  * Per-toolUseId handoff from the PostToolUse hook to `toolUpdateFromToolResult`.
  * Can't emit a standalone `tool_call_update` because the SDK emits its own
@@ -198,19 +259,39 @@ export const createTaskHook =
 
 export type OnModeChange = (mode: CodeExecutionMode) => Promise<void>;
 
+// The link a workflow build forms: the workflow (from a workflows-create
+// result) tracked by the canvas it publishes (dashboardId from the publish call).
+export interface WorkflowBuiltSignal {
+  dashboardId: string;
+  workflowId: string;
+  workflowStatus?: string;
+  workflowName?: string;
+}
+
 interface CreatePostToolUseHookParams {
   onModeChange?: OnModeChange;
   /** Called after a PostHog MCP `call` exec executes, with the sub-tool name
    *  and the raw command (the command embeds the SQL for execute-sql). */
   onPostHogResourceUsed?: (subTool: string, commandText?: string) => void;
+  /** Called once a workflow build has both created a workflow and published
+   *  its canvas - the host then writes the link onto the dashboard row. */
+  onWorkflowBuilt?: (signal: WorkflowBuiltSignal) => void;
 }
 
-export const createPostToolUseHook =
-  ({
-    onModeChange,
-    onPostHogResourceUsed,
-  }: CreatePostToolUseHookParams): HookCallback =>
-  async (
+export const createPostToolUseHook = ({
+  onModeChange,
+  onPostHogResourceUsed,
+  onWorkflowBuilt,
+}: CreatePostToolUseHookParams): HookCallback => {
+  // Session-scoped accumulation: the workflow is created before the canvas is
+  // published, so remember the last workflow this run created and fire the
+  // link the moment the canvas publish (which carries the dashboardId) lands.
+  let pendingWorkflow: {
+    workflowId: string;
+    workflowStatus?: string;
+    workflowName?: string;
+  } | null = null;
+  return async (
     input: HookInput,
     toolUseID: string | undefined,
   ): Promise<{ continue: boolean }> => {
@@ -235,6 +316,28 @@ export const createPostToolUseHook =
         }
       }
 
+      // Observe a workflow build (deterministic, no model cooperation): the
+      // workflow this run last created OR fetched is the one the canvas tracks;
+      // the subsequent `desktop-file-system-canvas-partial-update` carries the
+      // dashboard it publishes to. Pair them into the link the host persists.
+      // Capturing `workflows-get` (not just `workflows-create`) is what lets a
+      // build attach a canvas to an EXISTING workflow, not only a new one.
+      if (onWorkflowBuilt && isPostHogExecTool(toolName)) {
+        const subTool = extractPostHogSubTool(input.tool_input);
+        if (subTool === "workflows-create" || subTool === "workflows-get") {
+          const workflow = parseWorkflowFromResponse(input.tool_response);
+          if (workflow) pendingWorkflow = workflow;
+        } else if (
+          subTool === "desktop-file-system-canvas-partial-update" &&
+          pendingWorkflow
+        ) {
+          const dashboardId = parseCanvasPublishDashboardId(input.tool_input);
+          if (dashboardId) {
+            onWorkflowBuilt({ dashboardId, ...pendingWorkflow });
+          }
+        }
+      }
+
       if (toolUseID) {
         const onPostToolUseHook =
           toolUseCallbacks[toolUseID]?.onPostToolUseHook;
@@ -250,6 +353,7 @@ export const createPostToolUseHook =
     }
     return { continue: true };
   };
+};
 
 /**
  * Rewrites Agent tool calls targeting built-in subagent types to use our custom
@@ -407,13 +511,19 @@ export const createPreToolUseHook =
     // so the SDK invokes canUseTool.
     if (permissionCheck.decision === "allow" && isPostHogExecTool(toolName)) {
       const subTool = extractPostHogSubTool(toolInput);
-      if (subTool && isPostHogDestructiveSubTool(subTool)) {
+      // Force "ask" (→ canUseTool) for destructive sub-tools AND for go-live
+      // workflow tools, so a settings allow-rule can't skip either gate.
+      if (
+        subTool &&
+        (isPostHogDestructiveSubTool(subTool) ||
+          isPostHogAlwaysGatedSubTool(subTool))
+      ) {
         return {
           continue: true,
           hookSpecificOutput: {
             hookEventName: "PreToolUse" as const,
             permissionDecision: "ask" as const,
-            permissionDecisionReason: `Destructive PostHog sub-tool '${subTool}' requires explicit approval`,
+            permissionDecisionReason: `PostHog sub-tool '${subTool}' requires explicit approval`,
           },
         };
       }