Servidor HTTP

Apps agénticas

Una app que orquesta agentes frente a una UI en vivo necesita cinco cosas que un servidor REST común no tiene: un canal bidireccional al navegador, un proceso hijo que podés mirar mientras corre, una forma de que un evento llegue a todos los clientes abiertos, una sola espera sobre todo eso, y un servidor que vence, cancela y se apaga sin dejar nada atrás. Desde el engine v0.6.7 las cinco están en el lenguaje, con las mismas reglas que todo lo demás: deny-by-default, memoria acotada, errores que se dicen.

No es sólo para agentes. Las mismas cinco primitivas son lo que necesitan un chat, un minijuego multijugador, un editor colaborativo, un dashboard en vivo, un bot de build o una terminal en el navegador: un socket por cliente, un bus por sala o tema (bus_subscribe("room." + id)), un proceso que mirás, un select por conexión y un servidor que limpia lo suyo. "Agéntica" es donde se encontró el hueco; la página aplica a cualquier programa con estado vivo compartido entre clientes.

-- Doc example: the event bus (`bus_*`) and the unified `select` — the plumbing of an
-- agentic app. N subscribers receive the SAME event (fan-out — unlike signal/wait_for,
-- which one receiver consumes), queues are bounded, topics accept globs, and ONE wait
-- covers any mix of handles. Pure: no capability (same trust level as share/signal).
-- Incoming sockets (`route … socket`) and live processes (`proc_*`) need a running
-- server / an `exec` grant, so the page prose covers those with the shapes that run.
intent: "doc example: event bus + select"

let wide be bus_subscribe("agent.*")
let exact be bus_subscribe(["agent.done", "ui.*"])
let other be bus_subscribe("other")

test "publish fans out to every matching subscriber and says how many got it"
    assert_eq(bus_publish("agent.done", {"step": 1}), 2)
    let ev be bus_recv(wide, 1)
    assert_eq(ev["type"], "event")
    assert_eq(ev["topic"], "agent.done")
    assert_eq(ev["data"]["step"], 1)
    assert_eq(bus_recv(exact, 1)["topic"], "agent.done")
    assert_eq(bus_recv(other, 0.1), nothing)           -- no match → nothing at the timeout

test "select waits on any handles at once and tags the winner"
    bus_publish("ui.click", "go")
    let ev be select({"wide": wide, "exact": exact}, 1)
    assert_eq(ev["name"], "exact")
    assert_eq(ev["source"], "bus")
    assert_eq(ev["topic"], "ui.click")
    assert_eq(ev["data"], "go")
    assert_eq(select([wide, other], 0.1), nothing)      -- nothing ready → nothing

task publish_glob()
    give bus_publish("agent.*", 1)                      -- globs belong to bus_subscribe

task publish_task()
    give bus_publish("agent.done", publish_glob)        -- a task is not data

test "a published topic is literal and the payload must be data (loud, not degraded)"
    assert_error(publish_glob)
    assert_error(publish_task)

test "queues are bounded: drop_oldest keeps the newest — the publisher never blocks"
    let small be bus_subscribe("q", {"max_queue": 2})
    bus_publish("q", 1)
    bus_publish("q", 2)
    bus_publish("q", 3)
    assert_eq(bus_recv(small, 1)["data"], 2)
    assert_eq(bus_recv(small, 1)["data"], 3)
    bus_unsubscribe(small)

test "bus_topics lists live subscriptions by pattern"
    assert(some(bus_topics(), (t) => t["topic"] == "agent.*"))

Rutas WebSocket — socket§

Una ruta con un bloque socket acepta un WebSocket entrante. Adentro, socket es el handle de esta conexión — el mismo tipo de handle que devuelve ws_connect, así que toda la familia ws_* funciona sin cambios:

require serve(8080)

serve on 8080
    route "GET /ws"                              -- el handshake es un GET (RFC 6455)
        socket
            ws_send(socket, {"hello": "agent"})
            while true
                let ev be ws_recv(socket, 30)    -- {type: "text"|"binary"|"close", data}
                when ev == nothing               -- 30 s sin nada
                    stop
                when ev["type"] == "close"
                    stop
                otherwise
                    ws_send(socket, {"echo": ev["data"]})

    route "GET /private" requires auth            -- la auth corre ANTES del upgrade: 401, sin upgrade
        socket
            ws_send(socket, "hello " + request.user.name)

