@intutic/gate 1.10.1

package/dist/mastra.js

@@ -0,0 +1,161 @@
+/**
+ * Mastra adapter: `intuticHooks()`.
+ *
+ * `@intutic/gate/mastra` — 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()`,
+ * throwing/vetoing before the real tool body ever runs.
+ *
+ * Mastra (`@mastra/core`) exposes a documented pre-execution veto point: an
+ * `Agent`'s `hooks.beforeToolCall`. It runs for every tool in the agent's
+ * assembled tool dictionary — natively defined tools AND MCP-sourced tools
+ * registered through `@mastra/mcp`, since both are merged into the same
+ * `CoreTool` record before hook-wrapping happens (`wrapToolsWithHooks`
+ * operates generically over `Object.entries(tools)`, with no source-specific
+ * branch). Returning `{ proceed: false, output }` from `beforeToolCall` skips
+ * the tool's real `execute` entirely and hands `output` back to the model IN
+ * PLACE OF the tool's result.
+ *
+ * ## Confirmed against a real install
+ *
+ * `@mastra/core@1.59.0` was installed in a scratch directory and its shipped
+ * `.d.ts`/compiled source read directly (not inferred from docs alone):
+ *
+ * `dist/tools/types.d.ts`:
+ * ```ts
+ * export interface ToolHookContext<TInput, TContext, TMetadata> {
+ *   toolName: string
+ *   input: TInput
+ *   context: TContext
+ *   metadata?: TMetadata
+ * }
+ * export interface ToolBeforeHookResult<TOutput> {
+ *   proceed: false
+ *   output: TOutput
+ * }
+ * export interface ToolHooks<TInput, TOutput, TContext, TMetadata> {
+ *   beforeToolCall?: (context: ToolHookContext<TInput, TContext, TMetadata>) =>
+ *     void | ToolBeforeHookResult<TOutput> | Promise<void | ToolBeforeHookResult<TOutput>>
+ *   afterToolCall?: (context: ToolAfterHookContext<...>) => void | Promise<void>
+ * }
+ * ```
+ * `void`/`undefined` means "proceed" (allow); only an explicit
+ * `{ proceed: false, output }` vetoes — this adapter's `beforeToolCall`
+ * therefore returns `undefined` on allow, matching the framework's own
+ * "no opinion" contract rather than a synthetic allow value.
+ *
+ * `dist/agent-CKAVuxKN.js`'s `wrapToolWithHooks` (the actual wrapping the
+ * `.d.ts` above only declares the shape of) confirms the consumption side:
+ * ```js
+ * const beforeResult = await hooks.beforeToolCall?.(hookContext)
+ * if (beforeResult?.proceed === false) return beforeResult.output
+ * ```
+ * `output` is returned AS the tool's own `execute` return value at this
+ * layer, with no schema check performed by the hook wrapper itself — but a
+ * tool with a strict Zod `outputSchema` may still validate/reject that value
+ * further downstream, and `beforeToolCall` is never told what that schema
+ * is (the hook context carries no `outputSchema`/tool-definition reference).
+ * This adapter therefore cannot GUARANTEE a schema-conformant denial payload
+ * for an arbitrary tool; see {@link IntuticHooksOptions.denialOutput} to
+ * shape it per your own tools when the generic default will not validate.
+ *
+ * ## TAMPER NOTE — per-call hooks OVERRIDE agent-level hooks, they do not merge
+ *
+ * Also confirmed against the same install — `dist/agent.d.ts`'s
+ * `getConfiguredToolHooks()` doc comment:
+ *
+ * > Run-level hooks override these via {@link resolveToolHooks}, so callers
+ * > that need to preserve the configured hooks must read and compose them
+ * > explicitly.
+ *
+ * Concretely: `new Agent({ hooks: intuticHooks() })` installs this gate at
+ * the agent level, but ANY caller of `.generate()`/`.stream()` who passes
+ * their own `hooks` option — even `{}`, or a `hooks` object with no
+ * `beforeToolCall` — REPLACES the agent-level hooks wholesale for that call.
+ * This gate silently does not run: no error, no warning, just an unguarded
+ * tool call. This is Mastra's own documented behaviour, not a defect this
+ * package can work around from outside the framework — there is no hook
+ * inheritance or merge to opt into. See `gateRegistry.ts`'s `mastra` row for
+ * the same note surfaced to the registry, and
+ * `apps/docs/integrations/mastra.md` for the operator-facing version.
+ *
+ * If your application passes call-level `hooks` anywhere, compose this
+ * gate's `beforeToolCall` into that call's hooks yourself:
+ *
+ * ```ts
+ * const intutic = intuticHooks()
+ * await agent.generate(prompt, {
+ *   hooks: {
+ *     beforeToolCall: async (ctx) => {
+ *       const denied = await intutic.beforeToolCall(ctx)
+ *       if (denied) return denied
+ *       return myOwnBeforeToolCall(ctx)
+ *     },
+ *   },
+ * })
+ * ```
+ */
+import { active as activeGate } from './gate.js';
+import { IntuticGateRefusal } from './errors.js';
+function defaultDenialOutput(ctx) {
+    return {
+        error: true,
+        message: ctx.refusal.message,
+        code: ctx.refusal.code,
+        incidentId: ctx.refusal.incidentId,
+    };
+}
+/**
+ * Builds a `{ beforeToolCall }` object shaped for direct use in `@mastra/core`'s
+ * `Agent` constructor's `hooks` option:
+ *
+ * ```ts
+ * import { Agent } from '@mastra/core/agent'
+ * import { Gate, install } from '@intutic/gate'
+ * import { intuticHooks } from '@intutic/gate/mastra'
+ *
+ * install(new Gate({ workspaceId: process.env.INTUTIC_WORKSPACE_ID }))
+ *
+ * const agent = new Agent({
+ *   id: 'my-agent',
+ *   name: 'My Agent',
+ *   model: 'openai/gpt-5-mini',
+ *   tools: { deleteTool },
+ *   hooks: intuticHooks(),
+ * })
+ * ```
+ *
+ * On refusal, returns `{ proceed: false, output }` — the real tool body
+ * never runs. On allow, returns `undefined`, Mastra's own "no opinion"
+ * value, so the real `execute` runs untouched.
+ *
+ * Requires a `Gate` — either passed via `{ gate }` here, or installed
+ * process-wide with `install(new Gate(...))`. A call with neither throws
+ * (via the underlying `beforeToolCall`), refusing to run tools unguarded
+ * rather than silently skipping enforcement — same posture as `wrapTool`.
+ *
+ * See the module doc's TAMPER NOTE: this only governs calls that do not
+ * override `hooks` at the `.generate()`/`.stream()` call site.
+ */
+export function intuticHooks(opts = {}) {
+    const denialOutput = opts.denialOutput ?? defaultDenialOutput;
+    const beforeToolCall = async (ctx) => {
+        const g = opts.gate ?? activeGate();
+        if (g === null) {
+            throw new Error('No gate configured: call install(new Gate(...)) from @intutic/gate, or pass ' +
+                '{ gate } to intuticHooks(). Refusing to run the tool unguarded.');
+        }
+        try {
+            await g.guard(ctx.toolName, (ctx.input ?? {}));
+            return undefined;
+        }
+        catch (exc) {
+            if (exc instanceof IntuticGateRefusal) {
+                return { proceed: false, output: denialOutput({ toolName: ctx.toolName, refusal: exc }) };
+            }
+            throw exc;
+        }
+    };
+    return { beforeToolCall };
+}
+//# sourceMappingURL=mastra.js.map

