skillscript-runtime 0.10.0 → 0.13.2

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.");
+  }
+}

package/examples/connectors/McpConnectorTemplate/README.md

@@ -0,0 +1,153 @@
+# McpConnectorTemplate — fork-me skeleton
+
+A skeleton `McpConnector` implementation for adopters writing their own. Not runnable; every method throws a `TODO` error. Copy this directory, rename, fill in the substrate-specific work.
+
+**Most adopters don't need this template.** Four bundled impls already cover the common cases:
+
+| Bundled impl | What it covers |
+|---|---|
+| `RemoteMcpConnector` | Stdio bridging to remote MCP servers (`npx mcp-remote ...`). YouTrack, GitHub, Linear, most adopter MCP wiring goes through this. JSON-configurable via `connectors.json`. |
+| `CallbackMcpConnector` | Wraps a JS function. Test rigs + embedder-wired transports where the dispatch is local code. |
+| `LocalModelMcpConnector` | Bridges a registered `LocalModel` as `$ llm prompt=...`. Auto-wired when `substrate.local_model` is set. |
+| `MemoryStoreMcpConnector` | Bridges a registered `MemoryStore` as `$ memory mode=...`. Auto-wired when `substrate.memory_store` is set. |
+
+**Fork this template only 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 transport that doesn't match stdio framing
+- Cross-thread / worker-pool dispatch
+
+If you're trying to wire a remote MCP server like YouTrack or GitHub, **you want `RemoteMcpConnector` in `connectors.json`**, not this template. See `connectors.json.example` for the wiring pattern.
+
+## Forking workflow
+
+```bash
+cp -r examples/connectors/McpConnectorTemplate examples/connectors/MyMcpConnector
+```
+
+1. **Rename the class.** Convention: `<Transport>McpConnector` (e.g., `HttpMcpConnector`, `WebSocketMcpConnector`, `InProcessMcpConnector`).
+2. **Define your config interface.** Edit `McpConnectorTemplateConfig` to declare what your transport needs (URL, auth, timeouts, etc.).
+3. **Implement `call()`** — translate `(toolName, args)` to your transport's wire format; dispatch; return the result.
+4. **Implement `manifest()`** — return transport metadata for `runtime_capabilities` discovery.
+5. **Update `staticCapabilities()`** to declare what your impl supports.
+6. **(Optional) Implement `staticTools()`** — return the closed-set list of tools your connector exposes if static; lint validates `$ name.tool` against this list. Return `null` (or omit) if the surface is runtime-discovered.
+7. **Wire from your adopter bootstrap:**
+
+   ```typescript
+   import { Registry } from "skillscript-runtime";
+   import { MyMcpConnector } from "./MyMcpConnector.js";
+
+   const registry = new Registry();
+   registry.registerMcpConnector("mytool", new MyMcpConnector({ /* config */ }));
+   ```
+
+8. **(Optional) For `connectors.json` JSON-instantiability** — add a static `fromConfig(config)` factory + register the class via `registerConnectorClass()`:
+
+   ```typescript
+   import { registerConnectorClass } from "skillscript-runtime/connectors";
+
+   registerConnectorClass("MyMcpConnector", {
+     ctor: MyMcpConnector,
+     fromConfig: (cfg) => MyMcpConnector.fromConfig(cfg),
+   });
+   ```
+
+   Call this BEFORE `loadConnectorsConfig` runs in your bootstrap. Then adopters can declare instances in `connectors.json`:
+
+   ```json
+   {
+     "myinstance": {
+       "class": "MyMcpConnector",
+       "config": { "endpoint": "https://...", "authToken": "${MY_TOKEN}" }
+     }
+   }
+   ```
+
+## Reference implementations
+
+The bundled impls are the canonical reference:
+
+- **`src/connectors/mcp-remote.ts`** — `RemoteMcpConnector`. Most comprehensive: stdio framing (LSP and newline), child process lifecycle (spawn → initialize → tools/list cache → SIGTERM/SIGKILL on dispose), `fromConfig` factory with strict validation, per-message timeout discipline. The closest reference for any transport that needs robust lifecycle management.
+- **`src/connectors/mcp.ts`** — `CallbackMcpConnector`. Minimal reference: 60 LOC. The closest reference for embedder-wired transports.
+
+When in doubt, read both + the bridge classes (`local-model-mcp.ts`, `memory-store-mcp.ts`) for how single-substrate bridges work.
+
+## Contract surface (2 methods)
+
+McpConnector is the narrowest of the five contracts:
+
+| Method | What it does | When called |
+|---|---|---|
+| `call(toolName, args, ctx?)` | Dispatch a tool call to your transport | Every `$ <connector> ...` op |
+| `manifest()` | Transport metadata for discovery | At startup + on-demand from MCP clients |
+
+Plus `staticCapabilities()` (required static) and `staticTools()` (optional static).
+
+### `call()` semantics
+
+- **`toolName`** — the tool the caller wants:
+  - `$ youtrack.search_issues query="..."` → `toolName = "search_issues"`
+  - `$ youtrack query="..."` (bare form) → `toolName` is the *unqualified op name* (typically the connector's auto-routing target)
+- **`args`** — kwargs from the skill source as a plain object
+- **`ctxOverrides`** — optional identity propagation (`agentId`, `isAdmin`). Connectors that support identity-propagation thread these to upstream
+- **Return** — whatever the upstream MCP returns. Skills bind via `-> R`; if the return shape isn't statically discoverable, lint emits a tier-3 advisory when callers descend (`$(R.field)`)
+
+On dispatch failure, **throw** — the runtime's op-level `(fallback: ...)` machinery handles it cleanly. Don't return error envelopes silently; the v0.5.0+ contract surfaces inner-tool errors via throw.
+
+### `staticTools()` lint integration
+
+If your connector exposes a known closed set of tools (e.g., a JIRA wrapper that only exposes `search_issues`, `get_issue`, `create_issue`), implementing `staticTools()` lets lint validate `$ name.tool` references at authoring time:
+
+```typescript
+static staticTools(): string[] {
+  return ["search_issues", "get_issue", "create_issue"];
+}
+```
+
+Skills that write `$ jira.unknown_tool ...` fail lint with `unknown-tool-on-connector` (tier-1 error).
+
+If your surface is runtime-discovered (e.g., `RemoteMcpConnector` wrapping an arbitrary upstream MCP), return `null` or omit the method. Lint emits a tier-3 advisory on dotted dispatch instead of green-lighting.
+
+## Wiring against the dashboard / MCP
+
+Runtime hosts (MCP server + web dashboard) honor whichever McpConnector instances your registry has. There's no `substrate` slot for McpConnector — that's intentional, because McpConnector is intrinsically *instanced* (you'll have multiple: `youtrack`, `github`, `jira`, ...) not singleton.
+
+Two registration paths:
+
+- **Programmatic** (your bootstrap):
+  ```typescript
+  registry.registerMcpConnector("youtrack", new RemoteMcpConnector({ command: "npx", args: ["mcp-remote", "..."] }));
+  registry.registerMcpConnector("github", new RemoteMcpConnector({ ... }));
+  ```
+- **Declarative** (`connectors.json`):
+  ```json
+  {
+    "youtrack": { "class": "RemoteMcpConnector", "config": { "command": "npx", ... } },
+    "github":   { "class": "RemoteMcpConnector", "config": { ... } }
+  }
+  ```
+
+The declarative path is the canonical adopter pattern for stdio-bridged remote MCPs. Your fork is for transports the declarative path can't express.
+
+## McpConnector vs. SkillStore / MemoryStore differences
+
+| Aspect | McpConnector | SkillStore / MemoryStore |
+|---|---|---|
+| Methods | 2 (call, manifest) | 3-8 (more state machine) |
+| Cardinality | Many instances per deployment | One singleton per slot |
+| Substrate config | Per-instance via top-level keys | `substrate` section short/object/custom |
+| Class extensibility | `registerConnectorClass()` for adopter-custom classes | Programmatic bootstrap (or `substrate.skill_store: {type: "custom", ...}` once async-bootstrap lands) |
+| Auto-wired bridges | `llm` + `memory` + `memory_write` (LocalModel + MemoryStore exposed via bridge connectors) | n/a (these ARE the substrates being bridged) |
+
+McpConnector is fundamentally the "dispatch to external tools" surface — narrowest contract, broadest range of impls.
+
+## Further reading
+
+- **[`../../../docs/configuration.md`](../../../docs/configuration.md)** — `connectors.json` wiring (substrate + named MCP instances)
+- **[`../../../docs/adopter-playbook.md`](../../../docs/adopter-playbook.md)** — Case 1 vs Case 2 wiring patterns; substrate-portable vs substrate-locked
+- **`src/connectors/types.ts`** — authoritative `McpConnector` interface
+- **`src/connectors/mcp-remote.ts`** — full-featured reference impl with stdio framing + lifecycle
+- **`src/connectors/mcp.ts`** — minimal reference impl
+- **`src/connectors/config.ts`** — `registerConnectorClass()` + `loadConnectorsConfig()`

package/examples/connectors/MemoryStoreTemplate/MemoryStoreTemplate.ts

@@ -0,0 +1,155 @@
+/**
+ * MemoryStoreTemplate — fork-me skeleton for writing your own MemoryStore impl.
+ *
+ * This is NOT a runnable connector. Every method throws a "TODO" error. The
+ * purpose is to surface the MemoryStore contract surface in a copy-and-customize
+ * shape so adopters writing AMP-, Pinecone-, Weaviate-, Qdrant-, or
+ * Postgres-backed MemoryStores have a starting skeleton.
+ *
+ * Forking workflow:
+ *   1. Copy this directory into your codebase (`cp -r examples/connectors/MemoryStoreTemplate examples/connectors/MyMemoryStore`)
+ *   2. Rename the class — typically `<Substrate>MemoryStore` (e.g., `PineconeMemoryStore`, `AmpMemoryStore`)
+ *   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.registerMemoryStore("primary", new MyMemoryStore({ ... }))`
+ *   6. Validate via the conformance suite:
+ *        `MemoryStoreConformance.buildTests({ build: () => new MyMemoryStore(...), ctor: MyMemoryStore })`
+ *
+ * See `src/connectors/memory-store.ts` for the working reference implementation
+ * (`SqliteMemoryStore` — SQLite + FTS5 backing). The full contract spec lives in
+ * `src/connectors/types.ts` (`MemoryStore` interface + `PortableMemory` +
+ * `QueryFilters` + `MemoryWrite` types).
+ *
+ * Runtime hosts (MCP server + web dashboard) honor whichever MemoryStore impl
+ * you register via the registry, so once your fork passes the conformance
+ * suite the entire `$ memory` / `$ memory_write` dispatch path reads + writes
+ * against your substrate.
+ */
+
+import type {
+  MemoryStore,
+  QueryFilters,
+  PortableMemory,
+  MemoryWrite,
+  MemoryWriteRecord,
+  MemoryStoreCapabilities,
+  ManifestInfo,
+} from "../../../src/connectors/types.js";
+
+/** Replace with your substrate's connection config (host, dbName, API key, etc.). */
+export interface MemoryStoreTemplateConfig {
+  // TODO — declare the fields your substrate needs to connect.
+  // Examples:
+  //   pineconeApiKey?: string;
+  //   pineconeEnvironment?: string;
+  //   weaviateUrl?: string;
+  //   ampVault?: string;
+  exampleConfigField?: string;
+}
+
+export class MemoryStoreTemplate implements MemoryStore {
+  /**
+   * 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(): MemoryStoreCapabilities {
+    return {
+      connector_type: "memory_store",
+      implementation: "MemoryStoreTemplate", // ← 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 write() persist new memories?
+        supports_tag_filter: false,              // can query() filter by domain_tags?
+        supports_semantic: false,                // mode="semantic" supported?
+        supports_rerank: false,                  // mode="rerank" supported?
+        supports_thread_status_filter: false,    // can query() filter by thread_status?
+        supports_pinning: false,                 // does the substrate track pinned: true?
+        supports_decay_model: false,             // does the substrate honor decay_model?
+      },
+    };
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  constructor(_config: MemoryStoreTemplateConfig) {
+    // TODO — establish your substrate connection. For SQL: open the database
+    // + run schema migrations. For vector DB: cache the SDK client + index
+    // name. For HTTP: store the base URL + auth headers.
+    throw new Error("MemoryStoreTemplate 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, score range, etc.).
+   *
+   * The bundled `SqliteMemoryStore.manifest()` returns:
+   *   { capabilities_version: "1", manifest: { kind: "sqlite-fts",
+   *       supported_modes: ["fts"], score_range: "unbounded",
+   *       supported_filters: ["domain_tags"], supports_write: true } }
+   */
+  async manifest(): Promise<ManifestInfo<"memory_store">> {
+    // TODO — return a snapshot of your substrate's capabilities.
+    throw new Error("TODO: manifest() — return substrate-specific capability snapshot.");
+  }
+
+  /**
+   * Query memories by mode + filter. Return `PortableMemory[]` ordered by
+   * relevance (most relevant first). Empty result is fine; never throw "not
+   * found" — return [].
+   *
+   * `QueryFilters` shape:
+   *   - `query`: string (search terms; substrate-specific interpretation)
+   *   - `limit`: number (max results)
+   *   - `mode`: "fts" | "semantic" | "rerank" | substrate-specific string
+   *   - Plus arbitrary additional filter fields (`domain_tags`, `thread_status`,
+   *     `payload_type`, `pinned`, `agent_id`, etc.) — substrate honors what
+   *     it supports, ignores the rest. Per the curated-subset framing in
+   *     `types.ts`, these top-level fields are first-class for substrates
+   *     that have them.
+   *
+   * `PortableMemory` core fields:
+   *   - Always: `id`, `summary`, `created_at`
+   *   - Often: `detail`, `score`, `domain_tags`, `payload_type`
+   *   - Per-substrate (curated): `pinned`, `confidence`, `thread_status`,
+   *     `recipients`, `expires_at`, `agent_id`, `vault`
+   *   - Catch-all: `metadata` object for substrate-specific extensions
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async query(_filters: QueryFilters): Promise<PortableMemory[]> {
+    // TODO — translate `filters` to your substrate's query API.
+    //   - Reject unsupported `mode` values with a clear error (don't silently
+    //     fall back; cold authors will be confused)
+    //   - Apply curated-subset filters (domain_tags, payload_type, etc.) where
+    //     the substrate supports them
+    //   - Map your substrate's result rows into `PortableMemory` shape
+    //   - Order by relevance (most relevant first)
+    //   - Honor `limit`
+    throw new Error("TODO: query() — return PortableMemory[] ordered by relevance.");
+  }
+
+  /**
+   * Persist a new memory entry. Return the substrate-assigned `id` +
+   * `created_at` (unix seconds).
+   *
+   * `MemoryWrite` shape:
+   *   - `content`: string (required; the memory body)
+   *   - `tags`: string[] (optional; routed to substrate's tag mechanism)
+   *   - `recipients`: string[] (optional advisory — substrates with alerting
+   *     machinery use this to route notifications, e.g., AMP's mailbox model)
+   *   - `expires_at`: number (optional; unix seconds — substrate-side TTL)
+   *   - `metadata`: Record<string, unknown> (catch-all for substrate-specific
+   *     extensions like `vault`, `payload_type`, `confidence`)
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async write(_entry: MemoryWrite): Promise<MemoryWriteRecord> {
+    // TODO — persist the memory via your substrate.
+    //   - Generate or accept an id (substrate-dependent)
+    //   - Persist content + tags + metadata
+    //   - Apply recipients hint if your substrate has alerting
+    //   - Apply expires_at if your substrate has TTL
+    //   - Return { id, created_at }
+    throw new Error("TODO: write() — persist memory; return { id, created_at }.");
+  }
+}