feat(operator): Platform Operator agent (P1, read-only)

[ginccc]

What

An opt-in, admin-activated Platform Operator: an agent that inspects this EDDI deployment and explains what it finds. Off by default, read-only, one click to activate, with a kill switch.

It is provisioned through setup-api as an API Agent whose tools are generated from EDDI's own OpenAPI spec and scoped by a read-only allow-list.

Depends on labsai/EDDI#613 for the caller-identity auth mode.

Design notes worth reviewing

• The capability boundary is an allow-list (src/lib/operator/tool-scopes.ts), never a deny-list — a deny-list silently grants any endpoint added to the backend later. Writes are literally unreachable until an approval handler exists (isWriteScopeAvailable), enforced by tests rather than convention.
• Config is one atomic JSON blob in the platform.operator global variable. Activation writes several values that must land together and the variable store has no transaction.
• Activation runs a canary. A READY deployment badge only proves the agent config loaded; it says nothing about whether the generated tools can authenticate — which is exactly the failure a wrong auth mode produces. The probe sends one read and counts tool calls, so "answered without calling any tool" and "tools returned 401" are both reported as failures.
• A non-editable safety preamble treats all tool output as untrusted data. This is defence-in-depth, not a control — the real boundary is the read-only tool set.

A design assumption that turned out to be wrong

The design assumed EDDI forwards the chatting user's token to an API agent's tool calls. It does not — ApiCallExecutor builds headers only from the ApiCall config, and the template model exposes only userInfo.userId. The Phase 0 spike read as green because that box ran auth=none; "no apiAuth → empty headers" is evidence of no auth at all, not of pass-through.

That is what labsai/EDDI#613 fixes. This PR uses it: authMode: "caller-identity" provisions Bearer ${caller:token}, resolved server-side and never persisted. "none" remains the default and is blocked at activation when OIDC is enabled, since every tool call would 401.

Contract bug fixed along the way

createApiAgent sent name; the backend requires agentName and rejects a blank one — so the agent wizard's API-agent path was broken on main. Fixed in the type, the wizard and the MSW mock (which now rejects a blank agentName as the backend does). That exposed three tests passing for the wrong reason, including one shadowed by the broad */agents/:conversationId handler — MSW's * spans path segments, so setup-api was being answered with a conversation snapshot.

UX

Dashboard discovery card, guided two-step activation, operator screen with a live tool-activity trace (each turn keeps its own), status panel, pause/resume that redeploys in place rather than rebuilding, and a full delete. Conversations survive a reload per tab. The operator's agent carries an "Operator" badge in the Agents list so deleting it there is not a silent footgun.

Accessibility: every control in the activation form had no accessible name in the first pass (bare <label> with no htmlFor beside id-less controls) — fixed, with a regression test. The chat transcript is a live region.

operator.* i18n across all 11 locales (87 keys, parity verified).

Testing

4123 tests / 281 files passing; typecheck and lint clean. Mutation-checked the OIDC gate, the canary's tool-call detection and the deploy-result guard — each fails its tests when disabled.

