@agent-native/core 0.145.5 → 0.145.7

package/corpus/templates/analytics/server/lib/gong.ts

@@ -1,19 +1,14 @@
 // Gong sales call intelligence API helper
 // Fetches calls, transcripts, and users
 
-import { resolveCredential } from "./credentials";
-import {
-  requireRequestCredentialContext,
-  scopedCredentialCacheKey,
-} from "./credentials-context";
+import { scopedCredentialCacheKey } from "./credentials-context";
 import {
   DEFAULT_GONG_CALL_LIMIT,
   limitGongCalls,
   normalizeGongCallLimit,
 } from "./gong-limits";
-import { resolveAnalyticsGongCredentials } from "./provider-credentials";
+import { executeProviderApiRequest } from "./provider-api";
 
-const DEFAULT_API_BASE = "https://api.gong.io/v2";
 const MAX_GONG_SEARCH_PAGES = 50;
 const MAX_GONG_CALL_LIST_PAGES = 50;
 const MAX_GONG_EXHAUSTIVE_RECORDS = 500;
@@ -24,38 +19,101 @@ const cache = new Map<string, { data: unknown; ts: number }>();
 const CACHE_TTL_MS = 10 * 60 * 1000;
 const MAX_CACHE = 120;
 
-async function getAuthHeader(): Promise<string> {
-  const ctx = requireRequestCredentialContext("GONG_ACCESS_KEY");
-  const credentials = await resolveAnalyticsGongCredentials({ ctx });
-  if (!credentials)
-    throw new Error("GONG_ACCESS_KEY and GONG_ACCESS_SECRET not configured");
-  return `Basic ${Buffer.from(
-    `${credentials.accessKey}:${credentials.accessSecret}`,
-  ).toString("base64")}`;
-}
-
-async function getApiBase(): Promise<string> {
-  const ctx = requireRequestCredentialContext("GONG_ACCESS_KEY");
-  const configured = await resolveCredential("GONG_API_BASE", ctx);
-  return (configured || DEFAULT_API_BASE).replace(/\/+$/, "");
-}
-
 export interface GongRequestOptions {
   signal?: AbortSignal;
   deadlineAt?: number;
 }
 
