lampson 0.1.0

package/skills/debugging/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: debugging
+description: How to write and run throwaway scripts (sh, js/mjs/ts, py…) in the scratch dir to test, reproduce or probe something in the project — before touching real code. Load when a task needs an experiment, a repro, or a quick check of an API/library/function.
+---
+
+# Debugging with scratch scripts
+
+You have a scratch directory inside the workspace: **`.lampson/scratch/`** (create it with `write`;
+it is ignored by lampson's file tree and must never be committed — add `.lampson/` to the project's
+`.gitignore` if it is a git repo and it is not there yet).
+
+Use it to *prove* things instead of guessing:
+
+- **Reproduce a bug** in isolation: `write .lampson/scratch/repro.mjs` that imports the real module
+  (`import { f } from '../../src/lib/x.js'`) and calls it with the failing input; run with
+  `bash: node .lampson/scratch/repro.mjs`. Paths in the script are relative to the workspace root
+  because `bash` runs there.
+- **Probe an API or a running server**: `curl -s -i http://127.0.0.1:3000/api/x` (start the server with
+  the `process` tool first, then read its log with `process(logs)` after the request).
+- **Check a library's behavior** before relying on it: a 5-line script beats reading docs from memory.
+- **Try a data transformation** on real data: dump a sample to `.lampson/scratch/sample.json`, iterate.
+- **Run one test in isolation** (`npx vitest run path -t "name"`, `pytest path::test -x`, etc.).
+
+Pick the runtime the project already uses (look at `package.json`, `pyproject.toml`, `go.mod`,
+`Cargo.toml`…): `node x.mjs` / `npx tsx x.ts` / `python x.py` / `bash x.sh` / `go run x.go` /
+`synsema run x.syn`. TypeScript: prefer `npx tsx` (no build step); if it is not installed, write `.mjs`.
+
+Rules:
+1. Scripts print **evidence** (values, status codes, timings) — not just "ok". Compare expected vs actual.
+2. Keep them small and single-purpose; name them by intent (`repro-login-401.mjs`, `probe-db.py`).
+3. Never import secrets into a script; read config the same way the project does.
+4. When done, say what the script proved. Delete scripts that are pure noise; keep repros that document a bug.
+5. Anything long-running (a server you start to probe) goes through the `process` tool, never in the foreground.

