Fix false auth_required for Google Calendar WhoAmI (#37)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: teallarson

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcadeai/create-agent",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "type": "module",
   "description": "Scaffold an Arcade-powered AI agent",
   "license": "MIT",

templates/_shared/nextjs-ui/app/dashboard/page.tsx

@@ -14,6 +14,9 @@ import { useArcadeConnection } from "@/hooks/use-arcade-connection";
 import { useSourceCheck } from "@/hooks/use-source-check";
 import { usePlanStream } from "@/hooks/use-plan-stream";
 import {
+  Alert,
+  AlertTitle,
+  AlertDescription,
   Skeleton,
   Button,
   Card,
@@ -22,7 +25,7 @@ import {
   CardHeader,
   CardTitle,
 } from "@arcadeai/design-system";
-import { Loader2, ShieldAlert, AlertTriangle, RotateCcw } from "lucide-react";
+import { Info, Loader2, ShieldAlert, AlertTriangle, RotateCcw } from "lucide-react";
 
 // --- Config health warnings ---
 
@@ -209,6 +212,15 @@ function DashboardContent() {
                 >
                   I've already signed in — retry
                 </button>
+                <Alert className="text-left">
+                  <Info className="size-4" />
+                  <AlertTitle>Why Arcade?</AlertTitle>
+                  <AlertDescription>
+                    The agent uses Arcade as an MCP Gateway to read from your tools on your behalf.
+                    Signing in here links your Arcade identity so the gateway knows which
+                    user&apos;s tools to access.
+                  </AlertDescription>
+                </Alert>
               </CardContent>
             </Card>
           )}
@@ -313,6 +325,19 @@ function DashboardContent() {
 
           {loading && !hasItems && authUrls.length === 0 && (
             <div className="space-y-6">
+              <Alert>
+                <Info className="size-4" />
+                <AlertTitle>What&apos;s happening</AlertTitle>
+                <AlertDescription>
+                  The agent is reading from your connected sources and classifying what it finds.
+                  This behavior is driven by the system prompt in{" "}
+                  <code className="rounded bg-muted px-1 py-0.5 text-xs">
+                    app/api/plan/route.ts
+                  </code>{" "}
+                  — edit it to change what gets fetched, how items are prioritized, or what the
+                  agent focuses on.
+                </AlertDescription>
+              </Alert>
               <div className="grid grid-cols-1 gap-4 sm:grid-cols-3">
                 {Array.from({ length: 3 }).map((_, i) => (
                   <Skeleton key={i} className="h-24 rounded-xl" />
@@ -343,6 +368,19 @@ function DashboardContent() {
                   )}
                 </Button>
               </div>
+              <Alert>
+                <Info className="size-4" />
+                <AlertTitle>Make it yours</AlertTitle>
+                <AlertDescription>
+                  Start with the system prompt in{" "}
+                  <code className="rounded bg-muted px-1 py-0.5 text-xs">
+                    app/api/plan/route.ts
+                  </code>{" "}
+                  — that&apos;s where the agent&apos;s behavior is defined. From there, check out{" "}
+                  <code className="rounded bg-muted px-1 py-0.5 text-xs">AGENT_PLAYBOOK.md</code>{" "}
+                  for a full walkthrough of customization points.
+                </AlertDescription>
+              </Alert>
               <StatsBar
                 stats={stats}
                 activeSource={activeSource}

templates/_shared/nextjs-ui/components/auth/login-form.tsx

@@ -4,6 +4,9 @@ import { useRef, useState } from "react";
 import { useRouter } from "next/navigation";
 import { authClient } from "@/lib/auth-client";
 import {
+  Alert,
+  AlertTitle,
+  AlertDescription,
   Button,
   Card,
   CardContent,
@@ -12,6 +15,7 @@ import {
   Input,
   Label,
 } from "@arcadeai/design-system";
+import { Info } from "lucide-react";
 
 export function LoginForm() {
   const router = useRouter();
@@ -65,6 +69,15 @@ export function LoginForm() {
         </svg>
         <span className="text-xl font-semibold tracking-tight">Arcade Agent</span>
       </div>
+      <Alert className="mb-4 w-full max-w-sm">
+        <Info className="size-4" />
+        <AlertTitle>Two separate sign-ins</AlertTitle>
+        <AlertDescription>
+          This creates a local account for your agent app — it&apos;s just for session management
+          and stays in your own database. You&apos;ll connect your Arcade account on the next screen
+          to give the agent access to your tools.
+        </AlertDescription>
+      </Alert>
       <Card className="w-full max-w-sm">
         <CardHeader className="pb-2">
           <div className="mb-3 flex rounded-lg bg-muted p-1">

templates/_shared/nextjs-ui/components/dashboard/empty-state.tsx

@@ -1,7 +1,5 @@
-"use client";
-
-import { Inbox, Loader2 } from "lucide-react";
-import { Button } from "@arcadeai/design-system";
+import { Inbox, Info, Loader2 } from "lucide-react";
+import { Alert, AlertTitle, AlertDescription, Button } from "@arcadeai/design-system";
 
 interface EmptyStateProps {
   onPlan: () => void;
@@ -21,6 +19,17 @@ export function EmptyState({ onPlan, loading }: EmptyStateProps) {
           build your action plan.
         </p>
       </div>
+      <Alert className="max-w-md text-left">
+        <Info className="size-4" />
+        <AlertTitle>How this works</AlertTitle>
+        <AlertDescription>
+          When you click &ldquo;Plan my day&rdquo;, the agent connects to your Slack, Gmail, Google
+          Calendar, Linear, and GitHub through Arcade&apos;s MCP Gateway. It will first check if any
+          of those need authentication — if so, you&apos;ll be prompted to authorize before the run
+          starts. Then it reads your recent messages, emails, events, issues, and pull requests, and
+          classifies each item by priority and suggests next steps.
+        </AlertDescription>
+      </Alert>
       <Button size="lg" disabled={loading} onClick={onPlan}>
         {loading ? (
           <>

templates/_shared/nextjs-ui/components/dashboard/source-auth-gate.tsx

@@ -1,7 +1,5 @@
-"use client";
-
-import { Check, ArrowUpRight } from "lucide-react";
-import { Button } from "@arcadeai/design-system";
+import { Check, ArrowUpRight, Info } from "lucide-react";
+import { Alert, AlertTitle, AlertDescription, Button } from "@arcadeai/design-system";
 import type { SourceStatus } from "@/types/inbox";
 import { getSource } from "@/lib/sources";
 
@@ -36,6 +34,16 @@ export function SourceAuthGate({
         </p>
       </div>
 
+      <Alert className="mb-6">
+        <Info className="size-4" />
+        <AlertTitle>Why authorize?</AlertTitle>
+        <AlertDescription>
+          Each tool connects on your behalf using OAuth — the agent only gets read access to scan
+          for items to triage. You can skip any source you don&apos;t use, and revoke access anytime
+          from your Arcade dashboard.
+        </AlertDescription>
+      </Alert>
+
       <div className="mb-6 space-y-2">
         {Object.entries(sourceStatuses).map(([source, status]) => {
           const config = getSource(source);

templates/_shared/partials/extract-auth-url.hbs

@@ -1,23 +1,14 @@
 function extractAuthUrlFromToolOutput(output: unknown): string | null {
-  const looksLikeAuthUrl = (value: unknown): value is string =>
-    typeof value === "string" &&
-    /oauth|authorize/i.test(value);
-
   const fromRecord = (value: unknown): string | null => {
     if (!value || typeof value !== "object") return null;
     const obj = value as Record<string, unknown>;
-    const direct =
-      (typeof obj.authorization_url === "string" && obj.authorization_url) ||
-      (looksLikeAuthUrl(obj.url) ? obj.url : null);
-    if (direct) return direct;
+    if (typeof obj.authorization_url === "string" && obj.authorization_url)
+      return obj.authorization_url;
 
     if (obj.structuredContent && typeof obj.structuredContent === "object") {
       const nested = obj.structuredContent as Record<string, unknown>;
-      const nestedUrl =
-        (typeof nested.authorization_url === "string" &&
-          nested.authorization_url) ||
-        (looksLikeAuthUrl(nested.url) ? nested.url : null);
-      if (nestedUrl) return nestedUrl;
+      if (typeof nested.authorization_url === "string" && nested.authorization_url)
+        return nested.authorization_url;
     }
     return null;
   };

templates/langchain/app/routes/arcade.py

@@ -123,16 +123,14 @@ def _extract_auth_url_from_result(content: str) -> str | None:
     """Check if a tool result contains an Arcade authorization URL."""
     try:
         parsed = json.loads(content)
-        url = (
-            parsed.get("authorization_url")
-            or parsed.get("url")
-            or (parsed.get("structuredContent") or {}).get("authorization_url")
-        )
+        url = parsed.get("authorization_url") or (
+            parsed.get("structuredContent") or {}
+        ).get("authorization_url")
         if url:
             return url
     except (json.JSONDecodeError, AttributeError):
         pass
-    # Fallback: regex
+    # Fallback: regex — only match clear OAuth authorization endpoints
     match = re.search(
         r"https://[^\s\"'>\]]+/oauth/[^\s\"'>\]]+|https://[^\s\"'>\]]+authorize[^\s\"'>\]]*",
         content or "",

templates/langchain/app/templates/dashboard.html

@@ -120,6 +120,32 @@ <h2 class="text-lg font-semibold mb-2">Connect to Arcade</h2>
             I've already signed in &mdash; retry
           </button>
         </div>
+        <div
+          id="callout-why-arcade"
+          class="rounded-lg border border-border bg-card px-4 py-3 text-sm text-left mt-4"
+        >
+          <div class="flex items-start gap-3">
+            <svg
+              class="w-4 h-4 shrink-0 mt-0.5 text-foreground"
+              fill="none"
+              stroke="currentColor"
+              viewBox="0 0 24 24"
+              stroke-width="2"
+            >
+              <circle cx="12" cy="12" r="10" />
+              <path d="M12 16v-4" />
+              <path d="M12 8h.01" />
+            </svg>
+            <div class="flex-1">
+              <p class="font-medium text-foreground mb-1">Why Arcade?</p>
+              <p class="text-muted-foreground">
+                The agent uses Arcade as an MCP Gateway to read from your tools on your behalf.
+                Signing in here links your Arcade identity so the gateway knows which user's tools
+                to access.
+              </p>
+            </div>
+          </div>
+        </div>
         <div id="gate-auth-waiting" class="hidden">
           <div class="flex items-center justify-center gap-2 mb-3">
             <div
@@ -207,6 +233,34 @@ <h2 class="text-2xl font-semibold tracking-tight mb-2">Ready to triage?</h2>
             Your agent will scan your inbox, calendar, tasks, and PRs, then prioritize everything
             and build your action plan.
           </p>
+          <div
+            id="callout-how-it-works"
+            class="rounded-lg border border-border bg-card px-4 py-3 text-sm text-left max-w-md mt-2"
+          >
+            <div class="flex items-start gap-3">
+              <svg
+                class="w-4 h-4 shrink-0 mt-0.5 text-foreground"
+                fill="none"
+                stroke="currentColor"
+                viewBox="0 0 24 24"
+                stroke-width="2"
+              >
+                <circle cx="12" cy="12" r="10" />
+                <path d="M12 16v-4" />
+                <path d="M12 8h.01" />
+              </svg>
+              <div class="flex-1">
+                <p class="font-medium text-foreground mb-1">How this works</p>
+                <p class="text-muted-foreground">
+                  When you click "Plan my day", the agent connects to your Slack, Gmail, Google
+                  Calendar, Linear, and GitHub through Arcade's MCP Gateway. It will first check if
+                  any of those need authentication — if so, you'll be prompted to authorize before
+                  the run starts. Then it reads your recent messages, emails, events, issues, and
+                  pull requests, and classifies each item by priority and suggests next steps.
+                </p>
+              </div>
+            </div>
+          </div>
           <button
             id="plan-btn"
             class="px-6 py-3 bg-primary text-primary-foreground rounded-lg hover:bg-primary/90 disabled:bg-muted disabled:text-muted-foreground transition-colors font-medium"
@@ -217,6 +271,34 @@ <h2 class="text-2xl font-semibold tracking-tight mb-2">Ready to triage?</h2>
 
         <!-- Loading skeletons -->
         <div id="loading-skeletons" class="hidden space-y-6">
+          <div
+            id="callout-whats-happening"
+            class="rounded-lg border border-border bg-card px-4 py-3 text-sm text-left"
+          >
+            <div class="flex items-start gap-3">
+              <svg
+                class="w-4 h-4 shrink-0 mt-0.5 text-foreground"
+                fill="none"
+                stroke="currentColor"
+                viewBox="0 0 24 24"
+                stroke-width="2"
+              >
+                <circle cx="12" cy="12" r="10" />
+                <path d="M12 16v-4" />
+                <path d="M12 8h.01" />
+              </svg>
+              <div class="flex-1">
+                <p class="font-medium text-foreground mb-1">What's happening</p>
+                <p class="text-muted-foreground">
+                  The agent is reading from your connected sources and classifying what it finds.
+                  This behavior is driven by the system prompt in
+                  <code class="rounded bg-muted px-1 py-0.5 text-xs">app/system-prompt.md</code> —
+                  edit it to change what gets fetched, how items are prioritized, or what the agent
+                  focuses on.
+                </p>
+              </div>
+            </div>
+          </div>
           <div class="grid grid-cols-1 sm:grid-cols-3 gap-4">
             <div class="h-24 rounded-xl bg-muted animate-pulse"></div>
             <div class="h-24 rounded-xl bg-muted animate-pulse"></div>
@@ -248,6 +330,34 @@ <h2 class="text-lg font-semibold flex items-center gap-2">
               Replan my day
             </button>
           </div>
+          <div
+            id="callout-make-it-yours"
+            class="rounded-lg border border-border bg-card px-4 py-3 text-sm text-left"
+          >
+            <div class="flex items-start gap-3">
+              <svg
+                class="w-4 h-4 shrink-0 mt-0.5 text-foreground"
+                fill="none"
+                stroke="currentColor"
+                viewBox="0 0 24 24"
+                stroke-width="2"
+              >
+                <circle cx="12" cy="12" r="10" />
+                <path d="M12 16v-4" />
+                <path d="M12 8h.01" />
+              </svg>
+              <div class="flex-1">
+                <p class="font-medium text-foreground mb-1">Make it yours</p>
+                <p class="text-muted-foreground">
+                  Start with the system prompt in
+                  <code class="rounded bg-muted px-1 py-0.5 text-xs">app/system-prompt.md</code> —
+                  that's where the agent's behavior is defined. From there, check out
+                  <code class="rounded bg-muted px-1 py-0.5 text-xs">AGENT_PLAYBOOK.md</code> for a
+                  full walkthrough of customization points.
+                </p>
+              </div>
+            </div>
+          </div>
           <div id="task-container" class="space-y-3"></div>
         </div>
       </div>

templates/langchain/app/templates/login.html

@@ -10,6 +10,33 @@
       <span class="text-xl font-semibold tracking-tight">Arcade Agent</span>
     </div>
 
+    <div
+      id="callout-two-signins"
+      class="rounded-lg border border-border bg-card px-4 py-3 text-sm mb-4 w-full"
+    >
+      <div class="flex items-start gap-3">
+        <svg
+          class="w-4 h-4 shrink-0 mt-0.5 text-foreground"
+          fill="none"
+          stroke="currentColor"
+          viewBox="0 0 24 24"
+          stroke-width="2"
+        >
+          <circle cx="12" cy="12" r="10" />
+          <path d="M12 16v-4" />
+          <path d="M12 8h.01" />
+        </svg>
+        <div class="flex-1">
+          <p class="font-medium text-foreground mb-1">Two separate sign-ins</p>
+          <p class="text-muted-foreground">
+            This creates a local account for your agent app — it's just for session management and
+            stays in your own database. You'll connect your Arcade account on the next screen to
+            give the agent access to your tools.
+          </p>
+        </div>
+      </div>
+    </div>
+
     <div class="bg-card border border-border rounded-xl p-6 shadow-sm">
       <!-- Tab switcher -->
       <div class="mb-4 flex rounded-lg bg-muted p-1">