@agent-native/core 0.159.2 → 0.159.5

package/corpus/README.md

@@ -31,4 +31,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- template files: 8257
+- template files: 8263

package/corpus/templates/clips/.agents/skills/meetings/SKILL.md

@@ -25,9 +25,9 @@ For press-and-hold dictations (Hold-Fn / Cmd+Shift+Space) and the `/dictate` tab
 
 ## Design reference
 
-The Meetings tab intentionally mirrors **Granola**: card grid grouped by day, two-pane detail (transcript left + AI notes right), inline title edit, "Generate notes" button, per-attendee action items. See `templates/clips/desktop/design-refs/granola-ux.md` for the source-of-truth interaction notes — read this before redesigning any Meetings surface. (Wispr-style press-and-hold patterns belong in the Dictate skill, not here.)
+The Meetings tab intentionally mirrors **Granola**: a compact "Coming up" card over a dense reverse-chronological history, two-pane detail (transcript left + AI notes right), inline title edit, "Generate notes" button, per-attendee action items. See `templates/clips/desktop/design-refs/granola-ux.md` for the source-of-truth interaction notes — read this before redesigning any Meetings surface. (Wispr-style press-and-hold patterns belong in the Dictate skill, not here.)
 
-> If `granola-ux.md` is missing, treat that as a TODO — the Wispr ref has been written but the Granola ref hasn't landed yet.
+The list was a grid of tiles until 2026-08-14. That contradicted §2 of the ref ("list-row style rather than tile cards") and cost so much vertical space that history sat below the fold, which is how a user ends up unable to find last month's call.
 
 ## Data model touched
 