package/dist/mastra.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mastra.js","sourceRoot":"","sources":["../src/mastra.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;AAEH,OAAO,EAAE,MAAM,IAAI,UAAU,EAAa,MAAM,WAAW,CAAA;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AA6ChD,SAAS,mBAAmB,CAAC,GAAsD;IACjF,OAAO;QACL,KAAK,EAAE,IAAI;QACX,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,OAAO;QAC5B,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC,IAAI;QACtB,UAAU,EAAE,GAAG,CAAC,OAAO,CAAC,UAAU;KACnC,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,YAAY,CAAC,OAA4B,EAAE;IACzD,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,mBAAmB,CAAA;IAE7D,MAAM,cAAc,GAAyB,KAAK,EAAE,GAAG,EAAE,EAAE;QACzD,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,IAAI,UAAU,EAAE,CAAA;QACnC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACb,8EAA8E;gBAC5E,iEAAiE,CACpE,CAAA;QACH,CAAC;QACD,IAAI,CAAC;YACH,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAA4B,CAAC,CAAA;YACzE,OAAO,SAAS,CAAA;QAClB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,kBAAkB,EAAE,CAAC;gBACtC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,CAAA;YAC3F,CAAC;YACD,MAAM,GAAG,CAAA;QACX,CAAC;IACH,CAAC,CAAA;IAED,OAAO,EAAE,cAAc,EAAE,CAAA;AAC3B,CAAC"}

package/dist/openai.d.ts

