Method executeHeartbeat

src/node/services/workspaceService.ts:9204–9259

* Execute a synthetic heartbeat turn for an idle workspace. * * This path is frontend-independent: heartbeats still run even if no UI is open. * Throws on failure so HeartbeatService can log and continue with the next workspace.

(workspaceId: string)

   * Throws on failure so HeartbeatService can log and continue with the next workspace.
   */
  async executeHeartbeat(workspaceId: string): Promise<void> {
    assert(workspaceId.trim().length > 0, "executeHeartbeat requires a non-empty workspaceId");

    const heartbeatRequest = await this.buildHeartbeatRequest(workspaceId);
    const session = this.getOrCreateSession(workspaceId);
    if (session.isBusy()) {
      throw new Error(
        "Failed to execute heartbeat: Workspace is busy; idle-only send was skipped."
      );
    }
    if (session.hasQueuedMessages()) {
      throw new Error(
        "Failed to execute heartbeat: Workspace has queued user input; idle-only send was skipped."
      );
    }

    log.info("Executing heartbeat", {
      workspaceId,
      contextMode: heartbeatRequest.contextMode,
      model: heartbeatRequest.sendOptions.model,
      agentId: heartbeatRequest.sendOptions.agentId,
    });

    switch (heartbeatRequest.contextMode) {
      case "normal":
        await this.dispatchHeartbeatMessage(workspaceId, heartbeatRequest);
        return;
      case "compact":
        await this.dispatchHeartbeatCompactionRequest(workspaceId, heartbeatRequest);
        return;
      case "reset": {
        const appendResult = await session.appendHeartbeatContextResetBoundary({
          boundaryText: HEARTBEAT_RESET_BOUNDARY_MESSAGE,
          pendingFollowUp: heartbeatRequest.followUp,
        });
        if (!appendResult.success) {
          throw new Error(`Failed to execute heartbeat: ${appendResult.error}`);
        }

        const dispatched = await session.dispatchPendingCompactionFollowUpIfNeeded(
          appendResult.data.summaryMessageId
        );
        if (!dispatched) {
          log.info("Skipped heartbeat follow-up after reset boundary", {
            workspaceId,
            contextMode: heartbeatRequest.contextMode,
          });
        }
        return;
      }
      default: {
        const exhaustiveContextMode: never = heartbeatRequest.contextMode;
        throw new Error(`Unhandled heartbeat context mode: ${String(exhaustiveContextMode)}`);
      }
    }
  }

  private async buildHeartbeatRequest(workspaceId: string): Promise<HeartbeatExecutionRequest> {