@openai/agents-core 0.3.6 → 0.3.8

package/dist/utils/toolGuardrails.d.ts

@@ -0,0 +1,24 @@
+import type { ToolInputGuardrailDefinition, ToolInputGuardrailResult, ToolOutputGuardrailDefinition, ToolOutputGuardrailResult } from '../toolGuardrail';
+import type { Agent } from '../agent';
+import type { RunContext } from '../runContext';
+import type * as protocol from '../types/protocol';
+export declare function runToolInputGuardrails<TContext, TAgent extends Agent<any, any>>({ guardrails, context, agent, toolCall, onResult, }: {
+    guardrails?: ToolInputGuardrailDefinition<TContext>[];
+    context: RunContext<TContext>;
+    agent: TAgent;
+    toolCall: protocol.FunctionCallItem;
+    onResult?: (result: ToolInputGuardrailResult) => void;
+}): Promise<{
+    type: 'allow';
+} | {
+    type: 'reject';
+    message: string;
+}>;
+export declare function runToolOutputGuardrails<TContext, TAgent extends Agent<any, any>>({ guardrails, context, agent, toolCall, toolOutput, onResult, }: {
+    guardrails?: ToolOutputGuardrailDefinition<TContext>[];
+    context: RunContext<TContext>;
+    agent: TAgent;
+    toolCall: protocol.FunctionCallItem;
+    toolOutput: unknown;
+    onResult?: (result: ToolOutputGuardrailResult) => void;
+}): Promise<unknown>;

package/dist/utils/toolGuardrails.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runToolInputGuardrails = runToolInputGuardrails;
+exports.runToolOutputGuardrails = runToolOutputGuardrails;
+const errors_1 = require("../errors.js");
+function normalizeBehavior(output) {
+    return output.behavior ?? { type: 'allow' };
+}
+async function runToolInputGuardrails({ guardrails, context, agent, toolCall, onResult, }) {
+    const list = guardrails ?? [];
+    for (const guardrail of list) {
+        const output = await guardrail.run({
+            context,
+            agent,
+            toolCall,
+        });
+        const behavior = normalizeBehavior(output);
+        const result = {
+            guardrail: { type: 'tool_input', name: guardrail.name },
+            output: { ...output, behavior },
+        };
+        onResult?.(result);
+        if (behavior.type === 'rejectContent') {
+            return { type: 'reject', message: behavior.message };
+        }
+        if (behavior.type === 'throwException') {
+            throw new errors_1.ToolInputGuardrailTripwireTriggered(`Tool input guardrail triggered: ${guardrail.name}`, result);
+        }
+    }
+    return { type: 'allow' };
+}
+async function runToolOutputGuardrails({ guardrails, context, agent, toolCall, toolOutput, onResult, }) {
+    const list = guardrails ?? [];
+    let finalOutput = toolOutput;
+    for (const guardrail of list) {
+        const output = await guardrail.run({
+            context,
+            agent,
+            toolCall,
+            output: toolOutput,
+        });
+        const behavior = normalizeBehavior(output);
+        const result = {
+            guardrail: { type: 'tool_output', name: guardrail.name },
+            output: { ...output, behavior },
+        };
+        onResult?.(result);
+        if (behavior.type === 'rejectContent') {
+            finalOutput = behavior.message;
+            break;
+        }
+        if (behavior.type === 'throwException') {
+            throw new errors_1.ToolOutputGuardrailTripwireTriggered(`Tool output guardrail triggered: ${guardrail.name}`, result);
+        }
+    }
+    return finalOutput;
+}
+//# sourceMappingURL=toolGuardrails.js.map

