@johpaz/hive-sdk 0.2.0 → 0.3.1

package/packages/core/src/hooks/index.ts

@@ -0,0 +1,203 @@
+/**
+ * Hooks — engancharse al ciclo de vida sin bifurcar el SDK.
+ *
+ * `HooksConfigSchema` (`config/loader.ts`) declaraba 14 hooks y **ninguno se
+ * invocaba**: era un esquema sin implementación. Quien lo encontrara asumiría
+ * que funciona.
+ *
+ * Acá se implementan, con dos formas y una decisión de diseño detrás:
+ *
+ *  - **Callbacks en proceso** (`registerHook`) — tipados, sin costo de arranque,
+ *    y pueden **devolver una decisión**: `beforeToolCall` puede impedir que una
+ *    tool se ejecute. Es el primitivo, porque quien consume el SDK ya está en el
+ *    mismo proceso.
+ *  - **Scripts externos** (`hooks.scripts` en la configuración) — para quien no
+ *    escribe TypeScript. Se montan encima del primitivo: cada script declarado
+ *    se registra como un callback que lo ejecuta. Cuestan un `Bun.spawn` por
+ *    invocación, así que conviene reservarlos para lo que no ocurre en cada
+ *    tool call.
+ *
+ * Sólo están los hooks que tienen un uso claro. Los otros nueve del esquema
+ * original se dejaron fuera a propósito: cada hook es una promesa que después
+ * hay que sostener, y uno que nadie usa es superficie que envejece mal.
+ */
+
+import { logger } from "../utils/logger.ts";
+import { loadConfig } from "../config/loader.ts";
+
+const log = logger.child("hooks");
+
+/** Lo que recibe un hook de tool. */
+export interface ToolCallContext {
+  toolName: string;
+  args: Record<string, unknown>;
+  agentId?: string;
+  userId?: string;
+  threadId?: string;
+}
+
+export interface ToolResultContext extends ToolCallContext {
+  result: unknown;
+  ok: boolean;
+  durationMs: number;
+}
+
+export interface CompactionContext {
+  threadId: string;
+  messageCount: number;
+  totalTokens: number;
+}
+
+export interface SessionContext {
+  threadId: string;
+  userId?: string;
+  channel?: string;
+}
+
+/**
+ * Lo que puede devolver `beforeToolCall`.
+ *
+ * `void` o `undefined` = seguir adelante. Devolver `{ block }` impide la
+ * ejecución y el motivo le llega al modelo como resultado de la tool, para que
+ * sepa por qué no se hizo en vez de reintentar a ciegas.
+ */
+export type BeforeToolCallResult = void | undefined | { block: true; reason: string };
+
+export interface HookMap {
+  beforeToolCall: (ctx: ToolCallContext) => BeforeToolCallResult | Promise<BeforeToolCallResult>;
+  afterToolCall: (ctx: ToolResultContext) => void | Promise<void>;
+  beforeCompaction: (ctx: CompactionContext) => void | Promise<void>;
+  sessionStart: (ctx: SessionContext) => void | Promise<void>;
+  sessionEnd: (ctx: SessionContext) => void | Promise<void>;
+}
+
+export type HookName = keyof HookMap;
+
+const registry: { [K in HookName]: Array<HookMap[K]> } = {
+  beforeToolCall: [],
+  afterToolCall: [],
+  beforeCompaction: [],
+  sessionStart: [],
+  sessionEnd: [],
+};
+
+/**
+ * Registra un hook. Devuelve la función para quitarlo.
+ *
+ * Se pueden registrar varios del mismo tipo: corren en orden de registro.
+ */
+export function registerHook<K extends HookName>(name: K, fn: HookMap[K]): () => void {
+  registry[name].push(fn);
+  return () => {
+    const i = registry[name].indexOf(fn);
+    if (i >= 0) registry[name].splice(i, 1);
+  };
+}
+
+/** Quita todos los hooks. Pensado para tests. */
+export function clearHooks(name?: HookName): void {
+  if (name) registry[name] = [];
+  else for (const k of Object.keys(registry) as HookName[]) registry[k] = [];
+}
+
+export function hasHooks(name: HookName): boolean {
+  return registry[name].length > 0;
+}
+
+/**
+ * Corre los `beforeToolCall` y devuelve el motivo del bloqueo, si alguno objeta.
+ *
+ * El primero que bloquea gana: no tiene sentido seguir preguntando cuando ya
+ * hay una negativa. Un hook que lanza **no** bloquea la ejecución —un error en
+ * el observador no debería impedir el trabajo— pero se registra.
+ */
+export async function runBeforeToolCall(ctx: ToolCallContext): Promise<string | null> {
+  for (const fn of registry.beforeToolCall) {
+    try {
+      const r = await fn(ctx);
+      if (r && typeof r === "object" && r.block) return r.reason;
+    } catch (err) {
+      log.warn(`beforeToolCall falló para ${ctx.toolName}: ${(err as Error).message}`);
+    }
+  }
+  return null;
+}
+
+/** Corre los hooks de observación. Nunca lanza: son observadores. */
+async function runObservers<K extends "afterToolCall" | "beforeCompaction" | "sessionStart" | "sessionEnd">(
+  name: K,
+  ctx: Parameters<HookMap[K]>[0],
+): Promise<void> {
+  for (const fn of registry[name]) {
+    try {
+      await (fn as (c: unknown) => unknown)(ctx);
+    } catch (err) {
+      log.warn(`${name} falló: ${(err as Error).message}`);
+    }
+  }
+}
+
+export const runAfterToolCall = (ctx: ToolResultContext) => runObservers("afterToolCall", ctx);
+export const runBeforeCompaction = (ctx: CompactionContext) => runObservers("beforeCompaction", ctx);
+export const runSessionStart = (ctx: SessionContext) => runObservers("sessionStart", ctx);
+export const runSessionEnd = (ctx: SessionContext) => runObservers("sessionEnd", ctx);
+
+// ─── Scripts declarados en la configuración ──────────────────────────────────
+
+/** Nombres del esquema de config → hooks implementados. */
+const SCRIPT_MAP: Record<string, HookName> = {
+  before_tool_call: "beforeToolCall",
+  after_tool_call: "afterToolCall",
+  before_compaction: "beforeCompaction",
+  session_start: "sessionStart",
+  session_end: "sessionEnd",
+};
+
+/**
+ * Ejecuta un script pasándole el contexto como JSON por stdin.
+ *
+ * Convención para `before_tool_call`: **salir con código distinto de 0 bloquea**
+ * la ejecución, y lo que el script escriba en stdout es el motivo que se le
+ * cuenta al modelo. Es el equivalente en procesos a devolver `{ block }`.
+ */
+async function runScript(path: string, ctx: unknown): Promise<{ blocked: boolean; reason: string }> {
+  const proc = Bun.spawn(["bun", path], { stdin: "pipe", stdout: "pipe", stderr: "pipe" });
+  proc.stdin.write(JSON.stringify(ctx));
+  proc.stdin.end();
+
+  const [salida, code] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+  return { blocked: code !== 0, reason: salida.trim() || `el hook ${path} salió con código ${code}` };
+}
+
+let scriptsCargados = false;
+
+/**
+ * Registra los scripts declarados en `hooks.scripts`.
+ *
+ * Es opt-in y explícito: ejecutar procesos externos no es algo que deba pasar
+ * por el solo hecho de importar el SDK. Idempotente.
+ */
+export function loadConfiguredHookScripts(): number {
+  if (scriptsCargados) return 0;
+  const scripts = loadConfig().hooks?.scripts;
+  if (!scripts) return 0;
+
+  let n = 0;
+  for (const [clave, hook] of Object.entries(SCRIPT_MAP)) {
+    const path = (scripts as Record<string, string | undefined>)[clave];
+    if (!path) continue;
+
+    if (hook === "beforeToolCall") {
+      registerHook("beforeToolCall", async (ctx) => {
+        const r = await runScript(path, ctx);
+        return r.blocked ? { block: true as const, reason: r.reason } : undefined;
+      });
+    } else {
+      registerHook(hook as "afterToolCall", async (ctx) => { await runScript(path, ctx); });
+    }
+    n++;
+    log.info(`hook ${clave} → ${path}`);
+  }
+  scriptsCargados = true;
+  return n;
+}

