Notify once while an agent's finish is unread, not on each turn it starts on its own (#10200)

* fix(server): notify once while an agent's finish is unread

Since v0.16.0, a turn that an agent starts on its own cleared the
agent's unread "finished" attention. Every such turn that then ended
raised a new "finished" notification. A Claude Code agent that reacts
to each event of a Monitor or a background task starts one turn per
event, so the user got a notification every few seconds.

A turn that the agent starts on its own now clears only error
attention, which is what the earlier change intended. An unread finish
stays unread, so the next finish does not notify again. After the
user reads the agent, the next finish notifies as before. A prompt
from the user still clears all attention.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(server): notify a repeat finish the user was not told about

The previous commit kept an unread finish across turns that an agent
starts on its own, and the agent manager then sent no attention for
the later finishes. Suppose the user had the agent on screen for the
first finish. The app keeps that finish unread, and no notification
is sent while the agent is on screen. After the user left, no later
finish notified at all.

The agent manager now reports each finish, and marks a finish that
repeats an unread finish. The websocket server owns delivery, so it
records whether it delivered a notification for the unread finish.
A repeat notifies only when nothing was delivered for it yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(server): key the notified unread finish by its attention timestamp

The websocket server recorded only that it had notified for some
finish of an agent. Mark as unread starts a new unread finish without
an attention event, so a later repeat used the record of an older
finish that the user had already read, and sent nothing.

