@openai/agents-extensions 0.3.7 → 0.3.9

package/dist/experimental/codex/index.d.ts

@@ -0,0 +1,536 @@
+import type { FunctionCallItem, FunctionTool } from '@openai/agents';
+import { Codex, type CodexOptions, type SandboxMode, type ThreadEvent, type ThreadOptions, type TurnOptions, type Usage as CodexUsage } from '@openai/codex-sdk';
+import { z } from 'zod';
+declare const OutputSchemaDescriptorSchema: z.ZodEffects<z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    properties: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        schema: z.ZodUnion<[z.ZodUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"string">;
+            description: z.ZodOptional<z.ZodString>;
+            enum: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        }, "strict", z.ZodTypeAny, {
+            type: "string";
+            description?: string | undefined;
+            enum?: string[] | undefined;
+        }, {
+            type: "string";
+            description?: string | undefined;
+            enum?: string[] | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"number">;
+            description: z.ZodOptional<z.ZodString>;
+            enum: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+        }, "strict", z.ZodTypeAny, {
+            type: "number";
+            description?: string | undefined;
+            enum?: number[] | undefined;
+        }, {
+            type: "number";
+            description?: string | undefined;
+            enum?: number[] | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"integer">;
+            description: z.ZodOptional<z.ZodString>;
+            enum: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+        }, "strict", z.ZodTypeAny, {
+            type: "integer";
+            description?: string | undefined;
+            enum?: number[] | undefined;
+        }, {
+            type: "integer";
+            description?: string | undefined;
+            enum?: number[] | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"boolean">;
+            description: z.ZodOptional<z.ZodString>;
+            enum: z.ZodOptional<z.ZodArray<z.ZodBoolean, "many">>;
+        }, "strict", z.ZodTypeAny, {
+            type: "boolean";
+            description?: string | undefined;
+            enum?: boolean[] | undefined;
+        }, {
+            type: "boolean";
+            description?: string | undefined;
+            enum?: boolean[] | undefined;
+        }>]>, z.ZodObject<{
+            type: z.ZodLiteral<"array">;
+            description: z.ZodOptional<z.ZodString>;
+            items: z.ZodUnion<[z.ZodObject<{
+                type: z.ZodLiteral<"string">;
+                description: z.ZodOptional<z.ZodString>;
+                enum: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            }, "strict", z.ZodTypeAny, {
+                type: "string";
+                description?: string | undefined;
+                enum?: string[] | undefined;
+            }, {
+                type: "string";
+                description?: string | undefined;
+                enum?: string[] | undefined;
+            }>, z.ZodObject<{
+                type: z.ZodLiteral<"number">;
+                description: z.ZodOptional<z.ZodString>;
+                enum: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+            }, "strict", z.ZodTypeAny, {
+                type: "number";
+                description?: string | undefined;
+                enum?: number[] | undefined;
+            }, {
+                type: "number";
+                description?: string | undefined;
+                enum?: number[] | undefined;
+            }>, z.ZodObject<{
+                type: z.ZodLiteral<"integer">;
+                description: z.ZodOptional<z.ZodString>;
+                enum: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+            }, "strict", z.ZodTypeAny, {
+                type: "integer";
+                description?: string | undefined;
+                enum?: number[] | undefined;
+            }, {
+                type: "integer";
+                description?: string | undefined;
+                enum?: number[] | undefined;
+            }>, z.ZodObject<{
+                type: z.ZodLiteral<"boolean">;
+                description: z.ZodOptional<z.ZodString>;
+                enum: z.ZodOptional<z.ZodArray<z.ZodBoolean, "many">>;
+            }, "strict", z.ZodTypeAny, {
+                type: "boolean";
+                description?: string | undefined;
+                enum?: boolean[] | undefined;
+            }, {
+                type: "boolean";
+                description?: string | undefined;
+                enum?: boolean[] | undefined;
+            }>]>;
+        }, "strict", z.ZodTypeAny, {
+            type: "array";
+            items: {
+                type: "string";
+                description?: string | undefined;
+                enum?: string[] | undefined;
+            } | {
+                type: "number";
+                description?: string | undefined;
+                enum?: number[] | undefined;
+            } | {
+                type: "integer";
+                description?: string | undefined;
+                enum?: number[] | undefined;
+            } | {
+                type: "boolean";
+                description?: string | undefined;
+                enum?: boolean[] | undefined;
+            };
+            description?: string | undefined;
+        }, {
+            type: "array";
+            items: {
+                type: "string";
+                description?: string | undefined;
+                enum?: string[] | undefined;
+            } | {
+                type: "number";
+                description?: string | undefined;
+                enum?: number[] | undefined;
+            } | {
+                type: "integer";
+                description?: string | undefined;
+                enum?: number[] | undefined;
+            } | {
+                type: "boolean";
+                description?: string | undefined;
+                enum?: boolean[] | undefined;
+            };
+            description?: string | undefined;
+        }>]>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        schema: {
+            type: "string";
+            description?: string | undefined;
+            enum?: string[] | undefined;
+        } | {
+            type: "number";
+            description?: string | undefined;
+            enum?: number[] | undefined;
+        } | {
+            type: "integer";
+            description?: string | undefined;
+            enum?: number[] | undefined;
+        } | {
+            type: "boolean";
+            description?: string | undefined;
+            enum?: boolean[] | undefined;
+        } | {
+            type: "array";
+            items: {
+                type: "string";
+                description?: string | undefined;
+                enum?: string[] | undefined;
+            } | {
+                type: "number";
+                description?: string | undefined;
+                enum?: number[] | undefined;
+            } | {
+                type: "integer";
+                description?: string | undefined;
+                enum?: number[] | undefined;
+            } | {
+                type: "boolean";
+                description?: string | undefined;
+                enum?: boolean[] | undefined;
+            };
+            description?: string | undefined;
+        };
+        description?: string | undefined;
+    }, {
+        name: string;
+        schema: {
+            type: "string";
+            description?: string | undefined;
+            enum?: string[] | undefined;
+        } | {
+            type: "number";
+            description?: string | undefined;
+            enum?: number[] | undefined;
+        } | {
+            type: "integer";
+            description?: string | undefined;
+            enum?: number[] | undefined;
+        } | {
+            type: "boolean";
+            description?: string | undefined;
+            enum?: boolean[] | undefined;
+        } | {
+            type: "array";
+            items: {
+                type: "string";
+                description?: string | undefined;
+                enum?: string[] | undefined;
+            } | {
+                type: "number";
+                description?: string | undefined;
+                enum?: number[] | undefined;
+            } | {
+                type: "integer";
+                description?: string | undefined;
+                enum?: number[] | undefined;
+            } | {
+                type: "boolean";
+                description?: string | undefined;
+                enum?: boolean[] | undefined;
+            };
+            description?: string | undefined;
+        };
+        description?: string | undefined;
+    }>, "many">;
+    required: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    properties: {
+        name: string;
+        schema: {
+            type: "string";
+            description?: string | undefined;
+            enum?: string[] | undefined;
+        } | {
+            type: "number";
+            description?: string | undefined;
+            enum?: number[] | undefined;
+        } | {
+            type: "integer";
+            description?: string | undefined;
+            enum?: number[] | undefined;
+        } | {
+            type: "boolean";
+            description?: string | undefined;
+            enum?: boolean[] | undefined;
+        } | {
+            type: "array";
+            items: {
+                type: "string";
+                description?: string | undefined;
+                enum?: string[] | undefined;
+            } | {
+                type: "number";
+                description?: string | undefined;
+                enum?: number[] | undefined;
+            } | {
+                type: "integer";
+                description?: string | undefined;
+                enum?: number[] | undefined;
+            } | {
+                type: "boolean";
+                description?: string | undefined;
+                enum?: boolean[] | undefined;
+            };
+            description?: string | undefined;
+        };
+        description?: string | undefined;
+    }[];
+    required?: string[] | undefined;
+    description?: string | undefined;
+    title?: string | undefined;
+}, {
+    properties: {
+        name: string;
+        schema: {
+            type: "string";
+            description?: string | undefined;
+            enum?: string[] | undefined;
+        } | {
+            type: "number";
+            description?: string | undefined;
+            enum?: number[] | undefined;
+        } | {
+            type: "integer";
+            description?: string | undefined;
+            enum?: number[] | undefined;
+        } | {
+            type: "boolean";
+            description?: string | undefined;
+            enum?: boolean[] | undefined;
+        } | {
+            type: "array";
+            items: {
+                type: "string";
+                description?: string | undefined;
+                enum?: string[] | undefined;
+            } | {
+                type: "number";
+                description?: string | undefined;
+                enum?: number[] | undefined;
+            } | {
+                type: "integer";
+                description?: string | undefined;
+                enum?: number[] | undefined;
+            } | {
+                type: "boolean";
+                description?: string | undefined;
+                enum?: boolean[] | undefined;
+            };
+            description?: string | undefined;
+        };
+        description?: string | undefined;
+    }[];
+    required?: string[] | undefined;
+    description?: string | undefined;
+    title?: string | undefined;
+}>, {
+    properties: {
+        name: string;
+        schema: {
+            type: "string";
+            description?: string | undefined;
+            enum?: string[] | undefined;
+        } | {
+            type: "number";
+            description?: string | undefined;
+            enum?: number[] | undefined;
+        } | {
+            type: "integer";
+            description?: string | undefined;
+            enum?: number[] | undefined;
+        } | {
+            type: "boolean";
+            description?: string | undefined;
+            enum?: boolean[] | undefined;
+        } | {
+            type: "array";
+            items: {
+                type: "string";
+                description?: string | undefined;
+                enum?: string[] | undefined;
+            } | {
+                type: "number";
+                description?: string | undefined;
+                enum?: number[] | undefined;
+            } | {
+                type: "integer";
+                description?: string | undefined;
+                enum?: number[] | undefined;
+            } | {
+                type: "boolean";
+                description?: string | undefined;
+                enum?: boolean[] | undefined;
+            };
+            description?: string | undefined;
+        };
+        description?: string | undefined;
+    }[];
+    required?: string[] | undefined;
+    description?: string | undefined;
+    title?: string | undefined;
+}, {
+    properties: {
+        name: string;
+        schema: {
+            type: "string";
+            description?: string | undefined;
+            enum?: string[] | undefined;
+        } | {
+            type: "number";
+            description?: string | undefined;
+            enum?: number[] | undefined;
+        } | {
+            type: "integer";
+            description?: string | undefined;
+            enum?: number[] | undefined;
+        } | {
+            type: "boolean";
+            description?: string | undefined;
+            enum?: boolean[] | undefined;
+        } | {
+            type: "array";
+            items: {
+                type: "string";
+                description?: string | undefined;
+                enum?: string[] | undefined;
+            } | {
+                type: "number";
+                description?: string | undefined;
+                enum?: number[] | undefined;
+            } | {
+                type: "integer";
+                description?: string | undefined;
+                enum?: number[] | undefined;
+            } | {
+                type: "boolean";
+                description?: string | undefined;
+                enum?: boolean[] | undefined;
+            };
+            description?: string | undefined;
+        };
+        description?: string | undefined;
+    }[];
+    required?: string[] | undefined;
+    description?: string | undefined;
+    title?: string | undefined;
+}>;
+declare const codexParametersSchema: z.ZodObject<{
+    inputs: z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        text: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        text: string;
+        type: "text";
+    }, {
+        text: string;
+        type: "text";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"local_image">;
+        path: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        type: "local_image";
+        path: string;
+    }, {
+        type: "local_image";
+        path: string;
+    }>]>, "many">;
+}, "strict", z.ZodTypeAny, {
+    inputs: ({
+        text: string;
+        type: "text";
+    } | {
+        type: "local_image";
+        path: string;
+    })[];
+}, {
+    inputs: ({
+        text: string;
+        type: "text";
+    } | {
+        type: "local_image";
+        path: string;
+    })[];
+}>;
+type CodexToolParametersSchema = typeof codexParametersSchema;
+type OutputSchemaDescriptor = z.infer<typeof OutputSchemaDescriptorSchema>;
+export type CodexToolStreamEvent = {
+    event: ThreadEvent;
+    threadId: string | null;
+    toolCall?: FunctionCallItem;
+};
+export type CodexToolStreamHandler = (event: CodexToolStreamEvent) => void | Promise<void>;
+export type CodexToolOptions = {
+    /**
+     * Name of the tool as exposed to the agent model.
+     *
+     * @defaultValue `'codex'`
+     */
+    name?: string;
+    /**
+     * Description surfaced to the agent model.
+     */
+    description?: string;
+    /**
+     * Explicit Zod parameter schema. When omitted, the default schema is used.
+     * Custom schemas must be compatible with the default `inputs` shape.
+     */
+    parameters?: CodexToolParametersSchema;
+    /**
+     * Optional descriptor or JSON schema used for Codex structured output.
+     * This schema is applied to every Codex turn.
+     */
+    outputSchema?: OutputSchemaDescriptor | Record<string, unknown> | z.ZodTypeAny;
+    /**
+     * Reuse an existing Codex instance. When omitted a new Codex instance will be created.
+     */
+    codex?: Codex;
+    /**
+     * Options passed to the Codex constructor when {@link CodexToolOptions.codex} is undefined.
+     */
+    codexOptions?: CodexOptions;
+    /**
+     * Default options applied to every Codex thread.
+     */
+    defaultThreadOptions?: ThreadOptions;
+    /**
+     * Resume a specific Codex thread by id.
+     */
+    threadId?: string;
+    /**
+     * Sandbox permissions for the Codex task.
+     */
+    sandboxMode?: SandboxMode;
+    /**
+     * Absolute path used as the working directory for the Codex thread.
+     */
+    workingDirectory?: string;
+    /**
+     * Allow Codex to run outside a Git repository when true.
+     */
+    skipGitRepoCheck?: boolean;
+    /**
+     * Default options applied to every Codex turn.
+     */
+    defaultTurnOptions?: TurnOptions;
+    /**
+     * Reuse a single Codex thread across tool invocations.
+     */
+    persistSession?: boolean;
+    /**
+     * Optional hook to receive streamed Codex events during execution.
+     */
+    onStream?: CodexToolStreamHandler;
+};
+type CodexToolResult = {
+    threadId: string | null;
+    response: string;
+    usage: CodexUsage | null;
+};
+/**
+ * Wraps the Codex SDK in a function tool that can be consumed by the Agents SDK.
+ *
+ * The tool streams Codex events, creating child spans for reasoning items, command executions,
+ * and MCP tool invocations. Those spans are nested under the Codex tool span automatically when
+ * tracing is enabled.
+ */
+export declare function codexTool(options?: CodexToolOptions): FunctionTool<unknown, typeof codexParametersSchema, CodexToolResult>;
+export type CodexOutputSchemaDescriptor = OutputSchemaDescriptor;
+export type CodexOutputSchema = Record<string, unknown>;
+export {};