agent-mockingbird 0.0.1

package/apps/server/src/backend/heartbeat/runtimeService.ts

@@ -0,0 +1,190 @@
+import { deleteLegacyHeartbeatJobs } from "./defaultJob";
+import { executeHeartbeat, parseInterval } from "./service";
+import { getHeartbeatRuntimeState, patchHeartbeatRuntimeState } from "./state";
+import type { HeartbeatRuntimeConfig, HeartbeatStatus } from "./types";
+import { getConfigSnapshot } from "../config/service";
+import { getSessionById, setSessionModel, setSessionTitle } from "../db/repository";
+import { getRuntime } from "../runtime";
+
+const HEARTBEAT_SESSION_TITLE = "Heartbeat";
+const TICK_MS = 1_000;
+
+function nowMs() {
+  return Date.now();
+}
+
+function toIso(value: number | null) {
+  return value == null ? null : new Date(value).toISOString();
+}
+
+function loadHeartbeatConfig(): HeartbeatRuntimeConfig {
+  return getConfigSnapshot().config.runtime.heartbeat;
+}
+
+export class HeartbeatRuntimeService {
+  private timer: Timer | null = null;
+  private inFlight: Promise<HeartbeatStatus> | null = null;
+
+  start() {
+    deleteLegacyHeartbeatJobs();
+    void this.ensureHeartbeatSession();
+    this.timer = setInterval(() => {
+      void this.tick();
+    }, TICK_MS);
+    void this.tick();
+  }
+
+  stop() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+  }
+
+  getStatus(): HeartbeatStatus {
+    const config = loadHeartbeatConfig();
+    const state = getHeartbeatRuntimeState();
+    const sessionTitle = state.sessionId ? getSessionById(state.sessionId)?.title ?? null : null;
+    return {
+      config,
+      state,
+      sessionTitle,
+      nextDueAt: this.computeNextDueAt(config.interval, state.lastRunAt, state.running, config.enabled),
+    };
+  }
+
+  async runNow() {
+    return this.runHeartbeat({ manual: true });
+  }
+
+  private async tick() {
+    const config = loadHeartbeatConfig();
+    if (!config.enabled) return;
+    const state = getHeartbeatRuntimeState();
+    const nextDueAt = this.computeNextDueAt(config.interval, state.lastRunAt, state.running, config.enabled);
+    if (!nextDueAt) {
+      await this.runHeartbeat();
+      return;
+    }
+    if (Date.parse(nextDueAt) <= nowMs()) {
+      await this.runHeartbeat();
+    }
+  }
+
+  private computeNextDueAt(
+    interval: string,
+    lastRunAtIso: string | null,
+    running: boolean,
+    enabled: boolean,
+  ) {
+    if (!enabled || running) return null;
+    if (!lastRunAtIso) return null;
+    const lastRunAt = Date.parse(lastRunAtIso);
+    if (!Number.isFinite(lastRunAt)) return null;
+    return toIso(lastRunAt + parseInterval(interval));
+  }
+
+  private async ensureHeartbeatSession() {
+    const config = loadHeartbeatConfig();
+    const state = getHeartbeatRuntimeState();
+    let session = state.sessionId ? getSessionById(state.sessionId) : null;
+    if (!session) {
+      const mainSession = getSessionById("main");
+      if (!mainSession) {
+        throw new Error("Main session not available");
+      }
+      const runtime = getRuntime();
+      if (!runtime?.spawnBackgroundSession) {
+        throw new Error("Runtime does not support heartbeat child sessions");
+      }
+      const spawned = await runtime.spawnBackgroundSession({
+        parentSessionId: "main",
+        title: HEARTBEAT_SESSION_TITLE,
+        requestedBy: "heartbeat",
+        prompt: "",
+      });
+      const sessionId = spawned.childSessionId?.trim();
+      if (!sessionId) {
+        throw new Error("Failed to create heartbeat child session");
+      }
+      session = getSessionById(sessionId);
+      if (!session) {
+        throw new Error(`Failed to load heartbeat child session ${sessionId}`);
+      }
+      patchHeartbeatRuntimeState({
+        sessionId,
+        backgroundRunId: spawned.runId,
+        parentSessionId: spawned.parentSessionId,
+        externalSessionId: spawned.childExternalSessionId,
+      });
+    }
+
+    if (session.title !== HEARTBEAT_SESSION_TITLE) {
+      setSessionTitle(session.id, HEARTBEAT_SESSION_TITLE);
+    }
+    if (session.model !== config.model) {
+      setSessionModel(session.id, config.model);
+    }
+
+    return getSessionById(session.id) ?? session;
+  }
+
+  private async runHeartbeat(input?: { manual?: boolean }) {
+    if (this.inFlight) return this.inFlight;
+
+    const run = (async () => {
+      let sessionIdForState: string | null = getHeartbeatRuntimeState().sessionId;
+      try {
+        const config = loadHeartbeatConfig();
+        const session = await this.ensureHeartbeatSession();
+        sessionIdForState = session.id;
+        patchHeartbeatRuntimeState({
+          sessionId: session.id,
+          running: true,
+          lastError: null,
+        });
+
+        const result = await executeHeartbeat(this.resolveAgentId(config), session.id, {
+          enabled: input?.manual ? true : config.enabled,
+          interval: config.interval,
+          activeHours: config.activeHours,
+          prompt: config.prompt,
+          ackMaxChars: config.ackMaxChars,
+        });
+
+        patchHeartbeatRuntimeState({
+          sessionId: session.id,
+          running: false,
+          lastRunAt: nowMs(),
+          lastResult: result.error
+            ? "error"
+            : result.skipped
+              ? "skipped"
+              : result.acknowledged
+                ? "acknowledged"
+                : "attention",
+          lastResponse: result.response ?? null,
+          lastError: result.error ?? null,
+        });
+      } catch (error) {
+        patchHeartbeatRuntimeState({
+          sessionId: sessionIdForState,
+          running: false,
+          lastRunAt: nowMs(),
+          lastResult: "error",
+          lastResponse: null,
+          lastError: error instanceof Error ? error.message : "Unknown heartbeat error",
+        });
+      }
+      return this.getStatus();
+    })().finally(() => {
+      this.inFlight = null;
+    });
+
+    this.inFlight = run;
+    return run;
+  }
+
+  private resolveAgentId(config: HeartbeatRuntimeConfig) {
+    const requested = config.agentId.trim();
+    return requested || "build";
+  }
+}

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

