@agent-native/core 0.98.17 → 0.99.0

package/src/templates/default/.agents/skills/security/SKILL.md

@@ -147,6 +147,16 @@ export default defineEventHandler(async (event) => {
 
 - Never create unprotected routes that modify data.
 
+**Exception — the SSR HTML/`.data` catch-all is deliberately session-blind.**
+The rule above is for routes that read or mutate user data. The SSR page
+render and React Router `.data` route are different: they serve one
+impersonal, public-cacheable shell to every visitor by design, and loaders on
+that path render no user data. Do not "fix" this by adding `getSession`,
+`private`, or `no-store` to it — that regresses the CDN cache contract for the
+whole site. Data scoping lives in actions and API routes; the client gates
+private UI after the shell loads. See the `authentication` skill and
+`guard:ssr-cache-shell` / `ssr-handler.spec.ts`.
+
 ## Human-in-the-Loop Approval for High-Consequence Actions
 
 For a small set of outward-facing, hard-to-undo operations — sending an email, charging a card, deleting an account, posting publicly — auth and access control are necessary but not sufficient: you also do not want the **agent** to perform them autonomously. Set `needsApproval` on the `defineAction` so the agent cannot run the action without a human approving the specific call.

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

@@ -36,12 +36,12 @@ Auth is powered by **Better Auth** with account-first design. Every new user cre
 
 ## Remote MCP OAuth
 
-Every app's `/_agent-native/mcp` endpoint is also a standard protected MCP
+Every app's `/mcp` endpoint is also a standard protected MCP
 resource. OAuth-capable hosts connect with the remote MCP URL only, receive a
 `WWW-Authenticate` challenge, discover `/.well-known/oauth-protected-resource`
 and `/.well-known/oauth-authorization-server`, dynamically register a public
 client, and complete authorization-code + PKCE at
-`/_agent-native/mcp/oauth/authorize` / `/_agent-native/mcp/oauth/token`.
+`/mcp/oauth/authorize` / `/mcp/oauth/token`.
 Access tokens are audience-bound to the exact MCP URL and carry user/org
 identity plus `mcp:read`, `mcp:write`, `mcp:apps`, and/or `offline_access`;
 advertising `offline_access` lets hosts such as ChatGPT retain refresh access.
@@ -137,10 +137,19 @@ Bookmarked private paths work through the client session gate: the shared shell
 ## Gating the App Shell (avoid the logged-out infinite spinner)
 
 Normal app HTML and React Router page-data responses deliberately bypass the
-server session guard. They are rendered impersonally and cached as one shared
-shell; APIs, actions, and framework data routes remain server-protected. The
-client session gate is therefore the authoritative decision point for whether
-private app UI renders.
+server session guard. They are rendered impersonally and cached as one shared,
+public, hard-cached-at-the-CDN shell; APIs, actions, and framework data routes
+remain server-protected. The client session gate is therefore the
+authoritative decision point for whether private app UI renders.
+
+**Never**, on the SSR HTML/`.data` path: set `private`, `no-store`, or
+`Vary: Cookie`; call `getSession` or read cookies in the SSR route or the
+login HTML path; or embed tokens/secrets into the rendered HTML — a
+token-bearing page still returns the same anonymous shell and resolves access
+client-side. This has regressed repeatedly (agents "fixing" it back to
+per-user SSR); it is enforced by `guard:ssr-cache-shell` and
+`ssr-handler.spec.ts` (`packages/core/src/server/ssr-handler.ts`), and reverts
+will be rejected.
 
 `AppProviders` applies `RequireSession` automatically on its private branch. It
 resolves the session on the client and redirects signed-out visitors to

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

@@ -21,12 +21,12 @@ An agent-native app is reachable by any MCP-compatible host (Claude, Claude
 Desktop, Claude Code, ChatGPT custom MCP apps, Codex, Cursor, Cowork, VS Code
 GitHub Copilot, Goose, Postman, MCPJam, and future standard clients). Keep
 setup simple: for workspace or cross-app access, add one remote MCP connector:
-`https://dispatch.agent-native.com/_agent-native/mcp`. Dispatch's Agents page
+`https://dispatch.agent-native.com/mcp`. Dispatch's Agents page
 controls whether that single connector reaches all apps or only selected apps,
 and Dispatch filters `list_apps`, `ask_app`, and `open_app` to the granted set.
 For a deliberately isolated app, add that app directly at
-`https://<app>.agent-native.com/_agent-native/mcp` or
-`https://<your-host>/_agent-native/mcp`.
+`https://<app>.agent-native.com/mcp` or
+`https://<your-host>/mcp`.
 
 OAuth-capable hosts should use the standard remote MCP OAuth flow. Claude
 connectors and Claude Code `/mcp` authentication discover the protected
@@ -68,7 +68,7 @@ the real app focused on exactly what was produced. It reuses the existing
 Use one connector for normal workspace access:
 
 ```text
-https://dispatch.agent-native.com/_agent-native/mcp
+https://dispatch.agent-native.com/mcp
 ```
 
 Then open Dispatch → Agents to choose whether the gateway exposes every app or
@@ -79,8 +79,8 @@ only selected app IDs. External agents call `list_apps` to see the granted set,
 Use a direct app URL only when you intentionally want one isolated app:
 
 ```text
-https://mail.agent-native.com/_agent-native/mcp
-https://<your-app>.agent-native.com/_agent-native/mcp
+https://mail.agent-native.com/mcp
+https://<your-app>.agent-native.com/mcp
 ```
 
 Claude / Claude Desktop: add a custom connector with the URL, click Connect,
@@ -104,7 +104,7 @@ npx @agent-native/core@latest connect https://mail.agent-native.com
 
 The command opens the app in the browser, the user clicks **Authorize**, and a
 per-user, scoped, revocable token is written to the selected client config. The
-no-CLI equivalent is `https://<app>/_agent-native/mcp/connect`, which shows
+no-CLI equivalent is `https://<app>/mcp/connect`, which shows
 the copyable MCP URL, Claude / ChatGPT / Cursor / Claude Code / Codex / Other
 steps, and static-token fallback for clients that need it.
 
@@ -130,7 +130,7 @@ that MCP URL; pass `--client` to limit which configs it searches. Pass
 Under the hood: a logged-in browser session mints an `A2A_SECRET`-signed JWT
 carrying the caller's `sub` + `org_domain` and a unique `jti`, so tool runs
 stay tenant-scoped via `runWithRequestContext`. The existing
-`/_agent-native/mcp` endpoint accepts it like any bearer — no new endpoint.
+`/mcp` endpoint accepts it like any bearer — no new endpoint.
 The same Connect page lists and revokes minted tokens by `jti`; treat them
 like personal access tokens. Nothing exposes the deployment's shared secret.
 
@@ -146,7 +146,13 @@ agent has a predictable surface without guessing per-app action names:
   "Open …" link and, with `embed: true`, an inline full-app MCP App in capable
   hosts.
 - `ask_app({ app, message })` — routes a natural-language task to that app's
-  in-app agent (delegates to the existing `ask-agent` meta-tool).
+  in-app agent (delegates to the existing `ask-agent` meta-tool). It also
+  accepts `async` and `maxWaitMs`; hosted calls wait at most 25 seconds inline
+  and return a durable `taskId` plus an `ask_app_status` poll instruction when
+  the task is still running.
+- `ask_app_status({ app, taskId })` — retrieves the current or terminal result
+  for a durable `ask_app` task. Dispatch checks the selected-app grant again
+  before polling.
 - `create_workspace_app({ name, template })` — scaffolds + boots a new app via
   the workspace path (rejects non-allow-listed templates), returns its running
   URL + deep link.
@@ -375,7 +381,7 @@ the `[mcp_servers.*]` block in `~/.codex/config.toml` for Codex,
 user `mcp.json` for GitHub Copilot / VS Code, and the Claude-Code JSON shape
 for Cowork. The entry runs `pnpm exec agent-native mcp serve --app <id>`, by
 default a **thin stdio proxy** to the running local app's
-`/_agent-native/mcp` (live registry + HMR + correct deep links stay the single
+`/mcp` (live registry + HMR + correct deep links stay the single
 source of truth; `--standalone` builds the registry in-process). Companion
 subcommands: `mcp uninstall`, `mcp status`, `mcp token [--rotate]`. You can
 also hand-write an `http` `.mcp.json` entry with a token you supply yourself —

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

@@ -121,7 +121,24 @@ index the growing tables first.
 - Data the UI doesn't display (export formats, alternate renderings) belongs in a
   separate on-demand action, not baked into the hot read.
 
-## 6. Big payloads and long lists
+## 6. SSR shell caching — load-bearing, do not undo
+
+Every SSR HTML page and React Router `.data` response is one impersonal,
+public shell, hard-cached at the CDN and served identically to every visitor —
+logged in or not. This is the single biggest lever on first-response latency:
+one shared cache entry serves the whole site instead of a per-user render on
+every request. Adding `private`, `no-store`, `Vary: Cookie`, a session read, or
+an auth branch to the SSR path defeats the cache for **every visitor**, not
+just one.
+
+If you're debugging a slow first response, check whether something
+re-personalized the shell before concluding the render itself is slow — the
+fix is client-side data loading after the shell paints, never per-user SSR.
+See the `authentication` skill for the full model and `guard:ssr-cache-shell`
+plus `ssr-handler.spec.ts` (`packages/core/src/server/ssr-handler.ts`) for the
+enforced contract.
+
+## 7. Big payloads and long lists
 
 - **Paginate or window** unbounded lists (messages, responses, events, activity).
   Don't load the entire history on open; load a recent window and fetch older on
@@ -144,3 +161,5 @@ index the growing tables first.
 - [ ] Client fires independent queries in parallel, not a waterfall.
 - [ ] No heavy recompute on every read; no aggressive polling of heavy endpoints.
 - [ ] Unbounded lists are paginated/windowed; large blobs aren't inlined on the hot path.
+- [ ] SSR HTML/`.data` path stays session-blind and cacheable — no `private`,
+      `no-store`, `Vary: Cookie`, or auth branch added to it.

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

@@ -147,6 +147,16 @@ export default defineEventHandler(async (event) => {
 
 - Never create unprotected routes that modify data.
 
+**Exception — the SSR HTML/`.data` catch-all is deliberately session-blind.**
+The rule above is for routes that read or mutate user data. The SSR page
+render and React Router `.data` route are different: they serve one
+impersonal, public-cacheable shell to every visitor by design, and loaders on
+that path render no user data. Do not "fix" this by adding `getSession`,
+`private`, or `no-store` to it — that regresses the CDN cache contract for the
+whole site. Data scoping lives in actions and API routes; the client gates
+private UI after the shell loads. See the `authentication` skill and
+`guard:ssr-cache-shell` / `ssr-handler.spec.ts`.
+
 ## Human-in-the-Loop Approval for High-Consequence Actions
 
 For a small set of outward-facing, hard-to-undo operations — sending an email, charging a card, deleting an account, posting publicly — auth and access control are necessary but not sufficient: you also do not want the **agent** to perform them autonomously. Set `needsApproval` on the `defineAction` so the agent cannot run the action without a human approving the specific call.