refactor: share agent state priority (#846)

packages/server/src/shared/agent-state-bucket.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from "vitest";
+import {
+  deriveAgentStateBucket,
+  getAgentStatusPriority,
+  getWorkspaceStateBucketPriority,
+} from "./agent-state-bucket.js";
+
+describe("deriveAgentStateBucket", () => {
+  it("prioritizes pending permissions as needs_input", () => {
+    expect(
+      deriveAgentStateBucket({
+        status: "idle",
+        pendingPermissionCount: 1,
+        requiresAttention: false,
+        attentionReason: null,
+      }),
+    ).toBe("needs_input");
+  });
+
+  it("keeps legacy permission attention in needs_input", () => {
+    expect(
+      deriveAgentStateBucket({
+        status: "idle",
+        pendingPermissionCount: 0,
+        requiresAttention: true,
+        attentionReason: "permission",
+      }),
+    ).toBe("needs_input");
+  });
+
+  it("prioritizes error attention before running status", () => {
+    expect(
+      deriveAgentStateBucket({
+        status: "running",
+        pendingPermissionCount: 0,
+        requiresAttention: true,
+        attentionReason: "error",
+      }),
+    ).toBe("failed");
+  });
+
+  it("treats unread finished agents as attention", () => {
+    expect(
+      deriveAgentStateBucket({
+        status: "idle",
+        pendingPermissionCount: 0,
+        requiresAttention: true,
+        attentionReason: "finished",
+      }),
+    ).toBe("attention");
+  });
+
+  it("treats initializing agents as done for workspace buckets", () => {
+    expect(
+      deriveAgentStateBucket({
+        status: "initializing",
+        pendingPermissionCount: 0,
+        requiresAttention: false,
+        attentionReason: null,
+      }),
+    ).toBe("done");
+  });
+});
+
+describe("getWorkspaceStateBucketPriority", () => {
+  it("orders active buckets before done", () => {
+    expect(
+      ["done", "attention", "running", "failed", "needs_input"].sort(
+        (left, right) =>
+          getWorkspaceStateBucketPriority(left) - getWorkspaceStateBucketPriority(right),
+      ),
+    ).toEqual(["needs_input", "failed", "running", "attention", "done"]);
+  });
+});
+
+describe("getAgentStatusPriority", () => {
+  it("keeps initializing agents ahead of completed agents in agent lists", () => {
+    expect(getAgentStatusPriority({ status: "initializing" })).toBeLessThan(
+      getAgentStatusPriority({ status: "idle" }),
+    );
+  });
+
+  it("prioritizes pending permissions before errors and running agents", () => {
+    const permission = getAgentStatusPriority({ status: "running", pendingPermissionCount: 1 });
+    expect(permission).toBeLessThan(
+      getAgentStatusPriority({ status: "error", pendingPermissionCount: 0 }),
+    );
+    expect(permission).toBeLessThan(
+      getAgentStatusPriority({ status: "running", pendingPermissionCount: 0 }),
+    );
+  });
+});

packages/server/src/shared/agent-state-bucket.ts

@@ -0,0 +1,55 @@
+import type { AgentLifecycleStatus } from "./agent-lifecycle.js";
+import type { WorkspaceStateBucket } from "./messages.js";
+
+export type AgentAttentionReason = "finished" | "error" | "permission" | null | undefined;
+
+export interface AgentStateBucketInput {
+  status: AgentLifecycleStatus;
+  pendingPermissionCount?: number;
+  requiresAttention?: boolean;
+  attentionReason?: AgentAttentionReason;
+}
+
+const WORKSPACE_STATE_BUCKET_PRIORITY = {
+  needs_input: 0,
+  failed: 1,
+  running: 2,
+  attention: 3,
+  done: 4,
+} as const satisfies Record<WorkspaceStateBucket, number>;
+
+export function deriveAgentStateBucket(input: AgentStateBucketInput): WorkspaceStateBucket {
+  if ((input.pendingPermissionCount ?? 0) > 0 || input.attentionReason === "permission") {
+    return "needs_input";
+  }
+  if (input.status === "error" || input.attentionReason === "error") {
+    return "failed";
+  }
+  if (input.status === "running") {
+    return "running";
+  }
+  if (input.requiresAttention) {
+    return "attention";
+  }
+  return "done";
+}
+
+export function getWorkspaceStateBucketPriority(bucket: WorkspaceStateBucket): number {
+  return WORKSPACE_STATE_BUCKET_PRIORITY[bucket];
+}
+
+export function getAgentStatusPriority(input: AgentStateBucketInput): number {
+  if ((input.pendingPermissionCount ?? 0) > 0 || input.attentionReason === "permission") {
+    return 0;
+  }
+  if (input.status === "error" || input.attentionReason === "error") {
+    return 1;
+  }
+  if (input.status === "running") {
+    return 2;
+  }
+  if (input.status === "initializing") {
+    return 3;
+  }
+  return 4;
+}