lampson 0.1.0

package/lib/tools/img.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# img.sh — imágenes para el REPL (Linux/macOS). Imprime UNA línea: media_type|ancho|alto|base64
+#   bash lib/tools/img.sh clip          # portapapeles: wl-paste, xclip o pbpaste (macOS)
+#   bash lib/tools/img.sh file <ruta>
+# Sin redimensionar (no asumimos ImageMagick); ancho/alto en 0 si no hay `identify`.
+set -euo pipefail
+mode="$1"; tmp="$(mktemp)"; trap 'rm -f "$tmp"' EXIT
+if [ "$mode" = "clip" ]; then
+    if command -v wl-paste >/dev/null 2>&1; then wl-paste -t image/png > "$tmp" 2>/dev/null || true
+    elif command -v xclip >/dev/null 2>&1; then xclip -selection clipboard -t image/png -o > "$tmp" 2>/dev/null || true
+    elif command -v osascript >/dev/null 2>&1; then osascript -e 'set f to POSIX file "'"$tmp"'"' -e 'try' -e 'set d to the clipboard as «class PNGf»' -e 'set o to open for access f with write permission' -e 'write d to o' -e 'close access o' -e 'end try' >/dev/null 2>&1 || true
+    fi
+    [ -s "$tmp" ] || { echo "ERROR|no hay una imagen en el portapapeles"; exit 0; }
+    type="image/png"
+else
+    [ -f "$2" ] || { echo "ERROR|no existe $2"; exit 0; }
+    cp "$2" "$tmp"
+    case "${2,,}" in *.jpg|*.jpeg) type="image/jpeg";; *.gif) type="image/gif";; *.webp) type="image/webp";; *) type="image/png";; esac
+fi
+w=0; h=0
+if command -v identify >/dev/null 2>&1; then read -r w h < <(identify -format "%w %h" "$tmp[0]" 2>/dev/null || echo "0 0"); fi
+echo "$type|$w|$h|$(base64 < "$tmp" | tr -d '\n')"

package/lib/tools/ls.syn

@@ -0,0 +1,18 @@
+-- lib/tools/ls.syn — listar un directorio (no recursivo)
+use "./common.syn" as c
+
+export task tool(path)
+    require file.read("workspace")
+    require file.read("workspace/*")
+    let lines be []
+    each e in list_dir(c.ws(path))
+        set lines to append(lines, e["name"] + (when e["is_dir"] then "/" otherwise ""))
+    when length(lines) == 0
+        give "(empty directory)"
+    give join(lines, "\n")
+
+export let SPEC be {
+    "name": "ls",
+    "description": "List the entries of a directory (non-recursive). Directories end with a slash. Defaults to the workspace root.",
+    "parameters": {"type": "object", "properties": {"path": {"type": "string"}}, "required": []}
+}

package/lib/tools/memo.syn

