aleleba
18efe3fa5d
Diagnosis (audited gate5 full-mode transcripts, PNGs, and holdout payloads): the dominant failure mode was NOT rubro/content coverage but a tool-call formatting bug -- after diagnosing an exception, the model often writes its retry as literal <tool_call> XML text embedded in reasoning instead of a structured call, so it's silently dropped (9/10 gate5 full-mode prompts hit this on their final captured turn). Reasoning length before a tool call correlates with the failure (malformed-turn mean 1895 chars vs 364 for well-formed turns), while the training mix's own tool-calling turns never exceed 1630 chars and export_shape turns never exceed 485. Corrective seeds (group D, grupo 'D', short 1-3 sentence diagnosis + immediate well-formed retry, to avoid reinforcing long-reasoning risk): - 9 seeds across fresh rubros (lavanderia, zapateria, optica, jugueteria, papeleria, peluqueria, floreria, heladeria, cerrajeria) covering distinct real API errors: .color on Text, addFlexLayout on non-Board, findShapeById 2-arg, createText() no-arg, textAlign, typography.setFont, createBoolean null, appendChild no-arg, uploadMediaUrl network rejection. - 4 seeds reinforcing uploadMediaUrl over the exact penpot.importImage variant the model actually invents (distinct from the one existing seed, which only taught the penpotUtils.importImage variant) -- rubros: relojeria, guarderia infantil, agencia de viajes, kiosco. Deliberately avoid ferreteria/gimnasio/veterinaria/panaderia: reserved for the held-out generalization probe (separate from the frozen gate 5). Added the newly-verified error strings (t.color, penpot.importImage, addFlexLayout-on-non-Board) to penpot_errors.md -- all captured live from this phase's own gate 5 full-mode run, not fabricated. Rebuilt train_lora2.jsonl (901)/eval_lora2.jsonl (99)/calibration_v2.jsonl from the 138-seed corpus (07_build_lora2_mix.py) and validated (06_validate_dataset.py, 0 exceptions, 0 secrets, max 3271 tokens).
11 KiB
Penpot MCP — strings de error reales
Mensajes de error literales que devuelve el servidor MCP de Penpot cuando un execute_code falla.
Por qué existe este archivo. El grupo D de data/raw/seeds/penpot.jsonl (6 seeds de auto-corrección)
entrena al modelo a diagnosticar y recuperarse de errores. Si el mensaje de error de un seed es
inventado, el modelo aprende a reaccionar a un string que nunca va a ver. Este archivo es la
allow-list de mensajes de error: scripts/07_lint_penpot_code.py verifica que todo content de un
mensaje tool que representa un error sea un string presente acá, verbatim.
Procedencia. Los mensajes de las secciones 1-4 fueron capturados en vivo por la sesión madre el
2026-07-30, contra el archivo real del usuario, ejecutando el código de la columna "Disparador" vía
mcp__penpot__execute_code. Están registrados en PLAN.md § "La API verificada" y en la página de
Docmost de la Fase 6 § "Diagnóstico". Los de la sección 5 son mensajes estándar del runtime de
JavaScript (V8/SpiderMonkey), deterministas dada la expresión que los produce.
Nota operativa (2026-07-30): al intentar re-capturar estos strings durante el paso 6.1.3, el
servidor MCP devolvió No Penpot plugin instances are currently connected. Please ensure the plugin is running and connected. — el plugin del usuario no está conectado. Los mensajes de abajo se conservan
tal como los verificó la sesión madre; la re-verificación en vivo queda pendiente y se hace junto
con el baseline de la puerta 5 (paso 6.3.17), que también requiere el plugin conectado. Ningún seed
puede usar un string de error ausente de este archivo.
1. Propiedad inexistente sobre un objeto no extensible
El objeto Text (y en general los shapes) no es extensible: asignar una propiedad que no está en
la interfaz lanza, y la excepción aborta todo el execute_code, no solo esa línea.
| Disparador | Mensaje verbatim |
|---|---|
text.textAlign = 'center' |
Cannot add property textAlign, object is not extensible |
text.color = '#...' |
Cannot add property color, object is not extensible |
Forma del mensaje, generalizable: Cannot add property <nombre>, object is not extensible.
text.color (capturado en vivo, puerta 5 modo full, paso 6.4.25, prompts g5-06-landing-pizzeria y
g5-01-boton-primario, 2026-08-03): el modelo asume que Text tiene una propiedad color de nivel
superior (analogía con CSS) en vez de usar fills. Es el mismo mecanismo que textAlign —el objeto
Text no es extensible— pero para una propiedad distinta, y hoy no hay ningún seed que lo enseñe (el
lint ya lo detecta como patrón prohibido, cero ejemplos de recuperación en el corpus).
La propiedad correcta para alineación horizontal de texto es align
('left' \| 'center' \| 'right' \| 'justify'). Ver penpot_api_docs.md Captura 4.
Este es el error más caro del conjunto, porque el modelo suele escribir textAlign por analogía con
CSS, en medio de un payload de 80 líneas que construye una landing entera: la excepción tira abajo la
composición completa, no solo el título.
2. Función inexistente en el runtime
| Disparador | Mensaje verbatim |
|---|---|
penpotUtils.importImage(url) |
penpotUtils.importImage is not a function |
penpot.importImage(url) |
penpot.importImage is not a function |
typography.setFont(font) sobre un LibraryTypography |
t.setFont is not a function |
penpot.importImage (capturado en vivo, puerta 5 modo full y holdout, paso 6.4.25, 2026-08-03):
variante distinta de la ya documentada penpotUtils.importImage — el modelo la invoca directamente
sobre el objeto penpot (no sobre penpotUtils), en 1 de los 10 prompts de la puerta 5 modo full
(g5-03-card-producto) y en 4 de los 60 del holdout, siempre en prompts que piden "una foto real
traída de una URL". El único seed de recuperación existente (grupo D) enseña la variante
penpotUtils.importImage, no ésta — de ahí que el modelo no generalizara la lección.
Tres casos distintos, y la diferencia importa pedagógicamente:
penpotUtils.importImagenunca existió: no está en la Captura 1 depenpot_api_docs.md, niimport_imageestá entre las herramientas MCP de este deployment (verdata/schemas/penpot.json). El overview la menciona en prosa (Use the export_shape and import_image tools), lo cual es un anzuelo real: la lista de herramientas que recibe el modelo es autoritativa, la prosa del overview no. La ruta correcta esawait penpot.uploadMediaUrl(name, url).typography.setFontsí está en el tipo (penpot_api_docs.mdCaptura 26) pero no existe en el runtime de esta versión. Es el caso canónico de "la documentación no es el runtime": hay que setear las propiedades de tipografía una por una (fontFamily,fontSize,fontWeight,lineHeight). Notar que el mensaje dicet.setFont, con el nombre de la variable local — notypography.setFont.
3. Uso de un retorno null sin chequear
La familia de errores más frecuente y la que produce la falla reportada por el usuario. Todas las
llamadas de creación y de búsqueda pueden devolver null; usar el resultado sin chequearlo produce un
TypeError en la línea siguiente, lo que hace que el stack apunte al síntoma y no a la causa.
| Disparador | Mensaje verbatim |
|---|---|
const t = penpot.createText(); t.characters = 'Hola' |
Cannot set properties of null (setting 'characters') |
const s = penpotUtils.findShapeById(page, id); s.x = 10 |
Cannot read properties of null (reading 'x') |
const s = penpotUtils.findShapeById(idInexistente); return s.fills |
Cannot read properties of null (reading 'fills') |
const b = penpot.createBoolean('union', []); b.name = 'x' |
Cannot set properties of null (setting 'name') |
const r = penpot.createRectangle(); const f = r.addFlexLayout(); f.dir = 'row' |
Cannot set properties of null (setting 'dir') |
addFlexLayout() sobre un Rectangle (capturado en vivo, puerta 5 modo full, g5-02-navbar-flex,
2026-08-03): addFlexLayout() solo existe en Board. Llamarlo sobre un Rectangle (o sobre un
Board que ya tiene un layout asignado) devuelve null en silencio en vez de lanzar; el error real
aparece recién en la línea siguiente al intentar setear una propiedad del layout inexistente. Hay que
chequear el retorno de addFlexLayout() antes de usarlo, igual que con createText().
Forma del mensaje, generalizable:
Cannot read properties of null (reading '<prop>') y
Cannot set properties of null (setting '<prop>').
Las tres fuentes de null que los seeds deben enseñar a chequear:
penpot.createText()sin argumento o con''→null. Con un string no vacío →Text. El ejemplo de la documentación oficial (penpot_api_docs.mdCaptura 6) usa la forma sin argumento.penpotUtils.findShapeById(page, id)— la forma de dos argumentos no lanza: devuelvenullen silencio, porquefindShapeByIdtiene aridad 1 y el segundo argumento se descarta mientras el primero (unPage, no unstring) no matchea ningún id. La forma correcta espenpotUtils.findShapeById(id).penpot.createBoolean(type, shapes)ypenpot.createShapeFromSvg(svg)declarannull | Ten su firma (Capturas 10 y 11).
4. Fallos de red y de subida de medios
| Disparador | Mensaje verbatim |
|---|---|
await penpot.uploadMediaUrl('foto', 'https://dominio-inexistente.invalid/a.jpg') |
Error uploading media |
uploadMediaUrl devuelve una Promise; el fallo llega como rechazo, así que hay que envolverlo en
try/catch con await adentro del try (un .catch() colgado de la promesa sin await deja el
resto del payload corriendo con undefined).
5. Errores estándar del runtime de JavaScript
Deterministas dada la expresión, no específicos de Penpot. Se listan porque aparecen en los seeds del grupo D y el lint los tiene que aceptar.
| Disparador | Mensaje verbatim |
|---|---|
undefined.foo |
Cannot read properties of undefined (reading 'foo') |
shapes.map(...) donde shapes es null |
Cannot read properties of null (reading 'map') |
JSON.parse('{') |
Unexpected end of JSON input |
board.appendChild() sin argumento |
Cannot read properties of undefined (reading 'id') |
6. Errores a nivel de servidor MCP (no de execute_code)
No son excepciones de JavaScript: los devuelve el servidor MCP antes de llegar al plugin. No pueden
aparecer como resultado de un execute_code en un seed, porque no dejan al modelo en una situación
de "diagnosticá tu código" — significan que no hay con qué hablar.
| Situación | Mensaje verbatim |
|---|---|
| El plugin de Penpot no está abierto / no está conectado al servidor MCP | No Penpot plugin instances are currently connected. Please ensure the plugin is running and connected. |
Capturado en vivo el 2026-07-30 durante el paso 6.1.3 de esta fase.
7. Fallos SILENCIOSOS — no producen ningún error
La categoría más peligrosa, y la razón por la que el invariante R8 (leer de vuelta el efecto)
existe. Estas operaciones no lanzan, no devuelven null, y dejan el diseño mal. Un modelo que
solo maneja excepciones no las detecta nunca.
| Operación | Comportamiento real | Cómo detectarlo |
|---|---|---|
flex.horizontalSizing = 'auto' |
Se lee de vuelta como 'auto' pero el board no crece (200×200 sigue 200×200 tras insertar un hijo de 300 de ancho). Bug conocido penpot#8520 |
Leer board.width tras insertar; hacer board.resize() a mano |
layoutChild.zIndex = 10 |
Se lee de vuelta como 0. Se ignora |
Leer layoutChild.zIndex; usar el orden del array children para z-order |
text.letterSpacing = '-0.02' |
Se lee de vuelta como "0". Los valores negativos en unidades tipo em se descartan |
Leer text.letterSpacing; usar unidades tipo px ('-1') |
penpot.createRectangle() sin asignar fills |
Queda con el fill por defecto #B1B2B5 — el gris exacto del problema reportado |
Invariante R1: fills explícito en todo shape creado |
penpotUtils.findShapeById(page, id) |
Devuelve null, sin lanzar |
Chequear el retorno antes de usarlo |
board.layout |
undefined; 'layout' in shape === false. La propiedad no existe |
Usar board.flex / board.grid, que devuelven null cuando no hay layout |
generateStyle(shapes, {withChildren: true}) |
La opción real es includeChildren; withChildren se ignora y el CSS sale sin los hijos |
Ver penpot_api_docs.md Captura 8 |
grid.appendChild(shape, 0, 0) |
El 0 se clampea a 1: se lee de vuelta [1,1]. Los índices son 1-based |
Leer shape.layoutCell.row / .column |
text.resize(w, h) |
Setea growType a 'fixed' en silencio; el texto desborda su caja |
Invariante R6: restaurar growType tras resize() |
Leer text.width justo después de setear characters |
El auto-sizing no es inmediato: se lee 1 |
Dormir ~120 ms antes de leer el bounding box |