Render the agent's live plan as a checklist card

Handles the new plan envelope from the worker: the stream validator
admits it, the handler upserts one plan content block in place (latest
list wins), and persistence/display carry planItems through to a
PlanChecklist card in the transcript. update_plan joins the hidden
tool names since the card replaces its row.

Claude-Session: https://claude.ai/code/session_01CgaxNAaeD3taGdghbXn17w

Author: Sg312

apps/sim/app/workspace/[workspaceId]/home/components/message-content/components/plan-checklist/index.ts

@@ -0,0 +1 @@
+export { PlanChecklist } from './plan-checklist'

apps/sim/app/workspace/[workspaceId]/home/components/message-content/components/plan-checklist/plan-checklist.tsx

@@ -0,0 +1,49 @@
+import { Check, cn } from '@sim/emcn'
+import type { AgentPlanItem } from '@/lib/mothership/request/types'
+
+interface PlanChecklistProps {
+  items: AgentPlanItem[]
+}
+
+/**
+ * The agent's live plan: one card, updated in place as the worker's
+ * update_plan tool replaces the list. Read-only — progress display, not an
+ * input surface.
+ */
+export function PlanChecklist({ items }: PlanChecklistProps) {
+  if (items.length === 0) return null
+
+  return (
+    <div className='my-1 rounded-[10px] border border-[var(--border)] bg-[var(--bg)] px-3 py-2'>
+      <div className='flex flex-col gap-1'>
+        {items.map((item, index) => (
+          <div key={`${index}-${item.step}`} className='flex items-start gap-2'>
+            <span
+              className={cn(
+                'mt-[3px] flex size-[14px] shrink-0 items-center justify-center rounded-full border',
+                item.status === 'done' && 'border-[var(--brand-accent)] bg-[var(--brand-accent)]',
+                item.status === 'active' && 'border-[var(--text-primary)]',
+                item.status === 'pending' && 'border-[var(--border-1)]'
+              )}
+            >
+              {item.status === 'done' && <Check className='size-[9px] text-[var(--bg)]' />}
+              {item.status === 'active' && (
+                <span className='size-[6px] animate-pulse rounded-full bg-[var(--text-primary)]' />
+              )}
+            </span>
+            <span
+              className={cn(
+                'font-[family-name:var(--font-inter)] text-[13px] leading-[19px]',
+                item.status === 'done' && 'text-[var(--text-tertiary)] line-through',
+                item.status === 'active' && 'font-medium text-[var(--text-primary)]',
+                item.status === 'pending' && 'text-[var(--text-secondary)]'
+              )}
+            >
+              {item.step}
+            </span>
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}

apps/sim/app/workspace/[workspaceId]/home/components/message-content/message-content.tsx

@@ -12,6 +12,7 @@ import {
 } from 'react'
 import { cn } from '@sim/emcn'
 import { PrepareFileEdit, Read as ReadTool } from '@/lib/mothership/generated/tool-catalog-v1'
+import type { AgentPlanItem } from '@/lib/mothership/request/types'
 import { isToolHiddenInUi } from '@/lib/mothership/tools/client/hidden-tools'
 import { resolveToolDisplay } from '@/lib/mothership/tools/client/store-utils'
 import { ClientToolCallState } from '@/lib/mothership/tools/client/tool-call-state'
@@ -21,6 +22,7 @@ import {
   humanizeToolName,
 } from '@/lib/mothership/tools/tool-display'
 import { useChatSurface } from '@/app/workspace/[workspaceId]/home/components/chat-surface-context'
+import { PlanChecklist } from '@/app/workspace/[workspaceId]/home/components/message-content/components/plan-checklist'
 import type { CredentialSubmissionPayload } from '@/app/workspace/[workspaceId]/home/components/message-content/components/special-tags'
 import { useCustomBlockOverlayVersion } from '@/blocks/custom/client-overlay'
 import type { ContentBlock, OptionItem, ToolCallData } from '../../types'
@@ -74,7 +76,17 @@ interface StoppedSegment {
   type: 'stopped'
 }
 
-type MessageSegment = TextSegment | AgentGroupSegment | OptionsSegment | StoppedSegment
+interface PlanSegment {
+  type: 'plan'
+  items: AgentPlanItem[]
+}
+
+type MessageSegment =
+  | TextSegment
+  | AgentGroupSegment
+  | OptionsSegment
+  | StoppedSegment
+  | PlanSegment
 
 function getAgentGroupActivityKey(items: AgentGroupItem[]): string {
   return items
@@ -115,6 +127,9 @@ function getVisibleStreamActivityKey(segments: MessageSegment[]): string {
         return `options:${segment.items.map((item) => `${item.id}:${item.label.length}`).join(',')}`
       }
       if (segment.type === 'stopped') return 'stopped'
+      if (segment.type === 'plan') {
+        return `plan:${segment.items.map((item) => `${item.status}:${item.step.length}`).join(',')}`
+      }
       return [
         'agent',
         segment.id,
@@ -462,6 +477,12 @@ function parseBlocksWithSpanTree(blocks: ContentBlock[]): MessageSegment[] {
       continue
     }
 
+    if (block.type === 'plan') {
+      if (!block.planItems?.length) continue
+      segments.push({ type: 'plan', items: block.planItems })
+      continue
+    }
+
     if (block.type === 'subagent_end') {
       if (block.spanId) {
         const g = groupsBySpanId.get(block.spanId)
@@ -713,6 +734,13 @@ function parseBlocksLegacy(blocks: ContentBlock[]): MessageSegment[] {
       continue
     }
 
+    if (block.type === 'plan') {
+      if (!block.planItems?.length) continue
+      flushLanes()
+      segments.push({ type: 'plan', items: block.planItems })
+      continue
+    }
+
     if (block.type === 'subagent_end') {
       if (block.parentToolCallId) {
         for (const [key, g] of groupsByKey) {
@@ -1046,6 +1074,8 @@ function MessageContentInner({
                   <Options items={segment.items} onSelect={onOptionSelect} />
                 </div>
               )
+            case 'plan':
+              return <PlanChecklist key={`plan-${i}`} items={segment.items} />
             // The stopped row renders in the tail region below, in the
             // shimmer's place — a stop while the shimmer is visible must read
             // as an in-place replacement, not the shimmer vanishing from the

apps/sim/app/workspace/[workspaceId]/home/types.ts

@@ -116,12 +116,15 @@ export const ContentBlockType = {
   subagent_thinking: 'subagent_thinking',
   options: 'options',
   stopped: 'stopped',
+  plan: 'plan',
 } as const
 export type ContentBlockType = (typeof ContentBlockType)[keyof typeof ContentBlockType]
 
 export interface ContentBlock {
   type: ContentBlockType
   content?: string
+  /** The agent's plan checklist (plan blocks only); whole-list, latest wins. */
+  planItems?: import('@/lib/mothership/request/types').AgentPlanItem[]
   subagent?: string
   /** Orchestrator-chosen display name for a `subagent` start block (shown instead of the generic agent label). */
   subagentName?: string

apps/sim/lib/mothership/chat/display-message.ts

@@ -66,6 +66,9 @@ function toDisplayBlock(block: PersistedContentBlock): ContentBlock | undefined
 
 function toDisplayBlockBody(block: PersistedContentBlock): ContentBlock | undefined {
   switch (block.type) {
+    case 'plan':
+      if (!block.planItems?.length) return undefined
+      return { type: ContentBlockType.plan, planItems: block.planItems }
     case MothershipStreamV1EventType.text:
       if (block.lane === 'subagent') {
         if (block.channel === 'thinking') {

apps/sim/lib/mothership/chat/persisted-message.ts

@@ -38,7 +38,7 @@ interface PersistedToolCall {
 }
 
 export interface PersistedContentBlock {
-  type: MothershipStreamV1EventType
+  type: MothershipStreamV1EventType | 'plan'
   lane?: MothershipStreamV1StreamScope['lane']
   /**
    * Subagent name on lane text blocks. The span-tree parser needs a name to
@@ -56,6 +56,8 @@ export interface PersistedContentBlock {
   /** Orchestrator-chosen display name on a subagent start block. */
   name?: string
   toolCall?: PersistedToolCall
+  /** The agent's plan checklist (plan blocks only). */
+  planItems?: import('@/lib/mothership/request/types').AgentPlanItem[]
   timestamp?: number
   endedAt?: number
   parentToolCallId?: string
@@ -227,6 +229,8 @@ function mapContentBlock(block: ContentBlock): PersistedContentBlock {
 
 function mapContentBlockBody(block: ContentBlock): PersistedContentBlock {
   switch (block.type) {
+    case 'plan':
+      return { type: 'plan', ...(block.planItems ? { planItems: block.planItems } : {}) }
     case 'text':
       return {
         type: MothershipStreamV1EventType.text,

apps/sim/lib/mothership/generated/protocol.ts

@@ -137,7 +137,7 @@ export interface ExecuteMessage {
  */
 export interface StreamEnvelope {
   v: 1;
-  type: "session" | "text" | "tool" | "span" | "run" | "resource" | "error" | "complete";
+  type: "session" | "text" | "tool" | "span" | "run" | "resource" | "plan" | "error" | "complete";
   seq: number;
   /** ISO timestamp. */
   ts: string;
@@ -149,6 +149,12 @@ export interface StreamEnvelope {
   payload: Record<string, unknown>;
 }
 
+/** One step of the agent's visible plan (the update_plan tool's whole-list payload). */
+export interface PlanItem {
+  step: string;
+  status: "pending" | "active" | "done";
+}
+
 /** One subagent lane: keyed by the delegating tool call; agentId/spanId identify the lane. */
 export interface StreamScope {
   lane: "subagent";

apps/sim/lib/mothership/request/handlers/index.ts

@@ -3,6 +3,7 @@ import { MothershipStreamV1EventType } from '@/lib/mothership/generated/mothersh
 import type { StreamEvent, StreamingContext } from '@/lib/mothership/request/types'
 import { handleCompleteEvent } from './complete'
 import { handleErrorEvent } from './error'
+import { handlePlanEvent } from './plan'
 import { handleResourceEvent } from './resource'
 import { handleRunEvent } from './run'
 import { handleSessionEvent } from './session'
@@ -25,6 +26,7 @@ export const sseHandlers: Record<string, StreamHandler> = {
   [MothershipStreamV1EventType.complete]: handleCompleteEvent,
   [MothershipStreamV1EventType.error]: handleErrorEvent,
   [MothershipStreamV1EventType.span]: handleSpanEvent,
+  plan: handlePlanEvent,
 }
 
 export const subAgentHandlers: Record<string, StreamHandler> = {

apps/sim/lib/mothership/request/handlers/plan.test.ts

@@ -0,0 +1,42 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import { handlePlanEvent } from '@/lib/mothership/request/handlers/plan'
+import type { StreamEvent, StreamingContext } from '@/lib/mothership/request/types'
+
+function contextWith(blocks: StreamingContext['contentBlocks']): StreamingContext {
+  return { contentBlocks: blocks } as StreamingContext
+}
+
+const planEvent = (items: unknown): StreamEvent =>
+  ({ type: 'plan', payload: { items } }) as unknown as StreamEvent
+
+describe('handlePlanEvent', () => {
+  it('creates one plan block and updates it in place on later events', () => {
+    const context = contextWith([])
+    handlePlanEvent(planEvent([{ step: 'a', status: 'active' }]), context, {} as never, {} as never)
+    expect(context.contentBlocks).toHaveLength(1)
+    expect(context.contentBlocks[0].planItems).toEqual([{ step: 'a', status: 'active' }])
+
+    handlePlanEvent(
+      planEvent([
+        { step: 'a', status: 'done' },
+        { step: 'b', status: 'active' },
+      ]),
+      context,
+      {} as never,
+      {} as never
+    )
+    expect(context.contentBlocks).toHaveLength(1)
+    expect(context.contentBlocks[0].planItems).toHaveLength(2)
+    expect(context.contentBlocks[0].planItems?.[0].status).toBe('done')
+  })
+
+  it('ignores malformed payloads', () => {
+    const context = contextWith([])
+    handlePlanEvent(planEvent(undefined), context, {} as never, {} as never)
+    handlePlanEvent(planEvent([]), context, {} as never, {} as never)
+    expect(context.contentBlocks).toHaveLength(0)
+  })
+})

apps/sim/lib/mothership/request/handlers/plan.ts

@@ -0,0 +1,28 @@
+import type { AgentPlanItem, StreamEvent, StreamingContext } from '@/lib/mothership/request/types'
+import { ContentBlockType } from '@/lib/mothership/request/types'
+import type { StreamHandler } from './types'
+import { addContentBlock } from './types'
+
+/**
+ * The agent's visible plan: whole-list replacement semantics (the worker's
+ * update_plan tool sends the complete list every call). One plan block per
+ * message, updated in place so the checklist renders live instead of stacking
+ * a card per update.
+ */
+export const handlePlanEvent: StreamHandler = (event: StreamEvent, context: StreamingContext) => {
+  const items = (event.payload as { items?: AgentPlanItem[] } | undefined)?.items
+  if (!Array.isArray(items) || items.length === 0) return
+
+  for (let i = context.contentBlocks.length - 1; i >= 0; i--) {
+    const block = context.contentBlocks[i]
+    if (block.type === ContentBlockType.plan) {
+      block.planItems = items
+      block.endedAt = Date.now()
+      return
+    }
+  }
+  addContentBlock(context, {
+    type: ContentBlockType.plan,
+    planItems: items,
+  })
+}