skillscript-runtime 0.22.0 → 0.23.0

package/scaffold/.env.example

@@ -1,196 +1,119 @@
 # Skillscript runtime — example .env file.
 #
-# Copy this to `.env` in the same directory ($SKILLSCRIPT_HOME) and edit
-# the values you want set. The CLI auto-loads `.env` at startup and
-# populates `process.env` for any key not already set in the shell.
-#
+# Copy this to `.env` in $SKILLSCRIPT_HOME and uncomment the lines you want.
+# The CLI auto-loads `.env` at startup for any key not already set in the shell.
 # Precedence (most-specific wins):
-#   1. CLI flag       (e.g. `--port 8080`)
-#   2. Shell env var  (e.g. `export SKILLSCRIPT_PORT=8080`)
-#   3. This `.env`    (the values you set below)
-#   4. `skillscript.config.json` field
-#   5. Built-in default
+#   CLI flag  >  shell env var  >  this .env  >  skillscript.config.json  >  default
 #
-# Lines starting with `#` are comments. Blank lines are ignored.
-# Values can be quoted ("..." or '...') if they contain spaces.
+# This file says what each setting does. The security reasoning behind the
+# boundaries lives in docs/adopter-playbook.md.
 
 
 # ─── Approval boundary (secured mode) ──────────────────────────────────
 
-# Enforce the approval boundary: in secured mode, only a key-SIGNED skill
-# may perform effectful ops ($ / shell / file_* / notify). An unapproved or
-# tampered skill cannot execute a single effect, however it's dispatched
-# (CLI, cron, /event, MCP, composition). Default OFF — the unkeyed
-# convenience posture, where a bare `# Status: Approved` runs. Turn ON for
-# any multi-author or networked deployment.
+# Require a key-signed approval before a skill can run any effectful op
+# ($ / shell / file_* / notify). Default OFF — a bare `# Status: Approved`
+# runs. Turn ON for any multi-author or networked deployment.
 # SKILLSCRIPT_SECURED_MODE=true
 
-# Operator's Ed25519 approval keypair. First run in secured mode
-# auto-provisions one if the PUBLIC key is absent (private written 0600).
-# Defaults live OUTSIDE SKILLSCRIPT_HOME so a co-resident agent can't read
-# the forging key. HARDENED POSTURE: provision the keypair yourself, give
-# the deployment ONLY the public key (set the pub path, leave the private
-# off-box), and sign operator-side — the runtime verifies with the public
-# key and never needs the private one.
+# Paths to the operator's Ed25519 approval keypair. In secured mode the runtime
+# auto-provisions one on first run if the public key is missing. Hardened setup:
+# give the box only the public key and sign operator-side. Defaults live outside
+# SKILLSCRIPT_HOME.
 # SKILLSCRIPT_APPROVAL_KEY_FILE=~/.config/skillscript/approval.key
 # SKILLSCRIPT_APPROVAL_PUBLIC_KEY_FILE=~/.config/skillscript/approval.pub
 
-# Filesystem path allowlist for file_read / file_write (the third operator
-# allowlist; mirrors SKILLSCRIPT_SHELL_ALLOWLIST). Default-deny: unset = every
-# file op refused. Comma-separated roots, canonicalized so `..`/symlink can't
-# escape. KEEP YOUR APPROVAL-KEY DIRECTORY OUT OF IT.
+# Directory roots a skill may file_read / file_write under. Comma-separated
+# absolute paths. Unset = every file op refused. Keep your approval-key
+# directory OUT of this list.
 # SKILLSCRIPT_FS_ALLOWLIST=/srv/skillscript/workspace,/var/skillscript/events
 
-# Optional shared-secret gate for the dashboard (SPA + /rpc) — network/casual
-# hygiene when binding beyond localhost. Present via `?token=` (browser sets a
-# cookie), the `skillscript_dash` cookie, or `Authorization: Bearer`. Default
-# unset = open (localhost bind is the only gate). NOT an agent-forgery boundary
-# (the dashboard holds no signing key) — that remains key custody.
+# Shared secret for the dashboard (SPA + /rpc) when binding beyond localhost.
+# Pass via `?token=`, the `skillscript_dash` cookie, or `Authorization: Bearer`.
+# Default unset = open (the localhost bind is the only gate).
 # SKILLSCRIPT_DASHBOARD_AUTH_TOKEN=change-me-to-random-hex
 
