@johpaz/hive-sdk 0.2.0 → 0.3.0

package/packages/core/src/services/cron.ts

@@ -0,0 +1,257 @@
+/**
+ * Tareas programadas — la API, no la tool.
+ *
+ * A diferencia de la memoria, acá la implementación ya existía y era buena:
+ * `CronScheduler` (`scheduler/CronScheduler.ts`) tiene `create`, `update`,
+ * `delete`, `pause`, `resume`, `trigger`, `getHistory` y `listTasks`. El
+ * problema era el alcance: sólo se llegaba a ella desde dentro de las ocho
+ * `cron*Tool`, con argumentos con forma de LLM.
+ *
+ * Este servicio es la fachada. Conserva el comportamiento **híbrido** que ya
+ * tenían las tools y que hive replica en su ruta HTTP: si hay un scheduler
+ * corriendo se delega en él —es quien sabe calcular la próxima ejecución y
+ * rearmar los timers—; si no, se opera directo sobre `cronJobs`, para que un
+ * proceso que sólo administra tareas (una UI, un script) no necesite levantar
+ * el scheduler entero.
+ *
+ * Un job creado sin scheduler queda persistido y lo recoge el próximo arranque.
+ */
+
+import { col } from "../storage/hive.ts";
+import type { CronJobDoc, TaskRunDoc } from "../storage/collections.ts";
+import { getSchedulerInstance } from "../tools/cron/index.ts";
+import { logger } from "../utils/logger.ts";
+
+const log = logger.child("services/cron");
+
+export interface CreateCronInput {
+  name: string;
+  task: string;
+  taskType: "recurring" | "one_shot";
+  /** Requerido para `recurring`. */
+  cronExpression?: string;
+  /** Requerido para `one_shot` (ISO 8601). */
+  fireAt?: string;
+  timezone?: string;
+  agentId?: string | null;
+  channel?: string;
+  payload?: Record<string, unknown>;
+  toolName?: string | null;
+  maxRuns?: number | null;
+  startAt?: string;
+  stopAt?: string;
+  domAndDow?: boolean;
+}
+
+export interface CronJobSummary {
+  id: string;
+  name: string;
+  task: string;
+  taskType: CronJobDoc["task_type"];
+  status: CronJobDoc["status"];
+  cronExpression: string | null;
+  fireAt: string | null;
+  nextRun?: string | null;
+}
+
+function toSummary(doc: CronJobDoc): CronJobSummary {
+  return {
+    id: doc.id,
+    name: doc.name,
+    task: doc.task,
+    taskType: doc.task_type,
+    status: doc.status,
+    cronExpression: doc.cron_expression,
+    fireAt: doc.fire_at,
+    nextRun: (doc as { next_run?: string | null }).next_run ?? null,
+  };
+}
+
+async function jobsCol() {
+  return col<CronJobDoc>("cronJobs");
+}
+
+/** true cuando hay un scheduler vivo capaz de disparar las tareas. */
+export function hasScheduler(): boolean {
+  return !!getSchedulerInstance();
+}
+
+export async function createCronJob(input: CreateCronInput): Promise<CronJobSummary> {
+  if (!input.name?.trim()) throw new Error("La tarea necesita un nombre");
+  if (input.taskType === "recurring" && !input.cronExpression) {
+    throw new Error("Una tarea recurrente necesita `cronExpression`");
+  }
+  if (input.taskType === "one_shot" && !input.fireAt) {
+    throw new Error("Una tarea de una sola vez necesita `fireAt`");
+  }
+
+  const timezone = input.timezone ?? "UTC";
+  const scheduler = getSchedulerInstance();
+
+  if (scheduler) {
+    const res = await scheduler.create({
+      name: input.name,
+      task: input.task,
+      task_type: input.taskType,
+      cron_expression: input.cronExpression,
+      fire_at: input.fireAt,
+      timezone,
+      start_at: input.startAt,
+      stop_at: input.stopAt,
+      dom_and_dow: input.domAndDow,
+      agent_id: input.agentId ?? null,
+      channel: input.channel,
+      payload: input.payload,
+      tool_name: input.toolName ?? null,
+      max_runs: input.maxRuns ?? null,
+    });
+    const doc = (await (await jobsCol()).get(res.id))?.doc;
+    return doc ? { ...toSummary(doc), nextRun: res.nextRun ?? null } : {
+      id: res.id, name: input.name, task: input.task, taskType: input.taskType,
+      status: "active", cronExpression: input.cronExpression ?? null,
+      fireAt: input.fireAt ?? null, nextRun: res.nextRun ?? null,
+    };
+  }
+
+  // Sin scheduler: se persiste igual y el próximo arranque la recoge.
+  const c = await jobsCol();
+  const id = crypto.randomUUID().replace(/-/g, "").slice(0, 16);
+  const now = new Date().toISOString();
+  const doc = {
+    id,
+    name: input.name,
+    task: input.task,
+    task_type: input.taskType,
+    cron_expression: input.cronExpression ?? null,
+    fire_at: input.fireAt ?? null,
+    timezone,
+    start_at: input.startAt ?? null,
+    stop_at: input.stopAt ?? null,
+    dom_and_dow: input.domAndDow ? 1 : 0,
+    max_runs: input.maxRuns ?? null,
+    agent_id: input.agentId ?? "",
+    channel: input.channel ?? "webchat",
+    payload_json: JSON.stringify(input.payload ?? { prompt: input.task }),
+    tool_name: input.toolName ?? null,
+    status: "active",
+    created_at: now,
+    updated_at: now,
+  } as unknown as CronJobDoc;
+
+  await c.put(id, doc, { expectedVersion: 0 });
+  log.info(`tarea "${input.name}" creada sin scheduler (${id}) — se activará al próximo arranque`);
+  return toSummary(doc);
+}
+
+export async function listCronJobs(status?: CronJobDoc["status"]): Promise<CronJobSummary[]> {
+  const rows = await (await jobsCol()).scan({});
+  return rows
+    .map((e) => e.doc)
+    .filter((d) => (status ? d.status === status : true))
+    .map(toSummary);
+}
+
+export async function getCronJob(id: string): Promise<CronJobSummary | null> {
+  const entry = await (await jobsCol()).get(id);
+  return entry ? toSummary(entry.doc) : null;
+}
+
+/** Cambia el estado de una tarea. `false` si no existe. */
+async function setStatus(id: string, status: CronJobDoc["status"]): Promise<boolean> {
+  const c = await jobsCol();
+  const entry = await c.get(id);
+  if (!entry) return false;
+  await c.put(id, { ...entry.doc, status, updated_at: new Date().toISOString() } as CronJobDoc,
+    { expectedVersion: entry.version });
+  return true;
+}
+
+export interface UpdateCronInput {
+  name?: string;
+  task?: string;
+  cronExpression?: string;
+  fireAt?: string;
+  timezone?: string;
+  channel?: string;
+  maxRuns?: number | null;
+}
+
+/**
+ * Edita una tarea. Con scheduler se delega en él, porque cambiar la expresión
+ * cron exige recalcular la próxima ejecución y rearmar el timer — hacerlo sólo
+ * en la BD dejaría la tarea corriendo con el horario viejo hasta el reinicio.
+ */
+export async function updateCronJob(id: string, changes: UpdateCronInput): Promise<CronJobSummary> {
+  const scheduler = getSchedulerInstance();
+
+  if (scheduler) {
+    const ok = await scheduler.update(id, {
+      name: changes.name,
+      task: changes.task,
+      cron_expression: changes.cronExpression,
+      fire_at: changes.fireAt,
+      timezone: changes.timezone,
+      channel: changes.channel,
+      max_runs: changes.maxRuns,
+    });
+    if (!ok) throw new Error(`No existe la tarea "${id}"`);
+  } else {
+    const c = await jobsCol();
+    const entry = await c.get(id);
+    if (!entry) throw new Error(`No existe la tarea "${id}"`);
+
+    const doc = { ...entry.doc, updated_at: new Date().toISOString() } as CronJobDoc;
+    if (changes.name !== undefined) doc.name = changes.name;
+    if (changes.task !== undefined) doc.task = changes.task;
+    if (changes.cronExpression !== undefined) doc.cron_expression = changes.cronExpression;
+    if (changes.fireAt !== undefined) doc.fire_at = changes.fireAt;
+    if (changes.maxRuns !== undefined) (doc as { max_runs?: number | null }).max_runs = changes.maxRuns;
+    await c.put(id, doc, { expectedVersion: entry.version });
+  }
+
+  const actualizada = await getCronJob(id);
+  if (!actualizada) throw new Error(`No existe la tarea "${id}"`);
+  return actualizada;
+}
+
+export async function pauseCronJob(id: string): Promise<boolean> {
+  const scheduler = getSchedulerInstance();
+  if (scheduler) return await scheduler.pause(id);
+  return setStatus(id, "paused");
+}
+
+export async function resumeCronJob(id: string): Promise<boolean> {
+  const scheduler = getSchedulerInstance();
+  if (scheduler) return await scheduler.resume(id);
+  return setStatus(id, "active");
+}
+
+export async function deleteCronJob(id: string): Promise<boolean> {
+  const scheduler = getSchedulerInstance();
+  if (scheduler) return await scheduler.delete(id);
+
+  const c = await jobsCol();
+  if (!(await c.get(id))) return false;
+  await c.delete(id);
+  return true;
+}
+
+/**
+ * Dispara la tarea ahora. Requiere scheduler: sin él no hay nada que ejecute,
+ * y devolver `true` sería mentir.
+ */
+export function triggerCronJob(id: string): boolean {
+  const scheduler = getSchedulerInstance();
+  if (!scheduler) throw new Error("Disparar una tarea requiere un scheduler activo");
+  return scheduler.trigger(id);
+}
+
+export async function getCronHistory(id: string, limit = 50): Promise<TaskRunDoc[]> {
+  const rows = await (await col<TaskRunDoc>("taskRuns")).scan({});
+  return rows
+    .map((e) => e.doc)
+    .filter((r) => (r as { task_id?: string }).task_id === id)
+    .sort((a, b) => String((b as { started_at?: string }).started_at ?? "")
+      .localeCompare(String((a as { started_at?: string }).started_at ?? "")))
+    .slice(0, limit);
+}