@@ -75,7 +75,8 @@ When meetings are enabled, the Clips desktop app also watches for native Zoom (`
 
 | Action                    | What it does                                                          |
 | ------------------------- | --------------------------------------------------------------------- |
-| `list-meetings`           | Upcoming + past, scoped via `accessFilter`; reads connected Google Calendar live |
+| `list-meetings`           | Upcoming + past, scoped via `accessFilter`; reads connected Google Calendar live. `hasContent` filters to meetings worth reopening; `offset` + `hasMore` page the history |
+| `search-meetings`         | Find a meeting by title, summary, notes, attendee, or linked transcript text, with a match snippet. Use this — not `list-meetings` — when the user describes what was said rather than when it happened |
 | `get-meeting`             | One meeting + participants + segments + notes                         |
 | `create-meeting`          | Create a meeting row (`source`: `calendar` / `adhoc` / `manual`); desktop adhoc Zoom/Teams detection passes `source: "adhoc"` |
 | `update-meeting`          | Inline title/notes edits and owner/admin visibility changes; meeting share links include the full transcript whenever one exists |
@@ -159,20 +160,24 @@ When on `view: "dictate"`, the block instead contains a `dictation` object with
 | "Summarize the standup I just finished"       | `pnpm action finalize-meeting --id=<id>` (delegates to agent for Gemini cleanup)        |
 | "Create a meeting note for the call I just finished" | Prefer the current calendar event. If it was not on the calendar, send the user to `/record` instead of creating a fake meeting from the UI. |
 | "Connect my Google Calendar"                  | `pnpm action connect-calendar --provider=google` then open returned `authUrl`           |
-| "Show my action items from last week"         | `list-meetings --since=<iso>`, then collect `actionItemsJson` and filter by `assigneeEmail` |
+| "Show my action items from last week"         | `list-meetings --view=past --hasContent`, then collect `actionItemsJson` and filter by `assigneeEmail` |
 
 ## How the agent uses Meetings
 
 These flows are common enough to memorize:
 
-- **"Summarize my last meeting with Alice"** — `list-meetings` filtered by participant, pick the most recent, `get-meeting`, then `finalize-meeting` if `summaryMd` is empty.
+- **"Summarize my last meeting with Alice"** — `search-meetings --query=alice`, pick the most recent, `get-meeting`, then `finalize-meeting` if `summaryMd` is empty.
+- **"Find the call where we discussed the renewal"** — `search-meetings --query="renewal"`. It reads transcripts, so it finds calls the user never titled usefully; `list-meetings` cannot answer this.
 - **"Show me action items I owe Bob"** — `list-meetings` (recent), aggregate `actionItemsJson`, filter `assigneeEmail` matching Bob's email. Mention the mic+system caveat if the user expects coverage of remote attendees.
 - **"Create a meeting note for the call I just finished"** — prefer an existing calendar-synced meeting. If the call was not on the calendar, send the user to `/record`; do not invent a fake calendar meeting in the visible Meetings list.
 - **"What did Alice commit to in last Tuesday's standup?"** — `get-meeting`, scan `actionItemsJson` filtered by assignee, fall back to grepping the transcript segments tagged `source: "system"` (since Alice is remote).
 
 ## UI conventions (don't break)
 
-- **Card grid** for meeting lists, grouped by day with a date header (Today / Tomorrow / Weekday Date).
+- **Upcoming is one compact card** ("Coming up"), never a tile grid: a date column per day, one line per event, and Join / Open notes only on the live or imminent row. It must not push history below the fold.
+- **History is dense one-line rows**, grouped by day with a date header (Today / Yesterday / Weekday Date): attendee avatars, title, attendee names, right-aligned time. No summary preview and no per-row status pills — transcript/notes state belongs on the detail page, not repeated down a list.
+- **History is paged, never capped.** The list reads `list-meetings` with `hasContent: true` (not `recordedOnly`) so desktop live notes without a linked recording still appear, and pages with `offset` + `hasMore` behind a "Load older" button.
+- **The search box is server-side**, calling `search-meetings`. Never filter the loaded page client-side: the meeting a user is hunting for is usually one they have not scrolled to.
 - **Calendar-sourced list**: no "New meeting" CTA and no manual sync requirement in the Meetings list. Users connect/reconnect/disconnect the calendar from the calendar settings menu; events are fetched live from Google Calendar.
 - **Two-pane detail**: transcript (left) + AI notes (right) with a "Generate notes" button in the header.
 - **Live indicator** is a red animated dot — never a sparkle or a robot icon.

package/corpus/templates/clips/AGENTS.md

@@ -88,6 +88,7 @@ video sharing app. The agent and the UI share the same SQL data and actions.
 | `regenerate-title`, `-summary`, `-chapters` | AI metadata |
 | `trim-`, `split-recording`, `remove-silences`, `remove-filler-words` | Edits |
 | `list-meetings`, `get-`, `update-`, `finalize-meeting` | Meetings |
+| `search-meetings` | Find a meeting by title, summary, notes, attendee, or transcript |
 | `list-dictations`, `cleanup-dictation` | Dictation history |
 | `add-comment`, `update-comment`, `create-folder`, `create-space` | Comments, folders |
 | `share-resource`, `set-resource-visibility`, `build-embed-url` | Share, embed |

package/corpus/templates/clips/actions/lib/meeting-content.ts

@@ -1,9 +1,20 @@
 /**
- * Whether a persisted meeting contains something a user can reopen.
+ * What makes a meeting worth showing in history.
  *
- * Calendar events are materialized before they are recorded, so the meetings
- * table also contains empty calendar rows. History should keep notes and
- * completed meeting rows even when no recording was linked.
+ * A calendar-sourced `clips_meetings` row is created as soon as the user
+ * records or edits an event, so the table also holds bare husks that carry
+ * nothing a user would ever reopen. Two places need that distinction and they
+ * MUST agree:
+ *
+ *   1. this predicate, for rows already in memory, and
+ *   2. `meetingHasContentFilter()` in `../list-meetings.ts`, its SQL mirror.
+ *
+ * The same rule decides which rows the history list returns AND which
+ * persisted rows a live calendar event may supersede. Let the two drift and
+ * history rows start vanishing behind their own calendar events — which is the
+ * bug that made `recordedOnly` look like a reasonable filter in the first
+ * place. `recordingId` alone is NOT the rule: desktop live notes produce a
+ * meeting with a summary and no linked recording.
  */
 export interface MeetingContentFields {
   recordingId?: string | null;

package/corpus/templates/clips/actions/list-meetings.ts

@@ -2,11 +2,22 @@
  * List meetings visible to the current user.
  *
  * Filtering:
- *   - view='upcoming' — scheduled_start in the future, not trashed
- *   - view='past'     — actual_end OR scheduled_end in the past, not trashed
+ *   - view='upcoming' — scheduled_start in the future and not yet started
+ *   - view='agenda'   — scheduled_start from `agendaLookbackMin` ago onward,
+ *                       started or not. The Meetings tab's rolling day view.
+ *   - view='past'     — actual_end OR scheduled_end in the past, OR a
+ *                       manual/ad-hoc meeting with no scheduling and no
+ *                       in-progress recording; not trashed
  *   - view='all'      — every visible meeting (excluding trashed)
  *   - view='trash'    — trashed_at is not null
  *
+ *   'upcoming' and 'agenda' differ on purpose: desktop reminders need "has not
+ *   started yet", the Meetings agenda needs "belongs to the day you are in".
+ *
+ *   `hasContent` narrows any view to meetings that actually hold something —
+ *   see `./lib/meeting-content.ts`. The Meetings history list uses it so notes
+ *   taken without a linked recording still appear.
+ *
  * Calendar behavior:
  *   Connected Google Calendar accounts are read live on every call. We only
  *   materialize a calendar event into `clips_meetings` when the user records
@@ -21,6 +32,7 @@ import {
   asc,
   desc,
   eq,
+  inArray,
   isNull,
   isNotNull,
   lt,
@@ -52,8 +64,14 @@ import { booleanParam } from "./lib/cli-params.js";
 import { meetingRowHasContent } from "./lib/meeting-content.js";
 
 const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000;
+// Must stay above `limit`'s own max (500): the persisted query always fetches
+// one row past the caller's limit as a `hasMore` probe, so if this cap ever
+// equalled 500 a caller requesting the max limit would have that probe row
+// truncated away and `hasMore` would silently read false forever at that
+// exact boundary, even with more rows still to page through.
+const MAX_PERSISTED_ROWS_PER_QUERY = 1000;
 
-/** SQL mirror of `meetingRowHasContent`. Keep history filtering consistent. */
+/** SQL mirror of `meetingRowHasContent`. Keep the two in lockstep. */
 function meetingHasContentFilter() {
   return or(
     isNotNull(schema.meetings.recordingId),
@@ -71,9 +89,20 @@ export default defineAction({
     "List meetings (Granola-style) the current user has access to. Connected calendars are read live; use view='upcoming' / 'past' / 'all' / 'trash' to filter by lifecycle.",
   schema: z.object({
     view: z
-      .enum(["upcoming", "past", "all", "trash"])
+      .enum(["upcoming", "agenda", "past", "all", "trash"])
       .default("upcoming")
-      .describe("Which list to show"),
+      .describe(
+        "Which list to show. 'agenda' is the Meetings tab's rolling window — everything scheduled from `agendaLookbackMin` ago onward, so calls that already happened today stay on the agenda; 'upcoming' is strictly not-yet-started and is what desktop reminders poll.",
+      ),
+    agendaLookbackMin: z.coerce
+      .number()
+      .int()
+      .min(0)
+      .max(60 * 24 * 7)
+      .default(60 * 24)
+      .describe(
+        "How far back view='agenda' reaches, in minutes. Default 1440 (24h): a meeting from earlier today is still part of today.",
+      ),
     limit: z.coerce.number().int().min(1).max(500).default(100),
     offset: z.coerce.number().int().min(0).default(0),
     recordedOnly: booleanParam
@@ -82,7 +111,7 @@ export default defineAction({
     hasContent: booleanParam
       .default(false)
       .describe(
-        "Only return persisted meetings that contain a recording, completed capture, notes, a summary, bullets, or action items.",
+        "Only return persisted meetings that hold something worth reopening — a linked recording, an actual start/end, notes, a summary, bullets, or action items. Prefer this over recordedOnly for history: live notes taken without a linked recording still count.",
       ),
     includeLiveCalendar: booleanParam
       .default(true)
@@ -129,9 +158,11 @@ export default defineAction({
     // slice(offset, offset + limit) at the end. To make that final slice
     // correct we must fetch enough rows from BOTH sources to cover the whole
     // offset + limit window before merging — fetching only `limit` would drop
-    // events once offset > 0 or the calendar is large. Keep the live-event cap
-    // so a huge calendar can't blow up the request. Persisted history needs
-    // the full sentinel window so pages remain available after 500 rows.
+    // events once offset > 0 or the calendar is large. Keep the hard caps
+    // (MAX_PERSISTED_ROWS_PER_QUERY persisted, 250 live) so a huge calendar
+    // can't blow up the request. We fetch one row past the window purely as a
+    // `hasMore` probe: the extra row is never returned, it only tells the
+    // caller another page exists.
     const windowCount = args.offset + args.limit;
     const upcomingWindowMaxIso = args.upcomingWithinMin
       ? new Date(
@@ -143,6 +174,28 @@ export default defineAction({
       startedWithinMin > 0
         ? new Date(now.getTime() - startedWithinMin * 60 * 1000).toISOString()
         : nowIso;
+    const agendaFloorIso = new Date(
+      now.getTime() - args.agendaLookbackMin * 60 * 1000,
+    ).toISOString();
+    // Mirrors the live calendar's own forward cap (see timeMax below) so a
+    // meeting scheduled months out can't sit ahead of nearer ones in a
+    // consistent window; harmless under the ascending sort today, but keeps
+    // "agenda" honestly meaning "the near future" if that ever changes.
+    const agendaCeilingIso = new Date(
+      now.getTime() + THIRTY_DAYS_MS,
+    ).toISOString();
+    // 'agenda' and 'upcoming' both read forward in time, so they share the
+    // ascending sort. They differ in where the window starts and in whether a
+    // meeting that already started is still allowed in.
+    const isForwardLooking = args.view === "upcoming" || args.view === "agenda";
+    // Live calendar events require a global re-sort against persisted rows, so
+    // that branch keeps the "fetch the whole window from offset 0" approach.
+    // Every other view can paginate for real in SQL — which matters here
+    // because the whole-window approach caps out at 500 rows no matter how
+    // large `offset` grows, silently stranding "Load older" once history
+    // passes 500 meetings.
+    const willMergeLiveCalendar =
+      args.includeLiveCalendar && !args.recordedOnly && args.view !== "trash";
 
     const whereClauses = [accessFilter(schema.meetings, schema.meetingShares)];
 
@@ -166,14 +219,41 @@ export default defineAction({
             : undefined,
         )!,
       );
+    } else if (args.view === "agenda") {
+      // Everything scheduled from the lookback floor onward. Deliberately does
+      // NOT exclude meetings that already started or ended: "the call you just
+      // finished" is the most useful row on a day's agenda, and excluding it is
+      // what made the old upcoming-only list feel like it had lost your day.
+      whereClauses.push(
+        and(
+          isNotNull(schema.meetings.scheduledStart),
+          gte(schema.meetings.scheduledStart, agendaFloorIso),
+          lte(schema.meetings.scheduledStart, agendaCeilingIso),
+        )!,
+      );
     } else if (args.view === "past") {
-      // Either completed (actualEnd set) or scheduled-end in the past.
+      // Either completed (actualEnd set), scheduled-end in the past, or a
+      // manual/ad-hoc meeting with no scheduling and no in-progress recording
+      // at all. That last group (dictation-style notes with no calendar event
+      // and no actualStart) can never satisfy 'agenda' or 'upcoming' — both
+      // require scheduledStart — so 'past' is the only lifecycle view left
+      // for their content to surface in. A meeting that IS actively recording
+      // (actualStart set, actualEnd not yet) still waits for actualEnd.
       whereClauses.push(
         or(
           isNotNull(schema.meetings.actualEnd),
           and(
             isNotNull(schema.meetings.scheduledEnd),
             lt(schema.meetings.scheduledEnd, nowIso),
+            // A meeting that started recording and is still going (actualStart
+            // set, actualEnd not yet) waits for actualEnd even if its schedule
+            // says it should be over — otherwise it double-appears here and on
+            // the Agenda while still in progress.
+            isNull(schema.meetings.actualStart),
+          )!,
+          and(
+            isNull(schema.meetings.scheduledStart),
+            isNull(schema.meetings.actualStart),
           )!,
         )!,
       );
@@ -185,22 +265,55 @@ export default defineAction({
       whereClauses.push(meetingHasContentFilter());
     }
 
-    const orderBy =
-      args.view === "upcoming"
-        ? [asc(schema.meetings.scheduledStart)]
-        : [
-            desc(
-              sql`COALESCE(${schema.meetings.actualStart}, ${schema.meetings.scheduledStart}, ${schema.meetings.createdAt})`,
-            ),
-          ];
-
-    const rows = await db
-      .select()
-      .from(schema.meetings)
-      .where(and(...whereClauses))
-      .orderBy(...orderBy)
-      .limit(windowCount + 1)
-      .offset(0);
+    const orderBy = isForwardLooking
+      ? [asc(schema.meetings.scheduledStart)]
+      : [
+          desc(
+            sql`COALESCE(${schema.meetings.actualStart}, ${schema.meetings.scheduledStart}, ${schema.meetings.createdAt})`,
+          ),
+        ];
+
+    // `persistedHasMore` is only meaningful (and only trusted below) on the
+    // no-merge path — the merge path derives its own `hasMore` from the
+    // combined, re-sorted array once live events are folded in.
+    let persistedHasMore = false;
+    let rows: Array<typeof schema.meetings.$inferSelect>;
+    if (willMergeLiveCalendar) {
+      rows = await db
+        .select()
+        .from(schema.meetings)
+        .where(and(...whereClauses))
+        .orderBy(...orderBy)
+        .limit(Math.min(MAX_PERSISTED_ROWS_PER_QUERY, windowCount + 1))
+        .offset(0);
+    } else {
+      const page = await db
+        .select()
+        .from(schema.meetings)
+        .where(and(...whereClauses))
+        .orderBy(...orderBy)
+        .limit(Math.min(MAX_PERSISTED_ROWS_PER_QUERY, args.limit + 1))
+        .offset(args.offset);
+      persistedHasMore = page.length > args.limit;
+      rows = page.slice(0, args.limit);
+    }
+
+    // Participants drive the history row's avatar stack and "who was on this
+    // call" subtitle. Live calendar events carry their own attendees, so this
+    // only backfills persisted rows, in one batched read rather than per row.
+    const persistedIds = rows.map((m) => m.id);
+    const participantRows = persistedIds.length
+      ? await db
+          .select()
+          .from(schema.meetingParticipants)
+          .where(inArray(schema.meetingParticipants.meetingId, persistedIds))
+      : [];
+    const participantsByMeeting = new Map<string, typeof participantRows>();
+    for (const participant of participantRows) {
+      const list = participantsByMeeting.get(participant.meetingId) ?? [];
+      list.push(participant);
+      participantsByMeeting.set(participant.meetingId, list);
+    }
 
     // Add a derived `summaryPreview` (first ~100 chars of summaryMd) so the
     // Granola-style cards can render a one-liner without re-parsing markdown.
@@ -209,7 +322,11 @@ export default defineAction({
       const preview = summary
         ? summary.replace(/\s+/g, " ").slice(0, 100)
         : null;
-      return { ...m, summaryPreview: preview };
+      return {
+        ...m,
+        summaryPreview: preview,
+        participants: participantsByMeeting.get(m.id) ?? [],
+      };
     });
 
     const liveMeetings: any[] = [];
@@ -231,11 +348,7 @@ export default defineAction({
     // Google event externalId so we can match it against the emitted set.
     const calendarEventIdToExternalId = new Map<string, string>();
 
-    if (
-      args.includeLiveCalendar &&
-      !args.recordedOnly &&
-      args.view !== "trash"
-    ) {
+    if (willMergeLiveCalendar) {
       const accountWhere = [
         accessFilter(schema.calendarAccounts, schema.calendarAccountShares),
         eq(schema.calendarAccounts.status, "connected"),
@@ -269,10 +382,12 @@ export default defineAction({
               ? new Date(now.getTime() - THIRTY_DAYS_MS).toISOString()
               : args.view === "all"
                 ? new Date(now.getTime() - THIRTY_DAYS_MS).toISOString()
-                : startedWithinMin > 0
-                  ? upcomingWindowMinIso
-                  : // Small cushion for clock skew when listing pure upcoming.
-                    new Date(now.getTime() - 60 * 1000).toISOString();
+                : args.view === "agenda"
+                  ? agendaFloorIso
+                  : startedWithinMin > 0
+                    ? upcomingWindowMinIso
+                    : // Small cushion for clock skew when listing pure upcoming.
+                      new Date(now.getTime() - 60 * 1000).toISOString();
           const timeMax =
             args.view === "past"
               ? nowIso
@@ -348,6 +463,14 @@ export default defineAction({
               continue;
             }
             if (args.view === "past" && endMs >= now.getTime()) continue;
+            // The agenda keeps already-finished events, but only back to its
+            // floor — anything that started before it belongs in Past.
+            if (
+              args.view === "agenda" &&
+              startMs < Date.parse(agendaFloorIso)
+            ) {
+              continue;
+            }
             if (
               upcomingWindowMaxIso &&
               startMs > Date.parse(upcomingWindowMaxIso)
@@ -364,11 +487,16 @@ export default defineAction({
               meeting: persisted,
             });
             if (liveMeeting) {
-              liveMeetings.push(liveMeeting);
+              // Mark the event as emitted regardless of hasContent, so an
+              // empty correlated persisted husk (below) stays suppressed
+              // rather than reappearing once its live event is filtered out.
               emittedLiveEventKeys.add(liveMeeting.id);
               if (liveMeeting.calendarExternalId) {
                 emittedLiveEventKeys.add(liveMeeting.calendarExternalId);
               }
+              if (!args.hasContent || meetingRowHasContent(liveMeeting)) {
+                liveMeetings.push(liveMeeting);
+              }
             }
           }
 
@@ -415,6 +543,18 @@ export default defineAction({
       combined.push(meeting);
     }
 
+    // Without a live merge, `combined` is exactly `persistedMeetings` — a page
+    // the DB already ordered and offset correctly. Re-sorting by a different
+    // key and re-slicing by `offset` here would both scramble that order and
+    // apply the offset a second time, so the no-merge path returns as-is.
+    if (!willMergeLiveCalendar) {
+      return {
+        meetings: combined,
+        calendarErrors,
+        hasMore: persistedHasMore,
+      };
+    }
+
     combined.sort((a, b) => {
       const aStart = Date.parse(a.scheduledStart ?? a.createdAt ?? "");
       const bStart = Date.parse(b.scheduledStart ?? b.createdAt ?? "");
@@ -424,11 +564,8 @@ export default defineAction({
     });
 
     const meetings = combined.slice(args.offset, args.offset + args.limit);
+    const hasMore = combined.length > args.offset + args.limit;
 
-    return {
-      meetings,
-      calendarErrors,
-      hasMore: combined.length > args.offset + args.limit,
-    };
+    return { meetings, calendarErrors, hasMore };
   },
 });