orquestra-mcp 1.10.0 → 1.14.0

package/README.md

@@ -189,7 +189,7 @@ create/update sigue siendo criterio del agente y del humano.
 38 tools: 9 de lectura (contexto/tasks/search + dashboard/workspace/infra/
 paridad/setup guide/stage playbook) + 6 `list_*` + 19 de creación/edición
 (tasks/ideas/changelog/notes/docs + módulos/flujo/categorías/servicios/
-entornos/distribuciones/proyecto) + 2 de QA (create_qa_run/get_qa_run) +
+entornos/distribuciones/proyecto) + 2 de Agentes (create_agent_run/get_agent_run) +
 2 compuestas (init_project, apply_stage_playbook). No hay `delete_*`, ni
 `update_idea`/`update_note`/`update_doc`/`update_changelog_entry`
 todavía. Publicado en npm como `orquestra-mcp` (unscoped) -- `npx

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "orquestra-mcp",
-  "version": "1.10.0",
-  "description": "Servidor MCP de Orquestra -- 72 tools para leer y escribir tareas, ideas, changelog, infraestructura, contenido, QA y más desde un agente de IA",
+  "version": "1.14.0",
+  "description": "Servidor MCP de Orquestra -- 78 tools para leer y escribir tareas, ideas, changelog, infraestructura, contenido, QA y más desde un agente de IA",
   "type": "module",
   "bin": {
-    "orquestra-mcp": "./bin/orquestra-mcp.mjs"
+    "orquestra-mcp": "bin/orquestra-mcp.mjs"
   },
   "files": [
     "bin",

package/src/api.mjs

@@ -102,3 +102,16 @@ export async function apiDelete(config, path, { projectId, id }) {
   })
   return parseResponse(res)
 }
+
+// PUT crudo a una presigned URL de S3 (createAttachmentUploadUrl en
+// orquestra-infra) -- a diferencia de apiGet/apiPost/etc, este request NO
+// va contra config.apiBase ni lleva el Bearer del MCP: la URL firmada YA
+// es la autorización completa.
+export async function putToPresignedUrl(uploadUrl, buffer, contentType) {
+  const res = await fetch(uploadUrl, {
+    method: 'PUT',
+    headers: { 'Content-Type': contentType },
+    body: buffer,
+  })
+  if (!res.ok) throw new Error(`Falló la subida a S3: HTTP ${res.status}`)
+}

package/src/server.mjs

@@ -1,6 +1,8 @@
+import { readFileSync, statSync } from 'node:fs'
+import path from 'node:path'
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { z } from 'zod'
-import { loadConfig, apiGet, apiPost, apiPatch, apiDelete, ApiError } from './api.mjs'
+import { loadConfig, apiGet, apiPost, apiPatch, apiDelete, putToPresignedUrl, ApiError } from './api.mjs'
 import { STAGES, PLAYBOOKS } from './stages.mjs'
 import { FOUNDATIONS } from './foundations.mjs'
 
@@ -36,6 +38,15 @@ const PLATFORM_TYPES = ['android', 'ios', 'web', 'desktop-mac', 'desktop-win', '
 const INFRA_STATUSES = ['operational', 'degraded', 'down']
 const STAGE_IDS = STAGES.map(s => s.id)
 
+// Adjuntos -- entityType en la tool es singular (task/note/idea/doc, más
+// natural para el modelo), la API usa el plural de la colección de
+// Firestore (tasks/notes/ideas/docs) -- este mapa traduce entre los dos.
+const ATTACHMENT_ENTITY_PATH = { task: 'tasks', note: 'notes', idea: 'ideas', doc: 'docs' }
+const ATTACHMENT_ENTITY_TYPES = Object.keys(ATTACHMENT_ENTITY_PATH)
+const ATTACHMENT_IMAGE_MIME_BY_EXT = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp' }
+const MAX_ATTACHMENT_IMAGE_BYTES = 15 * 1024 * 1024
+const MAX_ATTACHMENT_CODE_CHARS = 200_000
+
 const SETUP_GUIDE = {
   intro: 'Para configurar o sincronizar un proyecto completo: revisa primero con la tool de "check" de cada paso; si ya existe algo que coincide por name/type/title, edítalo con la tool de "update"; si no existe, créalo con la de "create". Sigue el orden -- los pasos 4 en adelante referencian ids de los pasos 1-3 (statusId, categoryId, moduleId, distId).',
   steps: [
@@ -66,6 +77,8 @@ Si get_project_context devuelve un proyecto vacío (sin módulos ni tareas), es
 - Si es una idea nueva: llama a get_setup_guide y ofrece un playbook de etapa "pre" (get_stage_playbook + apply_stage_playbook) -- ahí sí basta con eso, el proyecto de verdad no tiene nada más que sincronizar todavía.
 - Si ya existe y está avanzado: NO te limites a update_project ni a las distributions -- eso es solo el primer paso, no el trabajo completo. Llama a get_setup_guide y recorre sus 9 pasos en orden real (estatus/flujo, categorías, infraestructura completa -- servicios Y entornos, no solo distribuciones --, módulos, tareas, ideas, notas, changelog, docs), usando list_* de cada uno antes de crear para no duplicar. No asumas ni dejes vacío lo que no puedas inferir del código -- pregúntale al usuario los servicios/entornos reales, los módulos o áreas de trabajo, y las tareas pendientes reales que tenga en mente. Ofrece el playbook de etapa "build" (no "pre") solo como plantilla de módulo+tareas inicial, no como sustituto de sincronizar el resto.
 
+Al aplicar un playbook con apply_stage_playbook -- sobre todo el de etapa "post" (marketing/contenido) -- nunca asumas herramientas o canales que este proyecto no tiene registrados en Orquestra. Antes de crear tareas de contenido/publicación, llama a list_channels: si viene vacío, la plantilla ya incluye una tarea para conectar canales reales primero -- no la saltees ni generes tareas del tipo "publica en Instagram/LinkedIn/TikTok" para un canal que el proyecto no tiene. Si list_channels SÍ trae canales reales, no te quedes solo con la tarea recordatorio de "programa tu contenido" -- además creá piezas REALES con create_content (un plan de lanzamiento concreto: teaser, anuncio, demo del caso de uso, historia de por qué se construyó, 1-2 testimonios, repartidos entre esos canales) usando siempre un channelId de list_channels, nunca un canal inventado. Mismo criterio para cualquier otra tarea del playbook que dependa de una integración -- si el hueco es real (ej. no hay servicios/distribuciones configurados), la tarea correcta es configurar eso primero, no asumir que ya existe.
+
 Durante el trabajo normal de código, sin que el usuario te lo pida explícitamente y SIN ESPERAR a que lo mencione (si tienes esta tool disponible en la sesión, se usa por default en todo trabajo real, no solo cuando alguien dice "usa Orquestra"):
 - Si te pide una funcionalidad o arreglo real (no una pregunta rápida ni exploración de código sin cambios), revisa con list_tasks/search si ya existe una tarea relacionada; si no, créala con create_task ANTES de empezar a trabajar, en el estatus inicial del proyecto (ver list_statuses). Si no hay un proyecto default configurado para esta carpeta, no te rindas ahí -- usa get_workspace_summary para encontrar el proyecto correcto y pásalo explícito como projectId en cada llamada.
 - Mientras trabajas, mueve la tarea por los estatus reales según avanzas (no la dejes en el inicial hasta el final). Al terminar, muévela a su estatus final con update_task y registra una entrada de changelog con create_changelog_entry -- así el usuario nunca tiene que documentar esto a mano. Si sabes en qué repo real estás trabajando (podés correr "git remote get-url origin" o ya lo sabes por la carpeta), pásalo SIEMPRE como "repo" ("owner/name") -- encontrado real (17 ago 2026): ni el hook local ni el GitHub Action ni la reconciliación de orquestra-infra lo estaban mandando pese a que el campo existe hace rato, así que ninguna entrada automática sabía de qué repo/plataforma venía. Si además la distribución de ese repo ya está identificada (ver list_distributions), pásala en "distributions" -- sin esto el changelog no puede filtrar/agrupar por plataforma.
@@ -76,7 +89,8 @@ Durante el trabajo normal de código, sin que el usuario te lo pida explícitame
 - Si tienes acceso al repo real de una distribución (ej. puedes correr "git remote get-url origin" en ese código), llena repoUrl en create_distribution/update_distribution sin preguntar -- es solo informativo, no requiere credenciales. Esto es distinto de conectar el repo con PAT para el changelog automático (Workspace → Conexiones en orquestra-web): eso sí es un paso deliberado del usuario, con una credencial real -- nunca lo hagas tú solo ni sugieras que ya está conectado por haber llenado repoUrl.
 - Al crear o editar una tarea (o un módulo), llena TODO campo para el que tengas un dato real, no solo title/moduleId/dueDate/comment: type (no lo dejes en el default "feature" si en realidad es un bug/mejora/doc/etc.), tags, stack (tecnologías que genuinamente tocaste), scope (paridad multiplataforma, si aplica), y los campos de código (branch/prNumber/prUrl/prStatus/commitCount/resolvedCommitSha/resolvedCommitMessage/resolvedCommitUrl/resolvedCommitAt) cuando de verdad sepas esos valores (el branch en el que estás trabajando, el PR que abriste, el commit que resolvió la tarea). No dejes un campo en blanco solo porque no es obligatorio -- pero esto no es licencia para inventar: si no tenés el dato real (ej. no hay branch/PR porque el proyecto commitea directo a main), dejalo vacío en vez de rellenarlo con algo plausible pero falso -- mismo criterio que ya se pedía para resolvedCommitSha.
 - Si una tarea tiene más de una actividad o paso concreto, no los amontones como texto corrido en description -- usa el checklist (add_checklist_item, un ítem por actividad, opcionalmente con responsable) para que cada paso se pueda marcar independientemente. description queda para el contexto/propósito general de la tarea (el qué y el por qué), no como lista de pasos. Si estás editando una tarea existente cuya description ya creció así, migra esos puntos a checklist en vez de seguir agregando ahí.
-- No todas las tareas necesitan una corrida de QA -- clasifica antes de disparar una: cambios que afectan comportamiento real (features, bugs, UI, lógica de negocio, endpoints/API) sí la necesitan; cambios que no alteran comportamiento (docs, comentarios, refactors sin cambio funcional, config/tooling interno, notas/reuniones/ideas) no. Si decides que sí, revisa primero con list_qa_agents que exista un agente para el stack que tocaste (si no hay ninguno, créalo con create_qa_agent -- necesita una máquina ya emparejada, ver Workspace → QA) y llama a create_qa_run en la rama real de ese trabajo (manda taskId si el trabajo era de una tarea puntual -- si el agente tiene la revisión con IA activada, la acota a eso en vez de "revisa todo el proyecto"), dejando la tarea en "En revisión" -- NUNCA la muevas a "Listo" ni digas que "QA lo revisó" sin haber confirmado con get_qa_run un estatus terminal "passed" de verdad (las corridas son asíncronas, tardan minutos en otra máquina). Si tarda, dile al usuario que quedó en cola (con el runId) y que confirmas cuando termine -- no lo des por hecho nunca.
+- Al cerrar una tarea en la que trabajaste de verdad (o al final de una sesión de trabajo real sobre ella), registrá las horas con log_time -- el tiempo REAL que llevó ese trabajo en esta sesión (aproximalo con honestidad: minutos de trabajo real, no la duración del chat ni la estimación de la tarea), con una nota corta de qué se hizo. Ese registro alimenta "Horas del equipo" en Inversión de Contenido y es la única forma de que el costo real del proyecto no dependa de que el usuario lo cargue a mano. No lo inventes ni lo infles; si genuinamente no podés estimar el tiempo de la sesión, no registres nada.
+- No todas las tareas necesitan una corrida de QA -- clasifica antes de disparar una: cambios que afectan comportamiento real (features, bugs, UI, lógica de negocio, endpoints/API) sí la necesitan; cambios que no alteran comportamiento (docs, comentarios, refactors sin cambio funcional, config/tooling interno, notas/reuniones/ideas) no. Si decides que sí, revisa primero con list_agents que exista un agente (kind="qa") para el stack que tocaste (si no hay ninguno, créalo con create_agent -- necesita una máquina ya emparejada, ver Workspace → Máquinas) y llama a create_agent_run en la rama real de ese trabajo (manda taskId si el trabajo era de una tarea puntual -- si el agente tiene la revisión con IA activada, la acota a eso en vez de "revisa todo el proyecto"), dejando la tarea en "En revisión" -- NUNCA la muevas a "Listo" ni digas que "QA lo revisó" sin haber confirmado con get_agent_run un estatus terminal "passed" de verdad (las corridas son asíncronas, tardan minutos en otra máquina). Si tarda, dile al usuario que quedó en cola (con el runId) y que confirmas cuando termine -- no lo des por hecho nunca.
 
 Si el usuario pide "sincronizar"/"revisar que todo esté al día"/"verificar el proyecto" (o algo equivalente -- una auditoría manual, no el trabajo normal de arriba), hacé una "revisión de sincronización" completa, de cero, no un vistazo rápido:
 1. Llamá a get_sync_report -- devuelve lo objetivo (tareas sin moduleId, tareas activas sin dueDate, referencias huérfanas a un módulo/categoría/tarea/estatus que ya no existe) y activeTasksSnapshot (TODAS las tareas activas, no solo las incompletas).
@@ -93,7 +107,7 @@ Si estás iniciando una sesión de trabajo real en un proyecto que YA tiene cód
 
 export function createServer() {
   const config = loadConfig()
-  const server = new McpServer({ name: 'orquestra-mcp', version: '1.0.0' }, { instructions: SERVER_INSTRUCTIONS })
+  const server = new McpServer({ name: 'orquestra-mcp', version: '1.14.0' }, { instructions: SERVER_INSTRUCTIONS })
 
   function resolveProjectId(projectId) {
     if (config.defaultProjectId) return config.defaultProjectId
@@ -568,6 +582,127 @@ export function createServer() {
     }
   )
 
+  // Adjuntos (imágenes + código) en tasks/notes/ideas/docs -- mismo criterio
+  // que checklist: entityType/entityId van en el path (dos segmentos
+  // dinámicos), así que server.registerTool directo. Ver
+  // orquestra-infra/functions/api/lib/attachments.mjs.
+  server.registerTool(
+    'list_attachments',
+    {
+      description: 'Lista los adjuntos (imágenes + código) de una task/note/idea/doc de Orquestra.',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        entityType: z.enum(ATTACHMENT_ENTITY_TYPES).describe('Tipo de entidad dueña de los adjuntos'),
+        entityId: z.string().describe('ID de la entidad (task/note/idea/doc)'),
+      },
+    },
+    async ({ projectId, entityType, entityId }) => {
+      try {
+        const plural = ATTACHMENT_ENTITY_PATH[entityType]
+        const data = await apiGet(config, `/v1/${plural}/${entityId}/attachments`, { projectId: resolveProjectId(projectId) })
+        return textResult(data)
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  // filePath vs content son alternativas -- filePath es lo normal para
+  // evidencia real (una captura, o un archivo de código ya en el repo);
+  // content sirve para pegar un snippet generado en la sesión sin haberlo
+  // guardado a un archivo. NUNCA se acepta base64 en el input: para una
+  // imagen, este server lee los bytes él mismo (tiene filesystem real) y
+  // los sube directo a S3 -- mandarlos por el input de la tool los metería
+  // en el contexto del modelo, carísimo e innecesario.
+  server.registerTool(
+    'add_attachment',
+    {
+      description: 'Adjunta evidencia (una imagen o un pedazo de código) a una task/note/idea/doc de Orquestra. Manda EXACTAMENTE uno de filePath (ruta local -- una imagen png/jpg/jpeg/gif/webp se sube a S3, cualquier otra extensión se lee como texto/código) o content (texto/código directo, sin tocar el filesystem). Nunca mandes bytes de imagen en base64 dentro de content -- usa filePath para que este server los suba él mismo.',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        entityType: z.enum(ATTACHMENT_ENTITY_TYPES).describe('Tipo de entidad a la que se adjunta'),
+        entityId: z.string().describe('ID de la entidad (task/note/idea/doc)'),
+        filePath: z.string().optional().describe('Ruta local a un archivo -- imagen (png/jpg/jpeg/gif/webp) o código/texto.'),
+        content: z.string().optional().describe('Texto/código a adjuntar directo, sin leer un archivo.'),
+        language: z.string().optional().describe('Label libre del lenguaje del snippet (ej. "python", "diff") -- solo informativo, no tokeniza (Orquestra no resalta sintaxis).'),
+        fileName: z.string().optional().describe('Nombre a mostrar -- si no se manda, sale de filePath o de un default genérico.'),
+        caption: z.string().optional().describe('Descripción corta de la evidencia (ej. "output del test que falló").'),
+      },
+    },
+    async ({ projectId, entityType, entityId, filePath, content, language, fileName, caption }) => {
+      try {
+        if (!filePath && !content) throw new Error('Manda filePath o content')
+        if (filePath && content) throw new Error('Manda solo uno de filePath o content -- no los dos')
+        const resolvedProjectId = resolveProjectId(projectId)
+        const plural = ATTACHMENT_ENTITY_PATH[entityType]
+
+        let body
+        if (content) {
+          if (content.length > MAX_ATTACHMENT_CODE_CHARS) {
+            throw new Error(`El snippet supera el máximo de ${MAX_ATTACHMENT_CODE_CHARS} caracteres`)
+          }
+          body = { kind: 'code', content, language, fileName: fileName || 'snippet.txt', caption }
+        } else {
+          const stat = statSync(filePath)
+          const ext = path.extname(filePath).slice(1).toLowerCase()
+          const mime = ATTACHMENT_IMAGE_MIME_BY_EXT[ext]
+          const resolvedFileName = fileName || path.basename(filePath)
+          if (mime) {
+            if (stat.size > MAX_ATTACHMENT_IMAGE_BYTES) {
+              throw new Error(`La imagen supera el máximo de ${MAX_ATTACHMENT_IMAGE_BYTES / 1024 / 1024}MB`)
+            }
+            const buffer = readFileSync(filePath)
+            const { uploadUrl, key } = await apiPost(config, '/v1/attachments/upload-url', {
+              projectId: resolvedProjectId, entityType: plural, entityId,
+              fileName: resolvedFileName, fileType: mime, fileSize: stat.size,
+            })
+            await putToPresignedUrl(uploadUrl, buffer, mime)
+            body = { kind: 'image', key, fileName: resolvedFileName, fileType: mime, fileSize: stat.size, caption }
+          } else {
+            const text = readFileSync(filePath, 'utf8')
+            if (text.length > MAX_ATTACHMENT_CODE_CHARS) {
+              throw new Error(`El archivo supera el máximo de ${MAX_ATTACHMENT_CODE_CHARS} caracteres`)
+            }
+            body = { kind: 'code', content: text, language, fileName: resolvedFileName, caption }
+          }
+        }
+
+        const data = await apiPost(config, `/v1/${plural}/${entityId}/attachments`, { projectId: resolvedProjectId, ...body })
+        return textResult(data)
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  // Segunda excepción real a "creación + edición, nunca borrado" (junto a
+  // delete_checklist_item, ver CLAUDE.md) -- decisión consciente de José:
+  // un agente puede subir evidencia equivocada (screenshot que no era,
+  // snippet viejo) y conviene que la pueda limpiar sin depender de un
+  // humano. Borra también el objeto en S3 si el adjunto era una imagen
+  // (ver deleteAttachment en attachments.mjs de orquestra-infra).
+  server.registerTool(
+    'delete_attachment',
+    {
+      description: 'Borra un adjunto (imagen o código) de una task/note/idea/doc de Orquestra -- limpia también el objeto en S3 si era una imagen. Segunda excepción a "nunca borrado" (junto a delete_checklist_item) -- usalo para limpiar evidencia subida por error, no como reemplazo de mantener historial.',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        entityType: z.enum(ATTACHMENT_ENTITY_TYPES).describe('Tipo de entidad dueña del adjunto'),
+        entityId: z.string().describe('ID de la entidad (task/note/idea/doc)'),
+        attachmentId: z.string().describe('ID del adjunto a borrar (ver list_attachments)'),
+      },
+    },
+    async ({ projectId, entityType, entityId, attachmentId }) => {
+      try {
+        const plural = ATTACHMENT_ENTITY_PATH[entityType]
+        const data = await apiDelete(config, `/v1/${plural}/${entityId}/attachments`, { projectId: resolveProjectId(projectId), id: attachmentId })
+        return textResult(data)
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
   server.registerTool(
     'convert_checklist_item_to_task',
     {
@@ -592,6 +727,51 @@ export function createServer() {
     }
   )
 
+  // Horas de una tarea (22 ago 2026, tarea "Time-tracking real") -- mismo
+  // criterio de registro directo que las tools de checklist (taskId en el
+  // path). Solo listar + registrar: corregir/borrar una entrada es de la
+  // web, este canal no borra (ver gotcha "nunca borrado" en CLAUDE.md).
+  server.registerTool(
+    'list_time_entries',
+    {
+      description: 'Lista los registros de horas trabajadas de una tarea de Orquestra (horas, fecha, nota, quién). El total ya vive desnormalizado en la tarea (hoursLogged) -- usa esta tool solo si necesitás el detalle entrada por entrada.',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        taskId: z.string().describe('ID de la tarea'),
+      },
+    },
+    async ({ projectId, taskId }) => {
+      try {
+        const data = await apiGet(config, `/v1/tasks/${taskId}/time`, { projectId: resolveProjectId(projectId) })
+        return textResult(data)
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  server.registerTool(
+    'log_time',
+    {
+      description: 'Registra horas trabajadas en una tarea de Orquestra -- el time-tracking honesto que alimenta "Horas del equipo" en Inversión de Contenido (horas del mes × tarifa del proyecto). Registrá el tiempo REAL de trabajo en la tarea (el de esta sesión, o el que el usuario te diga), nunca un número inventado ni la estimación de la tarea (estimatedDays es otra cosa). La entrada queda atribuida al miembro del token (para un agente, "agent_<slug>").',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        taskId: z.string().describe('ID de la tarea en la que se trabajó'),
+        hours: z.number().positive().describe('Horas trabajadas, > 0 -- admite fracciones (0.5 = media hora)'),
+        date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Formato esperado: YYYY-MM-DD').optional().describe('El día en que se TRABAJÓ (no cuándo se registra) -- default hoy. Es el corte mensual de Inversión.'),
+        note: z.string().optional().describe('Qué se hizo en esas horas, texto corto'),
+      },
+    },
+    async ({ projectId, taskId, ...body }) => {
+      try {
+        const data = await apiPost(config, `/v1/tasks/${taskId}/time`, { projectId: resolveProjectId(projectId), ...body })
+        return textResult(data)
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
   registerCreate(
     'create_idea',
     '/v1/ideas',
@@ -876,6 +1056,40 @@ export function createServer() {
     }
   )
 
+  // Convertir nota → tarea (23 ago 2026) -- mismo patrón que
+  // convert_idea_to_task. Compuesta: POST /v1/notes/{id}/convert-to-task en
+  // orquestra-infra crea la tarea (reusando createTask tal cual, mismas
+  // reglas que create_task) Y en el mismo paso liga los dos lados: la nota
+  // queda con taskId (ya existía, antes solo se llenaba a mano) y la tarea
+  // nueva queda con sourceNoteId (campo nuevo en tasks.json) apuntando de
+  // vuelta a la nota que la originó. La nota NUNCA se borra -- queda
+  // trazable. No se puede convertir una nota que ya tiene taskId.
+  server.registerTool(
+    'convert_note_to_task',
+    {
+      description: 'Convierte una nota en una tarea real -- crea la tarea (mismas reglas que create_task: moduleId y dueDate son obligatorios, de la nota o de este llamado) y liga los dos lados: la nota queda con taskId ("Se convirtió en la tarea X") y la tarea nueva queda con sourceNoteId ("Proviene de la nota X"). La nota nunca se borra. No se puede convertir una nota que ya fue convertida antes.',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        noteId: z.string().describe('Nota a convertir -- ver list_notes/search para encontrar su id.'),
+        title: z.string().optional().describe('Default: el título de la nota.'),
+        description: z.string().optional().describe('Default: el body de la nota.'),
+        moduleId: z.string().optional().describe('Solo si la nota no tiene moduleId propio -- si no existe uno relacionado, revisá list_modules/create_module primero.'),
+        dueDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Formato esperado: YYYY-MM-DD').describe('OBLIGATORIO -- las notas no tienen dueDate propio, calculala con criterio real (prioridad/tamaño del trabajo), nunca un valor arbitrario.'),
+        priority: z.enum(TASK_PRIORITIES).optional().describe('Default: medium -- las notas no tienen priority propia.'),
+      },
+    },
+    async ({ projectId, noteId, title, description, moduleId, dueDate, priority }) => {
+      try {
+        const data = await apiPost(config, `/v1/notes/${noteId}/convert-to-task`, {
+          projectId: resolveProjectId(projectId), title, description, moduleId, dueDate, priority,
+        })
+        return textResult(data)
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
   registerCreate(
     'create_doc',
     '/v1/docs',
@@ -1224,39 +1438,50 @@ export function createServer() {
     translationOf: z.string().optional(),
   })
 
-  // ═══ QA (módulo de runners -- ver orquestra-qa-agent) ═══════════════════════
+  // ═══ AGENTES (módulo de runners, generalizado 22 ago 2026 desde "QA" --
+  // ver orquestra-qa-agent) ═══════════════════════════════════════════════════
   // Asíncronas: una corrida puede tardar minutos en otra máquina. Ver
   // SERVER_INSTRUCTIONS para la regla de no asumir "passed" sin confirmar.
   //
-  // Un agente = un stack de este proyecto (web/ios/android/node/nestjs)
-  // atado a una máquina (runnerId) y una ruta de checkout en ella
-  // (localPath) -- "orquestra-qa-agent setup" crea/actualiza el suyo solo;
-  // estas tools existen para revisarlos/crearlos desde acá también.
-  const QA_AGENT_STACKS = ['web', 'ios', 'android', 'node', 'nestjs']
-
-  registerRead('list_qa_agents', '/v1/qaAgents',
-    'Lista los agentes de QA (stack+máquina+ruta local) configurados en un proyecto. Úsala antes de create_qa_agent o de create_qa_run con stack, para saber si ya existe uno.',
-    {}, (args, projectId) => ({ projectId }))
-
-  registerCreate('create_qa_agent', '/v1/qaAgents', 'Crea un agente de QA: asocia un stack de este proyecto a una máquina (runner, ver Workspace → QA) y una ruta de checkout en ESA máquina.', {
+  // Un agente tiene un `kind` atado a una máquina (runnerId); los 3 kinds de
+  // hoy (23 ago 2026: qa/security/performance) exigen stack+localPath (un
+  // checkout real en esa máquina), y performance además perfUrl (URL viva
+  // contra la que corre Lighthouse). Los 3 solo tienen lógica real para
+  // stack="web" por ahora. "orquestra-qa-agent setup" crea/actualiza solo
+  // agentes kind="qa" -- security/performance se crean a mano acá o desde
+  // la web.
+  const AGENT_KINDS = ['qa', 'security', 'performance']
+  const AGENT_STACKS = ['web', 'ios', 'android', 'node', 'nestjs']
+
+  registerRead('list_agents', '/v1/agents',
+    'Lista los agentes (kind+máquina+stack+ruta local) configurados en un proyecto. Úsala antes de create_agent o de create_agent_run con stack, para saber si ya existe uno.',
+    { kind: z.enum(AGENT_KINDS).optional().describe('Filtra por kind: "qa" (lint/test/build/E2E), "security" (npm audit + gitleaks) o "performance" (build size + Lighthouse)') },
+    (args, projectId) => ({ projectId }))
+
+  registerCreate('create_agent', '/v1/agents', 'Crea un agente: asocia un kind ("qa" | "security" | "performance") a una máquina (runner, ver Workspace → Máquinas), un stack de este proyecto y una ruta de checkout en ESA máquina. kind="performance" además necesita perfUrl.', {
     name: z.string().describe('Nombre a mostrar, ej. "Agente web"'),
-    stack: z.enum(QA_AGENT_STACKS),
-    runnerId: z.string().describe('ID de la máquina emparejada -- ver list_qa_agents o Workspace → QA'),
-    localPath: z.string().describe('Ruta absoluta del checkout en esa máquina'),
+    kind: z.enum(AGENT_KINDS).default('qa').describe('"qa" (lint/test/build/E2E), "security" (npm audit + gitleaks) o "performance" (build size + Lighthouse) -- default "qa"'),
+    runnerId: z.string().describe('ID de la máquina emparejada -- ver list_agents o Workspace → Máquinas'),
+    stack: z.enum(AGENT_STACKS).optional().describe('Requerido para los 3 kinds -- security/performance solo tienen lógica real para "web" hoy'),
+    localPath: z.string().optional().describe('Requerido para los 3 kinds -- ruta absoluta del checkout en esa máquina'),
     branch: z.string().optional().describe('Rama de este agente -- default "main" si no se manda'),
     distributionId: z.string().optional().describe('Distribución vinculada (repo/fuente de conocimiento)'),
     enabled: z.boolean().optional(),
     createTasks: z.boolean().optional().describe('Si los fallos de este agente generan tareas automáticas -- default true'),
     openStatusId: z.string().optional().describe('Estatus donde se abren los bugs de este agente -- default: estatus inicial del proyecto'),
     closeStatusId: z.string().optional().describe('Estatus donde se mueven los bugs de este agente al cerrarse solos -- default: primer estatus final'),
-    testUserEmail: z.string().optional().describe('Cuenta de prueba DEDICADA (no una credencial real) que la revisión con IA puede usar para iniciar sesión y revisar pantallas autenticadas'),
+    testUserEmail: z.string().optional().describe('Específico de kind="qa" -- cuenta de prueba DEDICADA (no una credencial real) que la revisión con IA puede usar para iniciar sesión y revisar pantallas autenticadas'),
     testUserPassword: z.string().optional().describe('Password de testUserEmail'),
-    plannedRunAt: z.string().optional().describe('YYYY-MM-DD -- recordatorio manual de "próxima corrida planeada". QA no tiene scheduling real (todo trigger es manual/push): esto NO dispara ninguna corrida sola, solo alimenta el calendario global.'),
+    plannedRunAt: z.string().optional().describe('YYYY-MM-DD -- recordatorio manual de "próxima corrida planeada". Ningún kind tiene scheduling real (todo trigger es manual/push): esto NO dispara ninguna corrida sola, solo alimenta el calendario global.'),
+    perfUrl: z.string().optional().describe('Requerido si kind="performance" -- URL viva (ej. staging/prod) contra la que corre Lighthouse'),
+    maxBundleSizeKb: z.number().optional().describe('Específico de kind="performance" -- umbral en KB para el paso de tamaño de build (default 5000)'),
+    minPerfScore: z.number().optional().describe('Específico de kind="performance" -- score mínimo de Lighthouse (0-100) para pasar (default 50)'),
   })
 
-  registerUpdate('update_qa_agent', '/v1/qaAgents', 'Edita un agente de QA existente.', {
+  registerUpdate('update_agent', '/v1/agents', 'Edita un agente existente.', {
     name: z.string().optional(),
-    stack: z.enum(QA_AGENT_STACKS).optional(),
+    kind: z.enum(AGENT_KINDS).optional(),
+    stack: z.enum(AGENT_STACKS).optional(),
     runnerId: z.string().optional(),
     localPath: z.string().optional(),
     branch: z.string().optional(),
@@ -1267,32 +1492,36 @@ export function createServer() {
     closeStatusId: z.string().optional(),
     testUserEmail: z.string().optional().describe('Cuenta de prueba DEDICADA (no una credencial real) para que la revisión con IA inicie sesión'),
     testUserPassword: z.string().optional(),
-    plannedRunAt: z.string().optional().describe('YYYY-MM-DD -- ver create_qa_agent.'),
+    plannedRunAt: z.string().optional().describe('YYYY-MM-DD -- ver create_agent.'),
+    perfUrl: z.string().optional().describe('Ver create_agent -- específico de kind="performance"'),
+    maxBundleSizeKb: z.number().optional(),
+    minPerfScore: z.number().optional(),
   })
 
-  registerCreate('create_qa_run', '/v1/qa/runs', 'Dispara una corrida de QA (lint/tests/build/E2E según el stack) en la rama indicada. Necesita al menos un agente de QA activo para el stack (o falla explícito -- ver list_qa_agents/create_qa_agent). La corrida queda "queued" -- nunca asumas que pasó, confirma con get_qa_run.', {
-    agentId: z.string().optional().describe('Agente específico -- si se manda, gana sobre stack'),
+  registerCreate('create_agent_run', '/v1/agent-runs', 'Dispara una corrida de agente (qa: lint/tests/build/E2E; security: npm audit + gitleaks; performance: build size + Lighthouse) en la rama indicada. Necesita al menos un agente activo para el stack (o falla explícito -- ver list_agents/create_agent). La corrida queda "queued" -- nunca asumas que pasó, confirma con get_agent_run.', {
+    agentId: z.string().optional().describe('Agente específico -- si se manda, gana sobre stack/kind'),
     branch: z.string().optional().describe('Rama a probar -- default: la del agente, o "main"'),
     commit: z.string().optional(),
     trigger: z.enum(['manual', 'push', 'schedule']).optional().describe('Default: manual'),
-    stack: z.string().optional().describe('Stack a probar (ej. "web", "ios", "android") -- resuelve contra los agentes activos de ese stack. Falla si hay 0 (créalo con create_qa_agent) o más de 1 (usa agentId).'),
+    stack: z.string().optional().describe('Stack a probar (ej. "web", "ios", "android") -- resuelve contra los agentes activos de ese stack. Falla si hay 0 (créalo con create_agent) o más de 1 (usa agentId o suma kind para desambiguar).'),
+    kind: z.enum(AGENT_KINDS).optional().describe('Desambigua junto con stack cuando el proyecto tiene más de un agente para el mismo stack (ej. un "qa" y un "security", ambos "web") -- sin esto, resuelve por stack solo y falla explícito si hay más de uno.'),
     runnerId: z.string().optional().describe('Máquina específica -- si se manda, gana sobre la del agente resuelto'),
     taskId: z.string().optional().describe('Acota la revisión con IA (si el agente la tiene activada) a esta tarea en vez de "revisa todo el proyecto" -- útil para pedir "corre QA de esto que acabo de hacer". Sin efecto en los pasos de script (lint/test/build corren igual siempre). No combinar con moduleId.'),
     moduleId: z.string().optional().describe('Igual que taskId pero acota a un módulo completo. No combinar con taskId.'),
   })
 
   server.registerTool(
-    'get_qa_run',
+    'get_agent_run',
     {
-      description: 'Consulta el estatus real de una corrida de QA por id (queued|running|passed|failed|error|cancelled, con steps y summary). Única forma válida de confirmar un resultado -- nunca lo des por hecho.',
+      description: 'Consulta el estatus real de una corrida de agente por id (queued|running|passed|failed|error|cancelled, con steps y summary -- steps no trae el log completo de cada paso, solo status/seconds). Única forma válida de confirmar un resultado -- nunca lo des por hecho.',
       inputSchema: {
-        runId: z.string().describe('ID de la corrida, devuelto por create_qa_run'),
+        runId: z.string().describe('ID de la corrida, devuelto por create_agent_run'),
         projectId: z.string().optional().describe(PROJECT_ID_DESC),
       },
     },
     async ({ runId, projectId }) => {
       try {
-        const data = await apiGet(config, `/v1/qa/runs/${runId}`, { projectId: resolveProjectId(projectId) })
+        const data = await apiGet(config, `/v1/agent-runs/${runId}`, { projectId: resolveProjectId(projectId) })
         return textResult(data)
       } catch (err) {
         return errorResult(err)

package/src/stages.mjs

@@ -71,12 +71,13 @@ export const PLAYBOOKS = {
       { title: 'Preparar assets de tienda (ASO): capturas, descripción, keywords', description: '5-8 capturas que cuenten una historia (no pantallas sueltas), descripción con el pitch arriba, y keywords que tu público realmente busca.', type: 'business', priority: 'high', tags: ['marketing', 'aso'], offsetDays: 5 },
       { title: 'Publicar landing con captura de correos', description: 'Una página: pitch, 3 beneficios, capturas y un CTA (descargar o dejar correo). Los correos capturados son tu canal propio para siempre.', type: 'feature', priority: 'high', tags: ['marketing', 'landing'], offsetDays: 7 },
       { title: 'Configurar analytics de adquisición', description: 'Fuentes de tráfico, conversión de visita→registro→activación. Necesitas saber DE DÓNDE llegan los usuarios que sí se quedan.', type: 'tech', priority: 'medium', tags: ['analytics', 'adquisición'], offsetDays: 8 },
-      { title: 'Plan de contenido de lanzamiento (2 semanas)', description: 'Programa las publicaciones en la sección Contenido: teaser, anuncio, demo del caso de uso principal, historia de por qué lo construiste, testimonios de beta testers.', type: 'business', priority: 'high', tags: ['marketing', 'contenido'], offsetDays: 10 },
+      { title: 'Conectar tus canales reales de contenido', description: 'Antes de programar nada: registra en Contenido → Cuentas conectadas los canales donde de verdad vas a publicar (redes, blog, newsletter). El plan de contenido de abajo solo sirve con canales reales, no uno genérico — si personalizas este playbook con IA y ya tienes canales conectados, te genera piezas reales directo.', type: 'tech', priority: 'high', tags: ['marketing', 'contenido'], offsetDays: 9 },
+      { title: 'Plan de contenido de lanzamiento (2 semanas)', description: 'Con tus canales ya conectados (tarea anterior), programa en Contenido: teaser, anuncio, demo del caso de uso principal, historia de por qué lo construiste, testimonios de beta testers — uno por canal real, no una lista genérica.', type: 'business', priority: 'high', tags: ['marketing', 'contenido'], offsetDays: 10 },
       { title: 'Lanzar en canales: Product Hunt, comunidades y redes', description: 'Elige 3 canales donde vive tu público (PH, subreddits, grupos de FB/Discord, foros del nicho). Un post honesto de creador funciona mejor que uno de venta.', type: 'business', priority: 'high', tags: ['marketing', 'lanzamiento'], offsetDays: 14 },
       { title: 'Contactar 10 personas con audiencia en el nicho', description: 'Creators, newsletters, podcasts o prensa pequeña del tema. Mensaje corto y personalizado + acceso gratis. Con que respondan 2, ganaste.', type: 'followup', priority: 'medium', tags: ['marketing', 'outreach'], offsetDays: 16 },
       { title: 'Activar loop de feedback de usuarios reales', description: 'Un canal permanente: encuesta in-app, correo de bienvenida que pregunta "¿qué te trajo aquí?", o botón de sugerencias. Todo aterriza en Ideas.', type: 'improvement', priority: 'medium', tags: ['feedback'], offsetDays: 18 },
       { title: 'Definir y medir activación y retención (D1 / D7 / D30)', description: 'Activación: % que llega al momento de valor. Retención: % que regresa al día 1, 7 y 30. Estos números te dicen si tienes producto o solo descargas.', type: 'business', priority: 'medium', tags: ['métricas'], offsetDays: 21 },
-      { title: 'Ritmo de contenido post-lanzamiento (3 publicaciones/semana)', description: 'El lanzamiento es un día; el crecimiento es constancia. Deja programadas en Contenido las siguientes 2 semanas: tips de uso, casos, mejoras del changelog.', type: 'business', priority: 'medium', tags: ['marketing', 'contenido'], offsetDays: 24 },
+      { title: 'Ritmo de contenido post-lanzamiento (3 publicaciones/semana)', description: 'El lanzamiento es un día; el crecimiento es constancia. Deja programadas en Contenido las siguientes 2 semanas: tips de uso, casos, mejoras del changelog — repartidas entre tus canales reales conectados.', type: 'business', priority: 'medium', tags: ['marketing', 'contenido'], offsetDays: 24 },
       { title: 'Publicar release notes / changelog público v1', description: 'Convierte tu Changelog en comunicación: qué hay de nuevo, en lenguaje de usuario. Cada release es una excusa para volver a aparecer.', type: 'docs', priority: 'low', tags: ['changelog'], offsetDays: 26 },
       { title: 'Revisión semanal de métricas y próximos pasos', description: 'Reunión recurrente (aunque seas solo tú): adquisición, activación, retención, top feedback. Decide UNA mejora prioritaria por semana.', type: 'meeting', priority: 'medium', tags: ['métricas', 'ritmo'], offsetDays: 28 },
     ],