-# In-browser approval. When set (+ secured mode + a readable key),
-# the dashboard offers click-to-Approve: the approver enters this passcode once
-# per browser session to unlock signing (15-min idle TTL), then signs skills
-# with the operator's key. Default unset = dashboard stays review-only (copy
-# the `skillfile approve` command, sign at a terminal). SECURITY: enabling this
-# gives the dashboard process key access — run it operator-side, isolated from
-# the agent (no network path to it; agent can't read this passcode).
+# Enable click-to-Approve in the dashboard. Needs secured mode + a readable key;
+# the approver enters this passcode once per browser session to unlock signing.
+# Default unset = dashboard is review-only. Run the dashboard operator-side when
+# enabling — it gets key access.
 # SKILLSCRIPT_APPROVAL_PASSCODE=change-me
 
 
 # ─── Posture / security switches ───────────────────────────────────────
 
-# Force every outside-MCP `skill_write` to land Draft regardless of what
-# the body declares. Closes the agent-self-approval path — adopters
-# wanting a human approval gate before any skill executes set this true.
-# Default false.
+# Make every skill an agent writes land as Draft, so a human must approve it
+# before it can run. Default false.
 # SKILLSCRIPT_FORCE_ALWAYS_DRAFT=true
 
-# Permit `shell(unsafe=true)` ops (full bash interpretation: pipes, $VAR,
-# command substitution). Default false. Set true only after auditing
-# every unsafe-shell op in your skill corpus — lint tier-2 warning fires
-# on every appearance regardless.
+# Allow shell(unsafe=true) — full bash (pipes, $VAR, command substitution).
+# Default false. Audit your unsafe-shell ops before enabling.
 # SKILLSCRIPT_ENABLE_UNSAFE_SHELL=true
 
-# Operator-controlled allowlist of binaries reachable via `shell(...)` ops.
-# Default-deny: when this var is unset, NO `shell()` op will run.
-# Set to a comma-separated list of binary names; the first token of each
-# `shell(command="X ...")` body must appear in the list.
-#
-# Two independent axes — separate from SKILLSCRIPT_ENABLE_UNSAFE_SHELL:
-#   - this var controls WHICH binaries (binary scope)
-#   - enable_unsafe_shell controls WHETHER bash interpretation is permitted
-#     (syntax scope)
-# Both must allow for a `shell(..., unsafe=true)` op to dispatch:
-#   on-list + safe syntax        → runs
-#   on-list + pipeline/unsafe     → runs iff ENABLE_UNSAFE_SHELL=true
-#   off-list                     → refused, period (no author keyword escapes this)
-#
-# For unsafe ops the runtime invokes `bash -c <body>` — the literal first
-# token is `bash`. So permitting any unsafe shell at all requires `bash`
-# on the allowlist in addition to ENABLE_UNSAFE_SHELL=true. Per-binary
-# scope on unsafe-mode bodies is NOT supported at runtime (parse-based
-# enumeration is unsound; OS-level execve/seccomp/restricted-PATH is the
-# proper layer — see docs/adopter-playbook.md).
-#
-# Discovery: run `skillfile shell-audit` to scan your skill corpus and emit
-# the current set of binaries used. Paste the suggested value here. Skills
-# using shell() will refuse to run until this is configured.
+# Binaries a skill may run via shell(). Comma-separated names; unset = no shell
+# op runs at all. Run `skillfile shell-audit` to list what your skills use.
+# (Permitting an unsafe shell op also needs `bash` here + the switch above.)
 # SKILLSCRIPT_SHELL_ALLOWLIST=curl,git,jq,grep
 
 
 # ─── Network / bind config ─────────────────────────────────────────────
 
-# Dashboard / serve HTTP bind address. Default 127.0.0.1 (localhost-only).
-# Container deployments set 0.0.0.0 so the host-side port-forward can
-# reach the listener.
+# HTTP bind address. Default 127.0.0.1 (localhost-only). Set 0.0.0.0 for
+# containers that port-forward from the host.
 # SKILLSCRIPT_HOST=0.0.0.0
 
-# Dashboard / serve HTTP port. Default 7878. Used for the SPA, JSON-RPC
-# at /rpc, AND the event-trigger ingress at /event (they share
-# one HTTP server — no separate event port).
-# SKILLSCRIPT_PORT=8080
+# HTTP port for the SPA, /rpc, and /event. Default 7878.
+# SKILLSCRIPT_PORT=7878
 
 
-# ─── Event-trigger HTTP ingress ──────────────────────────────
+# ─── Event-trigger HTTP ingress ────────────────────────────────────────
 
-# 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."
+# Enable POST /event so external services can fire event-triggered skills.
+# Default false (route returns 404). Mounts on SKILLSCRIPT_PORT; localhost-only
+# unless SKILLSCRIPT_HOST is opened.
 # 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.
