@hyperdrive.bot/paseo-protocol 0.3.66 → 0.3.67

package/dist/agent-filter.d.ts

@@ -136,8 +136,21 @@ export declare function deriveAgentOrigin(labels: Record<string, string> | null
  * This is a MODE, not a second dimension. AND-ing "created today" with "active
  * today" produces a mostly-empty list; the reader means one question or the
  * other.
+ *
+ * `archived` (2026-08-28) measures `archivedAt`, so the same spans answer "what
+ * did I archive in this period". That question cannot be asked with the
+ * `archivedMode` dimension alone: `only` isolates the archive but says nothing
+ * about WHEN. The two stay orthogonal - this picks the DATE, that picks the
+ * ROWS - and no coupling is needed to make the pair behave, because a session
+ * that was never archived has `archivedAt === null` and every caller's resolver
+ * yields null, which `isWithinAgentTimeWindow` already refuses to match.
+ *
+ * The one pairing that is empty by construction is `archived` with
+ * `archivedMode: "hide"`: rows that are NOT archived, dated by when they were
+ * archived. Surfaces should name that rather than render a bare zero, which
+ * reads as a broken filter.
  */
-export type AgentTimeField = "created" | "active";
+export type AgentTimeField = "created" | "active" | "archived";
 /**
  * The rolling presets. They NEST (`today` is inside `3d` is inside `7d` ...),
  * which is why the span is single-select: OR-ing two always collapses to the
@@ -173,6 +186,39 @@ export type AgentTimeSelection = {
     range: AgentDateRange;
 };
 export declare function isAgentTimeField(value: unknown): value is AgentTimeField;
+/**
+ * The field a cycling control lands on from `current`. Wraps at the end.
+ *
+ * Exported from the protocol so the app's chip cannot drift from the declared
+ * list. The two-way flip this replaced (`f === "created" ? "active" : "created"`)
+ * made any third member unreachable: the label rendered, no tap could select
+ * it. Driving the cycle off AGENT_TIME_FIELDS means a fourth field is
+ * selectable the moment it joins the union.
+ */
+export declare function nextAgentTimeField(current: AgentTimeField): AgentTimeField;
+/** The agent timestamps a time field can name. Shapes differ per caller, so this is the union of them. */
+export interface AgentTimeSource {
+    createdAt?: Date | null;
+    lastActivityAt?: Date | null;
+    archivedAt?: Date | null;
+}
+/**
+ * Collapses an agent's timestamps to the ONE the reader selected.
+ *
+ * This is what makes the field a mode rather than a second dimension:
+ * everything downstream compares a single value and never learns which field
+ * produced it. Exported so the four surfaces that each carried their own copy
+ * of this mapping (the app's Sessions screen and workspace tab strip, the
+ * daemon's `list_agents`, the CLI's `agent ls`) share one definition.
+ *
+ * A `switch`, not a ternary. All four copies were written as
+ * `field === "created" ? created : active`, which treats every field that is
+ * not "created" as "active" - so a new union member compiled clean on all four
+ * and silently measured the wrong timestamp while the UI named the new one.
+ * Exhaustive here, so a fifth field is a type error instead of a filter that
+ * quietly lies.
+ */
+export declare function resolveAgentTimeValue(agent: AgentTimeSource, field: AgentTimeField): Date | null;
 export declare function isAgentTimeWindow(value: unknown): value is AgentTimeWindow;
 /** True for a real `YYYY-MM-DD` calendar day (rejects 2026-02-31). */
 export declare function isAgentDay(value: unknown): value is string;

package/dist/agent-filter.js

@@ -190,12 +190,51 @@ export function isAgentOrigin(value) {
 export function deriveAgentOrigin(labels) {
     return isDelegatedAgent({ labels }) ? "delegated" : "root";
 }
-export const AGENT_TIME_FIELDS = ["created", "active"];
+export const AGENT_TIME_FIELDS = ["created", "active", "archived"];
 export const AGENT_TIME_WINDOWS = ["today", "3d", "7d", "30d", "stale"];
 const DAY_MS = 24 * 60 * 60 * 1000;
 const DAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
 export function isAgentTimeField(value) {
-    return value === "created" || value === "active";
+    return value === "created" || value === "active" || value === "archived";
+}
+/**
+ * The field a cycling control lands on from `current`. Wraps at the end.
+ *
+ * Exported from the protocol so the app's chip cannot drift from the declared
+ * list. The two-way flip this replaced (`f === "created" ? "active" : "created"`)
+ * made any third member unreachable: the label rendered, no tap could select
+ * it. Driving the cycle off AGENT_TIME_FIELDS means a fourth field is
+ * selectable the moment it joins the union.
+ */
+export function nextAgentTimeField(current) {
+    const index = AGENT_TIME_FIELDS.indexOf(current);
+    return AGENT_TIME_FIELDS[(index + 1) % AGENT_TIME_FIELDS.length] ?? "active";
+}
+/**
+ * Collapses an agent's timestamps to the ONE the reader selected.
+ *
+ * This is what makes the field a mode rather than a second dimension:
+ * everything downstream compares a single value and never learns which field
+ * produced it. Exported so the four surfaces that each carried their own copy
+ * of this mapping (the app's Sessions screen and workspace tab strip, the
+ * daemon's `list_agents`, the CLI's `agent ls`) share one definition.
+ *
+ * A `switch`, not a ternary. All four copies were written as
+ * `field === "created" ? created : active`, which treats every field that is
+ * not "created" as "active" - so a new union member compiled clean on all four
+ * and silently measured the wrong timestamp while the UI named the new one.
+ * Exhaustive here, so a fifth field is a type error instead of a filter that
+ * quietly lies.
+ */
+export function resolveAgentTimeValue(agent, field) {
+    switch (field) {
+        case "created":
+            return agent.createdAt ?? null;
+        case "active":
+            return agent.lastActivityAt ?? null;
+        case "archived":
+            return agent.archivedAt ?? null;
+    }
 }
 export function isAgentTimeWindow(value) {
     return (value === "today" || value === "3d" || value === "7d" || value === "30d" || value === "stale");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperdrive.bot/paseo-protocol",
-  "version": "0.3.66",
+  "version": "0.3.67",
   "description": "Paseo shared protocol schemas and wire types",
   "files": [
     "dist",