watchmyagents 0.9.3 → 1.0.0

package/README.md

@@ -129,7 +129,7 @@ Logs land in `./watchmyagents-logs/<agent_id>/<date>.ndjson` (file mode `0600`,
 
 ### `wma-anonymize` — preview what would leave your machine
 
-Produces the anonymized signals payload (counts, latencies, salted IoC hashes, sequence histograms — no raw URLs/commands/prompts) that future WMA cloud features would ship. Useful to verify Modèle C compliance and to test the format.
+Produces the anonymized signals payload (counts, latencies, salted IoC hashes, sequence histograms — no raw URLs/commands/prompts) that future WMA cloud features would ship. Useful to verify Containment compliance and to test the format.
 
 ```bash
 export WMA_SIGNALS_SALT="$(node -e 'console.log(require("crypto").randomBytes(16).toString("hex"))')"
@@ -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.
@@ -174,7 +174,7 @@ Outputs sections aligned with security audit needs: tokens summary, by-tool / by
 
 Lists every Managed Agent under your key and classifies each one's **typology**
 (one of 10 Guardian Core archetypes) from its OBSERVED behaviour in your local
-logs — which drives the cold-start Shield template. Modèle C: reads local logs
+logs — which drives the cold-start Shield template. Containment: reads local logs
 only (tool-category fractions, never raw content) and transmits nothing.
 
 ```bash
@@ -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.
 
@@ -303,7 +303,7 @@ Decisions are logged to the same NDJSON stream as Watch (`action_type: shield_de
 
 - ✅ Watch SDK — Anthropic Managed Agents post-hoc fetch + local audit
 - ✅ Shield SDK — real-time enforcement (interrupt mode + tool_confirmation mode)
-- ✅ Anonymizer — produce signals payloads (Modèle C: no raw content leaves)
+- ✅ Anonymizer — produce signals payloads (Containment: no raw content leaves)
 - ✅ Anonymized telemetry to WMA Fortress cloud (`wma-upload-fortress` in v0.5.0)
 - ✅ Guardian AI (cloud) — automatic policy suggestions from observed behavior
 - ✅ Fortress (cloud) — dashboard + human-in-the-loop validation queue

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "watchmyagents",
-  "version": "0.9.3",
+  "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/agents.js

@@ -5,14 +5,14 @@
 // Usage:
 //   wma-agents [list] [--log-dir ~/.watchmyagents/logs] [--json]
 //
-// Reads the local Watch logs (NEVER leaves the machine — Modèle C) and derives
+// Reads the local Watch logs (NEVER leaves the machine — Containment) and derives
 // the anonymized behavioural FEATURE VECTOR per the typology spec:
 //   per-tool-category FRACTIONS (f_*), boolean local flags (flag_*), aux ratios
 //   (aux_*), and n_events. It then calls classifyAgentType() and prints the
 //   schema-conformant result. With <50 events an agent is `generic` (cold start)
 //   and refines as activity accumulates.
 //
-// Modèle C invariant: only counts/ratios/flags are computed here — never raw
+// Containment invariant: only counts/ratios/flags are computed here — never raw
 // prompt/output content, never the agent display name. Nothing is transmitted.
 //
 // ANTHROPIC_API_KEY from env (or --api-key, discouraged).
@@ -39,7 +39,7 @@ function die(msg, code = 1) { process.stderr.write(`error: ${msg}\n`); process.e
 function info(msg) { process.stdout.write(`[wma-agents] ${msg}\n`); }
 
 // Feature aggregation lives in src/typology-features.js (shared with the Watch
-// daemon so both CLI snapshot and continuous upload use the same Modèle C
+// daemon so both CLI snapshot and continuous upload use the same Containment
 // extraction). The rest of this file is just CLI presentation.
 
 async function main() {
@@ -76,7 +76,7 @@ async function main() {
   if (asJson) { process.stdout.write(JSON.stringify(results, null, 2) + '\n'); return; }
 
   info(`discovered ${results.length} agent(s) - classified from local logs in ${logDir}`);
-  info(`Modele C: features below default to 0 (logs don't expose them): ${NON_DERIVABLE.join(', ')}`);
+  info(`Containment: features below default to 0 (logs don't expose them): ${NON_DERIVABLE.join(', ')}`);
   process.stdout.write('\n');
   for (const r of results) {
     const mods = (r.modifiers && r.modifiers.length) ? ` [+${r.modifiers.join(',')}]` : '';

package/scripts/fetch-anthropic.js

@@ -14,7 +14,7 @@
 //     by the stable Anthropic event id), appends them to the NDJSON, and — with
 //     --upload — anonymizes the new window and ships signals to Fortress. This
 //     automates the Watch leg of the WGS loop so Guardian gets fresh data with
-//     no manual step. The raw NDJSON always stays local (Modèle C).
+//     no manual step. The raw NDJSON always stays local (Containment).
 //
 // API key from --api-key or env ANTHROPIC_API_KEY.
 // --upload also needs: WMA_API_KEY, WMA_FORTRESS_BASE_URL, WMA_SIGNALS_SALT.
@@ -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,
     });
@@ -213,7 +238,7 @@ async function fetchOneShot({ apiKey, agentId, model, logDir, since, sessionId,
 // up. `windowMs` bounds discovery of NEW sessions, but sessions we're ALREADY
 // tracking are re-fetched regardless of age, so a long-running (>window) session
 // never drops out of capture. `sendNames`: include the human agent name in the
-// Fortress display_name (opt-in); default sends the agent id only (Modèle C).
+// Fortress display_name (opt-in); default sends the agent id only (Containment).
 async function runWatch({ apiKey, resolveAgents, fleet, logDir, intervalMs, windowMs, uploadCtx, sendNames }) {
   let agents = await resolveAgents();
   const seenIds = new Set();     // stable Anthropic event ids already captured
@@ -284,7 +309,7 @@ async function runWatch({ apiKey, resolveAgents, fleet, logDir, intervalMs, wind
         try {
           // Compute the agent's typology from its CUMULATIVE local logs and
           // thread the prior across cycles so the state machine refines toward
-          // stable (Modèle C: features = counts/categories only, no raw content).
+          // stable (Containment: features = counts/categories only, no raw content).
           let classification;
           try {
             const features = buildFeatures(await aggregate(logDir, ag.agentId));
@@ -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/service.js

@@ -17,7 +17,7 @@
 // environment) into a protected env file (~/.watchmyagents/env, chmod 600) that
 // the service loads at runtime. Required env at install time:
 //   ANTHROPIC_API_KEY, WMA_API_KEY, WMA_FORTRESS_BASE_URL, WMA_SIGNALS_SALT
-// Raw logs stay local (Modèle C); only anonymized signals are uploaded.
+// Raw logs stay local (Containment); only anonymized signals are uploaded.
 
 import os from 'node:os';
 import { mkdirSync, writeFileSync, rmSync, existsSync, chmodSync } from 'node:fs';

package/scripts/upload-fortress.js

@@ -4,7 +4,7 @@
 //
 // Composable with the rest of the SDK:
 //   wma-fetch  →  ./watchmyagents-logs/<agent_id>/<date>.ndjson   (local capture)
-//   wma-anonymize  →  signals payload (Modèle C: no raw content)
+//   wma-anonymize  →  signals payload (Containment: no raw content)
 //   wma-upload-fortress  →  POST signals to https://<project>.supabase.co/functions/v1/ingest-signals
 //
 // Usage:
@@ -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})`);
+  }
+}

package/src/typology-features.js

@@ -1,9 +1,9 @@
-// Shared local-log feature extraction for the typology classifier (Modèle C).
+// Shared local-log feature extraction for the typology classifier (Containment).
 // Both wma-agents (CLI snapshot) and the Watch daemon (continuous upload) use
 // this to derive the anonymized behavioural FEATURE VECTOR from local NDJSON
 // logs, then feed it to classifyAgentType() in ./typology.js.
 //
-// Modèle C invariant: only `action_type` and `tool_name` are read from each log
+// Containment invariant: only `action_type` and `tool_name` are read from each log
 // line — the raw payload fields (input/output/content/error/thinking) are NEVER
 // touched here, so no raw content can ever enter a feature.
 
@@ -37,7 +37,7 @@ const CATEGORY_RULES = [
 const DEPLOY_RE = /deploy|terraform|kubectl|helm|(^|_)release($|_)|ansible|pulumi|cloudformation/;
 
 // Features that the WMA NDJSON logs CANNOT reliably expose today (opaque tool
-// names, no behavioural signal, or raw content off-limits under Modèle C).
+// names, no behavioural signal, or raw content off-limits under Containment).
 // They default to 0/false; callers can surface this to the user.
 export const NON_DERIVABLE = [
   'f_database', 'f_email', 'f_payment', 'f_secret', 'f_memory',

package/src/typology-weights.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "WatchMyAgents — typology classifier weights + thresholds (Guardian Core, agent-typology-classification.spec.md §3/§4/§5). INVARIANT: weights and thresholds live HERE, never hardcoded in typology.js ('poids de signature en config, pas en dur'). Calibrate on labelled real traffic. Modèle C: all inputs are anonymized behavioural fractions/flags only.",
+  "$comment": "WatchMyAgents — typology classifier weights + thresholds (Guardian Core, agent-typology-classification.spec.md §3/§4/§5). INVARIANT: weights and thresholds live HERE, never hardcoded in typology.js ('poids de signature en config, pas en dur'). Calibrate on labelled real traffic. Containment: all inputs are anonymized behavioural fractions/flags only.",
   "version": "0.1.0",
   "updated_at": "2026-05-29T00:00:00Z",
 
@@ -42,7 +42,7 @@
   },
 
   "features": {
-    "$comment": "Canonical anonymized feature keys (Modèle C). Fractions f_* in [0,1]; flag_* in {0,1}; aux_* in [0,1]. Order is informational only — scoring is key-addressed.",
+    "$comment": "Canonical anonymized feature keys (Containment). Fractions f_* in [0,1]; flag_* in {0,1}; aux_* in [0,1]. Order is informational only — scoring is key-addressed.",
     "fractions": ["f_code", "f_browser", "f_database", "f_http", "f_email", "f_payment", "f_secret", "f_search", "f_memory", "f_handoff", "f_user_msg", "f_file"],
     "flags": ["flag_deploy", "flag_internal_sys", "flag_on_behalf"],
     "aux": ["aux_autonomy", "aux_untrusted", "aux_sensitive"]

package/src/typology.js

@@ -8,7 +8,7 @@
 // Why behaviour, not config: Anthropic Managed Agents expose their tools as an
 // opaque bundle (`agent_toolset_20260401`), so static config can't tell a
 // researcher from a coder. We classify from anonymized behavioural signals
-// (Modèle C): per-tool-category FRACTIONS (f_*), boolean local flags (flag_*),
+// (Containment): per-tool-category FRACTIONS (f_*), boolean local flags (flag_*),
 // and aux ratios (aux_*). NEVER raw content — no prompts, no outputs, no names.
 //
 // ──────────────────────────────────────────────────────────────────────────
@@ -23,7 +23,7 @@
 // ──────────────────────────────────────────────────────────────────────────
 //
 // INVARIANTS enforced here:
-//   1. Modèle C — inputs are anonymized fractions/flags/aux ONLY.
+//   1. Containment — inputs are anonymized fractions/flags/aux ONLY.
 //   2. Weights + thresholds come from config (typology-weights.json), never
 //      hardcoded in the logic below.
 //   3. No easy downgrade — moving to a LESS strict template needs a raised
@@ -76,7 +76,7 @@ function strictnessOf(cfg, type) {
  * Build the canonical feature vector from a loose features object.
  * Only the schema-legal keys are kept; everything is coerced to a number and
  * clamped to [0,1] (the schema requires every feature_vector value in [0,1]).
- * Missing features default to 0 — Modèle C: an absent signal is "not observed",
+ * Missing features default to 0 — Containment: an absent signal is "not observed",
  * never inferred from content.
  */
 function normalizeFeatures(cfg, features) {
@@ -121,7 +121,7 @@ function rankTypes(cfg, fv) {
  * classifyAgentType(features[, prior][, opts]) → object conforming EXACTLY to
  * agent-classification.schema.json.
  *
- * @param {object} features          Anonymized behavioural signals (Modèle C):
+ * @param {object} features          Anonymized behavioural signals (Containment):
  *   agent_id            {string}    pass-through identifier (no content)
  *   f_code,f_browser,…  {number}    per-category FRACTIONS in [0,1]
  *   flag_deploy,…       {0|1|bool}  local discriminator flags (no content)