AI subsystem

The AI subsystem is a BYOK orchestration layer over Vercel AI SDK v6. The UI, provider registry, tool surface and security boundaries are separate so a provider change does not change the approval model.

Provider resolution

src/modules/ai/config.ts defines providers, models, capabilities, context limits and pricing metadata. src/modules/ai/lib/agent.ts resolves a configured model and constructs the matching SDK provider. Local providers use an OpenAI-compatible shape through the native proxy.

To add a provider:

  1. Add its ProviderInfo entry.
  2. Add model ids and metadata.
  3. Add the construction branch or reuse the compatible endpoint path.
  4. Update key requirements and secret mapping.
  5. Add a dedicated package only when the unique capability justifies bundle cost.
  6. Test resolution, keyless behavior, errors and supported model capabilities.

Agent run loop

session + project memory + live context
  -> model resolution
  -> system prompt selection
  -> message normalization and compaction
  -> streamText with tools
  -> bounded step loop
  -> usage, tool and finish events

The step count is bounded by MAX_AGENT_STEPS. The context compactor handles provider limits and preserves the current interaction shape expected by the UI.

Tool surface

Tool builders live under src/modules/ai/tools/ and cover filesystem reads, edits, searches, shell actions, terminal context, todos, sub-agents and managed agents. Read-only tools execute after security checks. Mutations carry an approval requirement into the AI SDK message stream.

The edit tools require a read-before-edit invariant. In plan mode, edits are queued for review rather than immediately written.

Sessions and composer

chatStore keeps a module-scoped chat map while the Tauri store persists session metadata and messages. AgentRunBridge mirrors active changes to disk and derives a title from the first user message.

AiComposerProvider owns text, attachments, selections and voice state. Terminal and editor selections are attached as structured <selection> blocks with a source marker.

Security invariants

  • Keys use only secrets_* commands.
  • All file tools apply the deny-list to reads and writes.
  • Mutating tools require approval.
  • Network requests use the native proxy and its SSRF guard.
  • Live context is read lazily and bounded to the active terminal.
  • A new provider must not bypass model, key or network policy.