agent-orchestrator-mcp-server 0.8.10 → 0.8.11

package/README.md

@@ -21,24 +21,24 @@ MCP server for PulseMCP's agent-orchestrator: a Claude Code + MCP-powered agent-
 
 ### Tools
 
-| Tool                       | Tool Group    | Read/Write | Description                                                                                                                                                                             |
-| -------------------------- | ------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `quick_search_sessions`    | sessions      | read       | Quick title-based search/list sessions with optional ID lookup, title query, and status filter                                                                                          |
-| `get_session`              | sessions      | read       | Get detailed session info with optional logs, transcripts, and transcript format (text/json)                                                                                            |
-| `get_configs`              | sessions      | read       | Fetch all static configuration (MCP servers, agent roots, goals)                                                                                                                        |
-| `get_transcript_archive`   | sessions      | read       | Get download URL and metadata for the transcript archive zip file                                                                                                                       |
-| `start_session`            | sessions      | write      | Create and start a new agent session                                                                                                                                                    |
-| `action_session`           | sessions      | write      | Perform actions: follow_up, pause, restart, archive, unarchive, change_mcp_servers, change_model, fork, refresh, refresh_all, update_notes, update_title, toggle_favorite, bulk_archive |
-| `manage_enqueued_messages` | sessions      | write      | Manage session message queue: list, get, create, update, delete, reorder, interrupt                                                                                                     |
-| `manage_categories`        | sessions      | write      | Manage dashboard categories that organize sessions: list, create, update, delete, reorder, set_session_category                                                                         |
-| `respond_to_elicitation`   | sessions      | write      | Accept or decline a pending elicitation by its request_id, with optional structured content on accept                                                                                   |
-| `get_notifications`        | notifications | read       | Get/list notifications and badge count                                                                                                                                                  |
-| `send_push_notification`   | notifications | write      | Send a push notification about a session needing human attention                                                                                                                        |
-| `action_notification`      | notifications | write      | Mark read, mark all read, dismiss, dismiss all read notifications                                                                                                                       |
-| `search_triggers`          | triggers      | read       | Search/list automation triggers with optional channel info                                                                                                                              |
-| `action_trigger`           | triggers      | write      | Create, update, delete, toggle automation triggers                                                                                                                                      |
-| `get_system_health`        | health        | read       | Get system health report and optional CLI status                                                                                                                                        |
-| `action_health`            | health        | write      | System maintenance: cleanup_processes, retry_sessions, archive_old, cli_refresh, cli_clear_cache                                                                                        |
+| Tool                       | Tool Group    | Read/Write | Description                                                                                                                                                                                            |
+| -------------------------- | ------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `quick_search_sessions`    | sessions      | read       | Quick title-based search/list sessions with optional ID lookup, title query, and status filter                                                                                                         |
+| `get_session`              | sessions      | read       | Get detailed session info with optional logs, transcripts, and transcript format (text/json)                                                                                                           |
+| `get_configs`              | sessions      | read       | Fetch all static configuration (MCP servers, agent roots, goals)                                                                                                                                       |
+| `get_transcript_archive`   | sessions      | read       | Get download URL and metadata for the transcript archive zip file                                                                                                                                      |
+| `start_session`            | sessions      | write      | Create and start a new agent session                                                                                                                                                                   |
+| `action_session`           | sessions      | write      | Perform actions: follow_up, pause, restart, archive, unarchive, change_mcp_servers, change_model, set_heartbeat, fork, refresh, refresh_all, update_notes, update_title, toggle_favorite, bulk_archive |
+| `manage_enqueued_messages` | sessions      | write      | Manage session message queue: list, get, create, update, delete, reorder, interrupt                                                                                                                    |
+| `manage_categories`        | sessions      | write      | Manage dashboard categories that organize sessions: list, create, update, delete, reorder, set_session_category                                                                                        |
+| `respond_to_elicitation`   | sessions      | write      | Accept or decline a pending elicitation by its request_id, with optional structured content on accept                                                                                                  |
+| `get_notifications`        | notifications | read       | Get/list notifications and badge count                                                                                                                                                                 |
+| `send_push_notification`   | notifications | write      | Send a push notification about a session needing human attention                                                                                                                                       |
+| `action_notification`      | notifications | write      | Mark read, mark all read, dismiss, dismiss all read notifications                                                                                                                                      |
+| `search_triggers`          | triggers      | read       | Search/list automation triggers with optional channel info                                                                                                                                             |
+| `action_trigger`           | triggers      | write      | Create, update, delete, toggle automation triggers                                                                                                                                                     |
+| `get_system_health`        | health        | read       | Get system health report and optional CLI status                                                                                                                                                       |
+| `action_health`            | health        | write      | System maintenance: cleanup_processes, retry_sessions, archive_old, cli_refresh, cli_clear_cache                                                                                                       |
 
 ### Resources
 
