agent-mockingbird 0.0.1

package/apps/server/src/backend/cron/storage.ts

@@ -0,0 +1,92 @@
+import { sqlite } from "../db/client";
+
+function tableHasColumn(tableName: string, columnName: string): boolean {
+  const columns = sqlite.query(`PRAGMA table_info(${tableName})`).all() as Array<{ name?: unknown }>;
+  return columns.some(column => column.name === columnName);
+}
+
+export function ensureCronTables() {
+  sqlite.exec(`
+    CREATE TABLE IF NOT EXISTS cron_job_definitions (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      thread_session_id TEXT,
+      enabled INTEGER NOT NULL DEFAULT 1,
+      schedule_kind TEXT NOT NULL CHECK (schedule_kind IN ('at', 'every', 'cron')),
+      schedule_expr TEXT,
+      every_ms INTEGER,
+      at_iso TEXT,
+      timezone TEXT,
+      run_mode TEXT NOT NULL CHECK (run_mode IN ('background', 'conditional_agent', 'agent')),
+      handler_key TEXT,
+      condition_module_path TEXT,
+      condition_description TEXT,
+      agent_prompt_template TEXT,
+      agent_model_override TEXT,
+      max_attempts INTEGER NOT NULL DEFAULT 3,
+      retry_backoff_ms INTEGER NOT NULL DEFAULT 30000,
+      payload_json TEXT NOT NULL DEFAULT '{}',
+      last_enqueued_for INTEGER,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS cron_job_definitions_enabled_idx
+      ON cron_job_definitions(enabled, schedule_kind);
+
+    CREATE TABLE IF NOT EXISTS cron_job_instances (
+      id TEXT PRIMARY KEY,
+      job_definition_id TEXT NOT NULL REFERENCES cron_job_definitions(id) ON DELETE CASCADE,
+      scheduled_for INTEGER NOT NULL,
+      state TEXT NOT NULL CHECK (state IN ('queued', 'leased', 'running', 'completed', 'failed', 'dead')),
+      attempt INTEGER NOT NULL DEFAULT 0,
+      next_attempt_at INTEGER,
+      lease_owner TEXT,
+      lease_expires_at INTEGER,
+      last_heartbeat_at INTEGER,
+      result_summary TEXT,
+      error_json TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      UNIQUE(job_definition_id, scheduled_for)
+    );
+
+    CREATE INDEX IF NOT EXISTS cron_job_instances_ready_idx
+      ON cron_job_instances(state, next_attempt_at, scheduled_for);
+    CREATE INDEX IF NOT EXISTS cron_job_instances_job_idx
+      ON cron_job_instances(job_definition_id, created_at DESC);
+
+    CREATE TABLE IF NOT EXISTS cron_job_steps (
+      id TEXT PRIMARY KEY,
+      job_instance_id TEXT NOT NULL REFERENCES cron_job_instances(id) ON DELETE CASCADE,
+      step_kind TEXT NOT NULL CHECK (step_kind IN ('background', 'conditional_agent', 'agent')),
+      status TEXT NOT NULL CHECK (status IN ('pending', 'running', 'completed', 'failed', 'skipped')),
+      input_json TEXT,
+      output_json TEXT,
+      error_json TEXT,
+      started_at INTEGER,
+      finished_at INTEGER,
+      created_at INTEGER NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS cron_job_steps_instance_idx
+      ON cron_job_steps(job_instance_id, created_at ASC);
+  `);
+
+  if (!tableHasColumn("cron_job_definitions", "condition_module_path")) {
+    sqlite.exec("ALTER TABLE cron_job_definitions ADD COLUMN condition_module_path TEXT");
+  }
+  if (!tableHasColumn("cron_job_definitions", "condition_description")) {
+    sqlite.exec("ALTER TABLE cron_job_definitions ADD COLUMN condition_description TEXT");
+  }
+  if (!tableHasColumn("cron_job_definitions", "thread_session_id")) {
+    sqlite.exec("ALTER TABLE cron_job_definitions ADD COLUMN thread_session_id TEXT");
+  }
+}
+
+export function clearCronTables() {
+  ensureCronTables();
+  sqlite.query("DELETE FROM cron_job_steps").run();
+  sqlite.query("DELETE FROM cron_job_instances").run();
+  sqlite.query("DELETE FROM cron_job_definitions").run();
+}

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

