Skip to content

The open-source app everyone uses to manage agents at work

refactor(server): extract heartbeat run-log formatting (#15573)

Dotta87a7312cfd23
diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.md
index 3ef4c6b62e..1809c2fc16 100644
--- a/doc/DEVELOPING.md
+++ b/doc/DEVELOPING.md
@@ -1204,12 +1204,20 @@ In Vite middleware mode, Paperclip gives HMR a dedicated HTTP server bound to th
When a workspace service runs Paperclip for browser OAuth QA, configure its `expose.urlTemplate` with the canonical URL the browser can reach. Paperclip preserves explicit `PAPERCLIP_PUBLIC_URL` or `BETTER_AUTH_URL` settings; otherwise it uses a valid exposed HTTPS origin (or loopback HTTP) as the managed runtime fallback for Better Auth and `/api/tools/oauth/callback`. Internal service names such as `http://paperclip-dev:<port>` are rejected unless that hostname is genuinely the browser route. Use a unique origin per isolated worktree. See [Execution Workspaces And Runtime Services](../docs/guides/board-operator/execution-workspaces-and-runtime-services.md#browser-reachable-origins-for-oauth-qa) for configuration and verification.
-## Wake Context Delivery
+## Heartbeat Service Extractions
+
+Keep relevant heartbeat extractions and their focused tests in `server/src/services/heartbeat/`.
Task assignment Markdown is rendered by `server/src/services/heartbeat/task-markdown.ts`.
`heartbeat.ts` calls the renderer and re-exports it for existing callers. Keep prompt
formatting changes in the renderer and its tests, separate from run orchestration.
-Keep relevant heartbeat extractions and their focused tests in `server/src/services/heartbeat/`.
+
+Run-log formatting is in `server/src/services/heartbeat/run-log.ts`. It bounds
+stored event payloads, redacts and shortens log chunks, and caps stdout/stderr
+excerpts. `heartbeat.ts` keeps event writes, current-user redaction, and live
+event delivery. Existing public helpers remain available from `heartbeat.ts`.
+
+## Wake Context Delivery
Built-in adapters deliver wake context through the run prompt, including structured
execution-continuation data. They do not export `PAPERCLIP_WAKE_PAYLOAD_JSON`. A
diff --git a/server/src/services/heartbeat.ts b/server/src/services/heartbeat.ts
index 68dd8bbec2..0e9118c75f 100644
--- a/server/src/services/heartbeat.ts
+++ b/server/src/services/heartbeat.ts
@@ -1,3 +1,12 @@
+import {
+ appendExcerpt,
+ boundHeartbeatRunEventPayloadForStorage,
+ compactRunLogChunk,
+} from "./heartbeat/run-log.js";
+export {
+ boundHeartbeatRunEventPayloadForStorage,
+ compactRunLogChunk,
+} from "./heartbeat/run-log.js";
import { buildPaperclipTaskMarkdown } from "./heartbeat/task-markdown.js";
export { buildPaperclipTaskMarkdown } from "./heartbeat/task-markdown.js";
import { preserveWorkspaceRestoreRecoveryMetadataSql } from "./legacy-workspace-restore-recovery.js";
@@ -327,8 +336,6 @@ import {
parseObject,
asBoolean,
asNumber,
- appendWithByteCap,
- MAX_EXCERPT_BYTES,
} from "../adapters/utils.js";
import {
authorizeChatConversationForBoundRun,
@@ -672,9 +679,6 @@ import type { PluginWorkerManager } from "./plugin-worker-manager.js";
import { serverVersion } from "../version.js";
const MAX_LIVE_LOG_CHUNK_BYTES = 8 * 1024;
-const MAX_PERSISTED_LOG_CHUNK_CHARS = 64 * 1024;
-const MAX_RUN_EVENT_PAYLOAD_STRING_CHARS = 16 * 1024;
-const MAX_RUN_EVENT_PAYLOAD_ARRAY_ITEMS = 50;
export function redactDetectedSuccessfulRunProgressSummaryForBoard(
summary: string,
@@ -697,8 +701,6 @@ export function redactSuccessfulRunHandoffEvidence(
);
}
-const MAX_RUN_EVENT_PAYLOAD_OBJECT_KEYS = 100;
-const MAX_RUN_EVENT_PAYLOAD_DEPTH = 6;
const HEARTBEAT_MAX_CONCURRENT_RUNS_DEFAULT = AGENT_DEFAULT_MAX_CONCURRENT_RUNS;
const HEARTBEAT_MAX_CONCURRENT_RUNS_MIN = 1;
const HEARTBEAT_MAX_CONCURRENT_RUNS_MAX = 50;
@@ -1433,8 +1435,6 @@ export function getTaskDrainStatus(): {
};
}
-const INLINE_BASE64_IMAGE_DATA_RE =
- /("type":"image","source":\{"type":"base64","data":")([A-Za-z0-9+/=]{1024,})(")/g;
type RuntimeConfigSecretResolver = Pick<
ReturnType<typeof secretService>,
| "resolveAdapterConfigForRuntime"
@@ -3722,115 +3722,6 @@ const heartbeatRunIssueSummaryColumns = {
issueId: heartbeatRuns.issueId,
} as const;
-function appendExcerpt(prev: string, chunk: string) {
- return appendWithByteCap(prev, chunk, MAX_EXCERPT_BYTES);
-}
-
-function truncateRunEventString(value: string) {
- if (value.length <= MAX_RUN_EVENT_PAYLOAD_STRING_CHARS) return value;
- const omittedChars = value.length - MAX_RUN_EVENT_PAYLOAD_STRING_CHARS;
- return `${value.slice(0, MAX_RUN_EVENT_PAYLOAD_STRING_CHARS)}\n[truncated ${omittedChars} chars]`;
-}
-
-function boundRunEventValue(
- value: unknown,
- depth: number,
- seen: WeakSet<object>,
-): unknown {
- if (typeof value === "string") {
- return truncateRunEventString(value);
- }
- if (
- value === null ||
- typeof value === "number" ||
- typeof value === "boolean"
- ) {
- return value;
- }
- if (value instanceof Date) {
- return value.toISOString();
- }
- if (Array.isArray(value)) {
- if (depth >= MAX_RUN_EVENT_PAYLOAD_DEPTH) {
- return {
- _truncated: true,
- type: "array",
- originalLength: value.length,
- };
- }
- const bounded = value
- .slice(0, MAX_RUN_EVENT_PAYLOAD_ARRAY_ITEMS)
- .map((entry) => boundRunEventValue(entry, depth + 1, seen));
- if (value.length > MAX_RUN_EVENT_PAYLOAD_ARRAY_ITEMS) {
- bounded.push({
- _truncated: true,
- omittedItems: value.length - MAX_RUN_EVENT_PAYLOAD_ARRAY_ITEMS,
- });
- }
- return bounded;
- }
- if (typeof value !== "object" || value === undefined) {
- return null;
- }
- if (seen.has(value)) {
- return "[Circular]";
- }
- seen.add(value);
- const entries = Object.entries(value as Record<string, unknown>);
- if (depth >= MAX_RUN_EVENT_PAYLOAD_DEPTH) {
- const bounded = {
- _truncated: true,
- type: "object",
- keys: entries.map(([key]) => key).slice(0, 20),
- };
- seen.delete(value);
- return bounded;
- }
-
- const out: Record<string, unknown> = {};
- for (const [key, entryValue] of entries.slice(
- 0,
- MAX_RUN_EVENT_PAYLOAD_OBJECT_KEYS,
- )) {
- out[key] = boundRunEventValue(entryValue, depth + 1, seen);
- }
- if (entries.length > MAX_RUN_EVENT_PAYLOAD_OBJECT_KEYS) {
- out._truncated = true;
- out._omittedKeys = entries.length - MAX_RUN_EVENT_PAYLOAD_OBJECT_KEYS;
- }
- seen.delete(value);
- return out;
-}
-
-export function boundHeartbeatRunEventPayloadForStorage(
- payload: Record<string, unknown>,
-): Record<string, unknown> {
- const bounded = boundRunEventValue(payload, 0, new WeakSet());
- return parseObject(bounded) ?? { _truncated: true };
-}
-
-function redactInlineBase64ImageData(chunk: string) {
- return chunk.replace(
- INLINE_BASE64_IMAGE_DATA_RE,
- (_match, prefix: string, data: string, suffix: string) =>
- `${prefix}[omitted base64 image data: ${data.length} chars]${suffix}`,
- );
-}
-
-export function compactRunLogChunk(
- chunk: string,
- maxChars = MAX_PERSISTED_LOG_CHUNK_CHARS,
-) {
- const normalized = redactSensitiveText(redactInlineBase64ImageData(chunk));
- if (normalized.length <= maxChars) return normalized;
-
- const headChars = Math.max(0, Math.floor(maxChars * 0.6));
- const tailChars = Math.max(0, Math.floor(maxChars * 0.25));
- const omittedChars = Math.max(0, normalized.length - headChars - tailChars);
- const marker = `\n[paperclip truncated run log chunk: omitted ${omittedChars} chars]\n`;
- return `${normalized.slice(0, headChars)}${marker}${normalized.slice(normalized.length - tailChars)}`;
-}
-
function normalizeMaxConcurrentRuns(value: unknown) {
const parsed = Math.floor(
asNumber(value, HEARTBEAT_MAX_CONCURRENT_RUNS_DEFAULT),
diff --git a/server/src/services/heartbeat/run-log.test.ts b/server/src/services/heartbeat/run-log.test.ts
new file mode 100644
index 0000000000..87fa5cf943
--- /dev/null
+++ b/server/src/services/heartbeat/run-log.test.ts
@@ -0,0 +1,175 @@
+import { describe, expect, it } from "vitest";
+import {
+ appendExcerpt,
+ boundHeartbeatRunEventPayloadForStorage,
+ compactRunLogChunk,
+} from "./run-log.js";
+
+describe("heartbeat run-log excerpts", () => {
+ it("appends chunks while preserving the most recent 32 KiB of output", () => {
+ const prefix = "x".repeat(32 * 1024);
+ expect(appendExcerpt("ready", "\nnext")).toBe("ready\nnext");
+ const full = appendExcerpt(prefix, "tail");
+ expect(full).toBe(`${"x".repeat(32 * 1024 - 4)}tail`);
+ expect(appendExcerpt(full, "next")).toBe(`${"x".repeat(32 * 1024 - 8)}tailnext`);
+ });
+
+ it("respects the byte limit without splitting a multibyte character", () => {
+ const suffix = "x".repeat(32 * 1024 - 4);
+ const excerpt = appendExcerpt(`🙂${suffix}`, "y");
+ expect(excerpt).toBe(`${suffix}y`);
+ expect(Buffer.byteLength(excerpt)).toBeLessThanOrEqual(32 * 1024);
+ });
+});
+
+describe("heartbeat run-log payload formatting", () => {
+ it("preserves ordinary values, serializes dates, and replaces unsupported values", () => {
+ expect(boundHeartbeatRunEventPayloadForStorage({
+ text: "ready",
+ count: 2,
+ flag: false,
+ empty: null,
+ at: new Date("2026-10-08T12:00:00Z"),
+ missing: undefined,
+ callback: () => "unused",
+ symbol: Symbol("unused"),
+ bigint: 1n,
+ })).toEqual({
+ text: "ready",
+ count: 2,
+ flag: false,
+ empty: null,
+ at: "2026-10-08T12:00:00.000Z",
+ missing: null,
+ callback: null,
+ symbol: null,
+ bigint: null,
+ });
+ });
+
+ it("keeps strings at the limit and reports the exact number of omitted characters", () => {
+ const limit = "x".repeat(16 * 1024);
+ expect(boundHeartbeatRunEventPayloadForStorage({
+ exact: limit,
+ oversized: `${limit}end`,
+ })).toEqual({
+ exact: limit,
+ oversized: `${limit}\n[truncated 3 chars]`,
+ });
+ });
+
+ it("keeps the first 50 array entries and reports omitted items", () => {
+ const exact = Array.from({ length: 50 }, (_, index) => index);
+ expect(boundHeartbeatRunEventPayloadForStorage({ exact, oversized: [...exact, 50, 51] }))
+ .toEqual({ exact, oversized: [...exact, { _truncated: true, omittedItems: 2 }] });
+ });
+
+ it("keeps the first 100 object keys and reports omitted keys", () => {
+ const exact = Object.fromEntries(Array.from({ length: 100 }, (_, index) => [`key${index}`, index]));
+ expect(boundHeartbeatRunEventPayloadForStorage({
+ exact,
+ oversized: { ...exact, extra1: 1, extra2: 2 },
+ })).toEqual({
+ exact,
+ oversized: { ...exact, _truncated: true, _omittedKeys: 2 },
+ });
+ });
+
+ it("replaces objects at the depth limit with at most 20 key names", () => {
+ const leaf = Object.fromEntries(Array.from({ length: 25 }, (_, index) => [`key${index}`, "hidden"]));
+ const payload = { one: { two: { three: { four: { five: { six: leaf } } } } } };
+ expect(boundHeartbeatRunEventPayloadForStorage(payload)).toEqual({
+ one: { two: { three: { four: { five: { six: {
+ _truncated: true,
+ type: "object",
+ keys: Object.keys(leaf).slice(0, 20),
+ } } } } } },
+ });
+ });
+
+ it("replaces arrays at the depth limit with their original length", () => {
+ const payload = { one: { two: { three: { four: { five: { six: [1, 2, 3] } } } } } };
+ expect(boundHeartbeatRunEventPayloadForStorage(payload)).toEqual({
+ one: { two: { three: { four: { five: { six: {
+ _truncated: true,
+ type: "array",
+ originalLength: 3,
+ } } } } } },
+ });
+ });
+
+ it("marks object cycles while preserving repeated references in separate branches", () => {
+ const shared = { text: "same value" };
+ const payload: Record<string, unknown> = { first: shared, second: shared };
+ payload.self = payload;
+ expect(boundHeartbeatRunEventPayloadForStorage(payload)).toEqual({
+ first: { text: "same value" },
+ second: { text: "same value" },
+ self: "[Circular]",
+ });
+ });
+
+ it("bounds a self-referencing array without changing it", () => {
+ const entries: unknown[] = [];
+ entries.push(entries);
+ const result = boundHeartbeatRunEventPayloadForStorage({ entries });
+ expect(JSON.stringify(result)).toBe('{"entries":[[[[[{"_truncated":true,"type":"array","originalLength":1}]]]]]}');
+ expect(entries[0]).toBe(entries);
+ });
+
+ it("leaves frozen input values unchanged and creates independent output", () => {
+ const nested = Object.freeze({ text: "x".repeat(20_000) });
+ const entries = Object.freeze([nested]);
+ const payload = Object.freeze({ nested, entries });
+ const first = boundHeartbeatRunEventPayloadForStorage(payload);
+ const second = boundHeartbeatRunEventPayloadForStorage(payload);
+ expect(first).toEqual(second);
+ expect(first.nested).not.toBe(nested);
+ expect(first.entries).not.toBe(entries);
+ expect(nested.text).toHaveLength(20_000);
+ expect(entries[0]).toBe(nested);
+ });
+});
+
+describe("heartbeat run-log chunk formatting", () => {
+ it("preserves ordinary chunks through the default 64 KiB character limit", () => {
+ const chunk = "x".repeat(64 * 1024);
+ expect(compactRunLogChunk("")).toBe("");
+ expect(compactRunLogChunk("ready\n")).toBe("ready\n");
+ expect(compactRunLogChunk(chunk)).toBe(chunk);
+ });
+
+ it("keeps the existing head, tail, and omission count for a custom limit", () => {
+ expect(compactRunLogChunk(`${"x".repeat(95)}tail!`, 20)).toBe(
+ `${"x".repeat(12)}\n[paperclip truncated run log chunk: omitted 83 chars]\ntail!`,
+ );
+ });
+
+ it.each([1023, 1024])("preserves the image omission threshold at %i characters", (length) => {
+ const data = "A".repeat(length);
+ const chunk = `{"type":"image","source":{"type":"base64","data":"${data}"}}`;
+ expect(compactRunLogChunk(chunk)).toBe(length < 1024
+ ? chunk
+ : chunk.replace(data, `[omitted base64 image data: ${length} chars]`));
+ });
+
+ it("omits every large image consistently across repeated calls", () => {
+ const chunk = [1024, 2048].map((length) =>
+ `{"type":"image","source":{"type":"base64","data":"${"A".repeat(length)}"}}`,
+ ).join("\n");
+ const expected = [1024, 2048].map((length) =>
+ `{"type":"image","source":{"type":"base64","data":"[omitted base64 image data: ${length} chars]"}}`,
+ ).join("\n");
+ expect(compactRunLogChunk(chunk)).toBe(expected);
+ expect(compactRunLogChunk(chunk)).toBe(expected);
+ });
+
+ it("redacts credentials and image data before deciding whether a chunk needs truncation", () => {
+ const chunk = `Authorization: Bearer fixture-secret-token\n{"type":"image","source":{"type":"base64","data":"${"A".repeat(70_000)}"}}`;
+ const compacted = compactRunLogChunk(chunk, 512);
+ expect(compacted).toContain("***REDACTED***");
+ expect(compacted).not.toContain("fixture-secret-token");
+ expect(compacted).toContain("[omitted base64 image data: 70000 chars]");
+ expect(compacted).not.toContain("[paperclip truncated");
+ });
+});
diff --git a/server/src/services/heartbeat/run-log.ts b/server/src/services/heartbeat/run-log.ts
new file mode 100644
index 0000000000..cbdd54e074
--- /dev/null
+++ b/server/src/services/heartbeat/run-log.ts
@@ -0,0 +1,120 @@
+import { appendWithByteCap, MAX_EXCERPT_BYTES, parseObject } from "../../adapters/utils.js";
+import { redactSensitiveText } from "../../redaction.js";
+
+const MAX_PERSISTED_LOG_CHUNK_CHARS = 64 * 1024;
+const MAX_RUN_EVENT_PAYLOAD_STRING_CHARS = 16 * 1024;
+const MAX_RUN_EVENT_PAYLOAD_ARRAY_ITEMS = 50;
+const MAX_RUN_EVENT_PAYLOAD_OBJECT_KEYS = 100;
+const MAX_RUN_EVENT_PAYLOAD_DEPTH = 6;
+const INLINE_BASE64_IMAGE_DATA_RE =
+ /("type":"image","source":\{"type":"base64","data":")([A-Za-z0-9+/=]{1024,})(")/g;
+
+export function appendExcerpt(prev: string, chunk: string) {
+ return appendWithByteCap(prev, chunk, MAX_EXCERPT_BYTES);
+}
+
+function truncateRunEventString(value: string) {
+ if (value.length <= MAX_RUN_EVENT_PAYLOAD_STRING_CHARS) return value;
+ const omittedChars = value.length - MAX_RUN_EVENT_PAYLOAD_STRING_CHARS;
+ return `${value.slice(0, MAX_RUN_EVENT_PAYLOAD_STRING_CHARS)}\n[truncated ${omittedChars} chars]`;
+}
+
+function boundRunEventValue(
+ value: unknown,
+ depth: number,
+ seen: WeakSet<object>,
+): unknown {
+ if (typeof value === "string") {
+ return truncateRunEventString(value);
+ }
+ if (
+ value === null ||
+ typeof value === "number" ||
+ typeof value === "boolean"
+ ) {
+ return value;
+ }
+ if (value instanceof Date) {
+ return value.toISOString();
+ }
+ if (Array.isArray(value)) {
+ if (depth >= MAX_RUN_EVENT_PAYLOAD_DEPTH) {
+ return {
+ _truncated: true,
+ type: "array",
+ originalLength: value.length,
+ };
+ }
+ const bounded = value
+ .slice(0, MAX_RUN_EVENT_PAYLOAD_ARRAY_ITEMS)
+ .map((entry) => boundRunEventValue(entry, depth + 1, seen));
+ if (value.length > MAX_RUN_EVENT_PAYLOAD_ARRAY_ITEMS) {
+ bounded.push({
+ _truncated: true,
+ omittedItems: value.length - MAX_RUN_EVENT_PAYLOAD_ARRAY_ITEMS,
+ });
+ }
+ return bounded;
+ }
+ if (typeof value !== "object" || value === undefined) {
+ return null;
+ }
+ if (seen.has(value)) {
+ return "[Circular]";
+ }
+ seen.add(value);
+ const entries = Object.entries(value as Record<string, unknown>);
+ if (depth >= MAX_RUN_EVENT_PAYLOAD_DEPTH) {
+ const bounded = {
+ _truncated: true,
+ type: "object",
+ keys: entries.map(([key]) => key).slice(0, 20),
+ };
+ seen.delete(value);
+ return bounded;
+ }
+
+ const out: Record<string, unknown> = {};
+ for (const [key, entryValue] of entries.slice(
+ 0,
+ MAX_RUN_EVENT_PAYLOAD_OBJECT_KEYS,
+ )) {
+ out[key] = boundRunEventValue(entryValue, depth + 1, seen);
+ }
+ if (entries.length > MAX_RUN_EVENT_PAYLOAD_OBJECT_KEYS) {
+ out._truncated = true;
+ out._omittedKeys = entries.length - MAX_RUN_EVENT_PAYLOAD_OBJECT_KEYS;
+ }
+ seen.delete(value);
+ return out;
+}
+
+export function boundHeartbeatRunEventPayloadForStorage(
+ payload: Record<string, unknown>,
+): Record<string, unknown> {
+ const bounded = boundRunEventValue(payload, 0, new WeakSet());
+ return parseObject(bounded) ?? { _truncated: true };
+}
+
+function redactInlineBase64ImageData(chunk: string) {
+ return chunk.replace(
+ INLINE_BASE64_IMAGE_DATA_RE,
+ (_match, prefix: string, data: string, suffix: string) =>
+ `${prefix}[omitted base64 image data: ${data.length} chars]${suffix}`,
+ );
+}
+
+export function compactRunLogChunk(
+ chunk: string,
+ maxChars = MAX_PERSISTED_LOG_CHUNK_CHARS,
+) {
+ const normalized = redactSensitiveText(redactInlineBase64ImageData(chunk));
+ if (normalized.length <= maxChars) return normalized;
+
+ const headChars = Math.max(0, Math.floor(maxChars * 0.6));
+ const tailChars = Math.max(0, Math.floor(maxChars * 0.25));
+ const omittedChars = Math.max(0, normalized.length - headChars - tailChars);
+ const marker = `\n[paperclip truncated run log chunk: omitted ${omittedChars} chars]\n`;
+ return `${normalized.slice(0, headChars)}${marker}${normalized.slice(normalized.length - tailChars)}`;
+}
+