Skip to main content

Aida Assistant

Aida is the in-app assistant mounted by AppLayout. It can answer questions about authorized Navaid data and propose allowlisted browser tool calls for navigation and interaction.

Architecture​

AidaWidget
  ├─ page/user/company context
  ├─ conversation contents
  ├─ declarations from frontend/src/aida/tools.ts
  └─ POST aida
       ├─ auth, flag, company scope, budget/rate
       ├─ Gemini returns text or tool calls
       └─ browser validates and executes allowlisted tools

Voice Aida uses aida-live and Gemini Live. Text tools remain a browser registry; the model does not execute arbitrary JavaScript.

Access​

aida_enabled defaults off. Non-system-admin requests are rejected in both client access logic and the aida/aida-live functions. System admins bypass the flag for testing.

Company data tools use the authenticated user's active memberships and permission utilities. A selected company ID is not authority.

Tool Registry​

Current browser tool names:

get_maturity_summary
list_tasks
list_sessions
list_clients
get_portfolio_overview
get_session_summary
get_company_knowledge
get_dimension_detail
navigate_to
open_session
show_maturity_dimension
switch_client
start_new_session
interact_with_page
complete_task
dismiss_task

Read tools return bounded structured data. Navigation tools map named destinations to internal routes. Mutation tools call normal authorized service surfaces.

Page interaction​

Interactive controls expose stable data-aida-act and data-aida-label attributes. interact_with_page resolves only registered/visible controls and valid action/value shapes.

Do not let a model-provided CSS selector or script run directly.

Confirmation boundaries​

The user must retain control of sensitive or consequential actions. Aida can prepare/navigation-fill flows, but consent checkboxes and destructive confirmation must not be silently bypassed.

Model Loop​

The request contains model contents and allowlisted tool declarations. Response:

{ done: true, text, modelContent }

or:

{ done: false, toolCalls, modelContent }

The widget executes calls, appends tool results, and continues with bounded iterations. Bound the number of tool rounds and result size to prevent runaway cost or context growth.

Context and Scope​

Aida may receive:

  • current route/page label
  • selected authorized company
  • portfolio context for eligible consultants/admins
  • maturity summary/detail
  • tasks
  • session summaries
  • company facts/learnings

UK-readiness scope instructions are shared with other assistants. Do not send raw unrelated DOM text or hidden form values.

Voice​

aida-live:

  • validates query token,
  • enforces the Aida flag,
  • checks budget,
  • opens Gemini Live,
  • uses the canonical Live model/voice,
  • records conservative realtime usage.

Browser URL/token logging rules from Realtime and Voice apply.

Seasonal/Billy Behaviour​

The optional World Cup theme is client-side and date-gated. Billy Bass is a deliberate English-only easter egg/narration voice. These presentation features must not alter authorization or tool behaviour.

Adding a Tool​

  1. Give it one narrow purpose and typed schema.
  2. Decide read, navigation, form interaction, or mutation.
  3. Resolve resources from authenticated state, not model-provided ownership.
  4. Bound results and strip confidential/unneeded fields.
  5. Require confirmation for destructive/consequential action.
  6. Route mutations through existing server controls.
  7. Add localized activity/error copy.
  8. Add unit tests for valid/invalid arguments and cross-company access.
  9. Document the tool and update prompt guidance.

Failure Modes​

  • Flag off: hide UI and return server 403.
  • Invalid tool name/args: return controlled tool error.
  • Stale page control: do not search arbitrary DOM; ask user/navigation again.
  • Membership changed: service/RLS denies even if old Aida context listed data.
  • Tool loop exceeds bound: stop with safe explanatory response.
  • Gemini unavailable/budget exceeded: keep ordinary application navigation usable.

Security Checklist​

  • tool allowlist only
  • no eval/arbitrary selectors
  • active membership checks
  • admin confirmation boundaries
  • bounded context/results/rounds
  • no hidden prompt/reasoning exposure
  • accounting for text and Live calls
  • Sentry replay masking
Last updated on