@@ -0,0 +1,148 @@
+-- lib/tools/memo.syn — memoria por proyecto: notas Markdown que el agente escribe y relee
+--
+-- Dónde: lampson/memory/<slug>/<nombre>.md — <slug> sale de la ruta REAL del workspace
+-- (LAMPSON_WORKSPACE, que fija el launcher): "<carpeta>-<hash8>". Así cada proyecto tiene su carpeta
+-- aunque dos se llamen igual, y las notas viven en lampson (no ensucian el repo del usuario).
+--
+-- El system prompt lleva SOLO el índice (nombre + primera línea de cada nota); el contenido entra al
+-- contexto cuando el agente llama `memory(read)`. Son archivos: el humano los lee/edita a mano y la
+-- UI web los muestra.
+use "./common.syn" as c
+
+export let ROOT be "memory"
+
+task valid_name(name)
+    when name == nothing or name == ""
+        give false
+    give matches(name, "[a-zA-Z0-9_-]{1,60}")
+
+-- slug del proyecto montado
+export task slug()
+    require env("LAMPSON_*")
+    let ws be env("LAMPSON_WORKSPACE", "workspace")
+    let norm be replace_text(lower(ws), "\\", "/")
+    let parts be where(split(norm, "/"), (x) => x != "")
+    let base be when length(parts) > 0 then parts[length(parts) - 1] otherwise "workspace"
+    let runs be find_all(base, "[a-z0-9]+")
+    let clean be when length(runs) == 0 then "project" otherwise join(runs, "-")
+    let h be slice(decode(sha256(norm), "hex"), 0, 8)
+    give clean + "-" + h
+
+export task dir()
+    require env("LAMPSON_*")
+    give ROOT + "/" + slug()
+
+task path(name)
+    give dir() + "/" + name + ".md"
+
+-- [{name, title}] — title = primera línea no vacía (sin '#')
+export task list()
+    require env("LAMPSON_*")
+    require file.read("memory")
+    require file.read("memory/*")
+    let out be []
+    try
+        each e in list_dir(dir())
+            when not e["is_dir"] and c.ends_with(e["name"], ".md")
+                let name be slice(e["name"], 0, length(e["name"]) - 3)
+                let title be ""
+                each line in split(read_file(path(name)), "\n")
+                    when title == "" and trim(line) != ""
+                        set title to trim(replace_text(line, "#", ""))
+                set out to append(out, {"name": name, "title": when length(title) > 120 then slice(title, 0, 120) otherwise title})
+    recover err
+        -- el runtime lanza "Not a directory: …" (mayúscula) cuando memory/<slug> aún no existe
+        let e be lower(text(err))
+        when not contains(e, "not a directory") and not contains(e, "not found") and not contains(e, "no such")
+            raise(err)
+        give []
+    give sort_by(out, (x) => x["name"])
+
+export task note_read(name)
+    require env("LAMPSON_*")
+    require file.read("memory")
+    require file.read("memory/*")
+    when not valid_name(name)
+        raise("invalid note name")
+    try
+        give read_file(path(name))
+    recover err
+        raise("no such note '" + name + "'. Existing: " + join(apply((x) => x["name"], list()), ", "))
+
+export task note_write(name, content)
+    require env("LAMPSON_*")
+    require file("memory")
+    require file("memory/*")
+    when not valid_name(name)
+        raise("invalid note name '" + text(name) + "' (letters, digits, - or _)")
+    write_file(path(name), content)
+    give "saved memory/" + slug() + "/" + name + ".md (" + text(length(content)) + " chars)"
+
+export task note_append(name, content)
+    require env("LAMPSON_*")
+    require file("memory")
+    require file("memory/*")
+    when not valid_name(name)
+        raise("invalid note name")
+    let prev be ""
+    try
+        set prev to read_file(path(name))
+    recover err
+        set prev to ""
+    let joined be when prev == "" then content otherwise prev + "\n\n" + content
+    write_file(path(name), joined)
+    give "appended to " + name + ".md (" + text(length(joined)) + " chars total)"
+
+export task note_clear(name)
+    require env("LAMPSON_*")
+    require file("memory")
+    require file("memory/*")
+    when not valid_name(name)
+        raise("invalid note name")
+    write_file(path(name), "")
+    give "cleared " + name + ".md (the file stays empty; the user can delete it)"
+
+-- sección del system prompt
+export task prompt_section()
+    require env("LAMPSON_*")
+    require file.read("memory")
+    require file.read("memory/*")
+    let items be list()
+    let head be "\n\n# Project memory (your own notes about THIS project, in memory/" + slug() + "/ — read with memory(read), keep them current with memory(write|append))"
+    when length(items) == 0
+        give head + "\n(empty — when you discover something non-obvious about this project: how to run/test it, gotchas, decisions, where things live — save it with memory(write). Keep notes short and factual.)"
+    let lines be [head]
+    each it in items
+        set lines to append(lines, "- " + it["name"] + ": " + it["title"])
+    give join(lines, "\n")
+
+-- ---------- tool ----------
+
+export task tool(action, name, content)
+    require env("LAMPSON_*")
+    require file("memory")
+    require file("memory/*")
+    when action == "list"
+        let items be list()
+        when length(items) == 0
+            give "no notes yet for this project"
+        give join(apply((x) => x["name"] + ": " + x["title"], items), "\n")
+    when action == "read"
+        give note_read(name)
+    when action == "write"
+        give note_write(name, content)
+    when action == "append"
+        give note_append(name, content)
+    when action == "delete"
+        give note_clear(name)
+    raise("unknown action '" + text(action) + "' (list | read | write | append | delete)")
+
+export let SPEC be {
+    "name": "memory",
+    "description": "Your persistent notes about THIS project, kept across sessions (Markdown files in Lampson's memory folder, never inside the repo). Use `write` to save non-obvious facts you discovered and will need again: how to run/build/test, environment quirks, architecture decisions, where things live, bugs and their causes, what the user prefers. `append` adds to an existing note, `read` loads one, `list` shows them, `delete` clears one. The system prompt shows the index of notes — read the relevant ones before repeating an investigation. Keep notes short, factual and current: update a note instead of writing a contradictory one.",
+    "parameters": {"type": "object", "properties": {
+        "action": {"type": "string", "enum": ["list", "read", "write", "append", "delete"]},
+        "name": {"type": "string", "description": "Note id: letters, digits, - or _ (e.g. how-to-run, db-schema, gotchas)"},
+        "content": {"type": "string", "description": "write/append: Markdown content (first line = title)"}
+    }, "required": ["action"]}
+}

