skillscript-runtime 0.18.9 → 0.19.0

package/docs/adopter-playbook.md

@@ -370,6 +370,104 @@ Per-skill capability declaration: skills declare what shell binaries they need i
 
 The operator policy validates `declared ∩ allowlist` — each skill's shell footprint becomes self-documenting and auditable. Slated for a future ring once the chokepoint + observability surfaces ship.
 
+## Trigger model (v0.19.0 — BREAKING)
+
+**v0.19.0 collapses the trigger surface to two primitives.** Per the Scott + Perry decision (memory `ceaf4579`):
+
+| Primitive | Purpose |
+|---|---|
+| `cron` | Time-based fires (unchanged) |
+| `event` | Generic external-signal fires via HTTP POST to `/event` |
+
+The previous sources (`session`, `agent-event`, `file-watch`, `sensor`) are **removed**. They were either parse-only stubs that never fired or substrate-coupled concepts that belong outside the runtime. Anything external becomes an adapter that POSTs to `/event` — including what would have been a session/agent-event/file-watch/sensor trigger. The `DeliveryMeta.origin.trigger_kind` receiver enum also drops `"session"` in lockstep (pre-v1.0 cleanup; the value was never functionally emitted).
+
+### The `event` primitive
+
+Skills declare an event trigger in their frontmatter:
+
+```
+# Skill: prox-handler
+# Status: Approved
+# Triggers: event: prox
+# Vars: ROOM, USER
+
+t:
+    emit(text="${USER} entered ${ROOM}")
+default: t
+```
+
+External services drive the skill by POSTing:
+
+```
+POST /event HTTP/1.1
+Host: localhost:7878
+Content-Type: application/json
+Authorization: Bearer <token>   # if SKILLSCRIPT_EVENT_INGRESS_AUTH_TOKEN set
+
+{
+  "event_name": "prox",
+  "params": { "ROOM": "kitchen", "USER": "scott" }
+}
+```
+
+Response on accept:
+
+```json
+{ "run_id": "f4a8b21c-...", "durability": "in-process" }
+```
+
+The `run_id` is the runtime's `trace_id` — adopters paste it into the dashboard `/fires` view or query via the `fires({trace_id})` MCP tool to look up completion status.
+
+### Wire contract
+
+| HTTP status | Meaning |
+|---|---|
+| **200** | Accepted into THIS process's in-memory queue. `{run_id, durability: "in-process"}`. Skill fires async; the 200 does NOT mean skill-completed |
+| **400** | Body not JSON; or `event_name` missing/empty; or params don't match declared (missing required or unknown extras) |
+| **401** | Auth token configured + missing/wrong `Authorization: Bearer <token>` |
+| **404** | `/event` route not enabled OR `event_name` not registered |
+| **405** | Wrong method (POST-only) |
+
+**Param validation is strict v1**: every declared param must be present; no unknown params accepted. No defaults; no type coercion. JSON already carries types, and a type mismatch fails inside the consuming op with a real error. Defaults + types may land in v2 if real adopter need surfaces.
+
+### `event_name` semantics
+
+- **Public contract** addressed by POSTers. Skill behind the event can swap without breaking callers — the `skill_name` is private impl.
+- **Case-insensitive** at register + lookup (normalized to lowercase internally).
+- **1:1**: one `event_name` → exactly one skill in the deployment. Fan-out is NOT supported — a skill can call other skills via `$ execute_skill` if needed.
+- **Cross-skill rebind allowed but audited**: registering an `event_name` that's already bound to a different skill replaces the binding (last-write-wins) AND logs a visible line (`event_name 'X' rebound: skill A → skill B`). Prevents silent cross-skill hijack without blocking the declarative re-save path. Same skill re-registering its own event is a silent upsert.
+
+### Enabling the `/event` HTTP ingress
+
+Off by default. Two operator knobs:
+
+```bash
+# Required to open the /event route
+SKILLSCRIPT_EVENT_INGRESS_ENABLED=true
+
+# Optional bearer-token auth (when set, required on every POST /event)
+SKILLSCRIPT_EVENT_INGRESS_AUTH_TOKEN=<token>
+```
+
+When `eventIngressEnabled=true`, the route mounts on the same HTTP server as the dashboard/RPC (no second port). Default bind is `127.0.0.1` (localhost-only) — adopters wanting `0.0.0.0` external reach pass `--host 0.0.0.0` explicitly. Per Perry's framing: "enforce the DMZ assumption by the bind, not by hope."
+
+### Durability honesty
+
+**`200 = ACCEPTED, not durable**.** The skill is queued in this process's memory; if the process crashes or restarts before the queue drains, the fire is lost. The `durability: "in-process"` field on every successful response self-describes this — adopters reading the response know the contract without consulting docs. Cron triggers have the same property today (no catch-up replay if the process was down).
+
+Durable / at-least-once delivery is a v2 if real adopter need surfaces. Don't oversell the 200 contract; build durable queueing on top yourself if you need it now.
+
+### Migration from removed sources
+
+If you have pre-v0.19.0 skills with `# Triggers: session: start` / `agent-event: X` / `file-watch: /path` / `sensor: X` declarations:
+
+- **session start/end** → boot/shutdown lifecycle moved to the substrate (NanoClaw / your harness). If you need a runtime skill to fire at session-start, your harness POSTs to `/event` after boot.
+- **agent-event** → external bridge (your agent fires `POST /event` when relevant).
+- **file-watch** → external watcher script (inotify / chokidar / fswatch) POSTs to `/event`. The "how to call /event" pattern lives in the language reference call-example; the file-watching itself is standard OS plumbing — you own that script.
+- **sensor** → same pattern as file-watch; sensor adapter POSTs to `/event`.
+
+Skills declaring removed sources fail to parse on v0.19.0 (tier-1 parse error). Run `skillfile lint` against your corpus pre-upgrade to find them.
+
 ## Wiring the AgentConnector
 
 `AgentConnector` is the substrate-neutral delivery surface for `# Output: agent: X` / `# Output: template: X` lifecycle hooks and `notify()` / `exchange()` ops. The runtime calls into the contract; your impl decides where the payload lands (webhook, tmux session, file drop, IPC pipe, Slack thread, your own agent harness, etc.).