@@ -0,0 +1,138 @@
+export type CronScheduleKind = "at" | "every" | "cron";
+export type CronRunMode = "background" | "conditional_agent" | "agent";
+
+export type CronJobState = "queued" | "leased" | "running" | "completed" | "failed" | "dead";
+export type CronStepStatus = "pending" | "running" | "completed" | "failed" | "skipped";
+export type CronStepKind = "background" | "conditional_agent" | "agent";
+
+export interface CronJobDefinition {
+  id: string;
+  name: string;
+  threadSessionId: string | null;
+  enabled: boolean;
+  scheduleKind: CronScheduleKind;
+  scheduleExpr: string | null;
+  everyMs: number | null;
+  atIso: string | null;
+  timezone: string | null;
+  runMode: CronRunMode;
+  conditionModulePath: string | null;
+  conditionDescription: string | null;
+  agentPromptTemplate: string | null;
+  agentModelOverride: string | null;
+  maxAttempts: number;
+  retryBackoffMs: number;
+  payload: Record<string, unknown>;
+  lastEnqueuedFor: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CronJobInstance {
+  id: string;
+  jobDefinitionId: string;
+  scheduledFor: string;
+  agentInvoked: boolean;
+  state: CronJobState;
+  attempt: number;
+  nextAttemptAt: string | null;
+  leaseOwner: string | null;
+  leaseExpiresAt: string | null;
+  lastHeartbeatAt: string | null;
+  resultSummary: string | null;
+  error: unknown;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CronJobStep {
+  id: string;
+  jobInstanceId: string;
+  stepKind: CronStepKind;
+  status: CronStepStatus;
+  input: unknown;
+  output: unknown;
+  error: unknown;
+  startedAt: string | null;
+  finishedAt: string | null;
+  createdAt: string;
+}
+
+export interface CronHealthSnapshot {
+  enabled: boolean;
+  schedulerPollMs: number;
+  workerPollMs: number;
+  leaseMs: number;
+  jobs: {
+    total: number;
+    enabled: number;
+  };
+  instances: {
+    queued: number;
+    leased: number;
+    running: number;
+    completed: number;
+    failed: number;
+    dead: number;
+  };
+}
+
+export interface CronJobCreateInput {
+  id?: string;
+  name: string;
+  enabled?: boolean;
+  scheduleKind: CronScheduleKind;
+  scheduleExpr?: string | null;
+  everyMs?: number | null;
+  atIso?: string | null;
+  timezone?: string | null;
+  runMode: CronRunMode;
+  conditionModulePath?: string | null;
+  conditionDescription?: string | null;
+  agentPromptTemplate?: string | null;
+  agentModelOverride?: string | null;
+  maxAttempts?: number;
+  retryBackoffMs?: number;
+  payload?: Record<string, unknown>;
+}
+
+export interface CronJobPatchInput {
+  name?: string;
+  enabled?: boolean;
+  scheduleKind?: CronScheduleKind;
+  scheduleExpr?: string | null;
+  everyMs?: number | null;
+  atIso?: string | null;
+  timezone?: string | null;
+  runMode?: CronRunMode;
+  conditionModulePath?: string | null;
+  conditionDescription?: string | null;
+  agentPromptTemplate?: string | null;
+  agentModelOverride?: string | null;
+  maxAttempts?: number;
+  retryBackoffMs?: number;
+  payload?: Record<string, unknown>;
+}
+
+export interface CronHandlerResult {
+  status: "ok" | "error";
+  summary?: string;
+  data?: unknown;
+  invokeAgent?: {
+    shouldInvoke: boolean;
+    prompt?: string;
+    context?: Record<string, unknown>;
+    severity?: "info" | "warn" | "critical";
+  };
+}
+
+export interface CronConditionalModuleContext {
+  nowMs: number;
+  payload: Record<string, unknown>;
+  job: CronJobDefinition;
+  instance: CronJobInstance;
+}
+
+export type CronConditionalModule = (
+  ctx: CronConditionalModuleContext,
+) => Promise<CronHandlerResult> | CronHandlerResult;

package/apps/server/src/backend/cron/utils.ts

@@ -0,0 +1,351 @@
+import { CronTime, validateCronExpression } from "cron";
+import { realpathSync, statSync } from "node:fs";
+import { extname, relative, resolve } from "node:path";
+
+import type {
+  CronHandlerResult,
+  CronJobCreateInput,
+  CronJobDefinition,
+  CronJobInstance,
+  CronJobPatchInput,
+  CronRunMode,
+  CronScheduleKind,
+} from "./types";
+import { getConfigSnapshot } from "../config/service";
+import { createLogger } from "../logging/logger";
+
+const CONDITION_MODULE_EXTENSIONS = new Set([".ts", ".js", ".mjs", ".cjs"]);
+const logger = createLogger("cron");
+
+export function nowMs() {
+  return Date.now();
+}
+
+export function toIso(ms: number | null | undefined): string | null {
+  if (typeof ms !== "number" || !Number.isFinite(ms)) return null;
+  return new Date(ms).toISOString();
+}
+
+export function parseJson(value: string | null): unknown {
+  if (!value) return null;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+
+export function normalizePayload(
+  input: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  return input && typeof input === "object" && !Array.isArray(input)
+    ? input
+    : {};
+}
+
+export function normalizeConditionalModuleResult(
+  value: unknown,
+): CronHandlerResult {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("conditional module must return an object");
+  }
+  const result = value as Record<string, unknown>;
+  if (result.status !== "ok" && result.status !== "error") {
+    throw new Error("conditional module result.status must be 'ok' or 'error'");
+  }
+  return value as CronHandlerResult;
+}
+
+function readLegacyHandlerKey(input: { handlerKey?: unknown }): string | null {
+  return typeof input.handlerKey === "string" ? input.handlerKey.trim() || null : null;
+}
+
+export function validateSchedule(input: {
+  scheduleKind: CronScheduleKind;
+  scheduleExpr: string | null;
+  everyMs: number | null;
+  atIso: string | null;
+}) {
+  if (input.scheduleKind === "at") {
+    if (!input.atIso) throw new Error("scheduleKind=at requires atIso");
+    const parsedAt = Date.parse(input.atIso);
+    if (!Number.isFinite(parsedAt)) {
+      throw new Error("atIso must be a valid ISO timestamp");
+    }
+    return;
+  }
+
+  if (input.scheduleKind === "every") {
+    if (
+      typeof input.everyMs !== "number" ||
+      !Number.isFinite(input.everyMs) ||
+      input.everyMs < 1_000
+    ) {
+      throw new Error("scheduleKind=every requires everyMs >= 1000");
+    }
+    return;
+  }
+
+  const expr = input.scheduleExpr?.trim();
+  if (!expr) throw new Error("scheduleKind=cron requires scheduleExpr");
+  const valid = validateCronExpression(expr);
+  if (!valid.valid) {
+    throw new Error(`invalid cron expression: ${valid.error?.message ?? "parse failed"}`);
+  }
+}
+
+export function validateMode(input: {
+  runMode: CronRunMode;
+  conditionModulePath: string | null;
+  conditionDescription: string | null;
+  agentPromptTemplate: string | null;
+  handlerKey?: string | null;
+}) {
+  if (input.handlerKey?.trim()) {
+    throw new Error("handlerKey is no longer supported");
+  }
+
+  if (input.runMode === "background") {
+    if (!input.conditionModulePath?.trim()) {
+      throw new Error("runMode=background requires conditionModulePath");
+    }
+    if (input.agentPromptTemplate?.trim()) {
+      throw new Error("runMode=background does not allow agentPromptTemplate");
+    }
+    return;
+  }
+
+  if (input.runMode === "agent") {
+    if (input.conditionModulePath) {
+      throw new Error("runMode=agent does not allow conditionModulePath");
+    }
+    if (input.conditionDescription) {
+      throw new Error("runMode=agent does not allow conditionDescription");
+    }
+    if (!input.agentPromptTemplate?.trim()) {
+      throw new Error("runMode=agent requires agentPromptTemplate");
+    }
+    return;
+  }
+
+  if (!input.conditionModulePath?.trim()) {
+    throw new Error("runMode=conditional_agent requires conditionModulePath");
+  }
+}
+
+export function computeBackoffMs(base: number, attempt: number): number {
+  const cappedAttempt = Math.max(1, Math.min(10, attempt));
+  return Math.min(
+    base * 2 ** (cappedAttempt - 1),
+    getConfigSnapshot().config.runtime.cron.retryBackoffCapMs,
+  );
+}
+
+export function renderTemplate(
+  template: string,
+  ctx: Record<string, unknown>,
+): string {
+  return template.replace(/\{\{\s*([a-zA-Z0-9_.-]+)\s*\}\}/g, (_full, key: string) => {
+    const raw = ctx[key];
+    if (raw === undefined || raw === null) return "";
+    if (typeof raw === "string") return raw;
+    if (typeof raw === "number" || typeof raw === "boolean") return String(raw);
+    return JSON.stringify(raw);
+  });
+}
+
+export function createUniqueId(prefix: string): string {
+  return `${prefix}-${crypto.randomUUID().slice(0, 8)}`;
+}
+
+export function definitionPayloadContext(
+  definition: CronJobDefinition,
+  extra?: Record<string, unknown>,
+) {
+  return {
+    ...definition.payload,
+    jobId: definition.id,
+    jobName: definition.name,
+    ...(extra ?? {}),
+  };
+}
+
+export function buildNormalizedJobInput(
+  input: CronJobCreateInput | (CronJobPatchInput & { id?: string }),
+  defaults?: CronJobDefinition,
+): {
+  id: string;
+  name: string;
+  enabled: boolean;
+  scheduleKind: CronScheduleKind;
+  scheduleExpr: string | null;
+  everyMs: number | null;
+  atIso: string | null;
+  timezone: string | null;
+  runMode: CronRunMode;
+  handlerKey: string | null;
+  conditionModulePath: string | null;
+  conditionDescription: string | null;
+  agentPromptTemplate: string | null;
+  agentModelOverride: string | null;
+  maxAttempts: number;
+  retryBackoffMs: number;
+  payload: Record<string, unknown>;
+} {
+  return {
+    id: input.id?.trim() ? input.id.trim() : defaults?.id ?? createUniqueId("cron"),
+    name: input.name?.trim() ?? defaults?.name ?? "",
+    enabled: input.enabled ?? defaults?.enabled ?? true,
+    scheduleKind: (input.scheduleKind ?? defaults?.scheduleKind)!,
+    scheduleExpr:
+      input.scheduleExpr !== undefined
+        ? input.scheduleExpr?.trim() ?? null
+        : defaults?.scheduleExpr ?? null,
+    everyMs: input.everyMs !== undefined ? input.everyMs : defaults?.everyMs ?? null,
+    atIso: input.atIso !== undefined ? input.atIso?.trim() ?? null : defaults?.atIso ?? null,
+    timezone:
+      input.timezone !== undefined ? input.timezone?.trim() ?? null : defaults?.timezone ?? null,
+    runMode: (input.runMode ?? defaults?.runMode)!,
+    handlerKey: readLegacyHandlerKey(input as { handlerKey?: unknown }),
+    conditionModulePath:
+      input.conditionModulePath !== undefined
+        ? input.conditionModulePath?.trim() ?? null
+        : defaults?.conditionModulePath ?? null,
+    conditionDescription:
+      input.conditionDescription !== undefined
+        ? input.conditionDescription?.trim() ?? null
+        : defaults?.conditionDescription ?? null,
+    agentPromptTemplate:
+      input.agentPromptTemplate !== undefined
+        ? input.agentPromptTemplate?.trim() ?? null
+        : defaults?.agentPromptTemplate ?? null,
+    agentModelOverride:
+      input.agentModelOverride !== undefined
+        ? input.agentModelOverride?.trim() ?? null
+        : defaults?.agentModelOverride ?? null,
+    maxAttempts: Math.max(
+      1,
+      input.maxAttempts ??
+        defaults?.maxAttempts ??
+        getConfigSnapshot().config.runtime.cron.defaultMaxAttempts,
+    ),
+    retryBackoffMs: Math.max(
+      1_000,
+      input.retryBackoffMs ??
+        defaults?.retryBackoffMs ??
+        getConfigSnapshot().config.runtime.cron.defaultRetryBackoffMs,
+    ),
+    payload:
+      input.payload !== undefined
+        ? normalizePayload(input.payload)
+        : defaults?.payload ?? {},
+  };
+}
+
+function resolveWorkspaceRootPath(): string {
+  const configured = getConfigSnapshot().config.runtime.opencode.directory?.trim();
+  return resolve(configured || process.cwd());
+}
+
+export function resolveConditionModuleAbsolutePath(conditionModulePath: string): string {
+  const extension = extname(conditionModulePath).toLowerCase();
+  if (!CONDITION_MODULE_EXTENSIONS.has(extension)) {
+    throw new Error("conditionModulePath must target a .ts, .js, .mjs, or .cjs file");
+  }
+
+  const workspaceRoot = realpathSync(resolveWorkspaceRootPath());
+  const target = resolve(workspaceRoot, conditionModulePath);
+  let resolvedTarget: string;
+  try {
+    resolvedTarget = realpathSync(target);
+  } catch {
+    throw new Error("conditionModulePath must reference an existing file under the runtime workspace directory");
+  }
+  const relativePath = relative(workspaceRoot, resolvedTarget);
+  if (!relativePath || relativePath === ".") {
+    throw new Error("conditionModulePath must target a file under the runtime workspace directory");
+  }
+  if (relativePath.startsWith("..")) {
+    throw new Error("conditionModulePath escapes the runtime workspace directory");
+  }
+  if (!statSync(resolvedTarget).isFile()) {
+    throw new Error("conditionModulePath must reference a regular file");
+  }
+  return resolvedTarget;
+}
+
+export function computeDueTimesForDefinition(
+  row: {
+    schedule_kind: CronScheduleKind;
+    schedule_expr: string | null;
+    every_ms: number | null;
+    at_iso: string | null;
+    timezone: string | null;
+    last_enqueued_for: number | null;
+    created_at: number;
+  },
+  now: number,
+  maxPerTick: number,
+): number[] {
+  const due: number[] = [];
+  const lastEnqueued = row.last_enqueued_for ?? null;
+
+  if (row.schedule_kind === "at") {
+    if (!row.at_iso) return due;
+    const atMs = Date.parse(row.at_iso);
+    if (!Number.isFinite(atMs)) return due;
+    if (atMs <= now && (lastEnqueued === null || lastEnqueued < atMs)) {
+      due.push(atMs);
+    }
+    return due;
+  }
+
+  if (row.schedule_kind === "every") {
+    const everyMs = row.every_ms ?? 0;
+    if (!Number.isFinite(everyMs) || everyMs <= 0) return due;
+    let cursor = lastEnqueued ?? row.created_at;
+    for (let i = 0; i < maxPerTick; i += 1) {
+      const next = cursor + everyMs;
+      if (next > now) break;
+      due.push(next);
+      cursor = next;
+    }
+    return due;
+  }
+
+  const expr = row.schedule_expr?.trim();
+  if (!expr) return due;
+  try {
+    const cronTime = new CronTime(expr, row.timezone ?? undefined);
+    let cursor = lastEnqueued ?? row.created_at - 1_000;
+    for (let i = 0; i < maxPerTick; i += 1) {
+      const nextDate = cronTime.getNextDateFrom(new Date(cursor));
+      const nextMs = nextDate.toMillis();
+      if (!Number.isFinite(nextMs)) break;
+      if (nextMs > now) break;
+      if (nextMs <= cursor) break;
+      due.push(nextMs);
+      cursor = nextMs + 1_000;
+    }
+  } catch {
+    logger.warn("Ignoring invalid cron expression during scheduling", {
+      scheduleExpr: expr,
+      timezone: row.timezone,
+    });
+  }
+  return due;
+}
+
+export function buildAgentPromptContext(
+  definition: CronJobDefinition,
+  instance: CronJobInstance,
+  context?: Record<string, unknown>,
+) {
+  return {
+    ...definitionPayloadContext(definition),
+    ...(context ?? {}),
+    threadSessionId: definition.threadSessionId,
+    instanceId: instance.id,
+    scheduledFor: instance.scheduledFor,
+  };
+}

package/apps/server/src/backend/db/client.ts

@@ -0,0 +1,20 @@
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import path from "node:path";
+
+import { env } from "../env";
+import { resolveDataPath } from "../paths";
+
+const resolvedDbPath = env.AGENT_MOCKINGBIRD_DB_PATH
+  ? path.resolve(env.AGENT_MOCKINGBIRD_DB_PATH)
+  : resolveDataPath("agent-mockingbird.db");
+
+mkdirSync(path.dirname(resolvedDbPath), { recursive: true });
+
+export const sqlite = new Database(resolvedDbPath);
+sqlite.exec("PRAGMA journal_mode=WAL;");
+sqlite.exec("PRAGMA synchronous=NORMAL;");
+sqlite.exec("PRAGMA busy_timeout=5000;");
+sqlite.exec("PRAGMA foreign_keys=ON;");
+
+export { resolvedDbPath };

package/apps/server/src/backend/db/migrate.ts

@@ -0,0 +1,40 @@
+import { drizzle } from "drizzle-orm/bun-sqlite";
+import { migrate } from "drizzle-orm/bun-sqlite/migrator";
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+import { resolvedDbPath, sqlite } from "./client";
+import * as schema from "./schema";
+import { getBinaryDir } from "../paths";
+
+function hasMigrationJournal(candidate: string) {
+  return existsSync(path.join(candidate, "meta", "_journal.json"));
+}
+
+function resolveMigrationsFolder() {
+  const candidates = [
+    path.resolve(process.cwd(), "drizzle"),
+    path.resolve(import.meta.dir, "../../../../../drizzle"),
+    path.resolve(path.dirname(process.execPath), "drizzle"),
+    path.resolve(getBinaryDir(), "drizzle"),
+  ];
+  for (const candidate of candidates) {
+    if (hasMigrationJournal(candidate)) {
+      return candidate;
+    }
+  }
+
+  throw new Error(
+    `SQLite migrations are missing meta/_journal.json. Checked: ${candidates.join(", ")}`,
+  );
+}
+
+const migrationsFolder = resolveMigrationsFolder();
+const migrationDb = drizzle({ client: sqlite, schema });
+
+console.log(`Running SQLite migrations from ${migrationsFolder}`);
+console.log(`Target database: ${resolvedDbPath}`);
+
+migrate(migrationDb, { migrationsFolder });
+
+console.log("Migrations complete");