package/skills/lampson/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: lampson
+description: How this harness works — tools, workspace mount, permissions, agents, sessions. Load when asked about Lampson itself or when a tool behaves unexpectedly.
+---
+
+# Lampson (the harness you are running in)
+
+## Where you are
+- Your tools only reach `workspace/` — the user's project, mounted as a junction/symlink by
+  `lampson.ps1 <path>` / `lampson.sh <path>`. All paths you pass are relative to that root.
+- Anything outside (absolute paths, `..`, sibling dirs) fails with `Capability not granted`.
+  That is by design (Synsema deny-by-default + `call_tool` least-privilege). Do not try to work
+  around it; tell the user if you genuinely need something outside the workspace.
+- `bash` runs with cwd = workspace root and a hard timeout (default 120 s): when it expires the command AND
+  its child processes are killed. Never run servers/watchers/REPLs in `bash`; use the `process` tool:
+  `process(start, name="web", command="npm run dev")`, then `process(logs, name="web")`, and
+  `process(stop, name="web")` when done. New log lines of every managed process are appended to each
+  `bash` result automatically — you SEE the server's console (errors, requests, crashes) without asking.
+  The user sees the same logs live in the web UI ("Procesos" panel). Its child process is NOT confined by Synsema; dangerous
+  commands are screened by `permission.syn` (hardline = always denied; dangerous = needs the user's
+  approval in `ask` mode, denied in `strict`, allowed in `yolo`).
+
+## Tool behavior worth knowing
+- `edit` needs an exact, unique `old_string`; if it fails, `read` the region again and retry with
+  more context. `replace_all=true` for intentional multi-replace.
+- `read` returns up to 2000 lines; use `offset`/`limit` for big files. Outputs > 30k chars are truncated.
+- `find` is a simple glob (`*.ts`, `test_*`, `*config*`), `grep` is regex by default (`regex=false` for literals).
+- `lsp(op=symbols, path)` is the cheapest way to understand a big file: every function/class/variable
+  with its line range — then `read` only the range you need. `definition` / `references` / `hover` /
+  `implementation` take 1-based `line` + `character` ON the identifier. If no server is configured for
+  that extension, propose `lsp(op=add, server=<preset>)` (typescript, python, rust, go, css, html) — it
+  always asks the user and needs nothing installed (`npx` fetches it); `op=list` shows what is configured.
+  Do not install language servers with bash yourself.
+- Calling the same tool with identical args 3 times in a row is blocked (doom loop) — change approach.
+- After 8 tool errors in a turn the harness asks you to stop and report.
+- `delegate(tasks=[{agent, brief, context}…])` runs sub-agents (`explore` / `plan` / `review` /
+  `worker`) IN PARALLEL, each with a fresh context and a restricted toolset, and returns their reports
+  consolidated. `background=true` returns ids at once and each report arrives later as a message in
+  your context (do not poll); `action=list|steer|stop|result` manages them. Give a self-contained
+  brief — a child does not see this conversation, cannot ask the user and cannot delegate. Reports are
+  self-reports: verify before claiming success. Live logs: `.lampson/agents/<id>.log`.
+
+## When you need the USER to run something
+The user can run any command themselves from the chat by prefixing it with `!` — e.g. `!npm run dev`,
+`!cat .env`, `!git push`. Their command runs without the permission policy and its output is added to
+your context automatically. In the terminal REPL, `!` runs inside a real pseudo-terminal: prompts
+(`y/N`, passwords, `npm init`) work — the user answers them inline. In the web UI there is also a
+**full interactive terminal** (header button `>_ terminal`, a shell with cwd = workspace, opens in the
+center pane like a file). Offer these when: a command needs an interactive terminal (logins, TUIs,
+watching a dev server), when something is denied for you (secrets, dangerous commands), or when they
+should verify a result with their own eyes. Say exactly what to type, e.g. "run `!npm run dev` (or open
+the terminal button and run `npm run dev`), then tell me the URL".
+
+## Provider, model, keys, images
+- Provider/model/API keys live in `lampson/.lampson/config.json` (local); the user changes them with
+  `/setup`, `/provider`, or the `provider · model` pill in the web header. Never ask the user to paste a
+  key into the chat; point them there. Keys are sealed secrets: you cannot read or print them.
+- The user can paste images in the web UI, or in the terminal with `/paste` (clipboard) and
+  `/image <path>`. If they say "look at this screenshot" in the terminal, tell them to copy it and type
+  `/paste`, then send their message. If your model has no vision, the image arrives as a text
+  note `[Image N WxHpx attached, but this model does not accept image input …]` — say so and suggest
+  a vision model instead of guessing what the image shows.
+- Sessions can be deleted (`/delete <id>`, or ✕ in the web sidebar).
+
+## Network exposure
+- The web server listens on all interfaces but every `/api/*` route (and the terminal socket) only
+  accepts loopback clients; others get 401 unless they present `LAMPSON_WEB_TOKEN`. If the user asks
+  to use Lampson from another machine, point them to that token — never suggest removing the check.
+
+## Agents / modes
+- `build` (default): all tools. `plan`: read-only, produce a numbered plan. `review`: read + run
+  tests, never edit. `explore`: read-only search. The user switches with `/agent <name>`.
+
+## Project memory (persistent notes)
+- `memory(write, name, content)` saves a Markdown note about THIS project in Lampson's `memory/<project>/`
+  folder (outside the repo). The system prompt lists your notes; `memory(read, name)` loads one.
+- Save what you would otherwise rediscover: how to run/test, env quirks, decisions, where things live,
+  root causes of bugs. Update notes instead of contradicting them. The user can read and edit them.
+
+## Sessions and memory
+- The whole history — including every tool result, error and DENIED message — is persisted in
+  `.lampson/sessions/<id>.json` and resent to you each turn, so you know exactly what happened.
+- When the context grows past the compaction threshold, older turns are replaced by a summary that
+  keeps goals, files touched, current state, pending work and errors seen.
+
+## Updating Lampson
+- Lampson is installed as a git clone (`~/lampson`), so updating is a fast-forward pull. Both UIs
+  check `origin/main` on start and show a notice when a newer version exists (terminal banner, web
+  header button). The user updates with **`lampson --update`** in any terminal, `/update` in the REPL,
+  or the header button in the web UI — then restarts Lampson. Re-running the installer does the same.
+- If asked "how do I update Lampson?", answer exactly that. If the pull fails because of local edits
+  in the lampson folder, suggest `git -C ~/lampson stash` first. (When the distribution changes —
+  desktop app, single binary — this section is the place that gets rewritten.)
+
+## Extending the harness (if the user asks you to)
+- One tool = one file `lib/tools/<name>.syn` exporting `task tool(...)` (its `require` lines at the
+  top of the body) and `let SPEC` (JSON Schema). Register it in `lib/tools.syn` (`use`, `registry()`,
+  `CATALOG`) and in the profiles of `lib/agents.syn`. `synsema check chat.syn` validates everything.
+- Providers are raw HTTP (`lib/provider.syn`): OpenAI wire (`/chat/completions`) and Anthropic wire
+  (`/messages`). Config via `.env` (`LAMPSON_PROVIDER`, `LAMPSON_API_KEY`, `LAMPSON_MODEL`, `LAMPSON_BASE_URL`).
+- Skills: `skills/<name>/SKILL.md` (harness), `workspace/skills/<name>/SKILL.md` (project),
+  `workspace/.lampson/skills/<name>/SKILL.md` (local), plus external ones installed with `npx skills add`
+  (`workspace/.agents/skills`, `workspace/.claude/skills`, and the global `~/.agents/skills` / `~/.claude/skills`
+  mounted as `.lampson/skills-global` / `.lampson/skills-claude`). Frontmatter `name:` + `description:`.
+  `skill(action=install, source=owner/repo, name=x, scope=global|project)` installs one (always asks the user).
+- **Lamps** = tool plugins you can create for this project without touching the harness:
+  `lamp(action=create, name, manifest, files={"lamp.syn": "…"})` writes `workspace/.lampson/lamps/<name>/`,
+  validates the manifest and runs `synsema check` on a syn entry (it does not run or enable anything —
+  like dsh's cordis_define). Then `lamp(action=enable, name)` — the user must approve (a lamp is off until
+  a human turns it on). Build one when a task needs a reusable project-specific tool. Manifest:
+  `{"name", "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}]}`. Lamp names: letters,
+  digits, `-` (no `_`). Each call runs the lamp as ONE child process: `synsema run --cap-set <ceiling> entry`
+  for `syn`, the command for `exec`. Inside, read `LAMP_TOOL` and `LAMP_ARGS` (JSON) from env
+  (`require env("LAMP_*")` in a .syn) and print the result to stdout. A syn lamp cannot use more than its
+  manifest's `caps`; ask only for what the tool needs. Once on, its tools are `lamp_<name>_<tool>`.