package/dist/utils/toolGuardrails.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolGuardrails.js","sourceRoot":"","sources":["../../src/utils/toolGuardrails.ts"],"names":[],"mappings":";;AAqBA,wDAwCC;AAED,0DA6CC;AAlGD,yCAGmB;AAEnB,SAAS,iBAAiB,CACxB,MAAmC;IAEnC,OAAO,MAAM,CAAC,QAAQ,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC9C,CAAC;AAEM,KAAK,UAAU,sBAAsB,CAG1C,EACA,UAAU,EACV,OAAO,EACP,KAAK,EACL,QAAQ,EACR,QAAQ,GAOT;IACC,MAAM,IAAI,GAAG,UAAU,IAAI,EAAE,CAAC;IAC9B,KAAK,MAAM,SAAS,IAAI,IAAI,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC;YACjC,OAAO;YACP,KAAK;YACL,QAAQ;SACT,CAAC,CAAC;QACH,MAAM,QAAQ,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;QAC3C,MAAM,MAAM,GAA6B;YACvC,SAAS,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE;YACvD,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE;SAChC,CAAC;QACF,QAAQ,EAAE,CAAC,MAAM,CAAC,CAAC;QACnB,IAAI,QAAQ,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;YACtC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC;QACvD,CAAC;QACD,IAAI,QAAQ,CAAC,IAAI,KAAK,gBAAgB,EAAE,CAAC;YACvC,MAAM,IAAI,4CAAmC,CAC3C,mCAAmC,SAAS,CAAC,IAAI,EAAE,EACnD,MAAM,CACP,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC3B,CAAC;AAEM,KAAK,UAAU,uBAAuB,CAG3C,EACA,UAAU,EACV,OAAO,EACP,KAAK,EACL,QAAQ,EACR,UAAU,EACV,QAAQ,GAQT;IACC,MAAM,IAAI,GAAG,UAAU,IAAI,EAAE,CAAC;IAC9B,IAAI,WAAW,GAAG,UAAU,CAAC;IAC7B,KAAK,MAAM,SAAS,IAAI,IAAI,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC;YACjC,OAAO;YACP,KAAK;YACL,QAAQ;YACR,MAAM,EAAE,UAAU;SACnB,CAAC,CAAC;QACH,MAAM,QAAQ,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;QAC3C,MAAM,MAAM,GAA8B;YACxC,SAAS,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE;YACxD,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE;SAChC,CAAC;QACF,QAAQ,EAAE,CAAC,MAAM,CAAC,CAAC;QACnB,IAAI,QAAQ,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;YACtC,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC;YAC/B,MAAM;QACR,CAAC;QACD,IAAI,QAAQ,CAAC,IAAI,KAAK,gBAAgB,EAAE,CAAC;YACvC,MAAM,IAAI,6CAAoC,CAC5C,oCAAoC,SAAS,CAAC,IAAI,EAAE,EACpD,MAAM,CACP,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/utils/toolGuardrails.mjs

@@ -0,0 +1,54 @@
+import { ToolInputGuardrailTripwireTriggered, ToolOutputGuardrailTripwireTriggered, } from "../errors.mjs";
+function normalizeBehavior(output) {
+    return output.behavior ?? { type: 'allow' };
+}
+export async function runToolInputGuardrails({ guardrails, context, agent, toolCall, onResult, }) {
+    const list = guardrails ?? [];
+    for (const guardrail of list) {
+        const output = await guardrail.run({
+            context,
+            agent,
+            toolCall,
+        });
+        const behavior = normalizeBehavior(output);
+        const result = {
+            guardrail: { type: 'tool_input', name: guardrail.name },
+            output: { ...output, behavior },
+        };
+        onResult?.(result);
+        if (behavior.type === 'rejectContent') {
+            return { type: 'reject', message: behavior.message };
+        }
+        if (behavior.type === 'throwException') {
+            throw new ToolInputGuardrailTripwireTriggered(`Tool input guardrail triggered: ${guardrail.name}`, result);
+        }
+    }
+    return { type: 'allow' };
+}
+export async function runToolOutputGuardrails({ guardrails, context, agent, toolCall, toolOutput, onResult, }) {
+    const list = guardrails ?? [];
+    let finalOutput = toolOutput;
+    for (const guardrail of list) {
+        const output = await guardrail.run({
+            context,
+            agent,
+            toolCall,
+            output: toolOutput,
+        });
+        const behavior = normalizeBehavior(output);
+        const result = {
+            guardrail: { type: 'tool_output', name: guardrail.name },
+            output: { ...output, behavior },
+        };
+        onResult?.(result);
+        if (behavior.type === 'rejectContent') {
+            finalOutput = behavior.message;
+            break;
+        }
+        if (behavior.type === 'throwException') {
+            throw new ToolOutputGuardrailTripwireTriggered(`Tool output guardrail triggered: ${guardrail.name}`, result);
+        }
+    }
+    return finalOutput;
+}
+//# sourceMappingURL=toolGuardrails.mjs.map

