// Structured heartbeat response tool payload helpers.

import { isRecord } from "@openclaw/normalization-core/record-coerce";

import { normalizeOptionalString as readString } from "@openclaw/normalization-core/string-coerce";

import type { ReplyPayload } from "./reply-payload.js";

import { HEARTBEAT_TOKEN } from "./tokens.js";

/** Tool name used by heartbeat runs to report visible or silent progress. */

export const HEARTBEAT_RESPONSE_TOOL_NAME = "heartbeat_respond";

const HEARTBEAT_RESPONSE_CHANNEL_DATA_KEY = "openclawHeartbeatResponse";

/** Allowed heartbeat response outcomes. */

export const HEARTBEAT_TOOL_OUTCOMES = [

"no_change",

"progress",

] as const;

type HeartbeatToolOutcome = (typeof HEARTBEAT_TOOL_OUTCOMES)[number];

/** Allowed heartbeat notification priorities. */

export const HEARTBEAT_TOOL_PRIORITIES = ["low", "normal", "high"] as const;

type HeartbeatToolPriority = (typeof HEARTBEAT_TOOL_PRIORITIES)[number];

/** Normalized response emitted by the heartbeat response tool. */

export type HeartbeatToolResponse = {

outcome: HeartbeatToolOutcome;

notify: boolean;

return undefined;

}

/** Validate and normalize unknown heartbeat tool output. */

export function normalizeHeartbeatToolResponse(value: unknown): HeartbeatToolResponse | undefined {

if (!isRecord(value)) {

return undefined;

};

}

/** Resolve the user-visible notification text for a heartbeat response. */

export function getHeartbeatToolNotificationText(response: HeartbeatToolResponse): string {

return response.notify ? (response.notificationText ?? response.summary).trim() : "";

}

/** Store a heartbeat tool response in reply channel data for later extraction. */

export function createHeartbeatToolResponsePayload(response: HeartbeatToolResponse): ReplyPayload {

return {

text: response.notify ? getHeartbeatToolNotificationText(response) : HEARTBEAT_TOKEN,

);

}

/** Find the last heartbeat tool response embedded in a reply result. */

export function resolveHeartbeatToolResponseFromReplyResult(

replyResult: ReplyPayload | ReplyPayload[] | undefined,

): HeartbeatToolResponse | undefined {