@directive-run/claude-plugin 1.17.1 → 1.18.0

package/package.json

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

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

@@ -0,0 +1,406 @@
+# AI × Sources
+
+> Wire `@directive-run/core`'s `source` primitive into `@directive-run/ai`
+> agents and orchestrators. Sources are how external event streams
+> (Supabase realtime, WebSockets, Cloudflare DO alarms, MCP server lifecycle)
+> publish into facts that agents reason over.
+
+The source primitive's full semantics live at
+[`../core/sources.md`](../core/sources.md). This doc covers the AI-specific
+patterns: which external streams to wire as a source vs. as an
+`AsyncIterable` (anti-pattern), how `runStream` reacts to live fact
+changes, how to keep PII out of agent prompts, and which existing
+adapter (`@directive-run/sources/*`) covers the common vendors.
+
+---
+
+## Decision: source vs AsyncIterable
+
+A long-running external stream can show up as a Directive **source** OR
+as a per-call **AsyncIterable**. The boundary is durable.
+
+| Use a **source** when... | Use an **AsyncIterable** when... |
+|---|---|
+| The stream's lifetime is the **system's lifetime** (Supabase realtime channel, WebSocket message stream, MCP server connection) | The stream's lifetime is **one agent generation** (LLM token stream from `runStream`, per-call SSE response) |
+| You want every message to update **facts** the agent reasons over | You want the LLM's output tokens delivered to a single caller |
+| The publisher cannot read facts | The consumer needs to act on each chunk synchronously |
+
+**Three-tier lifetime ladder:**
+
+1. **System source** (outermost): Supabase channel, MCP server, DO alarm,
+   WebSocket message stream. Mount at `system.start()`, tear down at
+   `system.stop()`.
+2. **Conversation subscription** (middle): per-agent message bus
+   subscription, PubSub topic subscription, per-agent breakpoint waiter.
+   Created in the orchestrator's constructor, cleaned up on
+   destroy. Lives across many generations.
+3. **Generation iterable** (innermost): the actual LLM token AsyncIterable
+   returned by `runStream`. Created per `runStream` call, ends when the
+   model finishes or `abort()` fires.
+
+Sources own the outermost ring; AsyncIterable owns the innermost; the
+middle ring is what `@directive-run/ai/communication` covers today.
+
+---
+
+## Recipes by user intent
+
+### "I want my agent to react to external lifecycle events"
+
+Wire the lifecycle as a source on the orchestrator's module. The agent
+sees fact-change reactions through its bound-facts view; resolvers can
+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).
+
+### "I want my agent's facts to update from a live external feed"
+
+This is the **live-context** pattern — the differentiator nobody in the
+agent-framework space has. See `runStream({ liveContext })` below for the
+full recipe. tl;dr: sources publish into facts; `liveContext` re-renders
+the agent's system prompt on each change AND can interrupt the stream
+when conditions warrant.
+
+### "I want to bridge a callback-based SDK into Directive"
+
+Wrap the SDK's `subscribe()` / `on('event')` API inside `attach(publish)`,
+forward the unsubscribe. Direct generalization of the source primitive —
+no AI-specific machinery required.
+
+### "I want to multiplex agent messages into the system"
+
+Use `createMessageBus` from `@directive-run/ai/communication` for
+per-agent messaging. The bus is a conversation-tier subscription (tier 2
+above), not a source. Wire it inside the orchestrator's constructor.
+
+---
+
+## `runStream({ liveContext })` — Reactive Agents
+
+> The killer demo: the agent is mid-generation, a source publishes a fact
+> update, the agent's NEXT token reflects the new state — or interrupts
+> the stream and re-prompts with fresh context. No external orchestration
+> required.
+
+### When to use
+
+- A market-data agent whose recommendation depends on live prices.
+- A coding agent reviewing a PR while commits keep landing.
+- A customer-support agent whose context updates when Stripe confirms a
+  refund mid-conversation.
+
+### Signature
+
+```ts
+const result = orchestrator.runStream(agent, input, {
+  signal,                                     // existing AbortSignal — terminates stream
+  liveContext: {
+    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
+  },
+});
+
+// New methods on the returned result:
+result.interrupt(reason?);  // cancel in-flight LLM run, KEEP liveContext alive
+result.abort();             // tear down stream + detach liveContext
+```
+
+Two new chunk variants land on the stream:
+
+```ts
+| { type: "context_updated"; changedKeys: readonly string[] }
+| {
+    type: "interrupted";
+    reason: string;
+    partialOutput: string;
+    changedKeys: readonly string[];
+  }
+```
+
+### Anatomy
+
+- The orchestrator subscribes to `system.facts.$store.subscribe(keys, ...)`
+  for the keys it depends on — the same bridge primitive that powers
+  breakpoints and approvals elsewhere in `agent-orchestrator.ts`.
+- The subscription wires up BEFORE the LLM run's IIFE starts, so a fact
+  change during the input-guardrail phase is observed correctly.
+- On each batch of fact changes that touches the watched keys:
+  - `liveContext.onContextUpdate(changedKeys)` fires (logging hook).
+  - `interruptWhen(facts, changedKeys)` runs.
+  - If it returns `true`, the orchestrator emits an `interrupted` chunk
+    with the partial output captured so far + the changed keys, then
+    aborts the in-flight LLM stream. The consumer's `for await` sees
+    the `interrupted` chunk before the final `error` chunk lands.
+  - If it returns `false` and `notifyOn === "all-changes"`, a
+    `context_updated` chunk is emitted. With the default
+    `"interrupt-only"`, no chunk is emitted for non-interrupting
+    changes.
+- `result.interrupt(reason?)` is the CALLER-driven counterpart: same
+  `interrupted` chunk, same abort, but the subscription stays attached
+  so the next caller-driven `runStream` continues against the live
+  fact stream without re-subscribing.
+
+### Status — shipped
+
+`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).
+
+**Security companion (mandatory when watched facts may carry PII):**
+wire `createFactPIIGuardrail` on the same Directive system. Without
+it, `liveContext` expands the source → fact → prompt PII bypass
+surface into mid-stream context updates. See the
+["Sources × Security"](#sources--security) section below for the full
+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:
+
+```ts
+import { createSystem, createModule, t } from "@directive-run/core";
+import { createMCPAdapter } from "@directive-run/ai/mcp";
+
+const adapter = createMCPAdapter({ /* ... */ });
+
+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() },
+    },
+  },
+  init: (f) => {
+    f.mcp = { servers: {} };
+  },
+  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: (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();
+        };
+      },
+    },
+  },
+});
+```
+
+Constraints can now gate agent execution on
+`facts.allServersHealthy` — no separate health-check loop needed.
+
+---
+
+## Sources × Security
+
+> A source can publish PII into a fact BEFORE any input guardrail runs.
+> The pattern is real and exploitable. ALWAYS wire `createFactPIIGuardrail`
+> when sources feed facts the agent will reason over.
+
+### The bypass chain
+
+1. Source wraps Supabase realtime: `subscribe('users', row => publish('USER_UPDATED', { email: row.email, ssn: row.ssn }))`.
+2. Event handler writes: `f.email = payload.email; f.ssn = payload.ssn;`.
+3. Agent prompt template embeds: `"Hello ${facts.email}, your record shows ${facts.ssn}..."`.
+4. `createPIIGuardrail` (input guardrail) only inspects the `input` argument
+   passed to `runStream(agent, input, ...)`. The facts injected into the
+   prompt are **not in `input`** — they flow through the resolver's
+   templating layer.
+5. The LLM call ships the PII. The audit ledger's `fact.change` entry
+   carries it. Devtools / breakpoint snapshots see it. Operators see it.
+
+### The fix — `createFactPIIGuardrail`
+
+A Directive plugin that scans every write to a `pii`-tagged fact and
+either redacts (default) or alerts:
+
+```ts
+import { createSystem } from "@directive-run/core";
+import { createFactPIIGuardrail } from "@directive-run/ai/guardrails";
+
+const system = createSystem({
+  module: customer,                 // schema tags `email` + `ssn` with `tags: ['pii']`
+  plugins: [
+    createFactPIIGuardrail({
+      mode: "redact",               // 'redact' (default) | 'alert'
+      types: ["ssn", "credit_card", "email"],
+      onBlocked: (key, detected) => {
+        Sentry.captureMessage(`pii redacted: ${key}`, { extra: { count: detected.length } });
+      },
+    }),
+  ],
+});
+```
+
+**Modes:**
+
+- `"redact"` (default, safest): rewrites the fact value via a follow-up
+  store write. The raw value briefly exists for one microtask while the
+  redaction lands; downstream subscribers that snapshot at that instant
+  see it; the LLM call after the next settle does not.
+- `"alert"`: fires `onBlocked` but does NOT mutate the fact. Use for
+  monitoring-only deployments where the source's transport is already
+  trusted and you want to page on every match without modifying state.
+
+The plugin scans `pii`-tagged facts auto-detected via `meta.byTag("pii")`,
+plus any `includeKeys` you list explicitly. The built-in regex matches
+SSN, credit card, and email; pass a `customDetector` for domain-specific
+patterns (internal account numbers, partner IDs).
+
+### Limitation — hard rejection needs an RFC
+
+Plugin hooks (`onFactSet`, `onFactsBatch`) are wrapped by the plugin
+manager's `safeCall`, so a `throw` from the guardrail can't actually
+reject the write. The `"redact"` mode handles this with a follow-up write;
+the `"alert"` mode is observation-only. Hard rejection at the publish
+boundary requires a pre-commit transform hook on the source primitive
+itself — that's tracked as a future RFC. For now: wire `"redact"` for
+safety, `"alert"` for monitoring.
+
+See also: [`ai-security.md`](./ai-security.md) — "Sources × PII" section
+for the full threat model and the additional output-side mitigations
+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.
+
+| Subpath | Source factory | Wraps |
+|---|---|---|
+| `@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/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.
+
+---
+
+## Anti-patterns
+
+### Anti-pattern A — Don't use a source for token streaming
+
+LLM tokens are a per-generation hot stream. Wrap them in an
+`AsyncIterable` (the existing `runStream` contract), not a source.
+
+```ts
+// WRONG — sources are mount-once; tokens are per-call
+sources: {
+  llmTokens: {
+    attach: (publish) => {
+      const stream = openai.chat.completions.create({ stream: true });
+      for await (const chunk of stream) {
+        publish("TOKEN", { content: chunk.choices[0].delta.content });
+      }
+      return () => stream.abort();
+    },
+  },
+},
+
+// RIGHT — tokens flow through the runStream AsyncIterable
+const result = orchestrator.runStream(agent, input);
+for await (const chunk of result.stream) {
+  if (chunk.type === "token") render(chunk.content);
+}
+```
+
+The rule: **source per connection; AsyncIterable per generation.**
+
+### Anti-pattern B — Don't poll an external system from a constraint
+
+Constraints model declarative when-then rules over facts. A
+`setInterval` inside a constraint smuggles a long-running subscription
+into a non-lifecycle hook.
+
+```ts
+// WRONG — constraint kicks off polling that lives forever
+constraints: {
+  pollLatest: {
+    when: (facts) => true,
+    require: { type: "POLL_INVENTORY" },
+  },
+},
+resolvers: {
+  pollInventory: {
+    requirement: "POLL_INVENTORY",
+    resolve: async (req, context) => {
+      setInterval(async () => {
+        const latest = await fetch("/api/inventory");
+        context.facts.inventory = await latest.json();
+      }, 5000);
+    },
+  },
+},
+
+// RIGHT — declare a source; the engine owns the lifecycle
+sources: {
+  inventoryPoll: {
+    attach: (publish) => {
+      const id = setInterval(async () => {
+        const latest = await fetch("/api/inventory");
+        publish("INVENTORY_LATEST", await latest.json());
+      }, 5000);
+      return () => clearInterval(id);
+    },
+  },
+},
+```
+
+---
+
+## Related
+
+- [`../core/sources.md`](../core/sources.md) — full source primitive semantics, lifecycle, recipes
+- [`ai-security.md`](./ai-security.md) — PII detection, prompt-injection, output guardrails (see "Sources × PII" section)
+- [`ai-orchestrator.md`](./ai-orchestrator.md) — `createAgentOrchestrator` + `runStream`
+- [`ai-mcp-rag.md`](./ai-mcp-rag.md) — MCP adapter
+- [`ai-communication.md`](./ai-communication.md) — agent message bus + PubSub

