@agent-native/core 0.99.3 → 0.100.1

package/corpus/templates/mail/server/db/schema.ts

@@ -1,5 +1,22 @@
 import { table, text, integer } from "@agent-native/core/db/schema";
 
+/**
+ * Short-lived, owner-scoped continuation state for the external Mail
+ * inventory. It intentionally contains compact metadata only; credentials,
+ * bodies, HTML and attachments never enter this table.
+ */
+export const mailInventoryCursors = table("mail_inventory_cursors", {
+  id: text("id").primaryKey(),
+  ownerEmail: text("owner_email").notNull(),
+  queryFingerprint: text("query_fingerprint").notNull(),
+  state: text("state").notNull(),
+  version: integer("version").notNull().default(1),
+  claimId: text("claim_id"),
+  claimedAt: integer("claimed_at"),
+  expiresAt: integer("expires_at").notNull(),
+  updatedAt: integer("updated_at").notNull(),
+});
+
 export const scheduledJobs = table("scheduled_jobs", {
   id: text("id").primaryKey(),
   type: text("type", { enum: ["snooze", "send_later"] }).notNull(),

package/corpus/templates/mail/server/lib/google-auth.ts

@@ -375,12 +375,23 @@ export async function getClients(
  * handler uses this to return a 502 with the underlying reason instead
  * of silently rendering an empty inbox.
  */
-export async function getClientsWithErrors(forEmail?: string): Promise<{
+export async function getClientsWithErrors(
+  forEmail?: string,
+  accountEmails?: string[],
+): Promise<{
   clients: Array<{ email: string; accessToken: string; refreshToken: string }>;
   errors: Array<{ email: string; error: string }>;
 }> {
   if (!forEmail) return { clients: [], errors: [] };
-  const accounts = await listOAuthAccountsByOwner("google", forEmail);
+  const requested = accountEmails
+    ? new Set(accountEmails.map((email) => email.toLowerCase()))
+    : null;
+  // Filtering happens before getValidAccessToken. This is important: token
+  // refreshes are writes and an explicitly scoped inventory read must not
+  // refresh unrelated accounts.
+  const accounts = (await listOAuthAccountsByOwner("google", forEmail)).filter(
+    (account) => !requested || requested.has(account.accountId.toLowerCase()),
+  );
 
   const clients: Array<{
     email: string;
@@ -571,6 +582,13 @@ type ListOptions = {
    * without hydrating a large metadata ranking window on every inbox poll.
    */
   threadRecentMessageCandidateLimit?: number;
+  /**
+   * Restrict this read before OAuth refreshes or provider calls.  This is
+   * deliberately an account-id allow-list rather than a post-fetch filter:
+   * a Mail user can have several connected inboxes and an explicitly scoped
+   * read must not wake up the others.
+   */
+  accountEmails?: string[];
 };
 
 const LIST_CACHE_TTL = 45_000;
@@ -791,6 +809,10 @@ async function fetchThreadBatchWithRefill(
     }
   }
 
+  if (batchResults.some((result) => !result.data)) {
+    throw new Error("Gmail thread metadata response was incomplete");
+  }
+
   return batchResults;
 }
 
@@ -852,7 +874,11 @@ function listCacheKey(
         .join("|")
     : "";
   const queryPart = query === undefined ? "<default>" : query;
-  return `${forEmail ?? ""}::${queryPart}::${maxResults}::${tokenPart}::${options?.mode ?? "messages"}::${options?.threadFormat ?? ""}::${options?.messageFormat ?? ""}::${options?.threadCandidateLimit ?? ""}::${options?.threadRecentMessageCandidateLimit ?? ""}`;
+  const accounts = options?.accountEmails
+    ?.map((email) => email.toLowerCase())
+    .sort()
+    .join(",");
+  return `${forEmail ?? ""}::${queryPart}::${maxResults}::${tokenPart}::${options?.mode ?? "messages"}::${options?.threadFormat ?? ""}::${options?.messageFormat ?? ""}::${options?.threadCandidateLimit ?? ""}::${options?.threadRecentMessageCandidateLimit ?? ""}::${accounts ?? ""}`;
 }
 
 export async function listGmailMessages(
@@ -1542,8 +1568,10 @@ async function listGmailMessagesUncached(
   pageTokens?: Record<string, string>,
   options?: ListOptions,
 ): Promise<ListResult> {
-  const { clients, errors: refreshErrors } =
-    await getClientsWithErrors(forEmail);
+  const { clients, errors: refreshErrors } = await getClientsWithErrors(
+    forEmail,
+    options?.accountEmails,
+  );
   // Seed the per-fetch error list with refresh failures so a fully-dead
   // connection (every account's refresh_token revoked or invalidated by a
   // GOOGLE_CLIENT_ID rotation) reaches the handler — otherwise the list

package/corpus/templates/mail/server/lib/inventory-cursor.ts

@@ -0,0 +1,406 @@
+import { createHash } from "node:crypto";
+
+import { and, eq, gt, lt, or, sql } from "drizzle-orm";
+
+import { getDb } from "../db/index.js";
+import { mailInventoryCursors } from "../db/schema.js";
+
+const TTL_MS = 10 * 60 * 1000;
+const CLAIM_TTL_MS = 60 * 1000;
+const PAGE_ITEMS_BUDGET_BYTES = 12 * 1024;
+
+export interface MailInventoryItem {
+  id: string;
+  threadId: string;
+  accountEmail: string;
+  date: string;
+  from: { name?: string; email: string };
+  subject: string;
+  isUnread: boolean;
+  isStarred?: boolean;
+  messageCount: number;
+  unreadCount: number;
+  snippet?: string;
+}
+
+export interface MailInventoryError {
+  code: string;
+  message: string;
+  retryable: boolean;
+}
+
+export interface MailInventoryAccountState {
+  accountEmail: string;
+  status: "ok" | "error";
+  error?: MailInventoryError;
+  providerPageToken?: string;
+  exhausted: boolean;
+  pending: MailInventoryItem[];
+  emittedCount: number;
+  /** Unique rows discovered so coverage remains visible before emission. */
+  knownCount?: number;
+  /** Account-local thread ids already emitted by an earlier output page. */
+  emittedThreadIds?: string[];
+}
+
+export interface MailInventoryCursorState {
+  queryFingerprint: string;
+  requestedAccounts: string[] | null;
+  accounts: MailInventoryAccountState[];
+  firstPage: boolean;
+}
+
+export interface MailInventoryCursorClaim {
+  id: string;
+  claimId: string;
+  ownerEmail: string;
+  queryFingerprint: string;
+  version: number;
+  state: MailInventoryCursorState;
+}
+
+export interface MailInventoryFetchResult {
+  items: MailInventoryItem[];
+  errors: Record<string, MailInventoryError>;
+  nextPageTokens: Record<string, string>;
+}
+
+function stableValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, child]) => [key, stableValue(child)]),
+    );
+  }
+  return value;
+}
+
+export function inventoryQueryFingerprint(input: unknown): string {
+  return createHash("sha256")
+    .update(JSON.stringify(stableValue(input)))
+    .digest("hex");
+}
+
+export function compareInventoryItems(
+  a: MailInventoryItem,
+  b: MailInventoryItem,
+): number {
+  const date = new Date(b.date).getTime() - new Date(a.date).getTime();
+  if (date) return date;
+  const account = a.accountEmail.localeCompare(b.accountEmail);
+  if (account) return account;
+  const thread = a.threadId.localeCompare(b.threadId);
+  if (thread) return thread;
+  return a.id.localeCompare(b.id);
+}
+
+function dedupeAndSort(items: MailInventoryItem[]): MailInventoryItem[] {
+  const unique = new Map<string, MailInventoryItem>();
+  for (const item of items) {
+    const key = `${item.accountEmail.toLowerCase()}:${item.threadId}`;
+    const current = unique.get(key);
+    if (!current || compareInventoryItems(item, current) < 0) {
+      unique.set(key, item);
+    }
+  }
+  return [...unique.values()].sort(compareInventoryItems);
+}
+
+function applyFetch(
+  states: MailInventoryAccountState[],
+  result: MailInventoryFetchResult,
+): void {
+  const byAccount = new Map<string, MailInventoryItem[]>();
+  for (const item of result.items) {
+    const key = item.accountEmail.toLowerCase();
+    const accountItems = byAccount.get(key) ?? [];
+    accountItems.push(item);
+    byAccount.set(key, accountItems);
+  }
+
+  for (const state of states) {
+    const key = state.accountEmail.toLowerCase();
+    const error = result.errors[key];
+    if (error) {
+      state.status = "error";
+      state.error = error;
+      state.exhausted = true;
+      state.providerPageToken = undefined;
+      continue;
+    }
+    const emitted = new Set(state.emittedThreadIds ?? []);
+    const before = new Set(
+      state.pending.map((item) => item.threadId).concat([...emitted]),
+    );
+    const additions = (byAccount.get(key) ?? []).filter(
+      (item) => !before.has(item.threadId),
+    );
+    state.knownCount =
+      (state.knownCount ?? state.emittedCount) + additions.length;
+    state.pending = dedupeAndSort([...state.pending, ...additions]);
+    state.providerPageToken = result.nextPageTokens[key];
+    state.exhausted = !state.providerPageToken;
+  }
+}
+
+export async function buildMailInventoryPage(
+  state: MailInventoryCursorState,
+  limit: number,
+  fetch: (
+    accounts: Array<{ accountEmail: string; pageToken?: string }>,
+  ) => Promise<MailInventoryFetchResult>,
+): Promise<{ items: MailInventoryItem[]; hasMore: boolean }> {
+  const pageLimit = Math.max(1, Math.min(Math.floor(limit), 100));
+  const refillCounts = new Map<string, number>();
+  const refillFrontiers = async () => {
+    while (true) {
+      const needsFetch = state.accounts.filter(
+        (account) =>
+          account.status === "ok" &&
+          account.pending.length === 0 &&
+          !account.exhausted,
+      );
+      if (needsFetch.length === 0) return;
+      const fetchable = needsFetch.filter((account) => {
+        const key = account.accountEmail.toLowerCase();
+        const count = refillCounts.get(key) ?? 0;
+        if (count < 4) {
+          refillCounts.set(key, count + 1);
+          return true;
+        }
+        account.status = "error";
+        account.error = {
+          code: "pagination_limit",
+          message:
+            "Mail pagination did not expose a row frontier within four provider pages.",
+          retryable: true,
+        };
+        account.exhausted = true;
+        account.providerPageToken = undefined;
+        return false;
+      });
+      if (fetchable.length === 0) continue;
+      const prior = fetchable.map((account) => ({
+        account,
+        token: account.providerPageToken,
+      }));
+      applyFetch(
+        fetchable,
+        await fetch(
+          fetchable.map((account) => ({
+            accountEmail: account.accountEmail,
+            pageToken: account.providerPageToken,
+          })),
+        ),
+      );
+      for (const { account, token } of prior) {
+        if (
+          account.status === "ok" &&
+          !account.exhausted &&
+          account.pending.length === 0 &&
+          account.providerPageToken === token
+        ) {
+          throw new Error(
+            `Mail provider pagination made no progress for ${account.accountEmail}.`,
+          );
+        }
+      }
+    }
+  };
+
+  const page: MailInventoryItem[] = [];
+  const emittedKeys = new Set<string>();
+  let pageBytes = 2; // JSON array brackets
+  const emit = (
+    account: MailInventoryAccountState,
+    item: MailInventoryItem,
+  ) => {
+    const key = `${item.accountEmail.toLowerCase()}:${item.threadId}`;
+    if (emittedKeys.has(key)) return;
+    emittedKeys.add(key);
+    page.push(item);
+    account.emittedCount += 1;
+    account.emittedThreadIds = [
+      ...(account.emittedThreadIds ?? []),
+      item.threadId,
+    ];
+  };
+
+  while (page.length < pageLimit) {
+    // A global merge is only safe when every live account has a known
+    // frontier. Refill an emptied account before emitting an older candidate
+    // from another account; otherwise an unseen newer provider row can be
+    // skipped across the page boundary.
+    await refillFrontiers();
+    const candidates = state.accounts
+      .filter((account) => account.pending.length > 0)
+      .map((account) => ({ account, item: account.pending[0] }))
+      .sort((a, b) => compareInventoryItems(a.item, b.item));
+    if (candidates.length === 0) {
+      break;
+    }
+    const winner = candidates[0];
+    const itemBytes = new TextEncoder().encode(
+      JSON.stringify(winner.item),
+    ).byteLength;
+    if (
+      page.length > 0 &&
+      pageBytes + itemBytes + 1 > PAGE_ITEMS_BUDGET_BYTES
+    ) {
+      break;
+    }
+    winner.account.pending.shift();
+    emit(winner.account, winner.item);
+    pageBytes += itemBytes + (page.length > 1 ? 1 : 0);
+  }
+
+  page.sort(compareInventoryItems);
+  state.firstPage = false;
+  return {
+    items: page,
+    hasMore: state.accounts.some(
+      (account) => account.pending.length > 0 || !account.exhausted,
+    ),
+  };
+}
+
+export async function createInventoryCursor(
+  ownerEmail: string,
+  state: MailInventoryCursorState,
+): Promise<string> {
+  const now = Date.now();
+  const id = crypto.randomUUID();
+  await getDb()
+    .insert(mailInventoryCursors)
+    .values({
+      id,
+      ownerEmail,
+      queryFingerprint: state.queryFingerprint,
+      state: JSON.stringify(state),
+      version: 1,
+      expiresAt: now + TTL_MS,
+      updatedAt: now,
+    });
+  await getDb()
+    .delete(mailInventoryCursors)
+    .where(lt(mailInventoryCursors.expiresAt, now));
+  return id;
+}
+
+/**
+ * Atomically leases a cursor without consuming it. Provider work happens only
+ * after this short-lived CAS. Failures can release the lease; success settles
+ * it into a distinct successor id (or deletes it at exhaustion).
+ */
+export async function claimInventoryCursor(
+  ownerEmail: string,
+  id: string,
+  queryFingerprint: string,
+): Promise<MailInventoryCursorClaim | null> {
+  const now = Date.now();
+  const claimId = crypto.randomUUID();
+  const staleBefore = now - CLAIM_TTL_MS;
+  const rows = await getDb()
+    .update(mailInventoryCursors)
+    .set({ claimId, claimedAt: now, updatedAt: now })
+    .where(
+      and(
+        eq(mailInventoryCursors.id, id),
+        eq(mailInventoryCursors.ownerEmail, ownerEmail),
+        eq(mailInventoryCursors.queryFingerprint, queryFingerprint),
+        gt(mailInventoryCursors.expiresAt, now),
+        or(
+          sql`${mailInventoryCursors.claimId} IS NULL`,
+          lt(mailInventoryCursors.claimedAt, staleBefore),
+        ),
+      ),
+    )
+    .returning({
+      state: mailInventoryCursors.state,
+      expiresAt: mailInventoryCursors.expiresAt,
+      version: mailInventoryCursors.version,
+    });
+  const row = rows[0];
+  if (!row || row.expiresAt <= now) return null;
+  try {
+    return {
+      id,
+      claimId,
+      ownerEmail,
+      queryFingerprint,
+      version: row.version,
+      state: JSON.parse(row.state) as MailInventoryCursorState,
+    };
+  } catch {
+    await releaseInventoryCursorClaim({
+      id,
+      claimId,
+      ownerEmail,
+      queryFingerprint,
+      version: row.version,
+      state: {} as MailInventoryCursorState,
+    });
+    return null;
+  }
+}
+
+export async function releaseInventoryCursorClaim(
+  claim: MailInventoryCursorClaim,
+): Promise<void> {
+  await getDb()
+    .update(mailInventoryCursors)
+    .set({ claimId: null, claimedAt: null, updatedAt: Date.now() })
+    .where(
+      and(
+        eq(mailInventoryCursors.id, claim.id),
+        eq(mailInventoryCursors.ownerEmail, claim.ownerEmail),
+        eq(mailInventoryCursors.queryFingerprint, claim.queryFingerprint),
+        eq(mailInventoryCursors.version, claim.version),
+        eq(mailInventoryCursors.claimId, claim.claimId),
+      ),
+    );
+}
+
+/** Atomically consumes a leased id and optionally creates its successor. */
+export async function settleInventoryCursorClaim(
+  claim: MailInventoryCursorClaim,
+  state: MailInventoryCursorState,
+  hasMore: boolean,
+): Promise<string | undefined> {
+  const db = getDb();
+  const successorId = hasMore ? crypto.randomUUID() : undefined;
+  const now = Date.now();
+  return db.transaction(async (tx: any) => {
+    const consumed = await tx
+      .delete(mailInventoryCursors)
+      .where(
+        and(
+          eq(mailInventoryCursors.id, claim.id),
+          eq(mailInventoryCursors.ownerEmail, claim.ownerEmail),
+          eq(mailInventoryCursors.queryFingerprint, claim.queryFingerprint),
+          eq(mailInventoryCursors.version, claim.version),
+          eq(mailInventoryCursors.claimId, claim.claimId),
+        ),
+      )
+      .returning({ id: mailInventoryCursors.id });
+    if (consumed.length !== 1) {
+      throw new Error("Inventory cursor lease was lost before settlement.");
+    }
+    if (successorId) {
+      await tx.insert(mailInventoryCursors).values({
+        id: successorId,
+        ownerEmail: claim.ownerEmail,
+        queryFingerprint: claim.queryFingerprint,
+        state: JSON.stringify(state),
+        version: claim.version + 1,
+        claimId: null,
+        claimedAt: null,
+        expiresAt: now + TTL_MS,
+        updatedAt: now,
+      });
+    }
+    return successorId;
+  });
+}

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