package/skills/synsema/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: synsema
+description: Writing, checking, running and testing Synsema (.syn) code — syntax reflexes, capabilities, live processes / pseudo-terminals, and the runtime traps that cost hours. Load before touching any .syn file.
+---
+
+# Synsema quick reference (v0.6.10)
+
+> Curated 10 KB summary for the agent (the full reference is ~450 KB and lives in the user's editor
+> skill). Kept in sync by hand with each `synsema update`; if `synsema --version` is newer than the
+> version above, trust the runtime's error messages over this file.
+
+## Dev loop
+- `synsema check file.syn` (parse + validates every `use` import) · `synsema run file.syn` ·
+  `synsema test file.syn` (runs `test "..."` blocks) · `synsema serve file.syn` (HTTP server) ·
+  `synsema update` (self-update; then refresh the AI skill with the command it prints).
+- Errors carry `file:line` and a suggestion. Read them; they are usually right.
+
+## Syntax reflexes (Python → Synsema)
+- `let x be 5` / `set x to 6` (no `=`) · `-- comment` · `when / otherwise when / otherwise` (no colons)
+- `each x in xs` (lists only; maps → `each k in keys(m)`) · `while c` · `task f(x)` … `give v`
+- `nothing / true / false` · backtick strings interpolate: `` `n={n}` `` (double-quoted do NOT)
+- `try` … `recover err` (recover SWALLOWS; `raise(err)` to re-throw) · `raise("msg")`
+- `contains(xs, x)` (on maps checks KEYS) · `append(xs, x)` returns a NEW list → `set xs to append(xs, x)`
+- `apply(f, xs)`, `where(xs, p)`, `sort_by(xs, f)`, `slice(xs, a, b)`, `split/join/trim/lower/upper`
+- `json_encode / json_decode` · `length` · `text(x)` · `number(s)` (ALWAYS float → `floor()` for ints)
+- Modules: `use "./m.syn" as m` (local only, never `../`), `export task/let`. A module cannot have
+  top-level `require` or `serve` — the ENTRY file grants capabilities.
+
+## Capabilities (deny-by-default)
+- Declare at the top: `require net("host")`, `require file("dir")` + `require file("dir/*")`,
+  `require exec`, `require env("X_*")`, `require secret("KEY")`, `require serve(8080)`, `require time`.
+- A task's own top-of-body `require` lines are what `call_tool(task, args_map)` intersects
+  (least-privilege). Plain calls run with the program's ambient capabilities.
+- `sandbox` blocks strip everything. `secret("K")` is opaque: pass it as a header, never print it.
+
+## Processes
+- `run(cmd, [args], timeout?, {cwd, env, stdin})` → `{exit_code, stdout, stderr}`; captures everything,
+  returns at the end; non-zero exit is DATA (only timeout / can't-launch raise).
+- Live process (v0.6.7+): `let p be proc_spawn(cmd, [args], {cwd})` then `proc_recv(p, secs)` →
+  `{type: "stdout"|"stderr"|"exit", data}` or `nothing`; `proc_send(p, text)`, `proc_kill(p)`, `proc_close(p)`.
+  `select({"a": handle, "b": handle}, secs)` waits on processes, sockets and bus at once (`ev["name"]`).
+- **Pseudo-terminal (v0.6.8+)**: `proc_spawn(cmd, args, {"pty": true, "cols": 120, "rows": 40})` for
+  y/N prompts, passwords, REPLs, TUIs. One `stdout` stream of TEXT chunks with ANSI (never split inside a UTF-8 char);
+  `strip_ansi(text)` shows what a human sees; keys go with `proc_send` (Enter = `"\r"`, Ctrl-C = `bytes([3])`);
+  `proc_resize(p, cols, rows)`. Web terminal = `socket` route + pty in one `select` (xterm.js renders).
+- **Tree kill (v0.6.9+)**: `proc_kill`/`proc_close` reach the WHOLE process tree (Job Object on Windows,
+  process group on unix) — `sh -c "npm run dev"` takes its `node` with it; `proc_stats(p)["tree"]` confirms.
+  `{"process_group": false}` deliberately detaches a daemon. A grandchild holding the pipe cannot hang you (1 s grace).
+- Every live process dies with its interpreter — **under `serve` that means the END OF THE REQUEST**: a
+  `proc_spawn` in a handler is gone when the handler returns. A process that must outlive requests lives
+  inside an `agent` spawned from the handler (own lifecycle; blackboard `share/observe` + `bus_*` are shared
+  with handlers). That is how lampson's `process` tool works (`lib/tools/proc.syn`).
+- **File watch (v0.6.9+)**: `let w be watch("src", {"interval": 0.2, "ignore": ["*.tmp"]})` → events
+  `{type: "create"|"modify"|"delete", path, is_dir}` via `watch_recv(w, secs)` or `select`; polling with a
+  snapshot (latency = interval), `watch_close(w)`. Gate: `file("src")` + `file("src/*")`.
+
+## Traps verified on this machine (do not fight them)
+- Agents: an `agent` body sees ONLY its `spawn X with a = …` parameters, the builtins and the TOP-LEVEL
+  tasks of the entry program — not the module's `let` constants, tasks nor `c.*` imports ("Undefined
+  variable"); a task passed through `spawn` arrives as text. Each agent needs its OWN `require` lines.
+  `stop` only inside loops. `synsema run`/`test` join agents at the end: a `while true` supervisor must be
+  told to stop (bus/signal). (≤ 0.6.9 `test` had no swarm; v0.6.10+ runs agents for real in `test`.)
+- `;` between statements is a lexer error (one statement per line).
+- `file("./*")` behaves like `"*"` (whole disk). Use a named dir scope: `file("workspace/*")`.
+- `http_post(url, MAP)` sends `text(map)`, not JSON → `http_post(url, json_encode(body), {"Content-Type": "application/json"})`.
+- Responses have `status, ok, body, headers` — no `json` key → `json_decode(body of r)`; on network error: `status 0` + `error`.
+- `localhost` resolves to IPv6; use `127.0.0.1`.
+- `run("bash", ...)` hangs on Windows (WSL bash) → `C:\Program Files\Git\bin\bash.exe` or `cmd /c`.
+- A task named `run` shadows the builtin `run` (infinite recursion).
+- Reserved words that break variable/param names: `reason task ask stop decide analyze generate show approve confirm`.
+- `and`/`or` do NOT short-circuit → nest `when` before indexing.
+- No `merge`: add a key with `set m["k"] to v`. No `append_file`: read + write (atomic; parents created).
+- Runtime error messages are Capitalized (`Not a directory: …`) and `contains` is case-sensitive → compare `lower(text(err))`.
+- Under `serve`: resolve `secret()` inside the handler; define tasks before `serve on`; `send` only inside `stream`.
+- `.env` values override shell-exported ones if set there.