@ynhcj/xiaoyi-channel 0.0.217-beta → 0.0.217-next

package/dist/src/cron-query-handler.js

@@ -3,16 +3,96 @@
 // calls Gateway cron RPC via callGatewayTool, and sends the
 // result back to the client via sendCommand as a System.CronQuery
 // command with the result in payload.ans.
+//
+// This module adapts between the XY Channel device-facing RPC schema
+// and the OpenClaw Gateway native cron RPC (protocol v4).
+// Each action transforms request params from device format → gateway format,
+// then transforms the gateway response → device format before sending back.
 import { callGatewayTool } from "openclaw/plugin-sdk/agent-harness-runtime";
-import * as os from "os";
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
 import { sendCommand } from "./formatter.js";
 import { resolveXYConfig } from "./config.js";
 import { configManager } from "./utils/config-manager.js";
 import { setJobPushId } from "./utils/cron-push-map.js";
 import { logger } from "./utils/logger.js";
-import { readFileSync, readdirSync } from "fs";
-import { join } from "path";
+// ── Local run-log constants, types, and parsers (moved from cron-recovery) ───
+const ROOT_DIR = path.join(os.homedir(), ".openclaw");
+/** Path to the legacy cron run-log directory. */
+const LEGACY_CRON_RUNS_DIR = path.join(ROOT_DIR, "cron", "runs");
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readString(record, key) {
+    const val = record[key];
+    return typeof val === "string" && val.trim() ? val.trim() : undefined;
+}
+function readOptionalString(record, key) {
+    const val = record[key];
+    return typeof val === "string" ? val : undefined;
+}
+function readNumber(record, key) {
+    const val = record[key];
+    return typeof val === "number" && Number.isFinite(val) ? val : undefined;
+}
+function readBoolean(record, key) {
+    const val = record[key];
+    return typeof val === "boolean" ? val : undefined;
+}
+function parseRunLogEntry(obj, opts) {
+    if (!isRecord(obj))
+        return null;
+    const ts = readNumber(obj, "ts");
+    if (ts === undefined)
+        return null;
+    const jobId = opts?.jobId ?? readString(obj, "jobId");
+    if (!jobId)
+        return null;
+    return {
+        jobId,
+        ts,
+        runId: readOptionalString(obj, "runId"),
+        status: readOptionalString(obj, "status"),
+        error: readOptionalString(obj, "error"),
+        summary: readOptionalString(obj, "summary"),
+        diagnosticsSummary: readOptionalString(obj, "diagnosticsSummary"),
+        deliveryStatus: readOptionalString(obj, "deliveryStatus"),
+        deliveryError: readOptionalString(obj, "deliveryError"),
+        delivered: readBoolean(obj, "delivered"),
+        sessionId: readOptionalString(obj, "sessionId"),
+        sessionKey: readOptionalString(obj, "sessionKey"),
+        runAtMs: readNumber(obj, "runAtMs"),
+        durationMs: readNumber(obj, "durationMs"),
+        nextRunAtMs: readNumber(obj, "nextRunAtMs"),
+        model: readOptionalString(obj, "model"),
+        provider: readOptionalString(obj, "provider"),
+        totalTokens: readNumber(obj, "totalTokens"),
+    };
+}
+function parseCronRunLogEntriesFromJsonl(raw, opts) {
+    if (!raw.trim())
+        return [];
+    const entries = [];
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const entry = parseRunLogEntry(JSON.parse(trimmed), opts);
+            if (entry)
+                entries.push(entry);
+        }
+        catch {
+            // Skip malformed historical rows
+        }
+    }
+    return entries;
+}
 const GATEWAY_TIMEOUT_MS = 60_000;