+# Require `Authorization: Bearer <token>` on every POST /event. Default unset =
+# no token check (still gated by the bind address).
 # SKILLSCRIPT_EVENT_INGRESS_AUTH_TOKEN=your-secret-token-here
 
 
 # ─── Runtime tuning ────────────────────────────────────────────────────
 
-# Scheduler tick / poll interval in seconds. Default 30. Lower (e.g. 5)
-# for test environments wanting faster trigger pickup; higher for deployments
-# wanting less CPU churn at the cost of cron-edge timing accuracy.
+# Scheduler tick interval, seconds. Default 30. Lower for faster trigger pickup
+# in tests; higher for less CPU churn.
 # SKILLSCRIPT_POLL_INTERVAL_SECONDS=30
 
-# Runtime absolute timeout in milliseconds — the built-in fallback when
-# no per-op, skill (`# Timeout:`), or connector default applies. Default
-# 300000 (5 minutes). Adopters tightening prod cancellation windows or
-# raising for skills doing legitimately-long work (large $ llm runs)
-# set this. Operator-grade kill switch; per-skill `# Timeout: N` header
-# is the author-grade knob for the same intent.
+# Fallback run timeout, milliseconds, when no per-op / `# Timeout:` / connector
+# default applies. Default 300000 (5 min).
 # SKILLSCRIPT_ABSOLUTE_TIMEOUT_MS=300000
 
-# Composition recursion depth ceiling. Default 10. The runtime throws
-# `RecursionDepthExceededError` when a skill's `$ execute_skill` /
-# inline-composition chain exceeds this. Adopters with deeply composing
-# skill suites (chaining 8+ levels) bump this; tightening below the
-# default is a guardrail signal that the skill suite is composing
-# too deeply.
+# Max composition depth before the runtime throws. Default 10. Raise for
+# deeply-composing skill suites.
 # SKILLSCRIPT_MAX_RECURSION_DEPTH=10
 
 
 # ─── Identity propagation (multi-agent hosts only) ─────────────────────
 
-# Inbound HTTP header name carrying host-attested caller identity.
-# When set, `DashboardServer` reads this header on every /rpc request
-# and threads the value as `McpRequestCtx.callerIdentity`; the
-# `skill_write` handler captures it as `SkillMeta.author`. Multi-agent
-# MCP hosts (NanoClaw-style) configure this. Skip if single-user /
-# single-tenant — author is captured from the runtime's own writer
-# identity by default. See adopter playbook for the trust model.
+# HTTP header carrying host-attested caller identity; captured as a skill's
+# author on skill_write. For multi-agent MCP hosts; skip if single-tenant.
 # SKILLSCRIPT_MCP_CALLER_IDENTITY_HEADER=X-Agent-Id
 
 
 # ─── LocalModel (Ollama) ───────────────────────────────────────────────
 
-# Override the Ollama endpoint. Default http://localhost:11434.
+# Ollama endpoint. Default http://localhost:11434.
 # OLLAMA_BASE_URL=http://ollama.internal:11434
 
 
 # ─── Substrate-specific tokens / endpoints ─────────────────────────────
 #
-# Any variable set here is also reachable via `${VAR}` substitution in
-# `skillscript.config.json` and `connectors.json`. The canonical adopter
-# pattern: secrets + endpoints in `.env` (gitignored), declarative shape
-# in JSON configs (committed).
-#
-# Example wiring in connectors.json:
+# Any var set here is also usable as `${VAR}` in skillscript.config.json and
+# connectors.json — the adopter pattern is secrets in `.env` (gitignored),
+# declarative shape in JSON (committed). Example connectors.json wiring:
 #
-#   {
-#     "amp": {
-#       "class": "HttpMcpConnector",
-#       "config": {
-#         "endpoint": "${AMP_ENDPOINT}",
-#         "headers": { "Authorization": "Bearer ${AMP_TOKEN}" }
-#       }
-#     }
-#   }
+#   "config": { "endpoint": "${AMP_ENDPOINT}",
+#               "headers": { "Authorization": "Bearer ${AMP_TOKEN}" } }
 #
 # AMP_ENDPOINT=https://amp.internal/rpc
 # AMP_TOKEN=your-token-here
@@ -198,6 +121,5 @@
 
 # ─── NOT settable via .env (chicken-and-egg) ───────────────────────────
 #
-# SKILLSCRIPT_HOME — read BEFORE this .env loads (we need HOME_DIR to
-# find the .env). Set in your shell, Docker `-e`, or systemd Environment=
-# directive instead.
+# SKILLSCRIPT_HOME is read BEFORE this file loads (we need it to find the file).
+# Set it in your shell, Docker `-e`, or systemd Environment=.