fix: preserve defined W3C flags in native tracing

.changeset/a2a-serialized-results.md

@@ -0,0 +1,6 @@
+---
+'@openai/agents': patch
+'@openai/agents-codex': patch
+---
+
+fix: preserve the JSON representation of structured A2A results when saving and publishing a task.

.changeset/defined-native-trace-flags.md

@@ -0,0 +1,6 @@
+---
+'@openai/agents': patch
+'@openai/agents-codex': patch
+---
+
+fix: accept defined sampled and random-trace-ID flag combinations and preserve them through native parent and callback header propagation, including later owned child turns.

.changeset/limit-a2a-response-encoding.md

@@ -0,0 +1,6 @@
+---
+'@openai/agents': patch
+'@openai/agents-codex': patch
+---
+
+Reject compressed A2A discovery and RPC responses before reading their bodies, and request identity encoding so the adapter's response-byte bound does not depend on automatic decompression.

.changeset/native-prepared-request.md

@@ -0,0 +1,5 @@
+---
+'@openai/agents-codex': minor
+---
+
+feat: Add per-operation prepared-request editing for native HTTP root conversations while preserving original tool and history authority.

.changeset/owned-child-tracing-context.md

@@ -0,0 +1,6 @@
+---
+'@openai/agents': patch
+'@openai/agents-codex': patch
+---
+
+fix: preserve each queued native submission's trace and privacy settings when another workflow is active

.changeset/passive-request-metadata.md

@@ -0,0 +1,6 @@
+---
+'@openai/agents': minor
+'@openai/agents-codex': minor
+---
+
+Expose passive root request metadata and optional links to retained response occurrences through existing observation streams. Report resolved serialized settings and the selected client invocation transport without retaining request bodies or changing inference behavior.

.changeset/quiet-terminal-authentication.md

@@ -0,0 +1,6 @@
+---
+'@openai/agents': patch
+'@openai/agents-codex': patch
+---
+
+fix: stop sampling after final HTTP 401 or 403 responses and share bounded credential recovery across WebSocket-to-HTTP fallback while preserving final provider metadata.

examples/realtime-react-native/test/token-server.test.ts

@@ -1,5 +1,6 @@
 import assert from 'node:assert/strict';
 import { spawn } from 'node:child_process';
+import { once } from 'node:events';
 import { request as httpRequest } from 'node:http';
 import { createServer } from 'node:net';
 import type { AddressInfo } from 'node:net';