package/packages/core/src/images/index.ts

@@ -0,0 +1,161 @@
+/**
+ * Imágenes — redimensionar, convertir y medir, sin dependencias nativas.
+ *
+ * Usa `Bun.Image` (Bun 1.4), que es sharp integrado en el runtime: no hay que
+ * instalar nada ni compilar bindings. El SDK ya exige Bun ≥ 1.4, así que esto
+ * no agrega ningún requisito.
+ *
+ * Sirve para dos cosas distintas y conviene no confundirlas:
+ *
+ *  1. **Tools activables** para el agente (`tools/images/`) — recortar, convertir
+ *     de formato, leer dimensiones. Es una capacidad de producto.
+ *  2. **Normalizar lo que entra** — una foto de 4 MB que un usuario manda por
+ *     WhatsApp no tiene por qué viajar entera al modelo. Redimensionarla antes
+ *     cuesta una fracción de los tokens y no cambia lo que el modelo puede ver.
+ *
+ * Nota sobre `Bun.Image`: las transformaciones son **diferidas**. `metadata()`
+ * sobre una cadena sin materializar devuelve las dimensiones del origen, no las
+ * del resultado — hay que pedir los bytes y releerlos. `measureImage()` lo hace
+ * por vos cuando hace falta.
+ */
+
+import { logger } from "../utils/logger.ts";
+
+const log = logger.child("images");
+
+/** Los que `Bun.Image` sabe escribir. */
+export type ImageFormat = "jpeg" | "png" | "webp" | "avif" | "heic";
+
+export interface ImageMetadata {
+  width: number;
+  height: number;
+  format: string;
+}
+
+export interface TransformOptions {
+  /** Ancho máximo; la altura se ajusta manteniendo la proporción si no se da. */
+  width?: number;
+  height?: number;
+  format?: ImageFormat;
+  /** 1–100. Sólo lo respetan los formatos con pérdida. */
+  quality?: number;
+  /** Grados: 90, 180, 270. */
+  rotate?: number;
+  flip?: boolean;
+  flop?: boolean;
+}
+
+function bunImage(): any {
+  const I = (Bun as any).Image;
+  if (!I) {
+    throw new Error("Bun.Image no está disponible: se necesita Bun >= 1.4");
+  }
+  return I;
+}
+
+function toBytes(input: Uint8Array | ArrayBuffer | Buffer | string): Uint8Array {
+  if (typeof input === "string") return Uint8Array.from(Buffer.from(input, "base64"));
+  if (input instanceof Uint8Array) return input;
+  return new Uint8Array(input as ArrayBuffer);
+}
+
+/** Dimensiones y formato sin decodificar la imagen entera. */
+export async function measureImage(input: Uint8Array | ArrayBuffer | Buffer | string): Promise<ImageMetadata> {
+  const meta = await new (bunImage())(toBytes(input)).metadata();
+  return { width: meta.width, height: meta.height, format: meta.format };
+}
+
+/**
+ * Aplica las transformaciones y devuelve los bytes resultantes.
+ *
+ * Sin `format` conserva el de origen. Sin nada que hacer devuelve la entrada tal
+ * cual, para no recomprimir de gusto.
+ */
+export async function transformImage(
+  input: Uint8Array | ArrayBuffer | Buffer | string,
+  opts: TransformOptions,
+): Promise<{ bytes: Uint8Array; metadata: ImageMetadata }> {
+  const bytes = toBytes(input);
+  const hayQueHacer = opts.width || opts.height || opts.format || opts.rotate || opts.flip || opts.flop;
+  if (!hayQueHacer) return { bytes, metadata: await measureImage(bytes) };
+
+  let img = new (bunImage())(bytes);
+
+  if (opts.width || opts.height) img = img.resize(opts.width, opts.height);
+  if (opts.rotate) img = img.rotate(opts.rotate);
+  if (opts.flip) img = img.flip();
+  if (opts.flop) img = img.flop();
+
+  const formato = opts.format ?? ((await measureImage(bytes)).format as ImageFormat);
+  const args = opts.quality !== undefined ? [{ quality: opts.quality }] : [];
+  img = typeof img[formato] === "function" ? img[formato](...args) : img;
+
+  const salida: Uint8Array = await img.bytes();
+  // Se releen los bytes porque `metadata()` sobre la cadena diferida informa el
+  // origen, no el resultado.
+  return { bytes: salida, metadata: await measureImage(salida) };
+}
+
+export interface NormalizeOptions {
+  /** Lado mayor permitido. Por encima se reduce manteniendo la proporción. */
+  maxDimension?: number;
+  /** Formato de salida; `webp` pesa mucho menos que un JPEG equivalente. */
+  format?: ImageFormat;
+  quality?: number;
+}
+
+/** Por defecto: 1024 px de lado mayor y webp al 80 — el punto donde un modelo de visión deja de ganar detalle. */
+const NORMALIZE_DEFAULTS: Required<NormalizeOptions> = {
+  maxDimension: 1024,
+  format: "webp",
+  quality: 80,
+};
+
+export interface NormalizeResult {
+  bytes: Uint8Array;
+  metadata: ImageMetadata;
+  /** Bytes originales, para saber cuánto se ahorró. */
+  originalBytes: number;
+  /** true si hubo que tocarla; false si ya era chica. */
+  changed: boolean;
+}
+
+/**
+ * Deja una imagen entrante en un tamaño razonable para mandársela a un modelo.
+ *
+ * Una foto de teléfono son varios megabytes y unos cuantos miles de tokens; a
+ * 1024 px el modelo ve lo mismo por una fracción del costo. Si ya está por
+ * debajo del límite no se toca — recomprimir una imagen chica sólo la empeora.
+ */
+export async function normalizeForModel(
+  input: Uint8Array | ArrayBuffer | Buffer | string,
+  opts: NormalizeOptions = {},
+): Promise<NormalizeResult> {
+  const cfg = { ...NORMALIZE_DEFAULTS, ...opts };
+  const bytes = toBytes(input);
+  const meta = await measureImage(bytes);
+  const mayor = Math.max(meta.width, meta.height);
+
+  if (mayor <= cfg.maxDimension && meta.format === cfg.format) {
+    return { bytes, metadata: meta, originalBytes: bytes.length, changed: false };
+  }
+
+  const escala = mayor > cfg.maxDimension ? cfg.maxDimension / mayor : 1;
+  const { bytes: salida, metadata } = await transformImage(bytes, {
+    width: Math.round(meta.width * escala),
+    height: Math.round(meta.height * escala),
+    format: cfg.format,
+    quality: cfg.quality,
+  });
+
+  log.info(
+    `imagen normalizada: ${meta.width}x${meta.height} ${meta.format} (${bytes.length}b) → ` +
+    `${metadata.width}x${metadata.height} ${metadata.format} (${salida.length}b)`,
+  );
+  return { bytes: salida, metadata, originalBytes: bytes.length, changed: true };
+}
+
+/** true si este runtime puede procesar imágenes. */
+export function imagesSupported(): boolean {
+  return typeof (Bun as any).Image === "function";
+}

