@wirecat/cli-core 0.500.0 → 0.502.0

package/dist/calendar/reads.js

@@ -1,6 +1,7 @@
 import { CliError } from "@wirecat/cli-base";
-import { dayBoundary, zonedMoment } from "@wirecat/cli-base/query";
-import { eventChange, eventItem, listed, } from "../meetings/index.js";
+import { dateRange, dayBoundary, queryError, queryFieldsOf, } from "@wirecat/cli-base/query";
+import { LIST_QUERY_GUIDE, listQuery, nativeTerms, typedQuery } from "../cli/list-query.js";
+import { event, eventChange, eventItem, listed, } from "../meetings/index.js";
 const iso = (at) => (at === null ? null : new Date(at).toISOString());
 /** Fields whose text whoever sent the invitation wrote: an agent reads them as data. */
 export const CALENDAR_UNTRUSTED_FIELDS = [
@@ -45,65 +46,114 @@ export const plusDays = (date, days) => {
     const [year, month, day] = date.split("-").map(Number);
     return new Date(Date.UTC(year, month - 1, day + days)).toISOString().slice(0, 10);
 };
-export const EVENTS_QUERY_HELP = `
-Words, any order:
-  today | week            today, or today and the next six days, in your time zone
-  from:<date> to:<date>   from the start of one day through the end of another (or a time with a zone)
-  person:<email|id>       events one person attends: an address, or a person id from search
-  calendar:<id>           one calendar, by its id or the provider's id
-  changed:<date>          events new, moved or cancelled since then, each with what changed (from the local copy)
-  overlapping             events that clash with another: timed, not cancelled, not declined, not marked free
-Without a time word: events from the start of today on.`;
+const LIST = "events list";
+const oneSided = (field, example) => (node) => {
+    if (node.operator !== "range" || node.upper !== "*")
+        queryError("query.unsupported-operator", node.span, `${field} takes only an earliest moment, such as ${example}`, {
+            command: LIST,
+            guide: LIST_QUERY_GUIDE,
+        });
+};
+/** `events list`'s query. The store answers `ends_at` and `changed_at` from below only; `starts_at` either way. */
+export const EVENTS_QUERY = {
+    entity: "event",
+    backend: "native",
+    fields: queryFieldsOf(event, {
+        native: ["starts_at", "ends_at", "changed_at", "calendar", "person"],
+        relations: {
+            calendar: { type: "kw", example: "calendar:3", relation: "one calendar, by its id or the provider's id" },
+            person: {
+                type: "kw",
+                example: "person:ana@example.com",
+                relation: "events one person attends: an address, or a person id from search",
+            },
+        },
+        examples: {
+            starts_at: "starts_at:[2026-11-02 TO 2026-11-07}",
+            ends_at: "ends_at>=2026-11-02",
+            changed_at: "changed_at>=2026-10-01",
+        },
+        validate: {
+            ends_at: oneSided("ends_at", "ends_at>=2026-11-02; for the latest, write starts_at<2026-11-07"),
+            changed_at: oneSided("changed_at", "changed_at>=2026-10-01"),
+        },
+    }).map((field) => field.native
+        ? { ...field, operators: field.type === "time" ? ["term", "range"] : ["term", "phrase"] }
+        : field),
+};
+export const EVENTS_QUERY_NOTE = "\nends_at keeps events that end after its moment, so one that ends exactly then is left out. Without starts_at " +
+    "or ends_at: events that end after the start of today, in your time zone.";
+/** A time term as epoch ms: from `lower` on, and before `upper`. */
+export const timeWindow = (node, zone, now) => {
+    const range = node.operator === "range"
+        ? dateRange(node.value, node.upper ?? "*", node.lower_inclusive !== false, node.upper_inclusive !== false, zone, node.span, now)
+        : dateRange(node.value, node.value, true, true, zone, node.span, now);
+    return {
+        ...(range.lower === undefined ? {} : { lower: range.lower_inclusive ? range.lower : range.lower + 1 }),
+        ...(range.upper === undefined ? {} : { upper: range.upper_inclusive ? range.upper + 1 : range.upper }),
+    };
+};
 /**
- * `events list` words into a store filter, for one account. A person named by address is found through the shared
- * store; one nobody knows matches no event.
+ * `events list`'s query into a store filter, for one account. A person named by address is found through the
+ * shared store; one nobody knows matches no event.
  */
-export const eventsFilter = async (words, context) => {
+export const eventsFilter = async (query, context) => {
     const filter = { accountId: context.accountId };
-    const today = localDate(context.now, context.zone);
+    const { zone, now } = context;
     const span = (text) => ({ start: 0, end: text.length });
-    const day = (date) => dayBoundary(date, context.zone, false, span(date));
-    let timed = false;
-    for (const word of words) {
-        const [, field, value = ""] = /^([a-z]+):(.+)$/u.exec(word) ?? [];
-        if (word === "today" || word === "week") {
-            filter.from = day(today);
-            filter.to = day(plusDays(today, word === "today" ? 1 : 7));
-            timed = true;
+    const day = (date) => dayBoundary(date, zone, false, span(date));
+    for (const [field, node] of nativeTerms(listQuery(typedQuery(query), EVENTS_QUERY, LIST), LIST)) {
+        if (field === "starts_at") {
+            const { lower, upper } = timeWindow(node, zone, now);
+            if (lower !== undefined)
+                filter.startsFrom = lower;
+            if (upper !== undefined)
+                filter.to = upper;
         }
-        else if (field === "from") {
-            filter.from = zonedMoment(value, context.zone, span(value));
-            timed = true;
+        else if (field === "ends_at") {
+            // Strictly after, as the default window: `ends_at>=today` leaves out yesterday's all-day event, which ends at
+            // today's midnight.
+            const { lower } = timeWindow(node, zone, now);
+            if (lower !== undefined)
+                filter.from = lower;
         }
-        else if (field === "to") {
-            filter.to = zonedMoment(value, context.zone, span(value), { end: true }) + 1;
-            timed = true;
+        else if (field === "changed_at") {
+            const { lower } = timeWindow(node, zone, now);
+            if (lower !== undefined)
+                filter.changedSince = lower;
         }
-        else if (field === "changed")
-            filter.changedSince = zonedMoment(value, context.zone, span(value));
-        else if (word === "overlapping")
-            filter.overlapping = true;
         else if (field === "calendar")
-            filter.calendarId = (await calendarIn(context.store, context.accountId, value)).id;
+            filter.calendarId = (await calendarIn(context.store, context.accountId, node.value)).id;
         else if (field === "person") {
             if (!context.personOf)
                 throw new CliError("configuration_error", "this tool cannot look people up");
-            const person = await context.personOf(value);
+            const person = await context.personOf(node.value);
             if (person === null)
                 return null;
             filter.personId = person;
         }
-        else
-            throw new CliError("validation_error", `${word} is not an events list word${EVENTS_QUERY_HELP}`, {
-                reason: "query.unknown_word",
-            });
     }
-    if (!timed)
-        filter.from = day(today);
+    if (filter.from === undefined && filter.startsFrom === undefined && filter.to === undefined)
+        filter.from = day(localDate(now, zone));
+    return datedFilter(filter, zone);
+};
+/** Events that end after the start of today and start within seven days, in `zone`. */
+export const weekFilter = (accountId, zone, now) => {
+    const today = localDate(now, zone);
+    const day = (date) => dayBoundary(date, zone, false, { start: 0, end: date.length });
+    return datedFilter({ accountId, from: day(today), to: day(plusDays(today, 7)) }, zone);
+};
+/** The local days an all-day event is compared by, from the filter's instants. */
+const datedFilter = (filter, zone) => {
     if (filter.from !== undefined)
-        filter.fromDate = localDate(filter.from, context.zone);
+        filter.fromDate = localDate(filter.from, zone);
     if (filter.to !== undefined)
-        filter.toDate = plusDays(localDate(filter.to - 1, context.zone), 1);
+        filter.toDate = plusDays(localDate(filter.to - 1, zone), 1);
+    if (filter.startsFrom !== undefined) {
+        const date = localDate(filter.startsFrom, zone);
+        const midnight = dayBoundary(date, zone, false, { start: 0, end: date.length });
+        filter.startsFromDate = midnight < filter.startsFrom ? plusDays(date, 1) : date;
+    }
     return filter;
 };
 /**

package/dist/calendar/testing/memory.js

@@ -474,6 +474,10 @@ export const memoryEventStore = () => {
                     (event.allDay && filter.toDate !== undefined
                         ? has(event, (one) => one.startDate !== null && one.startDate < (filter.toDate ?? ""))
                         : event.startsAt !== null && event.startsAt < filter.to)) &&
+                (filter.startsFrom === undefined ||
+                    (event.allDay && filter.startsFromDate !== undefined
+                        ? has(event, (one) => one.startDate !== null && one.startDate >= (filter.startsFromDate ?? ""))
+                        : event.startsAt !== null && event.startsAt >= filter.startsFrom)) &&
                 (filter.calendarId === undefined || has(event, (one) => one.calendarId === filter.calendarId)) &&
                 (filter.accountId === undefined ||
                     has(event, (one) => calendarOf(one.calendarId).accountId === filter.accountId)) &&

package/dist/cli/envelope.d.ts

@@ -1,5 +1,5 @@
 import { type Renderer, type RenderFormat, type Streams } from "@wirecat/cli-base";
-import { type ItemEnvelope, type ListEnvelope, type Meta, type Missing, type NextStep, type StepInput } from "@wirecat/cli-base/standards";
+import { type ItemEnvelope, type ListEnvelope, type Meta, type Missing, type NextStep, type StepInput, type Total } from "@wirecat/cli-base/standards";
 import type { Command } from "commander";
 import * as v from "valibot";
 export type ListBody<T> = Omit<ListEnvelope<T>, "meta"> & {
@@ -19,6 +19,8 @@ export interface ListInput<T> {
     paging?: "cursor";
     /** The page shown, from 1, for a list paged by `--page`. */
     page?: number;
+    /** How many match, every page together, for a search that counts them. */
+    total?: Total;
     /** The command's own arguments and query, so `page.next` reruns the same list. */
     args?: Record<string, unknown>;
     next?: NextStep[];
@@ -33,11 +35,19 @@ export declare const answerSchema: (item?: v.GenericSchema) => v.UnionSchema<[v.
         readonly limit: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>;
         readonly has_more: v.BooleanSchema<undefined>;
         readonly next_page: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 2, undefined>]>, undefined>;
+        readonly total: v.OptionalSchema<v.StrictObjectSchema<{
+            readonly value: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+            readonly relation: v.PicklistSchema<["eq", "gte"], undefined>;
+        }, undefined>, undefined>;
     }, undefined>, v.StrictObjectSchema<{
         readonly mode: v.LiteralSchema<"cursor", undefined>;
         readonly limit: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>;
         readonly has_more: v.BooleanSchema<undefined>;
         readonly next_cursor: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>;
+        readonly total: v.OptionalSchema<v.StrictObjectSchema<{
+            readonly value: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+            readonly relation: v.PicklistSchema<["eq", "gte"], undefined>;
+        }, undefined>, undefined>;
     }, undefined>], undefined>;
     readonly next: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.VariantSchema<"kind", [v.StrictObjectSchema<{
         readonly kind: v.LiteralSchema<"command", undefined>;

package/dist/cli/envelope.js

@@ -14,7 +14,7 @@ const capped = (steps) => (steps.length > 0 ? { next: steps.slice(0, MAX_NEXT_ST
  * page where the source has no cursor.
  */
 export const listOf = (command, input) => {
-    const { items, limit, has_more, cursor, paging, page, args = {}, next = [], missing, meta } = input;
+    const { items, limit, has_more, cursor, paging, page, total, args = {}, next = [], missing, meta } = input;
     const byCursor = paging === "cursor" || cursor !== undefined;
     const more = has_more
         ? [
@@ -28,8 +28,20 @@ export const listOf = (command, input) => {
     const body = {
         items,
         page: byCursor
-            ? { mode: "cursor", limit, has_more, ...(has_more && cursor !== undefined ? { next_cursor: cursor } : {}) }
-            : { mode: "page", limit, has_more, ...(has_more ? { next_page: (page ?? 1) + 1 } : {}) },
+            ? {
+                mode: "cursor",
+                limit,
+                has_more,
+                ...(has_more && cursor !== undefined ? { next_cursor: cursor } : {}),
+                ...(total ? { total } : {}),
+            }
+            : {
+                mode: "page",
+                limit,
+                has_more,
+                ...(has_more ? { next_page: (page ?? 1) + 1 } : {}),
+                ...(total ? { total } : {}),
+            },
         ...capped([...more, ...next]),
         ...(missing && missing.length > 0 ? { missing } : {}),
         ...(meta ? { meta } : {}),

package/dist/cli/index.d.ts

@@ -77,7 +77,7 @@ export { type FirstScreen, type FirstScreenLine, firstScreen, installHelp, WIREC
 export { type HelpSection, inSection, SECTIONS } from "./help/sections.js";
 export { bufferedInput, type InputPolicy, inputPolicy, MAX_BUFFERED_INPUT, MAX_SECRET_INPUT, provideInputPolicy, } from "./input-policy.js";
 export { answerFields, checkJson, type EntityFields, entityFields, type JsonFieldsResolver, type JsonRequest, liftJson, } from "./json-fields.js";
-export { commandPath, LIST_QUERY_GUIDE, listQuery, nativeField, nativeTerms, pagedList, pageOf, type QueryWords, queryArgument, queryHelp, queryTerms, searchText, termField, timeBounds, typedQuery, unfilteredQuery, withQuery, } from "./list-query.js";
+export { commandPath, LIST_QUERY_GUIDE, listQuery, nativeField, nativeTermLists, nativeTerms, pagedList, pageOf, type QueryWords, queryArgument, queryHelp, queryTerms, searchText, termField, timeBounds, typedQuery, unfilteredQuery, withQuery, } from "./list-query.js";
 export { MCP_HTTP_DEFAULT_PORT, type McpServerOptions, type McpServerTarget, mcpServerCommand, } from "./mcp-server-command.js";
 export { formatMeetingBatch, prepareMeetingBatch } from "./meeting-batch.js";
 export { meetingEvidenceItem, meetingPersonContextItem } from "./meeting-evidence-answer.js";
@@ -96,7 +96,7 @@ export { httpTokenFile, type McpEnvironment, type McpHost, serverEntry } from ".
 export { type MessageItem, messageItem, type ReadMessage } from "./messenger/message-items.js";
 export { type ModeProblem, type PrivateFiles, privateFiles, withSqliteSidecars } from "./messenger/private-files.js";
 export { buildReport as buildDoctorReport, type Report as DoctorReport, type ReportContext as DoctorReportContext, reportFileName as doctorReportFileName, } from "./messenger/report.js";
-export { allAnswer, allHitItem, coverageGaps, type HitItem, type MessageHitItem, messageHitItem, type NoteHitItem, noteHitItem, } from "./messenger/search-answers.js";
+export { allAnswer, allHitItem, coverageGaps, type HitItem, type MessageHitItem, messageHitItem, type NoteHitItem, noteHitItem, shownOf, } from "./messenger/search-answers.js";
 export { SEARCHES_QUERY } from "./messenger/searches-command.js";
 export { servingProfiles } from "./messenger/serve-command.js";
 export { DAY_MS, FIRST_FETCH_MS, type MemberFetches, memberFetches } from "./messenger/serve-members.js";

package/dist/cli/index.js

@@ -69,7 +69,7 @@ export { firstScreen, installHelp, WIRECAT_TOOLS } from "./help/first-screen.js"
 export { inSection, SECTIONS } from "./help/sections.js";
 export { bufferedInput, inputPolicy, MAX_BUFFERED_INPUT, MAX_SECRET_INPUT, provideInputPolicy, } from "./input-policy.js";
 export { answerFields, checkJson, entityFields, liftJson, } from "./json-fields.js";
-export { commandPath, LIST_QUERY_GUIDE, listQuery, nativeField, nativeTerms, pagedList, pageOf, queryArgument, queryHelp, queryTerms, searchText, termField, timeBounds, typedQuery, unfilteredQuery, withQuery, } from "./list-query.js";
+export { commandPath, LIST_QUERY_GUIDE, listQuery, nativeField, nativeTermLists, nativeTerms, pagedList, pageOf, queryArgument, queryHelp, queryTerms, searchText, termField, timeBounds, typedQuery, unfilteredQuery, withQuery, } from "./list-query.js";
 export { MCP_HTTP_DEFAULT_PORT, mcpServerCommand, } from "./mcp-server-command.js";
 export { formatMeetingBatch, prepareMeetingBatch } from "./meeting-batch.js";
 export { meetingEvidenceItem, meetingPersonContextItem } from "./meeting-evidence-answer.js";
@@ -87,7 +87,7 @@ export { httpTokenFile, serverEntry } from "./messenger/mcp-command.js";
 export { messageItem } from "./messenger/message-items.js";
 export { privateFiles, withSqliteSidecars } from "./messenger/private-files.js";
 export { buildReport as buildDoctorReport, reportFileName as doctorReportFileName, } from "./messenger/report.js";
-export { allAnswer, allHitItem, coverageGaps, messageHitItem, noteHitItem, } from "./messenger/search-answers.js";
+export { allAnswer, allHitItem, coverageGaps, messageHitItem, noteHitItem, shownOf, } from "./messenger/search-answers.js";
 export { SEARCHES_QUERY } from "./messenger/searches-command.js";
 export { servingProfiles } from "./messenger/serve-command.js";
 export { DAY_MS, FIRST_FETCH_MS, memberFetches } from "./messenger/serve-members.js";

package/dist/cli/list-query.d.ts

@@ -39,6 +39,11 @@ export declare const queryArgument: (registry: QueryRegistry) => v.OptionalSchem
  * question the source cannot ask, so it is refused rather than answered from a part of the list.
  */
 export declare const nativeTerms: (ast: QueryAst | undefined, command: string) => Map<string, Predicate>;
+/**
+ * As `nativeTerms`, but each `repeatable` field may be named again, every term kept in order: `person:a person:b`
+ * asks for both, as AND reads.
+ */
+export declare const nativeTermLists: (ast: QueryAst | undefined, command: string, repeatable?: readonly string[]) => Map<string, Predicate[]>;
 /**
  * A store that compares whole values: each field's `field:value` or `field:"two words"`, enum values lowercased
  * as validation already accepts them. A range or wildcard is refused rather than read as a value.

package/dist/cli/list-query.js

@@ -91,7 +91,12 @@ export const queryArgument = (registry) => {
  * The terms of a query a provider answers: field:value joined by AND, each field once. Anything else is a
  * question the source cannot ask, so it is refused rather than answered from a part of the list.
  */
-export const nativeTerms = (ast, command) => {
+export const nativeTerms = (ast, command) => new Map([...nativeTermLists(ast, command)].map(([field, [node]]) => [field, node]));
+/**
+ * As `nativeTerms`, but each `repeatable` field may be named again, every term kept in order: `person:a person:b`
+ * asks for both, as AND reads.
+ */
+export const nativeTermLists = (ast, command, repeatable = []) => {
     const terms = new Map();
     if (!ast)
         return terms;
@@ -106,9 +111,10 @@ export const nativeTerms = (ast, command) => {
             }
             return;
         }
-        if (terms.has(node.field))
+        const held = terms.get(node.field);
+        if (held && !repeatable.includes(node.field))
             queryError("query.unsupported-placement", node.span, `${node.field} only once here`, context);
-        terms.set(node.field, node);
+        terms.set(node.field, [...(held ?? []), node]);
     };
     add(ast.root);
     return terms;

package/dist/cli/meeting-preparation-answer.d.ts

@@ -345,11 +345,19 @@ export declare const meetingPreparationAnswer: (packet: MeetingPreparation) => i
                 limit: number;
                 has_more: boolean;
                 next_page?: number | undefined;
+                total?: {
+                    value: number;
+                    relation: "eq" | "gte";
+                } | undefined;
             } | {
                 mode: "cursor";
                 limit: number;
                 has_more: boolean;
                 next_cursor?: string | undefined;
+                total?: {
+                    value: number;
+                    relation: "eq" | "gte";
+                } | undefined;
             };
             coverage: {
                 archive_completeness: "unknown";

package/dist/cli/meeting-preparation-projects.d.ts

@@ -65,11 +65,19 @@ export declare const mapPreparationProjectEvidence: (section: NonNullable<Meetin
             limit: number;
             has_more: boolean;
             next_page?: number | undefined;
+            total?: {
+                value: number;
+                relation: "eq" | "gte";
+            } | undefined;
         } | {
             mode: "cursor";
             limit: number;
             has_more: boolean;
             next_cursor?: string | undefined;
+            total?: {
+                value: number;
+                relation: "eq" | "gte";
+            } | undefined;
         };
         coverage: {
             archive_completeness: "unknown";

package/dist/cli/meeting-preparation-read.d.ts

@@ -374,11 +374,19 @@ export declare const readMeetingPreparation: (read: MeetingPreparationReader, in
                 limit: number;
                 has_more: boolean;
                 next_page?: number | undefined;
+                total?: {
+                    value: number;
+                    relation: "eq" | "gte";
+                } | undefined;
             } | {
                 mode: "cursor";
                 limit: number;
                 has_more: boolean;
                 next_cursor?: string | undefined;
+                total?: {
+                    value: number;
+                    relation: "eq" | "gte";
+                } | undefined;
             };
             coverage: {
                 archive_completeness: "unknown";

package/dist/cli/meeting-series-inventory-read.d.ts

@@ -34,11 +34,19 @@ export declare const readMeetingSeriesInventory: (read: MeetingSeriesInventoryRe
         limit: number;
         has_more: boolean;
         next_page?: number | undefined;
+        total?: {
+            value: number;
+            relation: "eq" | "gte";
+        } | undefined;
     } | {
         mode: "cursor";
         limit: number;
         has_more: boolean;
         next_cursor?: string | undefined;
+        total?: {
+            value: number;
+            relation: "eq" | "gte";
+        } | undefined;
     };
     fingerprint: string;
     limits: {

package/dist/cli/messenger/messages-search-command.js

@@ -12,7 +12,7 @@ import { renderAnswer } from "../envelope.js";
 import { positiveCount } from "../paging.js";
 import { archiveSummary } from "./archive-summary.js";
 import { messengerContext } from "./context.js";
-import { meaningNote, messagesAnswer, offsetOf } from "./search-answers.js";
+import { meaningNote, messagesAnswer, offsetOf, shownOf } from "./search-answers.js";
 import { backendOptions, backendRequest, noteServer } from "./search-backend-options.js";
 import { syncOptions, syncRequest, syncsFirst } from "./search-sync-options.js";
 import { threadOptions, threadRequest } from "./thread-options.js";
@@ -184,6 +184,9 @@ const searchAction = (messenger) => async function (given) {
         if (elsewhere.length > 0) {
             context.renderer.note(`hits in ${elsewhere.join(", ")} open in that messenger's own CLI, by the locator: messages context msg:…`);
         }
+        const shown = shownOf(found.items.length, offsetOf(page, limit) ?? 0, found.total);
+        if (shown)
+            context.renderer.note(shown);
         if (found.items.length === 0)
             context.renderer.note(found.server && !found.server.skipped
                 ? "nothing found in the local store or on the messenger's server"

package/dist/cli/messenger/search-answers.d.ts

@@ -1,6 +1,7 @@
 import type { Missing, NextStep } from "@wirecat/cli-base/standards";
 import type { InferOutput } from "valibot";
 import type { ENTITIES } from "../../entities/index.js";
+import type { SearchTotal } from "../../search/total.js";
 import type { ChatCoverage } from "../../services/chat-coverage.js";
 import type { FoundMessage, SearchFound } from "../../services/messages.js";
 import type { MeaningSkipped } from "../../services/messages-discovery.js";
@@ -33,6 +34,8 @@ export interface Paging {
     /** The query and options `page.next` repeats. */
     again?: Record<string, unknown>;
 }
+/** "showing 20 of 144", for the human view under a page of hits; `+` when the total is a lower bound. */
+export declare const shownOf: (shown: number, offset: number, total: SearchTotal | undefined) => string | undefined;
 /** `search messages` and `search mail`, CLI and MCP alike. */
 export declare const messagesAnswer: (command: string, found: SearchFound, { limit, page, again }: Paging, query?: string) => ListBody<MessageHitItem>;
 export declare const noteHitItem: (hit: FoundNote) => NoteHitItem;

package/dist/cli/messenger/search-answers.js

@@ -227,6 +227,10 @@ const pictureItems = (found) => {
         untrusted: ["sender_name"],
     }));
 };
+/** "showing 20 of 144", for the human view under a page of hits; `+` when the total is a lower bound. */
+export const shownOf = (shown, offset, total) => total === undefined || shown === 0
+    ? undefined
+    : `showing ${offset + 1}–${offset + shown} of ${total.value}${total.relation === "gte" ? "+" : ""}`;
 /** `search messages` and `search mail`, CLI and MCP alike. */
 export const messagesAnswer = (command, found, { limit, page, again }, query = "") => {
     const accounts = found.coverage?.accounts ?? found.accounts ?? [];
@@ -235,6 +239,7 @@ export const messagesAnswer = (command, found, { limit, page, again }, query = "
         limit,
         has_more: found.hasMore && (page ?? 1) * limit <= MAX_SEARCH_OFFSET,
         page: page ?? 1,
+        ...(found.total ? { total: found.total } : {}),
         ...(again ? { args: again } : {}),
         ...gapsOf(found),
         meta: metaOf(accounts, found.skipped, coverageGaps(found).missing.length > 0),
@@ -297,6 +302,7 @@ export const notesAnswer = (command, found, { limit, page, again }, exact = fals
     limit,
     has_more: found.has_more && found.next_offset !== undefined,
     page: page ?? 1,
+    total: found.total,
     ...(again ? { args: again } : {}),
     ...meaningGap(found.meaning_skipped, exact),
     meta: metaOf(found.accounts, found.skipped),

package/dist/cli/messenger/search-command.js

@@ -11,7 +11,7 @@ import { commandAt } from "../steps.js";
 import { messengerContext } from "./context.js";
 import { conversationsSearchCommand } from "./conversations-command.js";
 import { messagesSearchCommand } from "./messages-search-command.js";
-import { allAnswer, meaningNote, notesAnswer, offsetOf, SOURCE_SEARCHED, } from "./search-answers.js";
+import { allAnswer, meaningNote, notesAnswer, offsetOf, SOURCE_SEARCHED, shownOf, } from "./search-answers.js";
 import { backendOptions, backendRequest, noteServer } from "./search-backend-options.js";
 import { topicsSearchCommand } from "./topics-command.js";
 const onlyOf = (value) => {
@@ -150,6 +150,9 @@ const notesCommand = (messenger) => annotate(new Command("notes"), { effects: LO
     renderAnswer(this, context, notesAnswer("search notes", found, { limit, page: options.page ?? 1, again }), () => {
         if (found.hits.length === 0)
             context.renderer.note("no note matches");
+        const shown = shownOf(found.hits.length, ((options.page ?? 1) - 1) * limit, found.total);
+        if (shown)
+            context.renderer.note(shown);
         return found.hits
             .map((hit) => `${singleLine(hit.title ?? hit.path ?? hit.ref)}  ${hit.ref}  (${hit.found_by.join(", ")})${hit.url ? `\n  ${singleLine(hit.url)}` : ""}\n  ${singleLine(hit.excerpt)}\n`)
             .join("");

package/dist/entities/index.d.ts

@@ -5529,11 +5529,19 @@ export declare const ENTITIES: {
             readonly limit: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>;
             readonly has_more: v.BooleanSchema<undefined>;
             readonly next_page: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 2, undefined>]>, undefined>;
+            readonly total: v.OptionalSchema<v.StrictObjectSchema<{
+                readonly value: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+                readonly relation: v.PicklistSchema<["eq", "gte"], undefined>;
+            }, undefined>, undefined>;
         }, undefined>, v.StrictObjectSchema<{
             readonly mode: v.LiteralSchema<"cursor", undefined>;
             readonly limit: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>;
             readonly has_more: v.BooleanSchema<undefined>;
             readonly next_cursor: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>;
+            readonly total: v.OptionalSchema<v.StrictObjectSchema<{
+                readonly value: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+                readonly relation: v.PicklistSchema<["eq", "gte"], undefined>;
+            }, undefined>, undefined>;
         }, undefined>], undefined>;
         readonly fingerprint: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
         readonly limits: v.StrictObjectSchema<{
@@ -5689,11 +5697,19 @@ export declare const ENTITIES: {
             readonly limit: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>;
             readonly has_more: v.BooleanSchema<undefined>;
             readonly next_page: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 2, undefined>]>, undefined>;
+            readonly total: v.OptionalSchema<v.StrictObjectSchema<{
+                readonly value: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+                readonly relation: v.PicklistSchema<["eq", "gte"], undefined>;
+            }, undefined>, undefined>;
         }, undefined>, v.StrictObjectSchema<{
             readonly mode: v.LiteralSchema<"cursor", undefined>;
             readonly limit: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>;
             readonly has_more: v.BooleanSchema<undefined>;
             readonly next_cursor: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>;
+            readonly total: v.OptionalSchema<v.StrictObjectSchema<{
+                readonly value: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+                readonly relation: v.PicklistSchema<["eq", "gte"], undefined>;
+            }, undefined>, undefined>;
         }, undefined>], undefined>;
         readonly coverage: v.StrictObjectSchema<{
             readonly archive_completeness: v.LiteralSchema<"unknown", undefined>;
@@ -6052,11 +6068,19 @@ export declare const ENTITIES: {
                     readonly limit: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>;
                     readonly has_more: v.BooleanSchema<undefined>;
                     readonly next_page: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 2, undefined>]>, undefined>;
+                    readonly total: v.OptionalSchema<v.StrictObjectSchema<{
+                        readonly value: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+                        readonly relation: v.PicklistSchema<["eq", "gte"], undefined>;
+                    }, undefined>, undefined>;
                 }, undefined>, v.StrictObjectSchema<{
                     readonly mode: v.LiteralSchema<"cursor", undefined>;
                     readonly limit: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>;
                     readonly has_more: v.BooleanSchema<undefined>;
                     readonly next_cursor: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>;
+                    readonly total: v.OptionalSchema<v.StrictObjectSchema<{
+                        readonly value: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+                        readonly relation: v.PicklistSchema<["eq", "gte"], undefined>;
+                    }, undefined>, undefined>;
                 }, undefined>], undefined>;
                 readonly coverage: v.StrictObjectSchema<{
                     readonly archive_completeness: v.LiteralSchema<"unknown", undefined>;

package/dist/entities/meeting-preparation.d.ts

@@ -345,11 +345,19 @@ export declare const meetingPreparation: v.StrictObjectSchema<{
                 readonly limit: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>;
                 readonly has_more: v.BooleanSchema<undefined>;
                 readonly next_page: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 2, undefined>]>, undefined>;
+                readonly total: v.OptionalSchema<v.StrictObjectSchema<{
+                    readonly value: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+                    readonly relation: v.PicklistSchema<["eq", "gte"], undefined>;
+                }, undefined>, undefined>;
             }, undefined>, v.StrictObjectSchema<{
                 readonly mode: v.LiteralSchema<"cursor", undefined>;
                 readonly limit: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>;
                 readonly has_more: v.BooleanSchema<undefined>;
                 readonly next_cursor: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>;
+                readonly total: v.OptionalSchema<v.StrictObjectSchema<{
+                    readonly value: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+                    readonly relation: v.PicklistSchema<["eq", "gte"], undefined>;
+                }, undefined>, undefined>;
             }, undefined>], undefined>;
             readonly coverage: v.StrictObjectSchema<{
                 readonly archive_completeness: v.LiteralSchema<"unknown", undefined>;

package/dist/entities/meeting-series-inventory.d.ts

@@ -19,11 +19,19 @@ export declare const meetingSeriesInventory: v.StrictObjectSchema<{
         readonly limit: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>;
         readonly has_more: v.BooleanSchema<undefined>;
         readonly next_page: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 2, undefined>]>, undefined>;
+        readonly total: v.OptionalSchema<v.StrictObjectSchema<{
+            readonly value: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+            readonly relation: v.PicklistSchema<["eq", "gte"], undefined>;
+        }, undefined>, undefined>;
     }, undefined>, v.StrictObjectSchema<{
         readonly mode: v.LiteralSchema<"cursor", undefined>;
         readonly limit: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>;
         readonly has_more: v.BooleanSchema<undefined>;
         readonly next_cursor: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>;
+        readonly total: v.OptionalSchema<v.StrictObjectSchema<{
+            readonly value: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+            readonly relation: v.PicklistSchema<["eq", "gte"], undefined>;
+        }, undefined>, undefined>;
     }, undefined>], undefined>;
     readonly fingerprint: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
     readonly limits: v.StrictObjectSchema<{

package/dist/mcp/meeting-preparation.d.ts

@@ -412,11 +412,19 @@ export declare const callMeetingPreparationTool: (read: MeetingPreparationReader
                     limit: number;
                     has_more: boolean;
                     next_page?: number | undefined;
+                    total?: {
+                        value: number;
+                        relation: "eq" | "gte";
+                    } | undefined;
                 } | {
                     mode: "cursor";
                     limit: number;
                     has_more: boolean;
                     next_cursor?: string | undefined;
+                    total?: {
+                        value: number;
+                        relation: "eq" | "gte";
+                    } | undefined;
                 };
                 coverage: {
                     archive_completeness: "unknown";