• request, params, query, headers y user están ligados como en cualquier ruta. ws_stats(socket)["role"] es "server".
• El cierre es honesto. Termina el bloque o stop → Close 1000. Error no atrapado → Close 1011 + el mensaje (≤ 123 bytes) y una línea [socket] … handler failed en el log. El server cancelando el handler (timeout de la ruta, shutdown) → Close 1001 (going away) + el motivo. Un cliente que desaparece sin handshake de cierre llega como {type: "close", data: "connection reset without closing handshake"} en el próximo ws_recv/select.
• Un request HTTP común a una ruta socket → 426 Upgrade Required (body JSON, header Upgrade: websocket). Los clientes HTTP/2 reciben el mismo 426; los navegadores siempre abren WebSockets por HTTP/1.1.
• El keepalive es del server: responde pings y manda los suyos cada SYNSEMA_WS_SERVER_PING segundos (default 30) mientras el handler espera; sin pong en dos intervalos → un close con motivo keepalive timeout. Un mensaje mayor a SYNSEMA_WS_MAX_MESSAGE (16MB, techo 64MB) es un error atrapable. El backpressure es real en las dos direcciones (canales acotados; la ventana TCP frena al lado lento).
• Presupuesto: un socket ocupa un slot de max_streams (503 + Retry-After al agotar) y cuenta contra SYNSEMA_WS_MAX_CONNS. Sin capability nueva — la ruta ya está dentro de serve.
• Reglas: sólo GET, socket y stream en la misma ruta es error de parseo, todavía no se permite dentro de un grupo export routes (error claro). Fuera de una ruta socket es un nombre común.
• Un handle jamás cruza requests. Para empujar a N sockets abiertos desde un cron, un agente u otro request, cada handler de socket se suscribe al bus y reenvía — abajo. A propósito no hay una tabla global de sockets.

Procesos vivos — proc_*§

run es one-shot: captura todo y devuelve al final. Un agente que corre cargo test, npm run build o un worker largo necesita ver la salida a medida que sale, mandar stdin y matarlo — un proceso como handle con eventos. Mismo gate que run (require exec(cmd), scope = el comando tal como se escribe), args como lista, nunca un shell. Pipes por defecto (una herramienta que detecta "no es una tty" se comporta como en CI); "pty": true le da una terminal real — ver Pseudo-terminal abajo.

require exec("cargo")

let p be proc_spawn("cargo", ["test"], {"cwd": "./repo"})
while true
    let ev be proc_recv(p, 60)                   -- {type: "stdout"|"stderr"|"exit", data} o nothing
    when ev == nothing
        proc_kill(p)                              -- 60 s en silencio: TERM ("KILL" para insistir)
    otherwise when ev["type"] == "exit"
        print("exit " + text(ev["data"]["exit_code"]))
        stop
    otherwise
        print(ev["type"] + ": " + ev["data"])     -- un evento por línea, sin el salto final
proc_close(p)

exit llega una vez, después de drenar los dos pipes, como {exit_code, signal} (exit_code -1 si murió por señal; signal es nothing en una salida normal y siempre en Windows). opts: cwd, env (hereda + sobreescribe; un valor secret es error — reveal() explícito), line_mode (true; false = chunks crudos de texto ≤ 64 KiB — data siempre es texto, UTF-8 lossy, nunca partido dentro de un carácter), stderr ("separate" | "merge"), pty (+ cols, rows, term — abajo), process_group (true: grupo de procesos / Job Object propio para que el kill alcance al árbol; false desprende a propósito un daemon que debe sobrevivir a proc_close — entonces sólo muere el hijo directo), y la cola acotada max_queue (4096) / max_queue_bytes (64 MiB) con on_full = "block" (default: el lector deja de drenar, el hijo se frena en su write — backpressure real, sin pérdida) | "drop_oldest" | "error" (el próximo recv falla, el proceso se mata).

