openai 7.25.0 → 7.27.0

package/src/lib/beta/agents/agent-turn-result-collector.ts

@@ -0,0 +1,122 @@
+import type {
+  AgentSession,
+  AgentSessionEvent,
+  AgentSessionAssistantMessage,
+} from '../../../resources/beta/agents/agents';
+import type { Turn } from '../../../resources/beta/agents/sessions/turns';
+import { AgentTurnResult } from './agent-turn-result';
+import { AgentTurnResultError } from './agent-turn-result-error';
+
+/** Accumulates completed items independently of transport and tool execution.
+ * @internal
+ */
+export class AgentTurnResultCollector {
+  #sessionID: string | undefined;
+  #turn: Turn | undefined;
+  #messages = new Map<string, { index: number; message: AgentSessionAssistantMessage }>();
+  #requiredActions: AgentSession['required_actions'] = [];
+  #sessionFailed = false;
+  #terminal = false;
+  #idle = false;
+
+  constructor(sessionID?: string) {
+    this.#sessionID = sessionID;
+  }
+
+  accept(event: AgentSessionEvent): void {
+    if (this.ready) {
+      return;
+    }
+    if ('session' in event) {
+      this.#sessionID ??= event.session.id;
+      this.#requiredActions = structuredClone(event.session.required_actions ?? []);
+      this.#sessionFailed ||= event.type === 'agent.session.failed';
+      this.#idle ||= event.type === 'agent.session.idle' && this.#terminal;
+    }
+    if (event.type === 'agent.session.turn.created' && event.turn.subagent_id === null && !this.#turn) {
+      this.#turn = structuredClone(event.turn);
+      this.#sessionID = event.turn.session_id;
+    }
+    let turnID = 'turn_id' in event ? event.turn_id : undefined;
+    if ('item' in event) {
+      turnID = event.item.turn_id;
+    }
+    if (!this.#turn || turnID !== this.#turn.id) {
+      return;
+    }
+    this.#acceptTurn(event);
+  }
+
+  #acceptTurn(event: AgentSessionEvent): void {
+    if ('turn' in event) {
+      this.#turn = structuredClone(event.turn);
+      this.#terminal ||=
+        event.type === 'agent.session.turn.completed' ||
+        event.type === 'agent.session.turn.failed' ||
+        event.type === 'agent.session.turn.cancelled';
+    }
+    this.#acceptOutput(event);
+  }
+
+  #acceptOutput(event: AgentSessionEvent): void {
+    if (
+      event.type !== 'agent.session.turn.item.done' ||
+      event.item.type !== 'message' ||
+      event.item.status !== 'completed' ||
+      event.item.phase === 'commentary' ||
+      this.#messages.has(event.item.id)
+    ) {
+      return;
+    }
+    this.#messages.set(event.item.id, { index: event.output_index, message: structuredClone(event.item) });
+  }
+
+  #finalMessages(): AgentSessionAssistantMessage[] {
+    return (
+      [...this.#messages.values()]
+        // oxlint-disable-next-line unicorn/no-array-sort -- Sort a fresh array; ES2020 declarations do not include toSorted.
+        .sort((a, b) => a.index - b.index)
+        .map(({ message }) => message)
+    );
+  }
+
+  error(reason: AgentTurnResultError['reason'], cause?: unknown): AgentTurnResultError {
+    return new AgentTurnResultError(
+      reason,
+      this.#sessionID,
+      this.#turn,
+      this.#finalMessages(),
+      this.#requiredActions,
+      cause,
+    );
+  }
+
+  checkAction(canHandle: (name: string) => boolean): void {
+    if (this.#sessionFailed || this.#turn?.status === 'failed') {
+      throw this.error('failed');
+    }
+    if (this.#turn?.status === 'cancelled') {
+      throw this.error('cancelled');
+    }
+    if (this.#requiredActions.some((action) => action.type !== 'function_call' || !canHandle(action.name))) {
+      throw this.error('requires_action');
+    }
+  }
+
+  get ready(): boolean {
+    return this.#terminal && this.#idle;
+  }
+
+  release(): void {
+    this.#messages.clear();
+    this.#requiredActions = [];
+  }
+
+  finish(): AgentTurnResult {
+    this.checkAction(() => this.ready);
+    if (!this.#terminal || this.#turn?.status !== 'completed' || !this.#idle) {
+      throw this.error('observation');
+    }
+    return new AgentTurnResult(this.#turn, this.#finalMessages());
+  }
+}

