Context AwarenessCAUTION

A framework for building agentic apps

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: context-awareness
description: >-
  How the agent knows what the user is looking at. Use when exposing UI state to
  the agent, implementing view-screen or navigate actions, wiring navigation
  state, or debugging agent context issues.
scope: dev
metadata:
  internal: true
---

# Context Awareness

## Rule

Apps can sync semantic navigation state when the route changes by using the
shared route-state hook. When screen context is available, Core includes a
`<current-screen>` snapshot in each agent turn, so the agent can get basic
route context without first calling another tool. Apps can add concise
visible-record details to that snapshot and expose selection in tab-scoped
state.

## Why

Without context awareness, the agent is blind. It asks "which email?" when the user is staring at one. It cannot act on the current selection, cannot provide relevant suggestions, and cannot modify what the user sees. Context awareness is what makes the agent feel like a collaborator rather than a disconnected chatbot.

## The Core Patterns

### 1. Navigation State (`navigation` key)

Use the shared route-state hook to write a tab-scoped `navigation` key as the
route changes. Include semantic screen state such as the view, open IDs, active
tab, and focused object.

**UI side** — use `useAgentRouteState` in the app's route-state hook. The app
can wrap it in an app-owned `useNavigationState` hook to map route paths to
semantic views and consume the agent's `navigate` command.

```tsx
// app/hooks/use-navigation-state.ts
import { useAgentRouteState } from "@agent-native/core/client/navigation";
import { TAB_ID } from "@/lib/tab-id";

export function useNavigationState() {
  useAgentRouteState({
    browserTabId: TAB_ID,
    requestSource: TAB_ID,
    getNavigationState: ({ pathname, searchParams }) => ({
      view:
        pathname === "/"
          ? "home"
          : pathname === "/sign-in"
            ? "sign-in"
            : pathname.replace(/^\/+/, ""),
      // Optional semantic alias. Raw query params are already exposed in
      // <current-url> and controllable with set-search-params.
      label: searchParams.get("label"),
    }),
    getCommandPath: (command: any) =>
      command.path ?? `/${command.view === "home" ? "home" : command.view}`,
  });
}
```

The default scaffold uses `/home` for home and `/sign-in` for authentication;
`/` redirects according to the configured home route. Map navigation to the
app's actual routes and pass an explicit `path` for destinations that do not
follow the `/<view>` convention.

`TAB_ID` comes from the framework's `getBrowserTabId()` (see the scaffolded `app/lib/tab-id.ts`; never redefine it). The server resolves tab-scoped `application_state` writes and page-local WebMCP calls (`X-Agent-Native-Browser-Tab`) against this same id, so a hand-rolled random id silently breaks selection sync for hidden and background tabs.

**Agent side** — read before acting:

```ts
import { readAppState } from "@agent-native/core/application-state";

const navigation = await readAppState("navigation");
// e.g. { view: "thread", threadId: "abc123", subject: "Re: Q3 Planning" }
```

**What to include in navigation state:**

- `view` — the current page/section (e.g., "inbox", "form-builder", "dashboard")
- Item IDs — the selected/open item (e.g., `threadId`, `formId`, `issueKey`)
- Semantic aliases — label names, active tabs, focused row, or stable filter names the agent should reason about
- Focused object IDs and active tabs that are not already represented by URL state

Keep text-selection ranges and excerpts in the tab-scoped `selection` key, not
in `navigation`.

Raw URL query params are already synced by the framework to `__url__` and shown to the built-in agent as `<current-url>`. Keep shareable filters in URL state, then use `view-screen` to summarize important query params as `activeFilters` when helpful.

Keep `application_state` values small. Do not store pasted files, base64 images,
recording chunks, screenshots, or other large blobs in navigation or app-state
keys; upload them and store only a URL or storage handle.

### Selection state

For app-owned per-tab selection, suffix the key with `TAB_ID`; `requestSource`
labels the write origin but does not scope the key. Keep the value to stable ids
and a short label or excerpt, never the full document:

```ts
import { writeClientAppState } from "@agent-native/core/client/hooks";
import { TAB_ID } from "@/lib/tab-id";

await writeClientAppState(
  `selection:${TAB_ID}`,
  { kind: "text", id: "artifact-123", text: "short excerpt" },
  { requestSource: TAB_ID },
);
```

A server action can read that tab's value with
`readAppStateForCurrentTab("selection")`. A `view-screen` result may include the
selection and a specific next action when that helps the agent target an edit.

### 2. Current URL (`__url__` key)

`AgentPanel` automatically writes `__url__` with `{ pathname, search, hash, searchParams }`. The built-in agent sees it as a `<current-url>` block in every turn.

Use this for URL-reachable filters and search state. The agent can update it with the built-in `set-search-params` and `set-url-path` tools; do not duplicate the whole query string into `navigation`.

### Settings page (`settings-view` key)

The redesigned Settings shell writes tab-scoped `settings-view` = `{ page, sub, label }` (for example `{ page: "integrations", sub: "builder", label: "Connections › Integrations › Builder.io" }`) and deletes it when Settings closes. `<current-url>` shows it as a `settingsPage:` line, because a legacy or mounted pathname doesn't name the page the shell resolved. To send the user to a page, call the built-in `open-settings-page` tool with a page id (plus `sub` or `anchor`); it resolves old tab and section ids through the same redirect table as links. A template's own `navigate` action only needs a Settings branch for its app areas (`/settings/app/<area>`), built with `buildSettingsRoute`.

### 3. The `view-screen`

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (5)

.agents/skills/an

.agents/skills/content-product-development

.agents/skills/design-exploration

.agents/skills/turn-into-app

.agents/skills/visual-edit

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Context Awareness](https://modelsatlas.com/skills/builderio/context-awareness/badge.svg)](https://modelsatlas.com/skills/builderio/context-awareness/)

Not your listing, or something out of date? Claim or update your listing.