feat: serialize command auto-replies with queue

src/process/command-queue.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+
+import { enqueueCommand, getQueueSize } from "./command-queue.js";
+
+describe("command queue", () => {
+	it("runs tasks one at a time in order", async () => {
+		let active = 0;
+		let maxActive = 0;
+		const calls: number[] = [];
+
+		const makeTask = (id: number) => async () => {
+			active += 1;
+			maxActive = Math.max(maxActive, active);
+			calls.push(id);
+			await new Promise((resolve) => setTimeout(resolve, 15));
+			active -= 1;
+			return id;
+		};
+
+		const results = await Promise.all([
+			enqueueCommand(makeTask(1)),
+			enqueueCommand(makeTask(2)),
+			enqueueCommand(makeTask(3)),
+		]);
+
+		expect(results).toEqual([1, 2, 3]);
+		expect(calls).toEqual([1, 2, 3]);
+		expect(maxActive).toBe(1);
+		expect(getQueueSize()).toBe(0);
+	});
+
+	it("invokes onWait callback when a task waits past the threshold", async () => {
+		let waited: number | null = null;
+		let queuedAhead: number | null = null;
+
+		// First task holds the queue long enough to trigger wait notice.
+		const first = enqueueCommand(async () => {
+			await new Promise((resolve) => setTimeout(resolve, 30));
+		});
+
+		const second = enqueueCommand(
+			async () => {},
+			{
+				warnAfterMs: 5,
+				onWait: (ms, ahead) => {
+					waited = ms;
+					queuedAhead = ahead;
+				},
+			},
+		);
+
+		await Promise.all([first, second]);
+
+		expect(waited).not.toBeNull();
+		expect((waited as number)).toBeGreaterThanOrEqual(5);
+		expect(queuedAhead).toBe(0);
+	});
+});

src/process/command-queue.ts

@@ -0,0 +1,58 @@
+// Minimal in-process queue to serialize command executions.
+// Ensures only one command runs at a time across webhook, poller, and web inbox flows.
+
+type QueueEntry = {
+	task: () => Promise<unknown>;
+	resolve: (value: unknown) => void;
+	reject: (reason?: unknown) => void;
+	enqueuedAt: number;
+	warnAfterMs: number;
+	onWait?: (waitMs: number, queuedAhead: number) => void;
+};
+
+const queue: QueueEntry[] = [];
+let draining = false;
+
+async function drainQueue() {
+	if (draining) return;
+	draining = true;
+	while (queue.length) {
+		const entry = queue.shift() as QueueEntry;
+		const waitedMs = Date.now() - entry.enqueuedAt;
+		if (waitedMs >= entry.warnAfterMs) {
+			entry.onWait?.(waitedMs, queue.length);
+		}
+		try {
+			const result = await entry.task();
+			entry.resolve(result);
+		} catch (err) {
+			entry.reject(err);
+		}
+	}
+	draining = false;
+}
+
+export function enqueueCommand<T>(
+	task: () => Promise<T>,
+	opts?: {
+		warnAfterMs?: number;
+		onWait?: (waitMs: number, queuedAhead: number) => void;
+	},
+): Promise<T> {
+	const warnAfterMs = opts?.warnAfterMs ?? 2_000;
+	return new Promise<T>((resolve, reject) => {
+		queue.push({
+			task: () => task(),
+			resolve: (value) => resolve(value as T),
+			reject,
+			enqueuedAt: Date.now(),
+			warnAfterMs,
+			onWait: opts?.onWait,
+		});
+		void drainQueue();
+	});
+}
+
+export function getQueueSize() {
+	return queue.length + (draining ? 1 : 0);
+}