@agent-native/core 0.97.0 → 0.98.1

package/corpus/templates/mail/server/lib/list-inbox-emails.ts

@@ -0,0 +1,169 @@
+/**
+ * Shared Gmail inbox-listing core.
+ *
+ * This is the single source of truth for turning a view/query/label into a
+ * filtered, sorted list of emails from Gmail — called by both the actions
+ * surface (agent, `actions/list-emails.ts`) and the REST route handler
+ * (frontend, `handlers/emails.ts::listEmails`). Before this file existed the
+ * two call sites re-implemented the same query-build + pagination +
+ * thread-scoping pipeline independently, which let them drift: the REST
+ * handler filtered out snoozed threads and handled Gmail 429/quota errors
+ * gracefully, while the agent action did neither. Keeping this logic in one
+ * place means the agent's inbox always matches what the human sees.
+ *
+ * Callers remain responsible for resolving `accountTokens` / `labelMap`
+ * (the two call sites fetch these differently — the REST handler caches
+ * label names and account display names, the action does not — that's a
+ * legitimate perf difference, not part of the listing core) and for shaping
+ * their own response envelope (compact/counts for the action; pagination
+ * tokens, error headers, and HTTP status for the REST handler).
+ */
+import type { EmailMessage } from "@shared/types.js";
+
+import {
+  buildGmailEmailSearchQuery,
+  filterInboxScopedThreadMessages,
+} from "./gmail-query.js";
+import {
+  DEFAULT_THREAD_RECENT_MESSAGE_CANDIDATE_LIMIT,
+  gmailToEmailMessage,
+  listGmailMessages,
+} from "./google-auth.js";
+import { getSnoozedThreadIds } from "./jobs.js";
+
+export interface ListInboxEmailsAccountToken {
+  email: string;
+  accessToken: string;
+}
+
+export interface ListInboxEmailsParams {
+  ownerEmail: string;
+  view: string;
+  q?: string;
+  label?: string;
+  limit: number;
+  pageTokens?: Record<string, string>;
+  threadFormat?: "full" | "metadata" | "minimal";
+  threadCandidateLimit?: number;
+  accountTokens: ListInboxEmailsAccountToken[];
+  labelMap: Map<string, string>;
+}
+
+export interface ListInboxEmailsSuccess {
+  ok: true;
+  emails: EmailMessage[];
+  errors: Array<{ email: string; error: string }>;
+  nextPageTokens?: Record<string, string>;
+  resultSizeEstimate?: number;
+}
+
+export interface ListInboxEmailsFailure {
+  ok: false;
+  message: string;
+  isQuotaError: boolean;
+  retryAfterSeconds?: number;
+}
+
+export type ListInboxEmailsResult =
+  | ListInboxEmailsSuccess
+  | ListInboxEmailsFailure;
+
+export function isGmailQuotaError(message: string): boolean {
+  return /\b(?:429|quota|rate limit|rateLimitExceeded|userRateLimitExceeded)\b/i.test(
+    message,
+  );
+}
+
+export function retryAfterSecondsFromErrors(
+  errors: Array<{ error: string }>,
+): number {
+  let retryAfter = 60;
+  for (const { error } of errors) {
+    const match = error.match(/retry in\s+(\d+)s/i);
+    if (!match) continue;
+    const seconds = Number(match[1]);
+    if (Number.isFinite(seconds) && seconds > retryAfter) {
+      retryAfter = seconds;
+    }
+  }
+  return Math.min(retryAfter, 5 * 60);
+}
+
+/**
+ * Fetch, thread-scope, sort, and snooze-filter Gmail messages for a view.
+ * Returns a discriminated result instead of throwing on Gmail errors so both
+ * callers can decide how to surface a rate-limit/quota failure gracefully
+ * (HTTP status + Retry-After header for the REST handler, a structured JSON
+ * error payload for the agent action) rather than an unhandled exception.
+ */
+export async function listInboxEmails(
+  params: ListInboxEmailsParams,
+): Promise<ListInboxEmailsResult> {
+  const {
+    ownerEmail,
+    view,
+    q,
+    label,
+    limit,
+    pageTokens,
+    threadFormat,
+    threadCandidateLimit,
+    accountTokens,
+    labelMap,
+  } = params;
+
+  const connectedEmails = new Set(
+    accountTokens.map((account) => account.email.toLowerCase()),
+  );
+  const searchQuery = buildGmailEmailSearchQuery({ view, q, label });
+
+  const { messages, errors, nextPageTokens, resultSizeEstimate } =
+    await listGmailMessages(searchQuery, limit, ownerEmail, pageTokens, {
+      mode: "threads",
+      threadFormat,
+      threadCandidateLimit,
+      threadRecentMessageCandidateLimit:
+        !q && (view === "inbox" || view === "unread")
+          ? DEFAULT_THREAD_RECENT_MESSAGE_CANDIDATE_LIMIT
+          : undefined,
+    });
+
+  if (messages.length === 0 && errors.length > 0) {
+    const isQuotaError = errors.every((e) => isGmailQuotaError(e.error));
+    return {
+      ok: false,
+      message: errors.map((e) => `${e.email}: ${e.error}`).join("; "),
+      isQuotaError,
+      retryAfterSeconds: isQuotaError
+        ? retryAfterSecondsFromErrors(errors)
+        : undefined,
+    };
+  }
+
+  let emails = messages.map((m: any) =>
+    gmailToEmailMessage(m, m._accountEmail, labelMap),
+  ) as EmailMessage[];
+  emails = filterInboxScopedThreadMessages(
+    emails,
+    view,
+    label,
+    connectedEmails,
+  );
+  emails = [...emails].sort(
+    (a, b) => new Date(b.date).getTime() - new Date(a.date).getTime(),
+  );
+
+  // Filter out snoozed threads (they may linger in Gmail due to eventual
+  // consistency). Skip when searching — the user/agent wants to find snoozed
+  // emails too when explicitly searching for them.
+  if (!q && (view === "inbox" || view === "unread")) {
+    const snoozedIds = await getSnoozedThreadIds(ownerEmail);
+    if (snoozedIds.size > 0) {
+      emails = emails.filter(
+        (e) => !snoozedIds.has(e.threadId) && !snoozedIds.has(e.id),
+      );
+    }
+  }
+
+  return { ok: true, emails, errors, nextPageTokens, resultSizeEstimate };
+}