package/src/lib/beta/agents/agent-turn-result-error.ts

@@ -0,0 +1,33 @@
+import { OpenAIError } from '../../../core/error';
+import type { AgentSession, AgentSessionAssistantMessage } from '../../../resources/beta/agents/agents';
+import type { Turn } from '../../../resources/beta/agents/sessions/turns';
+
+/** Beta: final collection failed; partial state is evidence, not a successful result. */
+export class AgentTurnResultError extends OpenAIError {
+  override name = 'AgentTurnResultError';
+  readonly reason: 'failed' | 'cancelled' | 'requires_action' | 'observation';
+  readonly session_id: string | undefined;
+  readonly turn: Turn | undefined;
+  readonly messages: AgentSessionAssistantMessage[];
+  readonly required_actions: AgentSession['required_actions'];
+  readonly cause: unknown;
+  constructor(
+    reason: 'failed' | 'cancelled' | 'requires_action' | 'observation',
+    session_id: string | undefined,
+    turn: Turn | undefined,
+    messages: AgentSessionAssistantMessage[],
+    required_actions: AgentSession['required_actions'] = [],
+    cause?: unknown,
+  ) {
+    super(`Could not collect the agent turn result: ${reason}`);
+    this.reason = reason;
+    this.session_id = session_id;
+    this.turn = turn;
+    this.messages = messages;
+    this.required_actions = required_actions;
+    this.cause = cause;
+  }
+  get turn_id(): string | undefined {
+    return this.turn?.id;
+  }
+}

package/src/lib/beta/agents/agent-turn-result.ts

@@ -0,0 +1,22 @@
+import type { AgentSessionAssistantMessage } from '../../../resources/beta/agents/agents';
+import type { Turn } from '../../../resources/beta/agents/sessions/turns';
+import { outputText } from '../../agents/output-text';
+
+/** Beta: the completed final assistant messages from one hosted root turn. */
+export class AgentTurnResult {
+  readonly turn: Turn;
+  readonly messages: AgentSessionAssistantMessage[];
+  constructor(turn: Turn, messages: AgentSessionAssistantMessage[]) {
+    this.turn = turn;
+    this.messages = messages;
+  }
+  get session_id(): string {
+    return this.turn.session_id;
+  }
+  get turn_id(): string {
+    return this.turn.id;
+  }
+  get output_text(): string {
+    return this.messages.map(outputText).join('');
+  }
+}

package/src/lib/beta/agents/files.ts

