lampson 0.1.0

package/lib/tools/todo.syn

@@ -0,0 +1,97 @@
+-- lib/tools/todo.syn — lista de tareas del agente (reemplazo total), POR SESIÓN
+--
+-- Diseño (deepseek-harness tool-todo + hermes todo_tool + opencode session/todo): el modelo manda la lista
+-- ENTERA cada vez (nada de merges ambiguos), como máximo UNA tarea in_progress (se valida en código y la
+-- llamada falla si no), y la lista NO se re-inyecta en cada paso — los tres harnesses coinciden: gasta tokens
+-- y compite con el prompt. Sí se re-inyecta al COMPACTAR el contexto (lib/loop.syn), y solo los items
+-- pending/in_progress: incluir los completados hace que el modelo rehaga trabajo terminado (hermes
+-- todo_tool.py:136).
+--
+-- Alcance = la SESIÓN, como en los tres (opencode la guarda por sessionID; hermes/deepseek la atan al agente
+-- de la sesión): es un andamio de planificación del trabajo en curso, no un tracker del proyecto. Sesión
+-- nueva → lista vacía; /resume de una sesión → vuelve SU lista. Antes (2026-08-28) era por proyecto y la
+-- lista de un pedido viejo reaparecía "apagada" en el siguiente y se pisaba sin que nadie la cerrara.
+-- Persistida en .lampson/todo/<session_id>.json; la sesión actual la comparte el entry en el blackboard
+-- "lampson:session" (chat.syn / web.syn) porque la tool no recibe contexto de sesión.
+use "./common.syn" as c
+
+export let DIR be ".lampson/todo"
+let STATES be ["pending", "in_progress", "completed", "cancelled"]
+
+-- id de la sesión actual (blackboard); sin entry (tests) → "default"
+export task current()
+    observe "lampson:session" as s
+    when s == nothing
+        give "default"
+    give s["id"]
+
+task path(sid)
+    give DIR + "/" + sid + ".json"
+
+-- lista de una sesión (sid == nothing → la actual)
+export task load(sid)
+    require file(".lampson")
+    require file(".lampson/*")
+    let id be when sid == nothing then current() otherwise sid
+    try
+        give json_decode(read_file(path(id)))
+    recover err
+        give []
+
+task mark(s)
+    when s == "completed"
+        give "[x]"
+    when s == "in_progress"
+        give "[>]"
+    when s == "cancelled"
+        give "[-]"
+    give "[ ]"
+
+export task format(items)
+    let lines be []
+    each e in enumerate(items)
+        let it be e["item"]
+        set lines to append(lines, text(e["index"] + 1) + ". " + mark(it["status"]) + " " + it["content"] + (when it["status"] == "in_progress" then "  ← in progress" otherwise ""))
+    give join(lines, "\n")
+
+-- texto para re-inyectar tras una compaction: solo lo activo; "" si no hay nada activo
+export task active_text()
+    require file(".lampson")
+    require file(".lampson/*")
+    let active be where(load(nothing), (it) => it["status"] == "pending" or it["status"] == "in_progress")
+    when length(active) == 0
+        give ""
+    give "[Your active task list was preserved across context compression — completed items omitted]\n" + format(active)
+
+export task tool(items)
+    require file(".lampson")
+    require file(".lampson/*")
+    when items == nothing
+        let cur be load(nothing)
+        give when length(cur) == 0 then "(empty task list)" otherwise format(cur)
+    let clean be []
+    let in_progress be 0
+    each it in items
+        when not contains(it, "content") or trim(text(it["content"])) == ""
+            raise("every item needs a non-empty content")
+        let st be when contains(it, "status") then lower(text(it["status"])) otherwise "pending"
+        when not contains(STATES, st)
+            raise("invalid status '" + st + "' (pending | in_progress | completed | cancelled)")
+        when st == "in_progress"
+            set in_progress to in_progress + 1
+        set clean to append(clean, {"content": trim(text(it["content"])), "status": st})
+    when in_progress > 1
+        raise("at most ONE item may be in_progress at a time (you sent " + text(in_progress) + "): finish or cancel the others first")
+    write_file(path(current()), json_encode(clean))
+    give when length(clean) == 0 then "(empty task list)" otherwise format(clean)
+
+export let SPEC be {
+    "name": "todo",
+    "description": "Your task list for the current session. Send the WHOLE list every time (it replaces the previous one); with no items it just returns the current list. Statuses: pending, in_progress (at most ONE at a time), completed, cancelled. Use it for any task with 3+ steps: write the plan first, mark an item in_progress when you start it, and completed only after it is verified done — never on intent; if something fails, cancel it and add a revised item. The list is shown to the user and preserved across context compression; it is not re-sent to you every step, so keep it current yourself. A new session starts with an empty list.",
+    "parameters": {"type": "object", "properties": {
+        "items": {"type": "array", "items": {"type": "object", "properties": {
+            "content": {"type": "string"},
+            "status": {"type": "string", "enum": ["pending", "in_progress", "completed", "cancelled"]}
+        }, "required": ["content"]}}
+    }}
+}