package/corpus/templates/plan/.agents/skills/frontend-design/SKILL.md

@@ -48,7 +48,7 @@ Default to Apple/Linear-level restraint: make the primary workflow obvious, then
 
 - **Typography**: Use the product's existing type system first. For net-new public pages, choose characterful but readable type and keep sizing appropriate to the surface.
 - **Color and theme**: Use semantic tokens and CSS variables. Avoid one-note palettes and default purple/blue gradients unless the brand demands them.
-- **Motion**: Prefer purposeful transitions and small state changes. Use CSS transitions/keyframes unless the app already uses a motion library.
+- **Motion**: Prefer purposeful transitions and small state changes. Use CSS transitions/keyframes unless the app already uses a motion library. Never `transition-all` — list the properties that actually change (e.g. `transition-[opacity,transform]`). Use the shared easing tokens defined in `packages/core/src/styles/agent-native.css` instead of hand-typing curves: `var(--ease-drawer)` (260ms, drawers/app chrome), `var(--ease-collapse)` (200ms, expand/collapse), `var(--ease-out-strong)` (snappy entrances) — in Tailwind, `ease-[var(--ease-collapse)]`. Enter/exit with ease-out, never `ease-in`. Overlays that zoom in must set the Radix origin var (e.g. `origin-[--radix-popover-content-transform-origin]`). Animate `transform`/`opacity`, not width/height/padding/box-shadow. Gate looping or large-movement animations with `motion-reduce:`. Command palettes and keyboard-triggered actions get no animation.
 - **Composition**: Match the workflow. Operational apps should be dense and scannable; marketing or portfolio pages can be more immersive.
 - **Visual assets**: Websites, games, and object-focused pages need real or generated media when images help users understand the subject.
 - **Responsive fit**: Text must not overflow buttons, cards, tabs, sidebars, or fixed-format tools. Use stable dimensions for boards, grids, toolbars, and counters.

