@directive-run/claude-plugin 1.18.0 → 1.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@directive-run/claude-plugin",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "description": "Claude Code plugin for Directive — 12 skills covering modules, constraints, resolvers, derivations, AI orchestration, and adapters. Installable via Claude Code's plugin marketplace or consumable programmatically as an npm package.",
   "license": "(MIT OR Apache-2.0)",
   "author": "Jason Comes",
@@ -52,7 +52,7 @@
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
     "vitest": "^3.0.0",
-    "@directive-run/knowledge": "1.18.0"
+    "@directive-run/knowledge": "1.19.0"
   },
   "scripts": {
     "build": "tsx scripts/build-skills.ts && tsup",

package/skills/building-ai-agents/ai-sources.md

@@ -101,9 +101,6 @@ const result = orchestrator.runStream(agent, input, {
     system,                                   // the Directive system whose facts feed the agent
     keys: ["pr.headSha", "pr.state"],         // REQUIRED — fact keys to watch
     interruptWhen: (facts, changedKeys) => boolean,  // optional; default: () => true
-    mode: "inject-system-message",            // shipped today (default behavior).
-                                              // "restart" reserved for follow-up minor;
-                                              // behaves identically to inject-system-message today.
     notifyOn: "interrupt-only",               // default; "all-changes" emits chunk per watched change
     onContextUpdate: (changedKeys) => void,   // optional logging hook
   },
@@ -170,26 +167,50 @@ threat model.
 
 ## MCP Lifecycle as a Source
 
-`@directive-run/ai/mcp` already exposes `MCPAdapterConfig.events`
-(`onConnect`, `onDisconnect`, `onToolCall`, ...) as callback hooks. The
-canonical adapter wraps those callbacks into a source on the
-orchestrator's module:
+`@directive-run/ai/mcp` exposes `MCPAdapterConfig.events`
+(`onConnect`, `onDisconnect`, `onToolCall`, `onError`, ...) as a single
+bag of callbacks set at adapter-construction time. To bridge the
+adapter's lifecycle into a Directive source the recipe is: declare a
+holder that the source's `attach` populates with the live `publish`,
+then point the adapter's `events.onConnect` / `onDisconnect` at the
+holder. The holder pattern lets you construct the adapter and the
+source in either order — the source's mount/unmount drives which
+publish closure (if any) receives lifecycle events.
 
 ```ts
 import { createSystem, createModule, t } from "@directive-run/core";
+import type { SourcePublish } from "@directive-run/core";
 import { createMCPAdapter } from "@directive-run/ai/mcp";
 
-const adapter = createMCPAdapter({ /* ... */ });
+// Holder that the source's `attach` populates. The adapter's events
+// forward through this — when the source is detached (`attach`'s
+// unsubscribe runs), the holder goes null and the adapter callbacks
+// no-op. This guarantees post-stop lifecycle events from the MCP
+// transport can't write into a torn-down system.
+let publishRef: SourcePublish | null = null;
+
+const adapter = createMCPAdapter({
+  servers: [/* ... */],
+  events: {
+    onConnect: (name) => publishRef?.("MCP_SERVER_CONNECTED", { name }),
+    onDisconnect: (name) => publishRef?.("MCP_SERVER_DISCONNECTED", { name }),
+  },
+});
 
 const orchestrator = createModule("orchestrator", {
   schema: {
     facts: {
-      mcp: t.object<{ servers: Record<string, "connected" | "disconnected"> }>(),
+      mcp: t.object<{
+        servers: Record<string, "connected" | "disconnected">;
+      }>(),
     },
     events: {
       MCP_SERVER_CONNECTED: { name: t.string() },
       MCP_SERVER_DISCONNECTED: { name: t.string() },
     },
+    derivations: {
+      allServersHealthy: t.boolean(),
+    },
   },
   init: (f) => {
     f.mcp = { servers: {} };
@@ -209,21 +230,19 @@ const orchestrator = createModule("orchestrator", {
     },
   },
   derive: {
-    allServersHealthy: (f) =>
-      Object.values(f.mcp.servers).every((s) => s === "connected"),
+    allServersHealthy: (facts) =>
+      Object.values(facts.mcp.servers).every((s) => s === "connected"),
   },
   sources: {
     mcpLifecycle: {
       attach: (publish) => {
-        const off1 = adapter.onConnect((name) =>
-          publish("MCP_SERVER_CONNECTED", { name }),
-        );
-        const off2 = adapter.onDisconnect((name) =>
-          publish("MCP_SERVER_DISCONNECTED", { name }),
-        );
-        return () => {
-          off1();
-          off2();
+        publishRef = publish;
+        // Kick the adapter's connection lifecycle once the source is
+        // attached so the first `onConnect` flows into our publish.
+        void adapter.connect();
+        return async () => {
+          publishRef = null;
+          await adapter.disconnect();
         };
       },
     },
@@ -234,6 +253,14 @@ const orchestrator = createModule("orchestrator", {
 Constraints can now gate agent execution on
 `facts.allServersHealthy` — no separate health-check loop needed.
 
+> The holder + closure pattern is the canonical bridge from any
+> single-callback-bag third-party SDK (MCP, telemetry SDKs that take an
+> `onEvent` config at construction) into a Directive source. The
+> alternative — passing `publish` from inside `attach` into the
+> adapter's events — requires the adapter to be constructed AFTER the
+> source is created, which is awkward when the adapter is used outside
+> Directive too.
+
 ---
 
 ## Sources × Security

package/skills/writing-directive-modules/sources.md

@@ -421,4 +421,4 @@ sources: {
 - `anti-patterns.md` (#20) — "subscribe inside an effect / useEffect" anti-pattern; prefer sources.
 - `naming.md` — canonical-term entry for `sources` + cross-paradigm aliases (RxJS Observable, DOM EventTarget, XState callback actor, Supabase realtime).
 - [`../ai/ai-sources.md`](../ai/ai-sources.md) — AI integration: `runStream({ liveContext })`, MCP lifecycle as a source, the `@directive-run/sources/*` adapter subpaths.
-- [`../ai/ai-security.md`](../ai/ai-security.md#sources-pii--closing-the-fact-injection-bypass) — `createFactPIIGuardrail`: closes the source → fact → agent-prompt PII bypass. Wire whenever sources publish into facts the agent reads.
+- [`../ai/ai-security.md`](../ai/ai-security.md#sources--pii--closing-the-fact-injection-bypass) — `createFactPIIGuardrail`: closes the source → fact → agent-prompt PII bypass. Wire whenever sources publish into facts the agent reads.