@hyperdrive.bot/paseo-cli 0.3.45 → 0.3.47

package/dist/commands/agent/ls-filter.d.ts

@@ -0,0 +1,68 @@
+/**
+ * `paseo agent ls` filtering, over the SAME predicate the app and the MCP tool
+ * use (`@hyperdrive.bot/paseo-protocol/agent-filter`).
+ *
+ * Two things this file exists to avoid. First, a third hand-rolled copy of the
+ * semantics: the app has drifted from itself three times this way, and a CLI
+ * that disagreed with the UI about what "running" means would be worse, because
+ * nobody is looking at a list while it lies. Second, the `--status`/`--cwd`
+ * situation this replaces -- both were declared on the options interface and
+ * both were applied by `runLsCommand`, but neither was ever registered as a
+ * Commander option, so the filtering code was live and completely unreachable.
+ */
+import { type AgentArchivedMode, type AgentFilterCriteria, type AgentTimeField, type AgentTimeSelection } from "@hyperdrive.bot/paseo-protocol/agent-filter";
+import { type WorkspaceStateBucket } from "@hyperdrive.bot/paseo-protocol/agent-state-bucket";
+import type { AgentSnapshotPayload } from "@hyperdrive.bot/paseo-protocol/messages";
+/** The filter flags `agent ls` accepts, mirroring the UI's dimensions. */
+export interface AgentLsFilterOptions {
+    archived?: string;
+    all?: boolean;
+    state?: string[];
+    origin?: string[];
+    tag?: string[];
+    notTag?: string[];
+    kanban?: string[];
+    notKanban?: string[];
+    provider?: string[];
+    notProvider?: string[];
+    timeField?: string;
+    window?: string;
+    from?: string;
+    to?: string;
+    text?: string;
+}
+/**
+ * `--archived` wins when given; otherwise `-a` means "all" and the default is
+ * `hide`, which is the behaviour `agent ls` has always had.
+ */
+export declare function resolveLsArchivedMode(options: AgentLsFilterOptions): AgentArchivedMode;
+export declare function resolveLsTimeField(options: AgentLsFilterOptions): AgentTimeField;
+/**
+ * A window and an exact range are the same dimension, so the more specific
+ * request (the range) wins rather than intersecting into an unexplainable
+ * empty list.
+ */
+export declare function resolveLsTimeSelection(options: AgentLsFilterOptions): AgentTimeSelection | null;
+/**
+ * Builds the criteria.
+ *
+ * `state` and `origin` are closed sets, so they carry no exclude half: "except
+ * running" is the other five buckets, and listing them is not the burden that
+ * enumerating an open set of tags would be.
+ */
+export declare function buildAgentLsCriteria(options: AgentLsFilterOptions): AgentFilterCriteria;
+type FilterableAgent = Pick<AgentSnapshotPayload, "id" | "status" | "cwd" | "createdAt" | "updatedAt" | "archivedAt" | "labels" | "provider"> & Partial<Pick<AgentSnapshotPayload, "title" | "lastUserMessageAt" | "requiresAttention" | "attentionReason" | "pendingPermissions" | "activeBackgroundTaskCount">>;
+/**
+ * `parentAgentId -> live child count`, computed over the corpus BEFORE any
+ * narrowing so a parent does not lose its `pending` bucket because its only
+ * live child was filtered out.
+ */
+export declare function countActiveChildrenByParent(agents: readonly FilterableAgent[]): Map<string, number>;
+/** The derived bucket, matching what the app shows for the same agent. */
+export declare function deriveLsStateBucket(agent: FilterableAgent, activeChildCount: number): WorkspaceStateBucket;
+/** Narrows `agents` with the shared predicate. `now` is injected so tests are deterministic. */
+export declare function applyAgentLsFilter<T extends FilterableAgent>(agents: readonly T[], criteria: AgentFilterCriteria, timeField: AgentTimeField, now: Date): T[];
+/** `agentId -> derived bucket`, so the table can SHOW what `--state` filtered on. */
+export declare function stateBucketsById(agents: readonly FilterableAgent[]): Map<string, WorkspaceStateBucket>;
+export {};
+//# sourceMappingURL=ls-filter.d.ts.map

