agent-mockingbird 0.0.1

package/apps/server/src/backend/queue/queue.test.ts

@@ -0,0 +1,189 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+
+import { LaneQueue } from "./service";
+import type { QueueConfig } from "./types";
+
+const defaultConfig: QueueConfig = {
+  enabled: true,
+  defaultMode: "collect",
+  maxDepth: 10,
+  coalesceDebounceMs: 500,
+};
+
+describe("LaneQueue", () => {
+  let queue: LaneQueue;
+
+  beforeEach(() => {
+    queue = new LaneQueue(defaultConfig);
+  });
+
+  describe("enqueue", () => {
+    test("queues message when enabled", () => {
+      const result = queue.enqueue("session-1", "Hello");
+      expect(result.queued).toBe(true);
+      expect(result.depth).toBe(1);
+    });
+
+    test("returns depth after multiple enqueues", () => {
+      queue.enqueue("session-1", "Message 1");
+      queue.enqueue("session-1", "Message 2");
+      const result = queue.enqueue("session-1", "Message 3");
+      expect(result.depth).toBe(3);
+    });
+
+    test("respects maxDepth", () => {
+      const smallQueue = new LaneQueue({ ...defaultConfig, maxDepth: 2 });
+      smallQueue.enqueue("session-1", "Message 1");
+      smallQueue.enqueue("session-1", "Message 2");
+      const result = smallQueue.enqueue("session-1", "Message 3");
+      expect(result.depth).toBe(2);
+    });
+
+    test("does not queue when disabled", () => {
+      const disabledQueue = new LaneQueue({ ...defaultConfig, enabled: false });
+      const result = disabledQueue.enqueue("session-1", "Hello");
+      expect(result.queued).toBe(false);
+      expect(result.depth).toBe(0);
+    });
+  });
+
+  describe("modes", () => {
+    test("replace mode keeps only latest", () => {
+      queue.setMode("session-1", "replace");
+      queue.enqueue("session-1", "Message 1");
+      queue.enqueue("session-1", "Message 2");
+      queue.enqueue("session-1", "Message 3");
+
+      const drained = queue.drain("session-1");
+      expect(drained).toHaveLength(1);
+      expect(drained?.[0]?.content).toBe("Message 3");
+    });
+
+    test("collect mode keeps all messages", () => {
+      queue.setMode("session-1", "collect");
+      queue.enqueue("session-1", "Message 1");
+      queue.enqueue("session-1", "Message 2");
+
+      const drained = queue.drain("session-1");
+      expect(drained).toHaveLength(2);
+    });
+
+    test("followup mode queues for sequential processing", () => {
+      queue.setMode("session-1", "followup");
+      queue.enqueue("session-1", "Message 1");
+      queue.enqueue("session-1", "Message 2");
+      queue.enqueue("session-1", "Message 3");
+
+      const drained = queue.drain("session-1");
+      expect(drained).toHaveLength(3);
+    });
+  });
+
+  describe("drain", () => {
+    test("returns null for empty queue", () => {
+      const drained = queue.drain("session-1");
+      expect(drained).toBeNull();
+    });
+
+    test("removes messages from queue", () => {
+      queue.enqueue("session-1", "Hello");
+      queue.drain("session-1");
+      expect(queue.depth("session-1")).toBe(0);
+    });
+  });
+
+  describe("stats", () => {
+    test("returns stats for all lanes", () => {
+      queue.enqueue("session-1", "Message 1");
+      queue.enqueue("session-2", "Message 2");
+
+      const stats = queue.stats();
+      expect(stats).toHaveLength(2);
+    });
+
+    test("includes depth and mode", () => {
+      queue.setMode("session-1", "replace");
+      queue.enqueue("session-1", "Message 1");
+
+      const stats = queue.stats();
+      expect(stats[0]?.depth).toBe(1);
+      expect(stats[0]?.mode).toBe("replace");
+    });
+  });
+
+  describe("clear", () => {
+    test("clears queue and returns depth", () => {
+      queue.enqueue("session-1", "Message 1");
+      queue.enqueue("session-1", "Message 2");
+      const cleared = queue.clear("session-1");
+      expect(cleared).toBe(2);
+      expect(queue.depth("session-1")).toBe(0);
+    });
+  });
+
+  describe("getMode/setMode", () => {
+    test("returns default mode when not set", () => {
+      expect(queue.getMode("session-1")).toBe("collect");
+    });
+
+    test("returns set mode", () => {
+      queue.setMode("session-1", "replace");
+      expect(queue.getMode("session-1")).toBe("replace");
+    });
+  });
+
+  describe("drainAndExecute", () => {
+    test("coalesces multiple messages in collect mode", async () => {
+      queue.enqueue("session-1", "Message 1");
+      queue.enqueue("session-1", "Message 2");
+      queue.enqueue("session-1", "Message 3");
+
+      let receivedContent = "";
+      queue.setDrainHandler(async (_sessionId, messages) => {
+        receivedContent = messages[0]?.content ?? "";
+      });
+
+      const result = await queue.drainAndExecute("session-1");
+      expect(result?.coalesced).toBe(true);
+      expect(result?.messagesProcessed).toBe(1);
+      expect(receivedContent).toContain("Message 1");
+      expect(receivedContent).toContain("Message 2");
+      expect(receivedContent).toContain("Message 3");
+    });
+
+    test("processes all messages in replace mode", async () => {
+      queue.setMode("session-1", "replace");
+      queue.enqueue("session-1", "Message 1");
+      queue.enqueue("session-1", "Message 2");
+
+      const received: string[] = [];
+      queue.setDrainHandler(async (_sessionId, messages) => {
+        for (const msg of messages) {
+          received.push(msg.content);
+        }
+      });
+
+      await queue.drainAndExecute("session-1");
+      expect(received).toEqual(["Message 2"]);
+    });
+
+    test("processes first message only in followup mode", async () => {
+      queue.setMode("session-1", "followup");
+      queue.enqueue("session-1", "Message 1");
+      queue.enqueue("session-1", "Message 2");
+      queue.enqueue("session-1", "Message 3");
+
+      const received: string[] = [];
+      queue.setDrainHandler(async (_sessionId, messages) => {
+        for (const msg of messages) {
+          received.push(msg.content);
+        }
+      });
+
+      const result = await queue.drainAndExecute("session-1");
+      expect(result?.messagesProcessed).toBe(1);
+      expect(received).toEqual(["Message 1"]);
+      expect(queue.depth("session-1")).toBe(2);
+    });
+  });
+});

