skillscript-runtime 0.2.4

package/dist/trace.js

@@ -0,0 +1,226 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { join, basename, dirname } from "node:path";
+const DEFAULT_SAMPLE_PCT = 10;
+const DEFAULT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+// ─── FilesystemTraceStore (bundled default) ─────────────────────────────────
+/**
+ * Writes JSON records under `<rootDir>/<skill_name>/<trace_id>.json`.
+ * Zero external dependency; suitable for the standalone runtime out of
+ * the box. Operators with a substrate wired can swap for a
+ * substrate-backed store via config.
+ */
+export class FilesystemTraceStore {
+    rootDir;
+    constructor(rootDir) {
+        this.rootDir = rootDir;
+    }
+    async write(record) {
+        const dir = join(this.rootDir, sanitize(record.skill_name));
+        await mkdir(dir, { recursive: true });
+        const path = join(dir, `${record.trace_id}.json`);
+        await writeFile(path, JSON.stringify(record, null, 2), "utf8");
+    }
+    async query(filter) {
+        const results = [];
+        let skillDirs;
+        if (filter.skill_name !== undefined) {
+            skillDirs = [sanitize(filter.skill_name)];
+        }
+        else {
+            try {
+                skillDirs = await readdir(this.rootDir);
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    return [];
+                throw err;
+            }
+        }
+        for (const skillDir of skillDirs) {
+            const full = join(this.rootDir, skillDir);
+            let entries;
+            try {
+                entries = await readdir(full);
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    continue;
+                throw err;
+            }
+            for (const entry of entries) {
+                if (!entry.endsWith(".json"))
+                    continue;
+                try {
+                    const text = await readFile(join(full, entry), "utf8");
+                    const rec = JSON.parse(text);
+                    if (filter.since_ms !== undefined && rec.fired_at_ms < filter.since_ms)
+                        continue;
+                    if (filter.until_ms !== undefined && rec.fired_at_ms > filter.until_ms)
+                        continue;
+                    results.push(rec);
+                }
+                catch {
+                    /* unreadable / unparseable — skip */
+                }
+            }
+        }
+        results.sort((a, b) => b.fired_at_ms - a.fired_at_ms);
+        if (filter.limit !== undefined)
+            return results.slice(0, filter.limit);
+        return results;
+    }
+    async get(traceId) {
+        let skillDirs;
+        try {
+            skillDirs = await readdir(this.rootDir);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+        for (const skillDir of skillDirs) {
+            const path = join(this.rootDir, skillDir, `${traceId}.json`);
+            try {
+                const text = await readFile(path, "utf8");
+                return JSON.parse(text);
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    continue;
+                throw err;
+            }
+        }
+        return null;
+    }
+    async prune(retentionMs) {
+        const cutoff = Date.now() - retentionMs;
+        let count = 0;
+        let skillDirs;
+        try {
+            skillDirs = await readdir(this.rootDir);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return 0;
+            throw err;
+        }
+        for (const skillDir of skillDirs) {
+            const full = join(this.rootDir, skillDir);
+            let entries;
+            try {
+                entries = await readdir(full);
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (!entry.endsWith(".json"))
+                    continue;
+                const path = join(full, entry);
+                try {
+                    const text = await readFile(path, "utf8");
+                    const rec = JSON.parse(text);
+                    if (rec.fired_at_ms < cutoff) {
+                        await unlink(path);
+                        count++;
+                    }
+                }
+                catch {
+                    /* skip unreadable */
+                }
+            }
+        }
+        return count;
+    }
+}
+// ─── Sampling decision ─────────────────────────────────────────────────────
+/**
+ * Deterministic sample decision per Open Q #2: SHA-256 of `trigger_id +
+ * ":" + skill_name`, take the first byte mod 100, fire trace if under
+ * `pct`. Same inputs always produce the same sampling decision — useful
+ * for reproducible testing + dashboard drill-down.
+ */
+export function shouldSample(triggerId, skillName, pct) {
+    if (pct >= 100)
+        return true;
+    if (pct <= 0)
+        return false;
+    const hash = createHash("sha256").update(`${triggerId}:${skillName}`).digest();
+    return hash[0] % 100 < pct;
+}
+// ─── TraceBuilder (mutable, used during execution) ──────────────────────────
+/**
+ * Accumulator used by the runtime during a single fire. Records per-op
+ * timing + body; finalize() builds the immutable TraceRecord.
+ */
+export class TraceBuilder {
+    skill_name;
+    skill_version;
+    trigger;
+    identity;
+    ops = [];
+    firedAtMs;
+    trace_id;
+    constructor(skill_name, skill_version, trigger, identity) {
+        this.skill_name = skill_name;
+        this.skill_version = skill_version;
+        this.trigger = trigger;
+        this.identity = identity;
+        this.firedAtMs = trigger.fired_at_ms;
+        this.trace_id = randomUUID();
+    }
+    recordOp(record) {
+        this.ops.push(record);
+    }
+    finalize(emissions, outputs, errors) {
+        const completedAtMs = Date.now();
+        return {
+            version: 1,
+            trace_id: this.trace_id,
+            skill_name: this.skill_name,
+            skill_version: this.skill_version,
+            trigger: this.trigger,
+            identity: this.identity,
+            ops: this.ops,
+            emissions: [...emissions],
+            outputs: { ...outputs },
+            errors: [...errors],
+            fired_at_ms: this.firedAtMs,
+            completed_at_ms: completedAtMs,
+            duration_ms: completedAtMs - this.firedAtMs,
+        };
+    }
+}
+/**
+ * Decide whether a fire should be traced given config + trigger context.
+ * Used by the runtime / scheduler at fire start. `mode === "off"` always
+ * returns false (errors are still surfaced via `result.errors[]` — the
+ * NFR-11 floor); the trace store is bypassed entirely.
+ */
+export function shouldTraceFire(config, triggerId, skillName) {
+    if (config === undefined || config.mode === "off")
+        return false;
+    if (config.mode === "on")
+        return true;
+    const pct = config.samplePct ?? DEFAULT_SAMPLE_PCT;
+    return shouldSample(triggerId, skillName, pct);
+}
+export const TRACE_DEFAULTS = {
+    SAMPLE_PCT: DEFAULT_SAMPLE_PCT,
+    RETENTION_MS: DEFAULT_RETENTION_MS,
+};
+// ─── Internals ──────────────────────────────────────────────────────────────
+function sanitize(name) {
+    // Filesystem-safe per the FilesystemSkillStore convention. Same charset
+    // — alphanumeric, hyphen, underscore, dot.
+    return name.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+/** Convenience for tests: derive the on-disk path FilesystemTraceStore writes to. */
+export function _traceFilePathFor(rootDir, record) {
+    void basename;
+    void dirname;
+    return join(rootDir, sanitize(record.skill_name), `${record.trace_id}.json`);
+}
+//# sourceMappingURL=trace.js.map

package/dist/trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../src/trace.ts"],"names":[],"mappings":"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"}

package/examples/README.md

@@ -0,0 +1,56 @@
+# Examples
+
+Curated production-quality skills demonstrating distinct language patterns. Each compiles + lints clean and can be run directly via `skillfile run examples/<name>.skill.md` (some require connectors — see the per-skill notes below).
+
+For full language semantics, see [`../docs/language-reference.md`](../docs/language-reference.md).
+
+| Example | Patterns demonstrated |
+|---|---|
+| [`hello.skill.md`](./hello.skill.md) | Three-command first run; `! emit`; default target; `# Vars:` declared inputs |
+| [`morning-brief.skill.md`](./morning-brief.skill.md) | Multi-target with `needs:`; cron-fired with `EVENT.fired_at_*`; `# OnError:` fallback; dual `# Output:` (slack + prompt-context); `# Requires:` user-var cascade with fallback; LocalModel + retrieval composition |
+| [`doc-qa-with-citations.skill.md`](./doc-qa-with-citations.skill.md) | Single-target retrieval; `(fallback: [])` op-level fallback; LLM-with-citation pattern; pipe filter `\|json` for prompt embedding |
+| [`classify-support-ticket.skill.md`](./classify-support-ticket.skill.md) | `if`/`elif`/`else` multi-branch routing; classifier-cascade pattern; MemoryStore `$` writes with structured `domain_tags`; `$set` literal binding |
+| [`cut-release-tag.skill.md`](./cut-release-tag.skill.md) | `??` interactive ask-for-input; `else:` short-circuit on multiple targets; `@` shell ops with per-op error fallback; rollback-on-failure flow |
+| [`service-health-watch.skill.md`](./service-health-watch.skill.md) | `foreach` iteration; cron-fired with `expires_at=$(EVENT.fired_at_plus_1d_unix)` TTL math; classifier-gated MemoryStore writes; pipe filter `\|url` for path-safe interpolation |
+| [`feedback-sentiment-scan.skill.md`](./feedback-sentiment-scan.skill.md) | `in` / `not in` set-membership ops; dedupe-via-seen-markers idiom; nested `if`/`elif` classification cascade; TTL on bookkeeping writes |
+
+## Connector requirements
+
+Most examples assume the bundled-default connectors:
+
+- `hello.skill.md` — zero deps (runs cold)
+- `doc-qa-with-citations.skill.md` — Ollama (LocalModel) + MemoryStore for the retrieval cache
+- `morning-brief.skill.md`, `feedback-sentiment-scan.skill.md` — Ollama + MemoryStore + a calendar MCP connector (the `$ calendar.list_events` op)
+- `classify-support-ticket.skill.md` — Ollama + MemoryStore
+- `cut-release-tag.skill.md` — git CLI on `PATH`; expects to run inside a git repo
+- `service-health-watch.skill.md` — `curl` on `PATH`; network egress to `status.internal/*`
+
+Skills that talk to MCP tools (like `calendar.list_events`) need that tool wired into the `Registry` via `registerMcpConnector()`. The `CallbackMcpConnector` in `skillscript-runtime/connectors` lets you stub one inline for development.
+
+## Running an example
+
+```sh
+# Cold install — no Ollama, no MCP, no external state
+skillfile run examples/hello.skill.md
+
+# With overrides
+skillfile run examples/hello.skill.md --input WHO=Scott
+
+# Preview the compiled artifact without execution
+skillfile compile examples/hello.skill.md
+
+# Mechanical preview — $/~/> ops short-circuit (useful for examining flow
+# without firing real LLM calls)
+skillfile run examples/morning-brief.skill.md --mechanical
+
+# Render the control-flow graph
+skillfile diagram examples/cut-release-tag.skill.md
+```
+
+## Programmatic example
+
+`programmatic-trace-demo.mjs` shows the library API path — wiring a `FilesystemSkillStore` + `FilesystemTraceStore` + `Scheduler`, dispatching a skill, and reading back the recorded trace + per-skill health metrics.
+
+```sh
+node examples/programmatic-trace-demo.mjs
+```

package/examples/classify-support-ticket.skill.md

@@ -0,0 +1,30 @@
+# Skill: classify-support-ticket
+# Status: Approved
+# Description: Read an incoming support ticket and route it: severity-1 tickets get paged to ops-channel, billing tickets get tagged for finance review, everything else gets a draft reply queued for human review
+# Vars: TICKET_TEXT, TICKET_ID
+# Output: slack: ops-pages
+
+classify:
+    ~ prompt="Categorize this support ticket. Reply with EXACTLY one of: 'sev-1', 'billing', 'general'. No other text.\n\nTicket: $(TICKET_TEXT)" model=qwen maxTokens=10 -> CATEGORY
+
+severity_check:
+    needs: classify
+    ~ prompt="Does this support ticket describe a service outage, data loss, security incident, or other production-severity-1 issue? Reply ONLY 'yes' or 'no'.\n\nTicket: $(TICKET_TEXT)" model=qwen maxTokens=10 -> IS_SEV1
+
+route:
+    needs: severity_check
+    if $(CATEGORY|trim) == "sev-1":
+        ! PAGE: sev-1 ticket $(TICKET_ID) - $(TICKET_TEXT)
+        $ memorystore.write summary="sev-1 ticket $(TICKET_ID)" detail="$(TICKET_TEXT)" knowledge_type=hard_won vault=private domain_tags=["support","sev-1","page"]
+    elif $(IS_SEV1|trim) == "yes":
+        ! PAGE: classifier said $(CATEGORY|trim) but severity-check flagged this as sev-1: $(TICKET_ID)
+        $ memorystore.write summary="sev-1 escalation $(TICKET_ID)" detail="category=$(CATEGORY|trim) but severity-check=yes" knowledge_type=hard_won vault=private domain_tags=["support","sev-1","disagreement"]
+    elif $(CATEGORY|trim) == "billing":
+        $set TAG_FOR = "finance"
+        ! Tagged for $(TAG_FOR) review: $(TICKET_ID)
+        $ memorystore.write summary="billing ticket $(TICKET_ID)" detail="$(TICKET_TEXT)" knowledge_type=common vault=private domain_tags=["support","billing"]
+    else:
+        ~ prompt="Draft a polite acknowledgment reply for this support ticket. Two short sentences. No greeting, no sign-off.\n\n$(TICKET_TEXT)" model=qwen maxTokens=150 -> DRAFT
+        $ memorystore.write summary="support draft $(TICKET_ID)" detail="$(DRAFT|trim)" knowledge_type=common vault=private domain_tags=["support","draft"]
+
+default: route

package/examples/cut-release-tag.skill.md

@@ -0,0 +1,40 @@
+# Skill: cut-release-tag
+# Status: Approved
+# Description: Run when the user says "ship a release" or "cut a tag" on the current branch; collects commit-list since last tag, asks the user to confirm the version bump, applies the tag, and pushes it
+# Vars: BUMP_KIND=patch
+# Output: text
+
+last_tag:
+    @ git describe --tags --abbrev=0 -> PREV_TAG
+else:
+    $set PREV_TAG = "(no prior tags)"
+    ! no previous tag found; treating this as the first release
+
+commits_since:
+    needs: last_tag
+    @ git log --oneline $(PREV_TAG)..HEAD -> COMMITS
+else:
+    $set COMMITS = "(unable to read commit log; proceeding without preview)"
+
+propose:
+    needs: commits_since
+    ~ prompt="Propose the next semver tag given prev tag '$(PREV_TAG)', bump kind '$(BUMP_KIND)', and commits below. Return ONLY the new tag string (e.g. v1.4.3). No commentary.\n\nCommits:\n$(COMMITS)" model=qwen maxTokens=30 -> PROPOSED_TAG
+
+confirm:
+    needs: propose
+    ! Previous tag: $(PREV_TAG)
+    ! Commits since:
+    ! $(COMMITS)
+    ! Proposed new tag: $(PROPOSED_TAG|trim)
+    ?? "Cut tag $(PROPOSED_TAG|trim)?" -> APPROVED
+
+apply:
+    needs: confirm
+    @ git tag $(PROPOSED_TAG|trim) -> TAG_OUT
+    @ git push origin $(PROPOSED_TAG|trim) -> PUSH_OUT
+    ! Tagged and pushed $(PROPOSED_TAG|trim)
+else:
+    ! Tag/push failed; rolling back local tag
+    @ git tag -d $(PROPOSED_TAG|trim) -> ROLLBACK
+
+default: apply

package/examples/doc-qa-with-citations.skill.md

@@ -0,0 +1,12 @@
+# Skill: doc-qa-with-citations
+# Status: Approved
+# Description: When the user asks a question that requires retrieval over the doc set, answer with inline citations to memory IDs
+# Vars: QUESTION, K=6
+# Output: text
+
+answer:
+    > mode=rerank query="$(QUESTION)" limit=$(K) -> HITS (fallback: [])
+    ~ prompt="Answer the question using ONLY the supplied passages. Cite each claim inline as [id:<memory-id>]. Question: $(QUESTION). Passages: $(HITS|json)" maxTokens=900 -> RESPONSE
+    ! $(RESPONSE)
+
+default: answer

package/examples/feedback-sentiment-scan.skill.md

@@ -0,0 +1,29 @@
+# Skill: feedback-sentiment-scan
+# Status: Approved
+# Description: Each night, scan the previous 24h of customer feedback records, classify sentiment via local model, surface entries where sentiment is "frustrated" or "blocking" so the team sees them at start-of-day; skip entries already seen on prior nights
+# Triggers: cron: 0 3 * * *
+# Vars: SCAN_LIMIT=50
+# Output: slack: customer-pulse
+# Output: prompt-context: support-lead
+
+fetch_new:
+    > mode=fts query="customer feedback" limit=$(SCAN_LIMIT) created_after=$(EVENT.fired_at_unix) -> FEEDBACK
+
+fetch_seen:
+    > mode=fts query="sentiment-scan seen marker" limit=200 domain_tags=["sentiment-scan-seen"] -> SEEN_MARKERS
+
+classify_and_emit:
+    needs: fetch_new, fetch_seen
+    ! Sentiment scan results for $(NOW):
+    foreach F in $(FEEDBACK):
+        if $(F.id|trim) in $(SEEN_MARKERS):
+            ! - skipped (already classified): $(F.id|trim)
+        elif $(F.id|trim) not in $(SEEN_MARKERS):
+            ~ prompt="Classify the sentiment of this customer feedback. Respond with ONE word: 'frustrated', 'blocking', 'satisfied', 'neutral'. No explanation.\n\nFeedback: $(F.summary)\nDetail: $(F.detail)" model=gemma2 maxTokens=10 -> VERDICT
+            if $(VERDICT|trim) == "frustrated":
+                ! - FRUSTRATED [$(F.id|trim)] $(F.summary)
+            elif $(VERDICT|trim) == "blocking":
+                ! - BLOCKING [$(F.id|trim)] $(F.summary)
+            $ memorystore.write summary="sentiment-scan seen $(F.id|trim)" detail="verdict=$(VERDICT|trim) on $(EVENT.fired_at_unix)" knowledge_type=common vault=private domain_tags=["sentiment-scan-seen"] expires_at=$(EVENT.fired_at_plus_7d_unix)
+
+default: classify_and_emit

package/examples/hello.skill.md

@@ -0,0 +1,9 @@
+# Skill: hello
+# Description: The canonical first-run example — runs without Ollama, MCP, or external state.
+# Vars: WHO=world
+
+greet:
+    ! Hello, $(WHO)!
+    ! Welcome to Skillscript. You ran a skill end-to-end with three commands.
+
+default: greet

package/examples/hello.skill.provenance.json

@@ -0,0 +1,10 @@
+{
+  "provenance_version": "1.0",
+  "language_version": "1.0",
+  "compiler_version": "0.1.0-dev",
+  "compiled_at": "2026-05-22T17:41:55.239Z",
+  "source_skill": {
+    "name": "hello"
+  },
+  "data_skills_inlined": []
+}

package/examples/morning-brief.skill.md

@@ -0,0 +1,24 @@
+# Skill: morning-brief
+# Status: Approved
+# Description: Compose a daily morning brief from calendar, mailbox, and overnight memory writes when the cron trigger fires at 7am.
+# Vars: AGENT, BRIEF_HORIZON_HOURS=24
+# Requires: user-var:morning-brief-channel -> CHANNEL (fallback: dev-null)
+# Triggers: cron: 0 7 * * *
+# OnError: morning-brief-degraded
+# Output: slack: $(CHANNEL)
+# Output: prompt-context: perry
+
+calendar:
+    $ calendar.list_events horizon_hours=$(BRIEF_HORIZON_HOURS) -> EVENTS
+
+mailbox:
+    > mode=fts query="addressed:$(AGENT) created_after:$(EVENT.fired_at_unix)" limit=10 -> MAIL
+
+overnight:
+    > mode=rerank query="overnight writes since:$(EVENT.fired_at_plus_1d_unix)" limit=15 -> NOTES
+
+compose: needs: calendar, mailbox, overnight
+    ~ prompt="Compose a concise morning brief. Calendar: $(EVENTS|json). Mailbox: $(MAIL|json). Overnight notes: $(NOTES|json). Three sections, six bullets max each." model=qwen maxTokens=1200 -> BRIEF
+    ! $(BRIEF)
+
+default: compose

package/examples/programmatic-trace-demo.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+// Programmatic Scheduler demo — exercises the library API surface that
+// embedders (not just CLI users) would use. Wires:
+//   - FilesystemSkillStore for skill sources
+//   - FilesystemTraceStore for dispatch traces
+//   - Scheduler with trace recording enabled
+// Then registers a cron trigger, dispatches a few times, and queries
+// traces + metrics back. ~60 lines of operator-shaped code.
+//
+// Run:   node examples/programmatic-trace-demo.mjs
+// Uses:  /tmp/skillscript-prog-demo as a sandbox.
+
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  Scheduler,
+  FilesystemSkillStore,
+  FilesystemTraceStore,
+  Registry,
+  healthMetrics,
+} from "../dist/index.js";
+
+const HOME = "/tmp/skillscript-prog-demo";
+rmSync(HOME, { recursive: true, force: true });
+mkdirSync(join(HOME, "skills"), { recursive: true });
+mkdirSync(join(HOME, "traces"), { recursive: true });
+
+const skillStore = new FilesystemSkillStore(join(HOME, "skills"));
+const traceStore = new FilesystemTraceStore(join(HOME, "traces"));
+
+const SKILL_SRC = `# Skill: heartbeat
+# Description: Per-fire heartbeat exercising the observability surface.
+# Status: Approved
+# Triggers: cron: */1 * * * *
+
+emit:
+    ! heartbeat at $(EVENT.fired_at_unix)
+
+default: emit
+`;
+await skillStore.store("heartbeat", SKILL_SRC);
+console.log(`stored skill at ${HOME}/skills/heartbeat.skill.md\n`);
+
+const sched = new Scheduler({
+  registry: new Registry(),
+  skillStore,
+  traceStore,
+  trace: { mode: "on" },
+});
+
+sched.registerTrigger({
+  skillName: "heartbeat",
+  source: "cron",
+  name: "*/1 * * * *",
+  declarative: true,
+});
+
+// Fire 5 times via direct dispatch (the scheduler would also fire these
+// via the poll loop; direct dispatch is faster for the demo).
+console.log("dispatching 5 fires...");
+for (let i = 0; i < 5; i++) {
+  const firedAtMs = Date.now();
+  const result = await sched.dispatchSkill("heartbeat", undefined, {
+    source: "cron",
+    name: "*/1 * * * *",
+    fired_at_ms: firedAtMs,
+    trigger_id: `demo-${i}`,
+  });
+  const status = result.errors.length === 0 ? "ok" : `err:${result.errors[0].class}`;
+  console.log(`  fire ${i + 1}: ${status} (${result.emissions[0]})`);
+  // Brief sleep so fired_at_ms timestamps don't collide.
+  await new Promise((r) => setTimeout(r, 20));
+}
+
+console.log("\nquerying traces back:");
+const traces = await traceStore.query({ skill_name: "heartbeat", limit: 10 });
+for (const t of traces) {
+  const ts = new Date(t.fired_at_ms).toISOString();
+  console.log(`  ${ts}  ${t.trace_id}  ops=${t.ops.length}  errors=${t.errors.length}`);
+}
+
+console.log("\nhealth metrics:");
+const metrics = await healthMetrics(traceStore, { since_ms: Date.now() - 60_000 });
+console.log(`  total fires: ${metrics.totalFires}`);
+for (const [name, m] of Object.entries(metrics.perSkill)) {
+  console.log(`  ${name}: ${m.fireCount} fires, successRate=${(m.successRate * 100).toFixed(0)}%`);
+}
+
+console.log(`\ntrace files on disk: ${HOME}/traces/heartbeat/`);

package/examples/service-health-watch.skill.md

@@ -0,0 +1,18 @@
+# Skill: service-health-watch
+# Status: Approved
+# Description: Every 5 minutes check named service endpoints — if latency or status degrades, write a signal memory and alert
+# Vars: SERVICES=[auth-api, ledger-api, search-api], LATENCY_BUDGET_MS=400
+# Triggers: cron: */5 * * * *
+# Output: none
+
+probe:
+    foreach SVC in $(SERVICES):
+        @ curl -s -o /dev/null -w "%{http_code} %{time_total}" https://status.internal/$(SVC|url) -> RAW
+        ~ prompt="From the line '$(RAW|trim)' (http_code time_seconds), and budget $(LATENCY_BUDGET_MS) ms, answer ok or degraded only." -> STATUS
+        if $(STATUS|trim) == "degraded":
+            $ memorystore.write summary="service degradation: $(SVC)" detail="probe at $(NOW): $(RAW|trim)" domain_tags=[ops, service-health, degraded:$(SVC)] vault=private knowledge_type=common expires_at=$(EVENT.fired_at_plus_1d_unix) -> ACK
+            ! $(SVC) degraded — wrote signal
+        else:
+            ! $(SVC) ok
+
+default: probe

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "skillscript-runtime",
+  "version": "0.2.4",
+  "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>",
+  "homepage": "https://github.com/sshwarts/skillscript-runtime",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sshwarts/skillscript-runtime.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sshwarts/skillscript-runtime/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./connectors": {
+      "types": "./dist/connectors/index.d.ts",
+      "import": "./dist/connectors/index.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "import": "./dist/errors.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.js"
+    },
+    "./trace": {
+      "types": "./dist/trace.d.ts",
+      "import": "./dist/trace.js"
+    },
+    "./metrics": {
+      "types": "./dist/metrics.d.ts",
+      "import": "./dist/metrics.js"
+    },
+    "./scheduler": {
+      "types": "./dist/scheduler.d.ts",
+      "import": "./dist/scheduler.js"
+    },
+    "./mcp-server": {
+      "types": "./dist/mcp-server.d.ts",
+      "import": "./dist/mcp-server.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "skillfile": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "scaffold",
+    "examples",
+    "ARCHITECTURE.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.5"
+  },
+  "keywords": [
+    "skillscript",
+    "agent",
+    "agent-workflow",
+    "dsl",
+    "declarative",
+    "workflow",
+    "llm",
+    "mcp",
+    "model-context-protocol"
+  ],
+  "dependencies": {
+    "cron-parser": "^4.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/copy-dashboard-assets.mjs",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "loc-check": "node scripts/loc-ceiling.mjs",
+    "lint": "tsc --noEmit && vitest run"
+  }
+}