Also excludes .claude/** from vitest so other branches' worktrees don't run their tests against this branch's mocks.

Not verified

Nothing here has run live. Every test is against mocks; contracts were verified by reading backend source. The first real activation with a real model key — and caller-identity against real Keycloak — is what mocks cannot tell you.

Summary by CodeRabbit

• New Features
  • Added a Platform Operator workspace at /manage/operator with activation/setup, reconfiguration, and read-only operator chat.
  • Added operator status monitoring with deploy state badges, canary connectivity checks, and managed-operator indicators in the agent list.
  • Extended navigation and dashboard discovery to surface Operator access.
  • Added operator UI/flows to all supported locales (activation, auth modes, stages/status, chat copy).
• Bug Fixes
  • Updated API agent creation to send agentName (instead of the old name field).
• Tests
  • Expanded operator coverage across activation gating, lifecycle UI states, chat streaming, tool-scope filtering, vault key parsing, and canary behavior.
• Documentation
  • Updated operator documentation structure and CI/test status notes.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8938366a-a988-4b0c-895a-e2e1f45c494e

📥 Commits

Reviewing files that changed from the base of the PR and between 7412f9c and f4bd525.

📒 Files selected for processing (7)

• src/components/operator/operator-activation.tsx
• src/components/operator/operator-chat.tsx
• src/components/operator/operator-status.tsx
• src/lib/api/__tests__/operator.test.ts
• src/lib/api/agent-setup.ts
• src/lib/api/operator.ts
• src/pages/operator.tsx

🚧 Files skipped from review as they are similar to previous changes (7)

• src/lib/api/agent-setup.ts
• src/components/operator/operator-status.tsx
• src/components/operator/operator-activation.tsx
• src/pages/operator.tsx
• src/lib/api/operator.ts
• src/lib/api/tests/operator.test.ts
• src/components/operator/operator-chat.tsx

---

📝 Walkthrough

Walkthrough

Adds a Platform Operator feature with read-only provisioning, persisted configuration, canary validation, lifecycle controls, operator chat, navigation, localized UI, managed-agent labeling, and comprehensive tests.

Changes

Platform Operator

Layer / File(s)	Summary
Operator contracts and backend lifecycle src/lib/api/operator.ts, src/lib/operator/*, src/lib/model-suggestions.ts, src/lib/api/agent-setup.ts	Defines operator configuration, provisioning, read-only endpoint scopes, prompt construction, vault references, canary checks, lifecycle operations, model suggestions, and the agentName API contract.
Operator hooks and streaming chat src/hooks/use-operator.ts, src/hooks/use-operator-chat.ts	Adds configuration/status queries, activation and lifecycle mutations, session-persistent chat state, SSE parsing, streaming updates, and reset/stop controls.
Activation, chat, and status interface src/components/operator/*	Adds activation/review forms, operator chat, deployment status, confirmation dialogs, progress states, validation, and accessibility semantics.
Page routing and application integration src/pages/operator.tsx, src/app.tsx, src/components/layout/sidebar.tsx, src/pages/dashboard.tsx, src/components/agents/agent-card.tsx, src/pages/agent-wizard.tsx, src/i18n/locales/*	Adds the operator page and route, navigation and discovery entry points, managed-agent labeling, shared model catalog usage, and localized operator strings.
Regression coverage and supporting updates src/lib/api/__tests__/*, src/components/operator/__tests__/*, src/pages/__tests__/operator.test.tsx, src/lib/operator/__tests__/*, src/hooks/__tests__/*, src/test/mocks/handlers.ts, vitest.config.ts, AGENTS.md, HANDOFF.md	Adds backend, UI, scope, API-agent, mock-handler, and test-runner coverage, and updates project documentation and handoff status.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant OperatorPage
  participant OperatorHooks
  participant OperatorAPI
  participant AgentService
  User->>OperatorPage: Open operator management
  OperatorPage->>OperatorHooks: Read config and deployment status
  OperatorHooks->>OperatorAPI: Fetch persisted config and status
  User->>OperatorPage: Submit activation
  OperatorPage->>OperatorHooks: Start activation mutation
  OperatorHooks->>OperatorAPI: Validate spec and provision agent
  OperatorAPI->>AgentService: Create and deploy read-only agent
  AgentService-->>OperatorAPI: Return agent and deployment result
  OperatorAPI-->>OperatorHooks: Return config and canary result
  OperatorHooks-->>OperatorPage: Update active operator view
  User->>OperatorPage: Send chat message
  OperatorPage->>OperatorHooks: Stream operator conversation
  OperatorHooks->>AgentService: Start or resume conversation
  AgentService-->>OperatorHooks: Return tokens and task events
  OperatorHooks-->>OperatorPage: Render response and traces

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 58.46% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding a read-only Platform Operator agent.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/platform-operator-agent

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 9

🧹 Nitpick comments (3)

src/components/operator/operator-activation.tsx (1)

112-376: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add i18n fallback strings to t() calls.

None of the t() calls in this file pass a fallback (e.g. t("operator.activation.title") instead of t("operator.activation.title", "...")). This applies to essentially every call in the component (title/subtitle/labels/hints/stage text/auth-mode copy).
As per coding guidelines, src/**/*.{ts,tsx} should "Use inline i18n fallbacks with t("key", "Fallback")".

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/components/operator/operator-activation.tsx` around lines 112 - 376, Add
inline fallback text to every translation call in the operator activation
component, including labels, hints, buttons, notices, stage messages, and
auth-mode strings. Update both the main component and AuthModeField, including
dynamic keys such as operator.stage and operator.authMode, while preserving the
existing translation keys and interpolation parameters.

Source: Coding guidelines

src/lib/api/__tests__/operator.test.ts (1)

185-189: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Prefer stubbing only location rather than replacing window.

{ ...globalThis.window } copies only own enumerable properties, so the stubbed global loses prototype members (addEventListener, HTMLElement, etc.). Anything in the code path under test that touches those would fail for a reason unrelated to the assertion. Stubbing window.location alone keeps the rest of the environment intact.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/api/__tests__/operator.test.ts` around lines 185 - 189, Update the
beforeEach setup around the window stub to stub only window.location with the
required origin, preserving the existing window object and its prototype
members; keep the openapi server setup unchanged.