package/skills/building-directive-systems/system-api.md

@@ -182,6 +182,34 @@ inspection.derivations; // [{ id: "doubled", meta: { ... } }]
 inspection.modules;     // [{ id: "auth", meta: { ... } }]
 inspection.events;      // [{ name: "increment", meta: { ... } }]
 
+// Sources with per-source telemetry. Operators read these to answer
+// "is this source publishing?" / "did it error?" / "is the engine
+// silently dropping its publishes?" without registering a custom
+// plugin. Counters reset at every system.start() cycle.
+inspection.sources;
+// [{
+//   id: "supabaseRealtime",
+//   moduleId: "messages",
+//   attached: true,
+//   attachedAt: 1709000000,
+//   detachedAt: null,
+//   publishCount: 47,
+//   lastPublishAt: 1709000123,
+//   // dropCount counts publishes the engine's dispatch guard rejected
+//   // (post-stop, BLOCKED_PROPS event name, empty / non-string name).
+//   dropCount: 0,
+//   lastDropReason: null,        // | "post-destroy" | "post-stop"
+//                                 // | "blocked-event-name"
+//                                 // | "invalid-event-name"
+//   lastDropAt: null,
+//   errorCount: 0,
+//   lastError: null,             // { phase, message (truncated), at } | null
+//   meta: { label: "Supabase channel" },
+// }]
+
+// Aggregate — number of sources currently attached (== count of `attached: true` rows).
+inspection.attachedSourceCount;  // 3
+
 // Unmet requirements (no matching resolver)
 inspection.unmet;
 
