Integrate Fusion Agent

# Integrate Fusion Agent Panel

Wire a Flows/Dune app into the Fusion built-in PAIA agent using `@cognite/app-sdk`.

There are three independent capabilities — implement only the ones needed:

1. **Open the agent panel** — a button that shows the sidebar/fullscreen agent UI
2. **Send the agent a message** — inject context into the chat (e.g. on item click)
3. **Register an agent server** — expose app state (resources) and actions the agent can call

---

## Step 0 — Understand the app

Before writing any code, read:

- `package.json` — detect package manager and whether `@cognite/app-sdk` is already installed
- `src/App.tsx` (or main entry) — understand current structure, existing SDK usage

Ask the user which of the three capabilities they need if it's not clear from context.

---

## Step 1 — Install the SDK

If `@cognite/app-sdk` is not already in `package.json`, install it:

```shell
pnpm add @cognite/app-sdk     # or npm/yarn depending on the app
```

Minimum required version: `0.3.1`

---

## Step 2 — Connect to the host app

All capabilities require a `HostAppAPI` instance. Obtain it once on mount and store it in React state or context. Always catch the rejection — the SDK throws when running outside Fusion (e.g. standalone `vite dev`).

**Pattern for React apps:**

```typescript
// src/hooks/useHostApp.ts
import { useState, useEffect } from 'react';
import { connectToHostApp, type HostAppAPI } from '@cognite/app-sdk';

export function useHostApp(): HostAppAPI | null {
  const [api, setApi] = useState<HostAppAPI | null>(null);

  useEffect(() => {
    connectToHostApp({ applicationName: 'my-app' })
      .then(({ api: resolvedApi }) => {
        // IMPORTANT: use the updater form here. Comlink proxies are callable
        // objects, so setApi(proxy) causes React to invoke the proxy as a
        // state-updater function — storing a Promise instead of the proxy.
        // setApi(() => proxy) returns the proxy as the new state value.
        setApi(() => resolvedApi);
      })
      .catch(() => {
        // Running outside Fusion — agent features disabled, no-op
      });
  }, []);

  return api;
}
```

Call `useHostApp()` at the root of your app and pass `api` down (or put it in context). When `api` is `null`, all agent UI triggers should be hidden or disabled — not shown as broken.

---

## Step 3 — Opening the agent panel

Wire a persistent toolbar button (or equivalent trigger) to `api.sendAgentLayoutMode`.

```typescript
import { type AgentLayoutPayload } from '@cognite/app-sdk';

// Open as sidebar (most common)
await api.sendAgentLayoutMode({ mode: 'sidebar' });

// Other modes
await api.sendAgentLayoutMode({ mode: 'fullscreen' });
await api.sendAgentLayoutMode({ mode: 'closed' });
```

The button should only render when `api` is not null — agent features are unavailable outside Fusion.

```tsx
{api && (
  <button onClick={() => api.sendAgentLayoutMode({ mode: 'sidebar' })}>
    Open Assistant
  </button>
)}
```

---

## Step 4 — Sending the agent a message

Use `sendAgentMessage` on contextual triggers (e.g. "Analyse this item" button). Always pair it with `sendAgentLayoutMode` so the panel is visible.

```typescript
// Open sidebar then