skillscript-runtime 0.9.9 → 0.13.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/README.md +39 -46
  2. package/dist/bootstrap.d.ts +57 -18
  3. package/dist/bootstrap.d.ts.map +1 -1
  4. package/dist/bootstrap.js +188 -54
  5. package/dist/bootstrap.js.map +1 -1
  6. package/dist/cli.js +5 -6
  7. package/dist/cli.js.map +1 -1
  8. package/dist/connectors/agent-noop.d.ts +2 -2
  9. package/dist/connectors/agent-noop.d.ts.map +1 -1
  10. package/dist/connectors/config.d.ts +46 -0
  11. package/dist/connectors/config.d.ts.map +1 -1
  12. package/dist/connectors/config.js +109 -1
  13. package/dist/connectors/config.js.map +1 -1
  14. package/dist/connectors/index.d.ts +3 -1
  15. package/dist/connectors/index.d.ts.map +1 -1
  16. package/dist/connectors/index.js +6 -3
  17. package/dist/connectors/index.js.map +1 -1
  18. package/dist/connectors/local-model-mcp.d.ts +3 -3
  19. package/dist/connectors/local-model-mcp.d.ts.map +1 -1
  20. package/dist/connectors/local-model.d.ts +30 -11
  21. package/dist/connectors/local-model.d.ts.map +1 -1
  22. package/dist/connectors/local-model.js +44 -12
  23. package/dist/connectors/local-model.js.map +1 -1
  24. package/dist/connectors/mcp-remote.d.ts +3 -3
  25. package/dist/connectors/mcp-remote.d.ts.map +1 -1
  26. package/dist/connectors/mcp.d.ts +3 -3
  27. package/dist/connectors/mcp.d.ts.map +1 -1
  28. package/dist/connectors/memory-store-mcp.d.ts +3 -3
  29. package/dist/connectors/memory-store-mcp.d.ts.map +1 -1
  30. package/dist/connectors/memory-store-mcp.js +3 -1
  31. package/dist/connectors/memory-store-mcp.js.map +1 -1
  32. package/dist/connectors/memory-store.d.ts +26 -6
  33. package/dist/connectors/memory-store.d.ts.map +1 -1
  34. package/dist/connectors/memory-store.js +84 -15
  35. package/dist/connectors/memory-store.js.map +1 -1
  36. package/dist/connectors/registry.d.ts +28 -5
  37. package/dist/connectors/registry.d.ts.map +1 -1
  38. package/dist/connectors/registry.js +34 -11
  39. package/dist/connectors/registry.js.map +1 -1
  40. package/dist/connectors/skill-store.d.ts +3 -3
  41. package/dist/connectors/skill-store.d.ts.map +1 -1
  42. package/dist/connectors/sqlite-skill-store.d.ts +89 -0
  43. package/dist/connectors/sqlite-skill-store.d.ts.map +1 -0
  44. package/dist/connectors/sqlite-skill-store.js +506 -0
  45. package/dist/connectors/sqlite-skill-store.js.map +1 -0
  46. package/dist/connectors/types.d.ts +86 -9
  47. package/dist/connectors/types.d.ts.map +1 -1
  48. package/dist/connectors/types.js.map +1 -1
  49. package/dist/errors.d.ts +15 -1
  50. package/dist/errors.d.ts.map +1 -1
  51. package/dist/errors.js +47 -6
  52. package/dist/errors.js.map +1 -1
  53. package/dist/help-content.d.ts.map +1 -1
  54. package/dist/help-content.js +18 -4
  55. package/dist/help-content.js.map +1 -1
  56. package/dist/index.d.ts +2 -0
  57. package/dist/index.d.ts.map +1 -1
  58. package/dist/index.js +1 -0
  59. package/dist/index.js.map +1 -1
  60. package/dist/runtime-config.d.ts +0 -2
  61. package/dist/runtime-config.d.ts.map +1 -1
  62. package/dist/runtime-config.js +1 -1
  63. package/dist/runtime-config.js.map +1 -1
  64. package/dist/runtime.d.ts.map +1 -1
  65. package/dist/runtime.js +29 -30
  66. package/dist/runtime.js.map +1 -1
  67. package/dist/testing/conformance.d.ts.map +1 -1
  68. package/dist/testing/conformance.js +12 -6
  69. package/dist/testing/conformance.js.map +1 -1
  70. package/examples/README.md +13 -13
  71. package/examples/connectors/LocalModelTemplate/LocalModelTemplate.ts +138 -0
  72. package/examples/connectors/LocalModelTemplate/README.md +134 -0
  73. package/examples/connectors/McpConnectorTemplate/McpConnectorTemplate.ts +200 -0
  74. package/examples/connectors/McpConnectorTemplate/README.md +153 -0
  75. package/examples/connectors/MemoryStoreTemplate/MemoryStoreTemplate.ts +155 -0
  76. package/examples/connectors/MemoryStoreTemplate/README.md +169 -0
  77. package/examples/connectors/README.md +47 -0
  78. package/examples/connectors/SkillStoreTemplate/README.md +143 -0
  79. package/examples/connectors/SkillStoreTemplate/SkillStoreTemplate.ts +199 -0
  80. package/examples/{hello.skill.provenance.json → skillscripts/hello.skill.provenance.json} +1 -1
  81. package/package.json +1 -1
  82. package/scaffold/config.toml +8 -12
  83. package/scaffold/connectors.json +31 -3
  84. /package/examples/{classify-support-ticket.skill.md → skillscripts/classify-support-ticket.skill.md} +0 -0
  85. /package/examples/{cut-release-tag.skill.md → skillscripts/cut-release-tag.skill.md} +0 -0
  86. /package/examples/{doc-qa-with-citations.skill.md → skillscripts/doc-qa-with-citations.skill.md} +0 -0
  87. /package/examples/{feedback-sentiment-scan.skill.md → skillscripts/feedback-sentiment-scan.skill.md} +0 -0
  88. /package/examples/{hello.skill.md → skillscripts/hello.skill.md} +0 -0
  89. /package/examples/{morning-brief.skill.md → skillscripts/morning-brief.skill.md} +0 -0
  90. /package/examples/{queue-length-monitor.skill.md → skillscripts/queue-length-monitor.skill.md} +0 -0
  91. /package/examples/{service-health-watch.skill.md → skillscripts/service-health-watch.skill.md} +0 -0
  92. /package/examples/{youtrack-morning-sweep.skill.md → skillscripts/youtrack-morning-sweep.skill.md} +0 -0
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
  *A language for agents to write themselves in.*
