@directive-run/claude-plugin 1.19.1 → 1.19.3

package/package.json

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

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

@@ -189,11 +189,13 @@ publish closure (if any) receives lifecycle events.
 > 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.
+> first tenant's pipe. **Always construct BOTH the adapter AND the
+> module inside the same factory function** so the adapter's
+> `events` callbacks close over the same factory-local `publishRef`
+> as the source's `attach`. Sharing an adapter across factory calls
+> re-introduces the cross-contamination because the adapter's
+> `events.onConnect` was bound at construction time to whichever
+> factory's `publishRef` was in scope first.
 
 ```ts
 import { createSystem, createModule, t } from "@directive-run/core";
@@ -364,7 +366,13 @@ that should accompany this plugin in regulated deployments.
 ## Adapter packages
 
 The canonical bridges live in **`@directive-run/sources`** as subpath
-exports. One install, optional peerDependencies per vendor.
+exports. One install, optional peerDependencies per vendor:
+
+```bash
+pnpm add @directive-run/sources                              # umbrella
+pnpm add @directive-run/sources @supabase/supabase-js        # + supabase
+pnpm add @directive-run/sources @cloudflare/workers-types    # + cloudflare (devDep)
+```
 
 | Subpath | Source factory | Wraps |
 |---|---|---|
@@ -375,7 +383,57 @@ exports. One install, optional peerDependencies per vendor.
 | `@directive-run/sources/sentry` | `sourceFromSentryHook()` | (future RFC) Sentry production-error stream |
 
 Install only the umbrella; the vendor peerDeps are optional and pull in
-only when the corresponding subpath is imported.
+only when the corresponding subpath is imported. `package.json` marks
+both `@supabase/supabase-js` and `@cloudflare/workers-types` as
+optional peer dependencies — consumers using only one subpath get no
+install-error nag for the other.
+
+---
+
+## Observability — pipe `source.*` events to OpenTelemetry
+
+`attachSourcesToOtel(system, { tracer, serviceName })` bridges the
+`system.observe()` source lifecycle (`source.attach` / `.publish` /
+`.detach` / `.error`) into OTel spans. Pairs with `createOtelPlugin`
+which exports the agent-side trace surface; the two together cover
+the entire publish-to-prompt pipeline:
+
+```ts
+import { createAgentOrchestrator, createOtelPlugin } from "@directive-run/ai";
+import { attachSourcesToOtel } from "@directive-run/ai";
+import { trace } from "@opentelemetry/api";
+
+const tracer = trace.getTracer("agent-service", "1.0.0");
+
+const orchestrator = createAgentOrchestrator({
+  runner: anthropic(/* ... */),
+  plugins: [createOtelPlugin({ tracer })],
+});
+
+// One long-lived span per (sourceId, moduleId); publishes land as span
+// events on the parent attach span (cardinality-budgeted).
+const unsub = attachSourcesToOtel(system, {
+  tracer,
+  serviceName: "agent-service",
+  // Optional: throttle high-frequency publishes (default 1 = every publish).
+  publishSampleRate: 1,
+});
+
+// On `system.destroy()` / `evict()`, call unsub to close any open spans.
+```
+
+What you see in your trace backend:
+- `directive.source.attached` — long-lived span; closes on `detach` with
+  OK status, or on `unsub()` with `directive.detached: true` attribute.
+- Span events (`publish`) on the parent span with `source.event_name`
+  attribute and a wall-clock timestamp.
+- `directive.source.error` spans with `phase: "attach" | "cleanup" |
+  "runtime"` and the truncated error message.
+
+This complements `createOtelPlugin`'s agent-span coverage so an SRE
+debugging "agent stopped mid-stream" can trace back through
+`runStream` → `liveContext` interrupt → the watched fact → the source
+publish that triggered the change — one trace tree, no manual joins.
 
 ---
 

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

@@ -194,6 +194,17 @@ const unsub = system.observe((event) => {
 
 `system.inspect().sources` lists the declared sources + `system.inspect().attachedSourceCount` reports how many are currently bound.
 
+### Pipe `source.*` to OpenTelemetry
+
+For production observability, `@directive-run/ai` ships
+`attachSourcesToOtel(system, { tracer, serviceName })` which bridges
+the lifecycle into OTel spans (one long-lived span per
+`(sourceId, moduleId)`; publishes as span events; errors as
+`directive.source.error` spans tagged with `phase`). See
+[`../ai/ai-sources.md` § Observability](../ai/ai-sources.md#observability--pipe-source-events-to-opentelemetry)
+for the full recipe; nothing in core depends on OTel so the bridge
+lives next to the AI orchestrator's own span integration.
+
 ## Error handling — runtime errors via `reportError`
 
 Per RFC 0008, `attach` receives an optional second argument: a
@@ -314,6 +325,74 @@ sources: {
 Inside a DO `alarm()` or `webSocketClose()` handler:
 `await system.evict(/* deadline */ Date.now() + 5000)`.
 
+## Runtime compatibility
+
+The `source` primitive itself is runtime-agnostic — `attach`, `publish`,
+`unsubscribe`, `onEvict`, and `coalesce` only depend on `Promise`,
+`queueMicrotask`, and standard timers (all available in every modern
+JS runtime). The matrix below covers the SHIPPED adapters in
+`@directive-run/sources`; consumer-authored sources inherit each
+runtime's standard guarantees.
+
+| Runtime | Source primitive | `sourceFromSupabaseChannel` | `sourceFromDOAlarm` | `sourceFromWebSocketMessage` | Notes |
+|---|---|---|---|---|---|
+| **Cloudflare DO** | ✅ | ✅ (peerDep `@supabase/supabase-js` works in workerd) | ✅ default `onEvict` clears alarm | ✅ default `onEvict` closes socket 1001 | DO eviction recipe at top of this section; call `await system.evict(deadline)` from `alarm()` / `webSocketClose()`. |
+| **Cloudflare Workers** | ✅ | ✅ | ✅ (needs DO `storage` handle) | ✅ (needs DO `WebSocket` handle) | Same recipes as DO; the 30s wall-clock budget applies to `cleanupAllAsync`. |
+| **Bun** | ✅ | ✅ (Bun supports the `ws` transport supabase uses) | n/a (DO API) | n/a (DO API) | Sync `stop()` + async `stopAsync()` both work; Bun supports top-level `await`. |
+| **Deno** | ✅ | ✅ via `npm:` specifier; needs `--allow-net` | n/a (DO API) | n/a (DO API) | Permissions: `--allow-net` for any transport; `--allow-env` for SUPABASE_URL / SUPABASE_KEY. |
+| **Browser** | ✅ | ✅ | n/a (DO API) | partial — DOM `WebSocket` works with a thin adapter; the Cloudflare-typed helper is DO-specific | DOM `addEventListener` / `BroadcastChannel` / `visibilitychange` recipes inline above. |
+| **Node** | ✅ | ✅ | n/a (DO API) | n/a (DO API) | Test target; vitest exercises every source path. |
+
+The `@directive-run/sandbox` validator allowlists `@directive-run/sources`
+and both subpaths, so the playground / `run_in_sandbox` MCP tool / docs
+live runner all accept source-using snippets.
+
+### Polling — when a transport is request/response only
+
+When the upstream system has no push channel (REST endpoint, a polled
+status URL, a `setInterval`-driven heartbeat), declare a polling source.
+The runtime owns mount/unmount, the `onEvict` hook lets you cancel any
+pending fetch before hibernation, and the engine's batching keeps the
+per-tick fact mutations cheap:
+
+```typescript
+sources: {
+  status: {
+    attach: (publish, reportError) => {
+      const controller = new AbortController();
+      const tick = async () => {
+        try {
+          const res = await fetch(statusUrl, { signal: controller.signal });
+          const body = await res.json();
+          publish("STATUS_TICK", body);
+        } catch (err) {
+          // RFC 0008 — runtime errors go through reportError so they
+          // route to source.error with phase: "runtime"; the source
+          // stays attached.
+          if ((err as { name?: string }).name !== "AbortError") {
+            reportError?.(err);
+          }
+        }
+      };
+      const id = setInterval(tick, 5_000);
+      void tick(); // first poll, immediate.
+      return () => {
+        clearInterval(id);
+        controller.abort();
+      };
+    },
+    coalesce: "lastWriteWins", // only the most recent tick survives a flush
+  },
+},
+```
+
+Choose the `coalesce` strategy that matches the consumer:
+- `"lastWriteWins"` — gauge / dashboard updates where stale ticks
+  don't matter.
+- `"none"` — counters / time-series where every tick must land.
+- `"all"` — currently an alias for `"none"`; reserved for future
+  bounded-buffer semantics (do not depend on it).
+
 ## Common Patterns
 
 ### Pattern: Source supplies inbound; resolver supplies outbound