@@ -0,0 +1,119 @@
+import type { OpenAI } from '../../../client';
+import { OpenAIError } from '../../../core/error';
+import { buildHeaders } from '../../../internal/headers';
+import type { RequestOptions } from '../../../internal/request-options';
+import type { Uploadable } from '../../../internal/uploads';
+import type { FileObject } from '../../../resources/files';
+import type {
+  EnvironmentFile,
+  FileCreateParams,
+  Files,
+} from '../../../resources/beta/agents/environments/files';
+
+/** Beta: file references ready for a hosted environment, plus caller-owned uploads. */
+export interface PreparedAgentFiles {
+  files: Extract<FileCreateParams, { type: 'file_id' }>[];
+  uploadedFiles: FileObject[];
+}
+
+/** Beta: uploaded file IDs remain available after partial preparation or staging failure. */
+export class AgentFileUploadError extends OpenAIError {
+  override readonly name = 'AgentFileUploadError';
+  declare readonly cause: unknown;
+  readonly uploadedFiles: FileObject[];
+  constructor(uploadedFiles: FileObject[], cause: unknown) {
+    super('Agent file preparation or staging failed; uploaded files remain caller-owned.');
+    this.uploadedFiles = uploadedFiles;
+    Object.defineProperty(this, 'cause', { value: cause, configurable: true });
+  }
+}
+
+/** @internal */
+export function validateAgentFilePath(path: string): void {
+  const parts = path.split('/');
+  const root = parts[2] ?? '';
+  if (
+    !path.startsWith('/workspace/') ||
+    path.includes('\\') ||
+    path.includes('\0') ||
+    parts.slice(1).some((part) => part === '' || part === '.' || part === '..') ||
+    root === '.codex' ||
+    root === '.managed-agents' ||
+    root.startsWith('.managed-agents-') ||
+    path === '/workspace/outputs'
+  ) {
+    throw new OpenAIError('Agent files require a non-reserved absolute file path inside /workspace');
+  }
+}
+
+function preflight(files: Record<string, Uploadable>, options: RequestOptions): [string, Uploadable][] {
+  const entries = Object.entries(files);
+  const headers = buildHeaders([options.headers]);
+  if (
+    entries.length > 1 &&
+    (headers.values.has('idempotency-key') ||
+      (!headers.nulls.has('idempotency-key') && options?.idempotencyKey !== undefined))
+  ) {
+    throw new OpenAIError('Do not reuse an Idempotency-Key across multiple file uploads');
+  }
+  const paths = new Set(entries.map(([path]) => path));
+  for (const [path] of entries) {
+    validateAgentFilePath(path);
+    for (let slash = path.lastIndexOf('/'); slash > 0; slash = path.lastIndexOf('/', slash - 1)) {
+      if (paths.has(path.slice(0, slash))) {
+        throw new OpenAIError('Agent file destinations conflict');
+      }
+    }
+  }
+  return entries;
+}
+
+/** @internal */
+export async function prepareAgentFiles(
+  client: OpenAI,
+  files: Record<string, Uploadable>,
+  options?: RequestOptions,
+): Promise<PreparedAgentFiles> {
+  const requestOptions = { ...options };
+  // Internal SDK read: capture effective headers once, including defaults and explicit omissions.
+  const headers = buildHeaders([client['_options'].defaultHeaders, requestOptions.headers]);
+  requestOptions.headers = headers;
+  const entries = preflight(files, requestOptions);
+  if (entries.length > 1) {
+    // Keep a later mutation of client defaults from adding one key to this entire batch.
+    headers.nulls.add('idempotency-key');
+  }
+  const prepared: PreparedAgentFiles = { files: [], uploadedFiles: [] };
+  try {
+    for (const [path, file] of entries) {
+      // oxlint-disable-next-line no-await-in-loop -- Stop on the first failure and expose precisely the uploads already created.
+      const uploaded = await client.files.create({ file, purpose: 'user_data' }, requestOptions);
+      prepared.uploadedFiles.push(uploaded);
+      prepared.files.push({ type: 'file_id', file_id: uploaded.id, path });
+    }
+    return prepared;
+  } catch (error) {
+    throw new AgentFileUploadError(prepared.uploadedFiles, error);
+  }
+}
+
+/** @internal */
+export async function uploadAgentFile(
+  client: OpenAI,
+  resource: Files,
+  environmentID: string,
+  params: { file: Uploadable; path: string },
+  options?: RequestOptions,
+): Promise<{ uploadedFile: FileObject; environmentFile: EnvironmentFile }> {
+  const prepared = await prepareAgentFiles(client, { [params.path]: params.file }, options);
+  const [reference] = prepared.files;
+  const [uploadedFile] = prepared.uploadedFiles;
+  if (!reference || !uploadedFile) {
+    throw new OpenAIError('Missing prepared agent file');
+  }
+  try {
+    return { uploadedFile, environmentFile: await resource.create(environmentID, reference, options) };
+  } catch (error) {
+    throw new AgentFileUploadError(prepared.uploadedFiles, error);
+  }
+}

package/src/lib/beta/agents/function-tool.ts

