watchmyagents 1.4.7 → 1.4.8

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

@@ -29,12 +29,31 @@ Sign in to the Fortress dashboard → **Settings → API Keys → Generate** →
 ```bash
 # .env
 WMA_API_KEY=wma_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+WMA_FORTRESS_BASE_URL=https://<project>.supabase.co/functions/v1   # for Fortress policies + decisions
+WMA_SIGNALS_SALT=<stable per-customer salt>   # hashes session/input in uploads
 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.
+**Policy source (v1.4.6+).** The adapter can load policies two ways:
+- **Fortress (recommended)** — `policies: { source: 'fortress' }` pulls the ruleset
+  live from Fortress (the same control plane `wma-shield` uses for Anthropic) and
+  refreshes it in the background. Requires `agentId` + `WMA_API_KEY` +
+  `WMA_FORTRESS_BASE_URL`. This is what the Fortress "Register an OpenAI agent"
+  onboarding gives you.
+- **Local file** — `policiesPath: './policies.json'` (or an in-memory `ruleset`),
+  for tests / air-gapped setups.
+
+```typescript
+import { openaiAgents } from 'watchmyagents/openai-agents';
+
+const wma = openaiAgents({
+  mode: 'enforce',
+  agentId: 'support_bot',                 // your Fortress-registered agent id
+  policies: { source: 'fortress' },       // WMA_API_KEY + WMA_FORTRESS_BASE_URL from env
+  // policies: { source: 'fortress', uploadDecisions: false }  // ← keep decisions local-only
+});
+```
 
 ### 4. Wire it up — two patterns
 
@@ -190,20 +209,23 @@ attachWmaWatch(runner, {
 
 ## 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.
+Tool arguments and results stay LOCAL. The anonymizer converts WMAAction → a signals payload (salted hashes, no raw values). Two egress paths, both anonymized — see [CONTAINMENT.md](../CONTAINMENT.md) for the full model:
+
+- **Signals** — aggregated counts + salted IoC hashes, uploaded to `ingest-signals` (run `wma-upload-fortress --provider openai-agents --agent-id <id>` against the NDJSON, or the Watch path).
+- **Decisions (v1.4.7+)** — when `policies: { source: 'fortress' }` is set, the guardrail ships each Shield decision to `ingest-decisions` **fire-and-forget** (off the hot path). The payload carries `provider: 'openai-agents'`, `native_agent_id`, the decision/rule, salted `session_hash`/`event_id_hash`/`input_hash`, and `enforcement_delivered` (always `true` for an enforced deny/interrupt — the in-process guardrail blocks synchronously). The local NDJSON `shield_decision` row is the durable record; a failed upload never blocks the tool call. In-flight uploads are bounded (`maxDecisionUploadsInFlight`, default 32) — under a Fortress outage the excess is dropped from the live post (still in NDJSON). Opt out with `policies: { uploadDecisions: false }` to keep decisions local-only.
 
 ## 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`
+- TypeScript: any version — `import { openaiAgents } from 'watchmyagents/openai-agents'` is fully typed (`src/openai-agents.d.ts`); the low-level escape hatches are typed in `src/sources/openai-agents-js.d.ts`.
 - `@openai/agents` version range: **`^0.2.0`** (declared in `package.json#peerDependencies`). Real fixtures in `test/fixtures/openai-agents-events/` were captured against 0.2.x and the adapter's lifecycle event signatures match that line. Older 0.1.x lacked AgentHooks ergonomics the adapter relies on.
 
-## Limits + known gaps (v1.3.0)
+## Limits + known gaps (v1.4.8)
 
 | 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 |
+| Decision uploads are live fire-and-forget — a short-lived process can lose in-flight posts on exit | The NDJSON `shield_decision` row is durable; a batch backfill (NDJSON → `ingest-decisions`) is planned for fully-durable short runs |
 | 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) |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "watchmyagents",