@@ -0,0 +1,176 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+import { isActiveHours } from "./activeHours";
+import type { HeartbeatConfig, HeartbeatContext, HeartbeatResult } from "./types";
+import { getConfigSnapshot } from "../config/service";
+import { getRuntime } from "../runtime";
+
+export const DEFAULT_HEARTBEAT_PROMPT =
+  "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.";
+
+export function parseInterval(interval: string): number {
+  const match = interval.match(/^(\d+)([mhd])$/);
+  if (!match) throw new Error(`Invalid interval: ${interval}`);
+
+  const value = match[1];
+  const unit = match[2];
+  const num = parseInt(value ?? "0", 10);
+
+  switch (unit) {
+    case "m":
+      return num * 60 * 1000;
+    case "h":
+      return num * 60 * 60 * 1000;
+    case "d":
+      return num * 24 * 60 * 60 * 1000;
+    default:
+      throw new Error(`Unknown unit: ${unit}`);
+  }
+}
+
+function buildHeartbeatPrompt(config: HeartbeatConfig, context: HeartbeatContext): string {
+  const parts: string[] = [];
+
+  const workspaceDir = getConfigSnapshot().config.runtime.opencode.directory;
+  if (workspaceDir) {
+    const heartbeatPath = path.join(workspaceDir, "HEARTBEAT.md");
+    if (existsSync(heartbeatPath)) {
+      const content = readFileSync(heartbeatPath, "utf8").trim();
+      if (content) {
+        parts.push(`# Heartbeat Checklist\n\n${content}`);
+      }
+    }
+  }
+
+  parts.push(`## Heartbeat Prompt
+
+${config.prompt?.trim() || DEFAULT_HEARTBEAT_PROMPT}`);
+
+  parts.push(`## Heartbeat Context
+- Agent: ${context.agentId}
+- Main session: main
+- Thread kind: heartbeat
+- Current time: ${context.now}
+- Scheduled for: ${context.scheduledFor}
+${context.lastHeartbeat ? `- Last heartbeat: ${context.lastHeartbeat}` : ""}
+
+**Instructions:** If everything is fine and nothing needs attention, reply with "HEARTBEAT_OK" (optionally with brief status, max ${config.ackMaxChars} chars). If something needs attention, describe what and why.`);
+
+  return parts.join("\n\n");
+}
+
+function isHeartbeatAck(response: string, ackMaxChars: number): boolean {
+  const trimmed = response.trim();
+  if (!trimmed) return false;
+
+  const stripped = stripHeartbeatTokenAtEdges(trimmed);
+  if (!stripped.didStrip) return false;
+
+  const remaining = stripped.text.trim();
+  return remaining.length <= ackMaxChars;
+}
+
+function stripHeartbeatTokenAtEdges(response: string): { didStrip: boolean; text: string } {
+  let text = response.trim();
+  let didStrip = false;
+  const token = "HEARTBEAT_OK";
+  const isWordChar = (value: string | undefined) => Boolean(value && /[A-Za-z0-9_]/.test(value));
+
+  while (text) {
+    const prefixNext = text[token.length];
+    if (text.startsWith(token) && !isWordChar(prefixNext)) {
+      text = text.slice(token.length).trimStart();
+      didStrip = true;
+      continue;
+    }
+
+    const index = text.lastIndexOf(token);
+    const beforeToken = index > 0 ? text[index - 1] : undefined;
+    const afterToken = index >= 0 ? text[index + token.length] : undefined;
+    if (
+      index >= 0 &&
+      !isWordChar(beforeToken) &&
+      !isWordChar(afterToken) &&
+      text.slice(index + token.length).replace(/[^\w]/g, "").length === 0
+    ) {
+      const before = text.slice(0, index).trimEnd();
+      const after = text.slice(index + token.length).trimStart();
+      text = `${before}${after}`.trim();
+      didStrip = true;
+      continue;
+    }
+
+    break;
+  }
+
+  return { didStrip, text };
+}
+
+export async function executeHeartbeat(
+  agentId: string,
+  sessionId: string,
+  config: HeartbeatConfig,
+): Promise<HeartbeatResult> {
+  if (!isActiveHours(config)) {
+    return {
+      acknowledged: false,
+      skipped: true,
+      suppressed: true,
+      response: "Skipped: outside active hours",
+    };
+  }
+
+  const runtime = getRuntime();
+  if (!runtime) {
+    return {
+      acknowledged: false,
+      suppressed: false,
+      error: "Runtime not available",
+    };
+  }
+
+  const context: HeartbeatContext = {
+    agentId,
+    sessionId,
+    scheduledFor: new Date().toISOString(),
+    now: new Date().toISOString(),
+  };
+
+  const prompt = buildHeartbeatPrompt(config, context);
+
+  try {
+    const ack = await runtime.sendUserMessage({
+      sessionId,
+      content: prompt,
+      agent: agentId,
+      metadata: { heartbeat: true },
+    });
+
+    const lastMessage = [...ack.messages].reverse().find(m => m.role === "assistant");
+
+    const response = lastMessage?.content ?? "";
+    const acknowledged = isHeartbeatAck(response, config.ackMaxChars);
+
+    return {
+      acknowledged,
+      suppressed: acknowledged,
+      response: acknowledged ? undefined : response,
+    };
+  } catch (error) {
+    if (error instanceof Error && (error.name === "RuntimeSessionBusyError" || error.name === "RuntimeSessionQueuedError")) {
+      return {
+        acknowledged: false,
+        skipped: true,
+        suppressed: true,
+        response: "Skipped: session busy",
+      };
+    }
+
+    return {
+      acknowledged: false,
+      suppressed: false,
+      error: error instanceof Error ? error.message : "Unknown error",
+    };
+  }
+}