package/lib/tools/proc.sh

@@ -0,0 +1,42 @@
+# proc.sh — consultas al sistema que Synsema no tiene nativas (puertos, línea de comando, matar un pid ajeno)
+#
+#   bash lib/tools/proc.sh ports        → "port pid name" por línea (>=1024, sin sistema)
+#   bash lib/tools/proc.sh info <pid>   → línea de comando del proceso
+#   bash lib/tools/proc.sh kill <pid>   → mata el árbol de un pid AJENO (huérfano de otra herramienta)
+#
+# Los procesos gestionados (start/stop/alive) ya NO pasan por acá: viven en un agente supervisor con
+# proc_spawn / proc_close (lib/tools/proc.syn, v0.6.9: tree-kill nativo). 2026-08-27.
+. "$(dirname "$0")/common.sh"
+ACTION="$1"
+case "$ACTION" in
+    ports)
+        if is_win; then
+            # netstat + tasklist → "port pid name"
+            tasklist //FO CSV //NH 2>/dev/null | awk -F'","' '{gsub(/"/,"",$1); gsub(/"/,"",$2); print $2" "$1}' > /tmp/lampson_tl.$$
+            netstat -ano 2>/dev/null | awk '/LISTENING/ {n=split($2,a,":"); print a[n]" "$NF}' | sort -u -k1,1n | while read -r port pid; do
+                name="$(awk -v p="$pid" '$1==p {print $2; exit}' /tmp/lampson_tl.$$)"
+                echo "$port $pid ${name:-?}"
+            done
+            rm -f /tmp/lampson_tl.$$
+        elif command -v ss >/dev/null 2>&1; then
+            ss -ltnpH 2>/dev/null | awk '{n=split($4,a,":"); port=a[n]; name="?"; pid="?"; if (match($0,/users:\(\("[^"]+",pid=[0-9]+/)) { s=substr($0,RSTART,RLENGTH); gsub(/users:\(\("/,"",s); split(s,b,"\",pid="); name=b[1]; pid=b[2] } print port" "pid" "name}' | sort -u -k1,1n
+        elif command -v lsof >/dev/null 2>&1; then
+            lsof -nP -iTCP -sTCP:LISTEN 2>/dev/null | awk 'NR>1 {n=split($9,a,":"); print a[n]" "$2" "$1}' | sort -u -k1,1n
+        fi
+        ;;
+    info)
+        # línea de comando de un pid (para saber QUÉ escucha en un puerto)
+        PID="$2"
+        if is_win; then
+            powershell.exe -NoProfile -Command "(Get-CimInstance Win32_Process -Filter 'ProcessId=$PID').CommandLine" 2>/dev/null | tr -d '\r'
+        else
+            ps -o args= -p "$PID" 2>/dev/null
+        fi
+        ;;
+    kill)
+        PID="$2"
+        if is_win; then taskkill //T //F //PID "$PID" >/dev/null 2>&1; else kill_tree "$PID"; fi
+        echo "killed $PID"
+        ;;
+esac
+exit 0

package/lib/tools/proc.syn

