# Agent Sessions and public agent chat route

## Why this note exists

This train makes `Agent Sessions` the canonical internal full-page chat surface and
introduces the browser-safe public agent chat substrate. Public browser clients use
platform-issued access grants and short-lived capability tokens; they must not call
server-to-server session APIs with platform API keys.

The shared public chat UI is published from `@elevasis/ui/features/public-agent-chat`.
The tenant route is authored after the UI package publish, then propagated through the
strict manifest sync.

The template Organization Model now also declares the `operations-sessions` navigation
surface (`/operations/sessions`). That lets template-derived tenants inherit the
standard Agent Sessions page or opt into the same surface from their own OM navigation
without hand-authoring a route.

## Applies to

- Template-derived projects that want public or code-gated agent chat links.
- Projects syncing the template route baseline after the `@elevasis/ui` package baseline
  is bumped.
- Projects that want the internal Agent Sessions page exposed through OM-authored
  navigation.

## Required actions

1. Accept the package baseline updates for `@elevasis/core` and `@elevasis/ui`.
2. Accept the new public chat route baseline once it appears in
   `ui/src/routes/chat.$slug.tsx` and any root-shell adjustment needed to keep that route
   outside the authenticated app shell.
3. If your project customizes `core/config/organization-model/navigation.ts`, merge the
   `operations-sessions` surface into the Operations group:

```ts
'operations-sessions': {
  type: 'surface',
  label: 'Agent Sessions',
  path: '/operations/sessions',
  surfaceType: 'list',
  order: 30
}
```

4. Run the project UI install and typecheck/build after sync:

```bash
pnpm -C ui install
pnpm -C ui check-types
pnpm -C ui build
```

5. Configure platform-side public agent access grants before sharing a public chat URL.

## Verification

After sync, verify the OM exposes the Agent Sessions navigation surface:

```bash
grep -n "operations-sessions\\|Agent Sessions\\|/operations/sessions" core/config/organization-model/navigation.ts
pnpm -C core test
```

## Security notes

- Browser code must use the public grant/capability-token flow.
- Do not expose `ELEVASIS_PLATFORM_KEY` or operations API keys in browser code.
- Public turns use the public WebSocket route backed by a capability token.

## Not handled by /git-sync

`/git-sync` does not create production access grants, choose which agents are public,
merge project-owned OM customizations automatically, or redeploy tenant UIs. Those are
project/operator decisions after the code and package baselines are accepted.
