skillscript-runtime 0.2.4

package/ARCHITECTURE.md

@@ -0,0 +1,70 @@
+# Architecture
+
+One-page map of the `skillscript-runtime` codebase. Per ERD §1, the core stays ≤ 5K LOC across < 20 source files. Tests count separately.
+
+## Top-level layout
+
+```
+src/
+  index.ts              — library entrypoint; named exports for embedders
+  cli.ts                — `skillfile` CLI entrypoint
+  parser.ts             — source text → AST
+  compile.ts            — AST → resolved skill model → rendered artifact (owns toposort)
+  filters.ts            — pipe-filter implementations (url / shell / json / trim)
+  lint.ts               — structural validation (compiler preflight + standalone)
+  runtime.ts            — executor: walks compiled artifact, dispatches ops
+  scheduler.ts          — trigger registry + cron scan (T5)
+  output.ts             — output dispatch (text, prompt-context, none) (T6/T7)
+  connectors/
+    types.ts            — contracts: SkillStore, MemoryStore, LocalModel, McpConnector
+    registry.ts         — per-kind instance registry + three-layer resolution
+    skill-store.ts      — bundled default: filesystem at ~/.skillscript/skills/
+    memory-store.ts     — bundled default: SQLite + FTS at ~/.skillscript/memory.db
+    local-model.ts      — bundled default: Ollama at localhost:11434
+    mcp.ts              — bundled default: stub; no servers wired by default
+```
+
+Target: 13 source files written + 2 more planned (scheduler.ts in T5, output.ts in T6/T7). Budget headroom from the < 20 ceiling: 5 files.
+
+## What each file owns
+
+| File | Responsibility |
+| --- | --- |
+| `parser.ts` | Tokenize and parse skill source. Header lines, target blocks, op grammar, conditionals, `foreach`, variable interpolation. Produces AST. Syntax errors only — semantic checks are downstream. |
+| `compile.ts` | Three subsystems: (1) variable resolution against `# Requires:` cascade + caller inputs; (2) data-skill compile-time inlining (T3); (3) topo-sort + render. Owns the `toposort` function (semantic analysis). Output formats: `prompt` (canonical), `prose`, `test`. Produces compiled artifact + provenance. |
+| `filters.ts` | Pipe-filter implementations dispatched by `$(NAME|filter)` syntax. v1: `url`, `shell`, `json`, `trim`. Adding a new filter = adding a case to `applyFilter` and documenting it in the Language Reference. Per ERD §2 modifiability, this is the predictable location agents look for filter extensions. |
+| `lint.ts` | Structured diagnostics. T1 baseline rules: `parse-error` (any parser syntax error), `no-targets` (zero targets), `no-entry-target` (no `default:` resolved), `orphan-target` (target unreachable from entry). Full 20-rule v1 set + adversarial library land in T4 — baseline rules keep their IDs and severity through T4 so authors consuming today's diagnostics don't see breakage. |
+| `runtime.ts` | Executor that walks the compiled artifact and dispatches ops through connector instances. Handles error propagation, per-op timeout chain, `foreach` iteration, conditionals, `$set`, output binding. |
+| `scheduler.ts` | Trigger registry. Cron firing in v1; event/agent-event/file-watch/sensor are parse-only. Status-aware: skips `Draft` / `Disabled` skills at fire time. |
+| `output.ts` | Routes the goal target's output by `# Output:` header. Kinds: `text` (stdout), `prompt-context` (returns to caller), `none`. |
+| `connectors/types.ts` | The four contract interfaces. The integration boundary — every external system (skill storage, memory, local model, MCP) plugs in through one of these. |
+| `connectors/registry.ts` | Maps connector names to instances. Three-layer resolution: per-call override > skill-declared > primary default. Multi-instance support. |
+| `connectors/skill-store.ts` | Filesystem-backed `SkillStore`. Reads/writes skills as `*.skill.md` files under `~/.skillscript/skills/` (the `.skill` extension is reserved for compiled artifacts). Status transitions produce git-friendly file history. |
+| `connectors/memory-store.ts` | SQLite-backed `MemoryStore` with FTS5. Schema: `memories(id, summary, detail, tags, created_at)`. PortableMemory shape + metadata bag. |
+| `connectors/local-model.ts` | Ollama HTTP client. Bundled instances: `default` and `gemma2` (both `gemma2:9b`), `qwen` (`qwen2.5:7b`). |
+| `connectors/mcp.ts` | MCP connector scaffold. v1: no servers wired by default; `connectors.json` has commented example. |
+
+## Non-source
+
+```
+docs/                   — spec documentation (PRD, Language Reference, ERD)
+examples/               — bundled example skills (incl. `hello.skill.md`)
+scaffold/               — files copied by `skillfile init` into ~/.skillscript/
+scripts/loc-ceiling.mjs — CI check; fails if core exceeds budget
+tests/                  — vitest specs
+.github/workflows/      — CI: tests + loc-ceiling on push/PR
+Dockerfile              — multi-arch image base
+docker-compose.yml      — runtime + Ollama + SQLite volume
+```
+
+## Out-of-scope for T1
+
+Defers to later threads per the v1 plan:
+
+- **T2** — full connector contract surface, capabilities discovery, identity propagation
+- **T3** — data-skill inlining in `compile.ts` (T1 ports the existing simpler compile path)
+- **T4** — 20-rule v1 lint set + adversarial library
+- **T5** — autonomous trigger dispatch (T1 has parse-only `# Triggers:`)
+- **T6** — browser dashboard
+- **T7** — full CLI (`diagram`, `audit`, `sign`/`verify`, etc.), MCP server contract
+- **T8** — backend-specific adapters for the four contracts

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scott Shwarts
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,346 @@
+# Skillscript
+
+> A small declarative language for authoring agent workflows.
+
+**Status: v1 in progress (current release: 0.2.4).** The public API, language syntax, and connector contracts may change before v1.0.0. Expect breakage until then.
+
+A skillscript is a declarative recipe — a small program with a dependency DAG of named targets, each composed of typed operations. Skills are authored once and executed many times, either by the interpreter (autonomous, cron-fired) or by an agent reading a compiled prompt artifact.
+
+The runtime is substrate-neutral. Bundled reference connectors back filesystem, SQLite, Ollama, and an MCP scaffold; adapter implementations against other backings (cloud key-value stores, hosted LLMs, vector DBs) live in separate packages that consume the public connector contracts exported here.
+
+---
+
+## Table of contents
+
+1. [Installation](#installation)
+2. [Quickstart: author and run a skill](#quickstart-author-and-run-a-skill)
+3. [CLI reference](#cli-reference)
+4. [Browser dashboard](#browser-dashboard)
+5. [Container deployment](#container-deployment)
+6. [Language overview](#language-overview)
+7. [Connector model](#connector-model)
+8. [External adapters](#external-adapters)
+9. [Library API](#library-api)
+10. [Contributing](#contributing)
+11. [License](#license)
+
+---
+
+## Installation
+
+### npm (recommended)
+
+```sh
+npm install -g skillscript-runtime
+skillfile --version
+```
+
+This installs the `skillfile` binary globally. Requires Node.js ≥ 22.5 (the runtime uses `node:sqlite` and other features that landed in 22.5+).
+
+### From source
+
+```sh
+git clone https://github.com/sshwarts/skillscript-runtime.git
+cd skillscript-runtime
+pnpm install
+pnpm run build
+node dist/cli.js --help
+```
+
+The repo uses pnpm for reproducible installs. `pnpm run build` compiles TypeScript to `dist/` and copies dashboard assets into place.
+
+---
+
+## Quickstart: author and run a skill
+
+```sh
+# 1. Scaffold the config tree
+skillfile init
+
+# 2. Inspect the bundled hello example
+cat ~/.skillscript/examples/hello.skill.md
+
+# 3. Run it (no Ollama, no MCP, no external state required)
+skillfile run examples/hello.skill.md
+# → Hello, world!
+
+# 4. Override an input
+skillfile run hello --input WHO=Scott
+# → Hello, Scott!
+```
+
+A minimal `.skill.md` looks like:
+
+```skillscript
+# Skill: greet
+# Status: Draft
+# Vars: WHO=world
+
+greet:
+    ! Hello, $(WHO)!
+
+default: greet
+```
+
+Save that as `greet.skill.md` and run `skillfile run ./greet.skill.md`. The `!` op emits a message; the dispatcher walks the dependency DAG from `default:` backward.
+
+Lint as you go:
+
+```sh
+skillfile lint ./greet.skill.md
+```
+
+Compile to a prompt artifact (the form an agent consumes when it dispatches a skill mid-conversation):
+
+```sh
+skillfile compile ./greet.skill.md
+# Writes greet.skill.provenance.json sidecar with content hashes
+```
+
+---
+
+## CLI reference
+
+All 13 commands. Run `skillfile <command> --help` for per-command options + examples.
+
+| Command | Purpose |
+|---|---|
+| `init` | Scaffold `~/.skillscript/` tree + bundled example |
+| `run <path\|name>` | Compile + execute a skill end-to-end |
+| `compile <path\|name>` | Render the compiled artifact (no execution) |
+| `audit <provenance-path>` | Detect recompile-staleness via `.provenance.json` sidecar |
+| `lint <path\|name>` | Run static validation, print findings |
+| `list` | List available skills in the configured SkillStore |
+| `fires <skill>` | List recent trace records for a skill |
+| `diagram <path\|name>` | Emit mermaid graph of the skill's control flow |
+| `sign <path\|name>` | Content-hash sign the skill source (SHA-256) |
+| `verify <path\|name> <hash>` | Verify the skill matches a signature |
+| `replay <trace_id>` | Re-run a recorded trace mechanically |
+| `health` | Aggregate runtime metrics across all traces |
+| `dashboard` | Start the runtime host: scheduler + MCP server + browser dashboard SPA |
+
+> Trigger registration is handled through the MCP server exposed by `skillfile dashboard` (`register_trigger` / `unregister_trigger` / `list_triggers` tools). The v0.2.0 CLI register-trigger family was removed in v0.2.1 — those commands constructed throwaway in-memory schedulers and never fired.
+
+Environment variables:
+
+| Var | Default | Purpose |
+|---|---|---|
+| `SKILLSCRIPT_HOME` | `~/.skillscript` | Config + data root |
+| `OLLAMA_BASE_URL` | `http://localhost:11434` | Ollama endpoint for LocalModel dispatch |
+
+---
+
+## Browser dashboard
+
+The runtime ships with a browser dashboard for non-CLI operators. Five views: overview, skills, triggers, connectors, plus a skill detail drilldown. 30-second polling; write paths for status transitions and trigger CRUD. Localhost-only by default — no authentication in v1.
+
+```sh
+skillfile dashboard
+# → http://127.0.0.1:7878
+```
+
+Options:
+
+```sh
+skillfile dashboard --port 8080            # custom port
+skillfile dashboard --host 0.0.0.0         # bind all interfaces (container only)
+```
+
+The dashboard talks to the runtime via an MCP server contract (JSON-RPC 2.0 over HTTP at `/rpc`). Real MCP clients (Claude Desktop, Cursor, future tools) can consume the same endpoint — the SPA is one of several possible UIs over the same contract. **Eleven tools** today: `skill_list`, `skill_metadata`, `skill_status` (write), `list_triggers`, `register_trigger` (write), `unregister_trigger` (write), `health_metrics`, `runtime_capabilities`, `lint_skill`, `compile_skill`, `skill_write` (write). The last three (v0.2.3) close the over-the-wire authoring lifecycle — foreign clients can lint → compile → write → status → register_trigger end-to-end without filesystem access.
+
+---
+
+## Container deployment
+
+The repo ships a multi-stage Dockerfile + `docker-compose.yml`. The image bundles the runtime, CLI, and dashboard SPA in one Node process.
+
+```sh
+docker compose up --build              # default profile: dashboard
+# → http://127.0.0.1:7878
+```
+
+Profiles:
+
+```sh
+docker compose --profile tools run --rm tools lint my-skill.skill.md
+docker compose --profile ollama up     # adds Ollama for LocalModel
+```
+
+Persistent state (`SKILLSCRIPT_HOME=/data`) mounts as a volume so skills + traces survive restarts. The host port mapping (`127.0.0.1:7878:7878`) keeps the dashboard reachable only from localhost even though the container itself binds `0.0.0.0` internally.
+
+### Pulling from a registry
+
+Images publish to GitHub Container Registry:
+
+```sh
+docker pull ghcr.io/sshwarts/skillscript-runtime:latest
+# or pin to a specific version
+docker pull ghcr.io/sshwarts/skillscript-runtime:v0.2.4
+```
+
+Authentication (`gh auth login` then `gh auth token | docker login ghcr.io -u sshwarts --password-stdin`) is only required for pushes; pulls are public.
+
+---
+
+## Language overview
+
+A skill is markdown with structured headers and a body of named targets:
+
+```skillscript
+# Skill: weather-brief
+# Status: Approved
+# Vars: CITY=Asheville
+# Requires: user-var:home_location -> CITY (fallback: Asheville)
+# Triggers: cron: */30 * * * *
+
+fetch needs:
+    ~ memory-store.get key="weather:$(CITY|url)" -> CACHED
+
+forecast: fetch
+    if $(CACHED):
+        $set FORECAST = $(CACHED)
+    else:
+        > local-model.complete prompt="Brief weather for $(CITY)" -> FORECAST
+        ~ memory-store.set key="weather:$(CITY|url)" value=$(FORECAST)
+
+emit: forecast
+    ! Weather for $(CITY): $(FORECAST)
+
+default: emit
+```
+
+Eight typed operations (`!` emit, `?` ask, `??` ask-for-input, `$` set, `~` retrieve, `>` complete, `@` shell, `&` invoke-skill), three control-flow constructs (`if`/`elif`/`else`, `foreach`, `needs:`), and a small set of headers (`# Skill:`, `# Status:`, `# Vars:`, `# Requires:`, `# Triggers:`, `# Output:`, `# Timeout:`, `# OnError:`, `# Type:`).
+
+**Full canonical reference**: [`docs/language-reference.md`](./docs/language-reference.md) — syntax, ops, semantics, lifecycle, connectors, error handling, all 1500+ lines.
+
+---
+
+## Connector model
+
+The runtime depends on five pluggable connector contracts:
+
+| Contract | Purpose | Bundled reference impl |
+|---|---|---|
+| `SkillStore` | Persist + version + filter skills | `FilesystemSkillStore` (filesystem) |
+| `MemoryStore` | Cache + query memory data with TTL | `SqliteMemoryStore` (`node:sqlite`) |
+| `LocalModel` | Dispatch `>` and `~` ops to a local LLM | `OllamaLocalModel` (HTTP to Ollama) |
+| `McpConnector` | Dispatch `$` and `~` ops via MCP tools | `CallbackMcpConnector` (in-process) |
+| `AgentConnector` | Deliver to / wake a frontier agent (T7.1) | `NoOpAgentConnector` (warns + discards) |
+
+Wire your own impls through `Registry`:
+
+```typescript
+import { Registry } from "skillscript-runtime";
+import { MyRedisSkillStore } from "./my-adapter.js";
+
+const registry = new Registry();
+registry.registerSkillStore(new MyRedisSkillStore({ url: "redis://..." }));
+registry.registerLocalModel(new OllamaLocalModel());
+// ... use with execute() or Scheduler
+```
+
+The connector resolution cascade (`# Requires:` → static capability check → runtime dispatch) is described in detail in [`docs/ERD.md`](./docs/ERD.md) §3 and the [language reference](./docs/language-reference.md).
+
+---
+
+## External adapters
+
+The connector contracts are exported under `skillscript-runtime/connectors`:
+
+```typescript
+import type {
+  SkillStore, MemoryStore, LocalModel, McpConnector, AgentConnector,
+  StaticCapabilities, ManifestInfo,
+} from "skillscript-runtime/connectors";
+
+export class MyCloudMemoryStore implements MemoryStore {
+  staticCapabilities(): StaticCapabilities {
+    return { connector_type: "memory-store", features: { ttl: true, query: true } };
+  }
+  // ... implement get / set / delete / query / snapshot / manifestInfo
+}
+```
+
+Adapter packages can ship publicly (npm) or privately (internal registries). The runtime treats all adapters identically as long as they conform to the typed contract. The `skillscript-runtime/testing` entry point exports `SkillStoreConformance`, `MemoryStoreConformance`, `LocalModelConformance`, `McpConnectorConformance`, and `AgentConnectorConformance` — drop-in test suites that adapter authors run against their implementation to verify contract conformance before shipping.
+
+### AgentConnector — delivery to frontier agents
+
+Augmenting and Template skill outputs (`# Output: prompt-context: <agent>` and `# Output: template: <agent>`) deliver through `AgentConnector.deliver`. The contract surfaces three verbs (`list_agents`, `deliver`, `wake`) plus an optional `agent_status` probe. Substrate examples:
+
+| Substrate | `deliver` impl | `wake` impl |
+|---|---|---|
+| tmux session | `tmux send-keys` to a pane | `tmux send-keys` with wake prompt |
+| webhook | POST to `/augment` or `/template` endpoint | POST to `/wake` endpoint |
+| file-watch | write to `<path>/augment-<id>.txt` | write to `<path>/wake-<id>.txt` |
+| Slack thread | post to monitored thread | post + @mention |
+| IPC named pipe | write to delivery pipe | write to wake pipe |
+
+The bundled `NoOpAgentConnector` is the default — it logs a one-line warning and discards the payload, so the runtime starts cleanly when no agent substrate is wired. Production deployments wire a real impl through `Registry.registerAgentConnector()`.
+
+
+```typescript
+import { describe } from "vitest";
+import { SkillStoreConformance } from "skillscript-runtime/testing";
+import { MyCloudSkillStore } from "./my-cloud-skill-store.js";
+
+describe("MyCloudSkillStore", () => {
+  SkillStoreConformance(() => new MyCloudSkillStore({ /* fixture config */ }));
+});
+```
+
+---
+
+## Library API
+
+Embedders consume the runtime as a library rather than via CLI:
+
+```typescript
+import { compile, execute, lint, Registry, Scheduler } from "skillscript-runtime";
+import { FilesystemSkillStore } from "skillscript-runtime/connectors";
+import { FilesystemTraceStore } from "skillscript-runtime/trace";
+
+const skillStore = new FilesystemSkillStore("./skills");
+const traceStore = new FilesystemTraceStore("./traces");
+const registry = new Registry();
+registry.registerSkillStore(skillStore);
+
+const scheduler = new Scheduler({ registry, skillStore, traceStore });
+const result = await scheduler.dispatchSkill("hello", { WHO: "Scott" });
+console.log(result.emissions);
+```
+
+Subpath exports for adapter authors and embedders who want narrower imports:
+
+| Path | Content |
+|---|---|
+| `skillscript-runtime` | Main barrel — everything |
+| `skillscript-runtime/connectors` | Connector contracts + Registry + bundled impls |
+| `skillscript-runtime/errors` | `OpError` + subclasses, `LintFailureError`, `ConnectorError` |
+| `skillscript-runtime/runtime` | `execute()` + helpers |
+| `skillscript-runtime/trace` | `TraceStore`, `FilesystemTraceStore`, sampling |
+| `skillscript-runtime/metrics` | `healthMetrics()` aggregator |
+| `skillscript-runtime/scheduler` | `Scheduler` + `TriggerRegistration` |
+| `skillscript-runtime/mcp-server` | `McpServer` + JSON-RPC types |
+| `skillscript-runtime/testing` | Contract conformance suites |
+
+---
+
+## Contributing
+
+The codebase prioritizes a small, agent-modifiable core. The narrow runtime + compiler + lint + connectors set lives under 5K LOC; CLI, dashboard, MCP server, and observability surfaces are tracked separately. See [`ARCHITECTURE.md`](./ARCHITECTURE.md) for a file-by-file map and [`docs/ERD.md`](./docs/ERD.md) for the engineering requirements.
+
+Pre-flight checks:
+
+```sh
+pnpm run typecheck
+pnpm run loc-check       # enforces ERD §1 LOC ceiling
+pnpm test                # 473+ tests
+```
+
+Full `CONTRIBUTING.md` lands in v1.x.
+
+---
+
+## License
+
+MIT. See [`LICENSE`](./LICENSE).

package/dist/audit.d.ts

@@ -0,0 +1,33 @@
+import type { SkillStore } from "./connectors/types.js";
+import type { ProvenanceBlock } from "./provenance.js";
+export type AuditRule = "stale-data-skill" | "missing-data-skill";
+export interface AuditFinding {
+    rule: AuditRule;
+    severity: "warning" | "error";
+    skill_name: string;
+    recorded_content_hash: string;
+    /** Absent when the skill couldn't be found in the store. */
+    current_content_hash?: string;
+    message: string;
+}
+export interface AuditResult {
+    audited_at: string;
+    /** The provenance block that was audited (echoed for cross-reference). */
+    provenance: ProvenanceBlock;
+    findings: AuditFinding[];
+    /** True if any finding has severity error OR any stale-data-skill. */
+    is_stale: boolean;
+}
+/**
+ * Audit a provenance block against current SkillStore state. Returns a
+ * structured report; never throws on missing/stale skills — those become
+ * findings, not exceptions. Throws only on unexpected SkillStore errors
+ * (e.g., substrate down).
+ */
+export declare function audit(provenance: ProvenanceBlock, store: SkillStore): Promise<AuditResult>;
+/**
+ * Pretty-print an AuditResult for human display. JSON output is the canonical
+ * form; this is a thin formatter for CLI/dashboard surfaces.
+ */
+export declare function formatAuditResult(result: AuditResult): string;
+//# sourceMappingURL=audit.d.ts.map

package/dist/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,MAAM,MAAM,SAAS,GAAG,kBAAkB,GAAG,oBAAoB,CAAC;AAElE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,4DAA4D;IAC5D,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,UAAU,EAAE,eAAe,CAAC;IAC5B,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,sEAAsE;IACtE,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAsB,KAAK,CACzB,UAAU,EAAE,eAAe,EAC3B,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC,WAAW,CAAC,CAyCtB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAY7D"}

package/dist/audit.js

@@ -0,0 +1,76 @@
+// Recompile-staleness detection. Reads a previously-recorded provenance
+// block and compares its `data_skills_inlined[].content_hash` to the
+// current content_hash of each referenced skill via the SkillStore.
+// Surfaces stale entries (source changed since compile) and missing ones
+// (referenced skill deleted/renamed).
+//
+// Agent-first JSON output: every audit produces a structured `AuditResult`
+// with typed findings keyed by rule ID. Human-readable display is a
+// pretty-printer over the same shape.
+import { SkillNotFoundError } from "./errors.js";
+/**
+ * Audit a provenance block against current SkillStore state. Returns a
+ * structured report; never throws on missing/stale skills — those become
+ * findings, not exceptions. Throws only on unexpected SkillStore errors
+ * (e.g., substrate down).
+ */
+export async function audit(provenance, store) {
+    const findings = [];
+    for (const recorded of provenance.data_skills_inlined) {
+        try {
+            const meta = await store.metadata(recorded.name);
+            if (meta.content_hash !== recorded.content_hash) {
+                findings.push({
+                    rule: "stale-data-skill",
+                    severity: "warning",
+                    skill_name: recorded.name,
+                    recorded_content_hash: recorded.content_hash,
+                    current_content_hash: meta.content_hash,
+                    message: `Data-skill '${recorded.name}' has been updated since this artifact ` +
+                        `was compiled (recorded ${recorded.content_hash.slice(0, 12)}..., ` +
+                        `current ${meta.content_hash.slice(0, 12)}...). Recompile to pick up the new content.`,
+                });
+            }
+        }
+        catch (err) {
+            if (err instanceof SkillNotFoundError) {
+                findings.push({
+                    rule: "missing-data-skill",
+                    severity: "error",
+                    skill_name: recorded.name,
+                    recorded_content_hash: recorded.content_hash,
+                    message: `Data-skill '${recorded.name}' (recorded ${recorded.content_hash.slice(0, 12)}...) ` +
+                        `is no longer present in the SkillStore. The compiled artifact references ` +
+                        `content that can no longer be re-derived.`,
+                });
+                continue;
+            }
+            throw err;
+        }
+    }
+    return {
+        audited_at: new Date().toISOString(),
+        provenance,
+        findings,
+        is_stale: findings.length > 0,
+    };
+}
+/**
+ * Pretty-print an AuditResult for human display. JSON output is the canonical
+ * form; this is a thin formatter for CLI/dashboard surfaces.
+ */
+export function formatAuditResult(result) {
+    const lines = [];
+    const sourceName = result.provenance.source_skill.name ?? "(unnamed)";
+    lines.push(`Audit of '${sourceName}' (${result.findings.length} finding${result.findings.length === 1 ? "" : "s"})`);
+    if (result.findings.length === 0) {
+        lines.push(`  OK: no stale or missing references. ${result.provenance.data_skills_inlined.length} data-skill(s) audited.`);
+    }
+    else {
+        for (const f of result.findings) {
+            lines.push(`  [${f.severity}] ${f.rule} (${f.skill_name}): ${f.message}`);
+        }
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=audit.js.map

package/dist/audit.js.map

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

package/dist/bootstrap.d.ts

@@ -0,0 +1,69 @@
+import { Registry } from "./connectors/registry.js";
+import { FilesystemSkillStore } from "./connectors/skill-store.js";
+import { FilesystemTraceStore } from "./trace.js";
+import { Scheduler } from "./scheduler.js";
+import type { TraceConfig } from "./trace.js";
+import { McpServer } from "./mcp-server.js";
+export interface BootstrapOpts {
+    skillsDir: string;
+    traceDir: string;
+    /** When set + existing, register `SqliteMemoryStore` as primary memory_store. */
+    memoryDbPath?: string;
+    /** Override `OLLAMA_BASE_URL` env default. */
+    ollamaBaseUrl?: string;
+    /** Scheduler poll interval (default 30s). */
+    pollIntervalSeconds?: number;
+    /** Forwarded to scheduler/runtime. Default false. */
+    enableUnsafeShell?: boolean;
+    /** When set, scheduler-driven fires record traces via the result's traceStore. */
+    trace?: TraceConfig;
+}
+export interface BootstrapResult {
+    registry: Registry;
+    scheduler: Scheduler;
+    mcpServer: McpServer;
+    skillStore: FilesystemSkillStore;
+    traceStore: FilesystemTraceStore;
+    /** Read back so runtime_capabilities can surface the active mode. */
+    enableUnsafeShell: boolean;
+}
+export interface DefaultRegistryOpts {
+    skillsDir: string;
+    memoryDbPath?: string;
+    ollamaBaseUrl?: string;
+}
+/**
+ * Build the default connector registry: primary SkillStore + primary
+ * MemoryStore (if the db file/directory exists) + three named LocalModels
+ * pointed at Ollama. Used by both `bootstrap()` (long-lived host) and the
+ * `skillfile run` one-shot path so both surfaces wire the same defaults.
+ */
+export declare function defaultRegistry(opts: DefaultRegistryOpts): {
+    registry: Registry;
+    skillStore: FilesystemSkillStore;
+};
+/**
+ * Construct the long-lived runtime surface. Caller is expected to:
+ *   1. Optionally call `wireDeclarativeTriggers(result)` to register
+ *      `# Triggers:` headers from already-Approved skills.
+ *   2. Call `result.scheduler.start()` to arm the tick loop.
+ *   3. Mount any additional surfaces (e.g., `DashboardServer`) on top of
+ *      `result.mcpServer`.
+ */
+export declare function bootstrap(opts: BootstrapOpts): BootstrapResult;
+/**
+ * Walk the SkillStore for Approved skills with declared `# Triggers:`
+ * headers and register each into the scheduler. Returns the number of
+ * triggers registered. Skips skills whose body fails to parse rather
+ * than crashing boot — operators can fix the offender and restart.
+ *
+ * Implementation note: the SkillStore's `query()` returns SkillMeta with
+ * an *optional* `triggers` field; not all impls populate it (the bundled
+ * FilesystemSkillStore does not). This helper loads + parses each skill
+ * source directly so it works against any SkillStore.
+ */
+export declare function wireDeclarativeTriggers(result: Pick<BootstrapResult, "scheduler" | "skillStore">, log?: (msg: string) => void): Promise<{
+    registered: number;
+    skipped: number;
+}>;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAGnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,SAAS,EAAgC,MAAM,gBAAgB,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAI5C,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,kFAAkF;IAClF,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,QAAQ,CAAC;IACnB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,SAAS,CAAC;IACrB,UAAU,EAAE,oBAAoB,CAAC;IACjC,UAAU,EAAE,oBAAoB,CAAC;IACjC,qEAAqE;IACrE,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAMD,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,mBAAmB,GAAG;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,UAAU,EAAE,oBAAoB,CAAA;CAAE,CAenH;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,eAAe,CAiB9D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,GAAG,YAAY,CAAC,EACzD,GAAG,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAA4D,GACjF,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAkClD"}