src/hooks/use-operator-chat.ts (1)

188-194: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Two rapid sends can each create a conversation.

conversationId is read from render-time state, so a second send dispatched before the first setState commits also sees null and calls startConversation again — the second id overwrites the first in sessionStorage, silently splitting the investigation. A ref written synchronously alongside the state update avoids this and also removes state.conversationId from the useCallback deps.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/hooks/use-operator-chat.ts` around lines 188 - 194, Update the
conversation initialization in the send callback around startConversation to use
a ref as the synchronous source of truth: read the existing conversation ID from
the ref, and when creating one, write it to the ref immediately alongside
storeConversationId and setState. Remove state.conversationId from the
useCallback dependency list while preserving the existing conversation creation
behavior.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@HANDOFF.md`:
- Around line 127-133: The “Last Commit Focus” Platform Operator summary in
HANDOFF.md still describes the obsolete caller-context token forwarding
mechanism. Update the authMode design note to document the shipped
caller-identity mode and EDDI server-side ${caller:token} resolver, matching the
OperatorAuthMode values in operator-activation.tsx and the AGENTS.md Platform
Operator section; remove the conversation-context eddiAuthToken and
token-at-rest wording.

In `@src/components/operator/operator-chat.tsx`:
- Around line 56-70: Replace direct Operator UI translation calls with inline
fallback strings: in src/components/operator/operator-chat.tsx lines 56-70,
change OPERATOR_STARTER_PROMPTS to key/fallback pairs and pass both values to t;
in src/components/operator/operator-status.tsx lines 54-76, add fallbacks for
static and dynamic operator labels, including
operator.authMode.${config.authMode}.label; in src/pages/operator.tsx lines
78-82, add fallbacks for activation, canary, lifecycle, configuration-error,
active-status, and toast messages; in src/components/layout/sidebar.tsx line 53,
provide the nav.operator fallback through the sidebar item fallback path.

In `@src/hooks/use-operator-chat.ts`:
- Around line 225-243: Guard the cleanup in the streaming operation’s finally
block so a stale turn cannot affect a newer one: only clear abortRef.current and
set isStreaming to false when the settling turn’s controller is still the
current controller. Preserve the existing event, trace, and message cleanup,
while ensuring a newer send remains active and abortable.

In `@src/hooks/use-operator.ts`:
- Around line 100-157: Update useActivateOperator so failures after
provisionOperator/assertProvisioned trigger best-effort retirement of the newly
provisioned result.agentId, then rethrow the original error; keep
superseded-agent cleanup targeting config.agentId separately. After
writeOperatorConfig(next) succeeds, immediately invalidate operatorKeys.all
through qc rather than relying only on the mutation-level onSuccess callback.

In `@src/lib/api/operator.ts`:
- Around line 100-114: Update readOperatorConfig to validate that the JSON.parse
result is a non-null object before returning it as OperatorConfig; return null
for valid JSON primitives, arrays, or null, while preserving the existing
handling for parse errors and missing variables.
- Around line 318-382: Update runOperatorCanary’s task_complete handling to
deduplicate overlapping toolTrace entries from multiple completion events before
incrementing toolCalls or evaluating tool results. Track each completed taskId,
or use an equivalent stable identifier, so each canary tool call is processed
only once while preserving stream and authentication error handling.

