@johpaz/hive-sdk 0.2.0 → 0.3.1

package/packages/core/src/harness/executors.ts

@@ -0,0 +1,493 @@
+/**
+ * Ejecutores del harness — qué corre la cola durable cuando toma un job.
+ *
+ * `harness/` da la cola, los leases y el checkpoint, pero no sabía ejecutar
+ * nada: registrar los ejecutores quedaba en manos de quien usara el SDK, y eso
+ * son varios cientos de líneas de cableado —reintentos, epoch, proof packets,
+ * criterios de aceptación, fan-in— antes de poder correr un solo enjambre
+ * durable. Estos dos vienen listos:
+ *
+ *  - `worker_task`: ejecuta un worker delegado en contexto aislado, verifica
+ *    sus criterios de aceptación, arma el proof packet y avisa por el bus.
+ *  - `goal_run`: orquesta varios turnos contra un objetivo hasta que lo
+ *    verifica o se acaba el presupuesto.
+ *
+ * `chat_turn` NO está acá a propósito: en hive depende de `webchat-turn.ts`,
+ * que es su servidor HTTP. Un turno de chat lo define la aplicación —qué es un
+ * "canal", cómo se transmite un token— así que ese se registra desde fuera con
+ * `registerExecutor("chat_turn", ...)`.
+ *
+ * Registrar es opt-in: `initHarnessExecutors()` no se llama sola, porque quién
+ * ejecuta qué es decisión de la app.
+ */
+
+import { registerExecutor, getDurableQueue, type JobExecutor } from "../gateway/durable-queue.ts";
+import { logger } from "../utils/logger.ts";
+import { col, updateDoc } from "../storage/hive.ts";
+import { isRetryableError } from "../resilience/retry.ts";
+import type { JobDoc, TaskDoc, AgentRunDoc, AgentDoc } from "../storage/collections.ts";
+import { runAgent, runAgentIsolatedDetailed } from "../agent/agent-loop.ts";
+import {
+  createRun, completeRun, failRun, interruptRun, getRun, reclaimRun, bumpTurn,
+  startLeaseRenewal, stopLeaseRenewal, deserializeAcceptance, deserializeEpoch,
+} from "../agent/run-store.ts";
+import { sendToUserChannel } from "../gateway/channel-notify.ts";
+import { verifyGoal } from "../agent/goal-runner.ts";
+import { buildProofPacket } from "../agent/proof-packet.ts";
+import { runAcceptanceChecks, recordAgentOutcome } from "../agent/acceptance-checks.ts";
+import { prepareDelegation, type PreparedDelegation } from "../agent/delegation-runtime.ts";
+import { agentBus } from "../events/agent-bus.ts";
+import type { MCPClientManager } from "../mcp/index.ts";
+import { publishNarration } from "../events/narration.ts";
+import {
+  emitDelegationStarted,
+  emitDelegationFinished,
+  emitWorkEvent,
+} from "../canvas/emitter.ts";
+
+const log = logger.child("harness-executors");
+
+let mcpManager: MCPClientManager | null = null;
+
+/** Las tools MCP que verá un worker delegado. Sin esto corre sólo con las nativas. */
+export function setHarnessExecutorMCPManager(m: MCPClientManager | null): void {
+  mcpManager = m;
+}
+
+const workerTaskExecutor: JobExecutor = async (job, signal) => {
+  const payload = JSON.parse(job.payload_json);
+  const workerId = payload.workerId as string;
+  const taskDescription = payload.taskDescription as string;
+  const taskName = payload.taskName as string;
+  const taskId = payload.taskId as string | undefined;
+  const acceptance = (payload.acceptance ?? null) as import("../agent/run-store").AcceptanceCriterion[] | null;
+  const runId = job.run_id;
+  const turnId = payload.turnId as string | undefined;
+  const parentAgentId = (payload.parentAgentId as string | undefined) ?? "";
+  const originThreadId = payload.originThreadId as string | undefined;
+  const originChannel = payload.originChannel as string | undefined;
+  const originUserId = payload.userId as string | undefined;
+  const originSessionId = payload.originSessionId as string | undefined;
+
+  log.info(`[worker_task] Job ${job.id} → worker=${workerId} task="${taskName}"`);
+
+  const agentsCol = await col<AgentDoc>("agents");
+  const workerEntry = await agentsCol.get(workerId);
+  if (!workerEntry) return { ok: false, error: `Worker not found: ${workerId}`, retryable: false };
+  if (!workerEntry.doc.enabled) return { ok: false, error: `Worker disabled: ${workerEntry.doc.name}`, retryable: false };
+
+  const workerName = workerEntry.doc.name;
+  const isCatalogAgent = workerEntry.doc.source === "catalog";
+  agentBus.notifyTaskStarted(workerId, workerName, 0, taskName, "");
+  const delegationRef = taskId ?? job.id;
+  emitDelegationStarted({ workerId, parentAgentId, taskRef: delegationRef, taskName });
+  if (turnId && originThreadId) {
+    await publishNarration({
+      turnId,
+      threadId: originThreadId,
+      channel: originChannel,
+      userId: originUserId,
+      sessionId: originSessionId,
+      agentId: workerId,
+      agentName: workerName,
+      kind: "worker_started",
+      status: "running",
+      label: `${workerName} inició “${taskName}”`,
+      dedupeKey: `worker_started:${taskId ?? job.id}`,
+    });
+  }
+
+  // Update TaskDoc → in_progress if we have a taskId
+  if (taskId) {
+    await updateDoc<TaskDoc>("tasks", taskId, {
+      status: "in_progress",
+      started_at: Date.now(),
+      job_id: job.id,
+      run_id: runId,
+      updated_at: Date.now(),
+    } as Partial<TaskDoc>).catch(() => {});
+  }
+
+  let prepared: PreparedDelegation | null = null;
+  try {
+    prepared = await prepareDelegation(workerId, {
+      workspace: payload.workspace ?? workerEntry.doc.workspace ?? null,
+      parentProviderId: payload.parentProviderId ?? null,
+      parentModelId: payload.parentModelId ?? null,
+      mcpManager,
+    });
+    // Resume from the checkpoint on a re-claimed job (payload can't know this)
+    const run = runId ? await getRun(runId) : null;
+    const resume = !!run?.state_json;
+    const threadId = run?.thread_id || `task-${Date.now()}-${workerId}`;
+
+    const execution = await runAgentIsolatedDetailed({
+      agentId: workerId,
+      taskDescription,
+      threadId,
+      mcpManager,
+      runId,
+      resume,
+      durable: !!runId,
+      signal,
+      turnId,
+      taskId,
+      userId: originUserId,
+      channel: originChannel,
+      sessionId: originSessionId,
+    });
+    const result = execution.content;
+
+    if (signal.aborted) {
+      agentBus.notifyTaskFailed(workerId, workerName, 0, taskName, "", "Aborted");
+      emitWorkEvent({
+        phase: "aborted",
+        taskRef: delegationRef,
+        taskName,
+        actorId: workerId,
+        targetId: parentAgentId || null,
+        detail: "Trabajo interrumpido",
+      });
+      if (taskId) {
+        await updateDoc<TaskDoc>("tasks", taskId, {
+          status: "pending",
+          updated_at: Date.now(),
+        } as Partial<TaskDoc>).catch(() => {});
+      }
+      return { ok: false, error: "Aborted", retryable: false };
+    }
+
+    const finishedRun = runId ? await getRun(runId) : null;
+    const resolvedAcceptance = acceptance ?? (finishedRun ? deserializeAcceptance(finishedRun) : null);
+    const evidence = [result, ...execution.toolEvidence];
+    const checks = await runAcceptanceChecks({
+      objective: taskDescription,
+      acceptance: resolvedAcceptance,
+      delivery: result,
+      evidence,
+    });
+
+    if (checks.status === "failed") {
+      await recordAgentOutcome(workerId, "harmful");
+      emitWorkEvent({
+        phase: "review_failed",
+        taskRef: delegationRef,
+        taskName,
+        actorId: parentAgentId || workerId,
+        targetId: workerId,
+        detail: checks.summary,
+      });
+      if (turnId && originThreadId) {
+        await publishNarration({
+          turnId,
+          threadId: originThreadId,
+          channel: originChannel,
+          userId: originUserId,
+          sessionId: originSessionId,
+          agentId: workerId,
+          agentName: workerName,
+          kind: "failed",
+          status: "error",
+          label: `La entrega de ${workerName} no pasó los checks automáticos`,
+          detail: checks.summary,
+          dedupeKey: `verification_failed:${taskId ?? job.id}`,
+        });
+      }
+      if (taskId) {
+        await updateDoc<TaskDoc>("tasks", taskId, {
+          status: "blocked",
+          error: checks.summary,
+          updated_at: Date.now(),
+        } as Partial<TaskDoc>).catch(() => {});
+      }
+      return {
+        ok: false,
+        error: checks.summary,
+        retryable: false,
+      };
+    }
+
+    await recordAgentOutcome(workerId, "helpful");
+    emitWorkEvent({
+      phase: "review_passed",
+      taskRef: delegationRef,
+      taskName,
+      actorId: parentAgentId || workerId,
+      targetId: workerId,
+    });
+    if (turnId && originThreadId) {
+      await publishNarration({
+        turnId,
+        threadId: originThreadId,
+        channel: originChannel,
+        userId: originUserId,
+        sessionId: originSessionId,
+        agentId: workerId,
+        agentName: workerName,
+        kind: "verified",
+        status: "done",
+        label: `${workerName} completó “${taskName}”`,
+        detail: checks.status === "passed" ? checks.summary : "El coordinador revisa el resultado.",
+        dedupeKey: `verified:${taskId ?? job.id}`,
+      });
+    }
+
+    agentBus.notifyTaskCompleted(workerId, workerName, 0, taskName, "", result);
+
+    // Update TaskDoc → completed
+    if (taskId) {
+      await updateDoc<TaskDoc>("tasks", taskId, {
+        status: "completed",
+        progress: 100,
+        result,
+        completed_at: Date.now(),
+        updated_at: Date.now(),
+      } as Partial<TaskDoc>).catch(() => {});
+    }
+
+    await buildProofPacket({
+      runId,
+      agentId: workerId,
+      intendedOutcome: taskDescription,
+      met: true,
+      checksRun: checks.results.length ? checks.results.map((r) => r.check) : ["none"],
+      evidence,
+      epoch: finishedRun ? deserializeEpoch(finishedRun) : null,
+      catalogAgentId: isCatalogAgent ? workerId : null,
+    });
+
+    emitWorkEvent({
+      phase: "completed",
+      taskRef: delegationRef,
+      taskName,
+      actorId: workerId,
+      targetId: parentAgentId || null,
+    });
+
+    return {
+      ok: true,
+      result: {
+        content: result,
+        evidence: execution.toolEvidence,
+        acceptance: resolvedAcceptance,
+        checks,
+      },
+    };
+  } catch (err) {
+    const errorMsg = (err as Error).message;
+    agentBus.notifyTaskFailed(workerId, workerName, 0, taskName, "", errorMsg);
+    emitWorkEvent({
+      phase: signal.aborted ? "aborted" : "failed",
+      taskRef: delegationRef,
+      taskName,
+      actorId: workerId,
+      targetId: parentAgentId || null,
+      detail: signal.aborted ? "Trabajo interrumpido" : errorMsg,
+    });
+    if (turnId && originThreadId) {
+      await publishNarration({
+        turnId,
+        threadId: originThreadId,
+        channel: originChannel,
+        userId: originUserId,
+        sessionId: originSessionId,
+        agentId: workerId,
+        agentName: workerName,
+        kind: "failed",
+        status: "error",
+        label: `${workerName} no pudo completar “${taskName}”`,
+        detail: errorMsg,
+        dedupeKey: `worker_failed:${taskId ?? job.id}`,
+      });
+    }
+
+    // Update TaskDoc → failed
+    if (taskId) {
+      await updateDoc<TaskDoc>("tasks", taskId, {
+        status: "failed",
+        error: errorMsg,
+        updated_at: Date.now(),
+      } as Partial<TaskDoc>).catch(() => {});
+    }
+
+    return { ok: false, error: errorMsg, retryable: isRetryableError(err) };
+  } finally {
+    emitDelegationFinished({ workerId, taskRef: delegationRef });
+    await prepared?.release();
+  }
+};
+
+// ─── goal_run executor ──────────────────────────────────────────────────────
+// Multi-turn orchestration: run a turn → verify the goal → continue with the
+// verifier's feedback (verifyGoal, goal-runner.ts) until the goal is met or
+// the budget runs out. The goal
+// AgentRun row (job.run_id) is the orchestrator record: goal_attempts,
+// turns_used and tokens_used accumulate across turns and the budget is HARD.
+// Turns are plain (non-durable) runs on the same thread — a mid-turn crash
+// re-runs the current attempt; conversation history preserves prior progress.
+
+const goalRunExecutor: JobExecutor = async (job, signal) => {
+  const payload = JSON.parse(job.payload_json);
+  const agentId = payload.agentId as string;
+  const threadId = payload.threadId as string;
+  const goal = payload.goal as string;
+  const checkTool = (payload.goal_check_tool as string | null) ?? null;
+  const budget = (payload.budget ?? {}) as { maxIterations?: number; maxTurns?: number; maxTokens?: number };
+  const maxIterationsPerTurn = budget.maxIterations ?? 20;
+  const maxTurns = budget.maxTurns ?? 10;
+  const maxTokens = budget.maxTokens ?? 200_000;
+  const maxAttempts = (payload.maxAttempts as number | undefined) ?? 5;
+  const goalRunId = job.run_id;
+
+  log.info(`[goal_run] Job ${job.id} → agent=${agentId} goal="${goal}" maxAttempts=${maxAttempts}`);
+
+  const goalRun = await getRun(goalRunId);
+  if (!goalRun) return { ok: false, error: `Goal run ${goalRunId} not found` };
+  const channel = goalRun.channel;
+  const notifyUserId = goalRun.user_id;
+
+  const notify = async (text: string) => {
+    if (channel && notifyUserId) {
+      await sendToUserChannel(channel, notifyUserId, text, { threadId }).catch(() => {});
+    }
+  };
+
+  const acceptance = deserializeAcceptance(goalRun);
+  const epoch = deserializeEpoch(goalRun);
+
+  await reclaimRun(goalRunId).catch(() => {});
+  startLeaseRenewal(goalRunId);
+
+  try {
+    let attempts = goalRun.goal_attempts ?? 0;
+    let lastContent = "";
+    let lastReason = "";
+
+    for (;;) {
+      if (signal.aborted) {
+        await interruptRun(goalRunId, "Goal run aborted").catch(() => {});
+        return { ok: false, error: "Aborted", retryable: false };
+      }
+
+      // HARD budget check against the accumulated goal run row
+      const current = await getRun(goalRunId);
+      const turnsUsed = current?.turns_used ?? 0;
+      const tokensUsed = current?.tokens_used ?? 0;
+      if (attempts >= maxAttempts || turnsUsed >= maxTurns || tokensUsed >= maxTokens) {
+        const summary = `intentos ${attempts}/${maxAttempts}, turnos ${turnsUsed}/${maxTurns}, tokens ${tokensUsed}/${maxTokens}`;
+        await failRun(goalRunId, `Goal not met — budget exhausted (${summary}). ${lastReason}`.trim());
+        await notify(`❌ Meta no cumplida: "${goal}". Presupuesto agotado (${summary}).${lastReason ? ` Última razón: ${lastReason}` : ""}`);
+        await buildProofPacket({
+          runId: goalRunId,
+          agentId,
+          intendedOutcome: goal,
+          met: false,
+          checksRun: acceptance ? acceptance.map((a) => a.checkTool ?? "llm_verifier") : [checkTool ?? "llm_verifier"],
+          evidence: [lastReason || "budget exhausted before verification succeeded"],
+          knownLimits: `Budget exhausted: ${summary}`,
+          epoch,
+        }).catch(() => {});
+        return { ok: false, error: `Goal budget exhausted (${summary})`, retryable: false };
+      }
+
+      const turnMessage = attempts === 0
+        ? `Meta: ${goal}\n\nTrabajá hasta cumplir esta meta. Explicá el resultado al terminar.`
+        : `La meta aún no se verificó como cumplida.\nMeta: "${goal}"\nRazón del verificador: ${lastReason}\nPresupuesto restante: ${maxAttempts - attempts} intento(s), ${maxTurns - turnsUsed} turno(s).\nContinuá trabajando para cumplirla.`;
+
+      // One turn (non-durable: the goal row carries the durable state)
+      let turnTokens = 0;
+      let turnContent = "";
+      for await (const chunk of runAgent({
+        agentId,
+        userMessage: turnMessage,
+        threadId,
+        signal,
+        mcpManager,
+        budget: { maxIterations: maxIterationsPerTurn },
+      })) {
+        const msgs = (chunk as any).agent?.messages;
+        if (msgs?.[0]?.content) turnContent = msgs[0].content;
+        const usage = (chunk as any).usage;
+        if (usage) turnTokens = (usage.input_tokens ?? 0) + (usage.output_tokens ?? 0);
+      }
+
+      attempts++;
+      lastContent = turnContent || lastContent;
+      await bumpTurn(goalRunId, turnTokens).catch(() => {});
+      await updateDoc<AgentRunDoc>("agentRuns", goalRunId, {
+        goal_attempts: attempts,
+        updated_at: Date.now(),
+      } as Partial<AgentRunDoc>).catch(() => {});
+
+      // Verify: deterministic tool when configured, a single LLM judgment
+      // otherwise (one call total, covering every acceptance criterion —
+      // see verifyGoal in goal-runner.ts).
+      const providerCfg = await resolveGoalProviderCfg(agentId);
+      const verdict = await verifyGoal(goal, checkTool, [
+        { role: "user", content: `Meta: ${goal}` },
+        { role: "assistant", content: turnContent || "(sin respuesta)" },
+      ], providerCfg, acceptance);
+
+      if (verdict.met) {
+        await completeRun(goalRunId, lastContent);
+        await notify(`✅ Meta cumplida: "${goal}". ${verdict.reason}`);
+        log.info(`[goal_run] Goal met after ${attempts} attempt(s): ${verdict.reason}`);
+        await buildProofPacket({
+          runId: goalRunId,
+          agentId,
+          intendedOutcome: goal,
+          met: true,
+          acceptanceResults: verdict.acceptanceResults,
+          checksRun: acceptance ? acceptance.map((a) => a.checkTool ?? "llm_verifier") : [checkTool ?? "llm_verifier"],
+          evidence: [verdict.reason, lastContent].filter(Boolean),
+          epoch,
+          catalogAgentId: null,
+        });
+        return { ok: true, result: { met: true, attempts, reason: verdict.reason, content: lastContent } };
+      }
+
+      lastReason = verdict.reason;
+      log.info(`[goal_run] Attempt ${attempts}/${maxAttempts} not met: ${verdict.reason}`);
+    }
+  } catch (err) {
+    await failRun(goalRunId, (err as Error).message).catch(() => {});
+    await notify(`❌ No pude completar la meta: "${goal}". Error: ${(err as Error).message}`);
+    return { ok: false, error: (err as Error).message, retryable: isRetryableError(err) };
+  } finally {
+    stopLeaseRenewal(goalRunId);
+  }
+};
+
+async function resolveGoalProviderCfg(agentId: string) {
+  const { fromIndexable } = await import("../storage/hive");
+  const { resolveProviderConfig, getDefaultLLM } = await import("../agent/llm-client");
+  const agentsCol = await col<{ provider_id?: string | null; model_id?: string | null }>("agents");
+  const entry = await agentsCol.get(agentId);
+  let providerId = entry ? fromIndexable(entry.doc.provider_id ?? null) : null;
+  let modelId = entry ? fromIndexable(entry.doc.model_id ?? null) : null;
+  if (!providerId || !modelId) {
+    const dflt = await getDefaultLLM();
+    providerId = providerId || dflt?.provider || "";
+    modelId = modelId || dflt?.model || "";
+  }
+  return resolveProviderConfig(providerId, modelId);
+}
+
+// ─── Register all executors ─────────────────────────────────────────────────
+
+
+let initialized = false;
+
+/**
+ * Registra `worker_task` y `goal_run` en la cola durable. Idempotente.
+ *
+ * No se llama sola: la app decide qué tipos de job ejecuta este proceso. Para
+ * un turno de chat, registrá el tuyo con `registerExecutor("chat_turn", ...)`.
+ */
+export function initHarnessExecutors(): void {
+  if (initialized) return;
+  registerExecutor("worker_task", workerTaskExecutor);
+  registerExecutor("goal_run", goalRunExecutor);
+  initialized = true;
+  log.info("ejecutores del harness registrados: worker_task, goal_run");
+}

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

