@directive-run/claude-plugin 1.18.0 → 1.19.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@directive-run/claude-plugin",
-  "version": "1.18.0",
+  "version": "1.19.1",
   "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.1"
   },
   "scripts": {
     "build": "tsx scripts/build-skills.ts && tsup",

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

@@ -54,7 +54,11 @@ gate execution on `facts.<lifecycle>.healthy` derivations.
 - **MCP server connect/disconnect** → see "MCP Lifecycle" below.
 - **Health checks** → poll inside the source's `attach`; publish
   `health_changed` events as the upstream service responds.
-- **WebSocket open / close** → `sourceFromWebSocket()` (sources/websocket).
+- **WebSocket open / close (Cloudflare DO)** → `sourceFromWebSocketMessage()`
+  (`@directive-run/sources/cloudflare`). For raw Node/browser WebSocket
+  bridges, declare a source whose `attach` wires `addEventListener` and
+  publishes `MESSAGE` / `CLOSE` / `ERROR` events (a generic
+  `sourceFromWebSocket()` helper is queued for a follow-up RFC).
 
 ### "I want my agent's facts to update from a live external feed"
 
@@ -101,9 +105,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
   },
@@ -154,10 +155,14 @@ Two new chunk variants land on the stream:
 `runStream({ liveContext })` is the dedicated subject of
 [RFC 0005](../../docs/rfcs/0005-live-context-agent.md). Today's
 implementation is **231 LOC in `agent-orchestrator.ts`** — under the
-RFC's 300-LOC scope guard. The `mode: "restart"` automatic
-re-invocation is reserved for a follow-up minor; today both `mode`
-values produce identical behavior (the chunk-emission contract +
-abort wiring; consumers re-prompt via a fresh `runStream` call).
+RFC's 300-LOC scope guard. Behavior is **abort-and-emit**: when
+`interruptWhen` returns `true`, the orchestrator aborts the in-flight
+LLM run and emits an `interrupted` chunk with the partial output; the
+caller resumes by issuing a fresh `runStream` against the still-live
+subscription (or fully tears down via `result.abort()`). Automatic
+re-invocation (the "restart" semantic the original RFC drafted) is
+reserved for a follow-up RFC + field — the original `mode` field was
+removed before release because the impl never read it.
 
 **Security companion (mandatory when watched facts may carry PII):**
 wire `createFactPIIGuardrail` on the same Directive system. Without
