watchmyagents 1.2.1 → 1.4.0

package/src/anonymizer.js

@@ -156,17 +156,65 @@ export function normalizeToolInput(rawInput, aliases = {}) {
 // programmatically reference the contract.
 export { HASHABLE_INPUT_FIELDS };
 
+// ── Heuristic field-name patterns (v1.3.1 F-30 Codex audit on v1.3.0) ───
+//
+// HASHABLE_INPUT_FIELDS is the canonical set; adapter authors are also
+// encouraged to call `normalizeToolInput()` to map their native names.
+// But OpenAI Agents SDK customers define their own tool argument names
+// (`endpoint_url`, `shell_cmd`, `requestUrl`, …) and rarely think to
+// register aliases. The result before v1.3.1: those fields silently
+// disappeared from Fortress signals — not a leak (the raw payload stays
+// LOCAL), but a detection blind spot.
+//
+// This heuristic catches the long tail. For each non-canonical input
+// field, if its NAME matches a common suffix/word pattern, hash its
+// value as if it were the corresponding canonical field. Conservative
+// by design: regex anchored to word/suffix boundaries (`_url` matches,
+// `urlsafe` does NOT) so we err toward false positives (hashing a
+// harmless field is fine) over false negatives (missing a sensitive
+// field is the bug we're fixing).
+//
+// Add new patterns here when adapters surface new common names.
+const HEURISTIC_FIELD_PATTERNS = Object.freeze({
+  url:     /(?:^|[_-])(?:url|uri|endpoint|webhook|address)$/i,
+  command: /(?:^|[_-])(?:cmd|command|shell|exec|script)$/i,
+  path:    /(?:^|[_-])(?:path|file|filename|filepath|dir|folder)$/i,
+  query:   /(?:^|[_-])(?:query|search|q|prompt|term)$/i,
+});
+
+function fieldMatchesCanonicalByHeuristic(fieldName, canonical) {
+  const pat = HEURISTIC_FIELD_PATTERNS[canonical];
+  return pat ? pat.test(fieldName) : false;
+}
+
 // ── Single-entry extractor: what hashable IoCs are in this entry? ────────
 
 function extractIocs(entry, salt) {
   const out = [];
   if (!entry.input || typeof entry.input !== 'object') return out;
+
+  // Exact canonical match (original v1.0+ behavior — backwards compat).
   for (const field of HASHABLE_INPUT_FIELDS) {
     const v = entry.input[field];
     if (typeof v === 'string' && v.length > 0) {
       out.push(hashWithSalt(v, salt));
     }
   }
+
+  // v1.3.1 F-30 — heuristic suffix matching for non-canonical field
+  // names common to OpenAI Agents SDK / LangGraph / CrewAI tools. Skip
+  // fields already handled above so we never double-hash.
+  for (const [key, v] of Object.entries(entry.input)) {
+    if (HASHABLE_INPUT_FIELDS.includes(key)) continue;
+    if (typeof v !== 'string' || v.length === 0) continue;
+    for (const canonical of HASHABLE_INPUT_FIELDS) {
+      if (fieldMatchesCanonicalByHeuristic(key, canonical)) {
+        out.push(hashWithSalt(v, salt));
+        break; // one canonical bucket per field — first match wins
+      }
+    }
+  }
+
   return out;
 }
 

package/src/index.js

@@ -0,0 +1,52 @@
+// WatchMyAgents — main entry point (v1.4 Codex #10).
+//
+// `import { ... } from 'watchmyagents'` resolves here via the package.json
+// `exports['.']` field. For adapter-specific imports (the recommended
+// path for v1.4+), use the sub-entries:
+//
+//   import { openaiAgents } from 'watchmyagents/openai-agents';
+//
+// This root entry exposes the most stable cross-adapter primitives:
+//   - the source-adapter contract (PROVIDERS, ACTION_TYPES, COMPOSITION_PATTERNS,
+//     ENFORCEMENT_MODES, validateWMAAction)
+//   - the policy engine + context tracker + decision chain that EVERY
+//     adapter shares
+//   - the Logger
+//
+// Internal modules (`src/sources/openai-agents-js.js`,
+// `src/shield/*.js`, etc.) remain accessible to advanced consumers via
+// deep imports, but those paths are NOT part of the stable surface;
+// they may move between minor releases. Stick to the sub-entries and
+// this root export for production code.
+
+// ── Source-adapter contract ─────────────────────────────────────────
+export {
+  PROVIDERS,
+  ACTION_TYPES,
+  STATUS_VALUES,
+  ENFORCEMENT_MODES,
+  COMPOSITION_PATTERNS,
+  validateWMAAction,
+} from './sources/contract.js';
+
+// ── Shield engine (policy eval + context + audit chain) ─────────────
+export {
+  evaluate,
+  matchesPolicy,
+  loadPolicies,
+} from './shield/policy.js';
+
+export { createContextTracker, defaultIsError } from './shield/context.js';
+
+export {
+  createDecisionChain,
+  verifyDecisionChain,
+  buildGenesisMarker,
+  newChainId,
+  CHAIN_FIELDS,
+} from './shield/decision-chain.js';
+
+export { DecisionLogger } from './shield/decisions.js';
+
+// ── Logger ──────────────────────────────────────────────────────────
+export { Logger } from './logger.js';

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/openai-agents.js

@@ -0,0 +1,202 @@
+// Public entry point for the OpenAI Agents SDK adapter (v1.4 Codex #1).
+//
+// Customers import the SDK like this:
+//
+//   import { openaiAgents } from 'watchmyagents/openai-agents';
+//
+//   const wma = openaiAgents({
+//     policiesPath: './policies.json',
+//     logDir: './watchmyagents-logs',
+//     mode: 'enforce',  // 'observe' | 'enforce' (default 'enforce')
+//     toolInputs: {
+//       fetch_url: { endpoint_url: 'url' },     // per-tool aliases
+//       shell:     { shell_cmd: 'command' },
+//     },
+//   });
+//
+//   const agent = new Agent({
+//     name: 'support_bot',
+//     tools,
+//     toolInputGuardrails: [wma.shield()],   // ← Shield
+//   });
+//
+//   wma.watch(agent);   // ← Watch (auto-detects Agent vs Runner)
+//   // or:
+//   wma.watch(runner);
+//
+//   await run(agent, 'help me');
+//
+// Why a factory: it lets the customer configure once (policy path,
+// log dir, mode, tool input aliases) and get back a small object with
+// `shield()` and `watch()` methods that share that config. The pre-v1.4
+// pattern asked customers to import deep paths (
+// `watchmyagents/src/sources/openai-agents-js.js`) and pass options to
+// each call — fragile and verbose. This entry point is the stable
+// surface; the internal module stays free to refactor.
+
+import {
+  wmaToolInputGuardrail,
+  attachWmaWatch,
+  attachWmaWatchToAgent,
+  adapterMeta,
+} from './sources/openai-agents-js.js';
+
+/**
+ * Build the WMA OpenAI Agents SDK adapter from a single shared config.
+ *
+ * @param {object} [options]
+ * @param {string} [options.policiesPath]      Local JSON policy file.
+ * @param {object} [options.ruleset]           In-memory ruleset.
+ * @param {string} [options.logDir]            NDJSON log dir.
+ * @param {'observe'|'enforce'} [options.mode] v1.4 Codex #2 — explicit
+ *                                             mode. `enforce` requires
+ *                                             a policy source; `observe`
+ *                                             attaches Watch only and
+ *                                             refuses to issue a Shield
+ *                                             (calling `.shield()` throws
+ *                                             so it's impossible to ship
+ *                                             a build that looks armed
+ *                                             but isn't).
+ * @param {object<string, object>} [options.toolInputs]
+ *   v1.4 Codex #4 — per-tool argument aliases. Maps tool_name →
+ *   { nativeFieldName: canonicalFieldName }. Applied alongside the
+ *   F-30 heuristic so customers with off-canonical arg names get
+ *   exact hashing without relying on the suffix heuristic.
+ * @param {boolean} [options.failOpen]         Default false (closed).
+ * @param {number} [options.maxArgBytes]       Default 256 KB.
+ * @param {number} [options.maxResultBytes]    Default 256 KB.
+ * @param {object} [options.tracker]           Inject ContextTracker.
+ * @param {object} [options.logger]            Inject Logger.
+ * @param {object} [options.decisionLogger]    Inject DecisionLogger.
+ * @returns {{
+ *   shield: () => object,
+ *   watch:  (target: object) => () => void,
+ *   meta:   typeof adapterMeta,
+ * }}
+ */
+export function openaiAgents(options = {}) {
+  const mode = options.mode || 'enforce';
+  if (mode !== 'observe' && mode !== 'enforce') {
+    throw new TypeError(
+      `openaiAgents: options.mode must be 'observe' or 'enforce', got '${mode}'`,
+    );
+  }
+
+  // v1.4 Codex #2 — fail-loud refusal to start in enforce mode without
+  // any policy source. Avoids the v1.3.0 footgun where missing policies
+  // silently degraded to "allow all" with only a stderr warning. The
+  // failure surfaces at config time (not on the first request) so it's
+  // impossible to deploy a build that LOOKS armed but isn't.
+  if (mode === 'enforce' && options.policiesPath == null && options.ruleset == null) {
+    throw new Error(
+      "openaiAgents({ mode: 'enforce' }) requires policiesPath or ruleset. " +
+      "Either provide one, or switch to { mode: 'observe' } if you only " +
+      "want Watch (NDJSON capture) without Shield enforcement.",
+    );
+  }
+
+  // Shared config we thread into both shield() and watch() so the
+  // customer doesn't have to repeat it.
+  const sharedOptions = {
+    policiesPath:    options.policiesPath,
+    ruleset:         options.ruleset,
+    logDir:          options.logDir,
+    sessionId:       options.sessionId,
+    failOpen:        options.failOpen,
+    recentWindowSize: options.recentWindowSize,
+    getTeamId:       options.getTeamId,
+    tracker:         options.tracker,
+    logger:          options.logger,
+    decisionLogger:  options.decisionLogger,
+    toolInputs:      options.toolInputs,
+    maxArgBytes:     options.maxArgBytes,
+    maxResultBytes:  options.maxResultBytes,
+  };
+
+  return Object.freeze({
+    /** Returns the @openai/agents Tool Input Guardrail. In `observe`
+     *  mode this throws — the customer asked for Watch-only and a
+     *  guardrail would be misleading. */
+    shield() {
+      if (mode === 'observe') {
+        throw new Error(
+          "openaiAgents({ mode: 'observe' }).shield() is not allowed. " +
+          "Observe mode does not produce Shield enforcement. " +
+          "Switch to { mode: 'enforce', policiesPath: '...' } if you want to block.",
+        );
+      }
+      return wmaToolInputGuardrail(sharedOptions);
+    },
+
+    /** Attaches Watch listeners. Auto-detects whether `target` is an
+     *  Agent (AgentHooks) or a Runner (RunHooks) by checking method
+     *  shape and known fields. Returns a detach function. */
+    watch(target) {
+      return autoAttachWatch(target, sharedOptions);
+    },
+
+    /** Adapter metadata — useful for tooling that wants to introspect
+     *  what's available (capabilities, peer-dep min version, etc.). */
+    meta: adapterMeta,
+
+    /** The configured mode, exposed for runtime introspection. */
+    mode,
+  });
+}
+
+// v1.4 Codex #7 — auto-detect Runner vs Agent and dispatch to the
+// matching attach function. The shape difference:
+//   - @openai/agents Runner has `.run(agent, input)` AND emits the
+//     RunHooks events with the agent as an explicit arg.
+//   - @openai/agents Agent has `.name`/`.instructions`/`.tools` AND
+//     emits AgentHooks events with the agent IMPLICIT (closure-
+//     captured by attachWmaWatchToAgent).
+//
+// Both expose `.on()` from the EventEmitter base. We detect the
+// runner by checking for `.run` (function) — it's the convenience the
+// Runner class exposes that Agent doesn't. As a tiebreaker we look
+// at the presence of `.tools` (Agent-only) and the absence of `.name`
+// is fine as a hint but not load-bearing.
+function autoAttachWatch(target, options) {
+  if (!target || typeof target.on !== 'function') {
+    throw new TypeError(
+      'openaiAgents().watch(target): target must expose .on(event, listener). ' +
+      'Pass an @openai/agents Runner or Agent instance.',
+    );
+  }
+  // Independent signal checks — DO NOT make `looksLikeRunner` exclusive
+  // of `looksLikeAgent`. The whole point of the ambiguity check below
+  // is to catch targets that satisfy both shapes.
+  const hasRunMethod = typeof target.run === 'function';
+  const hasAgentShape = Array.isArray(target.tools) && typeof target.name === 'string';
+
+  if (hasRunMethod && hasAgentShape) {
+    throw new TypeError(
+      'openaiAgents().watch(target): target looks like both Agent and Runner ' +
+      '(has .tools[] AND .name AND .run() method). Disambiguate by calling ' +
+      'attachWmaWatch(runner) or attachWmaWatchToAgent(agent) directly.',
+    );
+  }
+  if (hasAgentShape) {
+    return attachWmaWatchToAgent(target, options);
+  }
+  if (hasRunMethod) {
+    return attachWmaWatch(target, options);
+  }
+  // Neither shape unambiguously identified — fall back to AgentHooks
+  // since the convenience `run(agent, ...)` function dispatches
+  // AgentHooks, which is the more common path for new customers
+  // (validated against real fixtures captured 2026-06-10).
+  return attachWmaWatchToAgent(target, options);
+}
+
+// Re-export the low-level functions so customers that need fine-grained
+// control (e.g. test scaffolding, advanced multi-runner setups) can
+// still reach them. The factory is the recommended entry point; these
+// are the escape hatches.
+export {
+  wmaToolInputGuardrail,
+  attachWmaWatch,
+  attachWmaWatchToAgent,
+  adapterMeta,
+};

package/src/shield/decisions.js

@@ -15,7 +15,17 @@ import { Logger } from '../logger.js';
 import { createDecisionChain, buildGenesisMarker, newChainId } from './decision-chain.js';
 
 export class DecisionLogger {
-  constructor({ logDir, agentId, sessionId }) {
+  // v1.3.1 F-29 (P1 Codex audit on v1.3.0): `provider` is now an
+  // explicit constructor option. Before v1.3.1 the provider was
+  // hard-coded to `anthropic-managed` in record() — when the OpenAI
+  // Agents SDK adapter (shipped v1.3.0) wrote shield_decision rows
+  // through this logger, those rows were mis-attributed to Anthropic.
+  // Fortress / Guardian forensic surfaces saw OpenAI blocks as
+  // Anthropic blocks. Default is preserved at `anthropic-managed` so
+  // existing v1.2.x callers behave unchanged; the OpenAI adapter
+  // explicitly passes `provider: PROVIDERS.OPENAI_AGENTS`.
+  constructor({ logDir, agentId, sessionId, provider }) {
+    this._provider = provider || 'anthropic-managed';
     // Each DecisionLogger instance owns a single chain segment. A Shield
     // restart creates a fresh DecisionLogger → fresh genesis. The
     // genesis marker is self-describing (agent + session + start time +
@@ -53,7 +63,7 @@ export class DecisionLogger {
       && (decision === 'deny' || decision === 'interrupt');
     return this._logger.write({
       action_type: 'shield_decision',
-      provider: 'anthropic-managed',
+      provider: this._provider,
       tool_name: sourceEvent?.name || sourceEvent?.tool_name || null,
       status: enforced ? 'error' : 'ok',
       error: enforced ? message : 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'];