@agent-native/core 0.100.0 → 0.100.1

package/corpus/templates/calendar/changelog/2026-07-13-calendar-inventory-reads-report-source-coverage.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-13
+---
+
+Direct Calendar reads now show which connected sources were covered, including partial connection or feed failures.

package/corpus/templates/calendar/server/lib/calendar-connector-catalog.ts

@@ -0,0 +1,8 @@
+/**
+ * Deliberately narrow authenticated MCP surface for Calendar.
+ *
+ * External callers may read calendar coverage through list-events. Other
+ * actions remain available through the in-app agent, ask_app, or an explicit
+ * full-catalog connection; tool-search alone never makes them callable.
+ */
+export const CALENDAR_CONNECTOR_CATALOG = ["list-events"] as const;

package/corpus/templates/calendar/server/lib/google-calendar.ts

@@ -190,6 +190,22 @@ const LIST_EVENT_TYPES = [
   "outOfOffice",
   "workingLocation",
 ];
+const GOOGLE_READ_CONCURRENCY = 4;
+
+async function mapWithConcurrency<T, R>(
+  values: T[],
+  map: (value: T) => Promise<R>,
+): Promise<R[]> {
+  const results: R[] = [];
+  for (let index = 0; index < values.length; index += GOOGLE_READ_CONCURRENCY) {
+    results.push(
+      ...(await Promise.all(
+        values.slice(index, index + GOOGLE_READ_CONCURRENCY).map(map),
+      )),
+    );
+  }
+  return results;
+}
 
 function mapReminders(
   event: any,
@@ -684,6 +700,85 @@ export async function getClientsWithErrors(forEmail?: string): Promise<{
   return { clients, errors };
 }
 
+/**
+ * Resolve a caller's connected Google accounts without refreshing tokens. This
+ * is intentionally separate from `getClientsWithErrors`: callers that accept
+ * an account filter must reject an unowned requested account before they do
+ * provider work for any account.
+ */
+export async function getOwnedAccountEmails(
+  forEmail?: string,
+): Promise<string[]> {
+  if (!forEmail) return [];
+  const accounts = await listOAuthAccountsByOwner("google", forEmail);
+  return accounts.map((account) => account.accountId);
+}
+
+export async function getClientsForAccountsWithErrors(
+  forEmail: string | undefined,
+  accountEmails?: string[],
+): Promise<{
+  clients: Array<{ email: string; accessToken: string }>;
+  errors: Array<{ email: string; error: string }>;
+  requestedAccounts: string[];
+  resolvedAccounts: string[];
+}> {
+  if (!forEmail) {
+    return {
+      clients: [],
+      errors: [],
+      requestedAccounts: [],
+      resolvedAccounts: [],
+    };
+  }
+  const accounts = await listOAuthAccountsByOwner("google", forEmail);
+  const byNormalized = new Map(
+    accounts.map((account) => [
+      account.accountId.trim().toLowerCase(),
+      account,
+    ]),
+  );
+  const requestedAccounts = Array.from(
+    new Set(
+      (accountEmails ?? accounts.map((account) => account.accountId))
+        .map((email) => email.trim().toLowerCase())
+        .filter(Boolean),
+    ),
+  );
+  const unowned = requestedAccounts.filter((email) => !byNormalized.has(email));
+  if (unowned.length > 0) {
+    throw new Error(
+      `Google Calendar account not connected for this user: ${unowned.join(", ")}`,
+    );
+  }
+  const selected = requestedAccounts.map((email) => byNormalized.get(email)!);
+  const clients: Array<{ email: string; accessToken: string }> = [];
+  const errors: Array<{ email: string; error: string }> = [];
+  await mapWithConcurrency(selected, async (account) => {
+    try {
+      const accessToken = await getValidAccessToken(
+        account.accountId,
+        account.tokens as unknown as GoogleTokens,
+        forEmail,
+      );
+      clients.push({ email: account.accountId, accessToken });
+    } catch (err: any) {
+      errors.push({
+        email: account.accountId,
+        error: err?.message || "Unknown refresh error",
+      });
+    }
+  });
+  clients.sort((a, b) => a.email.localeCompare(b.email));
+  errors.sort((a, b) => a.email.localeCompare(b.email));
+  return {
+    clients,
+    errors,
+    requestedAccounts,
+    resolvedAccounts: selected.map((account) => account.accountId),
+  };
+}
+
 export async function isConnected(forEmail?: string): Promise<boolean> {
   return isOAuthConnected("google", forEmail ?? "");
 }
@@ -779,12 +874,13 @@ export async function listEvents(
   timeMin: string,
   timeMax: string,
   forEmail?: string,
+  options: { accountEmails?: string[]; maxResults?: number } = {},
 ): Promise<{
   events: CalendarEvent[];
   errors: Array<{ email: string; error: string }>;
 }> {
   const { clients, errors: refreshErrors } =
-    await getClientsWithErrors(forEmail);
+    await getClientsForAccountsWithErrors(forEmail, options.accountEmails);
   // Seed with refresh failures so a fully-dead connection (every account's
   // refresh_token revoked or invalidated by a GOOGLE_CLIENT_ID rotation)
   // reaches the caller — otherwise the result is indistinguishable from
@@ -792,8 +888,9 @@ export async function listEvents(
   const errors: Array<{ email: string; error: string }> = [...refreshErrors];
   if (clients.length === 0) return { events: [], errors };
 
-  const allResults = await Promise.all(
-    clients.map(async ({ email, accessToken }) => {
+  const allResults = await mapWithConcurrency(
+    clients,
+    async ({ email, accessToken }) => {
       try {
         const events: any[] = [];
         let pageToken: string | undefined;
@@ -803,7 +900,7 @@ export async function listEvents(
             timeMax,
             singleEvents: true,
             orderBy: "startTime",
-            maxResults: 2500,
+            maxResults: options.maxResults ?? 2500,
             pageToken,
             eventTypes: LIST_EVENT_TYPES,
           });
@@ -883,7 +980,7 @@ export async function listEvents(
         errors.push({ email, error: error.message });
         return [];
       }
-    }),
+    },
   );
 
   return { events: allResults.flat(), errors };
@@ -993,64 +1090,89 @@ export async function listOverlayEvents(
   timeMax: string,
   overlayEmails: string[],
   forEmail?: string,
+  options: { accountEmails?: string[] } = {},
 ): Promise<{
   events: CalendarEvent[];
   errors: Array<{ email: string; error: string }>;
+  accountErrors: Array<{ email: string; error: string }>;
 }> {
   const { clients, errors: refreshErrors } =
-    await getClientsWithErrors(forEmail);
-  const errors: Array<{ email: string; error: string }> = [...refreshErrors];
-  if (clients.length === 0) return { events: [], errors };
-
-  // Use the first available token to query other people's calendars
-  const { accessToken } = clients[0];
+    await getClientsForAccountsWithErrors(forEmail, options.accountEmails);
+  const errors: Array<{ email: string; error: string }> = [];
+  if (clients.length === 0) {
+    const message =
+      refreshErrors[0]?.error ?? "Google Calendar is not connected";
+    return {
+      events: [],
+      errors: overlayEmails.map((email) => ({ email, error: message })),
+      accountErrors: refreshErrors,
+    };
+  }
 
   const allResults = await Promise.all(
     overlayEmails.map(async (overlayEmail) => {
-      try {
-        const response = await calendarListEvents(accessToken, overlayEmail, {
-          timeMin,
-          timeMax,
-          singleEvents: true,
-          orderBy: "startTime",
-          eventTypes: LIST_EVENT_TYPES,
-        });
-
-        const events = response.items || [];
-        return events.map((event: any) => ({
-          id: `overlay-${overlayEmail}-${event.id}`,
-          title: event.summary || "Busy",
-          description: event.description || "",
-          start: event.start?.dateTime || event.start?.date || "",
-          end: event.end?.dateTime || event.end?.date || "",
-          startTimeZone: event.start?.timeZone || undefined,
-          endTimeZone: event.end?.timeZone || undefined,
-          location: event.location || "",
-          allDay: !event.start?.dateTime,
-          source: "google" as const,
-          googleEventId: event.id || undefined,
-          htmlLink: event.htmlLink || undefined,
-          eventType: event.eventType || "default",
-          accountEmail: undefined,
-          overlayEmail,
-          ...mapColor(event),
-          attendees: mapAttendees(event),
-          organizer: mapOrganizer(event),
-          createdAt: event.created || new Date().toISOString(),
-          updatedAt: event.updated || new Date().toISOString(),
-        }));
-      } catch (error: any) {
-        console.error(
-          `[listOverlayEvents] Error fetching ${overlayEmail}:`,
-          error.message,
-        );
-        errors.push({ email: overlayEmail, error: error.message });
-        return [];
+      const accessErrors: string[] = [];
+      for (const client of clients) {
+        try {
+          const events: any[] = [];
+          let pageToken: string | undefined;
+          do {
+            const response = await calendarListEvents(
+              client.accessToken,
+              overlayEmail,
+              {
+                timeMin,
+                timeMax,
+                singleEvents: true,
+                orderBy: "startTime",
+                eventTypes: LIST_EVENT_TYPES,
+                pageToken,
+              },
+            );
+            events.push(...(response.items || []));
+            pageToken = response.nextPageToken;
+          } while (pageToken);
+          return events.map((event: any) => ({
+            id: `overlay-${overlayEmail}-${event.id}`,
+            title: event.summary || "Busy",
+            description: event.description || "",
+            start: event.start?.dateTime || event.start?.date || "",
+            end: event.end?.dateTime || event.end?.date || "",
+            startTimeZone: event.start?.timeZone || undefined,
+            endTimeZone: event.end?.timeZone || undefined,
+            location: event.location || "",
+            allDay: !event.start?.dateTime,
+            source: "google" as const,
+            googleEventId: event.id || undefined,
+            htmlLink: event.htmlLink || undefined,
+            eventType: event.eventType || "default",
+            accountEmail: client.email,
+            overlayEmail,
+            ...mapColor(event),
+            attendees: mapAttendees(event),
+            organizer: mapOrganizer(event),
+            createdAt: event.created || new Date().toISOString(),
+            updatedAt: event.updated || new Date().toISOString(),
+          }));
+        } catch (error: any) {
+          const message = error?.message || "Unable to read overlay calendar";
+          console.error(
+            `[listOverlayEvents] Error fetching ${overlayEmail} via ${client.email}:`,
+            message,
+          );
+          accessErrors.push(`${client.email}: ${message}`);
+        }
       }
+
+      errors.push({
+        email: overlayEmail,
+        error: `No selected Google account could read this overlay (${accessErrors.join("; ")})`,
+      });
+      return [];
     }),
   );
 
-  return { events: allResults.flat(), errors };
+  return { events: allResults.flat(), errors, accountErrors: refreshErrors };
 }
 
 export async function getEvent(

package/corpus/templates/calendar/server/lib/ical-fetcher.ts

@@ -273,6 +273,7 @@ export async function fetchICalEvents(
   color: string,
   from: string,
   to: string,
+  options: { throwOnError?: boolean } = {},
 ): Promise<CalendarEvent[]> {
   const httpUrl = normalizeUrl(url);
 
@@ -281,6 +282,7 @@ export async function fetchICalEvents(
   } catch {
     // Silently degrade — never echo the URL or reason back. A loud error
     // helps an attacker map internal infrastructure via probe responses.
+    if (options.throwOnError) throw new Error("ICS feed URL is not allowed");
     return [];
   }
 
@@ -294,9 +296,17 @@ export async function fetchICalEvents(
       },
       { maxRedirects: 3 },
     );
-    if (!response.ok) return [];
+    if (!response.ok) {
+      if (options.throwOnError) throw new Error("ICS feed request failed");
+      return [];
+    }
     icsText = await response.text();
-  } catch {
+  } catch (error) {
+    if (options.throwOnError) {
+      throw error instanceof Error
+        ? error
+        : new Error("ICS feed request failed");
+    }
     return [];
   }
 
@@ -323,6 +333,7 @@ export async function fetchICalEvents(
       location: e.location || "",
       allDay: e.allDay,
       source: "ical" as const,
+      sourceId: feedId,
       color,
       createdAt: now,
       updatedAt: now,

package/corpus/templates/calendar/server/plugins/agent-chat.ts

@@ -13,6 +13,7 @@ import { z } from "zod";
 // why `autoDiscoverActions` on its own produces 404s for action routes in
 // production.
 import actionsRegistry from "../../.generated/actions-registry.js";
+import { CALENDAR_CONNECTOR_CATALOG } from "../lib/calendar-connector-catalog.js";
 
 // ---------------------------------------------------------------------------
 // Register calendar event-bus events
@@ -83,6 +84,7 @@ const INITIAL_TOOL_NAMES = [
 export default createAgentChatPlugin({
   appId: "calendar",
   initialToolNames: INITIAL_TOOL_NAMES,
+  connectorCatalog: [...CALENDAR_CONNECTOR_CATALOG],
   // Enable sandboxed JavaScript execution so Calendar agents can fetch,
   // paginate, and reduce provider data through providerFetch() without us
   // hardcoding one action per Google Calendar / CRM endpoint.
@@ -102,7 +104,7 @@ Google Calendar events are NOT stored in the local database. They are fetched li
 
 Provider-specific Calendar actions are shortcuts, not limits. If a first-class action cannot express the exact Google Calendar/CRM endpoint, calendar id, filter, request body, pagination mode, attendee search, recurrence field, or API version needed, call \`provider-api-catalog\` and \`provider-api-docs\` as needed, then call \`provider-api-request\` against the provider's real HTTP API. Use this raw provider API escape hatch instead of weakening the answer, broadening filters, or claiming Calendar cannot do something the underlying API can do.
 
-- \`pnpm action view-screen\` — See what the user is looking at (current view, date, events). ALWAYS run this first.
+- \`pnpm action view-screen\` — See the visible UI state (current view, date, selected event). Use it for questions about what the user is looking at, not as a prerequisite for deterministic schedule reads.
 - \`pnpm action list-events --from YYYY-MM-DD --to YYYY-MM-DD\` — List events from Google Calendar. The --to date is exclusive, so use tomorrow for today's events.
 - \`pnpm action search-events --query "term" --from YYYY-MM-DD --to YYYY-MM-DD\` — Convenience bounded search by title, attendees, organizer, location, or description. For relationship history, all-calendar discovery, exact attendee/domain search, or custom pagination, prefer provider-api-request with provider=google_calendar.
 - \`pnpm action provider-api-catalog\` / \`provider-api-docs\` / \`provider-api-request\` — Inspect and call the real Google Calendar, Apollo, Gong, HubSpot, and Pylon APIs directly. For Google Calendar events.list pagination use provider=google_calendar, path=/calendars/primary/events, query={...}, fetchAllPages={cursorPath:"nextPageToken",cursorParam:"pageToken",itemsPath:"items"}. For large relationship-history scans, pass stageAs and pagination={nextCursorPath:"nextPageToken",cursorParam:"pageToken",maxPages:N} with itemsPath="items", then use query-staged-dataset.
@@ -125,14 +127,14 @@ Provider-specific Calendar actions are shortcuts, not limits. If a first-class a
 Use \`create-event\` or \`update-event --colorId 1..11\` when the user wants one specific Google Calendar event color changed. Use \`update-calendar-visual-preferences\` when the user wants broad app-layer display rules such as color-coding meetings by internal/external, 1:1/group, focus time, or one display color for all Google events.
 
 ## Google Connection Check
-Before answering schedule questions, run view-screen first for context, then use list-events for the requested date range even if the user is currently on Settings, Booking Links, or another non-calendar page. Do not infer a Google Calendar connection problem just because the current page is Settings. Only ask the user to reconnect Google if list-events or the explicit Google status reports an auth/connection error.
+For broad, deterministic schedule reads, call list-events directly for the requested date range in inventory/coverage mode, even when UI context is irrelevant or the user is on Settings, Booking Links, or another non-calendar page. Do not require view-screen as a connection preflight, and do not infer a Google Calendar connection problem from the current screen. Only ask the user to reconnect Google if list-events or the explicit Google status reports an auth/connection error.
 
 When the user explicitly asks you to connect or reconnect Google Calendar, call \`connect-google-calendar\` and give them the returned link. Do not call raw HTTP/fetch/web-request against \`/_agent-native/google/auth-url\`; that route depends on the user's browser session and will return 401 from the agent backend.
 
 For relationship-history or frequency questions such as "who have I met at Adobe?" or "how often do I meet with Mattel?", prefer the raw Google Calendar API through provider-api-request so you can choose the exact timeMin/timeMax, q, calendarId, maxResults, and pageToken behavior. Stage large paginated results before analysis. Do not conclude there are no recurring meetings from the visible range or from a convenience action alone.
 
 ## Context Awareness
-The UI writes navigation state including the current view, date, view mode (day/week/month), and selected event ID. Always check view-screen to know what the user sees before responding.
+The UI writes navigation state including the current view, date, view mode (day/week/month), and selected event ID. Check view-screen when the answer depends on that visible state; skip it for headless inventory/coverage reads with an explicit date range.
 
 When the user says "show me", "go to", "open", or "switch to" a view or date, ALWAYS use the \`navigate\` action to update the UI first, then fetch/display data. The user expects to SEE the result in the app.`,
   mentionProviders: async () => {

package/corpus/templates/calendar/shared/api.ts

@@ -11,6 +11,8 @@ export interface CalendarEvent {
   location: string;
   allDay: boolean;
   source: "local" | "google" | "ical";
+  /** Stable feed/source identifier for non-Google inventory provenance. */
+  sourceId?: string;
   googleEventId?: string;
   /** Absolute Google Calendar web URL for Google events */
   htmlLink?: string;

package/corpus/templates/mail/AGENTS.md

@@ -7,6 +7,18 @@ updates mail state through actions and application state.
 Detailed draft, queue, and contact-resolution patterns live in
 `.agents/skills/`.
 
+## Coverage-aware inventory reads
+
+`list-emails` remains the compatibility list action for the UI and internal
+callers. External MCP callers receive its structured inventory envelope by
+default (or pass `format: "inventory"`). Inventory reads use `accountEmails`
+for an explicit set; the legacy singular `account` alias cannot be combined
+with it. The response reports each account's success, empty result, exhaustion
+or bounded error, so partial coverage must never be described as complete.
+Inventory items are intentionally compact metadata only — use `get-email` or
+`get-thread` only after selecting a specific result when body content is
+needed.
+
 ## Core Rules
 
 - Store large file/blob payloads in configured file/blob storage, not SQL: no