agenta-package-practices

# Agenta package practices

This skill is the source of truth for where frontend code lives and how the
`@agenta/*` workspace packages are used. Load it when you author or move code in
`web/packages/`, decide between the app layer and a package, or work with the entity
state primitives (molecules, bridges, pickers) or package unit tests.

## When to use this skill

- Deciding whether new code belongs in `web/oss`/`web/ee` (app layer) or a package.
- Importing from `@agenta/ui`, `@agenta/entities`, `@agenta/entity-ui`, `@agenta/shared`,
  `@agenta/playground`.
- Building with molecules, the loadable bridge, the runnable bridge, or the EntityPicker.
- Writing or fixing unit tests inside a package under `web/packages/*/tests/`.

## Code placement: packages vs application code

### Quick heuristic

```text
Is the code used by 2+ features, or could be?
├─ NO  → Keep it in the app layer (web/oss/src/ or web/ee/src/)
└─ YES → Move it to a package, picking by purpose:
         ├─ Reusable UI component / style util          → @agenta/ui
         ├─ Entity state (molecule, atoms, controllers) → @agenta/entities
         ├─ Entity-specific UI (modals, pickers)        → @agenta/entity-ui
         ├─ Playground state                            → @agenta/playground
         ├─ Playground UI                               → @agenta/playground-ui
         └─ Pure utility / type (no React, no antd)     → @agenta/shared
```

### Hard rules

- **Respect the hierarchy.** A package may only import from packages below it:
  `shared ← ui ← entities ← entity-ui ← playground ← playground-ui`. Circular imports
  break the build.
- **No legacy compat shims in packages.** Keep `OldFormat → NewFormat` adapters in the
  app layer. Packages stay clean.
- **No `any` types.** Packages enforce `@typescript-eslint/no-explicit-any: error`.
- **Never import the `queryClient` singleton.** Reach the cache with
  `getHostQueryClient()` from `@agenta/shared/api`, resolved per call. The singleton is the
  host's to install; on a host that brought its own client, writes to it silently do nothing.
  Lint-enforced. Contract: `web/AGENTS.md` § "The QueryClient host contract".
- **Use exported subpaths**, not internal paths:
  `import {x} from "@agenta/entities/testcase"`, not
  `from "@agenta/entities/src/testcase/state/molecule"`.
- **Verify your change builds AND lints before pushing:**
  `pnpm turbo run build --filter=@agenta/<package>` and
  `pnpm turbo run lint --filter=@agenta/<package>`.

## Package overview

| Package | Purpose | Key exports |
| --- | --- | --- |
| `@agenta/shared` | Pure utilities (no React) | Path utilities, common types |
| `@agenta/ui` | Reusable React components | `EnhancedModal`, `InfiniteVirtualTable`, `cn`, `textColors`, presentational components |
| `@agenta/entities` | Entity state/hooks/controllers | Molecules, bridges, controllers |
| `@agenta/entity-ui` | Entity-specific UI components | `EntityPicker`, `EntityCascader`, modals |
| `@agenta/playground` | Playground-specific components | `PlaygroundContent`, `EntitySelector`, `InputMappingModal` |

READMEs:

| Package | README |
| --- | --- |
| `@agenta/ui` | `web/packages/agenta-ui/README.md` |
| `@agenta/entities` | `web/packages/agenta-entities/README.md` |
| `@agenta/shared` | `web/packages/agenta-shared/README.md` |
| `@agenta/playground` | `web/packages/agenta-playground/` |

## Subpath imports for tree-shaking

Always use subpath imports. Importing from a root barrel (`@agenta/shared`) pulls the
entire dependency graph and inflates the bundle.

`@agenta/shared`:

```typescript
import {axios, getAgentaApiUrl, getEnv, configureAxios} from "@agenta/shared/api"
import {projectIdAtom, setProjectIdAtom} from "@agenta/shared/state"
import {dayjs, isValidUUID, getValueAtPath, setValueAtPath, formatNumber, formatLatency} from "@agenta/shared/utils"
import {useDebounceInput} from "@agenta/shared/hooks"
import {MESSAGE_CONTENT_SCHEMA, CHAT_MESSAGE_SCHEMA} from "@agenta/shared/schemas"
import type {SimpleChatMessage, MessageContent, ToolCall} from "@agenta/shared/types"
```

`@agenta/ui`:

```typescript
import {...} from "@agenta/ui"                    // presentational components, cn, textColors
import {...} from "@agenta/ui/table"              // InfiniteVirtualTable, paginated stores
import {...} from "@agenta/ui/editor"             // Editor, JSON parsing utilities
import {...} from "@agenta/ui/shared-editor"      // SharedEditor, useDebounceInput
import {...} from "@agenta/ui/chat-message"       // ChatMessageEditor, message types/schemas
import {...} from "@agenta/ui/llm-icons"          // LLM provider icons
import {...} from "@agenta/ui/cell-renderers"     // Table cell renderers, CellRendererRegistry
```

`@agenta/entities`:

```typescript
import {...} from "@agenta/entities"              // clean named exports (preferred)
import {...} from "@agenta/entities/shared"       // molecule factories, transforms
import {...} from "@agenta/entities/trace"        // trace/span molecule, schemas
import {...} from "@agenta/entities/testset"      // testset/revision molecules
import {...} from "@agenta/entities/testcase"     // testcase molecule
import {...} from "@agenta/entities/loadable"     // loadable bridge
import {...} from "@agenta/entities/runnable"     // runnable bridge
import {...} from "@agenta/entity-ui"             // UI components (modals, pickers)
```

## EnhancedModal (required for all new modals)

All new modals MUST use `EnhancedModal` from `@agenta/ui` instead of raw antd `Modal`.

```typescript
import {EnhancedModal, ModalContent, ModalFooter} from "@agenta/ui"

function MyModal({open, onClose}: {open: boolean; onClose: () => void}) {
    return (
        <EnhancedModal open={open} onCancel={onClose} title="Modal Title" footer={null}>
            <ModalContent>{/* Main content */}</ModalContent>
            <ModalFooter>
                <Button onClick={onClose}>Cancel</Button>
                <Button type="primary">Confirm</Button>