@@ -0,0 +1,60 @@
+import { OpenAIError } from '../../../core/error';
+import type { AgentToolHandler } from '../../agents/agent-session-stream';
+import type { AutoParseableResponseTool } from '../../ResponsesParser';
+import type { AgentToolParam } from '../../../resources/beta/agents/agents';
+import { isInputContent } from './tool-output';
+
+/** A beta Agents function definition paired with its local, validating handler. */
+export interface AgentFunctionTool {
+  /** Model-visible function name, also used as the key in `toolHandlers`. */
+  readonly name: string;
+  /** Hosted configuration for `agent.tools`; contains no local callback or parser. */
+  readonly definition: AgentToolParam.AgentToolConfigParamFunction;
+  /** Validates arguments before invoking the callback through the existing stream dispatcher. */
+  readonly handler: AgentToolHandler;
+}
+
+/**
+ * Adapts a `zodResponsesFunction` or `standardResponsesFunction` to beta Agents.
+ * Pass `definition` to `agent.tools` and register `handler` under `name` in
+ * `sessions.stream()`'s `toolHandlers`. Creating a definition does not execute it.
+ * The existing dispatcher handles callback results, failures, and submission retries.
+ * Scalar results and business-data arrays become JSON text; `undefined` becomes
+ * the text `undefined`. Supported text/image content arrays retain their format.
+ *
+ * @throws {OpenAIError} If the tool has no callback or argument schema.
+ */
+export function functionTool<Arguments>(
+  tool: AutoParseableResponseTool<{ name: string; arguments: Arguments }>,
+): AgentFunctionTool {
+  const execute = tool.$callback;
+  const parse = tool.$parseRaw;
+  if (!execute || !tool.parameters) {
+    throw new OpenAIError('Agents function tools require a callback and argument schema');
+  }
+  return {
+    name: tool.name,
+    definition: {
+      type: 'function',
+      name: tool.name,
+      description: tool.description ?? '',
+      parameters: tool.parameters,
+      ...(tool.defer_loading === undefined ? {} : { defer_loading: tool.defer_loading }),
+    },
+    handler: async (arguments_) => {
+      const result: unknown = await execute(parse(JSON.stringify(arguments_)));
+      if (Array.isArray(result)) {
+        return result.length > 0 && result.every(isInputContent) ? result : JSON.stringify(result);
+      }
+      // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Existing schema-tool callbacks return arbitrary application values; adapt them to the Agents dispatcher's output contract.
+      if (typeof result === 'object' || typeof result === 'string') {
+        return result;
+      }
+      const text = result === undefined ? 'undefined' : JSON.stringify(result);
+      if (text === undefined) {
+        throw new OpenAIError('Tool output must be JSON serializable');
+      }
+      return text;
+    },
+  };
+}

package/src/lib/beta/agents/output-format-types.ts

@@ -0,0 +1,12 @@
+import type { TextFormatParam } from '../../../resources/beta/agents/agents';
+import type { AgentTurnResult } from './agent-turn-result';
+import type { ParsedAgentTurnResult } from './parsed-agent-turn-result';
+
+/** Beta: an Agents JSON Schema format with a local output validator. */
+export interface AgentOutputFormat<T> extends TextFormatParam.TextFormatParamJSONSchema {
+  /** SDK-only parser; omitted from serialized requests. */
+  $parseRaw: (text: string) => T;
+}
+
+/** Beta: raw results remain unchanged unless a typed format is supplied. */
+export type AgentResult<T> = [T] extends [never] ? AgentTurnResult : ParsedAgentTurnResult<T>;

package/src/lib/beta/agents/output-format.ts

@@ -0,0 +1,20 @@
+import type { AgentOutputFormat } from './output-format-types';
+
+import type { JSONSchema } from '../../jsonschema';
+
+export type { AgentOutputFormat, AgentResult } from './output-format-types';
+
+export { ParsedAgentTurnResult } from './parsed-agent-turn-result';
+export { AgentOutputParseError } from './output-parse-error';
+
+/** Beta: bind a JSON schema to its local output parser; the API validates schema support. */
+export function agentOutputFormat<T>(schema: JSONSchema, parse: (text: string) => T): AgentOutputFormat<T> {
+  // Keep spread-compatible parsing without exposing caller-owned serialization hooks.
+  const parser = Object.defineProperty((text: string) => parse(text), 'toJSON', {
+    value: () => {
+      /* Parser metadata is omitted from JSON requests. */
+    },
+  });
+  // SAFETY: The API schema type exposes JSON Schema keywords as a record; preserve the supplied schema unchanged.
+  return { type: 'json_schema', schema: schema as AgentOutputFormat<T>['schema'], $parseRaw: parser };
+}