package/corpus/templates/plan/.agents/skills/real-time-sync/SKILL.md

@@ -30,7 +30,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
    useDbSync({ queryClient });
    ```
 
-   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries for ordinary domain events — that caused a request storm in production. The exception is `source: "action"`: a successful mutating action is the framework-wide "agent changed app data" signal, so `useDbSync` also refreshes active React Query observers as a compatibility safety net for custom apps that have not yet moved every read to `useActionQuery` or source-versioned query keys.
+   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries — that caused request storms in production. A successful mutating action refreshes active `useActionQuery` observers under the `["action"]` prefix. Browser actions carry a tab id so their originating tab ignores the sync echo while other tabs refresh. Legacy apps can opt into broader compatibility with `actionInvalidatePredicate`, but first-party apps should use action-backed or source-versioned query keys. Idle fallback polling runs once per minute; active agent work temporarily uses the faster cadence.
 
 3. **Templates fold per-source counters into their query keys.** This is the pattern that makes "agent writes show up without a manual refresh" reliable:
 
@@ -117,7 +117,7 @@ useQuery({
 | UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Does the affected query have an active observer?         |
 | Poll endpoint not responding       | Is `/_agent-native/poll` accessible? Is the server running?                                                    |
 | SSE not connecting                 | Is `/_agent-native/events` accessible and authenticated? Polling should still keep the UI fresh as fallback.   |
-| High CPU / event storms            | The agent is writing rapidly. Add `staleTime` to queries to debounce refetches.                                |
+| High CPU / event storms            | Use targeted source keys, settle bursty list counters, and avoid broad action invalidation.                   |
 
 ## Jitter Prevention
 

package/corpus/templates/plan/.env.example

@@ -11,6 +11,10 @@
 # Google sign-in (optional)
 # Set these to show "Continue with Google" on the account screen.
 # For simple local plan generation, the dev auto-session is enough.
+# Preferred: low-scope, sign-in-only credentials.
+# GOOGLE_SIGN_IN_CLIENT_ID=
+# GOOGLE_SIGN_IN_CLIENT_SECRET=
+# Fallback: broader-scope legacy credentials, used if the pair above is unset.
 # GOOGLE_CLIENT_ID=
 # GOOGLE_CLIENT_SECRET=
 

package/corpus/templates/plan/actions/create-plan-design.ts

@@ -34,7 +34,10 @@ import {
   sectionInputSchema,
   writeEvent,
 } from "../server/plans.js";
-import { planContentSchema } from "../shared/plan-content.js";
+import {
+  agentPlanContentSchema,
+  planContentSchema,
+} from "../shared/plan-content.js";
 
 const designSurfaceSchema = z.enum([
   "desktop",
@@ -100,89 +103,94 @@ const designContextRecordSchema = z.record(z.string(), z.unknown()).refine(
   { message: "Design context metadata is too large." },
 );
 
+const CONTENT_DESCRIPTION =
+  "Full structured content when the caller has already authored the design/prototype. Prefer screens/transitions for normal /plan-design creation.";
+
+// Named (and un-refined) so `agentInputSchema` below can `.extend()` it with
+// a compact `content` field instead of duplicating every other key. The
+// `.refine()` (brief/goal requirement) only applies to the real runtime
+// `schema` further down.
+const createPlanDesignSchema = z.object({
+  title: z.string().optional().describe("Short design plan title"),
+  brief: z
+    .string()
+    .optional()
+    .describe(
+      "One short sentence summarizing the design direction, shown as the lede under the title. Keep it to a single tight line.",
+    ),
+  goal: z.string().optional().describe("Alias for brief."),
+  source: planSourceSchema.optional().default("manual"),
+  repoPath: z.string().optional().describe("Repository path for the run"),
+  currentFocus: z.string().optional().describe("Current design review focus"),
+  status: planStatusSchema.optional().default("review"),
+  content: planContentSchema.optional().describe(CONTENT_DESCRIPTION),
+  screens: z
+    .array(designScreenSchema)
+    .max(6)
+    .optional()
+    .default([])
+    .describe(
+      "Full-fidelity design screens. Include one to six substantial screens/states with real labels, brand styling, and data-design-id attributes on editable elements. Use CSS for Tailwind-like utility classes because the Plan renderer does not load arbitrary CDN scripts.",
+    ),
+  transitions: z
+    .array(designTransitionSchema)
+    .max(24)
+    .optional()
+    .default([])
+    .describe(
+      "Expected screen transitions for the Prototype tab. Use data-goto attributes in screen HTML for true route/step changes.",
+    ),
+  designMd: z
+    .string()
+    .max(100_000)
+    .optional()
+    .describe("Optional design.md content used as design direction"),
+  brandKit: designContextRecordSchema
+    .optional()
+    .describe("Optional parsed brand kit or .fig design-system data"),
+  codebaseStyles: designContextRecordSchema
+    .optional()
+    .describe("Optional parsed CSS vars, Tailwind tokens, fonts, and colors"),
+  designNotes: z
+    .string()
+    .max(20_000)
+    .optional()
+    .describe("Concise notes about brand/style assumptions"),
+  implementationNotes: z
+    .string()
+    .max(20_000)
+    .optional()
+    .describe("Concise notes for the implementation map section"),
+  markdown: z
+    .string()
+    .max(100_000)
+    .optional()
+    .describe("Markdown/text fallback or source design plan"),
+  sections: z
+    .array(sectionInputSchema)
+    .optional()
+    .default([])
+    .describe("Optional legacy plan sections"),
+  comments: z
+    .array(commentInputSchema)
+    .optional()
+    .default([])
+    .describe("Initial annotations or review prompts"),
+});
+
 export default defineAction({
   description:
     "Create a full-fidelity branded design plan with a Design tab (editable design canvas) and optional Prototype tab. For a document-first plan use create-visual-plan; for a wireframe-canvas plan use create-ui-plan; for a recap of an existing diff use create-visual-recap; for a functional prototype use create-prototype-plan. Use design.md, .fig brand kits, and codebase CSS/Tailwind/token evidence when available. Design screens are bounded HTML/CSS fragments with data-design-id targets. Publish via this tool; never deliver the plan as inline chat text.",
-  schema: z
-    .object({
-      title: z.string().optional().describe("Short design plan title"),
-      brief: z
-        .string()
-        .optional()
-        .describe(
-          "One short sentence summarizing the design direction, shown as the lede under the title. Keep it to a single tight line.",
-        ),
-      goal: z.string().optional().describe("Alias for brief."),
-      source: planSourceSchema.optional().default("manual"),
-      repoPath: z.string().optional().describe("Repository path for the run"),
-      currentFocus: z
-        .string()
-        .optional()
-        .describe("Current design review focus"),
-      status: planStatusSchema.optional().default("review"),
-      content: planContentSchema
-        .optional()
-        .describe(
-          "Full structured content when the caller has already authored the design/prototype. Prefer screens/transitions for normal /plan-design creation.",
-        ),
-      screens: z
-        .array(designScreenSchema)
-        .max(6)
-        .optional()
-        .default([])
-        .describe(
-          "Full-fidelity design screens. Include one to six substantial screens/states with real labels, brand styling, and data-design-id attributes on editable elements. Use CSS for Tailwind-like utility classes because the Plan renderer does not load arbitrary CDN scripts.",
-        ),
-      transitions: z
-        .array(designTransitionSchema)
-        .max(24)
-        .optional()
-        .default([])
-        .describe(
-          "Expected screen transitions for the Prototype tab. Use data-goto attributes in screen HTML for true route/step changes.",
-        ),
-      designMd: z
-        .string()
-        .max(100_000)
-        .optional()
-        .describe("Optional design.md content used as design direction"),
-      brandKit: designContextRecordSchema
-        .optional()
-        .describe("Optional parsed brand kit or .fig design-system data"),
-      codebaseStyles: designContextRecordSchema
-        .optional()
-        .describe(
-          "Optional parsed CSS vars, Tailwind tokens, fonts, and colors",
-        ),
-      designNotes: z
-        .string()
-        .max(20_000)
-        .optional()
-        .describe("Concise notes about brand/style assumptions"),
-      implementationNotes: z
-        .string()
-        .max(20_000)
-        .optional()
-        .describe("Concise notes for the implementation map section"),
-      markdown: z
-        .string()
-        .max(100_000)
-        .optional()
-        .describe("Markdown/text fallback or source design plan"),
-      sections: z
-        .array(sectionInputSchema)
-        .optional()
-        .default([])
-        .describe("Optional legacy plan sections"),
-      comments: z
-        .array(commentInputSchema)
-        .optional()
-        .default([])
-        .describe("Initial annotations or review prompts"),
-    })
-    .refine((args) => Boolean(args.brief || args.goal), {
-      message: "Either brief or goal is required.",
-    }),
+  schema: createPlanDesignSchema.refine(
+    (args) => Boolean(args.brief || args.goal),
+    { message: "Either brief or goal is required." },
+  ),
+  // ADVERTISED-ONLY: same top-level shape, but `content` swaps the deep
+  // per-block-type union for a compact `type`-enum stand-in. Runtime
+  // validation always runs the full schema above — see the `actions` skill.
+  agentInputSchema: createPlanDesignSchema.extend({
+    content: agentPlanContentSchema.optional().describe(CONTENT_DESCRIPTION),
+  }),
   publicAgent: {
     expose: true,
     readOnly: false,

package/corpus/templates/plan/actions/create-prototype-plan.ts

@@ -34,7 +34,10 @@ import {
   sectionInputSchema,
   writeEvent,
 } from "../server/plans.js";
-import { planContentSchema } from "../shared/plan-content.js";
+import {
+  agentPlanContentSchema,
+  planContentSchema,
+} from "../shared/plan-content.js";
 
 const prototypeSurfaceSchema = z.enum([
   "desktop",
@@ -80,67 +83,77 @@ const prototypeTransitionSchema = z.object({
   trigger: z.string().optional(),
 });
 
+const CONTENT_DESCRIPTION =
+  "Full structured content when the caller has already authored a prototype. Prefer screens/transitions unless replacing the whole document.";
+
+// Named (and un-refined) so `agentInputSchema` below can `.extend()` it with
+// a compact `content` field instead of duplicating every other key. The
+// `.refine()` (brief/goal requirement) only applies to the real runtime
+// `schema` further down.
+const createPrototypePlanSchema = z.object({
+  title: z.string().optional().describe("Short visual plan title"),
+  brief: z
+    .string()
+    .optional()
+    .describe(
+      "The question the prototype answers, in one short line. Shown as the lede under the title — keep it tight, not a paragraph.",
+    ),
+  goal: z.string().optional().describe("Alias for brief."),
+  source: planSourceSchema.optional().default("manual"),
+  repoPath: z.string().optional().describe("Repository path for the run"),
+  currentFocus: z
+    .string()
+    .optional()
+    .describe("Current prototype review focus"),
+  status: planStatusSchema.optional().default("review"),
+  content: planContentSchema.optional().describe(CONTENT_DESCRIPTION),
+  screens: z
+    .array(prototypeScreenSchema)
+    .optional()
+    .default([])
+    .describe(
+      "Prototype screens. Default to one functional screen when local UI behavior is enough; use 2-4 screens only for true routes/steps. Screen HTML should include working local controls, inputs, toggles, lists, filters, or lightweight flows where relevant.",
+    ),
+  transitions: z
+    .array(prototypeTransitionSchema)
+    .optional()
+    .default([])
+    .describe(
+      "Expected screen/route transitions. The viewer also honors data-goto attributes in screen HTML, but ordinary UI state should stay inside the functional prototype.",
+    ),
+  implementationNotes: z
+    .string()
+    .optional()
+    .describe("Concise notes for the implementation map section"),
+  markdown: z
+    .string()
+    .optional()
+    .describe("Markdown/text fallback or source visual plan"),
+  sections: z
+    .array(sectionInputSchema)
+    .optional()
+    .default([])
+    .describe("Optional legacy plan sections"),
+  comments: z
+    .array(commentInputSchema)
+    .optional()
+    .default([])
+    .describe("Initial annotations or review prompts"),
+});
+
 export default defineAction({
   description:
     "Create a plan whose primary review surface is a running interactive prototype. For a document-first plan use create-visual-plan; for a UI-first wireframe canvas use create-ui-plan; for a recap of an existing diff use create-visual-recap; for full-fidelity branded design use create-plan-design. Prototype screen HTML uses safe Alpine-like directives for local state and data-goto for screen navigation only. Publish via this tool; never deliver the plan as inline chat text.",
-  schema: z
-    .object({
-      title: z.string().optional().describe("Short visual plan title"),
-      brief: z
-        .string()
-        .optional()
-        .describe(
-          "The question the prototype answers, in one short line. Shown as the lede under the title — keep it tight, not a paragraph.",
-        ),
-      goal: z.string().optional().describe("Alias for brief."),
-      source: planSourceSchema.optional().default("manual"),
-      repoPath: z.string().optional().describe("Repository path for the run"),
-      currentFocus: z
-        .string()
-        .optional()
-        .describe("Current prototype review focus"),
-      status: planStatusSchema.optional().default("review"),
-      content: planContentSchema
-        .optional()
-        .describe(
-          "Full structured content when the caller has already authored a prototype. Prefer screens/transitions unless replacing the whole document.",
-        ),
-      screens: z
-        .array(prototypeScreenSchema)
-        .optional()
-        .default([])
-        .describe(
-          "Prototype screens. Default to one functional screen when local UI behavior is enough; use 2-4 screens only for true routes/steps. Screen HTML should include working local controls, inputs, toggles, lists, filters, or lightweight flows where relevant.",
-        ),
-      transitions: z
-        .array(prototypeTransitionSchema)
-        .optional()
-        .default([])
-        .describe(
-          "Expected screen/route transitions. The viewer also honors data-goto attributes in screen HTML, but ordinary UI state should stay inside the functional prototype.",
-        ),
-      implementationNotes: z
-        .string()
-        .optional()
-        .describe("Concise notes for the implementation map section"),
-      markdown: z
-        .string()
-        .optional()
-        .describe("Markdown/text fallback or source visual plan"),
-      sections: z
-        .array(sectionInputSchema)
-        .optional()
-        .default([])
-        .describe("Optional legacy plan sections"),
-      comments: z
-        .array(commentInputSchema)
-        .optional()
-        .default([])
-        .describe("Initial annotations or review prompts"),
-    })
-    .refine((args) => Boolean(args.brief || args.goal), {
-      message: "Either brief or goal is required.",
-    }),
+  schema: createPrototypePlanSchema.refine(
+    (args) => Boolean(args.brief || args.goal),
+    { message: "Either brief or goal is required." },
+  ),
+  // ADVERTISED-ONLY: same top-level shape, but `content` swaps the deep
+  // per-block-type union for a compact `type`-enum stand-in. Runtime
+  // validation always runs the full schema above — see the `actions` skill.
+  agentInputSchema: createPrototypePlanSchema.extend({
+    content: agentPlanContentSchema.optional().describe(CONTENT_DESCRIPTION),
+  }),
   publicAgent: {
     expose: true,
     readOnly: false,