@hyperdrive.bot/paseo-protocol 0.3.45 → 0.3.47

package/dist/agent-filter.d.ts

@@ -0,0 +1,248 @@
+/**
+ * The ONE agent-filter vocabulary and predicate, shared by every surface.
+ *
+ * ## Why this lives in `protocol`
+ *
+ * The app has had a complete filter system for months: three-state chips over
+ * status / kanban / tag / provider / origin, a three-state archived mode, a
+ * created-vs-active time field, nesting date windows plus exact ranges, and a
+ * free-text query. The MCP `list_agents` tool had five arguments, two of which
+ * did not mean what they read as. An agent driving paseo through MCP or the
+ * CLI therefore could not ask most of the questions a human can ask by
+ * clicking, which is the gap this module closes.
+ *
+ * The obvious fix -- reimplement the predicate daemon-side -- is the one this
+ * repo has already paid for three times. `screens/workspace/session-tab-filter.ts`
+ * documents the incidents: every time a dimension was added or renamed, one of
+ * the two hand-rolled copies was updated and the other went quietly inert. The
+ * chip stayed lit, the count kept moving, and the list did not change. A third
+ * copy behind an RPC would be worse, because nobody is looking at a list while
+ * it lies.
+ *
+ * So the semantics move DOWN into the shared package instead. `packages/app`
+ * re-exports these symbols from its existing `utils/*` module paths, so every
+ * app call site is unchanged and the app's own tests keep asserting against the
+ * same functions; the server imports the same predicate for `list_agents` and
+ * the CLI imports it for `agent ls`. One implementation, three surfaces.
+ *
+ * ## What is deliberately NOT here
+ *
+ * Anything that only exists because a human is pointing at it: the chip cycle
+ * (`cycleFilterValue` is kept because the app's store calls it, but no wire
+ * surface uses it), the calendar grid, the two-tap range draft reducer, sort
+ * order. Those stay in `packages/app`.
+ */
+import type { WorkspaceStateBucket } from "./messages.js";
+/**
+ * Which direction a single value is filtering in.
+ *
+ * `include` is "only this", `exclude` is "everything except this", `neutral` is
+ * the value saying nothing.
+ */
+export type FilterValueMode = "neutral" | "include" | "exclude";
+/**
+ * A multi-pick selection over the values of one dimension.
+ *
+ * Both halves are REQUIRED on the in-memory shape. An optional `exclude` would
+ * read `undefined` at a call site that forgot it, and `undefined` means "off",
+ * which is exactly how this system has shipped an inert filter before. Wire
+ * schemas may accept partial input, but they normalize into this before it
+ * reaches the predicate.
+ */
+export interface FilterSelection<T extends string = string> {
+    /** Values the reader asked to see exclusively. Empty = no inclusion rule. */
+    include: T[];
+    /** Values the reader asked to remove. Empty = no exclusion rule. */
+    exclude: T[];
+}
+/** The cycle a chip walks: rest -> only -> except -> rest. */
+export declare const FILTER_VALUE_MODES: FilterValueMode[];
+export declare function isFilterValueMode(value: unknown): value is FilterValueMode;
+/** A selection with no value in either half: the "dimension is off" value. */
+export declare function emptyFilterSelection<T extends string = string>(): FilterSelection<T>;
+/** Lifts a plain inclusion array into a selection. */
+export declare function filterSelectionFromInclude<T extends string = string>(include: readonly T[]): FilterSelection<T>;
+/**
+ * Builds a selection from two optional halves, which is the shape every wire
+ * surface hands over. A value listed in both halves keeps its inclusion, so a
+ * malformed request narrows rather than contradicting itself.
+ */
+export declare function filterSelectionFrom<T extends string = string>(include: readonly T[] | undefined, exclude: readonly T[] | undefined): FilterSelection<T>;
+/**
+ * Re-validates an untrusted value into a selection, keeping only string entries
+ * and never letting a value sit in both halves.
+ *
+ * Persisted app state is the only untrusted input the app has here, and a
+ * malformed one must degrade to "off" rather than throw on a screen that is
+ * just trying to render a list.
+ */
+export declare function normalizeFilterSelection<T extends string = string>(value: unknown): FilterSelection<T>;
+/** The mode `value` currently sits in. Unknown values are neutral by construction. */
+export declare function getFilterValueMode<T extends string>(selection: FilterSelection<T>, value: T): FilterValueMode;
+/** The mode a chip lands on from `current`. Wraps at the end of the cycle. */
+export declare function nextFilterValueMode(current: FilterValueMode): FilterValueMode;
+/** Moves `value` to `mode`, returning a NEW selection. */
+export declare function setFilterValueMode<T extends string>(selection: FilterSelection<T>, value: T, mode: FilterValueMode): FilterSelection<T>;
+/** One chip tap: advance `value` to the next mode in the cycle. */
+export declare function cycleFilterValue<T extends string>(selection: FilterSelection<T>, value: T): FilterSelection<T>;
+/** Returns `value` to neutral. */
+export declare function clearFilterValue<T extends string>(selection: FilterSelection<T>, value: T): FilterSelection<T>;
+/** True when the dimension is narrowing the list at all. */
+export declare function isFilterSelectionActive<T extends string>(selection: FilterSelection<T>): boolean;
+/** Every value the reader has touched, includes first. */
+export declare function filterSelectionEntries<T extends string>(selection: FilterSelection<T>): {
+    value: T;
+    mode: Exclude<FilterValueMode, "neutral">;
+}[];
+/**
+ * Whether a subject with `value` survives this dimension.
+ *
+ * `null` models a subject with no value in this dimension at all. It cannot
+ * satisfy an inclusion rule -- the reader asked for specific values and this is
+ * not one of them -- but it is not excluded either, since it matches no
+ * excluded value.
+ */
+export declare function passesFilterSelection<T extends string>(value: T | null, selection: FilterSelection<T>): boolean;
+/**
+ * Whether a subject carrying MANY values in this dimension survives (tags).
+ *
+ * Include is satisfied by ANY overlap, and exclude drops the subject if ANY of
+ * its values is excluded -- "except #wip" has to remove a session tagged
+ * `#wip #urgent`, or the chip means nothing on precisely the sessions that
+ * carry several tags.
+ */
+export declare function passesFilterSelectionMulti<T extends string>(values: readonly T[], selection: FilterSelection<T>): boolean;
+/**
+ * `all` shows archived alongside live, `only` shows archived exclusively,
+ * `hide` drops them.
+ *
+ * A boolean cannot express `only`, which is why the wire surfaces take this
+ * instead of the `includeArchived` flag they started with.
+ */
+export type AgentArchivedMode = "all" | "only" | "hide";
+export declare const AGENT_ARCHIVED_MODES: AgentArchivedMode[];
+export declare function isAgentArchivedMode(value: unknown): value is AgentArchivedMode;
+export declare function nextAgentArchivedMode(current: AgentArchivedMode): AgentArchivedMode;
+export declare function passesAgentArchivedMode(isArchived: boolean, mode: AgentArchivedMode): boolean;
+export declare function isAgentArchivedModeActive(mode: AgentArchivedMode): boolean;
+/** `root` = a human started it; `delegated` = another agent spawned it. */
+export type AgentOrigin = "root" | "delegated";
+export declare const AGENT_ORIGINS: AgentOrigin[];
+export declare function isAgentOrigin(value: unknown): value is AgentOrigin;
+export declare function deriveAgentOrigin(labels: Record<string, string> | null | undefined): AgentOrigin;
+/**
+ * Which timestamp the span is measured against.
+ *
+ * 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.
+ */
+export type AgentTimeField = "created" | "active";
+/**
+ * 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
+ * wider one, leaving the narrower one looking selected while doing nothing.
+ * `stale` is the strict complement of `30d`, so the two partition the corpus.
+ */
+export type AgentTimeWindow = "today" | "3d" | "7d" | "30d" | "stale";
+export declare const AGENT_TIME_FIELDS: AgentTimeField[];
+export declare const AGENT_TIME_WINDOWS: AgentTimeWindow[];
+/**
+ * An inclusive span of LOCAL CALENDAR DAYS, `YYYY-MM-DD` on both ends.
+ *
+ * Stored as days rather than instants on purpose: resolving to instants at
+ * store time freezes one timezone's midnight into the filter, so the same saved
+ * span covers a different 24 hours after a flight or a DST change.
+ */
+export interface AgentDateRange {
+    from: string;
+    to: string;
+}
+/**
+ * Presets and exact dates are ONE dimension in two shapes.
+ *
+ * A second field beside the window would be able to hold "7 days" AND "March
+ * 4" at once -- an intersection that is empty unless March 4 falls inside the
+ * week, and whose emptiness no surface can explain to the reader.
+ */
+export type AgentTimeSelection = {
+    kind: "window";
+    window: AgentTimeWindow;
+} | {
+    kind: "range";
+    range: AgentDateRange;
+};
+export declare function isAgentTimeField(value: unknown): value is AgentTimeField;
+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;
+export declare function isAgentDateRange(value: unknown): value is AgentDateRange;
+export declare function isAgentTimeSelection(value: unknown): value is AgentTimeSelection;
+export declare function formatAgentDay(date: Date): string;
+export declare function normalizeAgentDateRange(range: AgentDateRange): AgentDateRange;
+export declare function isWithinAgentDateRange(timestamp: Date | null | undefined, range: AgentDateRange): boolean;
+export declare function isWithinAgentTimeWindow(timestamp: Date | null | undefined, window: AgentTimeWindow, now: Date): boolean;
+/** Dispatches on the selection's shape. `null` means the dimension is off. */
+export declare function matchesAgentTimeSelection(timestamp: Date | null | undefined, selection: AgentTimeSelection | null, now: Date): boolean;
+/**
+ * Everything one agent contributes to a filtering decision.
+ *
+ * Built by each surface from whatever record it holds (the app's directory
+ * entry, the daemon's list-item payload) so the predicate itself never has to
+ * know which one it is looking at.
+ */
+export interface AgentFilterSubject {
+    /** The derived state bucket. See `deriveAgentStateBucket`. */
+    stateBucket: WorkspaceStateBucket;
+    /** User tag names, without the `tag:` prefix. */
+    tags: string[];
+    /** The kanban bucket id from `labels.kanban`, or `null` when unresolved. */
+    kanbanBucket: string | null;
+    isArchived: boolean;
+    /** The timestamp the caller resolved for the active `timeField`. */
+    timeValue: Date | null;
+    /** Provider id (`claude`, `codex`, `pool-tu`, ...). */
+    provider: string;
+    origin: AgentOrigin;
+    /** Lowercased haystack for the free-text query (title + cwd). */
+    searchableText: string;
+}
+/**
+ * A complete filter request.
+ *
+ * Composition: OR within a dimension, AND across dimensions.
+ *
+ * Note which dimensions carry an `exclude` half and which do not. `stateBucket`
+ * and `origin` are CLOSED sets (six values and two), so "except running" is
+ * expressible as an include list of the others and an exclude half would buy
+ * nothing. `tag`, `kanban` and `provider` are OPEN sets discovered from live
+ * data, so their complement cannot be enumerated at all and the exclude half is
+ * the only way to say "except this one". They are typed identically for the
+ * predicate's benefit; it is the WIRE schemas that decline to offer the
+ * exclude half where it adds nothing.
+ */
+export interface AgentFilterCriteria {
+    stateSelection: FilterSelection<WorkspaceStateBucket>;
+    tagSelection: FilterSelection<string>;
+    kanbanSelection: FilterSelection<string>;
+    archivedMode: AgentArchivedMode;
+    timeSelection: AgentTimeSelection | null;
+    providerSelection: FilterSelection<string>;
+    originSelection: FilterSelection<AgentOrigin>;
+    /** Lowercased, trimmed. Empty = no text filter. */
+    textQuery: string;
+}
+/** Criteria that keep everything. The starting point for a partial request. */
+export declare function emptyAgentFilterCriteria(): AgentFilterCriteria;
+/** True when any dimension is narrowing the corpus. */
+export declare function isAgentFilterActive(criteria: AgentFilterCriteria): boolean;
+/**
+ * Whether `subject` survives every dimension of `criteria`.
+ *
+ * `now` is a parameter rather than a `new Date()` call so that a caller
+ * computing facet counts and a caller filtering the list read the SAME instant.
+ * Two independent clock reads can count a boundary session in the chip and drop
+ * it from the list, producing a "showing 4 of 5" that never resolves.
+ */
+export declare function agentPassesFilter(subject: AgentFilterSubject, criteria: AgentFilterCriteria, now: Date): boolean;
+//# sourceMappingURL=agent-filter.d.ts.map