The attention callback now carries the timestamp of the agent's
current unread attention, which identifies the unread finish. The
server stores the timestamp it notified for, and suppresses a finish
only when it belongs to that same unread finish. This replaces the
repeatsUnreadFinish flag.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: paseo-bot[bot] <266920839+paseo-bot[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
paseo-bot[bot]
2026-11-19 11:08:01 +00:00
committed by GitHub
co-authored by Claude Opus 5.5
parent c4e8c17022
commit 4fb95106e7
4 changed files with 168 additions and 8 deletions
@@ -9768,6 +9768,69 @@ test.each([
},
);
test("turns an agent starts on its own keep its finish unread until it is read", async () => {
const workdir = mkdtempSync(join(tmpdir(), "agent-manager-autonomous-finish-unread-"));
const storage = new AgentStorage(join(workdir, "agents"), logger);
class AutonomousClient extends TestAgentClient {
readonly session = new TestAgentSession({ provider: "codex", cwd: workdir });
override async createSession(): Promise<AgentSession> {
return this.session;
}
}
const client = new AutonomousClient();
const attention: Array<{ reason: string; attentionTimestamp: Date | null }> = [];
const manager = new AgentManager({
clients: { codex: client },
registry: storage,
logger,
onAgentAttention: ({ reason, attentionTimestamp }) =>
attention.push({ reason, attentionTimestamp }),
});
onTestFinished(async () => {
await manager.closeAgent(agent.id);
await manager.flush();
rmSync(workdir, { recursive: true, force: true });
});
const agent = await manager.createAgent({ provider: "codex", cwd: workdir }, undefined, {
workspaceId: undefined,
});
async function runAutonomousTurn(turnId: string): Promise<void> {
const running = waitForAgentLifecycle(manager, agent.id, "running");
client.session.pushEvent({ type: "turn_started", provider: "codex", turnId });
await running;
const idle = waitForAgentLifecycle(manager, agent.id, "idle");
client.session.pushEvent({ type: "turn_completed", provider: "codex", turnId });
await idle;
}
// A background task's output wakes the agent three times while nobody reads it.
await runAutonomousTurn("wake-1");
await runAutonomousTurn("wake-2");
await runAutonomousTurn("wake-3");
// Each finish is reported, and all three belong to the same unread finish.
const unreadFinish = attention[0]?.attentionTimestamp;
expect(unreadFinish).toBeInstanceOf(Date);
expect(attention).toEqual([
{ reason: "finished", attentionTimestamp: unreadFinish },
{ reason: "finished", attentionTimestamp: unreadFinish },
{ reason: "finished", attentionTimestamp: unreadFinish },
]);
expect(toAgentPayload(manager.getAgent(agent.id)!)).toMatchObject({
requiresAttention: true,
attentionReason: "finished",
});
// After the user reads the agent, its next finish is a new unread finish.
await manager.clearAgentAttention(agent.id);
await runAutonomousTurn("wake-4");
expect(attention).toHaveLength(4);
expect(attention[3]?.reason).toBe("finished");
expect(attention[3]?.attentionTimestamp).not.toBe(unreadFinish);
});
test("streamAgent clears pending run when startTurn fails before a turn id exists", async () => {
const workdir = mkdtempSync(join(tmpdir(), "agent-manager-start-turn-failure-"));
const storagePath = join(workdir, "agents");
@@ -334,6 +334,8 @@ export type AgentAttentionCallback = (params: {
agentId: string;
provider: AgentProvider;
reason: "finished" | "error" | "permission";
/** When the agent's current unread attention started; null when the agent is read. */
attentionTimestamp: Date | null;
}) => void;
export type AgentArchivedCallback = (agentId: string) => Promise<void> | void;
@@ -5596,7 +5598,11 @@ export class AgentManager {
this.openActiveTurn(agent, eventTurnId, new Date());
}
agent.lastError = undefined;
agent.attention = { requiresAttention: false };
// Nobody read the agent, so an unread finish stays unread. Clearing it would make every
// turn the agent starts on its own, such as a reaction to background output, notify again.
if (agent.attention.requiresAttention && agent.attention.attentionReason === "error") {
agent.attention = { requiresAttention: false };
}
agent.lifecycle = "running";
this.emitState(agent);
}
@@ -5872,11 +5878,16 @@ export class AgentManager {
return;
}
const finished = previousStatus === "running" && currentStatus === "idle";
if (agent.attention.requiresAttention) {
// The unread finish stays the same; the notifier knows whether the user was told about it.
if (finished && agent.attention.attentionReason === "finished") {
this.broadcastAgentAttention(agent, "finished");
}
return;
}
if (previousStatus === "running" && currentStatus === "idle") {
if (finished) {
agent.attention = {
requiresAttention: true,
attentionReason: "finished",
@@ -6013,6 +6024,9 @@ export class AgentManager {
agentId: agent.id,
provider: agent.provider,
reason,
attentionTimestamp: agent.attention.requiresAttention
? agent.attention.attentionTimestamp
: null,
});
}
@@ -246,6 +246,7 @@ describe("VoiceAssistantWebSocketServer notification payloads", () => {
agentId: "agent-1",
provider: "claude",
reason: "finished",
attentionTimestamp: new Date(),
});
expect(unsubscribed.send).not.toHaveBeenCalled();
@@ -270,6 +271,7 @@ describe("VoiceAssistantWebSocketServer notification payloads", () => {
agentId: "agent-1",
provider: "claude",
reason: "finished",
attentionTimestamp: new Date(),
});
expect(pushNotifications.sent).toEqual([
@@ -304,6 +306,7 @@ describe("VoiceAssistantWebSocketServer notification payloads", () => {
agentId: "agent-2",
provider: "claude",
reason: "finished",
attentionTimestamp: new Date(),
});
expect(pushNotifications.sent).toHaveLength(1);
@@ -330,6 +333,7 @@ describe("VoiceAssistantWebSocketServer notification payloads", () => {
agentId: "agent-X",
provider: "claude",
reason: "finished",
attentionTimestamp: new Date(),
});
expect(readAttentionRequiredMessage(electronWs).shouldNotify).toBe(true);
@@ -345,6 +349,7 @@ describe("VoiceAssistantWebSocketServer notification payloads", () => {
agentId: "agent-no-heartbeat",
provider: "claude",
reason: "finished",
attentionTimestamp: new Date(),
});
expect(readAttentionRequiredMessage(ws).shouldNotify).toBe(false);
@@ -359,9 +364,60 @@ describe("VoiceAssistantWebSocketServer notification payloads", () => {
agentId: "agent-no-heartbeat",
provider: "claude",
reason: "error",
attentionTimestamp: new Date(),
});
expect(readAttentionRequiredMessage(ws).shouldNotify).toBe(false);
expect(pushNotifications.sent).toEqual([]);
});
it("notifies once while an agent's finish stays unread", async () => {
const { server, pushNotifications } = createServer();
const broadcast = (attentionTimestamp: Date) =>
asInternals<WebSocketServerInternals>(server).broadcastAgentAttention({
agentId: "agent-1",
provider: "claude",
reason: "finished",
attentionTimestamp,
});
const firstUnreadFinish = new Date(1_000);
await broadcast(firstUnreadFinish);
await broadcast(firstUnreadFinish);
await broadcast(firstUnreadFinish);
expect(pushNotifications.sent).toHaveLength(1);
// After the user reads the agent (or marks it unread), its next unread finish is new.
await broadcast(new Date(2_000));
expect(pushNotifications.sent).toHaveLength(2);
});
it("notifies a repeated finish when the user had the agent on screen for the first one", async () => {
const { server, pushNotifications } = createServer();
const activity = {
deviceType: "web" as const,
appVisible: true,
focusedAgentId: "agent-1" as string | null,
lastActivityAt: new Date(),
};
connectClient(server, activity);
const unreadFinish = new Date(1_000);
const broadcast = () =>
asInternals<WebSocketServerInternals>(server).broadcastAgentAttention({
agentId: "agent-1",
provider: "claude",
reason: "finished",
attentionTimestamp: unreadFinish,
});
await broadcast();
expect(pushNotifications.sent).toEqual([]);
// The user leaves; the agent keeps finishing turns it starts on its own.
activity.appVisible = false;
activity.focusedAgentId = null;
activity.lastActivityAt = new Date(Date.now() - 600_000);
await broadcast();
await broadcast();
expect(pushNotifications.sent).toHaveLength(1);
});
});
+33 -6
View File
@@ -98,6 +98,7 @@ import {
computeNotificationPlan,
isPushEligibleAttentionReason,
type ClientPresenceState,
type NotificationPlan,
} from "./agent-attention-policy.js";
import {
buildAgentAttentionNotificationPayload,
@@ -599,6 +600,8 @@ export class VoiceAssistantWebSocketServer {
private readonly daemonConfigStore: DaemonConfigStore;
private readonly pushNotifications: PushNotifications;
private readonly pushNotificationSender: PushNotificationSender;
// Per agent, the unread finish (by its attention timestamp) that a notification was delivered for.
private readonly notifiedUnreadFinishAt = new Map<string, number>();
private readonly mcpBaseUrl: string | null;
private speech!: SpeechService | null;
private terminalManager!: TerminalManager | null;
@@ -2922,6 +2925,7 @@ export class VoiceAssistantWebSocketServer {
agentId: string;
provider: AgentProvider;
reason: "finished" | "error" | "permission";
attentionTimestamp: Date | null;
}): Promise<void> {
const agent = this.agentManager.getAgent(params.agentId);
if (!agent?.workspaceId) {
@@ -2960,12 +2964,15 @@ export class VoiceAssistantWebSocketServer {
permissionRequest: findLatestPermissionRequest(agent.pendingPermissions),
});
const plan = computeNotificationPlan({
allStates,
focusTarget: { kind: "agent", id: params.agentId },
pushEligible: isPushEligibleAttentionReason(params.reason),
nowMs,
});
const plan = this.planOncePerUnreadFinish(
params,
computeNotificationPlan({
allStates,
focusTarget: { kind: "agent", id: params.agentId },
pushEligible: isPushEligibleAttentionReason(params.reason),
nowMs,
}),
);
if (plan.shouldPush) {
void this.pushNotificationSender.send(notification).catch((err) => {
@@ -3016,6 +3023,26 @@ export class VoiceAssistantWebSocketServer {
}
}
// An agent can finish many times while its first finish is unread, for example when it
// reacts to each event of a background task. The user hears about an unread finish once.
// A finish that was not delivered, because the user had the agent on screen, does not count.
private planOncePerUnreadFinish(
params: { agentId: string; reason: string; attentionTimestamp: Date | null },
plan: NotificationPlan,
): NotificationPlan {
if (params.reason !== "finished" || params.attentionTimestamp === null) {
return plan;
}
const unreadFinishAt = params.attentionTimestamp.getTime();
if (this.notifiedUnreadFinishAt.get(params.agentId) === unreadFinishAt) {
return { inAppRecipientIndex: null, shouldPush: false };
}
if (plan.shouldPush || plan.inAppRecipientIndex !== null) {
this.notifiedUnreadFinishAt.set(params.agentId, unreadFinishAt);
}
return plan;
}
private async broadcastTerminalAttention(params: {
terminalId: string;
cwd: string;