@agent-native/core 0.146.4 → 0.146.6

package/dist/provider-api/corpus-jobs.d.ts

@@ -73,6 +73,7 @@ export declare function createProviderCorpusJobAction(options: CreateProviderCor
     offset?: unknown;
     limit?: unknown;
 }, {
+    deleted?: undefined;
     jobs: {
         id: string;
         name: string;
@@ -83,7 +84,6 @@ export declare function createProviderCorpusJobAction(options: CreateProviderCor
         updatedAt: string;
     }[];
     total: number;
-    deleted?: undefined;
     jobId?: undefined;
 } | {
     jobs?: undefined;
@@ -91,9 +91,9 @@ export declare function createProviderCorpusJobAction(options: CreateProviderCor
     deleted: boolean;
     jobId: string;
 } | {
+    deleted?: undefined;
     jobs?: undefined;
     total?: undefined;
-    deleted?: undefined;
     jobId?: undefined;
     hits: Record<string, unknown>[];
     offset: number;

package/dist/secrets/routes.d.ts

@@ -37,17 +37,17 @@ export declare function createWriteSecretHandler(): import("h3").EventHandlerWit
     ok?: undefined;
     status?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     status: string;
+    error?: undefined;
 } | {
     ok?: undefined;
     error: string;
     removed?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;
 /**
  * POST /_agent-native/secrets/:key/test — validate an optional candidate value
@@ -58,13 +58,13 @@ export declare function createTestSecretHandler(): import("h3").EventHandlerWith
     error: string;
     note?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     note?: undefined;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     note: string;
+    error?: undefined;
 } | {
     note?: undefined;
     ok: boolean;
@@ -95,11 +95,11 @@ export interface AdHocSecretPayload {
 export declare function createAdHocSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<AdHocSecretPayload[] | {
     error: string;
 } | {
-    error?: undefined;
     ok: boolean;
     key: string;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;

package/dist/server/agent-chat/mcp-glue.js

@@ -1,5 +1,5 @@
 import { defineEventHandler, getMethod, setResponseHeader, setResponseStatus, } from "h3";
-import { buildMergedConfig, getHubStatus, } from "../../mcp-client/index.js";
+import { buildMergedConfig, getHubStatus, McpConfigUnreadableError, } from "../../mcp-client/index.js";
 import { getH3App } from "../framework-request-handler.js";
 // ---------------------------------------------------------------------------
 // MCP client glue — a shared manager reference + a /_agent-native/mcp/status
@@ -18,8 +18,17 @@ export async function refreshGlobalMcpManager() {
     const manager = getGlobalMcpManager();
     if (!manager)
         return false;
-    await manager.reconfigure(await buildMergedConfig());
-    return true;
+    try {
+        await manager.reconfigure(await buildMergedConfig());
+        return true;
+    }
+    catch (err) {
+        if (err instanceof McpConfigUnreadableError) {
+            console.warn(`[mcp-client] global refresh skipped: ${err.message}`);
+            return false;
+        }
+        throw err;
+    }
 }
 export function mountMcpHubStatusRoute(nitroApp) {
     const mountedApps = (globalThis.__agentNativeMcpHubStatusMountedApps ??= new WeakSet());

package/dist/server/agent-chat-plugin.js

@@ -24,11 +24,11 @@ import { runChatThreadDataMigrations } from "../chat-threads/migrations.js";
 import { adoptThreadScopeIfUnscoped, createThread, forkThread, getThread, registerChatThreadsShareable, resolveRunThreadScope, resolveThreadAccess, listThreads, searchThreads, renameThread, createThreadShareLink, getThreadByShareToken, getThreadShareState, revokeThreadShareLink, setThreadArchived, setThreadPinned, setThreadScope, updateThreadData, withThreadDataLock, deleteThread, setThreadQueuedMessages, setThreadSourceIfMissing, } from "../chat-threads/store.js";
 import { isCheckpointRestorePath } from "../checkpoints/route-match.js";
 import { createDbAdminAgentTools } from "../db-admin/agent-tools.js";
-import { isTransientDatabaseError } from "../db/client.js";
+import { isProductionServerlessFunctionRuntime, isTransientDatabaseError, } from "../db/client.js";
 import { filterFrameworkToolGroups, resolveFrameworkTools, } from "../framework-tools.js";
 import { verifyInternalToken, extractBearerToken, } from "../integrations/internal-token.js";
 import { RECURRING_JOBS_SWEEP_PATH, RECURRING_JOBS_SWEEP_TOKEN_SUBJECT, } from "../jobs/scheduler-dispatch.js";
-import { McpClientManager, loadMcpConfig, autoDetectMcpConfig, mcpToolsToActionEntries, syncMcpActionEntries, mountMcpServersRoutes, mountMcpHubRoutes, buildMergedConfig, startMcpConfigRefresh, getHubStatus, isHubServeEnabled, } from "../mcp-client/index.js";
+import { McpClientManager, mcpToolsToActionEntries, syncMcpActionEntries, mountMcpServersRoutes, mountMcpHubRoutes, buildMergedConfig, startMcpConfigRefresh, getHubStatus, isHubServeEnabled, } from "../mcp-client/index.js";
 import { setProgressPreListHook } from "../progress/store.js";
 import { getSkillNameFromPath } from "../resources/metadata.js";
 import { resourceList, resourceListAccessible, resourceGet, ensurePersonalDefaults, SHARED_OWNER, WORKSPACE_OWNER, } from "../resources/store.js";
@@ -309,36 +309,43 @@ export function createAgentChatPlugin(options) {
             const mcpActionEntries = {};
             let mcpInitializationPromise = null;
             const initializeMcpManager = async () => {
-                let mcpConfig = await buildMergedConfig().catch((err) => {
-                    console.warn(`[mcp-client] buildMergedConfig failed: ${err?.message ?? err}`);
-                    return null;
-                });
-                if (!mcpConfig) {
-                    mcpConfig = loadMcpConfig() ?? autoDetectMcpConfig();
-                    if (mcpConfig?.source) {
-                        console.log(`[mcp-client] loaded config from ${mcpConfig.source} (${Object.keys(mcpConfig.servers).length} server(s))`);
-                    }
-                    else if (process.env.DEBUG) {
-                        console.log("[mcp-client] no configured MCP servers — skipping MCP tools");
-                    }
-                }
-                else if (mcpConfig.source) {
+                const mcpConfig = await buildMergedConfig();
+                if (mcpConfig?.source) {
                     console.log(`[mcp-client] merged config (${Object.keys(mcpConfig.servers).length} server(s), source: ${mcpConfig.source})`);
                 }
-                try {
-                    await mcpManager.reconfigure(mcpConfig);
+                else if (process.env.DEBUG) {
+                    console.log("[mcp-client] no configured MCP servers — skipping MCP tools");
                 }
-                catch (err) {
-                    console.warn(`[mcp-client] initialization failed: ${err?.message ?? err}. Continuing without MCP tools.`);
-                }
-                finally {
-                    startMcpConfigRefresh(mcpManager);
+                await mcpManager.reconfigure(mcpConfig);
+                startMcpConfigRefresh(mcpManager);
+            };
+            /**
+             * Start MCP initialization at most once, and return the run in flight.
+             *
+             * On a serverless function nothing kicks this off at boot (see the
+             * `isProductionServerlessFunctionRuntime` gate below), so every surface
+             * that actually consumes MCP tools must await this or the manager stays
+             * empty for the life of the container.
+             */
+            const ensureMcpInitialized = () => {
+                if (!mcpInitializationPromise) {
+                    mcpInitializationPromise = initializeMcpManager().catch((err) => {
+                        // Do not cache a settings outage as a successful empty manager;
+                        // the next MCP-consuming request must retry the configuration read.
+                        mcpInitializationPromise = null;
+                        throw err;
+                    });
                 }
+                return mcpInitializationPromise;
             };
-            const getJobMcpActionEntries = (job) => {
+            const getJobMcpActionEntries = async (job) => {
                 const requested = job?.meta.mcpTools ?? [];
                 if (requested.length === 0)
                     return {};
+                // Background action suppliers may be async so event-triggered and
+                // scheduled runs can await lazy MCP hydration on serverless cold
+                // starts. Runs without requested MCP tools still skip this work.
+                await ensureMcpInitialized();
                 const entries = mcpToolsToActionEntries(mcpManager, {
                     toolNames: requested,
                 });
@@ -354,7 +361,7 @@ export function createAgentChatPlugin(options) {
             mountMcpServersRoutes(nitroApp, mcpManager, {
                 // Serialize an unusually early settings mutation behind the initial
                 // config snapshot so stale startup data cannot overwrite the write.
-                waitUntilReady: () => mcpInitializationPromise ?? Promise.resolve(),
+                waitUntilReady: ensureMcpInitialized,
             });
             // Hub-serve: expose org-scope servers to other agent-native apps in the
             // workspace when `AGENT_NATIVE_MCP_HUB_TOKEN` is set (dispatch, by
@@ -825,25 +832,28 @@ export function createAgentChatPlugin(options) {
             // background surface. Interactive-only tools stay out of it, while
             // shared capabilities such as call-agent and core-send-email cannot
             // drift independently between the two background entry points.
-            const getBackgroundActionEntries = (automation) => ({
-                ...templateScripts,
-                ...resourceScripts,
-                ...docsScripts,
-                ...(lazyContext ? frameworkContextTool : {}),
-                ...urlTools,
-                ...chatScripts,
-                ...callAgentScript,
-                ...jobTools,
-                ...automationTools,
-                ...notificationTools,
-                ...progressTools,
-                ...fetchTool,
-                ...webSearchTool,
-                ...toolActions,
-                ...backgroundCoreEmailTools,
-                ...coreAttachmentTools,
-                ...getJobMcpActionEntries(automation),
-            });
+            const getBackgroundActionEntries = async (automation) => {
+                const mcpActions = await getJobMcpActionEntries(automation);
+                return {
+                    ...templateScripts,
+                    ...resourceScripts,
+                    ...docsScripts,
+                    ...(lazyContext ? frameworkContextTool : {}),
+                    ...urlTools,
+                    ...chatScripts,
+                    ...callAgentScript,
+                    ...jobTools,
+                    ...automationTools,
+                    ...notificationTools,
+                    ...progressTools,
+                    ...fetchTool,
+                    ...webSearchTool,
+                    ...toolActions,
+                    ...backgroundCoreEmailTools,
+                    ...coreAttachmentTools,
+                    ...mcpActions,
+                };
+            };
             // -----------------------------------------------------------------------
             // Production code-execution mode resolution.
             //
@@ -4514,6 +4524,10 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
             // the background worker), so both go through identical context + handler
             // selection.
             const invokeAgentChatHandler = async (event) => {
+                // Chat is the main MCP consumer, and on serverless nothing hydrated the
+                // manager at boot. Awaiting here trades first-chat latency for tools
+                // that are actually present instead of a silently MCP-less run.
+                await ensureMcpInitialized();
                 // Resolve per-request auth context.
                 const ownerContext = await resolveOwnerContext(event);
                 return runWithAgentRunContext({
@@ -4851,6 +4865,10 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                         };
                     }
                     try {
+                        // Jobs may request MCP tools, and `getActions` is synchronous —
+                        // hydrate before the sweep so a serverless container that never
+                        // eagerly initialized still resolves them.
+                        await ensureMcpInitialized();
                         await processRecurringJobs(schedulerDeps);
                         return { ok: true };
                     }
@@ -4913,10 +4931,17 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                     setInterval(() => void sweep(), 30_000);
                 })();
             }
-            mcpInitializationPromise = initializeMcpManager().catch((err) => {
-                console.warn(`[mcp-client] deferred initialization failed: ${err?.message ?? err}`);
-            });
-            void mcpInitializationPromise;
+            // Long-lived runtimes hydrate MCP once at boot. Serverless functions must
+            // not: nothing awaits this, so a settings scan plus third-party MCP
+            // handshakes run on EVERY cold start of every app — including requests
+            // that never touch MCP — and outlive the response on a runtime that
+            // freezes after responding. There, `ensureMcpInitialized()` is driven by
+            // the surfaces that consume MCP tools instead.
+            if (!isProductionServerlessFunctionRuntime()) {
+                void ensureMcpInitialized().catch((err) => {
+                    console.warn(`[mcp-client] eager initialization failed: ${err?.message ?? err}`);
+                });
+            }
             // ─── Agent Teams orphan sweep ─────────────────────────────────────
             // Re-fires stuck/queued dispatches when the browser is closed and the
             // RunsTray's per-user reconciliation never triggers. Runs every 2 minutes

package/dist/server/http-response-telemetry.js

@@ -13,10 +13,21 @@ const TRACKING_INGEST_PATHS = new Set([
     "/api/events/track",
     "/_agent-native/track",
 ]);
+const SLOW_REQUEST_MS = 1_000;
+const SLOW_REQUEST_LOG_EVENT = "agent-native.slow_request";
 const PROCESS_STATE_KEY = Symbol.for("@agent-native/core/http-response-telemetry.process-state");
 const globalRef = globalThis;
+// Process start → this module being evaluated. On a serverless cold start that
+// span is the platform's container boot plus server-bundle evaluation, which
+// happens entirely before any request handler runs and is therefore invisible
+// to every in-handler measurement. Recorded here because module scope is the
+// earliest point our own code can observe. Stored on globalThis so the
+// earliest-evaluated copy wins if the bundle loads this module twice.
 const processState = globalRef[PROCESS_STATE_KEY] ??
-    (globalRef[PROCESS_STATE_KEY] = { requestSequence: 0 });
+    (globalRef[PROCESS_STATE_KEY] = {
+        requestSequence: 0,
+        moduleEvalUptimeMs: Math.max(0, Math.round(process.uptime() * 1_000)),
+    });
 const REQUEST_TELEMETRY_KEY = Symbol.for("@agent-native/core/http-response-telemetry.request");
 const installedApps = new WeakSet();
 function envValue(key) {
@@ -118,7 +129,7 @@ function shouldTrack(pathname, statusCode, state) {
         return true;
     if (state.startupDb)
         return true;
-    if (Date.now() - state.startedAt >= 1_000)
+    if (Date.now() - state.startedAt >= SLOW_REQUEST_MS)
         return true;
     if (state.db.errorCount > 0 || state.db.timeoutCount > 0) {
         return true;
@@ -151,6 +162,10 @@ function runtimeProvider() {
         return "cloudflare-pages";
     return "node";
 }
+/** Module evaluation → this request starting, i.e. idle boot the app paid for. */
+function moduleToRequestMs(state) {
+    return Math.max(0, state.processAgeAtStartMs - processState.moduleEvalUptimeMs);
+}
 function emitTelemetry(event, state, response) {
     const statusCode = responseStatusCode(event, response);
     const pathname = requestPath(event);
@@ -175,6 +190,8 @@ function emitTelemetry(event, state, response) {
             cold_start: state.requestSequence === 1,
             request_sequence: state.requestSequence,
             process_age_ms: state.processAgeAtStartMs,
+            boot_to_module_ms: processState.moduleEvalUptimeMs,
+            module_to_request_ms: moduleToRequestMs(state),
             framework_ready_wait_ms: state.frameworkReadyWaitMs,
             runtime_provider: runtimeProvider(),
             function_name: envValue("AWS_LAMBDA_FUNCTION_NAME"),
@@ -238,20 +255,99 @@ function requestTelemetryState(event) {
 export function getHttpRequestTelemetryId(event) {
     return requestTelemetryState(event)?.requestId;
 }
-function appendServerTiming(response, event, name, durationMs) {
+function appendServerTiming(response, event, name, durationMs, desc) {
     const duration = Math.max(0, Math.round(durationMs));
+    const suffix = desc ? `;desc=${JSON.stringify(desc)}` : "";
     try {
-        response.headers.append("server-timing", `${name};dur=${duration}`);
+        response.headers.append("server-timing", `${name};dur=${duration}${suffix}`);
     }
     catch {
         try {
-            setServerTiming(event, name, { dur: duration });
+            setServerTiming(event, name, desc ? { dur: duration, desc } : { dur: duration });
         }
         catch {
             // Some adapters finalize headers eagerly. Tracking still runs.
         }
     }
 }
+/**
+ * Does this response get stored in a shared (CDN) cache and replayed?
+ *
+ * SSR HTML and React Router `.data` are one impersonal shell hard-cached for
+ * every visitor, so their headers are written ONCE by the origin render and
+ * then handed unchanged to everyone who hits the cache afterwards.
+ */
+function isSharedCacheable(response) {
+    const cacheControl = response.headers.get("cache-control")?.toLowerCase() ?? "";
+    if (!cacheControl)
+        return false;
+    if (/\b(?:no-store|no-cache|private)\b/.test(cacheControl))
+        return false;
+    return (/\bpublic\b/.test(cacheControl) || /\bs-maxage=[1-9]/.test(cacheControl));
+}
+/**
+ * Per-phase `server-timing` entries do NOT belong on a shared-cacheable
+ * response. `app;dur=2159` on a cached shell describes one origin render from
+ * an arbitrary point in the past, yet every later visitor reads it as the cost
+ * of their own request — a stale number wearing a live number's name.
+ *
+ * So a cacheable response gets exactly one entry, `origin`, whose description
+ * leads with the absolute wall-clock time of the render that produced it. Two
+ * visitors comparing notes see the identical timestamp, which is what a replay
+ * is. The live per-invocation breakdown goes to the slow-request log line and
+ * to tracking instead; neither is ever cached.
+ */
+function originSnapshotDesc(state) {
+    const parts = [new Date(state.startedAt).toISOString()];
+    if (state.requestSequence === 1) {
+        parts.push("cold", `boot=${processState.moduleEvalUptimeMs}`, `init=${moduleToRequestMs(state)}`);
+    }
+    if (state.frameworkReadyWaitMs > 0) {
+        parts.push(`startup=${Math.round(state.frameworkReadyWaitMs)}`);
+    }
+    if (state.db.operationCount > 0) {
+        parts.push(`db=${Math.round(state.db.operationWallMs)}`, `dbops=${state.db.operationCount}`);
+    }
+    return parts.join(" ");
+}
+/**
+ * One structured line per cold or slow request, straight to stdout.
+ *
+ * Function logs are the only timing surface readable without a deploy, and
+ * `track()` silently no-ops when no tracking provider is registered — which is
+ * the common case. Deliberately NOT wrapped in a catch: a swallowed emit would
+ * leave a slow request indistinguishable from a fast one.
+ */
+function logSlowRequest(event, state, response, durationMs, pathname) {
+    const coldStart = state.requestSequence === 1;
+    if (!coldStart && durationMs < SLOW_REQUEST_MS)
+        return;
+    console.log(JSON.stringify({
+        event: SLOW_REQUEST_LOG_EVENT,
+        app: getAppName(),
+        method: getMethod(event),
+        path: normalizeHttpTelemetryPath(pathname),
+        status: responseStatusCode(event, response),
+        duration_ms: Math.round(durationMs),
+        cold_start: coldStart,
+        request_sequence: state.requestSequence,
+        boot_to_module_ms: processState.moduleEvalUptimeMs,
+        module_to_request_ms: moduleToRequestMs(state),
+        process_age_ms: state.processAgeAtStartMs,
+        framework_ready_wait_ms: Math.round(state.frameworkReadyWaitMs),
+        db_ms: Math.round(state.db.operationWallMs),
+        db_connect_ms: Math.round(state.db.connectTotalMs),
+        db_operation_count: state.db.operationCount,
+        db_error_count: state.db.errorCount,
+        db_timeout_count: state.db.timeoutCount,
+        startup_db_ms: state.startupDb
+            ? Math.round(state.startupDb.operationWallMs)
+            : undefined,
+        shared_cacheable: response ? isSharedCacheable(response) : undefined,
+        runtime_provider: runtimeProvider(),
+        request_id: state.requestId,
+    }));
+}
 export function recordFrameworkReadyWait(event, durationMs) {
     const state = requestTelemetryState(event);
     if (state) {
@@ -295,7 +391,17 @@ export function installHttpResponseTelemetryHooks(nitroApp) {
                 // Some adapters finalize headers eagerly. Tracking still has the id.
             }
         }
+        if (isSharedCacheable(response)) {
+            appendServerTiming(response, event, "origin", durationMs, originSnapshotDesc(state));
+            logSlowRequest(event, state, response, durationMs, requestPath(event));
+            emitTelemetry(event, state, response);
+            return;
+        }
         appendServerTiming(response, event, "app", durationMs);
+        if (state.requestSequence === 1) {
+            appendServerTiming(response, event, "boot", processState.moduleEvalUptimeMs);
+            appendServerTiming(response, event, "init", moduleToRequestMs(state));
+        }
         if (state.frameworkReadyWaitMs > 0) {
             appendServerTiming(response, event, "startup", state.frameworkReadyWaitMs);
         }
@@ -309,6 +415,7 @@ export function installHttpResponseTelemetryHooks(nitroApp) {
             appendServerTiming(response, event, "startup-db", state.startupDb.operationWallMs);
             appendServerTiming(response, event, "startup-db-connect", state.startupDb.connectTotalMs);
         }
+        logSlowRequest(event, state, response, durationMs, requestPath(event));
         emitTelemetry(event, state, response);
     });
 }

package/dist/server/realtime-token.d.ts

@@ -26,8 +26,8 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
-    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
+    error?: undefined;
 }>>;

package/dist/server/release-migrations.js

@@ -2,6 +2,7 @@ import { CONTEXT_XRAY_MIGRATIONS } from "../agent/context-xray/migrations.js";
 import { OBSERVATIONAL_MEMORY_MIGRATIONS } from "../agent/observational-memory/migrations.js";
 import { runMigrations } from "../db/migrations.js";
 import { runAutomationRunMigrations } from "../jobs/run-history.js";
+import { runAutomationSchedulerHealthMigrations } from "../jobs/scheduler-health.js";
 import { ORG_MIGRATIONS } from "../org/migrations.js";
 import { runBetterAuthMigrations } from "./better-auth-migrations.js";
 /**
@@ -21,4 +22,5 @@ export async function runFrameworkReleaseMigrations(nitroApp) {
         table: "_observational_memory_migrations",
     })(nitroApp);
     await runAutomationRunMigrations(nitroApp);
+    await runAutomationSchedulerHealthMigrations(nitroApp);
 }

package/dist/server/ssr-handler.js

@@ -193,6 +193,14 @@ function isSsrHtmlOrDataResponse(headers, status, pathname) {
  * │ hatch — because that is what poisons a shared CDN cache key. A value fixed │
  * │ for the whole deployment cannot.                                           │
  * └──────────────────────────────────────────────────────────────────────────┘
+ *
+ * The same sharing rule governs any DIAGNOSTIC header on this response. A
+ * per-request timing written here is stored once by the origin render and
+ * replayed unchanged to every later visitor, so it must not wear a live-looking
+ * phase name. `installHttpResponseTelemetryHooks` detects the shared-cacheable
+ * policy stamped below and collapses `server-timing` to one `origin` entry
+ * carrying the render's wall-clock time; do not add a per-request header here
+ * that contradicts that.
  */
 function applyDefaultSsrCacheHeader(headers, status, pathname) {
     if (!isSsrHtmlOrDataResponse(headers, status, pathname))

package/dist/server/transcribe-voice.d.ts

@@ -20,6 +20,6 @@ export declare function createTranscribeVoiceHandler(): import("h3").EventHandle
     error: string;
     text?: undefined;
 } | {
-    error?: undefined;
     text: string;
+    error?: undefined;
 }>>;

package/dist/templates/chat/app/hooks/use-navigation-state.ts

@@ -42,7 +42,10 @@ function viewForPath(pathname: string): string {
   if (pathname.startsWith("/database")) return "database";
   if (pathname.startsWith("/extensions")) return "extensions";
   if (pathname.startsWith("/observability")) return "observability";
-  if (pathname.startsWith("/agent")) return "agent";
+  if (pathname.startsWith("/settings/agent") || pathname.startsWith("/agent")) {
+    return "agent";
+  }
+  if (pathname.startsWith("/settings")) return "settings";
   if (pathname.startsWith("/team")) return "settings";
   return "chat";
 }
@@ -60,7 +63,7 @@ function pathForView(view?: string): string {
     case "observability":
       return "/observability";
     case "agent":
-      return "/agent";
+      return "/settings/agent";
     case "settings":
       return "/settings";
     case "team":

package/dist/templates/chat/app/routes/agent.tsx

@@ -1,5 +1,4 @@
-import { useT } from "@agent-native/core/client/i18n";
-import { useSetPageTitle } from "@agent-native/toolkit/app-shell";
+import { buildLegacyAgentSettingsRoute } from "@agent-native/core/client/navigation";
 import { Navigate, useLocation } from "react-router";
 
 export function meta() {
@@ -7,34 +6,11 @@ export function meta() {
 }
 
 export default function AgentRoute() {
-  const t = useT();
   const location = useLocation();
-  useSetPageTitle(t("settings.agentTitle"));
-
-  const legacyTab = location.hash.replace(/^#/, "").toLowerCase();
-  const resourceTabs = new Set([
-    "files",
-    "instructions",
-    "agents",
-    "memory",
-    "skills",
-    "learnings",
-  ]);
-  const destination = resourceTabs.has(legacyTab)
-    ? `/settings/agent/resources/${legacyTab}`
-    : legacyTab === "remote-agents"
-      ? "/settings/agent/agents"
-      : legacyTab === "connections"
-        ? "/settings/integrations"
-        : legacyTab === "jobs"
-          ? "/settings/agent/automations"
-          : legacyTab === "access"
-            ? "/settings/agent"
-            : ["llm", "app-models", "limits", "voice", "background"].includes(
-                  legacyTab,
-                )
-              ? `/settings/agent/${legacyTab}`
-              : "/settings/agent";
-
-  return <Navigate to={destination} replace />;
+  return (
+    <Navigate
+      to={buildLegacyAgentSettingsRoute(location.hash, location.search)}
+      replace
+    />
+  );
 }

package/dist/templates/default/app/routes/_index.tsx

@@ -76,7 +76,7 @@ export default function IndexPage() {
             </p>
           </Link>
           <Link
-            to="/agent"
+            to="/settings/agent"
             className="group rounded-lg border border-border/50 px-4 py-3 hover:bg-accent/50 transition-colors"
           >
             <p className="text-[13px] font-medium text-foreground">

package/dist/templates/default/app/routes/agent.tsx

@@ -1,34 +1,16 @@
-import { AgentTabsPage } from "@agent-native/core/client/agent-chat";
-import { useT } from "@agent-native/core/client/i18n";
-import { Link } from "react-router";
+import { buildLegacyAgentSettingsRoute } from "@agent-native/core/client/navigation";
+import { Navigate, useLocation } from "react-router";
 
 export function meta() {
   return [{ title: "Agent - {{APP_TITLE}}" }];
 }
 
 export default function AgentPage() {
-  const t = useT();
-
+  const location = useLocation();
   return (
-    <main className="min-h-screen bg-background px-6 py-10">
-      <div className="mx-auto w-full max-w-5xl space-y-6">
-        <div className="space-y-2">
-          <Link
-            to="/settings"
-            className="text-[13px] text-muted-foreground hover:text-foreground"
-          >
-            {t("settings.title")}
-          </Link>
-          <h1 className="text-2xl font-semibold tracking-tight text-foreground">
-            {t("settings.agentTitle")}
-          </h1>
-          <p className="text-[14px] leading-relaxed text-muted-foreground">
-            {t("settings.agentDescription")}
-          </p>
-        </div>
-
-        <AgentTabsPage className="min-h-[640px] rounded-lg border border-border/50" />
-      </div>
-    </main>
+    <Navigate
+      to={buildLegacyAgentSettingsRoute(location.hash, location.search)}
+      replace
+    />
   );
 }