lampson 0.1.0

package/lib/settings.syn

@@ -0,0 +1,70 @@
+-- lib/settings.syn — configuración editable en caliente: proveedor, modelo y API keys
+--
+-- Dónde: lampson/.lampson/config.json (gitignored, local). Lo escriben el onboarding de la terminal, la
+-- ventana "proveedor" de la web y /provider. .env sigue valiendo (LAMPSON_PROVIDER, LAMPSON_API_KEY[_X]):
+-- config.json gana sobre .env, y una key guardada acá se sella con as_secret() al leerla (nunca se
+-- devuelve al navegador ni se imprime; el frontend solo ve has_key).
+--
+-- Forma: {"provider": "deepseek", "model": "deepseek-chat", "keys": {"deepseek": "sk-…"}}
+
+let PATH be ".lampson/config.json"
+
+export task load()
+    require file.read(".lampson")
+    require file.read(".lampson/*")
+    require env("LAMPSON_*")
+    -- LAMPSON_NO_CONFIG=1: ignorar config.json (proveedor/key reales) — lo fija tests/run.ps1|sh para que la
+    -- suite hable SOLO con el mock (2026-08-27: agents_test gastó tokens reales de DeepSeek por no tenerlo)
+    when env("LAMPSON_NO_CONFIG", "") == "1"
+        give {"provider": "", "model": "", "keys": {}}
+    try
+        let doc be json_decode(read_file(PATH))
+        -- claves siempre presentes: quien lee no tiene que chequear (y `and` no cortocircuita)
+        when not contains(doc, "keys")
+            set doc["keys"] to {}
+        when not contains(doc, "provider")
+            set doc["provider"] to ""
+        when not contains(doc, "model")
+            set doc["model"] to ""
+        give doc
+    recover err
+        give {"provider": "", "model": "", "keys": {}}
+
+export task save(doc)
+    require file(".lampson")
+    require file(".lampson/*")
+    write_file(PATH, json_encode(doc))
+    give true
+
+-- key guardada para un proveedor, como TEXTO ("" si no hay). Sellarla con as_secret antes de usarla.
+export task raw_key(name)
+    require file.read(".lampson")
+    require file.read(".lampson/*")
+    let doc be load()
+    when contains(doc["keys"], lower(name))
+        give text(doc["keys"][lower(name)])
+    give ""
+
+export task set_key(name, key)
+    require file(".lampson")
+    require file(".lampson/*")
+    let doc be load()
+    when trim(key) == ""
+        let keys be {}
+        each k in keys(doc["keys"])
+            when k != lower(name)
+                set keys[k] to doc["keys"][k]
+        set doc["keys"] to keys
+    otherwise
+        set doc["keys"][lower(name)] to trim(key)
+    save(doc)
+    give true
+
+export task set_default(name, model)
+    require file(".lampson")
+    require file(".lampson/*")
+    let doc be load()
+    set doc["provider"] to lower(name)
+    set doc["model"] to model
+    save(doc)
+    give true

package/lib/skills.syn

