@agent-native/core 0.98.5 → 0.98.7

package/corpus/core/src/mcp/build-server.ts

@@ -51,6 +51,7 @@ import {
   MCP_CONNECT_SCOPE,
 } from "./connect-store.js";
 import { MCP_APP_REQUEST_ORIGIN_CSP_SOURCE } from "./embed-app.js";
+import type { ExternalAgentPolicy } from "./external-agent-policy.js";
 import {
   MCP_OAUTH_SCOPES,
   hasMcpOAuthScope,
@@ -124,8 +125,9 @@ export interface MCPConfig {
    * from connectors. It is no longer gated behind an environment variable, and
    * the catalog is never inferred from the client name/user-agent.
    *
-   * `tool-search` stays available in the compact catalog so any trimmed tool is
-   * reachable on demand. Callers who need the full surface up front opt in
+   * `tool-search` stays available in the compact catalog for discovery. A
+   * searched action still needs the connector catalog or authenticated-read
+   * policy before `tools/call`; callers who need the full surface up front opt in
    * explicitly with `agent-native connect --full-catalog` (embeds a
    * `catalog_scope: "full"` claim in the connect-minted JWT) or the
    * deployment-wide `AGENT_NATIVE_MCP_FULL_CATALOG=1` env override.
@@ -134,6 +136,11 @@ export interface MCPConfig {
    * setting it on `MCPConfig` directly; the plugin copies it through.
    */
   connectorCatalog?: string[];
+  /**
+   * Optional policy for automatically exposing explicitly annotated,
+   * authenticated read actions to external MCP callers.
+   */
+  externalAgents?: ExternalAgentPolicy;
 }
 
 /**
@@ -281,7 +288,7 @@ function explicitlyRequestsFullMcpCatalog(
   // (100k+ tokens) into a context window just because a client called itself
   // "code"/"cursor"/"codex" was a recurring footgun. Everything else gets the
   // connector/compact catalog plus `tool-search`, which keeps every tool
-  // reachable on demand.
+  // discoverable; only permitted actions are callable without full opt-in.
   if (process.env.AGENT_NATIVE_MCP_FULL_CATALOG === "1") return true;
   return requestMeta?.fullCatalog === true;
 }
@@ -309,17 +316,101 @@ function warnFullCatalogServed(toolCount: number): void {
   );
 }
 
+function isAuthenticatedReadAction(entry: ActionEntry): boolean {
+  return (
+    entry.http !== false &&
+    entry.http?.method === "GET" &&
+    entry.readOnly === true &&
+    entry.publicAgent?.expose === true &&
+    entry.publicAgent.readOnly === true &&
+    entry.publicAgent.requiresAuth === true
+  );
+}
+
 /**
- * Returns true when the given action name is in the template's connector
- * catalog, OR is a builtin cross-app tool that is always included for
- * external connector clients. Builtin tool names from
- * `COMPACT_MCP_APP_CATALOG_BUILTINS` are always allowed since they are the
- * stable external-agent verb set.
+ * Hard exclusion list for the `authenticatedReads: "auto"` derivation ONLY
+ * (see `autoAuthenticatedReadNames` below). Explicit `connectorCatalog`
+ * entries are a deliberate, reviewed choice made by the app and are NOT
+ * affected by this list — an app can still list any of these names in
+ * `connectorCatalog` on purpose.
+ *
+ * These are the footgun families this file's other comments already call
+ * out ("removes footguns (db-exec, seed-*, extension tools, browser-session
+ * tools, etc.)" above, and "keeps db-exec / seed-* / extension /
+ * browser-session footguns off the external surface" near the connector
+ * tier below): generic core SQL access, template demo/seed data, the
+ * extension-management suite, live browser-session control, and Context
+ * X-Ray internals. `isAuthenticatedReadAction` only inspects action
+ * metadata (http/readOnly/publicAgent flags) — nothing stops a future
+ * change from mis-annotating one of these with that exact flag set again,
+ * the way `db-query`/`db-schema` were briefly (and accidentally) annotated
+ * before it was caught in review. These names can never be auto-derived
+ * from metadata alone; exposing one to external callers requires an
+ * explicit `connectorCatalog` entry.
  */
-function isActionInConnectorCatalog(name: string, config: MCPConfig): boolean {
-  if (COMPACT_MCP_APP_CATALOG_BUILTINS.has(name)) return true;
-  if (!Array.isArray(config.connectorCatalog)) return false;
-  return config.connectorCatalog.includes(name);
+const AUTO_READ_EXCLUDED_ACTION_NAMES = new Set([
+  "db-query",
+  "db-schema",
+  "db-exec",
+  "db-patch",
+  "context-manifest-get",
+  "context-pin",
+  "context-evict",
+  "context-restore",
+  "context-report",
+]);
+
+/**
+ * Substring/prefix patterns for excluded name *families* that aren't a
+ * fixed, enumerable set: `seed-*` varies per app/template, and the
+ * extension-management and browser-session tool suites use varying verb
+ * prefixes around a shared noun (e.g. `list-extensions`, `create-extension`,
+ * `hide-extension`; `list-browser-sessions`, `run-browser-session-action`) —
+ * so a leading-prefix match alone would miss most of them.
+ */
+const AUTO_READ_EXCLUDED_ACTION_PATTERNS: RegExp[] = [
+  /^seed-/,
+  /extension/,
+  /browser-session/,
+];
+
+function isAutoReadExcludedActionName(name: string): boolean {
+  return (
+    AUTO_READ_EXCLUDED_ACTION_NAMES.has(name) ||
+    AUTO_READ_EXCLUDED_ACTION_PATTERNS.some((pattern) => pattern.test(name))
+  );
+}
+
+function autoAuthenticatedReadNames(
+  actions: Record<string, ActionEntry>,
+  config: MCPConfig,
+): Set<string> {
+  if (config.externalAgents?.authenticatedReads !== "auto") return new Set();
+  return new Set(
+    Object.entries(actions)
+      .filter(
+        ([name, entry]) =>
+          isAuthenticatedReadAction(entry) &&
+          !isAutoReadExcludedActionName(name),
+      )
+      .map(([name]) => name),
+  );
+}
+
+function externalAgentDenySet(config: MCPConfig): Set<string> {
+  return new Set(
+    (config.externalAgents?.denyActions ?? [])
+      .map((name) => name.trim())
+      .filter(Boolean),
+  );
+}
+
+function externalAgentWritesAreAskAppOnly(config: MCPConfig): boolean {
+  return (
+    config.externalAgents?.writes === "ask_app_only" ||
+    (config.externalAgents?.authenticatedReads === "auto" &&
+      config.externalAgents?.writes !== "allowlisted")
+  );
 }
 
 interface ResolvedMcpAppResource {
@@ -1300,16 +1391,21 @@ export async function createMCPServerForRequest(
         ),
       )
     : visibleActions;
+  const autoReadNames = autoAuthenticatedReadNames(visibleActions, config);
+  const connectorNames = new Set([
+    ...(config.connectorCatalog ?? []),
+    ...autoReadNames,
+  ]);
+  const denyNames = externalAgentDenySet(config);
+  const automaticConnectorPolicyActive =
+    config.externalAgents?.authenticatedReads === "auto";
   // Connector-catalog tier: when a template declares a connector allow-list,
-  // serve exactly that curated surface (+ cross-app builtins + tool-search) to
-  // external callers unless they explicitly opted into the full catalog. This
-  // is active by default whenever a catalog is declared — no env flag required —
-  // so the ~105-tool full catalog can never leak just because a deployment
-  // forgot to set one. It also keeps db-exec / seed-* / extension /
+  // serve exactly that curated surface plus any explicitly annotated
+  // authenticated reads from `externalAgents.authenticatedReads: "auto"`.
+  // This stays compact by default and keeps db-exec / seed-* / extension /
   // browser-session footguns off the external surface.
   const connectorCatalogActive =
-    Array.isArray(config.connectorCatalog) &&
-    config.connectorCatalog.length > 0 &&
+    (connectorNames.size > 0 || automaticConnectorPolicyActive) &&
     !fullCatalogRequested;
   // When the connector catalog is active, filter directly from visibleActions
   // rather than advertisedActionsBeforeConnector. This ensures the connector
@@ -1318,9 +1414,18 @@ export async function createMCPServerForRequest(
   // would have activated the compact catalog for the same caller.
   const advertisedActions = connectorCatalogActive
     ? Object.fromEntries(
-        Object.entries(visibleActions).filter(([name]) =>
-          isActionInConnectorCatalog(name, config),
-        ),
+        Object.entries(visibleActions).filter(([name, entry]) => {
+          if (denyNames.has(name)) return false;
+          if (COMPACT_MCP_APP_CATALOG_BUILTINS.has(name)) return true;
+          if (!connectorNames.has(name)) return false;
+          if (
+            externalAgentWritesAreAskAppOnly(config) &&
+            entry.readOnly !== true
+          ) {
+            return false;
+          }
+          return true;
+        }),
       )
     : advertisedActionsBeforeConnector;
   if (fullCatalogRequested) {

package/corpus/core/src/mcp/builtin-tools.ts

@@ -858,8 +858,11 @@ function askAppTool(
   return {
     tool: tool(
       "Send a natural-language message to an app's AI agent and get its " +
-        "response. Use for complex, multi-step tasks needing the agent's " +
-        "reasoning and full app context. In a single-app project the 'app' " +
+        "response. Use this first for natural-language investigation, " +
+        "diagnosis, multi-step work, and changes; it runs with the app's " +
+        "full skills, instructions, tools, and context. Use direct action " +
+        "tools only for a known, bounded read or simple UI handoff. In a " +
+        "single-app project the 'app' " +
         "param is optional (defaults to this app). When 'app' names a " +
         "different workspace app it is routed there over A2A; the result's " +
         "'routedVia' field reports whether it ran cross-app or locally. " +

package/corpus/core/src/mcp/external-agent-policy.ts

@@ -0,0 +1,18 @@
+/**
+ * Policy for the default authenticated external-agent connector surface.
+ *
+ * The policy is intentionally narrow: "auto" only discovers actions that
+ * explicitly opt into authenticated, read-only public-agent exposure. It
+ * never makes an unannotated action callable and never grants writes.
+ */
+export interface ExternalAgentPolicy {
+  /** Automatically advertise authenticated GET/read-only public-agent actions. */
+  authenticatedReads?: "off" | "auto";
+  /**
+   * Keep writes behind `ask_app` by default. `allowlisted` preserves explicit
+   * connectorCatalog write exposure for apps that intentionally need it.
+   */
+  writes?: "ask_app_only" | "allowlisted";
+  /** Explicit action names to remove from the derived connector surface. */
+  denyActions?: string[];
+}

package/corpus/core/src/mcp/index.ts

@@ -10,6 +10,7 @@ export {
   buildLinkArtifacts,
 } from "./build-server.js";
 export type { MCPCallerIdentity, MCPRequestMeta } from "./build-server.js";
+export type { ExternalAgentPolicy } from "./external-agent-policy.js";
 
 // stdio transport for `agent-native mcp serve` (Node-only).
 export { runMCPStdio } from "./stdio.js";

package/corpus/core/src/server/agent-chat/plugin-options.ts

@@ -5,6 +5,7 @@ import type {
   AgentChatReference,
   MentionProvider,
 } from "../../agent/types.js";
+import type { ExternalAgentPolicy } from "../../mcp/external-agent-policy.js";
 import type { DatabaseToolsOption } from "../../scripts/db/tool-mode.js";
 import type { PromptExamples } from "../prompts/index.js";
 
@@ -293,7 +294,9 @@ export interface AgentChatPluginOptions {
    * browser-session tools) from connectors. It is no longer gated behind an
    * environment variable, and the catalog is never inferred from the client.
    *
-   * `tool-search` stays available so any trimmed tool is reachable on demand.
+   * `tool-search` stays available for discovery; a trimmed action still needs
+   * the connector catalog, authenticated-read policy, or full-catalog opt-in
+   * before an external caller can execute it.
    * Callers who need the full surface up front opt in explicitly with
    * `agent-native connect --full-catalog` (embeds a `catalog_scope: "full"`
    * claim in their connect-minted JWT) or the deployment-wide
@@ -303,6 +306,14 @@ export interface AgentChatPluginOptions {
    */
   connectorCatalog?: string[];
 
+  /**
+   * Default authenticated external-agent policy. In `auto` read mode, every
+   * action explicitly marked as GET + readOnly + publicAgent.requiresAuth is
+   * added to the connector surface automatically. Writes remain ask_app-only
+   * unless `writes: "allowlisted"` is explicitly selected.
+   */
+  externalAgents?: ExternalAgentPolicy;
+
   /**
    * Skip mounting the remote MCP protocol route.
    *

package/corpus/core/src/server/agent-chat/script-entries.ts

@@ -31,7 +31,10 @@ import {
 function wrapCliScript(
   tool: ActionTool,
   cliDefault: (args: string[]) => Promise<void>,
-  opts?: { readOnly?: boolean },
+  opts?: {
+    allowedArgs?: readonly string[];
+    readOnly?: boolean;
+  },
 ): ActionEntry {
   return {
     tool,
@@ -39,6 +42,14 @@ function wrapCliScript(
     run: async (args: Record<string, string>): Promise<string> => {
       const cliArgs: string[] = [];
       for (const [k, v] of Object.entries(args)) {
+        // MCP input schemas are descriptive and some hosts can still send
+        // undeclared keys. The externally exposed DB readers must never accept
+        // the CLI-only `--db` escape hatch, which could point at another local
+        // SQLite file. Keep their runtime surface identical to the advertised
+        // schema instead of trusting the client to validate it.
+        if (opts?.allowedArgs && !opts.allowedArgs.includes(k)) {
+          throw new Error(`Unknown argument: ${k}`);
+        }
         const raw = v as unknown;
         const value =
           raw != null && typeof raw === "object"
@@ -101,7 +112,10 @@ export async function createDbScriptEntries(
           },
         },
         schemaMod.default,
-        { readOnly: true },
+        {
+          allowedArgs: ["format"],
+          readOnly: true,
+        },
       ),
       "db-query": wrapCliScript(
         {
@@ -134,7 +148,10 @@ export async function createDbScriptEntries(
           },
         },
         queryMod.default,
-        { readOnly: true },
+        {
+          allowedArgs: ["sql", "args", "format", "limit"],
+          readOnly: true,
+        },
       ),
     };
 

package/corpus/core/src/server/agent-chat-plugin.ts

@@ -1512,6 +1512,9 @@ export function createAgentChatPlugin(
           ...(options?.connectorCatalog
             ? { connectorCatalog: options.connectorCatalog }
             : {}),
+          ...(options?.externalAgents
+            ? { externalAgents: options.externalAgents }
+            : {}),
           askAgent: async (message: string) => {
             const mcpEngine = await resolveEngine({
               engineOption: options?.engine,

package/corpus/core/src/templates/workspace-core/.agents/skills/external-agents/SKILL.md

@@ -160,15 +160,44 @@ tiny by default for ChatGPT/Claude-style app hosts, including OAuth MCP Apps
 callers and generic authenticated remote HTTP/static-token callers. The model
 sees the generic app-facing verbs (`list_apps`, `open_app`, `ask_app`, and
 app-only `create_embed_session`) and routes UI through
-`open_app({ embed: true })`. Stdio/code clients that explicitly identify as
-developer clients keep the full connected action surface, and
-`publicAgent.expose` remains the opt-in for safe read/ingest tools outside the
-compact MCP Apps catalog. Do not rely on action-specific `mcpApp` resources
-appearing in ChatGPT/Claude discovery by default; use `open_app` for the
+`open_app({ embed: true })`. Stdio/code clients use the same compact surface
+unless they explicitly opt into the full catalog, and
+`publicAgent.expose` remains the action-level opt-in for safe read/ingest tools
+outside the compact MCP Apps catalog. Apps can set
+`externalAgents.authenticatedReads: "auto"` to automatically advertise every
+action that is GET + `readOnly` + `publicAgent.requiresAuth`, instead of
+maintaining a long connector allow-list. This policy never includes writes by
+default; use `writes: "ask_app_only"` to keep mutations behind `ask_app`, and
+use `denyActions` for defense-in-depth vetoes. `tool-search` remains available
+for discovery, but a searched action still needs to be in the connector
+catalog, included by the authenticated-read policy, or enabled by the explicit
+full-catalog opt-in before `tools/call` can execute it. Do not rely on
+action-specific `mcpApp` resources appearing in ChatGPT/Claude discovery by
+default; use `open_app` for the
 first-class app embed path. If a specific
 action truly must remain visible in that compact app-host catalog, set
 `mcpApp.compactCatalog: true` as a rare escape hatch.
 
+Generic core `db-schema` and `db-query` are intentionally not automatic
+external reads. They remain available to the in-app agent through the normal
+scoped SQL path, but broad schema/SQL access is too powerful to infer from
+read-only metadata alone. If an app needs direct external querying, expose an
+app-owned bounded GET action or add an explicit table/column allow-list with
+row, byte, timeout, and audit limits. Keep `db-exec` and `db-patch` outside
+automatic external-agent exposure.
+
+Authentication and authorization are separate gates. A verified MCP OAuth or
+connect token identifies the caller and organization; `publicAgent` only opts
+an action into the external protocol surface and does not grant record access.
+Actions still need `accessFilter`, `resolveAccess`, or `assertAccess` so private
+documents/dashboards, shares, organization boundaries, and roles are enforced.
+For Slack, verified DMs are linked to an existing Agent Native org member
+before execution and run with that user's context; shared channels use a
+service principal, and guests/external members cannot borrow personal access.
+Managed Slack OAuth and the generated app manifest both request
+`users:read.email`; existing installs must reconnect/reinstall after a scope
+change, while legacy bot-token installs must add the scope in Slack manually.
+
 ### 1b. Fast-path expectations for MCP Apps hosts
 
 Keep ChatGPT/Claude paths short. For a known app-facing intent, the external

package/corpus/templates/analytics/.agents/skills/session-replay/SKILL.md

@@ -164,7 +164,10 @@ agent answers about browser recordings in the Analytics template.
   reintroducing a clamp) — as regression guards against reintroducing any
   viewport "recovery" or pointer-projection heuristic. Do not change their
   expectations merely to bless a new sanitizer or clamp; validate the affected
-  replay in a browser first.
+  replay in a browser first. An interim clamp for the exact 3,189x885 pair was
+  also deleted once the view-time redaction root cause was proven; the earlier
+  3,000-3,999px band was rejected because it also catches real 3440px-wide
+  displays. Neither the exact exception nor the band belongs in the player.
 - The event timeline soft-highlights the active marker, auto-scrolls it into
   view (pausing briefly after manual scroll), and supports search. It appears
   beside the player from ~880px content width upward.

package/corpus/templates/analytics/AGENTS.md

@@ -113,11 +113,26 @@ details live in `.agents/skills/`.
   clicks when needed. The authenticated connector catalog is the fast fallback
   and exposes only bounded, user/org-scoped read actions for incident triage:
   `list-session-recordings`, `get-session-replay-summary`,
-  `get-session-replay-events`, `query-agent-native-analytics`,
-  `list-error-issues`, and `get-error-issue`. Fetch the summary before raw
-  events, use the event filters/limits to keep the response bounded, and do not
-  add replay blob or dashboard mutation actions to this catalog without an
-  explicit security review.
+  `get-session-replay-timeline`, `query-agent-native-analytics`,
+  `list-error-issues`, and `get-error-issue`. Fetch the summary before the
+  sanitized timeline; the timeline contains bounded page/click/error markers
+  without raw replay events or storage references. Do not add replay blob or
+  dashboard mutation actions to this catalog without an explicit security
+  review.
+- While Demo mode is enabled, session and error identities display anonymized
+  (`anonymous@builder.io`), so incident lookups must filter by the stable
+  `userId`/email parameter (e.g. `userId: "user@example.com"`) or recording/
+  issue id — never by matching emails read back from previously displayed
+  output.
+- Analytics keeps its direct MCP surface explicitly curated, so external
+  agents should use `ask_app` for multi-step investigation and changes. The
+  six incident reads above are bounded, user/org-scoped fallback tools for
+  callers that already know which lookup they need. Generic core
+  `db-schema` / `db-query` remain in-app agent tools and are not exposed
+  directly because broad SQL/schema access is too powerful to infer from
+  read-only metadata. Writes remain `ask_app`-only. Use the explicit catalog
+  and `denyActions` policy for any unusually sensitive read instead of
+  exposing an unannotated action.
 - `/agents` is the Analytics home for admin surfaces. The default Monitoring
   view embeds the shared observability dashboard for traces, conversations,
   evals, experiments, and feedback. `/agents?view=dashboards` shows the

package/corpus/templates/analytics/actions/create-session-replay-agent-link.ts

@@ -20,7 +20,6 @@ export default defineAction({
   schema: z.object({
     recordingId: z.string().describe("The session_recordings id"),
   }),
-  readOnly: true,
   run: async (args) => {
     return createSessionReplayAgentLink({
       recordingId: args.recordingId,

package/corpus/templates/analytics/actions/get-session-replay-events.ts

@@ -40,7 +40,6 @@ export default defineAction({
   }),
   http: { method: "GET" },
   readOnly: true,
-  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
   run: async (args) => {
     return getSessionReplayEvents(args.recordingId, resolveScope(), {
       startSeq: args.startSeq,

package/corpus/templates/analytics/actions/get-session-replay-timeline.ts

@@ -0,0 +1,40 @@
+import { defineAction } from "@agent-native/core";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+import { getSessionReplayTimeline } from "../server/lib/session-replay-agent-context.js";
+
+function resolveScope() {
+  const userEmail = getRequestUserEmail();
+  if (!userEmail) throw new Error("no authenticated user");
+  return { userEmail, orgId: getRequestOrgId() || null };
+}
+
+export default defineAction({
+  description:
+    "Get a bounded, sanitized timeline for one first-party Analytics session recording: page navigation, clicks, inputs, scrolls, custom events, console errors, and failed network requests. Returns marker metadata only; never returns raw rrweb/DOM/input values, replay chunks, or storage references. Use this after get-session-replay-summary when direct incident triage needs the user's click/page sequence.",
+  schema: z.object({
+    recordingId: z.string().describe("The session_recordings id"),
+    eventLimit: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(10000)
+      .optional()
+      .default(10000)
+      .describe(
+        "Maximum replay events to inspect before building the capped timeline",
+      ),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  run: async (args) => {
+    return getSessionReplayTimeline(args.recordingId, resolveScope(), {
+      eventLimit: args.eventLimit,
+    });
+  },
+});

package/corpus/templates/analytics/actions/list-error-issues.ts

@@ -26,6 +26,18 @@ export default defineAction({
       .optional()
       .describe("Search across issue title, type, culprit, and fingerprint."),
     app: z.string().optional().describe("Optional app filter."),
+    sessionRecordingId: z
+      .string()
+      .optional()
+      .describe(
+        "Filter to issues with an occurrence in this session recording.",
+      ),
+    userId: z
+      .string()
+      .optional()
+      .describe(
+        "Filter to issues with an occurrence for this user ID or user key.",
+      ),
     sort: z
       .enum(["lastSeen", "eventCount", "firstSeen"])
       .optional()

package/corpus/templates/analytics/actions/query-agent-native-analytics.ts

@@ -33,7 +33,10 @@ export default defineAction({
     ),
   }),
   readOnly: true,
-  http: { method: "GET" },
+  // No raw HTTP route: a GET endpoint would put caller SQL in query strings
+  // and access logs. External MCP callers reach this through the explicit
+  // ANALYTICS_CONNECTOR_CATALOG entry, which dispatches run() in-process.
+  http: false,
   publicAgent: { expose: true, readOnly: true, requiresAuth: true },
   run: async (args) => {
     return queryFirstPartyAnalytics(args.sql, resolveScope());

package/corpus/templates/analytics/app/pages/sessions/SessionsPage.tsx

@@ -21,7 +21,7 @@ import {
   IconSettings,
 } from "@tabler/icons-react";
 import { useQuery } from "@tanstack/react-query";
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Link, useNavigate, useSearchParams } from "react-router";
 import { toast } from "sonner";
 
@@ -169,6 +169,40 @@ type SessionRecordingDevice = Pick<SessionRecordingSummary, "metadata">;
 const RANGE_OPTIONS: ReplayRange[] = ["24h", "7d", "30d", "90d", "all"];
 const SESSION_QUERY_DEBOUNCE_MS = 250;
 
+/**
+ * Local input state for a URL-backed filter, debounced into the URL.
+ *
+ * `urlValue` only resyncs local state when it changes for a reason other
+ * than this hook's own debounced write (back/forward navigation, an agent
+ * driven URL change, etc). React Router commits `setSearchParams` inside a
+ * transition, so without this guard the echo of our own write can land
+ * after a newer keystroke and clobber it.
+ */
+export function useDebouncedUrlFilter(
+  urlValue: string,
+  onCommit: (value: string) => void,
+): [string, (value: string) => void] {
+  const [input, setInput] = useState(urlValue);
+  const lastPushedRef = useRef(urlValue);
+
+  useEffect(() => {
+    if (urlValue === lastPushedRef.current) return;
+    lastPushedRef.current = urlValue;
+    setInput(urlValue);
+  }, [urlValue]);
+
+  useEffect(() => {
+    if (input === urlValue) return;
+    const timeout = window.setTimeout(() => {
+      lastPushedRef.current = input;
+      onCommit(input);
+    }, SESSION_QUERY_DEBOUNCE_MS);
+    return () => window.clearTimeout(timeout);
+  }, [input, urlValue, onCommit]);
+
+  return [input, setInput];
+}
+
 export default function SessionsPage() {
   const t = useT();
   const navigate = useNavigate();
@@ -176,13 +210,8 @@ export default function SessionsPage() {
   const range = readRange(searchParams.get("range"));
   const app = searchParams.get("app") ?? "";
   const query = searchParams.get("q") ?? "";
-  const [queryInput, setQueryInput] = useState(query);
   const from = useMemo(() => rangeToFrom(range), [range]);
 
-  useEffect(() => {
-    setQueryInput(query);
-  }, [query]);
-
   const updateFilter = useCallback(
     (key: string, value: string) => {
       setSearchParams(
@@ -200,13 +229,17 @@ export default function SessionsPage() {
     [setSearchParams],
   );
 
-  useEffect(() => {
-    if (queryInput === query) return;
-    const timeout = window.setTimeout(() => {
-      updateFilter("q", queryInput);
-    }, SESSION_QUERY_DEBOUNCE_MS);
-    return () => window.clearTimeout(timeout);
-  }, [query, queryInput, updateFilter]);
+  const commitQuery = useCallback(
+    (value: string) => updateFilter("q", value),
+    [updateFilter],
+  );
+  const [queryInput, setQueryInput] = useDebouncedUrlFilter(query, commitQuery);
+
+  const commitApp = useCallback(
+    (value: string) => updateFilter("app", value),
+    [updateFilter],
+  );
+  const [appInput, setAppInput] = useDebouncedUrlFilter(app, commitApp);
 
   const { data, isLoading, isFetching, refetch, error } = useActionQuery<
     SessionRecordingSummary[]
@@ -291,10 +324,8 @@ export default function SessionsPage() {
                       {t("sessions.userFilters")}
                     </div>
                     <Input
-                      value={app}
-                      onChange={(event) =>
-                        updateFilter("app", event.target.value)
-                      }
+                      value={appInput}
+                      onChange={(event) => setAppInput(event.target.value)}
                       placeholder={t("sessions.appPlaceholder")}
                       className="h-9"
                     />

package/corpus/templates/analytics/changelog/2026-07-12-analytics-uses-the-full-in-app-agent-for-multi-step-incident.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-12
+---
+
+Analytics uses the full in-app agent for multi-step incident investigations, with direct read tools available for focused lookups.

package/corpus/templates/analytics/changelog/2026-07-12-connected-external-agents-can-now-look-up-sessions-error-iss.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-12
+---
+
+Connected external agents can now look up sessions, error issues, and sanitized replay timelines directly, with the app agent remaining the default path.

package/corpus/templates/analytics/changelog/2026-07-12-session-identities-stay-visible-when-demo-mode-is-off.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-12
+---
+
+Session identities stay visible when Demo mode is off