package/apps/server/src/backend/heartbeat/state.test.ts

@@ -0,0 +1,63 @@
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  test,
+} from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { patchHeartbeatRuntimeState, isActiveHeartbeatSession } from "./state";
+
+const testRoot = mkdtempSync(
+  path.join(tmpdir(), "agent-mockingbird-heartbeat-state-test-"),
+);
+const testDbPath = path.join(
+  testRoot,
+  "agent-mockingbird.heartbeat-state.test.db",
+);
+const testConfigPath = path.join(
+  testRoot,
+  "agent-mockingbird.heartbeat-state.config.json",
+);
+const testWorkspacePath = path.join(testRoot, "workspace");
+
+process.env.NODE_ENV = "test";
+process.env.AGENT_MOCKINGBIRD_DB_PATH = testDbPath;
+process.env.AGENT_MOCKINGBIRD_CONFIG_PATH = testConfigPath;
+process.env.AGENT_MOCKINGBIRD_MEMORY_WORKSPACE_DIR = testWorkspacePath;
+process.env.AGENT_MOCKINGBIRD_MEMORY_ENABLED = "false";
+
+let resetDatabaseToDefaults: () => unknown;
+
+beforeAll(async () => {
+  await import("../db/migrate");
+  ({ resetDatabaseToDefaults } = await import("../db/repository"));
+});
+
+beforeEach(() => {
+  resetDatabaseToDefaults();
+});
+
+describe("heartbeat state helpers", () => {
+  test("identifies the active heartbeat session from runtime state", () => {
+    expect(isActiveHeartbeatSession("session-heartbeat")).toBe(false);
+
+    patchHeartbeatRuntimeState({
+      sessionId: "session-heartbeat",
+      backgroundRunId: "bg-heartbeat-1",
+      parentSessionId: "main",
+      externalSessionId: "ext-heartbeat-1",
+    });
+
+    expect(isActiveHeartbeatSession("session-heartbeat")).toBe(true);
+    expect(isActiveHeartbeatSession("other-session")).toBe(false);
+  });
+});
+
+afterAll(() => {
+  rmSync(testRoot, { recursive: true, force: true });
+});