@@ -0,0 +1,179 @@
+-- lib/skills.syn — skills: procedimientos en Markdown que el modelo carga bajo demanda 
+--
+-- Una skill = carpeta con SKILL.md y frontmatter YAML mínimo:
+--   ---
+--   name: deploy
+--   description: Cómo desplegar este proyecto (una línea; es lo que ve el modelo en el índice)
+--   ---
+--   ...instrucciones...
+--
+-- Se buscan en (prioridad de abajo hacia arriba, el nombre repetido gana el más específico):
+--   .lampson/skills-global/<name>/SKILL.md     -- ~/.agents/skills  (junction que crea lampson.ps1/sh; `npx skills add -g`)
+--   .lampson/skills-claude/<name>/SKILL.md     -- ~/.claude/skills  (idem; las de Claude Code también sirven acá)
+--   skills/<name>/SKILL.md                     -- del harness (enseñan a usar lampson y Synsema)
+--   workspace/.claude/skills/<name>/SKILL.md   -- del proyecto, instaladas para Claude Code
+--   workspace/.agents/skills/<name>/SKILL.md   -- del proyecto, canónico de `npx skills add owner/repo` (skills.sh)
+--   workspace/skills/<name>/SKILL.md           -- del proyecto (committeables)
+--   workspace/.lampson/skills/<name>/SKILL.md  -- locales al proyecto (no committeadas)
+--
+-- Skills externas (2026-08-27): el estándar "Agent Skills" (agentskills.io) es el mismo formato que usamos
+-- (SKILL.md + frontmatter name/description), así que NO hay instalador propio: `npx skills add owner/repo
+-- --skill x` deja la skill en ./.agents/skills (o ~/.agents/skills con -g) y Lampson la ve en el próximo
+-- arranque. Las carpetas de HOME no se pueden declarar como capability con ruta dinámica → se MONTAN
+-- bajo .lampson/ (mismo truco que workspace/).
+--
+-- El system prompt lleva SOLO el índice (name + description); el contenido entra al contexto
+-- cuando el modelo llama a la tool `skill(name)`. Así el prompt no crece con cada skill.
+
+let ROOTS be [
+    {"dir": ".lampson/skills-global", "source": "global"},
+    {"dir": ".lampson/skills-claude", "source": "global"},
+    {"dir": "skills", "source": "harness"},
+    {"dir": "workspace/.claude/skills", "source": "project"},
+    {"dir": "workspace/.agents/skills", "source": "project"},
+    {"dir": "workspace/skills", "source": "project"},
+    {"dir": "workspace/.lampson/skills", "source": "local"}
+]
+
+task frontmatter(md)
+    -- devuelve {name, description, body}; sin frontmatter → name vacío
+    let out be {"name": "", "description": "", "body": md}
+    when not starts_with(md, "---")
+        give out
+    let rest be slice(md, 3, length(md))
+    let parts be split(rest, "\n---")
+    when length(parts) < 2
+        give out
+    let head be parts[0]
+    let body be join(slice(parts, 1, length(parts)), "\n---")
+    each line in split(head, "\n")
+        let l be trim(line)
+        when starts_with(l, "name:")
+            set out["name"] to trim(slice(l, 5, length(l)))
+        otherwise when starts_with(l, "description:")
+            set out["description"] to trim(slice(l, 12, length(l)))
+    set out["body"] to trim(body)
+    give out
+
+task scan_root(root, acc)
+    let out be acc
+    try
+        each e in list_dir(root["dir"])
+            when e["is_dir"]
+                let path be root["dir"] + "/" + e["name"] + "/SKILL.md"
+                try
+                    let fm be frontmatter(read_file(path))
+                    let name be when fm["name"] == "" then e["name"] otherwise fm["name"]
+                    set out[name] to {"name": name, "description": fm["description"], "path": path, "source": root["source"]}
+                recover err
+                    set out to out
+    recover err
+        give out
+    give out
+
+-- índice: map name → {name, description, path, source}
+export task index()
+    require file.read("skills")
+    require file.read("skills/*")
+    require file.read("workspace")
+    require file.read("workspace/*")
+    require file.read(".lampson")
+    require file.read(".lampson/*")
+    let acc be {}
+    each r in ROOTS
+        set acc to scan_root(r, acc)
+    give acc
+
+-- sección del system prompt
+export task prompt_section(idx)
+    let names be sort_by(keys(idx), (n) => n)
+    when length(names) == 0
+        give ""
+    let lines be ["", "# Skills (load one with the `skill` tool when relevant — read it BEFORE doing that kind of task)"]
+    each n in names
+        let s be idx[n]
+        set lines to append(lines, "- " + n + " (" + s["source"] + "): " + s["description"])
+    give join(lines, "\n")
+
+export task load(name)
+    require file.read("skills")
+    require file.read("skills/*")
+    require file.read("workspace")
+    require file.read("workspace/*")
+    require file.read(".lampson")
+    require file.read(".lampson/*")
+    let idx be index()
+    when not contains(idx, name)
+        raise("unknown skill '" + name + "'. Available: " + join(sort_by(keys(idx), (n) => n), ", "))
+    let s be idx[name]
+    let fm be frontmatter(read_file(s["path"]))
+    -- archivos hermanos de la skill (scripts, templates) para que el modelo sepa que existen
+    let dir be slice(s["path"], 0, length(s["path"]) - length("/SKILL.md"))
+    let extras be []
+    each e in list_dir(dir)
+        when e["name"] != "SKILL.md"
+            set extras to append(extras, dir + "/" + e["name"] + (when e["is_dir"] then "/" otherwise ""))
+    let head be "# skill: " + name + " (" + s["source"] + ", " + s["path"] + ")\n"
+    when length(extras) > 0
+        set head to head + "Files in this skill: " + join(extras, ", ") + "\n"
+    give head + "\n" + fm["body"]
+
+-- ---------- instalación de skills externas (skills.sh / cualquier repo con SKILL.md) ----------
+-- No reinventamos el instalador: `npx skills add <owner/repo> --skill <name>` (vercel-labs/skills) escribe
+-- en ./.agents/skills (scope project) o ~/.agents/skills (-g, scope global — sirve para TODOS los proyectos,
+-- que es lo que uno quiere con una skill de Go, de Next, de diseño…). `-a codex -y` = no interactivo
+-- (codex ya usa la carpeta canónica, así que no crea symlinks extra; verificado 2026-08-27). Es una acción
+-- con efectos fuera del workspace → permission.syn la marca "ask" SIEMPRE (human in the loop), incluso en yolo.
+task shell_exe()
+    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_slug(s)
+    when s == nothing or s == ""
+        give false
+    give matches(s, "[a-zA-Z0-9._/@:-]{1,120}")
+
+-- la junction/symlink .lampson/skills-global → ~/.agents/skills la crea lampson.ps1/sh al arrancar, pero si
+-- la carpeta HOME no existía todavía (primera instalación global) hay que crear ambas ahora
+task ensure_global_mount()
+    require exec
+    require env("LAMPSON_*")
+    require env("OS")
+    let is_win be env("OS", "") == "Windows_NT"
+    let win be "src=\"$USERPROFILE/.agents/skills\"; mkdir -p \"$src\"; [ -e .lampson/skills-global ] || cmd //c mklink //J \".lampson\\\\skills-global\" \"$(cygpath -w \"$src\")\" >/dev/null"
+    let unix be "src=\"$HOME/.agents/skills\"; mkdir -p \"$src\"; [ -e .lampson/skills-global ] || ln -s \"$src\" .lampson/skills-global"
+    run(shell_exe(), ["-c", when is_win then win otherwise unix], 30, {"cwd": "."})
+
+task tail_out(s)
+    let t be strip_ansi(replace_text(s, "\r", ""))
+    when length(t) > 3000
+        give slice(t, length(t) - 3000, length(t))
+    give t
+
+export task install(source, name, 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 not valid_slug(source)
+        raise("invalid source '" + text(source) + "' (expected owner/repo or a github URL)")
+    when not valid_slug(name)
+        raise("invalid skill name '" + text(name) + "'")
+    let global be scope != "project"
+    let argv be ["-y", "skills", "add", source, "--skill", name, "-a", "codex", "-y"]
+    when global
+        set argv to append(argv, "-g")
+        ensure_global_mount()
+    let r be run(shell_exe(), ["-c", "CI=1 npx " + join(argv, " ") + " 2>&1"], 240, {"cwd": when global then "." otherwise "workspace"})
+    let idx be index()
+    when contains(idx, name)
+        give "installed skill '" + name + "' (" + (when global then "global: ~/.agents/skills, available in every project" otherwise "project: ./.agents/skills") + "). It is in the skills index now — call skill(name=\"" + name + "\") to load it.\n" + tail_out(r["stdout"])
+    give "npx skills finished (exit " + text(r["exit_code"]) + ") but '" + name + "' is not in the skills index. Output:\n" + tail_out(r["stdout"])

package/lib/tools/bash.syn

@@ -0,0 +1,105 @@
+-- lib/tools/bash.syn — ejecutar un comando de shell con cwd = workspace/
+--
+-- MIGAS:
+--   * en Windows `bash` a secas resuelve al de WSL y cuelga; usar Git Bash explícito (default) o cmd.
+--   * NO usar `run()` para el comando del modelo: se cuelga para siempre si el comando deja un
+--     descendiente vivo (Windows hereda el pipe de stdout) y su timeout mata solo al hijo directo.
+--     Desde 2026-08-27 el comando corre con `proc_spawn` (v0.6.9): eventos por línea hasta el exit o el
+--     plazo, stdin cerrado (EOF: nada se queda esperando teclado), y `proc_close` mata el ÁRBOL
+--     (Job Object / process group) — un nieto con el pipe abierto no cuelga (1 s de gracia). Adiós
+--     bash_wrapper.sh y archivos temporales.
+--   * el proceso hijo NO hereda el scope de Synsema (un `cat ../x` en bash funciona). El aislamiento del
+--     shell lo dan permission.syn (patrones) + el operador (contenedor si hace falta).
+use "./common.syn" as c
+use "./proc.syn" as proc
+
+export task shell_config()
+    require env("LAMPSON_*")
+    require env("OS")
+    let is_win be env("OS", "") == "Windows_NT"
+    let shell be env("LAMPSON_SHELL", when is_win then "C:\\Program Files\\Git\\bin\\bash.exe" otherwise "bash")
+    let is_cmd be c.ends_with(lower(shell), "cmd.exe") or lower(shell) == "cmd"
+    give {"shell": shell, "flag": env("LAMPSON_SHELL_FLAG", when is_cmd then "/c" otherwise "-c"), "is_cmd": is_cmd}
+
+-- comandos que son servidores/watchers: rechazarlos ANTES de correrlos. El timeout mata el árbol, pero
+-- un servidor lanzado acá dejó un huérfano con el puerto 3000 tomado y el `process` real se fue al 3001
+-- (2026-08-27). La descripción ya lo decía; el modelo lo intentó igual "con | head" — hay que impedirlo.
+let SERVER_RE be ".*((npm|pnpm|yarn|bun)( run)? (dev|start|serve|watch|preview)|npx (next|vite|nodemon|serve|http-server)|next (dev|start)|vite( |$)|nodemon|synsema serve|uvicorn|gunicorn|flask run|manage\\.py runserver|python3? -m http\\.server|rails s(erver)?|php -S|ng serve|cargo (run|watch)|go run|dotnet (run|watch)|tail -f).*"
+
+export task looks_like_server(command)
+    let cmd be trim(lower(replace_text(command, "\n", " ")))
+    when matches(cmd, "timeout [0-9]+.*")
+        give false
+    give matches(cmd, SERVER_RE)
+
+-- corre argv con plazo real: junta stdout+stderr por líneas, corta al plazo y mata el árbol
+export task run_capture(exe, argv, t)
+    require exec
+    require time
+    require file("workspace")
+    require file("workspace/*")
+    let p be proc_spawn(exe, argv, {"cwd": c.ROOT, "stderr": "merge", "on_full": "drop_oldest"})
+    proc_close_stdin(p)
+    let deadline be now() + t
+    let lines be []
+    let size be 0
+    let cut be false
+    let code be nothing
+    let timed_out be false
+    while code == nothing and not timed_out
+        let left be deadline - now()
+        when left <= 0
+            set timed_out to true
+        otherwise
+            let ev be proc_recv(p, when left < 0.2 then 0.2 otherwise left)
+            when ev == nothing
+                set timed_out to now() >= deadline
+            otherwise when ev["type"] == "exit"
+                set code to ev["data"]["exit_code"]
+            otherwise when size < 1000000
+                set lines to append(lines, ev["data"])
+                set size to size + length(ev["data"]) + 1
+            otherwise
+                set cut to true
+    proc_close(p)
+    let out be join(lines, "\n")
+    when cut
+        set out to out + "\n[output truncated at 1 MB]"
+    when timed_out
+        give "ERROR: timeout after " + text(t) + "s — the command and its child processes were killed. For servers/watchers use the process tool. Output so far:\n" + out
+    when code != 0
+        set out to out + "\n[exit code " + text(code) + "]"
+    give out
+
+export task tool(command, timeout)
+    require exec
+    require time
+    require env("LAMPSON_*")
+    require env("OS")
+    require file(".lampson")
+    require file(".lampson/*")
+    when looks_like_server(command)
+        give "REFUSED: this looks like a server/watcher (`" + command + "`). bash kills its process tree at the timeout, and a dev server left half-killed keeps its port busy. Use the process tool instead: process(action=\"start\", name=\"dev\", command=\"...\"), then process(action=\"logs\") or just keep working — its new output is appended to every bash result. If it is really a one-shot command, wrap it with `timeout 30 ...` and explain why."
+    let sc be shell_config()
+    let t be when timeout == nothing then 120 otherwise floor(timeout)
+    when t > 600
+        set t to 600
+    when t < 1
+        set t to 1
+    let out be run_capture(sc["shell"], [sc["flag"], command], t)
+    when trim(out) == ""
+        set out to "(no output)"
+    -- lo que pasó mientras tanto en los procesos gestionados (servidores) — el agente "ve la consola"
+    let rep be proc.report()
+    when rep != ""
+        set out to out + "\n\n" + rep
+    give c.truncate(out, c.MAX_OUTPUT)
+
+export let SPEC be {
+    "name": "bash",
+    "description": "Run a shell command with the workspace root as working directory (no persistent shell state between calls: cwd and env reset). Returns stdout+stderr and [exit code N] when non-zero. Use it for git, tests, builds, package managers. Commands are killed (with their child processes) after the timeout (default 120s, max 600) — so NEVER run a server, watcher or REPL here: use the `process` tool (start/logs/stop) for anything long-running; its new log lines are appended to every bash result automatically. Avoid interactive commands. Prefer read/grep/find over cat/grep/find for files.",
+    "parameters": {"type": "object", "properties": {
+        "command": {"type": "string"},
+        "timeout": {"type": "integer", "description": "Seconds (optional, default 120, max 600)"}
+    }, "required": ["command"]}
+}

package/lib/tools/common.sh

@@ -0,0 +1,49 @@
+# common.sh — helpers de shell de proc.sh (kill_tree para pids AJENOS; Windows/Git Bash, Linux, macOS)
+#
+# Windows (MSYS/Git Bash): hay DOS árboles. El de MSYS (bash → bash) no lo ve taskkill /T, así que se
+# recorre PPID→PID con `ps`; y cada bash puede tener descendientes NATIVOS (npm.cmd → cmd → node → node)
+# que MSYS no ve pero Windows sí: por eso a cada WINPID se le hace `taskkill /T /F` (árbol nativo).
+# Sin el /T, un `npm run dev` lanzado desde bash sobrevivía al timeout con el puerto tomado (2026-08-27).
+# Linux/macOS: `pgrep -P` para descender y kill -9. (Probado en Windows; unix escrito con cuidado, sin probar.)
+is_win() { case "$(uname -s 2>/dev/null)" in MINGW*|MSYS*|CYGWIN*) return 0 ;; *) return 1 ;; esac; }
+
+kill_tree() {
+    local root="$1" k
+    if is_win; then
+        for k in $(ps 2>/dev/null | awk -v p="$root" 'NR>1 && $2==p {print $1}'); do kill_tree "$k"; done
+        local w; w="$(ps 2>/dev/null | awk -v p="$root" 'NR>1 && $1==p {print $4}')"
+        if [ -n "$w" ] && command -v taskkill >/dev/null 2>&1; then taskkill //T //F //PID "$w" >/dev/null 2>&1; fi
+        kill -9 "$root" 2>/dev/null
+    else
+        for k in $(pgrep -P "$root" 2>/dev/null); do kill_tree "$k"; done
+        kill -9 "$root" 2>/dev/null
+    fi
+}
+
+# ¿el PID sigue siendo NUESTRO proceso (y no otro que reutilizó el número tras un reinicio)?
+# Windows: el WINPID guardado en el pidfile debe coincidir con el actual. (Antes se exigía que el
+# COMMAND fuera "bash": falso negativo, porque `bash -c "a && npm run dev"` hace exec del último comando
+# y ps pasa a mostrar cmd/node → el process tool declaraba "EXITED" a un servidor vivo, 2026-08-27.)
+# Unix: comparamos el instante de arranque guardado en el pidfile.
+pid_alive() {
+    local pid="$1" stamp="$2"
+    [ -n "$pid" ] || return 1
+    kill -0 "$pid" 2>/dev/null || return 1
+    if is_win; then
+        local w; w="$(ps -p "$pid" 2>/dev/null | awk 'NR>1 {print $4; exit}')"
+        [ -n "$w" ] || return 1
+        if [ -n "$stamp" ]; then [ "$w" = "$stamp" ] || return 1; fi
+    else
+        if [ -n "$stamp" ]; then
+            local now; now="$(ps -o lstart= -p "$pid" 2>/dev/null | tr -s ' ')"
+            [ "$now" = "$stamp" ] || return 1
+        fi
+    fi
+    return 0
+}
+
+proc_stamp() {
+    if is_win; then ps -p "$1" 2>/dev/null | awk 'NR>1 {print $4; exit}'; else ps -o lstart= -p "$1" 2>/dev/null | tr -s ' '; fi
+}
+
+abs() { case "$1" in /*|?:*) printf '%s' "$1" ;; *) printf '%s/%s' "$PWD" "$1" ;; esac; }

package/lib/tools/common.syn

@@ -0,0 +1,91 @@
+-- lib/tools/common.syn — helpers compartidos por las tools (puros, sin capacidades)
+--
+-- MODELO DE WORKSPACE (miga de seguridad, verificada en v0.6.7):
+--   el scope `file("./*")` se comporta como `"*"` (disco entero) — un bug del runtime; `file("dir/*")`
+--   sí deniega `..`, absolutos y hermanos. Por eso el proyecto objetivo se MONTA como `./workspace`
+--   (junction en Windows / symlink en unix, lo hace lampson.ps1 / lampson.sh) y TODAS las tools
+--   declaran `file("workspace/*")`. El modelo ve paths relativos a la raíz del workspace; `ws()` los
+--   traduce. Es el mismo modelo mental que `docker -v proyecto:/workspace`.
+
+export let ROOT be "workspace"
+export let MAX_OUTPUT be 30000
+export let IGNORED_DIRS be [".git", "node_modules", ".synsema", ".lampson", "workspace", "target", "dist", "build", "coverage", "__pycache__", ".venv", ".next", ".netlify", ".cache", ".turbo"]
+
+-- path del modelo → path real bajo workspace/
+export task ws(path)
+    let p be when path == nothing then "." otherwise replace_text(text(path), "\\", "/")
+    let stripping be true
+    while stripping
+        when starts_with(p, "./")
+            set p to slice(p, 2, length(p))
+        otherwise when starts_with(p, "/")
+            set p to slice(p, 1, length(p))
+        otherwise
+            set stripping to false
+    when p == "." or p == "" or p == ROOT
+        give ROOT
+    when starts_with(p, ROOT + "/")
+        give p
+    -- los resultados largos van a .lampson/spill/<call>.txt (loop.spill) y el modelo los relee con read/grep:
+    -- viven en la raíz de lampson, no en el workspace (2026-08-28: "File not found: workspace/.lampson/spill/…")
+    when starts_with(p, ".lampson/spill/") and not contains(p, "..")
+        give p
+    give ROOT + "/" + p
+
+-- path real → path como lo ve el modelo
+export task unws(path)
+    when starts_with(path, ROOT + "/")
+        give slice(path, length(ROOT) + 1, length(path))
+    when path == ROOT
+        give "."
+    give path
+
+export task truncate(s, max)
+    when length(s) > max
+        give slice(s, 0, max) + `\n\n[... truncated: {text(length(s) - max)} more chars ...]`
+    give s
+
+export task ends_with(s, suffix)
+    when length(suffix) > length(s)
+        give false
+    give slice(s, length(s) - length(suffix), length(s)) == suffix
+
+-- glob mínimo: "*.ts" (sufijo), "test_*" (prefijo), "*foo*" (contiene), exacto.
+export task glob_match(name, pat)
+    when pat == "*"
+        give true
+    when pat == ""
+        give true
+    let star_first be starts_with(pat, "*")
+    let star_last be ends_with(pat, "*")
+    when star_first and star_last
+        give contains(name, slice(pat, 1, length(pat) - 1))
+    when star_first
+        give ends_with(name, slice(pat, 1, length(pat)))
+    when star_last
+        give starts_with(name, slice(pat, 0, length(pat) - 1))
+    give name == pat
+
+-- ---------- leer antes de editar (política de observación, tomada de deepseek-harness fs-observation-policy) ----------
+-- `read` registra en el blackboard el hash del archivo que el modelo vio ("observed:<path>"); `edit` y `write`
+-- sobre un archivo existente exigen esa observación y que el archivo no haya cambiado desde entonces (CAS por
+-- hash). Es un gate en CÓDIGO, no una regla de prompt: elimina "edita a ciegas y pisa" sin gastar tokens.
+export task file_hash(real)
+    require file.read("workspace")
+    require file.read("workspace/*")
+    give decode(sha256(read_file(real)), "hex")
+
+export task mark_observed(real)
+    require file.read("workspace")
+    require file.read("workspace/*")
+    share file_hash(real) as "observed:" + real
+
+export task check_observed(real, action)
+    require file.read("workspace")
+    require file.read("workspace/*")
+    observe "observed:" + real as seen
+    let shown be unws(real)
+    when seen == nothing
+        raise(action + " requires reading \"" + shown + "\" first: call read on it (the whole file, or the region you will change), then " + action)
+    when seen != file_hash(real)
+        raise("\"" + shown + "\" changed on disk since you read it (another tool, a build, or the user): read it again, then " + action)

package/lib/tools/edit.syn

@@ -0,0 +1,32 @@
+-- lib/tools/edit.syn — reemplazo exacto y único (sin fuzzy replacers: exactitud antes que magia)
+use "./common.syn" as c
+
+export task tool(path, old_string, new_string, replace_all)
+    require file("workspace")
+    require file("workspace/*")
+    let real be c.ws(path)
+    let shown be c.unws(real)
+    c.check_observed(real, "edit")
+    let content be read_file(real)
+    let parts be split(content, old_string)
+    let n be length(parts) - 1
+    when n == 0
+        raise("old_string not found in " + shown + " — read the file and copy the exact text (whitespace included)")
+    let all be when replace_all == nothing then false otherwise replace_all
+    when n > 1
+        when not all
+            raise(`old_string appears {text(n)} times in {shown}; include more surrounding context to make it unique, or pass replace_all=true`)
+    write_file(real, join(parts, new_string))
+    c.mark_observed(real)
+    give `edited {shown}: {text(n)} replacement(s)`
+
+export let SPEC be {
+    "name": "edit",
+    "description": "Replace an exact string in a file. old_string must match EXACTLY (including whitespace and indentation) and be unique in the file, otherwise the call fails — include more surrounding lines to disambiguate, or set replace_all=true to replace every occurrence. The file MUST have been read in this session (and not changed since), or the call is rejected.",
+    "parameters": {"type": "object", "properties": {
+        "path": {"type": "string"},
+        "old_string": {"type": "string"},
+        "new_string": {"type": "string"},
+        "replace_all": {"type": "boolean"}
+    }, "required": ["path", "old_string", "new_string"]}
+}

package/lib/tools/find.syn

@@ -0,0 +1,35 @@
+-- lib/tools/find.syn — buscar archivos por nombre (walk recursivo con glob mínimo)
+use "./common.syn" as c
+
+task walk(dir, pat, acc, depth)
+    when depth > 8
+        give acc
+    when length(acc) > 500
+        give acc
+    let out be acc
+    each e in list_dir(dir)
+        let full be dir + "/" + e["name"]
+        when e["is_dir"]
+            when not contains(c.IGNORED_DIRS, e["name"])
+                set out to walk(full, pat, out, depth + 1)
+        otherwise
+            when c.glob_match(e["name"], pat)
+                set out to append(out, c.unws(full))
+    give out
+
+export task tool(pattern, path)
+    require file.read("workspace")
+    require file.read("workspace/*")
+    let found be walk(c.ws(path), pattern, [], 0)
+    when length(found) == 0
+        give "no files matched " + pattern
+    give join(found, "\n")
+
+export let SPEC be {
+    "name": "find",
+    "description": "Find files by name pattern, recursively (skips .git, node_modules, build dirs). Pattern is a simple glob: '*.ts', 'test_*', '*config*', or an exact name. Returns paths relative to the workspace root, max 500.",
+    "parameters": {"type": "object", "properties": {
+        "pattern": {"type": "string"},
+        "path": {"type": "string", "description": "Directory to start from (default: workspace root)"}
+    }, "required": ["pattern"]}
+}

package/lib/tools/grep.syn

@@ -0,0 +1,31 @@
+-- lib/tools/grep.syn — buscar contenido (builtin grep: streaming por línea, literal o regex)
+use "./common.syn" as c
+
+export task tool(pattern, path, glob, regex)
+    require file.read("workspace")
+    require file.read("workspace/*")
+    require file.read(".lampson")
+    require file.read(".lampson/*")
+    let rx be when regex == nothing then true otherwise regex
+    let opts be when glob == nothing then {"regex": rx, "max_results": 200} otherwise {"regex": rx, "max_results": 200, "glob": glob}
+    let r be grep(c.ws(path), pattern, opts)
+    let lines be []
+    each m in r["matches"]
+        set lines to append(lines, c.unws(replace_text(m["file"], "\\", "/")) + ":" + text(m["line"]) + ": " + trim(m["text"]))
+    when length(lines) == 0
+        give "no matches"
+    let out be join(lines, "\n")
+    when r["truncated"]
+        set out to out + "\n[truncated at 200 results]"
+    give c.truncate(out, c.MAX_OUTPUT)
+
+export let SPEC be {
+    "name": "grep",
+    "description": "Search file contents (regex by default; set regex=false for a literal). Returns 'file:line: text' lines, max 200. Use glob to filter filenames (e.g. '*.syn').",
+    "parameters": {"type": "object", "properties": {
+        "pattern": {"type": "string"},
+        "path": {"type": "string", "description": "File or directory (default: workspace root)"},
+        "glob": {"type": "string"},
+        "regex": {"type": "boolean"}
+    }, "required": ["pattern"]}
+}

package/lib/tools/img.ps1

@@ -0,0 +1,36 @@
+# img.ps1 — imágenes para el REPL (Windows). Imprime UNA línea: media_type|ancho|alto|base64
+#   powershell -File lib/tools/img.ps1 clip            # imagen del portapapeles (PNG)
+#   powershell -File lib/tools/img.ps1 file <ruta>     # archivo png/jpg/gif/webp
+# Reduce el lado mayor a 1568 px (lo que un modelo con visión aprovecha) y saca PNG, o JPEG si queda pesado.
+param([string]$Mode, [string]$Path)
+$ErrorActionPreference = "Stop"
+Add-Type -AssemblyName System.Drawing
+Add-Type -AssemblyName System.Windows.Forms
+
+if ($Mode -eq "clip") {
+    $img = [System.Windows.Forms.Clipboard]::GetImage()
+    if ($null -eq $img) { Write-Output "ERROR|no hay una imagen en el portapapeles (copiá una captura o una imagen y repetí /paste)"; exit 0 }
+} else {
+    if (-not (Test-Path -LiteralPath $Path)) { Write-Output "ERROR|no existe $Path"; exit 0 }
+    $img = [System.Drawing.Image]::FromFile((Resolve-Path -LiteralPath $Path).Path)
+}
+
+$max = 1568
+$scale = [Math]::Min(1.0, $max / [Math]::Max($img.Width, $img.Height))
+$w = [int][Math]::Round($img.Width * $scale); $h = [int][Math]::Round($img.Height * $scale)
+$bmp = New-Object System.Drawing.Bitmap $w, $h
+$g = [System.Drawing.Graphics]::FromImage($bmp)
+$g.InterpolationMode = [System.Drawing.Drawing2D.InterpolationMode]::HighQualityBicubic
+$g.DrawImage($img, 0, 0, $w, $h); $g.Dispose()
+
+$ms = New-Object IO.MemoryStream
+$bmp.Save($ms, [System.Drawing.Imaging.ImageFormat]::Png)
+$type = "image/png"
+if ($ms.Length -gt 1400000) {
+    $ms = New-Object IO.MemoryStream
+    $codec = [System.Drawing.Imaging.ImageCodecInfo]::GetImageEncoders() | Where-Object { $_.MimeType -eq "image/jpeg" }
+    $params = New-Object System.Drawing.Imaging.EncoderParameters 1
+    $params.Param[0] = New-Object System.Drawing.Imaging.EncoderParameter ([System.Drawing.Imaging.Encoder]::Quality), 85L
+    $bmp.Save($ms, $codec, $params); $type = "image/jpeg"
+}
+Write-Output ("{0}|{1}|{2}|{3}" -f $type, $w, $h, [Convert]::ToBase64String($ms.ToArray()))