skillscript-runtime 0.9.9 → 0.13.2

package/examples/connectors/SkillStoreTemplate/README.md

@@ -0,0 +1,143 @@
+# SkillStoreTemplate — fork-me skeleton
+
+A skeleton `SkillStore` implementation for adopters writing their own. Not runnable; every method throws a `TODO` error. Copy this directory, rename, fill in the substrate-specific work.
+
+Use this when you want skillscript skills backed by:
+- A database the bundled impls don't cover (Postgres, MySQL, MongoDB, etc.)
+- A vector store (Pinecone, Weaviate, Qdrant)
+- A memory system (AMP, hosted memory API)
+- An HTTP CRUD service
+- Anything else with a query/write interface
+
+## The three legs
+
+```
+SkillStore (choose which connector)
+   ├── FilesystemSkillStore (bundled, FS-backed — src/connectors/skill-store.ts)
+   ├── SqliteSkillStore     (bundled, DB-backed   — src/connectors/sqlite-skill-store.ts)
+   └── Your fork from this template
+```
+
+The runtime is substrate-agnostic. Skills don't know which backend they're stored against — the contract is the `SkillStore` interface, and any class implementing it works.
+
+## Forking workflow
+
+```bash
+cp -r examples/connectors/SkillStoreTemplate examples/connectors/MyDatabaseSkillStore
+```
+
+1. **Rename the class.** Convention: `<Substrate>SkillStore` (e.g., `PostgresSkillStore`, `PineconeSkillStore`, `AmpSkillStore`).
+2. **Define your config interface.** Edit `SkillStoreTemplateConfig` to declare what your substrate needs (connection URL, API key, vault name, etc.).
+3. **Implement each method.** Eight methods + `staticCapabilities()`. Each has a TODO comment in the skeleton explaining what to do.
+4. **Update `staticCapabilities()`** to declare what your impl actually supports. The runtime + lint consult these flags before exercising features.
+5. **Wire from your adopter bootstrap:**
+
+   ```typescript
+   import { Registry } from "skillscript-runtime";
+   import { MyDatabaseSkillStore } from "./MyDatabaseSkillStore.js";
+
+   const registry = new Registry();
+   registry.registerSkillStore("primary", new MyDatabaseSkillStore({
+     // your config
+   }));
+   ```
+
+6. **Validate via the conformance suite:**
+
+   ```typescript
+   import { describe, it } from "vitest";
+   import { SkillStoreConformance } from "skillscript-runtime/testing";
+   import { MyDatabaseSkillStore } from "./MyDatabaseSkillStore.js";
+
+   describe("MyDatabaseSkillStore conformance", () => {
+     const tests = SkillStoreConformance.buildTests({
+       build: () => new MyDatabaseSkillStore({ /* test config */ }),
+       ctor: MyDatabaseSkillStore,
+     });
+     for (const t of tests) it(`[${t.category}] ${t.name}`, t.run);
+   });
+   ```
+
+   The conformance suite verifies your impl honors the contract: method presence, return-type shape, error-class throw conditions, capability flag self-consistency. If it passes, the runtime treats your impl interchangeably with the bundled defaults.
+
+## Reference implementations
+
+When in doubt about semantics, read the bundled impls:
+
+- **`src/connectors/skill-store.ts`** — `FilesystemSkillStore`, filesystem-backed. Skills as `.skill.md` files; version history in a sidecar `.versions.jsonl`. Simplest reference.
+- **`src/connectors/sqlite-skill-store.ts`** — `SqliteSkillStore`, SQLite-backed. Two-table schema, transactional status transitions, WAL, JSON-extract tag filter. Closest reference for any database-backed fork.
+
+Both implement the same `SkillStore` interface; the differences are in the substrate-specific code.
+
+## Approval token semantics
+
+The runtime ships an approval-token mechanism so headless MCP-only adopters get a runnable `Approved` state without a dashboard round-trip. When you `store()` or `update_status()` a body declaring `# Status: Approved`, the impl should stamp `# Status: Approved v1:<hex>` automatically.
+
+Helpers from `src/approval.ts`:
+
+```typescript
+import { extractStatusFromBody, stampApprovalToken } from "skillscript-runtime";
+
+// In store():
+const extracted = extractStatusFromBody(source);
+const body = extracted?.status === "Approved" ? stampApprovalToken(source) : source;
+
+// In update_status() — when transitioning TO Approved:
+const updated = status === "Approved"
+  ? stampApprovalToken(rewriteStatusHeader(source, "Approved"))
+  : rewriteStatusHeader(source, status);
+```
+
+Both bundled impls follow this pattern; your fork should too unless you're explicitly disabling approval tokens.
+
+## Error classes to throw
+
+From `src/errors.ts`:
+
+- **`SkillNotFoundError(name, implementationName)`** — `load()` / `metadata()` / `versions()` / `update_status()` / `delete()` on a missing skill
+- **`VersionNotFoundError(name, version, implementationName)`** — `load(name, version)` where `name` exists but `version` doesn't
+- **`StorageConflictError(name, reason, implementationName)`** — `store()` rejects (e.g., name violates substrate constraints)
+
+The `implementationName` is your class name — let cold authors trace errors back to the substrate.
+
+## Schema-level decisions
+
+Document your substrate's particulars in a README alongside your fork:
+
+- **Versioning shape** — full body bytes per version (rich audit), or just hash + status (lightweight)?
+- **Delete semantics** — hard-cascade (removes versions) or preserve (audit-grade retention)?
+- **Concurrency model** — single-writer, multi-reader (e.g., WAL), or fully concurrent?
+- **Tag filter** — indexed lookup, table scan, or unsupported?
+
+These trade-offs are substrate-side; the contract just specifies what each method does, not how.
+
+## Wiring against the CLI / dashboard
+
+Runtime hosts (MCP server + web dashboard) honor whichever SkillStore impl your registry has. To make your fork visible through `skillfile dashboard`:
+
+- Write a custom bootstrap that constructs the runtime with your SkillStore (see `src/bootstrap.ts` for the reference shape + `docs/adopter-playbook.md` for the pattern)
+- OR (planned future) declare in `~/.skillscript/connectors.json`:
+
+  ```json
+  {
+    "substrate": {
+      "skill_store": {
+        "type": "custom",
+        "module": "./my-database-skill-store.js",
+        "export": "MyDatabaseSkillStore",
+        "config": { "postgresUrl": "${POSTGRES_URL}" }
+      }
+    }
+  }
+  ```
+
+  Current limitation: sync `bootstrap()` can't dynamic-import, so the `custom` form surfaces an error today. Programmatic bootstrap is the path until async-bootstrap support lands.
+
+The bundled CLI authoring commands (`skillfile compile`, `skillfile lint`, `skillfile audit`, `skillfile list`) stay filesystem-pinned by design — they're the FS-authoring loop. Adopter-substrate skills are authored via the dashboard UI or the `skill_write` MCP tool.
+
+## Further reading
+
+- **[`docs/configuration.md`](../../../docs/configuration.md)** — substrate selection via `connectors.json`
+- **[`docs/sqlite-skill-store.md`](../../../docs/sqlite-skill-store.md)** — the bundled SqliteSkillStore's schema + semantics + forking checklist
+- **`src/connectors/types.ts`** — authoritative `SkillStore` interface spec (lines 192-208)
+- **`src/testing/conformance.ts`** — the conformance test suite