package/apps/server/src/backend/heartbeat/state.ts

@@ -0,0 +1,167 @@
+import type { HeartbeatLastResult, HeartbeatRuntimeState } from "./types";
+import { sqlite } from "../db/client";
+
+interface HeartbeatRuntimeStateRow {
+  id: string;
+  session_id: string | null;
+  background_run_id: string | null;
+  parent_session_id: string | null;
+  external_session_id: string | null;
+  running: number;
+  last_run_at: number | null;
+  last_result: HeartbeatLastResult;
+  last_response: string | null;
+  last_error: string | null;
+  updated_at: number;
+}
+
+const STATE_ID = "default";
+
+function nowMs() {
+  return Date.now();
+}
+
+function toIso(value: number | null) {
+  return value == null ? null : new Date(value).toISOString();
+}
+
+export function ensureHeartbeatStateTable() {
+  sqlite.run(`
+    CREATE TABLE IF NOT EXISTS heartbeat_runtime_state (
+      id TEXT PRIMARY KEY,
+      session_id TEXT,
+      background_run_id TEXT,
+      parent_session_id TEXT,
+      external_session_id TEXT,
+      running INTEGER NOT NULL DEFAULT 0,
+      last_run_at INTEGER,
+      last_result TEXT NOT NULL DEFAULT 'idle',
+      last_response TEXT,
+      last_error TEXT,
+      updated_at INTEGER NOT NULL
+    );
+  `);
+  const columns = sqlite
+    .query("PRAGMA table_info(heartbeat_runtime_state)")
+    .all() as Array<{ name: string }>;
+  const columnNames = new Set(columns.map(column => column.name));
+  if (!columnNames.has("background_run_id")) {
+    sqlite.run("ALTER TABLE heartbeat_runtime_state ADD COLUMN background_run_id TEXT");
+  }
+  if (!columnNames.has("parent_session_id")) {
+    sqlite.run("ALTER TABLE heartbeat_runtime_state ADD COLUMN parent_session_id TEXT");
+  }
+  if (!columnNames.has("external_session_id")) {
+    sqlite.run("ALTER TABLE heartbeat_runtime_state ADD COLUMN external_session_id TEXT");
+  }
+}
+
+function rowToState(row: HeartbeatRuntimeStateRow | null): HeartbeatRuntimeState {
+  if (!row) {
+    return {
+      sessionId: null,
+      backgroundRunId: null,
+      parentSessionId: null,
+      externalSessionId: null,
+      running: false,
+      lastRunAt: null,
+      lastResult: "idle",
+      lastResponse: null,
+      lastError: null,
+      updatedAt: new Date(0).toISOString(),
+    };
+  }
+
+  return {
+    sessionId: row.session_id,
+    backgroundRunId: row.background_run_id,
+    parentSessionId: row.parent_session_id,
+    externalSessionId: row.external_session_id,
+    running: row.running === 1,
+    lastRunAt: toIso(row.last_run_at),
+    lastResult: row.last_result,
+    lastResponse: row.last_response,
+    lastError: row.last_error,
+    updatedAt: new Date(row.updated_at).toISOString(),
+  };
+}
+
+export function getHeartbeatRuntimeState(): HeartbeatRuntimeState {
+  ensureHeartbeatStateTable();
+  const row = sqlite
+    .query(
+      `
+      SELECT
+        id, session_id, background_run_id, parent_session_id, external_session_id,
+        running, last_run_at, last_result, last_response, last_error, updated_at
+      FROM heartbeat_runtime_state
+      WHERE id = ?1
+      LIMIT 1
+    `,
+    )
+    .get(STATE_ID) as HeartbeatRuntimeStateRow | null;
+  return rowToState(row);
+}
+
+export function getReservedHeartbeatSessionId(): string | null {
+  return getHeartbeatRuntimeState().sessionId;
+}
+
+export function isActiveHeartbeatSession(sessionId: string): boolean {
+  const normalizedSessionId = sessionId.trim();
+  if (!normalizedSessionId) return false;
+  return getReservedHeartbeatSessionId() === normalizedSessionId;
+}
+
+export function patchHeartbeatRuntimeState(
+  patch: Partial<{
+    sessionId: string | null;
+    backgroundRunId: string | null;
+    parentSessionId: string | null;
+    externalSessionId: string | null;
+    running: boolean;
+    lastRunAt: number | null;
+    lastResult: HeartbeatLastResult;
+    lastResponse: string | null;
+    lastError: string | null;
+  }>,
+) {
+  ensureHeartbeatStateTable();
+  const existing = getHeartbeatRuntimeState();
+  const updatedAt = nowMs();
+  sqlite
+    .query(
+      `
+      INSERT INTO heartbeat_runtime_state (
+        id, session_id, background_run_id, parent_session_id, external_session_id,
+        running, last_run_at, last_result, last_response, last_error, updated_at
+      )
+      VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11)
+      ON CONFLICT(id) DO UPDATE SET
+        session_id = excluded.session_id,
+        background_run_id = excluded.background_run_id,
+        parent_session_id = excluded.parent_session_id,
+        external_session_id = excluded.external_session_id,
+        running = excluded.running,
+        last_run_at = excluded.last_run_at,
+        last_result = excluded.last_result,
+        last_response = excluded.last_response,
+        last_error = excluded.last_error,
+        updated_at = excluded.updated_at
+    `,
+    )
+    .run(
+      STATE_ID,
+      patch.sessionId !== undefined ? patch.sessionId : existing.sessionId,
+      patch.backgroundRunId !== undefined ? patch.backgroundRunId : existing.backgroundRunId,
+      patch.parentSessionId !== undefined ? patch.parentSessionId : existing.parentSessionId,
+      patch.externalSessionId !== undefined ? patch.externalSessionId : existing.externalSessionId,
+      (patch.running !== undefined ? patch.running : existing.running) ? 1 : 0,
+      patch.lastRunAt !== undefined ? patch.lastRunAt : existing.lastRunAt ? Date.parse(existing.lastRunAt) : null,
+      patch.lastResult !== undefined ? patch.lastResult : existing.lastResult,
+      patch.lastResponse !== undefined ? patch.lastResponse : existing.lastResponse,
+      patch.lastError !== undefined ? patch.lastError : existing.lastError,
+      updatedAt,
+    );
+  return getHeartbeatRuntimeState();
+}

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

