notify_session_progress

Send progress updates from AFK Mode to mobile clients during active sessions. Use categories like milestone, error, or info to communicate task status while away from your desk.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description
`sessionId`	Yes	The session ID
`summary`	Yes	Short human-readable summary
`detail`	No	Extended detail (shown in detailed verbosity)
`category`	Yes	Category of the progress update
`progress`	No	Optional structured progress
`filesChanged`	No	Optional list of files touched
`toolsUsed`	No	Optional list of tools called

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);
}
```

AFK Mode