package/examples/connectors/SkillStoreTemplate/SkillStoreTemplate.ts

@@ -0,0 +1,199 @@
+/**
+ * SkillStoreTemplate — fork-me skeleton for writing your own SkillStore impl.
+ *
+ * This is NOT a runnable connector. Every method throws a "TODO" error. The
+ * purpose is to surface the SkillStore contract surface in a copy-and-customize
+ * shape so adopters writing Postgres-, MySQL-, MongoDB-, AMP-, or
+ * vector-DB-backed SkillStores have a starting skeleton.
+ *
+ * Forking workflow:
+ *   1. Copy this directory into your codebase (`cp -r examples/connectors/SkillStoreTemplate examples/connectors/MyDatabaseSkillStore`)
+ *   2. Rename the class — typically `<Substrate>SkillStore` (e.g., `PostgresSkillStore`)
+ *   3. Implement each method against your substrate's API
+ *   4. Update `staticCapabilities()` to declare what your impl actually supports
+ *   5. Register from your adopter bootstrap:
+ *        `registry.registerSkillStore("primary", new MyDatabaseSkillStore({ ... }))`
+ *   6. Validate via the conformance suite:
+ *        `SkillStoreConformance.buildTests({ build: () => new MyDatabaseSkillStore(...), ctor: MyDatabaseSkillStore })`
+ *
+ * See `src/connectors/sqlite-skill-store.ts` for a working reference
+ * implementation against SQLite + `node:sqlite`. See `src/connectors/skill-store.ts`
+ * for the bundled filesystem default. The full contract spec lives in
+ * `src/connectors/types.ts` (`SkillStore` interface, lines 192-208) and
+ * `docs/sqlite-skill-store.md` for schema + semantics depth.
+ *
+ * Runtime hosts (MCP server + web dashboard) honor whichever SkillStore impl
+ * you register via the registry, so once your fork passes the conformance
+ * suite the entire skillscript surface (skill_write / skill_list /
+ * execute_skill / etc.) reads + writes against your substrate.
+ */
+
+import type {
+  SkillStore,
+  SkillSource,
+  SkillMeta,
+  SkillStatus,
+  SkillFilter,
+  VersionInfo,
+  SkillStoreCapabilities,
+  ManifestInfo,
+} from "../../../src/connectors/types.js";
+
+/** Replace with your substrate's connection config (host, dbName, credentials, etc.). */
+export interface SkillStoreTemplateConfig {
+  // TODO — declare the fields your substrate needs to connect.
+  // Examples:
+  //   postgresUrl?: string;
+  //   pineconeApiKey?: string;
+  //   ampVault?: string;
+  exampleConfigField?: string;
+}
+
+export class SkillStoreTemplate implements SkillStore {
+  /**
+   * Declare what your impl supports. The runtime + lint consult these flags
+   * before exercising features. Set conservatively — overclaiming triggers
+   * cryptic downstream failures; underclaiming hides usable features.
+   */
+  static staticCapabilities(): SkillStoreCapabilities {
+    return {
+      connector_type: "skill_store",
+      implementation: "SkillStoreTemplate", // ← rename to your class name
+      contract_version: "1.0.0",
+      features: {
+        // TODO — set each flag based on what your substrate can actually do.
+        supports_writes: false,               // can you persist new skills?
+        supports_versioning: false,           // can you return historical bytes via load(name, version)?
+        supports_tag_filter: false,           // can query() filter by tag?
+        supports_audit_trail: false,          // does update_status populate previous_status?
+        supports_atomic_status_transitions: false, // can UPDATE + INSERT versions be transactional?
+      },
+    };
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  constructor(_config: SkillStoreTemplateConfig) {
+    // TODO — establish your substrate connection. For SQL: open the database
+    // + run schema migrations. For HTTP: store the base URL + auth headers.
+    // For AMP/Pinecone: cache the SDK client.
+    throw new Error("SkillStoreTemplate is a fork-me skeleton; replace with your impl.");
+  }
+
+  /**
+   * Capability snapshot for `runtime_capabilities` discovery. Return free-form
+   * substrate-specific metadata (kind, version, supported modes, etc.).
+   */
+  async manifest(): Promise<ManifestInfo<"skill_store">> {
+    // TODO — return a snapshot of your substrate's capabilities.
+    throw new Error("TODO: manifest() — return substrate-specific capability snapshot.");
+  }
+
+  /**
+   * Read the skill body bytes + metadata. If `version` is supplied, return
+   * historical bytes (or throw `VersionNotFoundError` if the version is
+   * unknown). If the skill doesn't exist at all, throw `SkillNotFoundError`.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async load(_name: string, _version?: string): Promise<SkillSource> {
+    // TODO — fetch the skill record from your substrate.
+    //   - Return SkillSource { name, version, content_hash, source, metadata }
+    //   - Throw SkillNotFoundError if name doesn't exist
+    //   - Throw VersionNotFoundError if version is supplied but unknown
+    throw new Error("TODO: load() — fetch skill source by name (+ optional version).");
+  }
+
+  /**
+   * List skill metadata. Apply the filter where your substrate supports it;
+   * fall back to client-side filtering for unsupported fields. Empty result
+   * is fine; never throw "not found" — return [].
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async query(_filter?: SkillFilter): Promise<SkillMeta[]> {
+    // TODO — query your substrate for skill metadata.
+    //   - Apply filter.status / filter.tag / filter.author / etc. as supported
+    //   - Honor filter.limit + filter.offset
+    //   - Never throw on no matches; return []
+    throw new Error("TODO: query() — return SkillMeta[] honoring the filter.");
+  }
+
+  /**
+   * Read skill metadata without the body bytes. Equivalent to `load()` but
+   * skips the `source` field — useful for listings + introspection where
+   * the body isn't needed.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async metadata(_name: string): Promise<SkillMeta> {
+    // TODO — return SkillMeta for `name`. Throw SkillNotFoundError if missing.
+    throw new Error("TODO: metadata() — return SkillMeta without body bytes.");
+  }
+
+  /**
+   * Return version history (chronological). Each entry has `version` +
+   * `content_hash` + `status` + `changed_at` + optional `previous_status`
+   * (audit trail). Throws `SkillNotFoundError` if the skill doesn't exist.
+   *
+   * If your substrate doesn't track versions, return a single-element array
+   * with the current state (and set `supports_versioning: false`).
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async versions(_name: string): Promise<VersionInfo[]> {
+    // TODO — return version chain. SQL substrates: SELECT FROM skill_versions
+    // ORDER BY changed_at. MemoryStore-style: query memories with the right tag.
+    throw new Error("TODO: versions() — return VersionInfo[] chronologically.");
+  }
+
+  /**
+   * Persist a skill (create or update). Compute content_hash from the source;
+   * append a new version row; update the current-version pointer. Returns
+   * `VersionInfo` for the new version.
+   *
+   * For atomicity, wrap your substrate writes in a transaction (or equivalent)
+   * so the version row is never created without the current-version pointer
+   * updating, and vice versa.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async store(_name: string, _source: string, _metadata?: Partial<SkillMeta>): Promise<VersionInfo> {
+    // TODO — persist the skill source bytes + metadata.
+    //   - Compute content_hash (SHA-256 of source) + version (short hash)
+    //   - Auto-stamp approval token if body declares Approved (see
+    //     src/approval.ts → stampApprovalToken / extractStatusFromBody)
+    //   - Write to your substrate atomically
+    //   - Return VersionInfo
+    throw new Error("TODO: store() — persist skill source + metadata.");
+  }
+
+  /**
+   * Hard-delete the skill (substrate-only — referential integrity is the
+   * runtime's concern). Whether to cascade version history is your substrate
+   * choice; the bundled SqliteSkillStore cascades (rationale in
+   * `docs/sqlite-skill-store.md`).
+   *
+   * Throws `SkillNotFoundError` if `name` doesn't exist (so adopters get a
+   * clear error rather than a silent no-op).
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async delete(_name: string): Promise<void> {
+    // TODO — remove the skill from your substrate. Decide cascade vs preserve
+    // history per your compliance needs. Throw SkillNotFoundError if missing.
+    throw new Error("TODO: delete() — remove skill (+ optionally history).");
+  }
+
+  /**
+   * Transition a skill's status (Draft / Approved / Disabled). Updates the
+   * current state + appends a `skill_versions` row with `previous_status`
+   * populated (audit trail). Wrap in a transaction for atomicity.
+   *
+   * Approved transitions should stamp the approval token (see
+   * `src/approval.ts`); transitions away from Approved should strip it.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async update_status(_name: string, _status: SkillStatus): Promise<VersionInfo> {
+    // TODO — atomically update status + append audit row.
+    //   - Load current status (for previous_status field)
+    //   - Apply stampApprovalToken if status=Approved
+    //   - Strip token if transitioning to Draft/Disabled
+    //   - UPDATE skills SET status, INSERT skill_versions (transaction)
+    //   - Return VersionInfo with previous_status populated
+    throw new Error("TODO: update_status() — atomic status transition + audit row.");
+  }
+}

package/examples/{hello.skill.provenance.json → skillscripts/hello.skill.provenance.json}

@@ -2,7 +2,7 @@
   "provenance_version": "1.0",
   "language_version": "1.0",
   "compiler_version": "0.1.0-dev",
-  "compiled_at": "2026-05-28T16:02:39.753Z",
+  "compiled_at": "2026-05-29T18:50:40.018Z",
   "source_skill": {
     "name": "hello"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillscript-runtime",
-  "version": "0.9.9",
+  "version": "0.13.2",
   "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/config.toml

@@ -16,18 +16,14 @@ plugins_dir = "~/.skillscript/plugins"
 # security-conscious deployments invert this to ["packages"] only.
 resolution_order = ["filesystem", "packages"]
 
-[local_model.default]
-# Bundled-default LocalModel: Ollama gemma2:9b at localhost.
-kind = "ollama"
-base_url = "http://localhost:11434"
-model_tag = "gemma2:9b"
-timeout_ms = 60000
-
-[local_model.qwen]
-kind = "ollama"
-base_url = "http://localhost:11434"
-model_tag = "qwen2.5:7b"
-timeout_ms = 60000
+# LocalModel wiring lives in `connectors.json` under `substrate.local_model`,
+# NOT here. v0.10+ moved substrate selection out of this file. Example:
+#   {
+#     "substrate": {
+#       "local_model": { "type": "ollama", "config": { "defaultModelTag": "gemma2:9b" } }
+#     }
+#   }
+# See docs/configuration.md.
 
 [runtime]
 # `@@` opt-in unsafe shell. Disabled by default. v1 spec gates this behind

package/scaffold/connectors.json

@@ -1,9 +1,37 @@
 {
-  "_comment": "Per-host connector wiring. Copied to ~/.skillscript/connectors.json by `skillfile init`. Each top-level key is a connector instance name referenced via `$ name args` in skill source. Pick names that read well at your call sites (e.g. `llm`, `memory`, `youtrack`, `github`).",
+  "_comment": "Per-host connector wiring. Copied to ~/.skillscript/connectors.json by `skillfile init`. The top-level `substrate` key selects singleton substrate connectors (SkillStore, MemoryStore, LocalModel). All other top-level keys define named MCP connector instances referenced via `$ name args` in skill source.",
 
-  "_comment_substrate": "v0.7.0 substrate framing: language-level dispatch is via `$ <connector_name>`. Wire whatever substrate you want under whatever name reads well. Tradita's deployment is separate from this scaffold; ship your own wiring here.",
+  "_comment_substrate": "Substrate selection — runtime hosts (MCP server + web dashboard) honor whatever you configure here. The bundled CLI authoring commands (`skillfile compile`, `skillfile lint`, `skillfile audit`, `skillfile list`) stay filesystem-pinned regardless — they're the FS-authoring loop. Three legs: bundled filesystem, bundled sqlite, adopter-custom (write your own SkillStore impl).",
 
-  "_comment_classes": "v0.4.0+ closed-set class registry. Available: `RemoteMcpConnector` (stdio-bridged remote MCP). Use `runtime_capabilities({include:['mcpConnectorClasses']})` to introspect the runtime's available class set. v0.7.2 plans to ship `LocalModelMcpConnector` + `MemoryStoreMcpConnector` bridges so `$ llm` / `$ memory` work canonically.",
+  "_comment_substrate_forms": "Each substrate slot accepts: (a) bare string for built-in types — \"filesystem\", \"sqlite\", \"ollama\"; (b) null to explicitly disable; (c) object form `{type, config}` to override defaults; (d) object form `{type:\"custom\", module, export, config}` for adopter-custom impls (requires programmatic bootstrap; sync `bootstrap()` doesn't dynamic-import).",
+
+  "substrate": {
+    "skill_store": "filesystem",
+    "memory_store": "sqlite",
+    "local_model": null,
+
+    "_example_sqlite_skills": "Uncomment to switch skill storage to SQLite. Adopter-portable; persists between restarts. dbPath defaults to <skillsDir>/skills.db.",
+    "_example_sqlite_skills_object": {
+      "type": "sqlite",
+      "config": { "dbPath": "/var/skillscript/skills.db" }
+    },
+
+    "_example_ollama": "Uncomment to wire OllamaLocalModel as the primary LocalModel. Default baseUrl is OLLAMA_BASE_URL env or http://localhost:11434.",
+    "_example_ollama_object": {
+      "type": "ollama",
+      "config": { "baseUrl": "http://gpu-host:11434", "defaultModelTag": "gemma2:9b" }
+    },
+
+    "_example_custom": "Adopter-custom impl. Write `class FooSkillStore implements SkillStore { ... }` then reference it here. NOTE — this form requires a programmatic bootstrap (sync `bootstrap()` can't dynamic-import). Wire via your own bootstrap script today; declarative custom config is a planned follow-up.",
+    "_example_custom_object": {
+      "type": "custom",
+      "module": "./my-amp-skill-store.js",
+      "export": "AmpSkillStore",
+      "config": { "vault": "team" }
+    }
+  },
+
+  "_comment_classes": "Closed-set class registry for MCP connectors. Available: `RemoteMcpConnector` (stdio-bridged remote MCP). Use `runtime_capabilities({include:['mcpConnectorClasses']})` to introspect the available class set. The `LocalModelMcpConnector` + `MemoryStoreMcpConnector` bridges (for `$ llm` / `$ memory` canonical dispatch) auto-wire when their substrates are configured above.",
 
   "_comment_security": "This file is secret-bearing when filled with real credentials. The repo's `.gitignore` excludes `connectors.json` (the live copy) but tracks `connectors.json.example`. Prefer `${VAR}` substitution over in-file literals for deployments.",