@@ -0,0 +1,54 @@
+export interface HeartbeatConfig {
+  enabled: boolean;
+  interval: string;
+  activeHours?: {
+    start: string;
+    end: string;
+    timezone: string;
+  } | null;
+  prompt: string;
+  ackMaxChars: number;
+}
+
+export interface HeartbeatRuntimeConfig extends HeartbeatConfig {
+  agentId: string;
+  model: string;
+}
+
+export interface HeartbeatContext {
+  agentId: string;
+  sessionId: string;
+  scheduledFor: string;
+  now: string;
+  lastHeartbeat?: string;
+}
+
+export interface HeartbeatResult {
+  acknowledged: boolean;
+  skipped?: boolean;
+  suppressed: boolean;
+  response?: string;
+  error?: string;
+}
+
+export type HeartbeatLastResult = "idle" | "acknowledged" | "attention" | "skipped" | "error";
+
+export interface HeartbeatRuntimeState {
+  sessionId: string | null;
+  backgroundRunId: string | null;
+  parentSessionId: string | null;
+  externalSessionId: string | null;
+  running: boolean;
+  lastRunAt: string | null;
+  lastResult: HeartbeatLastResult;
+  lastResponse: string | null;
+  lastError: string | null;
+  updatedAt: string;
+}
+
+export interface HeartbeatStatus {
+  config: HeartbeatRuntimeConfig;
+  state: HeartbeatRuntimeState;
+  sessionTitle: string | null;
+  nextDueAt: string | null;
+}