In `@src/pages/dashboard.tsx`:
- Around line 451-458: Add inline English fallbacks to every listed operator
translation lookup: update operator.discovery.title,
operator.discovery.description, and operator.discovery.action in
src/pages/dashboard.tsx (lines 451-458), plus operator.managedAgentHint and
operator.managedAgentBadge in src/components/agents/agent-card.tsx (lines
123-132), using the two-argument t(key, fallback) form.

In `@src/pages/operator.tsx`:
- Around line 76-82: Update the activation flow around the canary result
handling in the operator page so a failed canary is not lost when navigating or
reloading. Persist the failed result with the operator configuration, or re-run
the canary while loading an active operator, and ensure the resulting warning
prevents the deployment status from presenting the operator as READY when
platform access remains unavailable.

In `@src/test/mocks/handlers.ts`:
- Around line 1036-1050: Update the mock response in the API agent creation
handler to derive resources.agentLocation from the same generated agentId
returned in the payload, preserving the expected agent-store URL format and
ensuring both values identify the same agent.

---

Nitpick comments:
In `@src/components/operator/operator-activation.tsx`:
- Around line 112-376: Add inline fallback text to every translation call in the
operator activation component, including labels, hints, buttons, notices, stage
messages, and auth-mode strings. Update both the main component and
AuthModeField, including dynamic keys such as operator.stage and
operator.authMode, while preserving the existing translation keys and
interpolation parameters.

In `@src/hooks/use-operator-chat.ts`:
- Around line 188-194: Update the conversation initialization in the send
callback around startConversation to use a ref as the synchronous source of
truth: read the existing conversation ID from the ref, and when creating one,
write it to the ref immediately alongside storeConversationId and setState.
Remove state.conversationId from the useCallback dependency list while
preserving the existing conversation creation behavior.

In `@src/lib/api/__tests__/operator.test.ts`:
- Around line 185-189: Update the beforeEach setup around the window stub to
stub only window.location with the required origin, preserving the existing
window object and its prototype members; keep the openapi server setup
unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 215b8c0f-44cf-4eb0-b946-a70db26044d1

📥 Commits

Reviewing files that changed from the base of the PR and between 44a0e68 and ef5ea77.

📒 Files selected for processing (39)

• AGENTS.md
• HANDOFF.md
• src/app.tsx
• src/components/agents/agent-card.tsx
• src/components/layout/sidebar.tsx
• src/components/operator/__tests__/operator-activation.test.tsx
• src/components/operator/operator-activation.tsx
• src/components/operator/operator-chat.tsx
• src/components/operator/operator-status.tsx
• src/hooks/__tests__/use-agent-setup.test.tsx
• src/hooks/__tests__/use-misc-hooks.test.tsx
• src/hooks/use-operator-chat.ts
• src/hooks/use-operator.ts
• src/i18n/locales/ar.json
• src/i18n/locales/de.json
• src/i18n/locales/en.json
• src/i18n/locales/es.json
• src/i18n/locales/fr.json
• src/i18n/locales/hi.json
• src/i18n/locales/ja.json
• src/i18n/locales/ko.json
• src/i18n/locales/pt.json
• src/i18n/locales/th.json
• src/i18n/locales/zh.json
• src/lib/api/__tests__/agent-setup.test.ts
• src/lib/api/__tests__/operator.test.ts
• src/lib/api/agent-setup.ts
• src/lib/api/operator.ts
• src/lib/model-suggestions.ts
• src/lib/operator/__tests__/tool-scopes.test.ts
• src/lib/operator/system-prompt.ts
• src/lib/operator/tool-scopes.ts
• src/lib/operator/vault-ref.ts
• src/pages/__tests__/operator.test.tsx
• src/pages/agent-wizard.tsx
• src/pages/dashboard.tsx
• src/pages/operator.tsx
• src/test/mocks/handlers.ts
• vitest.config.ts