package/lib/tools/write.syn

@@ -0,0 +1,22 @@
+-- lib/tools/write.syn — crear/sobrescribir un archivo (atómico, crea directorios)
+use "./common.syn" as c
+
+export task tool(path, content)
+    require file("workspace")
+    require file("workspace/*")
+    let real be c.ws(path)
+    -- sobrescribir un archivo existente exige haberlo leído (y que no haya cambiado): igual que edit
+    when file_exists(real)
+        c.check_observed(real, "write")
+    write_file(real, content)
+    c.mark_observed(real)
+    give `wrote {text(length(content))} chars to {c.unws(real)}`
+
+export let SPEC be {
+    "name": "write",
+    "description": "Create a file with the given content (atomic; creates parent dirs). Overwriting an EXISTING file requires having read it first (and not changed since) — and prefer `edit` for targeted changes. Paths are relative to the workspace root.",
+    "parameters": {"type": "object", "properties": {
+        "path": {"type": "string"},
+        "content": {"type": "string"}
+    }, "required": ["path", "content"]}
+}

package/lib/tools.syn

@@ -0,0 +1,198 @@
+-- lib/tools.syn — agregador de tools: una tool = un archivo en lib/tools/<nombre>.syn
+--
+-- Contrato de cada archivo de tool ("plugin"):
+--   export task tool(...)    -- la tool; sus `require` al TOPE del cuerpo (call_tool los intersecta)
+--   export let SPEC be {...} -- {name, description, parameters (JSON Schema)} para el modelo
+--
+-- Para agregar una tool: crear lib/tools/x.syn con ese contrato y sumarla a las dos listas de abajo.
+-- La lista es EXPLÍCITA a propósito: Synsema no tiene `use` dinámico (sin supply chain), así que
+-- el allow-list de tools se lee en este archivo y se audita con `synsema check`.
+--
+-- Seguridad que ya pone el lenguaje: ninguna tool declara `net` → ninguna tool puede usar la red,
+-- aunque el entry la tenga para hablar con el LLM.
+
+use "./tools/common.syn" as common
+use "./tools/read.syn" as t_read
+use "./tools/write.syn" as t_write
+use "./tools/edit.syn" as t_edit
+use "./tools/ls.syn" as t_ls
+use "./tools/find.syn" as t_find
+use "./tools/grep.syn" as t_grep
+use "./tools/bash.syn" as t_bash
+use "./tools/skill.syn" as t_skill
+use "./tools/process.syn" as t_process
+use "./tools/memo.syn" as t_memo
+use "./tools/todo.syn" as t_todo
+use "./skills.syn" as skills
+use "./mcp.syn" as mcp
+use "./lamps.syn" as lamps
+use "./lsp.syn" as lsp
+
+-- la task de la tool skill (su SPEC está en tools/skill.syn)
+task skill_tool(name, action, source, scope)
+    require exec
+    require time
+    require env("LAMPSON_*")
+    require env("OS")
+    require file.read("skills")
+    require file.read("skills/*")
+    require file.read("workspace")
+    require file.read("workspace/*")
+    require file.read(".lampson")
+    require file.read(".lampson/*")
+    when action == "install"
+        give skills.install(source, name, scope)
+    when action == "list"
+        let idx be skills.index()
+        let lines be []
+        each n in sort_by(keys(idx), (x) => x)
+            set lines to append(lines, n + " (" + idx[n]["source"] + "): " + idx[n]["description"])
+        give join(lines, "\n")
+    give skills.load(name)
+
+-- la task de la tool mcp (mcp.syn está un nivel arriba de tools/, así que vive acá, como skill_tool).
+-- add/remove SIEMPRE piden aprobación (permission.syn): conectar un server = ejecutar un comando de terceros.
+task mcp_tool(action, name, command, env, scope)
+    require exec
+    require time
+    require env("LAMPSON_*")
+    require env("OS")
+    require file(".lampson")
+    require file(".lampson/*")
+    require file("workspace")
+    require file("workspace/*")
+    when action == "add"
+        give mcp.add_server(name, command, env, scope)
+    when action == "remove"
+        give mcp.remove_server(name)
+    let sm be mcp.summary()
+    when length(sm) == 0
+        give "no MCP servers connected. Config files: " + mcp.GLOBAL_CONFIG + " (global) · " + mcp.PROJECT_CONFIG + " (this project)"
+    let lines be []
+    each ms in sm
+        set lines to append(lines, ms["name"] + " (" + ms["scope"] + ", " + ms["status"] + "): " + text(length(ms["tools"])) + " tools" + (when ms["error"] != nothing then " · " + text(ms["error"]) otherwise ""))
+    give join(lines, "\n")
+
+let MCP_SPEC be {
+    "name": "mcp",
+    "description": "Manage MCP (Model Context Protocol) servers. action=list (default): connected servers and their status. action=add: connect a server — name plus the full command line that starts it (e.g. command='npx -y @modelcontextprotocol/server-github'); scope=global (default) makes it available in every project (lampson/.lampson/mcp.json), scope=project only in this one (workspace/.lampson/mcp.json); env = extra environment variables the server needs (tokens, keys). action=remove: disconnect and delete it from the config. add/remove always ask the user for approval. A connected server's tools appear in your catalog as mcp_<server>_<tool> from the NEXT turn. Propose add when the user asks to connect/install an MCP or a task clearly needs one.",
+    "parameters": {"type": "object", "properties": {
+        "action": {"type": "string", "enum": ["list", "add", "remove"], "description": "Default: list"},
+        "name": {"type": "string", "description": "add/remove: server name (letters, digits, - or _)"},
+        "command": {"type": "string", "description": "add only: full command line that starts the server (quotes allowed)"},
+        "env": {"type": "object", "description": "add only: environment variables for the server, e.g. {\"GITHUB_TOKEN\": \"…\"}"},
+        "scope": {"type": "string", "enum": ["global", "project"], "description": "add only: global (default, every project) or project"}
+    }, "required": ["action"]}
+}
+
+-- la task de la tool lamp (lamps.syn vive un nivel arriba de tools/, como mcp). enable/disable piden humano
+-- SIEMPRE (permission.syn): encender = autorizar código a correr con las capacidades de su manifiesto.
+task lamp_tool(action, name, manifest, files)
+    require exec
+    require time
+    require env("LAMPSON_*")
+    require file(".lampson")
+    require file(".lampson/*")
+    require file.read("lamps")
+    require file.read("lamps/*")
+    require file("workspace")
+    require file("workspace/*")
+    when action == "create"
+        give lamps.create(name, manifest, files)
+    when action == "enable"
+        give lamps.set_enabled(name, true)
+    when action == "disable"
+        give lamps.set_enabled(name, false)
+    let sm be lamps.summary()
+    when length(sm) == 0
+        give "no lamps found. A lamp is a folder with a lamp.json manifest: " + lamps.GLOBAL_DIR + "/<name>/ (global) or " + lamps.PROJECT_DIR + "/<name>/ (this project; you can create it with write). See the lampson skill for the manifest format."
+    let lines be []
+    each l in sm
+        set lines to append(lines, l["name"] + " (" + l["scope"] + ", " + l["kind"] + ", " + (when l["enabled"] then "ON" otherwise "off") + "): " + (when l["error"] != nothing then "BROKEN — " + text(l["error"]) otherwise text(length(l["tools"])) + " tools [" + join(l["tools"], ", ") + "]" + (when l["description"] != "" then " — " + l["description"] otherwise "")))
+    give join(lines, "\n")
+
+let LAMP_SPEC be {
+    "name": "lamp",
+    "description": "Lamps are tool plugins you can build for this project: a folder with a lamp.json manifest plus code — a Synsema program (kind=syn) run under a capability ceiling, or any executable (kind=exec). Consider one when a task needs a reusable custom tool (a project-specific query, generator, checker) that plain bash would repeat clumsily. action=list (default): every lamp found, on/off, its tools. action=create: write a PROJECT lamp (name + manifest + files) — it validates the manifest and runs `synsema check` on a syn entry, but does NOT run or enable it. action=enable / disable: turn one on or off — ALWAYS asks the user (enabling authorizes its code to run with the manifest's capabilities). An enabled lamp's tools appear in your catalog as lamp_<lamp>_<tool> from the NEXT turn. Manifest: {\"description\", \"kind\": \"syn\"|\"exec\", \"entry\": \"lamp.syn\" (syn) | \"command\": \"python lamp.py\" (exec), \"caps\": \"file.read=workspace/*\" (syn, optional extra ceiling over stdout,time,env=LAMP_*), \"timeout\": 60, \"tools\": [{\"name\", \"description\", \"parameters\": JSON Schema, \"readonly\": bool}]}. Inside the code read LAMP_TOOL and LAMP_ARGS (JSON) from env and print the result to stdout (a .syn needs `require env(\"LAMP_*\")`). Lamp names: letters, digits, - (no _).",
+    "parameters": {"type": "object", "properties": {
+        "action": {"type": "string", "enum": ["list", "create", "enable", "disable"], "description": "Default: list"},
+        "name": {"type": "string", "description": "create/enable/disable: lamp name"},
+        "manifest": {"type": "object", "description": "create only: the lamp.json content (name is filled in)"},
+        "files": {"type": "object", "description": "create only: {\"lamp.syn\": \"<code>\", …} — files written into the lamp folder", "additionalProperties": {"type": "string"}}
+    }, "required": ["action"]}
+}
+
+-- la tool lsp (lib/lsp.syn): navegación semántica. Solo lectura → permission la permite siempre.
+task lsp_tool(op, path, line, character, server, scope)
+    require exec
+    require time
+    require env("LAMPSON_*")
+    require env("OS")
+    require file(".lampson")
+    require file(".lampson/*")
+    require file("workspace")
+    require file("workspace/*")
+    -- op=add: el agente propone un preset y el humano aprueba (permission.syn: ask siempre, como mcp add)
+    when op == "add"
+        give lsp.add_server(server, nothing, nothing, when scope == nothing then "global" otherwise scope)
+    when op == "list"
+        let sm be lsp.summary()
+        when length(sm) == 0
+            give "no language servers configured. Presets: " + join(keys(lsp.PRESETS), ", ") + " — propose op=add with server=<preset> (the user approves)."
+        give join(apply(sm, (x) => x["name"] + " (" + x["scope"] + ", " + x["status"] + "): " + join(x["extensions"], " ") + (when x["error"] != nothing then " · " + text(x["error"]) otherwise "")), "\n")
+    give lsp.query(op, path, line, character)
+
+let LSP_SPEC be {
+    "name": "lsp",
+    "description": "Semantic code navigation through the project's language server (same engine as the editor). Use it when grep is ambiguous or before a change that needs exact definitions/usages, and to see a file's structure WITHOUT reading it: op=symbols lists every function/class/variable with line ranges — then read only the range you need. op=definition: where the symbol under the cursor is defined. op=references: every usage (declaration included). op=implementation: implementations of an interface/abstract member. op=hover: type signature and docs. Positions are 1-based line and character, like the editor; put the cursor ON the identifier (an off-symbol position returns nothing). The server for a file is chosen by extension; if none is configured for that extension, propose op=add with server=<preset> (typescript, python, rust, go, css, html) — it always asks the user for approval and needs nothing installed (npx fetches it); op=list shows what is configured. The first query of a session starts the server (a few seconds).",
+    "parameters": {"type": "object", "properties": {
+        "op": {"type": "string", "enum": ["symbols", "definition", "references", "implementation", "hover", "list", "add"]},
+        "server": {"type": "string", "description": "add only: preset name (typescript | python | rust | go | css | html)"},
+        "scope": {"type": "string", "enum": ["global", "project"], "description": "add only: global (default, every project) or project"},
+        "path": {"type": "string", "description": "File path relative to the workspace root"},
+        "line": {"type": "integer", "description": "1-based line (not for symbols)"},
+        "character": {"type": "integer", "description": "1-based column of the identifier (not for symbols)"}
+    }, "required": ["op"]}
+}
+
+-- Allow-list nombre → task. El modelo solo devuelve NOMBRES; el loop decide si se ejecuta.
+export task registry()
+    give {
+        "read": t_read.tool,
+        "write": t_write.tool,
+        "edit": t_edit.tool,
+        "ls": t_ls.tool,
+        "find": t_find.tool,
+        "grep": t_grep.tool,
+        "bash": t_bash.tool,
+        "process": t_process.tool,
+        "memory": t_memo.tool,
+        "todo": t_todo.tool,
+        "skill": skill_tool,
+        "mcp": mcp_tool,
+        "lamp": lamp_tool,
+        "lsp": lsp_tool
+    }
+
+export let CATALOG be [t_read.SPEC, t_write.SPEC, t_edit.SPEC, t_ls.SPEC, t_find.SPEC, t_grep.SPEC, LSP_SPEC, t_bash.SPEC, t_process.SPEC, t_memo.SPEC, t_todo.SPEC, t_skill.SPEC, MCP_SPEC, LAMP_SPEC]
+
+-- Subconjuntos (para perfiles de agente): registry/catálogo filtrados por nombre.
+export task registry_subset(names)
+    let all be registry()
+    let out be {}
+    each n in names
+        when contains(all, n)
+            set out[n] to all[n]
+    give out
+
+export task catalog_subset(names)
+    give where(CATALOG, (s) => contains(names, s["name"]))
+
+-- Re-exports usados por los entries
+export task truncate(s, max)
+    give common.truncate(s, max)
+
+export task shell_config()
+    require env("LAMPSON_*")
+    require env("OS")
+    give t_bash.shell_config()