package/src/lib/beta/agents/output-parse-error.ts

@@ -0,0 +1,16 @@
+import { OpenAIError } from '../../../core/error';
+import type { AgentTurnResult } from './agent-turn-result';
+
+/** Beta: hosted execution completed, but local output parsing failed. */
+export class AgentOutputParseError extends OpenAIError {
+  override name = 'AgentOutputParseError';
+  readonly #rawResult: AgentTurnResult;
+  constructor(result: AgentTurnResult) {
+    super('The completed agent output could not be parsed');
+    this.#rawResult = result;
+  }
+  /** Inspect the completed output explicitly; ordinary error logging omits it. */
+  get raw_result(): AgentTurnResult {
+    return this.#rawResult;
+  }
+}

package/src/lib/beta/agents/pages.ts

@@ -0,0 +1,32 @@
+import { OpenAIError } from '../../../core/error';
+import type { CursorPage } from '../../../core/pagination';
+import { isObj } from '../../../internal/utils/values';
+
+/** Retain server cursor metadata for legacy Agents items with nullable IDs.
+ * @internal
+ * @yields {T} Each item in server order, failing if pagination cannot advance.
+ */
+export async function* agentItems<T extends { id?: string | null }>(
+  load: (after: string | undefined) => PromiseLike<CursorPage<T>>,
+): AsyncGenerator<T, void, undefined> {
+  let after: string | undefined;
+  while (true) {
+    // oxlint-disable-next-line no-await-in-loop -- Each page determines the next cursor.
+    const page = await load(after);
+    yield* page.data;
+    if (!page.has_more) {
+      return;
+    }
+    // Internal SDK read: CursorPage keeps raw metadata but does not expose last_id.
+    // oxlint-disable-next-line prefer-destructuring -- Bracket access intentionally reads a protected internal field.
+    const body = page['body'];
+    // oxlint-disable-next-line unicorn/prefer-at -- Keep published source compatible with ES2020 declarations.
+    const last = page.data[page.data.length - 1];
+    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Validate only the opaque cursor from response metadata.
+    const cursor = isObj(body) && typeof body['last_id'] === 'string' ? body['last_id'] : last?.id;
+    if (!cursor || cursor === after) {
+      throw new OpenAIError('Agent pagination cannot advance to the next page');
+    }
+    after = cursor;
+  }
+}

package/src/lib/beta/agents/parse-result.ts