package/dist/utils/toolGuardrails.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolGuardrails.mjs","sourceRoot":"","sources":["../../src/utils/toolGuardrails.ts"],"names":[],"mappings":"OAUO,EACL,mCAAmC,EACnC,oCAAoC,GACrC;AAED,SAAS,iBAAiB,CACxB,MAAmC;IAEnC,OAAO,MAAM,CAAC,QAAQ,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC9C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAG1C,EACA,UAAU,EACV,OAAO,EACP,KAAK,EACL,QAAQ,EACR,QAAQ,GAOT;IACC,MAAM,IAAI,GAAG,UAAU,IAAI,EAAE,CAAC;IAC9B,KAAK,MAAM,SAAS,IAAI,IAAI,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC;YACjC,OAAO;YACP,KAAK;YACL,QAAQ;SACT,CAAC,CAAC;QACH,MAAM,QAAQ,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;QAC3C,MAAM,MAAM,GAA6B;YACvC,SAAS,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE;YACvD,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE;SAChC,CAAC;QACF,QAAQ,EAAE,CAAC,MAAM,CAAC,CAAC;QACnB,IAAI,QAAQ,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;YACtC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC;QACvD,CAAC;QACD,IAAI,QAAQ,CAAC,IAAI,KAAK,gBAAgB,EAAE,CAAC;YACvC,MAAM,IAAI,mCAAmC,CAC3C,mCAAmC,SAAS,CAAC,IAAI,EAAE,EACnD,MAAM,CACP,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC3B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAG3C,EACA,UAAU,EACV,OAAO,EACP,KAAK,EACL,QAAQ,EACR,UAAU,EACV,QAAQ,GAQT;IACC,MAAM,IAAI,GAAG,UAAU,IAAI,EAAE,CAAC;IAC9B,IAAI,WAAW,GAAG,UAAU,CAAC;IAC7B,KAAK,MAAM,SAAS,IAAI,IAAI,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC;YACjC,OAAO;YACP,KAAK;YACL,QAAQ;YACR,MAAM,EAAE,UAAU;SACnB,CAAC,CAAC;QACH,MAAM,QAAQ,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;QAC3C,MAAM,MAAM,GAA8B;YACxC,SAAS,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE;YACxD,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE;SAChC,CAAC;QACF,QAAQ,EAAE,CAAC,MAAM,CAAC,CAAC;QACnB,IAAI,QAAQ,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;YACtC,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC;YAC/B,MAAM;QACR,CAAC;QACD,IAAI,QAAQ,CAAC,IAAI,KAAK,gBAAgB,EAAE,CAAC;YACvC,MAAM,IAAI,oCAAoC,CAC5C,oCAAoC,SAAS,CAAC,IAAI,EAAE,EACpD,MAAM,CACP,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@openai/agents-core",
   "repository": "https://github.com/openai/openai-agents-js",
   "homepage": "https://openai.github.io/openai-agents-js/",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows.",
   "author": "OpenAI <support@openai.com>",
   "main": "dist/index.js",
@@ -62,7 +62,7 @@
   ],
   "license": "MIT",
   "optionalDependencies": {
-    "@modelcontextprotocol/sdk": "^1.24.0"
+    "@modelcontextprotocol/sdk": "^1.25.2"
   },
   "dependencies": {
     "debug": "^4.4.0",
@@ -105,6 +105,7 @@
   "scripts": {
     "prebuild": "tsx ../../scripts/embedMeta.ts",
     "build": "tsc",
-    "build-check": "tsc --noEmit -p ./tsconfig.test.json"
+    "build-check": "tsc --noEmit -p ./tsconfig.test.json",
+    "dist:check": "tsc --noEmit -p ./tsconfig.dist-check.json"
   }
 }

package/dist/runImplementation.d.ts