@@ -170,70 +175,118 @@ 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.
+
+> **Multi-tenant safety.** If you import the module that owns the
+> holder from two places (e.g., a Worker that mounts one Directive
+> system per tenant DO), a module-level `let publishRef` would be
+> SHARED — the second tenant's `attach` would silently overwrite the
+> first tenant's pipe. **Always declare the holder + adapter inside a
+> factory function** so each call yields an isolated closure pair.
+> The recipe below uses `makeOrchestrator(adapter)` for exactly this
+> reason; if you create the adapter outside the factory, pass it in
+> per call too.
 
 ```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({ /* ... */ });
+// Factory closure — each call yields a fresh `(adapter, module)`
+// pair with its own `publishRef`. Multi-tenant safe; SSR / Vitest
+// hot-reload safe; one tenant's MCP traffic can never leak into
+// another tenant's facts.
+function makeOrchestrator() {
+  let publishRef: SourcePublish | null = null;
 
-const orchestrator = createModule("orchestrator", {
-  schema: {
-    facts: {
-      mcp: t.object<{ servers: Record<string, "connected" | "disconnected"> }>(),
-    },
+  const adapter = createMCPAdapter({
+    servers: [/* ... */],
     events: {
-      MCP_SERVER_CONNECTED: { name: t.string() },
-      MCP_SERVER_DISCONNECTED: { name: t.string() },
+      onConnect: (name) => publishRef?.("MCP_SERVER_CONNECTED", { name }),
+      onDisconnect: (name) =>
+        publishRef?.("MCP_SERVER_DISCONNECTED", { name }),
     },
-  },
-  init: (f) => {
-    f.mcp = { servers: {} };
-  },
-  events: {
-    MCP_SERVER_CONNECTED: (f, p) => {
-      f.mcp = {
-        ...f.mcp,
-        servers: { ...f.mcp.servers, [p.name]: "connected" },
-      };
+  });
+
+  const orchestrator = createModule("orchestrator", {
+    schema: {
+      facts: {
+        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(),
+      },
     },
-    MCP_SERVER_DISCONNECTED: (f, p) => {
-      f.mcp = {
-        ...f.mcp,
-        servers: { ...f.mcp.servers, [p.name]: "disconnected" },
-      };
+    init: (f) => {
+      f.mcp = { servers: {} };
     },
-  },
-  derive: {
-    allServersHealthy: (f) =>
-      Object.values(f.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();
+    events: {
+      MCP_SERVER_CONNECTED: (f, p) => {
+        f.mcp = {
+          ...f.mcp,
+          servers: { ...f.mcp.servers, [p.name]: "connected" },
+        };
+      },
+      MCP_SERVER_DISCONNECTED: (f, p) => {
+        f.mcp = {
+          ...f.mcp,
+          servers: { ...f.mcp.servers, [p.name]: "disconnected" },
         };
       },
     },
-  },
-});
+    derive: {
+      allServersHealthy: (facts) =>
+        Object.values(facts.mcp.servers).every((s) => s === "connected"),
+    },
+    sources: {
+      mcpLifecycle: {
+        attach: (publish) => {
+          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();
+          };
+        },
+      },
+    },
+  });
+
+  return { orchestrator, adapter };
+}
+
+// Per-tenant / per-request usage:
+const { orchestrator, adapter } = makeOrchestrator();
+const system = createSystem({ module: 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
@@ -317,7 +370,8 @@ exports. One install, optional peerDependencies per vendor.
 |---|---|---|
 | `@directive-run/sources/supabase` | `sourceFromSupabaseChannel()` | Supabase realtime channel |
 | `@directive-run/sources/cloudflare` | `sourceFromDOAlarm()` | Cloudflare Durable Object alarm |
-| `@directive-run/sources/websocket` | `sourceFromWebSocket()` | (future RFC) raw WebSocket |
+| `@directive-run/sources/cloudflare` | `sourceFromWebSocketMessage()` | Cloudflare Durable Object WebSocket message stream |
+| `@directive-run/sources/websocket` | `sourceFromWebSocket()` | (future RFC) raw browser / Node WebSocket |
 | `@directive-run/sources/sentry` | `sourceFromSentryHook()` | (future RFC) Sentry production-error stream |
 
 Install only the umbrella; the vendor peerDeps are optional and pull in

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

@@ -274,20 +274,38 @@ flushes return Promises) work with both sync and async teardown:
   wall-clock cutoff so the runtime can evict the isolate even if
   some sources hang.
 
+Use the **holder + closure** bridge pattern (the same shape the MCP
+recipe in `ai-sources.md` documents) so the `attach` and `onEvict`
+sibling closures share the channel handle:
+
 ```typescript
+// Holder shared between `attach` and `onEvict`. Both closures live
+// inside the same `sources` object; declaring the channel above them
+// keeps the handle reachable from both.
+let channel: RealtimeChannel | null = null;
+
 sources: {
   channel: {
     attach: (publish) => {
-      const ch = supabase.channel("game").subscribe();
-      ch.on("postgres_changes", { event: "UPDATE" }, (p) =>
+      channel = supabase.channel("game");
+      channel.on("postgres_changes", { event: "UPDATE" }, (p) =>
         publish("ROW_UPDATED", p),
       );
-      return () => ch.unsubscribe();  // returns a Promise
+      channel.subscribe();
+      // Per RFC 0009, the unsubscribe MAY return a Promise; awaiting
+      // it on `system.stopAsync()` ensures the broker has dropped the
+      // subscription before the next start cycle re-attaches.
+      return async () => {
+        if (channel) await supabase.removeChannel(channel);
+        channel = null;
+      };
     },
     onEvict: async () => {
       // Cloudflare DO hibernate signal: close the channel actively
       // so the broker drops the subscription before the isolate dies.
-      await supabase.removeChannel(ch);
+      // The unsubscribe will also run, but onEvict fires first and
+      // bounds the pre-hibernation work to a deadline.
+      if (channel) await supabase.removeChannel(channel);
     },
   },
 }
@@ -421,4 +439,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.