macroclaw 0.0.0-dev

package/src/orchestrator.ts

@@ -0,0 +1,396 @@
+import { z } from "zod/v4";
+import { Claude, type ClaudeDeferredResult, ClaudeParseError, ClaudeProcessError, type ClaudeResult, isDeferred } from "./claude";
+import { logPrompt, logResult } from "./history";
+import { createLogger } from "./logger";
+import { BG_TIMEOUT, CRON_TIMEOUT, MAIN_TIMEOUT, SYSTEM_PROMPT } from "./prompts";
+import { Queue } from "./queue";
+import { loadSettings, newSessionId, type Settings, saveSettings } from "./settings";
+
+const log = createLogger("orchestrator");
+
+// --- Response schema (owned by orchestrator) ---
+// Flat object (no oneOf/discriminatedUnion) — Claude CLI --json-schema requires a single top-level object.
+
+const backgroundAgentSchema = z.object({
+  name: z.string().describe("Label for the background agent"),
+  prompt: z.string().describe("The prompt/task for the background agent"),
+  model: z.enum(["haiku", "sonnet", "opus"]).describe("Model to use for the background agent").optional(),
+});
+
+const claudeResponseSchema = z.object({
+  action: z.enum(["send", "silent"]).describe("'send' to reply to the user, 'silent' to do nothing"),
+  actionReason: z.string().describe("Why the agent chose this action (logged, not sent)"),
+  message: z.string().describe("The message to send to Telegram (required when action is 'send')").optional(),
+  files: z.array(z.string()).describe("Absolute paths to files to send to Telegram").optional(),
+  buttons: z.array(z.string()).describe("Button labels to show below the message").optional(),
+  backgroundAgents: z.array(backgroundAgentSchema).describe("Background agents to spawn alongside this response").optional(),
+});
+
+type ClaudeResponseInternal = z.infer<typeof claudeResponseSchema>;
+
+const jsonSchema = JSON.stringify(z.toJSONSchema(claudeResponseSchema, { target: "jsonSchema7" }));
+
+// --- Public response type ---
+
+export interface OrchestratorResponse {
+  message: string;
+  files?: string[];
+  buttons?: string[];
+}
+
+// --- Internal request types ---
+
+type OrchestratorRequest =
+  | { type: "user"; message: string; files?: string[] }
+  | { type: "cron"; name: string; prompt: string; model?: string }
+  | { type: "background-agent-result"; name: string; response: ClaudeResponseInternal; sessionId?: string }
+  | { type: "background-agent"; name: string; prompt: string; model?: string }
+  | { type: "button"; label: string };
+
+function escapeHtml(text: string): string {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+// --- Background tracking ---
+
+interface BackgroundInfo {
+  name: string;
+  sessionId: string;
+  startTime: Date;
+}
+
+// --- Orchestrator ---
+
+export interface OrchestratorConfig {
+  model?: string;
+  workspace: string;
+  settingsDir?: string;
+  onResponse: (response: OrchestratorResponse) => Promise<void>;
+  claude?: Claude;
+}
+
+interface BuiltRequest {
+  prompt: string;
+  model: string | undefined;
+  timeout: number;
+  files?: string[];
+  useMainSession: boolean;
+}
+
+interface CallResult {
+  response: ClaudeResponseInternal;
+  sessionId: string;
+}
+
+export class Orchestrator {
+  #claude: Claude;
+  #settings: Settings;
+  #sessionId: string;
+  #sessionFlag: "--resume" | "--session-id";
+  #sessionResolved = false;
+  #config: OrchestratorConfig;
+  #active = new Map<string, BackgroundInfo>();
+  #queue: Queue<OrchestratorRequest>;
+
+  constructor(config: OrchestratorConfig) {
+    this.#config = config;
+    this.#claude = config.claude ?? new Claude({ workspace: config.workspace, jsonSchema });
+    this.#settings = loadSettings(config.settingsDir);
+    this.#queue = new Queue<OrchestratorRequest>();
+    this.#queue.setHandler((request) => this.#handleRequest(request));
+
+    if (this.#settings.sessionId) {
+      this.#sessionId = this.#settings.sessionId;
+      this.#sessionFlag = "--resume";
+    } else {
+      this.#sessionId = newSessionId();
+      this.#sessionFlag = "--session-id";
+      saveSettings({ sessionId: this.#sessionId }, config.settingsDir);
+      log.info({ sessionId: this.#sessionId }, "Created new session");
+    }
+  }
+
+  // --- Public handle methods ---
+
+  handleMessage(message: string, files?: string[]): void {
+    this.#queue.push({ type: "user", message, files });
+  }
+
+  handleButton(label: string): void {
+    this.#queue.push({ type: "button", label });
+  }
+
+  handleCron(name: string, prompt: string, model?: string): void {
+    this.#queue.push({ type: "cron", name, prompt, model });
+  }
+
+  handleBackgroundCommand(prompt: string): void {
+    const name = prompt.slice(0, 30).replace(/\s+/g, "-");
+    this.#spawnBackground(name, prompt, this.#config.model);
+    this.#callOnResponse({ message: `Background agent "${escapeHtml(name)}" started.` });
+  }
+
+  handleBackgroundList(): void {
+    const agents = [...this.#active.values()];
+    if (agents.length === 0) {
+      this.#callOnResponse({ message: "No background agents running." });
+      return;
+    }
+    const lines = agents.map((a) => {
+      const elapsed = Math.round((Date.now() - a.startTime.getTime()) / 1000);
+      return `- ${escapeHtml(a.name)} (${elapsed}s)`;
+    });
+    this.#callOnResponse({ message: lines.join("\n") });
+  }
+
+  handleSessionCommand(): void {
+    this.#callOnResponse({ message: `Session: <code>${this.#sessionId}</code>` });
+  }
+
+  // --- Internal queue handler ---
+
+  async #handleRequest(request: OrchestratorRequest): Promise<void> {
+    log.debug({ type: request.type }, "Incoming request");
+
+    // Background result with matching session ID: deliver directly without Claude round-trip
+    if (request.type === "background-agent-result" && "sessionId" in request && request.sessionId === this.#sessionId) {
+      log.debug({ name: request.name }, "Background result on current session, applying directly");
+      await this.#deliverClaudeResponse(request.response);
+      return;
+    }
+
+    // Fork session if a backgrounded task is running on the main session
+    const needsFork = (request.type === "user" || request.type === "button") && this.#active.has(this.#sessionId);
+
+    const startTime = new Date();
+    const rawResponse = await this.#processRequest(request, needsFork ? { forkSession: true } : undefined);
+    if (isDeferred(rawResponse)) {
+      const name = request.type === "user" ? request.message.slice(0, 30).replace(/\s+/g, "-")
+        : request.type === "cron" ? `cron-${request.name}`
+        : "task";
+      log.info({ name, sessionId: rawResponse.sessionId }, "Request backgrounded due to timeout");
+      this.#callOnResponse({ message: "This is taking longer, continuing in the background." });
+      this.#adoptBackground(name, rawResponse.sessionId, startTime, rawResponse.completion.then(
+        (r) => {
+          const msg = r.structuredOutput ? String((r.structuredOutput as Record<string, unknown>).message ?? "") : (r.result ?? "");
+          return { action: "send" as const, message: msg, actionReason: "deferred-completed" };
+        },
+        (err) => ({ action: "send" as const, message: `[Error] ${err}`, actionReason: "deferred-failed" }),
+      ));
+      return;
+    }
+
+    log.debug({ action: rawResponse.action, actionReason: rawResponse.actionReason }, "Response");
+    await this.#deliverClaudeResponse(rawResponse);
+  }
+
+  async #deliverClaudeResponse(response: ClaudeResponseInternal): Promise<void> {
+    if (response.action === "send") {
+      this.#callOnResponse({
+        message: response.message || "[No output]",
+        files: response.files,
+        buttons: response.buttons,
+      });
+    } else {
+      log.debug("Silent response");
+    }
+
+    if (response.backgroundAgents?.length) {
+      for (const agent of response.backgroundAgents) {
+        const agentModel = agent.model ?? this.#config.model;
+        this.#spawnBackground(agent.name, agent.prompt, agentModel);
+        this.#callOnResponse({ message: `Background agent "${escapeHtml(agent.name)}" started.` });
+      }
+    }
+  }
+
+  #callOnResponse(response: OrchestratorResponse): void {
+    this.#config.onResponse(response).catch((err) => {
+      log.error({ err }, "onResponse callback failed");
+    });
+  }
+
+  // --- Internal background management ---
+
+  #spawnBackground(name: string, prompt: string, model: string | undefined) {
+    const sessionId = newSessionId();
+    const info: BackgroundInfo = { name, sessionId, startTime: new Date() };
+    this.#active.set(sessionId, info);
+
+    log.debug({ name, sessionId }, "Starting background agent");
+
+    this.#processRequest({ type: "background-agent", name, prompt, model }).then(
+      async (rawResponse) => {
+        let response: ClaudeResponseInternal;
+        if (isDeferred(rawResponse)) {
+          try {
+            const r = await rawResponse.completion;
+            response = { action: "send", message: String(r.structuredOutput ?? r.result ?? ""), actionReason: "deferred-completed" };
+          } catch (err) {
+            response = { action: "send", message: `[Error] ${err}`, actionReason: "deferred-failed" };
+          }
+        } else {
+          response = rawResponse;
+        }
+        this.#active.delete(sessionId);
+        log.debug({ name, message: response.message }, "Background agent finished");
+        this.#queue.push({ type: "background-agent-result", name, response });
+      },
+      (err) => {
+        this.#active.delete(sessionId);
+        log.error({ name, err }, "Background agent failed");
+        this.#queue.push({ type: "background-agent-result", name, response: { action: "send", message: `[Error] ${err}`, actionReason: "bg-agent-failed" } });
+      },
+    );
+  }
+
+  #adoptBackground(name: string, sessionId: string, startTime: Date, completion: Promise<ClaudeResponseInternal>) {
+    const info: BackgroundInfo = { name, sessionId, startTime };
+    this.#active.set(sessionId, info);
+
+    log.debug({ name, sessionId }, "Adopting backgrounded task");
+
+    // completion is pre-wrapped with .then(ok, err) at the call site, so it never rejects
+    completion.then((response) => {
+      this.#active.delete(sessionId);
+      log.debug({ name, message: response.message }, "Adopted task finished");
+      this.#queue.push({ type: "background-agent-result", name, response, sessionId });
+    });
+  }
+
+  // --- Core Claude processing ---
+
+  async #processRequest(request: OrchestratorRequest, options?: { forkSession?: boolean }): Promise<ClaudeResponseInternal | ClaudeDeferredResult> {
+    const built = this.#buildRequest(request);
+    await logPrompt(request);
+
+    if (built.useMainSession) {
+      let result = await this.#callClaude(built, this.#sessionFlag, this.#sessionId, options?.forkSession);
+
+      // Session resolution: if resume failed on first call, create new session
+      if (!isDeferred(result) && !this.#sessionResolved && this.#sessionFlag === "--resume" && result.response.actionReason === "process-error") {
+        this.#sessionId = newSessionId();
+        log.info({ sessionId: this.#sessionId }, "Resume failed, created new session");
+        this.#sessionFlag = "--session-id";
+        saveSettings({ sessionId: this.#sessionId }, this.#config.settingsDir);
+        result = await this.#callClaude(built, this.#sessionFlag, this.#sessionId);
+      }
+
+      if (isDeferred(result)) return result;
+
+      // Update session ID from response (important after fork)
+      if (result.sessionId && result.sessionId !== this.#sessionId) {
+        log.info({ oldSessionId: this.#sessionId, newSessionId: result.sessionId }, "Session forked, updating session ID");
+        this.#sessionId = result.sessionId;
+        saveSettings({ sessionId: this.#sessionId }, this.#config.settingsDir);
+      }
+
+      // Mark resolved on first success
+      if (!this.#sessionResolved && result.response.actionReason !== "process-error") {
+        this.#sessionResolved = true;
+        this.#sessionFlag = "--resume";
+      }
+
+      await logResult(result.response);
+      return result.response;
+    }
+
+    // background-agent: fork from main session for full context
+    log.debug({ name: (request as { name: string }).name }, "Processing background-agent (forked session)");
+    const bgResult = await this.#callClaude(built, "--resume", this.#sessionId, true);
+    if (isDeferred(bgResult)) return bgResult;
+    await logResult(bgResult.response);
+    return bgResult.response;
+  }
+
+  #buildRequest(request: OrchestratorRequest): BuiltRequest {
+    switch (request.type) {
+      case "user":
+        return {
+          prompt: this.#buildPromptWithFiles(request.message, request.files),
+          model: this.#config.model,
+          timeout: MAIN_TIMEOUT,
+          useMainSession: true,
+        };
+      case "cron":
+        return {
+          prompt: `[Context: cron/${request.name}] ${request.prompt}`,
+          model: request.model ?? this.#config.model,
+          timeout: CRON_TIMEOUT,
+          useMainSession: true,
+        };
+      case "background-agent-result":
+        return {
+          prompt: `[Context: background-result/${request.name}] ${request.response.message || "[No output]"}`,
+          model: this.#config.model,
+          timeout: MAIN_TIMEOUT,
+          useMainSession: true,
+        };
+      case "button":
+        return {
+          prompt: `[Context: button-click] User tapped "${request.label}"`,
+          model: this.#config.model,
+          timeout: MAIN_TIMEOUT,
+          useMainSession: true,
+        };
+      case "background-agent":
+        return {
+          prompt: `[Context: background-agent/${request.name}] ${request.prompt}`,
+          model: request.model ?? this.#config.model,
+          timeout: BG_TIMEOUT,
+          useMainSession: false,
+        };
+    }
+  }
+
+  #buildPromptWithFiles(message: string, files?: string[]): string {
+    if (!files?.length) return message;
+    const prefix = files.map((f) => `[File: ${f}]`).join("\n");
+    return message ? `${prefix}\n${message}` : prefix;
+  }
+
+  #validateResponse(raw: unknown): ClaudeResponseInternal {
+    const parsed = claudeResponseSchema.safeParse(raw);
+    if (parsed.success) return parsed.data;
+    log.warn({ error: parsed.error.message }, "structured_output failed validation");
+    const rawObj = raw as Record<string, unknown> | null;
+    const msg = typeof rawObj?.message === "string" ? rawObj.message : JSON.stringify(raw);
+    return { action: "send", message: msg, actionReason: "validation-failed" };
+  }
+
+  #resultToCallResult(result: ClaudeResult): CallResult {
+    if (result.structuredOutput) {
+      return { response: this.#validateResponse(result.structuredOutput), sessionId: result.sessionId };
+    }
+    log.error({ hasResult: !!result.result }, "No structured_output in response");
+    const raw = result.result ? escapeHtml(result.result) : "";
+    const msg = raw ? `[No structured output] ${raw}` : "[No output]";
+    return { response: { action: "send", message: msg, actionReason: "no-structured-output" }, sessionId: result.sessionId };
+  }
+
+  async #callClaude(built: BuiltRequest, flag: "--resume" | "--session-id", sid: string, forkSession?: boolean): Promise<CallResult | ClaudeDeferredResult> {
+    try {
+      const result = await this.#claude.run({
+        prompt: built.prompt,
+        sessionFlag: flag,
+        sessionId: sid,
+        forkSession,
+        model: built.model,
+        systemPrompt: SYSTEM_PROMPT,
+        timeoutMs: built.timeout,
+      });
+
+      if (isDeferred(result)) return result;
+
+      return this.#resultToCallResult(result);
+    } catch (err) {
+      if (err instanceof ClaudeProcessError) {
+        return { response: { action: "send", message: `[Error] Claude exited with code ${err.exitCode}:\n${err.stderr}`, actionReason: "process-error" }, sessionId: sid };
+      }
+      if (err instanceof ClaudeParseError) {
+        return { response: { action: "send", message: `[JSON Error] ${err.raw}`, actionReason: "json-parse-failed" }, sessionId: sid };
+      }
+      throw err;
+    }
+  }
+}