@@ -0,0 +1,314 @@
+-- lib/tools/proc.syn — procesos gestionados (servidores, watchers): start / logs / stop / list / report
+--
+-- DISEÑO (2026-08-27, nativo sobre proc_spawn — antes era bash + pidfiles, ver README "runtime notes"):
+--   * Cada proceso vive dentro de un AGENTE supervisor (`Sup`), que es lo único con ciclo de vida
+--     propio bajo `serve`: un proc_spawn hecho en un handler muere al terminar el request; uno hecho
+--     en un agente vive hasta que el agente termina (verificado en v0.6.9, run y serve).
+--   * El supervisor drena los eventos del proceso (select) al ARCHIVO .lampson/proc/<name>.log, así:
+--       - `report()` devuelve las líneas NUEVAS desde la última vez (offset en .pos) — la tool bash lo
+--         agrega a cada resultado: el agente "ve la consola" de sus servidores sin pedirla;
+--       - la UI web y `/logs` leen el mismo archivo;
+--       - el archivo es el spill: nada se pierde por tamaño de cola.
+--   * Estado vivo en el blackboard: "proc:<name>" = {status, pid, exit_code, started}. Se lee con
+--     observe desde cualquier handler/agente (misma máquina de estado que ve el modelo).
+--   * `stop` = bus_publish("proc.stop.<name>") → el supervisor hace proc_close = TERM → KILL a 2 s
+--     sobre el ÁRBOL (Job Object en Windows, process group en unix; v0.6.9+). Sin taskkill, sin ps.
+--   * Al cerrar Lampson (chat: /exit; web: Ctrl-C → agent_stop) los procesos mueren con él —
+--     el runtime no deja huérfanos. Es la decisión de opencode/deepseek; hermes es el único que persiste.
+--   * El comando corre en `bash -c` (Git Bash en Windows) para que el modelo tenga pipes y &&.
+use "./common.syn" as c
+
+export let DIR be ".lampson/proc"
+let MAX_REPORT be 4000
+-- procesos del sistema que nunca son "tu servidor" (ruido en la lista de puertos)
+let SYSTEM_PROCS be ["svchost.exe", "lsass.exe", "wininit.exe", "services.exe", "spoolsv.exe", "system", "mmsshost.exe", "sqlservr.exe", "dns.exe", "onedrive.exe", "msedge.exe", "chrome.exe", "code.exe", "explorer.exe", "searchhost.exe", "nvcontainer.exe"]
+
+task shell()
+    require env("LAMPSON_*")
+    require env("OS")
+    let is_win be env("OS", "") == "Windows_NT"
+    give env("LAMPSON_SHELL", when is_win then "C:\\Program Files\\Git\\bin\\bash.exe" otherwise "bash")
+
+task valid_name(name)
+    when name == nothing or name == ""
+        give false
+    give matches(name, "[a-zA-Z0-9_-]{1,40}")
+
+task path(name, ext)
+    give DIR + "/" + name + "." + ext
+
+task tail_lines(content, n)
+    let lines be split(replace_text(content, "\r", ""), "\n")
+    when length(lines) > n
+        set lines to slice(lines, length(lines) - n, length(lines))
+    give join(lines, "\n")
+
+-- ---------- supervisor: un agente por proceso ----------
+-- Parámetros del spawn: name, command, sh (ejecutable del shell), cwd, log (path). OJO: un agente NO ve
+-- las constantes del módulo (DIR, c.*) — solo sus parámetros y las builtins. Estado → blackboard "proc:<name>";
+-- salida → .lampson/proc/<name>.log (una línea por evento, más "[process exited with code N]").
+agent Sup
+    require exec
+    require time
+    require env("LAMPSON_*")
+    require env("OS")
+    require file(".lampson")
+    require file(".lampson/*")
+    require file("workspace")
+    require file("workspace/*")
+    let key be "proc:" + name
+    let p be nothing
+    try
+        set p to proc_spawn(sh, ["-c", command], {"cwd": cwd, "stderr": "merge", "on_full": "drop_oldest"})
+    recover err
+        append_file(log, "[cannot start: " + text(err) + "]\n[process exited with code -1]\n")
+        share {"status": "exited", "exit_code": -1, "pid": 0, "started": now()} as key
+    when p != nothing
+        share {"status": "running", "exit_code": nothing, "pid": proc_stats(p)["pid"], "started": now()} as key
+        bus_publish("proc." + name, {"name": name, "status": "running"})
+        let sub be bus_subscribe(["proc.stop." + name, "proc.stop_all"])
+        let open be true
+        while open
+            let ev be select({"p": p, "stop": sub}, 30)
+            when ev == nothing
+                set open to proc_status(p) == "running"
+            otherwise when ev["name"] == "stop"
+                proc_close(p)
+                append_file(log, "[process stopped by lampson]\n")
+                share {"status": "stopped", "exit_code": -1, "pid": 0, "started": nothing} as key
+                bus_publish("proc." + name, {"name": name, "status": "stopped"})
+                set open to false
+            otherwise when ev["type"] == "exit"
+                let code be ev["data"]["exit_code"]
+                append_file(log, "[process exited with code " + text(code) + "]\n")
+                share {"status": "exited", "exit_code": code, "pid": 0, "started": nothing} as key
+                bus_publish("proc." + name, {"name": name, "status": "exited", "exit_code": code})
+                set open to false
+            otherwise
+                append_file(log, ev["data"] + "\n")
+                -- la UI web lo recibe por /api/events (SSE) y refresca el log sin timers
+                bus_publish("proc." + name, {"name": name, "status": "running", "line": ev["data"]})
+        proc_close(p)
+        bus_unsubscribe(sub)
+
+-- estado vivo de un proceso: {status, exit_code, pid, started} o nothing si nunca arrancó en ESTA sesión
+export task state(name)
+    observe "proc:" + name as st
+    give st
+
+export task alive(name)
+    let st be state(name)
+    when st == nothing
+        give false
+    give st["status"] == "running"
+
+export task start(name, command)
+    require exec
+    require time
+    require env("LAMPSON_*")
+    require env("OS")
+    require file(".lampson")
+    require file(".lampson/*")
+    require file("workspace")
+    require file("workspace/*")
+    when not valid_name(name)
+        raise("invalid process name '" + text(name) + "' (use letters, digits, - or _)")
+    when alive(name)
+        raise("process '" + name + "' is already running — stop it first or pick another name")
+    write_file(path(name, "cmd"), command)
+    write_file(path(name, "log"), "")
+    write_file(path(name, "pos"), "0")
+    -- dueño: la corrida y la sesión que lo arrancaron (blackboard). list() solo muestra lo que corre o lo
+    -- de ESTA sesión en ESTA corrida: un proceso terminado de otra sesión/corrida ya no aparece
+    write_file(path(name, "owner"), json_encode(owner()))
+    -- la clave del blackboard puede tener el estado VIEJO (stopped/exited) de un arranque anterior:
+    -- marcar "starting" antes del spawn, el supervisor la pisa con running/exited
+    share {"status": "starting", "exit_code": nothing, "pid": 0, "started": now()} as "proc:" + name
+    spawn Sup with name = name, command = command, sh = shell(), cwd = c.ROOT, log = path(name, "log")
+    -- esperar a que el supervisor publique (running/exited) y hasta 3s a que salga algo (npm en Windows
+    -- tarda >2s en escribir una línea en frío); "EXITED" solo lo dice el supervisor, nunca un log vacío
+    let waited be 0
+    let log be ""
+    while waited < 20 and state(name)["status"] == "starting"
+        sleep(0.1)
+        set waited to waited + 1
+    set waited to 0
+    while waited < 6 and trim(log) == "" and alive(name)
+        sleep(0.5)
+        set waited to waited + 1
+        set log to read_file(path(name, "log"))
+    set log to read_file(path(name, "log"))
+    let running be alive(name)
+    let status be when running then "status: running (pid " + text(state(name)["pid"]) + "; NEW log lines arrive with every bash result, or call logs)" otherwise "status: EXITED (the log ends with its exit code) — read it, fix the cause and start again with this tool; do NOT run the same command with bash"
+    when running and trim(log) == ""
+        set status to status + "\nlog: empty so far (cold start) — call logs in a few seconds"
+    give "started '" + name + "': $ " + command + "\n" + status + "\nlog (first lines):\n" + tail_lines(log, 30)
+
+export task logs(name, tail)
+    require file(".lampson")
+    require file(".lampson/*")
+    let n be when tail == nothing then 60 otherwise floor(tail)
+    try
+        give tail_lines(read_file(path(name, "log")), n)
+    recover err
+        give "no such process '" + text(name) + "'"
+
+-- stop cooperativo: aviso por bus → el supervisor mata el árbol; esperamos hasta 6s la confirmación
+export task halt(name)
+    require time
+    when not alive(name)
+        give "process '" + text(name) + "' is not running"
+    bus_publish("proc.stop." + name, {})
+    let waited be 0
+    while waited < 12 and alive(name)
+        sleep(0.5)
+        set waited to waited + 1
+    when alive(name)
+        give "stop requested for '" + name + "' but it is still running — check `list` again in a moment"
+    give "stopped '" + name + "'"
+
+-- mata todos los gestionados (salida de lampson)
+export task halt_all()
+    require time
+    bus_publish("proc.stop_all", {})
+    let waited be 0
+    while waited < 10 and length(where(list(), (p) => p["running"])) > 0
+        sleep(0.3)
+        set waited to waited + 1
+
+-- Nota para el modelo cuando se reanuda una sesión guardada por una corrida ANTERIOR de lampson:
+-- los procesos gestionados mueren con lampson, pero el historial de la sesión dice que estaban corriendo.
+-- Sin esto el modelo "recuerda" servers vivos que ya no existen (visto 2026-08-28). "" si no hay nada que decir.
+-- procesos que ESTA sesión arrancó en cualquier corrida (para la nota de resume: qué se murió con el restart)
+export task list_for_session(sid)
+    require file(".lampson")
+    require file(".lampson/*")
+    let out be []
+    try
+        each e in list_dir(DIR)
+            when c.ends_with(e["name"], ".cmd")
+                let name be slice(e["name"], 0, length(e["name"]) - 4)
+                let mine be false
+                try
+                    set mine to json_decode(read_file(path(name, "owner")))["session"] == text(sid)
+                recover err
+                    set mine to false
+                when mine
+                    set out to append(out, {"name": name, "running": alive(name), "command": read_file(path(name, "cmd"))})
+    recover err
+        give []
+    give out
+
+export task resume_note(sid)
+    require file(".lampson")
+    require file(".lampson/*")
+    let items be list_for_session(sid)
+    when length(items) == 0
+        give ""
+    let lines be []
+    each p in items
+        set lines to append(lines, "- " + p["name"] + ": " + (when p["running"] then "running" otherwise "NOT running") + "  ($ " + first_line_of(p["command"]) + ")")
+    give "[harness] This session was resumed after a lampson restart. Managed processes do NOT survive a restart — anything this conversation started earlier is gone unless listed as running below. Current real state:\n" + join(lines, "\n") + "\nOld logs remain in " + DIR + "/<name>.log. Start a process again with the `process` tool only if it is needed now; do not assume any server is up."
+
+task first_line_of(s)
+    let t be replace_text(text(s), "\r", "")
+    give split(t, "\n")[0]
+
+-- {run, session} actuales (blackboard "lampson:run" / "lampson:session"; vacíos fuera de un entry)
+task owner()
+    observe "lampson:run" as r
+    observe "lampson:session" as s
+    give {"run": when r == nothing then "" otherwise text(r["id"]), "session": when s == nothing then "" otherwise text(s["id"])}
+
+task owned_here(name)
+    try
+        let o be json_decode(read_file(path(name, "owner")))
+        let cur be owner()
+        give o["run"] == cur["run"] and o["session"] == cur["session"]
+    recover err
+        give false
+
+-- [{name, running, command}] — lo que corre ahora + lo terminado de esta sesión en esta corrida.
+-- Como la lista de tareas (todo): un proceso muerto de otra sesión o de una corrida anterior no es
+-- información, es ruido (2026-08-28: la UI mostraba servers de hace días como "apagados").
+export task list()
+    require file(".lampson")
+    require file(".lampson/*")
+    let out be []
+    try
+        each e in list_dir(DIR)
+            when c.ends_with(e["name"], ".cmd")
+                let name be slice(e["name"], 0, length(e["name"]) - 4)
+                let running be alive(name)
+                when running or owned_here(name)
+                    set out to append(out, {"name": name, "running": running, "command": read_file(path(name, "cmd"))})
+    recover err
+        give []
+    give out
+
+-- Puertos TCP en escucha (cualquier proceso, gestionado o no): [{port, pid, name, command}] — via proc.sh ports
+-- (Windows: netstat+tasklist · Linux: ss · macOS: lsof). Un servidor huérfano no aparece en list(); acá sí.
+export task listeners()
+    require exec
+    require env("LAMPSON_*")
+    require env("OS")
+    require file(".lampson")
+    require file(".lampson/*")
+    let out be []
+    try
+        let r be run(shell(), ["lib/tools/proc.sh", "ports"], 20, {"cwd": "."})
+        let seen be {}
+        each line in split(replace_text(r["stdout"], "\r", ""), "\n")
+            let parts be where(split(trim(line), " "), (x) => x != "")
+            when length(parts) >= 2
+                let port be floor(number(parts[0]))
+                let nm be when length(parts) >= 3 then parts[2] otherwise "?"
+                when port >= 1024 and port < 49152 and not contains(SYSTEM_PROCS, lower(nm)) and not contains(seen, text(port))
+                    set seen[text(port)] to true
+                    set out to append(out, {"port": port, "pid": floor(number(parts[1])), "name": nm, "command": ""})
+    recover err
+        give out
+    -- la línea de comando dice QUÉ es (next dev, un MCP server de otra herramienta, synsema serve…); un run por pid
+    let cmds be {}
+    let enriched be []
+    each l in out
+        let key be text(l["pid"])
+        when not contains(cmds, key)
+            try
+                let r be run(shell(), ["lib/tools/proc.sh", "info", key], 15, {"cwd": "."})
+                set cmds[key] to trim(replace_text(r["stdout"], "\n", " "))
+            recover err
+                set cmds[key] to ""
+        set l["command"] to when length(cmds[key]) > 300 then slice(cmds[key], 0, 300) + "…" otherwise cmds[key]
+        set enriched to append(enriched, l)
+    give sort_by(enriched, (x) => x["port"])
+
+-- matar un pid ajeno (huérfano de otra herramienta): taskkill /T o kill_tree, via proc.sh
+export task kill_pid(pid)
+    require exec
+    require env("LAMPSON_*")
+    require env("OS")
+    let r be run(shell(), ["lib/tools/proc.sh", "kill", text(floor(pid))], 20, {"cwd": "."})
+    give trim(r["stdout"])
+
+-- líneas nuevas de cada proceso desde la última llamada. "" si no hay nada.
+-- La salida del proceso ("[process exited with code N]") llega como línea nueva: es el aviso.
+export task report()
+    require file(".lampson")
+    require file(".lampson/*")
+    let parts be []
+    each p in list()
+        let log be read_file(path(p["name"], "log"))
+        let pos be 0
+        try
+            set pos to floor(number(trim(read_file(path(p["name"], "pos")))))
+        recover err
+            set pos to 0
+        when pos > length(log)
+            set pos to 0
+        let fresh be slice(log, pos, length(log))
+        write_file(path(p["name"], "pos"), text(length(log)))
+        when trim(fresh) != ""
+            let status be when p["running"] then "running" otherwise "EXITED"
+            set parts to append(parts, "[process '" + p["name"] + "' (" + status + ") new output:\n" + c.truncate(fresh, MAX_REPORT) + "]")
+    give join(parts, "\n")

