watchmyagents 1.2.1 → 1.3.0

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;