@@ -45,7 +45,11 @@ export interface ListInboxEmailsParams {
   pageTokens?: Record<string, string>;
   threadFormat?: "full" | "metadata" | "minimal";
   threadCandidateLimit?: number;
+  /** Disable the extra recent-message candidate pass for bounded inventory. */
+  includeRecentMessageCandidates?: boolean;
   accountTokens: ListInboxEmailsAccountToken[];
+  /** Selected account ids are forwarded to Gmail before token refresh. */
+  accountEmails?: string[];
   labelMap: Map<string, string>;
 }
 
@@ -108,7 +112,9 @@ export async function listInboxEmails(
     pageTokens,
     threadFormat,
     threadCandidateLimit,
+    includeRecentMessageCandidates = true,
     accountTokens,
+    accountEmails,
     labelMap,
   } = params;
 
@@ -123,12 +129,25 @@ export async function listInboxEmails(
       threadFormat,
       threadCandidateLimit,
       threadRecentMessageCandidateLimit:
-        !q && (view === "inbox" || view === "unread")
+        includeRecentMessageCandidates &&
+        !q &&
+        (view === "inbox" || view === "unread")
           ? DEFAULT_THREAD_RECENT_MESSAGE_CANDIDATE_LIMIT
           : undefined,
+      accountEmails,
     });
 