package/packages/core/src/services/endpoints.ts

@@ -0,0 +1,289 @@
+/**
+ * Endpoints HTTP como herramientas — lo más cerca de "crear una tool desde la UI".
+ *
+ * Una tool normal es código con un `execute`, y desde una interfaz no hay dónde
+ * ponerlo. Este módulo invierte el problema: el usuario aporta **datos** —URL,
+ * método, cabeceras, qué parámetros acepta— y el ejecutor es genérico y vive
+ * acá. Así alguien suma una capacidad propia sin escribir código en el SDK y sin
+ * levantar un servidor MCP, que eran las dos únicas vías.
+ *
+ * Al registrarse, un endpoint hace tres cosas:
+ *  1. guarda su definición (`apiEndpoints`),
+ *  2. cifra sus credenciales aparte, y
+ *  3. escribe una fila en `tools` y reindexa, para que `search_knowledge` lo
+ *     descubra. Sin ese último paso el modelo nunca sabría que existe: el
+ *     loadout inicial es mínimo por diseño.
+ *
+ * La credencial nunca vuelve al llamador ni aparece en el resultado de una
+ * ejecución — es el motivo por el que un endpoint es más seguro que darle al
+ * modelo una `api_request` con la clave escrita en el prompt.
+ */
+
+import { col } from "../storage/hive.ts";
+import type { ApiEndpointDoc, ToolDoc } from "../storage/collections.ts";
+import { storeSecret, loadSecret, deleteSecret } from "../storage/crypto.ts";
+import { apiRequestTool } from "../tools/api/api-request.ts";
+import { registerAppTool } from "../tools/index.ts";
+import { syncToolCatalogToIndex } from "../agent/tool-selector.ts";
+import type { Tool } from "../tools/types.ts";
+import { slugify } from "./agents.ts";
+import { logger } from "../utils/logger.ts";
+
+const log = logger.child("services/endpoints");
+
+const ALLOWED_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+
+/** Las cabeceras con credenciales viven en el secret store, no en la fila. */
+const secretKey = (id: string) => `endpoint:${id}:headers`;
+
+export interface EndpointSummary {
+  id: string;
+  /** El nombre con el que el modelo la llama. */
+  toolName: string;
+  name: string;
+  description: string;
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  query: Record<string, string>;
+  bodyTemplate: string | null;
+  paramSchema: Record<string, unknown> | null;
+  /** Qué cabeceras secretas hay configuradas — nunca sus valores. */
+  secretHeaderNames: string[];
+  enabled: boolean;
+}
+
+export interface CreateEndpointInput {
+  name: string;
+  description: string;
+  url: string;
+  method?: string;
+  /** Cabeceras visibles (Content-Type, Accept…). */
+  headers?: Record<string, string>;
+  /** Cabeceras con credenciales: se cifran y no vuelven a salir. */
+  secretHeaders?: Record<string, string>;
+  query?: Record<string, string>;
+  bodyTemplate?: string | null;
+  /** JSON Schema de los parámetros que el modelo puede pasar. */
+  paramSchema?: Record<string, unknown> | null;
+  enabled?: boolean;
+}
+
+function parseObj(raw: string | null): Record<string, string> {
+  try {
+    return raw ? (JSON.parse(raw) as Record<string, string>) : {};
+  } catch {
+    return {};
+  }
+}
+
+/** El nombre de la tool se deriva del id: `endpoint_<slug>`. */
+export const toolNameFor = (id: string) => `endpoint_${id}`;
+
+async function endpointsCol() {
+  return col<ApiEndpointDoc>("apiEndpoints");
+}
+
+async function toSummary(doc: ApiEndpointDoc): Promise<EndpointSummary> {
+  const secretos = await loadSecret(secretKey(doc.id)).catch(() => null);
+  let nombres: string[] = [];
+  try {
+    nombres = secretos ? Object.keys(JSON.parse(secretos)) : [];
+  } catch {
+    nombres = [];
+  }
+  return {
+    id: doc.id,
+    toolName: toolNameFor(doc.id),
+    name: doc.name,
+    description: doc.description,
+    method: doc.method,
+    url: doc.url,
+    headers: parseObj(doc.headers_json),
+    query: parseObj(doc.query_json),
+    bodyTemplate: doc.body_template,
+    paramSchema: doc.param_schema_json ? JSON.parse(doc.param_schema_json) : null,
+    secretHeaderNames: nombres,
+    enabled: doc.enabled,
+  };
+}
+
+/**
+ * Reemplaza `{{param}}` por lo que el modelo haya pasado.
+ *
+ * Los valores se serializan como JSON cuando no son strings, para que un número
+ * o un booleano no terminen como `[object Object]` dentro del cuerpo.
+ */
+function fillTemplate(template: string, params: Record<string, unknown>): string {
+  return template.replace(/\{\{\s*(\w+)\s*\}\}/g, (_, key) => {
+    const v = params[key];
+    if (v === undefined) return "";
+    return typeof v === "string" ? v : JSON.stringify(v);
+  });
+}
+
+/**
+ * Construye la tool ejecutable de un endpoint.
+ *
+ * El ejecutor es `api_request`: no se reimplementa el cliente HTTP, con su
+ * manejo de timeouts, redacción y detección de content-type. Lo que agrega esta
+ * capa es resolver la credencial cifrada en el momento de llamar, de modo que
+ * nunca pase por el prompt ni por el resultado.
+ */
+export function buildEndpointTool(ep: EndpointSummary): Tool {
+  return {
+    name: ep.toolName,
+    description: ep.description,
+    parameters: (ep.paramSchema as Tool["parameters"]) ?? { type: "object", properties: {} },
+    execute: async (params: Record<string, unknown>) => {
+      const secretos = await loadSecret(secretKey(ep.id)).catch(() => null);
+      let secretHeaders: Record<string, string> = {};
+      try {
+        secretHeaders = secretos ? JSON.parse(secretos) : {};
+      } catch {
+        secretHeaders = {};
+      }
+
+      const url = new URL(fillTemplate(ep.url, params));
+      for (const [k, v] of Object.entries(ep.query)) url.searchParams.set(k, fillTemplate(v, params));
+
+      return apiRequestTool.execute({
+        method: ep.method,
+        url: url.toString(),
+        headers: { ...ep.headers, ...secretHeaders },
+        ...(ep.bodyTemplate ? { body: fillTemplate(ep.bodyTemplate, params) } : {}),
+      });
+    },
+  };
+}
+
+/** Registra en el proceso las tools de todos los endpoints habilitados. */
+export async function registerEndpointTools(): Promise<number> {
+  const eps = await listEndpoints();
+  for (const ep of eps) registerAppTool(buildEndpointTool(ep));
+  return eps.length;
+}
+
+/** La fila en `tools` es lo que hace que `search_knowledge` lo encuentre. */
+async function upsertToolRow(ep: EndpointSummary): Promise<void> {
+  const c = await col<ToolDoc>("tools");
+  const name = ep.toolName;
+  const existing = await c.get(name);
+  const now = Date.now();
+  await c.put(name, {
+    id: name,
+    name,
+    description: ep.description,
+    category: "api",
+    enabled: true,
+    active: ep.enabled,
+    created_at: existing?.doc.created_at ?? now,
+    updated_at: now,
+  }, { expectedVersion: existing?.version ?? 0 });
+  await syncToolCatalogToIndex().catch((e) => log.warn(`no pude reindexar: ${(e as Error).message}`));
+}
+
+export async function createEndpoint(input: CreateEndpointInput): Promise<EndpointSummary> {
+  if (!input.name?.trim()) throw new Error("El endpoint necesita un nombre");
+  if (!input.description?.trim()) {
+    throw new Error("El endpoint necesita una descripción: es lo que el modelo lee para decidir si le sirve");
+  }
+  if (!input.url?.trim()) throw new Error("El endpoint necesita una URL");
+
+  const method = (input.method ?? "GET").toUpperCase();
+  if (!ALLOWED_METHODS.includes(method)) throw new Error(`Método no permitido: ${method}`);
+
+  const c = await endpointsCol();
+  const id = slugify(input.name);
+  if (await c.get(id)) throw new Error(`Ya existe un endpoint con id "${id}"`);
+
+  const now = Date.now();
+  const doc: ApiEndpointDoc = {
+    id,
+    name: input.name,
+    description: input.description,
+    method,
+    url: input.url,
+    headers_json: input.headers ? JSON.stringify(input.headers) : null,
+    query_json: input.query ? JSON.stringify(input.query) : null,
+    body_template: input.bodyTemplate ?? null,
+    param_schema_json: input.paramSchema ? JSON.stringify(input.paramSchema) : null,
+    enabled: input.enabled ?? true,
+    created_at: now,
+    updated_at: now,
+  };
+
+  await c.put(id, doc, { expectedVersion: 0 });
+  if (input.secretHeaders) await storeSecret(secretKey(id), JSON.stringify(input.secretHeaders));
+
+  const summary = await toSummary(doc);
+  await upsertToolRow(summary);
+  registerAppTool(buildEndpointTool(summary));
+  log.info(`endpoint "${input.name}" registrado como tool ${summary.toolName}`);
+  return summary;
+}
+
+export async function getEndpoint(id: string): Promise<EndpointSummary | null> {
+  const entry = await (await endpointsCol()).get(id);
+  return entry ? toSummary(entry.doc) : null;
+}
+
+export async function listEndpoints(opts?: { includeDisabled?: boolean }): Promise<EndpointSummary[]> {
+  const rows = await (await endpointsCol()).scan({});
+  const docs = rows.map((e) => e.doc).filter((d) => (opts?.includeDisabled ? true : d.enabled));
+  return Promise.all(docs.map(toSummary));
+}
+
+export async function updateEndpoint(id: string, changes: Partial<CreateEndpointInput>): Promise<EndpointSummary> {
+  const c = await endpointsCol();
+  const entry = await c.get(id);
+  if (!entry) throw new Error(`No existe el endpoint "${id}"`);
+
+  const doc: ApiEndpointDoc = { ...entry.doc, updated_at: Date.now() };
+  if (changes.name !== undefined) doc.name = changes.name;
+  if (changes.description !== undefined) doc.description = changes.description;
+  if (changes.url !== undefined) doc.url = changes.url;
+  if (changes.method !== undefined) {
+    const m = changes.method.toUpperCase();
+    if (!ALLOWED_METHODS.includes(m)) throw new Error(`Método no permitido: ${m}`);
+    doc.method = m;
+  }
+  if (changes.headers !== undefined) doc.headers_json = JSON.stringify(changes.headers);
+  if (changes.query !== undefined) doc.query_json = JSON.stringify(changes.query);
+  if (changes.bodyTemplate !== undefined) doc.body_template = changes.bodyTemplate;
+  if (changes.paramSchema !== undefined) {
+    doc.param_schema_json = changes.paramSchema ? JSON.stringify(changes.paramSchema) : null;
+  }
+  if (changes.enabled !== undefined) doc.enabled = changes.enabled;
+
+  await c.put(id, doc, { expectedVersion: entry.version });
+  if (changes.secretHeaders) await storeSecret(secretKey(id), JSON.stringify(changes.secretHeaders));
+
+  const summary = await toSummary(doc);
+  await upsertToolRow(summary);
+  registerAppTool(buildEndpointTool(summary));
+  return summary;
+}
+
+export const toggleEndpoint = (id: string, enabled: boolean) => updateEndpoint(id, { enabled });
+
+/**
+ * Llama al endpoint sin pasar por el modelo, para que una UI pueda probarlo
+ * antes de dejárselo a un agente.
+ */
+export async function testEndpoint(id: string, params: Record<string, unknown> = {}): Promise<unknown> {
+  const ep = await getEndpoint(id);
+  if (!ep) throw new Error(`No existe el endpoint "${id}"`);
+  return buildEndpointTool(ep).execute(params);
+}
+
+export async function deleteEndpoint(id: string): Promise<boolean> {
+  const c = await endpointsCol();
+  if (!(await c.get(id))) return false;
+
+  await c.delete(id);
+  await deleteSecret(secretKey(id)).catch(() => {});
+  await (await col<ToolDoc>("tools")).delete(toolNameFor(id)).catch(() => {});
+  await syncToolCatalogToIndex().catch(() => {});
+  return true;
+}