package/dist/commands/agent/ls-filter.js

@@ -0,0 +1,139 @@
+/**
+ * `paseo agent ls` filtering, over the SAME predicate the app and the MCP tool
+ * use (`@hyperdrive.bot/paseo-protocol/agent-filter`).
+ *
+ * Two things this file exists to avoid. First, a third hand-rolled copy of the
+ * semantics: the app has drifted from itself three times this way, and a CLI
+ * that disagreed with the UI about what "running" means would be worse, because
+ * nobody is looking at a list while it lies. Second, the `--status`/`--cwd`
+ * situation this replaces -- both were declared on the options interface and
+ * both were applied by `runLsCommand`, but neither was ever registered as a
+ * Commander option, so the filtering code was live and completely unreachable.
+ */
+import { agentPassesFilter, deriveAgentOrigin, emptyAgentFilterCriteria, filterSelectionFrom, isAgentDay, } from "@hyperdrive.bot/paseo-protocol/agent-filter";
+import { PARENT_AGENT_ID_LABEL } from "@hyperdrive.bot/paseo-protocol/agent-labels";
+import { deriveAgentStateBucket, } from "@hyperdrive.bot/paseo-protocol/agent-state-bucket";
+const TAG_LABEL_PREFIX = "tag:";
+const KANBAN_LABEL_KEY = "kanban";
+function isTimeWindow(value) {
+    return (value === "today" || value === "3d" || value === "7d" || value === "30d" || value === "stale");
+}
+/**
+ * `--archived` wins when given; otherwise `-a` means "all" and the default is
+ * `hide`, which is the behaviour `agent ls` has always had.
+ */
+export function resolveLsArchivedMode(options) {
+    const explicit = options.archived?.trim();
+    if (explicit === "all" || explicit === "only" || explicit === "hide")
+        return explicit;
+    return options.all ? "all" : "hide";
+}
+export function resolveLsTimeField(options) {
+    return options.timeField === "created" ? "created" : "active";
+}
+/**
+ * A window and an exact range are the same dimension, so the more specific
+ * request (the range) wins rather than intersecting into an unexplainable
+ * empty list.
+ */
+export function resolveLsTimeSelection(options) {
+    const { from, to, window } = options;
+    if (isAgentDay(from) && isAgentDay(to))
+        return { kind: "range", range: { from, to } };
+    if (isTimeWindow(window))
+        return { kind: "window", window };
+    return null;
+}
+/**
+ * Builds the criteria.
+ *
+ * `state` and `origin` are closed sets, so they carry no exclude half: "except
+ * running" is the other five buckets, and listing them is not the burden that
+ * enumerating an open set of tags would be.
+ */
+export function buildAgentLsCriteria(options) {
+    return {
+        ...emptyAgentFilterCriteria(),
+        stateSelection: filterSelectionFrom(options.state, undefined),
+        originSelection: filterSelectionFrom(options.origin, undefined),
+        tagSelection: filterSelectionFrom(options.tag, options.notTag),
+        kanbanSelection: filterSelectionFrom(options.kanban, options.notKanban),
+        providerSelection: filterSelectionFrom(options.provider, options.notProvider),
+        archivedMode: resolveLsArchivedMode(options),
+        timeSelection: resolveLsTimeSelection(options),
+        textQuery: (options.text ?? "").trim().toLowerCase(),
+    };
+}
+function isAliveChild(agent) {
+    if (agent.archivedAt)
+        return false;
+    return agent.status === "running" || agent.status === "initializing";
+}
+/**
+ * `parentAgentId -> live child count`, computed over the corpus BEFORE any
+ * narrowing so a parent does not lose its `pending` bucket because its only
+ * live child was filtered out.
+ */
+export function countActiveChildrenByParent(agents) {
+    const counts = new Map();
+    for (const agent of agents) {
+        const parentId = agent.labels?.[PARENT_AGENT_ID_LABEL]?.trim();
+        if (!parentId || !isAliveChild(agent))
+            continue;
+        counts.set(parentId, (counts.get(parentId) ?? 0) + 1);
+    }
+    return counts;
+}
+/** The derived bucket, matching what the app shows for the same agent. */
+export function deriveLsStateBucket(agent, activeChildCount) {
+    return deriveAgentStateBucket({
+        status: agent.status,
+        pendingPermissionCount: agent.pendingPermissions?.length ?? 0,
+        requiresAttention: agent.requiresAttention ?? false,
+        attentionReason: agent.attentionReason ?? null,
+        activeChildCount,
+    });
+}
+function timeValueFor(agent, field) {
+    const raw = field === "created" ? agent.createdAt : (agent.lastUserMessageAt ?? agent.updatedAt);
+    if (!raw)
+        return null;
+    const date = new Date(raw);
+    return Number.isFinite(date.getTime()) ? date : null;
+}
+function tagsFromLabels(labels) {
+    if (!labels)
+        return [];
+    return Object.keys(labels)
+        .filter((key) => key.startsWith(TAG_LABEL_PREFIX) && key.length > TAG_LABEL_PREFIX.length)
+        .map((key) => key.slice(TAG_LABEL_PREFIX.length))
+        .sort();
+}
+/** Narrows `agents` with the shared predicate. `now` is injected so tests are deterministic. */
+export function applyAgentLsFilter(agents, criteria, timeField, now) {
+    const childrenByParent = countActiveChildrenByParent(agents);
+    return agents.filter((agent) => {
+        const activeChildCount = (childrenByParent.get(agent.id) ?? 0) + (agent.activeBackgroundTaskCount ?? 0);
+        return agentPassesFilter({
+            stateBucket: deriveLsStateBucket(agent, activeChildCount),
+            tags: tagsFromLabels(agent.labels),
+            kanbanBucket: agent.labels?.[KANBAN_LABEL_KEY]?.trim() || null,
+            isArchived: Boolean(agent.archivedAt),
+            timeValue: timeValueFor(agent, timeField),
+            provider: agent.provider,
+            origin: deriveAgentOrigin(agent.labels),
+            searchableText: `${agent.title ?? ""} ${agent.cwd}`.toLowerCase(),
+        }, criteria, now);
+    });
+}
+/** `agentId -> derived bucket`, so the table can SHOW what `--state` filtered on. */
+export function stateBucketsById(agents) {
+    const childrenByParent = countActiveChildrenByParent(agents);
+    const buckets = new Map();
+    for (const agent of agents) {
+        const activeChildCount = (childrenByParent.get(agent.id) ?? 0) + (agent.activeBackgroundTaskCount ?? 0);
+        buckets.set(agent.id, deriveLsStateBucket(agent, activeChildCount));
+    }
+    return buckets;
+}
+//# sourceMappingURL=ls-filter.js.map