-  if (messages.length === 0 && errors.length > 0) {
+  const failedAccounts = new Set(
+    errors.map((error) => error.email.toLowerCase()),
+  );
+  const everySelectedAccountFailed = [...connectedEmails].every((email) =>
+    failedAccounts.has(email),
+  );
+  if (
+    messages.length === 0 &&
+    errors.length > 0 &&
+    everySelectedAccountFailed
+  ) {
     const isQuotaError = errors.every((e) => isGmailQuotaError(e.error));
     return {
       ok: false,

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

@@ -0,0 +1,8 @@
+/**
+ * Deliberately narrow authenticated MCP surface for Mail.
+ *
+ * External callers may read inbox coverage through list-emails. 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 MAIL_CONNECTOR_CATALOG = ["list-emails"] as const;

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

@@ -6,6 +6,7 @@ import {
 } from "@agent-native/core/server";
 
 import actionsRegistry from "../../.generated/actions-registry.js";
+import { MAIL_CONNECTOR_CATALOG } from "../lib/mail-connector-catalog.js";
 
 const INITIAL_TOOL_NAMES = [
   "view-screen",
@@ -33,6 +34,7 @@ export default createAgentChatPlugin({
   actions: loadActionsFromStaticRegistry(actionsRegistry),
   appId: "mail",
   initialToolNames: INITIAL_TOOL_NAMES,
+  connectorCatalog: [...MAIL_CONNECTOR_CATALOG],
   resolveOrgId: async (event) => {
     const ctx = await getOrgContext(event);
     return ctx.orgId;
@@ -90,16 +92,9 @@ export default createAgentChatPlugin({
 
 Some less-common tool schemas are loaded on demand. Use tool-search with a specific query when you need a capability that is not already available as a direct tool.
 
-## Google Connection Check — CRITICAL
+## Deterministic Mail Reads
 
-BEFORE doing anything else, run view-screen to check if Google is connected.
-If view-screen shows 0 emails or indicates Google is not connected:
-- Do NOT run list-emails, search-emails, send-email, or any email operation scripts
-- Do NOT pretend to have access to emails
-- Tell the user: "You need to connect your Google account first. Click the 'Connect Google' button on the main screen to get started."
-- You can still answer general questions, but you cannot perform any email operations
-
-Only proceed with email operations if view-screen confirms real emails are available.
+For deterministic headless email reads, call list-emails directly in inventory/coverage mode. Do not require view-screen as a Google connection preflight: list-emails selects the connected Gmail or synthetic local-mail backend for the user and returns the relevant result. Use view-screen only when the answer depends on visible UI state, such as the active thread, selected message, draft, queue item, or current inbox view. Treat real action errors as the evidence for an unavailable connection; do not infer it from a zero-email screen.
 
 Available operations:
 - List and search emails

package/corpus/templates/mail/server/plugins/db.ts

@@ -188,6 +188,26 @@ CREATE INDEX IF NOT EXISTS idx_snippets_owner_name ON snippets(owner_email, name
       sql: `ALTER TABLE queued_email_drafts ADD COLUMN IF NOT EXISTS send_claim_id TEXT;
 ALTER TABLE queued_email_drafts ADD COLUMN IF NOT EXISTS send_claimed_at ${intType()}`,
     },
+    {
+      version: 18,
+      name: "mail-inventory-cursors",
+      sql: `CREATE TABLE IF NOT EXISTS mail_inventory_cursors (
+    id TEXT PRIMARY KEY,
+    owner_email TEXT NOT NULL,
+    query_fingerprint TEXT NOT NULL,
+    state TEXT NOT NULL,
+    version ${intType()} NOT NULL DEFAULT 1,
+    expires_at ${intType()} NOT NULL,
+    updated_at ${intType()} NOT NULL
+  );
+CREATE INDEX IF NOT EXISTS idx_mail_inventory_cursors_owner_expiry ON mail_inventory_cursors(owner_email, expires_at);`,
+    },
+    {
+      version: 19,
+      name: "mail-inventory-cursor-leases",
+      sql: `ALTER TABLE mail_inventory_cursors ADD COLUMN IF NOT EXISTS claim_id TEXT;
+ALTER TABLE mail_inventory_cursors ADD COLUMN IF NOT EXISTS claimed_at ${intType()}`,
+    },
   ],
   { table: "mail_migrations" },
 );

package/corpus/templates/plan/app/components/layout/Header.tsx

@@ -11,6 +11,7 @@ import { APP_TITLE } from "@/lib/app-config";
 const pageTitleKeys: Record<string, string> = {
   "/": "header.plan",
   "/plans": "header.plan",
+  "/agent": "settings.agentTitle",
   "/settings": "header.settings",
 };
 

package/corpus/templates/plan/app/components/layout/Layout.tsx

@@ -204,6 +204,7 @@ export function Layout({ children }: LayoutProps) {
             chatViewTransition
             storageKey="plans"
             openOnChatRunning={chatHomeHandoffActive}
+            agentPageHref="/agent"
             emptyStateText={t("agent.emptyState")}
             suggestions={[
               t("agent.suggestionShipped"),

package/corpus/templates/plan/app/components/layout/Sidebar.tsx

@@ -18,6 +18,7 @@ import { ExtensionsSidebarSection } from "@agent-native/core/client/extensions";
 import { OrgSwitcher } from "@agent-native/core/client/org";
 import {
   IconArchive,
+  IconBrain,
   IconClipboardCheck,
   IconDots,
   IconEdit,
@@ -87,6 +88,7 @@ function buildBrandingCustomizationMessage(request: string) {
 const navItems = [
   { icon: IconMessageCircle, labelKey: "navigation.ask", href: "/" },
   { icon: IconClipboardCheck, labelKey: "navigation.plan", href: "/plans" },
+  { icon: IconBrain, labelKey: "settings.agentTitle", href: "/agent" },
   { icon: IconSettings, labelKey: "navigation.settings", href: "/settings" },
 ];
 

package/corpus/templates/plan/app/root.tsx

@@ -13,6 +13,7 @@ import {
 } from "@agent-native/core/client";
 import { configureTracking } from "@agent-native/core/client";
 import {
+  IconBrain,
   IconMoon,
   IconScribble,
   IconShape2,
@@ -176,6 +177,13 @@ function AppContent() {
           <CommandMenu.Item onSelect={() => go("/recaps")}>
             {t("root.openRecaps")}
           </CommandMenu.Item>
+          <CommandMenu.Item
+            onSelect={() => go("/agent")}
+            keywords={["agent", "context", "connections", "jobs", "access"]}
+          >
+            <IconBrain size={16} />
+            {t("settings.openAgentSettings")}
+          </CommandMenu.Item>
         </CommandMenu.Group>
         <CommandMenu.Group heading={t("root.commandAppearance")}>
           <CommandMenu.Item