-  "version": "1.4.7",
+  "version": "1.4.8",
   "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": [
@@ -22,7 +22,7 @@
   "exports": {
     ".": "./src/index.js",
     "./openai-agents": {
-      "types": "./src/sources/openai-agents-js.d.ts",
+      "types": "./src/openai-agents.d.ts",
       "default": "./src/openai-agents.js"
     },
     "./package.json": "./package.json"

package/src/openai-agents.d.ts

@@ -0,0 +1,110 @@
+// Type declarations for the stable entry point `watchmyagents/openai-agents`.
+//
+// The runtime is src/openai-agents.js (the openaiAgents() factory + the
+// re-exported low-level escape hatches). v1.4.8 (P2 quality): these types were
+// previously pointed at the low-level module's .d.ts, which never declared
+// openaiAgents() nor the v1.4.6/1.4.7 options (agentId, policies.source,
+// uploadDecisions, signalsSalt) — TS users got a broken/incomplete typed API.
+
+import type {
+  WMAToolInputGuardrail,
+  WMAGuardrailOptions,
+  WMAAdapterMeta,
+  WMARunnerLike,
+  WMAAgentLike,
+  WMAWatchOptions,
+} from './sources/openai-agents-js';
+
+// Re-export the low-level types + escape-hatch functions so TS users importing
+// from 'watchmyagents/openai-agents' see the full surface the runtime exports.
+export * from './sources/openai-agents-js';
+
+/** Live policy source config. Today only Fortress is supported. */
+export interface OpenaiAgentsPoliciesConfig {
+  /** Pull the ruleset from Fortress (the same control plane wma-shield uses). */
+  source: 'fortress';
+  /** Fortress functions base URL. Defaults to WMA_FORTRESS_BASE_URL. */
+  baseUrl?: string;
+  /** WMA API key. Defaults to WMA_API_KEY. */
+  apiKey?: string;
+  /** Require Ed25519-signed policies (strict mode). */
+  requireSignedPolicies?: boolean;
+  /** Fail mode when a refresh yields no valid policies ('open' | 'closed'). */
+  failMode?: 'open' | 'closed';
+  /** Ship Shield decisions to the same Fortress's ingest-decisions.
+   *  Default: true. Set false to keep decisions local-only (NDJSON). */
+  uploadDecisions?: boolean;
+}
+
+/** Options for {@link openaiAgents}. */
+export interface OpenaiAgentsOptions {
+  /** 'enforce' (default) requires a policy source; 'observe' attaches Watch
+   *  only and makes .shield() throw. */
+  mode?: 'observe' | 'enforce';
+  /** Agent id registered in Fortress — NDJSON path + native_agent_id, and
+   *  scopes the Fortress policy pull. Required with policies.source='fortress'. */
+  agentId?: string;
+  /** Live policy source (Fortress). Mutually complete with policiesPath/ruleset. */
+  policies?: OpenaiAgentsPoliciesConfig;
+  /** Local JSON policy file. */
+  policiesPath?: string;
+  /** In-memory ruleset (overrides policiesPath). */
+  ruleset?: { policies: unknown[]; default?: { action: string } };
+  /** NDJSON log dir. Defaults to WMA_LOG_DIR or ./watchmyagents-logs. */
+  logDir?: string;
+  /** Override the session id (default: auto-minted). */
+  sessionId?: string;
+  /** Salt for hashing session/input in the Fortress decision payload.
+   *  Defaults to WMA_SIGNALS_SALT. */
+  signalsSalt?: string;
+  /** On Shield internal error, allow vs deny. Default: false (fail-CLOSED). */
+  failOpen?: boolean;
+  /** Trailing window for ctx.recent_error_rate etc. Default: 20. */
+  recentWindowSize?: number;
+  /** Custom team id resolver. */
+  getTeamId?: () => string | null;
+  /** Per-tool argument aliases ({ tool: { nativeField: canonical } }). */
+  toolInputs?: Record<string, Record<string, string>>;
+  /** Byte caps on captured tool args / results. Default 256 KB. */
+  maxArgBytes?: number;
+  maxResultBytes?: number;
+  /** Cap on concurrent in-flight decision uploads (excess dropped best-effort,
+   *  NDJSON stays durable). Default: 32. */
+  maxDecisionUploadsInFlight?: number;
+  /** Inject for testing. */
+  tracker?: unknown;
+  logger?: unknown;
+  decisionLogger?: unknown;
+}
+
+/** The object returned by {@link openaiAgents}. */
+export interface OpenaiAgentsHandle {
+  /** The @openai/agents Tool Input Guardrail (Shield). Throws in observe mode. */
+  shield(): WMAToolInputGuardrail;
+  /** Attach Watch — auto-detects Runner vs Agent. Returns a detach function. */
+  watch(target: WMARunnerLike | WMAAgentLike): () => void;
+  /** Adapter metadata. */
+  readonly meta: WMAAdapterMeta;
+  /** The configured mode. */
+  readonly mode: 'observe' | 'enforce';
+}
+
+/**
+ * Build the WMA OpenAI Agents SDK adapter from one shared config.
+ *
+ * ```typescript
+ * import { openaiAgents } from 'watchmyagents/openai-agents';
+ * import { Agent, run } from '@openai/agents';
+ *
+ * const wma = openaiAgents({
+ *   mode: 'enforce',
+ *   agentId: 'support_bot',
+ *   policies: { source: 'fortress' },   // WMA_API_KEY + WMA_FORTRESS_BASE_URL from env
+ * });
+ *
+ * const agent = new Agent({ name: 'support_bot', tools, toolInputGuardrails: [wma.shield()] });
+ * wma.watch(agent);
+ * await run(agent, 'help me');
+ * ```
+ */
+export function openaiAgents(options?: OpenaiAgentsOptions): OpenaiAgentsHandle;

package/src/openai-agents.js

@@ -163,6 +163,7 @@ export function openaiAgents(options = {}) {
     agentId:         options.agentId,            // v1.4.6: NDJSON path + native_agent_id
     fortressPolicySource,                        // v1.4.6: live Fortress ruleset (or null)
     fortressDecisionSink,                        // v1.4.7 #1: ship decisions (or null)
+    maxDecisionUploadsInFlight: options.maxDecisionUploadsInFlight,  // v1.4.8: backpressure cap
     signalsSalt:     options.signalsSalt || process.env.WMA_SIGNALS_SALT,  // hash session/input
     policiesPath:    options.policiesPath,
     ruleset:         options.ruleset,

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

@@ -110,6 +110,32 @@ export interface WMAGuardrailOptions {
   decisionLogger?: WMADecisionLogger;
   /** Inject an existing ContextTracker (testing). */
   tracker?: WMAContextTracker;
+  /** v1.4.6 — agent id used for the NDJSON path segment + native_agent_id.
+   *  Defaults to 'openai-agents' when un-named. */
+  agentId?: string;
+  /** v1.4.6 — a live policy source (e.g. FortressPolicySource). The guardrail
+   *  single-flight-starts it then reads current() on every call. */
+  fortressPolicySource?: {
+    start(): Promise<void>;
+    current(): { policies: unknown[]; default?: { action: string } };
+  };
+  /** v1.4.7 — best-effort sink the guardrail fires each decision to
+   *  (fire-and-forget). Built by openaiAgents() from policies.source='fortress'. */
+  fortressDecisionSink?: (payload: object) => unknown | Promise<unknown>;
+  /** v1.4.7 — salt for hashing session/input in the Fortress decision payload
+   *  (defaults to WMA_SIGNALS_SALT). Without it, those hashes are null. */
+  signalsSalt?: string;
+  /** v1.4.7 — cap on concurrent in-flight decision uploads; excess are dropped
+   *  best-effort (NDJSON stays durable). Default: 32. */
+  maxDecisionUploadsInFlight?: number;
+  /** v1.4 Codex #4 — per-tool argument aliases ({ tool: { nativeField: canonical } }). */
+  toolInputs?: Record<string, Record<string, string>>;
+  /** v1.4 F-32 — byte caps on captured tool args / results. Default 256 KB. */
+  maxArgBytes?: number;
+  maxResultBytes?: number;
+  /** v1.4.1 F-35 — explicit escape hatch to allow ALL tool calls when no policy
+   *  source is configured (demos/smoke tests only). */
+  allowAllWhenUnconfigured?: boolean;
 }
 
 /**

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

@@ -523,6 +523,15 @@ export function wmaToolInputGuardrail(options = {}) {
     ? options.getTeamId
     : () => teamTracker.bootstrap(sessionId);
 
+  // v1.4.8 (P2 audit): bound the best-effort decision uploads. A Fortress
+  // outage + a high tool-call rate could otherwise accumulate unbounded
+  // in-flight POSTs in the agent process. We cap concurrency and DROP excess
+  // (the NDJSON shield_decision row is the durable record), with a throttled
+  // stderr summary so the operator notices sustained backpressure.
+  const maxDecisionUploadsInFlight = options.maxDecisionUploadsInFlight ?? 32;
+  let decisionUploadsInFlight = 0;
+  let decisionUploadsDropped = 0;
+
   // Lazily load the ruleset on first invocation if a path was given.
   // v1.4.6: SINGLE-FLIGHT start. start() creates a setInterval, so two
   // concurrent first tool-calls must NOT both call it (that leaks a second
@@ -643,21 +652,43 @@ export function wmaToolInputGuardrail(options = {}) {
         // enforcement_delivered (the v1.4.6 prereqs) so Fortress attributes it
         // to the right runtime and surfaces degraded enforcement.
         if (options.fortressDecisionSink) {
-          try {
-            const payload = buildFortressDecisionPayload({
-              agentId: loggerAgentId,
-              provider: PROVIDER,
-              nativeAgentId: loggerAgentId,
-              sessionId,
-              rawEvent: event,
-              normalized: event,
-              result,
-              decidedInMs,
-              signalsSalt: options.signalsSalt,
-              enforcementDelivered: enforcedBlock ? true : undefined,
-            });
-            Promise.resolve(options.fortressDecisionSink(payload)).catch(() => undefined);
-          } catch { /* payload build must never break enforcement */ }
+          if (decisionUploadsInFlight >= maxDecisionUploadsInFlight) {
+            // Backpressure: drop the live post (NDJSON keeps the record).
+            decisionUploadsDropped++;
+            if (decisionUploadsDropped === 1 || decisionUploadsDropped % 100 === 0) {
+              process.stderr.write(
+                `[wma/openai-agents] Fortress decision-upload backpressure: ${decisionUploadsDropped} ` +
+                `decision(s) dropped from the live post (still in local NDJSON); ` +
+                `in-flight cap=${maxDecisionUploadsInFlight}\n`,
+              );
+            }
+          } else {
+            let payload = null;
+            try {
+              payload = buildFortressDecisionPayload({
+                agentId: loggerAgentId,
+                provider: PROVIDER,
+                nativeAgentId: loggerAgentId,
+                sessionId,
+                rawEvent: event,
+                normalized: event,
+                result,
+                decidedInMs,
+                signalsSalt: options.signalsSalt,
+                enforcementDelivered: enforcedBlock ? true : undefined,
+              });
+            } catch { /* build error → skip the post; never break enforcement */ }
+            if (payload) {
+              decisionUploadsInFlight++;
+              // Defer the sink call INTO the promise chain so a synchronous
+              // throw becomes a rejection — the .finally then always runs and
+              // the in-flight counter can never leak (which would wedge the cap).
+              Promise.resolve()
+                .then(() => options.fortressDecisionSink(payload))
+                .catch(() => undefined)
+                .finally(() => { decisionUploadsInFlight--; });
+            }
+          }
         }
 
         // 5. Watch log (the event itself, separate from the decision).