@@ -11,12 +11,22 @@
  * dos estados posibles, así que ahora esto re-exporta la implementación única y el
  * subpath `@johpaz/hive-sdk/harness` sigue funcionando igual.
  *
- * El módulo no se cablea solo dentro del agent loop: la app decide qué significa
- * "durable" para sus tipos de job y registra ejecutores con `registerExecutor()`.
+ * La app decide qué significa "durable" para sus tipos de job. Para los dos
+ * casos que necesita cualquier enjambre —ejecutar un worker delegado y
+ * perseguir un objetivo— hay ejecutores listos: `initHarnessExecutors()`. Para
+ * el resto, `registerExecutor()`.
  */
 
 import { ensureHiveDb } from "../storage/bootstrap.ts";
 
+// ─── Ejecutores listos para usar ─────────────────────────────────────────────
+// La cola sabe encolar, reintentar y recuperar; estos son los que saben hacer
+// el trabajo. Ver executors.ts para por qué `chat_turn` no está entre ellos.
+export {
+  initHarnessExecutors,
+  setHarnessExecutorMCPManager,
+} from "./executors.ts";
+
 // ─── Cola y almacén de jobs ──────────────────────────────────────────────────
 export * from "../gateway/job-store.ts";
 export * from "../gateway/durable-queue.ts";