@directive-run/claude-plugin 1.19.2 → 1.19.4

package/package.json

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

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

@@ -82,6 +82,30 @@ above), not a source. Wire it inside the orchestrator's constructor.
 
 ---
 
+## What other agent frameworks have (and don't)
+
+The closest comparable surfaces today, and what they cover:
+
+| Capability | Directive `runStream({ liveContext })` | LangChain / LangGraph | Vercel AI SDK | LlamaIndex |
+|---|---|---|---|---|
+| **Mid-generation fact updates from an external stream** | ✅ source primitive bridges the transport; `liveContext` watches fact keys; predicate decides interrupt vs. notify | partial — `Tool` callbacks can be invoked but no "fact store the LLM sees through" surface | partial — `streamText` exposes `onChunk` for the consumer but no mid-stream re-prompt | partial — `QueryEngine` re-runs are caller-driven |
+| **Declarative source / inbound subscription** | ✅ `source` primitive — engine owns mount/unmount; lifecycle observable | hand-rolled per integration (LangChain runnables don't own subscriptions) | n/a — Vercel AI is a streaming SDK, not a state engine | n/a — LlamaIndex is a retrieval framework |
+| **Interrupt + resume against the same subscription** | ✅ `result.interrupt(reason?)` keeps the fact subscription alive; caller re-prompts | callback orchestration on the consumer | abort signal only — no "resume against the same context" affordance | re-query each time |
+| **Tier 0 PII guard at the publish→fact boundary** | ✅ `createFactPIIGuardrail` — wired at `createSystem`; runs on every fact write | callback pattern; consumer wires per chain | input/output guardrails on the call; nothing at the fact-store / state-update boundary | Pydantic schema validation at the retrieval boundary |
+| **Source × OTel out of the box** | ✅ `attachSourcesToOtel` — one long-lived span per `(sourceId, moduleId)` | manual `with_config(callbacks=...)` plumbing | consumer wires `onChunk` into their tracer | manual |
+| **Multi-system reactive composition** | ✅ `liveContext.system` accepts ANY Directive system, even one not owned by the orchestrator | n/a — single-graph model | n/a | n/a |
+
+Directive's pitch is not "we're a better LangChain" — it's **"your
+state engine and your agent runtime share one fact store, so the agent
+sees the world change without you wiring callbacks."** The shipped
+1.x surface delivers that for inbound sources + abort-and-emit
+interruption; the queued follow-up RFC adds automatic re-prompt with
+merge strategies. See
+[RFC 0005's "Demo" section](../../docs/rfcs/0005-live-context-agent.md#demo-the-launch-video)
+for the 6-second launch GIF concept.
+
+---
+
 ## `runStream({ liveContext })` — Reactive Agents
 
 > The killer demo: the agent is mid-generation, a source publishes a fact
@@ -366,7 +390,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 |
 |---|---|---|
@@ -377,7 +407,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/getting-started-with-directive/choosing-primitives.md

@@ -0,0 +1,163 @@
+# Choosing the right primitive
+
+Directive ships six core primitives. Picking the wrong one — modeling
+business state as a derivation, or running a side effect inside a
+resolver — is the most common source of "Directive feels heavy"
+complaints. The framework rewards getting this right; this page is the
+decision matrix.
+
+## The six primitives
+
+| Primitive | Purpose | Reads | Writes | Triggers when |
+|---|---|---|---|---|
+| **`facts`** | Owned, mutable state | n/a | event handlers, `init`, resolvers, plugin pre-emit | the consumer writes to it |
+| **`derivations`** | Pure, cached read-only views of facts | facts + other derivations | nothing | watched dependency changes |
+| **`events`** | Typed mutation entry points | facts (via `f`) | facts (via `f`) | `system.events.name(payload)` or a source `publish` |
+| **`constraints`** | Declarative "when X, require Y" rules | facts + derivations | NOTHING (emits requirements) | watched dependency changes |
+| **`resolvers`** | Async work that fulfills a constraint's requirement | facts + derivations + `req.payload` | facts (via the resolver's `ctx.set`) | matched requirement enters the inflight queue |
+| **`effects`** | Side effects that fire on fact change | facts + derivations | nothing inside Directive (writes to the outside world) | watched dependency changes |
+| **`sources`** | External event streams mounted by the runtime | nothing | facts (via `publish` → event handler) | the external transport calls `publish(...)` |
+
+## Decision tree
+
+```
+Does this thing belong to my system's state?
+├── No  → it's external. Inbound or outbound?
+│        ├── Inbound (something happens out there, I want to react)
+│        │   ├── Once per ingest event (channel.on, addEventListener,
+│        │   │   setInterval poll, MCP notification) → `source`
+│        │   └── Continuous LLM token stream → AsyncIterable / runStream;
+│        │       NOT a source (the source owns the connection; the
+│        │       iterable owns the per-generation token sequence)
+│        └── Outbound (state changed, I want to tell the world)
+│            ├── Async work I want to retry / cancel / dedupe →
+│            │   `resolver` (paired with a `constraint`)
+│            └── Fire-and-forget side effect (log, ping, animate) →
+│                `effect`
+└── Yes → does it change over time?
+         ├── Yes  → `fact` (declare in `schema.facts`, mutate via
+         │         `events:` handlers and resolver `ctx.set`)
+         └── No  → it's computed from other facts → `derivation`
+                  (declare in `schema.derivations`, compute in `derive:`)
+
+Then: does anything need to RUN when this changes?
+├── A rule must trigger and require async work → `constraint`
+│   (declarative `when`; emits a requirement; a `resolver` fulfills it)
+├── A side effect that just runs → `effect`
+└── Nothing — the LLM / hook / view just reads it next time → done
+```
+
+## Side-by-side comparisons
+
+### `effect` vs `source`
+
+The most common confusion. Both wrap something that fires "when
+something changes."
+
+| | `effect` | `source` |
+|---|---|---|
+| Direction | **Outbound** — your state changes, code runs | **Inbound** — the world changes, your state updates |
+| Trigger | watched facts / derivations change | external transport calls `publish` |
+| Body | imperative side effect | call `publish(eventName, payload)` |
+| Lifecycle | per fact change | mount-once at `start`, detach at `stop` |
+| Owner | tied to a fact/derivation watcher | owns its external transport (channel, socket, listener) |
+| Replaces | hand-rolled `useEffect(() => { /* writes elsewhere */ }, [factA])` | hand-rolled `useEffect(() => { subscribe(); return unsub; }, [])` |
+
+If the `useEffect` body is `subscribe + return unsubscribe`, declare a
+source. If the `useEffect` body is `do something external because some
+fact changed`, declare an effect.
+
+### `derivation` vs `resolver` vs `effect`
+
+All three "react to fact changes." Pick by what they OWN:
+
+| | `derivation` | `resolver` | `effect` |
+|---|---|---|---|
+| Owns a **value** | YES (the computed result) | NO | NO |
+| Owns a **promise** | NO | YES (retries, cancels, dedupes) | NO (fire-and-forget) |
+| Owns a **side effect** | NO (pure) | NO (writes facts via `ctx.set`) | YES |
+| Reruns on input change | always (cached) | NEVER automatically — only when the constraint emits a new requirement | always |
+| Can be `await`-ed externally | n/a (read synchronously) | YES (constraints + `system.settle()`) | NO |
+| Wrong-choice symptom | "I want a fact but it's always derived" → fact; "I want side effects" → effect | "I want this to retry but it doesn't" → likely should be an effect; "I want this to run every render" → likely should be a derivation | "I want to write a fact based on the change" → likely should be a resolver |
+
+### `event` vs `resolver`
+
+Both can write facts. Pick by who calls them:
+
+| | `event` | `resolver` |
+|---|---|---|
+| Caller | external code (`system.events.name(payload)`) OR a source's `publish` | the engine, when a constraint emits a matching requirement |
+| Body | synchronous mutation via `f` accessor | async, can retry, can await |
+| Best for | user actions, source-driven mutations, deterministic state transitions | async work whose result is a fact update |
+
+A typical pattern: `event` ingests raw data, `derivation` computes a
+"needs sync?" flag, `constraint` triggers when the flag is true,
+`resolver` does the async work, on success writes the result back via
+another `event`. The same fact pipeline doesn't mix `events` and
+`resolvers` for the SAME write — events are user/source-driven; resolvers
+are engine-driven.
+
+### `constraint` vs `derivation` (predicates)
+
+Both can hold `when` predicates. Different jobs:
+
+- **`derivation`** evaluates an expression against the current facts
+  and returns a value. It's a noun. Other constraints / effects can
+  watch it.
+- **`constraint`** evaluates a `when` predicate and, when it matches,
+  emits a `requirement` object that a resolver pattern-matches and
+  fulfills. It's a verb. Constraints never write — they describe what
+  the world MUST do.
+
+The constraint's `when` may reference a derivation; that's the canonical
+pattern (compute the condition cheaply once; multiple constraints share
+it).
+
+## Worked example
+
+You're building a chat app that mirrors a Supabase realtime channel,
+calls a moderation API on each message, and displays the result.
+
+| Layer | Primitive | Why |
+|---|---|---|
+| `messages: t.array<Message>()` | `fact` | mutable list owned by this module |
+| `unmoderated: t.array<Id>()` | `derivation` | filtered view of `messages` where `verdict === null` |
+| `realtime` (the broker subscription) | `source` | mount-once external event stream → `publish('MESSAGE_RECEIVED', row)` |
+| `MESSAGE_RECEIVED` handler | `event` | source-driven mutation; writes the row into `messages` |
+| `moderateUnverified` | `constraint` + `resolver` | constraint emits `MODERATE` requirements for each `unmoderated` id; resolver calls the moderation API + writes `MODERATION_COMPLETE` |
+| `MODERATION_COMPLETE` handler | `event` | engine-driven mutation; sets `verdict` on the message |
+| `announceFlag` | `effect` | watches `unmoderated`, posts to #alerts when count crosses a threshold |
+| `mcpHealthCheck` | `source` | the moderation API has a status SSE; mount once, publish health changes |
+
+Every external touch is a `source` or a `resolver`. Every state field
+is a `fact` or a `derivation`. Every "must-happen rule" is a
+`constraint`. Every "do this when X" is an `effect`. Six primitives,
+seven pieces of work, zero `useEffect` hooks.
+
+## When you find yourself wanting to break the model
+
+- "I want to call `set` from inside a derivation" — you wanted a
+  resolver (the work has a result that's a fact update).
+- "I want my effect to retry" — you wanted a resolver (resolvers
+  have retry config; effects don't).
+- "I want my source to write multiple facts at once" — declare an
+  event whose handler does the batch write; the source publishes the
+  event with the batch payload.
+- "I want to write a fact from a constraint" — you wanted a
+  resolver. Constraints declare; resolvers do.
+- "I have a value that's derived from outside state (URL, env, time)"
+  — declare it as a `fact` whose `init` reads the external value,
+  and use a `source` if it changes (e.g. `popstate` listener).
+
+## Related
+
+- [`core-patterns.md`](./core-patterns.md) — module composition and
+  the recommended structure of a module file.
+- [`sources.md`](./sources.md) — the source primitive's full lifecycle
+  and recipes.
+- [`constraints.md`](./constraints.md) — `when` predicates, requirement
+  shapes, and the `bind` / `owns` field-scoped CAS contract.
+- [`resolvers.md`](./resolvers.md) — retry config, batch semantics, and
+  the `ctx.set` write contract.
+- [`anti-patterns.md`](./anti-patterns.md) — the things to avoid that
+  every Directive consumer eventually tries.

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