ANDL AI Configuration Extension

Professional AI configuration interface for ANDL with a polished, intuitive UI/UX. Manage AI providers, models, memory systems, resilience settings, and toolkit configuration through a modern webview interface.

Version: 0.3.0
Status: ✅ Production Ready

Configuration

The extension contributes a full settings schema under “ANDL AI” in VS Code Settings, organized to match the webview’s tabs:

• AI & Models: default/cheaper model routing, execution mode
• Chat & Context: prompt normalization, loop control, cognitive options
• RAG & Indexing: STM/LTM/RAG, proactive context, response cache
• Automation: edits/shell/git/loop/test toggles (schema only)
• Security & Audit: redaction and audit logging
• Budget & Costs: budget limits and token rates
• Advanced: toolkit configuration and overrides
• Orchestration: approvals and governance (schema only)
• Integration: reporting, remote services, webhooks, reflector, attachments
• System: sync, telemetry, cockpit URL, GitHub

Tip: You can edit settings either in the webview (Save/Apply) or directly in VS Code Settings. Changes persist across reloads.

Configure Providers (Pluggable)

This extension uses a centralized provider registry (src/extension/toolkit/providerRegistry.ts) as the single source of truth for all tool providers. No provider-specific logic is duplicated across consumer files.

Three-Tier Provider Discovery:

1. Builtins — Extension-bundled providers (e.g., andl-indexer)
2. Extensions — VS Code extensions via andl.ai.providerExtensions setting
3. Modules — External modules via andl.ai.externalProviders setting or ANDL_AI_PROVIDERS env

For architecture details, see: src/extension/toolkit/README.md

Settings

• andl.ai.providerExtensions (string[])
  • Provide extension IDs that export providers via one of:
    • getAiToolProviders(): Provider[]
    • aiToolProviders: Provider[]
    • default export: Provider[]
• andl.ai.externalProviders (string[])
  • Provide Node module specifiers or file: URLs that export a provider through one of:
    • createToolProvider(): Provider
    • createOrchestratorProvider(...): Provider
    • default provider or named provider
• Environment: ANDL_AI_PROVIDERS
  • Comma-separated module specifiers or file: URLs; same shapes as above.

When configured, the extension loads providers and enumerates tools via ai-client’s NodeToolkitAdapter.

Quick Add Integration (Marketplace-Style Discovery)

The Toolkit tab includes a ⚡ Quick Add Integration button that opens a marketplace-style modal showcasing pre-configured integrations:

Available Integrations (12 total):

• Serper - Google Search (web, image, news, places) - $50 free credit
• Resend - Email sending - 100/day free
• Firecrawl - Web scraping - 500 pages/month free
• Tavily - AI research - 1000 queries/month free
• Browserless - Browser automation - 6 hours/month free
• SerpAPI - Multi-engine search aggregator - $50 free credit
• Brave Search - Privacy-focused search - $5/month for 2k queries
• DuckDuckGo - Instant answers (free)
• Perplexity - AI-powered research - $5/month starter
• SendGrid - Transactional email - 100/day free
• Postmark - Email delivery - 100/month free
• Mailgun - Email API - 5k/month free

Coming Soon: 50+ additional integrations across 15+ categories

Features:

• 🔍 Search integrations by name or description
• 📂 Filter by category (Search, Communication, Data, Automation, Research)
• 📊 View pricing tiers and free quotas
• 🔑 Optional API key prompts (ESC to skip if not needed)
• ⚡ One-click installation with automatic configuration

Tool Display:

• Origin: Shows friendly service name (e.g., "Serper Google Search") instead of generic "external"
• Risk Level: Each tool displays its risk rating (0-10 scale)

The extension bundles pre-configured provider templates that are automatically copied during build. No internet connection required for discovery - all metadata is local.

Contributing Integrations: Want to add your favorite API? See CONTRIBUTING_INTEGRATIONS.md for the complete guide.

Add from Module (Design-time Flow)

In the Toolkit tab, use "Add from Module…" to scan your workspace for module-based providers. The scanner looks for files named:

• andl.tools.provider.js
• andl.tools.provider.mjs
• andl.tools.provider.cjs

Export shapes supported (any one):

• export function createToolProvider(): Provider
• export function createOrchestratorProvider(...): Provider
• export const provider: Provider
• export default Provider

Provider Pattern Support:

