Ampliar

Plugins

Un plugin es una carpeta que le enseña a Lampson una herramienta nueva. Consultar tu base de datos, llamar a la API de tu empresa, ejecutar un despliegue, publicar un mensaje — cualquier cosa que pueda hacer un script, en cualquier lenguaje. Los plugins están apagados por defecto: tú enciendes cada uno, y solo entonces el agente puede usar sus herramientas.

Hasta Lampson 0.2.6 los plugins se llamaban lámparas (lamps). Ese nombre ahora es de lamps.sh — mira Plugins y lámparas. Las carpetas viejas siguen funcionando: qué sigue andando.

Encender uno§

❯ /plugins on postgres
☼ postgres is on — 1 tool available: plugin_postgres_query

En la interfaz web, haz clic en el pill plugins de la cabecera: una lista de todos los plugins con un interruptor, sus herramientas y un formulario para probar cada una tú mismo. /plugins off <name> lo apaga. El agente puede pedirte que enciendas un plugin, pero nunca puede hacerlo por su cuenta.

Anatomía§

~/lampson/plugins/postgres/      ← global: disponible en todos los proyectos
  plugin.json                    ← el manifiesto
  query.py                       ← el código, en cualquier lenguaje

my-project/.lampson/plugins/…    ← o dentro de un proyecto (súbelo a git y tu equipo lo tiene)

plugin.json:

{
  "name": "postgres",
  "description": "read-only queries on the dev database",
  "kind": "exec",
  "command": "python query.py",
  "timeout": 30,
  "tools": [
    {
      "name": "query",
      "description": "Run a SELECT and return the rows as JSON.",
      "parameters": {"type": "object", "properties": {"sql": {"type": "string"}}, "required": ["sql"]},
      "readonly": true
    }
  ]
}

Cómo funciona una llamada§

Cada vez que el agente usa una herramienta de un plugin, Lampson arranca un proceso corto y le pasa la llamada en variables de entorno:

Lo que el script imprima en stdout es el resultado que ve el modelo. Una salida distinta de cero o un timeout se convierten en un error que el modelo puede leer.

# query.py
import os, json, psycopg
tool = os.environ["PLUGIN_TOOL"]
args = json.loads(os.environ.get("PLUGIN_ARGS", "{}"))
if tool == "query":
    with psycopg.connect(os.environ["DEV_DATABASE_URL"]) as db:
        rows = db.execute(args["sql"]).fetchall()
    print(json.dumps(rows, default=str))

Dos tipos§

• "kind": "exec" — command se ejecuta tal cual, desde la carpeta del proyecto. Cualquier lenguaje. Una palabra del comando que nombre un archivo de la carpeta del plugin se resuelve automáticamente (python query.py encuentra el query.py del plugin). Sin sandbox: el script puede hacer todo lo que puede tu usuario.
• "kind": "syn" — un programa en Synsema ("entry": "plugin.syn"). Se ejecuta bajo un techo de capacidades tomado de "caps" en el manifiesto: el plugin puede hacer exactamente lo que aprobaste al encenderlo, y el código que pida más falla. Ejemplo: "caps": "file.read=workspace/*,net".

Como un plugin exec no tiene ese techo, encender cualquier plugin es siempre una decisión humana. Tu código, tus reglas, tu riesgo.

Permisos§

Las herramientas de los plugins siguen el modo de permisos: preguntan en ask, se ejecutan en yolo, se deniegan en strict. Las herramientas marcadas con "readonly": true también están disponibles para los perfiles de solo lectura (plan, review, explore).

Deja que el agente escriba uno§

«Hazme un plugin que liste los pull requests abiertos con gh.» El agente crea la carpeta y el manifiesto dentro de tu proyecto, lo valida (synsema check para un plugin Synsema) y te dice que está listo — encenderlo sigue siendo cosa tuya. En el chat web aparece una línea ☼ plugin created y el pill de plugins parpadea.

Programar un plugin§

Una herramienta de un plugin puede ser el trabajo de una tarea programada: «cada mañana, ejecuta postgres.query con este SQL y envíame el resultado». Encender el plugin es la autorización.

El ejemplo§

~/lampson/plugins/example-hello/ viene incluido con Lampson — un plugin Synsema con una herramienta, greet. Copia la carpeta, renómbrala y ya tienes un punto de partida.

Plugins y lámparas§

Son dos cosas distintas, a propósito:

• Un plugin es local, tuyo y de tu repo: cualquier lenguaje, sin distribución, sin techo salvo que lo escribas en Synsema. Rápido de hacer; confías tú.
• Una lámpara (lamps.sh) es una unidad portable de capacidad: un manifiesto que declara exactamente qué puede tocar el código, un runtime que lo hace cumplir y audita cada comprobación, versionada por tag de git, descargada desde un hub y usable por cualquier agente MCP — Claude Code, Cursor, Lampson…

Para usar lámparas en Lampson: instala el CLI, lamp add <ref>, habilítala y añade lamp mcp como servidor MCP. Sus herramientas llegan con su techo escrito en la descripción.

Antes se llamaban lámparas§

Si usabas lámparas en Lampson antes de 0.2.7, hoy no se rompe nada:

• Las carpetas .lampson/lamps/<name>/ se siguen descubriendo (marcadas como carpeta vieja en la interfaz y en /plugins); si falta plugin.json se lee lamp.json.
• El estado de encendido en .lampson/lamps.json se lee hasta que exista .lampson/plugins.json.
• Los scripts siguen recibiendo LAMP_TOOL, LAMP_ARGS, LAMP_DIR y LAMP_WORKSPACE junto a los nombres nuevos; un plugin Synsema puede conservar require env("LAMP_*").
• Las tareas programadas guardadas con "type": "lamp" siguen corriendo; /lamps es un alias de /plugins.
• Las carpetas globales que pusiste en ~/lampson/lamps/ se mueven a ~/lampson/plugins/ la primera vez que ejecutas Lampson.

Es un puente, no un segundo formato: renombra la carpeta a .lampson/plugins/, el manifiesto a plugin.json y lee las variables PLUGIN_*.