mcp-rubber-duck 1.9.5 → 1.11.0

package/src/services/task-manager.ts

@@ -0,0 +1,162 @@
+/**
+ * Task lifecycle adapter wrapping the MCP SDK's experimental Tasks API.
+ *
+ * This module isolates all direct usage of `@modelcontextprotocol/sdk/experimental`
+ * behind a single adapter class so that future breaking changes in the experimental
+ * API only require updates here.
+ */
+
+import {
+  InMemoryTaskStore,
+  InMemoryTaskMessageQueue,
+} from '@modelcontextprotocol/sdk/experimental';
+import type {
+  TaskStore,
+  TaskMessageQueue,
+} from '@modelcontextprotocol/sdk/experimental';
+import type { CallToolResult, Result } from '@modelcontextprotocol/sdk/types.js';
+import { logger } from '../utils/logger.js';
+
+export interface TaskManagerConfig {
+  /** Time-to-live for completed task results (milliseconds). */
+  defaultTtl: number;
+  /** Suggested interval between client polls (milliseconds). */
+  pollInterval: number;
+  /** Maximum messages per task queue (prevents unbounded growth). */
+  maxQueueSize: number;
+  /** Interval for cleanup/monitoring sweep (milliseconds). */
+  cleanupInterval: number;
+}
+
+const DEFAULT_CONFIG: TaskManagerConfig = {
+  defaultTtl: 300_000,       // 5 minutes
+  pollInterval: 2_000,       // 2 seconds
+  maxQueueSize: 100,
+  cleanupInterval: 60_000,   // 1 minute
+};
+
+/**
+ * Manages MCP task lifecycle: creation, background execution, cancellation, and cleanup.
+ *
+ * - Provides `InMemoryTaskStore` and `InMemoryTaskMessageQueue` instances for
+ *   `McpServer`'s `ProtocolOptions`.
+ * - Tracks active background work via `AbortController` per task for cancellation.
+ * - Handles graceful shutdown (cancels active tasks, clears timers).
+ */
+export class TaskManager {
+  readonly taskStore: TaskStore;
+  readonly taskMessageQueue: TaskMessageQueue;
+  readonly config: TaskManagerConfig;
+
+  /** Maps taskId → AbortController for active background work. */
+  private activeControllers: Map<string, AbortController> = new Map();
+  private cleanupTimer?: ReturnType<typeof setInterval>;
+
+  constructor(config?: Partial<TaskManagerConfig>) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.taskStore = new InMemoryTaskStore();
+    this.taskMessageQueue = new InMemoryTaskMessageQueue();
+    this.startCleanup();
+  }
+
+  /**
+   * Start background work for a task.
+   *
+   * This is fire-and-forget: the returned promise resolves immediately.
+   * The `work` function runs asynchronously; its result is stored in the
+   * task store on completion. On error the task is marked `failed`.
+   * On abort (cancellation) the task is marked `cancelled`.
+   *
+   * @param taskId    ID of the task (from `taskStore.createTask`)
+   * @param work      Async function receiving an `AbortSignal` and returning a `CallToolResult`
+   */
+  startBackground(
+    taskId: string,
+    work: (signal: AbortSignal) => Promise<CallToolResult>
+  ): void {
+    const controller = new AbortController();
+    this.activeControllers.set(taskId, controller);
+
+    void (async () => {
+      try {
+        await this.taskStore.updateTaskStatus(taskId, 'working');
+        const result = await work(controller.signal);
+
+        if (!controller.signal.aborted) {
+          await this.taskStore.storeTaskResult(taskId, 'completed', result as Result);
+        } else {
+          // Work completed but cancellation was requested mid-execution.
+          // Mark as cancelled so the task doesn't stay stuck in 'working'.
+          try {
+            await this.taskStore.updateTaskStatus(taskId, 'cancelled', 'Task was cancelled');
+          } catch {
+            // Task may already be in a terminal state
+          }
+        }
+      } catch (error) {
+        if (controller.signal.aborted) {
+          try {
+            await this.taskStore.updateTaskStatus(taskId, 'cancelled', 'Task was cancelled');
+          } catch {
+            // Task may already be in a terminal state
+          }
+        } else {
+          const message = error instanceof Error ? error.message : String(error);
+          logger.error(`Task ${taskId} failed:`, message);
+          try {
+            await this.taskStore.storeTaskResult(taskId, 'failed', {
+              content: [{ type: 'text', text: `Error: ${message}` }],
+              isError: true,
+            } as Result);
+          } catch {
+            // Task store may have already cleaned up (TTL)
+          }
+        }
+      } finally {
+        this.activeControllers.delete(taskId);
+      }
+    })();
+  }
+
+  /** Cancel a running task by aborting its AbortController. */
+  cancel(taskId: string): boolean {
+    const controller = this.activeControllers.get(taskId);
+    if (controller) {
+      controller.abort();
+      return true;
+    }
+    return false;
+  }
+
+  /** Number of currently active background tasks. */
+  get activeCount(): number {
+    return this.activeControllers.size;
+  }
+
+  private startCleanup(): void {
+    this.cleanupTimer = setInterval(() => {
+      logger.debug(`Active background tasks: ${this.activeControllers.size}`);
+    }, this.config.cleanupInterval);
+    // Allow the process to exit even if the timer is still running
+    if (this.cleanupTimer && typeof this.cleanupTimer === 'object' && 'unref' in this.cleanupTimer) {
+      this.cleanupTimer.unref();
+    }
+  }
+
+  /** Graceful shutdown: cancel all active tasks and clear timers. */
+  shutdown(): void {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = undefined;
+    }
+
+    for (const [taskId, controller] of this.activeControllers) {
+      logger.info(`Cancelling active task ${taskId} during shutdown`);
+      controller.abort();
+    }
+    this.activeControllers.clear();
+
+    // Clear InMemoryTaskStore internal TTL timers
+    (this.taskStore as InMemoryTaskStore).cleanup();
+  }
+}

