notify_session_progress

Instructions

Implementation Reference

• src/server/mcp-tools.ts:66-132 (handler)

  The main handler for 'notify_session_progress' tool. Registers the tool with MCP server, defines Zod input schema (sessionId, summary, detail, category, progress, filesChanged, toolsUsed), creates a ProgressHistoryEntry, adds it to session history via addProgressEntry(), sends WebSocket update via sendProgressUpdate(), and triggers push notifications for error/milestone categories.

  // ── notify_session_progress ──
  server.tool(
    "notify_session_progress",
    "Sends a progress update to the connected mobile client. Only call this when AFK mode is active (afkMode: true and clientConnected: true). Returns immediately. Use category 'milestone' for significant steps, 'error' for failures, 'info' for routine updates.",
    {
      sessionId: z.string().describe("The session ID"),
      summary: z.string().describe("Short human-readable summary"),
      detail: z
        .string()
        .nullable()
        .optional()
        .describe("Extended detail (shown in detailed verbosity)"),
      category: z
        .enum(["info", "warning", "error", "success", "milestone"])
        .describe("Category of the progress update"),
      progress: z
        .object({
          current: z.number(),
          total: z.number(),
          label: z.string(),
        })
        .nullable()
        .optional()
        .describe("Optional structured progress"),
      filesChanged: z.array(z.string()).optional().describe("Optional list of files touched"),
      toolsUsed: z.array(z.string()).optional().describe("Optional list of tools called"),
    },
    async (args) => {
      const id = crypto.randomUUID();
      const timestamp = new Date().toISOString();
  
      const entry: ProgressHistoryEntry = {
        id,
        timestamp,
        summary: args.summary,
        detail: args.detail ?? null,
        category: args.category,
        progress: args.progress ?? null,
        filesChanged: args.filesChanged ?? [],
        toolsUsed: args.toolsUsed ?? [],
      };
      addProgressEntry(entry);
  
      const msg: ProgressUpdateMessage = {
        type: "progress_update",
        ...entry,
      };
      const delivered = sendProgressUpdate(msg);
  
      // Push notification for critical updates
      if (args.category === "error" || args.category === "milestone") {
        await sendPushNotification(
          args.category === "error" ? "⚠️ Error" : "🎯 Milestone",
          args.summary,
        );
      }
  
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify({ delivered }),
          },
        ],
      };
    },
  );

• src/shared/types.ts:11-21 (schema)

  ProgressUpdateMessage type definition - the message structure sent to the mobile client. Contains type, id, timestamp, summary, detail, category, progress, filesChanged, and toolsUsed fields.

  export interface ProgressUpdateMessage {
    type: "progress_update";
    id: string;
    timestamp: string;
    summary: string;
    detail: string | null;
    category: ProgressCategory;
    progress: ProgressInfo | null;
    filesChanged: string[];
    toolsUsed: string[];
  }

• src/shared/types.ts:98-106 (schema)

  NotifyProgressInput interface - defines the input type for the notify_session_progress tool with sessionId, summary, detail, category, progress, filesChanged, and toolsUsed fields.

  export interface NotifyProgressInput {
    sessionId: string;
    summary: string;
    detail?: string | null;
    category: ProgressCategory;
    progress?: ProgressInfo | null;
    filesChanged?: string[];
    toolsUsed?: string[];
  }

• src/server/websocket.ts:163-165 (helper)

  sendProgressUpdate helper function - wraps sendToClient to send the ProgressUpdateMessage to the connected WebSocket client. Returns boolean indicating delivery status.

  export function sendProgressUpdate(update: ProgressUpdateMessage): boolean {
    return sendToClient(update);
  }

• src/server/session.ts:54-56 (helper)

  addProgressEntry helper function - adds a ProgressHistoryEntry to the session's progressHistory array for tracking all progress updates.

  export function addProgressEntry(entry: ProgressHistoryEntry): void {
    getSession().progressHistory.push(entry);
  }