package/src/prompts.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "bun:test";
+import { SYSTEM_PROMPT } from "./prompts";
+
+describe("SYSTEM_PROMPT", () => {
+  it("contains key sections", () => {
+    expect(SYSTEM_PROMPT).toContain("macroclaw");
+    expect(SYSTEM_PROMPT).toContain("Structured output");
+    expect(SYSTEM_PROMPT).toContain("Context tags");
+    expect(SYSTEM_PROMPT).toContain("Background agents");
+    expect(SYSTEM_PROMPT).toContain("Cron");
+    expect(SYSTEM_PROMPT).toContain("Buttons");
+    expect(SYSTEM_PROMPT).toContain("Files");
+    expect(SYSTEM_PROMPT).toContain("Timeouts");
+  });
+
+  it("contains HTML formatting instructions", () => {
+    expect(SYSTEM_PROMPT).toContain("HTML parse mode");
+    expect(SYSTEM_PROMPT).toContain("<b>");
+  });
+
+  it("documents all context tag types", () => {
+    expect(SYSTEM_PROMPT).toContain("cron/<name>");
+    expect(SYSTEM_PROMPT).toContain("button-click");
+    expect(SYSTEM_PROMPT).toContain("background-result/<name>");
+    expect(SYSTEM_PROMPT).toContain("background-agent/<name>");
+  });
+
+  it("contains structured output reinforcement", () => {
+    expect(SYSTEM_PROMPT).toContain("StructuredOutput tool");
+    expect(SYSTEM_PROMPT).toContain("actionReason");
+  });
+
+  it("contains no personal names", () => {
+    expect(SYSTEM_PROMPT).not.toContain("Alfread");
+    expect(SYSTEM_PROMPT).not.toContain("Michal");
+  });
+
+  it("documents background agent model options", () => {
+    expect(SYSTEM_PROMPT).toContain("haiku");
+    expect(SYSTEM_PROMPT).toContain("sonnet");
+    expect(SYSTEM_PROMPT).toContain("opus");
+  });
+});