@@ -28,8 +29,10 @@ async function startServer(host: string, configuredPort?: number) {
       return listen.call(this, ${port}, ...args);
     };`
     }
+    let upstreamRequests = 0;
+    process.on('message', () => process.send(upstreamRequests));
     globalThis.fetch = async () => {
-      console.log('UPSTREAM_REQUEST');
+      upstreamRequests++;
       return new Response(JSON.stringify({ value: 'test-client-secret', expires_at: 123 }), { status: 200 });
     };
     await import(${JSON.stringify(serverUrl)});
@@ -41,7 +44,7 @@ async function startServer(host: string, configuredPort?: number) {
       PORT: String(configuredPort ?? port),
       OPENAI_API_KEY: 'test-api-key',
     },
-    stdio: ['ignore', 'pipe', 'pipe'],
+    stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
   });
   let output = '';
   await new Promise((resolve, reject) => {
@@ -63,8 +66,11 @@ async function startServer(host: string, configuredPort?: number) {
   });
   return {
     port,
-    get output() {
-      return output;
+    async upstreamRequests() {
+      const reply = once(child, 'message');
+      child.send('upstreamRequests');
+      const [count] = await reply;
+      return count as number;
     },
     pairingToken: output.match(/Pairing token: ([A-Za-z0-9_-]+)/)?.[1],
     request: (headers?: Record<string, string>) =>
@@ -95,7 +101,7 @@ test('LAN token issuance requires pairing and limits each client', async () => {
       (await server.request({ Authorization: 'Bearer wrong' })).status,
       401,
     );
-    assert.equal(server.output.includes('UPSTREAM_REQUEST'), false);
+    assert.equal(await server.upstreamRequests(), 0);
 
     assert.ok(server.pairingToken);
     const headers = { Authorization: `Bearer ${server.pairingToken}` };
@@ -105,7 +111,7 @@ test('LAN token issuance requires pairing and limits each client', async () => {
       assert.equal((await response.json()).value, 'test-client-secret');
     }
     assert.equal((await server.request(headers)).status, 429);
-    assert.equal(server.output.match(/UPSTREAM_REQUEST/g)?.length, 6);
+    assert.equal(await server.upstreamRequests(), 6);
   } finally {
     server.stop();
   }
@@ -137,7 +143,7 @@ test('loopback token issuance requires pairing and an expected origin', async ()
   try {
     assert.ok(server.pairingToken);
     assert.equal((await server.request()).status, 401);
-    assert.equal(server.output.includes('UPSTREAM_REQUEST'), false);
+    assert.equal(await server.upstreamRequests(), 0);
 
     const headers = { Authorization: `Bearer ${server.pairingToken}` };
     assert.equal(
@@ -162,15 +168,15 @@ test('loopback token issuance requires pairing and an expected origin', async ()
       ).status,
       403,
     );
-    assert.equal(server.output.includes('UPSTREAM_REQUEST'), false);
+    assert.equal(await server.upstreamRequests(), 0);
 
     assert.equal((await server.request(headers)).status, 200);
     assert.equal(
       (await server.request({ ...headers, Host: `10.0.2.2:${server.port}` }))
         .status,
       200,
     );
-    assert.equal(server.output.match(/UPSTREAM_REQUEST/g)?.length, 2);
+    assert.equal(await server.upstreamRequests(), 2);
   } finally {
     server.stop();
   }
@@ -204,7 +210,7 @@ test('HTTP port 80 accepts exact portless aliases and serialized origins while r
       ).status,
       403,
     );
-    assert.equal(server.output.includes('UPSTREAM_REQUEST'), false);
+    assert.equal(await server.upstreamRequests(), 0);
 
     for (const alias of ['127.0.0.1', 'localhost', '10.0.2.2']) {
       for (const Host of [alias, `${alias}:80`]) {
@@ -221,7 +227,7 @@ test('HTTP port 80 accepts exact portless aliases and serialized origins while r
       (await server.request({ ...headers, Host: 'localhost' })).status,
       429,
     );
-    assert.equal(server.output.match(/UPSTREAM_REQUEST/g)?.length, 6);
+    assert.equal(await server.upstreamRequests(), 6);
   } finally {
     server.stop();
   }

helpers/vitest/nativeAgentTestProfile.ts

@@ -17,4 +17,5 @@ export const nativeAgentTestIncludes =
         'test/classic/**/*.test.ts',
         'test/native/output-state.test.ts',
         'test/native/repair-observation.test.ts',
+        'test/native/request-metadata.test.ts',
       ];

packages/agents-codex/A2A.md

@@ -27,15 +27,15 @@ Discovery sends no credentials. After the card passes admission, the adapter res
 
 The returned client is the official A2A `Client`. Direct callers must treat an uncertain mutation acknowledgment as an unknown outcome; message IDs do not make creation idempotent. This profile supports `sendMessage`, `getTask`, and `cancelTask`. It uses polling rather than streaming, push notifications, extended cards, or remote callback execution. Native input supports text and inline PNG, JPEG, GIF, and WebP images. File URLs, arbitrary URIs, and other file types fail before native admission. Result validation remains the application's responsibility.
 
-`A2ALimits` sets `bodyBytes`, `inputBytes`, `checkpointBytes`, and `timeoutMs`. Defaults are 2 MiB, 1 MiB, 8 MiB, and 30 seconds. The HTTP reader stops before buffering more than `bodyBytes`. These bounds are adapter defaults, not service quotas. The host should also bound incoming HTTP bodies before protocol parsing.
+`A2ALimits` sets `bodyBytes`, `inputBytes`, `checkpointBytes`, and `timeoutMs`. Defaults are 2 MiB, 1 MiB, 8 MiB, and 30 seconds. The adapter requests identity HTTP encoding and cancels responses that declare another encoding before reading their bodies. `bodyBytes` limits the chunks the adapter retains. A custom `fetch` must preserve response encoding headers and body cancellation. The transport controls its own internal buffers. These bounds are adapter defaults, not service quotas. The host should also bound incoming HTTP bodies before protocol parsing.
 
 ## Deferred remote work
 
 `A2AJobProvider` implements the existing `JobProvider` contract. Register it with `DeferredTools`, a host `JobJournal`, and a current result projection. Set `requireReconciliation: false` only for work whose uncertain outcome the host can handle. Generic A2A cannot prove whether a lost create was accepted.
 
 The provider requires separate callbacks for current authorization, credential resolution, durable mutation reservation, input encoding, and result validation. Authorization checks the current principal, immutable native invocation binding, and claim generation. After discovery and local validation, the provider resolves credentials, checks authorization again, spends one mutation reservation, and sends once. A timeout or lost create, input-reply, or cancel acknowledgment returns `unknown`. It never resends that mutation. A known receipt binds the endpoint and original native invocation. A fresh worker observes that same remote task with `getTask`; it does not create another task.
 
-`inputRequired` exposes a remote challenge. `A2AInputReply` supplies its task ID, context ID, challenge, generation, and JSON `result`. The provider reads the current remote task before reserving a reply. Python and TypeScript share one wire profile: the status message contains one data part `{challenge, generation, tool, arguments}`; a reply contains exactly `{challenge, generation, result}`. Task and context IDs belong in the A2A message envelope. Structured completion artifacts contain `{result: output}`; string results remain text parts. `authRequired` remains a host credential flow and never becomes a generic approval answer. A host must not accept untrusted remote approval text as authority to perform local actions.
+`inputRequired` exposes a remote challenge. `A2AInputReply` supplies its task ID, context ID, challenge, generation, and JSON `result`. The provider reads the current remote task before reserving a reply. Python and TypeScript share one wire profile: the status message contains one data part `{challenge, generation, tool, arguments}`; a reply contains exactly `{challenge, generation, result}`. Task and context IDs belong in the A2A message envelope. The executor publishes string results as text parts. For structured results, it saves and sends `{result: output}` using the JSON representation that passed the byte limit. `authRequired` remains a host credential flow and never becomes a generic approval answer. A host must not accept untrusted remote approval text as authority to perform local actions.
 
 ## Serve a native agent
 

packages/agents-codex/examples/prepared-request.ts

@@ -0,0 +1,118 @@
+import assert from 'node:assert/strict';
+import { z } from 'zod';
+import { Agent, Runner, ToolOutput, tool } from '@openai/agents-codex';
+import {
+  text,
+  toolCall,
+  withScriptedResponses,
+} from '@openai/agents-codex/testing';
+
+/**
+ * Exercise the public request, argument and result controls without live credentials.
+ * The scripted provider uses explicit HTTP and a standard Responses (non-Lite) model.
+ * Select eager ordinary tools for each sampling step of a direct root.
+ * beforeStep may narrow a mixed opening catalog. Deferred sampled tools fail before the editor.
+ * Environment, code mode, children and automatic compaction are outside this profile.
+ * Pre-turn or mid-turn automatic compaction fails before any hidden model request.
+ * Shorten the input or start a new operation without the callback. Earlier tool effects remain.
+ * Post-turn compaction is refused while preserving the completed answer.
+ * Supply new input to Agent.run when using prepareRequest. A resumed turn cannot add an editor.
+ * Sampling edits do not change canonical history, executable schemas or policies.
+ * For structured output, use native mode or prompted mode with maxRetries: 0.
+ */
+export async function runPreparedRequestExample(): Promise<string> {
+  const effects: string[] = [];
+  const lookup = tool({
+    name: 'lookup',
+    description: 'Look up a synthetic record.',
+    parameters: z.object({ key: z.enum(['allowed']), label: z.string() }),
+    before: ({ callId, originalArguments }) => {
+      assert.equal(callId, 'lookup');
+      assert.deepEqual(originalArguments, {
+        key: 'allowed',
+        label: 'original',
+      });
+      return {
+        action: 'replaceArguments',
+        arguments: { key: 'allowed' as const, label: 'corrected' },
+      };
+    },
+    execute: ({ key, label }) => {
+      effects.push(label);
+      return `Raw record ${key}`;
+    },
+    after: (_output, { callId, effectiveArguments }) => {
+      assert.equal(callId, 'lookup');
+      assert.equal(effectiveArguments.label, 'corrected');
+      return new ToolOutput([{ type: 'inputText', text: 'SHAPED_RESULT' }]);
+    },
+  });
+  return withScriptedResponses(
+    [
+      [
+        toolCall(
+          'lookup',
+          { key: 'allowed', label: 'original' },
+          { callId: 'lookup' },
+        ),
+      ],
+      [text('The record is allowed.')],
+    ],
+    async (peer) => {
+      const result = await Runner.run(
+        new Agent({
+          model: 'gpt-5.5',
+          instructions: 'Call lookup, then explain its result.',
+          provider: peer.provider,
+          tools: [lookup],
+        }),
+        'Look up the record.',
+        {
+          prepareRequest({ request, signal }) {
+            signal.throwIfAborted();
+            // Recovery can advance the index without a result. Inspect native input.
+            if (
+              !request.input.some(
+                (item) =>
+                  item !== null &&
+                  typeof item === 'object' &&
+                  !Array.isArray(item) &&
+                  item.type === 'function_call_output' &&
+                  item.call_id === 'lookup',
+              )
+            )
+              return;
+            request.instructions = 'Explain the lookup result in one sentence.';
+            request.input.push({
+              type: 'message',
+              role: 'user',
+              content: [{ type: 'input_text', text: 'SAMPLING_ONLY_NOTE' }],
+            });
+            request.tools[0].description = 'Sampled record description.';
+            request.tools[0].parameters.properties = {
+              key: { type: 'string', enum: ['allowed', 'sampled-only'] },
+              label: { type: 'string' },
+            };
+            return request;
+          },
+        },
+      );
+      assert.deepEqual(effects, ['corrected']);
+      assert.equal(peer.toolOutput('lookup'), 'SHAPED_RESULT');
+      assert.equal(peer.requests.length, 2);
+      assert.match(
+        JSON.stringify(peer.requests[1].input),
+        /SAMPLING_ONLY_NOTE/,
+      );
+      assert.match(
+        JSON.stringify(peer.requests[1].tools),
+        /Sampled record description/,
+      );
+      assert.match(
+        JSON.stringify(peer.requests[1].input),
+        /Explain the lookup result in one sentence/,
+      );
+      return result.finalOutput;
+    },
+  );
+}

packages/agents-codex/native/index.d.ts

@@ -165,6 +165,7 @@ export class NativeThread {
     traceJson?: string | null,
     tracing_context?: string,
   ): Promise<string>;
+  _reply_prepared_request(responseJson: string): void;
   _reply_step(response_json: string): void;
   _check_step(response_json: string): boolean;
   _reply_child_step(response_json: string): boolean;
@@ -200,6 +201,7 @@ export class NativeThread {
     selectionJson?: string,
     traceJson?: string,
     tracing_context?: string,
+    observationSubmissionId?: string,
   ): Promise<string>;
   read_thread_history(subagent_id: string | null): Promise<string>;
   read_checklist(subagent_id?: string | null): Promise<string>;