@@ -0,0 +1,392 @@
+/**
+ * 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 { Gate } from './gate.js';
+import type { GateConfig, ToolInput } from './gate.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 declare const GUARDRAIL_NAME = "intutic";
+/** Slice of `protocol.FunctionCallItem` read by the guardrail: `arguments`
+ *  is the RAW, unparsed JSON string (the full item also carries `callId`,
+ *  `type: 'function_call'`, ...). */
+export interface OpenAiFunctionCallLike {
+    name: string;
+    arguments: string;
+}
+/** Slice of `ToolInputGuardrailData` the guardrail reads. The real data also
+ *  carries `context: RunContext` and `agent: Agent`, which pass through this
+ *  (wider-parameter) structural type untouched. */
+export interface OpenAiToolInputGuardrailData {
+    toolCall: OpenAiFunctionCallLike;
+}
+/** Structural copy of `ToolGuardrailFunctionOutput` — the subset of
+ *  `behavior` values this adapter emits (`throwException` is never used:
+ *  a refusal is a model-visible rejection, not a run-fatal tripwire). */
+export interface OpenAiToolGuardrailFunctionOutput {
+    behavior: {
+        type: 'allow';
+    } | {
+        type: 'rejectContent';
+        message: string;
+    };
+    outputInfo?: unknown;
+}
+/** Structural copy of `ToolInputGuardrailDefinition` — directly assignable
+ *  both to a built `FunctionTool.inputGuardrails` array and to the `tool()`
+ *  factory's `inputGuardrails` option. */
+export interface OpenAiToolInputGuardrail {
+    type: 'tool_input';
+    name: string;
+    run: (data: OpenAiToolInputGuardrailData) => Promise<OpenAiToolGuardrailFunctionOutput>;
+}
+/**
+ * Structural copy of the `{ approve, reason? }` decision `onApproval` /
+ * `on_approval` handlers resolve with — with one deliberate widening:
+ * `approve` is optional here.
+ *
+ * For SHELL and APPLY_PATCH tools the runner checks `decision.approve ===
+ * true` and `=== false` explicitly and treats anything else as "no decision
+ * made", leaving the approval pending so it surfaces as an interruption
+ * (VERIFIED against `@openai/agents-core@0.16.1`'s
+ * `dist/runner/toolExecution.js`, `resolveToolApproval()`). This adapter
+ * returns `{}` exactly once — when the gate allows a call whose ORIGINAL
+ * tool policy demanded a human and no original `onApproval` exists — so the
+ * caller's own interruption flow survives wrapping. That fall-through is
+ * real but UNDOCUMENTED SDK behaviour; see the TD entry this phase filed.
+ *
+ * Hosted MCP `on_approval` results are consumed with a TRUTHY check instead
+ * (`dist/runner/mcpApprovals.js`), so `{}` there would silently REJECT —
+ * the hosted-MCP wrapper never uses the fall-through.
+ */
+export interface OpenAiApprovalDecision {
+    approve?: boolean;
+    reason?: string;
+}
+/** Slice of `RunToolApprovalItem` the approval handlers read. */
+export interface OpenAiToolApprovalItemLike {
+    rawItem?: unknown;
+}
+/** Minimal structural slice of `Agent` needed by {@link wrapAgent}: the
+ *  static tool list plus the per-run materializer the runner actually
+ *  consumes (`dist/runner/modelPreparation.js`). */
+export interface OpenAiAgentLike {
+    tools: object[];
+    getAllTools(...args: never[]): Promise<object[]>;
+}
+export interface OpenAiWrapOptions {
+    /** Overrides the process-wide installed gate (`install(new Gate(...))`). */
+    gate?: Gate;
+}
+/**
+ * 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 declare function toolInputFromArguments(raw: string | null | undefined): ToolInput;
+/**
+ * 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 declare function intuticToolGuardrail(opts?: OpenAiWrapOptions): OpenAiToolInputGuardrail;
+/**
+ * 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 declare function intuticComputerNeedsApproval(opts?: OpenAiWrapOptions & {
+    /** Tool name reported to the gate. Defaults to `computer_use_preview`. */
+    toolName?: string;
+    /** Original predicate to defer to when the gate allows. */
+    fallback?: (...args: unknown[]) => Promise<boolean> | boolean;
+}): (runContext: unknown, action: unknown, callId?: unknown) => Promise<boolean>;
+/**
+ * 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 declare function wrapTools<T extends object>(tools: readonly T[], opts?: OpenAiWrapOptions): T[];
+/**
+ * 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 declare function wrapAgent<T extends OpenAiAgentLike>(agent: T, opts?: OpenAiWrapOptions): T;
+/**
+ * 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 declare function suppressAgentsTracingExport(): void;
+/** Config for {@link installOpenAiGate}. Extends the core {@link GateConfig}. */
+export interface OpenAiGateConfig extends GateConfig {
+    /** Overrides the generated-per-process session id. Mirrors
+     *  `INTUTIC_SESSION_ID` for callers that already have one to hand. */
+    sessionId?: string;
+    /**
+     * What to do about the tracing exporter's proxy bypass (see
+     * {@link suppressAgentsTracingExport}). `'disable'` (default) sets the
+     * SDK's kill-switch env; `'keep'` leaves tracing exactly as configured —
+     * choose it ONLY once the exporter endpoint is re-pointed somewhere
+     * approved, otherwise tool inputs/outputs leave via api.openai.com.
+     */
+    tracingExport?: 'disable' | 'keep' | 'intutic';
+}
+/**
+ * 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 declare function intuticTracingExporterOptions(env?: NodeJS.ProcessEnv): {
+    endpoint: string;
+    apiKey: string;
+};
+export declare function installOpenAiGate(config?: OpenAiGateConfig): Gate;
+//# sourceMappingURL=openai.d.ts.map

package/dist/openai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../src/openai.ts"],"names":[],"mappings":"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"}