package/lib/tools/process.syn

@@ -0,0 +1,46 @@
+-- lib/tools/process.syn — tool `process`: servidores y watchers gestionados (start / logs / stop / list)
+use "./proc.syn" as proc
+
+export task tool(action, name, command, tail)
+    require exec
+    require time
+    require env("LAMPSON_*")
+    require env("OS")
+    require file(".lampson")
+    require file(".lampson/*")
+    when action == "start"
+        when command == nothing or command == ""
+            raise("start needs a command")
+        give proc.start(name, command)
+    when action == "logs"
+        give proc.logs(name, tail)
+    when action == "stop"
+        give proc.halt(name)
+    when action == "ports"
+        let ls be proc.listeners()
+        when length(ls) == 0
+            give "no TCP ports listening (>=1024)"
+        let lines be []
+        each l in ls
+            set lines to append(lines, "port " + text(l["port"]) + "  pid " + text(l["pid"]) + "  " + l["name"])
+        give join(lines, "\n")
+    when action == "list"
+        let items be proc.list()
+        when length(items) == 0
+            give "no managed processes"
+        let lines be []
+        each p in items
+            set lines to append(lines, p["name"] + "  " + (when p["running"] then "running" otherwise "exited") + "  $ " + p["command"])
+        give join(lines, "\n")
+    raise("unknown action '" + text(action) + "' (start | logs | stop | list | ports)")
+
+export let SPEC be {
+    "name": "process",
+    "description": "Manage long-running processes (dev servers, watchers, APIs) so you can SEE their output. start: launches `command` detached with a `name`; its stdout/stderr go to a log you can read any time. After every bash call you automatically receive the NEW log lines of every managed process, so errors in a server you started reach you without asking. logs: last `tail` lines (default 60). A process is EXITED only when its pid is really gone; then its log ends with `[process exited with code N]` — read the reason there instead of retrying the command in bash. stop: kills the process and its whole tree (npm → node included). list: what is running. ports: every TCP port listening on the machine with its pid and program — use it when a port is busy (EADDRINUSE) or to check whether something is already up. Always use this instead of `cmd &` in bash, and stop what you started when the task is done.",
+    "parameters": {"type": "object", "properties": {
+        "action": {"type": "string", "enum": ["start", "logs", "stop", "list", "ports"]},
+        "name": {"type": "string", "description": "Short id: letters, digits, - or _ (e.g. web, api, dev)"},
+        "command": {"type": "string", "description": "start only: the shell command (runs with cwd = workspace root)"},
+        "tail": {"type": "integer", "description": "logs only: number of lines (default 60)"}
+    }, "required": ["action"]}
+}