package/docs/configuration.md

@@ -57,6 +57,8 @@ The CLI auto-loads `$SKILLSCRIPT_HOME/.env` at startup and populates `process.en
 | `SKILLSCRIPT_POLL_INTERVAL_SECONDS=30` | Scheduler tick / poll interval (seconds) | env > config > default `30` |
 | `SKILLSCRIPT_ABSOLUTE_TIMEOUT_MS=300000` | Runtime fallback timeout (ms) when no per-op / skill / connector default applies | env > config > default `300000` (5 min) |
 | `SKILLSCRIPT_MAX_RECURSION_DEPTH=10` | Composition recursion depth ceiling for `$ execute_skill` chains | env > config > default `10` |
+| `SKILLSCRIPT_EVENT_INGRESS_ENABLED=true` | Mount `POST /event` for v0.19.0 event-triggered skills. Default `false` — route returns 404 when not enabled. Shares `SKILLSCRIPT_PORT` with dashboard/RPC (one HTTP server). | env > default `false` |
+| `SKILLSCRIPT_EVENT_INGRESS_AUTH_TOKEN=<token>` | Bearer-token auth for `POST /event`. When set, every event POST requires `Authorization: Bearer <token>`; 401 otherwise. Default unset = open-internally (still gated by bind address). | env > default unset |
 | `OLLAMA_BASE_URL=http://...` | Ollama endpoint for LocalModel (default `http://localhost:11434`) | env > built-in default |
 
 `SKILLSCRIPT_HOME` is the chicken-and-egg case — the path to `.env` requires it, so `.env` can't set it. Use shell, Docker `-e`, or systemd `Environment=` instead.

package/examples/skillscripts/hello-world.skill.provenance.json

@@ -2,7 +2,7 @@
   "provenance_version": "1.0",
   "language_version": "1.0",
   "compiler_version": "0.1.0-dev",
-  "compiled_at": "2026-06-07T11:45:30.911Z",
+  "compiled_at": "2026-06-07T21:50:04.797Z",
   "source_skill": {
     "name": "hello-world"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillscript-runtime",
-  "version": "0.18.9",
+  "version": "0.19.0",
   "description": "Runtime, compiler, lint, CLI, and dashboard for Skillscript — a small declarative language for authoring agent workflows.",
   "license": "MIT",
   "author": "Scott Shwarts <scotts@pobox.com>",

package/scaffold/.env.example

@@ -64,10 +64,31 @@
 # reach the listener.
 # SKILLSCRIPT_HOST=0.0.0.0
 
-# Dashboard / serve HTTP port. Default 7878.
+# Dashboard / serve HTTP port. Default 7878. Used for the SPA, JSON-RPC
+# at /rpc, AND the v0.19.0 event-trigger ingress at /event (they share
+# one HTTP server — no separate event port).
 # SKILLSCRIPT_PORT=8080
 
 
+# ─── Event-trigger HTTP ingress (v0.19.0) ──────────────────────────────
+
+# Enable POST /event for external HTTP-triggered skills. Default false —
+# the route returns 404 when not enabled. Once enabled, external services
+# POST {event_name, params} and the runtime fires the registered skill
+# asynchronously, returning 200 + {run_id, durability: "in-process"}.
+# The route mounts on SKILLSCRIPT_PORT (above); no separate port.
+# Localhost-only by default — set SKILLSCRIPT_HOST=0.0.0.0 to expose
+# beyond loopback. "Enforce the DMZ assumption by the bind, not by hope."
+# SKILLSCRIPT_EVENT_INGRESS_ENABLED=true
+
+# Optional bearer-token auth for POST /event. When set, every event
+# POST must carry `Authorization: Bearer <token>` matching this value;
+# 401 otherwise. Default unset = open-internally (still gated by the
+# bind address). Cheap to wire early — turning it on later is just an
+# env edit + restart, no refactor.
+# SKILLSCRIPT_EVENT_INGRESS_AUTH_TOKEN=your-secret-token-here
+
+
 # ─── Runtime tuning ────────────────────────────────────────────────────
 
 # Scheduler tick / poll interval in seconds. Default 30. Lower (e.g. 5)