watchmyagents 0.9.4 → 1.0.0

package/README.md

@@ -155,7 +155,7 @@ wma-upload-fortress --agent-id agent_01ABC... [--display-name "My agent"]
 wma-upload-fortress --agent-id agent_xxx --dry-run
 ```
 
-**What is sent:** the anonymized signals payload (counts, latencies, salted IoC hashes, sequences — same as `wma-anonymize` output), the agent's **`classification`** when the daemon has it (`{agent_type, confidence, stage}` — anonymized metadata, never raw content), **plus two routing identifiers**: your `anthropic_agent_id` and a `display_name`. The agent id is required so Fortress can associate signals with the right agent; `display_name` defaults to the **human-readable agent name** (sanitized to strip control chars) for UX in the dashboard — pass `--no-send-agent-names` to keep it pseudonymized (sends the agent id instead) if your agent names themselves carry sensitive client/project info.
+**What is sent:** the anonymized signals payload (counts, latencies, salted IoC hashes, sequences — same as `wma-anonymize` output), the agent's **`classification`** when the daemon has it (`{agent_type, confidence, stage}` — anonymized metadata, never raw content), **plus the routing identifiers**: `provider` (e.g., `"anthropic-managed"` — added in v1.0 for the multi-framework SDK), `native_agent_id` (the canonical provider-agnostic field), `anthropic_agent_id` (kept for backwards compat with existing Fortress instances; will be dropped once Fortress migrates), `parent_agent_id` (`null` for root agents — populated for sub-agents detected via OpenAI Agents handoffs, CrewAI manager mode, Hermes Agent `spawn_subagent`, LangGraph sub-graphs), `composition_pattern` (`"solo" | "hierarchy" | "graph" | "peer"` — defaults to `"solo"` for Anthropic until thread-message detection lands), `enforcement_mode` (`"sync_confirm" | "sync_interrupt" | "detect_only"` — the strongest enforcement capability the Source provides; Fortress greys out Shield UI for `detect_only` agents to prevent UI/runtime mismatch), and a `display_name`. The agent id is required so Fortress can associate signals with the right agent; `display_name` defaults to the **human-readable agent name** (sanitized to strip control chars) for UX in the dashboard — pass `--no-send-agent-names` to keep it pseudonymized (sends the agent id instead) if your agent names themselves carry sensitive client/project info.
 **What is NOT sent:** raw prompts, raw URLs/commands/queries, raw agent responses, raw error messages. All payload content stays on your machine.
 
 The endpoint auto-registers the agent on the first upload if it doesn't exist in Fortress yet — no manual onboarding needed for new agents.
@@ -247,7 +247,7 @@ WatchMyAgents is built so that **your prompts and outputs never have to leave yo
 |---|---|
 | **Your machine** (`./watchmyagents-logs/`) | Full NDJSON with all prompts, tool inputs, agent outputs. `chmod 600` on every file. |
 | **Anthropic API** | Where the agent runs. WMA pulls events via the public REST API only. |
-| **WMA Fortress** (opt-in, only with `--upload` / `wma-upload-fortress` / `wma-shield --policies-source fortress`) | The **anonymized signals** payload (counts, timings, salted hashes, sequences) + two routing identifiers: your `anthropic_agent_id` and a `display_name` (defaults to the agent id; the human agent name only with `--send-agent-names`). Shield enforcement **decisions** (hashed session/event/input fingerprints — never raw values). **Never** raw prompts, URLs, commands, or outputs. |
+| **WMA Fortress** (opt-in, only with `--upload` / `wma-upload-fortress` / `wma-shield --policies-source fortress`) | The **anonymized signals** payload (counts, timings, salted hashes, sequences) + routing identifiers: `provider` (e.g. `"anthropic-managed"`), `native_agent_id`, `anthropic_agent_id` (legacy alias), and `display_name` (defaults to the agent id; the human agent name only with `--send-agent-names`). Shield enforcement **decisions** (hashed session/event/input fingerprints — never raw values). **Never** raw prompts, URLs, commands, or outputs. |
 
 This is the "local-first" guarantee: **raw payloads never leave your machine.** Cloud upload is opt-in and carries only anonymized metadata + the agent id/name needed to route it.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "watchmyagents",
-  "version": "0.9.4",
+  "version": "1.0.0",
   "description": "Security observability + real-time policy enforcement for AI agents. Local-first NDJSON capture with a continuous Watch daemon that auto-uploads anonymized signals, Shield CLI that blocks policy violations live (with policies pulled from Fortress cloud), anonymizer producing signals-only payloads, bidirectional sync with WatchMyAgents Fortress, and one-command install as an always-on launchd/systemd service — closing the recursive Watch→Guardian→Shield security loop.",
   "type": "module",
   "files": [

package/scripts/fetch-anthropic.js

@@ -34,6 +34,7 @@ import { classifyAgentType } from '../src/typology.js';
 import { aggregate, buildFeatures } from '../src/typology-features.js';
 import {
   getAgent, listAgents, listSessions, fetchSessionEntries, fetchRawEvents,
+  AnthropicManagedSource,
 } from '../src/sources/anthropic-managed.js';
 
 function parseArgs(argv) {
@@ -115,8 +116,32 @@ async function uploadSignals(uploadCtx, agentId, displayName, entries, classific
   for (const e of entries) agg.add(e);
   const sig = agg.finalize();
   if (!sig.window_start || !sig.window_end) return null; // nothing datable to ship
+  // PR-C: derive the agent's composition pattern + parent from the
+  // observed entries. For Anthropic today, the Source yields solo/root
+  // agents — sub-agent detection from thread_message_* events lands
+  // with PR-D or a follow-up. Once a future adapter populates these on
+  // the events themselves, this carries them up to Fortress without
+  // any payload-shape change.
+  const firstWithHierarchy = entries.find((e) => e.parent_agent_id != null);
+  const parent_agent_id = firstWithHierarchy?.parent_agent_id ?? null;
+  const composition_pattern = firstWithHierarchy?.composition_pattern
+    || entries.find((e) => e.composition_pattern && e.composition_pattern !== 'solo')?.composition_pattern
+    || 'solo';
+  // PR-B: payload carries the canonical provider-agnostic identifiers
+  // (`provider` + `native_agent_id`) AND the legacy `anthropic_agent_id`
+  // so old Fortress instances still recognize the upload. Once the
+  // Lovable-deployed ingest-signals migrates, future SDK releases will
+  // stop emitting `anthropic_agent_id`.
+  // PR-D: enforcement_mode is read CANONICALLY from the Source's static
+  // declaration so it stays in sync with the actual capability of the
+  // adapter — never re-declared inline.
   const body = JSON.stringify({
+    provider: AnthropicManagedSource.providerName,
+    native_agent_id: agentId,
     anthropic_agent_id: agentId,
+    parent_agent_id,
+    composition_pattern,
+    enforcement_mode: AnthropicManagedSource.enforcementMode,
     display_name: displayName,
     window_start: sig.window_start,
     window_end: sig.window_end,
@@ -194,7 +219,7 @@ async function fetchOneShot({ apiKey, agentId, model, logDir, since, sessionId,
     }
     const stats = tracker.stats().total;
     await logger.write({
-      action_type: 'session_end', framework: 'anthropic-managed', status: 'ok', model,
+      action_type: 'session_end', provider: 'anthropic-managed', status: 'ok', model,
       session_tokens: { input: stats.input, output: stats.output, cache_read: stats.cache_read, cache_creation: stats.cache_creation, total: stats.sum },
       session_cost_usd: stats.cost_usd || null,
     });
@@ -307,7 +332,7 @@ async function runWatch({ apiKey, resolveAgents, fleet, logDir, intervalMs, wind
         for (const e of fresh) tracker.record(e);
         const stats = tracker.stats().total;
         await logger.write({
-          action_type: 'session_end', framework: 'anthropic-managed', status: 'ok', model: ag.model,
+          action_type: 'session_end', provider: 'anthropic-managed', status: 'ok', model: ag.model,
           session_tokens: { input: stats.input, output: stats.output, cache_read: stats.cache_read, cache_creation: stats.cache_creation, total: stats.sum },
           session_cost_usd: stats.cost_usd || null,
         });

package/scripts/upload-fortress.js

@@ -30,6 +30,7 @@ import { createReadStream } from 'node:fs';
 import { createInterface } from 'node:readline';
 import { SignalsAggregator } from '../src/anonymizer.js';
 import { resolveFortressBase, fortressEndpoint } from '../src/fortress/url.js';
+import { AnthropicManagedSource } from '../src/sources/anthropic-managed.js';
 
 function parseArgs(argv) {
   const out = {};
@@ -177,8 +178,20 @@ async function main() {
     die('error: no entries had timestamps — nothing to upload');
   }
 
+  // PR-B: provider-agnostic identifiers + legacy fallback (see fetch-anthropic.js).
+  // PR-C: ship the agent's hierarchy + composition pattern. wma-upload-fortress
+  // is a one-shot post-hoc tool — it has no per-entry context to derive
+  // hierarchy from, so it sends defaults (solo / null) until a future
+  // adapter writes those fields into the local NDJSON.
+  // PR-D: enforcement_mode read from the Source class so any change to
+  // the adapter's capability automatically reflects in the payload.
   const body = {
+    provider: AnthropicManagedSource.providerName,
+    native_agent_id: agentId,
     anthropic_agent_id: agentId,
+    parent_agent_id: null,
+    composition_pattern: 'solo',
+    enforcement_mode: AnthropicManagedSource.enforcementMode,
     display_name: displayName,
     window_start: signals.window_start,
     window_end: signals.window_end,

package/src/logger.js

@@ -3,8 +3,16 @@ import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { assertSafePathSegment } from './validate.js';
 
+// PR-B: `framework` → `provider` (canonical name per src/sources/contract.js).
+// PR-C: adds `parent_agent_id` + `composition_pattern` so any future
+// adapter that knows the hierarchy (OpenAI Agents handoffs, CrewAI
+// manager, Hermes Agent spawn_subagent, LangGraph sub-graphs) can
+// thread the relationship through to Fortress without rework.
+// NDJSON written before PR-B may carry `framework`; readers that need the
+// provider tag should read `provider` first and fall back to `framework`.
 const EXPORT_FIELDS = [
-  'id', 'agent_id', 'framework', 'timestamp', 'action_type',
+  'id', 'agent_id', 'parent_agent_id', 'composition_pattern',
+  'provider', 'timestamp', 'action_type',
   'tool_name', 'duration_ms', 'tokens_used',
   'input_tokens', 'output_tokens', 'cache_read_tokens', 'cache_creation_tokens',
   'cost_usd', 'model',
@@ -47,7 +55,12 @@ export class Logger {
     const full = {
       id: e.id || randomUUID(),
       agent_id: this.agentId,
-      framework: e.framework || 'generic',
+      // PR-C: sub-agent fields. Defaults are honest for solo / root agents.
+      // An adapter that detects hierarchy (e.g. OpenAI Agents handoffs)
+      // populates these on the event, and the Logger threads them through.
+      parent_agent_id: e.parent_agent_id ?? null,
+      composition_pattern: e.composition_pattern || 'solo',
+      provider: e.provider || e.framework || 'generic',
       timestamp: e.timestamp || new Date().toISOString(),
       action_type: e.action_type || 'tool_call',
       tool_name: e.tool_name || null,

package/src/shield/decisions.js

@@ -25,7 +25,7 @@ export class DecisionLogger {
   }) {
     return this._logger.write({
       action_type: 'shield_decision',
-      framework: 'anthropic-managed',
+      provider: 'anthropic-managed',
       tool_name: sourceEvent?.name || sourceEvent?.tool_name || null,
       status: decision === 'deny' || decision === 'interrupt' ? 'error' : 'ok',
       error: decision === 'deny' || decision === 'interrupt' ? message : null,

package/src/sources/anthropic-managed.js

@@ -17,6 +17,7 @@
 
 import { request } from 'node:https';
 import { URLSearchParams } from 'node:url';
+import { Source, PROVIDERS, ENFORCEMENT_MODES } from './contract.js';
 
 const API_HOST = 'api.anthropic.com';
 const BETA = 'managed-agents-2026-04-01';
@@ -163,7 +164,14 @@ export async function* fetchSessionEntries({ apiKey, agentId, sessionId, model }
   const pendingModelReq = new Map();    // span.model_request_start.id → ts
   const pendingToolUse = new Map();     // agent.tool_use.id → { ts, name, isMcp, input }
 
-  const base = { framework: 'anthropic-managed', agent_id: agentId, session_id: sessionId };
+  // `provider` is the canonical field per src/sources/contract.js (no
+  // other consumer ever read the previous `framework` field, so it was
+  // dropped in PR-B with zero downstream impact).
+  const base = {
+    provider: PROVIDERS.ANTHROPIC_MANAGED,
+    agent_id: agentId,
+    session_id: sessionId,
+  };
 
   // No server-side `types[]` filter: the API rejects unknown values, but the
   // exact filterable set is undocumented & evolves. We pull everything and
@@ -459,3 +467,70 @@ function extractText(content) {
   if (content && typeof content === 'object') return content.text || JSON.stringify(content);
   return '';
 }
+
+// ────────────────────────────────────────────────────────────────────────
+// AnthropicManagedSource — V1 Source contract wrapper
+// ────────────────────────────────────────────────────────────────────────
+// Implements the Source ABC over the low-level functions above. New SDK
+// code should use this class; the function exports stay public for
+// backwards compat with the existing wma-fetch + wma-shield daemons
+// (migration is PR-B / PR-D).
+//
+// Capability declaration:
+//   sync_confirm — Anthropic Managed Agents exposes pre-execution
+//   `user.tool_confirmation` (block before the tool runs) AND
+//   `user.interrupt` (stop the current LLM turn). The stronger of the
+//   two is sync_confirm.
+
+export class AnthropicManagedSource extends Source {
+  static providerName = PROVIDERS.ANTHROPIC_MANAGED;
+  static enforcementMode = ENFORCEMENT_MODES.SYNC_CONFIRM;
+
+  constructor({ apiKey } = {}) {
+    super({ apiKey });
+    if (!apiKey) throw new Error('AnthropicManagedSource requires an apiKey');
+    this.apiKey = apiKey;
+  }
+
+  /**
+   * Discover Managed Agents under this API key. Returns the canonical
+   * agent descriptor (`{ id, name, native }`) — the raw vendor agent
+   * stays in `native` for adapters/UI that want richer metadata.
+   */
+  async listAgents() {
+    const raw = await listAgents(this.apiKey);
+    return raw.map((a) => ({
+      id: a.id,
+      name: a.name || null,
+      native: a,
+    }));
+  }
+
+  /**
+   * Stream WMAAction entries for a session. Anthropic events are
+   * per-session, so opts.sessionId is required — fleet-wide watching is
+   * the caller's job (wma-fetch already orchestrates this).
+   */
+  async *streamEvents(agentId, { sessionId, model } = {}) {
+    if (!sessionId) {
+      throw new Error('AnthropicManagedSource.streamEvents requires opts.sessionId — Anthropic events are scoped to a session');
+    }
+    yield* fetchSessionEntries({
+      apiKey: this.apiKey, agentId, sessionId, model,
+    });
+  }
+
+  /**
+   * Enforce a policy decision against a pending action.
+   *
+   * PR-A scaffold: the actual `user.tool_confirmation` / `user.interrupt`
+   * HTTP call currently lives in scripts/shield.js, which talks to the
+   * Anthropic API directly. Migrating that into this method is PR-D — at
+   * which point this body will POST the decision via the SSE/HTTP control
+   * channel. For PR-A, the method exists to satisfy the contract;
+   * Shield does not call it yet.
+   */
+  async enforce(action, decision) { // eslint-disable-line no-unused-vars
+    throw new Error('AnthropicManagedSource.enforce() — Shield migration pending PR-D (scripts/shield.js still handles enforcement directly)');
+  }
+}

package/src/sources/contract.js

@@ -0,0 +1,259 @@
+// ────────────────────────────────────────────────────────────────────────
+// WatchMyAgents — Source contract (V1)
+// ────────────────────────────────────────────────────────────────────────
+//
+// THIS FILE IS THE CONTRACT every adapter MUST follow.
+//
+// Why this exists:
+//   The SDK shipped today integrates Anthropic Managed Agents via the
+//   functions in `./anthropic-managed.js`. To add OpenAI / LangGraph /
+//   CrewAI / Bedrock / etc. without rewriting the pipe each time, the
+//   contract between "fetching events" and "the rest of WMA" has to be
+//   explicit.
+//
+//   Everything in WMA (anonymizer, typology classifier, Guardian scoring,
+//   Shield enforcement, Fortress signals payload) operates on `WMAAction`
+//   objects — the canonical shape defined below. Each Source adapter is
+//   responsible for translating its provider's native events into this
+//   shape, and nothing else.
+//
+// Containment invariant:
+//   A Source's `streamEvents()` yields WMAAction objects that MAY carry
+//   raw payload bytes in `input`/`output` — these are written to the
+//   LOCAL NDJSON file but NEVER sent to Fortress. The anonymizer is the
+//   single gate between WMAAction (raw) and the signals payload (cloud).
+//   See `src/anonymizer.js` and `docs/SOURCE-ADAPTER-CONTRACT.md`.
+
+// ── Canonical vocabulary ────────────────────────────────────────────────
+
+// Every WMAAction.action_type MUST be one of these. New adapters that
+// emit a novel kind of action should propose adding a new constant here
+// (and document it) rather than inventing one inline.
+export const ACTION_TYPES = Object.freeze({
+  LLM_CALL: 'llm_call',
+  TOOL_USE: 'tool_use',
+  MCP_TOOL_USE: 'mcp_tool_use',
+  CUSTOM_TOOL_USE: 'custom_tool_use',
+  CUSTOM_TOOL_RESULT: 'custom_tool_result',
+  TOOL_CONFIRMATION: 'tool_confirmation',
+  USER_MESSAGE: 'user_message',
+  USER_INTERRUPT: 'user_interrupt',
+  MESSAGE: 'message',
+  THINKING: 'thinking',
+  CONTEXT_COMPACTED: 'context_compacted',
+  THREAD_CREATED: 'thread_created',
+  THREAD_MESSAGE_SENT: 'thread_message_sent',
+  THREAD_MESSAGE_RECEIVED: 'thread_message_received',
+  CONFIG_CHANGE: 'config_change',
+  STATE_TRANSITION: 'state_transition',
+  SESSION_ERROR: 'session_error',
+  // Shield-only — emitted when WMA itself blocks an action:
+  SHIELD_DECISION: 'shield_decision',
+});
+
+export const STATUS_VALUES = Object.freeze({
+  OK: 'ok',
+  ERROR: 'error',
+  BLOCKED: 'blocked',
+});
+
+// A Source declares how strongly it can enforce policies. This drives
+// what Shield can do on its events:
+//   sync_confirm    → can confirm/deny a tool call before execution
+//                     (Anthropic user.tool_confirmation, AgentCore
+//                     Gateway interceptor with transformedResponse)
+//   sync_interrupt  → can interrupt mid-execution after an LLM call
+//                     (Anthropic user.interrupt)
+//   detect_only     → can observe but cannot block — post-hoc audit
+//                     (E2B lifecycle webhooks, pure observability sinks)
+export const ENFORCEMENT_MODES = Object.freeze({
+  SYNC_CONFIRM: 'sync_confirm',
+  SYNC_INTERRUPT: 'sync_interrupt',
+  DETECT_ONLY: 'detect_only',
+});
+
+// How the agent composes with other agents — drives the WMA dashboard
+// tree view and the policy `subtree` surface (PR-C).
+//   solo       → no sub-agents, one tool-loop
+//   hierarchy  → boss + workers (CrewAI manager, Anthropic Task tool,
+//                Hermes Agent spawn-subagent)
+//   graph      → nodes + edges (LangGraph)
+//   peer       → N agents converse on equal footing (AutoGen)
+export const COMPOSITION_PATTERNS = Object.freeze({
+  SOLO: 'solo',
+  HIERARCHY: 'hierarchy',
+  GRAPH: 'graph',
+  PEER: 'peer',
+});
+
+// Known provider identifiers. Adapters should register their provider
+// name here as they land so consumers can build provider-specific UI.
+export const PROVIDERS = Object.freeze({
+  ANTHROPIC_MANAGED: 'anthropic-managed',
+  // Coming next:
+  // OPENAI_AGENTS: 'openai-agents',
+  // AWS_BEDROCK_AGENTCORE: 'aws-bedrock-agentcore',
+  // LANGGRAPH: 'langgraph',
+  // CREWAI: 'crewai',
+});
+
+// ── WMAAction canonical shape ───────────────────────────────────────────
+//
+// /**
+//  * @typedef {object} WMAAction
+//  *
+//  * REQUIRED — every Source MUST populate these:
+//  * @property {string} id              Stable, dedup-friendly event id
+//  * @property {string} provider        From PROVIDERS (e.g. 'anthropic-managed')
+//  * @property {string} agent_id        Native agent identifier
+//  * @property {string} session_id      Native session/thread/run identifier
+//  * @property {string} action_type     From ACTION_TYPES
+//  * @property {string} timestamp       ISO-8601
+//  * @property {'ok'|'error'|'blocked'} status
+//  *
+//  * OPTIONAL — present when applicable:
+//  * @property {string|null} tool_name              For tool_use family
+//  * @property {string|null} model                  For llm_call
+//  * @property {number|null} duration_ms            Latency (start→end pair)
+//  * @property {number|null} tokens_used            For llm_call (input+output+cache)
+//  * @property {number|null} input_tokens
+//  * @property {number|null} output_tokens
+//  * @property {number|null} cache_read_tokens
+//  * @property {number|null} cache_creation_tokens
+//  * @property {string|null} error                  Truncated error message (≤500ch)
+//  * @property {object|null} input                  Raw input payload — STAYS LOCAL
+//  * @property {object|null} output                 Raw output payload — STAYS LOCAL
+//  *
+//  * SUB-AGENT FIELDS (PR-C — see WMAAction.parent_agent_id):
+//  * @property {string|null} parent_agent_id        Null for root agents
+//  * @property {string|null} composition_pattern    From COMPOSITION_PATTERNS
+//  */
+
+const REQUIRED_FIELDS = ['id', 'provider', 'agent_id', 'session_id', 'action_type', 'timestamp', 'status'];
+
+/**
+ * Validate a WMAAction at runtime. Returns `{ valid, errors }`.
+ * Cheap enough to run on every yield in dev (process.env.WMA_DEV_VALIDATE=1).
+ *
+ * Adapters should call this BEFORE yielding in their test suite, and the
+ * SDK can opt into runtime validation via the env flag.
+ */
+export function validateWMAAction(obj) {
+  const errors = [];
+  if (!obj || typeof obj !== 'object') {
+    return { valid: false, errors: ['not an object'] };
+  }
+  for (const f of REQUIRED_FIELDS) {
+    if (obj[f] == null) errors.push(`missing required field: ${f}`);
+  }
+  if (obj.action_type && !Object.values(ACTION_TYPES).includes(obj.action_type)) {
+    errors.push(`unknown action_type "${obj.action_type}" — add to ACTION_TYPES in contract.js`);
+  }
+  if (obj.status && !Object.values(STATUS_VALUES).includes(obj.status)) {
+    errors.push(`unknown status "${obj.status}" — must be one of ${Object.values(STATUS_VALUES).join(', ')}`);
+  }
+  if (obj.composition_pattern != null
+      && !Object.values(COMPOSITION_PATTERNS).includes(obj.composition_pattern)) {
+    errors.push(`unknown composition_pattern "${obj.composition_pattern}"`);
+  }
+  if (obj.timestamp && Number.isNaN(Date.parse(obj.timestamp))) {
+    errors.push(`timestamp not parseable: ${obj.timestamp}`);
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+// ── Source abstract base class ──────────────────────────────────────────
+
+/**
+ * Every framework adapter MUST extend this class and override the abstract
+ * methods. The Source is the boundary between "the customer's agent
+ * runtime" and "the rest of WMA" — the only place where vendor-specific
+ * code lives. Once a Source yields WMAAction objects, the pipe is
+ * provider-agnostic.
+ *
+ * Static contract:
+ *   providerName        — value from PROVIDERS
+ *   enforcementMode     — value from ENFORCEMENT_MODES
+ *
+ * Instance contract:
+ *   listAgents()        — return all agents accessible with the client creds
+ *   streamEvents(id)    — async generator yielding WMAAction objects
+ *   enforce(action, d)  — only required if enforcementMode != detect_only
+ *
+ * See `docs/SOURCE-ADAPTER-CONTRACT.md` for the full author guide.
+ */
+export class Source {
+  static providerName = null;
+  static enforcementMode = null;
+
+  constructor(config = {}) {
+    if (new.target === Source) {
+      throw new Error('Source is abstract — extend it in a subclass (e.g., AnthropicManagedSource).');
+    }
+    this.config = config;
+  }
+
+  /**
+   * Discover all agents under the client's credentials.
+   * @returns {Promise<Array<{id: string, name?: string, native?: object}>>}
+   */
+  async listAgents() {
+    throw new Error(`${this.constructor.name}.listAgents() not implemented`);
+  }
+
+  /**
+   * Stream WMAAction objects for the given agent. The implementation may
+   * page, retry, dedup, or restart internally — consumers see a single
+   * ordered stream.
+   * @param {string} agentId
+   * @param {object} [opts]
+   * @yields {WMAAction}
+   */
+  async *streamEvents(agentId, opts) { // eslint-disable-line no-unused-vars
+    throw new Error(`${this.constructor.name}.streamEvents() not implemented`);
+    yield; // make this a generator
+  }
+
+  /**
+   * Enforce a policy decision against a pending action. Only called when
+   * the Source's static `enforcementMode` is not `detect_only`. The
+   * subclass is responsible for translating WMA's canonical decision
+   * (`allow`|`deny`) into the provider's native confirm/interrupt call.
+   * @param {WMAAction} action
+   * @param {{decision: 'allow'|'deny', reason?: string}} decision
+   * @returns {Promise<{enforced: boolean, native_response?: object}>}
+   */
+  async enforce(action, decision) { // eslint-disable-line no-unused-vars
+    if (this.constructor.enforcementMode === ENFORCEMENT_MODES.DETECT_ONLY) {
+      throw new Error(`${this.constructor.name} is detect_only — enforce() must not be called`);
+    }
+    throw new Error(`${this.constructor.name}.enforce() not implemented`);
+  }
+}
+
+/**
+ * Assertion helper for tests: verify a Source subclass declares the
+ * required static fields and overrides the abstract methods.
+ * Throws on any contract violation.
+ */
+export function assertImplementsSource(SourceClass) {
+  if (!(SourceClass.prototype instanceof Source)) {
+    throw new Error(`${SourceClass?.name || SourceClass} does not extend Source`);
+  }
+  if (!Object.values(PROVIDERS).includes(SourceClass.providerName)) {
+    throw new Error(`${SourceClass.name}.providerName="${SourceClass.providerName}" not in PROVIDERS`);
+  }
+  if (!Object.values(ENFORCEMENT_MODES).includes(SourceClass.enforcementMode)) {
+    throw new Error(`${SourceClass.name}.enforcementMode="${SourceClass.enforcementMode}" not in ENFORCEMENT_MODES`);
+  }
+  // The base class throws "not implemented" — a real subclass must override.
+  for (const m of ['listAgents', 'streamEvents']) {
+    if (SourceClass.prototype[m] === Source.prototype[m]) {
+      throw new Error(`${SourceClass.name}.${m}() must be overridden`);
+    }
+  }
+  if (SourceClass.enforcementMode !== ENFORCEMENT_MODES.DETECT_ONLY
+      && SourceClass.prototype.enforce === Source.prototype.enforce) {
+    throw new Error(`${SourceClass.name}.enforce() must be overridden (enforcementMode=${SourceClass.enforcementMode})`);
+  }
+}