watchmyagents 1.2.0 → 1.3.0

package/examples/policies/mitre-starter.json

@@ -0,0 +1,133 @@
+{
+  "_comment_doc": "WatchMyAgents starter policy bundle — MITRE ATT&CK + ATLAS coverage. Tune to your environment before promoting from mode=shadow → mode=enforce. See docs/MITRE-ATTCK-COVERAGE.md for technique mapping. Every policy ships in shadow mode so the first run only LOGS would-be decisions without blocking — calibrate, then promote.",
+  "_comment_lifecycle": "Lifecycle: observe → shadow → enforce → retired. Per [[project_recursive_fractal_loop]], shadow is the calibration bench (Platt scaling + diff-in-diff efficacy). Promote a rule to mode=enforce only after you've seen enough shadow decisions to be confident the rule isn't false-positiving on your workload.",
+  "_comment_uses": "Uses v1.2.0+ DSL extensions (gt, in_range, length_gt) and ctx.* namespace (hour_of_day_utc, recent_error_rate, event_count_recent). Falls back gracefully on v1.1.x where unknown operators / ctx paths fail-closed (no false-allow).",
+
+  "policies": [
+    {
+      "id": "mitre-t1567-exfil-large-post",
+      "name": "T1567 Exfiltration Over Web Service — large outbound POST",
+      "action": "deny",
+      "mode": "shadow",
+      "message": "MITRE T1567: outbound POST exceeds 1MB threshold. Likely exfil channel.",
+      "match": {
+        "action_type": "tool_use",
+        "tool_name": { "in": ["web_fetch", "http_post"] },
+        "input.method": "POST",
+        "input.bytes": { "gt": 1000000 }
+      }
+    },
+
+    {
+      "id": "mitre-t1041-c2-host-allowlist",
+      "name": "T1041 Exfiltration Over C2 Channel — host allowlist",
+      "action": "deny",
+      "mode": "shadow",
+      "message": "MITRE T1041: outbound to non-allowlisted host. Replace the regex with your trusted egress hosts.",
+      "match": {
+        "action_type": "tool_use",
+        "tool_name": { "in": ["web_fetch", "http_post"] },
+        "input.url": { "not_regex": "^https://(api\\.openai\\.com|api\\.anthropic\\.com|github\\.com|api\\.github\\.com|raw\\.githubusercontent\\.com|wikipedia\\.org|en\\.wikipedia\\.org)(/|$|:[0-9]+)" }
+      }
+    },
+
+    {
+      "id": "mitre-t1485-data-destruction",
+      "name": "T1485 Data Destruction — destructive shell patterns",
+      "action": "deny",
+      "mode": "shadow",
+      "message": "MITRE T1485: destructive shell pattern (rm -rf / mkfs / dd if=).",
+      "match": {
+        "tool_name": "bash",
+        "input.command": { "regex": "(^|\\s|;|&&|\\|\\|)(rm\\s+-rf\\s|mkfs[. ]|dd\\s+if=)" }
+      }
+    },
+
+    {
+      "id": "mitre-t1548-privilege-escalation",
+      "name": "T1548 Abuse Elevation Control — sudo / pkexec / doas",
+      "action": "interrupt",
+      "mode": "shadow",
+      "message": "MITRE T1548: privilege-escalation attempt via sudo / pkexec / doas.",
+      "match": {
+        "tool_name": "bash",
+        "input.command": { "regex": "(^|\\s|;|&&|\\|\\|)(sudo|pkexec|doas)\\s" }
+      }
+    },
+
+    {
+      "id": "mitre-t1059-bash-command-length",
+      "name": "T1059 Command and Scripting Interpreter — improbably long command",
+      "action": "deny",
+      "mode": "shadow",
+      "message": "MITRE T1059: bash command exceeds 2KB — likely a base64-encoded payload or pipeline obfuscation.",
+      "match": {
+        "tool_name": "bash",
+        "input.command": { "length_gt": 2048 }
+      }
+    },
+
+    {
+      "id": "mitre-t1083-after-hours-discovery",
+      "name": "T1083 File and Directory Discovery — outside business hours (late)",
+      "action": "interrupt",
+      "mode": "shadow",
+      "message": "MITRE T1083: file discovery between 22:00 and 23:59 UTC. Tune for your business hours.",
+      "match": {
+        "tool_name": { "in": ["bash", "file_list"] },
+        "ctx.hour_of_day_utc": { "in_range": [22, 23] }
+      }
+    },
+
+    {
+      "id": "mitre-t1083-after-hours-discovery-early",
+      "name": "T1083 File and Directory Discovery — outside business hours (early)",
+      "action": "interrupt",
+      "mode": "shadow",
+      "message": "MITRE T1083: file discovery between 00:00 and 06:59 UTC. Tune for your business hours.",
+      "match": {
+        "tool_name": { "in": ["bash", "file_list"] },
+        "ctx.hour_of_day_utc": { "in_range": [0, 6] }
+      }
+    },
+
+    {
+      "id": "mitre-t1020-flailing-agent-throttle",
+      "name": "T1020 Automated Exfiltration — throttle flailing agent (high error rate)",
+      "action": "interrupt",
+      "mode": "shadow",
+      "message": "MITRE T1020: agent recent_error_rate > 0.5 across last >= 4 events — likely a runaway loop or retry storm.",
+      "match": {
+        "action_type": "tool_use",
+        "ctx.recent_error_rate": { "gt": 0.5 },
+        "ctx.event_count_recent": { "gte": 4 }
+      }
+    },
+
+    {
+      "id": "mitre-t1053-cron-persistence",
+      "name": "T1053 Scheduled Task/Job — cron / launchd persistence",
+      "action": "deny",
+      "mode": "shadow",
+      "message": "MITRE T1053: agent attempted to write a persistent task. Possible C2 persistence.",
+      "match": {
+        "tool_name": { "in": ["bash", "file_write"] },
+        "input.path": { "regex": "(crontab|/etc/cron\\.[a-z]+/|\\.crontab|/Library/LaunchAgents/|/Library/LaunchDaemons/|\\.service$|/etc/systemd/system/)" }
+      }
+    },
+
+    {
+      "id": "mitre-t1552-credential-store-read",
+      "name": "T1552 Unsecured Credentials — read of well-known credential store",
+      "action": "deny",
+      "mode": "shadow",
+      "message": "MITRE T1552: agent attempted to read a credential store. Tighten the path regex for your environment.",
+      "match": {
+        "tool_name": { "in": ["bash", "file_read"] },
+        "input.path": { "regex": "(/\\.aws/credentials|/\\.aws/config|/\\.ssh/id_[a-z]+|/\\.netrc|Library/Keychains|/etc/shadow)" }
+      }
+    }
+  ],
+
+  "default": { "action": "allow" }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "watchmyagents",
-  "version": "1.2.0",
+  "version": "1.3.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": [
@@ -12,6 +12,9 @@
     "scripts/upload-fortress.js",
     "scripts/service.js",
     "scripts/agents.js",
+    "examples/policies/",
+    "examples/adapters/",
+    "docs/adapters/",
     "README.md",
     "SECURITY.md",
     "LICENSE"
@@ -40,6 +43,14 @@
   },
   "dependencies": {},
   "devDependencies": {},
+  "peerDependencies": {
+    "@openai/agents": "^0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@openai/agents": {
+      "optional": true
+    }
+  },
   "keywords": [
     "ai",
     "agents",
@@ -50,7 +61,11 @@
     "cybersecurity",
     "anthropic",
     "claude",
+    "openai",
+    "openai-agents",
     "managed-agents",
+    "agent-runtime",
+    "guardrails",
     "audit",
     "ndjson",
     "policy-enforcement",

package/scripts/shield.js

@@ -203,18 +203,35 @@ async function runSessionWorker({ sessionId, ctx }) {
     })) {
       processed++;
 
+      // v1.2.1 F-26 (P1 Codex audit on v1.2.0): record EVERY event
+      // flowing through Shield, not just the cacheable tool_use ones.
+      // The previous wiring only called record() inside the cacheable
+      // branches, so events that DO carry the is_error / error / content
+      // tool_result markers (which arrive as a DIFFERENT event type
+      // from the upstream tool_use) never reached the tracker. Result
+      // in production: ctx.recent_error_rate stayed pinned at 0 even
+      // when the agent's tools were failing constantly, making the
+      // "throttle a flailing agent" policy class effectively a no-op.
+      //
+      // Implementation note: try/finally guarantees record() runs even
+      // when the cacheable branches `continue;` out mid-iteration. The
+      // finally executes BEFORE the continue takes effect (JS spec), so
+      // the compute() calls below — which must see PRIOR history only —
+      // still observe the correct window.
+      try {
+
       // ── INTERRUPT MODE ──────────────────────────────────────────────
       if (mode === 'interrupt' && CACHEABLE_TOOL_TYPES.has(rawEvent.type)) {
         // No caching in interrupt mode — react synchronously, free memory.
         const normalized = normalizeForPolicy(rawEvent);
         // v1.2.0 — compute policy context BEFORE evaluate so rules see
-        // PRIOR history (recent_error_rate, agent_age_minutes, …), then
-        // record AFTER so the next event sees this one in its window.
+        // PRIOR history (recent_error_rate, agent_age_minutes, …). The
+        // finally at the end of this iteration records the event so the
+        // NEXT iteration sees this one in its window.
         const policyCtx = policyTracker.compute(rawEvent);
         const t0 = Date.now();
         const result = evaluate(normalized, ctx.ruleset, policyCtx);
         const decidedInMs = Date.now() - t0;
-        policyTracker.record(rawEvent);
 
         // v1.1.3 Phase 1.D — mode badge in the log line for operator visibility.
         const modeTag = result.mode === 'shadow' ? ' [SHADOW]' : '';
@@ -282,12 +299,14 @@ async function runSessionWorker({ sessionId, ctx }) {
 
           const normalized = normalizeForPolicy(sourceEvent);
           // v1.2.0 — see interrupt-mode block above for the compute /
-          // record ordering rationale.
+          // record ordering rationale. sourceEvent here was the original
+          // tool_use rawEvent at an earlier loop iteration, and was
+          // recorded by THAT iteration's finally — so compute() correctly
+          // sees it as PRIOR history, not as the current event.
           const policyCtx = policyTracker.compute(sourceEvent);
           const t0 = Date.now();
           const result = evaluate(normalized, ctx.ruleset, policyCtx);
           const decidedInMs = Date.now() - t0;
-          policyTracker.record(sourceEvent);
 
           // v1.1.3 Phase 1.D — mode badge in the log line for operator visibility.
           const modeTag = result.mode === 'shadow' ? ' [SHADOW]' : '';
@@ -350,6 +369,21 @@ async function runSessionWorker({ sessionId, ctx }) {
         sinfo(sessionId, `session terminated: ${rawEvent.stop_reason?.type || 'unknown'}`);
         break;
       }
+
+      } finally {
+        // v1.2.1 F-26: record EVERY event into the policy tracker so
+        // recent_error_rate reflects real tool failures (which arrive
+        // as tool_result events carrying is_error: true, NOT as the
+        // upstream tool_use events). defaultIsError() inside the
+        // tracker handles the is_error / error / content[].is_error /
+        // type-contains-'error' shapes — see src/shield/context.js.
+        //
+        // Order: every compute() call above happens BEFORE this
+        // record() (JS guarantees finally runs after try-body but
+        // before continue/break take effect), so the "PRIOR history"
+        // contract of recent_error_rate is preserved.
+        policyTracker.record(rawEvent);
+      }
     }
   } catch (e) {
     if (!signal.aborted) {

package/src/logger.js

@@ -33,6 +33,10 @@ const EXPORT_FIELDS = [
   'cost_usd', 'model',
   'session_tokens', 'session_cost_usd',
   'status', 'error', 'sequence_number', 'session_id',
+  // v1.3.0 — team correlation across cooperating agents. Populated by
+  // adapters that observe handoffs (OpenAI Agents SDK, future Claude
+  // Code workflow runId). Null when unknown / no team scope.
+  'team_id',
 ];
 
 export class Logger {
@@ -78,7 +82,15 @@ export class Logger {
     const path = this._pathForToday();
     const full = {
       id: e.id || randomUUID(),
-      agent_id: this.agentId,
+      // v1.3.0 — prefer the event's agent_id when present so multi-agent
+      // adapters (OpenAI Agents SDK handoffs, future LangGraph subgraphs)
+      // can attribute each event to its actual emitter. Falls back to
+      // the Logger's constructor agentId for single-agent adapters
+      // (Anthropic Managed) where every event from this logger belongs
+      // to the same agent. Backwards compatible: existing Anthropic
+      // adapter doesn't populate e.agent_id on every yield, so the
+      // fallback path keeps its behavior intact.
+      agent_id: e.agent_id || this.agentId,
       // 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.
@@ -107,6 +119,10 @@ export class Logger {
       session_id: this.sessionId,
       session_tokens: e.session_tokens ?? null,
       session_cost_usd: e.session_cost_usd ?? null,
+      // v1.3.0 — team correlation. Adapters that observe multi-agent
+      // groupings (OpenAI Agents SDK handoffs, future Claude Code
+      // workflow runId) populate this. Null when unknown.
+      team_id: e.team_id ?? null,
       input: e.input ?? null,
       output: e.output ?? null,
     };

package/src/sources/contract.js

@@ -140,9 +140,15 @@ export const COMPOSITION_PATTERNS = Object.freeze({
 // name here as they land so consumers can build provider-specific UI.
 export const PROVIDERS = Object.freeze({
   ANTHROPIC_MANAGED: 'anthropic-managed',
+  // v1.3.0 (Phase 2.A) — OpenAI Agents SDK (TypeScript/JS).
+  // Customer-instrumented (not auto-discovery). Push-model via:
+  //   - Tool Input Guardrails (Shield enforcement: allow/deny/interrupt)
+  //   - RunHooks EventEmitter (Watch observability)
+  // See `./openai-agents-js.js` and `docs/adapters/openai-agents-js.md`.
+  OPENAI_AGENTS: 'openai-agents',
   // Coming next:
-  // OPENAI_AGENTS: 'openai-agents',
   // AWS_BEDROCK_AGENTCORE: 'aws-bedrock-agentcore',
+  // CLAUDE_CODE: 'claude-code',
   // LANGGRAPH: 'langgraph',
   // CREWAI: 'crewai',
 });
@@ -190,6 +196,30 @@ export const PROVIDERS = Object.freeze({
 //  * @property {string|null} agent_name             The human-named emitter of this event
 //  *                                                (the parent agent OR a sub-agent
 //  *                                                running inside the parent's session).
+//  *
+//  * TEAM CORRELATION (v1.3.0 — Phase 2.A OpenAI Agents SDK + future
+//  * Claude Code dynamic workflows):
+//  * @property {string|null} team_id                Stable identifier shared by every
+//  *                                                event in a logical group of
+//  *                                                cooperating agents. Sources:
+//  *                                                  (a) customer override via
+//  *                                                      WMA_TEAM_ID env var or
+//  *                                                      programmatic setter,
+//  *                                                  (b) auto-detected from the
+//  *                                                      OpenAI Agents SDK
+//  *                                                      `agent_handoff` event —
+//  *                                                      all agents in the handoff
+//  *                                                      chain share the same
+//  *                                                      team_id,
+//  *                                                  (c) future: Claude Code dynamic
+//  *                                                      workflow `runId`.
+//  *                                                Drives the Legions UI "Team view"
+//  *                                                drill-down. Null when unknown.
+//  *
+//  * RUNTIME-COMPUTED CONTEXT (v1.2.0 — see src/shield/context.js):
+//  *  ctx attributes (hour_of_day_utc, recent_error_rate, etc.) are NOT stored
+//  *  on WMAAction — they're computed at policy eval time and live in the
+//  *  ContextTracker only.
 //  */
 
 const REQUIRED_FIELDS = ['id', 'provider', 'agent_id', 'session_id', 'action_type', 'timestamp', 'status'];

package/src/sources/openai-agents-js.d.ts

@@ -0,0 +1,278 @@
+// TypeScript types for the OpenAI Agents SDK adapter — v1.3.0.
+//
+// These types pin the PUBLIC surface customers consume. The runtime
+// (openai-agents-js.js) is plain JS to preserve the zero-runtime-deps
+// invariant; this .d.ts is consumed by tsc only and never executed.
+//
+// The guardrail return shape and the EventEmitter event signatures
+// mirror @openai/agents v0.x — we don't import from it (also to avoid
+// dragging it as a runtime dep here), we re-declare the minimal subset
+// we need.
+
+// ── @openai/agents shapes we reference (minimal re-declaration) ────────
+
+/** Mirrors @openai/agents `ToolGuardrailBehavior`. */
+export type WMAToolGuardrailBehavior =
+  | { type: 'allow' }
+  | { type: 'rejectContent'; message: string }
+  | { type: 'throwException' };
+
+/** Mirrors @openai/agents `ToolGuardrailFunctionOutput`. */
+export interface WMAToolGuardrailFunctionOutput {
+  behavior: WMAToolGuardrailBehavior;
+  outputInfo?: unknown;
+}
+
+/** Mirrors @openai/agents `ToolInputGuardrailData`. */
+export interface WMAToolInputGuardrailData {
+  context?: unknown;
+  agent?: { name?: string; model?: string; instructions?: string };
+  toolCall?: {
+    id?: string;
+    callId?: string;
+    name?: string;
+    arguments?: string | object;
+  };
+}
+
+/**
+ * Return value of {@link wmaToolInputGuardrail}. Shape-compatible with
+ * @openai/agents `ToolInputGuardrailDefinition`. Drop into an Agent's
+ * `toolInputGuardrails: [...]` array.
+ */
+export interface WMAToolInputGuardrail {
+  readonly type: 'tool_input';
+  readonly name: string;
+  run: (data: WMAToolInputGuardrailData) => Promise<WMAToolGuardrailFunctionOutput>;
+}
+
+// ── Adapter-specific types ─────────────────────────────────────────────
+
+/** Minimal Logger surface — for advanced injection in tests. */
+export interface WMALogger {
+  write(event: unknown): Promise<unknown>;
+}
+
+/** Minimal DecisionLogger surface. */
+export interface WMADecisionLogger {
+  record(args: {
+    sourceEvent: unknown;
+    decision: string;
+    ruleId: string | null;
+    ruleName: string | null;
+    message: string | null;
+    decidedInMs: number | null;
+    mode: 'enforce' | 'shadow';
+  }): Promise<unknown>;
+}
+
+/** Minimal ContextTracker surface. */
+export interface WMAContextTracker {
+  compute(event: unknown, at?: number): {
+    hour_of_day_utc: number;
+    day_of_week_utc: number;
+    agent_age_minutes: number;
+    session_duration_ms: number;
+    recent_error_rate: number;
+    event_count_recent: number;
+    event_count_total: number;
+  };
+  record(event: unknown, opts?: { isError?: boolean }): void;
+  reset(): void;
+}
+
+/** Minimal team tracker for handoff propagation. */
+export interface WMATeamTracker {
+  resolve(sessionId: string): string | null;
+  bootstrap(sessionId: string): string;
+  recordHandoff(fromAgent: unknown, toAgent: unknown, sessionId: string): string | null;
+}
+
+/** Options for {@link wmaToolInputGuardrail}. */
+export interface WMAGuardrailOptions {
+  /** Path to a local JSON policy file. Loaded lazily on first invocation. */
+  policiesPath?: string;
+  /** In-memory ruleset (overrides policiesPath). Useful for tests. */
+  ruleset?: { policies: unknown[]; default?: { action: string } };
+  /** Directory for NDJSON logs. Defaults to env WMA_LOG_DIR or ./watchmyagents-logs. */
+  logDir?: string;
+  /** Override the session id. Defaults to an auto-minted UUID. */
+  sessionId?: string;
+  /** Trailing window for `ctx.recent_error_rate` etc. Default: 20. */
+  recentWindowSize?: number;
+  /** On Shield internal error, allow vs deny. Default: false (fail-CLOSED). */
+  failOpen?: boolean;
+  /** Custom team id resolver — overrides env + handoff propagation. */
+  getTeamId?: () => string | null;
+  /** Inject an existing Logger (testing). */
+  logger?: WMALogger;
+  /** Inject an existing DecisionLogger (testing). */
+  decisionLogger?: WMADecisionLogger;
+  /** Inject an existing ContextTracker (testing). */
+  tracker?: WMAContextTracker;
+}
+
+/**
+ * Build the WMA Shield as an @openai/agents Tool Input Guardrail.
+ *
+ * Usage:
+ * ```typescript
+ * import { Agent } from '@openai/agents';
+ * import { wmaToolInputGuardrail } from 'watchmyagents';
+ *
+ * const wmaShield = wmaToolInputGuardrail({
+ *   policiesPath: './policies/mitre-starter.json',
+ * });
+ *
+ * const agent = new Agent({
+ *   name: 'Support bot',
+ *   instructions: '...',
+ *   tools: [...],
+ *   toolInputGuardrails: [wmaShield],
+ * });
+ * ```
+ */
+export function wmaToolInputGuardrail(options?: WMAGuardrailOptions): WMAToolInputGuardrail;
+
+// ── Watch ──────────────────────────────────────────────────────────────
+
+/** Minimal Runner surface (the part of @openai/agents we touch). */
+export interface WMARunnerLike {
+  on(event: string, listener: (...args: any[]) => void): unknown;
+  off?(event: string, listener: (...args: any[]) => void): unknown;
+}
+
+/** Minimal Agent surface — same shape as Runner from an EventEmitter
+ * perspective. The methods are identical; the difference is the listener
+ * signatures (see attachWmaWatchToAgent). */
+export interface WMAAgentLike {
+  on(event: string, listener: (...args: any[]) => void): unknown;
+  off?(event: string, listener: (...args: any[]) => void): unknown;
+}
+
+/** Options for {@link attachWmaWatch}. */
+export interface WMAWatchOptions {
+  logDir?: string;
+  sessionId?: string;
+  logger?: WMALogger;
+  teamTracker?: WMATeamTracker;
+}
+
+/**
+ * Attach WMA Watch listeners to an @openai/agents Runner. Returns a
+ * detach function the customer can call on shutdown.
+ *
+ * USE THIS when the customer creates a Runner explicitly:
+ * ```typescript
+ * import { Runner } from '@openai/agents';
+ * import { attachWmaWatch } from 'watchmyagents';
+ *
+ * const runner = new Runner();
+ * const detach = attachWmaWatch(runner);
+ *
+ * await runner.run(agent, input);
+ *
+ * detach();  // optional, on process shutdown
+ * ```
+ *
+ * If the customer uses the convenience `run(agent, ...)` function
+ * (no explicit Runner), use {@link attachWmaWatchToAgent} instead.
+ */
+export function attachWmaWatch(
+  runner: WMARunnerLike,
+  options?: WMAWatchOptions,
+): () => void;
+
+/**
+ * Attach WMA Watch listeners to an @openai/agents Agent (AgentHooks
+ * pattern). Use this when the customer uses the convenience
+ * `run(agent, ...)` function rather than creating an explicit Runner.
+ *
+ * The AgentHooks event signatures differ slightly from RunHooks:
+ * agent_end, agent_handoff, agent_tool_start, agent_tool_end do NOT
+ * pass the agent in their args — it's captured via closure here.
+ *
+ * Usage:
+ * ```typescript
+ * import { Agent, run } from '@openai/agents';
+ * import { attachWmaWatchToAgent } from 'watchmyagents';
+ *
+ * const myAgent = new Agent({ name: 'support_bot', tools: [...] });
+ * const detach = attachWmaWatchToAgent(myAgent);
+ *
+ * await run(myAgent, 'help me reset my password');
+ *
+ * detach();  // optional, on process shutdown
+ * ```
+ */
+export function attachWmaWatchToAgent(
+  agent: WMAAgentLike,
+  options?: WMAWatchOptions,
+): () => void;
+
+// ── Normalizers (exported for advanced users / tests) ──────────────────
+
+/** Mirrors the WMA contract `WMAAction` shape. */
+export interface WMAAction {
+  id: string;
+  provider: string;
+  agent_id: string;
+  agent_name: string | null;
+  session_id: string;
+  session_thread_id: string | null;
+  action_type: string;
+  timestamp: string;
+  status: 'ok' | 'error' | 'blocked';
+  tool_name: string | null;
+  model: string | null;
+  duration_ms: number | null;
+  parent_agent_id: string | null;
+  composition_pattern: 'solo' | 'hierarchy' | 'graph' | 'peer';
+  team_id: string | null;
+  input: object | null;
+  output: object | null;
+}
+
+export interface NormalizeArgs<T extends string> {
+  sessionId: string;
+  teamId: string | null;
+  agent?: { name?: string; model?: string };
+}
+
+export function normalizeAgentStart(args: NormalizeArgs<'agent_start'> & { turnInput?: unknown[] }): Readonly<WMAAction>;
+export function normalizeAgentEnd(args: NormalizeArgs<'agent_end'> & { output?: string }): Readonly<WMAAction>;
+export function normalizeAgentHandoff(args: NormalizeArgs<'agent_handoff'> & {
+  fromAgent?: { name?: string; model?: string };
+  toAgent?: { name?: string; model?: string };
+}): Readonly<WMAAction>;
+export function normalizeToolStart(args: NormalizeArgs<'tool_start'> & {
+  tool?: { name?: string };
+  toolCall?: { id?: string; callId?: string; name?: string; arguments?: string | object };
+}): Readonly<WMAAction>;
+export function normalizeToolEnd(args: NormalizeArgs<'tool_end'> & {
+  tool?: { name?: string };
+  toolCall?: { id?: string; callId?: string; name?: string; arguments?: string | object };
+  result?: unknown;
+}): Readonly<WMAAction>;
+
+// ── Adapter metadata ───────────────────────────────────────────────────
+
+export interface WMAAdapterMeta {
+  readonly provider: 'openai-agents';
+  readonly displayName: string;
+  readonly enforcement: 'sync_confirm' | 'sync_interrupt' | 'detect_only';
+  readonly compositionDefault: 'solo' | 'hierarchy' | 'graph' | 'peer';
+  readonly customerInstrumented: true;
+  readonly peerPackage: '@openai/agents';
+  readonly minPeerVersion: string;
+  readonly capabilities: Readonly<{
+    watch: boolean;
+    shield: boolean;
+    preToolDeny: boolean;
+    postToolFilter: boolean;
+    teamIdAutoDetect: boolean;
+    streamingSupported: boolean | string;
+  }>;
+}
+
+export const adapterMeta: WMAAdapterMeta;