package/dist/agent-filter.js

@@ -0,0 +1,340 @@
+/**
+ * The ONE agent-filter vocabulary and predicate, shared by every surface.
+ *
+ * ## Why this lives in `protocol`
+ *
+ * The app has had a complete filter system for months: three-state chips over
+ * status / kanban / tag / provider / origin, a three-state archived mode, a
+ * created-vs-active time field, nesting date windows plus exact ranges, and a
+ * free-text query. The MCP `list_agents` tool had five arguments, two of which
+ * did not mean what they read as. An agent driving paseo through MCP or the
+ * CLI therefore could not ask most of the questions a human can ask by
+ * clicking, which is the gap this module closes.
+ *
+ * The obvious fix -- reimplement the predicate daemon-side -- is the one this
+ * repo has already paid for three times. `screens/workspace/session-tab-filter.ts`
+ * documents the incidents: every time a dimension was added or renamed, one of
+ * the two hand-rolled copies was updated and the other went quietly inert. The
+ * chip stayed lit, the count kept moving, and the list did not change. A third
+ * copy behind an RPC would be worse, because nobody is looking at a list while
+ * it lies.
+ *
+ * So the semantics move DOWN into the shared package instead. `packages/app`
+ * re-exports these symbols from its existing `utils/*` module paths, so every
+ * app call site is unchanged and the app's own tests keep asserting against the
+ * same functions; the server imports the same predicate for `list_agents` and
+ * the CLI imports it for `agent ls`. One implementation, three surfaces.
+ *
+ * ## What is deliberately NOT here
+ *
+ * Anything that only exists because a human is pointing at it: the chip cycle
+ * (`cycleFilterValue` is kept because the app's store calls it, but no wire
+ * surface uses it), the calendar grid, the two-tap range draft reducer, sort
+ * order. Those stay in `packages/app`.
+ */
+import { isDelegatedAgent } from "./agent-labels.js";
+/** The cycle a chip walks: rest -> only -> except -> rest. */
+export const FILTER_VALUE_MODES = ["neutral", "include", "exclude"];
+export function isFilterValueMode(value) {
+    return value === "neutral" || value === "include" || value === "exclude";
+}
+/** A selection with no value in either half: the "dimension is off" value. */
+export function emptyFilterSelection() {
+    return { include: [], exclude: [] };
+}
+/** Lifts a plain inclusion array into a selection. */
+export function filterSelectionFromInclude(include) {
+    return { include: [...include], exclude: [] };
+}
+/**
+ * Builds a selection from two optional halves, which is the shape every wire
+ * surface hands over. A value listed in both halves keeps its inclusion, so a
+ * malformed request narrows rather than contradicting itself.
+ */
+export function filterSelectionFrom(include, exclude) {
+    const includes = dedupe(include);
+    return { include: includes, exclude: dedupe(exclude).filter((v) => !includes.includes(v)) };
+}
+function dedupe(values) {
+    if (!values)
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const value of values) {
+        if (typeof value !== "string" || value === "" || seen.has(value))
+            continue;
+        seen.add(value);
+        out.push(value);
+    }
+    return out;
+}
+/**
+ * Re-validates an untrusted value into a selection, keeping only string entries
+ * and never letting a value sit in both halves.
+ *
+ * Persisted app state is the only untrusted input the app has here, and a
+ * malformed one must degrade to "off" rather than throw on a screen that is
+ * just trying to render a list.
+ */
+export function normalizeFilterSelection(value) {
+    if (typeof value !== "object" || value === null)
+        return emptyFilterSelection();
+    const raw = value;
+    return filterSelectionFrom(normalizeValueList(raw.include), normalizeValueList(raw.exclude));
+}
+function normalizeValueList(value) {
+    return Array.isArray(value) ? dedupe(value.filter((e) => typeof e === "string")) : [];
+}
+/** The mode `value` currently sits in. Unknown values are neutral by construction. */
+export function getFilterValueMode(selection, value) {
+    if (selection.include.includes(value))
+        return "include";
+    if (selection.exclude.includes(value))
+        return "exclude";
+    return "neutral";
+}
+/** The mode a chip lands on from `current`. Wraps at the end of the cycle. */
+export function nextFilterValueMode(current) {
+    const index = FILTER_VALUE_MODES.indexOf(current);
+    return FILTER_VALUE_MODES[(index + 1) % FILTER_VALUE_MODES.length] ?? "neutral";
+}
+/** Moves `value` to `mode`, returning a NEW selection. */
+export function setFilterValueMode(selection, value, mode) {
+    const include = selection.include.filter((entry) => entry !== value);
+    const exclude = selection.exclude.filter((entry) => entry !== value);
+    switch (mode) {
+        case "include":
+            return { include: [...include, value], exclude };
+        case "exclude":
+            return { include, exclude: [...exclude, value] };
+        case "neutral":
+            return { include, exclude };
+    }
+}
+/** One chip tap: advance `value` to the next mode in the cycle. */
+export function cycleFilterValue(selection, value) {
+    return setFilterValueMode(selection, value, nextFilterValueMode(getFilterValueMode(selection, value)));
+}
+/** Returns `value` to neutral. */
+export function clearFilterValue(selection, value) {
+    return setFilterValueMode(selection, value, "neutral");
+}
+/** True when the dimension is narrowing the list at all. */
+export function isFilterSelectionActive(selection) {
+    return selection.include.length > 0 || selection.exclude.length > 0;
+}
+/** Every value the reader has touched, includes first. */
+export function filterSelectionEntries(selection) {
+    return [
+        ...selection.include.map((value) => ({ value, mode: "include" })),
+        ...selection.exclude.map((value) => ({ value, mode: "exclude" })),
+    ];
+}
+/**
+ * Whether a subject with `value` survives this dimension.
+ *
+ * `null` models a subject with no value in this dimension at all. It cannot
+ * satisfy an inclusion rule -- the reader asked for specific values and this is
+ * not one of them -- but it is not excluded either, since it matches no
+ * excluded value.
+ */
+export function passesFilterSelection(value, selection) {
+    if (selection.include.length > 0 && (value === null || !selection.include.includes(value))) {
+        return false;
+    }
+    if (value !== null && selection.exclude.includes(value))
+        return false;
+    return true;
+}
+/**
+ * Whether a subject carrying MANY values in this dimension survives (tags).
+ *
+ * Include is satisfied by ANY overlap, and exclude drops the subject if ANY of
+ * its values is excluded -- "except #wip" has to remove a session tagged
+ * `#wip #urgent`, or the chip means nothing on precisely the sessions that
+ * carry several tags.
+ */
+export function passesFilterSelectionMulti(values, selection) {
+    if (selection.include.length > 0 && !selection.include.some((entry) => values.includes(entry))) {
+        return false;
+    }
+    if (selection.exclude.some((entry) => values.includes(entry)))
+        return false;
+    return true;
+}
+export const AGENT_ARCHIVED_MODES = ["all", "only", "hide"];
+export function isAgentArchivedMode(value) {
+    return value === "all" || value === "only" || value === "hide";
+}
+export function nextAgentArchivedMode(current) {
+    const index = AGENT_ARCHIVED_MODES.indexOf(current);
+    return AGENT_ARCHIVED_MODES[(index + 1) % AGENT_ARCHIVED_MODES.length] ?? "all";
+}
+export function passesAgentArchivedMode(isArchived, mode) {
+    switch (mode) {
+        case "only":
+            return isArchived;
+        case "hide":
+            return !isArchived;
+        case "all":
+            return true;
+    }
+}
+export function isAgentArchivedModeActive(mode) {
+    return mode !== "all";
+}
+export const AGENT_ORIGINS = ["root", "delegated"];
+export function isAgentOrigin(value) {
+    return value === "root" || value === "delegated";
+}
+export function deriveAgentOrigin(labels) {
+    return isDelegatedAgent({ labels }) ? "delegated" : "root";
+}
+export const AGENT_TIME_FIELDS = ["created", "active"];
+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";
+}
+export function isAgentTimeWindow(value) {
+    return (value === "today" || value === "3d" || value === "7d" || value === "30d" || value === "stale");
+}
+/** True for a real `YYYY-MM-DD` calendar day (rejects 2026-02-31). */
+export function isAgentDay(value) {
+    if (typeof value !== "string" || !DAY_PATTERN.test(value))
+        return false;
+    const [year, month, day] = value.split("-").map(Number);
+    if (year === undefined || month === undefined || day === undefined)
+        return false;
+    const date = new Date(year, month - 1, day);
+    return date.getFullYear() === year && date.getMonth() === month - 1 && date.getDate() === day;
+}
+export function isAgentDateRange(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    return isAgentDay(candidate.from) && isAgentDay(candidate.to);
+}
+export function isAgentTimeSelection(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    if (candidate.kind === "window")
+        return isAgentTimeWindow(candidate.window);
+    if (candidate.kind === "range")
+        return isAgentDateRange(candidate.range);
+    return false;
+}
+export function formatAgentDay(date) {
+    const year = String(date.getFullYear()).padStart(4, "0");
+    const month = String(date.getMonth() + 1).padStart(2, "0");
+    const day = String(date.getDate()).padStart(2, "0");
+    return `${year}-${month}-${day}`;
+}
+export function normalizeAgentDateRange(range) {
+    return range.from <= range.to ? range : { from: range.to, to: range.from };
+}
+function startOfLocalDay(now) {
+    const start = new Date(now);
+    start.setHours(0, 0, 0, 0);
+    return start.getTime();
+}
+function startOfDayMs(day) {
+    const [year, month, date] = day.split("-").map(Number);
+    return new Date(year ?? 0, (month ?? 1) - 1, date ?? 1, 0, 0, 0, 0).getTime();
+}
+function endOfDayExclusiveMs(day) {
+    const [year, month, date] = day.split("-").map(Number);
+    return new Date(year ?? 0, (month ?? 1) - 1, (date ?? 1) + 1, 0, 0, 0, 0).getTime();
+}
+export function isWithinAgentDateRange(timestamp, range) {
+    if (!timestamp)
+        return false;
+    const value = timestamp.getTime();
+    if (!Number.isFinite(value))
+        return false;
+    const { from, to } = normalizeAgentDateRange(range);
+    return value >= startOfDayMs(from) && value < endOfDayExclusiveMs(to);
+}
+export function isWithinAgentTimeWindow(timestamp, window, now) {
+    if (!timestamp)
+        return false;
+    const value = timestamp.getTime();
+    if (!Number.isFinite(value))
+        return false;
+    const nowMs = now.getTime();
+    switch (window) {
+        case "today":
+            return value >= startOfLocalDay(now);
+        case "3d":
+            return value >= nowMs - 3 * DAY_MS;
+        case "7d":
+            return value >= nowMs - 7 * DAY_MS;
+        case "30d":
+            return value >= nowMs - 30 * DAY_MS;
+        case "stale":
+            return value < nowMs - 30 * DAY_MS;
+    }
+}
+/** Dispatches on the selection's shape. `null` means the dimension is off. */
+export function matchesAgentTimeSelection(timestamp, selection, now) {
+    if (selection === null)
+        return true;
+    return selection.kind === "window"
+        ? isWithinAgentTimeWindow(timestamp, selection.window, now)
+        : isWithinAgentDateRange(timestamp, selection.range);
+}
+/** Criteria that keep everything. The starting point for a partial request. */
+export function emptyAgentFilterCriteria() {
+    return {
+        stateSelection: emptyFilterSelection(),
+        tagSelection: emptyFilterSelection(),
+        kanbanSelection: emptyFilterSelection(),
+        archivedMode: "all",
+        timeSelection: null,
+        providerSelection: emptyFilterSelection(),
+        originSelection: emptyFilterSelection(),
+        textQuery: "",
+    };
+}
+/** True when any dimension is narrowing the corpus. */
+export function isAgentFilterActive(criteria) {
+    return (isFilterSelectionActive(criteria.stateSelection) ||
+        isFilterSelectionActive(criteria.tagSelection) ||
+        isFilterSelectionActive(criteria.kanbanSelection) ||
+        isAgentArchivedModeActive(criteria.archivedMode) ||
+        criteria.timeSelection !== null ||
+        isFilterSelectionActive(criteria.providerSelection) ||
+        isFilterSelectionActive(criteria.originSelection) ||
+        criteria.textQuery.length > 0);
+}
+/**
+ * Whether `subject` survives every dimension of `criteria`.
+ *
+ * `now` is a parameter rather than a `new Date()` call so that a caller
+ * computing facet counts and a caller filtering the list read the SAME instant.
+ * Two independent clock reads can count a boundary session in the chip and drop
+ * it from the list, producing a "showing 4 of 5" that never resolves.
+ */
+export function agentPassesFilter(subject, criteria, now) {
+    if (!passesFilterSelection(subject.stateBucket, criteria.stateSelection))
+        return false;
+    if (!passesFilterSelectionMulti(subject.tags, criteria.tagSelection))
+        return false;
+    if (!passesFilterSelection(subject.kanbanBucket, criteria.kanbanSelection))
+        return false;
+    if (!passesAgentArchivedMode(subject.isArchived, criteria.archivedMode))
+        return false;
+    if (!matchesAgentTimeSelection(subject.timeValue, criteria.timeSelection, now))
+        return false;
+    if (!passesFilterSelection(subject.provider, criteria.providerSelection))
+        return false;
+    if (!passesFilterSelection(subject.origin, criteria.originSelection))
+        return false;
+    if (criteria.textQuery.length > 0 && !subject.searchableText.includes(criteria.textQuery)) {
+        return false;
+    }
+    return true;
+}
+//# sourceMappingURL=agent-filter.js.map

package/dist/agent-types.d.ts

@@ -429,6 +429,23 @@ export interface AgentSessionConfig {
      * Mapped by each provider to its native instruction field.
      */
     systemPrompt?: string;
+    /**
+     * BCP-47 tag for the language the agent must WRITE and SPEAK back in
+     * ("en-US", "pt-BR"). Session-scoped on purpose: it describes the work
+     * ("this agent works in English"), so it follows the agent across every
+     * device, client and resume, and it applies to typed input just as much as
+     * to dictated or spoken input.
+     *
+     * Deliberately a structured field and NOT prose folded into `systemPrompt`:
+     * voice mode rewrites `systemPrompt` by regex on every toggle
+     * (`stripVoiceModeSystemPrompt`), so anything stored in that string is
+     * living in a field another feature routinely edits. The instruction text is
+     * composed at prompt-build time instead.
+     *
+     * Undefined means "no instruction", i.e. the model mirrors the user's own
+     * language, which is the pre-existing behaviour.
+     */
+    outputLanguage?: string;
     modeId?: string;
     model?: string;
     thinkingOptionId?: string;