+// ============================================================================
+// Main handler
+// ============================================================================
 /**
  * Handle a cron-query-event.
  *
@@ -27,47 +107,111 @@ export async function handleCronQueryEvent(context, cfg) {
     let error;
     try {
         switch (action) {
-            case "list":
-                result = await callGatewayTool("cron.list", { timeoutMs: GATEWAY_TIMEOUT_MS }, params ?? {});
+            // ── list ──────────────────────────────────────────────────────
+            case "list": {
+                const gatewayParams = buildListParams(params);
+                let gatewayResult = await callGatewayTool("cron.list", { timeoutMs: GATEWAY_TIMEOUT_MS }, gatewayParams);
+                // Scan for systemEvent jobs and migrate them to agentTurn
+                // Skip main-session jobs — gateway requires payload.kind="systemEvent" for those
+                const jobs = gatewayResult?.jobs ?? [];
+                const systemEventJobs = jobs.filter((j) => j?.payload?.kind === "systemEvent");
+                if (systemEventJobs.length > 0) {
+                    log.log(`[CRON-QUERY] list: found ${systemEventJobs.length} systemEvent jobs, migrating to agentTurn`);
+                    for (const job of systemEventJobs) {
+                        const updatePatch = {
+                            sessionTarget: "isolated",
+                            description: job.payload?.text ?? job.payload?.message ?? "",
+                            payload: {
+                                kind: "agentTurn",
+                                message: job.payload?.text ?? job.payload?.message ?? "",
+                            },
+                            delivery: {
+                                channel: "xiaoyi-channel",
+                                mode: "announce",
+                                to: "default"
+                            }
+                        };
+                        try {
+                            await callGatewayTool("cron.update", { timeoutMs: GATEWAY_TIMEOUT_MS }, { id: job.id, patch: updatePatch });
+                            log.log(`[CRON-QUERY] list: migrated job ${job.id} (${job.name ?? ""}) from systemEvent → agentTurn`);
+                        }
+                        catch (err) {
+                            log.warn(`[CRON-QUERY] list: failed to migrate job ${job.id}:`, err);
+                        }
+                    }
+                    // Re-fetch list after migration
+                    gatewayResult = await callGatewayTool("cron.list", { timeoutMs: GATEWAY_TIMEOUT_MS }, gatewayParams);
+                }
+                result = transformListResponse(gatewayResult, params);
                 break;
-            case "status":
-                result = await callGatewayTool("cron.status", { timeoutMs: GATEWAY_TIMEOUT_MS }, {});
+            }
+            // ── status ────────────────────────────────────────────────────
+            case "status": {
+                const gatewayResult = await callGatewayTool("cron.status", { timeoutMs: GATEWAY_TIMEOUT_MS }, {});
+                result = transformStatusResponse(gatewayResult);
                 break;
-            case "runs":
-                result = await callGatewayTool("cron.runs", { timeoutMs: GATEWAY_TIMEOUT_MS }, {
-                    jobId,
-                    ...params,
-                });
+            }
+            // ── runs ─────────────────────────────────────────────────────
+            case "runs": {
+                const { offset = 0, limit = 50, ...otherParams } = params ?? {};
+                // Fetch from local runs folder and gateway RPC in parallel
+                const [localEntries, gatewayResult] = await Promise.all([
+                    readLocalRunLogsForJob(jobId).catch(() => []),
+                    callGatewayTool("cron.runs", { timeoutMs: GATEWAY_TIMEOUT_MS }, { jobId, scope: "job", ...otherParams }).catch(() => ({ entries: [] })),
+                ]);
+                const gatewayEntries = gatewayResult?.entries ?? [];
+                // Merge, deduplicate, and sort by time (newest first)
+                const merged = mergeAndDedupeRunEntries(localEntries, gatewayEntries);
+                // Apply pagination after merge
+                const total = merged.length;
+                const paged = merged.slice(offset, offset + limit);
+                const hasMore = total > offset + limit;
+                result = {
+                    entries: paged,
+                    total,
+                    offset,
+                    limit,
+                    hasMore,
+                    nextOffset: hasMore ? offset + limit : null,
+                };
                 break;
-            case "add":
-                result = await callGatewayTool("cron.add", { timeoutMs: GATEWAY_TIMEOUT_MS }, params ?? {});
+            }
+            // ── add ──────────────────────────────────────────────────────
+            case "add": {
+                const gatewayParams = buildAddParams(params);
+                const gatewayResult = await callGatewayTool("cron.add", { timeoutMs: GATEWAY_TIMEOUT_MS }, gatewayParams);
                 // 捕获 jobId↔pushId：cron-query 路径由 channel 自己建 job，
                 // 此处 context 握着 sessionId，configManager 有对应设备 pushId。
-                await persistCronPushMap(context.sessionId, result).catch((err) => {
+                await persistCronPushMap(context.sessionId, gatewayResult).catch((err) => {
                     logger.error(`[CRON-QUERY] Failed to persist cron-push-map:`, err);
                 });
+                result = transformAddResponse(gatewayResult);
                 break;
-            case "update":
-                result = await callGatewayTool("cron.update", { timeoutMs: GATEWAY_TIMEOUT_MS }, {
-                    jobId,
-                    ...params,
-                });
+            }
+            // ── update ───────────────────────────────────────────────────
+            case "update": {
+                const gatewayParams = buildUpdateParams(jobId, params);
+                const gatewayResult = await callGatewayTool("cron.update", { timeoutMs: GATEWAY_TIMEOUT_MS }, gatewayParams);
+                result = transformUpdateResponse(gatewayResult);
                 break;
-            case "remove":
-                result = await callGatewayTool("cron.remove", { timeoutMs: GATEWAY_TIMEOUT_MS }, {
-                    jobId,
-                });
+            }
+            // ── remove ───────────────────────────────────────────────────
+            case "remove": {
+                const gatewayResult = await callGatewayTool("cron.remove", { timeoutMs: GATEWAY_TIMEOUT_MS }, { id: jobId });
+                result = transformRemoveResponse(gatewayResult);
                 break;
-            case "run":
-                result = await callGatewayTool("cron.run", { timeoutMs: GATEWAY_TIMEOUT_MS }, {
-                    jobId,
-                    mode: "force",
-                    ...params,
-                });
+            }
+            // ── run ──────────────────────────────────────────────────────
+            case "run": {
+                const gatewayResult = await callGatewayTool("cron.run", { timeoutMs: GATEWAY_TIMEOUT_MS }, { id: jobId, mode: "force" });
+                result = transformRunResponse(gatewayResult);
                 break;
-            case "queryTimeList":
-                result = await queryTimeListLocal();
+            }
+            // ── queryTimeList ────────────────────────────────────────────
+            case "queryTimeList": {
+                result = await queryTimeListFromGateway(params);
                 break;
+            }
             default:
                 error = `Unknown action: ${context.action}`;
                 log.error(`[CRON-QUERY] ${error}`);
@@ -81,7 +225,7 @@ export async function handleCronQueryEvent(context, cfg) {
     }
     // Log the result
     log.log(`[CRON-QUERY] RPC result for action=${action}: ${JSON.stringify(result, null, 2)}`);
-    // Send result back via sendCommand as System.CronQuery with payload.ans
+    // Send result back via sendCommand as AgentEvent.CronQuery with payload.ans
     if (cfg && sessionId && taskId && messageId) {
         try {
             const config = resolveXYConfig(cfg);
@@ -92,6 +236,7 @@ export async function handleCronQueryEvent(context, cfg) {
                 },
                 payload: {
                     action,
+                    status: !error,
                     ans: result,
                 },
             };
@@ -113,6 +258,114 @@ export async function handleCronQueryEvent(context, cfg) {
         log.warn(`[CRON-QUERY] Missing cfg/sessionId/taskId/messageId, skipping sendCommand`);
     }
 }
+// ============================================================================
+// Request builders — device params → gateway params
+// ============================================================================
+/** list: device params pass through (gateway-compatible). */
+function buildListParams(params) {
+    return params ?? {};
+}
+/** add: unwrap params.job → top-level gateway params. */
+function buildAddParams(params) {
+    const job = params?.job ?? params ?? {};
+    return {
+        name: job.name,
+        schedule: job.schedule,
+        sessionTarget: job.sessionTarget,
+        wakeMode: job.wakeMode,
+        payload: job.payload,
+        enabled: job.enabled,
+        deleteAfterRun: job.deleteAfterRun,
+        delivery: job.delivery,
+        description: job.description,
+        failureAlert: job.failureAlert,
+    };
+}
+/** update: unwrap params.patch → patch, add jobId. */
+function buildUpdateParams(jobId, params) {
+    const patch = params?.patch ?? params ?? {};
+    return {
+        id: jobId,
+        patch
+    };
+}
+// ============================================================================
+// Response transformers — gateway result → device format
+// ============================================================================
+/** Compute pagination metadata from request params and total. */
+function computePagination(params, total) {
+    const offset = params?.offset ?? 0;
+    const limit = params?.limit ?? total;
+    const hasMore = total > offset + limit;
+    const nextOffset = hasMore ? offset + limit : null;
+    return { offset, limit, hasMore, nextOffset };
+}
+/** list: add pagination fields + status. */
+function transformListResponse(gatewayResult, params) {
+    const jobs = gatewayResult?.jobs ?? [];
+    const total = gatewayResult?.total ?? jobs.length;
+    const pagination = computePagination(params, total);
+    return {
+        jobs,
+        total,
+        offset: pagination.offset,
+        limit: pagination.limit,
+        hasMore: pagination.hasMore,
+        nextOffset: pagination.nextOffset,
+        deliveryPreviews: gatewayResult?.deliveryPreviews ?? {},
+    };
+}
+/** status: rename nextRunAtMs → nextWakeAtMs, add storePath. */
+function transformStatusResponse(gatewayResult) {
+    return {
+        enabled: gatewayResult?.enabled ?? false,
+        storePath: ".openclaw/cron/jobs.json",
+        jobs: gatewayResult?.jobs ?? 0,
+        nextWakeAtMs: gatewayResult?.nextRunAtMs ?? null,
+    };
+}
+/** add: pick relevant fields from gateway CronJob response. */
+function transformAddResponse(gatewayResult) {
+    return {
+        id: gatewayResult?.id,
+        name: gatewayResult?.name,
+        enabled: gatewayResult?.enabled,
+        description: gatewayResult?.payload?.message,
+        createdAtMs: gatewayResult?.createdAtMs,
+        updatedAtMs: gatewayResult?.updatedAtMs,
+        schedule: gatewayResult?.schedule,
+        sessionTarget: gatewayResult?.sessionTarget,
+        wakeMode: gatewayResult?.wakeMode,
+        payload: gatewayResult?.payload,
+        delivery: gatewayResult?.delivery,
+        state: {
+            nextRunAtMs: gatewayResult?.state?.nextRunAtMs ?? null,
+        },
+    };
+}
+/** update: same structure as add. */
+function transformUpdateResponse(gatewayResult) {
+    return transformAddResponse(gatewayResult);
+}
+/** remove: wrap with ok flag. */
+function transformRemoveResponse(gatewayResult) {
+    return {
+        ok: gatewayResult?.removed ?? false,
+        removed: gatewayResult?.removed ?? false,
+    };
+}
+/** run: map ran → enqueued. */
+function transformRunResponse(gatewayResult) {
+    return {
+        ok: gatewayResult?.ok ?? false,
+        runId: gatewayResult?.runId ?? null,
+        enqueued: gatewayResult?.ran ?? false,
+        error: gatewayResult?.error ?? undefined,
+    };
+}
+// ============================================================================
+// Supporting functions
+// ============================================================================
 /**
  * 从 cron.add 结果中提取 jobId，配合 sessionId 对应的 pushId 写入映射。
  */
