AI Chat assistant

The in-app AI Chat lets a user run orboto operations by talking to an assistant instead of clicking through the UI. It opens as a right-side drawer from the Sparkles icon in the top bar, or the Cmd/Ctrl+J shortcut. The assistant answers read-only questions on its own (search, "what's overdue on this project", "summarize this ticket"), and can also perform write actions - comment, assign, move, create - but only after the user explicitly approves each one. A destructive action (delete) always requires the user to type the exact ticket key to confirm, regardless of any other setting.

The important guarantee for an admin evaluating this feature: every tool the assistant runs executes as the logged-in user, through the exact same REST routes and permission gates the regular UI uses. The assistant can never do anything that specific user couldn't already do by clicking through the app themselves - it's a different input method, not a privilege escalation.

Turning it on

Three separate things must all be true before any user sees the chat button at all:

1. An AI provider is configured. Admin -> AI settings -> pick a provider and a model (see AI providers and models). The chat reuses whichever provider powers the rest of orboto's AI features - there is no separate provider just for chat.
2. The workspace flag is on. Admin -> System settings -> General -> "In-app AI Chat assistant". Off by default. While off, the chat is unavailable for absolutely everyone in the workspace - the button doesn't render, and the underlying API endpoint itself returns 403 if called directly.
3. The user holds the ai:chat:use permission. Granted by default to the super-admin, project-admin, and developer roles. To let anyone else use it, add the permission to their role under Admin -> Roles. A user without it sees no chat button and no keyboard shortcut at all - the feature is invisible to them, not merely disabled.

All three gates are independent - missing any one of them hides the feature completely for the affected users, so if a specific person can't see the chat, check all three in order rather than assuming it's the provider.

What a user can do with it

• Ask read-only questions - search, summaries, status lookups - answered directly, no approval needed.
• Ask it to take a write action (comment on a ticket, assign someone, move a ticket, create a new one). Unless the user has turned on auto-approve (below), each write shows a confirmation prompt with exactly what it's about to do before it runs.
• Ask it to delete something. This always requires typing the ticket key to confirm, even with auto-approve on - there is no setting that removes this specific confirmation.
• Attach an image to a message, if AI Chat image attachments (vision) is enabled (Admin -> AI settings) and the configured model actually supports vision - see the AI settings page for the exact requirement.
• Pick from a curated model list mid-conversation, if the admin configured Allowed chat models; otherwise every conversation uses the workspace's default chat model.
• Resume a previous conversation, or delete individual conversations / clear all history, from the drawer's Conversations panel.

Per-user options

In Profile -> "Auto-approve AI Chat write actions" (off by default), a user can opt themselves into skipping the per-action approval prompt for write actions - useful for a power user who trusts the assistant and doesn't want to click "approve" on every single comment it posts. Destructive actions still always require the typed-key confirmation regardless of this setting. Every auto-approved execution is marked as such in the audit log, so turning this on for yourself doesn't reduce what an admin can review afterward - it just removes the interactive prompt.

Cost controls

• Daily token cap per user (Admin -> System settings -> "AI Chat daily token cap per user"). 0 or empty means no cap. When set to a number, a user who spends more than that many tokens (prompt + completion combined) on AI Chat within one UTC day gets a "limit reached" message for the rest of that day - it resets at UTC midnight, not on a rolling 24-hour window.
• Conversations themselves are stored indefinitely (so users can resume them later) until the user deletes them - there's no separate conversation-count cap, only the token cap above.

Auditing and usage

• Every tool the assistant executes writes an ai.chat.tool_call row to the audit log, with auto_approved: true recorded whenever the per-user auto-approve setting skipped the confirmation prompt for that specific call. Approve and cancel decisions themselves are also logged separately (ai.chat.tool_call.approved / .cancelled), so you can reconstruct exactly what was proposed vs. what actually ran.
• Token usage for chat shows up in Admin -> AI Usage as its own chat.turn operation row, alongside a "Chat conversations" count and a "Top AI Chat users" table - the place to look if you suspect one account is driving disproportionate AI spend.

How the tool set is scoped (for maintainers)

The chat's available actions are a deliberately curated subset of everything orboto's automation surfaces (MCP, the API) can do - not every possible operation is exposed to the in-app assistant, only the ones that map cleanly onto something a chat user would naturally ask for. If you're building or extending an internal integration and wonder why the chat can't do something the MCP server can, that's usually by design rather than a gap to report.

Troubleshooting

• Chat button doesn't appear for anyone - check the three enable gates in order: is a provider actually configured and working (test it on the AI settings page), is the workspace flag on, and does at least one role have the permission. Missing any one of the three hides it workspace-wide or for that specific role.
• Chat button appears for admins but not regular users - almost always the ai:chat:use permission; it's only granted by default to super-admin, project-admin, and developer roles, so add it explicitly to any other role under Admin -> Roles.
• A user hits "limit reached" mid-workday - they've exceeded the daily token cap; it resets at UTC midnight, not 24 hours after their first message, so someone starting late in their own timezone can hit a cap that feels like it reset "too early" relative to their local day.
• A write action ran without a confirmation prompt and the user is surprised - check whether they turned on auto-approve in their own Profile; it's per-user and off by default, so this is either a setting they forgot enabling, or a genuine question worth asking them directly.
• Wondering exactly what the assistant did in a session - the audit log is the source of truth: filter for ai.chat.tool_call entries around the time in question, which show the exact tool, its parameters, and whether it was auto-approved.