package/src/tools/compare-ducks.ts

@@ -1,10 +1,12 @@
 import { ProviderManager } from '../providers/manager.js';
 import { duckArt } from '../utils/ascii-art.js';
 import { logger } from '../utils/logger.js';
+import type { ProgressReporter } from '../services/progress.js';
 
 export async function compareDucksTool(
   providerManager: ProviderManager,
-  args: Record<string, unknown>
+  args: Record<string, unknown>,
+  progress?: ProgressReporter
 ) {
   const { prompt, providers, model } = args as {
     prompt?: string;
@@ -16,8 +18,17 @@ export async function compareDucksTool(
     throw new Error('Prompt is required');
   }
 
-  // Get responses from multiple ducks
-  const responses = await providerManager.compareDucks(prompt, providers, { model });
+  // Get responses from multiple ducks, reporting progress as each completes
+  const responses = progress
+    ? await providerManager.compareDucksWithProgress(
+        prompt,
+        providers,
+        { model },
+        (providerName, completed, total) => {
+          void progress.report(completed, total, `${providerName} responded (${completed}/${total})`);
+        }
+      )
+    : await providerManager.compareDucks(prompt, providers, { model });
 
   // Build comparison response
   let response = `${duckArt.panel}\n`;
@@ -55,12 +66,32 @@ export async function compareDucksTool(
 
   logger.info(`Compared ${responses.length} ducks, ${successCount} successful`);
 
+  // Build structured data for UI consumption
+  const structuredData = responses.map(r => ({
+    provider: r.provider,
+    nickname: r.nickname,
+    model: r.model,
+    content: r.content,
+    latency: r.latency,
+    tokens: r.usage ? {
+      prompt: r.usage.prompt_tokens,
+      completion: r.usage.completion_tokens,
+      total: r.usage.total_tokens,
+    } : null,
+    cached: r.cached,
+    error: r.content.startsWith('Error:') ? r.content : undefined,
+  }));
+
   return {
     content: [
       {
         type: 'text',
         text: response,
       },
+      {
+        type: 'text',
+        text: JSON.stringify(structuredData),
+      },
     ],
   };
 }

package/src/tools/duck-council.ts

@@ -1,10 +1,12 @@
 import { ProviderManager } from '../providers/manager.js';
 import { duckArt, getRandomDuckMessage } from '../utils/ascii-art.js';
 import { logger } from '../utils/logger.js';
+import type { ProgressReporter } from '../services/progress.js';
 
 export async function duckCouncilTool(
   providerManager: ProviderManager,
-  args: Record<string, unknown>
+  args: Record<string, unknown>,
+  progress?: ProgressReporter
 ) {
   const { prompt, model } = args as {
     prompt?: string;
@@ -19,13 +21,22 @@ export async function duckCouncilTool(
 
   // Get all available ducks
   const allProviders = providerManager.getProviderNames();
-  
+
   if (allProviders.length === 0) {
     throw new Error('No ducks available for the council!');
   }
 
-  // Get responses from all ducks
-  const responses = await providerManager.duckCouncil(prompt, { model });
+  // Get responses from all ducks, reporting progress as each completes
+  const responses = progress
+    ? await providerManager.compareDucksWithProgress(
+        prompt,
+        undefined,
+        { model },
+        (providerName, completed, total) => {
+          void progress.report(completed, total, `${providerName} responded (${completed}/${total})`);
+        }
+      )
+    : await providerManager.duckCouncil(prompt, { model });
 
   // Build council response with a panel discussion format
   let response = `${duckArt.panel}\n\n`;

package/src/tools/duck-debate.ts

@@ -7,6 +7,7 @@ import {
   DebateResult,
 } from '../config/types.js';
 import { logger } from '../utils/logger.js';
+import type { ProgressReporter } from '../services/progress.js';
 
 export interface DuckDebateArgs {
   prompt: string;
@@ -20,7 +21,9 @@ const DEFAULT_ROUNDS = 3;
 
 export async function duckDebateTool(
   providerManager: ProviderManager,
-  args: Record<string, unknown>
+  args: Record<string, unknown>,
+  progress?: ProgressReporter,
+  signal?: AbortSignal
 ) {
   const {
     prompt,
@@ -73,13 +76,23 @@ export async function duckDebateTool(
 
   // Run debate rounds
   const debateRounds: DebateArgument[][] = [];
+  const totalSteps = rounds * participants.length + 1; // +1 for synthesis
+  let completedSteps = 0;
 
   for (let roundNum = 1; roundNum <= rounds; roundNum++) {
+    if (signal?.aborted) {
+      throw new Error('Task cancelled');
+    }
+
     logger.info(`Debate round ${roundNum}/${rounds}`);
     const roundArguments: DebateArgument[] = [];
 
     // Each participant argues in this round
     for (const participant of participants) {
+      if (signal?.aborted) {
+        throw new Error('Task cancelled');
+      }
+
       const argumentPrompt = buildArgumentPrompt(
         prompt,
         format,
@@ -99,16 +112,33 @@ export async function duckDebateTool(
         content: response.content,
         timestamp: new Date(),
       });
+
+      completedSteps++;
+      if (progress) {
+        void progress.report(
+          completedSteps,
+          totalSteps,
+          `Round ${roundNum}/${rounds}: ${participant.nickname} (${participant.position})`
+        );
+      }
     }
 
     debateRounds.push(roundArguments);
   }
 
+  if (signal?.aborted) {
+    throw new Error('Task cancelled');
+  }
+
   // Generate synthesis
   const synthesizerProvider = synthesizer || debateProviders[0];
   const synthesisPrompt = buildSynthesisPrompt(prompt, format, debateRounds, participants);
   const synthesisResponse = await providerManager.askDuck(synthesizerProvider, synthesisPrompt);
 
+  if (progress) {
+    void progress.report(totalSteps, totalSteps, 'Synthesis complete');
+  }
+
   const result: DebateResult = {
     topic: prompt,
     format,
@@ -124,12 +154,39 @@ export async function duckDebateTool(
 
   logger.info(`Debate completed: ${rounds} rounds, synthesized by ${synthesizerProvider}`);
 
+  // Build structured data for UI consumption
+  const structuredData = {
+    topic: result.topic,
+    format: result.format,
+    totalRounds: result.totalRounds,
+    participants: result.participants.map(p => ({
+      provider: p.provider,
+      nickname: p.nickname,
+      position: p.position,
+    })),
+    rounds: result.rounds.map(roundArgs =>
+      roundArgs.map(arg => ({
+        round: arg.round,
+        provider: arg.provider,
+        nickname: arg.nickname,
+        position: arg.position,
+        content: arg.content,
+      }))
+    ),
+    synthesis: result.synthesis,
+    synthesizer: result.synthesizer,
+  };
+
   return {
     content: [
       {
         type: 'text',
         text: formattedOutput,
       },
+      {
+        type: 'text',
+        text: JSON.stringify(structuredData),
+      },
     ],
   };
 }

package/src/tools/duck-iterate.ts

@@ -1,6 +1,7 @@
 import { ProviderManager } from '../providers/manager.js';
 import { IterationRound, IterationResult } from '../config/types.js';
 import { logger } from '../utils/logger.js';
+import type { ProgressReporter } from '../services/progress.js';
 
 export interface DuckIterateArgs {
   prompt: string;
@@ -14,7 +15,9 @@ const CONVERGENCE_THRESHOLD = 0.8; // 80% similarity indicates convergence
 
 export async function duckIterateTool(
   providerManager: ProviderManager,
-  args: Record<string, unknown>
+  args: Record<string, unknown>,
+  progress?: ProgressReporter,
+  signal?: AbortSignal
 ) {
   const {
     prompt,
@@ -54,6 +57,10 @@ export async function duckIterateTool(
   let lastResponse = '';
   let converged = false;
 
+  if (signal?.aborted) {
+    throw new Error('Task cancelled');
+  }
+
   // Round 1: Initial generation by provider A
   const initialResponse = await providerManager.askDuck(providers[0], prompt);
   const providerAInfo = providerManager.getProvider(providers[0]);
@@ -70,8 +77,16 @@ export async function duckIterateTool(
   lastResponse = initialResponse.content;
   logger.info(`Round 1: ${providers[0]} generated initial response`);
 
+  if (progress) {
+    void progress.report(1, iterations, `Round 1/${iterations}: ${providers[0]} generated`);
+  }
+
   // Subsequent rounds: Alternate between providers
   for (let i = 2; i <= iterations; i++) {
+    if (signal?.aborted) {
+      throw new Error('Task cancelled');
+    }
+
     const isProviderA = i % 2 === 1;
     const currentProvider = isProviderA ? providers[0] : providers[1];
     const providerInfo = providerManager.getProvider(currentProvider);
@@ -100,6 +115,10 @@ export async function duckIterateTool(
     lastResponse = response.content;
     logger.info(`Round ${i}: ${currentProvider} ${role === 'critic' ? 'critiqued' : 'refined'}`);
 
+    if (progress) {
+      void progress.report(i, iterations, `Round ${i}/${iterations}: ${currentProvider} ${role}`);
+    }
+
     if (converged) {
       break;
     }

package/src/tools/duck-vote.ts

@@ -2,6 +2,7 @@ import { ProviderManager } from '../providers/manager.js';
 import { ConsensusService } from '../services/consensus.js';
 import { VoteResult } from '../config/types.js';
 import { logger } from '../utils/logger.js';
+import type { ProgressReporter } from '../services/progress.js';
 
 export interface DuckVoteArgs {
   question: string;
@@ -12,7 +13,8 @@ export interface DuckVoteArgs {
 
 export async function duckVoteTool(
   providerManager: ProviderManager,
-  args: Record<string, unknown>
+  args: Record<string, unknown>,
+  progress?: ProgressReporter
 ) {
   const {
     question,
@@ -52,8 +54,17 @@ export async function duckVoteTool(
     require_reasoning
   );
 
-  // Get votes from all ducks in parallel
-  const responses = await providerManager.compareDucks(votePrompt, voterNames);
+  // Get votes from all ducks in parallel, reporting progress as each votes
+  const responses = progress
+    ? await providerManager.compareDucksWithProgress(
+        votePrompt,
+        voterNames,
+        undefined,
+        (providerName, completed, total) => {
+          void progress.report(completed, total, `${providerName} voted (${completed}/${total})`);
+        }
+      )
+    : await providerManager.compareDucks(votePrompt, voterNames);
 
   // Parse votes
   const votes: VoteResult[] = responses.map(response => {
@@ -76,12 +87,36 @@ export async function duckVoteTool(
     `winner: ${aggregatedResult.winner || 'none'}`
   );
 
+  // Build structured data for UI consumption
+  const structuredData = {
+    question: aggregatedResult.question,
+    options: aggregatedResult.options,
+    winner: aggregatedResult.winner,
+    isTie: aggregatedResult.isTie,
+    tally: aggregatedResult.tally,
+    confidenceByOption: aggregatedResult.confidenceByOption,
+    votes: aggregatedResult.votes.map(v => ({
+      voter: v.voter,
+      nickname: v.nickname,
+      choice: v.choice,
+      confidence: v.confidence,
+      reasoning: v.reasoning,
+    })),
+    totalVoters: aggregatedResult.totalVoters,
+    validVotes: aggregatedResult.validVotes,
+    consensusLevel: aggregatedResult.consensusLevel,
+  };
+
   return {
     content: [
       {
         type: 'text',
         text: formattedOutput,
       },
+      {
+        type: 'text',
+        text: JSON.stringify(structuredData),
+      },
     ],
   };
 }

package/src/tools/get-usage-stats.ts

@@ -75,12 +75,26 @@ export function getUsageStatsTool(
 
   logger.info(`Retrieved usage stats for period: ${period}`);
 
+  // Build structured data for UI consumption
+  const structuredData = {
+    period: stats.period,
+    startDate: stats.startDate,
+    endDate: stats.endDate,
+    totals: stats.totals,
+    usage: stats.usage,
+    costByProvider: stats.costByProvider,
+  };
+
   return {
     content: [
       {
         type: 'text',
         text: output,
       },
+      {
+        type: 'text',
+        text: JSON.stringify(structuredData),
+      },
     ],
   };
 }

package/src/ui/compare-ducks/app.ts

@@ -0,0 +1,88 @@
+import { App } from '@modelcontextprotocol/ext-apps';
+
+interface CompareResponse {
+  provider: string;
+  nickname: string;
+  model: string;
+  content: string;
+  latency: number;
+  tokens: { prompt: number; completion: number; total: number } | null;
+  cached: boolean;
+  error?: string;
+}
+
+const app = new App({ name: 'CompareDucks', version: '1.0.0' }, {});
+
+app.ontoolresult = (params) => {
+  const container = document.getElementById('app')!;
+  if (params.isError) {
+    container.innerHTML = `<div class="error-banner">Tool execution failed</div>`;
+    return;
+  }
+
+  // Parse JSON from second content item
+  const content = params.content;
+  if (!content || !Array.isArray(content) || content.length < 2) {
+    container.innerHTML = `<div class="error-banner">No structured data received</div>`;
+    return;
+  }
+
+  try {
+    const data: CompareResponse[] = JSON.parse(
+      (content[1] as { type: string; text: string }).text
+    );
+    render(data);
+  } catch {
+    container.innerHTML = `<div class="error-banner">Failed to parse response data</div>`;
+  }
+};
+
+function render(responses: CompareResponse[]) {
+  const container = document.getElementById('app')!;
+  const successCount = responses.filter((r) => !r.error).length;
+
+  let html = `<div class="summary-bar">${successCount}/${responses.length} ducks responded successfully</div>`;
+  html += `<div class="grid">`;
+
+  for (const r of responses) {
+    const isError = !!r.error;
+    const latencyClass =
+      r.latency < 2000 ? 'fast' : r.latency < 5000 ? 'medium' : 'slow';
+
+    html += `<div class="card${isError ? ' card-error' : ''}">`;
+    html += `<div class="card-header">`;
+    html += `<span class="nickname">${esc(r.nickname)}</span>`;
+    html += `<span class="provider">${esc(r.provider)}</span>`;
+    html += `</div>`;
+
+    if (!isError) {
+      html += `<div class="badges">`;
+      html += `<span class="badge model">${esc(r.model)}</span>`;
+      if (r.tokens) {
+        html += `<span class="badge tokens">${r.tokens.total} tokens</span>`;
+      }
+      if (r.cached) {
+        html += `<span class="badge cached">Cached</span>`;
+      }
+      html += `</div>`;
+      html += `<div class="latency-bar ${latencyClass}" style="width:${Math.min(100, (r.latency / 10000) * 100)}%"></div>`;
+      html += `<div class="latency-label">${r.latency}ms</div>`;
+      html += `<div class="content"><pre>${esc(r.content)}</pre></div>`;
+    } else {
+      html += `<div class="content error-text"><pre>${esc(r.content)}</pre></div>`;
+    }
+
+    html += `</div>`;
+  }
+
+  html += `</div>`;
+  container.innerHTML = html;
+}
+
+function esc(s: string): string {
+  const d = document.createElement('div');
+  d.textContent = s;
+  return d.innerHTML;
+}
+
+app.connect().catch(console.error);