@@ -0,0 +1,133 @@
+import type { RequestOptions } from '../../../internal/request-options';
+import { OpenAIError } from '../../../core/error';
+import type { SessionCreateParams } from '../../../resources/beta/agents/sessions/sessions';
+import type { AgentTurnResult } from './agent-turn-result';
+import type { TextFormatParam } from '../../../resources/beta/agents/agents';
+import type { AgentOutputFormat, AgentResult } from './output-format-types';
+import { ParsedAgentTurnResult } from './parsed-agent-turn-result';
+import { AgentOutputParseError } from './output-parse-error';
+
+/** @internal */
+export function parseAgentResult<T>(result: AgentTurnResult, format?: AgentOutputFormat<T>): AgentResult<T> {
+  try {
+    if (!format) {
+      // SAFETY: Absent formats use the default never/raw overload.
+      return result as AgentResult<T>;
+    }
+    let first: { value: T } | undefined;
+    for (const message of result.messages) {
+      for (const content of message.content) {
+        if (content.type === 'output_text') {
+          const value = format.$parseRaw(content.text);
+          first ??= { value };
+        }
+      }
+    }
+    if (!first) {
+      throw new AgentOutputParseError(result);
+    }
+    // SAFETY: Callers preserve the format's inferred T.
+    return new ParsedAgentTurnResult(result, first.value) as AgentResult<T>;
+  } catch {
+    throw new AgentOutputParseError(result);
+  }
+}
+
+// Inspect only JSON-visible data fields; leave getters and inherited values to normal serialization.
+function ownJSONValue<T extends object, K extends keyof T>(
+  object: T | null | undefined,
+  key: K,
+): T[K] | undefined {
+  const descriptor = object && Object.getOwnPropertyDescriptor(object, key);
+  // SAFETY: The own data descriptor corresponds to the requested property in T.
+  return descriptor?.enumerable && 'value' in descriptor ? (descriptor.value as T[K]) : undefined;
+}
+
+/** @internal */
+export function agentFormatParser<T = unknown>(
+  format: TextFormatParam | null | undefined,
+): AgentOutputFormat<T> | undefined {
+  if (!format) {
+    return undefined;
+  }
+  const descriptor = Object.getOwnPropertyDescriptor(format, '$parseRaw');
+  // oxlint-disable-next-line anti-slop/no-runtime-typeof -- An own parser data property is the explicit opt-in marker.
+  if (!descriptor || !('value' in descriptor) || typeof descriptor.value !== 'function') {
+    return undefined;
+  }
+  // SAFETY: Inspect the schema data descriptor without evaluating a caller getter; validate its discriminator below.
+  const schema = ownJSONValue(format as TextFormatParam.TextFormatParamJSONSchema, 'schema');
+  if (ownJSONValue(format, 'type') !== 'json_schema' || !schema) {
+    throw new OpenAIError('Typed agent formats require own enumerable type and schema data properties');
+  }
+  // SAFETY: The own descriptor was checked for a callable parser; retain its receiver and never reread the property.
+  const parse = descriptor.value as AgentOutputFormat<T>['$parseRaw'];
+  return { type: 'json_schema', schema, $parseRaw: (text) => parse.call(format, text) };
+}
+
+// Materialize JSON-visible envelope getters once without evaluating unrelated properties.
+function snapshotJSONProperty<T extends object, K extends keyof T>(
+  object: T,
+  key: K,
+  capture: (value: T[K]) => T[K] = (value) => value,
+): T {
+  const descriptor = Object.getOwnPropertyDescriptor(object, key);
+  if (!descriptor?.enumerable) {
+    return object;
+  }
+  const value = capture(object[key]);
+  if ('value' in descriptor && value === descriptor.value) {
+    return object;
+  }
+  // SAFETY: Preserve the original properties/prototype, replacing only this captured property's value.
+  return Object.create(Object.getPrototypeOf(object), {
+    ...Object.getOwnPropertyDescriptors(object),
+    [key]: { value, enumerable: true, configurable: descriptor.configurable, writable: true },
+  }) as T;
+}
+
+/** @internal */
+export function captureAgentOutput(input: SessionCreateParams, options?: RequestOptions) {
+  const body = snapshotJSONProperty(input, 'agent', (agent) =>
+    agent
+      ? snapshotJSONProperty(agent, 'text', (text) => (text ? snapshotJSONProperty(text, 'format') : text))
+      : agent,
+  );
+  const agent = ownJSONValue(body, 'agent');
+  const text = ownJSONValue(agent, 'text');
+  const format = agentFormatParser(ownJSONValue(text, 'format'));
+  if (!format) {
+    return { body, options };
+  }
+  const schema = structuredClone(format.schema);
+  for (const envelope of [body, agent, text]) {
+    if (envelope && 'toJSON' in envelope) {
+      throw new OpenAIError('Typed agent requests cannot customize body, agent, or text serialization');
+    }
+  }
+  // Snapshot options once, matching the own enumerable fields native request spreading uses.
+  const capturedOptions = { ...options };
+  if (ownJSONValue(capturedOptions, 'body') !== undefined) {
+    throw new OpenAIError('Typed agent requests cannot override the body in request options');
+  }
+  delete capturedOptions.body;
+  return {
+    options: capturedOptions,
+    body: {
+      ...body,
+      agent: {
+        ...agent,
+        text: { ...text, format: { type: 'json_schema', schema } },
+      },
+    },
+    format,
+  };
+}
+
+/** @internal */
+export async function parseAgentResultPromise<T>(
+  result: Promise<AgentTurnResult>,
+  format?: AgentOutputFormat<T>,
+): Promise<AgentResult<T>> {
+  return parseAgentResult(await result, format);
+}