package/apps/server/src/backend/http/boundedQueue.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test } from "bun:test";
+
+import { createBoundedQueue } from "./boundedQueue";
+
+describe("createBoundedQueue", () => {
+  test("overflows when the writer stays blocked", async () => {
+    let overflowed = false;
+    const queue = createBoundedQueue<string>({
+      maxSize: 2,
+      drainDelayMs: 5,
+      tryWrite: () => false,
+      onOverflow: () => {
+        overflowed = true;
+      },
+    });
+
+    expect(queue.enqueue("a")).toBe(true);
+    expect(queue.enqueue("b")).toBe(true);
+    expect(queue.enqueue("c")).toBe(false);
+    expect(overflowed).toBe(true);
+  });
+
+  test("drains queued frames once the writer becomes writable", async () => {
+    const written: string[] = [];
+    let writable = false;
+    const queue = createBoundedQueue<string>({
+      maxSize: 4,
+      drainDelayMs: 5,
+      tryWrite: (value) => {
+        if (!writable) return false;
+        written.push(value);
+        return true;
+      },
+      onOverflow: () => {
+        throw new Error("queue should not overflow");
+      },
+    });
+
+    queue.enqueue("first");
+    queue.enqueue("second");
+    expect(queue.size()).toBe(2);
+
+    writable = true;
+    await Bun.sleep(20);
+
+    expect(written).toEqual(["first", "second"]);
+    expect(queue.size()).toBe(0);
+  });
+});