package/src/prompts.ts

@@ -0,0 +1,48 @@
+export const MAIN_TIMEOUT = 60_000;
+export const CRON_TIMEOUT = 300_000;
+export const BG_TIMEOUT = 1_800_000;
+
+const fmtMin = (ms: number) => {
+  const m = ms / 60_000;
+  return `${m} minute${m > 1 ? "s" : ""}`;
+};
+
+export const SYSTEM_PROMPT = `\
+AI assistant running in macroclaw, an autonomous agent platform. \
+Persistent workspace at cwd with config, memory, skills. \
+Refer to workspace CLAUDE.md for identity, personality, conventions.
+
+Responses delivered as chat messages. Keep concise and direct.
+
+Structured output: you have a StructuredOutput tool. When you are done processing, \
+call StructuredOutput to deliver your final response. \
+Required fields: action ("send"|"silent"), actionReason. Include message when action="send".
+
+Formatting: message field sent to Telegram with HTML parse mode. \
+Use raw <b>, <i>, <code>, <pre> tags. Escape &, <, > in text content as &amp;, &lt;, &gt;.
+
+Architecture: message bridge connecting chat interface and scheduled tasks. \
+Persistent session — conversation history carries across messages. Workspace persists across sessions.
+
+Context tags: messages may be prefixed with [Context: <type>]. Types:
+- cron/<name> — automated scheduled task. Prefer action="silent" when nothing noteworthy.
+- button-click — user tapped an inline keyboard button.
+- background-result/<name> — output from a background agent you spawned. Decide whether to relay or handle silently.
+- background-agent/<name> — you are a background agent. Complete task, return result. Cannot spawn sub-agents.
+
+Background agents: spawn alongside any response via backgroundAgents array:
+  backgroundAgents: [{ name: "label", prompt: "task", model: "haiku" }]
+Each runs in same workspace, fresh session. Result fed back as [Context: background-result/<name>].
+Models: haiku (fast/cheap), sonnet (balanced, default), opus (complex reasoning).
+User can spawn directly with "bg:" prefix. Use for long-running tasks that shouldn't block.
+
+Files: attachments listed as [File: /path] prefixes. Read/view at those paths. \
+Send files via files array (absolute paths). Images (.png/.jpg/.jpeg/.gif/.webp) as photos, rest as documents. 50MB limit.
+
+Timeouts: user=${fmtMin(MAIN_TIMEOUT)}, cron=${fmtMin(CRON_TIMEOUT)}, background=${fmtMin(BG_TIMEOUT)}. \
+On timeout, task continues in background automatically. Spawn background agents proactively for long tasks.
+
+Cron: jobs in .macroclaw/cron.json (hot-reloaded). Use "silent" when check finds nothing new, "send" when noteworthy.
+
+MessageButtons: include a buttons field (flat array of label strings) to attach inline buttons below your message. \
+Each button gets its own row. Max 27 characters per label — if options need more detail, describe them in the message and use short labels on buttons.`;

