Supervisor

The core orchestrator that manages sessions, tasks, and Discord communication.

Overview

The Supervisor class is Tars’ central orchestrator. It manages the GeminiEngine, routes Discord messages, and coordinates background operations through the Heartbeat Service (maintenance) and the Cron Service (scheduled tasks).

Key Responsibilities

• Session Lifecycle — Coordinating with GeminiEngine to maintain and persist sessions.
• Message Routing — Processing Discord prompts and streaming responses back.
• Task Execution — Running background operations via executeTask() triggered by the Heartbeat and Cron services.
• Memory Mutation Detection — Detecting when tools like memory_store_fact are used and invalidating the session to pick up new facts.

Core Methods

run(prompt, callback)

The primary method for interactive prompts from Discord. It:

1. Acquires a processing lock (isProcessing flag) to prevent concurrent access.
2. Passes the prompt and optional attachments to the GeminiEngine.
3. Streams events back to the callback (text chunks, tool calls, errors, done signals).
4. Persists the sessionId if it was newly generated by the engine.
5. Invalidate the session if memory-mutating tools were detected.

await supervisor.run('Check deployment status', async (event) => {
    if (event.type === 'text') console.log(event.value);
    if (event.type === 'done') console.log('Complete');
});

executeTask(prompt)

Used by the Heartbeat and Cron services for background execution. This uses GeminiEngine.runSync() which collects the full response in an ephemeral session — preventing background tasks from bloating the user’s conversation history.

Startup Flow

When the supervisor initializes (via main.ts), it runs several bootstrap operations:

1. syncAgents: Deploys system-generated agents to ~/.tars/.gemini/agents/.
2. syncBuiltInSkills: Syncs built-in skills while preserving user-defined ones.
3. installExtensions: Integrates MCP extensions by copying them to the Gemini environment and configuring safety overrides.
4. GeminiEngine.initialize(): Discovers extensions, performs authentication, and warms up the Native Core.

Concurrency Control

The Supervisor uses an isProcessing lock to prevent multiple prompts from being processed simultaneously by the same instance, ensuring deterministic response patterns.