---
path: /studio/yemaya/multi-agent-orchestration
surface: studio
domain: yemaya
auth: signed-in + studio entitlement
source: apps/oshun/web/src/app/studio/yemaya/multi-agent-orchestration/page.tsx
status: walked
last_walked:
  '2026-05-29 automated runtime walk (Playwright headless) — render, /v1 data
  (2xx), console/page-errors, expected content, screenshot verified; live
  screen-reader, touch, offline, and telemetry-delivery checks pending a manual
  AT pass. Evidence: WALKTHROUGH/results/runtime-sweep-2026-05-29.md; body
  re-derived 2026-06-03 from current source (lane-console architecture)'
---

# Studio · Yemaya · Multi-Agent Orchestration

## Purpose

Admin lane console wired to the `@yemaya/orchestration` retry-manager
primitives: classify an agent error message into a retry category and compute
the deterministic backoff delay (fixed / linear) — the recovery logic the
orchestration runtime uses to retry failed agent steps.

## Entry points

- Studio index quick-actions.
- No breadcrumb panel on this page.
- This page links out to `/studio/yemaya/davinci-integration`; reachable inbound
  from `/studio/yemaya/ai-content-generation`.
- Direct URL / bookmark (signed-in + studio entitlement).

## Layout regions

`page.tsx` renders `ShellLayout active="studio"` and:

- **Workspace panel** (`StudioYemayaMultiAgentOrchestrationWorkspace`,
  `data-yemaya-multi-agent-orchestration-workspace`):
  - `<h1>` "Yemaya Multi-Agent Orchestration Workspace".
  - Summary `<p data-yemaya-multi-agent-orchestration-summary>` (classify error +
    compute backoff).
  - **Classify form** and **Retry-delay form** (both shown once the catalog
    loads).
- **Route Map panel** (`data-yemaya-multi-agent-orchestration-route-map`): `<h2>`
  "Route Map" with five entries.
- **Quick-action panel**: two `quickAction` links.

## States

- [ ] **Loading** — `data-yemaya-mao-loading` ("Loading retry manager…").
- [ ] **Unauthorized** — 401/403 → `data-yemaya-mao-unauthorized` with reason
      "Yemaya workspace scope required to view multi-agent orchestration.".
- [ ] **Error** — non-OK / malformed catalog → `data-yemaya-mao-error`.
- [ ] **Ready-form** — catalog (`errorCategories`, `retryStrategies`) loaded; both
      forms render.
- [ ] **Classify result** — 200 → `data-yemaya-mao-category`; classify failure →
      `data-yemaya-mao-classify-error`.
- [ ] **Retry result** — 200 → `data-yemaya-mao-delay`; negative/non-finite retry
      fields or a non-200 POST → `data-yemaya-mao-retry-error` ("Retry fields must
      be non-negative numbers.").

## Interactions

### Classify lane

`<form data-yemaya-mao-classify-form>`:

- [ ] **Agent error message** — `<input data-yemaya-mao-field-message>` (aria-label
      "error message").
- [ ] **"Classify error"** submit (`data-yemaya-mao-classify-submit`) — POSTs `{
      message }` to the classify endpoint.

### Retry-delay lane

`<form data-yemaya-mao-retry-form>`:

- [ ] **Strategy** — `<select data-yemaya-mao-field-strategy>` from
      `catalog.retryStrategies`.
- [ ] **Attempt** — `<input data-yemaya-mao-field-attempt>` (aria-label "attempt").
- [ ] **Base ms** — `<input data-yemaya-mao-field-base>` (aria-label "base delay").
- [ ] **Max ms** — `<input data-yemaya-mao-field-max>` (aria-label "max delay").
- [ ] **"Compute backoff"** submit (`data-yemaya-mao-retry-submit`) — POSTs `{
      strategy, attempt, baseDelayMs, maxDelayMs }` to the retry-delay endpoint.

### Route map

`data-yemaya-multi-agent-orchestration-route-map` — five entries:

- [ ] `/studio/yemaya/multi-agent-orchestration`
- [ ] `/studio/yemaya/multi-agent-orchestration/scenes/[sceneId]`
- [ ] `/studio/yemaya/multi-agent-orchestration/exports/[exportId]`
- [ ] `/studio/yemaya/multi-agent-orchestration/revisions/[revisionId]`
- [ ] `/studio/yemaya/multi-agent-orchestration/governance/[policyId]`

### Quick actions

- [ ] **"Open Yemaya DaVinci Integration workspace"** →
      `/studio/yemaya/davinci-integration`.
- [ ] **"Back to Studio workspace index"** → `/studio`.

## Data & contracts

- **Reads**: `GET /v1/admin/yemaya/multi-agent-orchestration` (catalog;
  `errorCategories`, `retryStrategies`) on mount with `buildBffAuthHeaders()`,
  `cache: 'no-store'`.
- **Writes**:
  - `POST /v1/admin/yemaya/multi-agent-orchestration/classify` → `{ category }`.
  - `POST /v1/admin/yemaya/multi-agent-orchestration/retry-delay` → `{ delayMs }`.
- **Realtime**: None.
- **Caching**: client `fetch` on mount, no-store; aborted on unmount.
- **Auth/role check**: admin-scoped, fail-closed; route additionally signed-in +
  studio via the proxy gate.

## Cross-references

- Workspace source:
  `apps/oshun/web/src/components/studio/StudioYemayaMultiAgentOrchestrationWorkspace.tsx`
- Route map source:
  `apps/oshun/web/src/components/studio/StudioYemayaMultiAgentOrchestrationRouteMap.ts`
- Page source:
  `apps/oshun/web/src/app/studio/yemaya/multi-agent-orchestration/page.tsx`
- Sibling: [`studio-yemaya-ai-content-generation.md`](./studio-yemaya-ai-content-generation.md)
- Studio overview: [`studio-overview.md`](../../studio-overview.md)
- Feature spec: [`V1/features.md`](../../../../V1/features.md)

## Open questions / known gaps

- [ ] Route-map children (`scenes`/`exports`/`revisions`/`governance`) are a
      sitemap contract; confirm which dynamic pages exist.
- [ ] The two lanes operate independently (classify does not feed the retry
      form); confirm whether a combined "what would the runtime do next" flow is
      planned.