coder · dannykopping · Jul 6, 2026 · Jun 30, 2026 · Jul 6, 2026
diff --git a/coderd/aibridged/proto/aibridged.pb.go b/coderd/aibridged/proto/aibridged.pb.go
diff --git a/coderd/aibridged/proto/aibridged.proto b/coderd/aibridged/proto/aibridged.proto
@@ -113,6 +113,10 @@ message RecordToolUsageRequest {
   map<string, google.protobuf.Any> metadata = 8;
   google.protobuf.Timestamp created_at = 9;
   string tool_call_id = 10; // The ID of the tool call provided by the AI provider.
+  // Specific to the OpenAI Responses API: the unique id of the output item that
+  // carried the tool call, distinct from tool_call_id (the call_id correlation
+  // key). Empty for chat completions and Anthropic messages.
+  string item_id = 11;
 }
 message RecordToolUsageResponse {}
 

diff --git a/coderd/aibridged/translator.go b/coderd/aibridged/translator.go
@@ -104,6 +104,7 @@ func (t *recorderTranslation) RecordToolUsage(ctx context.Context, req *aibridge
 		InterceptionId:  req.InterceptionID,
 		MsgId:           req.MsgID,
 		ToolCallId:      req.ToolCallID,
+		ItemId:          req.ItemID,
 		ServerUrl:       req.ServerURL,
 		Tool:            req.Tool,
 		Input:           string(serialized),

diff --git a/coderd/aibridgedserver/aibridgedserver.go b/coderd/aibridgedserver/aibridgedserver.go
@@ -429,6 +429,7 @@ func (s *Server) RecordToolUsage(ctx context.Context, in *proto.RecordToolUsageR
 			slog.F("interception_id", intcID.String()),
 			slog.F("msg_id", in.GetMsgId()),
 			slog.F("tool_call_id", in.GetToolCallId()),
+			slog.F("item_id", in.GetItemId()),
 			slog.F("tool", in.GetTool()),
 			slog.F("input", in.GetInput()),
 			slog.F("server_url", in.GetServerUrl()),
@@ -449,6 +450,7 @@ func (s *Server) RecordToolUsage(ctx context.Context, in *proto.RecordToolUsageR
 		InterceptionID:     intcID,
 		ProviderResponseID: in.GetMsgId(),
 		ProviderToolCallID: sql.NullString{String: in.GetToolCallId(), Valid: in.GetToolCallId() != ""},
+		ProviderItemID:     sql.NullString{String: in.GetItemId(), Valid: in.GetItemId() != ""},
 		ServerUrl:          sql.NullString{String: in.GetServerUrl(), Valid: in.ServerUrl != nil},
 		Tool:               in.GetTool(),
 		Input:              in.GetInput(),

diff --git a/coderd/aibridgedserver/aibridgedserver_test.go b/coderd/aibridgedserver/aibridgedserver_test.go
@@ -2219,6 +2219,7 @@ func TestRecordToolUsage(t *testing.T) {
 					InterceptionId:  uuid.NewString(),
 					MsgId:           "msg_123",
 					ToolCallId:      "call_xyz",
+					ItemId:          "fc_item_xyz",
 					ServerUrl:       ptr.Ref("https://api.example.com"),
 					Tool:            "read_file",
 					Input:           `{"path": "/etc/hosts"}`,
@@ -2248,6 +2249,7 @@ func TestRecordToolUsage(t *testing.T) {
 							!assert.Equal(t, interceptionID, p.InterceptionID, "interception ID") ||
 							!assert.Equal(t, req.GetMsgId(), p.ProviderResponseID, "provider response ID") ||
 							!assert.Equal(t, sql.NullString{String: "call_xyz", Valid: true}, p.ProviderToolCallID, "provider tool call ID") ||
+							!assert.Equal(t, sql.NullString{String: "fc_item_xyz", Valid: true}, p.ProviderItemID, "provider item ID") ||
 							!assert.Equal(t, req.GetTool(), p.Tool, "tool") ||
 							!assert.Equal(t, dbServerURL, p.ServerUrl, "server URL") ||
 							!assert.Equal(t, req.GetInput(), p.Input, "input") ||
@@ -2847,6 +2849,79 @@ func TestInferredThreadsByToolCalls(t *testing.T) {
 	require.Equal(t, uuid.NullUUID{UUID: aID, Valid: true}, intcC.ThreadRootID)
 }
 
+// TestRecordToolUsageProviderItemID exercises the RecordToolUsage RPC against a
+// real database and confirms that provider_item_id is persisted in its own
+// column for both shapes of Responses-API tool call. Agentic tools carry both
+// an item id and a tool_call_id; hosted tools (e.g. web_search_call) carry only
+// an item id. The hosted case is the important one: it proves the item id is
+// stored even when tool_call_id is absent, so persistence is not gated on the
+// tool_call_id being present, and the two ids are written to their own columns.
+func TestRecordToolUsageProviderItemID(t *testing.T) {
+	t.Parallel()
+	db, _ := dbtestutil.NewDB(t)
+	ctx := testutil.Context(t, testutil.WaitLong)
+	logger := testutil.Logger(t)
+
+	user := dbgen.User(t, db, database.User{})
+
+	srv, err := aibridgedserver.NewServer(ctx, db, logger, "/", codersdk.AIBridgeConfig{}, nil, requiredExperiments, agplaiseats.Noop{})
+	require.NoError(t, err)
+
+	intcID := uuid.New()
+	_, err = srv.RecordInterception(ctx, &proto.RecordInterceptionRequest{
+		Id:          intcID.String(),
+		ApiKeyId:    uuid.NewString(),
+		InitiatorId: user.ID.String(),
+		Provider:    "openai",
+		Model:       "gpt-5",
+		StartedAt:   timestamppb.Now(),
+	})
+	require.NoError(t, err)
+
+	// Agentic tool: both item_id and tool_call_id are present.
+	_, err = srv.RecordToolUsage(ctx, &proto.RecordToolUsageRequest{
+		InterceptionId: intcID.String(),
+		MsgId:          "resp_1",
+		ToolCallId:     "call_agentic",
+		ItemId:         "fc_item_1",
+		Tool:           "function_call",
+		Input:          "{}",
+		CreatedAt:      timestamppb.Now(),
+	})
+	require.NoError(t, err)
+
+	// Hosted tool: only item_id is present, tool_call_id is empty.
+	_, err = srv.RecordToolUsage(ctx, &proto.RecordToolUsageRequest{
+		InterceptionId: intcID.String(),
+		MsgId:          "resp_1",
+		ItemId:         "ws_item_1",
+		Tool:           "web_search_call",
+		Input:          "{}",
+		CreatedAt:      timestamppb.Now(),
+	})
+	require.NoError(t, err)
+
+	usages, err := db.GetAIBridgeToolUsagesByInterceptionID(ctx, intcID)
+	require.NoError(t, err)
+	require.Len(t, usages, 2)
+
+	byItemID := make(map[string]database.AIBridgeToolUsage, len(usages))
+	for _, u := range usages {
+		require.True(t, u.ProviderItemID.Valid, "item ID should be persisted for %q", u.Tool)
+		byItemID[u.ProviderItemID.String] = u
+	}
+
+	// Agentic tool: item id and tool_call_id land in their own columns.
+	agentic, ok := byItemID["fc_item_1"]
+	require.True(t, ok, "agentic tool usage persisted by item ID")
+	require.Equal(t, sql.NullString{String: "call_agentic", Valid: true}, agentic.ProviderToolCallID)
+
+	// Hosted tool: item id is persisted even though the tool_call_id is empty.
+	hosted, ok := byItemID["ws_item_1"]
+	require.True(t, ok, "hosted tool usage persisted by item ID")
+	require.Equal(t, sql.NullString{}, hosted.ProviderToolCallID, "hosted tool has no tool_call_id")
+}
+
 // TestGetAIProviders exercises the row-to-proto mapping over a real database:
 // enabled providers carry their keys (and typed Bedrock settings), disabled
 // providers are included but withhold keys and settings, Copilot (a keyless

diff --git a/coderd/database/dbgen/dbgen.go b/coderd/database/dbgen/dbgen.go
@@ -2078,6 +2078,7 @@ func AIBridgeToolUsage(t testing.TB, db database.Store, seed database.InsertAIBr
 		InterceptionID:     takeFirst(seed.InterceptionID, uuid.New()),
 		ProviderResponseID: takeFirst(seed.ProviderResponseID, "provider_response_id"),
 		ProviderToolCallID: takeFirst(seed.ProviderToolCallID),
+		ProviderItemID:     takeFirst(seed.ProviderItemID),
 		Tool:               takeFirst(seed.Tool, "tool"),
 		ServerUrl:          serverURL,
 		Input:              takeFirst(seed.Input, "input"),

diff --git a/coderd/database/dump.sql b/coderd/database/dump.sql
diff --git a/coderd/database/migrations/000537_aibridge_tool_usage_provider_item_id.down.sql b/coderd/database/migrations/000537_aibridge_tool_usage_provider_item_id.down.sql
@@ -0,0 +1,2 @@
+ALTER TABLE aibridge_tool_usages
+DROP COLUMN provider_item_id;
diff --git a/coderd/database/migrations/000537_aibridge_tool_usage_provider_item_id.up.sql b/coderd/database/migrations/000537_aibridge_tool_usage_provider_item_id.up.sql
@@ -0,0 +1,4 @@
+ALTER TABLE aibridge_tool_usages
+ADD COLUMN provider_item_id text NULL; -- nullable to allow existing data to remain valid
+
+COMMENT ON COLUMN aibridge_tool_usages.provider_item_id IS 'Specific to the OpenAI Responses API: the unique id of the output item that carried the tool call. Distinct from provider_tool_call_id (the call_id correlation key), which is empty for hosted tools. Empty for the chat completions and Anthropic messages APIs, which have no separate item id.';
diff --git a/coderd/database/models.go b/coderd/database/models.go
diff --git a/coderd/database/queries.sql.go b/coderd/database/queries.sql.go
diff --git a/coderd/database/queries/aibridge.sql b/coderd/database/queries/aibridge.sql
@@ -56,9 +56,9 @@ RETURNING *;
 
 -- name: InsertAIBridgeToolUsage :one
 INSERT INTO aibridge_tool_usages (
-  id, interception_id, provider_response_id, provider_tool_call_id, tool, server_url, input, injected, invocation_error, metadata, created_at
+  id, interception_id, provider_response_id, provider_tool_call_id, provider_item_id, tool, server_url, input, injected, invocation_error, metadata, created_at
 ) VALUES (
-  @id, @interception_id, @provider_response_id, @provider_tool_call_id, @tool, @server_url, @input, @injected, @invocation_error, COALESCE(@metadata::jsonb, '{}'::jsonb), @created_at
+  @id, @interception_id, @provider_response_id, @provider_tool_call_id, @provider_item_id, @tool, @server_url, @input, @injected, @invocation_error, COALESCE(@metadata::jsonb, '{}'::jsonb), @created_at
 )
 RETURNING *;
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		ALTER TABLE aibridge_tool_usages
		DROP COLUMN provider_item_id;