package/lib/tools/read.syn

@@ -0,0 +1,25 @@
+-- lib/tools/read.syn — leer un archivo del workspace (con rango de líneas)
+use "./common.syn" as c
+
+export task tool(path, offset, limit)
+    require file.read("workspace")
+    require file.read("workspace/*")
+    require file.read(".lampson")
+    require file.read(".lampson/*")
+    let off be when offset == nothing then 1 otherwise floor(offset)
+    let lim be when limit == nothing then 2000 otherwise floor(limit)
+    let real be c.ws(path)
+    let out be c.truncate(read_file(real, off, lim), c.MAX_OUTPUT)
+    -- registrar la observación (hash del archivo completo): edit/write la exigen
+    c.mark_observed(real)
+    give out
+
+export let SPEC be {
+    "name": "read",
+    "description": "Read a file from the workspace. Returns the text with line-range support. Use offset (1-based line) and limit (max lines) for big files; default reads the first 2000 lines. Always read a file before editing it.",
+    "parameters": {"type": "object", "properties": {
+        "path": {"type": "string", "description": "Path relative to the workspace root"},
+        "offset": {"type": "integer", "description": "1-based first line to read (optional)"},
+        "limit": {"type": "integer", "description": "Max lines to read (optional)"}
+    }, "required": ["path"]}
+}