package/apps/server/src/backend/queue/service.ts

@@ -0,0 +1,177 @@
+import type { DrainHandler, LaneStats, QueueConfig, QueueDrainResult, QueuedMessage, QueueMode } from "./types";
+import { getConfigSnapshot } from "../config/service";
+import type { RuntimeInputPart } from "../contracts/runtime";
+
+export class LaneQueue {
+  private pending = new Map<string, QueuedMessage[]>();
+  private modes = new Map<string, QueueMode>();
+  private config: QueueConfig;
+  private onDrain?: DrainHandler;
+
+  constructor(config: QueueConfig) {
+    this.config = config;
+  }
+
+  setDrainHandler(handler: DrainHandler): void {
+    this.onDrain = handler;
+  }
+
+  enqueue(
+    sessionId: string,
+    content: string,
+    parts?: RuntimeInputPart[],
+    agent?: string,
+    metadata?: Record<string, unknown>,
+    modeOverride?: QueueMode,
+  ): { queued: boolean; depth: number } {
+    if (!this.config.enabled) {
+      return { queued: false, depth: 0 };
+    }
+
+    const mode = modeOverride ?? this.modes.get(sessionId) ?? this.config.defaultMode;
+    const queue = this.pending.get(sessionId) ?? [];
+
+    const message: QueuedMessage = {
+      id: `qmsg-${crypto.randomUUID().slice(0, 12)}`,
+      sessionId,
+      content,
+      parts,
+      agent,
+      metadata,
+      arrivedAt: Date.now(),
+    };
+
+    switch (mode) {
+      case "replace":
+        this.pending.set(sessionId, [message]);
+        break;
+
+      case "collect":
+      case "followup":
+        if (queue.length >= this.config.maxDepth) {
+          queue.shift();
+        }
+        queue.push(message);
+        this.pending.set(sessionId, queue);
+        break;
+    }
+
+    return { queued: true, depth: this.pending.get(sessionId)?.length ?? 0 };
+  }
+
+  drain(sessionId: string): QueuedMessage[] | null {
+    const queue = this.pending.get(sessionId);
+    if (!queue || queue.length === 0) {
+      return null;
+    }
+
+    this.pending.delete(sessionId);
+    return queue;
+  }
+
+  async drainAndExecute(sessionId: string): Promise<QueueDrainResult | null> {
+    const queue = this.drain(sessionId);
+    if (!queue || queue.length === 0) {
+      return null;
+    }
+
+    const mode = this.modes.get(sessionId) ?? this.config.defaultMode;
+    let messagesToProcess: QueuedMessage[];
+    let coalesced = false;
+
+    const hasAttachments = queue.some(message => Array.isArray(message.parts) && message.parts.length > 0);
+    if (mode === "collect" && queue.length > 1 && !hasAttachments) {
+      const coalescedContent = this.coalesceMessages(queue);
+      messagesToProcess = [
+        {
+          id: `coalesced-${Date.now()}`,
+          sessionId,
+          content: coalescedContent,
+          arrivedAt: Date.now(),
+        },
+      ];
+      coalesced = true;
+    } else if (mode === "followup") {
+      messagesToProcess = [queue[0]!];
+      if (queue.length > 1) {
+        this.pending.set(sessionId, queue.slice(1));
+      }
+    } else {
+      messagesToProcess = queue;
+    }
+
+    if (this.onDrain) {
+      await this.onDrain(sessionId, messagesToProcess, mode);
+    }
+
+    return {
+      messagesProcessed: messagesToProcess.length,
+      mode,
+      coalesced,
+    };
+  }
+
+  private coalesceMessages(messages: QueuedMessage[]): string {
+    const parts: string[] = ["While you were processing, these messages arrived:\n"];
+
+    for (const [i, msg] of messages.entries()) {
+      const timestamp = new Date(msg.arrivedAt).toLocaleTimeString();
+      parts.push(`\n[${i + 1}] (${timestamp}) ${msg.content}`);
+    }
+
+    parts.push("\n\nPlease address these messages together.");
+    return parts.join("");
+  }
+
+  setMode(sessionId: string, mode: QueueMode): void {
+    this.modes.set(sessionId, mode);
+  }
+
+  getMode(sessionId: string): QueueMode {
+    return this.modes.get(sessionId) ?? this.config.defaultMode;
+  }
+
+  depth(sessionId: string): number {
+    return this.pending.get(sessionId)?.length ?? 0;
+  }
+
+  stats(): LaneStats[] {
+    const stats: LaneStats[] = [];
+    const now = Date.now();
+
+    for (const [sessionId, queue] of this.pending) {
+      stats.push({
+        sessionId,
+        depth: queue.length,
+        mode: this.getMode(sessionId),
+        oldestMessageAge: queue[0] ? now - queue[0].arrivedAt : null,
+      });
+    }
+
+    return stats;
+  }
+
+  clear(sessionId: string): number {
+    const depth = this.depth(sessionId);
+    this.pending.delete(sessionId);
+    return depth;
+  }
+
+  clearAll(): void {
+    this.pending.clear();
+    this.modes.clear();
+  }
+}
+
+let laneQueue: LaneQueue | null = null;
+
+function resolveQueueConfig(): QueueConfig {
+  return getConfigSnapshot().config.runtime.queue;
+}
+
+export function getLaneQueue(): LaneQueue {
+  if (!laneQueue) {
+    laneQueue = new LaneQueue(resolveQueueConfig());
+  }
+  return laneQueue;
+}

package/apps/server/src/backend/queue/types.ts

@@ -0,0 +1,39 @@
+import type { RuntimeInputPart } from "../contracts/runtime";
+
+export type QueueMode = "collect" | "followup" | "replace";
+
+export interface QueuedMessage {
+  id: string;
+  sessionId: string;
+  content: string;
+  parts?: RuntimeInputPart[];
+  agent?: string;
+  metadata?: Record<string, unknown>;
+  arrivedAt: number;
+}
+
+export interface LaneStats {
+  sessionId: string;
+  depth: number;
+  mode: QueueMode;
+  oldestMessageAge: number | null;
+}
+
+export interface QueueConfig {
+  enabled: boolean;
+  defaultMode: QueueMode;
+  maxDepth: number;
+  coalesceDebounceMs: number;
+}
+
+export interface QueueDrainResult {
+  messagesProcessed: number;
+  mode: QueueMode;
+  coalesced: boolean;
+}
+
+export type DrainHandler = (
+  sessionId: string,
+  messages: QueuedMessage[],
+  mode: QueueMode,
+) => Promise<void>;