Ciclo de vida. Cuando termina el intérprete que lo lanzó — el request bajo serve, el programa, el agente — todo proceso vivo se mata. El árbol entero, no sólo el hijo (v0.6.9+): el hijo nace en su propio grupo de procesos en Unix y en un Job Object con kill-on-close en Windows, así proc_kill/proc_close sobre sh -c "npm run dev" se llevan también al node de abajo — y en Windows hasta un crash del intérprete cierra el job y el árbol con él. proc_stats(h)["tree"] te dice que está en efecto. Un handler nunca deja un fantasma; el trabajo que debe sobrevivir a un request va en cron_after o en un agente. SYNSEMA_PROC_MAX (64, techo 1024) acota los procesos vivos por intérprete. Un nieto que retiene el pipe tras el exit del hijo no te cuelga: 1 s de gracia y se entrega el exit.

Pseudo-terminal — pty: true§

Engine v0.6.8+. Muchos programas preguntan "¿estoy hablando con una terminal?" y, sobre un pipe, saltan la pregunta, asumen "no", se cuelgan o se niegan: prompts y/N que leen /dev/tty, contraseñas de ssh/sudo/gpg, menús con flechas, docker run -it, REPLs, barras de progreso y toda TUI (vim, htop, un CLI agéntico). "pty": true corre al hijo dentro de un pseudo-terminal real — openpty en Linux/macOS, ConPTY en Windows ≥ 10 1809. Misma API, mismos eventos, mismo gate exec(cmd): un pty no otorga ningún poder del SO que un pipe no dé; cambia cómo se comporta el hijo, no qué puede hacer. sandbox lo deniega como a cualquier exec.

require exec("npm")

let p be proc_spawn("npm", ["install"], {"pty": true, "cols": 120, "rows": 40})
let screen be ""
while true
    let ev be proc_recv(p, 60)
    when ev == nothing
        proc_kill(p)
    otherwise when ev["type"] == "exit"
        stop
    otherwise
        set screen to screen + ev["data"]              -- texto crudo en chunks, ANSI incluido
        when contains(strip_ansi(screen), "[y/N]")    -- leerlo como lo leería un humano
            proc_send(p, "y\r")                       -- teclas: Enter es \r en una tty
            set screen to ""
proc_close(p)

Qué cambia en modo pty — consecuencias de "es una terminal", no API nueva:

• Un solo stream. Una tty no separa stderr: todo llega como stdout.
• Texto crudo con secuencias de escape. line_mode pasa a false por defecto — data sigue siendo texto, no bytes: chunks UTF-8, nunca partidos dentro de un carácter, bytes inválidos → U+FFFD. Mandáselos a xterm.js como frames de texto tal cual, o strip_ansi(texto) para ver lo que ve un humano (colores, movimientos de cursor y títulos OSC fuera; los redibujos con \r conservan el último cuadro). El runtime nunca interpreta VT.
• El eco está activo. Lo que mandás con proc_send vuelve por la salida. Un secret revelado que tipeás vuelve en claro — siguen valiendo las reglas de siempre (secret en args/env/send → error).
• Teclas, no líneas. Enter es "\r", Ctrl-C es bytes([3]), Ctrl-D bytes([4]), una flecha es ESC + [A. No hay proc_close_stdin (el error dice qué tecla mandar).
• Tamaño. cols/rows (default 80×24), proc_resize(h, cols, rows) después. term fija TERM (default xterm-256color; env.TERM gana).
• El kill alcanza al árbol (como con pipes desde v0.6.9). En Unix el hijo es líder de sesión y se señala al grupo de procesos entero; en Windows se termina el Job Object y se cierra la pseudo-consola — ningún nieto sobrevive colgado de la tty.
• El handshake de Windows está resuelto. ConPTY emite ESC[6n al arrancar y no entrega nada hasta que alguien contesta; el runtime contesta ese primero y lo quita del stream (un xterm.js del otro lado no lo ve, así no contesta dos veces). Los ESC[6n posteriores son de la app y pasan intactos.
• exit_code es -1 si murió por señal; en un pty signal es el número cuando se conoce (15, 9, 1, 2), si no nothing.

Una terminal web es una ruta socket y un pty en un mismo select: bytes del navegador → proc_send, eventos del proceso → socket_send, un mensaje {resize} → proc_resize; xterm.js dibuja. Quién recibe ese socket es una decisión de auth de la app — el runtime no agrega ninguna capability porque no hay nada nuevo que gatear.

Probá primero el flag no interactivo (--yes, CI=1, DEBIAN_FRONTEND=noninteractive): más barato y determinista. El pty es para cuando no existe.

Bus de eventos — bus_*§

signal/wait_for es punto a punto (un receptor consume). Una UI en vivo necesita fan-out: N handlers — uno por cliente SSE o socket — reciben el mismo evento que publicó un agente, un cron u otro request, sin polling. Eso es el bus. Un bus por programa, visible desde todos lados: top-level, workers de parallel_map, ticks de cron, agentes spawneados y cada handler de cada worker del server. Sólo in-process (Redis con la misma API es el roadmap). Sin capability — mismo nivel de confianza que share/signal.

bus_publish("agent.progress", {"step": 3, "of": 10})   -- → cuántos suscriptores lo recibieron
let sub be bus_subscribe("agent.*")                     -- un topic o una lista; globs * y ?
let ev be bus_recv(sub, 25)                             -- {type: "event", topic, data, timestamp} o nothing
bus_unsubscribe(sub)
bus_topics()                                            -- [{topic, subscribers}] por patrón

• Los payloads son datos (texto/número/bool/lista/mapa/bytes); una task o un secret es error, nunca una degradación silenciosa. Los topics publicados son literales — un glob en bus_publish es error (los globs son de bus_subscribe).
• Acotado por suscriptor en cantidad y bytes: bus_subscribe("t", {"max_queue": 1024, "max_queue_bytes": 16777216, "on_full": "drop_oldest"}). "drop_oldest" es el default (un suscriptor lento nunca frena al publicador); "error" hace fallar el próximo recv y retira la suscripción.
• Una suscripción vive lo que vive su intérprete: al terminar el handler/agente se retira — nadie llena una cola que nadie lee.

La ruta SSE que todo dashboard quiere — alimentada por el bus, con el heartbeat a cargo del server:

route "GET /events"
    stream
        let sub be bus_subscribe("agent.*")
        while true
            let ev be bus_recv(sub, 25)
            when ev != nothing
                send ev["data"] as ev["topic"]

File-watch — watch§

Cambios en disco como handle con eventos (engine v0.6.9+), en el mismo hub que procesos, sockets y bus — así un solo select cubre "cambió un archivo" y "terminó el build". Gate: require file(path) — mirar un árbol es leerlo, el mismo scope file_read que list_dir.

require file("src")
require file("src/*")
require exec("cargo")

let files be watch("src", {"interval": 0.2, "ignore": ["*.tmp"]})
let build be nothing
while true
    let ev be select({"files": files, "build": build}, 60)
    when ev == nothing
        continue
    when ev["source"] == "watch"                  -- {type, path, is_dir}
        when build != nothing
            proc_close(build)                     -- mata el build anterior, árbol entero
        set build to proc_spawn("cargo", ["build"])
    otherwise when ev["type"] == "exit"
        print("build exit " + text(ev["data"]["exit_code"]))

Los eventos son {type: "create" | "modify" | "delete", path, is_dir}. path usa / y queda relativa si la raíz era relativa. Un rename es un delete más un create. Los directorios sólo emiten create/delete (su mtime cambia con cada hijo — ruido). No se emite nada por lo que ya existía al arrancar el watch. opts: recursive (true), interval en segundos (0.5, piso 0.02), ignore (nombres de entrada, glob * permitido; default [".git", "node_modules", "target"] — pasá [] para incluirlos), max_entries (100 000: por encima watch() falla, y un árbol que lo supera después hace que el próximo recv falle y retira el handle), max_queue (4096; el overflow descarta lo más viejo y lo cuenta en dropped).

Cómo funciona, honestamente. Es polling con snapshot — mtime + tamaño por entrada, comparados cada interval — no inotify, FSEvents ni ReadDirectoryChangesW. Eso compra semántica idéntica en Linux, macOS y Windows, sin límites de watches del kernel y sin dependencia nueva; cuesta un recorrido del directorio por tick (de ahí ignore y max_entries) y una latencia igual a interval. Un cambio hecho y deshecho dentro de un mismo intervalo no se ve: recibís el estado, no la historia. SYNSEMA_WATCH_MAX (64, techo 1024) acota los watches vivos por intérprete; como los procesos, cada watch muere con el intérprete que lo abrió.

La terminal — term§

La terminal propia del programa como handle con eventos (engine v0.6.11+), en el mismo hub que procesos, sockets, bus y watches — así un solo select cubre "el humano tocó una tecla" y "el subagente publicó un resultado". Gate: require stdin. Es lo que necesita un chat CLI, una paleta de comandos o un editor de línea con historial: read_line te da una línea cocinada por vez; term_open te da cada tecla en el momento en que se pulsa.

require stdin
require stdout

let commands be ["/help", "/history", "/approve", "/model", "/quit"]
let term be term_open()
when term == nothing                       -- pipe / CI / serve / test: no hay terminal
    let line be read_line("> ")            -- el mismo programa, entrada plana
otherwise
    let buf be ""
    let sub be bus_subscribe("agent.*")
    while true
        let matches be where(commands, (c) => starts_with(c, buf))
        term_write(term, "\r\x1b[2K> " + buf + "   " + join(matches, "  "))
        let ev be select({"keys": term, "agent": sub}, 60)
        when ev == nothing
            continue
        when ev["source"] == "bus"
            term_write(term, "\r\n[agent] " + json_encode(ev["data"]) + "\r\n")
        otherwise when ev["type"] == "eof"
            stop
        otherwise when ev["type"] == "paste"
            set buf to buf + ev["text"]
        otherwise when ev["key"] == "char"
            set buf to buf + ev["text"]
        otherwise when ev["key"] == "backspace"
            set buf to slice(buf, 0, len(buf) - 1)
        otherwise when ev["key"] == "tab" and len(matches) == 1
            set buf to matches[0]
        otherwise when ev["key"] == "enter" and ev["alt"]
            set buf to buf + "\n"                  -- Alt+Enter = nueva línea
        otherwise when ev["key"] == "enter"
            stop
    term_close(term)

Cada tecla es un evento, así que el menú de / filtra mientras se tipea; el loop sigue vivo mientras un subagente habla por el bus.

Eventos (todos etiquetados source: "term", handle, name):

• {type: "key", key, text, ctrl, alt, shift} — key es un nombre: "char" (y text es el carácter, con Shift ya aplicado: "A"), "enter", "tab", "backtab", "backspace", "delete", "insert", "escape", "up"/"down"/"left"/"right", "home"/"end", "pageup"/"pagedown", "f1"…"f12". Tab y Enter nunca llegan como "\t"/"\r". Con ctrl: true, text es la letra minúscula (Ctrl+O → {key: "char", text: "o", ctrl: true}). Sólo pulsaciones (sin eventos de release/repeat).
• {type: "paste", text} — un pegado (bracketed paste) como un solo evento, saltos de línea incluidos (terminales Unix; en Windows un pegado llega como ráfaga de eventos key — term_stats(h)["paste"] dice cuál aplica).
• {type: "resize", cols, rows}, {type: "focus", gained} (cuando la terminal los emite).
• {type: "eof"} — stdin se cerró; se entrega una vez y el handle desaparece (como read_line → nothing, no es un error).

opts: paste (true, bracketed paste), kitty (true: pide el kitty keyboard protocol cuando la terminal lo soporta — Windows Terminal, kitty, WezTerm, foot, Ghostty — que es lo que hace distinguible Shift+Enter; sin él Shift+Enter es un Enter común, así que hacé de Alt+Enter tu atajo multilínea y de Shift+Enter un bonus), ctrl_c ("exit": Ctrl+C restaura la terminal y termina el proceso con código 130, como haría SIGINT — el raw mode si no se lo tragaría; "key": llega como {key: "char", text: "c", ctrl: true} y el programa decide), max_queue (16384, descarta los más viejos).

Lo que se sostiene con una terminal abierta: print/log siguen funcionando (el runtime escribe \r\n por vos, sin escalera); ask de texto libre, approve y confirm funcionan — el handler de consola suspende el raw mode mientras el humano contesta y lo reanuda; una terminal por proceso — un agente spawneado no puede abrirla mientras la tiene el programa principal. Restaurar la terminal es tarea del runtime, nunca del script: lo que activaste vos (cursor oculto, colores) lo deshacés vos.

Una sola espera — select§

let ev be select({"sock": socket, "child": child, "feed": feed, "cancel": sub}, 60)

targets es una lista de handles o un mapa nombre → handle — cualquier mezcla de ws_connect, socket, proc_spawn, bus_subscribe, watch, term_open. Devuelve el primer evento listo, etiquetado con source ("ws" | "proc" | "bus" | "watch" | "term"), handle y name (forma mapa), más los campos propios del evento (type/data en sockets y procesos; topic/data/timestamp en el bus). nothing al vencer o cuando todos los targets desaparecieron. Equitativo (round-robin), duerme en el poller del kernel mientras no hay nada, falla rápido con un error atrapable cuando un target muere por error de protocolo/cola, y despierta al instante ante una cancelación. ws_select también acepta cualquier handle (conserva su etiqueta conn); proc_select es la misma espera restringida a procesos.

Todo junto — una conexión, un hijo, una suscripción, un loop:

require serve(8080)
require exec("sh")

serve on 8080
    route "GET /console"
        socket
            let sub be bus_subscribe("agent.*")
            let child be proc_spawn("sh", ["-c", "for i in 1 2 3; do echo step $i; sleep 1; done"])
            while true
                let ev be select({"ui": socket, "child": child, "bus": sub}, 60)
                when ev == nothing
                    ws_send(socket, "idle")
                otherwise when ev["name"] == "ui"
                    when ev["type"] == "close"
                        stop
                    otherwise
                        ws_send(socket, "you said " + ev["data"])
                otherwise when ev["name"] == "child"
                    when ev["type"] == "exit"
                        ws_send(socket, "exit " + text(ev["data"]["exit_code"]))
                    otherwise
                        ws_send(socket, ev["type"] + ": " + ev["data"])
                otherwise
                    ws_send(socket, "[" + ev["topic"] + "] " + json_encode(ev["data"]))

La versión completa, con un feed SSE /events y un POST /announce que publica, es examples/agent_console.syn en el repo del engine.

Timeouts y cancelación§

Por default un handler no tiene límite de tiempo. Declaralo en el bloque serve (default de todas las rutas) y/o por ruta:

serve on 8080
    timeout 30                    -- segundos, default de todas las rutas
    route "POST /think"
        timeout 300               -- override de ruta: al principio del cuerpo, una sola vez
        give reason "…" given request.json
    route "GET /events"
        timeout none              -- esta ruta se exime del default del bloque
        stream
            …

• Rutas sized: al vencer, el cliente recibe 504 {"error": "gateway timeout: the handler exceeded 30s", "status": 504} con Connection: close, y el handler queda cancelado — se corta en su próximo statement o espera (log: handler cancelled: request timed out after 30s). El tiempo en cola esperando un worker cuenta.
• stream / socket: el timeout es la vida máxima de la conexión — el SSE termina con event: error {"error": "cancelled: request timed out after 30s"}; un socket recibe Close 1001 con ese motivo.
• La cancelación es cooperativa y no se cura. El intérprete la chequea antes de cada statement y dentro de cada espera (sleep, ws_recv, select, proc_*, bus_recv, wait_for, run), levantando cancelled: <motivo>. Un try/recover puede observarla, pero el próximo statement vuelve a fallar — limpiá y salí. Los hijos de run/proc_spawn se matan.
• timeout es una cláusula. En cualquier otro lugar (dentro de un when, una task, el top-level) es un error de runtime, no un no-op silencioso. Todavía no se soporta dentro de un grupo export routes — ponelo en el bloque serve.
• La desconexión del cliente en una ruta sized no se detecta (hyper no la expone sin body pendiente); streams y sockets sí la detectan.

Shutdown ordenado§

Ante SIGINT (Ctrl-C) — y SIGTERM en Unix, lo que mandan docker stop y systemd:

1. El listener se cierra: las conexiones nuevas se rechazan; un request sobre una conexión keep-alive abierta recibe 503 {"error": "server shutting down"} + Retry-After: 2. 2. Log: [serve] shutting down: draining N in-flight request(s), grace 10s (SYNSEMA_SHUTDOWN_GRACE). El cron deja de programar, los agentes vivos se cancelan (agent_stop, motivo server shutting down), streams y sockets se cancelan de inmediato (SSE event: error cancelled: server shutting down; sockets Close 1001). 3. Los requests sized en vuelo tienen hasta SYNSEMA_SHUTDOWN_GRACE segundos (default 10; 0 = inmediato); lo que queda se cancela; [serve] stopped; código de salida 0 (fue pedido). Un segundo Ctrl-C durante el drain sale ya con 130. 4. Con varios bloques serve on el proceso sale cuando drenó el último.

synsema run no cambia (no tiene listener). Bajo systemd poné TimeoutStopSec por encima de la gracia.

Desde el programa (engine v0.6.18+): shutdown(reason?) pide exactamente este drain — desde una ruta, un bloque socket, un job de cron o un agente. El log dice [serve] shutdown requested by the program: <motivo>, después corren los pasos de arriba y el proceso sale con 0. Idempotente (una segunda llamada no hace nada); error bajo synsema run (un programa run termina con su top level — stop sale de un loop o de una task) y antes de que algo escuche; sin capability (apagarse no es un recurso del host); un secret como motivo se rechaza (el motivo se loguea). Es como una app de escritorio se apaga cuando se cierra su última ventana — Tu app en el escritorio.

Agentes bajo serve§

Un agente spawneado desde un handler o un tick de cron recibe el mismo cableado que un tick de cron — state_*, la base compartida, la cola de approvals, cron, el bus, la memoria declarada — no una isla con builtins frescos. Corre bajo el techo del host de synsema serve --sandbox o --cap-set "<lista>" (un require adentro nunca excede lo que fijó el operador, exactamente como bajo run; --sandbox acá es stdout,time + serve), y un shutdown ordenado lo detiene.

agents()                  -- [{id, name, state, error, started_at, finished_at}]
agent_stop(id, motivo?)   -- true si estaba vivo; el agente termina en estado "stopped"

id es la instancia (Researcher_0), name el agente declarado; estados idle · starting · working · waiting · done · error · stopped. agent_stop es cancelación cooperativa: el agente levanta cancelled: <motivo> antes de su próximo statement y cualquier espera despierta al instante — un agente en while true ya no es inmortal. Los dos funcionan bajo run y serve, sin capability (introspección del propio proceso). Ojo: give agents() pagina como todo give <lista> — leé items, o give {"agents": agents()}.

Knobs del server (entorno del proceso, no .env)§

synsema init los lista, comentados, en .env.example — con la advertencia de que los lee el entorno del proceso (export, Environment= de systemd, -e de Docker):

Correr Synsema que generaste — run_program (v0.6.14+)§

Una app agéntica que escribe Synsema (una tool que emite el LLM, el plugin de un usuario, un loop que se auto-repara) lo corre con run_program(source, opts) — un proceso hijo del mismo binario bajo un techo ∩ el del padre, con su propio env/cwd/timeout y su audit devuelto como un valor (require sandbox_run). Sin exec, sin synsema en el PATH, sin parsear stderr; el hijo nunca puede exceder al padre. Es la forma segura de "correr el código que generó el modelo" — modelo completo en Sandbox, firma en Builtins.

Lo que a propósito no está§

• Un emulador de terminal o un framework de TUI. pty: true le da al hijo una terminal real; dibujarla (parsear VT, un modelo de pantalla) es tarea del consumidor — xterm.js en un navegador, strip_ansi para un agente. term_open te da a vos teclas y tamaño, nada más: un editor de línea, una paleta de / o un menú son unas decenas de líneas de Synsema sobre select (el ejemplo de arriba), no una biblioteca de widgets en el runtime.
• Un notificador nativo del filesystem. watch hace polling sobre un snapshot a propósito: una sola semántica en todos los SO, sin límites del kernel, sin crate *-sys. Si algún día importa latencia sub-segundo sobre un árbol enorme, sería un opts.backend, no una API nueva.
• Un bus entre procesos. Redis pub/sub va a reusar bus_* con un opts.backend.
• Una tabla global de sockets. Empujar a "todos los sockets" desde cualquier lado sería una puerta de escape del aislamiento por request; el camino es el bus.

Mirá Servidor HTTP, Cliente WebSocket, Multi-agente y Deploy.