package/packages/core/src/services/ethics.ts

@@ -0,0 +1,107 @@
+/**
+ * Código de ética — la API, no la ruta.
+ *
+ * Es el texto que se le inyecta al agente como marco obligatorio y que no puede
+ * ignorar. En hive el CRUD vive inline en `gateway/routes/ethics.ts`.
+ *
+ * `is_default` marca la plantilla que trae el sistema: se puede desactivar, pero
+ * borrarla dejaría la instalación sin ninguna referencia si el usuario no
+ * escribió la suya, así que se protege.
+ */
+
+import { col } from "../storage/hive.ts";
+import type { EthicsDoc } from "../storage/collections.ts";
+
+export interface EthicsSummary {
+  id: string;
+  name: string;
+  description: string | null;
+  content: string;
+  isDefault: boolean;
+  enabled: boolean;
+  active: boolean;
+}
+
+const toSummary = (d: EthicsDoc): EthicsSummary => ({
+  id: d.id,
+  name: d.name,
+  description: d.description,
+  content: d.content,
+  isDefault: d.is_default,
+  enabled: d.enabled,
+  active: d.active,
+});
+
+async function ethicsCol() {
+  return col<EthicsDoc>("ethics");
+}
+
+export async function listEthics(opts?: { includeInactive?: boolean }): Promise<EthicsSummary[]> {
+  const rows = await (await ethicsCol()).scan({});
+  return rows
+    .map((e) => e.doc)
+    .filter((d) => (opts?.includeInactive ? true : d.active))
+    .map(toSummary);
+}
+
+export async function getEthics(id: string): Promise<EthicsSummary | null> {
+  const entry = await (await ethicsCol()).get(id);
+  return entry ? toSummary(entry.doc) : null;
+}
+
+export async function createEthics(input: {
+  id?: string;
+  name: string;
+  content: string;
+  description?: string | null;
+  active?: boolean;
+}): Promise<EthicsSummary> {
+  if (!input.name?.trim()) throw new Error("El código de ética necesita un nombre");
+  if (!input.content?.trim()) throw new Error("El código de ética necesita contenido");
+
+  const c = await ethicsCol();
+  const id = input.id ?? crypto.randomUUID();
+  if (await c.get(id)) throw new Error(`Ya existe un código de ética con id "${id}"`);
+
+  const doc: EthicsDoc = {
+    id,
+    name: input.name,
+    description: input.description ?? null,
+    content: input.content,
+    is_default: false,
+    enabled: true,
+    active: input.active ?? false,
+  };
+  await c.put(id, doc, { expectedVersion: 0 });
+  return toSummary(doc);
+}
+
+export async function updateEthics(
+  id: string,
+  changes: { name?: string; content?: string; description?: string | null; active?: boolean },
+): Promise<EthicsSummary> {
+  const c = await ethicsCol();
+  const entry = await c.get(id);
+  if (!entry) throw new Error(`No existe el código de ética "${id}"`);
+
+  const doc: EthicsDoc = { ...entry.doc };
+  if (changes.name !== undefined) doc.name = changes.name;
+  if (changes.content !== undefined) doc.content = changes.content;
+  if (changes.description !== undefined) doc.description = changes.description;
+  if (changes.active !== undefined) doc.active = changes.active;
+
+  await c.put(id, doc, { expectedVersion: entry.version });
+  return toSummary(doc);
+}
+
+export const toggleEthics = (id: string, active: boolean) => updateEthics(id, { active });
+
+/** No borra la plantilla del sistema: dejaría la instalación sin referencia. */
+export async function deleteEthics(id: string): Promise<boolean> {
+  const c = await ethicsCol();
+  const entry = await c.get(id);
+  if (!entry) return false;
+  if (entry.doc.is_default) throw new Error("El código de ética por defecto no se puede borrar; desactívalo");
+  await c.delete(id);
+  return true;
+}