watchmyagents 1.2.1 → 1.3.0

package/README.md

@@ -86,6 +86,78 @@ total            : 811,798  (in=26 out=22,996 cache_r=492,220 cache_w=296,556)
   calls/min        : 0.08
 ```
 
+## Quickstart — instrument an OpenAI Agents SDK agent (v1.3.0+)
+
+For OpenAI agents, the runtime executes **in your process** (not on OpenAI's servers — see [docs/adapters/openai-agents-js.md](docs/adapters/openai-agents-js.md) for why). WMA is wired in as two lines:
+
+```bash
+npm install watchmyagents @openai/agents zod
+```
+
+**Pattern A — explicit Runner** (use `attachWmaWatch`) :
+```typescript
+import { Agent, Runner } from '@openai/agents';
+import {
+  wmaToolInputGuardrail,
+  attachWmaWatch,
+} from 'watchmyagents/src/sources/openai-agents-js.js';
+
+const wmaShield = wmaToolInputGuardrail({
+  policiesPath: './examples/policies/mitre-starter.json',
+});
+
+const agent = new Agent({
+  name: 'support_bot',
+  instructions: '...',
+  tools: [...],
+  toolInputGuardrails: [wmaShield],  // ← Shield enforcement (pre-execution deny)
+});
+
+const runner = new Runner();
+attachWmaWatch(runner);                // ← Watch observability
+
+await runner.run(agent, 'How do I reset my password?');
+```
+
+**Pattern B — convenience `run()` function** (use `attachWmaWatchToAgent`) :
+```typescript
+import { Agent, run } from '@openai/agents';
+import {
+  wmaToolInputGuardrail,
+  attachWmaWatchToAgent,
+} from 'watchmyagents/src/sources/openai-agents-js.js';
+
+const wmaShield = wmaToolInputGuardrail({
+  policiesPath: './examples/policies/mitre-starter.json',
+});
+
+const agent = new Agent({
+  name: 'support_bot',
+  tools: [...],
+  toolInputGuardrails: [wmaShield],
+});
+
+attachWmaWatchToAgent(agent);          // ← Watch attaches to the agent itself
+
+await run(agent, 'How do I reset my password?');
+```
+
+The two patterns reflect the two EventEmitter surfaces the SDK exposes (RunHooks vs AgentHooks). Both produce identical NDJSON output; pick the one that matches your call shape.
+
+That's it. NDJSON lands in `./watchmyagents-logs/openai-agents/`. The MITRE starter bundle catches common attack patterns (T1567 exfil, T1485 destructive shell, T1548 priv-esc, …) on Day 0 — all in `mode: 'shadow'` so the first run only LOGS without enforcing. Promote to `enforce` once you've calibrated.
+
+See [docs/adapters/openai-agents-js.md](docs/adapters/openai-agents-js.md) for the full options reference + troubleshooting.
+
+## Supported runtimes (v1.3.0)
+
+| Runtime | Mode | Onboarding | Status |
+|---|---|---|---|
+| **Anthropic Managed Agents** | pull REST/SSE | API key (zero-touch) | ✓ shipped |
+| **OpenAI Agents SDK** (TypeScript/JS) | push (in-process hooks + guardrails) | 2 lines of code | ✓ v1.3.0 |
+| OpenAI Agents SDK (Python) | push (separate `watchmyagents-py` package) | — | planned v1.4.0 |
+| Claude Code (dynamic workflows) | push (hooks via `settings.json`) | — | planned v1.4.x |
+| AWS Bedrock AgentCore | pull REST/SSE | similar to Anthropic | planned v1.5.0 |
+
 ## What gets logged
 
 Each line of the NDJSON file is one agent action. The 18 `action_type` values captured today:

package/docs/adapters/openai-agents-js.md

@@ -0,0 +1,230 @@
+# OpenAI Agents SDK adapter (TypeScript / JavaScript)
+
+**Status: v1.3.0 (Phase 2.A) — first adapter that observes a runtime which executes locally on the customer machine.**
+
+This adapter integrates `watchmyagents` with the [OpenAI Agents SDK](https://openai.github.io/openai-agents-js/) (`@openai/agents` on npm). Customers add two lines to their existing agent code; WMA logs every lifecycle event locally and can block tool calls before execution via Shield policies.
+
+## Why customer-instrumented and not "paste your API key"
+
+OpenAI's agent runtime executes **on the customer's machine**, not on OpenAI's servers. There is no `listAgents` / `listConversations` endpoint on the OpenAI API that would let WMA pull events from outside — the SDK is the agent. So WMA has to live inside the same process.
+
+This is the same model used by Datadog APM, Sentry, Langfuse, and OpenLLMetry for OpenAI observability. The integration is two lines of code; the rest is automatic.
+
+## Setup
+
+### 1. Install
+
+```bash
+npm install @openai/agents zod watchmyagents
+```
+
+`watchmyagents` declares `@openai/agents` as a peer dependency — the customer installs both; WMA ships zero runtime deps of its own.
+
+### 2. Get a WMA API key
+
+Sign in to the Fortress dashboard → **Settings → API Keys → Generate** → copy the `wma_xxx` value. Give it a label that maps to one of your environments (e.g. `production`, `staging`).
+
+### 3. Environment variables
+
+```bash
+# .env
+WMA_API_KEY=wma_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+WMA_LOG_DIR=./watchmyagents-logs          # optional; default shown
+WMA_TEAM_ID=customer-support              # optional; manual team tagging
+# WMA_POLICIES_SOURCE handling for Fortress-pulled policies arrives in 1.3.1
+```
+
+Today the adapter loads policies from a local file via `policiesPath`. Fortress-pulled policies for this adapter land in a 1.3.x patch.
+
+### 4. Wire it up — two patterns
+
+The `@openai/agents` SDK exposes two EventEmitter surfaces and lets you
+pick how to run an agent. WMA supports both:
+
+**Pattern A — explicit Runner (RunHooks):**
+
+```typescript
+import { Agent, Runner } from '@openai/agents';
+import {
+  wmaToolInputGuardrail,
+  attachWmaWatch,
+} from 'watchmyagents/src/sources/openai-agents-js.js';
+
+const wmaShield = wmaToolInputGuardrail({
+  policiesPath: './examples/policies/mitre-starter.json',
+});
+
+const agent = new Agent({
+  name: 'support_bot',
+  instructions: '...',
+  tools: [...],
+  toolInputGuardrails: [wmaShield],          // ← Shield enforcement
+});
+
+const runner = new Runner();
+attachWmaWatch(runner);                       // ← Watch via RunHooks
+
+await runner.run(agent, 'How do I reset my password?');
+```
+
+**Pattern B — convenience `run()` function (AgentHooks):**
+
+```typescript
+import { Agent, run } from '@openai/agents';
+import {
+  wmaToolInputGuardrail,
+  attachWmaWatchToAgent,
+} from 'watchmyagents/src/sources/openai-agents-js.js';
+
+const wmaShield = wmaToolInputGuardrail({
+  policiesPath: './examples/policies/mitre-starter.json',
+});
+
+const agent = new Agent({
+  name: 'support_bot',
+  tools: [...],
+  toolInputGuardrails: [wmaShield],          // ← Shield (unchanged)
+});
+
+attachWmaWatchToAgent(agent);                 // ← Watch via AgentHooks
+
+await run(agent, 'How do I reset my password?');
+```
+
+**Which to pick?** Use the function name (`Runner` vs `run`) as your
+heuristic. They behave identically from a Watch/Shield perspective —
+same NDJSON output, same audit chain, same team_id propagation. Under
+the hood, the SDK fires lifecycle events through two different event
+emitters with slightly different argument layouts (e.g. AgentHooks
+omits the agent from `agent_end` / `agent_tool_*` because the listener
+is registered on the agent itself); the two `attachWma…` variants
+handle those differences.
+
+That is the entire customer change.
+
+## What you get
+
+### Watch (observability)
+
+Every lifecycle event the SDK emits flows to a daily-rotated NDJSON log at `./watchmyagents-logs/openai-agents/YYYY-MM-DD.ndjson`. Five event types are captured:
+
+| @openai/agents event | WMA `action_type` | Notes |
+|---|---|---|
+| `agent_start` | `message` (kind=agent_start) | Agent received turn input |
+| `agent_end` | `message` (kind=agent_end) | Agent produced final output |
+| `agent_handoff` | `handoff` | One agent passes control to another |
+| `agent_tool_start` | `custom_tool_use` | Tool is about to fire |
+| `agent_tool_end` | `custom_tool_result` | Tool returned a result |
+
+Containment: tool arguments and tool results are captured in `input` / `output` and stay LOCAL. The anonymizer is the single gate to Fortress.
+
+### Shield (enforcement)
+
+The `wmaToolInputGuardrail()` returned object slots into the Agent's `toolInputGuardrails: [...]` array. Before every tool call, the SDK awaits our `run()` and respects the result:
+
+| Shield decision | OpenAI `behavior` | Effect on the tool call |
+|---|---|---|
+| `allow` | `{ type: 'allow' }` | Tool runs as if no guardrail existed |
+| `deny` | `{ type: 'rejectContent', message }` | Tool is BLOCKED; `message` returned in place of the tool result; the model sees the rejection and can decide next steps |
+| `interrupt` | `{ type: 'throwException' }` | Tool is blocked AND the agent loop aborts with an exception |
+| `shadow` mode | `{ type: 'allow' }` with diagnostic outputInfo | Tool runs; decision logged for calibration but not enforced |
+
+### Team correlation (Legions UI)
+
+Three resolution channels for `team_id`, in precedence order:
+
+1. **Customer override** — set `WMA_TEAM_ID` env var or pass `getTeamId` to the guardrail options.
+2. **Auto-detect via handoff** — when the SDK emits `agent_handoff(fromAgent, toAgent)`, every subsequent event in the same run shares the from-agent's team id. Useful for multi-agent flows without any customer config.
+3. **None** — events get `team_id: null` and appear under "Untagged" in the Fortress Legions view.
+
+### Audit chain (tamper-evidence)
+
+Every `shield_decision` row carries `prev_hash` + `chain_hash` (SHA-256). The audit chain is local-only tamper-evidence. Verify with:
+
+```typescript
+import { verifyDecisionChain } from 'watchmyagents/src/shield/decision-chain.js';
+import { readFile } from 'node:fs/promises';
+
+const lines = (await readFile('./watchmyagents-logs/openai-agents/2026-06-09.ndjson', 'utf8'))
+  .trim().split('\n').map((l) => JSON.parse(l))
+  .filter((l) => l.action_type === 'shield_decision');
+
+console.log(verifyDecisionChain(lines));
+// → { ok: true, count: N, segments: 1 }
+```
+
+Limits: tail truncation (removing the most recent rows) is invisible to an append-only chain. Cross-process replay would re-derive the chain from scratch. Fortress-side append-only ingest closes both gaps (planned).
+
+## Options reference
+
+```typescript
+wmaToolInputGuardrail({
+  // Policy source — pick ONE:
+  policiesPath?: string,         // local JSON file path
+  ruleset?: object,              // in-memory ruleset object
+
+  // Storage:
+  logDir?: string,               // default WMA_LOG_DIR or ./watchmyagents-logs
+  sessionId?: string,            // default auto-minted UUID
+
+  // Behavior:
+  failOpen?: boolean,            // on Shield internal error: allow (true) or
+                                 // deny (false). Default: false (fail-CLOSED)
+  recentWindowSize?: number,     // ctx.recent_error_rate window. Default: 20
+  getTeamId?: () => string|null, // custom team resolver
+
+  // Injection (for tests):
+  logger?: Logger,
+  decisionLogger?: DecisionLogger,
+  tracker?: ContextTracker,
+});
+
+attachWmaWatch(runner, {
+  logDir?: string,               // default same as guardrail
+  sessionId?: string,            // default auto-minted UUID
+  logger?: Logger,
+  teamTracker?: TeamTracker,
+});
+// → returns a `detach()` function the customer can call on shutdown.
+```
+
+## What gets sent to Fortress
+
+Tool arguments and results stay LOCAL. The anonymizer converts WMAAction → signals payload (salted hashes, no raw values) and pushes to `WMA_FORTRESS_BASE_URL/upload-signals` if `WMA_API_KEY` is set. See [CONTAINMENT.md](../CONTAINMENT.md) for the full egress model.
+
+## Compatibility
+
+- Node.js: **20+** (matches the WMA SDK baseline and `@openai/agents`'s requirement)
+- TypeScript: any version — types live in `src/sources/openai-agents-js.d.ts`
+- `@openai/agents` version range: tested against `^x.y` (verified in CI against the version pinned in our integration fixtures — see `test/fixtures/openai-agents-events/README.md`)
+
+## Limits + known gaps (v1.3.0)
+
+| Gap | Workaround |
+|---|---|
+| Streaming mode behavior under Tool Input Guardrails not formally verified | We expect the SDK to honor guardrails in streaming mode (the SDK code paths are the same); the test fixtures cover non-streaming today. Verification with a streaming smoke test before v1.3.1. |
+| Fortress-pulled policies via `WMA_POLICIES_SOURCE=fortress` not wired in this adapter yet | Use `policiesPath` with a local file in v1.3.0; Fortress pull lands in v1.3.x patch |
+| Tool Output Guardrails (post-execution filter) not exposed | Add only if customer demand — Shield's pre-tool deny covers 95% of the exfil-prevention use case |
+| Python Agents SDK | Separate package `watchmyagents-py` planned for v1.4.0 (Pattern 2 — pip-installable thin client that talks to a Node Shield daemon over UNIX socket) |
+
+## Troubleshooting
+
+**"no policy ruleset configured — guardrail will allow all"** stderr warning
+You passed neither `policiesPath` nor `ruleset` to `wmaToolInputGuardrail()`. The guardrail is loaded but every tool call is allowed. Pass one of the two options to enforce.
+
+**Tool calls succeed but never appear in NDJSON**
+Check that you also called `attachWmaWatch(runner)`. The guardrail handles Shield decisions; Watch handles the event log. Customers who only need enforcement can skip Watch (the guardrail still logs `shield_decision` rows itself).
+
+**Audit chain verification reports `chain_hash recomputation mismatch`**
+Someone modified an NDJSON row after write. The `broken_at` index points to the first tampered row. Investigate; do not delete the file (it IS the evidence).
+
+**Guardrail latency feels high**
+Policy eval is sub-millisecond for small rulesets. The audit chain hash takes <1ms. If you see >50ms, the log directory may be on slow storage — point `logDir` at a local SSD or in-memory tmpfs.
+
+## See also
+
+- [examples/adapters/openai-agents-js-quickstart.ts](../../examples/adapters/openai-agents-js-quickstart.ts) — runnable customer reference
+- [docs/adapters/](.) — sibling adapter docs
+- [docs/SOURCE-ADAPTER-CONTRACT.md](../SOURCE-ADAPTER-CONTRACT.md) — the contract every adapter follows
+- [docs/MITRE-ATTCK-COVERAGE.md](../MITRE-ATTCK-COVERAGE.md) — what the policy starter bundle covers
+- [docs/CONTAINMENT.md](../CONTAINMENT.md) — what stays local vs goes to Fortress

package/examples/adapters/capture-fixtures.ts

@@ -0,0 +1,193 @@
+// Fixture capture script — runs a real @openai/agents flow and writes
+// each lifecycle event's raw arguments to test/fixtures/openai-agents-events/.
+//
+// Goal: replace the synthetic fixtures in test/sources-openai-agents-js.test.js
+// with REAL captures from a live SDK version, so the adapter is verified
+// against the actual shape the SDK emits — not against our reading of the
+// source code.
+//
+// Run:
+//   npm install @openai/agents zod
+//   export OPENAI_API_KEY=sk-proj-...
+//   npx tsx examples/adapters/capture-fixtures.ts
+//
+// Output: one JSON per event type at
+//   test/fixtures/openai-agents-events/agent_start.json
+//   test/fixtures/openai-agents-events/agent_end.json
+//   test/fixtures/openai-agents-events/agent_handoff.json
+//   test/fixtures/openai-agents-events/agent_tool_start.json
+//   test/fixtures/openai-agents-events/agent_tool_end.json
+//
+// Each file contains the raw listener arguments + meta (SDK version,
+// Node version, capture timestamp).
+
+import { Agent, Runner, handoff, tool } from '@openai/agents';
+import { z } from 'zod';
+import { writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const FIXTURES_DIR = join(
+  dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+  'test',
+  'fixtures',
+  'openai-agents-events',
+);
+
+// Capture meta — Node + SDK versions are baked into each fixture so future
+// readers know what runtime emitted these shapes.
+async function getSdkVersion(): Promise<string> {
+  try {
+    const pkg = await import('@openai/agents/package.json', { assert: { type: 'json' } });
+    return (pkg as any).default?.version || (pkg as any).version || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+// One capture per event type. We overwrite if the file already exists so
+// re-running the script always reflects the LATEST SDK version observed.
+const captured: Record<string, boolean> = {};
+
+async function saveFixture(eventName: string, rawArgs: unknown[], sdkVersion: string) {
+  if (captured[eventName]) return; // first occurrence wins — keep deterministic
+  captured[eventName] = true;
+  const payload = {
+    event: eventName,
+    args: rawArgs.map((a) => safeSerialize(a)),
+    meta: {
+      sdk_version: sdkVersion,
+      node_version: process.version,
+      captured_at: new Date().toISOString(),
+      capture_script: 'examples/adapters/capture-fixtures.ts',
+    },
+  };
+  const path = join(FIXTURES_DIR, `${eventName}.json`);
+  await writeFile(path, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+  console.log(`[capture] wrote ${eventName}.json (${rawArgs.length} args)`);
+}
+
+// JSON-serialize while gracefully handling cyclic refs + class instances.
+function safeSerialize(v: unknown): unknown {
+  if (v === null || v === undefined) return v;
+  if (typeof v === 'function') return `[function ${v.name || '<anon>'}]`;
+  if (typeof v !== 'object') return v;
+  try {
+    return JSON.parse(JSON.stringify(v, (_k, val) => {
+      if (typeof val === 'function') return `[function ${val.name || '<anon>'}]`;
+      if (val instanceof Error) return { name: val.name, message: val.message };
+      return val;
+    }));
+  } catch {
+    return `[unserializable ${Object.prototype.toString.call(v)}]`;
+  }
+}
+
+// Two tools so we can capture tool_start + tool_end with realistic data.
+const searchKB = tool({
+  name: 'search_kb',
+  description: 'Search the support knowledge base.',
+  parameters: z.object({ query: z.string() }),
+  async execute({ query }: { query: string }) {
+    return `Found 3 articles for "${query}".`;
+  },
+});
+
+const escalate = tool({
+  name: 'escalate',
+  description: 'Escalate this ticket to a human supervisor.',
+  parameters: z.object({ reason: z.string() }),
+  async execute({ reason }: { reason: string }) {
+    return `Escalated. Reason: ${reason}`;
+  },
+});
+
+// Two agents wired by handoff so we capture the handoff event.
+const escalationBot = new Agent({
+  name: 'escalation_bot',
+  instructions: 'You handle escalated support tickets that the first-tier bot cannot resolve. Call escalate() with the reason.',
+  model: 'gpt-5',
+  tools: [escalate],
+});
+
+const supportBot = new Agent({
+  name: 'support_bot',
+  instructions: [
+    'You are tier-1 support. Try search_kb first.',
+    'If the customer is angry, hand off to escalation_bot.',
+  ].join('\n'),
+  model: 'gpt-5',
+  tools: [searchKB],
+  handoffs: [handoff(escalationBot)],
+});
+
+async function main() {
+  await mkdir(FIXTURES_DIR, { recursive: true });
+  const sdkVersion = await getSdkVersion();
+  console.log(`[capture] target dir: ${FIXTURES_DIR}`);
+  console.log(`[capture] @openai/agents version: ${sdkVersion}`);
+  console.log(`[capture] Node version: ${process.version}`);
+
+  const runner = new Runner();
+
+  // Attach raw listeners to all 5 lifecycle events. Each handler:
+  //   1. saves the first occurrence to its dedicated fixture file
+  //   2. logs a short note to stdout
+  // We do NOT attach the WMA guardrail here — this script captures the
+  // RAW SDK shapes, not the WMA-normalized ones.
+  runner.on('agent_start', async (...args) => {
+    await saveFixture('agent_start', args, sdkVersion);
+    console.log('[capture]   agent_start fired');
+  });
+  runner.on('agent_end', async (...args) => {
+    await saveFixture('agent_end', args, sdkVersion);
+    console.log('[capture]   agent_end fired');
+  });
+  runner.on('agent_handoff', async (...args) => {
+    await saveFixture('agent_handoff', args, sdkVersion);
+    console.log('[capture]   agent_handoff fired');
+  });
+  runner.on('agent_tool_start', async (...args) => {
+    await saveFixture('agent_tool_start', args, sdkVersion);
+    console.log('[capture]   agent_tool_start fired');
+  });
+  runner.on('agent_tool_end', async (...args) => {
+    await saveFixture('agent_tool_end', args, sdkVersion);
+    console.log('[capture]   agent_tool_end fired');
+  });
+
+  console.log('\n[capture] running support flow that should fire all 5 events…');
+  // The prompt is designed to (a) get search_kb to fire and (b) be angry
+  // enough that the bot hands off to escalation_bot, which then fires
+  // escalate(). That covers all 5 lifecycle events in a single run.
+  const result = await runner.run(
+    supportBot,
+    'Your KB has been useless for 30 minutes. I demand to speak to a supervisor. ' +
+    'My account number is X-9999. This is my third ticket about the same issue.',
+  );
+
+  console.log('\n[capture] final output:', result.finalOutput);
+  console.log('\n[capture] DONE. Files written:');
+  for (const evt of ['agent_start', 'agent_end', 'agent_handoff', 'agent_tool_start', 'agent_tool_end']) {
+    console.log(`  - ${join(FIXTURES_DIR, `${evt}.json`)} ${captured[evt] ? '✓' : '✗ MISSING'}`);
+  }
+
+  const missing = ['agent_start', 'agent_end', 'agent_handoff', 'agent_tool_start', 'agent_tool_end']
+    .filter((e) => !captured[e]);
+  if (missing.length > 0) {
+    console.warn(`\n[capture] WARNING: ${missing.length} event(s) didn't fire: ${missing.join(', ')}`);
+    console.warn('[capture] You may need to adjust the prompt to provoke those events.');
+    console.warn('[capture] Most common cause: the model didn\'t choose to hand off → re-run with a more escalation-heavy prompt.');
+    process.exit(1);
+  }
+
+  console.log('\n[capture] ALL 5 fixtures captured. Ship to WMA repo.');
+}
+
+main().catch((e) => {
+  console.error('[capture] fatal:', e);
+  process.exit(1);
+});