package/packages/core/src/index.ts

@@ -22,6 +22,7 @@ export type { Skill, SkillStep, OutputFormat, SkillsConfig } from "./skills/inde
 export { runAgent, runAgentIsolated, AgentLoop, getAgentLoop, buildAgentLoop, rebuildAgentLoop } from "./agent/agent-loop.ts";
 export type { AgentLoopOptions, StepEvent, StreamChunk } from "./agent/agent-loop.ts";
 export type { Provider } from "./agent/providers/index.ts";
+export { AgentRunner, createAgentRunner } from "./agent/providers/index.ts";
 
 // El cliente LLM es parte de la superficie pública: hasta 0.1.5 sólo se exportaba
 // el wrapper `AgentRunner`, así que no había forma de llamar a un provider ni de

package/packages/core/src/multimodal/vision-service.ts

@@ -35,6 +35,19 @@ class MultimodalService {
     }
   }
 
+  /**
+   * Convierte una imagen entrante en las partes que ve el modelo.
+   *
+   * Antes de mandarla la **normaliza**: una foto de teléfono son varios
+   * megabytes y unos cuantos miles de tokens, y a 1024 px el modelo ve lo mismo
+   * por una fracción del costo. Esa imagen no viaja una sola vez — queda en el
+   * historial y se reenvía en cada turno siguiente, así que el ahorro se
+   * multiplica por la longitud de la conversación.
+   *
+   * Es best-effort: si el runtime no puede procesarla (Bun < 1.4) o la imagen
+   * está corrupta, se manda tal cual. Perder la imagen sería peor que mandarla
+   * grande.
+   */
   async processImage(image: ImageInput, visionModelId?: string): Promise<ContentPart[]> {
     const parts: ContentPart[] = []
 
@@ -43,25 +56,44 @@ class MultimodalService {
     }
 
     if (image.type === "url") {
+      // Una URL no ocupa contexto: la descarga la hace el proveedor.
       parts.push({ type: "image_url", image_url: { url: image.data as string } })
-    } else if (image.type === "base64") {
-      parts.push({
-        type: "image_base64",
-        base64: image.data as string,
-        mimeType: image.mimeType || "image/jpeg",
-      })
-    } else if (image.type === "buffer") {
-      const base64 = Buffer.from(image.data as Buffer).toString("base64")
-      parts.push({
-        type: "image_base64",
-        base64,
-        mimeType: image.mimeType || "image/jpeg",
-      })
+      return parts
     }
 
+    const crudo = image.type === "base64"
+      ? (image.data as string)
+      : Buffer.from(image.data as Buffer).toString("base64")
+
+    const { base64, mimeType } = await this.normalizeIncoming(crudo, image.mimeType)
+    parts.push({ type: "image_base64", base64, mimeType })
+
     return parts
   }
 
