@intutic/gate 1.10.1

package/dist/openai.js

@@ -0,0 +1,658 @@
+/**
+ * OpenAI Agents SDK (TypeScript) adapter: `intuticToolGuardrail()`,
+ * `wrapTools()`, `wrapAgent()`, `installOpenAiGate()`.
+ *
+ * `@intutic/gate/openai` — a framework-specific specialization of the same
+ * idea `wrapTools.ts` implements generically (see that file's module doc):
+ * wrap the framework's own veto point around this package's `Gate.guard()`.
+ * The TypeScript twin of the Python SDK's
+ * `intutic_clawde.gate.adapters.openai_agents` (`intutic_tool_guardrail`).
+ *
+ * ## The veto mechanism — CONFIRMED against a real install
+ *
+ * `@openai/agents@0.16.1` was installed as a devDependency of this package
+ * and its shipped `.d.ts`/compiled source read directly (not inferred from
+ * docs alone). `@openai/agents` is a meta-package (`export * from
+ * '@openai/agents-core'` + `'@openai/agents-openai'` + `export * as
+ * realtime`); the relevant surface lives in `@openai/agents-core`:
+ *
+ * The SDK's documented per-tool veto point is a **tool input guardrail**
+ * (`dist/toolGuardrail.d.ts`, present since `@openai/agents-core` 0.3.8,
+ * 2026-01-14):
+ *
+ * ```ts
+ * interface ToolInputGuardrailDefinition<TContext> {
+ *   type: 'tool_input'
+ *   name: string
+ *   run: (data: { context: RunContext; agent: Agent; toolCall: protocol.FunctionCallItem })
+ *     => Promise<ToolGuardrailFunctionOutput>   // { behavior, outputInfo? }
+ * }
+ * // behavior: {type:'allow'} | {type:'rejectContent'; message} | {type:'throwException'}
+ * ```
+ *
+ * The runner (`dist/runner/toolExecution.js`) runs every guardrail in
+ * `FunctionTool.inputGuardrails` BEFORE `invoke` — on `rejectContent` the
+ * tool body never runs and `message` becomes the model-visible tool output
+ * (`resolveFunctionFailureOutput`). `protocol.FunctionCallItem.arguments` is
+ * the RAW, unparsed JSON arguments string (`z.ZodString`), same as the Python
+ * SDK's `ToolContext.tool_arguments` — hence {@link toolInputFromArguments}.
+ *
+ * Guardrail attachment is PER-TOOL: there is no run-level tool guardrail.
+ * That is what {@link wrapTools} and {@link wrapAgent} are for.
+ *
+ * Ordering caveat (documented, verified in `toolExecution.js`): for a tool
+ * whose `needsApproval` resolves true, input guardrails run AFTER the
+ * human-approval flow by default. Opt in to guardrails-before-approval with
+ * the run config `toolExecution: { preApprovalInputGuardrails: true }`
+ * (available since `@openai/agents-core` 0.11.8;
+ * `dist/runner/runConfig.d.ts`).
+ *
+ * ## The MCP materialization gotcha — why `wrapAgent` patches `getAllTools`
+ *
+ * Tools contributed by `agent.mcpServers` do NOT live in `agent.tools`: they
+ * are materialized per run by `agent.getAllTools()` → `getMcpTools()` →
+ * `mcpToFunctionTool()` (`dist/mcp.js`), which builds them with the same
+ * `tool()` factory — same guardrail path — but attaches NO guardrails of its
+ * own. Mapping over `agent.tools` alone therefore silently misses every
+ * MCP-sourced tool. {@link wrapAgent} closes that hole by patching the
+ * agent INSTANCE's `getAllTools` to inject the Intutic guardrail into every
+ * `FunctionTool` it returns, MCP-derived ones included (the runner resolves
+ * tools exclusively through `executionAgent.getAllTools(...)` —
+ * `dist/runner/modelPreparation.js`). Injection is idempotent (keyed on
+ * {@link GUARDRAIL_NAME}), so tools that are both in `agent.tools` and in the
+ * `getAllTools` result are gated exactly once.
+ *
+ * ## Non-function tools — what is and is not gateable
+ *
+ *   * **hostedMcpTool** entries execute at OpenAI's side, but expose a
+ *     client-visible approval loop: `providerData.require_approval` /
+ *     `providerData.on_approval` (snake_case POST-construction — the
+ *     camelCase `requireApproval`/`onApproval` exist only as `hostedMcpTool()`
+ *     factory options; the runner reads only the snake_case fields,
+ *     `dist/runner/mcpApprovals.js`). `wrapTools` rewrites these entries to
+ *     `require_approval: 'always'` plus an Intutic `on_approval` that guards
+ *     each call and composes any pre-existing handler. NOTE
+ *     `hostedMcpTool()`'s own default is `require_approval: 'never'` — an
+ *     unwrapped hosted MCP tool is entirely ungated.
+ *   * **shellTool / applyPatchTool** (local) carry `needsApproval` +
+ *     `onApproval` auto-resolvers. `wrapTools` forces `needsApproval` to
+ *     always-true and installs a composed Intutic `onApproval`: gate refusal
+ *     → reject (with the BLOCKED message); gate allow → the tool's ORIGINAL
+ *     approval policy is replayed (original `needsApproval` false → approve;
+ *     original `onApproval` present → delegated to). When the original
+ *     policy demanded a human and no original `onApproval` exists, the
+ *     decision is deliberately left undecided so the interruption still
+ *     surfaces — see {@link OpenAiApprovalDecision} for the verified
+ *     mechanism this relies on.
+ *   * **computerTool** has NO `onApproval` — only a per-action
+ *     `needsApproval` predicate (plus `onSafetyCheck`). `wrapTools` (and
+ *     {@link intuticComputerNeedsApproval}) can therefore only turn a gate
+ *     refusal into `needsApproval → true`, which surfaces as a pending
+ *     interruption in `result.interruptions` that YOUR code must
+ *     `state.reject(...)`. Stated honestly: a caller who `state.approve()`s
+ *     that interruption overrides the gate — the SDK gives this adapter no
+ *     reject-with-message hook for computer actions. (The refusal is still
+ *     emitted to the control plane as `tool_blocked` telemetry either way.)
+ *   * **Hosted tools** (`webSearchTool`, `fileSearchTool`,
+ *     `codeInterpreterTool`, `imageGenerationTool`, ...) are bare
+ *     `HostedTool` objects executed server-side at OpenAI: NO client-side
+ *     guardrail, approval hook, or wrapper ever sees them. The
+ *     hosted-environment variant of `shellTool` (`environment.type:
+ *     'container_*'`) is in the same bucket — its factory options type
+ *     `needsApproval`/`onApproval` as `never`. `wrapTools` passes all of
+ *     these through UNCHANGED rather than pretending they are gated.
+ *
+ * ## Realtime
+ *
+ * `@openai/agents-realtime` honours `FunctionTool.inputGuardrails` through
+ * the same `runToolInputGuardrails` helper (verified in its shipped
+ * `realtimeSession.js`), so a guardrail injected by this module also gates
+ * voice-agent tool calls.
+ *
+ * ## LLM egress and the tracing DLP leak
+ *
+ * Routing chat traffic through the Intutic proxy is env-only for this SDK:
+ * the underlying `openai` client (7.5.0, `client.js`) reads
+ * `OPENAI_BASE_URL` whenever no explicit `baseURL`/client is passed to
+ * `OpenAIProvider` — so a sourced `.env.intutic` governs egress with zero
+ * code, unlike the Vercel AI SDK (see vercel.ts's module doc). The default
+ * transport is the HTTP Responses API, whose wire shape the Intutic proxy
+ * already parses.
+ *
+ * BUT: `@openai/agents-openai`'s tracing exporter POSTs trace spans —
+ * including tool inputs/outputs — to a HARDCODED
+ * `https://api.openai.com/v1/traces/ingest` (`openaiTracingExporter.js`),
+ * bypassing `OPENAI_BASE_URL` entirely, and tracing is ON by default. That
+ * is a real DLP exfiltration path around the proxy.
+ * {@link suppressAgentsTracingExport} (called by {@link installOpenAiGate}
+ * unless opted out) sets the SDK's own kill-switch env
+ * `OPENAI_AGENTS_DISABLE_TRACING=1` (read lazily per run —
+ * `@openai/agents-core`'s `config.js`). Callers who need traces should
+ * instead re-point the exporter endpoint in code
+ * (`new OpenAITracingExporter({ endpoint })` + `setTraceProcessors`) at an
+ * approved collector and opt out with `{ tracingExport: 'keep' }`.
+ *
+ * ## What this module does NOT import
+ *
+ * Deliberately no runtime dependency on `@openai/agents`/
+ * `@openai/agents-core` — the `OpenAi*` types below are narrow structural
+ * copies of only the shapes this adapter touches, same policy as mastra.ts /
+ * vercel.ts / dsh.ts (see dsh.ts's module doc for the full rationale). The
+ * real packages are devDependencies used by `__tests__/openai.test.ts` to
+ * type-check these structural types against the real shipped ones and to
+ * drive the real runner machinery end to end.
+ *
+ * @module
+ */
+import { randomUUID } from 'node:crypto';
+import { Gate, active as activeGate, install } from './gate.js';
+import { GateClient } from './client.js';
+import { IntuticGateRefusal } from './errors.js';
+/** The `name` every guardrail this module builds carries. Also the
+ *  idempotency key: a `FunctionTool` whose `inputGuardrails` already contains
+ *  a guardrail with this name is never double-wrapped. */
+export const GUARDRAIL_NAME = 'intutic';
+const WRAPPED = Symbol.for('intutic.gate.openai.wrapped');
+const AGENT_WRAPPED = Symbol.for('intutic.gate.openai.agentWrapped');
+// ------------------------------------------------------------------ helpers
+function resolveGate(explicit, what) {
+    const g = explicit ?? activeGate();
+    if (g === null) {
+        throw new Error('No gate configured: call install(new Gate(...)) from @intutic/gate, or pass ' +
+            `{ gate } to ${what}. Refusing to run the tool unguarded.`);
+    }
+    return g;
+}
+/**
+ * Parse the raw JSON `arguments` string into the object `Gate.guard()`
+ * evaluates. Port of the Python adapter's `_tool_input_of` — same fallback
+ * keys (`raw`, `value`): a call the gate cannot parse should still reach a
+ * rule, not silently skip evaluation.
+ */
+export function toolInputFromArguments(raw) {
+    if (!raw)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { raw };
+    }
+    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        return parsed;
+    }
+    return { value: parsed };
+}
+function crashMessage(err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    return `[Intutic Governance] BLOCKED: gate crashed (${detail}) — failing closed rather than allowing an unevaluated call.`;
+}
+/** Refusal → rejection decision; anything else → fail-closed rejection.
+ *  Same posture as dsh.ts's `createPreExecuteListener` (see that module's
+ *  doc for why every adapter takes the closed direction on failure). */
+function errorToDecision(err) {
+    if (err instanceof IntuticGateRefusal) {
+        return { approve: false, reason: err.message };
+    }
+    return { approve: false, reason: crashMessage(err) };
+}
+// -------------------------------------------------------- primary guardrail
+/**
+ * Builds the Intutic tool input guardrail — `{ type: 'tool_input', name:
+ * 'intutic', run }` — attachable to any `FunctionTool`, either at
+ * construction:
+ *
+ * ```ts
+ * import { tool } from '@openai/agents'
+ * import { Gate, install } from '@intutic/gate'
+ * import { intuticToolGuardrail } from '@intutic/gate/openai'
+ *
+ * install(new Gate({ workspaceId: process.env.INTUTIC_WORKSPACE_ID }))
+ *
+ * const shell = tool({
+ *   name: 'shell',
+ *   description: 'Run a shell command',
+ *   parameters: z.object({ command: z.string() }),
+ *   inputGuardrails: [intuticToolGuardrail()],
+ *   execute: async ({ command }) => run(command),
+ * })
+ * ```
+ *
+ * or after the fact via {@link wrapTools}/{@link wrapAgent}. On refusal the
+ * guardrail resolves `{ behavior: { type: 'rejectContent', message } }` —
+ * the runner skips the tool body and hands `message` (the
+ * `[Intutic Governance] BLOCKED: ...` text) back to the model in place of a
+ * tool result. On an unexpected gate crash it rejects too (fail closed). On
+ * allow it resolves `{ behavior: { type: 'allow' } }`.
+ *
+ * Requires a `Gate` — either passed via `{ gate }`, or installed
+ * process-wide with `install(new Gate(...))`. A call with neither throws
+ * out of `run` (which the runner escalates into a run-fatal `ToolCallError`)
+ * rather than running the tool unguarded — same posture as
+ * `wrapTool`/`intuticHooks`/`intuticToolApproval`.
+ */
+export function intuticToolGuardrail(opts = {}) {
+    return {
+        type: 'tool_input',
+        name: GUARDRAIL_NAME,
+        run: async (data) => {
+            const g = resolveGate(opts.gate, 'intuticToolGuardrail()');
+            try {
+                await g.guard(data.toolCall.name, toolInputFromArguments(data.toolCall.arguments));
+            }
+            catch (err) {
+                if (err instanceof IntuticGateRefusal) {
+                    return {
+                        behavior: { type: 'rejectContent', message: err.message },
+                        outputInfo: { code: err.code, incidentId: err.incidentId },
+                    };
+                }
+                return { behavior: { type: 'rejectContent', message: crashMessage(err) } };
+            }
+            return { behavior: { type: 'allow' } };
+        },
+    };
+}
+// ------------------------------------------------------- per-type wrapping
+function wrapFunctionTool(tool, opts) {
+    const existing = tool.inputGuardrails ?? [];
+    if (existing.some((gr) => gr.name === GUARDRAIL_NAME))
+        return tool;
+    // Intutic FIRST: a governance refusal should not depend on (or pay the
+    // cost of) whatever caller-authored guardrails follow it.
+    return { ...tool, inputGuardrails: [intuticToolGuardrail(opts), ...existing] };
+}
+function isHostedMcp(tool) {
+    if (tool.name === 'hosted_mcp')
+        return true;
+    const pd = tool.providerData;
+    return pd?.type === 'mcp';
+}
+/** Whether the tool's ORIGINAL `require_approval` demanded approval for
+ *  `toolName`. Interpretation of the filter object form: a tool listed under
+ *  `never` does not need approval; everything else does (matching the
+ *  conservative reading of OpenAI's approval filter — unlisted tools require
+ *  approval unless the whole setting is 'never'). */
+function originallyDemandedApproval(requireApproval, toolName) {
+    if (requireApproval === undefined || requireApproval === 'never')
+        return false;
+    if (requireApproval === 'always')
+        return true;
+    if (requireApproval !== null && typeof requireApproval === 'object') {
+        const filter = requireApproval;
+        const neverNames = filter.never?.tool_names ?? filter.never?.toolNames ?? [];
+        if (neverNames.includes(toolName))
+            return false;
+        return true;
+    }
+    return false;
+}
+function hostedMcpApprovalDetails(item) {
+    const rawItem = item?.rawItem;
+    if (!rawItem || rawItem.type !== 'hosted_tool_call')
+        return null;
+    const pd = rawItem.providerData ?? {};
+    const toolName = typeof pd.name === 'string' && pd.name.length > 0
+        ? pd.name
+        : typeof rawItem.name === 'string' && rawItem.name !== 'mcp_approval_request'
+            ? rawItem.name
+            : null;
+    if (toolName === null)
+        return null;
+    return {
+        toolName,
+        ...(typeof pd.arguments === 'string' ? { rawArguments: pd.arguments } : {}),
+    };
+}
+function wrapHostedMcpTool(tool, opts) {
+    const marked = tool;
+    if (marked[WRAPPED] === true)
+        return tool;
+    const pd = { ...(tool.providerData ?? {}) };
+    const originalOnApproval = pd.on_approval ?? pd.onApproval;
+    const originalRequireApproval = pd.require_approval ?? pd.requireApproval;
+    pd.require_approval = 'always';
+    pd.on_approval = async (context, item) => {
+        const g = resolveGate(opts.gate, 'wrapTools()');
+        const details = hostedMcpApprovalDetails(item);
+        if (details === null) {
+            // Nothing recognisable to evaluate — refuse rather than approve a call
+            // the gate never saw.
+            return {
+                approve: false,
+                reason: '[Intutic Governance] BLOCKED: could not extract the MCP tool call from the approval ' +
+                    'request — failing closed rather than approving an unevaluated call.',
+            };
+        }
+        try {
+            await g.guard(details.toolName, toolInputFromArguments(details.rawArguments));
+        }
+        catch (err) {
+            return errorToDecision(err);
+        }
+        if (originalOnApproval)
+            return originalOnApproval(context, item);
+        if (originallyDemandedApproval(originalRequireApproval, details.toolName)) {
+            // The caller's original config demanded a human for this tool but gave
+            // the runner no resolver. The hosted-MCP approval loop consumes
+            // decisions with a truthy check (see OpenAiApprovalDecision's doc), so
+            // there is no "leave it pending" here: per this product's own posture
+            // (gate.ts, SOP_RULE_APPROVAL), an approval that cannot be granted is a
+            // block. Keep your own onApproval on the hostedMcpTool — this wrapper
+            // composes with it — to retain a human flow.
+            return {
+                approve: false,
+                reason: '[Intutic Governance] BLOCKED: this MCP tool call requires human approval ' +
+                    '(require_approval) and the tool has no onApproval resolver; an approval that ' +
+                    'cannot be granted in an unattended run is a block.',
+            };
+        }
+        return { approve: true };
+    };
+    delete pd.requireApproval;
+    delete pd.onApproval;
+    const wrapped = { ...tool, providerData: pd };
+    Object.defineProperty(wrapped, WRAPPED, { value: true, enumerable: false });
+    return wrapped;
+}
+/** Shared shell/apply_patch wrapping: force every action through the
+ *  approval path, gate it there, then replay the tool's original policy.
+ *
+ *  Fall-through, stated because it is easy to miss (TD-406): this relies on
+ *  `needsApproval`/`onApproval` being the SDK's veto point for these two
+ *  hosted tools. A future `@openai/agents` that executes a shell or
+ *  apply_patch action without consulting `onApproval` would bypass the gate
+ *  with no error here — which is why `package.json` pins the exact version
+ *  this was verified against, and a bump must re-run the openai adapter
+ *  tests (`__tests__/openai.test.ts`) before landing. */
+function wrapApprovalGatedTool(tool, opts, extract) {
+    const marked = tool;
+    if (marked[WRAPPED] === true)
+        return tool;
+    const originalNeedsApproval = tool.needsApproval;
+    const originalOnApproval = tool.onApproval;
+    const onApproval = async (runContext, item) => {
+        const g = resolveGate(opts.gate, 'wrapTools()');
+        const details = extract(item?.rawItem);
+        if (details === null) {
+            return {
+                approve: false,
+                reason: `[Intutic Governance] BLOCKED: could not extract the ${tool.type} action from the ` +
+                    'approval item — failing closed rather than approving an unevaluated call.',
+            };
+        }
+        try {
+            for (const toolInput of details.toolInputs) {
+                await g.guard(tool.name, toolInput);
+            }
+        }
+        catch (err) {
+            return errorToDecision(err);
+        }
+        // Gate allows. Replay the tool's ORIGINAL approval policy so wrapping is
+        // behaviour-preserving beyond the gate itself.
+        const originallyNeeded = typeof originalNeedsApproval === 'function'
+            ? await originalNeedsApproval(runContext, details.action, details.callId)
+            : Boolean(originalNeedsApproval);
+        if (!originallyNeeded)
+            return { approve: true };
+        if (originalOnApproval)
+            return originalOnApproval(runContext, item);
+        // Original policy: interruption for a human. Leave the decision unmade —
+        // the runner's `=== true`/`=== false` checks fall through to "pending"
+        // and the interruption surfaces exactly as before wrapping. See
+        // OpenAiApprovalDecision's doc for the verification of this mechanism.
+        return {};
+    };
+    const wrapped = { ...tool, needsApproval: async () => true, onApproval };
+    Object.defineProperty(wrapped, WRAPPED, { value: true, enumerable: false });
+    return wrapped;
+}
+function shellDetails(rawItem) {
+    const raw = rawItem;
+    if (!raw || raw.type !== 'shell_call')
+        return null;
+    const commands = Array.isArray(raw.action?.commands) ? raw.action.commands : null;
+    if (commands === null)
+        return null;
+    return {
+        // One guard() per command: a snapshot/SOP rule written against `command`
+        // must see each command on its own, not a joined blob.
+        toolInputs: commands.map((command) => ({ command: String(command) })),
+        action: raw.action,
+        ...(typeof raw.callId === 'string' ? { callId: raw.callId } : {}),
+    };
+}
+function applyPatchDetails(rawItem) {
+    const raw = rawItem;
+    if (!raw || raw.type !== 'apply_patch_call' || !raw.operation)
+        return null;
+    const op = raw.operation;
+    if (typeof op.path !== 'string')
+        return null;
+    const toolInput = {
+        path: op.path,
+        operation: typeof op.type === 'string' ? op.type : 'unknown',
+        // `content` so gate.ts's authoring-time infra check sees the diff body.
+        ...(typeof op.diff === 'string' ? { content: op.diff } : {}),
+        ...(typeof op.moveTo === 'string' ? { move_to: op.moveTo } : {}),
+    };
+    return {
+        toolInputs: [toolInput],
+        action: op,
+        ...(typeof raw.callId === 'string' ? { callId: raw.callId } : {}),
+    };
+}
+/**
+ * Gate-driven `needsApproval` predicate for `computerTool` — the ONLY
+ * pre-execution hook that tool exposes (no guardrails, no `onApproval`):
+ *
+ * ```ts
+ * computerTool({ computer, needsApproval: intuticComputerNeedsApproval() })
+ * ```
+ *
+ * A gate-refused (or gate-crashed — fail closed) action resolves `true`,
+ * which the runner turns into a pending interruption in
+ * `result.interruptions`; your interruption handler must `state.reject(...)`
+ * it. This is honestly weaker than the guardrail path: the SDK offers no way
+ * for this adapter to auto-reject a computer action with a message, and a
+ * handler that `state.approve()`s the interruption overrides the gate. An
+ * allowed action defers to `fallback` (the predicate the tool would
+ * otherwise have used; defaults to no approval).
+ */
+export function intuticComputerNeedsApproval(opts = {}) {
+    const toolName = opts.toolName ?? 'computer_use_preview';
+    return async (runContext, action, callId) => {
+        const g = resolveGate(opts.gate, 'intuticComputerNeedsApproval()');
+        const toolInput = action !== null && typeof action === 'object' && !Array.isArray(action)
+            ? action
+            : { value: action };
+        try {
+            await g.guard(toolName, toolInput);
+        }
+        catch {
+            // Refusal OR crash: force the approval interruption (fail closed).
+            // The refusal itself was already emitted as tool_blocked telemetry
+            // inside guard().
+            return true;
+        }
+        if (opts.fallback) {
+            return opts.fallback(runContext, action, callId);
+        }
+        return false;
+    };
+}
+function wrapComputerTool(tool, opts) {
+    const marked = tool;
+    if (marked[WRAPPED] === true)
+        return tool;
+    const wrapped = {
+        ...tool,
+        needsApproval: intuticComputerNeedsApproval({
+            ...opts,
+            toolName: tool.name,
+            fallback: typeof tool.needsApproval === 'function' ? tool.needsApproval : undefined,
+        }),
+    };
+    Object.defineProperty(wrapped, WRAPPED, { value: true, enumerable: false });
+    return wrapped;
+}
+// -------------------------------------------------------------- public API
+function wrapOneTool(tool, opts) {
+    const t = tool;
+    switch (t.type) {
+        case 'function':
+            return wrapFunctionTool(tool, opts);
+        case 'hosted_tool': {
+            const hosted = tool;
+            // Non-MCP hosted tools (webSearch, fileSearch, codeInterpreter, image
+            // generation, ...) execute server-side at OpenAI with no client-side
+            // hook — pass through UNCHANGED, documented in the module doc.
+            return isHostedMcp(hosted) ? wrapHostedMcpTool(hosted, opts) : tool;
+        }
+        case 'shell': {
+            // Hosted-environment shell (no local `shell` impl) is server-side —
+            // its factory types needsApproval/onApproval as `never`. Pass through.
+            if (t.shell === undefined)
+                return tool;
+            return wrapApprovalGatedTool(tool, opts, shellDetails);
+        }
+        case 'apply_patch':
+            return wrapApprovalGatedTool(tool, opts, applyPatchDetails);
+        case 'computer':
+            return wrapComputerTool(tool, opts);
+        default:
+            return tool;
+    }
+}
+/**
+ * Wrap a list of OpenAI Agents SDK tools so `Gate.guard()` runs before each
+ * one executes — see the module doc for exactly what each tool `type` gets
+ * (and what hosted tools cannot get). Returns NEW tool objects (shallow
+ * copies); the ones passed in are not mutated. Wrapping twice is a no-op.
+ *
+ * NOTE: this covers only the tools you hand it. Tools materialized from
+ * `agent.mcpServers` do not exist yet at wrapping time — use
+ * {@link wrapAgent} for an agent with MCP servers.
+ */
+export function wrapTools(tools, opts = {}) {
+    return tools.map((t) => wrapOneTool(t, opts));
+}
+/**
+ * Gate every tool an agent can reach, MCP-sourced tools included.
+ *
+ * ```ts
+ * import { Agent, run } from '@openai/agents'
+ * import { installOpenAiGate, wrapAgent } from '@intutic/gate/openai'
+ *
+ * installOpenAiGate({ workspaceId: process.env.INTUTIC_WORKSPACE_ID })
+ *
+ * const agent = wrapAgent(new Agent({
+ *   name: 'ops',
+ *   tools: [shell],
+ *   mcpServers: [filesystemServer],
+ * }))
+ * const result = await run(agent, prompt)
+ * ```
+ *
+ * Two things happen, both idempotent:
+ *
+ *   1. `agent.tools` is replaced with {@link wrapTools}' wrapped copies.
+ *   2. The agent INSTANCE's `getAllTools` — the materializer the runner
+ *      actually consumes each turn, and the ONLY place `mcpServers`-derived
+ *      tools ever appear (see module doc) — is patched to wrap everything it
+ *      returns.
+ *
+ * MUTATES (and returns) the agent passed in.
+ *
+ * Scope, stated plainly: this wraps ONE agent. Agents reached via handoffs
+ * are separate objects — wrap each of them too.
+ */
+export function wrapAgent(agent, opts = {}) {
+    const marked = agent;
+    if (marked[AGENT_WRAPPED] === true)
+        return agent;
+    agent.tools = wrapTools(agent.tools, opts);
+    const originalGetAllTools = agent.getAllTools.bind(agent);
+    agent.getAllTools = async (...args) => wrapTools(await originalGetAllTools(...args), opts);
+    Object.defineProperty(marked, AGENT_WRAPPED, { value: true, enumerable: false });
+    return agent;
+}
+// ------------------------------------------------------------ installation
+/**
+ * Close the tracing DLP leak: set the SDK's own kill-switch env
+ * (`OPENAI_AGENTS_DISABLE_TRACING=1`) so the default exporter never POSTs
+ * trace spans — which carry tool inputs/outputs — to its HARDCODED
+ * `https://api.openai.com/v1/traces/ingest` endpoint (which ignores
+ * `OPENAI_BASE_URL`, i.e. bypasses the Intutic proxy). The SDK reads the env
+ * lazily per run, so calling this any time before `run(...)` is effective.
+ *
+ * To keep traces instead, re-point the exporter at an approved collector in
+ * your own code — `setTraceProcessors([new BatchTraceProcessor(new
+ * OpenAITracingExporter({ endpoint }))])` — and pass
+ * `{ tracingExport: 'keep' }` to {@link installOpenAiGate}.
+ */
+export function suppressAgentsTracingExport() {
+    process.env.OPENAI_AGENTS_DISABLE_TRACING = '1';
+}
+/**
+ * One-call setup: build a {@link Gate} (with a `GateClient` from the
+ * environment when credentials allow — degrading to a client-less gate, Tier
+ * B/A3 inactive, rather than throwing out of setup, same posture as dsh.ts's
+ * `apply()`), `install()` it process-wide so every guardrail/wrapper in this
+ * module picks it up, and close the tracing leak (unless `tracingExport:
+ * 'keep'`). Returns the gate.
+ *
+ * Session id: one per PROCESS (`sessionId` option, else
+ * `INTUTIC_SESSION_ID`, else a random UUID) — the SDK has no single "current
+ * session" readable at install time; see dsh.ts's `resolveSessionId` for the
+ * full rationale this mirrors.
+ */
+/**
+ * Where to point `@openai/agents`' tracing exporter so traces stay governed
+ * (TD-405): the control plane's ingest route, authenticated with the same
+ * API key the gate uses. Pass the result to the SDK's own exporter —
+ *
+ * ```ts
+ * import { setTraceProcessors, BatchTraceProcessor, OpenAITracingExporter } from '@openai/agents'
+ * setTraceProcessors([new BatchTraceProcessor(new OpenAITracingExporter(intuticTracingExporterOptions()))])
+ * ```
+ *
+ * — and pass `{ tracingExport: 'intutic' }` to {@link installOpenAiGate}. No
+ * `@openai/agents` import here, so this module stays loadable without the SDK.
+ * Generation spans become traces in the ledger; tool spans are counted, not
+ * stored (the route's own doc says why).
+ */
+export function intuticTracingExporterOptions(env = process.env) {
+    // Trailing slashes stripped with a loop, not `/\/+$/`: CodeQL flags that
+    // regex as polynomial on a long run of slashes, and the input is operator
+    // config read once, so a loop is both safe and obviously linear.
+    let base = env.INTUTIC_CONTROL_PLANE_URL ?? '';
+    while (base.endsWith('/'))
+        base = base.slice(0, -1);
+    const apiKey = env.INTUTIC_API_KEY ?? '';
+    if (!base || !apiKey) {
+        throw new Error('intuticTracingExporterOptions: INTUTIC_CONTROL_PLANE_URL and INTUTIC_API_KEY must be set to route traces to Intutic');
+    }
+    return { endpoint: `${base}/api/v1/integrations/openai-agents/traces/ingest`, apiKey };
+}
+export function installOpenAiGate(config = {}) {
+    if ((config.tracingExport ?? 'disable') === 'disable') {
+        suppressAgentsTracingExport();
+    }
+    let client;
+    try {
+        client = GateClient.fromEnv({
+            harness: 'openai-agents',
+            sessionId: config.sessionId || process.env.INTUTIC_SESSION_ID || randomUUID(),
+        });
+    }
+    catch {
+        client = null;
+    }
+    const gate = new Gate(config, client);
+    install(gate);
+    return gate;
+}
+//# sourceMappingURL=openai.js.map