agent-orchestrator-mcp-server 0.8.9 → 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.9",
+  "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, 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;
@@ -25,6 +25,14 @@ export interface RawAgentRoot {
  * as they are not needed by MCP clients.
  */
 export declare function mapAgentRoot(raw: RawAgentRoot): AgentRootInfo;
+/**
+ * Folds the ergonomic top-level `trigger_type` + `configuration` shape into the
+ * REST API's nested `trigger_conditions_attributes`. Mirrors the
+ * `trigger_type` → `condition_type` mapping that listTriggers uses for filtering.
+ * Returns undefined when there is no condition to build (no trigger_type), so
+ * callers can leave the field off the request entirely.
+ */
+export declare function conditionAttributesFromLegacy(trigger_type: TriggerConditionType | undefined, configuration: Record<string, unknown> | undefined): TriggerConditionAttributes[] | undefined;
 /**
  * Interface for the Agent Orchestrator API client.
  * Used for dependency injection and testing.
@@ -59,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;
@@ -193,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;
@@ -256,6 +272,13 @@ export declare class AgentOrchestratorClient implements IAgentOrchestratorClient
     getTrigger(id: number): Promise<TriggerResponse>;
     createTrigger(data: CreateTriggerRequest): Promise<Trigger>;
     updateTrigger(id: number, data: UpdateTriggerRequest): Promise<Trigger>;
+    /**
+     * Builds the trigger_conditions_attributes for an update expressed with the
+     * ergonomic top-level `trigger_type` + `configuration` shape. Fetches the
+     * trigger to reuse the matching existing condition's id (so the condition is
+     * updated in place rather than duplicated).
+     */
+    private resolveUpdatedTriggerConditions;
     deleteTrigger(id: number): Promise<void>;
     toggleTrigger(id: number): Promise<Trigger>;
     getTriggerChannels(): Promise<TriggerChannelsResponse>;

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

@@ -3,6 +3,25 @@
  *
  * Used in integration tests to simulate API responses without hitting real endpoints.
  */
+import { conditionAttributesFromLegacy } from './orchestrator-client.js';
+/**
+ * Builds mock TriggerCondition rows from a create/update request, mirroring the
+ * real client: fold the ergonomic top-level trigger_type + configuration shape
+ * into nested condition attributes when the caller didn't supply them directly.
+ */
+function buildMockTriggerConditions(data) {
+    const conditionAttributes = data.trigger_conditions_attributes ??
+        conditionAttributesFromLegacy(data.trigger_type, data.configuration) ??
+        [];
+    return conditionAttributes.map((c, i) => ({
+        id: i + 1,
+        condition_type: c.condition_type,
+        configuration: c.configuration,
+        description: `${c.condition_type} condition`,
+        last_triggered_at: null,
+        last_polled_at: null,
+    }));
+}
 /**
  * Creates a mock Agent Orchestrator client for integration testing.
  */
@@ -290,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) {
@@ -751,14 +795,7 @@ export function createIntegrationMockOrchestratorClient(initialMockData) {
             return { trigger, recent_sessions: [] };
         },
         async createTrigger(data) {
-            const conditions = (data.trigger_conditions_attributes ?? []).map((c, i) => ({
-                id: i + 1,
-                condition_type: c.condition_type,
-                configuration: c.configuration,
-                description: `${c.condition_type} condition`,
-                last_triggered_at: null,
-                last_polled_at: null,
-            }));
+            const conditions = buildMockTriggerConditions(data);
             return {
                 id: 1,
                 name: data.name,
@@ -777,14 +814,7 @@ export function createIntegrationMockOrchestratorClient(initialMockData) {
             };
         },
         async updateTrigger(id, data) {
-            const conditions = (data.trigger_conditions_attributes ?? []).map((c, i) => ({
-                id: i + 1,
-                condition_type: c.condition_type,
-                configuration: c.configuration,
-                description: `${c.condition_type} condition`,
-                last_triggered_at: null,
-                last_polled_at: null,
-            }));
+            const conditions = buildMockTriggerConditions(data);
             return {
                 id,
                 name: data.name || 'Updated Trigger',

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

@@ -22,6 +22,19 @@ export function mapAgentRoot(raw) {
         default_model: raw.default_model,
     };
 }
+/**
+ * Folds the ergonomic top-level `trigger_type` + `configuration` shape into the
+ * REST API's nested `trigger_conditions_attributes`. Mirrors the
+ * `trigger_type` → `condition_type` mapping that listTriggers uses for filtering.
+ * Returns undefined when there is no condition to build (no trigger_type), so
+ * callers can leave the field off the request entirely.
+ */
+export function conditionAttributesFromLegacy(trigger_type, configuration) {
+    if (trigger_type === undefined) {
+        return undefined;
+    }
+    return [{ condition_type: trigger_type, configuration: configuration ?? {} }];
+}
 /** Default timeout for API requests in milliseconds */
 const DEFAULT_TIMEOUT_MS = 30000;
 /**
@@ -233,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);
@@ -387,13 +408,65 @@ export class AgentOrchestratorClient {
         return this.request('GET', `/triggers/${id}`);
     }
     async createTrigger(data) {
-        const response = await this.request('POST', '/triggers', data);
+        const { trigger_type, configuration, trigger_conditions_attributes, ...rest } = data;
+        const body = { ...rest };
+        // The Rails v1 /triggers endpoint permits neither a top-level `trigger_type`
+        // nor a top-level `configuration`; the condition must be nested as
+        // `trigger_conditions_attributes: [{ condition_type:, configuration: }]`.
+        // An explicitly-supplied nested array (e.g. from wake_me_up_* tools) wins;
+        // otherwise fold the ergonomic top-level shape into a single condition.
+        const conditions = trigger_conditions_attributes ?? conditionAttributesFromLegacy(trigger_type, configuration);
+        if (conditions !== undefined) {
+            body.trigger_conditions_attributes = conditions;
+        }
+        const response = await this.request('POST', '/triggers', body);
         return response.trigger;
     }
     async updateTrigger(id, data) {
-        const response = await this.request('PATCH', `/triggers/${id}`, data);
+        const { trigger_type, configuration, trigger_conditions_attributes, ...rest } = data;
+        const body = { ...rest };
+        if (trigger_conditions_attributes !== undefined) {
+            // Caller supplied the nested shape directly — forward verbatim.
+            body.trigger_conditions_attributes = trigger_conditions_attributes;
+        }
+        else if (trigger_type !== undefined || configuration !== undefined) {
+            // Ergonomic top-level shape. Resolve the existing condition's id so the
+            // condition is modified in place instead of a duplicate being appended
+            // (Rails uses accepts_nested_attributes_for). Metadata-only updates that
+            // omit both fields skip this entirely and never touch conditions.
+            body.trigger_conditions_attributes = await this.resolveUpdatedTriggerConditions(id, trigger_type, configuration);
+        }
+        const response = await this.request('PATCH', `/triggers/${id}`, body);
         return response.trigger;
     }
+    /**
+     * Builds the trigger_conditions_attributes for an update expressed with the
+     * ergonomic top-level `trigger_type` + `configuration` shape. Fetches the
+     * trigger to reuse the matching existing condition's id (so the condition is
+     * updated in place rather than duplicated).
+     */
+    async resolveUpdatedTriggerConditions(id, trigger_type, configuration) {
+        const { trigger } = await this.getTrigger(id);
+        const existing = trigger.conditions ?? [];
+        // Pick the condition to modify: the one matching the requested type, or the
+        // sole existing condition when no type was provided.
+        const target = trigger_type !== undefined
+            ? existing.find((c) => c.condition_type === trigger_type)
+            : existing.length === 1
+                ? existing[0]
+                : undefined;
+        const conditionType = trigger_type ?? target?.condition_type;
+        if (conditionType === undefined) {
+            throw new Error('Cannot update trigger configuration without a trigger_type when the trigger has zero or multiple conditions.');
+        }
+        return [
+            {
+                ...(target?.id !== undefined && { id: target.id }),
+                condition_type: conditionType,
+                configuration: configuration ?? target?.configuration ?? {},
+            },
+        ];
+    }
     async deleteTrigger(id) {
         await this.request('DELETE', `/triggers/${id}`);
     }

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/action-trigger.d.ts

@@ -19,24 +19,24 @@ export declare const ActionTriggerSchema: z.ZodObject<{
     goal?: string | undefined;
     mcp_servers?: string[] | undefined;
     trigger_type?: "slack" | "schedule" | undefined;
+    configuration?: Record<string, unknown> | undefined;
     name?: string | undefined;
-    id?: number | undefined;
     agent_root_name?: string | undefined;
     prompt_template?: string | undefined;
     reuse_session?: boolean | undefined;
-    configuration?: Record<string, unknown> | undefined;
+    id?: number | undefined;
 }, {
     action: "create" | "update" | "delete" | "toggle";
     status?: "enabled" | "disabled" | undefined;
     goal?: string | undefined;
     mcp_servers?: string[] | undefined;
     trigger_type?: "slack" | "schedule" | undefined;
+    configuration?: Record<string, unknown> | undefined;
     name?: string | undefined;
-    id?: number | undefined;
     agent_root_name?: string | undefined;
     prompt_template?: string | undefined;
     reuse_session?: boolean | undefined;
-    configuration?: Record<string, unknown> | undefined;
+    id?: number | undefined;
 }>;
 export declare function actionTriggerTool(_server: Server, clientFactory: () => IAgentOrchestratorClient): {
     name: string;

package/shared/tools/manage-categories.d.ts

@@ -11,16 +11,16 @@ export declare const ManageCategoriesSchema: z.ZodObject<{
     session_id: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
 }, "strip", z.ZodTypeAny, {
     action: "list" | "create" | "update" | "delete" | "reorder" | "set_session_category";
-    description?: string | undefined;
     name?: string | undefined;
+    description?: string | undefined;
     session_id?: string | number | undefined;
     category_id?: number | null | undefined;
     is_frozen?: boolean | undefined;
     ids?: (number | "uncategorized")[] | undefined;
 }, {
     action: "list" | "create" | "update" | "delete" | "reorder" | "set_session_category";
-    description?: string | undefined;
     name?: string | undefined;
+    description?: string | undefined;
     session_id?: string | number | undefined;
     category_id?: number | null | undefined;
     is_frozen?: boolean | undefined;

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;
@@ -298,6 +305,7 @@ export interface TriggerChannelsResponse {
     }>;
 }
 export interface TriggerConditionAttributes {
+    id?: number;
     condition_type: TriggerConditionType;
     configuration: Record<string, unknown>;
 }