assistme 0.7.0 → 0.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assistme",
-  "version": "0.7.0",
+  "version": "0.8.2",
   "description": "AssistMe CLI Agent - AI-powered agentic assistant for code, browser, and automation",
   "type": "module",
   "main": "dist/index.js",
@@ -8,8 +8,8 @@
     "assistme": "dist/index.js"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
-    "dev": "tsup src/index.ts --format esm --watch",
+    "build": "tsup src/index.ts src/workers/entry.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts src/workers/entry.ts --format esm --watch",
     "start": "node dist/index.js",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",

package/src/agent/self-analyzer.ts

@@ -166,7 +166,7 @@ function filterAndAggregateEvents(
 async function buildAnalysisContext(ctx: SelfAnalysisContext): Promise<string> {
   // Fetch all data sources in parallel
   const [sessionLogs, messageEvents, conversationMessages] = await Promise.all([
-    getSessionLogs(ctx.sessionId, SELF_ANALYSIS_MAX_SESSION_LOGS),
+    getSessionLogs(ctx.sessionId, SELF_ANALYSIS_MAX_SESSION_LOGS, ctx.conversationId),
     getMessageEvents(ctx.taskId, SELF_ANALYSIS_MAX_MESSAGE_EVENTS),
     getConversationMessages(ctx.conversationId, SELF_ANALYSIS_MAX_CONVERSATION_MESSAGES),
   ]);

package/src/commands/monitor.ts

@@ -4,7 +4,7 @@ import { getCurrentUserId } from "../db/supabase.js";
 import { log } from "../utils/logger.js";
 import type { HeartbeatEngine } from "../agent/proactive-monitor.js";
 
-// Shared heartbeat engine instance — set by SessionManager when agent starts
+// Shared heartbeat engine instance — set by Orchestrator when agent starts
 let sharedHeartbeat: HeartbeatEngine | null = null;
 
 export function setSharedMonitor(engine: HeartbeatEngine): void {
@@ -59,17 +59,15 @@ export function registerMonitorCommands(program: Command): void {
 
         const status = sharedHeartbeat.getStatus();
         console.log(chalk.bold("\nHeartbeat Status:"));
+        console.log(`  Enabled:    ${status.enabled ? chalk.green("yes") : chalk.red("no")}`);
         console.log(
-          `  Enabled:    ${status.enabled ? chalk.green("yes") : chalk.red("no")}`
+          `  Interval:   ${status.intervalMs / 1000}s (${status.intervalMs / 60_000} min)`
         );
-        console.log(`  Interval:   ${status.intervalMs / 1000}s (${status.intervalMs / 60_000} min)`);
         console.log(`  Cycles:     ${status.cycleCount}`);
         console.log(
           `  Checklist:  ${status.hasChecklist ? chalk.green("found") : chalk.yellow("no HEARTBEAT.md")}`
         );
-        console.log(
-          `  Executing:  ${status.executing ? chalk.yellow("running now") : "idle"}`
-        );
+        console.log(`  Executing:  ${status.executing ? chalk.yellow("running now") : "idle"}`);
         console.log();
       } catch (err) {
         log.error(`${err instanceof Error ? err.message : err}`);

package/src/commands/start.ts

@@ -5,8 +5,7 @@ import { createInterface } from "readline";
 import { getCurrentUserId } from "../db/supabase.js";
 import { setConfig } from "../utils/config.js";
 import { log, setLogLevel, setLogHook } from "../utils/logger.js";
-import { SessionManager } from "../agent/session.js";
-import { TaskProcessor } from "../agent/processor.js";
+import { Orchestrator } from "../orchestrator.js";
 import { getBrowser, ensureBrowserAvailable } from "../tools/browser.js";
 import { SessionLogEmitter } from "../db/session-log.js";
 import { setSharedMonitor } from "./monitor.js";
@@ -84,9 +83,7 @@ async function runAgent(opts: { workspace?: string; name?: string; verbose?: boo
     }
   }
 
-  const processor = new TaskProcessor();
-  processor.init(userId);
-  const sessionManager = new SessionManager();
+  const orchestrator = new Orchestrator();
   let logEmitter: SessionLogEmitter | null = null;
 
   // Graceful shutdown
@@ -105,7 +102,7 @@ async function runAgent(opts: { workspace?: string; name?: string; verbose?: boo
     } catch {
       /* ignore */
     }
-    await sessionManager.stop();
+    await orchestrator.stop();
     process.exit(0);
   };
 
@@ -113,22 +110,19 @@ async function runAgent(opts: { workspace?: string; name?: string; verbose?: boo
   process.on("SIGTERM", shutdown);
 
   try {
-    const session = await sessionManager.start(userId, async (task) => {
-      await processor.processTask(task);
-    });
-    processor.setSessionId(session.id);
+    const session = await orchestrator.start(userId);
 
-    // Share HeartbeatEngine with CLI commands and processor
-    setSharedMonitor(sessionManager.getHeartbeatEngine());
-    processor.setHeartbeatEngine(sessionManager.getHeartbeatEngine());
+    // Share HeartbeatEngine with CLI commands
+    setSharedMonitor(orchestrator.getHeartbeatEngine());
 
     // Start persisting logs to Supabase
     logEmitter = new SessionLogEmitter(session.id);
-    setLogHook((logType, message) => {
-      logEmitter?.push(logType, message);
+    setLogHook((logType, message, conversationId) => {
+      logEmitter?.push(logType, message, conversationId);
     });
 
     log.info("Listening for tasks (chat + jobs) from web UI...");
+    log.info(`Workers: conversation (per-conversation)`);
     log.info("Press Ctrl+C to stop.\n");
 
     // Interactive mode: also accept direct input from terminal
@@ -153,7 +147,7 @@ async function runAgent(opts: { workspace?: string; name?: string; verbose?: boo
       }
 
       if (input === "status") {
-        const s = sessionManager.getSession();
+        const s = orchestrator.getSession();
         if (s) {
           console.log(`Session: ${s.id}`);
           console.log(`Status: ${s.status}`);
@@ -162,6 +156,19 @@ async function runAgent(opts: { workspace?: string; name?: string; verbose?: boo
             `Browser: ${browserRef.isConnected() ? "connected" : launchResult.success ? "available" : "not available"}`
           );
         }
+
+        const workers = orchestrator.getWorkerManager()?.getWorkerInfos() ?? [];
+        if (workers.length > 0) {
+          console.log(`\nActive workers: ${workers.length}`);
+          for (const w of workers) {
+            console.log(
+              `  ${w.type} (${w.id}): ${w.status}, pid=${w.pid}, tasks=${w.tasksProcessed}${w.conversationId ? `, conv=${w.conversationId.slice(0, 8)}` : ""}`
+            );
+          }
+        } else {
+          console.log("Workers: none active (will spawn on demand)");
+        }
+
         rl.prompt();
         return;
       }
@@ -169,7 +176,7 @@ async function runAgent(opts: { workspace?: string; name?: string; verbose?: boo
       // Process as a direct task
       log.agent(`Processing: "${input}"`);
       try {
-        await sessionManager.submitTask(input);
+        await orchestrator.submitTask(input);
       } catch (err) {
         log.error(`${err instanceof Error ? err.message : err}`);
       }

package/src/db/analysis-data.ts

@@ -17,16 +17,19 @@ export interface MessageEventEntry {
 
 /**
  * Fetch agent session logs for a given session.
+ * Optionally filter by conversation_id to get only logs from a specific conversation.
  * Uses the log.list MCP handler endpoint.
  */
 export async function getSessionLogs(
   sessionId: string,
-  limit = 500
+  limit = 500,
+  conversationId?: string
 ): Promise<SessionLogEntry[]> {
   try {
     const data = await callMcpHandler<SessionLogEntry[]>("log.list", {
       session_id: sessionId,
       limit,
+      ...(conversationId ? { conversation_id: conversationId } : {}),
     });
     return data || [];
   } catch (err) {

package/src/db/session-log.ts

@@ -8,6 +8,7 @@ interface PendingLog {
   log_type: "stdout" | "stderr" | "status";
   message: string;
   seq: number;
+  conversation_id?: string | null;
 }
 
 /**
@@ -25,9 +26,9 @@ export class SessionLogEmitter {
   }
 
   /** Queue a log entry for batch insertion */
-  push(logType: "stdout" | "stderr" | "status", message: string): void {
+  push(logType: "stdout" | "stderr" | "status", message: string, conversationId?: string | null): void {
     this.sequence++;
-    this.buffer.push({ log_type: logType, message, seq: this.sequence });
+    this.buffer.push({ log_type: logType, message, seq: this.sequence, conversation_id: conversationId || null });
 
     // Flush immediately if buffer is large
     if (this.buffer.length >= MAX_BATCH_SIZE) {

package/src/orchestrator.ts

@@ -0,0 +1,492 @@
+/**
+ * Orchestrator — main process coordinator.
+ *
+ * Multi-process architecture:
+ * - Manages agent session lifecycle (DB heartbeat, status)
+ * - Polls for tasks and dispatches them to worker processes (non-blocking)
+ * - Runs scheduler and heartbeat engine in the main process
+ * - Tracks session busy state via worker busy count (reference counting)
+ * - Polls for unanalyzed jobs and dispatches analysis as regular tasks
+ *
+ * Each conversation gets its own worker process for isolation and concurrency.
+ */
+
+import {
+  createSession,
+  updateHeartbeat,
+  endSession,
+  setSessionBusy,
+  pollAndClaimTask,
+  pollAndClaimJobRun,
+  claimTask,
+  createTask,
+  getOrCreateCliConversation,
+  cleanupStaleSessions,
+  type AgentSession,
+  type PendingJobRun,
+} from "./db/supabase.js";
+import { callMcpHandler } from "./db/api-client.js";
+import { getConfig } from "./utils/config.js";
+import { log } from "./utils/logger.js";
+import { Scheduler, type ScheduledTask } from "./agent/scheduler.js";
+import { JobRunner } from "./agent/job-runner.js";
+import { HeartbeatEngine } from "./agent/proactive-monitor.js";
+import { WorkerManager } from "./workers/manager.js";
+
+const DEFAULT_HEARTBEAT_INTERVAL = 30_000; // 30 seconds
+const DEFAULT_POLL_INTERVAL = 2_000; // 2 seconds
+const MAX_POLL_INTERVAL = 30_000; // Max backoff: 30 seconds
+const JOB_ANALYSIS_POLL_INTERVAL = 30_000; // 30 seconds
+
+export class Orchestrator {
+  private session: AgentSession | null = null;
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  private pollTimer: ReturnType<typeof setTimeout> | null = null;
+  private running = false;
+  private scheduler: Scheduler;
+  private heartbeatEngine: HeartbeatEngine;
+  private workerManager: WorkerManager | null = null;
+  private userId: string | null = null;
+  private conversationId: string | null = null;
+  private consecutivePollFailures = 0;
+  private heartbeatInterval: number;
+  private basePollInterval: number;
+  private jobAnalysisTimer: ReturnType<typeof setInterval> | null = null;
+  /** Track jobs currently being analyzed to avoid duplicate tasks. */
+  private analyzingJobIds = new Set<string>();
+
+  constructor() {
+    this.scheduler = new Scheduler();
+    this.heartbeatEngine = new HeartbeatEngine();
+    this.heartbeatInterval = DEFAULT_HEARTBEAT_INTERVAL;
+    this.basePollInterval = DEFAULT_POLL_INTERVAL;
+  }
+
+  async start(userId: string): Promise<AgentSession> {
+    const config = getConfig();
+    this.userId = userId;
+
+    this.session = await createSession(config.sessionName, config.workspacePath, "0.1.0");
+    this.conversationId = await getOrCreateCliConversation();
+
+    // Initialize the worker manager with busy-count callback
+    this.workerManager = new WorkerManager(userId, this.session.id);
+    this.workerManager.setBusyChangeCallback((busyCount) => {
+      this.onBusyCountChange(busyCount);
+    });
+
+    this.running = true;
+    log.success(`Session started: ${this.session.id} (${config.sessionName})`);
+    log.info(`Workspace: ${config.workspacePath}`);
+
+    // Start heartbeat (session keepalive)
+    this.heartbeatTimer = setInterval(async () => {
+      if (this.session) {
+        await updateHeartbeat(this.session.id);
+        log.debug("Heartbeat sent");
+      }
+    }, this.heartbeatInterval);
+
+    // Start polling for tasks
+    this.schedulePoll();
+
+    // Start scheduler for cron tasks
+    await this.scheduler.start(async (scheduledTask: ScheduledTask) => {
+      await this.executeScheduledTask(scheduledTask);
+    });
+
+    // Start heartbeat engine
+    if (this.conversationId) {
+      this.heartbeatEngine.setConversationId(this.conversationId);
+    }
+    this.heartbeatEngine.start(async (prompt: string) => {
+      await this.executeHeartbeatAction(prompt);
+    });
+
+    // Start polling for unanalyzed jobs (dispatched as regular tasks)
+    this.startJobAnalysisPoll();
+
+    // Clean up stale sessions on startup
+    this.cleanupStaleSessions().catch(() => {});
+
+    return this.session;
+  }
+
+  // ── Busy State (reference counting) ─────────────────────────────
+
+  private onBusyCountChange(busyCount: number): void {
+    if (!this.session) return;
+
+    if (busyCount > 0) {
+      setSessionBusy(this.session.id, true).catch((err) => {
+        log.debug(`Failed to set session busy: ${err}`);
+      });
+    } else {
+      setSessionBusy(this.session.id, false).catch((err) => {
+        log.debug(`Failed to clear session busy: ${err}`);
+      });
+    }
+  }
+
+  // ── Polling ─────────────────────────────────────────────────────
+
+  private schedulePoll(): void {
+    if (!this.running) return;
+
+    const delay =
+      this.consecutivePollFailures === 0
+        ? this.basePollInterval
+        : Math.min(
+            this.basePollInterval * Math.pow(2, this.consecutivePollFailures),
+            MAX_POLL_INTERVAL
+          );
+
+    this.pollTimer = setTimeout(() => this.pollForTasks(), delay);
+  }
+
+  private async pollForTasks() {
+    if (!this.session || !this.running) {
+      this.schedulePoll();
+      return;
+    }
+
+    try {
+      // Priority 1: Chat tasks from web UI
+      const task = await pollAndClaimTask(this.session.id);
+      this.consecutivePollFailures = 0;
+
+      if (task) {
+        log.info(`New task claimed: ${task.id}`);
+        log.agent(`Task from conversation: ${task.conversation_id}`);
+
+        // Non-blocking dispatch — returns immediately after sending to worker
+        this.workerManager!.dispatchTask(task).catch((err) => {
+          log.error(`Task dispatch error: ${err}`);
+        });
+      } else if (this.userId) {
+        // Priority 2: Pending job runs (triggered from web UI)
+        const jobRun = await pollAndClaimJobRun();
+
+        if (jobRun) {
+          // Non-blocking — prepare and dispatch in background
+          this.executeJobRun(jobRun).catch((err) => {
+            log.error(`Job run error: ${err}`);
+          });
+        }
+      }
+    } catch (err) {
+      this.consecutivePollFailures++;
+      const delay = Math.min(
+        this.basePollInterval * Math.pow(2, this.consecutivePollFailures),
+        MAX_POLL_INTERVAL
+      );
+      log.debug(`Poll error (retry in ${delay}ms): ${err}`);
+    }
+
+    // Always schedule next poll immediately — don't wait for task completion
+    this.schedulePoll();
+  }
+
+  // ── Job Execution ───────────────────────────────────────────────
+
+  private async executeJobRun(jobRun: PendingJobRun): Promise<void> {
+    if (!this.session || !this.userId || !this.conversationId) return;
+
+    log.info(`Executing job run: ${jobRun.job_name} (${jobRun.id.slice(0, 8)}...)`);
+
+    const runner = new JobRunner();
+    const job = await runner.loadJob(jobRun.job_name);
+
+    if (!job) {
+      log.error(`Job "${jobRun.job_name}" not found, marking run as failed`);
+      try {
+        await runner.completeRun(jobRun.id, "failed", `Job "${jobRun.job_name}" not found`);
+      } catch {
+        /* already logged */
+      }
+      return;
+    }
+
+    if (job.skills.length === 0) {
+      log.error(`Job "${jobRun.job_name}" has no skills, marking run as failed`);
+      try {
+        await runner.completeRun(jobRun.id, "failed", "Job has no linked skills");
+      } catch {
+        /* already logged */
+      }
+      return;
+    }
+
+    // Link session to run record
+    try {
+      await callMcpHandler("job.link_run_session", {
+        run_id: jobRun.id,
+        session_id: this.session.id,
+      });
+    } catch (linkErr) {
+      log.debug(`Failed to link session to job run: ${linkErr}`);
+    }
+
+    // Build prompt and dispatch — wait for task completion before marking run done
+    const prompt = runner.buildJobPrompt(job, jobRun.id);
+
+    try {
+      await this.dispatchAndWait(`[JobRun: ${jobRun.job_name}] ${prompt}`);
+      await runner.completeRun(jobRun.id, "completed", "Job executed via web trigger");
+    } catch (err) {
+      log.error(`Job run failed: ${err}`);
+      try {
+        await runner.completeRun(
+          jobRun.id,
+          "failed",
+          `Execution error: ${err instanceof Error ? err.message : err}`
+        );
+      } catch (completeErr) {
+        log.error(`Failed to mark run as failed: ${completeErr}`);
+      }
+    }
+  }
+
+  // ── Job Analysis (as regular tasks) ─────────────────────────────
+
+  private startJobAnalysisPoll(): void {
+    // Run first check after a short delay to let the system settle
+    setTimeout(() => this.pollForUnanalyzedJobs(), 5_000);
+
+    this.jobAnalysisTimer = setInterval(() => {
+      this.pollForUnanalyzedJobs();
+    }, JOB_ANALYSIS_POLL_INTERVAL);
+  }
+
+  private async pollForUnanalyzedJobs(): Promise<void> {
+    if (!this.running || !this.session || !this.conversationId) return;
+
+    try {
+      const jobs = await callMcpHandler<Array<{ id: string; name: string }>>(
+        "job.list_unanalyzed"
+      );
+
+      if (!jobs || jobs.length === 0) return;
+
+      for (const job of jobs) {
+        if (this.analyzingJobIds.has(job.id)) continue;
+
+        this.analyzingJobIds.add(job.id);
+        log.info(`Dispatching job analysis task for "${job.name}"`);
+
+        const runner = new JobRunner();
+        const jobInfo = await runner.loadJob(job.name);
+
+        if (!jobInfo) {
+          log.debug(`Job "${job.name}" not found, skipping analysis`);
+          await this.markJobAnalyzed(job.id);
+          this.analyzingJobIds.delete(job.id);
+          continue;
+        }
+
+        const prompt = this.buildJobAnalysisPrompt(jobInfo);
+
+        // Mark analyzed immediately so we don't re-dispatch on next poll.
+        // Non-blocking dispatch — don't await completion to avoid blocking the poll loop.
+        await this.markJobAnalyzed(job.id);
+
+        this.dispatchTask(`[JobAnalysis: ${job.name}] ${prompt}`)
+          .then(() => {
+            log.info(`Job "${job.name}" analysis task dispatched`);
+          })
+          .catch((err) => {
+            log.debug(`Job analysis dispatch failed for "${job.name}": ${err}`);
+          })
+          .finally(() => {
+            this.analyzingJobIds.delete(job.id);
+          });
+      }
+    } catch (err) {
+      log.debug(`Job analysis poll error: ${err}`);
+    }
+  }
+
+  private buildJobAnalysisPrompt(job: { jobName: string; jobDescription: string; skills: Array<{ skillName: string; skillDescription: string; skillEmoji: string; skillContent: string }> }): string {
+    let prompt = `Analyze this job definition and determine what skills are needed to execute it effectively.\n\n`;
+    prompt += `## Job Definition\n`;
+    prompt += `**Name:** ${job.jobName}\n`;
+    prompt += `**Description:** ${job.jobDescription}\n\n`;
+
+    if (job.skills.length > 0) {
+      prompt += `**Current Skills:**\n`;
+      for (const skill of job.skills) {
+        const emoji = skill.skillEmoji ? `${skill.skillEmoji} ` : "";
+        prompt += `- ${emoji}${skill.skillName}: ${skill.skillDescription}\n`;
+      }
+      prompt += `\n`;
+    }
+
+    prompt += `## Instructions\n`;
+    prompt += `For each capability the job needs:\n`;
+    prompt += `1. Check if an existing skill covers it (use \`skill_search\` to check)\n`;
+    prompt += `2. If no existing skill covers it, create a new one using \`skill_create\`\n`;
+    prompt += `3. If an existing skill needs improvement, update it using \`skill_improve\`\n`;
+    prompt += `4. Link all relevant skills to the job using \`skill_link_job\`\n\n`;
+    prompt += `Be practical — only create skills that would genuinely help automate this job.\n`;
+    prompt += `When done, summarize what skills were created, updated, or already existed.\n`;
+
+    return prompt;
+  }
+
+  private async markJobAnalyzed(jobId: string): Promise<void> {
+    try {
+      await callMcpHandler("job.mark_analyzed", { job_id: jobId });
+    } catch (err) {
+      log.debug(`Failed to mark job analyzed: ${err}`);
+    }
+  }
+
+  // ── Scheduled & Heartbeat Tasks ─────────────────────────────────
+
+  private async executeScheduledTask(scheduledTask: ScheduledTask): Promise<void> {
+    if (!this.session || !this.userId || !this.conversationId) return;
+
+    log.info(`Running scheduled task: "${scheduledTask.name}"`);
+
+    try {
+      await this.dispatchTask(`[Scheduled: ${scheduledTask.name}] ${scheduledTask.prompt}`);
+    } catch (err) {
+      log.error(`Scheduled task error: ${err}`);
+    }
+  }
+
+  private async executeHeartbeatAction(prompt: string): Promise<void> {
+    if (!this.session || !this.userId || !this.conversationId) return;
+
+    log.info("Heartbeat action needed — submitting task");
+
+    try {
+      await this.dispatchTask(prompt);
+    } catch (err) {
+      log.error(`Heartbeat task error: ${err}`);
+    }
+  }
+
+  // ── Task Dispatch ───────────────────────────────────────────────
+
+  /**
+   * Create a task in the DB and dispatch to a conversation worker.
+   * Non-blocking — returns after dispatching, does not wait for completion.
+   */
+  async dispatchTask(prompt: string): Promise<void> {
+    if (!this.session || !this.userId || !this.conversationId) {
+      throw new Error("Session not started");
+    }
+
+    const task = await createTask(this.conversationId, this.session.id, prompt);
+    await claimTask(task.id);
+
+    // Non-blocking dispatch to worker
+    await this.workerManager!.dispatchTask(task);
+  }
+
+  /**
+   * Create a task, dispatch to a worker, and wait for completion.
+   * Used when the caller needs to know the task finished
+   * (e.g. job runs, interactive CLI).
+   */
+  async dispatchAndWait(prompt: string): Promise<void> {
+    if (!this.session || !this.userId || !this.conversationId) {
+      throw new Error("Session not started");
+    }
+
+    const task = await createTask(this.conversationId, this.session.id, prompt);
+    await claimTask(task.id);
+
+    await this.workerManager!.dispatchAndWait(task);
+  }
+
+  /**
+   * Submit a task from interactive CLI.
+   * Non-blocking — output streams via log messages.
+   */
+  async submitTask(prompt: string): Promise<void> {
+    await this.dispatchTask(prompt);
+  }
+
+  // ── Cleanup ─────────────────────────────────────────────────────
+
+  private async cleanupStaleSessions(): Promise<void> {
+    if (!this.userId || !this.session) return;
+
+    try {
+      const cleaned = await cleanupStaleSessions(this.session.id);
+      if (cleaned > 0) {
+        log.info(`Cleaned up ${cleaned} stale session(s)`);
+      }
+    } catch (err) {
+      log.debug(`Stale session cleanup error: ${err}`);
+    }
+  }
+
+  // ── Shutdown ────────────────────────────────────────────────────
+
+  async stop(timeoutMs = 5_000): Promise<void> {
+    this.running = false;
+    this.scheduler.stop();
+    this.heartbeatEngine.stop();
+
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+
+    if (this.pollTimer) {
+      clearTimeout(this.pollTimer);
+      this.pollTimer = null;
+    }
+
+    if (this.jobAnalysisTimer) {
+      clearInterval(this.jobAnalysisTimer);
+      this.jobAnalysisTimer = null;
+    }
+
+    // Stop all workers
+    if (this.workerManager) {
+      await this.workerManager.shutdown(timeoutMs);
+    }
+
+    if (this.session) {
+      try {
+        await Promise.race([
+          endSession(this.session.id),
+          new Promise<never>((_, reject) =>
+            setTimeout(() => reject(new Error("Shutdown timeout")), timeoutMs)
+          ),
+        ]);
+        log.success(`Session ended: ${this.session.id}`);
+      } catch (err) {
+        log.warn(`Session cleanup error: ${err}`);
+      } finally {
+        this.session = null;
+      }
+    }
+  }
+
+  // ── Getters ─────────────────────────────────────────────────────
+
+  getSession(): AgentSession | null {
+    return this.session;
+  }
+
+  getConversationId(): string | null {
+    return this.conversationId;
+  }
+
+  getHeartbeatEngine(): HeartbeatEngine {
+    return this.heartbeatEngine;
+  }
+
+  getWorkerManager(): WorkerManager | null {
+    return this.workerManager;
+  }
+
+  isRunning(): boolean {
+    return this.running;
+  }
+}