package/dist/commands/agent/ls.d.ts

@@ -11,6 +11,12 @@ export interface AgentListItem {
     provider: string;
     thinking: string;
     status: string;
+    /**
+     * The DERIVED bucket the app groups by. Shown next to the raw lifecycle
+     * because `--state pending` on a row whose STATUS reads `idle` is otherwise
+     * unreadable: they are different questions and both answers matter.
+     */
+    state: string;
     cwd: string;
     created: string;
 }
@@ -30,8 +36,23 @@ export interface AgentLsOptions extends CommandOptions {
     label?: string[];
     /** Filter by thinking option ID */
     thinking?: string;
+    /** Derived-state bucket(s), repeatable. */
+    state?: string[];
+    origin?: string[];
+    tag?: string[];
+    notTag?: string[];
+    kanban?: string[];
+    notKanban?: string[];
+    provider?: string[];
+    notProvider?: string[];
+    archived?: string;
+    timeField?: string;
+    window?: string;
+    from?: string;
+    to?: string;
+    text?: string;
 }
-export declare function buildAgentLsFetchOptions(options: Pick<AgentLsOptions, "all" | "global" | "label" | "thinking">): FetchAgentsOptions;
+export declare function buildAgentLsFetchOptions(options: Pick<AgentLsOptions, "all" | "global" | "label" | "thinking" | "archived">): FetchAgentsOptions;
 /**
  * Agent ls command semantics:
  * - `paseo agent ls`    → active non-archived agents

package/dist/commands/agent/ls.js

@@ -1,13 +1,33 @@
 import { connectToDaemon, getDaemonHost } from "../../utils/client.js";
 import { collectMultiple } from "../../utils/command-options.js";
 import { isSameOrDescendantPath } from "../../utils/paths.js";
+import { applyAgentLsFilter, buildAgentLsCriteria, resolveLsTimeField, stateBucketsById, } from "./ls-filter.js";
 export function addLsOptions(cmd) {
-    return cmd
+    return (cmd
         .description("List agents. By default excludes archived agents.")
         .option("-a, --all", "Include archived agents")
         .option("-g, --global", "List agents across all directories")
         .option("--label <key=value>", "Filter by label (can be used multiple times)", collectMultiple, [])
-        .option("--thinking <id>", "Filter by thinking option ID");
+        .option("--thinking <id>", "Filter by thinking option ID")
+        // The dimensions the paseo UI filters by. `--status` and `--cwd` are not new
+        // behaviour: `runLsCommand` has always applied them, but neither was ever
+        // registered here, so the code was unreachable from the command line.
+        .option("--status <status>", "Filter by raw lifecycle status (initializing|idle|running|error|closed)")
+        .option("--cwd <path>", "Filter to this directory and its descendants")
+        .option("--state <bucket>", "Filter by derived state bucket (needs_input|failed|running|pending|attention|done). Repeatable.", collectMultiple, [])
+        .option("--origin <origin>", "Filter by origin (root|delegated). Repeatable.", collectMultiple, [])
+        .option("--tag <tag>", "Keep agents carrying this tag. Repeatable.", collectMultiple, [])
+        .option("--not-tag <tag>", "Drop agents carrying this tag. Repeatable.", collectMultiple, [])
+        .option("--kanban <bucket>", "Keep agents in this kanban bucket. Repeatable.", collectMultiple, [])
+        .option("--not-kanban <bucket>", "Drop agents in this kanban bucket. Repeatable.", collectMultiple, [])
+        .option("--provider <id>", "Keep agents on this provider. Repeatable.", collectMultiple, [])
+        .option("--not-provider <id>", "Drop agents on this provider. Repeatable.", collectMultiple, [])
+        .option("--archived <mode>", "Archived handling: all|only|hide (default hide; -a means all)")
+        .option("--time-field <field>", "Which timestamp dates measure: created|active (default active)")
+        .option("--window <window>", "Rolling window: today|3d|7d|30d|stale")
+        .option("--from <YYYY-MM-DD>", "Exact range start (requires --to)")
+        .option("--to <YYYY-MM-DD>", "Exact range end, inclusive (requires --from)")
+        .option("--text <query>", "Case-insensitive substring over title and cwd"));
 }
 /** Helper to get relative time string */
 function relativeTime(date) {
@@ -60,12 +80,26 @@ export const agentLsSchema = {
                 return undefined;
             },
         },
