@wirecat/cli-core 0.500.0 → 0.502.0

package/CHANGELOG.md

@@ -5,7 +5,59 @@ Notable changes to `@wirecat/cli-core` (`@wirecat/cli-messaging` up to 0.261.0,
 minor version may break callers, and says how under "Changed — may break callers". `pnpm docs:check` checks the
 shape of this file.
 
-## Unreleased
+## 0.502.0 — 31.10.2026
+
+### Added
+
+- **The event store finds events by their earliest start: `EventFilter.startsFrom`.** It keeps events that start at
+  or after an instant, and `startsFromDate` keeps all-day events by their local date, as `toDate` does (WC-TIME-5).
+  Both stores (SQLite and `memoryEventStore`) answer it, and the event store contract checks the boundary.
+- **`nativeTermLists`** from `@wirecat/cli-core/cli`: as `nativeTerms`, but named fields may repeat
+  (`person:a person:b`), every term kept.
+
+### Changed — may break callers
+
+- **The shared calendar commands take the standard query and the paths the other tools use.** A CLI that mounts
+  `addCalendarCommands` (gcal) gets:
+  - `store status` in place of `status`, and `search events <query…>` in place of `search <words…>`; the permission
+    keys are `store.status` and `search.events`, and the sync's hint names `store status`.
+  - `events list [query…]` (`EVENTS_QUERY`): `starts_at` either way, now including `starts_at>=…` and
+    `starts_at:[a TO b}`, `ends_at>=…`, `changed_at>=…`, `calendar:` and `person:`. The words `today`, `week`,
+    `from:`, `to:`, `changed:` and `overlapping` are refused as query errors.
+  - `calendars busy [query…]` (`BUSY_QUERY`): the window as `start>=…` and `end<=…`, and `calendar:` and `person:`,
+    each repeatable. `today`, `week`, `from:` and `to:` are refused.
+  - `eventsFilter(query, …)` takes the query text in place of words, and `busyQuery(query, …)` as well;
+    `EVENTS_QUERY_HELP` and `BUSY_QUERY_HELP` are gone (`EVENTS_QUERY_NOTE`, `BUSY_QUERY_NOTE`), and `weekFilter`
+    builds `people list`'s week.
+  - `calendarTools`: `status` is `store_status`, and `events_list` takes `query` in place of `words`.
+
+## 0.501.0 — 31.10.2026
+
+### Added
+
+- **Search answers say how many match in all: `page.total`.** `search notes` and `search messages` add
+  `page.total: { value, relation }` to `--json`, and `NotesFound.total` / `SearchFound.total` carry it to a tool that
+  builds its own answer (drive prints it as `item.total`; memo's notes, messages and mail pass it on with their next
+  release). It is shaped as Elasticsearch's `hits.total`: `relation` is `eq` for an exact count and `gte` for a lower bound. The terminal adds a line such as
+  `showing 1–20 of 144` (`144+` for a lower bound). Notes count every note the words find plus every note found by
+  meaning; messages count the strict query's matches, or discovery's candidates with `--discover`. Counting stops at
+  10,000 (`TOTAL_CAP`, Elasticsearch's default), and a query whose leaves are checked row by row (a preset, a
+  pattern) gets the lower bound the page proves. New: `SearchTotal`, `NotesFound.total`, `SearchFound.total`,
+  `NoteSearch.matchingRefs` (refs only, no note read), `NoteSearch.scoreNotes` and `QueriesStore.countMatches`;
+  `listOf` takes `total`, and `shownOf(shown, offset, total)` from `@wirecat/cli-core/cli` writes the terminal line.
+
+### Changed — may break callers
+
+- **cli-core needs `@wirecat/cli-base` 0.67.** The peer range moves from `>=0.65.0 <0.66.0` to `>=0.67.0 <0.68.0`. A
+  CLI that pins cli-base moves its pin with this release. cli-base 0.67 adds `page.total` to the list envelope.
+
+### Fixed
+
+- **Search by meaning inside a filter ranks the filter's own notes.** With a filter that holds at most 2,000 notes
+  (`RANK_WITHIN`), `search notes` scores every one of them by meaning, instead of taking the 50 nearest notes overall
+  and dropping those outside the filter. On the owner's store, Drive's `budget date>=30d` went from 7 hits to a full
+  page of 20, and 50 of the 144 documents in the date range match in all; no hit falls outside the filter, as
+  before. A larger filter keeps the old way, as does one the store cannot list cheaply.
 
 ## 0.500.0 — 31.10.2026
 

package/dist/calendar/busy.d.ts

@@ -1,12 +1,19 @@
+import { type QueryRegistry } from "@wirecat/cli-base/query";
+import { type QueryWords } from "../cli/list-query.js";
 import type { EventStore, StoredCalendar } from "../meetings/index.js";
 import type { CalendarSource, SyncWindow } from "./source.js";
-export declare const BUSY_QUERY_HELP = "\nWords, any order:\n  today | week            today, or today and the next six days, in your time zone\n  from:<date> to:<date>   from the start of one day through the end of another (or a time with a zone)\n  calendar:<id>           one of the account's calendars, by its id or the provider's id; repeat for more\n  person:<email>          someone else, by email address; repeat for more\nWithout a time word: this week. Without calendar:, every calendar that syncs.";
 export interface BusyQuery {
     window: SyncWindow;
     calendars: StoredCalendar[];
     people: string[];
 }
-export declare const busyQuery: (words: readonly string[], context: {
+/**
+ * `calendars busy`'s query: the window by the answer's own `start` and `end`, and whom to ask. `calendar` and
+ * `person` repeat, and every one named is asked: the free stretches are those they all share.
+ */
+export declare const BUSY_QUERY: QueryRegistry;
+export declare const BUSY_QUERY_NOTE: string;
+export declare const busyQuery: (query: QueryWords, context: {
     store: EventStore;
     accountId: number;
     zone: string;

package/dist/calendar/busy.js

@@ -1,13 +1,8 @@
 import { CliError } from "@wirecat/cli-base";
-import { dayBoundary, zonedMoment } from "@wirecat/cli-base/query";
-import { calendarIn, plusDays } from "./reads.js";
-export const BUSY_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)
-  calendar:<id>           one of the account's calendars, by its id or the provider's id; repeat for more
-  person:<email>          someone else, by email address; repeat for more
-Without a time word: this week. Without calendar:, every calendar that syncs.`;
+import { dayBoundary, queryError, queryFieldsOf, zonedMoment, } from "@wirecat/cli-base/query";
+import { LIST_QUERY_GUIDE, listQuery, nativeTermLists, typedQuery } from "../cli/list-query.js";
+import { calendarBusy } from "./cli/answers.js";
+import { calendarIn, plusDays, timeWindow } from "./reads.js";
 /** Google answers for 50 calendars at most (`calendarExpansionMax`, reference/freebusy/query). */
 const MOST = 50;
 const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/u;
@@ -15,41 +10,68 @@ const HOURS = /^([01]\d|2[0-3]):([0-5]\d)-([01]\d|2[0-4]):([0-5]\d)$/u;
 const MINUTE = 60_000;
 const localDate = (at, zone) => new Intl.DateTimeFormat("en-CA", { timeZone: zone, year: "numeric", month: "2-digit", day: "2-digit" }).format(at);
 const span = (text) => ({ start: 0, end: text.length });
-export const busyQuery = async (words, context) => {
-    const today = localDate(context.now, context.zone);
-    const day = (date) => dayBoundary(date, context.zone, false, span(date));
+const BUSY = "calendars busy";
+const bound = (field, side, example) => (node) => {
+    const open = node.operator === "range" && (side === "lower" ? node.upper === "*" : node.value === "*");
+    if (!open)
+        queryError("query.unsupported-operator", node.span, `${field} takes only ${side === "lower" ? "the window's start" : "the window's end"}, such as ${example}`, { command: BUSY, guide: LIST_QUERY_GUIDE });
+};
+/**
+ * `calendars busy`'s query: the window by the answer's own `start` and `end`, and whom to ask. `calendar` and
+ * `person` repeat, and every one named is asked: the free stretches are those they all share.
+ */
+export const BUSY_QUERY = {
+    entity: "calendar_busy",
+    backend: "native",
+    fields: queryFieldsOf(calendarBusy, {
+        native: ["start", "end", "calendar", "person"],
+        relations: {
+            calendar: {
+                type: "kw",
+                example: "calendar:3",
+                relation: "one of the account's calendars, by its id or the provider's id; repeat for more",
+            },
+            person: { type: "kw", example: "person:ana@example.com", relation: "someone else, by address; repeat for more" },
+        },
+        examples: { start: "start>=2026-11-02", end: "end<=2026-11-06" },
+        validate: {
+            start: bound("start", "lower", "start>=2026-11-02"),
+            end: bound("end", "upper", "end<=2026-11-06"),
+        },
+    }).map((field) => field.native
+        ? { ...field, operators: field.type === "time" ? ["range"] : ["term", "phrase"] }
+        : field),
+};
+export const BUSY_QUERY_NOTE = "\nWithout start: from the start of today, in your time zone. Without end: seven days after the start. " +
+    "Without calendar: every calendar that syncs.";
+export const busyQuery = async (query, context) => {
+    const { zone, now } = context;
+    const today = localDate(now, zone);
     let from;
     let to;
     const calendars = [];
     const people = new Set();
-    for (const word of words) {
-        const [, field, value = ""] = /^([a-z]+):(.+)$/u.exec(word) ?? [];
-        if (word === "today" || word === "week") {
-            from = day(today);
-            to = day(plusDays(today, word === "today" ? 1 : 7));
-        }
-        else if (field === "from")
-            from = zonedMoment(value, context.zone, span(value));
-        else if (field === "to")
-            to = zonedMoment(value, context.zone, span(value), { end: true }) + 1;
-        else if (field === "calendar") {
-            const calendar = await calendarIn(context.store, context.accountId, value);
-            if (!calendars.some(({ id }) => id === calendar.id))
-                calendars.push(calendar);
-        }
-        else if (field === "person") {
-            const email = value.trim().toLowerCase();
-            if (!EMAIL.test(email))
-                throw new CliError("validation_error", `${value} is not an email address`);
-            people.add(email);
+    const terms = nativeTermLists(listQuery(typedQuery(query), BUSY_QUERY, BUSY), BUSY, ["calendar", "person"]);
+    for (const [field, nodes] of terms)
+        for (const node of nodes) {
+            if (field === "start")
+                from = timeWindow(node, zone, now).lower;
+            else if (field === "end")
+                to = timeWindow(node, zone, now).upper;
+            else if (field === "calendar") {
+                const calendar = await calendarIn(context.store, context.accountId, node.value);
+                if (!calendars.some(({ id }) => id === calendar.id))
+                    calendars.push(calendar);
+            }
+            else if (field === "person") {
+                const email = node.value.trim().toLowerCase();
+                if (!EMAIL.test(email))
+                    throw new CliError("validation_error", `${node.value} is not an email address`);
+                people.add(email);
+            }
         }
-        else
-            throw new CliError("validation_error", `${word} is not a calendars busy word${BUSY_QUERY_HELP}`, {
-                reason: "query.unknown_word",
-            });
-    }
-    from ??= day(today);
-    to ??= from === day(today) ? day(plusDays(today, 7)) : from + 7 * 86_400_000;
+    from ??= dayBoundary(today, zone, false, span(today));
+    to ??= from + 7 * 86_400_000;
     if (to <= from)
         throw new CliError("validation_error", "the window ends before it starts");
     const asked = calendars.length

package/dist/calendar/cli/answers.js

@@ -192,7 +192,7 @@ const ANSWERS = {
     "calendars unsync": { name: "calendar", schema: calendar },
     "calendars busy": { name: "calendar_busy", schema: calendarBusy },
     sync: { name: "calendar_sync", schema: calendarSync },
-    status: { name: "calendar_sync_progress", schema: calendarSyncProgress },
+    "store status": { name: "calendar_sync_progress", schema: calendarSyncProgress },
     "events list": { name: "event" },
     "events show": { name: "calendar_event", schema: calendarEvent },
     "events create": { name: "calendar_event_write", schema: calendarEventWrite },
@@ -200,7 +200,7 @@ const ANSWERS = {
     "events delete": { name: "calendar_event_write", schema: calendarEventWrite },
     "events move": { name: "calendar_event_write", schema: calendarEventWrite },
     "events respond": { name: "calendar_event_write", schema: calendarEventWrite },
-    search: { name: "calendar_search_hit", schema: calendarSearchHit },
+    "search events": { name: "calendar_search_hit", schema: calendarSearchHit },
     "people list": { name: "calendar_attendee", schema: calendarAttendee },
     "people link": { name: "calendar_linked_person", schema: calendarLinkedPerson },
     "links review": { name: "calendar_link_review", schema: calendarLinkReview },

package/dist/calendar/cli/index.js

@@ -9,8 +9,8 @@ import { terminalAsker } from "../../cli/messenger/ask.js";
 import { lineOf } from "../../cli/steps.js";
 import { searchEvents } from "../../services/events-search.js";
 import { linkPeople } from "../../services/people.js";
-import { BUSY_QUERY_HELP, busyAnswer, busyQuery, workingHoursOf } from "../busy.js";
-import { CALENDAR_UNTRUSTED_FIELDS, calendarIn, calendarItem, EVENTS_QUERY_HELP, eventAnswer, eventIdOf, eventOf, eventsAnswer, eventsFilter, peopleAnswer, resolveAnswer, reviewsAnswer, } from "../reads.js";
+import { BUSY_QUERY, BUSY_QUERY_NOTE, busyAnswer, busyQuery, workingHoursOf } from "../busy.js";
+import { CALENDAR_UNTRUSTED_FIELDS, calendarIn, calendarItem, EVENTS_QUERY, EVENTS_QUERY_NOTE, eventAnswer, eventIdOf, eventOf, eventsAnswer, eventsFilter, peopleAnswer, resolveAnswer, reviewsAnswer, weekFilter, } from "../reads.js";
 import { REPEAT_HELP } from "../recurrence.js";
 import { serverSearchAnswer } from "../server-search.js";
 import { calendarStatus, syncCalendars } from "../sync.js";
@@ -99,11 +99,9 @@ const addCalendarCommandsDefinition = (program, deps) => {
             print(calendarItem({ ...calendar, synced }), command);
         });
     if (deps.freeBusy)
-        example(annotate(calendars.command("busy"), { effects: REMOTE_READ, offline: false })
-            .description("when calendars and people are taken, asked of the provider and not stored; with --duration-minutes, " +
-            "the free stretches they share")
-            .argument("[words...]", "today, week, from:<date>, to:<date>, calendar:<id>, person:<email>")
-            .addHelpText("after", BUSY_QUERY_HELP), "calendars busy week person:ana@example.com --json", "calendars busy from:2026-11-02 to:2026-11-06 person:ana@example.com --duration-minutes 30 --hours 10:00-16:00")
+        example(withQuery(annotate(calendars.command("busy"), { effects: REMOTE_READ, offline: false }).description("when calendars and people are taken, asked of the provider and not stored; with --duration-minutes, " +
+            "the free stretches they share"), BUSY_QUERY).addHelpText("after", BUSY_QUERY_NOTE), "calendars busy person:ana@example.com --json", "calendars busy start>=2026-11-02 end<=2026-11-06 person:ana@example.com --duration-minutes 30 " +
+            "--hours 10:00-16:00")
             .option("--duration-minutes <minutes>", "find free stretches at least this long, 5–1440", minutes)
             .option("--hours <from-to>", "working hours in your time zone, Monday to Friday, with --duration-minutes", "09:00-17:00")
             .action(async (words, opts, command) => {
@@ -162,7 +160,7 @@ const addCalendarCommandsDefinition = (program, deps) => {
                 },
             ]
             : undefined;
-        const progressAt = lineOf(command, "status");
+        const progressAt = lineOf(command, "store status");
         report.hint = stuck
             ? `this run moved nothing on: raise --timeout or --max-pages, then run sync again; see progress: ${progressAt}`
             : report.state === "partial"
@@ -193,17 +191,17 @@ const addCalendarCommandsDefinition = (program, deps) => {
             });
         print({ ...report, ...(embeddings === undefined ? {} : { embeddings }), ...(next ? { next } : {}) }, command);
     });
-    example(annotate(program.command("status"), { effects: LOCAL_READ }).description("how far each synced calendar's sync is: entries done, partial or complete, and when it last moved"), "status --json").action(async (_opts, command) => {
+    const store = annotate(program.command("store").description("the local store of calendar events"), {
+        effects: GROUP,
+    });
+    example(annotate(store.command("status"), { effects: LOCAL_READ }).description("how far each synced calendar's sync is: entries done, partial or complete, and when it last moved"), "store status --json").action(async (_opts, command) => {
         print(await calendarStatus(deps.store, deps.accountId, {
             profile: deps.profile ?? `account ${deps.accountId}`,
             now: now(),
         }), command);
     });
     const events = annotate(program.command("events").description("the account's stored events"), { effects: GROUP });
-    example(annotate(events.command("list"), { effects: LOCAL_READ })
-        .description("list stored events, earliest first")
-        .argument("[words...]", "today, week, from:<date>, to:<date>, person:<who>, calendar:<id>")
-        .addHelpText("after", EVENTS_QUERY_HELP), "events list week --json", "events list from:2026-11-02 to:2026-11-06 person:ana@example.com")
+    example(withQuery(annotate(events.command("list"), { effects: LOCAL_READ }).description("list stored events, earliest first"), EVENTS_QUERY).addHelpText("after", EVENTS_QUERY_NOTE), "events list starts_at>=2026-11-02 starts_at<2026-11-07 --json", "events list ends_at>=today person:ana@example.com")
         .option("--limit <n>", "events at most, 1–1000", integer, 100)
         .action(async (words, opts, command) => {
         const filter = await eventsFilter(words, {
@@ -221,12 +219,15 @@ const addCalendarCommandsDefinition = (program, deps) => {
         const shown = await eventAnswer(await eventOf(deps.store, deps.accountId, eventIdOf(reference)), personOfEmail);
         print({ ...shown, untrusted: CALENDAR_UNTRUSTED_FIELDS }, command);
     });
-    const search = example(annotate(program.command("search"), { effects: deps.serverSearch ? LOCAL_OR_REMOTE_READ : LOCAL_READ })
+    const searches = annotate(program.command("search").description("find stored things by text: events"), {
+        effects: GROUP,
+    });
+    const search = example(annotate(searches.command("events"), { effects: deps.serverSearch ? LOCAL_OR_REMOTE_READ : LOCAL_READ })
         .description(deps.serverSearch
         ? "find stored events by words, and by meaning when its model is downloaded; with --backend server, ask " +
             "the provider instead"
         : "find stored events by words, and by meaning when its model is downloaded")
-        .argument("<words...>", "what to find in titles, descriptions, places and attendees"), "search roadmap planning --json", ...(deps.serverSearch ? ["search --backend server quarterly review"] : []))
+        .argument("<query...>", "what to find in titles, descriptions, places and attendees"), "search events roadmap planning --json", ...(deps.serverSearch ? ["search events --backend server quarterly review"] : []))
         .option("--limit <n>", "events per page", integer, 20)
         .option("--cursor <cursor>", "continue from a page's next_offset", (text) => (text === "0" ? 0 : integer(text)), 0)
         .option("--exact", "every word as written, no word stems")
@@ -238,16 +239,16 @@ const addCalendarCommandsDefinition = (program, deps) => {
             .default("archive"));
     search.action(async (words, opts, command) => {
         if (opts.backend === "both")
-            throw new CliError("validation_error", "search --backend both is not offered: the store's search and the provider's rank and page events " +
+            throw new CliError("validation_error", "search events --backend both is not offered: the store's search and the provider's rank and page events " +
                 "differently, so one merged list would have no single order or next page; run --backend archive and " +
                 "--backend server", { reason: "search.one-backend" });
         if (opts.backend === "server") {
             if (command.optsWithGlobals().offline)
-                throw new CliError("permission_error", "search --backend server asks the provider; leave out --offline", {
+                throw new CliError("permission_error", "search events --backend server asks the provider; leave out --offline", {
                     reason: "search.offline",
                 });
             if (opts.exact || opts.cursor || opts.newest)
-                throw new CliError("validation_error", "search --backend server takes neither --exact, --cursor nor --newest: the provider ranks and pages it", { reason: "search.server-options" });
+                throw new CliError("validation_error", "search events --backend server takes neither --exact, --cursor nor --newest: the provider ranks and pages it", { reason: "search.server-options" });
             const found = await serverSearchAnswer(source(), deps.store, {
                 accountId: deps.accountId,
                 account: deps.account,
@@ -276,9 +277,7 @@ const addCalendarCommandsDefinition = (program, deps) => {
     withQuery(example(annotate(people.command("list"), { effects: LOCAL_READ }).description("one event's attendees, or everyone attending this week's events"), "people list --json", "people list event:42"), PEOPLE_QUERY).action(async (words, _opts, command) => {
         const reference = queryTerms(words, PEOPLE_QUERY, "people list").get("event");
         const event = reference === undefined ? undefined : eventIdOf(reference);
-        const filter = event === undefined
-            ? await eventsFilter(["week"], { store: deps.store, accountId: deps.accountId, zone: zone(), now: now() })
-            : undefined;
+        const filter = event === undefined ? weekFilter(deps.accountId, zone(), now()) : undefined;
         const people = await peopleAnswer(deps.store, deps.accountId, {
             ...(event === undefined ? {} : { event }),
             ...(filter ? { filter } : {}),

package/dist/calendar/mcp/index.d.ts

@@ -10,20 +10,20 @@ export declare const calendarTools: ({
     inputSchema: {
         type: string;
         properties: {
-            limit?: undefined;
             account_id: {
                 type: string;
                 minimum: number;
             };
-            words?: undefined;
+            query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             event?: undefined;
         } | {
             account_id: {
                 type: string;
                 minimum: number;
             };
-            words: {
+            query: {
                 type: string;
                 minLength: number;
             };
@@ -38,9 +38,9 @@ export declare const calendarTools: ({
             };
             event?: undefined;
         } | {
-            limit?: undefined;
-            words?: undefined;
+            query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             event: {
                 type: string;
                 minLength: number;
@@ -50,9 +50,9 @@ export declare const calendarTools: ({
                 minimum: number;
             };
         } | {
-            limit?: undefined;
-            words?: undefined;
+            query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             event?: undefined;
             account_id?: undefined;
         };
@@ -71,20 +71,20 @@ export declare const calendarTools: ({
     inputSchema: {
         type: string;
         properties: {
-            limit?: undefined;
             account_id: {
                 type: string;
                 minimum: number;
             };
-            words?: undefined;
+            query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             event?: undefined;
         } | {
             account_id: {
                 type: string;
                 minimum: number;
             };
-            words: {
+            query: {
                 type: string;
                 minLength: number;
             };
@@ -99,9 +99,9 @@ export declare const calendarTools: ({
             };
             event?: undefined;
         } | {
-            limit?: undefined;
-            words?: undefined;
+            query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             event: {
                 type: string;
                 minLength: number;
@@ -111,9 +111,9 @@ export declare const calendarTools: ({
                 minimum: number;
             };
         } | {
-            limit?: undefined;
-            words?: undefined;
+            query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             event?: undefined;
             account_id?: undefined;
         };
@@ -132,20 +132,20 @@ export declare const calendarTools: ({
     inputSchema: {
         type: string;
         properties: {
-            limit?: undefined;
             account_id: {
                 type: string;
                 minimum: number;
             };
-            words?: undefined;
+            query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             event?: undefined;
         } | {
             account_id: {
                 type: string;
                 minimum: number;
             };
-            words: {
+            query: {
                 type: string;
                 minLength: number;
             };
@@ -160,9 +160,9 @@ export declare const calendarTools: ({
             };
             event?: undefined;
         } | {
-            limit?: undefined;
-            words?: undefined;
+            query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             event: {
                 type: string;
                 minLength: number;
@@ -172,9 +172,9 @@ export declare const calendarTools: ({
                 minimum: number;
             };
         } | {
-            limit?: undefined;
-            words?: undefined;
+            query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             event?: undefined;
             account_id?: undefined;
         };
@@ -193,20 +193,20 @@ export declare const calendarTools: ({
     inputSchema: {
         type: string;
         properties: {
-            limit?: undefined;
             account_id: {
                 type: string;
                 minimum: number;
             };
-            words?: undefined;
+            query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             event?: undefined;
         } | {
             account_id: {
                 type: string;
                 minimum: number;
             };
-            words: {
+            query: {
                 type: string;
                 minLength: number;
             };
@@ -221,9 +221,9 @@ export declare const calendarTools: ({
             };
             event?: undefined;
         } | {
-            limit?: undefined;
-            words?: undefined;
+            query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             event: {
                 type: string;
                 minLength: number;
@@ -233,9 +233,9 @@ export declare const calendarTools: ({
                 minimum: number;
             };
         } | {
-            limit?: undefined;
-            words?: undefined;
+            query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             event?: undefined;
             account_id?: undefined;
         };

package/dist/calendar/mcp/index.js

@@ -19,7 +19,7 @@ export const calendarTools = [
         required: [],
     },
     {
-        name: "status",
+        name: "store_status",
         description: "how far each synced calendar's sync is: done, state partial or complete, and cursor_age_ms, which grows while " +
             "nothing moves it",
         properties: { account_id: integer },
@@ -27,10 +27,10 @@ export const calendarTools = [
     },
     {
         name: "events_list",
-        description: "stored events, earliest first; `words` takes today, week, from:<date>, to:<date>, calendar:<id>, " +
-            "changed:<date> (events new, moved or cancelled since, each with change and was) and overlapping (events " +
-            "that clash, each with overlaps); a date in the zone given, UTC when absent",
-        properties: { account_id: integer, words: text, timezone: text, limit: { ...integer, maximum: 1000 } },
+        description: "stored events, earliest first; `query` takes field terms joined by AND: starts_at (>=, <, or " +
+            "[a TO b}), ends_at>=, changed_at>= (events new, moved or cancelled since, each with change and was), " +
+            "calendar:<id>; a date in the zone given, UTC when absent; without starts_at or ends_at, from today on",
+        properties: { account_id: integer, query: text, timezone: text, limit: { ...integer, maximum: 1000 } },
         required: [],
     },
     {
@@ -163,7 +163,7 @@ const argumentsOf = (name, input) => {
             (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1))
             throw new CliError("validation_error", `${key} must be a positive integer`);
         else if ([
-            "words",
+            "query",
             "timezone",
             "event",
             "calendar",
@@ -225,13 +225,12 @@ export const callCalendarTool = async (store, name, input, { accountIds, failure
             case "calendars_list":
                 answer = listed((await Promise.all(accounts.map((id) => store.calendars(id)))).flat().map(calendarItem));
                 break;
-            case "status":
+            case "store_status":
                 answer = listed((await Promise.all(accounts.map((id) => calendarStatus(store, id, { profile: profileOf(id), now }).then(({ items }) => items)))).flat());
                 break;
             case "events_list": {
-                const words = typeof args.words === "string" ? args.words.trim().split(/\s+/u) : [];
                 const limit = args.limit ?? 100;
-                const lists = await Promise.all(accounts.map(async (accountId) => eventsAnswer(store, await eventsFilter(words, {
+                const lists = await Promise.all(accounts.map(async (accountId) => eventsAnswer(store, await eventsFilter(args.query, {
                     store,
                     accountId,
                     zone: args.timezone ?? "UTC",

package/dist/calendar/reads.d.ts

@@ -1,3 +1,5 @@
+import { type Predicate, type QueryRegistry } from "@wirecat/cli-base/query";
+import { type QueryWords } from "../cli/list-query.js";
 import { type EventDetails, type EventFilter, type EventStore, type StoredCalendar, type StoredEntry } from "../meetings/index.js";
 /** Who looks a person up: the shared store's `people.personOf`, for an attendee's `email` contact. */
 export type PersonOfEmail = (email: string) => Promise<string | null>;
@@ -17,18 +19,27 @@ export declare const calendarItem: (one: StoredCalendar) => {
 export declare const calendarIn: (store: EventStore, accountId: number, reference: string) => Promise<StoredCalendar>;
 export declare const eventIdOf: (reference: string | number) => number;
 export declare const plusDays: (date: string, days: number) => string;
-export declare const EVENTS_QUERY_HELP = "\nWords, any order:\n  today | week            today, or today and the next six days, in your time zone\n  from:<date> to:<date>   from the start of one day through the end of another (or a time with a zone)\n  person:<email|id>       events one person attends: an address, or a person id from search\n  calendar:<id>           one calendar, by its id or the provider's id\n  changed:<date>          events new, moved or cancelled since then, each with what changed (from the local copy)\n  overlapping             events that clash with another: timed, not cancelled, not declined, not marked free\nWithout a time word: events from the start of today on.";
+/** `events list`'s query. The store answers `ends_at` and `changed_at` from below only; `starts_at` either way. */
+export declare const EVENTS_QUERY: QueryRegistry;
+export declare const EVENTS_QUERY_NOTE: string;
+/** A time term as epoch ms: from `lower` on, and before `upper`. */
+export declare const timeWindow: (node: Predicate, zone: string, now: number) => {
+    lower?: number;
+    upper?: number;
+};
 /**
- * `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 declare const eventsFilter: (words: readonly string[], context: {
+export declare const eventsFilter: (query: QueryWords, context: {
     store: EventStore;
     accountId: number;
     zone: string;
     now: number;
     personOf?: (reference: string) => Promise<number | null>;
 }) => Promise<EventFilter | null>;
+/** Events that end after the start of today and start within seven days, in `zone`. */
+export declare const weekFilter: (accountId: number, zone: string, now: number) => EventFilter;
 /** An event the account holds, with only its copies, or `not_found`: another account's event is not shown. */
 export declare const eventOf: (store: EventStore, accountId: number, id: number) => Promise<EventDetails>;
 export declare const entryItem: (entry: StoredEntry) => {