• MCP-style: tools array with execute() methods
• Legacy: listTools() async method with run() methods

After linking, the provider's tools are listed immediately. Use "Refresh Module Links" to re-scan linked modules for added/removed/updated tools.

Multi-Folder Workspace Support: The scanner loops through ALL workspace folders, not just the first. If automatic scan doesn't find your provider, use the "Browse for File…" button as a manual fallback.

Provider spec storage (workspace-relative by default)

When you link a module provider, the extension stores the spec as a workspace-relative value to keep settings portable across machines and directory layouts.

• Stored format: workspace:<folderName>/<relative/path/to/file>
• Examples:
  • workspace:andl-ai-client/examples/andl.tools.provider.mjs
  • Also supported at load time: ${workspaceFolder}/examples/andl.tools.provider.mjs and ${workspaceFolder:andl-ai-client}/examples/andl.tools.provider.mjs

At runtime, these specs are resolved to absolute file:// URIs for import. If the file is outside any open workspace folder, the absolute file:// URI is stored as a fallback.

Features

✨ Modern UI/UX - Material Design + Apple HIG principles with consistent 8pt grid system
🎨 Professional Design - Rounded cards, shadows, clear visual hierarchy
📊 Memory Stats - Live RAG index and LTM store statistics
📚 Comprehensive Help - Built-in guides for complex settings
🔧 Full Configuration - All ANDL AI settings in organized tabs
⚡ Real-time Updates - Instant feedback and validation

Quick Start

1. Install the extension (.vsix file)
2. Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
3. Run: "ANDL: Open AI Config"
4. Configure your AI providers and settings
5. Click Apply to save changes

Scripts

• pnpm run compile — Production build (no source maps)
• pnpm run package — Create .vsix file for installation
• pnpm run dev — Development watch mode
• pnpm test — Run tests

Profile & Protocol Architecture

Agent profiles and protocols use a packaged-builtin architecture with database seeding at runtime.

How it Works

1. Canonical authoring: andl-ai-client owns the builtin profiles and protocol markdown corpus.
2. Packaging: This extension bundles generated mirrors for VSIX/runtime seeding.
3. Runtime: Profiles and protocols are seeded into the settings database on activation.

Canonical Sources

• Profiles: ../andl-ai-client/src/profiles/builtins/ is the hand-edited canonical source.
• Extension mirror: builtin-agent-profiles/ is generated from the canonical profile source and bundled into the VSIX.
• Policies: ../andl-ai-client/andl/protocols/ is the hand-edited canonical source.
• Extension policy mirror: andl/protocols/ in this extension is a generated mirror bundled into the VSIX.

The extension now derives reseed inventory from packaged mirrors rather than maintaining a second authoring source. ANDL no longer carries its own mirrored protocol tree.

Development Mode

For extension developers who want edits to persist to builtin sources:

When syncToBuiltins is enabled, profile edits in Agent Studio write to BOTH the ai-client canonical source and the extension's packaged mirror. Policy edits write to the ai-client canonical source and the local packaged mirror.

Developer Workflow

The manual reseed loop stays the same, but profile syncing is now explicit and scriptable:

• pnpm run sync:builtin-profiles — refresh builtin-agent-profiles/ from ../andl-ai-client/src/profiles/builtins/
• pnpm run sync:builtin-policies — refresh packaged andl/protocols/ from ../andl-ai-client/andl/protocols/
• pnpm run sync:builtins — refresh both profile and policy mirrors
• pnpm run compile — now runs profile sync before building
• ANDL: Reseed Agent Profiles / ANDL: Reseed Protocols & Policies — reseed workspaces from the packaged mirrors

Human-facing naming note: the project is moving toward calling these documents “policies”, but the runtime path remains andl/protocols/ and existing command IDs remain unchanged for compatibility.

Troubleshooting

Profiles/Protocols not found?

1. Check for andl/profiles/ and andl/protocols/ under the configured ANDL Home
2. Set andl.ai.development.forceReseed: true and reload VS Code
3. Extension will re-seed from builtins

For full details, see: andl-ai-client/docs/PROFILE_ARCHITECTURE.md

Notes

• This extension is a thin wrapper around an owned webview composition that imports UI components from src/ui/**.
• The webview bundle (media/ai-config.js) is built locally with CSP-safe type="module"; inline source maps are enabled in dev only.