skillscript-runtime 0.9.9 → 0.13.2

package/examples/README.md

@@ -1,18 +1,18 @@
 # 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).
+Curated production-quality skills demonstrating distinct language patterns. The `.skill.md` files live in [`skillscripts/`](./skillscripts/); each compiles + lints clean and can be run directly via `skillfile run examples/skillscripts/<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 |
+| [`hello.skill.md`](./skillscripts/hello.skill.md) | Three-command first run; `! emit`; default target; `# Vars:` declared inputs |
+| [`morning-brief.skill.md`](./skillscripts/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`](./skillscripts/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`](./skillscripts/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`](./skillscripts/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`](./skillscripts/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`](./skillscripts/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
 
@@ -31,20 +31,20 @@ Skills that talk to MCP tools (like `calendar.list_events`) need that tool wired
 
 ```sh
 # Cold install — no Ollama, no MCP, no external state
-skillfile run examples/hello.skill.md
+skillfile run examples/skillscripts/hello.skill.md
 
 # With overrides
-skillfile run examples/hello.skill.md --input WHO=Scott
+skillfile run examples/skillscripts/hello.skill.md --input WHO=Scott
 
 # Preview the compiled artifact without execution
-skillfile compile examples/hello.skill.md
+skillfile compile examples/skillscripts/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
+skillfile run examples/skillscripts/morning-brief.skill.md --mechanical
 
 # Render the control-flow graph
-skillfile diagram examples/cut-release-tag.skill.md
+skillfile diagram examples/skillscripts/cut-release-tag.skill.md
 ```
 
 ## Programmatic example

package/examples/connectors/LocalModelTemplate/LocalModelTemplate.ts

@@ -0,0 +1,138 @@
+/**
+ * LocalModelTemplate — fork-me skeleton for writing your own LocalModel impl.
+ *
+ * This is NOT a runnable connector. Every method throws a "TODO" error.
+ * Adopters writing OpenAI-compat / Anthropic-compat / vLLM / TGI / SGLang /
+ * hosted-LLM / any-other LocalModel substrate fork this directory.
+ *
+ * The bundled `OllamaLocalModel` (in `src/connectors/local-model.ts`) is
+ * Ollama-specific. When that doesn't fit, fork from here.
+ *
+ * Forking workflow:
+ *   1. Copy this directory: `cp -r examples/connectors/LocalModelTemplate examples/connectors/MyLocalModel`
+ *   2. Rename the class — typically `<Substrate>LocalModel` (e.g., `OpenAICompatLocalModel`, `AnthropicLocalModel`, `VllmLocalModel`)
+ *   3. Implement `run()` against your transport
+ *   4. Implement `manifest()` returning substrate metadata
+ *   5. Update `staticCapabilities()` to declare what your impl supports
+ *   6. Register from your adopter bootstrap:
+ *        `registry.registerLocalModel("default", new MyLocalModel({ ... }))`
+ *   7. Validate via the conformance suite:
+ *        `LocalModelConformance.buildTests({ build: () => new MyLocalModel(...), ctor: MyLocalModel })`
+ *
+ * See `src/connectors/local-model.ts` (`OllamaLocalModel`) for a working
+ * reference implementation against the Ollama HTTP API. The full contract
+ * spec lives in `src/connectors/types.ts` (`LocalModel` interface).
+ *
+ * Runtime hosts (MCP server + web dashboard) honor whichever LocalModel impl
+ * you register. The auto-wired `$ llm` MCP bridge wraps your impl
+ * transparently — once registered, `$ llm prompt="..."` dispatches through
+ * your fork without any additional wiring.
+ *
+ * **Note on declarative wiring**: LocalModel is intrinsically *singleton* per
+ * deployment (one default per runtime), unlike McpConnector which is
+ * multi-instance. There's no `registerLocalModelClass()` equivalent of
+ * `registerConnectorClass()` — adopters wire their LocalModel
+ * programmatically via `registry.registerLocalModel()` from their bootstrap.
+ * Declarative custom-LocalModel via `connectors.json` substrate `{type:
+ * "custom", module, export, config}` form is deferred until async-bootstrap
+ * support lands (cross-cutting limitation across all three substrate slots).
+ */
+
+import type {
+  LocalModel,
+  LocalModelCapabilities,
+  ManifestInfo,
+} from "../../../src/connectors/types.js";
+
+/** Replace with your substrate's connection config (endpoint, auth, model selection, etc.). */
+export interface LocalModelTemplateConfig {
+  // TODO — declare the fields your substrate needs to connect.
+  // Examples:
+  //   endpoint?: string;           // OpenAI-compat / vLLM / TGI URL
+  //   apiKey?: string;             // hosted services
+  //   defaultModel?: string;       // model name / tag
+  //   timeoutMs?: number;
+  exampleConfigField?: string;
+}
+
+export class LocalModelTemplate implements LocalModel {
+  /**
+   * Declare what your impl supports. The runtime + lint consult these flags.
+   * Set conservatively — overclaiming triggers cryptic downstream failures;
+   * underclaiming hides usable features.
+   */
+  static staticCapabilities(): LocalModelCapabilities {
+    return {
+      connector_type: "local_model",
+      implementation: "LocalModelTemplate", // ← rename to your class name
+      contract_version: "1.0.0",
+      features: {
+        // TODO — set each flag based on what your substrate can actually do.
+        supports_max_tokens: false,  // can opts.maxTokens cap output?
+        supports_timeout: false,     // do you honor a per-call timeout?
+        supports_streaming: false,   // does your run() stream tokens? (v1 contract is non-streaming — flag for forward-compat)
+        supports_embedding: false,   // does your substrate also expose embeddings?
+      },
+    };
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  constructor(_config: LocalModelTemplateConfig) {
+    // TODO — establish your substrate connection. For HTTP: store base URL
+    // + auth headers + default model. For SDK: cache the client instance.
+    throw new Error("LocalModelTemplate is a fork-me skeleton; replace with your impl.");
+  }
+
+  /**
+   * Dispatch a prompt and return the model's response text.
+   *
+   * `prompt` — the substituted prompt body (template substitution already
+   * resolved by the runtime; you get the final string).
+   *
+   * `opts`:
+   *   - `maxTokens` — optional cap on output length. Honor if `supports_max_tokens: true`.
+   *   - `model` — optional override of the configured default. Honor if your
+   *     substrate supports multiple models per instance.
+   *
+   * Return the response text directly (not wrapped in an envelope). The
+   * `LocalModelMcpConnector` bridge exposes this as `$ llm prompt="..." -> R`
+   * where R binds to your string return value.
+   *
+   * On dispatch failure: throw. Don't return error envelopes silently — the
+   * runtime's op-level `(fallback: ...)` machinery catches throws cleanly.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async run(_prompt: string, _opts: { maxTokens?: number; model?: string }): Promise<string> {
+    // TODO — dispatch via your transport.
+    //   - Map prompt + opts to your substrate's wire format (chat completion / completion / etc.)
+    //   - Apply your per-call timeout
+    //   - Parse the response; extract the text
+    //   - Throw on dispatch failure (don't return error envelope silently)
+    throw new Error("TODO: run() — dispatch prompt + return response text.");
+  }
+
+  /**
+   * Capability snapshot for `runtime_capabilities` discovery. Return free-form
+   * substrate-specific metadata.
+   *
+   * Per `LocalModelManifest` in `src/connectors/types.ts`, known curated fields:
+   *   - `kind`: string tag for substrate flavor ("openai-compat", "vllm", etc.)
+   *   - `default_model`: configured default model name
+   *   - `endpoint`: URL the impl connects to
+   *   - `models_available`: list when introspectable (e.g., `/v1/models` for OpenAI-compat)
+   *   - `fetch_error`: set when introspection failed (don't silently cache empty array)
+   * Plus `[key: string]: unknown` for substrate extensions.
+   *
+   * The bundled `OllamaLocalModel.manifest()` returns:
+   *   { capabilities_version: "1", manifest: { kind: "ollama",
+   *     endpoint: "...", default_model: "gemma2:9b", models_available: [...] } }
+   */
+  async manifest(): Promise<ManifestInfo<"local_model">> {
+    // TODO — return a snapshot of your substrate's metadata.
+    //   - kind: identify the substrate
+    //   - endpoint: where you connect
+    //   - default_model: what model you'll dispatch to
+    //   - models_available: list if you can introspect; surface fetch_error if introspection fails
+    throw new Error("TODO: manifest() — return substrate metadata snapshot.");
+  }
+}

package/examples/connectors/LocalModelTemplate/README.md

@@ -0,0 +1,134 @@
+# LocalModelTemplate — fork-me skeleton
+
+A skeleton `LocalModel` 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 LocalModel inference backed by:**
+- An OpenAI-compat HTTP endpoint (vLLM, TGI, SGLang, llama.cpp server)
+- A hosted LLM API (OpenAI, Anthropic, Cohere — though most adopters wire those via `RemoteMcpConnector` + the provider's MCP server instead)
+- A custom transport (gRPC, WebSocket, in-process inference)
+- A multi-model gateway
+
+The bundled `OllamaLocalModel` (in `src/connectors/local-model.ts`) is Ollama-specific. Fork from here when that doesn't fit.
+
+## The two legs
+
+```
+LocalModel (choose which connector)
+   ├── OllamaLocalModel (bundled, Ollama HTTP — src/connectors/local-model.ts)
+   └── Your fork from this template
+```
+
+LocalModel is the narrowest contract — just 2 methods + staticCapabilities. Most of the work in a fork is substrate-specific (auth, wire format, response parsing), not contract conformance.
+
+## Forking workflow
+
+```bash
+cp -r examples/connectors/LocalModelTemplate examples/connectors/MyLocalModel
+```
+
+1. **Rename the class.** Convention: `<Substrate>LocalModel` (e.g., `OpenAICompatLocalModel`, `AnthropicLocalModel`, `VllmLocalModel`).
+2. **Define your config interface.** Edit `LocalModelTemplateConfig` to declare what your substrate needs (endpoint URL, API key, default model, timeout, etc.).
+3. **Implement `run()`** — translate `(prompt, opts)` to your substrate's wire format; dispatch; parse the response text.
+4. **Implement `manifest()`** — return substrate metadata (kind, endpoint, default model, available models when introspectable).
+5. **Update `staticCapabilities()`** to declare what your impl supports.
+6. **Wire from your adopter bootstrap:**
+
+   ```typescript
+   import { Registry } from "skillscript-runtime";
+   import { MyLocalModel } from "./MyLocalModel.js";
+
+   const registry = new Registry();
+   registry.registerLocalModel("default", new MyLocalModel({ /* config */ }));
+   ```
+
+   The auto-wired `$ llm` MCP bridge wraps your impl transparently — once registered, `$ llm prompt="..."` dispatches through your fork without additional wiring.
+
+7. **Validate via the conformance suite:**
+
+   ```typescript
+   import { describe, it } from "vitest";
+   import { LocalModelConformance } from "skillscript-runtime/testing";
+   import { MyLocalModel } from "./MyLocalModel.js";
+
+   describe("MyLocalModel conformance", () => {
+     const tests = LocalModelConformance.buildTests({
+       build: () => new MyLocalModel({ /* test config */ }),
+       ctor: MyLocalModel,
+     });
+     for (const t of tests) it(`[${t.category}] ${t.name}`, t.run);
+   });
+   ```
+
+## Reference implementation
+
+The bundled `OllamaLocalModel` at `src/connectors/local-model.ts` is the canonical reference (164 LOC):
+
+- Ollama HTTP API (`POST /api/generate`, `GET /api/tags`)
+- AbortController timeout pattern
+- Manifest caches successful introspection but NOT failures (retries on next call)
+- Deduped stderr warning for fetch errors
+- Surfaces `fetch_error` in manifest when `/api/tags` introspection fails
+
+The error-handling patterns (don't silently cache failures; surface in manifest; dedupe-log) apply to any LocalModel substrate that introspects.
+
+## Contract surface (2 methods)
+
+LocalModel is the narrowest contract surface in skillscript:
+
+| Method | What it does | When called |
+|---|---|---|
+| `run(prompt, opts)` | Dispatch a prompt; return response text | Every `$ llm prompt="..." -> R` op (via the LocalModelMcpConnector bridge) |
+| `manifest()` | Substrate metadata for discovery | At startup + on-demand from MCP clients |
+
+Plus `staticCapabilities()` (required static).
+
+### `run()` semantics
+
+- **`prompt`** — already-substituted prompt body. Template substitution (`${VAR}` resolution) happens before your impl is called; you get the final string.
+- **`opts.maxTokens`** — optional output length cap. Honor if `supports_max_tokens: true`.
+- **`opts.model`** — optional per-call model override. Useful for adopters with multi-model gateways. Honor if your substrate supports it.
+- **Return** — the response text directly. NOT wrapped in an envelope. The bridge passes this through to skill source as `$(R)`.
+
+On dispatch failure: **throw**. The runtime's op-level `(fallback: ...)` machinery catches throws cleanly. Don't return error envelopes silently — that's the silent-recovery footgun pattern.
+
+### `manifest()` semantics
+
+Surface enough substrate metadata for adopters running `runtime_capabilities` to understand what's wired. Curated fields per `LocalModelManifest`:
+
+- `kind` — substrate flavor tag (`"openai-compat"`, `"vllm"`, `"anthropic"`, etc.)
+- `default_model` — configured default model name
+- `endpoint` — URL your impl connects to (helps debugging)
+- `models_available` — list when introspectable
+- `fetch_error` — set when introspection failed; don't silently cache empty array
+
+Plus `[key: string]: unknown` for substrate extensions.
+
+## A note on declarative wiring
+
+Unlike `McpConnector` (which has `registerConnectorClass()` for adopter-extensible declarative wiring via `connectors.json`), `LocalModel` is intrinsically *singleton* per deployment — one default per runtime. There's no equivalent class registry.
+
+Adopters wire their custom LocalModel **programmatically** from their bootstrap:
+
+```typescript
+registry.registerLocalModel("default", new MyLocalModel({ /* config */ }));
+```
+
+Declarative custom-LocalModel via `connectors.json` `substrate.local_model: {type: "custom", module, export, config}` form is **deferred** until async-bootstrap support lands. Same limitation applies to `SkillStore` and `MemoryStore` custom forms — sync `bootstrap()` can't `await import()`. Not LocalModel-specific.
+
+## Wiring against the dashboard / MCP
+
+Runtime hosts (MCP server + web dashboard) honor whichever LocalModel impl you register. To make your fork visible through `skillfile dashboard`:
+
+- Write a custom bootstrap that constructs the runtime with your LocalModel
+- Or register via `registry.registerLocalModel("default", new MyLocalModel(...))` before `bootstrap()` returns
+
+The auto-wired `$ llm` MCP bridge picks up your registration automatically — skills writing `$ llm prompt="..." -> R` get your impl without additional config.
+
+## Further reading
+
+- **[`../../../docs/configuration.md`](../../../docs/configuration.md)** — substrate selection via `connectors.json`
+- **[`../../../docs/adopter-playbook.md`](../../../docs/adopter-playbook.md)** — programmatic-bootstrap patterns
+- **`src/connectors/types.ts`** — authoritative `LocalModel` interface + `LocalModelManifest` curated fields
+- **`src/connectors/local-model.ts`** — `OllamaLocalModel` reference impl
+- **`src/connectors/local-model-mcp.ts`** — the `LocalModelMcpConnector` bridge that wraps your impl as `$ llm`
+- **`src/testing/conformance.ts`** — the per-contract conformance test suites

package/examples/connectors/McpConnectorTemplate/McpConnectorTemplate.ts

@@ -0,0 +1,200 @@
+/**
+ * McpConnectorTemplate — fork-me skeleton for writing your own McpConnector impl.
+ *
+ * This is NOT a runnable connector. Every method throws a "TODO" error. The
+ * purpose is to surface the McpConnector contract surface in a copy-and-customize
+ * shape for the exotic cases the four bundled impls don't cover.
+ *
+ * **When to fork from this template** (vs. using a bundled impl):
+ *   - `RemoteMcpConnector` — covers the common case: spawn a child process,
+ *     bridge stdio (LSP or newline framing). YouTrack, GitHub, Linear, most
+ *     remote MCPs all wire through this. Use it for ANY external MCP server
+ *     reachable via stdio bridging — JSON-configurable via `connectors.json`.
+ *   - `CallbackMcpConnector` — wraps a JS function as McpConnector. For test
+ *     rigs + embedder-wired transports where the dispatch is local code.
+ *   - `LocalModelMcpConnector` — bridges a registered LocalModel as
+ *     `$ llm prompt=...` MCP dispatch. Auto-wired when LocalModel substrate
+ *     is configured.
+ *   - `MemoryStoreMcpConnector` — bridges a registered MemoryStore as
+ *     `$ memory mode=...` MCP dispatch. Auto-wired when MemoryStore substrate
+ *     is configured.
+ *
+ * Fork from this template when none of those fit — e.g.:
+ *   - Direct HTTP MCP (JSON-RPC over HTTP, no child process)
+ *   - WebSocket MCP
+ *   - In-process MCP (call methods directly without IPC)
+ *   - Custom protocol that doesn't match stdio framing
+ *   - Cross-thread / worker-pool dispatch
+ *
+ * Forking workflow:
+ *   1. Copy this directory: `cp -r examples/connectors/McpConnectorTemplate examples/connectors/MyMcpConnector`
+ *   2. Rename the class — typically `<Transport>McpConnector` (e.g., `HttpMcpConnector`, `WebSocketMcpConnector`)
+ *   3. Implement `call()` against your transport
+ *   4. Implement `manifest()` returning transport metadata
+ *   5. Update `staticCapabilities()` to declare what your impl supports
+ *   6. (Optional) Implement `staticTools()` — returns the closed-set list of
+ *      tools your connector exposes so lint can validate `$ name.tool` references
+ *   7. Register from your adopter bootstrap:
+ *        `registry.registerMcpConnector("mytool", new MyMcpConnector({ ... }))`
+ *   8. (Optional) For `connectors.json` JSON-instantiability, add a static
+ *      `fromConfig(config)` factory + register via `registerConnectorClass()`:
+ *        ```typescript
+ *        import { registerConnectorClass } from "skillscript-runtime/connectors";
+ *        registerConnectorClass("MyMcpConnector", {
+ *          ctor: MyMcpConnector,
+ *          fromConfig: (cfg) => MyMcpConnector.fromConfig(cfg),
+ *        });
+ *        ```
+ *
+ * See `src/connectors/mcp-remote.ts` (`RemoteMcpConnector`) for the most
+ * comprehensive reference impl — stdio framing, child process lifecycle,
+ * `fromConfig` factory, timeout discipline. See `src/connectors/mcp.ts`
+ * (`CallbackMcpConnector`) for the minimal reference impl.
+ *
+ * Runtime hosts (MCP server + web dashboard) honor whichever McpConnector
+ * instances your registry has — bare `$ <name>` or qualified `$ <name>.<tool>`
+ * dispatches route through whatever's registered.
+ */
+
+import type {
+  McpConnector,
+  McpDispatchCtx,
+  McpConnectorCapabilities,
+  ManifestInfo,
+} from "../../../src/connectors/types.js";
+
+/** Replace with your transport's connection config (URL, auth, timeouts, etc.). */
+export interface McpConnectorTemplateConfig {
+  // TODO — declare the fields your transport needs to connect.
+  // Examples:
+  //   httpEndpoint?: string;
+  //   wsUrl?: string;
+  //   authToken?: string;
+  //   timeoutMs?: number;
+  exampleConfigField?: string;
+}
+
+export class McpConnectorTemplate implements McpConnector {
+  /**
+   * Declare what your impl supports. The runtime + lint consult these flags.
+   * Conservative defaults shown; flip to true once your impl actually supports
+   * each capability.
+   */
+  static staticCapabilities(): McpConnectorCapabilities {
+    return {
+      connector_type: "mcp_connector",
+      implementation: "McpConnectorTemplate", // ← rename to your class name
+      contract_version: "1.0.0",
+      features: {
+        // TODO — set each flag based on what your transport can actually do.
+        supports_identity_propagation: false,  // can ctxOverrides.agentId thread through to upstream?
+        supports_streaming_responses: false,   // can `call()` return an async iterable?
+        supports_batch: false,                 // can the upstream batch multiple tool calls?
+      },
+    };
+  }
+
+  /**
+   * (Optional) Declare the closed-set tool surface for lint validation.
+   *
+   * Return:
+   *   - `string[]` — the canonical tool names your connector exposes;
+   *     `$ name.tool` references are validated against this list at lint time
+   *   - `null` — surface varies at runtime (e.g., `RemoteMcpConnector` wraps
+   *     an arbitrary upstream MCP server); lint emits a tier-3 advisory
+   *     instead of green-lighting
+   *
+   * Omit this method entirely and behavior is the same as `null`.
+   */
+  // static staticTools(): string[] | null {
+  //   return ["my_tool_a", "my_tool_b"];
+  // }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  constructor(_config: McpConnectorTemplateConfig) {
+    // TODO — establish your transport. For HTTP: store base URL + auth headers.
+    // For WebSocket: open the connection (or defer to first dispatch).
+    // For in-process: cache references to the dispatch targets.
+    throw new Error("McpConnectorTemplate is a fork-me skeleton; replace with your impl.");
+  }
+
+  /**
+   * (Optional, for `connectors.json` JSON-instantiability)
+   *
+   * Factory that constructs an instance from a JSON `config` block.
+   * Used by `loadConnectorsConfig()` when adopters declare your class in
+   * `connectors.json`:
+   *
+   *   { "mytool": { "class": "MyMcpConnector", "config": { ... } } }
+   *
+   * Validates the config shape; throws a clear error on missing/wrong fields.
+   *
+   * Adopters register the class via:
+   *   ```
+   *   import { registerConnectorClass } from "skillscript-runtime/connectors";
+   *   registerConnectorClass("MyMcpConnector", {
+   *     ctor: MyMcpConnector,
+   *     fromConfig: (cfg) => MyMcpConnector.fromConfig(cfg),
+   *   });
+   *   ```
+   * BEFORE `loadConnectorsConfig` runs in their bootstrap.
+   *
+   * Omit `fromConfig` if your connector can't be configured via JSON (e.g.,
+   * it needs a runtime instance the way `CallbackMcpConnector` needs a
+   * dispatch function). Adopters then wire it via embedder code only.
+   */
+  // static fromConfig(_config: Record<string, unknown>): McpConnectorTemplate {
+  //   // TODO — validate config + construct.
+  //   throw new Error("TODO: fromConfig() — validate JSON config + instantiate.");
+  // }
+
+  /**
+   * Dispatch a tool call to your transport.
+   *
+   * `toolName` — the tool the caller wants (`$ youtrack.search_issues` →
+   * `toolName = "search_issues"`; bare `$ youtrack args` → `toolName` = the
+   * unqualified op name).
+   *
+   * `args` — the kwargs from the skill source (`$ youtrack.search_issues
+   * query="..." limit=10` → `{ query: "...", limit: 10 }`).
+   *
+   * `ctxOverrides` — optional identity overrides threaded through dispatch
+   * (`agentId`, `isAdmin`). Bundled connectors that honor identity propagation
+   * forward these to the upstream substrate.
+   *
+   * Return whatever the upstream MCP returns. Skills that bind via `-> R`
+   * get the raw result; skills that descend into it (`$(R.field)`) get
+   * tier-3 advisory if your impl's return shape isn't statically discoverable.
+   *
+   * On dispatch failure, throw — the runtime's op-level `(fallback: ...)`
+   * machinery surfaces it cleanly. Don't return error envelopes silently;
+   * the v0.5.0+ contract surfaces inner-tool errors via throw.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async call(
+    _toolName: string,
+    _args: Record<string, unknown>,
+    _ctxOverrides?: McpDispatchCtx,
+  ): Promise<unknown> {
+    // TODO — dispatch via your transport.
+    //   - Map toolName + args to your transport's wire format
+    //   - Apply ctxOverrides if you support identity propagation
+    //   - Apply your transport-specific timeout
+    //   - Throw on dispatch failure (don't return an error envelope silently)
+    //   - Return the raw response from upstream
+    throw new Error("TODO: call() — dispatch tool call via your transport.");
+  }
+
+  /**
+   * Capability snapshot for `runtime_capabilities` discovery. Return free-form
+   * transport-specific metadata.
+   *
+   * The bundled `RemoteMcpConnector.manifest()` returns:
+   *   { capabilities_version: "1", manifest: { kind: "remote-mcp",
+   *       command: "...", framing: "lsp", tools_available: [...] } }
+   */
+  async manifest(): Promise<ManifestInfo<"mcp_connector">> {
+    // TODO — return a snapshot of your transport's metadata.
+    throw new Error("TODO: manifest() — return transport-specific capability snapshot.");
+  }
+}