@@ -213,6 +213,7 @@ This MCP server provides tools for the following Agent Orchestrator REST API end
 - `POST /api/v1/sessions/:id/refresh` - Refresh session status
 - `POST /api/v1/sessions/refresh_all` - Refresh all active sessions
 - `POST /api/v1/sessions/:id/toggle_favorite` - Toggle favorite
+- `PATCH /api/v1/sessions/:id/heartbeat` - Toggle heartbeat and/or set interval (set_heartbeat)
 - `POST /api/v1/sessions/bulk_archive` - Bulk archive sessions
 
 ### Transcript Archive

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-mcp-server",
-  "version": "0.8.10",
+  "version": "0.8.11",
   "description": "Local implementation of agent-orchestrator MCP server",
   "main": "build/index.js",
   "type": "module",

package/shared/orchestrator-client/orchestrator-client.d.ts

@@ -3,7 +3,7 @@
  *
  * A client for interacting with the Agent Orchestrator REST API.
  */
-import type { Session, Log, SubagentTranscript, SessionsResponse, SearchSessionsResponse, SessionActionResponse, LogsResponse, SubagentTranscriptsResponse, CreateSessionRequest, UpdateSessionRequest, CreateLogRequest, UpdateLogRequest, CreateSubagentTranscriptRequest, UpdateSubagentTranscriptRequest, SessionStatus, LogLevel, SubagentStatus, MCPServerInfo, AgentRootInfo, ConfigsResponse, SendPushNotificationResponse, EnqueuedMessage, EnqueuedMessagesResponse, EnqueuedMessageInterruptResponse, EnqueuedMessageStatus, Category, CategoriesResponse, CreateCategoryRequest, UpdateCategoryRequest, SetSessionCategoryResponse, Trigger, TriggerType, TriggerStatus, TriggersResponse, TriggerResponse, TriggerChannelsResponse, TriggerConditionAttributes, TriggerConditionType, CreateTriggerRequest, UpdateTriggerRequest, Notification, NotificationsResponse, NotificationBadgeResponse, NotificationMarkAllReadResponse, NotificationDismissAllReadResponse, HealthReport, HealthActionResponse, CliStatusResponse, CliActionResponse, ForkSessionResponse, RefreshSessionResponse, RefreshAllSessionsResponse, BulkArchiveResponse, TranscriptResponse, TranscriptArchiveStatusResponse, ElicitationActionType, ElicitationResponse } from '../types.js';
+import type { Session, Log, SubagentTranscript, SessionsResponse, SearchSessionsResponse, SessionActionResponse, SetHeartbeatResponse, LogsResponse, SubagentTranscriptsResponse, CreateSessionRequest, UpdateSessionRequest, CreateLogRequest, UpdateLogRequest, CreateSubagentTranscriptRequest, UpdateSubagentTranscriptRequest, SessionStatus, LogLevel, SubagentStatus, MCPServerInfo, AgentRootInfo, ConfigsResponse, SendPushNotificationResponse, EnqueuedMessage, EnqueuedMessagesResponse, EnqueuedMessageInterruptResponse, EnqueuedMessageStatus, Category, CategoriesResponse, CreateCategoryRequest, UpdateCategoryRequest, SetSessionCategoryResponse, Trigger, TriggerType, TriggerStatus, TriggersResponse, TriggerResponse, TriggerChannelsResponse, TriggerConditionAttributes, TriggerConditionType, CreateTriggerRequest, UpdateTriggerRequest, Notification, NotificationsResponse, NotificationBadgeResponse, NotificationMarkAllReadResponse, NotificationDismissAllReadResponse, HealthReport, HealthActionResponse, CliStatusResponse, CliActionResponse, ForkSessionResponse, RefreshSessionResponse, RefreshAllSessionsResponse, BulkArchiveResponse, TranscriptResponse, TranscriptArchiveStatusResponse, ElicitationActionType, ElicitationResponse } from '../types.js';
 /** Raw agent root shape as returned by the Rails API */
 export interface RawAgentRoot {
     name: string;
@@ -67,6 +67,10 @@ export interface IAgentOrchestratorClient {
     restartSession(id: string | number): Promise<SessionActionResponse>;
     changeMcpServers(id: string | number, mcp_servers: string[]): Promise<Session>;
     changeModel(id: string | number, model: string): Promise<Session>;
+    setHeartbeat(id: string | number, options: {
+        enabled?: boolean;
+        interval_seconds?: number;
+    }): Promise<SetHeartbeatResponse>;
     listLogs(sessionId: string | number, options?: {
         level?: LogLevel;
         page?: number;
@@ -201,6 +205,10 @@ export declare class AgentOrchestratorClient implements IAgentOrchestratorClient
     restartSession(id: string | number): Promise<SessionActionResponse>;
     changeMcpServers(id: string | number, mcp_servers: string[]): Promise<Session>;
     changeModel(id: string | number, model: string): Promise<Session>;
+    setHeartbeat(id: string | number, options: {
+        enabled?: boolean;
+        interval_seconds?: number;
+    }): Promise<SetHeartbeatResponse>;
     listLogs(sessionId: string | number, options?: {
         level?: LogLevel;
         page?: number;

package/shared/orchestrator-client/orchestrator-client.integration-mock.js

@@ -309,6 +309,31 @@ export function createIntegrationMockOrchestratorClient(initialMockData) {
             session.updated_at = new Date().toISOString();
             return session;
         },
+        async setHeartbeat(id, options) {
+            const session = mockData.sessions?.find((s) => s.id === Number(id) || s.slug === String(id));
+            if (!session) {
+                throw new Error(`API Error (404): Session not found`);
+            }
+            if (options.enabled === undefined && options.interval_seconds === undefined) {
+                throw new Error(`API Error (422): At least one of "enabled" or "interval_seconds" must be provided`);
+            }
+            if (options.interval_seconds !== undefined &&
+                (options.interval_seconds < 30 || options.interval_seconds > 86400)) {
+                throw new Error(`API Error (422): interval_seconds must be between 30 and 86400`);
+            }
+            if (options.enabled !== undefined) {
+                session.heartbeat_enabled = options.enabled;
+            }
+            if (options.interval_seconds !== undefined) {
+                session.heartbeat_interval_seconds = options.interval_seconds;
+            }
+            session.updated_at = new Date().toISOString();
+            return {
+                session,
+                heartbeat_enabled: session.heartbeat_enabled ?? false,
+                heartbeat_interval_seconds: session.heartbeat_interval_seconds ?? 300,
+            };
+        },
         async listLogs(sessionId, options) {
             let logs = (mockData.logs || []).filter((l) => l.session_id === Number(sessionId));
             if (options?.level) {

package/shared/orchestrator-client/orchestrator-client.js

@@ -246,6 +246,14 @@ export class AgentOrchestratorClient {
         });
         return response.session;
     }
+    async setHeartbeat(id, options) {
+        const body = {};
+        if (options.enabled !== undefined)
+            body.enabled = options.enabled;
+        if (options.interval_seconds !== undefined)
+            body.interval_seconds = options.interval_seconds;
+        return this.request('PATCH', `/sessions/${id}/heartbeat`, body);
+    }
     // Logs
     async listLogs(sessionId, options) {
         return this.request('GET', `/sessions/${sessionId}/logs`, undefined, options);

package/shared/resources.js

@@ -74,7 +74,7 @@ export function createRegisterResources(clientFactory) {
                         triggers_readonly: 'Trigger tools (read only): search_triggers',
                         health: 'All health tools (read + write): health report, CLI status, maintenance actions',
                         health_readonly: 'Health tools (read only): get_system_health',
-                        self_session: 'Self-management tools for auto-injected servers: get_session, get_configs (read), action_session (filtered: update_notes, update_title, archive), send_push_notification',
+                        self_session: 'Self-management tools for auto-injected servers: get_session, get_configs (read), action_session (filtered: update_notes, update_title, set_heartbeat, archive), send_push_notification',
                     },
                 };
                 return {

package/shared/tools/action-session.d.ts

@@ -3,34 +3,40 @@ import { z } from 'zod';
 import type { IAgentOrchestratorClient } from '../orchestrator-client/orchestrator-client.js';
 export declare const ActionSessionSchema: z.ZodObject<{
     session_id: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
-    action: z.ZodEnum<["follow_up", "pause", "restart", "archive", "unarchive", "change_mcp_servers", "change_model", "fork", "refresh", "refresh_all", "update_notes", "update_title", "toggle_favorite", "bulk_archive"]>;
+    action: z.ZodEnum<["follow_up", "pause", "restart", "archive", "unarchive", "change_mcp_servers", "change_model", "set_heartbeat", "fork", "refresh", "refresh_all", "update_notes", "update_title", "toggle_favorite", "bulk_archive"]>;
     prompt: z.ZodOptional<z.ZodString>;
     force_immediate: z.ZodOptional<z.ZodBoolean>;
     mcp_servers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     model: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    interval_seconds: z.ZodOptional<z.ZodNumber>;
     message_index: z.ZodOptional<z.ZodNumber>;
     session_notes: z.ZodOptional<z.ZodString>;
     session_ids: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
     title: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    action: "follow_up" | "pause" | "restart" | "archive" | "unarchive" | "change_mcp_servers" | "change_model" | "fork" | "refresh" | "refresh_all" | "update_notes" | "update_title" | "toggle_favorite" | "bulk_archive";
+    action: "follow_up" | "pause" | "restart" | "archive" | "unarchive" | "change_mcp_servers" | "change_model" | "set_heartbeat" | "fork" | "refresh" | "refresh_all" | "update_notes" | "update_title" | "toggle_favorite" | "bulk_archive";
+    enabled?: boolean | undefined;
     prompt?: string | undefined;
     title?: string | undefined;
     mcp_servers?: string[] | undefined;
     session_id?: string | number | undefined;
     force_immediate?: boolean | undefined;
     model?: string | undefined;
+    interval_seconds?: number | undefined;
     message_index?: number | undefined;
     session_notes?: string | undefined;
     session_ids?: number[] | undefined;
 }, {
-    action: "follow_up" | "pause" | "restart" | "archive" | "unarchive" | "change_mcp_servers" | "change_model" | "fork" | "refresh" | "refresh_all" | "update_notes" | "update_title" | "toggle_favorite" | "bulk_archive";
+    action: "follow_up" | "pause" | "restart" | "archive" | "unarchive" | "change_mcp_servers" | "change_model" | "set_heartbeat" | "fork" | "refresh" | "refresh_all" | "update_notes" | "update_title" | "toggle_favorite" | "bulk_archive";
+    enabled?: boolean | undefined;
     prompt?: string | undefined;
     title?: string | undefined;
     mcp_servers?: string[] | undefined;
     session_id?: string | number | undefined;
     force_immediate?: boolean | undefined;
     model?: string | undefined;
+    interval_seconds?: number | undefined;
     message_index?: number | undefined;
     session_notes?: string | undefined;
     session_ids?: number[] | undefined;
@@ -49,8 +55,8 @@ export declare function actionSessionTool(_server: Server, clientFactory: () =>
             };
             action: {
                 type: string;
-                enum: readonly ["follow_up", "pause", "restart", "archive", "unarchive", "change_mcp_servers", "change_model", "fork", "refresh", "refresh_all", "update_notes", "update_title", "toggle_favorite", "bulk_archive"];
-                description: "Action to perform: \"follow_up\", \"pause\", \"restart\", \"archive\", \"unarchive\", \"change_mcp_servers\", \"change_model\", \"fork\", \"refresh\", \"refresh_all\", \"update_notes\", \"update_title\", \"toggle_favorite\", \"bulk_archive\"";
+                enum: readonly ["follow_up", "pause", "restart", "archive", "unarchive", "change_mcp_servers", "change_model", "set_heartbeat", "fork", "refresh", "refresh_all", "update_notes", "update_title", "toggle_favorite", "bulk_archive"];
+                description: "Action to perform: \"follow_up\", \"pause\", \"restart\", \"archive\", \"unarchive\", \"change_mcp_servers\", \"change_model\", \"set_heartbeat\", \"fork\", \"refresh\", \"refresh_all\", \"update_notes\", \"update_title\", \"toggle_favorite\", \"bulk_archive\"";
             };
             prompt: {
                 type: string;
@@ -71,6 +77,14 @@ export declare function actionSessionTool(_server: Server, clientFactory: () =>
                 type: string;
                 description: "Required for \"change_model\" action. The model identifier to use (e.g., \"opus\", \"sonnet\").";
             };
+            enabled: {
+                type: string;
+                description: "Optional for \"set_heartbeat\" action. When true, enables the session heartbeat; when false, disables it. Omit to leave the enabled state unchanged (at least one of \"enabled\" or \"interval_seconds\" must be provided).";
+            };
+            interval_seconds: {
+                type: string;
+                description: "Optional for \"set_heartbeat\" action. Heartbeat cadence in seconds (30–86400). Omit to leave the interval unchanged (at least one of \"enabled\" or \"interval_seconds\" must be provided).";
+            };
             message_index: {
                 type: string;
                 description: "Required for \"fork\" action. The transcript message index to fork from.";
@@ -109,18 +123,24 @@ export declare function actionSessionTool(_server: Server, clientFactory: () =>
 };
 export declare const SelfSessionActionSessionSchema: z.ZodObject<{
     session_id: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
-    action: z.ZodEnum<["update_notes", "update_title", "archive"]>;
+    action: z.ZodEnum<["update_notes", "update_title", "set_heartbeat", "archive"]>;
     session_notes: z.ZodOptional<z.ZodString>;
     title: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    interval_seconds: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     session_id: string | number;
-    action: "archive" | "update_notes" | "update_title";
+    action: "archive" | "set_heartbeat" | "update_notes" | "update_title";
+    enabled?: boolean | undefined;
     title?: string | undefined;
+    interval_seconds?: number | undefined;
     session_notes?: string | undefined;
 }, {
     session_id: string | number;
-    action: "archive" | "update_notes" | "update_title";
+    action: "archive" | "set_heartbeat" | "update_notes" | "update_title";
+    enabled?: boolean | undefined;
     title?: string | undefined;
+    interval_seconds?: number | undefined;
     session_notes?: string | undefined;
 }>;
 export declare function selfSessionActionSessionTool(_server: Server, clientFactory: () => IAgentOrchestratorClient): {
@@ -137,7 +157,7 @@ export declare function selfSessionActionSessionTool(_server: Server, clientFact
             };
             action: {
                 type: string;
-                enum: readonly ["update_notes", "update_title", "archive"];
+                enum: readonly ["update_notes", "update_title", "set_heartbeat", "archive"];
                 description: string;
             };
             session_notes: {
@@ -148,6 +168,14 @@ export declare function selfSessionActionSessionTool(_server: Server, clientFact
                 type: string;
                 description: "Required for \"update_title\" action. The new title for the session.";
             };
+            enabled: {
+                type: string;
+                description: "Optional for \"set_heartbeat\" action. When true, enables the session heartbeat; when false, disables it. Omit to leave the enabled state unchanged (at least one of \"enabled\" or \"interval_seconds\" must be provided).";
+            };
+            interval_seconds: {
+                type: string;
+                description: "Optional for \"set_heartbeat\" action. Heartbeat cadence in seconds (30–86400). Omit to leave the interval unchanged (at least one of \"enabled\" or \"interval_seconds\" must be provided).";
+            };
         };
         required: string[];
     };

package/shared/tools/action-session.js

@@ -1,12 +1,44 @@
 import { z } from 'zod';
 import { parseAllowedAgentRoots } from '../allowed-agent-roots.js';
+// Heartbeat interval bounds enforced by the Rails API (PATCH /sessions/:id/heartbeat).
+const HEARTBEAT_MIN_INTERVAL_SECONDS = 30;
+const HEARTBEAT_MAX_INTERVAL_SECONDS = 86400;
+/**
+ * Validates set_heartbeat arguments. Returns an error message string if the
+ * arguments are invalid, or null if they are valid. Mirrors the Rails API's
+ * 422 conditions so callers get a clear error before the request is sent.
+ */
+function validateHeartbeatArgs(enabled, interval_seconds) {
+    if (enabled === undefined && interval_seconds === undefined) {
+        return 'Error: The "set_heartbeat" action requires at least one of "enabled" or "interval_seconds".';
+    }
+    if (interval_seconds !== undefined &&
+        (interval_seconds < HEARTBEAT_MIN_INTERVAL_SECONDS ||
+            interval_seconds > HEARTBEAT_MAX_INTERVAL_SECONDS)) {
+        return `Error: "interval_seconds" must be between ${HEARTBEAT_MIN_INTERVAL_SECONDS} and ${HEARTBEAT_MAX_INTERVAL_SECONDS}.`;
+    }
+    return null;
+}
+/** Formats a set_heartbeat response into the standard markdown result block. */
+function formatHeartbeatResult(response) {
+    return [
+        `## Heartbeat Updated`,
+        '',
+        `- **Session ID:** ${response.session.id}`,
+        `- **Title:** ${response.session.title}`,
+        `- **Heartbeat Enabled:** ${response.heartbeat_enabled ? 'Yes' : 'No'}`,
+        `- **Interval:** ${response.heartbeat_interval_seconds} seconds`,
+    ].join('\n');
+}
 const PARAM_DESCRIPTIONS = {
     session_id: 'Session ID (numeric) or slug (string). Required for most actions. Not required for "refresh_all" and "bulk_archive".',
-    action: 'Action to perform: "follow_up", "pause", "restart", "archive", "unarchive", "change_mcp_servers", "change_model", "fork", "refresh", "refresh_all", "update_notes", "update_title", "toggle_favorite", "bulk_archive"',
+    action: 'Action to perform: "follow_up", "pause", "restart", "archive", "unarchive", "change_mcp_servers", "change_model", "set_heartbeat", "fork", "refresh", "refresh_all", "update_notes", "update_title", "toggle_favorite", "bulk_archive"',
     prompt: 'Required for "follow_up" action. The prompt to send to the agent. Not used for other actions.',
     force_immediate: 'Optional for "follow_up" action. When true, interrupts a running session to deliver the prompt immediately instead of queuing it. Not used for other actions.',
     mcp_servers: 'Required for "change_mcp_servers" action. Array of MCP server names to set for the session.',
     model: 'Required for "change_model" action. The model identifier to use (e.g., "opus", "sonnet").',
+    enabled: 'Optional for "set_heartbeat" action. When true, enables the session heartbeat; when false, disables it. Omit to leave the enabled state unchanged (at least one of "enabled" or "interval_seconds" must be provided).',
+    interval_seconds: 'Optional for "set_heartbeat" action. Heartbeat cadence in seconds (30–86400). Omit to leave the interval unchanged (at least one of "enabled" or "interval_seconds" must be provided).',
     message_index: 'Required for "fork" action. The transcript message index to fork from.',
     session_notes: 'Required for "update_notes" action. The notes text to set on the session.',
     session_ids: 'Required for "bulk_archive" action. Array of session IDs to archive.',
@@ -20,6 +52,7 @@ const ACTION_ENUM = [
     'unarchive',
     'change_mcp_servers',
     'change_model',
+    'set_heartbeat',
     'fork',
     'refresh',
     'refresh_all',
@@ -35,6 +68,8 @@ export const ActionSessionSchema = z.object({
     force_immediate: z.boolean().optional().describe(PARAM_DESCRIPTIONS.force_immediate),
     mcp_servers: z.array(z.string()).optional().describe(PARAM_DESCRIPTIONS.mcp_servers),
     model: z.string().optional().describe(PARAM_DESCRIPTIONS.model),
+    enabled: z.boolean().optional().describe(PARAM_DESCRIPTIONS.enabled),
+    interval_seconds: z.number().int().optional().describe(PARAM_DESCRIPTIONS.interval_seconds),
     message_index: z.number().optional().describe(PARAM_DESCRIPTIONS.message_index),
     session_notes: z.string().optional().describe(PARAM_DESCRIPTIONS.session_notes),
     session_ids: z.array(z.number()).optional().describe(PARAM_DESCRIPTIONS.session_ids),
@@ -50,6 +85,7 @@ const TOOL_DESCRIPTION = `Perform an action on an agent session.
 - **unarchive**: Restore an archived session to idle "needs_input" status
 - **change_mcp_servers**: Update the MCP servers for a session (requires "mcp_servers" parameter)
 - **change_model**: Update the model for a session (requires "model" parameter, e.g., "opus", "sonnet")
+- **set_heartbeat**: Toggle a session's heartbeat and/or set its interval (provide "enabled" and/or "interval_seconds"). When enabled and the session sits in needs_input, a recurring nudge prompts it to keep working toward its goal; set "enabled" to false to stop the nudges.
 - **fork**: Fork a session from a specific transcript message (requires "message_index")
 - **refresh**: Refresh a single session's status from the execution provider
 - **refresh_all**: Refresh all active sessions (no session_id needed)
@@ -97,6 +133,14 @@ export function actionSessionTool(_server, clientFactory) {
                     type: 'string',
                     description: PARAM_DESCRIPTIONS.model,
                 },
+                enabled: {
+                    type: 'boolean',
+                    description: PARAM_DESCRIPTIONS.enabled,
+                },
+                interval_seconds: {
+                    type: 'number',
+                    description: PARAM_DESCRIPTIONS.interval_seconds,
+                },
                 message_index: {
                     type: 'number',
                     description: PARAM_DESCRIPTIONS.message_index,
@@ -121,7 +165,7 @@ export function actionSessionTool(_server, clientFactory) {
             try {
                 const validatedArgs = ActionSessionSchema.parse(args);
                 const client = clientFactory();
-                const { session_id, action, prompt, force_immediate, mcp_servers, model, message_index, session_notes, session_ids, title, } = validatedArgs;
+                const { session_id, action, prompt, force_immediate, mcp_servers, model, enabled, interval_seconds, message_index, session_notes, session_ids, title, } = validatedArgs;
                 // Actions that require session_id
                 const requiresSessionId = [
                     'follow_up',
@@ -131,6 +175,7 @@ export function actionSessionTool(_server, clientFactory) {
                     'unarchive',
                     'change_mcp_servers',
                     'change_model',
+                    'set_heartbeat',
                     'fork',
                     'refresh',
                     'update_notes',
@@ -184,6 +229,16 @@ export function actionSessionTool(_server, clientFactory) {
                         isError: true,
                     };
                 }
+                // Validate set_heartbeat arguments
+                if (action === 'set_heartbeat') {
+                    const heartbeatError = validateHeartbeatArgs(enabled, interval_seconds);
+                    if (heartbeatError) {
+                        return {
+                            content: [{ type: 'text', text: heartbeatError }],
+                            isError: true,
+                        };
+                    }
+                }
                 // Block change_mcp_servers when ALLOWED_AGENT_ROOTS is active
                 if (action === 'change_mcp_servers' && parseAllowedAgentRoots() !== null) {
                     return {
@@ -375,6 +430,14 @@ export function actionSessionTool(_server, clientFactory) {
                         result = lines.join('\n');
                         break;
                     }
+                    case 'set_heartbeat': {
+                        const response = await client.setHeartbeat(session_id, {
+                            enabled,
+                            interval_seconds,
+                        });
+                        result = formatHeartbeatResult(response);
+                        break;
+                    }
                     case 'fork': {
                         const response = await client.forkSession(session_id, message_index);
                         const lines = [
@@ -503,27 +566,36 @@ export function actionSessionTool(_server, clientFactory) {
 // SELF-SESSION VARIANT
 // =============================================================================
 // Restricted version of action_session for the self_session composite group.
-// Only allows self-management actions: update_notes, update_title, archive.
+// Only allows self-management actions: update_notes, update_title, set_heartbeat, archive.
 // =============================================================================
-const SELF_SESSION_ACTION_ENUM = ['update_notes', 'update_title', 'archive'];
+const SELF_SESSION_ACTION_ENUM = [
+    'update_notes',
+    'update_title',
+    'set_heartbeat',
+    'archive',
+];
 export const SelfSessionActionSessionSchema = z.object({
     session_id: z.union([z.string(), z.number()]).describe(PARAM_DESCRIPTIONS.session_id),
     action: z
         .enum(SELF_SESSION_ACTION_ENUM)
-        .describe('Action to perform: "update_notes", "update_title", "archive"'),
+        .describe('Action to perform: "update_notes", "update_title", "set_heartbeat", "archive"'),
     session_notes: z.string().optional().describe(PARAM_DESCRIPTIONS.session_notes),
     title: z.string().optional().describe(PARAM_DESCRIPTIONS.title),
+    enabled: z.boolean().optional().describe(PARAM_DESCRIPTIONS.enabled),
+    interval_seconds: z.number().int().optional().describe(PARAM_DESCRIPTIONS.interval_seconds),
 });
 const SELF_SESSION_TOOL_DESCRIPTION = `Perform a self-management action on a session.
 
 **Actions (limited to self-management):**
 - **update_notes**: Update the notes on a session (requires "session_notes")
 - **update_title**: Update the title of a session (requires "title")
+- **set_heartbeat**: Toggle this session's own heartbeat and/or set its interval (provide "enabled" and/or "interval_seconds"). When the heartbeat is enabled and this session sits in needs_input, a recurring nudge prompts it to keep working toward its goal. If you are genuinely blocked or done, set "enabled" to false to stop the nudges.
 - **archive**: Archive a session (marks as completed)
 
 **Use cases:**
 - Update session notes to record progress or context
 - Set a meaningful session title
+- Turn off this session's heartbeat when blocked or finished (set_heartbeat with enabled=false)
 - Archive the session when work is complete
 
 **Archive guidelines:**
@@ -544,7 +616,7 @@ export function selfSessionActionSessionTool(_server, clientFactory) {
                 action: {
                     type: 'string',
                     enum: SELF_SESSION_ACTION_ENUM,
-                    description: 'Action to perform: "update_notes", "update_title", "archive"',
+                    description: 'Action to perform: "update_notes", "update_title", "set_heartbeat", "archive"',
                 },
                 session_notes: {
                     type: 'string',
@@ -554,6 +626,14 @@ export function selfSessionActionSessionTool(_server, clientFactory) {
                     type: 'string',
                     description: PARAM_DESCRIPTIONS.title,
                 },
+                enabled: {
+                    type: 'boolean',
+                    description: PARAM_DESCRIPTIONS.enabled,
+                },
+                interval_seconds: {
+                    type: 'number',
+                    description: PARAM_DESCRIPTIONS.interval_seconds,
+                },
             },
             required: ['session_id', 'action'],
         },
@@ -561,7 +641,7 @@ export function selfSessionActionSessionTool(_server, clientFactory) {
             try {
                 const validatedArgs = SelfSessionActionSessionSchema.parse(args);
                 const client = clientFactory();
-                const { session_id, action, session_notes, title } = validatedArgs;
+                const { session_id, action, session_notes, title, enabled, interval_seconds } = validatedArgs;
                 // Validate update_notes requires session_notes
                 if (action === 'update_notes' && session_notes === undefined) {
                     return {
@@ -586,6 +666,16 @@ export function selfSessionActionSessionTool(_server, clientFactory) {
                         isError: true,
                     };
                 }
+                // Validate set_heartbeat arguments
+                if (action === 'set_heartbeat') {
+                    const heartbeatError = validateHeartbeatArgs(enabled, interval_seconds);
+                    if (heartbeatError) {
+                        return {
+                            content: [{ type: 'text', text: heartbeatError }],
+                            isError: true,
+                        };
+                    }
+                }
                 let result;
                 switch (action) {
                     case 'archive': {
@@ -601,6 +691,14 @@ export function selfSessionActionSessionTool(_server, clientFactory) {
                         result = lines.join('\n');
                         break;
                     }
+                    case 'set_heartbeat': {
+                        const response = await client.setHeartbeat(session_id, {
+                            enabled,
+                            interval_seconds,
+                        });
+                        result = formatHeartbeatResult(response);
+                        break;
+                    }
                     case 'update_notes': {
                         const session = await client.updateSessionNotes(session_id, session_notes);
                         const lines = [

package/shared/tools.js

@@ -69,7 +69,7 @@ export function parseEnabledToolGroups(enabledGroupsParam) {
  * - get_configs: Fetch all static configuration (sessions, read; self_session)
  * - get_transcript_archive: Get transcript archive download URL and metadata (sessions, read)
  * - start_session: Create a new session (sessions, write)
- * - action_session: Perform session actions (sessions, write; self_session: filtered to update_notes, update_title, archive)
+ * - action_session: Perform session actions (sessions, write; self_session: filtered to update_notes, update_title, set_heartbeat, archive)
  * - manage_enqueued_messages: Manage session message queue (sessions, write)
  * - manage_categories: Manage dashboard categories and session assignment (sessions, write)
  * - respond_to_elicitation: Accept or decline a pending elicitation by request_id (sessions, write)

package/shared/types.d.ts

@@ -34,6 +34,8 @@ export interface Session {
     archived_at: string | null;
     category_id?: number | null;
     category?: CategorySummary | null;
+    heartbeat_enabled?: boolean;
+    heartbeat_interval_seconds?: number;
     created_at: string;
     updated_at: string;
     transcript?: string;
@@ -82,6 +84,11 @@ export interface SessionActionResponse {
     session: Session;
     message?: string;
 }
+export interface SetHeartbeatResponse {
+    session: Session;
+    heartbeat_enabled: boolean;
+    heartbeat_interval_seconds: number;
+}
 export interface LogsResponse {
     logs: Log[];
     pagination: Pagination;