Files
PaperClipAI/ui/src/context/LiveUpdatesProvider.tsx
T
DottaandClaude Opus 5.5 34f71f7d57 fix(server): defer a run that meets a busy agent directory instead of failing it (#20829)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Each run of an agent with managed agent files gets a private copy of
the agent directory. Remote copies serialize their prepare, checkpoint,
collect, and release operations through one Postgres advisory lock per
agent, taken with `pg_try_advisory_xact_lock`
> - When the lock is busy, the operation fails at once with "Agent
directory operation is already active"
> - On staging, a deploy restarted the controller while three runs of
the same agent were active. When one run resumed, another run of that
agent was checkpointing its directory. The resume failed, used its last
attempt, and the task became blocked with "Retry or send a message"
> - A run must not fail because another run of the same agent is briefly
using the agent directory
> - This pull request keeps the fail-fast lock and, when it is busy
during preparation, puts the same native run back on the existing
same-run retry schedule a few seconds later
> - The benefit is that lock contention delays a run by seconds instead
of ending it as failed

## Linked Issues or Issue Description

**What happened?**
A task's run failed with `native_continuation_requires_reconciliation`
and the error "Agent directory operation is already active". The task
was blocked and asked the user to retry. The same error ended at least
two other runs of the same agent within one day.

**Steps to reproduce**
1. Use an agent with managed agent files in a remote sandbox.
2. Let one run of the agent checkpoint or collect its agent directory.
3. At the same time, let another run of the same agent prepare (for
example, a same-run resume after a controller restart).
4. The second run fails immediately with "Agent directory operation is
already active".

**Expected behavior**
The second run waits until the first operation is done, then continues.
It does not end as failed.

## What Changed

- `server/src/services/agent-directory-working-copies.ts`: The busy lock
now throws `AgentDirectoryOperationBusyError`, still a 409 with the same
message. Lock behavior is unchanged from `master`: a fail-fast
`pg_try_advisory_xact_lock` held for the life of the holder's
transaction.
- `server/src/services/heartbeat/agent-directory-busy.ts`:
`prepareWithAgentDirectoryDeferral` wraps only instruction preparation
and turns the busy error into `AgentDirectoryPreparationDeferral`
("Another run of this agent is still using its files"). A busy lock met
while collecting files after a turn is not wrapped and keeps its
existing path.
- **Before native admission** (a brand-new run, such as the first run of
a task): `server/src/services/heartbeat/retries.ts`
`finalizeAgentDirectoryBusyDeferral` cancels the run as an expected
control-plane wait (`providerWorkStarted: false`) and schedules an
`agent_directory_busy` retry 5–15 seconds later. The task keeps its
execution lock on the retry. The lane spends no failure retries
(`execution-recovery-attempt.ts`), its count is the retry run's
`scheduledRetryAttempt`, and it stops after 30 attempts.
`pre-dispatch-execution-evidence.ts` classifies this wait like the
existing workspace and AI-connection waits, so retry scheduling does not
ask for reconciliation.
- **A resumed native run**:
`server/src/services/native-runtime/native-controller-recovery.ts`
`deferNativeRunForBusyAgentDirectory` keeps the same run on the existing
same-run retry schedule without spending an attempt. It uses the same
guards as `deferNativeControllerRecovery`: it locks the task, requires
the task's execution run to be this run, requires the current lease
owner, and refuses after a Stop, a startup cancellation or a pending
native cancellation, so those settle normally. Its count is stored in
the run's `contextSnapshot`, which a resume claim does not clear, and it
stops after 30.
- `server/src/services/heartbeat.ts`: routes a preparation deferral to
the same-run path or, before admission, to the scheduled-retry path.
After the bound it follows the normal failure path with the plain
message.
- No schema or migration. Postgres releases a dead holder's advisory
lock with its session. The staging evidence showed a live holder
(another run's checkpoint), not a stale one.
- `doc/DEVELOPING.md`: Documented both paths and the bound.

Earlier revisions of this PR waited on the lock and added idle-session
expiry, keepalive, ownership fences, fenced remote removal and attempt
slots. This revision removes all of them.

### How the directory-wait retry keeps the original wake

The retry no longer replaces the wake. `scheduleBoundedRetryForRun`
takes `preserveWakeContext` for this wait: the retry keeps the original
`wakeReason`, `retryReason` and the whole wake context (interaction,
comment, continuation and admission fields), and its wake request keeps
the original reason. The wait is recorded separately as
`preparationWait: { kind: "agent_directory_busy", attempt, nextAttemptAt
}`, next to the carried `executionRetryAccounting`. Gates that key on
the wake reason therefore treat the retry exactly as they treated the
original wake.

| # | Site | Treatment for the directory wait | Why |
| --- | --- | --- | --- |
| 1 | `heartbeat/retries.ts` `scheduleBoundedRetryForRun` | Changed:
`preserveWakeContext` keeps the original wake context and reason and
adds `preparationWait` | Root cause: the retry overwrote the wake reason
|
| 2 | `run-dispatch/domain/wake-context.ts`
`isResolvedInteractionContinuationWakeContext` /
`PREPARATION_WAIT_RETRY_REASONS` | Special case removed | The original
wake context is kept, so the continuation is classified from it |
| 3 | `heartbeat/retries.ts` `interactionRunnerWait` | Special case
removed | The interaction fields are kept in the context |
| 4 | `run-dispatch/adapters/postgres.ts` scheduled-retry dependency
facts | Changed: a preparation-wait retry whose original wake was
admitted as a dependency-blocked interaction
(`dependencyBlockedInteraction`, recorded at wake time) is admitted the
same way | Without the wait the original wake would have run; this gate
is only met because of the wait |
| 5 | `run-dispatch/domain/wake-context.ts`
`isNonAssigneeWorkspaceBusyRetry` + `heartbeat/retries.ts`
`finalizeAgentDirectoryBusyDeferral` | Kept:
`preparationWaitDeferredWhileAssignee`, derived only from the recorded
admission authority | The scheduled-retry ownership gate has no
wake-reason path; the workspace and AI waits use the same recorded flag
|
| 6 | `heartbeat/retries.ts` explicit user continuation admission |
Kept: admits the `agent_directory_busy` scheduling reason | The
successor needs its own authorization receipt |
| 7 | `execution-recovery-attempt.ts` uncharged lane and
`agentDirectoryWaits` | Kept | Cap and accounting |
| 8 | `pre-dispatch-execution-evidence.ts` (`isPreDispatchResourceWait`,
`isAgentDirectoryPreparationWait`), used by
`legacy-execution-recovery.ts`, `cancelled-native-startup.ts`,
`explicit-native-continuation.ts` | Kept | Describe the cancelled
pre-provider parent run, not the retry's wake |
| 9 | `explicit-native-continuation.ts`
`undeliveredLegacyUserCommentIds`, `run-dispatch/adapters/postgres.ts`
`unstartedUserTurnOrigin` | Kept | The cancelled parent did not consume
the user's comment |
| 10 | `execution-projection.ts` label and saved accounting,
`task-interruption-presentation.ts`, UI toast and chat suppression |
Kept | Presentation of the wait |
| 11 | `run-dispatch/domain/policy.ts` AI-wait lock requirement;
AI-subscription lock recheck; AI wait detection
(`execution-configuration.ts`, `provider-limit-wait.ts`, `heartbeat.ts`,
`ai-connections.ts`, `ai-connection-runtime.ts`, `local-ai-login.ts`) |
Not applicable | AI-subscription specific |
| 12 | `workspace-busy-wait.ts`, `environment-selection.ts`,
`workspace-preparation.ts`, UI workspace-holder banners | Not applicable
| Workspace holder parking; the directory wait is a timed retry |
| 13 | `cancelled-native-startup.ts` paused workspace-retry repair;
`failureRetriesBefore*Wait` | Not applicable | Historical workspace and
AI records only; every directory wait saves its ledger |
| 14 | `failedRunRetryBudgetSpent`; storage-wait exhaustion escalation;
`status-relevance.ts` `isAdmissionWait` | Not applicable | A directory
wait never fails the run, stops at its own bound, and its run has
started |

## Verification

- Original wake kinds after a directory wait
(`heartbeat-agent-directory-busy.test.ts`, real heartbeat): an
assignment runs; a plain user comment on a dependency-blocked task is
answered with `dependencyBlockedInteraction`; an accepted interaction
continuation keeps its parked-task and reassignment gates; a user
message continuation runs with its comment; an accepted non-assignee
mention runs; and a reassignment during preparation does not let the
previous assignee restart. Each retry keeps the original `wakeReason`
and records `preparationWait`. With `preserveWakeContext` off, five of
these fail. Restart recovery keeps its attempt credit
(`native-runner-restart-recovery.integration.test.ts`).

- Non-assignee wake: an accepted mention for an agent other than the
assignee meets a busy directory; its retry records
`preparationWaitDeferredWhileAssignee: false`, survives promotion, runs
and succeeds once the directory is free. Without the shared clause in
`isNonAssigneeWorkspaceBusyRetry`, promotion cancels it.

- Interaction continuations: `heartbeat-agent-directory-busy.test.ts`
runs an accepted interaction continuation into a busy directory. The
retry keeps `mutation`, `interactionId`, `interactionKind` and
`interactionStatus` and is still classified as a continuation. If the
task is moved to todo, or reassigned, while the retry waits, the retry
does not run and the task stays parked or with its new owner. With the
old explicit storage/Runner lists, both cases fail.

- Red/green, new run:
`server/src/__tests__/heartbeat-agent-directory-busy.test.ts` runs a
real heartbeat for a new assignment whose first instruction preparation
meets a busy lock. Without the preparation wrapper, the run ends failed
(red). With it, the first run is cancelled as a wait, an
`agent_directory_busy` retry is scheduled with the task still locked to
it, the retry runs and succeeds, and no run of the task is failed
(green).
- Red/green, same-run: with the deferral as a no-op, the same-run
deferral tests failed (`expected false to be true`); they now pass.
- `native-controller-recovery.integration.test.ts` covers repeated
claim-and-defer cycles of a resumed run: each cycle keeps the attempt
count, cannot be claimed before the delay, stores the count on the run,
and the fourth deferral past a bound of 3 is refused. It also covers
Stop after the busy error, a foreign lease owner and a moved task (each
refused, nothing changed), a run before admission, and that a raw busy
error (as from collection) is never deferred.
- Focused suites: 232/232 passed (`agent-directory-working-copies`,
`instruction-working-copy`, `heartbeat-agent-directory-busy`,
`native-controller-recovery.integration`, `heartbeat-retry-scheduling`).
`tsc --noEmit` for `server` reports no errors in the changed files.
- Staging evidence (read-only): the failed run had a graceful restart at
07:25Z, then same-run resumes. Its third attempt failed at 07:31:08Z.
Another run of the same agent recorded a warm checkpoint receipt at
07:31:37Z. A second run of the same agent failed the same way at
07:59:46Z.

## Risks

- A deferred run waits 5 to 15 seconds per deferral, up to 30 times. If
the holder is still busy after that, the run fails as before with a
plain message.
- Before admission, deferral cancels the run and creates a retry run,
like the existing workspace-busy wait.

## Model Used

- Claude Opus 5.5 (claude-opus-5-5), Anthropic, with tool use and code
execution in Claude Code.

## 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
- [ ] All Paperclip CI gates are green
- [ ] 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-11 13:56:45 -06:00

2588 lines
92 KiB
TypeScript

import { LiveTranscriptInterests, DISCONNECTED_TRANSCRIPT_STREAM } from "../lib/live-transcript-interests";
import { resolveAgentAppearance, TASK_IDENTITY_CHANGED_FIELD, issueActivityChangesTaskIdentity } from "@paperclipai/shared";
import { getPageVisibility, usePageVisibility } from "../lib/page-visibility";
import { createLiveQueryRecovery } from "../lib/live-query-recovery";
import { isLiveReconciledQuery } from "../lib/live-reconcile";
import { refreshPendingTaskBrowserReads, refreshTaskBrowsers } from "../lib/task-browsers-refresh";
import {
createContext,
useCallback,
useContext,
useEffect,
useMemo,
useRef,
useState,
useSyncExternalStore,
type ReactNode,
} from "react";
import {
useQuery,
useQueryClient,
type InfiniteData,
type QueryClient,
} from "@tanstack/react-query";
import {
AMBIENT_INVALIDATION_SPACING_MS,
createCoalescingQueryClient,
createInvalidationBatcher,
createLaneRoutingBatcher,
excludingQueryKeys,
type InvalidationBatcher,
} from "../lib/query-invalidation-batcher";
import {
patchRunStatusInList,
removeRunFromList,
} from "../lib/live-runs-cache";
import type {
Agent,
HeartbeatRun,
Issue,
IssueComment,
LiveEvent,
} from "@paperclipai/shared";
import type { RunForIssue } from "../api/activity";
import type { ActiveRunForIssue, LiveRunForIssue } from "../api/heartbeats";
import type { CompanyUserDirectoryResponse } from "../api/access";
import type { CaseDetail, IssueCaseLink } from "../api/cases";
import { issuesApi } from "../api/issues";
import { authApi } from "../api/auth";
import type { CompanyListResult } from "../api/companies-query";
import { healthApi } from "../api/health";
import { useCompany } from "./CompanyContext";
import type { ToastActor, ToastInput } from "./ToastContext";
import { useToastActions } from "./ToastContext";
import { upsertIssueCommentInPages } from "../lib/optimistic-issue-comments";
import {
clearIssueExecutionRun,
removeLiveRunById,
} from "../lib/optimistic-issue-runs";
import { useConnectivityStore } from "../lib/connectivity";
import { queryKeys } from "../lib/queryKeys";
import { extractCompanyPrefixFromPath, toCompanyRelativePath } from "../lib/company-routes";
import { useLocation } from "../lib/router";
import { agentRouteRef } from "../lib/utils";
import { buildSameOriginWebSocketUrl } from "../lib/websocket-url";
import { tryCreateWebSocket } from "../lib/websocket";
const TOAST_COOLDOWN_WINDOW_MS = 10_000;
const TOAST_COOLDOWN_MAX = 3;
const RECONNECT_SUPPRESS_MS = 2000;
const RUN_TOAST_MAX_AGE_MS = 5 * 60_000;
const MAX_OBSERVED_RUN_OUTCOMES = 2000;
const DISCONNECTED_POLL_INTERVAL_MS = 15_000;
const SOCKET_CONNECTING = 0;
const SOCKET_OPEN = 1;
const TERMINAL_RUN_STATUSES = new Set([
"succeeded",
"interrupted",
"failed",
"cancelled",
"timed_out",
]);
type LiveUpdatesSocketLike = {
readyState: number;
onopen: ((this: WebSocket, ev: Event) => unknown) | null;
onmessage: ((this: WebSocket, ev: MessageEvent) => unknown) | null;
onerror: ((this: WebSocket, ev: Event) => unknown) | null;
onclose: ((this: WebSocket, ev: CloseEvent) => unknown) | null;
close: (code?: number, reason?: string) => void;
};
export type CompanyLiveEventHandler = (event: LiveEvent) => void;
interface LiveEventSubscription {
companyId?: string | null;
transcripts?: LiveTranscriptInterests;
subscribe: (handler: CompanyLiveEventHandler) => () => void;
}
const LiveEventSubscriptionContext =
createContext<LiveEventSubscription | null>(null);
const CompanyLiveConnectionContext = createContext<string | null>(null);
export function useHasCompanyLiveConnection(companyId: string | null | undefined): boolean {
const connectedCompanyId = useContext(CompanyLiveConnectionContext);
return Boolean(companyId && connectedCompanyId === companyId);
}
function dispatchLiveEventToSubscribers(
subscribers: Set<CompanyLiveEventHandler>,
expectedCompanyId: string,
event: LiveEvent,
) {
if (event.companyId !== expectedCompanyId) return;
// Snapshot so a handler that (un)subscribes mid-dispatch can't mutate the set
// we're iterating.
for (const handler of Array.from(subscribers)) {
try {
handler(event);
} catch {
// A misbehaving subscriber must never break the shared socket pipeline
// or the toast/invalidation handling that runs alongside it.
}
}
}
/**
* Subscribe to live company events off the single shared LiveUpdates socket.
* Components can react to `heartbeat.run.progress`, `activity.logged`, etc.
* without opening a WebSocket per mount. Events are already filtered to the
* active company. No-ops when rendered outside a LiveUpdatesProvider (e.g. in
* isolated tests), so callers get graceful degradation for free.
*/
export function useCompanyLiveEvent(handler: CompanyLiveEventHandler): void {
const subscription = useContext(LiveEventSubscriptionContext);
const handlerRef = useRef(handler);
useEffect(() => {
handlerRef.current = handler;
});
useEffect(() => {
if (!subscription) return;
return subscription.subscribe((event) => {
handlerRef.current(event);
});
}, [subscription]);
}
export function useTaskRunLiveUpdates(scope: {
companyId: string | null | undefined;
issueId: string | null | undefined;
issueQueryRef: string;
assigneeAgentId: string | null | undefined;
}): boolean {
const connected = useHasCompanyLiveConnection(scope.companyId);
const queryClient = useQueryClient();
const location = useLocation();
const refreshOwner = useRef<{ active: boolean } | null>(null);
const refreshRuns = useCallback((coveredByVisibleRoute = false) => {
const owner = refreshOwner.current;
if (!owner?.active) return;
for (const queryKey of [queryKeys.issues.liveRuns(scope.issueQueryRef), queryKeys.issues.activeRun(scope.issueQueryRef)]) {
const query = queryClient.getQueryCache().find({ queryKey });
if (query?.state.fetchStatus === "fetching") {
void (query.promise ?? queryClient.invalidateQueries({ queryKey }, { cancelRefetch: false }))
.catch(() => undefined).then(() => {
if (owner.active) return queryClient.invalidateQueries({ queryKey }, { cancelRefetch: false });
});
} else if (!coveredByVisibleRoute) {
void queryClient.invalidateQueries({ queryKey }, { cancelRefetch: false });
}
}
}, [queryClient, scope.issueQueryRef]);
useEffect(() => {
const owner = { active: true };
refreshOwner.current = owner;
if (connected && scope.issueId && scope.assigneeAgentId) refreshRuns();
return () => { owner.active = false; };
}, [connected, refreshRuns, scope.companyId, scope.issueId, scope.assigneeAgentId]);
useCompanyLiveEvent((event) => {
if (event.companyId !== scope.companyId || !scope.issueId ||
(event.type !== "heartbeat.run.queued" && event.type !== "heartbeat.run.status")) return;
const issueId = readString(event.payload.issueId);
const matches = issueId
? issueId === scope.issueId || issueId === scope.issueQueryRef
: true;
if (!matches) return;
const visible = resolveVisibleIssueRouteContext(queryClient, location.pathname);
refreshRuns(Boolean(visible?.issueRefs.has(scope.issueQueryRef) && runEventMatchesVisibleIssue(visible, event.payload)));
});
return connected && Boolean(scope.issueId && scope.assigneeAgentId);
}
const subscribeNoop = () => () => {};
const disconnectedSnapshot = () => DISCONNECTED_TRANSCRIPT_STREAM;
export function useTranscriptLiveStream(runIds: readonly string[], options: { companyId?: string | null; enabled?: boolean }, handler: CompanyLiveEventHandler) {
const subscription = useContext(LiveEventSubscriptionContext);
const { visible } = usePageVisibility();
useCompanyLiveEvent(event => {
if (visible && options.enabled !== false && (options.companyId === undefined || event.companyId === options.companyId)) handler(event);
});
const key = [...new Set(runIds)].sort().join(",");
const active = visible && options.enabled !== false && subscription?.transcripts !== undefined
&& (options.companyId === undefined || subscription.companyId === options.companyId);
const state = useSyncExternalStore(subscription?.transcripts?.subscribe ?? subscribeNoop,
subscription?.transcripts?.snapshot ?? disconnectedSnapshot, disconnectedSnapshot);
useEffect(() => {
if (!active || !subscription?.transcripts) return;
return subscription.transcripts.acquire(key ? key.split(",") : []);
}, [active, subscription, key]);
return active ? {
healthy: state.healthy && (key === "" || key.split(",").every(id => state.subscribedRunIds.has(id))),
epoch: state.epoch,
} : DISCONNECTED_TRANSCRIPT_STREAM;
}
function readString(value: unknown): string | null {
return typeof value === "string" && value.length > 0 ? value : null;
}
function readRecord(value: unknown): Record<string, unknown> | null {
if (typeof value !== "object" || value === null || Array.isArray(value))
return null;
return value as Record<string, unknown>;
}
function shortId(value: string) {
return value.slice(0, 8);
}
function resolveAgentName(
queryClient: QueryClient,
companyId: string,
agentId: string,
): string | null {
const agents = queryClient.getQueryData<Agent[]>(
queryKeys.agents.list(companyId),
);
const listedAgent = agents?.find((a) => a.id === agentId);
if (listedAgent?.name) return listedAgent.name;
return (
queryClient.getQueryData<Agent>(queryKeys.agents.detail(agentId))?.name ??
null
);
}
function resolveUserName(
queryClient: QueryClient,
companyId: string,
userId: string,
): string | null {
const directory = queryClient.getQueryData<CompanyUserDirectoryResponse>(
queryKeys.access.companyUserDirectory(companyId),
);
if (!directory) return null;
const entry = directory.users.find((u) => u.principalId === userId);
return entry?.user?.name?.trim() || entry?.user?.email?.trim() || null;
}
function truncate(text: string, max: number): string {
if (text.length <= max) return text;
return text.slice(0, max - 1) + "\u2026";
}
function resolveActorLabel(
queryClient: QueryClient,
companyId: string,
actorType: string | null,
actorId: string | null,
): string {
if (actorType === "agent" && actorId) {
return (
resolveAgentName(queryClient, companyId, actorId) ??
`Agent ${shortId(actorId)}`
);
}
if (actorType === "system") return "System";
if (actorType === "user" && actorId) {
return resolveUserName(queryClient, companyId, actorId) ??
(actorId === "board" || actorId === "local-board" ? "Board" : `User ${shortId(actorId)}`);
}
return actorType === "plugin" ? "Plugin" : "Unknown actor";
}
interface IssueToastContext {
ref: string;
title: string | null;
label: string;
href: string;
}
interface VisibleRouteOptions {
isForegrounded?: boolean;
}
interface VisibleIssueRouteContext {
conversation: boolean;
routeIssueRef: string;
issueRefs: Set<string>;
assigneeAgentId: string | null;
runIds: Set<string>;
subtreeIssueRefs: Set<string>;
subtreeAgentIds: Set<string>;
subtreeRunIds: Set<string>;
}
function resolveIssueQueryRefs(
queryClient: QueryClient,
companyId: string,
issueId: string,
details: Record<string, unknown> | null,
): string[] {
const refs = new Set<string>([issueId]);
const detailIssue = queryClient.getQueryData<Issue>(
queryKeys.issues.detail(issueId),
);
const listIssues = queryClient.getQueryData<Issue[]>(
queryKeys.issues.list(companyId),
);
const detailsIdentifier =
readString(details?.identifier) ?? readString(details?.issueIdentifier);
if (detailsIdentifier) refs.add(detailsIdentifier);
if (detailIssue?.id) refs.add(detailIssue.id);
if (detailIssue?.identifier) refs.add(detailIssue.identifier);
const listIssue = listIssues?.find((issue) => {
if (issue.id === issueId) return true;
if (issue.identifier && issue.identifier === issueId) return true;
if (detailsIdentifier && issue.identifier === detailsIdentifier)
return true;
return false;
});
if (listIssue?.id) refs.add(listIssue.id);
if (listIssue?.identifier) refs.add(listIssue.identifier);
return Array.from(refs);
}
function resolveIssueActivityQueryRefs(
queryClient: QueryClient,
companyId: string,
entityId: string,
details: Record<string, unknown> | null,
options?: { pathname?: string; isForegrounded?: boolean },
): string[] {
const refs = resolveIssueQueryRefs(queryClient, companyId, entityId, details);
const visible = options?.pathname
? resolveVisibleIssueRouteContext(queryClient, options.pathname, {
isForegrounded: options.isForegrounded,
})
: null;
if (visible && overlaps(visible.issueRefs, buildIssueRefsForPayload(entityId, details))
&& !refs.includes(visible.routeIssueRef)) {
// Authenticated events can omit the identifier used by the visible route.
refs.push(visible.routeIssueRef);
}
return refs;
}
function resolveIssueToastContext(
queryClient: QueryClient,
companyId: string,
issueId: string,
details: Record<string, unknown> | null,
): IssueToastContext {
const issueRefs = resolveIssueQueryRefs(
queryClient,
companyId,
issueId,
details,
);
const detailIssue = issueRefs
.map((ref) => queryClient.getQueryData<Issue>(queryKeys.issues.detail(ref)))
.find((issue): issue is Issue => !!issue);
const listIssue = queryClient
.getQueryData<Issue[]>(queryKeys.issues.list(companyId))
?.find((issue) =>
issueRefs.some((ref) => issue.id === ref || issue.identifier === ref),
);
const cachedIssue = detailIssue ?? listIssue ?? null;
const identifier =
readString(details?.identifier) ??
readString(details?.issueIdentifier) ??
cachedIssue?.identifier;
const ref = identifier ?? "Task";
const title =
readString(details?.title) ??
readString(details?.issueTitle) ??
cachedIssue?.title ??
null;
return {
ref,
title,
label: title ? `${ref} - ${truncate(title, 72)}` : ref,
href: `/issues/${identifier ?? issueId}`,
};
}
function isPageForegrounded(): boolean {
if (typeof document === "undefined") return false;
if (document.visibilityState !== "visible") return false;
if (typeof document.hasFocus === "function" && !document.hasFocus())
return false;
return true;
}
function resolveVisibleIssueRouteContext(
queryClient: QueryClient,
pathname: string,
options?: VisibleRouteOptions,
): VisibleIssueRouteContext | null {
const isForegrounded = options?.isForegrounded ?? isPageForegrounded();
if (!isForegrounded) return null;
const relativePath = toCompanyRelativePath(pathname);
const segments = relativePath.split("/").filter(Boolean);
if (!["issues", "chats"].includes(segments[0]) || !segments[1]) return null;
let issueRef = decodeURIComponent(segments[1]);
if (segments[0] === "chats") {
const session = queryClient.getQueryData<Awaited<ReturnType<typeof authApi.getSession>>>(queryKeys.auth.session);
const userId = session?.user?.id ?? session?.session?.userId ?? null;
const companyPrefix = extractCompanyPrefixFromPath(pathname);
const company = queryClient.getQueryData<CompanyListResult>(queryKeys.companies.list(userId))
?.companies.find(item => item.issuePrefix.toUpperCase() === companyPrefix?.toUpperCase());
if (!company) return null;
const agent = queryClient.getQueryData<Agent[]>(queryKeys.agents.list(company.id))
?.find(item => item.id === issueRef || agentRouteRef(item) === issueRef);
if (!agent) return null;
const conversation = queryClient.getQueryData<Issue | null>(queryKeys.agentChats.detail(company.id, userId, agent.id));
if (!conversation) return null;
issueRef = conversation.id;
}
const issue = queryClient.getQueryData<Issue>(queryKeys.issues.detail(issueRef)) ?? null;
const issueRefs = new Set<string>([issueRef]);
if (issue?.id) issueRefs.add(issue.id);
if (issue?.identifier) issueRefs.add(issue.identifier);
function collectCachedIssueRunIds(ref: string, target: Set<string>) {
const activeRun = queryClient.getQueryData<ActiveRunForIssue | null>(
queryKeys.issues.activeRun(ref),
);
const liveRuns =
queryClient.getQueryData<LiveRunForIssue[]>(
queryKeys.issues.liveRuns(ref),
) ?? [];
const linkedRuns =
queryClient.getQueryData<RunForIssue[]>(queryKeys.issues.runs(ref)) ?? [];
if (activeRun?.id) target.add(activeRun.id);
for (const run of liveRuns) {
if (run.id) target.add(run.id);
}
for (const run of linkedRuns) {
if (run.runId) target.add(run.runId);
}
}
// The route may use an identifier while the conversation loads canonical
// UUID-keyed history. A retryable terminal event can omit issueId after its
// first delivery has already removed the run from the company live cache.
const runIds = new Set<string>();
for (const ref of issueRefs) collectCachedIssueRunIds(ref, runIds);
// Notifications about descendants belong to the subtree already on screen.
// Keep these separate from issueRefs, which also drives cache invalidation.
const subtreeIssueRefs = new Set(issueRefs);
const subtreeAgentIds = new Set<string>();
const subtreeRunIds = new Set(runIds);
if (issue?.companyId && issue.id) {
const descendants =
queryClient.getQueryData<Issue[]>(
queryKeys.issues.listByDescendantRoot(issue.companyId, issue.id),
) ?? [];
for (const descendant of descendants) {
subtreeIssueRefs.add(descendant.id);
if (descendant.identifier) subtreeIssueRefs.add(descendant.identifier);
if (descendant.assigneeAgentId)
subtreeAgentIds.add(descendant.assigneeAgentId);
if (descendant.executionRunId)
subtreeRunIds.add(descendant.executionRunId);
// Only current descendants contribute history. Keep their run IDs out
// of runIds, which also drives invalidation of the root conversation.
collectCachedIssueRunIds(descendant.id, subtreeRunIds);
if (descendant.identifier)
collectCachedIssueRunIds(descendant.identifier, subtreeRunIds);
}
}
if (issue?.companyId) {
const companyRuns =
queryClient.getQueryData<LiveRunForIssue[]>(
queryKeys.liveRuns(issue.companyId),
) ?? [];
for (const run of companyRuns) {
if (run.issueId && subtreeIssueRefs.has(run.issueId))
subtreeRunIds.add(run.id);
}
}
return {
conversation: segments[0] === "chats" || Boolean(issue?.conversationAgentId),
routeIssueRef: issueRef,
issueRefs,
assigneeAgentId: issue?.assigneeAgentId ?? null,
runIds,
subtreeIssueRefs,
subtreeAgentIds,
subtreeRunIds,
};
}
function buildIssueRefsForPayload(
entityId: string,
details: Record<string, unknown> | null,
): Set<string> {
const refs = new Set<string>([entityId]);
const identifier =
readString(details?.identifier) ?? readString(details?.issueIdentifier);
if (identifier) refs.add(identifier);
return refs;
}
function overlaps(a: Set<string>, b: Set<string>): boolean {
for (const value of a) {
if (b.has(value)) return true;
}
return false;
}
function shouldSuppressActivityToastForVisibleIssue(
queryClient: QueryClient,
pathname: string,
payload: Record<string, unknown>,
options?: VisibleRouteOptions,
): boolean {
const entityType = readString(payload.entityType);
const entityId = readString(payload.entityId);
if (entityType !== "issue" || !entityId) return false;
const context = resolveVisibleIssueRouteContext(
queryClient,
pathname,
options,
);
if (!context) return false;
return overlaps(
context.subtreeIssueRefs,
buildIssueRefsForPayload(entityId, readRecord(payload.details)),
);
}
function shouldSuppressRunStatusToastForVisibleIssue(
queryClient: QueryClient,
pathname: string,
payload: Record<string, unknown>,
options?: VisibleRouteOptions,
): boolean {
if (!(options?.isForegrounded ?? isPageForegrounded())) return false;
const visibleRunId = toCompanyRelativePath(pathname).match(
/^\/agents\/[^/]+\/runs\/([^/]+)/,
)?.[1];
if (
visibleRunId &&
decodeURIComponent(visibleRunId) === readString(payload.runId)
)
return true;
const context = resolveVisibleIssueRouteContext(
queryClient,
pathname,
options,
);
if (!context) return false;
const issueId = readString(payload.issueId);
if (issueId) return context.subtreeIssueRefs.has(issueId);
const runId = readString(payload.runId);
if (runId) return context.subtreeRunIds.has(runId);
const agentId = readString(payload.agentId);
return (
!!agentId &&
(agentId === context.assigneeAgentId ||
context.subtreeAgentIds.has(agentId))
);
}
function runEventMatchesVisibleIssue(context: VisibleIssueRouteContext, payload: Record<string, unknown>): boolean {
const runId = readString(payload.runId);
const agentId = readString(payload.agentId);
return (runId !== null && context.runIds.has(runId)) ||
Boolean(agentId && context.assigneeAgentId && agentId === context.assigneeAgentId);
}
function invalidateVisibleIssueRunQueries(
queryClient: QueryClient,
pathname: string,
payload: Record<string, unknown>,
options?: VisibleRouteOptions,
): boolean {
const context = resolveVisibleIssueRouteContext(
queryClient,
pathname,
options,
);
if (!context) return false;
const runId = readString(payload.runId);
if (!runEventMatchesVisibleIssue(context, payload)) return false;
const status = readString(payload.status);
if (runId && status && TERMINAL_RUN_STATUSES.has(status)) {
for (const issueRef of context.issueRefs) {
// Finalization may commit the selected reply without comment_added.
// Fetch the canonical comment before handing off the live transcript;
// progress/queued events must not refetch the whole conversation.
queryClient.invalidateQueries({
queryKey: queryKeys.issues.comments(issueRef),
});
queryClient.setQueryData(
queryKeys.issues.liveRuns(issueRef),
(current: LiveRunForIssue[] | undefined) =>
removeLiveRunById(current, runId),
);
queryClient.setQueryData(
queryKeys.issues.activeRun(issueRef),
(current: ActiveRunForIssue | null | undefined) =>
current?.id === runId ? null : current,
);
queryClient.setQueryData(
queryKeys.issues.detail(issueRef),
(current: Issue | undefined) => clearIssueExecutionRun(current, runId),
);
}
}
for (const issueRef of context.issueRefs) {
queryClient.invalidateQueries({ queryKey: queryKeys.issues.detail(issueRef) });
queryClient.invalidateQueries({ queryKey: queryKeys.issues.activity(issueRef) });
queryClient.invalidateQueries({ queryKey: queryKeys.issues.runs(issueRef) });
queryClient.invalidateQueries({ queryKey: queryKeys.issues.liveRuns(issueRef) });
queryClient.invalidateQueries({ queryKey: queryKeys.issues.activeRun(issueRef) });
if (status && TERMINAL_RUN_STATUSES.has(status)) {
// A final comment can race the last in-flight history fetch. Reconcile
// persisted messages after the turn settles.
queryClient.invalidateQueries({ queryKey: queryKeys.issues.comments(issueRef) });
queryClient.invalidateQueries({ queryKey: queryKeys.issues.attachments(issueRef) });
queryClient.invalidateQueries({ queryKey: queryKeys.issues.workProducts(issueRef) });
queryClient.invalidateQueries({ queryKey: queryKeys.issues.workProductPullRequestRefresh(issueRef) });
queryClient.invalidateQueries({ queryKey: ["issues", "tree-control-state", issueRef] });
}
}
return true;
}
interface RunLiveStatusPatch {
runId: string;
agentId: string | null;
issueId: string | null;
message?: string | null;
updatedAt?: string | null;
currentToolName?: string | null;
lastAssistantSnippet?: string | null;
lastEventAt?: string | null;
}
function hasPatchKey<K extends keyof RunLiveStatusPatch>(
patch: RunLiveStatusPatch,
key: K,
): patch is RunLiveStatusPatch & Required<Pick<RunLiveStatusPatch, K>> {
return Object.prototype.hasOwnProperty.call(patch, key);
}
function applyRunLiveStatusPatch<T extends ActiveRunForIssue | LiveRunForIssue>(
run: T,
patch: RunLiveStatusPatch,
): T {
if (run.id !== patch.runId) return run;
return {
...run,
...(hasPatchKey(patch, "message")
? { currentStatusMessage: patch.message }
: {}),
...(hasPatchKey(patch, "updatedAt")
? { currentStatusUpdatedAt: patch.updatedAt }
: {}),
...(hasPatchKey(patch, "currentToolName")
? { currentToolName: patch.currentToolName }
: {}),
...(hasPatchKey(patch, "lastAssistantSnippet")
? { lastAssistantSnippet: patch.lastAssistantSnippet }
: {}),
...(hasPatchKey(patch, "lastEventAt")
? { lastEventAt: patch.lastEventAt }
: {}),
};
}
function applyRunLiveStatusPatchToArray<T extends LiveRunForIssue>(
runs: T[] | undefined,
patch: RunLiveStatusPatch,
): T[] | undefined {
if (!runs) return runs;
let changed = false;
const nextRuns = runs.map((run) => {
if (run.id !== patch.runId) return run;
changed = true;
return applyRunLiveStatusPatch(run, patch);
});
return changed ? nextRuns : runs;
}
function readRunLiveStatusPatchFromPayload(
payload: Record<string, unknown>,
eventCreatedAt: string,
eventType: string,
): RunLiveStatusPatch | null {
const runId = readString(payload.runId);
if (!runId) return null;
const patch: RunLiveStatusPatch = {
runId,
agentId: readString(payload.agentId),
issueId: readString(payload.issueId),
};
if (eventType === "heartbeat.run.progress") {
patch.message = readString(payload.message);
patch.updatedAt = readString(payload.updatedAt) ?? eventCreatedAt;
patch.currentToolName = readString(payload.currentToolName);
patch.lastAssistantSnippet = readString(payload.lastAssistantSnippet);
patch.lastEventAt = readString(payload.lastEventAt) ?? patch.updatedAt;
return patch;
}
if (eventType === "heartbeat.run.log" || eventType === "heartbeat.run.activity") {
patch.lastEventAt = readString(payload.ts) ?? eventCreatedAt;
return patch;
}
if (eventType === "heartbeat.run.event") {
const message = readString(payload.message);
if (message) patch.message = message;
patch.updatedAt = readString(payload.updatedAt) ?? eventCreatedAt;
const currentToolName = readString(payload.currentToolName);
if (currentToolName) patch.currentToolName = currentToolName;
const lastAssistantSnippet = readString(payload.lastAssistantSnippet);
if (lastAssistantSnippet) patch.lastAssistantSnippet = lastAssistantSnippet;
patch.lastEventAt = readString(payload.lastEventAt) ?? eventCreatedAt;
return patch;
}
return null;
}
function applyRunLiveStatusPatchToCaches(
queryClient: QueryClient,
companyId: string,
pathname: string,
patch: RunLiveStatusPatch,
options?: VisibleRouteOptions,
): boolean {
let changed = false;
queryClient.setQueryData(
queryKeys.liveRuns(companyId),
(current: LiveRunForIssue[] | undefined) => {
const nextRuns = applyRunLiveStatusPatchToArray(current, patch);
if (nextRuns !== current) changed = true;
return nextRuns;
},
);
const issueRefs = new Set<string>();
if (patch.issueId) {
for (const ref of resolveIssueQueryRefs(
queryClient,
companyId,
patch.issueId,
null,
)) {
issueRefs.add(ref);
}
}
const context = resolveVisibleIssueRouteContext(
queryClient,
pathname,
options,
);
if (
context &&
(context.runIds.has(patch.runId) ||
(!!patch.issueId && context.issueRefs.has(patch.issueId)) ||
(!!patch.agentId &&
!!context.assigneeAgentId &&
patch.agentId === context.assigneeAgentId))
) {
for (const ref of context.issueRefs) issueRefs.add(ref);
}
for (const issueRef of issueRefs) {
queryClient.setQueryData(
queryKeys.issues.activeRun(issueRef),
(current: ActiveRunForIssue | null | undefined) => {
if (!current || current.id !== patch.runId) return current;
changed = true;
return applyRunLiveStatusPatch(current, patch);
},
);
queryClient.setQueryData(
queryKeys.issues.liveRuns(issueRef),
(current: LiveRunForIssue[] | undefined) => {
const nextRuns = applyRunLiveStatusPatchToArray(current, patch);
if (nextRuns !== current) changed = true;
return nextRuns;
},
);
}
return changed;
}
function shouldSuppressAgentStatusToastForVisibleIssue(
queryClient: QueryClient,
pathname: string,
payload: Record<string, unknown>,
options?: VisibleRouteOptions,
): boolean {
const context = resolveVisibleIssueRouteContext(
queryClient,
pathname,
options,
);
if (!context) return false;
const agentId = readString(payload.agentId);
return (
!!agentId &&
(agentId === context.assigneeAgentId ||
context.subtreeAgentIds.has(agentId))
);
}
function shouldDeferIssueRefetchForVisibleAgentActivity(
queryClient: QueryClient,
pathname: string,
payload: Record<string, unknown>,
options?: VisibleRouteOptions,
): boolean {
const entityType = readString(payload.entityType);
const entityId = readString(payload.entityId);
const actorType = readString(payload.actorType);
const action = readString(payload.action);
const details = readRecord(payload.details);
if (entityType !== "issue" || !entityId) return false;
if (actorType !== "agent" && actorType !== "system") return false;
if (action !== "issue.updated") return false;
if (readString(details?.source) === "comment") return false;
const context = resolveVisibleIssueRouteContext(
queryClient,
pathname,
options,
);
if (!context) return false;
return overlaps(
context.issueRefs,
buildIssueRefsForPayload(entityId, details),
);
}
function shouldDeferVisibleIssueCommentActivity(
queryClient: QueryClient,
pathname: string,
payload: Record<string, unknown>,
options?: VisibleRouteOptions,
): boolean {
const entityType = readString(payload.entityType);
const entityId = readString(payload.entityId);
const action = readString(payload.action);
const details = readRecord(payload.details);
if (entityType !== "issue" || !entityId) return false;
if (action !== "issue.comment_added") return false;
// Authenticated events omit comment details. Only defer a refetch when
// the event contains the ID needed to hydrate the new comment separately.
if (!readString(details?.commentId)) return false;
const context = resolveVisibleIssueRouteContext(
queryClient,
pathname,
options,
);
if (!context) return false;
return overlaps(
context.issueRefs,
buildIssueRefsForPayload(entityId, details),
);
}
async function hydrateVisibleIssueComment(
queryClient: QueryClient,
pathname: string,
payload: Record<string, unknown>,
options?: VisibleRouteOptions,
) {
const entityType = readString(payload.entityType);
const action = readString(payload.action);
const details = readRecord(payload.details);
const commentId = readString(details?.commentId);
if (entityType !== "issue" || action !== "issue.comment_added" || !commentId)
return false;
const context = resolveVisibleIssueRouteContext(
queryClient,
pathname,
options,
);
if (!context) return false;
const entityId = readString(payload.entityId);
if (
!entityId ||
!overlaps(context.issueRefs, buildIssueRefsForPayload(entityId, details))
) {
return false;
}
try {
const comment = await issuesApi.getComment(
context.routeIssueRef,
commentId,
);
if (context.conversation) {
for (const ref of context.issueRefs) {
queryClient.setQueryData<IssueComment[]>(queryKeys.issues.acknowledgedComments(ref), current =>
[...new Map([...(current ?? []), comment].map(row => [row.id, row])).values()],
);
void queryClient.invalidateQueries({ queryKey: [...queryKeys.issues.comments(ref), "recent"] });
}
return true;
}
queryClient.setQueryData<
InfiniteData<IssueComment[], string | null> | undefined
>(queryKeys.issues.comments(context.routeIssueRef), (current) => {
if (!current) {
return {
pages: [[comment]],
pageParams: [null],
};
}
return {
...current,
pages: upsertIssueCommentInPages(current.pages, comment),
};
});
return true;
} catch {
queryClient.invalidateQueries({
queryKey: queryKeys.issues.comments(context.routeIssueRef),
});
return false;
}
}
const ISSUE_TOAST_ACTIONS = new Set([
"issue.created",
"issue.updated",
"issue.comment_added",
]);
/**
* The `@task` mention pool is the 100 most recently updated tasks (one large
* response) and only backs a client-side picker. A chat turn emits many task
* events, and refetching the pool for each one re-downloads that list again
* and again. The pool is kept fresh this way instead:
*
* - A created, deleted, hidden, unhidden or renamed task changes what the
* picker can offer, so the pool refetches at once. Authenticated sockets
* send no `details`; the server sends the closed `taskIdentityChanged`
* boolean instead, and full-detail events are classified the same way.
* - Any other event on a task already in the pool moves it to the front in
* place. No request is needed: its title and identifier have not changed.
* - Any other event on a task outside the pool may lift it into the top 100.
* The pool refetches at most once per `MENTION_POOL_REFRESH_WINDOW_MS`,
* trailing, so the picker catches up within that window without a refetch
* per event. Until then a task that just entered the top 100 may be missing.
*/
const MENTION_POOL_REFRESH_WINDOW_MS = 30_000;
const mentionPoolRefreshes = new WeakMap<
object,
Map<string, { lastRequestedAt: number; timer: ReturnType<typeof setTimeout> | null }>
>();
function activityChangesTaskIdentity(
payload: Record<string, unknown>,
action: string | null,
details: Record<string, unknown> | null,
): boolean {
const flag = payload[TASK_IDENTITY_CHANGED_FIELD];
if (typeof flag === "boolean") return flag;
return issueActivityChangesTaskIdentity(action, details);
}
function refreshMentionPoolForActivity(
queryClient: QueryClient,
companyId: string,
entityId: string | null,
identityChanged: boolean,
) {
const queryKey = queryKeys.issues.mentionPool(companyId);
if (identityChanged) {
queryClient.invalidateQueries({ queryKey });
return;
}
const pool = queryClient.getQueryData<Issue[]>(queryKey);
if (!pool) return;
const query = queryClient.getQueryCache().find({ queryKey, exact: true });
if (!query) return;
// A pending invalidation (for example a rename while the picker was closed)
// must survive: writing data would clear it and make the old list look fresh.
if (query.state.isInvalidated) return;
const index = entityId
? pool.findIndex((issue) => issue.id === entityId || issue.identifier === entityId)
: -1;
if (query.getObserversCount() === 0) {
// Nobody shows the picker. A task outside the pool may now belong in it, so
// refetch on the next mount; a reorder alone can wait for that mount too.
if (index < 0) queryClient.invalidateQueries({ queryKey, refetchType: "none" });
return;
}
if (index >= 0) {
if (index > 0) {
// Keep the freshness clock: a reorder is not a fetch.
queryClient.setQueryData<Issue[]>(
queryKey,
[pool[index], ...pool.slice(0, index), ...pool.slice(index + 1)],
{ updatedAt: query.state.dataUpdatedAt },
);
}
return;
}
let refresh = mentionPoolRefreshes.get(queryClient);
if (!refresh) {
refresh = new Map();
mentionPoolRefreshes.set(queryClient, refresh);
}
const state = refresh.get(companyId) ?? { lastRequestedAt: 0, timer: null };
refresh.set(companyId, state);
if (state.timer !== null) return;
// Count both the last completed fetch and the last one requested here, so a
// burst that arrives before the refetch finishes cannot start another.
const lastRefresh = Math.max(query.state.dataUpdatedAt, state.lastRequestedAt);
const wait = Math.max(0, lastRefresh + MENTION_POOL_REFRESH_WINDOW_MS - Date.now());
state.timer = setTimeout(() => {
state.timer = null;
state.lastRequestedAt = Date.now();
queryClient.invalidateQueries({ queryKey });
}, wait);
}
const ISSUE_DOCUMENT_ACTIVITY_ACTIONS = new Set([
"issue.document_created",
"issue.document_updated",
"issue.document_restored",
"issue.document_deleted",
]);
const ISSUE_CASE_WORK_ACTIVITY_ACTIONS = new Set([
"issue.updated",
"issue.checked_out",
"issue.released",
]);
const ISSUE_DOCUMENT_ANNOTATION_ACTIVITY_ACTIONS = new Set([
"issue.document_annotation_thread_created",
"issue.document_annotation_comment_added",
"issue.document_annotation_thread_resolved",
"issue.document_annotation_thread_reopened",
"issue.document_annotation_remapped",
]);
const ROUTINE_DOCUMENT_ANNOTATION_ACTIVITY_ACTIONS = new Set([
"routine.document_annotation_thread_created",
"routine.document_annotation_comment_added",
"routine.document_annotation_thread_resolved",
"routine.document_annotation_thread_reopened",
"routine.document_annotation_remapped",
]);
const CASE_DOCUMENT_ANNOTATION_ACTIVITY_ACTIONS = new Set([
"case.document_annotation_thread_created",
"case.document_annotation_comment_added",
"case.document_annotation_thread_resolved",
"case.document_annotation_thread_reopened",
"case.document_annotation_remapped",
]);
const AGENT_TOAST_STATUSES = new Set(["error"]);
const RUN_TOAST_STATUSES = new Set(["failed", "timed_out", "cancelled"]);
function describeIssueUpdate(
details: Record<string, unknown> | null,
): string | null {
if (!details) return null;
const changes: string[] = [];
if (typeof details.status === "string")
changes.push(`status -> ${details.status.replace(/_/g, " ")}`);
if (typeof details.priority === "string")
changes.push(`priority -> ${details.priority}`);
if (
typeof details.assigneeAgentId === "string" ||
typeof details.assigneeUserId === "string"
) {
changes.push("reassigned");
} else if (
details.assigneeAgentId === null ||
details.assigneeUserId === null
) {
changes.push("unassigned");
}
if (details.reopened === true) {
const from = readString(details.reopenedFrom);
changes.push(
from ? `reopened from ${from.replace(/_/g, " ")}` : "reopened",
);
}
if (typeof details.title === "string") changes.push("title changed");
if (typeof details.description === "string")
changes.push("description changed");
if (changes.length > 0) return changes.join(", ");
return null;
}
function buildActivityToast(
queryClient: QueryClient,
companyId: string,
payload: Record<string, unknown>,
currentActor: { userId: string | null; agentId: string | null },
): ToastInput | null {
const entityType = readString(payload.entityType);
const entityId = readString(payload.entityId);
const action = readString(payload.action);
const details = readRecord(payload.details);
const actorId = readString(payload.actorId);
const actorType = readString(payload.actorType);
if (
entityType !== "issue" ||
!entityId ||
!action ||
!ISSUE_TOAST_ACTIONS.has(action)
) {
return null;
}
const issue = resolveIssueToastContext(
queryClient,
companyId,
entityId,
{
...details,
identifier: readString(payload.issueIdentifier) ?? readString(details?.identifier),
},
);
const actor = readString(readString(payload.actorName)?.trim()) ?? resolveActorLabel(queryClient, companyId, actorType, actorId);
const cachedAgent = actorType === "agent" && actorId
? queryClient.getQueryData<Agent[]>(queryKeys.agents.list(companyId))?.find((a) => a.id === actorId)
?? queryClient.getQueryData<Agent>(queryKeys.agents.detail(actorId))
: undefined;
const cachedUser = actorType === "user" && actorId
? queryClient.getQueryData<CompanyUserDirectoryResponse>(queryKeys.access.companyUserDirectory(companyId))
?.users.find((u) => u.principalId === actorId)?.user
: undefined;
const toastActor: ToastActor | undefined = actorId && (actorType === "user" || actorType === "agent")
? { type: actorType, id: actorId, name: actor,
image: payload.actorImage !== undefined ? readString(payload.actorImage) : cachedUser?.image,
appearance: actorType === "agent"
? resolveAgentAppearance(payload.actorAppearance !== undefined ? payload.actorAppearance : cachedAgent?.appearance, actorId) : undefined }
: undefined;
const isSelfActivity =
(actorType === "user" &&
!!currentActor.userId &&
actorId === currentActor.userId) ||
(actorType === "agent" &&
!!currentActor.agentId &&
actorId === currentActor.agentId);
if (isSelfActivity) return null;
if (action === "issue.created") {
return {
actor: toastActor,
title: `${actor} created ${issue.ref}`,
body: issue.title ? truncate(issue.title, 96) : undefined,
tone: "success",
action: { label: `View ${issue.ref}`, href: issue.href },
dedupeKey: `activity:${action}:${entityId}`,
};
}
if (action === "issue.updated") {
if (readString(details?.source) === "comment") {
// Comment-driven updates emit a paired comment event; show one combined toast on the comment event.
return null;
}
const changeDesc = describeIssueUpdate(details);
const body = changeDesc
? issue.title
? `${truncate(issue.title, 64)} - ${changeDesc}`
: changeDesc
: issue.title
? truncate(issue.title, 96)
: issue.label;
return {
actor: toastActor,
title: `${actor} updated ${issue.ref}`,
body: truncate(body, 100),
tone: "info",
action: { label: `View ${issue.ref}`, href: issue.href },
dedupeKey: `activity:${action}:${entityId}`,
};
}
const commentId = readString(details?.commentId);
const bodySnippet = readString(details?.bodySnippet);
const reopened = details?.reopened === true;
const updated = details?.updated === true;
const reopenedFrom = readString(details?.reopenedFrom);
const reopenedLabel = reopened
? reopenedFrom
? `reopened from ${reopenedFrom.replace(/_/g, " ")}`
: "reopened"
: null;
const title = reopened
? `${actor} reopened and commented on ${issue.ref}`
: updated
? `${actor} commented and updated ${issue.ref}`
: `${actor} commented on ${issue.ref}`;
const body = bodySnippet
? reopenedLabel
? `${reopenedLabel} - ${bodySnippet.replace(/^#+\s*/m, "").replace(/\n/g, " ")}`
: bodySnippet.replace(/^#+\s*/m, "").replace(/\n/g, " ")
: reopenedLabel
? issue.title
? `${reopenedLabel} - ${issue.title}`
: reopenedLabel
: (issue.title ?? undefined);
return {
actor: toastActor,
title,
body: body ? truncate(body, 96) : undefined,
tone: "info",
action: { label: `View ${issue.ref}`, href: issue.href },
dedupeKey: `activity:${action}:${entityId}:${commentId ?? "na"}`,
};
}
function buildJoinRequestToast(
payload: Record<string, unknown>,
): ToastInput | null {
const entityType = readString(payload.entityType);
const action = readString(payload.action);
const entityId = readString(payload.entityId);
const details = readRecord(payload.details);
if (entityType !== "join_request" || !action || !entityId) return null;
if (action !== "join.requested" && action !== "join.request_replayed")
return null;
const requestType = readString(details?.requestType);
const label = requestType === "agent" ? "Agent" : "Someone";
return {
title: `${label} wants to join`,
body: "A new join request is waiting for approval.",
tone: "info",
action: { label: "View inbox", href: "/inbox/mine" },
dedupeKey: `join-request:${entityId}`,
};
}
function buildAgentStatusToast(
payload: Record<string, unknown>,
nameOf: (id: string) => string | null,
queryClient: QueryClient,
companyId: string,
): ToastInput | null {
const agentId = readString(payload.agentId);
const status = readString(payload.status);
if (!agentId || !status || !AGENT_TOAST_STATUSES.has(status)) return null;
const tone = status === "error" ? "error" : "info";
const name = nameOf(agentId) ?? `Agent ${shortId(agentId)}`;
const title = status === "running" ? `${name} started` : `${name} errored`;
const agents = queryClient.getQueryData<Agent[]>(
queryKeys.agents.list(companyId),
);
const agent = agents?.find((a) => a.id === agentId);
const body = agent?.title ?? undefined;
return {
title,
body,
tone,
action: { label: "View agent", href: `/agents/${agentId}` },
dedupeKey: `agent-status:${agentId}:${status}`,
};
}
function buildRunStatusToast(
payload: Record<string, unknown>,
nameOf: (id: string) => string | null,
): ToastInput | null {
const runId = readString(payload.runId);
const agentId = readString(payload.agentId);
const status = readString(payload.status);
if (!runId || !agentId || !status || !RUN_TOAST_STATUSES.has(status))
return null;
const error = readString(payload.error);
const errorCode = readString(payload.errorCode);
// Interrupt is an intentional conversation control. Its caller gives
// feedback; the terminal event must not announce a cancelled/failed run.
if (errorCode === "operator_interrupted") return null;
// Workspace contention is ordinary scheduling, not a failed user action.
if (errorCode === "workspace_busy" || errorCode === "agent_directory_busy") return null;
const contextSource = readString(payload.contextSource);
const triggerDetail = readString(payload.triggerDetail);
const name = nameOf(agentId) ?? "Agent";
if (
status === "failed" &&
errorCode === "low_trust_isolation_unavailable" &&
contextSource?.startsWith("chat:")
) {
return {
title: `${name} couldn't start this chat`,
body: "This external chat identity isn't linked, and isolated guest workspaces are disabled. Link the identity in Connectors or enable isolated workspaces, then start a new task.",
tone: "warn",
ttlMs: 10_000,
action: { label: "Open chat connections", href: "/apps" },
dedupeKey: `run-status:${runId}:${status}`,
};
}
const tone =
status === "succeeded"
? "success"
: status === "cancelled"
? "info"
: "error";
const statusLabel =
status === "succeeded"
? "succeeded"
: status === "failed"
? "failed"
: status === "timed_out"
? "timed out"
: "cancelled";
const title = `${name} run ${statusLabel}`;
let body: string | undefined;
if (error) {
body = truncate(error, 100);
} else if (triggerDetail) {
body = `Trigger: ${triggerDetail}`;
}
return {
title,
body,
tone,
ttlMs: status === "succeeded" ? 5000 : 7000,
action: { label: "View run", href: `/agents/${agentId}/runs/${runId}` },
dedupeKey: `run-status:${runId}:${status}`,
};
}
/**
* Event-source the company live-runs list from run-lifecycle events instead of
* invalidating + refetching it. Returns true when the cache was fully patched;
* false means a genuinely new run appeared that can't be reconstructed from the
* event, so the caller should refetch once to pick it up.
*/
function applyRunLifecycleToCompanyLiveRuns(
queryClient: QueryClient,
companyId: string,
payload: Record<string, unknown>,
): boolean {
const runId = readString(payload.runId);
const status = readString(payload.status);
if (!runId || !status) return false;
queryClient.setQueryData(
queryKeys.runDetail(runId),
(current: HeartbeatRun | undefined) => {
if (!current) return current;
const has = (key: string) =>
Object.prototype.hasOwnProperty.call(payload, key);
return {
...current,
status: status as HeartbeatRun["status"],
...(has("invocationSource")
? {
invocationSource:
readString(payload.invocationSource) ??
current.invocationSource,
}
: {}),
...(has("triggerDetail")
? { triggerDetail: readString(payload.triggerDetail) }
: {}),
...(has("error") ? { error: readString(payload.error) } : {}),
...(has("errorCode")
? { errorCode: readString(payload.errorCode) }
: {}),
...(has("startedAt")
? { startedAt: readString(payload.startedAt) }
: {}),
...(has("finishedAt")
? { finishedAt: readString(payload.finishedAt) }
: {}),
};
},
);
if (TERMINAL_RUN_STATUSES.has(status)) {
queryClient.setQueryData(
queryKeys.liveRuns(companyId),
(current: LiveRunForIssue[] | undefined) =>
removeRunFromList(current, runId),
);
// Always "handled": a terminal run must never be in the live list, so if it
// wasn't present there is deliberately nothing to refetch (removeRunFromList
// was a no-op and we must not re-add it).
return true;
}
let present = false;
queryClient.setQueryData(
queryKeys.liveRuns(companyId),
(current: LiveRunForIssue[] | undefined) => {
const result = patchRunStatusInList(current, runId, status);
present = result.present;
return result.next;
},
);
return present;
}
function invalidateHeartbeatQueries(
queryClient: ReturnType<typeof useQueryClient>,
companyId: string,
payload: Record<string, unknown>,
) {
queryClient.invalidateQueries({ queryKey: queryKeys.issues.summaries(companyId) });
// Note: liveRuns(companyId) is intentionally NOT invalidated here — it is
// event-sourced via applyRunLifecycleToCompanyLiveRuns in the caller.
queryClient.invalidateQueries({ queryKey: queryKeys.heartbeats(companyId) });
queryClient.invalidateQueries({ queryKey: queryKeys.issues.listMineByMe(companyId) });
queryClient.invalidateQueries({ queryKey: queryKeys.agents.list(companyId) });
queryClient.invalidateQueries({ queryKey: queryKeys.dashboard(companyId) });
queryClient.invalidateQueries({ queryKey: ["costs", companyId] });
queryClient.invalidateQueries({
queryKey: queryKeys.sidebarBadges(companyId),
});
const agentId = readString(payload.agentId);
if (agentId) {
queryClient.invalidateQueries({
queryKey: queryKeys.agents.detail(agentId),
});
queryClient.invalidateQueries({
queryKey: queryKeys.heartbeats(companyId, agentId),
});
// Provider rate limits reported during the run live in runtime state.
queryClient.invalidateQueries({
queryKey: queryKeys.agents.runtimeState(agentId),
});
}
const runId = readString(payload.runId);
if (runId) {
queryClient.invalidateQueries({ queryKey: queryKeys.runDetail(runId) });
}
}
function invalidateHeartbeatProgressQueries(
queryClient: ReturnType<typeof useQueryClient>,
_companyId: string,
payload: Record<string, unknown>,
) {
const agentId = readString(payload.agentId);
if (agentId) {
queryClient.invalidateQueries({
queryKey: queryKeys.agents.detail(agentId),
});
}
}
// Actions that can change the status, retry or recovery fields that related
// tasks embed in their `blockedBy`/`blocks` summaries.
const ISSUE_RELATION_SUMMARY_ACTIVITY_ACTIONS = new Set([
"issue.updated",
"issue.deleted",
"issue.status_decision_recorded",
"issue.checked_out",
"issue.released",
"issue.recovery_action_resolved",
"issue.recovery_generation_replaced",
"issue.retry_requested",
"issue.scheduled_retry_retry_now",
]);
/**
* A task detail embeds summaries of its blockers and the tasks it blocks. When
* one of those changes, refresh every cached detail that embeds it so the
* dependent page does not keep showing the old blocker status.
*/
function invalidateIssueDetailsEmbeddingRelation(queryClient: QueryClient, refs: Iterable<string>) {
const changed = new Set(refs);
if (changed.size === 0) return;
const embeds = (summaries: unknown) =>
Array.isArray(summaries) &&
summaries.some((summary) => {
const record = readRecord(summary);
return !!record && (changed.has(readString(record.id) ?? "") || changed.has(readString(record.identifier) ?? ""));
});
queryClient.invalidateQueries({
queryKey: ["issues", "detail"],
predicate: (query) => {
const cached = readRecord(query.state.data);
return !!cached && !changed.has(readString(cached.id) ?? "") && (embeds(cached.blockedBy) || embeds(cached.blocks));
},
});
}
function invalidateActivityQueries(
queryClient: ReturnType<typeof useQueryClient>,
companyId: string,
payload: Record<string, unknown>,
currentActor: { userId: string | null; agentId: string | null },
options?: { pathname?: string; isForegrounded?: boolean },
) {
const entityType = readString(payload.entityType);
const entityId = readString(payload.entityId);
const action = readString(payload.action);
const actorType = readString(payload.actorType);
const actorId = readString(payload.actorId);
const details = readRecord(payload.details);
queryClient.invalidateQueries({ queryKey: queryKeys.activity(companyId) });
if (entityType === "issue" && (action === "issue.read_marked" || action === "issue.read_unmarked")) {
// Audit views show read receipts, while unread state belongs to one person.
if (entityId) {
for (const ref of resolveIssueActivityQueryRefs(queryClient, companyId, entityId, details, options)) {
queryClient.invalidateQueries({ queryKey: queryKeys.issues.activity(ref) });
}
}
const readerId = readString(details?.userId) ?? (actorType === "user" ? actorId : null);
if (readerId && readerId === currentActor.userId) {
for (const queryKey of [
queryKeys.issues.listMineByMe(companyId),
queryKeys.issues.listTouchedByMe(companyId),
queryKeys.issues.listUnreadTouchedByMe(companyId),
queryKeys.sidebarBadges(companyId),
queryKeys.agentChats.list(companyId, readerId),
]) queryClient.invalidateQueries({ queryKey });
}
return;
}
queryClient.invalidateQueries({ queryKey: queryKeys.dashboard(companyId) });
queryClient.invalidateQueries({ queryKey: queryKeys.sidebarBadges(companyId) });
const decisionProjectionChanged = entityType === "decision" ||
["inbox.dismissed", "inbox.snoozed", "inbox.restored"].includes(action ?? "") ||
action?.startsWith("issue.thread_interaction_") ||
action === "issue.status_decision_recorded" ||
action === "issue.conversation_session_started" ||
(entityType === "issue" && ["issue.created", "issue.updated", "issue.deleted"].includes(action ?? ""));
const decisionAudienceChanged = action?.startsWith("issue_access_grant.") ||
action?.startsWith("resource_membership.") ||
action?.startsWith("company_membership.") ||
action?.startsWith("membership.") || action?.includes("privacy");
if (decisionAudienceChanged) {
// Drop old permission-filtered payloads immediately while the API resolves
// the current audience. A failed refetch must not retain a revoked receipt.
for (const queryKey of [queryKeys.attention(companyId), ["decisions", companyId, "task-record"], ["issues", "decision-receipts"], ["issues", "chat-handoffs"], ["issues", "pending-questions"]]) {
void queryClient.resetQueries({ queryKey });
}
} else if (decisionProjectionChanged) {
queryClient.invalidateQueries({ queryKey: queryKeys.attention(companyId) });
queryClient.invalidateQueries({ queryKey: ["decisions", companyId] });
queryClient.invalidateQueries({ queryKey: queryKeys.decisionQueues.list(companyId) });
queryClient.invalidateQueries({ queryKey: ["issues", "decision-receipts"] });
queryClient.invalidateQueries({ queryKey: ["issues", "chat-handoffs"] });
queryClient.invalidateQueries({ queryKey: ["issues", "pending-questions"] });
}
const ownActorActivity =
(actorType === "user" &&
!!currentActor.userId &&
actorId === currentActor.userId) ||
(actorType === "agent" &&
!!currentActor.agentId &&
actorId === currentActor.agentId);
if (action?.startsWith("ai_connection.") || action?.startsWith("connection_grant.")) {
queryClient.invalidateQueries({ queryKey: ["ai-connections", companyId] });
}
if (action?.startsWith("primary_agent.") || action?.startsWith("agent.") || action?.startsWith("resource_membership.")) {
queryClient.invalidateQueries({ queryKey: ["primary-agent", companyId] });
}
if (action?.startsWith("resource_membership.") || action?.startsWith("primary_agent.")) {
const targetUserId = readString(details?.userId);
if (!targetUserId || targetUserId === currentActor.userId) {
queryClient.invalidateQueries({
queryKey: queryKeys.resourceMemberships.mine(companyId),
});
}
}
if (entityType === "issue") {
// Browser lists stop polling while connected; this activity refreshes them.
if (entityId && action?.startsWith("browser.")) refreshTaskBrowsers(queryClient, entityId);
const chatListKey = queryKeys.agentChats.list(companyId, currentActor.userId);
const knownChat = entityId && queryClient.getQueryData<Issue[]>(chatListKey)?.some(chat => chat.id === entityId);
const ownChatDelivery = readString(details?.conversationUserId) === (currentActor.userId ?? "local-board");
if (knownChat || ownChatDelivery || action === "issue.conversation_opened" && ownActorActivity) {
queryClient.invalidateQueries({ queryKey: chatListKey });
queryClient.invalidateQueries({ queryKey: ["agent-chat", companyId, currentActor.userId] });
}
if (action === "issue.tree_hold_created" || action === "issue.tree_hold_released" || action === "issue.updated") {
// An ancestor hold or reparenting changes descendants' effective pause.
queryClient.invalidateQueries({ queryKey: ["issues", "tree-control-state"] });
}
queryClient.invalidateQueries({
queryKey: queryKeys.issues.list(companyId),
predicate: excludingQueryKeys(queryKeys.issues.mentionPool(companyId)),
});
refreshMentionPoolForActivity(
queryClient,
companyId,
entityId,
activityChangesTaskIdentity(payload, action, details),
);
queryClient.invalidateQueries({
queryKey: queryKeys.issues.listMineByMe(companyId),
});
queryClient.invalidateQueries({
queryKey: queryKeys.issues.listTouchedByMe(companyId),
});
queryClient.invalidateQueries({
queryKey: queryKeys.issues.listUnreadTouchedByMe(companyId),
});
if (entityId) {
const selfCommentActivity =
(action === "issue.comment_added" ||
(action === "issue.updated" &&
readString(details?.source) === "comment")) &&
((actorType === "user" &&
!!currentActor.userId &&
actorId === currentActor.userId) ||
(actorType === "agent" &&
!!currentActor.agentId &&
actorId === currentActor.agentId));
const visibleIssueAgentActivity =
!!options?.pathname &&
shouldDeferIssueRefetchForVisibleAgentActivity(
queryClient,
options.pathname,
payload,
{ isForegrounded: options.isForegrounded },
);
const visibleIssueCommentActivity =
!!options?.pathname &&
shouldDeferVisibleIssueCommentActivity(
queryClient,
options.pathname,
payload,
{ isForegrounded: options.isForegrounded },
);
const issueRefs = resolveIssueActivityQueryRefs(
queryClient,
companyId,
entityId,
details,
options,
);
if (action && ISSUE_RELATION_SUMMARY_ACTIVITY_ACTIONS.has(action)) {
invalidateIssueDetailsEmbeddingRelation(queryClient, [entityId, ...issueRefs]);
}
const taskDocumentsChanged = !!action && ISSUE_DOCUMENT_ACTIVITY_ACTIONS.has(action);
const caseWorkChanged = !!action && ISSUE_CASE_WORK_ACTIVITY_ACTIONS.has(action);
if (caseWorkChanged) {
// A changed task can bring a case into a filtered list that did not
// contain it, even when no case detail has been loaded yet.
queryClient.invalidateQueries({ queryKey: queryKeys.cases.list(companyId) });
}
if (taskDocumentsChanged || caseWorkChanged) {
const changedTaskRefs = new Set(issueRefs);
// Both detail aliases embed primary-task state. Linked tasks affect the
// document rollup, including creation of their first document.
queryClient.invalidateQueries({
queryKey: ["cases", "detail"],
predicate: (query) => {
const cached = query.state.data as CaseDetail | undefined;
return cached?.companyId === companyId && (
changedTaskRefs.has(cached.workIssueId ?? "") ||
(taskDocumentsChanged && cached.issueLinks?.some((link) => changedTaskRefs.has(link.issueId)) === true)
);
},
});
}
for (const ref of issueRefs) {
const invalidationOptions =
selfCommentActivity ||
visibleIssueAgentActivity ||
visibleIssueCommentActivity
? { refetchType: "inactive" as const }
: undefined;
queryClient.invalidateQueries({ queryKey: queryKeys.issues.detail(ref), ...invalidationOptions });
queryClient.invalidateQueries({ queryKey: queryKeys.issues.activity(ref), ...invalidationOptions });
if (action === "issue.comment_added" || action === "issue.conversation_session_started") {
queryClient.invalidateQueries({ queryKey: queryKeys.issues.comments(ref), ...invalidationOptions });
}
if (action?.startsWith("issue.attachment_") || action?.startsWith("issue.work_product_")) {
// These cards are durable API objects, not streamed text. Refresh the
// visible task too, including attachments bound to an existing comment.
queryClient.invalidateQueries({ queryKey: queryKeys.issues.attachments(ref) });
queryClient.invalidateQueries({ queryKey: queryKeys.issues.workProducts(ref) });
}
if (action === "issue.conversation_session_started") {
queryClient.invalidateQueries({ queryKey: ["issues", "tree-control-state", ref] });
queryClient.invalidateQueries({ queryKey: queryKeys.issues.interactions(ref) });
}
if (action && ISSUE_DOCUMENT_ACTIVITY_ACTIONS.has(action)) {
queryClient.invalidateQueries({ queryKey: queryKeys.issues.interactions(ref) });
const documentKey = readString(details?.key);
queryClient.invalidateQueries({
queryKey: queryKeys.issues.documents(ref),
...invalidationOptions,
});
if (documentKey) {
queryClient.invalidateQueries({
queryKey: queryKeys.issues.document(ref, documentKey),
...invalidationOptions,
});
queryClient.invalidateQueries({
queryKey: queryKeys.issues.documentRevisions(ref, documentKey),
...invalidationOptions,
});
} else {
queryClient.invalidateQueries({
queryKey: ["issues", "document", ref],
...invalidationOptions,
});
queryClient.invalidateQueries({
queryKey: ["issues", "document-revisions", ref],
...invalidationOptions,
});
}
}
if (
action &&
(ISSUE_DOCUMENT_ACTIVITY_ACTIONS.has(action) ||
ISSUE_DOCUMENT_ANNOTATION_ACTIVITY_ACTIONS.has(action))
) {
const documentKey =
readString(details?.key) ?? readString(details?.documentKey);
queryClient.invalidateQueries({
queryKey: documentKey
? ["issues", "document-annotations", ref, documentKey]
: ["issues", "document-annotations", ref],
...invalidationOptions,
});
}
if (
action?.startsWith("issue.thread_interaction_") ||
((action === "issue.updated" ||
action === "issue.status_decision_recorded") &&
readString(details?.source) === "native_status_decision")
) {
// Native status decisions may materialize a review interaction in the
// same transaction. Unlike run/activity rows, that card is not present
// in the streamed PRP projection, so inactive-only invalidation leaves
// the visible task stale until a full reload.
queryClient.invalidateQueries({
queryKey: queryKeys.issues.interactions(ref),
});
queryClient.invalidateQueries({
queryKey: queryKeys.tools.actionRequests(companyId, "pending"),
});
queryClient.invalidateQueries({
queryKey: queryKeys.apps.attention(companyId),
});
queryClient.invalidateQueries({
queryKey: queryKeys.tools.trustRules(companyId),
});
}
}
}
return;
}
if (entityType === "agent") {
queryClient.invalidateQueries({
queryKey: queryKeys.agents.list(companyId),
});
queryClient.invalidateQueries({ queryKey: queryKeys.org(companyId) });
if (entityId) {
queryClient.invalidateQueries({
queryKey: queryKeys.agents.detail(entityId),
});
queryClient.invalidateQueries({
queryKey: queryKeys.heartbeats(companyId, entityId),
});
}
return;
}
if (entityType === "project") {
const sourceIssueId = readString((payload.details as Record<string, unknown> | undefined)?.sourceIssueId);
if (sourceIssueId) queryClient.invalidateQueries({ queryKey: queryKeys.issues.activity(sourceIssueId) });
queryClient.invalidateQueries({ queryKey: queryKeys.projects.all(companyId) });
if (entityId) queryClient.invalidateQueries({ queryKey: queryKeys.projects.detail(entityId) });
return;
}
if (entityType === "company_skill_source") {
queryClient.invalidateQueries({ queryKey: queryKeys.skillSources.all(companyId) });
queryClient.invalidateQueries({ queryKey: queryKeys.companySkills.list(companyId) });
queryClient.invalidateQueries({ queryKey: queryKeys.skillSources.projects(companyId) });
return;
}
if (entityType === "company_skill") {
const sourceIssueId = readString((payload.details as Record<string, unknown> | undefined)?.sourceIssueId);
if (sourceIssueId) queryClient.invalidateQueries({ queryKey: queryKeys.issues.activity(sourceIssueId) });
if (entityId) queryClient.invalidateQueries({ queryKey: queryKeys.companySkills.detail(companyId, entityId) });
queryClient.invalidateQueries({ queryKey: queryKeys.companySkills.list(companyId) });
return;
}
if (entityType === "goal") {
queryClient.invalidateQueries({
queryKey: queryKeys.goals.list(companyId),
});
if (entityId)
queryClient.invalidateQueries({
queryKey: queryKeys.goals.detail(entityId),
});
return;
}
if (entityType === "approval") {
queryClient.invalidateQueries({
queryKey: queryKeys.approvals.list(companyId),
});
return;
}
if (entityType === "join_request") {
queryClient.invalidateQueries({
queryKey: queryKeys.access.joinRequests(companyId),
});
return;
}
if (entityType === "cost_event") {
queryClient.invalidateQueries({ queryKey: ["costs", companyId] });
queryClient.invalidateQueries({
queryKey: ["usage-by-provider", companyId],
});
queryClient.invalidateQueries({ queryKey: ["usage-by-biller", companyId] });
queryClient.invalidateQueries({
queryKey: queryKeys.usageWindowSpend(companyId),
});
// usageQuotaWindows is intentionally excluded: quota windows come from external provider
// apis on a 5-minute poll and do not change in response to cost events logged by agents
return;
}
if (
entityType === "routine" ||
entityType === "routine_trigger" ||
entityType === "routine_run"
) {
queryClient.invalidateQueries({ queryKey: ["routines"] });
if (
entityType === "routine" &&
action &&
ROUTINE_DOCUMENT_ANNOTATION_ACTIVITY_ACTIONS.has(action) &&
entityId
) {
const documentKey =
readString(details?.key) ??
readString(details?.documentKey) ??
"description";
const routineInvalidationOptions = ownActorActivity
? { refetchType: "inactive" as const }
: undefined;
queryClient.invalidateQueries({
queryKey: ["routines", "document-annotations", entityId, documentKey],
...routineInvalidationOptions,
});
}
return;
}
if (entityType === "case") {
queryClient.invalidateQueries({
queryKey: queryKeys.cases.list(companyId),
});
if (entityId) {
const caseRefs = new Set([entityId]);
const issueRefs = new Set<string>();
const handoffIssueId = action?.startsWith("case.handoff_")
? readString(payload.issueId) ?? readString(details?.issueId)
: null;
if (handoffIssueId) issueRefs.add(handoffIssueId);
// Detail routes normally use the identifier, while activity carries the UUID.
for (const [key, cached] of queryClient.getQueriesData<{ id: string; identifier?: string; workIssueId?: string | null }>({
queryKey: ["cases", "detail"],
})) {
if (cached?.id !== entityId) continue;
queryClient.invalidateQueries({ queryKey: key });
if (cached.identifier) caseRefs.add(cached.identifier);
if (cached.workIssueId) issueRefs.add(cached.workIssueId);
}
// A task's cases panel can be mounted without ever loading case detail.
for (const [key, links] of queryClient.getQueriesData<IssueCaseLink[]>({
queryKey: ["cases", "for-issue"],
})) {
const link = links?.find((candidate) => candidate.case.id === entityId);
if (!link) continue;
queryClient.invalidateQueries({ queryKey: key });
caseRefs.add(link.case.identifier);
}
const documentChanged = action !== null && [
"case.document_revised", "case.document_created", "case.document_updated",
"case.document_restored", "case.document_deleted",
].includes(action);
const documentKey = readString(details?.key) ?? readString(details?.documentKey);
for (const ref of caseRefs) {
queryClient.invalidateQueries({ queryKey: queryKeys.cases.detail(ref) });
queryClient.invalidateQueries({ queryKey: queryKeys.cases.events(ref) });
queryClient.invalidateQueries({ queryKey: queryKeys.cases.handoffs(ref) });
if (documentChanged) {
queryClient.invalidateQueries({ queryKey: queryKeys.cases.documents(ref) });
queryClient.invalidateQueries({
queryKey: documentKey ? ["cases", "document", ref, documentKey] : ["cases", "document", ref],
});
queryClient.invalidateQueries({
queryKey: documentKey ? queryKeys.cases.revisions(ref, documentKey) : ["cases", "revisions", ref],
});
}
}
for (const ref of issueRefs) {
queryClient.invalidateQueries({ queryKey: queryKeys.cases.forIssue(ref) });
}
if (action && CASE_DOCUMENT_ANNOTATION_ACTIVITY_ACTIONS.has(action)) {
const documentKey =
readString(details?.key) ?? readString(details?.documentKey);
const caseInvalidationOptions = ownActorActivity
? { refetchType: "inactive" as const }
: undefined;
queryClient.invalidateQueries({
queryKey: documentKey
? ["cases", "document-annotations", entityId, documentKey]
: ["cases", "document-annotations", entityId],
...caseInvalidationOptions,
});
}
}
return;
}
if (entityType === "summary_slot") {
// The Summarizer's authoritative PUT logs `summary_slot.write`; refresh the
// affected slot + its revisions so the finished summary lands instantly
// instead of waiting for the card's 3s generating poll tick.
const scopeKind = readString(details?.scopeKind);
const slotKey = readString(details?.slotKey);
const scopeId = readString(details?.scopeId);
if (scopeKind && slotKey) {
queryClient.invalidateQueries({
queryKey: queryKeys.summarySlots.detail(
companyId,
scopeKind,
slotKey,
scopeId,
),
});
queryClient.invalidateQueries({
queryKey: queryKeys.summarySlots.revisions(
companyId,
scopeKind,
slotKey,
scopeId,
),
});
}
return;
}
if (entityType === "company") {
queryClient.invalidateQueries({ queryKey: queryKeys.companies.all });
}
}
interface ToastGate {
cooldownHits: Map<string, number[]>;
suppressUntil: number;
observedRunOutcomes: Set<string>;
}
function observeRunOutcome(gate: ToastGate, event: LiveEvent): boolean {
const payload = event.payload ?? {};
const runId = readString(payload.runId);
const status = readString(payload.status);
if (!runId || !status || !TERMINAL_RUN_STATUSES.has(status)) return false;
const key = `${event.companyId}:${runId}:${status}`;
const observed = gate.observedRunOutcomes.has(key);
// Refresh insertion order so repeated deliveries stay remembered even in a
// busy company. Remember suppressed outcomes too (visible task/reconnect).
gate.observedRunOutcomes.delete(key);
gate.observedRunOutcomes.add(key);
if (gate.observedRunOutcomes.size > MAX_OBSERVED_RUN_OUTCOMES) {
gate.observedRunOutcomes.delete(gate.observedRunOutcomes.values().next().value!);
}
// Use the two server timestamps: delivery time is not failure time. This
// also keeps historical failures quiet after a reload, without client clock
// skew hiding fresh failures. Missing timestamps retain legacy behavior.
const finishedAt = Date.parse(readString(payload.finishedAt) ?? "");
const deliveredAt = Date.parse(event.createdAt);
return observed || deliveredAt - finishedAt > RUN_TOAST_MAX_AGE_MS;
}
function shouldSuppressToast(gate: ToastGate, category: string): boolean {
const now = Date.now();
if (now < gate.suppressUntil) return true;
const hits = gate.cooldownHits.get(category);
if (!hits) return false;
const recent = hits.filter((t) => now - t < TOAST_COOLDOWN_WINDOW_MS);
gate.cooldownHits.set(category, recent);
return recent.length >= TOAST_COOLDOWN_MAX;
}
function recordToastHit(gate: ToastGate, category: string) {
const now = Date.now();
const hits = gate.cooldownHits.get(category) ?? [];
hits.push(now);
gate.cooldownHits.set(category, hits);
}
function gatedPushToast(
gate: ToastGate,
pushToast: (toast: ToastInput) => string | null,
category: string,
toast: ToastInput,
) {
if (shouldSuppressToast(gate, category)) return;
const id = pushToast(toast);
if (id !== null) recordToastHit(gate, category);
}
function handleLiveEvent(
queryClient: QueryClient,
expectedCompanyId: string,
pathname: string,
event: LiveEvent,
pushToast: (toast: ToastInput) => string | null,
gate: ToastGate,
currentActor: { userId: string | null; agentId: string | null },
) {
if (event.companyId !== expectedCompanyId) return;
const nameOf = (id: string) =>
resolveAgentName(queryClient, expectedCompanyId, id);
const payload = event.payload ?? {};
// Resolve membership before terminal lifecycle patches remove live-run rows.
const suppressRunToast =
event.type === "heartbeat.run.status" &&
(observeRunOutcome(gate, event) ||
shouldSuppressRunStatusToastForVisibleIssue(queryClient, pathname, payload));
const liveStatusPatch = readRunLiveStatusPatchFromPayload(
payload,
event.createdAt,
event.type,
);
const liveStatusPatched = liveStatusPatch
? applyRunLiveStatusPatchToCaches(
queryClient,
expectedCompanyId,
pathname,
liveStatusPatch,
)
: false;
if (event.type === "heartbeat.run.log" || event.type === "heartbeat.run.activity") {
return;
}
if (
event.type === "heartbeat.run.queued" ||
event.type === "heartbeat.run.status"
) {
const liveRunsPatched = applyRunLifecycleToCompanyLiveRuns(
queryClient,
expectedCompanyId,
payload,
);
invalidateHeartbeatQueries(queryClient, expectedCompanyId, payload);
if (!liveRunsPatched) {
// A new run we couldn't reconstruct from the event — refetch once to add it.
queryClient.invalidateQueries({
queryKey: queryKeys.liveRuns(expectedCompanyId),
});
}
invalidateVisibleIssueRunQueries(queryClient, pathname, payload);
if (event.type === "heartbeat.run.status") {
const toast = buildRunStatusToast(payload, nameOf);
if (toast && event.toastEligible === true && !suppressRunToast) {
gatedPushToast(gate, pushToast, "run-status", toast);
}
}
return;
}
if (event.type === "heartbeat.run.progress") {
invalidateHeartbeatProgressQueries(queryClient, expectedCompanyId, payload);
if (!liveStatusPatched) invalidateVisibleIssueRunQueries(queryClient, pathname, payload);
return;
}
if (event.type === "heartbeat.run.event") {
return;
}
if (event.type === "agent.runtime_state.updated") {
// The server saved a new provider rate-limit snapshot for this agent.
const agentId = readString(payload.agentId);
if (agentId) queryClient.invalidateQueries({ queryKey: queryKeys.agents.runtimeState(agentId) });
return;
}
if (event.type === "agent.status") {
queryClient.invalidateQueries({
queryKey: queryKeys.agents.list(expectedCompanyId),
});
queryClient.invalidateQueries({
queryKey: queryKeys.dashboard(expectedCompanyId),
});
queryClient.invalidateQueries({
queryKey: queryKeys.org(expectedCompanyId),
});
const agentId = readString(payload.agentId);
if (agentId)
queryClient.invalidateQueries({
queryKey: queryKeys.agents.detail(agentId),
});
// Agent-wide errors have no task participation context. Task-linked
// failures are announced through the personally scoped run-status event.
return;
}
if (event.type === "activity.logged") {
invalidateActivityQueries(
queryClient,
expectedCompanyId,
payload,
currentActor,
{ pathname },
);
if (
shouldDeferVisibleIssueCommentActivity(queryClient, pathname, payload)
) {
void hydrateVisibleIssueComment(queryClient, pathname, payload);
}
const action = readString(payload.action);
const toast =
(event.toastEligible === true ? buildActivityToast(
queryClient,
expectedCompanyId,
payload,
currentActor,
) : null) ?? buildJoinRequestToast(payload);
if (
toast &&
!shouldSuppressActivityToastForVisibleIssue(
queryClient,
pathname,
payload,
)
) {
gatedPushToast(gate, pushToast, `activity:${action ?? "unknown"}`, toast);
}
}
}
/**
* Company-scoped query families whose data is a company-wide list or
* projection: task lists and summaries, the agent list, run lists, badges,
* the dashboard, costs and the company activity feed. Many events in a busy
* company change them, and no single task view depends on them for its own
* state. Task detail, comments, runs and other per-entity keys are not listed.
*/
const AMBIENT_COMPANY_QUERY_ROOTS: ReadonlySet<string> = new Set([
"issues",
"agents",
"heartbeats",
"live-runs",
"dashboard",
"sidebar-badges",
"costs",
"activity",
]);
function isAmbientCompanyQueryKey(companyId: string | null, queryKey: readonly unknown[]): boolean {
return !!companyId && queryKey[1] === companyId
&& typeof queryKey[0] === "string" && AMBIENT_COMPANY_QUERY_ROOTS.has(queryKey[0]);
}
function createLiveInvalidationBatcher(
queryClient: QueryClient,
companyId: string | null,
ambientSpacingMs: number = AMBIENT_INVALIDATION_SPACING_MS,
): InvalidationBatcher {
return createLaneRoutingBatcher(
createInvalidationBatcher(queryClient),
createInvalidationBatcher(queryClient, undefined, { minSpacingMs: ambientSpacingMs }),
(queryKey) => isAmbientCompanyQueryKey(companyId, queryKey),
);
}
function resolveLiveCompanyId(
selectedCompanyId: string | null,
selectedCompanyLiveId: string | null,
): string | null {
return selectedCompanyId && selectedCompanyId === selectedCompanyLiveId
? selectedCompanyId
: null;
}
function resetSocketHandlers(target: LiveUpdatesSocketLike) {
target.onopen = null;
target.onmessage = null;
target.onerror = null;
target.onclose = null;
}
function closeSocketQuietly(
target: LiveUpdatesSocketLike | null,
reason: string,
) {
if (!target) return;
if (target.readyState === SOCKET_CONNECTING) {
// Let the handshake complete and then close. Calling close() while the
// socket is still CONNECTING is what triggers the noisy browser error.
target.onopen = () => {
resetSocketHandlers(target);
target.close(1000, reason);
};
target.onmessage = null;
target.onerror = () => undefined;
target.onclose = null;
return;
}
resetSocketHandlers(target);
if (target.readyState === SOCKET_OPEN) {
target.close(1000, reason);
}
}
export const __liveUpdatesTestUtils = {
createLiveInvalidationBatcher,
isAmbientCompanyQueryKey,
MENTION_POOL_REFRESH_WINDOW_MS,
buildActivityToast,
applyRunLifecycleToCompanyLiveRuns,
buildAgentStatusToast,
buildRunStatusToast,
closeSocketQuietly,
dispatchLiveEventToSubscribers,
handleLiveEvent,
LiveEventSubscriptionContext,
applyRunLiveStatusPatchToCaches,
hydrateVisibleIssueComment,
invalidateActivityQueries,
invalidateHeartbeatQueries,
invalidateHeartbeatProgressQueries,
invalidateVisibleIssueRunQueries,
readRunLiveStatusPatchFromPayload,
resolveLiveCompanyId,
canUseLiveSession,
shouldDeferIssueRefetchForVisibleAgentActivity,
shouldDeferVisibleIssueCommentActivity,
shouldSuppressActivityToastForVisibleIssue,
shouldSuppressRunStatusToastForVisibleIssue,
shouldSuppressAgentStatusToastForVisibleIssue,
};
function canUseLiveSession(sessionStatus: string, hasSession: boolean, deploymentMode?: string) {
return sessionStatus === "success" && (hasSession || deploymentMode === "local_trusted");
}
export function LiveUpdatesProvider({ children }: { children: ReactNode }) {
const { visible } = usePageVisibility();
const wasHidden = useRef(!visible);
const hasOpenedSocket = useRef(false);
const hasNeededSocketRecovery = useRef(!visible);
const { selectedCompanyId, selectedCompany } = useCompany();
const queryClient = useQueryClient();
const connectivity = useConnectivityStore();
const { pushToast } = useToastActions();
const location = useLocation();
const gateRef = useRef<ToastGate>({
cooldownHits: new Map(),
suppressUntil: 0,
observedRunOutcomes: new Set(),
});
const pathnameRef = useRef(location.pathname);
const { data: session, status: sessionStatus } = useQuery({
queryKey: queryKeys.auth.session,
queryFn: () => authApi.getSession(),
});
const { data: health } = useQuery({ queryKey: queryKeys.health, queryFn: healthApi.get });
const currentUserId = session?.user?.id ?? session?.session?.userId ??
(health?.deploymentMode === "local_trusted" ? "local-board" : null);
const socketAuthKey = session?.session?.id ?? currentUserId ?? "signed_out";
const [connectedScopeKey, setConnectedScopeKey] = useState<string | null>(null);
const liveCompanyId = resolveLiveCompanyId(selectedCompanyId, selectedCompany?.id ?? null);
const socketScopeKey = JSON.stringify([liveCompanyId, socketAuthKey]);
const canConnectSocket = canUseLiveSession(sessionStatus, session != null, health?.deploymentMode) && liveCompanyId !== null;
const currentActorRef = useRef<{ userId: string | null; agentId: string | null }>({
userId: currentUserId,
agentId: null,
});
const subscribersRef = useRef<Set<CompanyLiveEventHandler>>(new Set());
const subscribe = useCallback((handler: CompanyLiveEventHandler) => {
subscribersRef.current.add(handler);
return () => {
subscribersRef.current.delete(handler);
};
}, []);
const transcripts = useMemo(() => new LiveTranscriptInterests(), [liveCompanyId, socketAuthKey]);
const subscriptionValue = useMemo<LiveEventSubscription>(
() => ({ subscribe, transcripts, companyId: liveCompanyId }),
[subscribe, transcripts, liveCompanyId],
);
// Coalesce the per-event invalidation storm. Optimistic setQueryData writes
// still pass straight through (immediate); only invalidateQueries is batched
// and flushed at most a few times per second. Company-wide lists and
// projections use a slower lane, so a busy company does not refetch them on
// every batch while a task is open.
const invalidationBatcher = useMemo(
() => createLiveInvalidationBatcher(queryClient, liveCompanyId),
[queryClient, liveCompanyId],
);
const coalescingClient = useMemo(
() => createCoalescingQueryClient(queryClient, invalidationBatcher),
[queryClient, invalidationBatcher],
);
useEffect(() => () => invalidationBatcher.dispose(), [invalidationBatcher]);
useEffect(() => {
pathnameRef.current = location.pathname;
}, [location.pathname]);
useEffect(() => {
currentActorRef.current = {
userId: currentUserId,
agentId: null,
};
}, [currentUserId]);
useEffect(() => {
if (!visible) {
wasHidden.current = true;
hasNeededSocketRecovery.current = true;
invalidationBatcher.dispose();
return;
}
if (!canConnectSocket || !liveCompanyId) return;
if (wasHidden.current) {
wasHidden.current = false;
// Reconcile events missed while hidden, including completed runs/issues.
void queryClient.invalidateQueries({ type: "active", predicate: isLiveReconciledQuery }, { cancelRefetch: false });
}
let closed = false;
let reconnectAttempt = 0;
let reconnectTimer: number | null = null;
let pollTimer: number | null = null;
let socket: WebSocket | null = null;
const clearReconnect = () => {
if (reconnectTimer !== null) {
window.clearTimeout(reconnectTimer);
reconnectTimer = null;
}
};
const stopPolling = () => {
if (pollTimer !== null) {
window.clearInterval(pollTimer);
pollTimer = null;
}
};
const startPolling = () => {
if (closed || pollTimer !== null) return;
// Visible queries still need fresh state when realtime is unavailable.
pollTimer = window.setInterval(() => {
void queryClient.invalidateQueries({ type: "active", predicate: isLiveReconciledQuery }, { cancelRefetch: false });
}, DISCONNECTED_POLL_INTERVAL_MS);
};
const scheduleReconnect = () => {
if (closed || reconnectTimer !== null) return;
reconnectAttempt += 1;
hasNeededSocketRecovery.current = true;
const delayMs = Math.min(
15000,
1000 * 2 ** Math.min(reconnectAttempt - 1, 4),
);
reconnectTimer = window.setTimeout(() => {
reconnectTimer = null;
connect();
}, delayMs);
};
const connect = () => {
if (closed) return;
const url = buildSameOriginWebSocketUrl(
`/api/companies/${encodeURIComponent(liveCompanyId)}/events/ws`,
);
const nextSocket = tryCreateWebSocket(url);
if (!nextSocket) {
startPolling();
scheduleReconnect();
return;
}
socket = nextSocket;
let recoveryActive = true;
const recoverQueries = createLiveQueryRecovery(queryClient,
() => !closed && recoveryActive && socket === nextSocket && getPageVisibility().visible,
{ predicate: isLiveReconciledQuery });
nextSocket.onopen = () => {
if (closed || socket !== nextSocket) {
closeSocketQuietly(nextSocket, "stale_connection");
return;
}
setConnectedScopeKey(socketScopeKey);
stopPolling();
connectivity.reportSocketStatus("open");
transcripts.open(nextSocket);
if (reconnectAttempt > 0) {
gateRef.current.suppressUntil = Date.now() + RECONNECT_SUPPRESS_MS;
}
// The initial page queries can finish before the first subscription,
// too. Reconcile that gap as well as reconnects: events are not replayed.
const initialHealthyOpen = !hasOpenedSocket.current && !hasNeededSocketRecovery.current;
hasOpenedSocket.current = true;
// Browser lists stop polling on an empty result. A reconcile that joins
// an older read needs one more read after it. Scan before reconciling,
// so the reconcile's own reads are not followed up again.
refreshPendingTaskBrowserReads(queryClient);
void queryClient.invalidateQueries({
type: "active",
predicate: initialHealthyOpen ? (query) => {
const key = JSON.stringify(query.queryKey);
return isLiveReconciledQuery(query)
&& key !== JSON.stringify(queryKeys.auth.session) && key !== JSON.stringify(queryKeys.health);
} : isLiveReconciledQuery,
}, { cancelRefetch: false });
reconnectAttempt = 0;
};
nextSocket.onmessage = (message) => {
if (closed || socket !== nextSocket) return;
const raw = typeof message.data === "string" ? message.data : "";
if (!raw) return;
try {
const parsed = JSON.parse(raw) as LiveEvent;
if (transcripts.receive(parsed, recoverQueries)) {
if ((parsed as { type: string }).type === "live.resync") {
refreshPendingTaskBrowserReads(queryClient);
void queryClient.invalidateQueries({ type: "active", predicate: isLiveReconciledQuery }, { cancelRefetch: false });
}
return;
}
if (!getPageVisibility().visible) return;
handleLiveEvent(
coalescingClient,
liveCompanyId,
pathnameRef.current,
parsed,
pushToast,
gateRef.current,
{
userId: currentActorRef.current.userId,
agentId: currentActorRef.current.agentId,
},
);
// Fan the raw event out to component subscribers after cache
// handling so any reader sees fresh query data.
dispatchLiveEventToSubscribers(
subscribersRef.current,
liveCompanyId,
parsed,
);
} catch {
// Ignore non-JSON payloads.
}
};
nextSocket.onerror = () => {
if (closed || socket !== nextSocket) return;
recoveryActive = false;
setConnectedScopeKey((current) => current === socketScopeKey ? null : current);
// Wait for onclose to drive the reconnect. Self-closing here is what
// produces the "closed before connection established" browser noise.
};
nextSocket.onclose = () => {
if (socket !== nextSocket) return;
recoveryActive = false;
socket = null;
transcripts.close();
if (closed) return;
setConnectedScopeKey((current) => current === socketScopeKey ? null : current);
// A dropped socket may be the first sign of an outage; the store
// confirms with a health probe before it changes state.
connectivity.reportSocketStatus("closed");
startPolling();
scheduleReconnect();
};
};
// Delay initial connect slightly so React StrictMode's double-invoke
// cleanup fires before the WebSocket is created, avoiding the
// "WebSocket closed before connection established" dev-mode error.
const connectTimer = window.setTimeout(connect, 0);
return () => {
closed = true;
setConnectedScopeKey((current) => current === socketScopeKey ? null : current);
window.clearTimeout(connectTimer);
clearReconnect();
stopPolling();
const activeSocket = socket;
socket = null;
transcripts.close();
closeSocketQuietly(activeSocket, "provider_unmount");
};
}, [
visible,
invalidationBatcher,
queryClient,
coalescingClient,
liveCompanyId,
pushToast,
canConnectSocket,
socketAuthKey,
connectivity,
socketScopeKey,
transcripts,
]);
return (
<CompanyLiveConnectionContext.Provider value={
visible && canConnectSocket && connectedScopeKey === socketScopeKey ? liveCompanyId : null
}>
<LiveEventSubscriptionContext.Provider value={subscriptionValue}>
{children}
</LiveEventSubscriptionContext.Provider>
</CompanyLiveConnectionContext.Provider>
);
}