@reefclaw/connect 0.1.36 → 0.1.38

package/assets/bridge/heartbeat-transcript.d.ts

@@ -0,0 +1,209 @@
+/** Max tool calls kept per record (the census still counts every call). */
+export declare const TOOL_CALLS_MAX = 250;
+/** Max chars of a tool call's JSON arguments. */
+export declare const ARGS_MAX = 300;
+/** Max chars of a tool result's text. */
+export declare const RESULT_MAX = 400;
+/** Max chars of the agent's final report text. */
+export declare const SUMMARY_MAX = 4000;
+/** Max model events kept. */
+export declare const MODEL_EVENTS_MAX = 50;
+/** Target upper bound for a serialized record (bytes). */
+export declare const RECORD_MAX_BYTES = 200000;
+export interface HeartbeatToolCall {
+    /** The gateway's toolCallId (pairs the call with its result). */
+    id: string;
+    name: string;
+    /** Epoch ms of the assistant message that issued the call, when known. */
+    at: number | null;
+    /** false when the tool result flagged isError; null when no result was seen. */
+    ok: boolean | null;
+    /** Compact JSON of the arguments, truncated; '[redacted]' for sensitive tools. */
+    args: string;
+    /** Truncated result text ('' when no result was seen). */
+    result: string;
+    /** result.timestamp − call.timestamp when both are present. */
+    durationMs: number | null;
+}
+export type HeartbeatModelEventKind = 'model_change' | 'thinking_level_change' | 'fallback_step' | 'error';
+export interface HeartbeatModelEvent {
+    kind: HeartbeatModelEventKind;
+    at: number | null;
+    detail: string;
+}
+export type HeartbeatRunStatus = 'ok' | 'error' | 'incomplete' | 'unknown';
+export interface HeartbeatTokens {
+    input: number | null;
+    output: number | null;
+    cacheRead: number | null;
+    cacheWrite: number | null;
+    total: number | null;
+    /** Where the counts came from — the dashboard labels 'none' as "n/a". */
+    source: 'run_log' | 'trajectory' | 'transcript' | 'none';
+}
+export interface HeartbeatRunRecord {
+    /** The isolated cron session id — one per beat, the idempotency key. */
+    runId: string;
+    cronJobId: string | null;
+    cronJobName: string | null;
+    trigger: 'cron' | 'unknown';
+    status: HeartbeatRunStatus;
+    startedAtMs: number;
+    endedAtMs: number | null;
+    durationMs: number | null;
+    /** `<provider>/<model>` that answered, when known. */
+    model: string | null;
+    tokens: HeartbeatTokens;
+    toolCallCount: number;
+    toolErrorCount: number;
+    toolCensus: Record<string, number>;
+    toolCalls: HeartbeatToolCall[];
+    /** The agent's final report text (what went to Telegram), truncated. */
+    summary: string | null;
+    modelEvents: HeartbeatModelEvent[];
+    /** Run-level error text (cron run log / promptError / assistant errorMessage). */
+    error: string | null;
+    /** OpenClaw FailoverReason from the cron run log (auth, rate_limit, format, …). */
+    errorReason: string | null;
+    mode: 'paper' | 'live' | null;
+    meta: {
+        transcriptBytes: number;
+        trajectoryBytes: number | null;
+        assistantMessages: number;
+        /** True when tool calls / results / summary were trimmed to fit the caps. */
+        truncated: boolean;
+        /** Tool catalog size the session started with (trajectory session.started). */
+        toolCount: number | null;
+        /** Model API the assistant messages carry (e.g. "openai-chatgpt-responses"). */
+        api: string | null;
+        thinkingLevel: string | null;
+    };
+}
+/** The subset of an OpenClaw cron run-log entry the recorder consumes
+ *  (gateway RPC `cron.runs` → `entries[]`, vendored `run-log-types.ts`). */
+export interface CronRunLogLite {
+    sessionId: string | null;
+    runId: string | null;
+    status: string | null;
+    error: string | null;
+    errorReason: string | null;
+    runAtMs: number | null;
+    durationMs: number | null;
+    model: string | null;
+    provider: string | null;
+    usage: {
+        input: number | null;
+        output: number | null;
+        cacheRead: number | null;
+        cacheWrite: number | null;
+        total: number | null;
+    } | null;
+}
+/** OpenClaw's state dir — `OPENCLAW_STATE_DIR` is the real override (the
+ *  bridge historically read a non-existent OPENCLAW_HOME; honour both). */
+export declare function resolveOpenClawStateDir(env?: NodeJS.ProcessEnv): string;
+export declare function resolveSessionsDir(agentId?: string, env?: NodeJS.ProcessEnv): string;
+export interface SessionCandidate {
+    sessionId: string;
+    file: string;
+    trajectoryFile: string | null;
+    mtimeMs: number;
+    sizeBytes: number;
+}
+/** Every `<sessionId>.jsonl` transcript in `dir` (not sidecars, checkpoints,
+ *  topic files or retired copies) modified at/after `minMtimeMs`, excluding
+ *  `exclude`d session ids. Never throws — a missing dir yields []. */
+export declare function listSessionCandidates(dir: string, opts?: {
+    minMtimeMs?: number;
+    exclude?: Set<string>;
+}): SessionCandidate[];
+export interface CronMarker {
+    jobId: string;
+    jobName: string | null;
+}
+export declare function parseCronMarker(text: string | null | undefined): CronMarker | null;
+/** Read only the head of a transcript and report whether its first user
+ *  message carries the `[cron:…]` marker. `null` = inconclusive (no user
+ *  message within the head) — callers then fall back to the trajectory key. */
+export declare function readCronMarker(file: string, headBytes?: number): CronMarker | null | undefined;
+export interface TranscriptUsage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+}
+export interface ParsedTranscript {
+    sessionId: string | null;
+    headerAtMs: number | null;
+    cron: CronMarker | null;
+    firstUserAtMs: number | null;
+    lastAtMs: number | null;
+    toolCalls: HeartbeatToolCall[];
+    /** Total calls seen (may exceed toolCalls.length once the cap trims). */
+    toolCallTotal: number;
+    toolErrorCount: number;
+    toolCensus: Record<string, number>;
+    assistantCount: number;
+    finalText: string | null;
+    /** `<provider>/<model>` ids in order of first appearance. */
+    models: string[];
+    api: string | null;
+    usage: TranscriptUsage;
+    usageNonZero: boolean;
+    lastStopReason: string | null;
+    lastErrorMessage: string | null;
+    modelEvents: HeartbeatModelEvent[];
+    thinkingLevel: string | null;
+    /** The last assistant message ended the turn (not mid tool-chain). */
+    complete: boolean;
+    truncated: boolean;
+    bytes: number;
+}
+/** Text of a content block / content array in every shape OpenClaw writes. */
+export declare function textOf(content: unknown, depth?: number): string;
+export declare function parseSessionTranscript(text: string): ParsedTranscript;
+export interface ParsedTrajectory {
+    sessionKey: string | null;
+    runId: string | null;
+    provider: string | null;
+    modelId: string | null;
+    modelApi: string | null;
+    toolCount: number | null;
+    trigger: string | null;
+    thinkLevel: string | null;
+    ended: {
+        status: string | null;
+        timedOut: boolean;
+        promptError: string | null;
+    } | null;
+    /** From an UNtruncated model.completed event. */
+    usage: TranscriptUsage | null;
+    fallbackSteps: HeartbeatModelEvent[];
+    toolCallEvents: number;
+    firstTs: number | null;
+    lastTs: number | null;
+    bytes: number;
+}
+export declare function parseTrajectory(text: string): ParsedTrajectory;
+export declare function isCronSessionKey(key: string | null | undefined): boolean;
+export interface BuildRecordInput {
+    sessionId: string;
+    transcript: ParsedTranscript;
+    trajectory: ParsedTrajectory | null;
+    runLog: CronRunLogLite | null;
+    mode: 'paper' | 'live' | null;
+    /** Fallback start time when neither file carries one (file mtime). */
+    fallbackStartedAtMs: number;
+}
+export declare function buildHeartbeatRunRecord(i: BuildRecordInput): HeartbeatRunRecord;
+/** Shrink a record until its JSON fits `maxBytes`: first shorter tool
+ *  results, then no results, then fewer tool calls. Pure; returns a copy. */
+export declare function shrinkRecord(record: HeartbeatRunRecord, maxBytes?: number): HeartbeatRunRecord;
+export interface ReadSessionResult {
+    transcript: ParsedTranscript;
+    trajectory: ParsedTrajectory | null;
+}
+/** Read + parse a candidate's transcript and (when present) its trajectory.
+ *  Never throws on a missing/torn file — a missing transcript yields null. */
+export declare function readSession(c: SessionCandidate): ReadSessionResult | null;