package/src/queue.test.ts

@@ -0,0 +1,150 @@
+import { describe, expect, it } from "bun:test";
+import { Queue } from "./queue";
+
+interface TestItem {
+  value: string;
+  extra?: number;
+}
+
+describe("Queue", () => {
+  it("processes items in FIFO order", async () => {
+    const queue = new Queue<TestItem>();
+    const results: string[] = [];
+    queue.setHandler(async (item) => {
+      results.push(item.value);
+    });
+
+    queue.push({ value: "first" });
+    await new Promise((r) => setTimeout(r, 10));
+
+    queue.push({ value: "second" });
+    await new Promise((r) => setTimeout(r, 10));
+
+    expect(results).toEqual(["first", "second"]);
+  });
+
+  it("processes queued items serially", async () => {
+    const queue = new Queue<TestItem>();
+    const order: string[] = [];
+    let resolveSecond: (() => void) | null = null;
+
+    queue.setHandler(async (item) => {
+      if (item.value === "slow") {
+        await new Promise<void>((r) => {
+          resolveSecond = r;
+        });
+      }
+      order.push(item.value);
+    });
+
+    queue.push({ value: "slow" });
+    queue.push({ value: "fast" });
+
+    // "fast" should be queued, not processed yet
+    await new Promise((r) => setTimeout(r, 10));
+    expect(order).toEqual([]);
+    expect(queue.isProcessing).toBe(true);
+
+    // Release the slow handler
+    resolveSecond!();
+    await new Promise((r) => setTimeout(r, 10));
+
+    expect(order).toEqual(["slow", "fast"]);
+    expect(queue.isProcessing).toBe(false);
+  });
+
+  it("does nothing without a handler", async () => {
+    const queue = new Queue<TestItem>();
+    queue.push({ value: "orphan" });
+    await new Promise((r) => setTimeout(r, 10));
+    expect(queue.length).toBe(1);
+  });
+
+  it("reports length correctly", () => {
+    const queue = new Queue<TestItem>();
+    expect(queue.length).toBe(0);
+    // No handler set, so items accumulate
+    queue.push({ value: "a" });
+    queue.push({ value: "b" });
+    expect(queue.length).toBe(2);
+  });
+
+  it("reports isProcessing correctly", async () => {
+    const queue = new Queue<TestItem>();
+    expect(queue.isProcessing).toBe(false);
+
+    let resolve: (() => void) | null = null;
+    queue.setHandler(async () => {
+      await new Promise<void>((r) => {
+        resolve = r;
+      });
+    });
+
+    queue.push({ value: "msg" });
+    await new Promise((r) => setTimeout(r, 10));
+    expect(queue.isProcessing).toBe(true);
+
+    resolve!();
+    await new Promise((r) => setTimeout(r, 10));
+    expect(queue.isProcessing).toBe(false);
+  });
+
+  it("does not re-enter process when already processing", async () => {
+    const queue = new Queue<TestItem>();
+    let callCount = 0;
+    let resolve: (() => void) | null = null;
+
+    queue.setHandler(async () => {
+      callCount++;
+      if (callCount === 1) {
+        await new Promise<void>((r) => {
+          resolve = r;
+        });
+      }
+    });
+
+    queue.push({ value: "a" });
+    await new Promise((r) => setTimeout(r, 10));
+
+    // Push while processing - process() will be called but should no-op
+    queue.push({ value: "b" });
+    expect(queue.isProcessing).toBe(true);
+
+    resolve!();
+    await new Promise((r) => setTimeout(r, 10));
+    // Both items should have been processed
+    expect(callCount).toBe(2);
+  });
+
+  it("continues processing after handler throws", async () => {
+    const queue = new Queue<TestItem>();
+    const results: string[] = [];
+    queue.setHandler(async (item) => {
+      if (item.value === "bad") throw new Error("handler failed");
+      results.push(item.value);
+    });
+
+    queue.push({ value: "first" });
+    await new Promise((r) => setTimeout(r, 10));
+
+    queue.push({ value: "bad" });
+    queue.push({ value: "third" });
+    await new Promise((r) => setTimeout(r, 10));
+
+    expect(results).toEqual(["first", "third"]);
+    expect(queue.isProcessing).toBe(false);
+  });
+
+  it("passes all fields through in queue item", async () => {
+    const queue = new Queue<TestItem>();
+    let received: TestItem | undefined;
+    queue.setHandler(async (item) => {
+      received = item;
+    });
+
+    queue.push({ value: "test", extra: 42 });
+    await new Promise((r) => setTimeout(r, 10));
+
+    expect(received).toEqual({ value: "test", extra: 42 });
+  });
+});

package/src/queue.ts

@@ -0,0 +1,42 @@
+import { createLogger } from "./logger";
+
+const log = createLogger("queue");
+
+export class Queue<T> {
+  #items: T[] = [];
+  #processing = false;
+  #handler: ((item: T) => Promise<void>) | null = null;
+
+  setHandler(fn: (item: T) => Promise<void>) {
+    this.#handler = fn;
+  }
+
+  push(item: T) {
+    this.#items.push(item);
+    this.process();
+  }
+
+  async process() {
+    if (this.#processing || !this.#handler) return;
+    this.#processing = true;
+
+    while (this.#items.length > 0) {
+      const item = this.#items.shift() as T;
+      try {
+        await this.#handler(item);
+      } catch (err) {
+        log.error({ err }, "Handler error");
+      }
+    }
+
+    this.#processing = false;
+  }
+
+  get length() {
+    return this.#items.length;
+  }
+
+  get isProcessing() {
+    return this.#processing;
+  }
+}