@@ -242,8 +270,10 @@ const unsub = system.observe((event: ObservationEvent) => {
   if (event.type === "fact.change") console.log(event.key, event.prev, "→", event.next);
 });
 
-// 18 event types: fact.change, constraint.evaluate/error, requirement.created/met/canceled,
-// resolver.start/complete/error, effect.run/error, derivation.compute,
+// 23 event types: fact.change, constraint.evaluate/error,
+// requirement.created/met/canceled, resolver.start/complete/error/write.rejected,
+// effect.run/error, derivation.compute,
+// source.attach/publish/detach/error,
 // reconcile.start/end, system.init/start/stop/destroy
 
 unsub(); // Stop observing

package/skills/getting-started-with-directive/core-patterns.md

@@ -11,6 +11,8 @@ User wants to...
 ├── Store state → schema.facts + init()
 ├── Compute derived values → schema.derivations + derive
 ├── React to state changes → effects
+├── Subscribe to an external event stream (WebSocket, Supabase realtime,
+│   browser events, MCP server lifecycle) → sources
 ├── Trigger side effects when conditions are met → constraints + resolvers
 ├── Handle user actions → schema.events + events handlers
 └── Coordinate multiple modules → createSystem({ modules: {} })
@@ -233,6 +235,7 @@ const typed = createModule("typed", {
 
 - [`constraints.md`](./constraints.md) — the demand side of the constraint-resolver loop
 - [`resolvers.md`](./resolvers.md) — the supply side that fulfills requirements
+- [`sources.md`](./sources.md) — typed external event sources (the inbound dual of effects)
 - [`schema-types.md`](./schema-types.md) — the `t.*()` builders that define fact and derivation types
 - [`multi-module.md`](./multi-module.md) — when a single module isn't enough
 - [`system-api.md`](./system-api.md) — `createSystem` and the runtime instance once your module is defined

package/skills/getting-started-with-directive/sitemap.md

@@ -29,6 +29,7 @@ Website: https://directive.run
 - [Constraints](https://directive.run/docs/constraints)
 - [Resolvers](https://directive.run/docs/resolvers)
 - [Effects](https://directive.run/docs/effects)
+- [Sources](https://directive.run/docs/sources)
 - [Events](https://directive.run/docs/events)
 - [Schema & Types](https://directive.run/docs/schema-overview)
 - [API Reference](https://directive.run/docs/api/core)

package/skills/hardening-ai-systems/ai-security.md

@@ -380,6 +380,62 @@ createCompliance({
 })
 ```
 
+## Sources × PII — closing the fact-injection bypass
+
+`createPIIGuardrail` and `createEnhancedPIIGuardrail` only inspect the
+`data.input` argument passed to `runStream(agent, input, ...)`. When a
+source publishes PII into a fact and the agent's prompt template embeds
+that fact (`"Hello ${facts.email}..."`), the PII reaches the LLM call
+without hitting the input guardrail chain.
+
+This is the documented R5 audit finding (red team, privacy, AI-integration
+reviewers independently flagged it). The Tier 0 fix:
+
+```ts
+import { createSystem, createModule, t } from "@directive-run/core";
+import { createFactPIIGuardrail } from "@directive-run/ai/guardrails";
+
+const customer = createModule("customer", {
+  schema: {
+    facts: {
+      email: t.string().meta({ tags: ["pii"] }),  // ← tag pii-bearing facts
+      ssn: t.string().meta({ tags: ["pii"] }),
+    },
+  },
+  sources: { /* Supabase realtime, webhook, ... */ },
+});
+
+const system = createSystem({
+  module: customer,
+  plugins: [
+    createFactPIIGuardrail({
+      mode: "redact",            // 'redact' (safe default) | 'alert'
+      onBlocked: (key, detected) =>
+        Sentry.captureMessage(`pii redacted: ${key}`, {
+          extra: { count: detected.length },
+        }),
+    }),
+  ],
+});
+```
+
+The plugin scans every write to a `pii`-tagged fact (auto-discovered via
+`meta.byTag("pii")` at `onInit`) and either redacts the value (default —
+rewrites via a follow-up store write so the next read sees the redacted
+form) or alerts (fires `onBlocked` without mutating). Together with the
+input-guardrail chain on `runStream`, this closes the source → fact →
+prompt PII path.
+
+**Limitation:** hard rejection at the write boundary requires a
+pre-commit transform hook on the source primitive itself (Directive
+plugin hooks are wrapped by `safeCall` and a thrown error is
+swallowed). Tracked as a future RFC; today's `"redact"` mode is the
+safe-shipping posture.
+
+See [`ai-sources.md`](./ai-sources.md) for the full source primitive
+integration recipes, including the live-context pattern that
+`createFactPIIGuardrail` gates.
+
 ## Quick reference
 
 | API | Import path | Returns | Purpose |
@@ -387,6 +443,7 @@ createCompliance({
 | `createPIIGuardrail` | `@directive-run/ai/guardrails` | `GuardrailFn<InputGuardrailData>` | Basic input PII detection (block or redact) |
 | `createEnhancedPIIGuardrail` | `@directive-run/ai/guardrails` | guardrail | Context-aware input PII |
 | `createOutputPIIGuardrail` | `@directive-run/ai/guardrails` | guardrail | Output PII coverage |
+| `createFactPIIGuardrail` | `@directive-run/ai/guardrails` | `Plugin` | **Fact-boundary PII guardrail — closes the source → fact → prompt bypass. Wire at `createSystem({ plugins })`.** |
 | `createPromptInjectionGuardrail` | `@directive-run/ai/guardrails` | guardrail | Risk-scored injection defense (`strictMode`, `blockThreshold`) |
 | `createAuditTrail` | `@directive-run/ai` | `AuditInstance` | Hash-chained audit log w/ signing + PII masking + async export |
 | `createCompliance` | `@directive-run/ai` | `ComplianceInstance` | GDPR exportData / deleteData / consent + retention enforcement |