@@ -1,161 +0,0 @@
-import { Agent } from './agent';
-import { Handoff } from './handoff';
-import { RunItem, RunToolApprovalItem } from './items';
-import { Logger } from './logger';
-import { ModelResponse } from './model';
-import { ComputerTool, FunctionTool, HostedMCPTool, ShellTool, ApplyPatchTool } from './tool';
-import { AgentInputItem, UnknownContext } from './types';
-import { Runner } from './run';
-import { RunContext } from './runContext';
-import { StreamedRunResult } from './result';
-import { z } from 'zod';
-import * as protocol from './types/protocol';
-import { type Session, type SessionInputCallback } from './memory/session';
-type ToolRunHandoff = {
-    toolCall: protocol.FunctionCallItem;
-    handoff: Handoff<any, any>;
-};
-type ToolRunFunction<TContext = UnknownContext> = {
-    toolCall: protocol.FunctionCallItem;
-    tool: FunctionTool<TContext>;
-};
-type ToolRunComputer = {
-    toolCall: protocol.ComputerUseCallItem;
-    computer: ComputerTool<any, any>;
-};
-type ToolRunShell = {
-    toolCall: protocol.ShellCallItem;
-    shell: ShellTool;
-};
-type ToolRunApplyPatch = {
-    toolCall: protocol.ApplyPatchCallItem;
-    applyPatch: ApplyPatchTool;
-};
-type ToolRunMCPApprovalRequest = {
-    requestItem: RunToolApprovalItem;
-    mcpTool: HostedMCPTool;
-};
-export type ProcessedResponse<TContext = UnknownContext> = {
-    newItems: RunItem[];
-    handoffs: ToolRunHandoff[];
-    functions: ToolRunFunction<TContext>[];
-    computerActions: ToolRunComputer[];
-    shellActions: ToolRunShell[];
-    applyPatchActions: ToolRunApplyPatch[];
-    mcpApprovalRequests: ToolRunMCPApprovalRequest[];
-    toolsUsed: string[];
-    hasToolsOrApprovalsToRun(): boolean;
-};
-export declare const nextStepSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
-    type: z.ZodLiteral<"next_step_handoff">;
-    newAgent: z.ZodAny;
-}, "strip", z.ZodTypeAny, {
-    type: "next_step_handoff";
-    newAgent?: any;
-}, {
-    type: "next_step_handoff";
-    newAgent?: any;
-}>, z.ZodObject<{
-    type: z.ZodLiteral<"next_step_final_output">;
-    output: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    type: "next_step_final_output";
-    output: string;
-}, {
-    type: "next_step_final_output";
-    output: string;
-}>, z.ZodObject<{
-    type: z.ZodLiteral<"next_step_run_again">;
-}, "strip", z.ZodTypeAny, {
-    type: "next_step_run_again";
-}, {
-    type: "next_step_run_again";
-}>, z.ZodObject<{
-    type: z.ZodLiteral<"next_step_interruption">;
-    data: z.ZodRecord<z.ZodString, z.ZodAny>;
-}, "strip", z.ZodTypeAny, {
-    type: "next_step_interruption";
-    data: Record<string, any>;
-}, {
-    type: "next_step_interruption";
-    data: Record<string, any>;
-}>]>;
-export type NextStep = z.infer<typeof nextStepSchema>;
-/**
- * Internal convenience wrapper that groups the outcome of a single agent turn. It lets the caller
- * update the RunState in one shot and decide which step to execute next.
- */
-declare class SingleStepResult {
-    /**
-     * The input items (i.e., the items before run() was called). May be mutated by handoff input filters.
-     */
-    originalInput: string | AgentInputItem[];
-    /**
-     * The model response for the current step
-     */
-    modelResponse: ModelResponse;
-    /**
-     * The items before the current step was executed
-     */
-    preStepItems: RunItem[];
-    /**
-     * The items after the current step was executed
-     */
-    newStepItems: RunItem[];
-    /**
-     * The next step to execute
-     */
-    nextStep: NextStep;
-    constructor(
-    /**
-     * The input items (i.e., the items before run() was called). May be mutated by handoff input filters.
-     */
-    originalInput: string | AgentInputItem[], 
-    /**
-     * The model response for the current step
-     */
-    modelResponse: ModelResponse, 
-    /**
-     * The items before the current step was executed
-     */
-    preStepItems: RunItem[], 
-    /**
-     * The items after the current step was executed
-     */
-    newStepItems: RunItem[], 
-    /**
-     * The next step to execute
-     */
-    nextStep: NextStep);
-    /**
-     * The items generated during the agent run (i.e. everything generated after originalInput)
-     */
-    get generatedItems(): RunItem[];
-}
-export declare function executeShellActions(agent: Agent<any, any>, actions: ToolRunShell[], runner: Runner, runContext: RunContext, customLogger?: Logger | undefined): Promise<RunItem[]>;
-export declare function executeApplyPatchOperations(agent: Agent<any, any>, actions: ToolRunApplyPatch[], runner: Runner, runContext: RunContext, customLogger?: Logger | undefined): Promise<RunItem[]>;
-export declare function streamStepItemsToRunResult(result: StreamedRunResult<any, any>, items: RunItem[]): void;
-export declare function addStepToRunResult(result: StreamedRunResult<any, any>, step: SingleStepResult, options?: {
-    skipItems?: Set<RunItem>;
-}): void;
-export declare class AgentToolUseTracker {
-    #private;
-    addToolUse(agent: Agent<any, any>, toolNames: string[]): void;
-    hasUsedTools(agent: Agent<any, any>): boolean;
-    toJSON(): Record<string, string[]>;
-}
-export declare function prepareInputItemsWithSession(input: string | AgentInputItem[], session?: Session, sessionInputCallback?: SessionInputCallback, options?: {
-    /**
-     * When true (default), the returned `preparedInput` includes both the persisted session history
-     * and the new turn items. Set to false when upstream code already provides history to the model
-     * (e.g. server-managed conversations) to avoid sending duplicated messages each turn.
-     */
-    includeHistoryInPreparedInput?: boolean;
-    /**
-     * When true, ensures new turn inputs are still provided to the model even if the session input
-     * callback drops them from persistence (used for server-managed conversations that redact
-     * writes).
-     */
-    preserveDroppedNewItems?: boolean;
-}): Promise<PreparedInputWithSessionResult>;
-export {};