4
4
 
5
5
  [![npm version](https://img.shields.io/npm/v/skillscript-runtime.svg)](https://www.npmjs.com/package/skillscript-runtime)
6
- [![tests](https://img.shields.io/badge/tests-896%2F896-green)](#)
6
+ [![tests](https://img.shields.io/badge/tests-passing-green)](#)
7
7
  [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
8
8
  [![status](https://img.shields.io/badge/status-pre--1.0-orange)](#status)
9
9
 
@@ -119,13 +119,13 @@ Every skillscript skill is one of three shapes, determined by the relationship t
119
119
 
120
120
  The kinds compose. A Headless monitor fires on cron, evaluates a condition, and routes into an Augmenting skill that wakes an agent with context, which itself references a Template skill for the agent to execute.
121
121
 
122
- The three kinds describe the skill's *role* (who consumes the output). Orthogonal to that is the skill's *delivery channel* — the actual op that ships the result. Three channels are first-class: `emit(text="...")` for embedded prompt-context, `$ memory_write content="..." addressed_to="<agent>"` for memory handoff, and `file_write(path="...", content="...")` for file handoff. A single skill can use any combination. See the [Language Reference](https://github.com/sshwarts/skillscript/blob/main/docs/language-reference.md) §1 for the full taxonomy.
122
+ The three kinds describe the skill's *role* (who consumes the output). Orthogonal to that is the skill's *delivery channel* — the actual op that ships the result. Three channels are first-class: `emit(text="...")` for embedded prompt-context, `$ memory_write content="..." addressed_to="<agent>"` for memory handoff, and `file_write(path="...", content="...")` for file handoff. A single skill can use any combination. See the [Language Reference](docs/language-reference.md) §1 for the full taxonomy.
123
123
 
124
124
  ### Waking agents
125
125
 
126
126
  Augmenting and Template skills don't just write somewhere; they deliver to a frontier agent through `AgentConnector`. The contract is substrate-neutral: a Headless monitor detects a condition, evaluates whether action is warranted, and either resolves silently or calls `AgentConnector.deliver(agent_id, payload)`. The implementation might write a memory the agent reads at next session, post to a chat thread the agent monitors, send a push notification, write to a tmux pane, or invoke a webhook. All the adopter's call.
127
127
 
128
- The runtime ships `NoOpAgentConnector` by default; production deployments wire their own. AgentConnector wiring is embedder-only in v0.7.0 — deployments instantiate a concrete impl in code at runtime startup and register it via the runtime's connector registry, rather than declaring it in `connectors.json`. Common wirings look like:
128
+ The runtime ships `NoOpAgentConnector` by default; production deployments wire their own and register it via the runtime's connector registry, rather than declaring it in `connectors.json`. Common wirings look like:
129
129
 
130
130
  ```typescript
131
131
  // At runtime startup
@@ -267,8 +267,7 @@ The hello example is a single static target. A more representative shape is a cr
267
267
  snapshot:
268
268
  shell(command="df -h --output=source,pcent,target") -> USAGE
269
269
  file_write(path="/var/log/skillscript/disk-${EVENT.fired_at_unix}.txt",
270
- content="${USAGE}",
271
- approved="cron-fired daily snapshot")
270
+ content="${USAGE}")
272
271
  emit(text="Snapshot written for ${NOW}")
273
272
 
274
273
  default: snapshot
@@ -277,7 +276,7 @@ default: snapshot
277
276
  Three things to notice:
278
277
 
279
278
  1. **`# Triggers: cron:"..."`** — the runtime registers the cron schedule at load time; no external scheduler.
280
- 2. **`# Autonomous: true`** — the skill-author's declaration that mutation ops (here `file_write`) are authorized to fire without per-call confirmation. Without this header, mutation ops require the inline `approved="<reason>"` kwarg shown above on each call site. Pick one; both work.
279
+ 2. **`# Autonomous: true`** — the skill-author's declaration that mutation ops (here `file_write`) are authorized to fire without per-call confirmation. Without this header, mutation ops require an inline `approved="<reason>"` kwarg on each call site, or a preceding `ask(...)` gate in the same target. Pick whichever fits.
281
280
  3. **`${EVENT.fired_at_unix}` + `${NOW}`** — ambient refs the runtime substitutes per-fire. `EVENT.*` covers the trigger payload; `NOW` is the ISO timestamp at op dispatch. See [Language Reference §3](docs/language-reference.md) for the full ambient list.
282
281
 
283
282
  Swap in `$ ticketing_search`, `$ llm`, `$ memory_write` once you've wired connectors, and the same skill shape becomes a real triage pipeline.
@@ -286,36 +285,35 @@ Swap in `$ ticketing_search`, `$ llm`, `$ memory_write` once you've wired connec
286
285
 
287
286
  Skills don't know what they're talking to. Five contracts decouple language from substrate:
288
287
 
289
- | Contract | Purpose | Routes |
288
+ | Contract | Purpose | Base config |
290
289
  |---|---|---|
291
- | `SkillStore` | Skill source persistence | `.skill.md` files (filesystem default) |
292
- | `LocalModel` | Local LLM dispatch Ollama backed by default | `~ prompt=...` legacy op + future `$ llm` MCP bridge |
293
- | `MemoryStore` | Retrieval over a knowledge store — SQLite-backed by default | `>` legacy op + future `$ memory` MCP bridge |
294
- | `McpConnector` | MCP tool invocation — external dispatch (any wired connector) | `$ <connector> args` ops |
295
- | `AgentConnector` | Delivery to a frontier agent | `prompt-context:` and `template:` outputs |
290
+ | `SkillStore` | Skill source persistence | `FilesystemSkillStore` (default); switch via `substrate.skill_store` in `connectors.json` |
291
+ | `MemoryStore` | Retrieval over a knowledge store | `SqliteMemoryStore` (conditional on dbPath); switch via `substrate.memory_store` |
292
+ | `LocalModel` | Local LLM dispatch | **null** (adopter wires explicitly via `substrate.local_model`) |
293
+ | `McpConnector` | MCP tool invocation — external dispatch | adopter wires named instances in `connectors.json` |
294
+ | `AgentConnector` | Delivery to a frontier agent | adopter wires explicitly (no bundled default) |
296
295
 
297
- <sub>† `LocalModel` and `MemoryStore` are scheduled to be deprivileged to adopter-level wiring in v0.7.1 via the generic bridge classes (`LocalModelMcpConnector`, `MemoryStoreMcpConnector`). They back the legacy `~` and `>` ops during the v0.7.x grace period; the canonical v0.7.0+ path routes through `$ llm` / `$ memory` MCP dispatch instead. The language-relevant contracts going forward are `McpConnector`, `AgentConnector`, and `SkillStore`.</sub>
296
+ Runtime hosts (MCP server + web dashboard) honor whichever substrate the deployment configures. Authoring CLI commands (`skillfile compile`, `skillfile lint`, `skillfile audit`, `skillfile list`) stay filesystem-pinned by design they're the FS-authoring loop.
298
297
 
299
- **v0.7.0 substrate framing.** The canonical syntax routes everything substrate-specific through MCP dispatch — `$ llm prompt="..."` rather than the legacy `~`, `$ memory mode=fts query="..."` rather than the legacy `>`. This keeps skill source portable across adopters who wire different substrates. Pick the connector names that read well at your call sites: `llm`, `memory`, `openai_chat`, `pinecone_query` — whatever matches the substrate.
300
-
301
- **Today's reality.** The `LocalModel` and `MemoryStore` contracts back the *legacy* `~` and `>` ops which continue to work during the grace period — Ollama via `LocalModel` (default endpoint `http://localhost:11434`) and SQLite via `MemoryStore`. The canonical `$ llm` / `$ memory` MCP-dispatch paths require an adopter-wired MCP bridge. v0.7.1 will ship generic bridge classes (`LocalModelMcpConnector` + `MemoryStoreMcpConnector`) that wrap the existing contracts as MCP connectors, so any `LocalModel`/`MemoryStore` implementation gets a canonical `$ <name>` dispatch surface. Until then:
302
-
303
- - **Use `~ prompt="..." model="qwen" -> R`** to call Ollama today (legacy syntax, fully functional)
304
- - **Use `> mode=fts query="..." limit=10 -> R`** to query the SQLite memory store today
305
- - **Use `$ llm prompt="..."`** only if you've wired an `llm` MCP connector in `connectors.json` (e.g., via `RemoteMcpConnector` pointing at an ollama-mcp server)
306
-
307
- The migration tool that ran on `examples/` rewrote everything to canonical form on the assumption that v0.7.1's bridge connectors will land; until then, examples that use `$ llm` / `$ memory` need adopter-wired connectors to execute.
298
+ See **[`docs/configuration.md`](docs/configuration.md)** for the full substrate config reference.
308
299
 
309
300
  Wire your own by implementing the interface and registering in `connectors.json`. See [`docs/language-reference.md`](docs/language-reference.md) §10 for full contracts.
310
301
 
311
- **Coming from v0.5.x or earlier?** v0.7.0 is a breaking-shape release: symbol-form ops (`~`, `>`, `@`, `!`, `??`, `&`) and `$(VAR)` substitution are deprecated. They still compile in v0.7.x during the grace period; v0.7.1 ships visibility-nudge lints (`deprecated-symbol-op`, `deprecated-substitution-shape`); removal slated for v0.8.x or v0.9. The mechanical rewrite rules are documented in [`CHANGELOG.md`](CHANGELOG.md) under `## 0.7.0 — Migration`. Most adopters writing new skills against canonical surface won't need to migrate anything.
302
+ ### `connectors.json`
312
303
 
313
- ### `connectors.json` (v0.4.0)
304
+ Per-host configuration. The runtime loads it at startup. Two top-level concerns:
314
305
 
315
- Per-host MCP connector configuration. The runtime loads it at startup; each top-level entry becomes a named connector instance referenced via `$ name.tool` in skill source.
306
+ 1. **`substrate`** which `SkillStore` / `MemoryStore` / `LocalModel` the runtime hosts use
307
+ 2. **Named MCP connector instances** — each becomes a connector referenced via `$ <name>` in skill source
316
308
 
317
309
  ```json
318
310
  {
311
+ "substrate": {
312
+ "skill_store": "sqlite",
313
+ "memory_store": "sqlite",
314
+ "local_model": null
315
+ },
316
+
319
317
  "youtrack": {
320
318
  "class": "RemoteMcpConnector",
321
319
  "config": {
@@ -327,6 +325,8 @@ Per-host MCP connector configuration. The runtime loads it at startup; each top-
327
325
  }
328
326
  ```
329
327
 
328
+ Substrate short-form (`"sqlite"` etc.) wires bundled defaults. Object form (`{type, config}`) overrides config. See **[`docs/configuration.md`](docs/configuration.md)** for the full schema + adopter-custom impl path.
329
+
330
330
  Two credential shapes:
331
331
 
332
332
  - **Literal**: `"AUTH_HEADER": "Bearer plnt-XXX..."` — the credential lives in the file
@@ -334,11 +334,11 @@ Two credential shapes:
334
334
 
335
335
  **Credential discipline (hard requirement):** `connectors.json` is secret-bearing. The repo's `.gitignore` excludes it by default. Use the version-controlled `connectors.json.example` as the template — copy it to `connectors.json` (gitignored), fill in real values. For deployments, prefer `${VAR}` substitution over in-file literals; commit the `${...}` references but keep the actual credentials in deployment env.
336
336
 
337
- **Closed-set class registry:** the runtime ships a fixed list of `class:` values it recognizes. v0.4.0 ships with `CallbackMcpConnector` (wired via embedder code only, not configurable from JSON). v0.4.1 adds `RemoteMcpConnector` for the stdio-bridged remote MCP pattern. Plugin-style runtime-arbitrary class loading is deliberately out of scope — see [ARCHITECTURE.md](ARCHITECTURE.md) for the rationale. Use `runtime_capabilities({include:["mcpConnectorClasses"]})` to introspect the available set in your runtime.
337
+ **Closed-set class registry:** the runtime ships a fixed list of `class:` values it recognizes. `RemoteMcpConnector` is the JSON-instantiable class for the stdio-bridged remote MCP pattern; `CallbackMcpConnector` is wired via embedder code only (not configurable from JSON). Plugin-style runtime-arbitrary class loading is deliberately out of scope — see [ARCHITECTURE.md](ARCHITECTURE.md) for the rationale. Use `runtime_capabilities({include:["mcpConnectorClasses"]})` to introspect the available set in your runtime.
338
338
 
339
339
  ## CLI
340
340
 
341
- 14 commands cover the full authoring + ops lifecycle:
341
+ 15 commands cover the full authoring + ops lifecycle:
342
342
 
343
343
  | Command | Purpose |
344
344
  |---|---|
@@ -352,9 +352,11 @@ Two credential shapes:
352
352
  | `skillfile verify <path\|name> <hash>` | Verify against a known signature |
353
353
  | `skillfile replay <trace_id>` | Re-run from a captured trace |
354
354
  | `skillfile health` | Aggregate runtime health metrics |
355
+ | `skillfile register-trigger <skill> <source> <name>` | Register an imperative trigger |
356
+ | `skillfile unregister-trigger <trigger_id>` | Remove a registered trigger |
357
+ | `skillfile list-triggers` | List registered triggers |
355
358
  | `skillfile serve [--port N]` | Headless: scheduler + MCP server, no SPA |
356
359
  | `skillfile dashboard [--port N]` | Same as `serve` plus dashboard SPA at `/` |
357
- | (Trigger management lives in the MCP surface, not the CLI) | |
358
360
 
359
361
  Run `skillfile <command> --help` for per-command flags. Use `serve` for production / containerized deployments and `dashboard` for development. CLI command names mirror the MCP tool names where they overlap (`execute` ↔ `execute_skill`, `compile` ↔ `compile_skill`, `lint` ↔ `lint_skill`), so authors who learn one surface can transfer immediately to the other.
360
362
 
@@ -375,39 +377,30 @@ This is the "agent reaches MCP" path — an external agent (Claude, GPT, anythin
375
377
 
376
378
  ## Examples
377
379
 
378
- Nine curated example skills in [`examples/`](examples/), migrated to canonical v0.7.0 syntax, covering:
380
+ Curated example skills in [`examples/`](examples/), covering:
379
381
 
380
382
  - Multi-target DAG with `needs:` dependencies
381
383
  - Cron triggers with `# OnError:` fallback
382
- - Session-start `prompt-context:` delivery
384
+ - Session-start `# Output: agent:` delivery
383
385
  - `ask(prompt=...)` interactive pattern
384
386
  - `# Requires:` cascade for compile-time data
385
387
  - `inline(skill=...)` skill composition
386
388
  - `execute_skill(...)` skill-to-skill composition
387
389
 
388
- Each example is annotated with the language pattern it demonstrates. The pre-v0.7.0 cold-author harness corpus (R1/R2/R3 from v0.2.9 production) was retired in the v0.7.0 syntax revamp — pre-adoption means no external users depend on backwards-compat regression coverage. The R4 harness round will produce fresh canonical-form fixtures.
390
+ Each example is annotated with the language pattern it demonstrates.
389
391
 
390
392
  ## Architecture and deep documentation
391
393
 
392
- - **[Language Reference](docs/language-reference.md)** — canonical spec (1600+ lines, 13 sections). The single source of truth on syntax + semantics.
394
+ - **[Language Reference](docs/language-reference.md)** — canonical spec. The single source of truth on syntax + semantics.
395
+ - **[Configuration](docs/configuration.md)** — `connectors.json` substrate selection + named MCP connector wiring + adopter-custom impl path.
396
+ - **[Adopter Playbook](docs/adopter-playbook.md)** — patterns for adopters embedding skillscript-runtime in their own deployment.
397
+ - **[Connector Contract Reference](docs/connector-contract-reference.md)** — interface contracts for adopters writing their own connector impls.
398
+ - **[SqliteSkillStore](docs/sqlite-skill-store.md)** — the bundled DB-backed SkillStore: schema, semantics, forking checklist.
393
399
  - **ROADMAP** — *coming soon to docs/*
394
400
 
395
401
  ## Status
396
402
 
397
- **v0.7.3** — pre-1.0, breaking changes still expected through the v0.7→v1.0 arc. The language *shape* locked at v0.7.2 (`${VAR}` substitution, function-call op grammar, substrate-portable connectors); v0.7.3 hardens the adopter surface (canonical config externalization, public `registerConnectorClass` API, onboarding scaffold + adopter playbook, OutputKind substrate-neutrality cleanup).
398
-
399
- Test coverage: 998/999 passing (10 skipped, 1 env-gated YouTrack). Narrow-core LOC under the budget per ERD.
400
-
401
- What's coming next (per the v0.7.3 → v1.0 roadmap settled in `076bdeac`):
402
- - **v0.8.0** — auth model + `$ memory_write` bundled. Mixed model: op-level mutations passthrough (substrate enforces; runtime threads credentials); skill-level `Draft → Approved` runtime-enforced (non-author signer required). Drops `unconfirmed-mutation` lint under passthrough. New-version-of-same-name returns to Draft on content change. `MemoryStore.write()` contract extension ships `$ memory_write` against the new auth model. See thread `43178c86` for the settled design.
403
- - **R7 cold-author harness** (post-v0.7.3 ship) — empirically tests NFR-6 agent-modifiability against the v0.7.3 file layout. Cold agent adds a filter, a lint rule, and a runtime-intrinsic op; failure modes target which extension point to refactor first. Evidence before refactor.
404
- - **v0.8.x** — tool-schema introspection: `describe_connector(name)` MCP tool exposes per-tool JSON-Schema from MCP `tools/list`; compile-time `mcp-arg-out-of-range` + `mcp-unknown-kwarg` lints
405
- - **v0.9** — pagination / `while` loop primitive; `search_skills` MCP tool for cross-agent discovery; skill-evaluation feedback loop
406
- - **v0.10** — reference `AgentConnector` impls (webhook, memory-handoff) shipped concretely; `# Output:` channel posture explicit
407
- - **v0.11** — Phase 2 trigger sources (event + agent-event + file-watch + sensor)
408
- - **v0.12** — emit-as-binding + op-level `(fallback:)` uniformity; `# Tests:` block
409
- - **v0.13+** — observability for scale-out (per-skill latency/error-rate/aggregate panels); portability stress-test scaffold (vector-DB memory + hosted-API LLM + webhook AgentConnector) as v1.0 gate prep
410
- - **v1.0** — API stability commitment, gates on first external adopter shipping against canonical contracts against a substrate that isn't AMP (not just harness rounds)
403
+ Pre-1.0, no external adopters. Core language stable; connector contracts locked; distribution polish in progress.
411
404
 
412
405
  ## Contributing
413
406
 
@@ -1,16 +1,22 @@
1
1
  import { Registry } from "./connectors/registry.js";
2
- import { FilesystemSkillStore } from "./connectors/skill-store.js";
3
2
  import { FilesystemTraceStore } from "./trace.js";
4
3
  import { Scheduler, type TriggerRegistration } from "./scheduler.js";
5
4
  import type { TraceConfig } from "./trace.js";
6
5
  import { McpServer } from "./mcp-server.js";
6
+ import type { SkillStore, MemoryStore, LocalModel } from "./connectors/types.js";
7
7
  export interface BootstrapOpts {
8
8
  skillsDir: string;
9
9
  traceDir: string;
10
10
  /** When set + existing, register `SqliteMemoryStore` as primary memory_store. */
11
11
  memoryDbPath?: string;
12
- /** Override `OLLAMA_BASE_URL` env default. */
13
- ollamaBaseUrl?: string;
12
+ /** Override the bundled-default SkillStore. v0.10 — threaded by the CLI when
13
+ * `connectors.json` substrate config selects sqlite / adopter-custom. */
14
+ skillStore?: SkillStore;
15
+ /** Override the conditional Sqlite MemoryStore wiring. */
16
+ memoryStore?: MemoryStore;
17
+ /** Optional LocalModel to register as `"default"`. v0.10 — base config is
18
+ * null; adopters wire explicitly via `connectors.json` or this opt. */
19
+ localModel?: LocalModel;
14
20
  /** Scheduler poll interval (default 30s). */
15
21
  pollIntervalSeconds?: number;
16
22
  /** Forwarded to scheduler/runtime. Default false. */
@@ -43,7 +49,10 @@ export interface BootstrapResult {
43
49
  registry: Registry;
44
50
  scheduler: Scheduler;
45
51
  mcpServer: McpServer;
46
- skillStore: FilesystemSkillStore;
52
+ /** v0.10 — generalized from concrete `FilesystemSkillStore` to the
53
+ * `SkillStore` interface since the connector is now configurable via
54
+ * `connectors.json` substrate config. */
55
+ skillStore: SkillStore;
47
56
  traceStore: FilesystemTraceStore;
48
57
  /** Read back so runtime_capabilities can surface the active mode. */
49
58
  enableUnsafeShell: boolean;
@@ -62,28 +71,58 @@ export interface BootstrapResult {
62
71
  export interface DefaultRegistryOpts {
63
72
  skillsDir: string;
64
73
  memoryDbPath?: string;
65
- ollamaBaseUrl?: string;
74
+ /**
75
+ * Override the bundled-default SkillStore. When supplied, used instead of
76
+ * `new FilesystemSkillStore(skillsDir)`. Threaded through by the CLI when
77
+ * `connectors.json` substrate config selects sqlite or adopter-custom.
78
+ */
79
+ skillStore?: SkillStore;
80
+ /**
81
+ * Override the conditional-Sqlite MemoryStore wiring. When supplied, used
82
+ * instead of the `memoryDbPath`-conditional `SqliteMemoryStore`.
83
+ */
84
+ memoryStore?: MemoryStore;
85
+ /**
86
+ * Optional LocalModel to register as `"default"`. **v0.10 — base config:
87
+ * LocalModel is NULL unless explicitly provided.** Adopters wanting Ollama
88
+ * (or any other LocalModel) wire it explicitly via `connectors.json`
89
+ * substrate config or by passing here.
90
+ */
91
+ localModel?: LocalModel;
66
92
  }
67
93
  /**
68
- * Build the default connector registry: primary SkillStore + primary
69
- * MemoryStore (if the db file/directory exists) + three named LocalModels
70
- * pointed at Ollama. Used by both `bootstrap()` (long-lived host) and the
71
- * `skillfile run` one-shot path so both surfaces wire the same defaults.
94
+ * Build the default connector registry: primary SkillStore (configurable),
95
+ * primary MemoryStore (configurable / conditional), and optional LocalModel
96
+ * (null by default — v0.10). Used by both `bootstrap()` (long-lived host)
97
+ * and the `skillfile run` one-shot path so both surfaces wire the same
98
+ * defaults.
99
+ *
100
+ * **v0.10 base config**:
101
+ * skill_store → FilesystemSkillStore (override via `opts.skillStore`)
102
+ * memory_store → SqliteMemoryStore (conditional on `memoryDbPath`)
103
+ * local_model → null (override via `opts.localModel`)
104
+ * mcp_connector → null (adopter wires via `connectors.json`)
105
+ * agent_connector → null (adopter wires explicitly)
72
106
  */
73
107
  export declare function defaultRegistry(opts: DefaultRegistryOpts): {
74
108
  registry: Registry;
75
- skillStore: FilesystemSkillStore;
109
+ skillStore: SkillStore;
76
110
  };
77
111
  /**
78
- * Construct the runtime surface with bundled-default substrate wiring.
112
+ * Construct the runtime surface with configurable substrate wiring.
113
+ *
114
+ * **Reference deployment, v0.10.** Base config:
115
+ * - `FilesystemSkillStore` (override via `opts.skillStore` or `connectors.json` substrate)
116
+ * - `SqliteMemoryStore` (conditional on `memoryDbPath`; override via `opts.memoryStore`)
117
+ * - LocalModel `null` (provide via `opts.localModel` or `connectors.json` substrate)
118
+ * - v0.7.2 MCP bridges (`llm`, `memory`, `memory_write`) wired when their
119
+ * substrates exist
120
+ * - Any `McpConnector` declared in `connectors.json`
79
121
  *
80
- * **Reference deployment.** This function wires `FilesystemSkillStore`,
81
- * `OllamaLocalModel` (`default` / `gemma2` / `qwen`), `SqliteMemoryStore`
82
- * (if `memoryDbPath` is set + the file/dir exists), the v0.7.2 bridge
83
- * connectors (`llm` + `memory`), and any `McpConnector` declared in
84
- * `connectors.json`. Adopters wanting custom substrate wiring should write
85
- * their own bootstrap that imports the public APIs (Registry, the
86
- * individual connector classes, `loadConnectorsConfig`, etc.) directly.
122
+ * Adopters wanting custom substrate wiring write `connectors.json` with a
123
+ * `substrate` section (per `docs/sqlite-skill-store.md`) OR write their own
124
+ * bootstrap that imports the public APIs (Registry, individual connector
125
+ * classes, `loadConnectorsConfig`, etc.) directly.
87
126
  *
88
127
  * Caller is expected to:
89
128
  * 1. Optionally call `wireDeclarativeTriggers(result)` to register
@@ -1 +1 @@
1
- {"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAMnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,SAAS,EAAgC,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACnG,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;IACpB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG,WAAW,CAAC;IAC7B;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;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;IAC3B,sEAAsE;IACtE,IAAI,EAAE,OAAO,GAAG,WAAW,CAAC;IAC5B,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,wBAAwB,EAAE,MAAM,EAAE,CAAC;IACnC,gHAAgH;IAChH,qBAAqB,EAAE,MAAM,EAAE,CAAC;CACjC;AAuCD,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,CAkCnH;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,eAAe,CAqF9D;AAED;;;;;GAKG;AACH;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,MAAM,EACZ,GAAG,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAA4D,GACjF;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAkDpC;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,aAAa,CAAC,mBAAmB,CAAC,GAC3C,IAAI,CAqBN;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"}
1
+ {"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"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"}