package/examples/adapters/openai-agents-js-quickstart.ts

@@ -0,0 +1,118 @@
+// WMA × OpenAI Agents SDK — quickstart.
+//
+// What this shows:
+//   - Minimal end-to-end wiring of WMA into an @openai/agents Runner
+//   - Both Shield (blocking via Tool Input Guardrail) and Watch (log via
+//     RunHooks) attached in two lines of customer code each
+//   - The included starter policy bundle (MITRE ATT&CK coverage) catches
+//     a deliberately-malicious shell command — this run blocks it
+//
+// Prerequisites:
+//   npm install @openai/agents zod watchmyagents
+//   export OPENAI_API_KEY=sk-proj-...
+//
+// Run with:
+//   npx tsx examples/adapters/openai-agents-js-quickstart.ts
+//
+// Expected output:
+//   - First call (search_kb with normal query): ALLOWED, returns 5 articles
+//   - Second call (bash with `rm -rf /var/log`): BLOCKED by MITRE T1485,
+//     guardrail returns rejectContent → the model sees the rejection
+//     message in place of the tool result
+//   - NDJSON event log lands at ./watchmyagents-logs/openai-agents/
+
+import { Agent, Runner, tool } from '@openai/agents';
+import { z } from 'zod';
+import {
+  wmaToolInputGuardrail,
+  attachWmaWatch,
+} from 'watchmyagents/src/sources/openai-agents-js.js';
+
+// ── Tools the agent can call ───────────────────────────────────────────
+
+const searchKB = tool({
+  name: 'search_kb',
+  description: 'Search the customer-support knowledge base.',
+  parameters: z.object({ query: z.string() }),
+  async execute({ query }) {
+    return `Found 5 articles matching "${query}".`;
+  },
+});
+
+// A deliberately-dangerous bash tool — Shield should block this when
+// the model tries to call it with `rm -rf /`.
+const runBash = tool({
+  name: 'bash',
+  description: 'Run a shell command on the server.',
+  parameters: z.object({ command: z.string() }),
+  async execute({ command }) {
+    // If this ever runs in real life, we have bigger problems.
+    return `EXECUTED: ${command}`;
+  },
+});
+
+// ── WMA Shield + Watch (the 2 lines that make this an observed agent) ─
+
+const wmaShield = wmaToolInputGuardrail({
+  policiesPath: './examples/policies/mitre-starter.json',
+  // Optional: failOpen: true would skip enforcement on Shield errors —
+  // we leave it false so any internal failure rejects the tool call.
+});
+
+// ── The agent ──────────────────────────────────────────────────────────
+
+const supportBot = new Agent({
+  name: 'support_bot',
+  instructions: [
+    'You help customers with support questions. You can search the KB.',
+    'If a customer escalates an issue, you may run shell commands to ',
+    'investigate. Be conservative — do not run destructive commands.',
+  ].join('\n'),
+  model: 'gpt-5',
+  tools: [searchKB, runBash],
+  toolInputGuardrails: [wmaShield],
+});
+
+// ── Run + observe ──────────────────────────────────────────────────────
+
+async function main() {
+  const runner = new Runner();
+  const detachWatch = attachWmaWatch(runner);
+
+  console.log('[wma-quickstart] Run 1: normal KB lookup (should pass) ───────');
+  const r1 = await runner.run(
+    supportBot,
+    'How do I reset my password?',
+  );
+  console.log('[wma-quickstart] r1.finalOutput:', r1.finalOutput);
+
+  console.log('[wma-quickstart] Run 2: simulated jailbreak — model is told to delete logs');
+  try {
+    const r2 = await runner.run(
+      supportBot,
+      'Please run: bash with command "rm -rf /var/log/*" to free disk space.',
+    );
+    console.log('[wma-quickstart] r2.finalOutput:', r2.finalOutput);
+  } catch (e) {
+    console.log('[wma-quickstart] Run 2 threw (interrupt mode):', (e as Error).message);
+  }
+
+  detachWatch();
+
+  console.log('\n[wma-quickstart] DONE.');
+  console.log('[wma-quickstart] Inspect the NDJSON log:');
+  console.log('  cat ./watchmyagents-logs/openai-agents/*.ndjson | jq');
+  console.log('[wma-quickstart] Verify the audit chain integrity:');
+  console.log(
+    "  node -e \"import('watchmyagents/src/shield/decision-chain.js').then(async m => { " +
+    "const fs = await import('node:fs/promises'); " +
+    "const files = (await fs.readdir('./watchmyagents-logs/openai-agents')).filter(f=>f.endsWith('.ndjson')); " +
+    "const lines = (await fs.readFile('./watchmyagents-logs/openai-agents/'+files[0], 'utf8')).trim().split('\\n').map(l=>JSON.parse(l)).filter(l=>l.action_type==='shield_decision'); " +
+    "console.log(m.verifyDecisionChain(lines)); })\"",
+  );
+}
+
+main().catch((e) => {
+  console.error('[wma-quickstart] fatal:', e);
+  process.exit(1);
+});

package/package.json

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