-function requestSignal(options?: GongRequestOptions): AbortSignal {
-  const remainingMs = options?.deadlineAt
+function requestTimeoutMs(options?: GongRequestOptions): number {
+  return options?.deadlineAt
     ? Math.max(
         1,
         Math.min(GONG_API_REQUEST_TIMEOUT_MS, options.deadlineAt - Date.now()),
       )
     : GONG_API_REQUEST_TIMEOUT_MS;
-  const timeoutSignal = AbortSignal.timeout(remainingMs);
-  return options?.signal
-    ? AbortSignal.any([options.signal, timeoutSignal])
-    : timeoutSignal;
+}
+
+interface GongProviderResponse {
+  response: {
+    ok: boolean;
+    status: number;
+    headers?: Record<string, string>;
+    json?: unknown;
+    text?: string;
+  };
+}
+
+function splitGongPath(path: string): {
+  path: string;
+  query?: Record<string, string>;
+} {
+  const separator = path.indexOf("?");
+  if (separator < 0) return { path };
+  const query = Object.fromEntries(
+    new URLSearchParams(path.slice(separator + 1)).entries(),
+  );
+  return {
+    path: path.slice(0, separator),
+    ...(Object.keys(query).length > 0 ? { query } : {}),
+  };
+}
+
+function responseHeader(
+  headers: Record<string, string> | undefined,
+  name: string,
+): string | undefined {
+  const lowerName = name.toLowerCase();
+  return Object.entries(headers ?? {}).find(
+    ([key]) => key.toLowerCase() === lowerName,
+  )?.[1];
+}
+
+function responseDetail(response: GongProviderResponse["response"]): string {
+  if (typeof response.text === "string" && response.text.trim()) {
+    return response.text.replace(/\s+/g, " ").trim().slice(0, 2_000);
+  }
+  if (response.json !== undefined) {
+    return JSON.stringify(response.json).slice(0, 2_000);
+  }
+  return "";
+}
+
+function gongApiError(response: GongProviderResponse["response"]): Error {
+  const requestId =
+    responseHeader(response.headers, "x-request-id") ??
+    responseHeader(response.headers, "request-id");
+  const retryAfter = responseHeader(response.headers, "retry-after");
+  const metadata = [
+    requestId ? `requestId ${requestId}` : "",
+    response.status === 429 && retryAfter ? `retry-after ${retryAfter}` : "",
+  ]
+    .filter(Boolean)
+    .join(", ");
+  const detail = responseDetail(response);
+  return new Error(
+    `Gong API error ${response.status}${metadata ? ` (${metadata})` : ""}${detail ? `: ${detail}` : ""}`,
+  );
+}
+
+async function executeGongRequest<T>(options: {
+  method: "GET" | "POST";
+  path: string;
+  body?: unknown;
+  requestOptions?: GongRequestOptions;
+}): Promise<T> {
+  const request = splitGongPath(options.path);
+  const result = (await executeProviderApiRequest({
+    provider: "gong",
+    method: options.method,
+    path: request.path,
+    ...(request.query ? { query: request.query } : {}),
+    ...(options.body !== undefined ? { body: options.body } : {}),
+    timeoutMs: requestTimeoutMs(options.requestOptions),
+    signal: options.requestOptions?.signal,
+  })) as GongProviderResponse;
+
+  if (!result.response.ok) throw gongApiError(result.response);
+  return result.response.json as T;
 }
 
 async function apiGet<T>(
@@ -69,21 +127,12 @@ async function apiGet<T>(
     return cached.data as T;
   }
 
-  const res = await fetch(`${await getApiBase()}${path}`, {
-    headers: {
-      Authorization: await getAuthHeader(),
-      "Content-Type": "application/json",
-    },
-    signal: requestSignal(options),
+  const data = await executeGongRequest<T>({
+    method: "GET",
+    path,
+    requestOptions: options,
   });
 
-  if (!res.ok) {
-    const text = await res.text();
-    throw new Error(`Gong API error ${res.status}: ${text}`);
-  }
-
-  const data = await res.json();
-
   if (cache.size >= MAX_CACHE) {
     const oldest = cache.keys().next().value;
     if (oldest) cache.delete(oldest);
@@ -108,23 +157,13 @@ async function apiPost<T>(
     return cached.data as T;
   }
 
-  const res = await fetch(`${await getApiBase()}${path}`, {
+  const data = await executeGongRequest<T>({
     method: "POST",
-    headers: {
-      Authorization: await getAuthHeader(),
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify(body),
-    signal: requestSignal(options),
+    path,
+    body,
+    requestOptions: options,
   });
 
-  if (!res.ok) {
-    const text = await res.text();
-    throw new Error(`Gong API error ${res.status}: ${text}`);
-  }
-
-  const data = await res.json();
-
   if (cache.size >= MAX_CACHE) {
     const oldest = cache.keys().next().value;
     if (oldest) cache.delete(oldest);
@@ -298,29 +337,9 @@ export async function getCall(
   return data.calls?.[0] ?? null;
 }
 
-export async function getCallDetail(
-  callId: string,
-  options?: GongRequestOptions,
-): Promise<GongCallDetail | null> {
-  const body = {
-    filter: { callIds: [callId] },
-    contentSelector: {
-      exposedFields: {
-        parties: true,
-        content: { brief: true, keyPoints: true, outline: true },
-      },
-    },
-  };
-  const data = await apiPost<{ calls?: any[] }>(
-    "/calls/extensive",
-    body,
-    `detail:${callId}`,
-    options,
-  );
-  const call = data.calls?.[0];
-  if (!call) return null;
+function normalizeCallDetail(call: any, fallbackId: string): GongCallDetail {
   return {
-    id: call.metaData?.id ?? callId,
+    id: call.metaData?.id ?? fallbackId,
     title: call.metaData?.title || "Untitled",
     url: call.metaData?.url || "",
     started: call.metaData?.started || "",
@@ -340,6 +359,48 @@ export async function getCallDetail(
   };
 }
 
+export async function getCallDetails(
+  callIds: string[],
+  options?: GongRequestOptions,
+): Promise<GongCallDetail[]> {
+  const ids = Array.from(
+    new Set(
+      callIds
+        .map((id) => (typeof id === "string" ? id.trim() : ""))
+        .filter(Boolean),
+    ),
+  );
+  if (!ids.length) return [];
+
+  const body = {
+    filter: { callIds: ids },
+    contentSelector: {
+      exposedFields: {
+        parties: true,
+        content: { brief: true, keyPoints: true, outline: true },
+      },
+    },
+  };
+  const data = await apiPost<{ calls?: any[] }>(
+    "/calls/extensive",
+    body,
+    `details:${ids.join(",")}`,
+    options,
+  );
+  return (data.calls ?? []).map((call, index) =>
+    normalizeCallDetail(call, ids[index] ?? ""),
+  );
+}
+
+export async function getCallDetail(
+  callId: string,
+  options?: GongRequestOptions,
+): Promise<GongCallDetail | null> {
+  const details = await getCallDetails([callId], options);
+  const detail = details[0];
+  return detail === undefined ? null : detail;
+}
+
 export async function getCallTranscripts(
   callIds: string[],
   options?: GongRequestOptions,

package/corpus/templates/analytics/server/lib/session-replay.ts

@@ -39,7 +39,10 @@ import {
   SESSION_REPLAY_NETWORK_EVENT_TAG,
 } from "../../shared/session-replay-diagnostics.js";
 import { getDb, schema } from "../db/index.js";
-import { resolveAnalyticsEventDimensions } from "./first-party-analytics.js";
+import {
+  resolveAnalyticsEventDimensions,
+  touchPublicKeyLastUsedAt,
+} from "./first-party-analytics.js";
 
 export type ReplayRange = "24h" | "7d" | "30d" | "90d" | "all";
 
@@ -1654,10 +1657,7 @@ export async function recordSessionReplayChunks(
     })
     .where(eq(schema.sessionRecordings.id, recording.id));
 
-  await db
-    .update(schema.analyticsPublicKeys)
-    .set({ lastUsedAt: ingestedAt })
-    .where(eq(schema.analyticsPublicKeys.id, key.id));
+  await touchPublicKeyLastUsedAt(key.id, ingestedAt);
 
   recordChange({
     source: "session-recordings",

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

@@ -1439,6 +1439,58 @@ const runAnalyticsMigrations = runMigrations(
         )`,
       },
     },
+    {
+      version: 138,
+      name: "analytics-dashboard-folders",
+      sql: {
+        postgres: `CREATE TABLE IF NOT EXISTS dashboard_folders (
+          id TEXT PRIMARY KEY,
+          name TEXT NOT NULL,
+          scope TEXT NOT NULL,
+          created_at TEXT NOT NULL DEFAULT (now()::text),
+          updated_at TEXT NOT NULL DEFAULT (now()::text),
+          owner_email TEXT NOT NULL DEFAULT 'local@localhost',
+          org_id TEXT,
+          visibility TEXT NOT NULL DEFAULT 'private'
+        );
+        CREATE TABLE IF NOT EXISTS dashboard_folder_shares (
+          id TEXT PRIMARY KEY,
+          resource_id TEXT NOT NULL,
+          principal_type TEXT NOT NULL,
+          principal_id TEXT NOT NULL,
+          role TEXT NOT NULL DEFAULT 'viewer',
+          created_by TEXT NOT NULL,
+          created_at TEXT NOT NULL DEFAULT (now()::text)
+        );
+        ALTER TABLE dashboards ADD COLUMN IF NOT EXISTS folder_id TEXT;
+        CREATE INDEX IF NOT EXISTS dashboard_folders_owner_org_idx ON dashboard_folders (owner_email, org_id);
+        CREATE INDEX IF NOT EXISTS dashboard_folder_shares_resource_idx ON dashboard_folder_shares (resource_id);
+        CREATE INDEX IF NOT EXISTS dashboards_folder_idx ON dashboards (folder_id)`,
+        sqlite: `CREATE TABLE IF NOT EXISTS dashboard_folders (
+          id TEXT PRIMARY KEY,
+          name TEXT NOT NULL,
+          scope TEXT NOT NULL,
+          created_at TEXT NOT NULL DEFAULT (datetime('now')),
+          updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+          owner_email TEXT NOT NULL DEFAULT 'local@localhost',
+          org_id TEXT,
+          visibility TEXT NOT NULL DEFAULT 'private'
+        );
+        CREATE TABLE IF NOT EXISTS dashboard_folder_shares (
+          id TEXT PRIMARY KEY,
+          resource_id TEXT NOT NULL,
+          principal_type TEXT NOT NULL,
+          principal_id TEXT NOT NULL,
+          role TEXT NOT NULL DEFAULT 'viewer',
+          created_by TEXT NOT NULL,
+          created_at TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+        ALTER TABLE dashboards ADD COLUMN IF NOT EXISTS folder_id TEXT;
+        CREATE INDEX IF NOT EXISTS dashboard_folders_owner_org_idx ON dashboard_folders (owner_email, org_id);
+        CREATE INDEX IF NOT EXISTS dashboard_folder_shares_resource_idx ON dashboard_folder_shares (resource_id);
+        CREATE INDEX IF NOT EXISTS dashboards_folder_idx ON dashboards (folder_id)`,
+      },
+    },
   ],
   { table: "analytics_migrations" },
 );
@@ -1476,29 +1528,17 @@ export default async (nitroApp: any): Promise<void> => {
     Boolean(process.env.NETLIFY_FUNCTION_NAME) ||
     Boolean(process.env.AWS_LAMBDA_FUNCTION_NAME) ||
     Boolean(process.env.LAMBDA_TASK_ROOT);
-  if (
-    isNetlifyServerlessRuntime &&
-    process.env.ANALYTICS_SKIP_BOOT_MIGRATIONS === "1"
-  ) {
+  if (isNetlifyServerlessRuntime && !isScheduledRollupRuntime) {
     console.info(
-      "[db] Skipping Analytics migrations in production serverless runtime by explicit incident flag",
+      "[db] Skipping Analytics migrations in production serverless runtime",
     );
     return;
   }
   // The schema must exist before the first query. Measured cost on this
   // database (180 tables): ~5.5s for the version check alone, which is why the
-  // serverless runtime skips this entirely via ANALYTICS_SKIP_BOOT_MIGRATIONS
-  // above rather than paying it on every cold start.
+  // serverless runtime never runs it on cold starts.
   // guard:allow-boot-data-work — schema must exist before the first query
   await runAnalyticsMigrations(nitroApp);
-  if (isNetlifyServerlessRuntime) {
-    // The migration list is authoritative; repeating repair and schema
-    // introspection on every function cold start only adds pool pressure.
-    console.info(
-      "[db] Skipping post-migration schema convergence in production serverless runtime",
-    );
-    return;
-  }
   try {
     const summary = await ensureAdditiveColumns({
       db: getDbExec(),

package/corpus/templates/analytics/server/plugins/session-replay-retention-jobs.ts

@@ -1,19 +1,23 @@
 import { runSessionReplayRetentionOnce } from "../jobs/session-replay-retention";
+import { isProductionServerlessRuntime } from "../lib/production-serverless-runtime";
 
 const ONE_DAY_MS = 24 * 60 * 60 * 1000;
 let skippingLogged = false;
 
 export default function registerSessionReplayRetentionJobs(): void {
   const isProd = process.env.NODE_ENV === "production";
+  const isServerless = isProductionServerlessRuntime();
   const flag =
     process.env.ANALYTICS_SESSION_REPLAY_RETENTION_JOBS ??
     process.env.RUN_BACKGROUND_JOBS;
-  const enabled = flag === "1" || (isProd && flag !== "0");
+  const enabled = !isServerless && (flag === "1" || (isProd && flag !== "0"));
 
   if (!enabled) {
     if (!skippingLogged) {
       console.log(
-        "[session-replay] Skipping retention job (set ANALYTICS_SESSION_REPLAY_RETENTION_JOBS=1 or RUN_BACKGROUND_JOBS=1 to enable in dev; on by default in production)",
+        isServerless
+          ? "[session-replay] Skipping in-process retention job because production serverless runtimes rely on scheduled/background sweeps."
+          : "[session-replay] Skipping retention job (set ANALYTICS_SESSION_REPLAY_RETENTION_JOBS=1 or RUN_BACKGROUND_JOBS=1 to enable in dev; on by default in production)",
       );
       skippingLogged = true;
     }

package/corpus/templates/analytics/server/routes/api/session-replay/retention.post.ts

@@ -0,0 +1,65 @@
+import { timingSafeEqual } from "node:crypto";
+
+import { createError, defineEventHandler, getHeader } from "h3";
+
+// guard:allow-action-twin — external scheduler endpoint authenticates before invoking retention job logic.
+import { runSessionReplayRetentionOnce } from "../../../jobs/session-replay-retention";
+
+declare global {
+  var __AGENT_NATIVE_SESSION_REPLAY_RETENTION_SCHEDULED_RUNTIME__:
+    | boolean
+    | undefined;
+}
+
+function productionLike(): boolean {
+  return (
+    process.env.NODE_ENV === "production" ||
+    process.env.NETLIFY === "true" ||
+    process.env.VERCEL === "1" ||
+    Boolean(process.env.AWS_LAMBDA_FUNCTION_NAME)
+  );
+}
+
+function scheduledFunctionRuntime(): boolean {
+  return (
+    globalThis.__AGENT_NATIVE_SESSION_REPLAY_RETENTION_SCHEDULED_RUNTIME__ ===
+    true
+  );
+}
+
+function cronSecret(): string | null {
+  const secret = process.env.SESSION_REPLAY_RETENTION_CRON_SECRET?.trim();
+  return secret ? secret : null;
+}
+
+function headerMatchesSecret(
+  header: string | undefined,
+  secret: string,
+): boolean {
+  const expected = `Bearer ${secret}`;
+  const value = header?.trim() ?? "";
+  if (value.length !== expected.length) return false;
+  return timingSafeEqual(Buffer.from(value), Buffer.from(expected));
+}
+
+export default defineEventHandler(async (event) => {
+  const secret = cronSecret();
+  const scheduledRuntime = scheduledFunctionRuntime();
+  if (!secret && productionLike() && !scheduledRuntime) {
+    throw createError({
+      statusCode: 503,
+      statusMessage: "SESSION_REPLAY_RETENTION_CRON_SECRET is required",
+    });
+  }
+
+  if (
+    secret &&
+    !scheduledRuntime &&
+    !headerMatchesSecret(getHeader(event, "authorization"), secret)
+  ) {
+    throw createError({ statusCode: 401, statusMessage: "Unauthorized" });
+  }
+
+  const result = await runSessionReplayRetentionOnce();
+  return { ok: true, ...result };
+});

package/corpus/templates/assets/.agents/skills/actions/SKILL.md

@@ -20,6 +20,24 @@ Before creating any custom REST/API route for app data, inspect `actions/` and t
 
 **Stop trigger:** the moment you are about to create a file under `server/routes/api/` — or add server middleware to guard one — stop and check it against the exception list in *When You Still Need Custom `/api/` Routes* below. If it is not on that list, write a `defineAction` instead. This applies even when you already started the route; abandoning a half-written action to hand-roll routes is the exact failure this rule exists to prevent.
 
+## Keep actions deterministic and composable
+
+An action may call a provider API, validate or normalize data, and persist
+records without being an AI feature. Keep those operations deterministic,
+focused, and independently useful to the agent. Do not put LLM calls or a
+second model runtime in ordinary actions. The only narrow exception is the
+`completeText()` text-in/text-out escape hatch described in
+`delegate-to-agent`; it must not own tools, chat history, run state, side
+effects, or user steering.
+
+When a workflow is framed as research, analysis, generation, recommendation,
+or synthesis, or spans several provider calls and writes, route the user into
+the AgentSidebar and let the agent orchestrate focused actions. Do not hide an
+AI-shaped workflow behind one opaque `generate-*` or `create-*` action just
+because its implementation is deterministic. A visible user-initiated run
+should use `sendToAgentChat({ openSidebar: true })`, and its follow-ups should
+continue in the same thread rather than a separate freeform input.
+
 ## Why
 
 Actions give the agent callable tools with structured input/output, AND they give the frontend a typed client contract through hooks. One implementation serves both the agent and the UI. They keep the agent's chat context clean, they're reusable, and they can be tested independently.

package/corpus/templates/assets/.agents/skills/agent-native-toolkit/SKILL.md

@@ -56,6 +56,11 @@ The repeated app shell has two distinct navigation surfaces:
   labeled as local, preview, or analyze. For original/generated review, stack
   the source above the result by default and use side-by-side only for short,
   highly scannable content.
+- Deterministic implementation does not make an AI-shaped experience
+  deterministic. If the user expects research, analysis, generation,
+  recommendation, synthesis, visible progress, or steering, route the button
+  to the AgentSidebar and let the agent call focused actions. Keep revisions in
+  the same thread instead of adding a second freeform prompt box.
 - Standalone apps with `AgentSidebar` must resolve one assistant-ui runtime
   context. Match direct assistant-ui pins to the installed core/toolkit peer
   graph, use Vite dedupe/aliases when linked dependencies can split contexts,

package/corpus/templates/assets/.agents/skills/delegate-to-agent/SKILL.md

@@ -14,11 +14,21 @@ metadata:
 
 ## Rule
 
-The UI never calls an LLM directly. Product workflows are delegated to the
-agent through the chat bridge so users can see, steer, and audit the work.
-Server-side one-shot model calls are an explicit escape hatch for narrow text
-transforms only; use `completeText()` from `@agent-native/core/server` when the
-work intentionally does not need tools, chat history, or run state.
+The app's default AI surface is the agent chat. Any user-facing work that asks
+the model to research, analyze, generate, recommend, synthesize, or reason over
+multiple steps must start or continue in the AgentSidebar so users can see,
+steer, and audit the work. UI buttons use `sendToAgentChat()` with
+`openSidebar: true`, and follow-up or revision text belongs in that same thread
+instead of a second app-local textbox.
+
+Actions are tools, not alternate AI runtimes. Keep them deterministic and
+focused: provider reads, validation, deterministic transforms, CRUD, and
+persistence are good action work. Let the agent orchestrate several such tools
+when the workflow is AI-shaped or user-steerable. Server-side one-shot model
+calls are a rare escape hatch for narrow text transforms only; use
+`completeText()` from `@agent-native/core/server` only when the work
+intentionally does not need tools, chat history, run state, side effects, or
+user steering.
 
 ## Why
 
@@ -35,6 +45,7 @@ sendToAgentChat({
   message: "Generate a summary of this document",
   context: documentContent, // optional hidden context (not shown in chat UI)
   submit: true, // auto-submit to the agent
+  openSidebar: true,
 });
 ```
 
@@ -56,6 +67,10 @@ sendToAgentChat({
 This is still a full agent run: tools, actions, thread state, and run tracking
 all remain active. It simply does not focus or open the sidebar.
 
+Use this silent form only for explicitly background or system-initiated work.
+It is not the default for a user clicking an AI-labeled button; visible work
+should open the sidebar so the user can follow and redirect the run.
+
 **From scripts (Node):**
 
 ```ts
@@ -77,8 +92,9 @@ const result = await completeText({
 });
 ```
 
-Wrap user-facing uses in actions so the UI and agent share the same operation.
-Do not call provider SDKs directly.
+If the narrow exception is exposed to the UI, wrap it in an action so the UI
+and agent share the same operation. Keep it clearly non-conversational and do
+not call provider SDKs directly.
 
 **From the UI, detecting when agent is done:**
 
@@ -97,9 +113,9 @@ The `submit` option controls whether the message is sent automatically or placed
 
 | `submit` value | Behavior                                | Use when                                                                            |
 | -------------- | --------------------------------------- | ----------------------------------------------------------------------------------- |
-| `true`         | Auto-submits to the agent immediately   | Routine operations the user has already approved                                    |
-| `false`        | Prefills the chat input for user review | High-stakes operations (deleting data, modifying code, API calls with side effects) |
-| omitted        | Uses the project's default setting      | General-purpose delegation                                                          |
+| `true`         | Auto-submits to the agent immediately   | Routine operations with clear intent; keep `openSidebar: true` for visible work |
+| `false`        | Prefills the AgentSidebar composer      | Review, edit, or add detail before the run; use the existing sidebar thread   |
+| omitted        | Uses the project's default setting      | General-purpose delegation                                                       |
 
 ```ts
 // Auto-submit: routine operation
@@ -109,61 +125,43 @@ sendToAgentChat({ message: "Update the project summary", submit: true });
 sendToAgentChat({
   message: "Delete all projects older than 30 days",
   submit: false,
+  openSidebar: true,
 });
 ```
 
-## Capture user input first when generating from a prompt
-
-Buttons that produce new content ("New Design", "Create Dashboard", "Make Deck", "Generate Form") need the user's prompt as input. **Never hardcode a generic message** — the result will be a generic generation the user didn't actually ask for.
+## Capture user input in the sidebar
 
-**Bad** — auto-submits a placeholder message; the user never said what they wanted:
+The AgentSidebar composer is the default prompt surface. When a button needs
+the user to describe what to create, prefill that same composer and let the
+user edit or complete it:
 
 ```tsx
 <Button
   onClick={() =>
-    sendToAgentChat({ message: "make a design", submit: true })
+    sendToAgentChat({
+      message: "Help me create a research report from this brief:",
+      context: researchBrief,
+      submit: false,
+      openSidebar: true,
+    })
   }
 >
-  New Design
+  Start in agent
 </Button>
 ```
 
-**Good** — Popover anchored to the button captures the prompt, then submits it:
-
-```tsx
-<Popover open={open} onOpenChange={setOpen}>
-  <PopoverTrigger asChild>
-    <Button>New Design</Button>
-  </PopoverTrigger>
-  <PopoverContent className="w-96">
-    <Textarea
-      autoFocus
-      value={prompt}
-      onChange={(e) => setPrompt(e.target.value)}
-      placeholder="What do you want to design?"
-    />
-    <Button
-      onClick={() => {
-        sendToAgentChat({ message: prompt, submit: true });
-        setOpen(false);
-        setPrompt("");
-      }}
-    >
-      Create
-    </Button>
-  </PopoverContent>
-</Popover>
-```
-
-**Always ask for input first when** the output depends on a prompt the user must provide — "design what?", "deck about what?", "dashboard for which metric?", "form for which use case?".
-
-**Auto-submit without input is fine when intent is unambiguous:**
+Never auto-submit a generic creative prompt when the user has not said what
+they want. Auto-submit without additional input is fine when intent is
+unambiguous:
 
 - "Try to fix" on a tool error — submits the error details with a clear fix instruction
 - "Retry the last operation" after a transient failure
 - Single-purpose buttons where there is nothing meaningful for the user to add
 
-If you find yourself writing `submit: true` with a hardcoded creative verb (`"design a..."`, `"write a..."`, `"build a..."`), stop and add a Popover.
+Use a Popover only for compact, structured parameters the UI must validate,
+such as a date range, target, or approval choice. Do not add a second freeform
+prompt or follow-up textbox for an AI workflow; keep the conversation and
+revisions in the AgentSidebar thread.
 
 ## Delegating to a Sub-Agent (Agent Teams)