Files
PaperClipAI/ui/src/components/IssueRunLedger.tsx
T
DottaandClaude Opus 5.5 fc9e4cbbb3 perf(ui): show a returning task's saved chat before any server response (#21671)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The board UI opens a task as a chat. A returning browser restores a
saved read cache from local storage before the first render.
> - #21650 made a returning hard load share the one chat bootstrap. But
the saved cache held no chat, so the first chat frame still waited for
that response.
> - The owner approved saving recent comments in the browser on
2026-11-14, so that cached tasks show their chat at once.
> - This pull request saves the first chat frame of the 20 most recently
opened tasks, with size, age, revocation and isolation guardrails. The
restored chat shows at once and revalidates through the bootstrap.
> - It also adopts the hard-load bootstrap at app start and sends the
other live-run readers through it, so readers that start before the task
page mounts do not send their own requests.
> - The benefit is that a hard load of a task the user opened before
shows its conversation before any server response.

## Linked Issues or Issue Description

**Describe the enhancement**
A hard load of a task that the user opened before still waits for one
server round trip before its chat appears. The saved read cache did not
include comments.

**Current behavior**
With every API response delayed by 800 ms, a returning load shows the
chat at 892 ms (median). The frame waits for the chat bootstrap
response.

**Proposed behavior**
The saved read cache also keeps the first chat frame of recently opened
tasks. A returning load shows that frame before any response, then
revalidates through the bootstrap.

**Why**
The owner approved saving recent comments in the browser for this on
2026-11-14. Cold and cached loads must both be as fast as possible.

Related: #21650 (returning load shares the chat bootstrap), #20594 and
#20591 (returning inbox from the saved cache), #20592 and #21557 (cold
task load from one bootstrap).

## What Changed

- `ui/src/lib/persisted-query-cache.ts`: saves the reads the first chat
frame waits for (`taskChatFirstFrameRef`): recent comments, their input
facts, recent activity, the recent run window, interactions, attachment
metadata, live and active runs, work products and the plan document.
- Only for the 20 saved recent tasks, in the record of the task's own
user and company.
- At most 50 comments per task (the newest; `hasMore` is set), 192 KiB
per task, 1 MiB in total, newest tasks first.
- If storage refuses a record, the record is saved again without chat,
so chat never displaces the rest of the cache.
- All other field exclusions (tokens, credentials, environment values,
embedded documents) still apply. Only `comments` is allowed, and only
for these keys.
  - Expiry is the same as every other entry: 24 hours after the read.
- A 401, 403 or 404 on the task or on any of its chat reads removes the
task and its saved chat from memory and storage at once.
- `ui/src/lib/issue-chat-bootstrap.ts` and `ui/src/main.tsx`:
`adoptHardLoadChatBootstrap` adopts the bootstrap that the HTML started,
at app start, under the task's restored id and identifier. Readers that
start before the task page mounts share it.
- `IssueDetail.tsx`, `LiveRunWidget.tsx`, `IssueRunLedger.tsx`,
`useTaskPluginPanels.ts`: their `live-runs` reads share the loading
bootstrap. Before, whichever observer mounted first could send its own
request.
- `doc/DEVELOPING.md`: the read-cache rules now state what is saved, the
bounds, why, and the owner's approval on 2026-11-14.
- Tests: `ui/src/lib/saved-task-chat.test.ts` (guardrails), a new case
in `restored-task-chat-bootstrap.test.ts`, and an always-on perf test:
"a returning task load shows its saved chat before any API response,
then revalidates".

## Verification

Local production build, local_trusted instance, CDP delay on every API
request, fresh browser context per run, JavaScript in the HTTP cache.
Time to the revealed history with the latest message and an editable
composer. Saved read cache present against cleared (other storage kept),
5 alternating pairs each.

| API delay | Build | Cleared | Present | Requests before frame
(present) |
| ---: | --- | ---: | ---: | ---: |
| 800 ms | master `36101ebcb9` | 1,911 ms (1,895–1,920) | 892 ms
(887–898), released by the bootstrap | 33 |
| 800 ms | this PR | 1,922 ms (1,912–1,936) | 571 ms (556–588), before
any response | 36 |
| 300 ms | master | 916 ms (907–920) | 570 ms (564–576) | 37 |
| 300 ms | this PR | 928 ms (910–998) | 586 ms (568–622) | 37 |

- At 300 ms the bootstrap answers before the page mounts on both builds,
so they are the same. At 800 ms the saved chat removes the wait for the
bootstrap: −321 ms against master.
- The new perf test holds every response for 2.5 s. It fails on master
(frame at 2,595 ms, first response at 2,524 ms) and passes with this PR.
- Guardrail tests, red/green: I disabled each guardrail in turn in
`persisted-query-cache.ts` and ran `saved-task-chat.test.ts`. Each
mutant made its test fail, and all 19 tests pass with the code. Mutants:
no chat saved, no 50-comment cap, no 20-task cap, no per-task budget, no
total budget, no retry without chat when storage refuses, no 24-hour
expiry, no revocation on a chat read, chat stored in the wrong company
record, and no field exclusions.
- Sign-out and other-user isolation use the existing per-user records
and their clearing (no new code). The tests cover them for saved chat.
- "Never overwrites newer data" is the query cache's hydrate rule; the
test covers it. "The bootstrap replaces saved data" uses the
restored-entry rule from #21650; the test covers it.
- App-start adoption test: it fails when the adoption call is removed,
and passes with it.
- Focused Vitest: 25 files that use the changed modules, including
`IssueDetail.test.tsx` and `TaskChatThread.test.tsx`: 1,156 passed.
`pnpm --filter @paperclipai/ui typecheck` passes.
- Browser journeys against this build: `layout-stability.spec.ts`,
`plan-startup.spec.ts`, `cold-bootstrap.perf.spec.ts`: 20 passed (2
opt-in benchmarks skipped).