@@ -129,7 +382,9 @@ async function persistCronPushMap(sessionId, result) {
             jobId = id.trim();
     }
     if (!jobId) {
-        const preview = typeof result === "string" ? result.slice(0, 200) : JSON.stringify(result)?.slice(0, 200);
+        const preview = typeof result === "string"
+            ? result.slice(0, 200)
+            : JSON.stringify(result)?.slice(0, 200);
         logger.log(`[CRONMAP] cron-query skip: no jobId in result. preview=${preview ?? "(empty)"}`);
         return;
     }
@@ -143,72 +398,46 @@ async function persistCronPushMap(sessionId, result) {
     logger.log(`[CRONMAP] cron-query map written OK`);
 }
 /**
- * Read local cron folder directly (bypassing openclaw RPC) and return
- * run records from the last 7 days, grouped by date and sorted by time.
- *
- * Data sources:
- *   - state/cron/jobs.json   → job id → name mapping
- *   - state/cron/runs/*.jsonl → run records (one JSON per line)
+ * Query run history from the last 7 days from both local runs folder
+ * and the gateway's native cron.runs RPC, merged and grouped by date.
  *
  * Return format:
  *   [ { "YYYY-MM-DD": [ { run record with .name }, ... ] }, ... ]
  */
-async function queryTimeListLocal() {
-    const cronDir = join(os.homedir(), ".openclaw", "cron");
-    const jobsPath = join(cronDir, "jobs.json");
-    const runsDir = join(cronDir, "runs");
-    // 1. Build jobId → name map from jobs.json
-    const jobNameMap = {};
-    try {
-        const jobsRaw = readFileSync(jobsPath, "utf-8");
-        const jobsData = JSON.parse(jobsRaw);
-        for (const job of jobsData.jobs || []) {
-            jobNameMap[job.id] = job.name || job.id;
-        }
-    }
-    catch (err) {
-        logger.error(`[CRON-QUERY] Failed to read jobs.json: ${err.message}`);
+async function queryTimeListFromGateway(params) {
+    // Fetch from local runs folder and gateway RPC in parallel
+    const [localEntries, rpcResult] = await Promise.all([
+        readAllLocalRunLogs().catch(() => []),
+        callGatewayTool("cron.runs", { timeoutMs: GATEWAY_TIMEOUT_MS }, {
+            scope: "all",
+            limit: 200,
+            sortDir: "desc",
+            ...(params ?? {}),
+        }).catch(() => ({ entries: [] })),
+    ]);
+    const gatewayEntries = rpcResult?.entries ?? [];
+    // Merge and deduplicate
+    const merged = mergeAndDedupeRunEntries(localEntries, gatewayEntries);
+    if (merged.length === 0) {
+        return [];
     }
-    // 2. Read all run files, collect runs within last 7 days
+    // Filter to last 7 days
     const sevenDaysAgo = Date.now() - 7 * 24 * 60 * 60 * 1000;
-    const allRuns = [];
-    let files = [];
-    try {
-        files = readdirSync(runsDir);
-    }
-    catch {
-        files = [];
-    }
-    for (const file of files) {
-        if (!file.endsWith(".jsonl"))
-            continue;
-        try {
-            const content = readFileSync(join(runsDir, file), "utf-8");
-            const lines = content.trim().split("\n");
-            for (const line of lines) {
-                if (!line.trim())
-                    continue;
-                try {
-                    const run = JSON.parse(line);
-                    if (run.ts && run.ts >= sevenDaysAgo) {
-                        run.name = jobNameMap[run.jobId] || run.jobId || "";
-                        allRuns.push(run);
-                    }
-                }
-                catch {
-                    // skip malformed line
-                }
-            }
+    const recent = merged.filter((e) => e.ts && e.ts >= sevenDaysAgo);
+    // Ensure .name is populated (gateway returns jobName; normalize to .name)
+    for (const run of recent) {
+        if (!run.name && run.jobName) {
+            run.name = run.jobName;
         }
-        catch (err) {
-            logger.error(`[CRON-QUERY] Failed to read run file ${file}: ${err.message}`);
+        else if (!run.name) {
+            run.name = run.jobId || "";
         }
     }
-    // 3. Sort by ts ascending
-    allRuns.sort((a, b) => a.ts - b.ts);
-    // 4. Group by date (YYYY-MM-DD in local time)
+    // Sort by ts ascending for chronological display
+    recent.sort((a, b) => a.ts - b.ts);
+    // Group by date (YYYY-MM-DD in local time)
     const grouped = new Map();
-    for (const run of allRuns) {
+    for (const run of recent) {
         const d = new Date(run.ts);
         const label = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
         if (!grouped.has(label)) {
@@ -216,10 +445,171 @@ async function queryTimeListLocal() {
         }
         grouped.get(label).push(run);
     }
-    // 5. Convert to ordered array of single-key objects
+    // Convert to ordered array of single-key objects
     const result = [];
     for (const [date, runs] of grouped) {
         result.push({ [date]: runs });
     }
     return result;
 }
+// ============================================================================
+// Local run-log helpers — read legacy runs/*.jsonl files
+// ============================================================================
+/**
+ * Filename patterns that may contain legacy run-log data.
+ *
+ * After cron-recovery migration (gateway_start hook), .jsonl files are
+ * archived to .jsonl.migrated (or .migrated.2, .migrated.3, …).
+ * We must match all of these so that historical runs are still visible
+ * in queryTimeList after migration.
+ */
+const RUN_LOG_SUFFIXES = [
+    ".jsonl", // active / pre-migration
+    ".jsonl.migrated", // first migration
+];
+/**
+ * Check whether a filename looks like a run-log file (any generation).
+ */
+function isRunLogFile(name) {
+    return RUN_LOG_SUFFIXES.some((suffix) => name.endsWith(suffix))
+        // Also catch .migrated.2, .migrated.3, …
+        || /\.jsonl\.migrated\.\d+$/.test(name);
+}
+/**
+ * Strip known run-log suffixes to extract the bare jobId from a filename.
+ * e.g. "abc123.jsonl.migrated.2" → "abc123"
+ */
+function extractJobIdFromRunLogName(name) {
+    // Try each known suffix first
+    for (const suffix of RUN_LOG_SUFFIXES) {
+        if (name.endsWith(suffix)) {
+            return name.slice(0, -suffix.length);
+        }
+    }
+    // Fallback: strip .jsonl and everything after
+    const dotJsonl = name.indexOf(".jsonl");
+    if (dotJsonl >= 0) {
+        return name.slice(0, dotJsonl);
+    }
+    // Last resort: just use the basename without extension
+    return path.basename(name, path.extname(name));
+}
+/**
+ * Read local run-log entries for a single job from the legacy runs folder.
+ *
+ * Tries multiple filename suffixes (active + archived) since migration
+ * may have renamed the file to .jsonl.migrated.
+ */
+async function readLocalRunLogsForJob(jobId) {
+    // Try active file first, then archived variants
+    const candidates = [
+        `${jobId}.jsonl`,
+        `${jobId}.jsonl.migrated`,
+    ];
+    for (const candidate of candidates) {
+        const filePath = path.join(LEGACY_CRON_RUNS_DIR, candidate);
+        try {
+            const raw = await fsp.readFile(filePath, "utf-8");
+            if (raw.trim()) {
+                return parseCronRunLogEntriesFromJsonl(raw, { jobId });
+            }
+        }
+        catch {
+            // Try next candidate
+        }
+    }
+    // Also scan for .migrated.N variants
+    try {
+        const dirEntries = await fsp.readdir(LEGACY_CRON_RUNS_DIR, { withFileTypes: true });
+        const migratedRe = new RegExp(`^${escapeRegex(jobId)}\\.jsonl\\.migrated\\.\\d+$`);
+        for (const entry of dirEntries) {
+            if (entry.isFile() && migratedRe.test(entry.name)) {
+                try {
+                    const raw = await fsp.readFile(path.join(LEGACY_CRON_RUNS_DIR, entry.name), "utf-8");
+                    if (raw.trim()) {
+                        return parseCronRunLogEntriesFromJsonl(raw, { jobId });
+                    }
+                }
+                catch {
+                    // Keep trying other candidates
+                }
+            }
+        }
+    }
+    catch {
+        // Directory listing failed, give up
+    }
+    return [];
+}
+/**
+ * Read all local run-log entries from the legacy runs folder.
+ *
+ * Matches .jsonl files as well as post-migration archived copies
+ * (.jsonl.migrated, .jsonl.migrated.2, …).
+ */
+async function readAllLocalRunLogs() {
+    try {
+        const entries = await fsp.readdir(LEGACY_CRON_RUNS_DIR, { withFileTypes: true });
+        const runLogFiles = entries.filter((e) => e.isFile() && isRunLogFile(e.name));
+        const allEntries = [];
+        for (const file of runLogFiles) {
+            const jobId = extractJobIdFromRunLogName(file.name);
+            try {
+                const raw = await fsp.readFile(path.join(LEGACY_CRON_RUNS_DIR, file.name), "utf-8");
+                const parsed = parseCronRunLogEntriesFromJsonl(raw, { jobId });
+                allEntries.push(...parsed);
+            }
+            catch {
+                // Skip unreadable files
+            }
+        }
+        return allEntries;
+    }
+    catch {
+        return [];
+    }
+}
+/** Escape special regex characters in a string. */
+function escapeRegex(s) {
+    return s.replace(/[-\/\\^$*+?.()|[\]{}]/g, "\\$&");
+}
+/**
+ * Build a dedup key for a run-log entry.
+ */
+function makeRunEntryKey(entry) {
+    return [
+        entry.jobId,
+        String(entry.ts),
+        entry.runId ?? "",
+        entry.status ?? "",
+        entry.summary ?? "",
+        entry.error ?? "",
+    ].join("\0");
+}
+/**
+ * Merge local and gateway run entries, deduplicate, and sort by ts descending.
+ * Gateway entries take precedence over local entries with the same key.
+ */
+function mergeAndDedupeRunEntries(localEntries, gatewayEntries) {
+    const seen = new Set();
+    const merged = [];
+    // Add gateway entries first (they take precedence)
+    for (const entry of gatewayEntries) {
+        const key = makeRunEntryKey(entry);
+        if (!seen.has(key)) {
+            seen.add(key);
+            merged.push(entry);
+        }
+    }
+    // Add local entries that aren't already in gateway results
+    for (const entry of localEntries) {
+        const key = makeRunEntryKey(entry);
+        if (!seen.has(key)) {
+            seen.add(key);
+            merged.push(entry);
+        }
+    }
+    // Sort by ts descending (newest first)
+    merged.sort((a, b) => b.ts - a.ts);
+    return merged;
+}