package/src/lib/beta/agents/parsed-agent-turn-result.ts

@@ -0,0 +1,12 @@
+import { AgentTurnResult } from './agent-turn-result';
+
+/** Beta: a completed hosted turn whose output passed the local parser. */
+export class ParsedAgentTurnResult<T> extends AgentTurnResult {
+  readonly output_parsed: T;
+  readonly raw_result: AgentTurnResult;
+  constructor(result: AgentTurnResult, parsed: T) {
+    super(result.turn, result.messages);
+    this.raw_result = result;
+    this.output_parsed = parsed;
+  }
+}

package/src/lib/beta/agents/result-artifacts.ts

@@ -0,0 +1,76 @@
+import type { WritableStream } from '../../../internal/shim-types';
+import { agentItems } from './pages';
+import { OpenAIError } from '../../../core/error';
+import type { RequestOptions } from '../../../internal/request-options';
+import type { Artifacts, SessionArtifact } from '../../../resources/beta/agents/sessions/artifacts';
+import type { AgentTurnResult } from './agent-turn-result';
+
+/** Beta: artifacts from the exact session and turn represented by a result. */
+export class AgentResultArtifacts {
+  readonly #resource: Artifacts;
+  readonly #sessionID: string;
+  readonly #turnID: string;
+  constructor(resource: Artifacts, result: AgentTurnResult) {
+    this.#resource = resource;
+    this.#sessionID = result.session_id;
+    this.#turnID = result.turn_id;
+  }
+
+  /** Find one immutable artifact by its exact hosted path, across all pages. */
+  async retrieve(path: string, options?: RequestOptions): Promise<SessionArtifact> {
+    let selected: SessionArtifact | undefined;
+    for await (const artifact of agentItems((after) =>
+      this.#resource.list(
+        this.#sessionID,
+        {},
+        { ...options, query: { ...options?.query, after, environment_id: undefined } },
+      ),
+    )) {
+      if (
+        artifact.session_id === this.#sessionID &&
+        artifact.turn_id === this.#turnID &&
+        artifact.path === path
+      ) {
+        if (selected) {
+          throw new OpenAIError('Multiple artifacts match this result and path');
+        }
+        selected = artifact;
+      }
+    }
+    if (!selected) {
+      throw new OpenAIError('No artifact matches this result and path');
+    }
+    return selected;
+  }
+
+  /** Return the native binary response for this result's exact artifact path. */
+  async content(path: string, options?: RequestOptions): Promise<Response> {
+    const artifact = await this.retrieve(path, options);
+    return this.#resource.content(artifact.id, { session_id: this.#sessionID }, options);
+  }
+
+  /** Stream bytes to a caller-chosen destination; the hosted path never selects a local path. */
+  async download(
+    params: { path: string; to: WritableStream<Uint8Array> },
+    options?: RequestOptions,
+  ): Promise<SessionArtifact> {
+    const { path, to } = params;
+    const artifact = await this.retrieve(path, options);
+    const response = await this.#resource.content(artifact.id, { session_id: this.#sessionID }, options);
+    if (!response.body) {
+      throw new OpenAIError('Artifact response has no content stream');
+    }
+    try {
+      await response.body.pipeTo(to, options?.signal ? { signal: options.signal } : {});
+    } catch (error) {
+      // pipeTo can reject before acquiring a reader, for example when the destination is locked.
+      try {
+        await response.body.cancel();
+      } catch {
+        /* already cancelled or owned by pipeTo */
+      }
+      throw error;
+    }
+    return artifact;
+  }
+}