+  /** Achica la imagen para el modelo; ante cualquier problema devuelve la original. */
+  private async normalizeIncoming(
+    base64: string,
+    mimeType?: string,
+  ): Promise<{ base64: string; mimeType: string }> {
+    const original = { base64, mimeType: mimeType || "image/jpeg" }
+    try {
+      const { imagesSupported, normalizeForModel } = await import("../images/index.ts")
+      if (!imagesSupported()) return original
+
+      const r = await normalizeForModel(base64)
+      if (!r.changed) return original
+
+      return {
+        base64: Buffer.from(r.bytes).toString("base64"),
+        mimeType: `image/${r.metadata.format}`,
+      }
+    } catch (err) {
+      log.warn(`no pude normalizar la imagen entrante, va sin achicar: ${(err as Error).message}`)
+      return original
+    }
+  }
+
   async ocrImage(image: ImageInput, providerId?: string): Promise<string> {
     const resolved = providerId || "openai"
 

package/packages/core/src/resilience/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Resilience — reintentos y circuit breakers.
+ *
+ * `withRetry` aplica backoff exponencial con jitter y respeta `Retry-After`
+ * cuando el proveedor lo manda; `isRetryableError` decide qué merece otro
+ * intento (429/5xx/timeout/red) y qué no (un 400 no mejora reintentando).
+ *
+ * El `CircuitBreaker` corta las llamadas a un servicio que ya viene fallando,
+ * en vez de seguir gastando intentos contra algo caído.
+ */
+
+export * from "./retry.ts";
+export * from "./circuit-breaker.ts";

package/packages/core/src/scheduler/CronScheduler.ts

@@ -1,11 +1,22 @@
 /**
  * Hive CronScheduler
  *
- * Croner-based scheduler for Hive with HiveDB persistence.
- * Manages recurring and one-shot cron jobs that execute through the agent pipeline.
+ * Manages recurring and one-shot cron jobs that execute through the agent pipeline,
+ * persisted in HiveDB.
+ *
+ * El motor de cron es propio (`./cron`), sin dependencias: sólo `setTimeout` e
+ * `Intl` del runtime. Antes era `croner`.
+ *
+ * `Bun.cron()` no sirve como reemplazo —se evaluó contra el runtime 1.4.0—:
+ * acepta sólo 5 campos y rechaza el sexto, no admite una fecha ISO como patrón
+ * (que es como se agendan los jobs `one_shot`), ignora la zona horaria, y su
+ * handle no expone la próxima corrida, que es de donde sale `next_run_at` y con
+ * lo que se detectan las corridas perdidas al arrancar. Tampoco tiene
+ * equivalente de `protect`, `maxRuns`, `interval`, `startAt`/`stopAt` ni
+ * `domAndDow`, todos campos persistidos de `CronJobDoc`.
  */
 
-import { Cron } from "croner";
+import { Cron } from "./cron/index.ts";
 import { logger } from "../utils/logger.ts";
 import { notifyTaskCompletion } from "./integration.ts";
 import { col, toIndexable, fromIndexable } from "../storage/hive.ts";
@@ -76,7 +87,7 @@ export class CronScheduler {
 
         if (misfirePolicy === "fire_once" && withinGrace) {
           log.info(`[boot:misfire] Job "${task.name}" (${task.id}) misfired at ${misfireTime.toISOString()} — executing now (fire_once, within grace)`);
-          // Activate the job first (so the Croner handle exists for future runs)
+          // Activate the job first (so it stays scheduled for future runs)
           await this.activate(task);
           // Then execute it immediately
           this.execute(task.id).catch((err) => {
@@ -100,7 +111,7 @@ export class CronScheduler {
           });
           await this.activate(task);
         } else {
-          // skip policy — recurring re-schedules its next occurrence via Croner
+          // skip policy — recurring re-schedules its next occurrence on its own
           log.info(`[boot:misfire] Job "${task.name}" (${task.id}) misfired at ${misfireTime.toISOString()} — skipping (misfire_policy=skip)`);
           await this.updateJob(task.id, {
             last_error: `Missed run at ${misfireTime.toISOString()} (policy: skip)`,
@@ -120,7 +131,7 @@ export class CronScheduler {
   }
 
   /**
-   * Activate a cron job - create or recreate its Croner instance
+   * Activate a cron job - create or recreate its scheduled instance
    */
   async activate(task: CronJob): Promise<void> {
     const existingJob = this.jobs.get(task.id);
@@ -218,13 +229,29 @@ export class CronScheduler {
     }
   }
 
-  /** Read-modify-write helper for cron_jobs partial updates, retrying on OCC conflict. */
-  private async updateJob(taskId: string, patch: Partial<CronJobDoc>): Promise<CronJobDoc | null> {
+  /**
+   * Read-modify-write helper for cron_jobs partial updates, retrying on OCC conflict.
+   *
+   * El parche puede ser una función, y para los contadores **tiene que serlo**:
+   * un objeto fijo se calcula una sola vez, fuera del bucle, así que al
+   * reintentar por conflicto de versión se vuelve a escribir el valor viejo y
+   * el incremento se pierde. Con dos ejecuciones solapadas del mismo job —algo
+   * normal en uno que tarda más que su intervalo y no declara `protect`— ambas
+   * leen `error_count: 4` y ambas escriben 5: el job nunca llega al umbral de
+   * auto-pausa y sigue fallando para siempre.
+   */
+  private async updateJob(
+    taskId: string,
+    patch: Partial<CronJobDoc> | ((actual: CronJobDoc) => Partial<CronJobDoc>),
+  ): Promise<CronJobDoc | null> {
     const cronJobsCol = await col<CronJobDoc>("cronJobs");
     for (let attempt = 0; attempt < 5; attempt++) {
       const existing = await cronJobsCol.get(taskId);
       if (!existing) return null;
-      const merged = { ...existing.doc, ...patch };
+      const merged = {
+        ...existing.doc,
+        ...(typeof patch === "function" ? patch(existing.doc) : patch),
+      };
       try {
         await cronJobsCol.put(taskId, merged, { expectedVersion: existing.version });
         return merged;
@@ -284,11 +311,11 @@ export class CronScheduler {
           agent_response: result.response?.slice(0, 1000) || null,
         });
 
-        const refreshed = await this.updateJob(task.id, {
-          run_count: task.run_count + 1,
+        const refreshed = await this.updateJob(task.id, (actual) => ({
+          run_count: actual.run_count + 1,
           last_run_at: finishedAt,
           last_error: null,
-        });
+        }));
 
         const job = this.jobs.get(task.id);
         if (job) {
@@ -322,10 +349,10 @@ export class CronScheduler {
         error_message: errorMessage,
       });
 
-      const updated = await this.updateJob(task.id, {
-        error_count: task.error_count + 1,
+      const updated = await this.updateJob(task.id, (actual) => ({
+        error_count: actual.error_count + 1,
         last_error: errorMessage,
-      });
+      }));
 
       log.error(`[execute] Job "${task.name}" (${task.id}) failed: ${errorMessage}`);
 
@@ -358,12 +385,12 @@ export class CronScheduler {
   }
 
   /**
-   * Handle errors from Croner
+   * Handle errors raised by the scheduled job
    */
   private handleError(task: CronJob, error: Error): void {
     log.error(`[error] Job "${task.name}" (${task.id}) error: ${error.message}`);
 
-    // Fix 3: record Croner-level errors in task_runs for full history
+    // Fix 3: record scheduler-level errors in task_runs for full history
     Promise.resolve().then(async () => {
       const runId = crypto.randomUUID().replace(/-/g, "").slice(0, 16);
       const now = new Date().toISOString();
@@ -384,10 +411,10 @@ export class CronScheduler {
         log.warn(`[handleError] Failed to insert task_run: ${(e as Error).message}`);
       }
 
-      await this.updateJob(task.id, {
-        error_count: task.error_count + 1,
+      await this.updateJob(task.id, (actual) => ({
+        error_count: actual.error_count + 1,
         last_error: error.message,
-      });
+      }));
     });
   }
 
@@ -431,7 +458,7 @@ export class CronScheduler {
   }
 
   /**
-   * Deactivate a cron job - stop Croner instance but keep in DB
+   * Deactivate a cron job - stop the scheduled instance but keep it in DB
    */
   deactivate(taskId: string): void {
     const job = this.jobs.get(taskId);