+        {
+            header: "STATE",
+            field: "state",
+            width: 12,
+            color: (value) => {
+                if (value === "running")
+                    return "green";
+                if (value === "needs_input" || value === "failed")
+                    return "red";
+                if (value === "pending" || value === "attention")
+                    return "yellow";
+                return undefined;
+            },
+        },
         { header: "CWD", field: "cwd", width: 30 },
         { header: "CREATED", field: "created", width: 15 },
     ],
 };
 /** Transform agent snapshot to AgentListItem */
-function toListItem(agent) {
+function toListItem(agent, state) {
     const model = normalizeModelId(agent.runtimeInfo?.model) ?? normalizeModelId(agent.model);
     return {
         id: agent.id,
@@ -74,6 +108,7 @@ function toListItem(agent) {
         provider: model ? `${agent.provider}/${model}` : agent.provider,
         thinking: agent.effectiveThinkingOptionId ?? "auto",
         status: agent.status,
+        state,
         cwd: shortenPath(agent.cwd),
         created: relativeTime(agent.createdAt),
     };
@@ -94,7 +129,10 @@ export function buildAgentLsFetchOptions(options) {
     const labelFilters = parseLabelFilters(options.label);
     const normalizedThinkingOptionId = options.thinking?.trim();
     const daemonFilter = {};
-    if (options.all) {
+    // `only` needs archived records on the wire just as much as `all` does; asking
+    // the daemon to hide them and then filtering FOR them client-side returns an
+    // always-empty list, which reads as "nothing is archived".
+    if (options.all || options.archived === "all" || options.archived === "only") {
         daemonFilter.includeArchived = true;
     }
     if (Object.keys(labelFilters).length > 0) {
@@ -146,15 +184,11 @@ export async function runLsCommand(options, _command) {
         const labelFilters = parseLabelFilters(options.label);
         const fetchPayload = await client.fetchAgents(buildAgentLsFetchOptions(options));
         let agents = fetchPayload.entries.map((entry) => entry.agent);
-        // By default, exclude archived agents. `-a` includes them.
-        if (!options.all) {
-            agents = agents.filter((a) => !a.archivedAt);
-        }
-        // If explicit status filter is provided, apply it.
+        // Raw lifecycle status and cwd stay separate from the shared predicate: they
+        // are properties of the record rather than filter dimensions the UI models.
         if (options.status) {
             agents = agents.filter((a) => a.status === options.status);
         }
-        // Optional cwd filter.
         if (options.cwd) {
             agents = agents.filter((a) => isSameOrDescendantPath(options.cwd, a.cwd));
         }
@@ -171,6 +205,11 @@ export async function runLsCommand(options, _command) {
             });
         }
         await client.close();
+        // Every UI dimension, through the one shared predicate. The state buckets are
+        // computed BEFORE narrowing so a parent keeps its `pending` bucket even when
+        // its only live child is filtered out of the result.
+        const buckets = stateBucketsById(agents);
+        agents = applyAgentLsFilter(agents, buildAgentLsCriteria(options), resolveLsTimeField(options), new Date());
         // Sort agents: running first, then idle, then others; within each group, most recent first
         const statusOrder = { running: 0, idle: 1 };
         agents.sort((a, b) => {
@@ -184,7 +223,7 @@ export async function runLsCommand(options, _command) {
             const bTime = new Date(b.createdAt).getTime();
             return bTime - aTime;
         });
-        const items = agents.map(toListItem);
+        const items = agents.map((agent) => toListItem(agent, buckets.get(agent.id) ?? "done"));
         return {
             type: "list",
             data: items,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperdrive.bot/paseo-cli",
-  "version": "0.3.45",
+  "version": "0.3.47",
   "description": "Paseo CLI - control your AI coding agents from the command line",
   "bin": {
     "paseo": "bin/paseo"
@@ -27,9 +27,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.0.0",
-    "@hyperdrive.bot/paseo-client": "0.3.45",
-    "@hyperdrive.bot/paseo-protocol": "0.3.45",
-    "@hyperdrive.bot/paseo-server": "0.3.45",
+    "@hyperdrive.bot/paseo-client": "0.3.47",
+    "@hyperdrive.bot/paseo-protocol": "0.3.47",
+    "@hyperdrive.bot/paseo-server": "0.3.47",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "mime-types": "^2.1.35",