package/lib/tools/skill.syn

@@ -0,0 +1,14 @@
+-- lib/tools/skill.syn — cargar una skill (SKILL.md) al contexto
+-- Nota: skills.syn está un nivel arriba y un módulo no puede importar "../", así que este archivo
+-- solo define el SPEC; la task real vive en lib/tools.syn (que sí puede importar ./skills.syn).
+
+export let SPEC be {
+    "name": "skill",
+    "description": "Skills are folders with a SKILL.md (the Agent Skills format used on skills.sh). action=load (default): load the instructions of a skill listed in the system prompt — do it BEFORE starting that kind of task and follow them. action=list: every skill available with its source. action=install: fetch a skill from a GitHub repo with `npx skills add` (source=owner/repo, name=the skill folder; e.g. source=anthropics/skills name=frontend-design). scope=global (default) installs into ~/.agents/skills so it is available in EVERY project; scope=project into ./.agents/skills. Installing always asks the user for approval — propose it when the task needs know-how you lack (a framework, a language, design guidelines) and a skill for it exists.",
+    "parameters": {"type": "object", "properties": {
+        "name": {"type": "string", "description": "Skill name (load: exactly as listed; install: the skill folder in the repo)"},
+        "action": {"type": "string", "enum": ["load", "list", "install"], "description": "Default: load"},
+        "source": {"type": "string", "description": "install only: owner/repo on GitHub, or a github URL"},
+        "scope": {"type": "string", "enum": ["global", "project"], "description": "install only: global (default, every project) or project"}
+    }, "required": ["name"]}
+}