Leftover early reads on staging (one run after #21650 started
`issues/:ref?view=core` and `issues/:ref/live-runs` before the frame): I
could not reproduce them locally. That included sidebar Recents and a
bootstrap delayed to 1.2 s with CDP initiator stacks. Both reads would
go to the server only if no bootstrap was being tracked for the task, or
if an observer used a direct read. This PR removes both openings: the
bootstrap is adopted at app start, and every `live-runs` observer shares
it. I will check the request timeline on staging after deploy.

## Risks

- Privacy: recent comments of up to 20 recent tasks now stay in local
storage for up to 24 hours, or until sign-out. The owner approved this
on 2026-11-14. The bounds, the revocation and the field exclusions are
tested. Saved data is per user and company, and sign-out clears it in
every tab.
- Storage: saved chat is limited to 1 MiB in total. A record that
storage refuses is saved again without chat.
- A saved chat can be up to 24 hours old when it shows. It is marked for
revalidation, and the bootstrap answer replaces it within one round
trip. A refused revalidation removes it.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code with tool use (shell, file edits, browser automation through
Playwright and Chrome).

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-14 17:38:28 -06:00

1053 lines
38 KiB
TypeScript

import { useEffect, useMemo, useState, type ReactNode } from "react";
import { AgentQueueWait } from "./AgentQueueWait";
import { agentQueueWaitOf, isWaitingToStart } from "../lib/agent-queue-wait";
import type { ActivityEvent, Issue, Agent, ProviderTraceMetadata } from "@paperclipai/shared";
import {
isResponsibleUserDenialCode,
normalizeRunFailureCause,
responsibleUserLabel,
} from "@paperclipai/shared";
import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
import { Link } from "@/lib/router";
import { accessApi, type CurrentBoardAccess } from "../api/access";
import {
activityApi,
type RunForIssue,
type RunLivenessState,
} from "../api/activity";
import { ApiError } from "../api/client";
import {
heartbeatsApi,
type ActiveRunForIssue,
type LiveRunForIssue,
type WatchdogDecisionInput,
} from "../api/heartbeats";
import { useToastActions } from "../context/ToastContext";
import { cn, relativeTime } from "../lib/utils";
import { queryKeys } from "../lib/queryKeys";
import { keepPreviousDataForSameQueryTail } from "../lib/query-placeholder-data";
import { describeRunRetryState } from "../lib/runRetryState";
import { readSourceResolvedWatchdogFold } from "../lib/source-resolved-watchdog-fold";
import { SourceResolvedFoldBadge } from "./SourceResolvedFoldBadge";
import { ResponsibleUserDenialNotice } from "./ResponsibleUserDenialNotice";
import { RunnerInspector } from "./RunnerInspector";
import { agentsApi } from "../api/agents";
import {
ProviderTraceStatusBadge,
runRequestedProviderTrace,
} from "./ProviderTraceStatusBadge";
import { readFromIssueChatBootstrap } from "@/lib/issue-chat-bootstrap";
type IssueRunLedgerProps = {
issueId: string;
companyId: string;
issueStatus: Issue["status"];
childIssues: Issue[];
agentMap: ReadonlyMap<string, Agent>;
hasLiveRuns: boolean;
activityEvents?: ActivityEvent[];
renderActivityEvent?: (event: ActivityEvent) => ReactNode;
resolveUserLabel?: (userId: string) => string | null | undefined;
};
type IssueRunLedgerContentProps = {
runs: RunForIssue[];
liveRuns?: LiveRunForIssue[];
activeRun?: ActiveRunForIssue | null;
issueStatus: Issue["status"];
childIssues: Issue[];
agentMap: ReadonlyMap<string, Pick<Agent, "name">>;
activityEvents?: ActivityEvent[];
renderActivityEvent?: (event: ActivityEvent) => ReactNode;
resolveUserLabel?: (userId: string) => string | null | undefined;
pendingWatchdogDecision?: WatchdogDecisionInput["decision"] | null;
canRecordWatchdogDecisions?: boolean;
watchdogDecisionError?: string | null;
onWatchdogDecision?: (input: WatchdogDecisionInput) => void;
onRerunWithTrace?: (run: RunForIssue) => void;
providerTraceMetadata?: ReadonlyMap<string, ProviderTraceMetadata>;
};
type LedgerRun = RunForIssue & {
isLive?: boolean;
agentName?: string;
outputSilence?: ActiveRunForIssue["outputSilence"];
};
type LedgerFeedItem =
| {
kind: "run";
id: string;
timestamp: string;
run: LedgerRun;
}
| {
kind: "activity";
id: string;
timestamp: string;
event: ActivityEvent;
};
type LivenessCopy = {
label: string;
tone: string;
description: string;
};
const LIVENESS_COPY: Record<RunLivenessState, LivenessCopy> = {
completed: {
label: "Completed",
tone: "border-emerald-500/30 bg-emerald-500/10 text-emerald-700 dark:text-emerald-300",
description: "Task reached a terminal state.",
},
advanced: {
label: "Advanced",
tone: "border-cyan-500/30 bg-cyan-500/10 text-cyan-700 dark:text-cyan-300",
description: "Run produced concrete evidence of progress.",
},
plan_only: {
label: "Plan only",
tone: "border-amber-500/30 bg-amber-500/10 text-amber-700 dark:text-amber-300",
description: "Run described future work without concrete action evidence.",
},
empty_response: {
label: "Empty response",
tone: "border-orange-500/30 bg-orange-500/10 text-orange-700 dark:text-orange-300",
description: "Run finished without useful output.",
},
blocked: {
label: "Blocked",
tone: "border-yellow-500/30 bg-yellow-500/10 text-yellow-700 dark:text-yellow-300",
description: "Run or task declared a blocker.",
},
failed: {
label: "Failed",
tone: "border-red-500/30 bg-red-500/10 text-red-700 dark:text-red-300",
description: "Run ended unsuccessfully.",
},
needs_followup: {
label: "Needs follow-up",
tone: "border-sky-500/30 bg-sky-500/10 text-sky-700 dark:text-sky-300",
description:
"Run produced useful output but did not prove concrete progress.",
},
};
const PENDING_LIVENESS_COPY: LivenessCopy = {
label: "Checks after finish",
tone: "border-border bg-background text-muted-foreground",
description: "Liveness is evaluated after the run finishes.",
};
const RETRY_PENDING_LIVENESS_COPY: LivenessCopy = {
label: "Retry pending",
tone: "border-blue-500/30 bg-blue-500/10 text-blue-700 dark:text-blue-300",
description: "Paperclip queued an automatic retry that has not started yet.",
};
const MISSING_LIVENESS_COPY: LivenessCopy = {
label: "No liveness data",
tone: "border-border bg-background text-muted-foreground",
description: "This run has no persisted liveness classification.",
};
const TERMINAL_CHILD_STATUSES = new Set<Issue["status"]>(["done", "cancelled"]);
const ACTIVE_RUN_STATUSES = new Set(["queued", "running"]);
type RunOutputSilenceLevel = NonNullable<
ActiveRunForIssue["outputSilence"]
>["level"];
type RunOutputSilenceCopy = {
label: string;
tone: string;
};
const RUN_OUTPUT_SILENCE_COPY: Partial<
Record<RunOutputSilenceLevel, RunOutputSilenceCopy>
> = {
suspicious: {
label: "Output silence",
tone: "border-amber-500/30 bg-amber-500/10 text-amber-700 dark:text-amber-300",
},
critical: {
label: "Critical silence",
tone: "border-red-500/30 bg-red-500/10 text-red-700 dark:text-red-300",
},
snoozed: {
label: "Silence snoozed",
tone: "border-cyan-500/30 bg-cyan-500/10 text-cyan-700 dark:text-cyan-300",
},
};
function asRecord(value: unknown): Record<string, unknown> | null {
if (typeof value !== "object" || value === null || Array.isArray(value))
return null;
return value as Record<string, unknown>;
}
function readString(value: unknown) {
return typeof value === "string" && value.trim().length > 0
? value.trim()
: null;
}
function readNumber(value: unknown) {
return typeof value === "number" && Number.isFinite(value) ? value : null;
}
function formatDuration(
start: string | Date | null | undefined,
end: string | Date | null | undefined,
) {
if (!start) return null;
const startMs = new Date(start).getTime();
const endMs = end ? new Date(end).getTime() : Date.now();
if (!Number.isFinite(startMs) || !Number.isFinite(endMs)) return null;
const totalSeconds = Math.max(0, Math.round((endMs - startMs) / 1000));
if (totalSeconds < 60) return `${totalSeconds}s`;
const minutes = Math.floor(totalSeconds / 60);
const seconds = totalSeconds % 60;
if (minutes < 60)
return seconds > 0 ? `${minutes}m ${seconds}s` : `${minutes}m`;
const hours = Math.floor(minutes / 60);
const remainingMinutes = minutes % 60;
return remainingMinutes > 0 ? `${hours}h ${remainingMinutes}m` : `${hours}h`;
}
function toIsoString(value: string | Date | null | undefined) {
if (!value) return null;
return value instanceof Date ? value.toISOString() : value;
}
function liveRunToLedgerRun(
run: LiveRunForIssue | ActiveRunForIssue,
): LedgerRun {
return {
runId: run.id,
status: run.status,
agentId: run.agentId,
agentName: run.agentName,
adapterType: run.adapterType,
startedAt: toIsoString(run.startedAt),
finishedAt: toIsoString(run.finishedAt),
createdAt: toIsoString(run.createdAt) ?? new Date().toISOString(),
invocationSource: run.invocationSource,
usageJson: null,
resultJson: null,
isLive: run.status === "queued" || run.status === "running",
outputSilence: run.outputSilence,
};
}
function mergeRuns(
runs: RunForIssue[],
liveRuns: LiveRunForIssue[] | undefined,
activeRun: ActiveRunForIssue | null | undefined,
) {
const byId = new Map<string, LedgerRun>();
for (const run of runs) byId.set(run.runId, run);
for (const run of liveRuns ?? []) {
const existing = byId.get(run.id);
byId.set(
run.id,
existing
? {
...existing,
isLive: true,
agentName: run.agentName,
outputSilence: run.outputSilence,
}
: liveRunToLedgerRun(run),
);
}
if (activeRun) {
const existing = byId.get(activeRun.id);
if (existing) {
byId.set(activeRun.id, {
...existing,
isLive: isActiveRun(existing) || isActiveRun(activeRun),
agentName: activeRun.agentName,
outputSilence: activeRun.outputSilence,
});
} else {
byId.set(activeRun.id, liveRunToLedgerRun(activeRun));
}
}
return [...byId.values()].sort((a, b) => {
const aTime = new Date(a.startedAt ?? a.createdAt).getTime();
const bTime = new Date(b.startedAt ?? b.createdAt).getTime();
if (aTime !== bTime) return bTime - aTime;
return b.runId.localeCompare(a.runId);
});
}
function statusLabel(status: string) {
return status.replace(/_/g, " ");
}
function isActiveRun(run: Pick<LedgerRun, "status" | "isLive">) {
return run.isLive || ACTIVE_RUN_STATUSES.has(run.status);
}
function runSummary(
run: LedgerRun,
agentMap: ReadonlyMap<string, Pick<Agent, "name">>,
) {
const agentName = compactAgentName(run, agentMap);
if (run.status === "running") return `Running now by ${agentName}`;
if (run.status === "queued") return `Queued for ${agentName}`;
if (run.status === "scheduled_retry")
return `Automatic retry scheduled for ${agentName}`;
return `${statusLabel(run.status)} by ${agentName}`;
}
function livenessCopyForRun(run: LedgerRun) {
if (run.status === "scheduled_retry") return RETRY_PENDING_LIVENESS_COPY;
if (run.livenessState) return LIVENESS_COPY[run.livenessState];
return isActiveRun(run) ? PENDING_LIVENESS_COPY : MISSING_LIVENESS_COPY;
}
function stopReasonLabel(run: RunForIssue) {
const result = asRecord(run.resultJson);
const stopReason = readString(result?.stopReason);
const timeoutFired = result?.timeoutFired === true;
const effectiveTimeoutSec = readNumber(result?.effectiveTimeoutSec);
const timeoutText =
effectiveTimeoutSec && effectiveTimeoutSec > 0
? `${effectiveTimeoutSec}s timeout`
: null;
if (timeoutFired || stopReason === "timeout") {
return timeoutText ? `timeout (${timeoutText})` : "timeout";
}
if (
stopReason === "max_turns_exhausted" ||
stopReason === "turn_limit_exhausted"
)
return "max turns exhausted";
if (stopReason === "budget_paused") return "budget paused";
if (stopReason === "cancelled") return "cancelled";
if (stopReason === "paused") return "paused by board";
if (stopReason === "process_lost") return "process lost";
if (stopReason === "unmanaged_background_task_stopped")
return "unmanaged background task stopped";
if (stopReason === "adapter_failed") {
// Older runs have no recorded cause and keep the plain label.
const failureCause = normalizeRunFailureCause(run.failureCause);
return failureCause ? `adapter failed (${failureCause})` : "adapter failed";
}
if (stopReason === "completed")
return timeoutText ? `completed (${timeoutText})` : "completed";
return timeoutText;
}
function stopStatusLabel(run: LedgerRun, stopReason: string | null) {
if (stopReason) return stopReason;
if (run.status === "scheduled_retry") return "Retry pending";
if (run.status === "queued") return "Waiting to start";
if (run.status === "running") return "Still running";
if (!run.livenessState) return "Unavailable";
return "No stop reason";
}
function lastUsefulActionLabel(run: LedgerRun) {
if (run.status === "scheduled_retry") return "Waiting for next attempt";
if (run.lastUsefulActionAt) return relativeTime(run.lastUsefulActionAt);
if (isActiveRun(run)) return "No action recorded yet";
if (
run.livenessState === "plan_only" ||
run.livenessState === "needs_followup"
) {
return "No concrete action";
}
if (run.livenessState === "empty_response") return "No useful output";
if (!run.livenessState) return "Unavailable";
return "None recorded";
}
function continuationLabel(run: LedgerRun) {
if (!run.continuationAttempt || run.continuationAttempt <= 0) return null;
return `Continuation attempt ${run.continuationAttempt}`;
}
function hasExhaustedContinuation(run: RunForIssue) {
return /continuation attempts exhausted/i.test(run.livenessReason ?? "");
}
function childIssueSummary(childIssues: Issue[]) {
const active = childIssues.filter(
(issue) => !TERMINAL_CHILD_STATUSES.has(issue.status),
);
const done = childIssues.filter((issue) => issue.status === "done").length;
const cancelled = childIssues.filter(
(issue) => issue.status === "cancelled",
).length;
return { active, done, cancelled, total: childIssues.length };
}
function compactAgentName(
run: LedgerRun,
agentMap: ReadonlyMap<string, Pick<Agent, "name">>,
) {
return (
run.agentName ?? agentMap.get(run.agentId)?.name ?? run.agentId.slice(0, 8)
);
}
function formatSilenceAge(ms: number | null | undefined) {
if (!ms || ms <= 0) return null;
const totalMinutes = Math.floor(ms / 60_000);
if (totalMinutes < 1) return "under 1 minute";
if (totalMinutes < 60)
return `${totalMinutes} minute${totalMinutes === 1 ? "" : "s"}`;
const hours = Math.floor(totalMinutes / 60);
const minutes = totalMinutes % 60;
if (minutes === 0) return `${hours} hour${hours === 1 ? "" : "s"}`;
return `${hours}h ${minutes}m`;
}
function canBoardRecordWatchdogDecision(
companyId: string,
boardAccess: CurrentBoardAccess | undefined,
) {
if (!boardAccess) return false;
if (boardAccess.source === "local_implicit" || boardAccess.isInstanceAdmin)
return true;
const membership = boardAccess.memberships?.find(
(item) => item.companyId === companyId && item.status === "active",
);
if (!membership)
return (
boardAccess.companyIds.includes(companyId) && !boardAccess.memberships
);
return (
membership.membershipRole !== "viewer" && membership.membershipRole !== null
);
}
function watchdogDecisionErrorMessage(error: unknown) {
if (error instanceof ApiError && error.status === 403) {
return "Only the board or the assigned recovery owner can record watchdog decisions";
}
return error instanceof Error && error.message.trim().length > 0
? error.message
: "Paperclip could not record the watchdog decision.";
}
export function IssueRunLedger({
issueId,
companyId,
issueStatus,
childIssues,
agentMap,
hasLiveRuns,
activityEvents,
renderActivityEvent,
resolveUserLabel,
}: IssueRunLedgerProps) {
const queryClient = useQueryClient();
const { pushToast } = useToastActions();
const [watchdogDecisionError, setWatchdogDecisionError] = useState<
string | null
>(null);
const { data: boardAccess } = useQuery({
queryKey: queryKeys.access.currentBoardAccess,
queryFn: () => accessApi.getCurrentBoardAccess(),
});
const { data: runs } = useQuery({
queryKey: queryKeys.issues.runs(issueId),
queryFn: () => activityApi.runsForIssue(issueId),
refetchInterval:
hasLiveRuns || issueStatus === "in_progress" ? 5000 : false,
placeholderData: keepPreviousDataForSameQueryTail<RunForIssue[]>(issueId),
});
const { data: liveRuns } = useQuery({
queryKey: queryKeys.issues.liveRuns(issueId),
queryFn: () => readFromIssueChatBootstrap(queryClient, queryKeys.issues.liveRuns(issueId), issueId, (item) => item.liveRuns, () => heartbeatsApi.liveRunsForIssue(issueId)),
enabled: hasLiveRuns,
refetchInterval: 3000,
placeholderData:
keepPreviousDataForSameQueryTail<LiveRunForIssue[]>(issueId),
});
const { data: activeRun = null } = useQuery({
queryKey: queryKeys.issues.activeRun(issueId),
queryFn: () => heartbeatsApi.activeRunForIssue(issueId),
enabled: hasLiveRuns || issueStatus === "in_progress",
refetchInterval: hasLiveRuns ? false : 3000,
placeholderData: keepPreviousDataForSameQueryTail<ActiveRunForIssue | null>(
issueId,
),
});
const traceRunIds = useMemo(
() => (runs ?? []).slice(0, 100).map((run) => run.runId),
[runs],
);
const canInspectProviderTrace =
boardAccess?.source === "local_implicit" || boardAccess?.isInstanceAdmin === true;
const { data: providerTraceRows } = useQuery({
queryKey: queryKeys.providerTraceMetadata(companyId, traceRunIds),
queryFn: () => heartbeatsApi.providerTraceMetadata(companyId, traceRunIds),
enabled: canInspectProviderTrace && traceRunIds.length > 0,
});
const providerTraceMetadata = useMemo(
() => new Map((providerTraceRows ?? []).map((trace) => [trace.runId, trace])),
[providerTraceRows],
);
const watchdogDecision = useMutation({
mutationFn: (input: WatchdogDecisionInput) =>
heartbeatsApi.recordWatchdogDecision(input),
onMutate: () => {
setWatchdogDecisionError(null);
},
onSuccess: () => {
setWatchdogDecisionError(null);
queryClient.invalidateQueries({
queryKey: queryKeys.issues.activeRun(issueId),
});
queryClient.invalidateQueries({
queryKey: queryKeys.issues.liveRuns(issueId),
});
},
onError: (error) => {
const message = watchdogDecisionErrorMessage(error);
const dedupeSuffix =
error instanceof ApiError ? String(error.status) : "error";
setWatchdogDecisionError(message);
pushToast({
title: "Watchdog decision not recorded",
body: message,
tone: "error",
dedupeKey: `watchdog-decision:${issueId}:${dedupeSuffix}`,
});
},
});
const rerunWithTrace = useMutation({
mutationFn: async (run: RunForIssue) => {
const context = asRecord(run.contextSnapshot);
const payload: Record<string, unknown> = {};
for (const key of ["issueId", "taskId", "taskKey"] as const) {
const value = readString(context?.[key]);
if (value) payload[key] = value;
}
const result = await agentsApi.wakeup(
run.agentId,
{
source: "on_demand",
triggerDetail: "manual",
reason: "rerun_with_provider_trace",
payload,
debug: { providerTrace: "raw" },
},
companyId,
);
if (!("id" in result))
throw new Error(result.message ?? "Trace re-run was skipped.");
return result;
},
onSuccess: () => {
queryClient.invalidateQueries({
queryKey: queryKeys.issues.runs(issueId),
});
queryClient.invalidateQueries({
queryKey: queryKeys.issues.liveRuns(issueId),
});
},
onError: (error) =>
pushToast({
title: "Trace re-run not started",
body:
error instanceof Error
? error.message
: "Paperclip could not start the trace re-run.",
tone: "error",
dedupeKey: `provider-trace-rerun:${issueId}`,
}),
});
return (
<IssueRunLedgerContent
runs={runs ?? []}
liveRuns={liveRuns}
activeRun={activeRun}
issueStatus={issueStatus}
childIssues={childIssues}
agentMap={agentMap}
activityEvents={activityEvents}
renderActivityEvent={renderActivityEvent}
resolveUserLabel={resolveUserLabel}
pendingWatchdogDecision={watchdogDecision.variables?.decision ?? null}
canRecordWatchdogDecisions={canBoardRecordWatchdogDecision(
companyId,
boardAccess,
)}
watchdogDecisionError={watchdogDecisionError}
onWatchdogDecision={(input) => watchdogDecision.mutate(input)}
onRerunWithTrace={
canInspectProviderTrace
? (run) => rerunWithTrace.mutate(run)
: undefined
}
providerTraceMetadata={providerTraceMetadata}
/>
);
}
export function IssueRunLedgerContent({
runs,
liveRuns,
activeRun,
issueStatus,
childIssues,
agentMap,
activityEvents,
renderActivityEvent,
resolveUserLabel,
pendingWatchdogDecision,
canRecordWatchdogDecisions = true,
watchdogDecisionError,
onWatchdogDecision,
onRerunWithTrace,
providerTraceMetadata = new Map(),
}: IssueRunLedgerContentProps) {
const [inspectedRun, setInspectedRun] = useState<LedgerRun | null>(null);
const ledgerRuns = useMemo(
() => mergeRuns(runs, liveRuns, activeRun),
[activeRun, liveRuns, runs],
);
useEffect(() => {
if (inspectedRun || typeof window === "undefined") return;
const requestedRunId = new URLSearchParams(window.location.search).get("inspectRun");
if (!requestedRunId) return;
const requestedRun = ledgerRuns.find((run) => run.runId === requestedRunId);
if (requestedRun) setInspectedRun(requestedRun);
}, [inspectedRun, ledgerRuns]);
const latestRun = ledgerRuns[0] ?? null;
const latestSilentRun = useMemo(
() =>
ledgerRuns.find(
(run) =>
isActiveRun(run) &&
(run.outputSilence?.level === "critical" ||
run.outputSilence?.level === "suspicious"),
) ?? null,
[ledgerRuns],
);
const children = childIssueSummary(childIssues);
const canRenderActivityEvents = Boolean(renderActivityEvent);
const feedItems = useMemo<LedgerFeedItem[]>(() => {
const items: LedgerFeedItem[] = [];
for (const run of ledgerRuns) {
items.push({
kind: "run",
id: run.runId,
timestamp: run.startedAt ?? run.createdAt,
run,
});
}
if (canRenderActivityEvents) {
for (const event of activityEvents ?? []) {
items.push({
kind: "activity",
id: event.id,
timestamp:
event.createdAt instanceof Date
? event.createdAt.toISOString()
: String(event.createdAt),
event,
});
}
}
return items.sort((a, b) => {
const aTime = new Date(a.timestamp).getTime();
const bTime = new Date(b.timestamp).getTime();
if (aTime !== bTime) return bTime - aTime;
if (a.kind !== b.kind) return a.kind === "run" ? -1 : 1;
return b.id.localeCompare(a.id);
});
}, [activityEvents, canRenderActivityEvents, ledgerRuns]);
return (
<section className="space-y-3" aria-label="Task run ledger">
<div className="flex items-center justify-between gap-2">
<div className="min-w-0">
<h3 className="text-sm font-medium text-muted-foreground">
Run ledger
</h3>
<p className="text-xs text-muted-foreground">
{latestRun
? runSummary(latestRun, agentMap)
: issueStatus === "in_progress"
? "Waiting for the first run record."
: "No runs linked yet."}
</p>
</div>
{latestRun ? (
<Link
to={`/agents/${latestRun.agentId}/runs/${latestRun.runId}`}
className="shrink-0 rounded-md border border-border px-2 py-1 text-xs text-muted-foreground hover:text-foreground"
>
Latest run
</Link>
) : null}
</div>
{children.total > 0 ? (
<div className="rounded-md border border-border/70 px-3 py-2">
<div className="flex flex-wrap items-center gap-2 text-xs">
<span className="font-medium text-foreground">Child work</span>
<span className="text-muted-foreground">
{children.active.length > 0
? `${children.active.length} active, ${children.done} done, ${children.cancelled} cancelled`
: `all ${children.total} terminal (${children.done} done, ${children.cancelled} cancelled)`}
</span>
</div>
{children.active.length > 0 ? (
<div className="mt-2 flex flex-wrap gap-1.5">
{children.active.slice(0, 4).map((child) => (
<Link
key={child.id}
to={`/issues/${child.identifier ?? child.id}`}
className="inline-flex min-w-0 max-w-full items-center gap-1 rounded-md border border-border bg-background px-2 py-1 text-(length:--text-micro) hover:bg-accent/40"
>
<span className="shrink-0 font-mono text-muted-foreground">
{child.identifier ?? child.id.slice(0, 8)}
</span>
<span className="truncate">{child.title}</span>
<span className="shrink-0 text-muted-foreground">
{statusLabel(child.status)}
</span>
</Link>
))}
{children.active.length > 4 ? (
<span className="rounded-md border border-border px-2 py-1 text-(length:--text-micro) text-muted-foreground">
+{children.active.length - 4} more
</span>
) : null}
</div>
) : null}
</div>
) : null}
{latestSilentRun?.outputSilence ? (
<div
className={cn(
"rounded-md border px-3 py-2 text-xs",
latestSilentRun.outputSilence.level === "critical"
? "border-red-500/30 bg-red-500/10 text-red-900 dark:text-red-200"
: "border-amber-500/30 bg-amber-500/10 text-amber-900 dark:text-amber-200",
)}
>
<p className="font-medium">
{latestSilentRun.outputSilence.level === "critical"
? "Critical output silence"
: "Output silence watchdog warning"}
</p>
<p className="mt-1">
Latest active run has been silent for{" "}
{formatSilenceAge(latestSilentRun.outputSilence.silenceAgeMs) ??
"an extended period"}
.
{latestSilentRun.outputSilence.evaluationIssueIdentifier ? (
<>
{" "}
Review{" "}
<Link
to={`/issues/${latestSilentRun.outputSilence.evaluationIssueIdentifier}`}
className="font-medium underline underline-offset-2"
>
{latestSilentRun.outputSilence.evaluationIssueIdentifier}
</Link>{" "}
for recovery context.
</>
) : null}
</p>
<p className="mt-1">
{latestSilentRun.outputSilence.evaluationIssueIdentifier
? "This signal is informational. Paperclip did not create new delegated recovery work."
: "This signal is informational. Paperclip did not create or assign a recovery task."}
</p>
{onWatchdogDecision && canRecordWatchdogDecisions ? (
<div className="mt-2 flex flex-wrap gap-1.5">
<button
type="button"
className="rounded-md border border-border bg-background/80 px-2 py-1 text-(length:--text-micro) text-foreground hover:bg-background"
onClick={() =>
onWatchdogDecision({
runId: latestSilentRun.runId,
decision: "continue",
evaluationIssueId:
latestSilentRun.outputSilence?.evaluationIssueId ?? null,
})
}
disabled={pendingWatchdogDecision != null}
>
Continue monitoring
</button>
<button
type="button"
className="rounded-md border border-border bg-background/80 px-2 py-1 text-(length:--text-micro) text-foreground hover:bg-background"
onClick={() =>
onWatchdogDecision({
runId: latestSilentRun.runId,
decision: "snooze",
evaluationIssueId:
latestSilentRun.outputSilence?.evaluationIssueId ?? null,
snoozedUntil: new Date(
Date.now() + 60 * 60 * 1000,
).toISOString(),
reason: "Snoozed from issue run ledger",
})
}
disabled={pendingWatchdogDecision != null}
>
Snooze 1h
</button>
<button
type="button"
className="rounded-md border border-border bg-background/80 px-2 py-1 text-(length:--text-micro) text-foreground hover:bg-background"
onClick={() =>
onWatchdogDecision({
runId: latestSilentRun.runId,
decision: "dismissed_false_positive",
evaluationIssueId:
latestSilentRun.outputSilence?.evaluationIssueId ?? null,
reason: "Dismissed from issue run ledger",
})
}
disabled={pendingWatchdogDecision != null}
>
Mark false positive
</button>
</div>
) : null}
{watchdogDecisionError ? (
<p className="mt-2 rounded-md border border-red-500/30 bg-red-500/10 px-2 py-1 text-(length:--text-micro) text-red-900 dark:text-red-200">
{watchdogDecisionError}
</p>
) : null}
</div>
) : null}
{feedItems.length === 0 ? (
<div className="rounded-md border border-dashed border-border px-3 py-3 text-sm text-muted-foreground">
{renderActivityEvent
? "Runs and activity will appear here once this task has history."
: "Historical runs without liveness metadata will appear here once linked to this task."}
</div>
) : (
<div className="space-y-1.5">
{feedItems.slice(0, 20).map((item) => {
if (item.kind === "activity") {
return (
<div key={`activity:${item.id}`}>
{renderActivityEvent?.(item.event)}
</div>
);
}
const run = item.run;
const nextAction = run.execution ? run.execution.nextAction : run.nextAction;
const agentQueue = isWaitingToStart(run) ? agentQueueWaitOf(run.execution) : null;
const liveness = livenessCopyForRun(run);
const stopReason = stopReasonLabel(run);
const duration = formatDuration(run.startedAt, run.finishedAt);
const exhausted = hasExhaustedContinuation(run);
const continuation = continuationLabel(run);
const retryState = describeRunRetryState(run);
const agentName = compactAgentName(run, agentMap);
const onBehalfOfLabel = run.responsibleUserId
? responsibleUserLabel(resolveUserLabel?.(run.responsibleUserId))
: null;
const denialCode = isResponsibleUserDenialCode(run.errorCode)
? run.errorCode
: null;
const sourceResolvedFold = readSourceResolvedWatchdogFold(
run.resultJson,
);
return (
<article
key={`run:${run.runId}`}
className="space-y-1.5 rounded-lg border border-border/60 px-3 py-2 text-xs text-muted-foreground"
>
<div className="flex flex-wrap items-center gap-1.5">
<span className="font-medium text-foreground">Run</span>
<Link
to={`/agents/${run.agentId}/runs/${run.runId}`}
className="min-w-0 max-w-full truncate font-mono text-foreground hover:underline"
>
{run.runId.slice(0, 8)}
</Link>
<span>by {agentName}</span>
{onBehalfOfLabel ? (
<span
data-testid="run-on-behalf-of"
className="min-w-0 max-w-full truncate text-muted-foreground"
title={`Acting on behalf of ${onBehalfOfLabel}`}
>
on behalf of{" "}
<span className="text-foreground">{onBehalfOfLabel}</span>
</span>
) : null}
<span className="rounded-md border border-border px-1.5 py-0.5 text-(length:--text-micro) capitalize text-muted-foreground">
{statusLabel(run.status)}
</span>
{run.isLive && !isWaitingToStart(run) ? (
<span className="inline-flex items-center gap-1 rounded-md border border-blue-500/30 bg-blue-500/10 px-1.5 py-0.5 text-(length:--text-micro) text-blue-700 dark:text-blue-300">
<span className="h-1.5 w-1.5 rounded-full bg-blue-500" />
live
</span>
) : null}
<ProviderTraceStatusBadge
trace={providerTraceMetadata.get(run.runId)}
requested={runRequestedProviderTrace(run.contextSnapshot)}
showOff
/>
<span
className={cn(
"rounded-md border px-1.5 py-0.5 text-(length:--text-micro) font-medium",
liveness.tone,
)}
title={liveness.description}
>
{liveness.label}
</span>
{exhausted ? (
<span className="rounded-md border border-red-500/30 bg-red-500/10 px-1.5 py-0.5 text-(length:--text-micro) font-medium text-red-700 dark:text-red-300">
Exhausted
</span>
) : null}
{continuation ? (
<span className="text-(length:--text-micro) text-muted-foreground">
{continuation}
</span>
) : null}
{retryState ? (
<span
className={cn(
"rounded-md border px-1.5 py-0.5 text-(length:--text-micro) font-medium",
retryState.tone,
)}
>
{retryState.badgeLabel}
</span>
) : null}
{run.outputSilence &&
RUN_OUTPUT_SILENCE_COPY[run.outputSilence.level] ? (
<span
className={cn(
"rounded-md border px-1.5 py-0.5 text-(length:--text-micro) font-medium",
RUN_OUTPUT_SILENCE_COPY[run.outputSilence.level]?.tone,
)}
>
{RUN_OUTPUT_SILENCE_COPY[run.outputSilence.level]?.label}
</span>
) : null}
{sourceResolvedFold ? <SourceResolvedFoldBadge /> : null}
<span className="ml-auto shrink-0">
{relativeTime(item.timestamp)}
</span>
<button
type="button"
className="rounded-md border border-border px-1.5 py-0.5 text-(length:--text-micro) text-foreground hover:bg-accent/40"
onClick={() => setInspectedRun(run)}
>
Inspect run
</button>
</div>
<div className="grid gap-2 text-xs text-muted-foreground sm:grid-cols-3">
<div className="min-w-0">
<span className="text-foreground">Elapsed</span>{" "}
{duration ?? "unknown"}
</div>
<div className="min-w-0">
<span className="text-foreground">Last useful action</span>{" "}
{lastUsefulActionLabel(run)}
</div>
<div className="min-w-0">
<span className="text-foreground">Stop</span>{" "}
{stopStatusLabel(run, stopReason)}
</div>
</div>
{retryState ? (
<div className="rounded-md border border-border/70 bg-accent/20 px-2 py-2 text-xs leading-5 text-muted-foreground">
{retryState.detail ? <p>{retryState.detail}</p> : null}
{retryState.secondary ? (
<p>{retryState.secondary}</p>
) : null}
{retryState.retryOfRunId ? (
<p>
Retry of{" "}
<Link
to={`/agents/${run.agentId}/runs/${retryState.retryOfRunId}`}
className="font-mono text-foreground hover:underline"
>
{retryState.retryOfRunId.slice(0, 8)}
</Link>
</p>
) : null}
</div>
) : null}
{run.livenessReason ? (
<p className="min-w-0 break-words text-xs leading-5 text-muted-foreground">
{run.livenessReason}
</p>
) : null}
{denialCode ? (
<ResponsibleUserDenialNotice
code={denialCode}
userName={
run.responsibleUserId
? resolveUserLabel?.(run.responsibleUserId)
: null
}
/>
) : null}
{agentQueue ? (
<AgentQueueWait queue={agentQueue} className="text-xs" />
) : nextAction ? (
<div className="min-w-0 rounded-md bg-accent/40 px-2 py-1.5 text-xs leading-5">
<span className="font-medium text-foreground">
Next action:{" "}
</span>
<span className="break-words text-muted-foreground">
{nextAction}
</span>
</div>
) : null}
</article>
);
})}
{feedItems.length > 20 ? (
<div className="px-3 py-2 text-xs text-muted-foreground">
{feedItems.length - 20} older items not shown
</div>
) : null}
</div>
)}
{inspectedRun ? (
<RunnerInspector
runId={inspectedRun.runId}
run={inspectedRun}
open
onOpenChange={(nextOpen) => {
if (!nextOpen) setInspectedRun(null);
}}
onRerunWithTrace={
!["queued", "running"].includes(inspectedRun.status) &&
onRerunWithTrace
? () => onRerunWithTrace(inspectedRun)
: undefined
}
/>
) : null}
</section>
);
}