@hyperdrive.bot/paseo-protocol 0.3.41 → 0.3.43

package/dist/agent-state-bucket.d.ts

@@ -9,15 +9,39 @@ export interface AgentStateBucketInput {
     attentionReason?: AgentAttentionReason;
     /**
      * Number of still-alive child activities owned by this agent — running
-     * subagents, open shell terminals, and in-flight background tasks. When > 0
-     * the agent is still doing work even if its own lifecycle status has settled
-     * to "idle", so it must keep surfacing as "running" (kanban, activity dot,
-     * background tray) until those children finish or are dismissed.
+     * subagents, open shell terminals, monitors, crons, and in-flight background
+     * tasks. When > 0 the agent is still doing work even if its own lifecycle
+     * status has settled to "idle", so it must keep surfacing as *alive* (kanban,
+     * activity dot, background tray) until those children finish or are dismissed.
+     *
+     * It surfaces as "pending", NOT "running". The distinction is about who
+     * initiates the next contact: "running" means this agent's own turn is in
+     * flight and output is moving right now (a user may want to watch it);
+     * "pending" means the turn has settled but something armed will come back on
+     * its own. Collapsing the two made an armed session indistinguishable from a
+     * live one, and routing armed work through "done" made it invisible.
      */
     activeChildCount?: number;
 }
 /** True when an agent has live children (subagents / shells / background tasks). */
 export declare function hasActiveChildren(input: Pick<AgentStateBucketInput, "activeChildCount">): boolean;
+/**
+ * Map an agent's raw state onto the bucket the UI groups and filters by.
+ *
+ * ORDER IS THE CONTRACT, and the branch order encodes an urgency ladder:
+ * blocked-on-you first, then broken, then live, then armed, then unread, then
+ * finished. In particular `pending` is checked BEFORE `requiresAttention`, so a
+ * session whose turn ended only because a monitor tick woke it does not land in
+ * the unread chip on every tick — see `checkAndSetAttention`, which suppresses
+ * the attention record at source for the same reason.
+ *
+ * ⚠️ `done` is a FALLTHROUGH. Anything this function has not been taught about
+ * becomes "done" — i.e. invisible — by construction rather than by decision.
+ * That is how armed background work stayed hidden for the life of the feature.
+ * When you add a new kind of background activity, it must either be counted in
+ * `activeChildCount` or be named explicitly in the exhaustiveness test
+ * (`agent-state-bucket.exhaustive.test.ts`), which fails the build otherwise.
+ */
 export declare function deriveAgentStateBucket(input: AgentStateBucketInput): WorkspaceStateBucket;
 export declare function getWorkspaceStateBucketPriority(bucket: WorkspaceStateBucket): number;
 export declare function getAgentStatusPriority(input: AgentStateBucketInput): number;

package/dist/agent-state-bucket.js

@@ -7,8 +7,26 @@ const WORKSPACE_STATE_BUCKET_PRIORITY = {
     failed: 1,
     running: 2,
     attention: 3,
-    done: 4,
+    pending: 4,
+    done: 5,
 };
+/**
+ * Map an agent's raw state onto the bucket the UI groups and filters by.
+ *
+ * ORDER IS THE CONTRACT, and the branch order encodes an urgency ladder:
+ * blocked-on-you first, then broken, then live, then armed, then unread, then
+ * finished. In particular `pending` is checked BEFORE `requiresAttention`, so a
+ * session whose turn ended only because a monitor tick woke it does not land in
+ * the unread chip on every tick — see `checkAndSetAttention`, which suppresses
+ * the attention record at source for the same reason.
+ *
+ * ⚠️ `done` is a FALLTHROUGH. Anything this function has not been taught about
+ * becomes "done" — i.e. invisible — by construction rather than by decision.
+ * That is how armed background work stayed hidden for the life of the feature.
+ * When you add a new kind of background activity, it must either be counted in
+ * `activeChildCount` or be named explicitly in the exhaustiveness test
+ * (`agent-state-bucket.exhaustive.test.ts`), which fails the build otherwise.
+ */
 export function deriveAgentStateBucket(input) {
     if ((input.pendingPermissionCount ?? 0) > 0 || input.attentionReason === "permission") {
         return "needs_input";
@@ -16,9 +34,12 @@ export function deriveAgentStateBucket(input) {
     if (input.status === "error" || input.attentionReason === "error") {
         return "failed";
     }
-    if (input.status === "running" || hasActiveChildren(input)) {
+    if (input.status === "running") {
         return "running";
     }
+    if (hasActiveChildren(input)) {
+        return "pending";
+    }
     if (input.requiresAttention) {
         return "attention";
     }
@@ -34,12 +55,15 @@ export function getAgentStatusPriority(input) {
     if (input.status === "error" || input.attentionReason === "error") {
         return 1;
     }
-    if (input.status === "running" || hasActiveChildren(input)) {
+    if (input.status === "running") {
         return 2;
     }
     if (input.status === "initializing") {
         return 3;
     }
-    return 4;
+    if (hasActiveChildren(input)) {
+        return 4;
+    }
+    return 5;
 }
 //# sourceMappingURL=agent-state-bucket.js.map