package/lib/trace.syn

@@ -0,0 +1,116 @@
+-- lib/trace.syn — traza legible de lo que hace el agente, por sesión: .lampson/trace/<sid>.log
+--
+-- Las sesiones (.lampson/sessions/*.json) guardan el historial canónico para el modelo; esto es para
+-- el HUMANO que quiere ver cómo trabajó el agente y dónde se equivoca: una línea por evento con hora,
+-- tiempo desde el evento anterior, paso, tokens, tool + args, resultado (primeras líneas), errores y
+-- denegaciones, avisos del buzón y subagentes. Se lee con `/trace [n]` (terminal), en la web (≡ en la
+-- sesión) o con cualquier editor / `tail -f`.
+--
+-- Formato de línea:  HH:MM:SS.mmm +Δs  [tag] KIND  texto
+--   Δs = segundos desde la línea anterior de la misma sesión (dónde se fue el tiempo: modelo vs tools).
+
+export let DIR be ".lampson/trace"
+let MAX_LINE be 600
+
+task path(sid)
+    give DIR + "/" + sid + ".log"
+
+task one_line(s, max)
+    let t be replace_text(replace_text(text(s), "\r", ""), "\n", " ⏎ ")
+    when length(t) > max
+        give slice(t, 0, max) + "…"
+    give t
+
+task pad2(n)
+    let t be text(floor(n))
+    when length(t) < 2
+        give "0" + t
+    give t
+
+task stamp()
+    let t be now()
+    let ms be floor((t - floor(t)) * 1000)
+    let mst be text(ms)
+    while length(mst) < 3
+        set mst to "0" + mst
+    give format_time(t, "%H:%M:%S") + "." + mst
+
+-- delta desde la última línea: guardamos el instante en <sid>.last
+task delta(sid)
+    let last be 0
+    try
+        set last to number(trim(read_file(DIR + "/" + sid + ".last")))
+    recover err
+        set last to 0
+    write_file(DIR + "/" + sid + ".last", text(now()))
+    when last == 0
+        give "      "
+    let d be now() - last
+    let s be text(floor(d * 10) / 10)
+    while length(s) < 5
+        set s to " " + s
+    give "+" + s
+
+export task write(sid, kind, line)
+    require time
+    require file(".lampson")
+    require file(".lampson/*")
+    when sid == nothing or sid == ""
+        give false
+    append_file(path(sid), stamp() + " " + delta(sid) + "s  " + kind + "  " + line + "\n")
+    give true
+
+-- eventos del loop (on_event de chat/web): kind ∈ assistant | tool_call | tool_result | tool_denied |
+-- error | usage | compact | inbox
+export task event(sid, kind, data, tag)
+    require time
+    require file(".lampson")
+    require file(".lampson/*")
+    let t be when tag == nothing or tag == "" then "" otherwise "[" + text(tag) + "] "
+    when kind == "usage"
+        let cached be when contains(data["usage"], "cached") then data["usage"]["cached"] otherwise 0
+        give write(sid, "STEP " + text(data["step"]), t + "modelo respondió · in=" + text(data["usage"]["input"]) + (when cached > 0 then " (cache " + text(cached) + ")" otherwise "") + " out=" + text(data["usage"]["output"]) + " · acumulado " + text(data["total"]["input"] + data["total"]["output"]))
+    when kind == "assistant"
+        give write(sid, "SAY ", t + one_line(data, MAX_LINE))
+    when kind == "tool_call"
+        give write(sid, "CALL", t + data["name"] + " " + one_line(json_encode(data["args"]), MAX_LINE))
+    when kind == "tool_result"
+        let out be text(data["output"])
+        let bad be starts_with(out, "ERROR") or starts_with(out, "DENIED")
+        give write(sid, when bad then "FAIL" otherwise "OK  ", t + data["call"]["name"] + " → " + one_line(out, MAX_LINE) + " (" + text(length(out)) + " chars)")
+    when kind == "tool_denied"
+        give write(sid, "DENY", t + data["call"]["name"] + " · " + one_line(data["reason"], MAX_LINE))
+    when kind == "error"
+        give write(sid, "ERR ", t + one_line(data, MAX_LINE))
+    when kind == "compact"
+        give write(sid, "PACK", t + "compactación de contexto (~" + text(data["before"]) + " tokens)")
+    when kind == "inbox"
+        give write(sid, "MAIL", t + one_line(data, MAX_LINE))
+    give false
+
+-- marcas de turno (las llaman chat.syn / web.syn)
+export task user(sid, content, agent, mode, model)
+    require time
+    require file(".lampson")
+    require file(".lampson/*")
+    give write(sid, "USER", "[" + agent + " · " + mode + " · " + model + "] " + one_line(content, MAX_LINE))
+
+export task turn_end(sid, result)
+    require time
+    require file(".lampson")
+    require file(".lampson/*")
+    give write(sid, "END ", text(result["steps"]) + " pasos · " + text(result["usage"]["input"] + result["usage"]["output"]) + " tokens · " + result["stopped"])
+
+export task tail(sid, n)
+    require file(".lampson")
+    require file(".lampson/*")
+    try
+        let lines be split(replace_text(read_file(path(sid)), "\r", ""), "\n")
+        when length(lines) > n
+            set lines to slice(lines, length(lines) - n, length(lines))
+        give join(lines, "\n")
+    recover err
+        give ""
+
+export task file_of(sid)
+    give path(sid)

package/lib/tree.syn

@@ -0,0 +1,59 @@
+-- lib/tree.syn — árbol de archivos del workspace (para el banner de terminal y el explorador web)
+use "./tools/common.syn" as c
+
+let MAX_ENTRIES be 2000
+
+task walk(dir, depth, max_depth, state)
+    let out be []
+    when depth > max_depth
+        give out
+    let entries be []
+    try
+        set entries to list_dir(dir)
+    recover err
+        give out
+    each e in entries
+        when state["n"] >= MAX_ENTRIES
+            give out
+        let rel be c.unws(dir + "/" + e["name"])
+        when e["is_dir"]
+            when not contains(c.IGNORED_DIRS, e["name"])
+                set state["n"] to state["n"] + 1
+                set out to append(out, {"name": e["name"], "path": rel, "is_dir": true, "children": walk(dir + "/" + e["name"], depth + 1, max_depth, state)})
+        otherwise
+            set state["n"] to state["n"] + 1
+            set out to append(out, {"name": e["name"], "path": rel, "is_dir": false, "size": e["size"]})
+    -- carpetas primero
+    give where(out, (x) => x["is_dir"]) + where(out, (x) => not x["is_dir"])
+
+-- árbol anidado: [{name, path, is_dir, size?, children?}]
+export task tree(max_depth)
+    require file.read("workspace")
+    require file.read("workspace/*")
+    let state be {"n": 0}
+    give {"entries": walk(c.ROOT, 0, max_depth, state), "count": state["n"], "truncated": state["n"] >= MAX_ENTRIES}
+
+-- render de texto para la terminal (2 niveles, compacto)
+export task render(max_depth, max_lines)
+    require file.read("workspace")
+    require file.read("workspace/*")
+    let t be tree(max_depth)
+    let lines be []
+    each e in t["entries"]
+        when length(lines) < max_lines
+            set lines to append(lines, "  " + e["name"] + (when e["is_dir"] then "/" otherwise ""))
+            when e["is_dir"] and contains(e, "children")
+                each ch in e["children"]
+                    when length(lines) < max_lines
+                        set lines to append(lines, "    " + ch["name"] + (when ch["is_dir"] then "/" otherwise ""))
+    when length(lines) >= max_lines
+        set lines to append(lines, "  … " + text(t["count"]) + " entradas en total — /files muestra el árbol completo")
+    give join(lines, "\n")
+
+-- contenido de un archivo para el visor web
+export task file_content(path)
+    require file.read("workspace")
+    require file.read("workspace/*")
+    let real be c.ws(path)
+    let content be read_file(real)
+    give {"path": c.unws(real), "content": c.truncate(content, 200000), "lines": length(split(content, "\n"))}

package/lib/update.syn

@@ -0,0 +1,57 @@
+-- lib/update.syn — ¿hay una versión nueva de Lampson? (git fetch contra origin/main)
+--
+-- Lampson se instala como clon de git (install.ps1 / install.sh), así que "actualizar" es un
+-- `git pull --ff-only`. check() compara HEAD con origin/main; el cwd es el directorio de lampson
+-- (el launcher hace cd antes de arrancar). Sin red o sin .git devuelve available=false en silencio.
+-- Cuando la distribución cambie (exe, app de escritorio), cambiar COMMAND y apply() acá y en el skill.
+
+export let COMMAND be "lampson --update"
+
+task run_git(args, secs)
+    try
+        let r be run("git", args, secs)
+        when r["exit_code"] != 0
+            give nothing
+        give trim(replace_text(r["stdout"], "\r", ""))
+    recover err
+        give nothing
+
+-- {available, behind, current, latest, notes: [líneas del log], command}
+export task check()
+    require exec("git")
+    require net
+    let current be run_git(["rev-parse", "--short", "HEAD"], 5)
+    let none be {"available": false, "behind": 0, "current": when current == nothing then "" otherwise current, "latest": "", "notes": [], "command": COMMAND}
+    when current == nothing
+        give none
+    when run_git(["fetch", "-q", "origin", "main"], 12) == nothing
+        give none
+    let behind be run_git(["rev-list", "--count", "HEAD..origin/main"], 5)
+    when behind == nothing or behind == "0"
+        give none
+    let latest be run_git(["rev-parse", "--short", "origin/main"], 5)
+    let log be run_git(["log", "--format=%s", "-5", "HEAD..origin/main"], 5)
+    let notes be when log == nothing then [] otherwise where(split(log, "\n"), (l) => trim(l) != "")
+    give {"available": true, "behind": floor(number(behind)), "current": current, "latest": when latest == nothing then "" otherwise latest, "notes": notes, "command": COMMAND}
+
+-- una línea para banners; "" si no hay nada
+export task line()
+    require exec("git")
+    require net
+    let u be check()
+    when not u["available"]
+        give ""
+    give "hay una versión nueva de Lampson (" + text(u["behind"]) + (when u["behind"] == 1 then " commit" otherwise " commits") + ", " + u["current"] + " → " + u["latest"] + ") · corré " + COMMAND
+
+-- aplica la actualización; devuelve el texto para mostrar
+export task apply()
+    require exec("git")
+    require net
+    try
+        let r be run("git", ["pull", "--ff-only", "origin", "main"], 60)
+        when r["exit_code"] != 0
+            give "no se pudo actualizar: " + trim(r["stderr"]) + "\n(si modificaste archivos de lampson, guardalos con git stash y volvé a intentar)"
+        let now be run_git(["rev-parse", "--short", "HEAD"], 5)
+        give "actualizado a " + (when now == nothing then "HEAD" otherwise now) + " · reiniciá lampson para usar la versión nueva"
+    recover err
+        give "no se pudo actualizar: " + text(err)

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "lampson",
+  "version": "0.1.0",
+  "description": "A coding agent written in Synsema: terminal + web, tools confined to the mounted project, lamps (your own tool plugins), LSP, MCP, sub-agents.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kitecosmic/lampson.git"
+  },
+  "homepage": "https://github.com/kitecosmic/lampson#readme",
+  "bugs": "https://github.com/kitecosmic/lampson/issues",
+  "keywords": ["agent", "coding-agent", "synsema", "llm", "cli", "lsp", "mcp"],
+  "bin": {
+    "lampson": "bin/lampson.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "public/",
+    "skills/",
+    "lamps/",
+    "chat.syn",
+    "web.syn",
+    "lampson.ps1",
+    "lampson.sh",
+    "lampson.cmd",
+    ".env.example",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "synsema": "^0.6.10"
+  },
+  "scripts": {
+    "test": "pwsh -NoProfile -File tests/run.ps1"
+  }
+}